ESP32-C3 × ESP-IDF BLE Hands-on

Building Notify, commands and pairing with NimBLE, then restructuring as event-driven

Today’s goals

  1. Explain the roles of BLE’s GAP / GATT / ATT / SM
  2. Implement advertising, a GATT service and Notify with NimBLE
  3. Receive commands via Write and return responses
  4. Implement passkey pairing and bonding, and protect access
  5. Organize the structure with an event queue + state transition table

Steps

flowchart LR
  S1["1 Hello"] --> S2["2 Advertising"] --> S3["3 Notify"] --> S4["4 Commands"] --> S5["5 Pairing"] --> S6["6 Event-driven"]

  • Each step is an independent ESP-IDF project (ESP-IDF v6.0.1)
  • Check with nRF Connect and the Web Bluetooth console

1. How BLE works

The stack

Layer Role NimBLE
GAP Discover, connect ble_gap_*, BLE_GAP_EVENT_*
GATT Services, characteristics ble_gatt_svc_def
ATT Read/write attributes (handles) BLE_ATT_ERR_*
SM Pairing, keys ble_hs_cfg.sm_*
LL / PHY Advertising, connections, encryption Controller (binary)

Advertising and connections

  • Broadcast on ch 37 / 38 / 39. Data up to 31 bytes
    • A name that doesn’t fit goes into the scan response
  • After connecting, communicate every connection interval, decided by the Central
  • When disconnected, restart advertising yourself

GATT

flowchart TB
  S["Service c0a60001-…"] --> C1["Counter<br/>Read / Notify"]
  S --> C2["Command<br/>Write / Notify"]
  C1 --> D1["CCCD 0x2902"]
  C2 --> D2["CCCD 0x2902"]

  • The server can only send Notify / Indicate
  • Only when 01 00 has been written to the CCCD
  • Generate custom UUIDs yourself. As bytes they are reversed
  • One Notify carries 20 bytes by default (MTU 23)

2. NimBLE

How it runs

  • The host is a dedicated task; callbacks run inside it
    • Don’t wait, don’t do heavy work
  • BLE APIs can be used after sync_cb
  • Define services as a static table and register before starting the host
  • mbufs passed to ble_gatts_notify_custom() are freed by NimBLE

The sdkconfig trap

  • BLE is disabled by default. Put CONFIG_BT_ENABLED=y etc. in sdkconfig.defaults
  • If sdkconfig already exists, defaults have no effect
    • → delete sdkconfig and regenerate it

3. Security

Pairing and bonding

  • Pairing = create keys, bonding = store keys
  • DisplayOnly (ESP32-C3) × KeyboardDisplay (phone) → Passkey Entry
  • With LE Secure Connections (ECDH), eavesdropping doesn’t leak keys
  • A fixed passkey is for learning. Products: random every time

Access control

#define SECURE_READ   (READ | READ_ENC | READ_AUTHEN)
#define SECURE_WRITE  (WRITE | WRITE_ENC | WRITE_AUTHEN)
#define SECURE_NOTIFY (NOTIFY | NOTIFY_INDICATE_ENC | NOTIFY_INDICATE_AUTHEN)
  • *_ENC = encryption required, *_AUTHEN = key with MITM protection required
  • The CCCD is a separate attribute → without NOTIFY_INDICATE_*, unpaired peers can subscribe
  • Deleting the bond on only one side causes failures → delete on both sides

4. Event-driven

Structure

flowchart LR
  GAP["GAP"] -->|enqueue| Q[("Queue")]
  GATT["GATT Write"] -->|enqueue| Q
  TMR["esp_timer 1s"] -->|enqueue| Q
  Q -->|dequeue| L["main loop"]
  L --> T["table[state][event]"]
  T --> H["Handler → next state"]

  • Drivers (host task) only post and return immediately
  • The state changes in one place in the loop

State transition table

State CONNECTED DISCONNECTED CMD_PING CMD_STATUS TIMER_1S
IDLE → CONNECTED — — — +1
CONNECTED — → IDLE PONG status +1, Notify
  • “—” = NULL = ignore
  • Adding a feature = add an event and decide the cell in every row

Summary

  • Understanding BLE in the specification’s terms lets you read NimBLE’s API directly
  • Notify presupposes a CCCD subscription
  • Protect with permission flags — don’t forget the CCCD
  • Callbacks only post; processing goes through the state transition table