ESP32 Bluetooth LE Proxy

Base URL: $TESTBENCH_URL — see Step 0

Step 0: Point at a bench

There are several benches and their addresses move, so nothing here writes one down. $BENCH is not usable either — a container cannot resolve mDNS. Discover the bench and export its URL:

export TESTBENCH_URL=$(sudo python3 .claude/skills/esp-idf-handling/discover-testbench.py \
                         --url --name <bench-hostname>)
curl -s "$TESTBENCH_URL/api/info"        # confirm before anything else

--url refuses to guess when more than one bench answers, so --name is required whenever a second bench is powered on. TESTBENCH_URL is the same variable pytest --wt-url falls back to.

Endpoints

Request and response shapes: FSD Appendix D.5.

One BLE connection at a time — connect to a second peripheral without disconnecting the first and the call fails rather than switching.

Examples

# Scan for BLE devices (5s timeout)
curl -X POST $TESTBENCH_URL/api/ble/scan \
  -H 'Content-Type: application/json' \
  -d '{"timeout": 5}'

# Scan with name filter
curl -X POST $TESTBENCH_URL/api/ble/scan \
  -H 'Content-Type: application/json' \
  -d '{"timeout": 5, "name_filter": "<device-name>"}'

# Connect by MAC address
curl -X POST $TESTBENCH_URL/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 $TESTBENCH_URL/api/ble/write \
  -H 'Content-Type: application/json' \
  -d '{"characteristic": "6e400002-b5a3-f393-e0a9-e50e24dcca9e", "data": "48656c6c6f", "response": true}'

# Check connection status
curl $TESTBENCH_URL/api/ble/status

# Disconnect
curl -X POST $TESTBENCH_URL/api/ble/disconnect

Nordic UART Service (NUS) UUIDs

Common Workflows

1. Send a command via NUS:
   • POST /api/ble/scan with name_filter to find device
   • POST /api/ble/connect with the MAC address from scan results
   • POST /api/ble/write with NUS RX UUID and hex-encoded command
   • POST /api/ble/disconnect when done
2. Check if device is advertising:
   • POST /api/ble/scan with short timeout and name filter
   • Check devices array in response
3. Send binary command protocol:
   • Connect to device
   • Encode command bytes as hex (e.g., 0x02 + "Hello" = 0248656c6c6f)
   • Write to NUS RX characteristic
   • Monitor device response via serial or UDP logs (see testbench-logging)

Troubleshooting