This page details how to setup the development environment for boards based on Nordic Microcontrollers such as the nRF5 family, used for Sensry Kallisto® Product. More information is also available here. The document describes the setup of the build system under a Linux operating system. If the host system operated under Microsoft Windows, it’s recommended to setup a virtual system (like VirtualBox) as build environment. A 64-bit system with 4GB RAM and 10GB Hard Disk should be enough to run the build environment. If the host is already a Debian based Linux system, it can be configured following the guidelines. Several additional tools are needed. In some case the version of it may be of importance. The versions presented in this page are known to work and be compatible. More recent versions may also work.
Since most development is done in managed computers (no admin rights for user), the footprint should be reduced to a minimum. This guide will focus on installing all the tools on the following folder:
Whenever it is required to make a file available somewhere else, a link will be created instead.
This has been tested with Ubuntu 18.04.3 LTS, 64-bit.
Make is required to run the project Makefiles and is usually already installed on Linux distributions. If it's not available, you can get it through the following command (requires admin privileges):
$ sudo apt-get install build-essential checkinstall
This toolchain is required to build the cross-compile the projects for the target microcontroller core, which is typically an Arm Cortex-M0+ or Arm Cortex-M4.
The toolchain is usually available here. After downloading, extract the contents to
The naming of the tool package may change with the version. Please use the appropriate one. The tested and validated version is gcc-arm-none-eabi-9-2019-q4-major, all others may work.
It is required to create a link in a "user agnostic" path to the tools folder:
$ cd /var/tmp $ ln -s kallisto/tools/gcc-arm/
The J-Link software tools are used to interface with the debug probes made by SEGGER. The software tools are downloaded from here. Please download the 64-bit TGZ archive from the JLink software and documentation pack list.
After accepting the license agreement and downloading the file, extract its contents to:
The naming of the tool package may change with the version. Please use the appropriate one. The tested and validated version is JLink_Linux_V672d_x86_64, although others may work.
Please follow the instructions on the J-Link README file in order to enable the Linux system to detect the SEGGER J-Link Debugger automatically:
Running JLinkExe (or J-Link via USB in general) with standard user rights ========================================================================= In order to run JLinkExe with standard user rights you have to do the following: - Copy the file "99-jlink.rules" provided with this J-Link software package in the /etc/udev/rules.d/ directory using this command:<br></br><br></br> sudo cp 99-jlink.rules /etc/udev/rules.d/ Note: For older systems it might be necessary to replace the "ATTRS" calls in the 99-jlink.rules by "SYSFS" Calls<br></br><br></br> - Restart your system
The system expects the libjlinkarm.so to be installed in /opt/SEGGER/JLink. To address this issue, create a symlink in this folder pointing to your J-Link extraction location:
$ cd /opt/ $ sudo mkdir SEGGER $ ln -s /var/tmp/kallisto/tools/segger/JLink_Linux_<version> /opt/SEGGER/JLink
The Nordic Command Line Tools (CLT) allow you to load firmware to the targets via the debug interface (SWD). The CLTs can usually be downloaded from here.
After downloading the file, extract its contents to:
The naming of the tool package may change with the version. Please use the appropriate one. The tested and validated version is nRF5x-Command-Line-Tools_10_8_0_Linux-amd64, although others may work.
One more step is needed to get nrfjprog and JLink to work together. There is the need to create a symbolic link from the nrfjprog folder to two specific files on the JLink folder. In order to setup the links please execute the commands below (replacing your username and tools versions where appropriate):
$ cd /var/tmp/kallisto/tools/nordic/clt/nRF-Command-Line-Tools_<version>/nrfjprog/ $ ln -s /var/tmp/kallisto/tools/segger/JLink_Linux_<version>/libjlinkarm.so $ ln -s /var/tmp/kallisto/tools/segger/JLink_Linux_<version>/libjlinkarm_x86.so
This Phyton tool is required for several firmware deployment tasks, such as compiling bootloaders or creating OTA DFU packages. It is assumed you already have python installed. You can check if you have python by running the following command on the terminal:
$ python --version
If python is not available, please install python and python packet manager (pip) with admin rights:
$ sudo apt-get install python $ sudo apt-get install python-pip
The tested and validated versions for python and pip are Python 2.7.15+ and pip 9.0.1. Once python and pip are available, we can get nrfutil:
$ pip install nrfutil
This tool is required for several firmware deployment tasks, such as compiling bootloaders or creating OTA DFU packages.
Please download the tool from here. The tested validated version is protoc-3.11.4-linux-x86_64. Please extract the contents to
The naming of the tool package may change with the version. Please use the appropriate one.
Some additional libraries may need to run build environment, please install the following tools with admin rights using the ubuntu package manager:
$ sudo apt-get install libncurses5 libncurses5-dev libtinfo5 libtinfo-dev
This step is needed to make all tools available on the terminal. This step will be performed by adding the tool path to the $PATH environment variable.
To check what is currently on $PATH, please type the following on any terminal:
$ echo $PATH
To add our tools to $PATH on login (when you start your computer), add the following to
replacing your username and tool versions/paths as appropriate. The tools paths must match to the downloaded and installed versions.
... # set PATH so it includes user's private bin directories PATH="$PATH:$HOME/bin:$HOME/.local/bin:$PATH" # My tools PATH="$PATH:/var/tmp/kallisto/tools/nordic/clt/nRF-Command-Line-Tools_<i>version</i>/nrfjprog" PATH="$PATH:/var/tmp/kallisto/tools/nordic/clt/nRF-Command-Line-Tools_<i>version</i>/mergehex" PATH="$PATH:/var/tmp/kallisto/tools/segger/JLink_Linux_<i>version</i>" PATH="$PATH:/var/tmp/kallisto/tools/protobuf/protoc-<i>version</i>/bin" # My libs if [ -z "$VAR" ]; then export LD_LIBRARY_PATH=/var/tmp/kallisto/tools/libs/ else export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/var/tmp/kallisto/tools/libs/ fi ...
Save the changes made to the file, and logout and login again. In order to check if all tools are available please execute the following commands in terminal:
$ make -v $ nrfjprog -v $ mergehex -v $ JLinkExe $ nrfutil version $ protoc --version
The tested and validated versions of the build tools are:
GNU Make 4.1
nrfjprog version: 10.8.0
mergehex version: 10.8.0
SEGGER J-Link Commander V6.72d
nrfutil version 5.2.0
In order to be able to download the latest Sensry Kallisto® SDK it is necessary to install the version control system Git. Please install the git client with admin rights in the terminal:
$ sudo apt-get install git
The tested and validated version is 2.17.1, although others may work.
Git need to be configured to a generic client in order to be able to download the sources from a repository. Please add your GitLab email and user name to the git system:
$ git config –-global user.email “email@example.com” $ git config –-global user.name “example_name”
The user data will be stored in the .gitconfig file in home directory. Please read the file to see the contents:
$ cat .gitconfig [user] email = firstname.lastname@example.org name = example_name
To ensure a proper connection between the system and the GitLab repository an SSH key must be created. Make sure your system includes SSH version 6.5 or higher. To check type
$ ssh -v
If your version is suitable use the following commands to create an RSA SSH key
$ ssh-keygen -t rsa -b 2048 -C “email@example.com“
Confirm the prompted info of the key pair location by typing “enter”
Generating public/private rsa key pair. Enter file in which to save the key (/home/user/.ssh/id_rsa):
In the next step you can enter a passphrase for your SSH which you can modify at any time by
$ ssh-keygen -p -f /path/to/ssh_key
Adding the SSH key to your GitLab account requires the xclip package
$ xclip -sel clip < ~/.ssh/id_rsa.pub
Copy your key from the .pub file. It begins with “ssh.rsa” and ends with your email address. Log in to your GitLab account, click on your avatar → Settings → SSH Keys → paste the key → Add key.
Before the git repository will be cloned a folder should be created in the home directory:
$ mkdir kallisto-dev
Change to folder and clone the Sensry Kallisto® SDK repository:
$ cd kallisto-dev $ git clone https://gitlab.sensry.net/kallisto/kallistosdk.git
Update the Git Submodule from the SDK root folder:
$ cd kallisto-dev/kallistosdk $ git submodule update --init --recursive
Adjust the Makefile.posix in
GNU_INSTALL_ROOT ?= /var/tmp/kallisto/tools/gcc-arm/gcc-arm-none-eabi-<version>/bin/
Attention: The generic client is not allowed to commit any code to the repository. The following file structure should be available in your local file system:
. ├── components → all Sensry Kallisto® SDK components │ ├── ble → BLE driver │ ├── boards → Board definitions │ ├── bootloader → Public & private keys for OTA updates │ ├── drivers → low level sensor driver │ ├── drivers_ext → external low-level sensor driver from vendors │ ├── hal → Hardware abstraction layer for sensors │ └── libraries → additional libraries ├── documentation → SDK documentation / version tag ├── examples → examples for the SDK │ ├── ble_peripheral → /ble_app_sensing is already flashed on devices │ ├── dfu → bootloader test example │ ├── drivers → driver test examples │ └── hals → Hardware Abstraction Layer test examples ├── external → external sources │ └── nordic-sdk → Nordic SDK including SoftDevice-Stack ├── README.md └── tools → several tools for compiling and flashing devices └── scripts
The recommended basic hardware to connect and flash the devices using JTAG is the SEGGER J-Link Base Tool. It is a common JTAG/SWD Debug Probe with USB Interface. Additionally, the J-Link 9-Pin Cortex-M Adapter are needed to connect to the target device. Optionally, a J-Link Supply Adapter is needed for old versions of J-Link which doens't have internal VTREF configuration support.
Once the J-Link Base is connected to the host system, it should be detected automatically due to the installation of the UDEV rules in the previous chapter.
The J-Link Supply Adapter is only needed if the firmware of SEGGER J-Link doesn’t support the “VTREF” command. The “VTREF” command can apply a fixed referenced voltage internally. Please refer to chapter SEGGER J-Link Commander commands to see how to use the command. The internally reference voltage need to be set to 1.8V.
Attention: In case the J-Link Supply Adapter is used, the 0603-resistor “Rx” need to be changed to 110kOhm in order to set the reference voltage to 1.8V! The J-Link Supply Adapter will be delivered with the default voltage setting of 3.3V.
The SEGGER J-Link Commander JLinkExe accepts multiple command line arguments, the most important are:
Allows the selection of the target device family. Please use nrf52 for Sensry Kallisto®.
Allows to select the interface. Please use swd for Sensry Kallisto®.
Allows to select the communication frequency. Please use 1000 for Sensry Kallisto®.
Allows to specify the serial number of the debugger that should be attached to this connection.
This option is needed for using multiple debuggers at the same computer.
Allows the selection of the telnet port for this connection. If this option is omitted, port 19021 will be used. The telnet port is where the communication data will be published to/read from.
This option becomes especially useful when multiple debuggers are connected to the same computer, and we wish to communicate with them concurrently.
When this option is used to select a port other than 19021, JLinkRTTClient can no longer be used, as it automatically connects to port 19021. Instead, you should connect directly using telnet (see below).
Allows to enable auto connection, eliminating the need to type connect after starting JLinkExe
To connect to Sensry Kallisto® board, use the following command:
$ JLinkExe -device nrf52 -if swd -speed 1000
After the SEGGER J-Link Commander JLinkExe has been started, more commands become available. Typing ‘?’ shows the available commands. Useful commands are:
Attention: This command is mandatory for the Sensry Kallisto® PCB!
Set the internally reference voltage permanently and fixed to 1.8V. To reset the configuration to auto-detect, apply the command “VTREF 0”.
Establishes the connection to the target
Resets the target
Halts the target
Starts the target, after reset or halt
Erases all the memory of the target
Loads the .bin/.hex file to the target, starting at address mem_addr
One must be careful with the choice of mem_addr, parts of the firmware are supposed to be flashed in specific addresses
Using the Makefiles to flash firmware should be preferred over this method.
After connecting to the target using JLinkExe (and keeping that terminal open), the developer can read information from the target (and even write to it, if needed). The J-Link RTT Client JLinkRTTClient exists for that purpose. The client is started by typing JLinkRTTClient to the terminal:
There are several methods (and tools) to flash firmware to the targets. This page presents some methods of flashing Sensry Kallisto® devices.
Before starting to flash and erase memory, it is best to know how the firmware is organized on the nRF family devices. The following information was taken from the Nordic SDK documentation. The following figure displays the default memory layout of a 512 kB nRF52 device:
SoftDevices have different sizes. The following table shows the memory layout on a 512 kB nRF52 device with the S132 SoftDevice:
|0x0007A000 – 0x00080000||DFU Bootloader and data|
|0x0001B000 – 0x0007A000||Application code, free/swap and application data|
|0x00001000 – 0x0001B000||SoftDevice|
|0x00000000 – 0x00001000||Master Boot Record (MBR)|
In Sensry Kallisto® SDK, no dynamic memory allocation is ever used. This allows for the suppression of the heap, extending the space for code and stack. Therefore, the firmware has:
Provided on the Nordic SDK, pre-compiled
Only required if BLE is to be used
Must always be flashed to memory address 0
Must be compiled by developer
Must be compiled by developer
When BLE is not used and no SD is present, application should be flashed to mem address 0
There are three main methods of flashing/erasing firmware from the targets: JLinkExe, nrfjprog, Makefile
J-Link> VTREF 1800 <-- only needed if J-Link Power Adapter used J-Link> power on J-Link> connect J-Link> erase all J-Link> loadbin <path_to_bin> <mem_addr> or J-Link> loadfile <path_to_hex> J-Link> r J-Link> g
This method is useful to flash .hex files that have been built in the past and then stored somewhere, such as previous releases.
The tool nrfjprog can be used to write to and read from targets. Since the commands can be called from the terminal, it makes a better fit to be used in scripts instead of JLinkExe.
$ nrfjprog –-program <path_to_hex> -f nrf52 –-chiperase $ nrfjprog –-reset -f nrf52
Project Makefiles usually support several Makefile targets, some of which are meant not only for compiling, but also for erasing and flashing memory.
This should be the preferred method of flashing, as the Makefile knows where to place each part of the code.
Each project has small variation on the Makefiles, and even sometimes on the Makefile targets, but most of the sample projects contain a set of common to all projects.
For example, Sensry Kallisto® based projects all support the Nordic SDK specified Makefile targets, such as:
$ make $ make clean $ make flash $ make flash_softdevice $ make erase
Part of the Kallisto SDK is a set of deployment tools in order to give the customer an easy way to deploy firmware on their devices. Following pre-requisites need to be considered at first in order to use the tools successful:
The Sensry Kallisto® firmware consists of three main parts:
Bluetooth stack implementation from Nordic. Is part of the Nordic SDK
Used to perform over-the-air (OTA) device firmware updates (DFU)
Must be compiled by customer
Requires a Bootloader Settings (compiled by customer)
Requires a set of security keys, to perform secure OTA-DFU (compiled by customer)
User application with specific functionality
The Sensry Kallisto® based projects all use the Nordic SDK v12.3 Makefiles as a starting point. Therefore, the available Makefile targets are:
Simply compiles the application
Compiles the application and flashes it to the target device
Does not flash the SoftDevice
Flashes the SoftDevice to the target device
Cleans the compilation directory
Does not erase the target
These flash methods are useful to flash a single board, which is connected to the computer through a debugger. One example of this situation is when developing new firmware.
To deploy firmware to multiple devices, check the methods presented below.
As noticed, the Makefile only addresses how to compile the application firmware, and not much else. Due to this, Sensry provides a set of tools (bash scripts) to perform the more advanced deployment tasks. The tools are part of the SDK and are located under “tools\scripts”.
These scripts are intended to be used to validate that all the examples in the KallistoSDK are ok and compliable, before submitting a commit. The make-examples.sh script call the single script for each of the examples.
The script accepts some command line arguments for build configuration:
$ cd <kallistosdk_path>/tools/scripts $ ./make-examples.sh -h Usage : make-examples.sh [-h] [-b] [-c] [-p] [-s] -h : Displays (this) usage message -s : Selects serial execution (default). Incompatible with -p option -p : Selects parallel execution. Incompatible with -s option -b : Selects examples build operation (default). Incompatible with -c option -c : Selects examples clean operation. Incompatible with -b option
In serial execution, one example is compiled at a time, while in parallel execution, one independent process is launched to compile each example. Once parallel execution has been launched it cannot be stopped and you need to wait for finish.#
Tip: Unless you have a very good reason, run this script in parallel mode! Otherwise the execution will take a very long time.
The output of the script shows if an example has been compiled successfully or not. For the examples that fail compilation, a log file is created in a folder called “_build_logs”
| v | Example pca9570 > nRF52 > <hardware version> passed |XXX| Example pca9570 > nRF52 > <hardware version> failed
Private and public keys are used to perform secure OTA-DFU. When a board has been flashed with a bootloader containing a key, it will only accept OTA-DFU which contains that same key.
Each project has its own key, and when that is not desirable the Sensry Kallisto® SDK default key is used. The key is located in:
The generate_keys.sh script, creates a new pair of public and private keys.
This script generates a bootloader (which enables the use of OTA-DFU). The scripts accept multiple command line parameters, which enable the user to tailor the generated bootloader. The text in parenthesis () is the default option, which will be used if none is provided when executing the script.
$ cd <kallistosdk_path>/tools/scripts $ ./generate_bootloader.sh -h Usage generate_bootloader.sh [-dhps] [-acktv arg] args -a <PATH> : should point to the .hex of the application to be used with bootloader (./app.hex) -c <VERSION> : chip version (nrf51) chips available: nrf51, nrf52 -d : debug version -k <PATH> : set DFU public_key.c (SDK key) -p : generate Protocol Buffers -s : keep the bootloader and booloader settings in seperate files. Don't merge them. (false) -t <VERSION> : set application version (1) -v <VERSION> : set bootloader version (1)
When a firmware is ready to go to production and be flashed on the assembly line, a single file must be created, containing all the firmware parts (SoftDevice + Bootloader + Bootloader Settings + Application). This is the purpose of this script.
$ cd <kallistosdk_path>/tools/scripts $ ./generate_app_hex.sh -h Usage : generate_app_hex.sh [-hd] [- abktv] args -a <PATH> : set application path to be used (../../examples/ble_peripheral/ble_app_sensing) -b <BOARD> : board names available: SY010_PCB and SY020_PCB -d : use bootloader debug version (false) -k <PATH> : set DFU public_key.c (SDK key) -t <VERSION> : set application version (1) -v <VERSION> : set bootloader version (1) -t <VERSION> : set application version (1)
$ ./generate_app_hex.sh -a../../examples/ble_peripheral/ble_app_sensing/ -b <board name> -k generated_keys/public_key.c -t 1 -v 1 >>>>>>>>> Generating Application... Application Version = 1 Application Path = /home/sensry/Kallisto/dev/kallistosdk/examples/ble_peripheral/ble_app_sensing Board Name = <hardware version> DFU public key = /home/sensry/Kallisto/dev/kallistosdk/tools/scripts/generated_keys/public_key.c Compiling application. PATH = /home/sensry/Kallisto/dev/kallistosdk/examples/ble_peripheral/ble_app_sensing/nRF52/a-2868-01-BM/s132/gcc >>>>>>>>> Generating Bootloader... Debug build = false Protob = false Chip Version = nrf52 Bootloader Version = 1 DFU public key file = /home/sensry/Kallisto/dev/kallistosdk/tools/scripts/generated_keys/public_key.c Application Path = /home/sensry/Kallisto/dev/kallistosdk/examples/ble_peripheral/ble_app_sensing/nRF52/a-2868-01-BM/s132/gcc/_build/nrf52832_xxaa.hex Application Version = 1 Build Path = generated_bootloader/_build/bootloader_secure/nRF52/s132/gcc Merge files = false Setting application keys in makefile... Compiling bootloader. Generating bootloader settings (with app)... Bootloader DFU settings .hex file and stored it in: generated_bootloader/nrf52_bootloader_settings.hex Bootloader DFU Settings: * File: generated_bootloader/nrf52_bootloader_settings.hex * Family: nRF52 * Start Address: 0x0007F000 * CRC: 0xB53B9C43 * Settings Version: 0x00000001 (1) * App Version: 0x00000001 (1) * Bootloader Version: 0x00000001 (1) * Bank Layout: 0x00000000 * Current Bank: 0x00000000 * Application Size: 0x0002052C (132396 bytes) * Application CRC: 0x06F723A7 * Bank0 Bank Code: 0x00000001 * Softdevice Size: 0x00000000 (0 bytes) * Boot Validation CRC: 0x00000000 * SD Boot Validation Type: 0x00000000 (0) * App Boot Validation Type: 0x00000000 (0) Done. Brought to you by Kallisto Team. >>>>>>>>> Merging App + Bootloader Settings + Bootloader... Parsing input hex files. Merging files. Storing merged file. >>>>>>>>> Merging App + Bootloader Settings + Bootloader + SoftDevice... Softdevice file = /home/sensry/Kallisto/dev/kallistosdk/tools/scripts/../..//external/nordic-sdk//components/softdevice/s132/hex/s132_nrf52_3.0.0_softdevice.hex Parsing input hex files. Merging files. Storing merged file. Creating flash script... Done. Use "/home/sensry/Kallisto/dev/kallistosdk/tools/scripts/generated_app_hex/flash.sh" to flash the application. Done. Brought to you by Kallisto Team.
Note: This script calls some of the scripts presented above, and outputs a single .hex file that can be directly flashed to the target device (in memory address 0). The firmware hex-File is generated in a subfolder called “generated_app_hex/”. The script also creates a flash script (flash.sh) to provide an easy way to flash the firmware to the target. Simply use the command
to flash the complete firmware to target.
Note: board_name = SY010_PCB or SY020_PCB
This script creates the .zip file that can be flashed OTA to perform DFU. The security key used to create this .zip must match the one used to create the bootloader (though generate_bootloader.sh or generate_app_hex.sh) running on the target device.
$ cd <kallistosdk_path>/tools/scripts $ ./generate_app_zip.sh -h Usage : generate_app_zip.sh [-h] [-abkt arg] args -a <PATH> : set application path to be used (../../examples/ble_peripheral/ble_app_sensing) -b <NAME> : board names available: SY010_PCB, SY020_PCB -k <PATH> : should point to the private key to be used (./private_key.pem) -t <VERSION> : set application version (1)
To create a .zip file for update the Sensry Kallisto® devices standard firmware (KallistoBleFw) through OTA-DFU (using the Android Kallisto Toolbox or Android nRF Connect):
$./generate_app_zip.sh -a../../examples/ble_peripheral/ble_app_sensing/ -b <board name> -k generated_keys/private_key.pem -t 1 Application Version = 1 Key Path = generated_keys/private_key.pem App Path = ../../examples/ble_peripheral/ble_app_sensing/ Board Name = <board name> /home/sensry/Kallisto/dev/kallistosdk/tools/scripts Compiling application. PATH = ../../examples/ble_peripheral/ble_app_sensing//nRF52/a-2868-01-BM/s132/gcc Generating .zip... Zip created at generated_app_zip/ble_app_sensing_HW<hardware version>_SW_SDK22.214.171.124.zip Done. Saved zip at generated_app_zip/ble_app_sensing_HW<hardware version>_SW_SDK126.96.36.199.zip Brought to you by Kallisto Team.
Note: board_name = SY010_PCB or SY020_PCB
Note: The generated zip-File is in a generated subfolder with the name generated_app_zip/
A previous generated example.hex-file can be flashed after the SoftDevice has been flashed. The command for both steps are:
nrfjprog -f nrf52 --eraseall nrfjprog --program $<SDK_ROOT>/external/nordic-sdk/components/softdevice/s140/hex/s140_nrf52_7.0.1_softdevice.hex -f nrf52 --sectorerase nrfjprog --program example.hex -f nrf52 --sectorerase nrfjprog --reset -f nrf52
When running the ./generate_bootloader.sh script, an error might occur saying that micro_ecc_lib_nrf52.a could not be found. If that is the case, run the the ./build_all.sh in /external/micro-ecc. If you do not have permission to run the script use chmod +x build_all.sh first.
If this error is displayed you can install dos2unix using sudo apt-get install dos2unix, go to the script’s folder /external/micro-cc and execute dos2unix build_all.sh.