RuuviTag nRF52 Bootloader & Example firmware projects
. ,-- bootloader | +-- ruuvitag_<HW_version>_debug | | +-- armgcc | | | +-- Makefile | | | `-- <Linkerscript> | | +-- config | | `-- sdk_configuration | `-- ruuvitag_<HW_version>_production | +-- armgcc... | `-- config ... |-- bsp | `-- <BSP files> |-- drivers | +-- battery | |-- bluetooth | |-- bme280 | |-- init | |-- lis2dh12 | |-- nrf_nordic_... | |-- pwm | |-- rng | |-- rtc | `-- spi | |-- libraries | +-- base64 | |-- base91 | |-- data_structures | |-- dsp | `-- rust_allocator | +-- keys | `-- ruuvi_open_private.pem | +-- ruuvi_examples | +-- APPLICATION | | +-- application_sdk_configuration | | +-- application_bsp_configuration | | +-- application_bluetooth_configuration | | +-- ble_services | | +-- ruuvitag_HW | | | +-- s132 | | | | +-- armgcc | | | | | +-- Makefile | | | | | +-- Linkerscript | | | | +-- config | | | | | +-- board_sdk_configuration | | | | | +-- board_bsp_configuration | | | | | +-- board_bluetooth_configuration | | +-- application files | sdk_overrides | +-- override_1.c | +-- etc +-- Makefile | +-- ble_app_beacon | | `-- ruuvitag_<HW_version> | | | +-- eddystone | | +-- ble_services | | |-- occ ... | | `-- ruuvitag_<HW_version> | | | `-- ruuvi_firmware | +-- ble_services | `-- ruuvitag_<HW_version> | `-- s132 | +-- armgcc | | +-- Makefile | | |-- _build | | `-- <Linkerscript> | `-- config | +-- bluetooth_board_configuration | +-- bsp_board_configuration | `-- sdk_board_configuration |-- sdk_overrides +-- nRF5_SDK_<vesion> +-- README.md
The Bootloader folder contains DFU bootloader which is used to upload new software to your RuuviTag without J-Link programmer, you can even use your smartphone and upload software over bluetooth. Starting from SDK12 the bootloader uses secure, signed packages. The encryption keys used to validate these software packages is split in two parts: dfu_public_key.c and your private key in "keys" folder. More details on signing and keys are explained on DFU package creation section.
BSP folder contains "Board Support Packages" which provide abstraction and portability between different boards. If you're interested in creating a custom board, create a custom board header file such as "ruuvitag_b3.h" and add your board header file to "custom_boards.h".
Drivers folder contains the peripheral drivers such as a driver for SPI as well as drives for sensors on PCB.
Libraries contain software routines which may not have hardware dependencies, i.e. they should run on your pc as well as on RuuviTag.
Ruuvi examples has example firmware projects which can be used as a basis for your own application. The top-level folder of application contains application code and configuration, and there is a subfolder for each hardware which can run the application. If the application requires softdevice, create a folder with softdevice name "s132" to let the users know that a softdevice is required. Configuration folder sets up board specific configuratuin, such as pins. Armgcc folder contains makefile and linker script.
The SDK folder contains Nordic Software development kit which is used to provide various low-level drivers and abstractions to speed up development. We do not host the SDK to reduce the size of repository, our makefile downloads and unzips the SDK if it is not present.
SDK overrides are bugfix backports or some minor changes to the official SDK files.
Please note that these examples inherit a lot of code from various sources and pay careful attention to license and origin of each application. Most importantly, the code will be statically linked against Nordic Softdevice, for which the source code is not available. Therefore the code is not GPL-compatible. For more details, please see licenses.md.
Developing Ruuvi Firmware
Instructions below are tested using OS X and Ubuntu, but basically any Unix distribution (or even Windows) should be fine. Compilation works also using the Bash on Ubuntu on Windows -feature added in the July 2016 update of Windows 10 if you follow the Ubuntu directions. If you've compiled and flashed successfully (or unsuccessfully), please identify yourself on our Slack :)
Prerequisites (to compile with ARMGCC):
The project currently uses the Nordic nRF52 SDK version 12.3.0 (downloaded in the
and thus requires the GNU ARM Embedded Toolchain version 4.9 Q3 2015 (aka 4.9.3) for compiling:
- Download and install GNU ARM Embedded Toolchain 4.9
For example on Xubuntu 16.04.3 using:
cd ~/Downloads/ wget https://launchpad.net/gcc-arm-embedded/4.9/4.9-2015-q3-update/+download/gcc-arm-none-eabi-4_9-2015q3-20150921-linux.tar.bz2 sudo tar xvfj gcc-arm-none-eabi-4_9-2015q3-20150921-linux.tar.bz2 -C /usr/local sudo apt-get install -y lib32ncurses5 lib32z1 echo 'PATH="/usr/local/gcc-arm-none-eabi-4_9-2015q3/bin:$PATH"' >> $HOME/.profile source $HOME/.profile # check version, expecting: 4.9.3 20150529 (release) arm-none-eabi-gcc --version
Changing the PATH might not be needed as the toolchain will use the path defined in the SDK Makefile.
Adjust the GNU_INSTALL_ROOT inside your Makefile in the
when using another destination than the
/usr/local shown above.
Note that the nRF52 SDK will be downloaded in
make, so only after this will
$SDK/components/toolchain/gcc/ folder exist in the project (typically
Prerequisites (to compile with Segger Embedded Studio):
Since Q4 of 2017 Segger Embedded Studio has been free (as in beer) to use with Nordic Semiconductor products such as nRF52. You can download latest version (>3.40) from Segger website.
You'll need to download and unzip the Nordic SDK 12.3 as above. Only Ruuvi Firmware is currently supported with SES, open folder
ruuvi_examples/ruuvi_firmware/ruuvitag_b/sesTo find the project file.
Prerequisites (to create DFU distribution .zip packages)
Instructions how to install (on OS X, Ubuntu):
curl -O https://bootstrap.pypa.io/get-pip.py sudo python get-pip.py
(Option 1) Install latest nrfutil from pip:
sudo pip install nrfutil # check version, expecting: 3.4.0 (or newer) nrfutil version
(Option 2) Install nrfutil from source:
git clone https://github.com/NordicSemiconductor/pc-nrfutil.git cd pc-nrfutil sudo pip install -r requirements.txt sudo python setup.py install # check version, expecting: 3.4.0 (or newer) nrfutil version
To get started with development kit you can try:
nrfutil settings generate --family NRF52 --application _build/ruuvi_firmware.hex --application-version 1 --bootloader-version 1 --bl-settings-version 1 settings.hex mergehex -m ~/git/s132_nrf52_3.1.0_softdevice.hex ~/git/ruuvitag_b_bootloader_1.0.0.hex settings.hex -o sbc.hex mergehex -m sbc.hex _build/ruuvi_firmware.hex -o packet.hex nrfjprog --family nrf52 --eraseall nrfjprog --family nrf52 --program packet.hex nrfjprog --family nrf52 --reset
Or to create a DFU packet:
nrfutil pkg generate --debug-mode --application _build/ruuvi_firmware.hex --hw-version 3 --sd-req 0x91 --key-file ~/git/ruuvitag_fw/keys/ruuvi_open_private.pem ruuvi_firmware_dfu.zip
Debug mode skips various version checks which is useful for development. Packages have to be signed,
RuuviTag ship with bootloader that accepts packages signed with the
More examples and details can be found at nrfutil repository.
make downloads Nordic Semiconductor's nRF52 SDK and extracts it. First time use will probably fail as SDK Makefile defines the path of toolchain, and the default path might differ from your system.
Modify $SDK/components/toolchain/gcc/Makefile.posix (on Linux and OSX) or Makefile.windows on windows to point to your gcc-arm install location.
You need also add support for secure bootloader elliptic curve cryptography by installing micro-ECC inside SDK, details can be found at Nordic Infocenter
Second time running
make builds all the sources.
make clean cleans the build directories.
For more help, please join Ruuvi Slack.
With Segger J-Link
If the device is empty (no SoftDevice S132 + bootloader flashed), you need to flash using SWD interface. The easiest way is to use nRF52 development kit (PCA10040) with embedded Segger. Steps:
Download and install latest J-Link
Start the J-Link from command line by typing:
JLinkExe -device nrf52 -if swd -speed 1000
SoftDevice is Nordic Semiconductor's Bluetooth Smart (or ANT) protocol stack. Sources are super secret, but the latest version is always bundled with the SDK. So, let's flash it:
After the SoftDevice is flashed successfully, flash the bootloader:
Get nrfjprog from Nordic's website.
nrfjprog offers simple wrapper to Segger's JLINK. To get started, erase your device:
nrfjprog --family nrf52 --eraseall
Then flash softdevice + bootloader:
nrfjprog --family nrf52 --program latest_softdevice.hex
nrfjprog --family nrf52 --program latest_bootloader.hex
Once you're ready, reset the device and verify yhe bootloader is broadcasting with your smartphone:
nrfjprog --family nrf52 -r
Over the Air
Once softdevice and bootloader are installed no cables are needed, ever (unless the device needs to be rescued for some reason)! From now on, the FW (and/or the bootloader and/or the SoftDevice) can be updated Over-The-Air using Nordic's nRF Toolbox (or MasterControl Panel):
If you're a developer, this is probably what you're after:
- Flash the SoftDevice protocol stack
- Compile the bootloader (and the application)
- Flash the bootloader
- Reset the device
- Create .zip distribution package (that includes at least the application code)
- Install nRF Toolbox (Android/iOS)
- Press DFU OTA button
- After completed, press it again! And again! No more cables needed ^^
- Now you can update SoftDevice and/or bootloader and/or application using DFU OTA. Cool, huh?