flowchart LR S1["Step 1<br/>Hello ESP-IDF"] --> S2["Step 2<br/>Advertising"] S2 --> S3["Step 3<br/>GATT and Notify"] S3 --> S4["Step 4<br/>Commands and responses"] S4 --> S5["Step 5<br/>Passkey pairing"] S5 --> S6["Step 6<br/>Restructure as<br/>event-driven"]
ESP32-C3 × ESP-IDF BLE Hands-on
Building Notify, commands and pairing with NimBLE, then restructuring as event-driven
Introduction
English version — machine-assisted translation (by generative AI, Anthropic Claude) of the original Japanese hands-on. 日本語版はこちら.
In this hands-on we use Espressif’s ESP32-C3 and the official development framework ESP-IDF to build a BLE (Bluetooth Low Energy) peripheral (the device that smartphones and PCs connect to) from scratch.
BLE also works with Arduino, but because the library hides a lot, when you run into questions such as
- why the name doesn’t fit into the advertisement
- what is missing when Notify doesn’t arrive
- why the pairing dialog sometimes appears and sometimes doesn’t
you tend to have no idea where to look. ESP-IDF’s BLE stack NimBLE turns the vocabulary of the BLE specification (GAP, GATT, ATT, Security Manager) into its API almost directly. The aim of this hands-on is to proceed while mapping the words of the specification one-to-one onto code.
What you will build
| Feature | Details |
|---|---|
| Advertising | Broadcasts under the name HANDSON-C3-XXXX (XXXX differs per device) and waits for a connection |
| Notify | While connected, sends a counter value to the phone/PC every second |
| Commands | Writing 0x00 returns PONG; writing 0x01 returns the counter and the seconds since boot |
| Pairing | Without entering the 6-digit passkey (123456), data can be neither read/written nor subscribed to. Once paired, it is not needed next time (bonding) |
| Structure | Finally restructured into an event-driven design with an event queue + state transition table |
| Browser | You can operate the device from this page via the BLE console in Chapter 11 (Chrome / Edge) |
Sample firmware
firmware.zip — six ESP-IDF projects (step1_hello to step6_event_driven). Each step can be built and flashed on its own.
The code in each chapter displays the source files of this sample firmware as they are. Builds have been confirmed with ESP-IDF v6.0.1.
Who this is for
- Those who know the basics of C (functions, structs, pointers,
switch) - Those who have played with microcontrollers via Arduino or similar
- Those who have used BLE “somehow” but want to properly understand how it works
What you need
| Item | Notes |
|---|---|
| ESP32-C3 board | Seeed Studio XIAO ESP32C3, ESP32-C3-DevKitM-1, etc. Always attach the antenna to the XIAO |
| USB cable | One that supports data transfer |
| PC | macOS / Windows / Linux. Install ESP-IDF v6 (Chapter 1) |
| Smartphone | Install nRF Connect for Mobile (by Nordic Semiconductor, iOS / Android, free) |
| Chrome or Edge (PC / Android) | For the BLE console in Chapter 11 (Safari on iPhone / iPad does not support Web Bluetooth) |
Chapters
| Chapter | Content | Step | Approx. time |
|---|---|---|---|
| 1 | Development environment and ESP-IDF basics | Step 1 | 40 min |
| 2 | The big picture of BLE: roles, advertising, connections | — | 30 min |
| 3 | ATT and GATT: the framework for exchanging data | — | 30 min |
| 4 | NimBLE, ESP-IDF’s BLE stack | — | 20 min |
| 5 | Advertising and waiting for a connection | Step 2 | 30 min |
| 6 | Creating a GATT service and notifying | Step 3 | 40 min |
| 7 | Receiving commands and responding | Step 4 | 30 min |
| 8 | BLE security: pairing and bonding | — | 30 min |
| 9 | Implementing passkey pairing | Step 5 | 40 min |
| 10 | Restructuring as event-driven | Step 6 | 40 min |
| 11 | Operating from the browser: Web Bluetooth console | Step 6 | 20 min |
| 12 | Troubleshooting | — | as needed |
| 13 | Review questions and further exercises | — | 30 min |
Chapters 2–4 and Chapter 8 explain how things work. If you’d rather get hands-on first, start from Chapter 5 and come back when you meet a term you don’t know.
Key-point slides for lectures are here.
There is also the nRF52840 Event-Driven Firmware Hands-on, which covers the same event-driven design with Arduino (Adafruit nRF52 core) + XIAO nRF52840. The design in Chapter 10 is aligned to almost the same shape as that one.