How to Use OpenClaw to Scan and Control BLE Devices from Your Terminal
Most BLE workflows look like this: write a Python script with bleak, fight with bluetoothctl for 20 minutes, grep through UUIDs you copied from a datasheet, and pray the connection doesn’t drop mid-read. You end up with 40 lines of boilerplate just to check a battery level. And if you want to talk to a different device? Start over.
OpenClaw replaces that with terminal commands and, when you want it, natural language. You scan, connect, read, and write BLE characteristics through a single interface. The AI agent layer means you can eventually say “turn on the living room light” instead of memorizing 0xFFE1.
Here’s what you’ll do in this guide: find nearby BLE peripherals, connect to one, read a sensor value, and send a control command.
This assumes you’ve already installed OpenClaw and run a basic agent at least once.
What You Need Before Starting
Operating system. Linux with the BlueZ stack or macOS. Windows support is limited and unreliable for BLE tooling; if you’re on Windows, consider WSL2 with USB passthrough.
Bluetooth adapter. Your machine needs a BLE-capable adapter. Check on Linux:
hciconfigOn macOS:
system_profiler SPBluetoothDataTypeIf you see an adapter listed, you’re good.
Permissions (Linux). BLE scanning requires elevated privileges. Either add your user to the bluetooth group or run with sudo. The group approach is cleaner:
sudo usermod -aG bluetooth $USER
# Log out and back in for this to take effectOpenClaw BLE plugin. Enable it in your config:
openclaw plugin enable bleQuick sanity check:
[x] OpenClaw installed (v0.x+)
[x] Bluetooth adapter present and enabled
[x] BLE plugin enabled in OpenClaw config
[x] User has bluetooth permissionsScanning for Nearby BLE Devices
openclaw ble scan --timeout 10This broadcasts a scan request for 10 seconds and collects advertisement packets from any BLE peripheral in range. Typical output:
Scanning for BLE devices...
NAME ADDRESS RSSI
─────────────────────── ─────────────────── ────────
Living Room Bulb AA:BB:CC:11:22:33 -42 dBm
TempSensor-017 DD:EE:FF:44:55:66 -58 dBm
Unknown 11:22:33:AA:BB:CC -71 dBm
Mi Band 6 77:88:99:DD:EE:FF -65 dBm
Found 4 devices in 10s.RSSI (Received Signal Strength Indicator) tells you how close the device is. Closer to 0 means stronger signal; -42 dBm is nearby, -71 dBm is across the room or behind a wall. Devices showing “Unknown” don’t broadcast a name in their advertisement packets, which is common for accessories and beacons.
You can filter results if the list is noisy:
openclaw ble scan --timeout 10 --name "TempSensor"
openclaw ble scan --timeout 10 --rssi-min -60The first filters by name substring. The second only shows devices with signal strength above -60 dBm, roughly meaning “within a few meters.”
Connecting to a Device
Pick a device from your scan results and connect by MAC address:
openclaw ble connect AA:BB:CC:11:22:33Under the hood, this establishes a GATT (Generic Attribute Profile) connection, the protocol BLE devices use to expose their data as readable and writable attributes. You don’t need to think about it much; just know that “connected” means you can now browse what the device offers.
If the connection fails, the three most common reasons are:
- Out of range. Move closer. BLE range varies wildly, from 1 meter to 30+ meters depending on the device and environment.
- Device requires pairing. Some peripherals won’t let you connect until you pair. OpenClaw will prompt you if this is needed, or you can force it with
--pair. - Timeout. The device might be asleep or already connected to another host. Only one central device can hold a BLE connection at a time (usually).
# If pairing is needed:
openclaw ble connect AA:BB:CC:11:22:33 --pairDiscovering Services and Characteristics
Once connected, ask the device what it’s got:
openclaw ble services AA:BB:CC:11:22:33This lists the GATT hierarchy, which is a simple tree. A device exposes services, groups of related functions. Each service contains characteristics, the individual data points you can read or write. Characteristics may also have descriptors that provide metadata about the characteristic.
┌─────────────────────────────────┐
│ BLE Device │
│ "Living Room Bulb" │
├─────────────────────────────────┤
│ │
│ ┌── Service: 0x1800 (GAP) │
│ │ └── 0x2A00 (Device Name) │
│ │ │
│ ┌── Service: 0x180F (Battery) │
│ │ └── 0x2A19 (Bat. Level) │
│ │ [READ, NOTIFY] │
│ │ │
│ ┌── Service: 0xFFE0 (LED) │
│ └── 0xFFE1 (LED Ctrl) │
│ [READ, WRITE] │
│ │
└─────────────────────────────────┘Standard services like Battery (0x180F) have well-known UUIDs defined by the Bluetooth SIG. Custom services (like 0xFFE0 above) are manufacturer-specific. You’ll need the device’s documentation to know what they do, or you can let OpenClaw’s agent guess based on common patterns (more on that shortly).
The tags in brackets, [READ], [WRITE], [NOTIFY], tell you what operations are allowed on each characteristic.
Reading and Writing Characteristics
Reading a value. Let’s check the battery level:
openclaw ble read AA:BB:CC:11:22:33 0x2A19Output:
Characteristic 0x2A19 (Battery Level):
Raw: 0x5F
Decoded: 95%The raw byte 0x5F is 95 in decimal. OpenClaw decodes standard characteristics like battery level automatically. For custom ones, you’ll see the raw bytes and need to interpret them yourself.
Writing a value. Let’s turn on an LED by writing to the custom characteristic:
openclaw ble write AA:BB:CC:11:22:33 0xFFE1 0x01Output:
Write to 0xFFE1: 0x01
ACK received. Write successful.The pattern for every BLE interaction is the same: scan, connect, discover, then read or write on a characteristic. Every smart bulb, every heart rate monitor, every temperature sensor follows this flow. The only thing that changes is which UUIDs you’re targeting and what the byte values mean.
Here’s a full session, end to end:
openclaw ble scan --timeout 5
openclaw ble connect AA:BB:CC:11:22:33
openclaw ble services AA:BB:CC:11:22:33
openclaw ble read AA:BB:CC:11:22:33 0x2A19
openclaw ble write AA:BB:CC:11:22:33 0xFFE1 0x01Five commands. No scripts. No boilerplate.
AI Agent BLE Control: Talking Instead of Typing UUIDs
The commands above are clean, but you still need to know MAC addresses and UUIDs. The agent layer strips that away.
After you’ve done an initial scan (so OpenClaw has a device inventory), you can switch to conversational mode:
openclaw agent
> What's the battery level of TempSensor-017?
Connecting to TempSensor-017 (DD:EE:FF:44:55:66)...
Reading Battery Level (0x2A19)...
Battery level is 95%.Or for control:
> Turn on the Living Room Bulb
Connecting to Living Room Bulb (AA:BB:CC:11:22:33)...
Writing 0x01 to LED Control (0xFFE1)...
Done. LED is now on.User OpenClaw Agent BLE Device
│ │ │
│ "Turn on the LED" │ │
│ ──────────────────────────>│ │
│ │ Resolve device mapping │
│ │ Connect to AA:BB:CC:... │
│ │ ────────────────────────>│
│ │ Write 0x01 to 0xFFE1 │
│ │ ────────────────────────>│
│ │ ACK │
│ │ <────────────────────────│
│ "Done. LED is now on." │ │
│ <──────────────────────────│ │The agent tracks discovered devices and their services, matching your intent (“turn on the LED”) to the correct characteristic and value. This works best with standard BLE services and well-named custom ones. For obscure proprietary characteristics, you might need to help by labeling devices in your OpenClaw config.
If you’re building IoT projects that also need cloud connectivity, Hubble’s terrestrial SDK for BLE devices is worth a look. It handles the advertising packet structure that BLE devices broadcast, the same layer OpenClaw scans during discovery.
Fixing What Breaks
“No adapter found.” Check if the adapter is blocked:
rfkill list bluetooth
# If blocked:
rfkill unblock bluetoothAlso verify the adapter driver is loaded (lsmod | grep btusb on Linux).
“Connection refused” or “Device not appearing in scan.” For connection refusal, the device probably isn’t in pairing mode. Check its manual and confirm you’re within range (try getting within 2 meters for testing).
If a device doesn’t appear in scans, it may already be connected to another host (your phone, maybe). Disconnect it from the other host first. Some devices also stop advertising after a timeout and need a button press to restart.
“Permission denied.” On Linux, either join the bluetooth group (see setup section) or run with sudo. On macOS, you may need to grant Bluetooth access in System Settings > Privacy & Security.
Automations, Multi-Device Control, and Cloud Bridges
You’ve gone from zero to reading sensors and toggling LEDs, all from the terminal.
A few things to try next: set up time-based automations (e.g., turn off a light at midnight), combine BLE control with other OpenClaw tools for richer workflows, or build a custom smart home agent that manages multiple devices. If you’re curious about how BLE devices can also push data to the cloud through satellite or terrestrial networks, the Hubble device integration guide covers that bridge between local BLE and global connectivity.
The BLE protocol underneath all of this hasn’t changed. OpenClaw just removes the friction between you and a write 0x01.
Hubble Network enables BLE devices to transmit data directly to the cloud—no gateways, no extra infrastructure. See how it works →