wehub-resource-sync
87 lines
3.3 KiB
Markdown
87 lines
3.3 KiB
Markdown
<!-- SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD -->
|
|
<!-- SPDX-License-Identifier: Apache-2.0 -->
|
|
|
|
# ESP-BLE-UART Profile Compatibility
|
|
|
|
ESP-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 matches the widely used BLE UART-over-GATT UUID set (service `6E400001-…`, RX/TX characteristics), but that layout is not the only possible BLE UART-style profile.
|
|
|
|
## Default BLE UART-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 service using those UUIDs.
|
|
|
|
## 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 the default BLE UART layout above.
|
|
|
|
ESP-IDF BLE SPP examples may define more characteristics than ESP-BLE-UART Bridge needs, such as data, command, and status characteristics. To use ESP-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 ESP-BLE-UART Bridge does not map
|
|
|
|
ESP-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 ESP-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 ESP-BLE-UART Bridge.
|
|
|
|
## Related docs
|
|
|
|
- [README.md](../README.md)
|
|
- [PORTING.md](PORTING.md)
|