Use this skill whenever the user needs to interact with BLE peripherals through the workbench — scanning for devices, connecting by address, writing to GATT characteristics, or checking connection status. The Pi acts as a BLE-to-HTTP bridge using bleak. Also use when sending keystrokes to BLE HID devices, triggering OTA via BLE commands, or debugging BLE connectivity. Triggers on "BLE", "bluetooth", "GATT", "NUS", "Nordic UART", "BLE scan", "BLE write", "BLE connect".
Base URL: http://workbench.local:8080
Before using any workbench API, ensure workbench.local resolves:
curl -s http://workbench.local:8080/api/info
If that fails, run the discovery script from the workbench repo:
sudo python3 .claude/skills/esp-idf-handling/discover-workbench.py --hosts
| Method | Path | Purpose |
|---|---|---|
| POST | /api/ble/scan | Scan for BLE devices (optional name filter) |
| POST | /api/ble/connect | Connect to a device by MAC address |
| POST | /api/ble/write | Write hex data to a GATT characteristic |
| POST | /api/ble/disconnect | Disconnect current device |
| GET | /api/ble/status | Connection state and device info |
One BLE connection at a time.
# Scan for BLE devices (5s timeout)
curl -X POST http://workbench.local:8080/api/ble/scan \
-H 'Content-Type: application/json' \
-d '{"timeout": 5}'
# Scan with name filter
curl -X POST http://workbench.local:8080/api/ble/scan \
-H 'Content-Type: application/json' \
-d '{"timeout": 5, "name_filter": "iOS-Keyboard"}'
# Connect by MAC address
curl -X POST http://workbench.local:8080/api/ble/connect \
-H 'Content-Type: application/json' \
-d '{"address": "AA:BB:CC:DD:EE:FF"}'
# Write hex data to a GATT characteristic
curl -X POST http://workbench.local:8080/api/ble/write \
-H 'Content-Type: application/json' \
-d '{"characteristic": "6e400002-b5a3-f393-e0a9-e50e24dcca9e", "data": "48656c6c6f", "response": true}'
# Check connection status
curl http://workbench.local:8080/api/ble/status
# Disconnect
curl -X POST http://workbench.local:8080/api/ble/disconnect
| UUID | Role |
|---|---|
6e400001-b5a3-f393-e0a9-e50e24dcca9e | NUS Service |
6e400002-b5a3-f393-e0a9-e50e24dcca9e | RX Characteristic (write to this) |
6e400003-b5a3-f393-e0a9-e50e24dcca9e | TX Characteristic (notifications from device) |
Send a command via NUS:
POST /api/ble/scan with name_filter to find devicePOST /api/ble/connect with the MAC address from scan resultsPOST /api/ble/write with NUS RX UUID and hex-encoded commandPOST /api/ble/disconnect when doneCheck if device is advertising:
POST /api/ble/scan with short timeout and name filterdevices array in responseSend binary command protocol:
0x02 + "Hello" = 0248656c6c6f)| Problem | Fix |
|---|---|
| "BLE not available" | bleak not installed on workbench Pi |
| Scan returns empty | Increase timeout; check device is advertising |
| Connect fails (409) | Already connected — disconnect first |
| Write fails "invalid hex data" | Data must be hex string (e.g., "48656c6c6f" for "Hello") |
| Device not found by name | Check exact advertised name; BLE names are case-sensitive |