mcbluetooth/docs-site/src/content/docs/guides/ble.md

---
title: BLE & GATT
description: Interact with Bluetooth Low Energy devices — sensors, fitness trackers, and IoT
---

import { Aside } from '@astrojs/starlight/components';

Bluetooth Low Energy (BLE) devices use GATT (Generic Attribute Profile) to expose services and characteristics. mcbluetooth provides tools to discover, read, write, and subscribe to BLE data.

## BLE Scanning

### Basic Scan

```
bt_ble_scan adapter="hci0" timeout=10
```

### Filtered Scan

```
# Filter by name
bt_ble_scan adapter="hci0" name_filter="Fitness"

# Filter by service UUID
bt_ble_scan adapter="hci0" service_filter="0000180d-0000-1000-8000-00805f9b34fb"
```

## GATT Structure

BLE devices organize data hierarchically:

```
Device
└── Service (UUID: 0000180d-...)     ← Heart Rate Service
    ├── Characteristic (UUID: 00002a37-...)  ← Heart Rate Measurement
    │   └── Descriptor              ← Client Configuration
    └── Characteristic (UUID: 00002a38-...)  ← Body Sensor Location
```

## Discover Services

After connecting:

```
bt_ble_services adapter="hci0" address="AA:BB:CC:DD:EE:FF"
```

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"
  }
]
```

## List Characteristics

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

Returns:
```json
[
  {
    "uuid": "00002a19-0000-1000-8000-00805f9b34fb",
    "flags": ["read", "notify"],
    "description": "Battery Level"
  }
]
```

## Read Values

### Read Battery Level (Shortcut)

```
bt_ble_battery adapter="hci0" address="AA:BB:CC:DD:EE:FF"
```

Returns battery percentage (0-100).

### Read Any Characteristic

```
bt_ble_read adapter="hci0" address="..." char_uuid="00002a19-0000-1000-8000-00805f9b34fb"
```

Returns:
```json
{
  "hex": "4b",
  "decoded": 75,
  "description": "Battery Level: 75%"
}
```

## Write Values

```
# 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 integer
bt_ble_write adapter="hci0" address="..." char_uuid="..." value="42" value_type="int"
```

### Write with/without Response

```
# With response (default) - waits for acknowledgment
bt_ble_write ... with_response=true

# Without response (faster, less reliable)
bt_ble_write ... with_response=false
```

## Notifications

Subscribe to value changes:

### Enable Notifications

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

### Disable Notifications

```
bt_ble_notify adapter="hci0" address="..." char_uuid="..." enable=false
```

## Common UUIDs

### Standard Services

| Service | UUID | Description |
|---------|------|-------------|
| Generic Access | `0x1800` | Device name, appearance |
| Generic Attribute | `0x1801` | Service change indication |
| Battery | `0x180F` | Battery level |
| Device Information | `0x180A` | Manufacturer, model, etc. |
| Heart Rate | `0x180D` | Heart rate measurement |
| Health Thermometer | `0x1809` | Temperature |
| Blood Pressure | `0x1810` | Blood pressure |

### Standard Characteristics

| Characteristic | UUID | Service |
|----------------|------|---------|
| Battery Level | `0x2A19` | Battery |
| Heart Rate Measurement | `0x2A37` | Heart Rate |
| Temperature Measurement | `0x2A1C` | Health Thermometer |
| Manufacturer Name | `0x2A29` | Device Information |
| Model Number | `0x2A24` | Device Information |

<Aside type="tip">
Full UUIDs are `0000XXXX-0000-1000-8000-00805f9b34fb` where `XXXX` is the short UUID.
</Aside>

## Example: Heart Rate Monitor

```
# Scan for heart rate monitors
bt_ble_scan adapter="hci0" service_filter="0000180d-0000-1000-8000-00805f9b34fb"

# Connect
bt_connect adapter="hci0" address="AA:BB:CC:DD:EE:FF"

# List services
bt_ble_services adapter="hci0" address="..."

# Enable heart rate notifications
bt_ble_notify adapter="hci0" address="..." char_uuid="00002a37-0000-1000-8000-00805f9b34fb" enable=true

# Read body sensor location
bt_ble_read adapter="hci0" address="..." char_uuid="00002a38-0000-1000-8000-00805f9b34fb"
```

## Example: Smart Light Bulb

```
# Connect to bulb
bt_connect adapter="hci0" address="AA:BB:CC:DD:EE:FF"

# Find the control characteristic (vendor-specific)
bt_ble_characteristics adapter="hci0" address="..."

# Write command to turn on (example - actual commands vary by device)
bt_ble_write adapter="hci0" address="..." char_uuid="..." value="01" value_type="hex"

# Set color (RGB example)
bt_ble_write adapter="hci0" address="..." char_uuid="..." value="ff0000" value_type="hex"
```

## Troubleshooting

### "ServicesResolved: false"

Services aren't discovered yet. Wait a moment after connecting:

```
bt_connect adapter="hci0" address="..."
# Wait 2-3 seconds
bt_ble_services adapter="hci0" address="..."
```

### Can't Read Characteristic

Check the characteristic flags:
- `read` must be present for reading
- `write` or `write-without-response` for writing
- `notify` for notifications

### Connection Drops Frequently

BLE has limited connection capacity. Try:
- Disconnecting other BLE devices
- Moving closer to the adapter
- Checking device battery level