Install Zephyr microPlatform

The Zephyr microPlatform is an extensible software platform that makes it easier to develop, secure, and maintain Internet-connected applications on microcontroller devices.

The Zephyr microPlatform is based on the Zephyr real-time operating system, and the MCUBoot secure bootloader.

Zephyr microPlatform

This document describes how to:

• Set up a Zephyr microPlatform development environment on your workstation

• Flash MCUBoot and a Zephyr application image onto a microcontroller device

• Boot the device, verifying that MCUBoot correctly validates and chain-loads the Zephyr image

Important

Make sure you’ve obtained dependencies as described in Dependencies before continuing.

Set up Build Environment

Select your platform for instructions:

Linux

1. Install dependencies for the Zephyr microPlatform.

   On Ubuntu (16.04 and up):

   sudo add-apt-repository ppa:fio-maintainers/ppa
   sudo apt-get update
   sudo apt-get install zmp-dev
   pip3 install --user west
   

   On other distributions, see Appendix: Zephyr microPlatform Dependencies.

2. Install the tools you need to flash your board.

   For the nRF DK boards, you’ll need the nRF5x Command Line Tools. (Make sure you install the SEGGER tools too.)

   For other boards, check your board’s documentation.

3. Configure your username and password in Git:

   git config --global user.name "Your Full Name"
   git config --global user.email "[email protected]"
   

Your system is now ready to install the Zephyr microPlatform.

macOS

We test on macOS Sierra (10.12).

1. Install HomeBrew.

2. Install dependencies for the Zephyr microPlatform:

   brew install cmake ninja gperf ccache dtc python3
   pip3 install west
   

3. Install the tools you need to flash your board.

   For the nRF DK boards, you’ll need the nRF5x Command Line Tools. (Make sure you install the SEGGER tools too.)

   For other boards, check your board’s documentation.

4. Configure your username and password in Git:

   git config --global user.name "Your Full Name"
   git config --global user.email "[email protected]"
   

Your system is now ready to install the Zephyr microPlatform.

Windows 10

Note

Earlier versions of Windows may work, but are not tested.

1. Install Chocolatey.

2. Open cmd.exe as an Administrator (press Windows, cmd.exe, right-click the result, click “Run as Administrator”).

3. For convenience, disable global confirmation for choco command entry:

   choco feature enable -n allowGlobalConfirmation
   

4. Install CMake:

   choco install cmake --installargs 'ADD_CMAKE_TO_PATH=System'
   

5. Install the rest of the Zephyr tools you need:

   choco install git ninja gperf dtc-msys2 python
   

6. Install the tools you need to flash your board.

   For the nRF DK boards, you’ll need the nRF5x Command Line Tools. (Note Nordic recommends a particular version of the required SEGGER tools as well.)

   For other boards, check your board’s documentation.

7. Configure your username and password in Git:

   git config --global user.name "Your Full Name"
   git config --global user.email "[email protected]"
   

8. Install west:

   pip install west
   

Your system is now ready to install the Zephyr microPlatform.

Install and Set Up a Toolchain

For nRF DK boards (and other boards based on ARM Cortex-M cores), the GNU Arm Embedded toolchain works on Mac, Linux, and Windows. Install it somewhere on your system in a directory with no spaces in the path.

Now set these environment variables:

• ZEPHYR_TOOLCHAIN_VARIANT: set this to gnuarmemb.

• GNUARMEMB_TOOLCHAIN_PATH: set this to the location you installed the toolchain.

If you’re on Linux, you can also try the Zephyr SDK as an alternative. This comes with some additional tools, such as a recent OpenOCD, that may be useful on non-nRF boards.

Install the Zephyr microPlatform

The Zephyr microPlatform can be installed in any directory on your workstation. These instructions create a directory named zmp. You can change this to anything you want.

The latest continuous release is available as open source software on GitHub from github.com/foundriesio. Install it as follows.

1. Install Zephyr microPlatform update 46 using the Zephyr west tool in a new directory named zmp:

   west init -m https://github.com/foundriesio/zmp-manifest --mr refs/tags/46 zmp
   cd zmp
   west update

   Note

   If you just want to install the latest, drop the “--mr refs/tags/46” option.

2. Install additional dependencies required by Zephyr and MCUboot (make sure you are in the zmp directory created by west init):

   # Windows and macOS
   pip3 install -r zephyr/scripts/requirements.txt
   pip3 install -r mcuboot/scripts/requirements.txt
   pip3 install -r zmp-manifest/requirements.txt
   
   # Linux
   pip3 install --user -r zephyr/scripts/requirements.txt
   pip3 install --user -r mcuboot/scripts/requirements.txt
   pip3 install --user -r zmp-manifest/requirements.txt
   

   Note

   These requirements change with time. If something stops working after an update, run these lines again and retry.

Connect to the Board’s Console

Next, connect to your board’s console so you’ll be able to see the message printed when you flash the application in the next step.

• Make sure your board is plugged into your computer via USB. A serial port device (usually named /dev/ttyACM0 or /dev/ttyUSB0 on Linux, but the number may change if you’ve got other devices plugged in) should be created when the board enumerates if it supports USB serial.

• Open the device with your favorite serial console program1 at 115200 baud.

Build and Flash MCUboot

Choose your board from the below options, and run the corresponding commands from the zmp directory you made earlier to build and flash MCUboot on the board.

nRF52840 DK

west build -s mcuboot/boot/zephyr -d build-mcuboot -b nrf52840_pca10056
west flash -d build-mcuboot

nRF52 DK (nRF52832)

west build -s mcuboot/boot/zephyr -d build-mcuboot -b nrf52_pca10040
west flash -d build-mcuboot

