Getting Started with Zephyr for CS7NS2
We will be making extensive use of the Zephyr Project's embedded operating system for Internet of Things devices. The Zephyr Project website provides its own comprehensive documenation. The guide below should be used in conjunction with the Zephyr documentation to configure your development environment and build your first application.
The Zephyr Project supports numerous hardware platforms. The instructions provided here are tailored to the Nordic Semiconductor nRF52-DK Development Kit (part number PCA10040) and we will be using the GNU ARM Embedded Toolchain (referred to as a 3rd party toolchain in the Zephyr documentation) instead of the Zephyr Software Development Kit (or Zephyr SDK).
The Zephyr Project supports Linux, MacOS and Windows operating systems for building application firmware and provides detailed instructions to build your first application for each of these operating systems. The instructions provided here have been tested on Linux and MacOS but will still serve as a guide for those of you following the Zephyr Project documentation for Windows.
It is likely that there are errors or omissions in the instructions provided here. When you find them, please drop me an email with the details.
Before building our first Zephyr application, you need to install and configure a development environment. Your development environment will consist of:
- Your preferred text editor (atom, emacs, vi, sublime, ...)
- The GNU ARM Embedded Toolchain (compiler, linker, etc.)
- Software tools to support the SEGGER JLink JTAG adapter
- Nordic Semiconductor command line tools for configuring and programming the nRF52-DK target platform
After installing and configuring the development environment, you will obtain a customized version of the Zephyr source code for CS7NS2, install some necessary prerequisite software and then build your first application.
These instructions assume that you will use a directory called cs7ns2
in your home directory to store the Zephyr source code, GNU ARM Embedded Toolchain, Nordic Semiconductor command line tools, etc. You are free to reaplce this with a directory of your choosing and adapt the instructions below to your preference.
Note for MacOS users: If you don't already have homebrew installed, you should consider installing it by following the instructions on the Homebrew website to install it now. The instructions here and in the Zephyr documentation will make use of homebrew later.
GNU ARM Embedded toolchain
The GNU ARM Embedded Toolchain provides compilers, linkers and other software tools for cross-compiling code on one hardware/OS platform (Linux, MacOS, Windows) that will execute on another platform, in this case, an ARM Cortex-M series microprocessor.
There are a number of ways you can install the GNU ARM Embedded Toolchain, depending on your host platform, but the most robust is to download the toolchain directly from the ARM website. You can extract the toolchain to any suitable location (e.g. ~/cs7ns2/gcc-arm-none-eabi/
on MacOS or Linux). Avoid the temptation to add it to your PATH environment variable for now but do take a note of where you have installed it.
Using homebrew on MacOS
If you are using MacOS, you can alternatively install the GNU ARM Toolchain using homebrew. If you adopt this method, the path to the toolchain is likely to be /usr/local/
$ brew tap ArmMbed/homebrew-formulae
$ brew install arm-none-eabi-gcc
Segger JLink tools
Download the JLink software for your platform from the SEGGER website and follow the instructions.
You may need to manually add the path to the SEGGER JLink executables to your system PATH, if the installer doesn't do this for you (platform dependent).
This is not necessary on Linux as the SEGGER tools are located in a bin directory that should already be on your system PATH.
On MacOS you should add the following to your ~/.bash_profile
file:
export PATH=$PATH:/Applications/SEGGER/JLink
nRF5x Command Line Tools
Follow the instructions provided by Nordic Semiconductor to download the nRF5x Command Line tools for your platform and extract them in a location of your choosing (e.g. ~/cs7ns2/NordicSemi/nRF5x-Command-Line-Tools
). Alternatively, you may be able to find a convenient installer for your OS platform!
Make sure the location of the executables is included in your path. On Linux or MacOS you will need to add it yourself. One approach is to create a bin
directory under by home directory (if it doesn't already exist), add that to your PATH (again, if not already in your PATH) and create symbolic links to executables such as nrfjprog and mergehex.
$ cd
$ mkdir bin # may already exist, particularly on Linux
$ cd bin
$ ln -s [PATH TO nrfjprog EXECUTABLE] .
$ ln -s [PATH TO mergehex EXECUTABLE] .
If not already present, you can add your ~/bin
directory to your PATH variable. On MacOS, you would do this by editing your ~/.bash_profile
file adding line below. On Linux, your ~/.bashrc
file has probably already added ~/bin
to your path. If not, you can add it now as follows:.
export PATH=$PATH:~/bin
On Windows, the path can be edited in your Computer settings.
Verify that the tools are working (you may need to reopen a new command line session if you have modified the PATH variable):
$ nrfjprog --version
nrfjprog version: 9.0.0
JLinkARM.dll version: 6.14d
JLink Interface Firmware
Before getting started, you need to make sure that the nRF52-DK's on-board J-Link adapter is programmed with J-Link interface firmware and not ARM mbed interface firmware (as supplied by the manufacturer). You can determine this easily by connecting the nRF52-DK to a USB port and observing the drive name of the associated device. The name should contain jlink. If it contains mbed, you need to update the interface firmware as follows:
- Download the J-Link Interface MCU Firmware from the product page for the nRF52-DK.
- Unplug your nRF52-DK, or power it down if it has a power switch.
- Hold the RESET push-button and while holding it, power the board up again.
- You should see a new drive with a name containing BOOT. Now copy (by dragging in Windows or MacOS) the downloaded J-Link firmware to the drive.
- Power-cycle the target device, either using the power switch or by disconnecting and reconnecting the USB cable.
Note on using nrfjprog with multiple boards
If you have more than one J-Link adapter connected to your computer, you will need to tell nrfjprog (and any other J-Link tools) which adapter you want to communicate with. To do this, include the -s [SNR]
command line option with all of the nrfjprog commands below. You will need to replace [SNR]
with the J-Link serial number of the device you want to select. You can list all connected devices as follows:
$ nrfjprog -i
Testing the SEGGER and Nordic Semiconductor tools
You can now test that the SEGGER JLink tools and Nordic Semiconductor Command Line Tools have been installed correctly. To do this, connect your nRF52-DK board to a USB port and execute the following command:
$ nrfjprog --eraseall
You should see the output below.
Erasing user available code and UICR flash areas.
Applying system reset.
Obtaining Zephyr and its Dependencies
After preparing your development environment, you are ready to download the Zephyr source and build your first application.
Rather than download the Zephyr source code from the Zephyr GitHub repository, you should clone the CS7NS2 Zephyr repository to a location of your choosing (e.g. ~/cs7ns2).
$ cd
$ mkdir cs7ns2 # if not created it already, or a directory of your choosing
$ cd cs7ns2
$ git clone https://gitlab.scss.tcd.ie/cs7ns2-1819/zephyr.git
You can now follow the instructions in the Zephyr Project's Getting Started Guide, and particularly their development environment configuration instructions for Linux, macOS and Windows.
Note however that you should not follow the instructions for "Installing the Zephyr Software Development Kit" or "Setting Up the Toolchain" as we are using our Custom or 3rd party toolchain (the GNU ARM Embedded Toolchain). The Zephyr instructions can be confusing in this respect.
For Ubuntu Linux, the short version is:
$ sudo apt-get install --no-install-recommends git cmake ninja-build gperf ccache doxygen dfu-util device-tree-compiler python3-ply python3-pip python3-setuptools python3-wheel xz-utils file make gcc-multilib autoconf automake libtool
$ cd ~/cs7ns2/zephyr # or wherever you have installed zephyr
$ pip3 install --user -r scripts/requirements.txt
For macOS, the short version is:
$ brew install cmake ninja dfu-util doxygen qemu dtc python3 gperf
$ cd ~/cs7ns2/zephyr # or wherever you have installed zephyr
$ pip3 install --user -r scripts/requirements.txt
For Windows, follow the recommended approach in the Zephyr Project documentation for Windows.
Building a Zephyr Application
Each time you open a new terminal (command line) session to build Zephyr code, you need to configure some environment variables.
On Linux or MacOS:
$ export GNUARMEMB_TOOLCHAIN_PATH="~/cs7ns2/gcc-arm-none-eabi/" # or wherever you have installed the GNU ARM toolchain
$ export ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb
$ cd ~/cs7ns2/zephyr # or wherever you have installed zephyr
$ source zephyr-env.sh
Similarly, on Windows:
$ set ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb
$ set GNUARMEMB_TOOLCHAIN_PATH=c:\gnuarmemb # or wherever you have installed the GNU ARM Embedded toolchain
$ cd %HOME%\cs7ns2\zephyr # or wherever you have installed zephyr
$ zephyr-env.cmd
NOTE: The above step is essential and you need to repeat it every time you open a new terminal session to build Zephyr code. You will forget to do this occasionally!! If your code fails to even begin building, this should be the first thing you check.
Finally, we are ready to build, flash and run our first Zephyr application. We will use one of the sample applications provided by Zephyr in the samples/basic/blinky
folder.
On MacOS or Linux:
$ cd ~/cs7ns2/zephyr/samples/basic/blinky
$ mkdir build && cd build
$ cmake -GNinja -DBOARD=nrf52_pca10040 ..
$ ninja
If your build system is configured correctly, you should see the following output:
[126/131] Linking C executable zephyr/zephyr_prebuilt.elf
Memory region Used Size Region Size %age Used
FLASH: 43024 B 512 KB 8.21%
SRAM: 11084 B 64 KB 16.91%
IDT_LIST: 120 B 2 KB 5.86%
[131/131] Linking C executable zephyr/zephyr.elf
Connect your nRF52-DK to a USB port and flash the blinky application to the board:
$ ninja flash
You should observe the following output, and a flashing LED on the nRF52-DK!
[0/1] Flashing nrf52_pca10040
Using runner: nrfjprog
Flashing file: /Users/jdukes/Developer/zephyr-cs7ns2-1819/samples/basic/blinky/build/zephyr/zephyr.hex
Parsing hex file.
Erasing page at address 0x0.
Erasing page at address 0x1000.
Erasing page at address 0x2000.
[...]
Erasing page at address 0xA000.
Applying system reset.
Checking that the area to write is not protected.
Programming device.
Enabling pin reset.
Applying pin reset.
Board with serial number 682145371 flashed successfully.
Finally, for convenience, ninja flash
will automatically rebuild the firmware before flashing if you have modified any of the project's source files.