espressif--esp-idf/tools/ble/ble_uart_bridge/docs/Quick-Start-BLE-UART-Console.md

Quick Start: ESP-BLE-UART Console

This guide shows how to use the ESP-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 ESP-BLE-UART Bridge dependencies:

   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 the de-facto BLE UART-over-GATT UUIDs (6E400001-… / …02 / …03). For a known-compatible test target, build and flash the ESP-BLE-UART example, which acts as an Echo Server by echoing RX writes back through TX notifications.

Find a device

cd tools/ble/ble_uart_bridge
python main.py list-devices

Example output may include a device address and name:

Found: AA:BB:CC:DD:EE:FF, with name BleUart-XXXX, 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

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

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.

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:

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.

python main.py console AA:BB:CC:DD:EE:FF --encoding hex

Inside the UI, enter bytes as hex:

01 02 03 0a

The console sends:

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:

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-BLE-UART Echo Server

Use the ESP-BLE-UART example when you want a ready-made ESP-IDF Echo Server for testing ESP-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.

# List nearby BLE 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

python main.py console AA:BB:CC:DD:EE:FF --terminator lf

Then type:

help

AT-style command

python main.py console AA:BB:CC:DD:EE:FF --terminator crlf

Then type:

AT

Binary smoke test

python main.py console AA:BB:CC:DD:EE:FF --encoding hex --with-response

Then type:

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.

• On Linux, reset the system Bluetooth service if connections keep failing, pairing gets stuck, or service discovery cannot find the BLE UART service or characteristics:

  sudo systemctl stop bluetooth
  sudo systemctl start bluetooth
  

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.