You will see something that looks like the following:

***** Booting Zephyr OS zephyr-v1.13.0-4453-gf2ef52f122 *****
[00:00:00.004,333] <inf> mcuboot: Starting bootloader
[00:00:00.010,986] <inf> mcuboot: Image 0: magic=unset, copy_done=0x3, image_ok=0x3
[00:00:00.019,348] <inf> mcuboot: Scratch: magic=unset, copy_done=0xc0, image_ok=0x3
[00:00:00.027,801] <inf> mcuboot: Boot source: slot 0
[00:00:00.036,193] <inf> mcuboot: Swap type: none
[00:00:00.041,503] <err> mcuboot: Unable to find bootable image

Important

The default MCUboot build uses a publicly available RSA key pair bundled with MCUBoot (mcuboot/root-rsa-2048.pem) for ease of demonstration.

This key pair is for development use only.

For production, you must generate and use your own keys, or anyone will be able to sign binaries for your boards. See MCUboot Key Provisioning HOWTO for details on how to do this.

MCUboot is now installed on your board. You only need to do this once; from now on, you’ll just install bootable application images onto the same board to be loaded and run by MCUboot. No Zephyr application is available on the flash which can be loaded by MCUboot yet, though, which explains the Unable to find bootable image error message.

Let’s fix that now.

Build and Flash “Hello World” for MCUBoot

Now it’s time to build and flash Zephyr’s hello_world app. Unlike the Zephyr getting started tutorial, you’re going to build and flash it as an application image which can be loaded by the MCUboot bootloader that’s already on your board.

nRF52840 DK

west build -s zephyr/samples/hello_world -d build-hello \
           -b nrf52840_pca10056 -- -DCONFIG_BOOTLOADER_MCUBOOT=y
west sign -t imgtool -d build-hello -- --key mcuboot/root-rsa-2048.pem
west flash -d build-hello --hex-file zephyr.signed.hex

nRF52 DK (nRF52832)

west build -s zephyr/samples/hello_world -d build-hello \
           -b nrf52_pca10040 -- -DCONFIG_BOOTLOADER_MCUBOOT=y
west sign -t imgtool -d build-hello -- --key mcuboot/root-rsa-2048.pem
west flash -d build-hello --hex-file zephyr.signed.hex

Note

This requires that west flash for your board supports (and in fact prefers) to flash Intel Hex files. This is the case for the flash back-end which uses the nRF5x Command Line Tools.

When running west flash, the board should reset and the console should print messages that look roughly like this:

***** Booting Zephyr OS vX.Y.Z-NN-gabcdef *****
[MCUBOOT] [INF] main: Starting bootloader
[MCUBOOT] [INF] boot_status_source: Image 0: magic=unset, copy_done=0xff, image_ok=0xff
[MCUBOOT] [INF] boot_status_source: Scratch: magic=unset, copy_done=0x0, image_ok=0xff
[MCUBOOT] [INF] boot_status_source: Boot source: slot 0
[MCUBOOT] [INF] boot_swap_type: Swap type: none
[MCUBOOT] [INF] main: Bootloader chainload address offset: 0x8000
[MCUBOOT] [INF] main: Jumping to the first image slot
***** Booting Zephyr OS vX.Y.Z-NN-gabcdef *****
Hello World! <BOARD>

During this second flashing process:

1. The signed “hello world” application image is flashed, and the chip is reset.

2. MCUBoot runs out of reset, and checks the cryptographic signature on the application binary.

3. Since the signature is valid, MCUboot runs the application itself.

4. The application you just built will print a “Hello World” message on screen.

If you’re using another board, you may need to do something slightly different (especially depending on your flashing tools), but the basic idea is the same.

Change the Application and Reflash

Next, build and flash the dining philosophers sample. You’ve already flashed MCUboot, so just flash the new application:

nRF52840 DK

west build -s zephyr/samples/philosophers -d build-philosophers \
           -b nrf52840_pca10056 -- -DCONFIG_BOOTLOADER_MCUBOOT=y
west sign -t imgtool -d build-philosophers -- --key mcuboot/root-rsa-2048.pem
west flash -d build-philosophers --hex-file zephyr.signed.hex

nRF52 DK (nRF52832)

west build -s zephyr/samples/philosophers -d build-philosophers \
           -b nrf52_pca10040 -- -DCONFIG_BOOTLOADER_MCUBOOT=y
west sign -t imgtool -d build-philosophers -- --key mcuboot/root-rsa-2048.pem
west flash -d build-philosophers --hex-file zephyr.signed.hex

The console output will now show a text view of the famous “dining philosophers” concurrency puzzle executing.

Next Steps

So far this just seems like an extra-complicated way to flash an ordinary Zephyr application. However, if you can continue the tutorial at Set Up Basic LWM2M System, you’ll learn how to flash an application that can update itself over the air, using MCUboot to install updated application images.

Alternatively, learn more about the Zephyr microPlatform in HOWTOs and Zephyr microPlatform Reference Manual.

Reporting Issues

Please report any issues to the Foundries.io Support Portal.

Appendix: Zephyr microPlatform Dependencies

Here is a list of dependencies needed to install the Zephyr microPlatform with these instructions, which may be useful on other development platforms.

• Device tree compiler (dtc) version 1.4.6 or later

• Git

• CMake version 3.8.2 or later

• Ninja

• gperf

• Python 3 with the west project and various additional requirements in the requirements.txt files mentioned above.

Footnotes

1

On Linux, with picocom:

picocom -b 115200 /dev/ttyACM0

On Linux or macOS, with screen:

screen /dev/ttyACM0 115200

To use PuTTY on Windows, see Connecting to a local serial line in the PuTTY documentation.