flowchart TB APP["Application<br/>(the code you write in this hands-on)"] ARD["Arduino API / Bluefruit library<br/>(digitalWrite, attachInterrupt, Bluefruit.begin ...)"] RTOS["FreeRTOS<br/>(tasks, queues, software timers)"] SD["SoftDevice S140<br/>(Nordic's BLE protocol stack)"] HW["nRF52840 hardware"] APP --> ARD --> RTOS --> HW ARD --> SD --> HW
1 Development environment and the nRF52840
1.1 The nRF52840 and the XIAO nRF52840
The nRF52840 is a BLE (Bluetooth Low Energy)-capable microcontroller from Nordic Semiconductor.
| Item | Details |
|---|---|
| CPU | Arm Cortex-M4F (with floating-point unit) 64 MHz |
| Memory | Flash 1 MB, RAM 256 KB |
| Radio | Bluetooth 5 (BLE), IEEE 802.15.4 (Thread / Zigbee) |
| Other | USB 2.0, QSPI, I²C / SPI / UART, 12-bit ADC |
The Seeed Studio XIAO nRF52840 is a board that puts this chip on a thumb-sized PCB. The Sense version carries a 6-axis IMU (accelerometer + gyroscope, LSM6DS3TR-C) and a PDM microphone. The board also has an RGB LED and 2 MB of QSPI flash, plus a charging circuit for a LiPo battery.
1.2 Software layers
In this hands-on we use the Arduino-compatible Adafruit nRF52 core (the XIAO-enabled version by Seeed). While keeping Arduino’s ease of writing, the following software runs underneath it.
- FreeRTOS: a real-time OS.
setup()/loop()actually run inside a FreeRTOS task (the loop task) too. BLE and timers also run in separate tasks - SoftDevice: a binary of the BLE stack provided by Nordic. It has the highest interrupt priority and interrupts application processing in order to keep radio timing
loop() is not “the only flow of processing”. BLE callbacks and timer callbacks are called in other tasks, and the button interrupt is called inside an interrupt handler. If you touch shared data directly from these, conflicts occur. That is why we use an event queue (Chapter 3).
1.3 Setting up PlatformIO
- Install VS Code
- Install the PlatformIO IDE extension
- Extract the sample firmware firmware.zip and open the
firmwarefolder in VS Code - The first time, PlatformIO automatically downloads the platform, toolchain and libraries (this takes a few minutes)
1.3.1 platformio.ini
; nRF52840 event-driven hands-on sample firmware
; Board: Seeed Studio XIAO nRF52840 Sense (Adafruit nRF52 core + FreeRTOS + SoftDevice S140)
[env]
; The Seeed platform's default GCC 7.2 exists only as an x86_64 build and does not run on
; Apple Silicon Macs without Rosetta. Specify a newer GCC that has an ARM-native build
platform_packages =
platformio/toolchain-gccarmnoneeabi@~1.120301.0
[env:xiao_sense]
platform = https://github.com/Seeed-Studio/platform-seeedboards.git
board = seeed-xiao-afruitnrf52-nrf52840-sense
framework = arduino
monitor_speed = 115200
lib_deps =
seeed-studio/Seeed Arduino LSM6DS3@^2.0.4
build_flags =
-Isrc/app
-Isrc/drivers
-D USE_IMU=1
; For the XIAO nRF52840 without an IMU (non-Sense). Acceleration becomes dummy data
[env:xiao]
platform = https://github.com/Seeed-Studio/platform-seeedboards.git
board = seeed-xiao-afruitnrf52-nrf52840
framework = arduino
monitor_speed = 115200
build_flags =
-Isrc/app
-Isrc/drivers
-D USE_IMU=0platform: the PlatformIO platform published by Seeed (fetched from GitHub)board:seeed-xiao-afruitnrf52-nrf52840-sensefor the Sense version,seeed-xiao-afruitnrf52-nrf52840for the one without Sense-Iinbuild_flagsaddssrc/appandsrc/driversto the header search path-D USE_IMU=1switches whether to use the IMU (#if USE_IMU)
The default compiler of Seeed’s platform (GCC 7.2) exists only as an x86_64 build, so on an Apple Silicon Mac without Rosetta 2 you get the error Bad CPU type in executable. The sample works around this by specifying, via platform_packages, a newer GCC (12.3) that has an ARM-native build.
1.4 Building and flashing
| Operation | VS Code (PlatformIO toolbar) | Command |
|---|---|---|
| Build | ✓ (Build) | pio run -e xiao_sense |
| Upload | → (Upload) | pio run -e xiao_sense -t upload |
| Serial monitor | 🔌 (Serial Monitor) | pio device monitor |
If uploading fails, press the reset button twice quickly to enter bootloader mode (the LED slowly pulses and the board appears on the PC as a USB drive). Then upload again.
When the upload is done, if the serial monitor shows
boot: state=WAIT
and the green LED flashes briefly once every 2 seconds, you have succeeded.
1.5 Wiring
For the button, just connect a tactile switch between D8 and GND. D8 is set to internal pull-up (INPUT_PULLUP), so it reads
- when not pressed: HIGH
- when pressed: LOW
1.6 File layout
firmware/
├── platformio.ini
└── src/
├── main.cpp setup() and loop() (the event loop)
├── app/ application (hardware-independent part)
│ ├── app_event.h/.cpp events and the event queue
│ ├── app_state.h states
│ ├── app_handler.h/.cpp state transition table and dispatch()
│ ├── app_handler_wait.cpp handlers for the idle state
│ ├── app_handler_meas.cpp handlers for the measuring state
│ └── app_meas.h/.cpp aggregation of measurement data and BLE responses
└── drivers/ parts that touch hardware (event sources)
├── drv_button.h/.cpp button interrupt
├── drv_timer.h/.cpp software timers
├── drv_ble.h/.cpp BLE
├── drv_imu.h/.cpp accelerometer
└── drv_led.h/.cpp LED
The split is: app/ holds the logic of events and states, drivers/ is the boundary with the hardware.
At first the file was named ble.h, but building it produced a flood of errors inside the Bluefruit library. Nordic’s SoftDevice also has a header with the same name, ble.h, and the -Isrc/drivers setting also applied to the library’s #include "ble.h", so our own header got included instead. event.h, timer.h and the like are also names that easily collide with other libraries. Adding a prefix such as app_ / drv_ (or My) is the safe choice.