Document BLE notification capture feature
- 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
This commit is contained in:
parent
d9b66560d9
commit
192c4fc3cf
@ -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
|
||||
```
|
||||
|
||||
<Aside type="note">
|
||||
After enabling notifications, the device will send updates when values change. Currently, mcbluetooth enables the notification mode but doesn't provide a callback mechanism — use protocol capture to see the actual notifications.
|
||||
</Aside>
|
||||
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
|
||||
|
||||
|
||||
@ -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-..."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user