mcbluetooth/docs-site/src/content/docs/reference/ble-tools.md

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

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

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

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

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

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

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

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