---
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. When enabled, notification values are automatically buffered and accessible via MCP resources.

**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 (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"
}
```

**Example:**
```
# 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 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-..."
```

---

## 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 |