Bluetooth Low Energy

Use the Bluetooth provider to test a BLE peripheral from the host running Embedder. The provider uses Bleak and exposes a script-only helper API. Scan results, connections, GATT trees, and notifications publish to the Monitor’s Bluetooth tab while the script runs. This provider covers Bluetooth Low Energy GATT operations. It does not expose Bluetooth Classic workflows.

Check the host adapter

Run hardware_status and inspect the bluetooth provider. It reports:

Whether Python is available
Whether Embedder’s Python environment is ready
Whether a host BLE adapter was detected

Approve Bleak installation on first use. Platform requirements differ:

Host	Requirement
macOS	Grant the Embedder process Bluetooth permission in System Settings
Linux	Install BlueZ 5.43 or newer
Windows	Use Windows 10 or newer with the system WinRT BLE runtime

Scan before connecting

Scan for five seconds, filter advertised names containing "EFR32", and return
the address, name, RSSI, service UUIDs, and manufacturer data for each result.

ble_scan returns platform-specific addresses:

macOS returns a CoreBluetooth UUID.
Linux and Windows return a Bluetooth MAC address.

Pass the exact address value returned by the scan. Do not replace a macOS UUID with a printed device MAC from another tool. You can filter by a case-insensitive name substring or by advertised service UUIDs. Active scanning requests scan responses; passive scanning does not.

Connect and discover GATT

Discover services once after you connect:

.embedder/hardware/ble_gatt.py

candidates = ble_scan(duration_s=5.0, name_filter="EFR32")
if not candidates:
    ble_print_result(success=False, summary="No EFR32 device advertising")
    raise SystemExit

target = candidates[0]
handle = ble_connect(target["address"])
try:
    services = ble_list_services(handle)
finally:
    ble_disconnect(handle)

ble_print_result(
    success=True,
    summary="Read BLE GATT database",
    data={"address": target["address"], "services": services},
)

ble_list_services returns services, characteristic UUIDs and properties, and descriptor UUIDs and handles. It also populates the GATT tree in the Bluetooth tab. The provider caches characteristic handles for that connection so later reads and writes do not walk the database again.

Read and write characteristics

Connect to the scanned device, list its services, read characteristic
00002a19-0000-1000-8000-00805f9b34fb, and return the raw bytes in hex.

Characteristic reads return bytes. Interpret them only with the service specification or project protocol. For a write, state whether you need an acknowledgement:

response=True uses Write With Response.
response=False uses Write Without Response.

Write data can be bytes, a byte array, a list of byte values, or a hexadecimal string. The helper returns the number of bytes written.

A GATT write can change configuration, start an OTA path, or control an actuator. Name the characteristic, payload, and expected result before you ask Embedder to write.

Descriptor helpers can read or write a descriptor such as CCCD 0x2902. Use the characteristic UUID and descriptor UUID returned by discovery.

Collect notifications

Notifications arrive asynchronously. Use this sequence:

Call ble_subscribe with the connection handle and characteristic UUID.

Collect a bounded window

Call ble_collect_notifications for the duration you need. Filter by characteristic when several subscriptions are active.

Unsubscribe

Call ble_unsubscribe to release the subscription.

Disconnect

Call ble_disconnect before the script exits.

.embedder/hardware/ble_notifications.py

HEART_RATE = "00002a37-0000-1000-8000-00805f9b34fb"

candidates = ble_scan(duration_s=5.0, name_filter="Sensor")
if not candidates:
    ble_print_result(success=False, summary="No Sensor device advertising")
    raise SystemExit

target = candidates[0]
handle = ble_connect(target["address"])
subscribed = False
try:
    ble_list_services(handle)
    ble_subscribe(handle, HEART_RATE)
    subscribed = True
    samples = ble_collect_notifications(
        handle,
        duration_s=10.0,
        char_uuid=HEART_RATE,
    )
finally:
    if subscribed:
        ble_unsubscribe(handle, HEART_RATE)
    ble_disconnect(handle)

ble_print_result(
    success=len(samples) > 0,
    summary=f"Collected {len(samples)} notifications",
    data={"samples": samples},
)

Each returned entry includes the connection handle, address, characteristic UUID, hexadecimal value, and timestamp. The Bluetooth tab receives notification events live even before the script drains its buffer.

Mark test phases

Use ble_publish_event to add a script milestone to the Bluetooth event log:

ble_publish_event("ota_start", {"image": "app.gbl"})

This marker helps you compare a GATT action with notifications emitted later in the same script.

Manage connections

The script runner disconnects open BLE handles during cleanup. Still disconnect explicitly when you:

Connect to several devices
Run a long background script
Need to reconnect during the same script

ble_get_rssi returns the current connection RSSI when the host backend provides it. Some Linux BlueZ versions return no post-connect RSSI.

Fix BLE problems

A macOS scan returns nothing

Open System Settings, go to Privacy & Security, then Bluetooth, and grant permission to the process running Embedder. Retry the scan after permission is enabled.

The address does not connect

Scan again and pass the returned platform-specific address. Confirm that the peripheral is still advertising and not connected to another central.

A characteristic is not found

Run service discovery and use the UUID returned by the GATT tree. Do not assume a short UUID when the backend returned a full 128-bit UUID.

No notifications arrive

Check the characteristic’s notify or indicate property, subscribe before triggering the peripheral, and keep the collection window open long enough.

A write has no visible result

Use Write With Response when the characteristic supports it, then read back or wait for the protocol’s acknowledgement notification.

Hardware scripts

Keep BLE workflows and result JSON under a hardware lease.

Power analyzer

Measure radio activity and sleep current during a BLE test.

Get started

Core concepts

Complex workflows

Monitor and debug

Project tools

Customize

Integrations

Automation

CLI

Reference

API

Bluetooth Low Energy

Check the host adapter

Scan before connecting

Connect and discover GATT

Read and write characteristics

Collect notifications

Mark test phases

Manage connections

Fix BLE problems

Hardware scripts

Power analyzer

​Check the host adapter

​Scan before connecting

​Connect and discover GATT

​Read and write characteristics

​Collect notifications

​Mark test phases

​Manage connections

​Fix BLE problems

Hardware scripts

Power analyzer

Check the host adapter

Scan before connecting

Connect and discover GATT

Read and write characteristics

Collect notifications

Mark test phases

Manage connections

Fix BLE problems