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

title	description
BLE & GATT	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:

[
  {
    "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:

[
  {
    "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:

{
  "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

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.

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

Full UUIDs are `0000XXXX-0000-1000-8000-00805f9b34fb` where `XXXX` is the short UUID.

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