HCIEMU 1.2.0

BLE testing toolkit built on Bumble with interactive menu, GATT ops, and HCI capture

Bumble BLE Testing Framework

A comprehensive BLE (Bluetooth Low Energy) testing toolkit built on the Bumble Bluetooth stack

Features:

• 🔍 Interactive menu-driven interface
• 📡 BLE scanning and device discovery
• 🔗 GATT operations (read/write/notify)
• 🔐 Pairing and persistent bonding
• 📊 Live HCI packet capture (Ellisys + BTSnoop)
• 🐍 Python API for automation

---

🚀 Start Guide

Choose one workflow:

Option A: Install from Package/Release (Fastest)

If you install the package (for example pip install HCIEMU), these commands are available:

Install method recommendation:

• Use pip inside a virtual environment for project development and reproducible dependencies.
• Use pipx for global command-line usage (HCI, BRIDGE) without polluting system Python.

Examples:

# Inside an active venv
pip install HCIEMU

# Global CLI install (isolated)
pipx install HCIEMU

• HCI - Launch the interactive menu app.
• BRIDGE - Launch bridge with defaults (usb:0 -> tcp-server:127.0.0.1:9001).
• BRIDGE <source> <target> - Launch bridge with custom endpoints.
• hciemu - Alias of HCI.
• bumble-hci-menu - Alias of HCI.

Windows example:

# Terminal 1
BRIDGE

# Terminal 2
HCI

Custom bridge example:

BRIDGE serial:COM5,115200 tcp-server:127.0.0.1:9001

Option B: Clone the Repository (Development/Source Mode)

git clone <repository-url>
cd bumble_hci

Windows quick run:

setup.bat
BRIDGE.bat
HCI.bat

Source-mode commands also work directly:

python src/main.py
bumble-hci-bridge usb:0 tcp-server:127.0.0.1:9001

Linux/macOS setup details: SETUP.md

---

📖 Documentation

For Users:

• docs/USER_MANUAL.md - Complete usage guide, troubleshooting, FAQ

For Developers:

• docs/TECHNICAL_REFERENCE.md - Architecture, APIs, protocols

Setup & Contributing:

• SETUP.md - Platform-specific installation
• CONTRIBUTING.md - How to contribute

---

📁 Project Structure

bumble_hci/
├── 📋 README.md              ← You are here
├── 📋 requirements.txt       ← Python dependencies
├── 📋 setup.py               ← Package configuration
├── 🔧 setup.bat              ← First-time setup (Windows)
├── 🔧 run.bat                ← Run application (Windows)
│
├── 📂 src/                   ← Application source code
│   ├── main.py               ← Main interactive menu
│   ├── connector.py          ← BLE operations
│   ├── scanner.py            ← Device scanning
│   ├── hci_snooper.py        ← HCI packet capture
│   └── utils.py              ← Utilities
│
├── 📂 docs/                  ← Documentation
│   ├── USER_MANUAL.md        ← User guide (START HERE!)
│   ├── TECHNICAL_REFERENCE.md ← Developer guide
│   └── development/          ← Historical dev docs
│
├── 📂 examples/              ← Code examples
│   ├── basic_connection.py
│   ├── scan_devices.py
│   └── hci_capture.py
│
├── 📂 tests/                 ← Test suite
├── 📂 scripts/               ← Utility scripts
├── 📂 configs/               ← Configuration files
│   └── bumble_bonds.json     ← Persistent bonds
├── 📂 logs/                  ← HCI captures & logs
└── 📂 resources/             ← UUID lookups, configs

---

---

🎯 Key Features

BLE Operations

• Scan - Discover nearby BLE devices with RSSI
• Connect - Establish connections to BLE peripherals
• GATT - Browse services, read/write characteristics
• Notify - Subscribe to characteristic notifications

Apple Services

• ANCS - Apple Notification Center Service: receive and act on iOS notifications
• AMS - Apple Media Service: monitor and control iOS media playback

Security & Bonding

• Pairing - Support for multiple pairing methods
• Bonding - Persistent bond storage (survives restart)
• Encryption - Manual encryption control
• SMP Security Request - Initiate security from the peripheral side

HCI Packet Capture

• Live Capture - Real-time HCI packet streaming
• Ellisys Integration - UDP injection for Ellisys Bluetooth Analyzer
• BTSnoop Format - Standard .log/.btsnoop file output
• Protocol Analysis - Decode and analyze BLE protocol

Developer Tools

• Python API - Programmatic access to all features
• Examples - Ready-to-use code samples
• Rich UI - Colorful terminal interface with tables

---

💡 Usage Examples

Interactive Menu

python src/main.py

═══════════════════════════════════════════════════════
  BUMBLE BLE Testing - Main Menu
═══════════════════════════════════════════════════════

  [1] Scan for BLE Devices
  [2] Connect to Device
  [3] Disconnect

  --- ATT / GATT (21-40) ---
  [21] Discover GATT Services
  [22] Read Characteristic
  [23] Write Characteristic
  [35] Apple Services (ANCS / AMS)

  --- SMP (41-50) ---
  [41] Pair / Encrypt Connection
  [42] Send SMP Security Request
  [43] SMP Settings
  [44] Unpair / Delete Bonding

  --- Advertising (51-60) ---
  [51] Advertising Menu

  --- L2CAP (61-80) ---
  [61] L2CAP Operations (CBFC/ECBFC)

Programmatic Usage

See examples/ for complete code samples:

from connector import BLEConnector

# Scan for devices
connector = BLEConnector("tcp-client:127.0.0.1:9001")
devices = await connector.scan(duration=10)

# Connect and read
await connector.connect("AA:BB:CC:DD:EE:FF")
value = await connector.read_characteristic(0x0012)

---

🛠️ Requirements

• Python 3.8+
• Bluetooth USB adapter (or built-in Bluetooth)
• USB driver: WinUSB (Windows - via Zadig)
• Bumble - Installed via pip install bumble

See SETUP.md for complete requirements and installation.

---

📦 Installation

Quick Install (Windows)

# Clone repository
git clone <repository-url>
cd bumble_hci

# Run setup
setup.bat

Manual Install (Any Platform)

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/macOS
# or
venv\Scripts\activate.ps1  # Windows

# Install dependencies
pip install -r requirements.txt

Full instructions: SETUP.md

---

🔧 Configuration

HCI Transport

Default: tcp-client:127.0.0.1:9001

Requires bumble-hci-bridge running:

bumble-hci-bridge usb:0 tcp-server:127.0.0.1:9001

Bond Storage

Bonds saved to: configs/bumble_bonds.json

HCI Capture

Files saved to: logs/hci_capture.log (BTSnoop format)
Ellisys: UDP port 24352

---

🧪 Testing

# Run all tests
python -m pytest tests/

# Run specific test
python tests/test_connection.py
python tests/test_ellisys_udp.py

# Check bonding status
python scripts/check_bonding.py

---

📚 Learn More

Documentation:

• User Manual - How to use the framework
• Technical Reference - How it works

Guides:

• Setup Guide - Installation for Windows/Linux/macOS
• Contributing - How to contribute

Examples:

• examples/scan_devices.py - Scan for BLE devices
• examples/basic_connection.py - Connect and read
• examples/hci_capture.py - Capture HCI packets

---

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md

---

📄 License

MIT License - see LICENSE

---

🙏 Acknowledgments

Built with Bumble - A Python Bluetooth stack by Google

---

Questions? Check the FAQ or open an issue.