ESP32-C3 × ESP-IDF BLE Hands-on

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

Published

October 17, 2026

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.

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"]

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

NoteDownload

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.

NoteSlide version

Key-point slides for lectures are here.

TipCompanion course

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.