mirror of
https://github.com/espressif/esp-idf.git
synced 2026-10-03 03:31:41 +03:00
docs(ble): document BLE UART bridge usage
This commit is contained in:
Zhou Xiao
zhiweijian
@@ -0,0 +1,286 @@
|
||||
<!-- SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD -->
|
||||
<!-- SPDX-License-Identifier: Apache-2.0 -->
|
||||
|
||||
# Porting BLE UART Bridge to Custom Scripts
|
||||
|
||||
This guide explains how to reuse BLE UART Bridge in your own Python scripts.
|
||||
|
||||
Use the Core API when the Console and Daemon are not the right abstraction for your application. For example, use Core directly when you want to implement custom framing, a test harness, a device provisioning flow, or a domain-specific automation script.
|
||||
|
||||
## Choose the right integration level
|
||||
|
||||
| Need | Recommended integration |
|
||||
| --- | --- |
|
||||
| Manual testing | Use `python main.py console DEVICE_ID` |
|
||||
| Local process talks to a BLE device through HTTP | Use Daemon mode |
|
||||
| Custom Python logic owns the BLE connection | Use `BLEUARTBridge` directly |
|
||||
| Custom service UUIDs or characteristics | Use `BLEUARTProfile` with `BLEUARTBridge` |
|
||||
|
||||
## Install dependencies
|
||||
|
||||
You can reuse the ESP-IDF Python environment, or use your own Python virtual environment. If you reuse the ESP-IDF environment, export it first and then install the extra dependencies required by BLE UART Bridge:
|
||||
|
||||
```bash
|
||||
cd $IDF_PATH
|
||||
. ./export.sh
|
||||
cd tools/ble/ble_uart_bridge
|
||||
python -m pip install -r requirements.txt
|
||||
```
|
||||
|
||||
On Windows, run `export.bat` or `export.ps1` from the ESP-IDF root directory before installing `requirements.txt`. If you use your own Python virtual environment instead, activate it before installing `requirements.txt`.
|
||||
|
||||
When importing from a script outside this directory, make sure `tools/ble/ble_uart_bridge` is on `PYTHONPATH`, or run the script from this directory.
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
PYTHONPATH=tools/ble/ble_uart_bridge python my_script.py
|
||||
```
|
||||
|
||||
## Basic script
|
||||
|
||||
The simplest script connects, sends one line, and disconnects:
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
|
||||
from src.core import BLEUARTBridge
|
||||
|
||||
|
||||
async def main() -> None:
|
||||
bridge = BLEUARTBridge("AA:BB:CC:DD:EE:FF")
|
||||
|
||||
try:
|
||||
if not await bridge.connect():
|
||||
raise RuntimeError("failed to connect")
|
||||
|
||||
await bridge.send("hello\n")
|
||||
finally:
|
||||
await bridge.disconnect()
|
||||
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
## Receive data with handlers
|
||||
|
||||
Register one or more RX handlers before connecting:
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
|
||||
from src.core import BLEUARTBridge
|
||||
|
||||
|
||||
def print_rx(data: bytearray) -> None:
|
||||
print("RX:", data.decode(errors="replace"))
|
||||
|
||||
|
||||
async def main() -> None:
|
||||
bridge = BLEUARTBridge("AA:BB:CC:DD:EE:FF")
|
||||
bridge.add_rx_handler(print_rx)
|
||||
|
||||
try:
|
||||
if not await bridge.connect():
|
||||
raise RuntimeError("failed to connect")
|
||||
|
||||
await bridge.send("help\n")
|
||||
await asyncio.sleep(2)
|
||||
finally:
|
||||
await bridge.disconnect()
|
||||
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
Handlers are synchronous callables. If your application needs async processing, push received data into an `asyncio.Queue`:
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
|
||||
from src.core import BLEUARTBridge
|
||||
|
||||
|
||||
async def main() -> None:
|
||||
bridge = BLEUARTBridge("AA:BB:CC:DD:EE:FF")
|
||||
rx_queue: asyncio.Queue[bytes] = asyncio.Queue()
|
||||
|
||||
def enqueue_rx(data: bytearray) -> None:
|
||||
rx_queue.put_nowait(bytes(data))
|
||||
|
||||
bridge.add_rx_handler(enqueue_rx)
|
||||
|
||||
try:
|
||||
if not await bridge.connect():
|
||||
raise RuntimeError("failed to connect")
|
||||
|
||||
await bridge.send("status\n")
|
||||
data = await asyncio.wait_for(rx_queue.get(), timeout=5.0)
|
||||
print("RX:", data)
|
||||
finally:
|
||||
await bridge.disconnect()
|
||||
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
## Send bytes instead of text
|
||||
|
||||
`BLEUARTBridge.send()` accepts `str`, `bytes`, and `bytearray`.
|
||||
|
||||
```python
|
||||
await bridge.send(b"\x01\x02\x03\x0a")
|
||||
await bridge.send(bytearray([0x01, 0x02, 0x03, 0x0A]))
|
||||
```
|
||||
|
||||
Use `with_response=True` when the target characteristic or debugging workflow should use BLE write-with-response:
|
||||
|
||||
```python
|
||||
await bridge.send(b"\x01\x02", with_response=True)
|
||||
```
|
||||
|
||||
## Use a custom BLE UART profile
|
||||
|
||||
The default profile uses Nordic UART Service UUIDs. For custom firmware, create a `BLEUARTProfile`:
|
||||
|
||||
```python
|
||||
from src.core import BLEUARTBridge
|
||||
from src.core import BLEUARTProfile
|
||||
|
||||
|
||||
profile = BLEUARTProfile(
|
||||
service_uuid="00000000-0000-0000-0000-000000000001",
|
||||
rx_char_uuid="00000000-0000-0000-0000-000000000002",
|
||||
tx_char_uuid="00000000-0000-0000-0000-000000000003",
|
||||
)
|
||||
|
||||
bridge = BLEUARTBridge("AA:BB:CC:DD:EE:FF", profile=profile)
|
||||
```
|
||||
|
||||
The naming follows BLE UART convention:
|
||||
|
||||
- RX characteristic: host writes to device.
|
||||
- TX characteristic: device notifies host.
|
||||
|
||||
## Implement your own request/response protocol
|
||||
|
||||
If your script needs request/response semantics, use a queue or future map and correlate responses at the application layer.
|
||||
|
||||
The daemon uses a lightweight JSONL envelope. You can reuse the same pattern:
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
import json
|
||||
from uuid import uuid4
|
||||
|
||||
from src.core import BLEUARTBridge
|
||||
|
||||
|
||||
async def main() -> None:
|
||||
bridge = BLEUARTBridge("AA:BB:CC:DD:EE:FF")
|
||||
rx_buffer = bytearray()
|
||||
pending: dict[str, asyncio.Future[object]] = {}
|
||||
|
||||
def handle_rx(data: bytearray) -> None:
|
||||
rx_buffer.extend(data)
|
||||
while b"\n" in rx_buffer:
|
||||
index = rx_buffer.index(b"\n")
|
||||
line = bytes(rx_buffer[:index])
|
||||
del rx_buffer[: index + 1]
|
||||
|
||||
message = json.loads(line.decode())
|
||||
request_id = message.get("id")
|
||||
future = pending.get(request_id)
|
||||
if future is None or future.done():
|
||||
continue
|
||||
|
||||
if message.get("ok") is False:
|
||||
future.set_exception(RuntimeError(str(message.get("error"))))
|
||||
else:
|
||||
future.set_result(message.get("data"))
|
||||
|
||||
bridge.add_rx_handler(handle_rx)
|
||||
|
||||
try:
|
||||
if not await bridge.connect():
|
||||
raise RuntimeError("failed to connect")
|
||||
|
||||
request_id = uuid4().hex
|
||||
loop = asyncio.get_running_loop()
|
||||
pending[request_id] = loop.create_future()
|
||||
|
||||
request = {"v": 1, "id": request_id, "op": "echo", "data": "hello"}
|
||||
await bridge.send(json.dumps(request) + "\n", with_response=True)
|
||||
|
||||
response = await asyncio.wait_for(pending[request_id], timeout=10.0)
|
||||
print(response)
|
||||
finally:
|
||||
await bridge.disconnect()
|
||||
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
For production scripts, add validation around incoming JSON and clean up `pending` entries on timeout.
|
||||
|
||||
## Scan for devices from Python
|
||||
|
||||
Use `scan_devices()` if your script needs to discover devices first:
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
|
||||
from src.core.scanner import scan_devices
|
||||
|
||||
|
||||
async def main() -> None:
|
||||
devices = await scan_devices(timeout=5.0)
|
||||
for device in devices:
|
||||
print(device.device_id, device.name, device.rssi)
|
||||
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
For custom service UUID discovery:
|
||||
|
||||
```python
|
||||
devices = await scan_devices(
|
||||
timeout=5.0,
|
||||
service_uuid="00000000-0000-0000-0000-000000000001",
|
||||
)
|
||||
```
|
||||
|
||||
## Error handling guidance
|
||||
|
||||
The current Core API returns `False` for connection or send failures and logs details through `loguru`.
|
||||
|
||||
Recommended script pattern:
|
||||
|
||||
```python
|
||||
if not await bridge.connect():
|
||||
raise RuntimeError("failed to connect to BLE UART device")
|
||||
|
||||
if not await bridge.send("hello\n"):
|
||||
raise RuntimeError("failed to send BLE UART data")
|
||||
```
|
||||
|
||||
Always disconnect in `finally`:
|
||||
|
||||
```python
|
||||
try:
|
||||
...
|
||||
finally:
|
||||
await bridge.disconnect()
|
||||
```
|
||||
|
||||
## Porting checklist
|
||||
|
||||
- [ ] Decide whether your use case needs Console, Daemon, or Core.
|
||||
- [ ] Confirm the BLE service and characteristic UUIDs.
|
||||
- [ ] Decide whether your payload is text, binary, JSON, or another framing format.
|
||||
- [ ] Register RX handlers before calling `connect()`.
|
||||
- [ ] Add a newline delimiter if your protocol is JSONL or line-oriented.
|
||||
- [ ] Use `with_response=True` only when needed.
|
||||
- [ ] Clean up pending request state on timeout.
|
||||
- [ ] Call `disconnect()` in `finally`.
|
||||
@@ -0,0 +1,86 @@
|
||||
<!-- SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD -->
|
||||
<!-- SPDX-License-Identifier: Apache-2.0 -->
|
||||
|
||||
# BLE UART Profile Compatibility
|
||||
|
||||
BLE UART Bridge works with BLE GATT profiles that provide a UART-like data path:
|
||||
|
||||
- one characteristic that the host writes to
|
||||
- one characteristic that the device uses to notify data back to the host
|
||||
|
||||
The default profile is compatible with the Nordic UART Service (NUS), but NUS is not the only possible BLE UART-style profile.
|
||||
|
||||
## Default NUS-compatible profile
|
||||
|
||||
The built-in default profile uses these UUIDs:
|
||||
|
||||
| Role | UUID |
|
||||
| --- | --- |
|
||||
| Service | `6E400001-B5A3-F393-E0A9-E50E24DCCA9E` |
|
||||
| RX, host to device | `6E400002-B5A3-F393-E0A9-E50E24DCCA9E` |
|
||||
| TX, device to host | `6E400003-B5A3-F393-E0A9-E50E24DCCA9E` |
|
||||
|
||||
Use the default profile when the device advertises a NUS-compatible service.
|
||||
|
||||
## ESP-IDF BLE SPP examples
|
||||
|
||||
ESP-IDF includes BLE SPP examples that implement Espressif BLE UART-like vendor-specific GATT profiles:
|
||||
|
||||
- `examples/bluetooth/nimble/ble_spp/spp_server`
|
||||
- `examples/bluetooth/nimble/ble_spp/spp_client`
|
||||
- `examples/bluetooth/bluedroid/ble/ble_spp_server`
|
||||
- `examples/bluetooth/bluedroid/ble/ble_spp_client`
|
||||
|
||||
BLE SPP over BLE is not a Bluetooth SIG standard profile. It is a vendor-specific GATT design that emulates a serial link, similar in purpose to NUS.
|
||||
|
||||
ESP-IDF BLE SPP examples may define more characteristics than BLE UART Bridge needs, such as data, command, and status characteristics. To use BLE UART Bridge with such a profile, map only the UART-like data path into `BLEUARTProfile`.
|
||||
|
||||
## Mapping an ESP-IDF BLE SPP profile
|
||||
|
||||
Map the profile fields as follows:
|
||||
|
||||
| `BLEUARTProfile` field | Map to |
|
||||
| --- | --- |
|
||||
| `service_uuid` | BLE SPP service UUID |
|
||||
| `rx_char_uuid` | Characteristic that the host writes to, such as the SPP data receive characteristic |
|
||||
| `tx_char_uuid` | Characteristic that the device notifies from, such as the SPP data notify characteristic |
|
||||
|
||||
Example:
|
||||
|
||||
```python
|
||||
from src.core import BLEUARTBridge
|
||||
from src.core import BLEUARTProfile
|
||||
|
||||
|
||||
profile = BLEUARTProfile(
|
||||
service_uuid="00000000-0000-0000-0000-00000000ABF0",
|
||||
rx_char_uuid="00000000-0000-0000-0000-00000000ABF1",
|
||||
tx_char_uuid="00000000-0000-0000-0000-00000000ABF2",
|
||||
)
|
||||
|
||||
bridge = BLEUARTBridge("AA:BB:CC:DD:EE:FF", profile=profile)
|
||||
```
|
||||
|
||||
Replace the UUIDs with the actual UUIDs used by the device firmware.
|
||||
|
||||
## What BLE UART Bridge does not map
|
||||
|
||||
BLE UART Bridge is intentionally focused on the data path. It does not automatically map extra control-plane characteristics that a profile may expose, such as:
|
||||
|
||||
- command characteristics
|
||||
- status characteristics
|
||||
- custom configuration characteristics
|
||||
- profile-specific flow-control semantics
|
||||
|
||||
If an application needs those characteristics, implement that logic in a custom script on top of `bleak`, or extend BLE UART Bridge for that specific profile.
|
||||
|
||||
## Classic Bluetooth SPP is different
|
||||
|
||||
Classic Bluetooth SPP examples, such as `examples/bluetooth/bluedroid/classic_bt/bt_spp_*`, are not BLE GATT profiles.
|
||||
|
||||
They use Classic Bluetooth SPP rather than BLE GATT characteristics, so they are not compatible with BLE UART Bridge.
|
||||
|
||||
## Related docs
|
||||
|
||||
- [README.md](../README.md)
|
||||
- [PORTING.md](PORTING.md)
|
||||
@@ -0,0 +1,202 @@
|
||||
<!-- SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD -->
|
||||
<!-- SPDX-License-Identifier: Apache-2.0 -->
|
||||
|
||||
# Quick Start: BLE UART Console
|
||||
|
||||
This guide shows how to use the BLE UART Console for quick manual testing.
|
||||
|
||||
The Console is useful when you want to type data into a BLE UART device and inspect the bytes or text sent back by the device.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. A host machine with Bluetooth access.
|
||||
2. Python environment prepared. You can reuse the ESP-IDF Python environment, or use your own Python virtual environment. If you reuse the ESP-IDF environment, export it first and then install the BLE UART Bridge dependencies:
|
||||
|
||||
```bash
|
||||
cd $IDF_PATH
|
||||
. ./export.sh
|
||||
cd tools/ble/ble_uart_bridge
|
||||
python -m pip install -r requirements.txt
|
||||
```
|
||||
|
||||
On Windows, run `export.bat` or `export.ps1` from the ESP-IDF root directory before installing `requirements.txt`. If you use your own Python virtual environment instead, activate it before installing `requirements.txt`.
|
||||
|
||||
3. A BLE device advertising the BLE UART service. By default the tool scans for Nordic UART Service UUIDs. For a known-compatible test target, build and flash the [BLE UART Service example](../../../../examples/bluetooth/ble_uart_service), which acts as an Echo Server by echoing RX writes back through TX notifications.
|
||||
|
||||
## Find a device
|
||||
|
||||
```bash
|
||||
cd tools/ble/ble_uart_bridge
|
||||
python main.py list-devices
|
||||
```
|
||||
|
||||
Example output may include a device address and name:
|
||||
|
||||
```text
|
||||
Found: AA:BB:CC:DD:EE:FF, with name esp-ble-uart, rssi=-42
|
||||
```
|
||||
|
||||
Use the printed device identifier as `DEVICE_ID`. On macOS, this identifier is a CoreBluetooth UUID and is different from the device MAC address.
|
||||
|
||||
## Check the connection
|
||||
|
||||
```bash
|
||||
python main.py connection-check AA:BB:CC:DD:EE:FF
|
||||
```
|
||||
|
||||
This command connects to the device, discovers the BLE UART service and characteristics, then disconnects.
|
||||
|
||||
## Start the Console
|
||||
|
||||
```bash
|
||||
python main.py console AA:BB:CC:DD:EE:FF
|
||||
```
|
||||
|
||||
The console connects before opening the UI. If connection fails, the UI is not started.
|
||||
|
||||
Inside the UI:
|
||||
|
||||
- Type a line and press Enter to send it.
|
||||
- Received data is shown with an `[RX]` prefix.
|
||||
- Transmitted data is shown with a `[TX]` prefix.
|
||||
- Connection information is shown with an `[INFO]` prefix.
|
||||
- Press `Ctrl+C` or `Ctrl+D` to quit.
|
||||
- Press `Ctrl+L` to clear the log.
|
||||
|
||||
## Text mode
|
||||
|
||||
Text mode is the default. It UTF-8 encodes input and appends a line terminator.
|
||||
|
||||
```bash
|
||||
python main.py console AA:BB:CC:DD:EE:FF
|
||||
```
|
||||
|
||||
By default, each submitted line is sent with `\n`.
|
||||
|
||||
### Choose a line terminator
|
||||
|
||||
Use `--terminator` for protocols that expect different line endings:
|
||||
|
||||
```bash
|
||||
python main.py console AA:BB:CC:DD:EE:FF --terminator lf
|
||||
python main.py console AA:BB:CC:DD:EE:FF --terminator crlf
|
||||
python main.py console AA:BB:CC:DD:EE:FF --terminator none
|
||||
```
|
||||
|
||||
Supported values:
|
||||
|
||||
| Value | Bytes appended |
|
||||
| --- | --- |
|
||||
| `lf` | `\n` |
|
||||
| `crlf` | `\r\n` |
|
||||
| `none` | nothing |
|
||||
|
||||
Use `crlf` for many AT-style command interpreters. Use `none` if the device expects the exact bytes you type.
|
||||
|
||||
## Hex mode
|
||||
|
||||
Hex mode sends raw bytes parsed from hexadecimal input and displays received bytes as hexadecimal.
|
||||
|
||||
```bash
|
||||
python main.py console AA:BB:CC:DD:EE:FF --encoding hex
|
||||
```
|
||||
|
||||
Inside the UI, enter bytes as hex:
|
||||
|
||||
```text
|
||||
01 02 03 0a
|
||||
```
|
||||
|
||||
The console sends:
|
||||
|
||||
```text
|
||||
0x01 0x02 0x03 0x0a
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- Hex input is parsed with Python `bytes.fromhex()`.
|
||||
- Spaces are allowed.
|
||||
- In hex mode, `--terminator` is ignored because the input already represents exact bytes.
|
||||
|
||||
## Write-with-response
|
||||
|
||||
By default the console writes without response. Use `--with-response` if the target characteristic or debugging workflow should use BLE write-with-response:
|
||||
|
||||
```bash
|
||||
python main.py console AA:BB:CC:DD:EE:FF --with-response
|
||||
```
|
||||
|
||||
This affects BLE GATT write behavior only. It does not create an application-level request/response protocol. For application-level request/response, use Daemon mode instead.
|
||||
|
||||
## Common examples
|
||||
|
||||
### ESP-IDF BLE UART Echo Server
|
||||
|
||||
Use the [BLE UART Service example](../../../../examples/bluetooth/ble_uart_service) when you want a ready-made ESP-IDF Echo Server for testing BLE UART Bridge Console. After building, flashing, and pairing with the example, open Console and type any text; the example should echo the same data back as `[RX]` output.
|
||||
|
||||
```bash
|
||||
# List nearby BLE UART devices and use the printed device ID as DEVICE_ID
|
||||
python main.py list-devices
|
||||
python main.py console AA:BB:CC:DD:EE:FF
|
||||
```
|
||||
|
||||
### ESP-IDF console-style command
|
||||
|
||||
```bash
|
||||
python main.py console AA:BB:CC:DD:EE:FF --terminator lf
|
||||
```
|
||||
|
||||
Then type:
|
||||
|
||||
```text
|
||||
help
|
||||
```
|
||||
|
||||
### AT-style command
|
||||
|
||||
```bash
|
||||
python main.py console AA:BB:CC:DD:EE:FF --terminator crlf
|
||||
```
|
||||
|
||||
Then type:
|
||||
|
||||
```text
|
||||
AT
|
||||
```
|
||||
|
||||
### Binary smoke test
|
||||
|
||||
```bash
|
||||
python main.py console AA:BB:CC:DD:EE:FF --encoding hex --with-response
|
||||
```
|
||||
|
||||
Then type:
|
||||
|
||||
```text
|
||||
aa 55 01 00
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### No devices found
|
||||
|
||||
- Confirm the host Bluetooth adapter is available.
|
||||
- Confirm the device is advertising the BLE UART service UUID.
|
||||
- Move the device closer to the host.
|
||||
|
||||
### Connection fails
|
||||
|
||||
- Make sure no other host is already connected to the BLE device.
|
||||
- Restart advertising on the device.
|
||||
- Run `connection-check` before opening the console.
|
||||
|
||||
### Text looks broken
|
||||
|
||||
- The console decodes RX bytes as UTF-8 in text mode.
|
||||
- Use `--encoding hex` if the device sends binary data.
|
||||
|
||||
### Device does not react to input
|
||||
|
||||
- Check the required line ending. Try `--terminator crlf` or `--terminator none`.
|
||||
- Check whether the device requires write-with-response. Try `--with-response`.
|
||||
@@ -0,0 +1,340 @@
|
||||
<!-- SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD -->
|
||||
<!-- SPDX-License-Identifier: Apache-2.0 -->
|
||||
|
||||
# Quick Start: BLE UART Daemon
|
||||
|
||||
This guide shows how to use BLE UART Daemon mode and the lightweight JSONL RPC protocol used between the host and the BLE device.
|
||||
|
||||
Daemon mode is useful when another local process needs to communicate with a BLE UART device without owning the BLE connection itself.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. A host machine with Bluetooth access.
|
||||
2. Python environment prepared. You can reuse the ESP-IDF Python environment, or use your own Python virtual environment. If you reuse the ESP-IDF environment, export it first and then install the BLE UART Bridge dependencies:
|
||||
|
||||
```bash
|
||||
cd $IDF_PATH
|
||||
. ./export.sh
|
||||
cd tools/ble/ble_uart_bridge
|
||||
python -m pip install -r requirements.txt
|
||||
```
|
||||
|
||||
On Windows, run `export.bat` or `export.ps1` from the ESP-IDF root directory before installing `requirements.txt`. If you use your own Python virtual environment instead, activate it before installing `requirements.txt`.
|
||||
|
||||
3. A BLE UART device that understands the daemon JSONL request/response protocol, or a device implementation you can adapt.
|
||||
|
||||
## Start the daemon
|
||||
|
||||
First, scan for a device:
|
||||
|
||||
```bash
|
||||
cd tools/ble/ble_uart_bridge
|
||||
python main.py list-devices
|
||||
```
|
||||
|
||||
Then start the daemon:
|
||||
|
||||
```bash
|
||||
python main.py daemon AA:BB:CC:DD:EE:FF
|
||||
```
|
||||
|
||||
By default, the daemon listens on `127.0.0.1:8888`.
|
||||
|
||||
To choose another host or port:
|
||||
|
||||
```bash
|
||||
python main.py daemon AA:BB:CC:DD:EE:FF --host 127.0.0.1 --port 8899
|
||||
```
|
||||
|
||||
The daemon keeps one BLE connection open until it is stopped.
|
||||
|
||||
Security note: the daemon HTTP API does not implement authentication or authorization. Keep `--host` on `127.0.0.1` for local-only access unless you place the daemon behind your own access control.
|
||||
|
||||
## Check daemon status
|
||||
|
||||
In another terminal:
|
||||
|
||||
```bash
|
||||
python main.py daemon-status
|
||||
```
|
||||
|
||||
Example response:
|
||||
|
||||
```json
|
||||
{
|
||||
"device_id": "AA:BB:CC:DD:EE:FF",
|
||||
"connection_state": "CONNECTED",
|
||||
"is_connected": true,
|
||||
"pending_requests": 0,
|
||||
"single_flight": true,
|
||||
"max_request_data_bytes": 4096,
|
||||
"protocol": "esp-jsonl-rpc-lite-v1"
|
||||
}
|
||||
```
|
||||
|
||||
If the daemon uses a non-default address:
|
||||
|
||||
```bash
|
||||
python main.py daemon-status --host 127.0.0.1 --port 8899
|
||||
```
|
||||
|
||||
## Send a request from the CLI
|
||||
|
||||
Send a raw string payload with the default operation name `raw`:
|
||||
|
||||
```bash
|
||||
python main.py daemon-send "hello"
|
||||
```
|
||||
|
||||
Send a request with an explicit operation name:
|
||||
|
||||
```bash
|
||||
python main.py daemon-send --op echo "hello"
|
||||
```
|
||||
|
||||
Send a JSON payload:
|
||||
|
||||
```bash
|
||||
python main.py daemon-send --op set_led --json '{"state": true}'
|
||||
```
|
||||
|
||||
Set the request timeout:
|
||||
|
||||
```bash
|
||||
python main.py daemon-send --op echo --timeout 5.0 "hello"
|
||||
```
|
||||
|
||||
Use a non-default daemon address:
|
||||
|
||||
```bash
|
||||
python main.py daemon-send --host 127.0.0.1 --port 8899 --op echo "hello"
|
||||
```
|
||||
|
||||
Do not send requests to a daemon bound to a shared network interface unless that network path is trusted or protected by your own access control.
|
||||
|
||||
The CLI prints only the response payload. If the device returns a JSON object, the CLI prints it as JSON.
|
||||
|
||||
## HTTP API
|
||||
|
||||
Daemon mode exposes a local HTTP API.
|
||||
|
||||
### `GET /status`
|
||||
|
||||
Returns daemon and BLE connection state:
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:8888/status
|
||||
```
|
||||
|
||||
Response fields:
|
||||
|
||||
| Field | Meaning |
|
||||
| --- | --- |
|
||||
| `device_id` | BLE device ID used by the daemon |
|
||||
| `connection_state` | Bridge connection state |
|
||||
| `is_connected` | Whether the BLE client is currently connected |
|
||||
| `pending_requests` | Number of pending request futures |
|
||||
| `single_flight` | Whether the daemon serializes requests |
|
||||
| `max_request_data_bytes` | Maximum JSON-encoded `data` size accepted by `/request` |
|
||||
| `protocol` | Wire protocol name and version |
|
||||
|
||||
### `POST /request`
|
||||
|
||||
Sends one request to the BLE device and waits for the response:
|
||||
|
||||
```bash
|
||||
curl -X POST http://127.0.0.1:8888/request \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{"op":"echo","data":"hello","timeout":10}'
|
||||
```
|
||||
|
||||
Request body:
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "echo",
|
||||
"data": "hello",
|
||||
"timeout": 10.0
|
||||
}
|
||||
```
|
||||
|
||||
Fields:
|
||||
|
||||
| Field | Required | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `op` | No | Operation name. Defaults to `raw`. |
|
||||
| `data` | Yes | Request payload. Can be a string, number, boolean, array, object, or null. |
|
||||
| `timeout` | No | Response timeout in seconds. Defaults to `10.0`. |
|
||||
|
||||
Limits:
|
||||
|
||||
- `op` must be 1 to 64 characters.
|
||||
- JSON-encoded `data` must not exceed 4096 bytes.
|
||||
|
||||
Successful response:
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": "hello"
|
||||
}
|
||||
```
|
||||
|
||||
HTTP error behavior:
|
||||
|
||||
| HTTP status | Meaning |
|
||||
| --- | --- |
|
||||
| `413` | Request data exceeds the daemon payload limit |
|
||||
| `500` | Failed to send data to the BLE device |
|
||||
| `502` | Device returned a protocol error or invalid response |
|
||||
| `504` | Timed out waiting for the device response |
|
||||
|
||||
## BLE JSONL RPC protocol
|
||||
|
||||
The daemon communicates with the BLE device using newline-delimited JSON. Every message is one JSON object followed by `\n`.
|
||||
|
||||
The protocol is named:
|
||||
|
||||
```text
|
||||
esp-jsonl-rpc-lite-v1
|
||||
```
|
||||
|
||||
It is intentionally small:
|
||||
|
||||
- Human-readable during debugging.
|
||||
- Easy to generate and parse on ESP-IDF firmware with `cJSON`.
|
||||
- No schema registry or capability negotiation.
|
||||
- No built-in routing framework.
|
||||
- One request at a time in the current daemon implementation.
|
||||
|
||||
### Host to device request
|
||||
|
||||
The daemon sends this JSONL message to the BLE device:
|
||||
|
||||
```json
|
||||
{"v":1,"id":"6f8f...","op":"echo","data":"hello"}
|
||||
```
|
||||
|
||||
Actual wire bytes include a final newline:
|
||||
|
||||
```text
|
||||
{"v":1,"id":"6f8f...","op":"echo","data":"hello"}\n
|
||||
```
|
||||
|
||||
Fields:
|
||||
|
||||
| Field | Meaning |
|
||||
| --- | --- |
|
||||
| `v` | Protocol version. Current value is `1`. |
|
||||
| `id` | Request ID generated by the daemon. The device must echo this in the response. |
|
||||
| `op` | Operation name selected by the client. |
|
||||
| `data` | Request payload. |
|
||||
|
||||
### Device to host success response
|
||||
|
||||
```json
|
||||
{"v":1,"id":"6f8f...","ok":true,"data":"hello"}
|
||||
```
|
||||
|
||||
Fields:
|
||||
|
||||
| Field | Meaning |
|
||||
| --- | --- |
|
||||
| `v` | Protocol version. Recommended value is `1`. |
|
||||
| `id` | The request ID from the host message. |
|
||||
| `ok` | `true` for success. |
|
||||
| `data` | Response payload. |
|
||||
|
||||
The daemon requires `data` to be present when `ok` is `true`.
|
||||
|
||||
### Device to host error response
|
||||
|
||||
```json
|
||||
{"v":1,"id":"6f8f...","ok":false,"error":"unsupported op"}
|
||||
```
|
||||
|
||||
Fields:
|
||||
|
||||
| Field | Meaning |
|
||||
| --- | --- |
|
||||
| `id` | The request ID from the host message. |
|
||||
| `ok` | `false` for error. |
|
||||
| `error` | Human-readable error message. |
|
||||
|
||||
The daemon requires `error` to be a non-empty string when `ok` is `false`.
|
||||
|
||||
### Response validation rules
|
||||
|
||||
For the preferred `ok/data/error` format, the daemon validates these rules:
|
||||
|
||||
- `id` must be a string and must match a pending request.
|
||||
- If present, `v` must be `1`.
|
||||
- `ok` must be a boolean.
|
||||
- `ok: true` requires a `data` field.
|
||||
- `ok: false` requires a non-empty string `error` field.
|
||||
|
||||
Messages without a matching pending `id` are treated as unsolicited messages and are logged only.
|
||||
|
||||
### Legacy response compatibility
|
||||
|
||||
The daemon also accepts older response shapes:
|
||||
|
||||
```json
|
||||
{"id":"6f8f...","response":"hello"}
|
||||
{"id":"6f8f...","error":"failed"}
|
||||
```
|
||||
|
||||
New device firmware should prefer the `ok/data/error` format.
|
||||
|
||||
## Minimal firmware-side behavior
|
||||
|
||||
On the BLE device, implement this loop conceptually:
|
||||
|
||||
1. Accumulate bytes received on the BLE UART RX characteristic.
|
||||
2. Split input on `\n`.
|
||||
3. Parse each line as JSON.
|
||||
4. Read `id`, `op`, and `data`.
|
||||
5. Execute the requested operation.
|
||||
6. Send a JSON response with the same `id` and a final `\n`.
|
||||
|
||||
For example, an `echo` operation can return the same data:
|
||||
|
||||
```json
|
||||
{"v":1,"id":"6f8f...","ok":true,"data":"hello"}
|
||||
```
|
||||
|
||||
## Single-flight behavior
|
||||
|
||||
The daemon currently processes one `/request` at a time. This is exposed as:
|
||||
|
||||
```json
|
||||
"single_flight": true
|
||||
```
|
||||
|
||||
This keeps the firmware-side example simple because the device only needs to handle one active request at a time. The request `id` is still included so the protocol can be extended later if concurrent requests are needed.
|
||||
|
||||
## Disconnect behavior
|
||||
|
||||
The daemon does not automatically reconnect after the BLE link is disconnected. If the device disconnects, stop and restart the daemon after the device starts advertising again.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### `daemon-send` times out
|
||||
|
||||
- Confirm the device sends a newline after the JSON response.
|
||||
- Confirm the device response contains the same `id` as the request.
|
||||
- Confirm the firmware handles the requested `op`.
|
||||
- Increase `--timeout` if the operation is slow.
|
||||
- Restart the daemon if the BLE link was disconnected.
|
||||
|
||||
### Daemon returns HTTP 502
|
||||
|
||||
- The device returned an error response, or the response was missing required fields.
|
||||
- Check daemon logs for the exact error.
|
||||
|
||||
### Device receives data but daemon never resolves the request
|
||||
|
||||
- Check that the response is valid JSON.
|
||||
- Check that the response is an object, not a JSON array or string.
|
||||
- Check that the response is newline terminated.
|
||||
- Check that the response `id` matches the request `id` exactly.
|
||||
Reference in New Issue
Block a user