Ryan Malloy
9d1c0f3e0f
23-page docs site following diataxis principles with guides, reference, and explanation sections covering all 61 MCP tools. Bluetooth-themed design with Pagefind search.
284 lines
6.5 KiB
Markdown
284 lines
6.5 KiB
Markdown
---
|
|
title: BLE Tools
|
|
description: Reference for Bluetooth Low Energy and GATT tools
|
|
---
|
|
|
|
Tools for interacting with Bluetooth Low Energy devices — sensors, fitness trackers, IoT devices, and more.
|
|
|
|
## bt_ble_scan
|
|
|
|
Scan for BLE (Bluetooth Low Energy) devices.
|
|
|
|
**Parameters:**
|
|
|
|
| Name | Type | Required | Default | Description |
|
|
|------|------|----------|---------|-------------|
|
|
| `adapter` | string | Yes | - | Adapter name |
|
|
| `timeout` | integer | No | 10 | Scan duration in seconds |
|
|
| `name_filter` | string | No | - | Only devices with name containing this |
|
|
| `service_filter` | string | No | - | Only devices advertising this service UUID |
|
|
|
|
**Returns:**
|
|
```json
|
|
[
|
|
{
|
|
"address": "AA:BB:CC:DD:EE:FF",
|
|
"name": "Heart Rate Monitor",
|
|
"rssi": -65,
|
|
"uuids": ["0000180d-0000-1000-8000-00805f9b34fb"],
|
|
"manufacturer_data": {"76": "02150201..."},
|
|
"service_data": {}
|
|
}
|
|
]
|
|
```
|
|
|
|
**Example:**
|
|
```
|
|
# Basic scan
|
|
bt_ble_scan adapter="hci0" timeout=10
|
|
|
|
# Filter by name
|
|
bt_ble_scan adapter="hci0" name_filter="Fitness"
|
|
|
|
# Filter by service (Heart Rate)
|
|
bt_ble_scan adapter="hci0" service_filter="0000180d-0000-1000-8000-00805f9b34fb"
|
|
```
|
|
|
|
---
|
|
|
|
## bt_ble_services
|
|
|
|
List GATT services for a connected BLE device.
|
|
|
|
**Parameters:**
|
|
|
|
| Name | Type | Required | Description |
|
|
|------|------|----------|-------------|
|
|
| `adapter` | string | Yes | Adapter name |
|
|
| `address` | string | Yes | Device MAC address |
|
|
|
|
**Returns:**
|
|
```json
|
|
[
|
|
{
|
|
"uuid": "0000180f-0000-1000-8000-00805f9b34fb",
|
|
"primary": true,
|
|
"description": "Battery Service"
|
|
},
|
|
{
|
|
"uuid": "0000180d-0000-1000-8000-00805f9b34fb",
|
|
"primary": true,
|
|
"description": "Heart Rate Service"
|
|
}
|
|
]
|
|
```
|
|
|
|
**Example:**
|
|
```
|
|
bt_ble_services adapter="hci0" address="AA:BB:CC:DD:EE:FF"
|
|
```
|
|
|
|
**Notes:**
|
|
- Device must be connected first
|
|
- Wait 2-3 seconds after connecting for service discovery
|
|
|
|
---
|
|
|
|
## bt_ble_characteristics
|
|
|
|
List GATT characteristics for a BLE device.
|
|
|
|
**Parameters:**
|
|
|
|
| Name | Type | Required | Default | Description |
|
|
|------|------|----------|---------|-------------|
|
|
| `adapter` | string | Yes | - | Adapter name |
|
|
| `address` | string | Yes | - | Device MAC address |
|
|
| `service_uuid` | string | No | - | Filter to this service only |
|
|
|
|
**Returns:**
|
|
```json
|
|
[
|
|
{
|
|
"uuid": "00002a19-0000-1000-8000-00805f9b34fb",
|
|
"service_uuid": "0000180f-0000-1000-8000-00805f9b34fb",
|
|
"flags": ["read", "notify"],
|
|
"description": "Battery Level"
|
|
}
|
|
]
|
|
```
|
|
|
|
**Example:**
|
|
```
|
|
# All characteristics
|
|
bt_ble_characteristics adapter="hci0" address="AA:BB:CC:DD:EE:FF"
|
|
|
|
# Filter by service
|
|
bt_ble_characteristics adapter="hci0" address="..." service_uuid="0000180f-0000-1000-8000-00805f9b34fb"
|
|
```
|
|
|
|
---
|
|
|
|
## bt_ble_read
|
|
|
|
Read a GATT characteristic value.
|
|
|
|
**Parameters:**
|
|
|
|
| Name | Type | Required | Description |
|
|
|------|------|----------|-------------|
|
|
| `adapter` | string | Yes | Adapter name |
|
|
| `address` | string | Yes | Device MAC address |
|
|
| `char_uuid` | string | Yes | Characteristic UUID |
|
|
|
|
**Returns:**
|
|
```json
|
|
{
|
|
"uuid": "00002a19-0000-1000-8000-00805f9b34fb",
|
|
"hex": "4b",
|
|
"decoded": 75,
|
|
"description": "Battery Level: 75%"
|
|
}
|
|
```
|
|
|
|
**Example:**
|
|
```
|
|
bt_ble_read adapter="hci0" address="AA:BB:CC:DD:EE:FF" char_uuid="00002a19-0000-1000-8000-00805f9b34fb"
|
|
```
|
|
|
|
**Notes:**
|
|
- Characteristic must have `read` flag
|
|
- Device must be connected
|
|
|
|
---
|
|
|
|
## bt_ble_write
|
|
|
|
Write a value to a GATT characteristic.
|
|
|
|
**Parameters:**
|
|
|
|
| Name | Type | Required | Default | Description |
|
|
|------|------|----------|---------|-------------|
|
|
| `adapter` | string | Yes | - | Adapter name |
|
|
| `address` | string | Yes | - | Device MAC address |
|
|
| `char_uuid` | string | Yes | - | Characteristic UUID |
|
|
| `value` | string | Yes | - | Value to write |
|
|
| `value_type` | string | No | "hex" | How to interpret value: "hex", "string", "int" |
|
|
| `with_response` | boolean | No | true | Wait for write acknowledgment |
|
|
|
|
**Value Types:**
|
|
| Type | Example | Bytes Written |
|
|
|------|---------|---------------|
|
|
| `hex` | "0102ff" | 0x01, 0x02, 0xFF |
|
|
| `string` | "hello" | UTF-8 encoded |
|
|
| `int` | "42" | Single byte (0-255) |
|
|
|
|
**Returns:**
|
|
```json
|
|
{
|
|
"status": "written",
|
|
"uuid": "...",
|
|
"bytes_written": 3
|
|
}
|
|
```
|
|
|
|
**Example:**
|
|
```
|
|
# Write hex bytes
|
|
bt_ble_write adapter="hci0" address="..." char_uuid="..." value="0102ff" value_type="hex"
|
|
|
|
# Write string
|
|
bt_ble_write adapter="hci0" address="..." char_uuid="..." value="hello" value_type="string"
|
|
|
|
# Write without waiting for response (faster)
|
|
bt_ble_write adapter="hci0" address="..." char_uuid="..." value="01" with_response=false
|
|
```
|
|
|
|
---
|
|
|
|
## bt_ble_notify
|
|
|
|
Enable or disable notifications for a characteristic.
|
|
|
|
**Parameters:**
|
|
|
|
| Name | Type | Required | Description |
|
|
|------|------|----------|-------------|
|
|
| `adapter` | string | Yes | Adapter name |
|
|
| `address` | string | Yes | Device MAC address |
|
|
| `char_uuid` | string | Yes | Characteristic UUID |
|
|
| `enable` | boolean | Yes | true to enable, false to disable |
|
|
|
|
**Returns:**
|
|
```json
|
|
{
|
|
"status": "notifications_enabled",
|
|
"uuid": "00002a37-0000-1000-8000-00805f9b34fb"
|
|
}
|
|
```
|
|
|
|
**Example:**
|
|
```
|
|
# Enable heart rate notifications
|
|
bt_ble_notify adapter="hci0" address="..." char_uuid="00002a37-0000-1000-8000-00805f9b34fb" enable=true
|
|
|
|
# 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
|
|
|
|
---
|
|
|
|
## bt_ble_battery
|
|
|
|
Read battery level from a BLE device (convenience function).
|
|
|
|
**Parameters:**
|
|
|
|
| Name | Type | Required | Description |
|
|
|------|------|----------|-------------|
|
|
| `adapter` | string | Yes | Adapter name |
|
|
| `address` | string | Yes | Device MAC address |
|
|
|
|
**Returns:**
|
|
```json
|
|
{
|
|
"battery_level": 75,
|
|
"unit": "percent"
|
|
}
|
|
```
|
|
|
|
**Example:**
|
|
```
|
|
bt_ble_battery adapter="hci0" address="AA:BB:CC:DD:EE:FF"
|
|
```
|
|
|
|
**Notes:**
|
|
- Uses standard Battery Service (UUID 0x180F)
|
|
- Returns error if device doesn't support battery service
|
|
|
|
## Common UUIDs
|
|
|
|
### Services
|
|
|
|
| Service | Short UUID | Full UUID |
|
|
|---------|------------|-----------|
|
|
| Battery | 0x180F | 0000180f-0000-1000-8000-00805f9b34fb |
|
|
| Heart Rate | 0x180D | 0000180d-0000-1000-8000-00805f9b34fb |
|
|
| Device Info | 0x180A | 0000180a-0000-1000-8000-00805f9b34fb |
|
|
| Generic Access | 0x1800 | 00001800-0000-1000-8000-00805f9b34fb |
|
|
|
|
### Characteristics
|
|
|
|
| Characteristic | Short UUID | Service |
|
|
|----------------|------------|---------|
|
|
| Battery Level | 0x2A19 | Battery |
|
|
| Heart Rate Measurement | 0x2A37 | Heart Rate |
|
|
| Manufacturer Name | 0x2A29 | Device Info |
|
|
| Model Number | 0x2A24 | Device Info |
|