Skip to content

mirkosertic/Megahub / .claude/skills/ble

Bluetooth context for the Megahub project. Use when working on BLE GATT server, Classic Bluetooth HID host, Web Bluetooth API integration, btremote library, connection handling, or any Bluetooth-related firmware code.

Bluetooth Architecture — Megahub ESP32

The project uses both BLE and Classic Bluetooth simultaneously (BTDM dual-mode).

TypePurposeLibrary
BLE (GATT server)Web Bluetooth API ↔ firmwarelib/btremote/
Classic BT (HID host)Gamepad/keyboard/mouse inputlib/btremote/

BLE GATT Server

Service UUID: 4fafc201-1fb5-459e-8fcc-c5c9c331914b

CharacteristicUUIDDirectionType
REQUESTbeb5483e-36e1-4688-b7f5-ea07361b26a8Browser → FirmwareWrite
RESPONSE1c95d5e3-d8f7-413a-bf3d-7a2e5d7be87eFirmware → BrowserNotify
EVENTd8de624e-140f-4a22-8594-e2216b84a5f2Firmware → BrowserNotify
CONTROLf78ebbff-c8b7-4107-93de-889a6a06d408Firmware → BrowserIndicate
  • Indications vs Notifications: CONTROL uses indications (require client ACK). RESPONSE/EVENT use notifications.
  • MTU: Default 23 bytes on connect. Firmware sends MTU_INFO notification immediately after connect, then again after negotiation (up to 517 bytes).
  • From real device logs: MTU negotiates to 514/517 bytes reliably.

BLE Rules (never violate)

  • Never block in BLE callbacks — they run in the BLE stack task context
  • Always check isConnected() before sending notifications/indications
  • Reconnection: Browser handles reconnect via device.gatt.connect() — firmware must keep advertising
  • Multiple connections: Each consumes ~30KB heap — the BT stack alone drops free heap from ~140KB to ~75KB
  • BLE callbacks → post work to a queue, handle in BTMsgProcessor task
  • Indication failures (status=132) during startup are normal — the client ACK pipeline needs time to stabilize after connect

Classic Bluetooth (HID Host)

  • Only for HID devices: gamepads, keyboards, mice
  • Auto-pairing enabled (IO capability: NONE, PIN: "0000")
  • HID events processed in HIDEventTask (priority 5, separate from BLE stack)
  • Never block in HID callback — post to queue
  • Pairing state is persisted in NVS; handle removal gracefully

Startup Sequence

From real device logs, BT init order:

  1. BT controller starts in BTDM dual-mode (esp_bt_controller_enable)
  2. Classic GAP callback registered
  3. Classic scan mode: connectable + discoverable
  4. HID Host initialized → waits for ESP_HIDH_INIT_EVT
  5. Bluedroid BLE init → waits for GATTS registration
  6. GATT service + characteristics created (handles 40–51)
  7. Advertising started
  8. Total heap consumed by BT stack: ~65KB

Message Protocol (BLE)

  • 5-byte fragment header: [type, messageId, fragmentNum(2), flags]
  • Fragmentation: automatic for all requests/responses
  • Streaming file upload: sliding window of 8 chunks, waits for ACK before advancing
  • App request types: from logs — type 10=ready-for-events, type 7=get-projects, type 8=get-autostart, type 9=set-autostart, type 2=get-file, type 6=execute-lua

Debugging BLE

# Enable HCI logs in ESP-IDF menuconfig for raw BLE packet capture
# Watch for these in serial log:
# [INFO] handleGattsConnect()   — client connected
# [INFO] handleGattsMTU()       — MTU negotiated
# [WARN] handleGattsConfirm()   — indication failed (status=132 at startup is normal)
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 321kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 321kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 321kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 321kUpdated Claude CodeCodexVerifiedInstall