diff --git a/docs-site/src/content/docs/guides/ble.md b/docs-site/src/content/docs/guides/ble.md index a250a78..d91d2af 100644 --- a/docs-site/src/content/docs/guides/ble.md +++ b/docs-site/src/content/docs/guides/ble.md @@ -132,7 +132,7 @@ bt_ble_write ... with_response=false ## Notifications -Subscribe to value changes: +BLE notifications let devices push data when values change — essential for real-time sensor data like heart rate, temperature, or button presses. ### Enable Notifications @@ -140,9 +140,60 @@ Subscribe to value changes: bt_ble_notify adapter="hci0" address="..." char_uuid="00002a37-..." enable=true ``` - +Returns: +```json +{ + "status": "notifications_enabled", + "uuid": "00002a37-0000-1000-8000-00805f9b34fb", + "uuid_short": "0x2A37", + "resource_uri": "bluetooth://ble/AA:BB:CC:DD:EE:FF/00002a37-.../notifications", + "history_uri": "bluetooth://ble/AA:BB:CC:DD:EE:FF/00002a37-.../notifications/history" +} +``` + +### Reading Notification Values + +Notification values are automatically buffered (up to 100) and accessible via MCP resources: + +``` +# Latest value and stats +ReadMcpResource uri="bluetooth://ble/AA:BB:CC:DD:EE:FF/00002a37-.../notifications" + +# Buffered history +ReadMcpResource uri="bluetooth://ble/AA:BB:CC:DD:EE:FF/00002a37-.../notifications/history" +``` + +**Latest notification resource:** +```json +{ + "address": "AA:BB:CC:DD:EE:FF", + "characteristic_uuid": "00002a37-...", + "notifying": true, + "latest": { + "timestamp": "2026-02-09T20:05:39.091206+00:00", + "value_hex": "1648", + "value_bytes": [22, 72] + }, + "buffer_count": 15, + "total_received": 47 +} +``` + +### Check Active Subscriptions + +``` +bt_ble_notification_status +``` + +Returns all active notification subscriptions with buffer stats. + +### Clear Notification Buffer + +``` +bt_ble_clear_notification_buffer adapter="hci0" address="..." char_uuid="..." +``` + +Clears buffered values while keeping the subscription active. ### Disable Notifications diff --git a/docs-site/src/content/docs/reference/ble-tools.md b/docs-site/src/content/docs/reference/ble-tools.md index 98e5e1e..36be4b2 100644 --- a/docs-site/src/content/docs/reference/ble-tools.md +++ b/docs-site/src/content/docs/reference/ble-tools.md @@ -199,7 +199,7 @@ bt_ble_write adapter="hci0" address="..." char_uuid="..." value="01" with_respon ## bt_ble_notify -Enable or disable notifications for a characteristic. +Enable or disable notifications for a characteristic. When enabled, notification values are automatically buffered and accessible via MCP resources. **Parameters:** @@ -210,10 +210,21 @@ Enable or disable notifications for a characteristic. | `char_uuid` | string | Yes | Characteristic UUID | | `enable` | boolean | Yes | true to enable, false to disable | -**Returns:** +**Returns (enable=true):** ```json { "status": "notifications_enabled", + "uuid": "00002a37-0000-1000-8000-00805f9b34fb", + "uuid_short": "0x2A37", + "resource_uri": "bluetooth://ble/AA:BB:CC:DD:EE:FF/00002a37-.../notifications", + "history_uri": "bluetooth://ble/AA:BB:CC:DD:EE:FF/00002a37-.../notifications/history" +} +``` + +**Returns (enable=false):** +```json +{ + "status": "notifications_disabled", "uuid": "00002a37-0000-1000-8000-00805f9b34fb" } ``` @@ -223,14 +234,77 @@ Enable or disable notifications for a characteristic. # Enable heart rate notifications bt_ble_notify adapter="hci0" address="..." char_uuid="00002a37-0000-1000-8000-00805f9b34fb" enable=true +# Read notification values via MCP resource +ReadMcpResource uri="bluetooth://ble/.../notifications" + # Disable notifications bt_ble_notify adapter="hci0" address="..." char_uuid="..." enable=false ``` **Notes:** - Characteristic must have `notify` flag -- Notifications are delivered via GATT protocol -- Use protocol capture to see notification data +- Notifications are buffered (up to 100 values) in a circular buffer +- Access buffered values via `resource_uri` or `history_uri` + +--- + +## bt_ble_notification_status + +List all active BLE notification subscriptions. + +**Parameters:** None + +**Returns:** +```json +{ + "count": 2, + "subscriptions": [ + { + "address": "AA:BB:CC:DD:EE:FF", + "char_uuid": "00002a37-0000-1000-8000-00805f9b34fb", + "uuid_short": "0x2A37", + "notifying": true, + "buffer_count": 15, + "total_received": 47, + "resource_uri": "bluetooth://ble/.../notifications", + "history_uri": "bluetooth://ble/.../notifications/history" + } + ] +} +``` + +**Example:** +``` +bt_ble_notification_status +``` + +--- + +## bt_ble_clear_notification_buffer + +Clear the notification buffer for a characteristic while keeping the subscription active. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `adapter` | string | Yes | Adapter name | +| `address` | string | Yes | Device MAC address | +| `char_uuid` | string | Yes | Characteristic UUID | + +**Returns:** +```json +{ + "status": "buffer_cleared", + "uuid": "00002a37-0000-1000-8000-00805f9b34fb", + "cleared_count": 15 +} +``` + +**Example:** +``` +bt_ble_clear_notification_buffer adapter="hci0" address="AA:BB:CC:DD:EE:FF" char_uuid="00002a37-..." +``` --- diff --git a/docs-site/src/content/docs/reference/resources.md b/docs-site/src/content/docs/reference/resources.md index bea1575..e83eeea 100644 --- a/docs-site/src/content/docs/reference/resources.md +++ b/docs-site/src/content/docs/reference/resources.md @@ -16,6 +16,9 @@ mcbluetooth exposes live Bluetooth state through MCP resources. These provide re | `bluetooth://trusted` | Trusted devices | | `bluetooth://adapter/{name}` | Specific adapter details | | `bluetooth://device/{address}` | Specific device details | +| `bluetooth://ble/notifications` | All active BLE notification subscriptions | +| `bluetooth://ble/{address}/{uuid}/notifications` | Latest notification value and stats | +| `bluetooth://ble/{address}/{uuid}/notifications/history` | Buffered notification history | ## Adapter Resources @@ -195,3 +198,85 @@ Resources can be read using the standard MCP resource protocol: - Connecting/disconnecting - Sending files - Changing settings + +## BLE Notification Resources + +These resources provide access to buffered BLE GATT notification values. + +### bluetooth://ble/notifications + +Lists all active notification subscriptions. + +**Response:** +```json +{ + "count": 1, + "subscriptions": [ + { + "address": "AA:BB:CC:DD:EE:FF", + "char_uuid": "00002a37-0000-1000-8000-00805f9b34fb", + "char_path": "/org/bluez/hci0/dev_.../service.../char...", + "notifying": true, + "buffer_count": 15, + "total_received": 47, + "uuid_short": "0x2A37" + } + ] +} +``` + +### bluetooth://ble/{address}/{uuid}/notifications + +Get latest notification value and buffer statistics. + +**URI:** `bluetooth://ble/AA:BB:CC:DD:EE:FF/00002a37-0000-1000-8000-00805f9b34fb/notifications` + +**Response:** +```json +{ + "address": "AA:BB:CC:DD:EE:FF", + "characteristic_uuid": "00002a37-0000-1000-8000-00805f9b34fb", + "characteristic_uuid_short": "0x2A37", + "notifying": true, + "latest": { + "timestamp": "2026-02-09T20:05:39.091206+00:00", + "value_hex": "1648", + "value_bytes": [22, 72] + }, + "buffer_count": 15, + "total_received": 47 +} +``` + +### bluetooth://ble/{address}/{uuid}/notifications/history + +Get buffered notification history (up to 100 values). + +**URI:** `bluetooth://ble/AA:BB:CC:DD:EE:FF/00002a37-.../notifications/history?count=10` + +**Response:** +```json +{ + "address": "AA:BB:CC:DD:EE:FF", + "characteristic_uuid": "00002a37-...", + "count": 10, + "values": [ + { + "timestamp": "2026-02-09T20:05:39.091206+00:00", + "value_hex": "1648", + "value_bytes": [22, 72] + }, + { + "timestamp": "2026-02-09T20:05:38.091206+00:00", + "value_hex": "1647", + "value_bytes": [22, 71] + } + ] +} +``` + +**Notes:** +- Enable notifications with `bt_ble_notify` first +- Notifications are buffered in a circular buffer (max 100 values) +- Buffer persists for the MCP server session lifetime +- Use `bt_ble_clear_notification_buffer` to clear without disabling