Add @dbus_property(PropertyAccess.READ) to GattServiceIface,
GattCharacteristicIface, and GattDescriptorIface so BlueZ can
validate objects via the standard Properties interface — fixes
"No valid service object found" error on RegisterApplication.
Also fix ELM327 emulator rejecting 2-char OBD commands (mode 03
for DTCs and mode 04 for clear) by padding to 4 chars.
Implement peripheral/GATT server support (14 tools) using BlueZ's
GattManager1 D-Bus API, enabling mcbluetooth to act as a BLE device
that advertises, accepts connections, and handles reads/writes/notifications.
Add ELM327 emulator (7 tools) that builds on the GATT server to emulate
a BLE OBD-II adapter over Nordic UART Service. Handles AT commands,
Mode 01/03/04/09 queries, configurable PIDs, DTCs, and VIN with
auto-response — no LLM round-trip needed for protocol handling.
New files:
- gatt_server.py: D-Bus ServiceInterface hierarchy + GattServerManager
- tools/gatt_server.py: MCP tool wrappers for server lifecycle
- tools/bt_elm327_emu.py: ELM327 protocol handler + NUS setup
Also adds 2 MCP resources (bluetooth://gatt/server, .../writes).
- Add Dockerfile with multi-stage build (node -> caddy)
- Add docker-compose.yml for caddy-docker-proxy
- Update astro.config.mjs with production site URL
- Add Documentation link to README.md header
- Add Documentation URL to pyproject.toml
- Update guides/ble.md with notification buffering and MCP resources
- Add bt_ble_notification_status and bt_ble_clear_notification_buffer to ble-tools.md
- Add BLE notification resources to resources.md reference
Implements async GATT notification buffering with D-Bus signal subscription.
Notifications are captured in circular buffers (100 values) and exposed via
dynamic MCP resources for polling or subscription.
New resources:
- bluetooth://ble/notifications (list active subscriptions)
- bluetooth://ble/{addr}/{uuid}/notifications (latest value + stats)
- bluetooth://ble/{addr}/{uuid}/notifications/history (buffered history)
New tools: bt_ble_notification_status, bt_ble_clear_notification_buffer
Updated bt_ble_notify to return resource URIs for easy access.
Multiple bugs preventing stable HFP connections with real hardware
(ESP32 Bluedroid HFU):
- Add AF_BLUETOOTH/BTPROTO_RFCOMM fallback constants for Python builds
compiled without bluetooth.h
- Fix NewConnection fd handling: validate, os.dup, transfer to socket
via socket.fromfd with proper protocol param, close intermediate fd
- Remove premature +BCS codec selection from AT+BAC handler — sending
+BCS during SLC setup confuses Bluedroid's state machine
- Add post-SLC command handlers: AT+BIA (indicator activation),
AT+CCWA (call waiting), AT+CLIP (caller line ID) — without these
the HF drops the RFCOMM connection after ~22 seconds
- Route AT+VTS= to DTMF handler (standard HFP command, alongside
the non-standard AT+DTMF=)
- Fix simulate_call_end to handle OUTGOING/ALERTING call states
- Respect AT+BIA flags in _update_indicator
- Only send +CLIP during RING when HF has enabled it
- Clean up debug logging: remove file-based logger, use log.debug
- Add ruff per-file-ignores for dbus-fast D-Bus type annotations
Validated: 85/86 E2E tests PASS with ESP32 HFP Hands-Free Unit
- README: Add HFP AG to features, tools table (8 tools), architecture
diagram, project structure, and roadmap. Update total from 61 to 69.
- Docs site: Create reference page (hfp-ag-tools.md) and practical
guide (hfp-ag.md) covering AG enable, call simulation, volume,
indicators, AT commands, and E2E test flow.
- Update tools overview, architecture, introduction, and sidebar
to include HFP AG category.
dbus_fast maps BlueZ's WriteValue 'ay' parameter to bytearray internally.
Passing list(value) caused "can't concat list to bytearray" when the
library tried to serialize the argument.
23-page docs site following diataxis principles with guides,
reference, and explanation sections covering all 61 MCP tools.
Bluetooth-themed design with Pagefind search.
23 new tools for file transfer, phonebook access, and messaging
via obexd D-Bus API. Includes session management, transfer
monitoring, and daemon lifecycle tools.
- Add ASCII art banner and badges
- Add example conversation showing real usage
- Reorganize features with natural language examples
- Complete tools reference with counts (38 total)
- Detailed architecture diagram showing all layers
- Pairing agent documentation with SSP methods
- Requirements table with tested configurations
- Development guide with project structure
- Roadmap showing completed and planned features
Implements the org.bluez.Agent1 D-Bus interface to handle Bluetooth
pairing operations with three modes:
- elicit: MCP elicitation for PIN/confirmation (if client supports)
- interactive: Returns pending status for bt_pair_confirm calls
- auto: Auto-accepts pairings (for trusted environments)
Changes:
- New agent.py with BlueZAgent ServiceInterface
- Updated bt_pair to use agent with configurable timeout
- Updated bt_pair_confirm to respond to pending agent requests
- Added bt_pairing_status tool to check pending requests
- Removed PEP 563 future import from monitor.py for FastMCP compat
New monitor tools:
- bt_capture_start: Start background HCI capture to btsnoop file
- bt_capture_stop: Stop running capture by ID
- bt_capture_list_active: List active captures
- bt_capture_parse: Parse btsnoop into structured packet data
- bt_capture_analyze: Run btmon analysis on capture file
- bt_capture_read_raw: Read decoded packets via btmon
Features:
- Native btsnoop file parsing (no btmon needed for parse)
- Filter by packet type (HCI_CMD, ACL_DATA, HCI_EVENT, etc.)
- Filter by direction (TX/RX)
- Statistics and hex dump output
Note: Live capture requires CAP_NET_RAW or sudo.
Comprehensive BlueZ MCP server exposing Linux Bluetooth stack to LLMs:
- Adapter management (list, power, discoverable, pairable)
- Device discovery and management (scan, pair, connect, trust)
- Audio profiles with PipeWire/PulseAudio integration (A2DP/HFP switching)
- BLE/GATT support (services, characteristics, read/write/notify)
Built on:
- FastMCP 2.14.4 for MCP protocol
- dbus-fast 4.0.0 for async BlueZ D-Bus communication
- pulsectl-asyncio 1.2.2 for audio control
