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.

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

  • 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
ImportantKey point

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

  1. Install VS Code
  2. Install the PlatformIO IDE extension
  3. Extract the sample firmware firmware.zip and open the firmware folder in VS Code
  4. 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=0
  • platform: the PlatformIO platform published by Seeed (fetched from GitHub)
  • board: seeed-xiao-afruitnrf52-nrf52840-sense for the Sense version, seeed-xiao-afruitnrf52-nrf52840 for the one without Sense
  • -I in build_flags adds src/app and src/drivers to the header search path
  • -D USE_IMU=1 switches whether to use the IMU (#if USE_IMU)
WarningIf you cannot build on an Apple Silicon Mac

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.

TipWhy the file names have prefixes

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.