[AdelinoGP]

Summary

Adds BLE advertising capture for reverse-engineering broadcast formats, exposed over the MCP interface, plus the WebSocket transport that makes the MCP server reachable on the port it advertises.

The GATT client is a hardware-verified state machine built directly on the raw esp_gattc API, replacing the Arduino BLE library's untimeoutable blocking calls.

Highlights

• BLE advertising scanner — Captures raw payloads from nearby devices, with per-device payload history limited to 32 devices and 8 distinct payloads per device. This makes broadcaster state changes, such as button presses or level changes, visible as payload deltas. Active scans request scan responses to capture advertised names and service data.

• GATT client — Implements ble/connect, ble/disconnect, and two-phase ble/services/start, ble/services/results, and ble/services/stop enumeration using a raw esp_gattc state machine. Per-operation deadlines are enforced:

  • Open: timeoutMs
  • Discovery: 10 seconds
  • Reads: 5 seconds
  • Notification capture: 3 seconds
  • Close: 2 seconds

• Async connect — ble/connect returns immediately, while ble/connect/results polls the outcome. The requested timeoutMs is genuinely enforced.

• MCP WebSocket transport — MCPServer::begin() now starts a WebSocket server on port 9000, which mDNS was already advertising. JSON-RPC frames are routed through processMessage(), and notifications are pushed to subscribed clients.

Note: BLE is compiled for the ESP32-S3 target only. On 4 MB-flash boards, the BLE stack cannot fit alongside the WebSocket transport and OTA. Therefore, the ble/* methods are not built for those boards.

New MCP methods

Method	Description
ble/scan	Start a non-blocking scan using durationMs.
ble/scan/results	Stop the scan and return captured devices and payload history.
ble/scan/stop	Stop a continuous scan early.
ble/connect	Begin an asynchronous GATT connection using mac and timeoutMs.
ble/connect/results	Poll the asynchronous connection outcome.
ble/disconnect	Drop the GATT link.
ble/services/start	Start two-phase GATT enumeration with notification capture.
ble/services/results	Retrieve GATT enumeration results.
ble/services/stop	Stop GATT enumeration.

Fixes included

• lwIP initialization crash — The board previously crashed in a reboot loop before joining Wi-Fi because AsyncServer::begin() called tcpip_api_call() before the TCP/IP stack was initialized. WiFi.mode() now runs first.

• WDT starvation under BLE load — CORE_DEBUG_LEVEL=5 flooded the UART at 115200 baud. Under heavy radio activity, verbose per-advertisement logging stalled BTC_TASK on core 0, starving async_tcp and triggering a watchdog abort. The default log level is now INFO, and AsyncTCP runs on core 1.

• Heap budget for BLE — BusHistory previously reserved freeHeap - 64 KB, leaving insufficient space for BLE controller and scan allocations and causing bad_alloc in the scan callback. The heap cap is now configurable through BOARD_BUS_HISTORY_HEAP_CAP:

  • ESP32-S3: 160 KB
  • Other boards: 128 KB
  • 0: Uncapped

• Payload history never populated — wantDuplicates=false caused the library to discard repeated advertisements before invoking the callback, limiting each device's history to one entry. Scans now request duplicates, while the library still frees each device after the callback. History logic was moved into natively tested core code with eviction and reappearance handling.

• GATT client defects found on hardware — The raw state machine now:

  • Uses the library's setCustomGattcHandler extension point because esp_ble_gattc_register_callback is one-shot.
  • Registers the GATT application once and verifies REG_EVT status.
  • Treats connection ID 0 as valid by gating on state instead of connection ID.
  • Transitions out of Discovering on SEARCH_CMPL_EVT, allowing the cache walk to run.

• 4 MB-flash boards — The original BLE commit did not compile on DevKitC, C3, HUZZAH32, or M5Stack because of a FreeRTOS.h include-path issue. BLE, transport, and OTA also exceeded the 1.25 MB OTA application slot. The include path is fixed, BLE is disabled on those boards, and the three classic ESP32 boards now use larger OTA slots through partitions_4mb_ota.csv:

  • 1.86 MB application slots
  • 128 KB SPIFFS
  • Coredump retained

• JSON-RPC error shape — ble/connect now returns a proper -32602 error envelope when mac is missing.

• Pre-existing CI blocker — test_mcp_server failed to build because std::find was used without including <algorithm> in the shared mock header. The firmware matrix is gated behind this test.

Testing

• pio test -e native — 173/173 passing

  • Includes 19 new BLE/GATT core tests covering hex encoding/decoding, connectable-flag heuristics, payload-history deduplication, bounds and eviction, and GATT state, deadline, UUID, and property logic.

• Full ESP32 matrix passes:

  • ESP32-S3
  • DevKitC V4
  • ESP32-C3
  • HUZZAH32
  • M5Stack

• nRF52 builds are unaffected.

• Verified live on hardware over the MCP WebSocket using an ESP32-S3-WROOM:

  • Six-device scan with payload history
  • Asynchronous connection to a Galaxy Watch Ultra in under 2 seconds
  • Five-service GATT enumeration with readable device name, model, and firmware values
  • Clean disconnect
  • Successful reconnect

Documentation

The README now includes a Bluetooth (BLE) section under the MCP API Reference, covering:

• Request and response examples
• Asynchronous connection and ble/connect/results
• Enforced per-operation timeouts
• Payload-history semantics, including the bounded eight-entry history and retained-entry count
• The ESP32-S3-only BLE limitation

Checklist

• Native tests pass: 173/173
• All ESP32 board builds pass
• Verified live on hardware: scan, connect, enumerate, disconnect, and reconnect
• nRF52 builds unaffected

Attribution

This implementation was developed using Agentic AI with human decision-making, OpenCode, and DeepSeek V4 Flash 0731 with Max reasoning.