Open Source Foundries microPlatforms¶

The Zephyr and Linux microPlatforms are minimal, secure, continuously updated software and hardware platforms that make it easier to develop and maintain Internet-connected embedded devices. The microPlatforms are easy to use and are released as open source software.

Getting Started Tutorial¶

Start here for a step by step tutorial on how to install the microPlatforms, then use them to set up an end-to-end IoT demonstration system using the OMA Lightweight M2M (LWM2M) protocol.

A block diagram of this system is shown here, and though it is not explicitly shown, one or more IoT devices can connect to the network through the same gateway.

Using this demonstration system, you can:

See live data readings from your devices using the Leshan web application.
Send commands to the device, such as turning on and off an LED.
Use Leshan to update your IoT device firmware.
Secure your network communication using the DTLS protocol.

To set up and use this system, follow these pages in order.

Procure Dependencies¶

Hardware¶

To set up this system, you will need a Linux or macOS workstation computer, one or more IoT devices, and an IoT gateway.

The Zephyr and Linux microPlatforms were designed for portability, and the LWM2M system has been ported to several boards. To get started, however, we recommend the following.

Zephyr microPlatform dependencies:

BLE Nano 2 as an IoT device. Make sure to purchase the entire kit, including the DAPLink board, not just the standalone BLE Nano 2 board.

Linux microPlatform dependencies:

Raspberry Pi 3 as an IoT gateway
3.3 volt USB to TTL Serial Cable, such as this SparkFun FTDI Basic Breakout 3.3V
SD card compatible with Raspberry Pi 3 (see this Embedded Linux wiki guide for examples)
(Optional, but recommended) Ethernet cable for Raspberry Pi 3

This hardware was chosen for this tutorial mainly because it is commonly, and relatively inexpensively, available.

Subscriber Token¶

The latest Linux and Zephyr microPlatform updates are made continuously avaiable to subscribers. To access subscriber-only content, you’ll need to generate a token at https://foundries.io/s/.

Non-subscribers can use the public microPlatform update streams. Note note that these lag behind the subscriber updates by up to six months.

Install microPlatforms¶

After procuring the necessary dependencies, it’s now time to install the base microPlatforms on your devices, and set up a development environment on your workstation.

Install Linux microPlatform¶

The Linux microPlatform has a base system, which is built using OpenEmbedded / Yocto. Applications targeting the Linux microPlatform are then developed and deployed as one or more containers which run on the base system. Currently, Docker containers are supported.

Linux microPlatform

This document describes how to:

Install the base system onto your device.
Run a containerized nginx web server application onto the device, to demonstrate application deployment.

Make sure you’ve set up dependencies as described in Procure Dependencies before continuing.

Later on, you’ll replace the simple nginx container with several different containers to turn your Linux microPlatform device into an LWM2M gateway for your IoT devices.

Get Prebuilt images¶

Subscribers: prebuilt images for Linux microPlatform update git-osf-0.7-6-g28d7082 are available for subscribers either uncompressed, or as an .xz compressed archive:
- lmp-gateway-image.rootfs.sdimg (.sdcard format)
- lmp-gateway-image.rootfs.sdimg.xz (.sdcard.xz format)
Public: publicly available images will be provided at a later date.

After downloading the image, you must rename it so it has an .sdcard (or .sdcard.img) extension, instead of .sdimg (or .sdimg.xz). This is necessary for Etcher to recognize it. A future update to the binary artifacts will eliminate this step.

Flash Images To SD Card¶

The Raspberry Pi foundation recommends using the the cross-platform Etcher tool to flash images onto the SD card you’ll use to boot your Raspberry Pi 3.

After you’ve installed Etcher on your system:

Attach an SD card onto your host computer. Refer to this Embedded Linux wiki guide for a list of SD cards compatible with Raspberry Pi 3.
Run Etcher, and select the pre-built Linux microPlatform image you downloaded on your file system.
Select the SD card you mounted from Etcher, and flash it.

Additional, more advanced guides are available for macOS, Windows, and Linux.

Boot Raspberry Pi 3 and Connect it to the Network¶

Connect using Ethernet¶

Ethernet works out of the box if a DHCP server is available on the local network.

Connect an Ethernet cable to the Raspberry Pi 3.
Safely unmount the SD card from your computer, and insert it into the Raspberry Pi 3.
Apply power to the Raspberry Pi 3.

Your board will connect to the network via Ethernet. You can now log in using Zeroconf as described below in Connecting to the Board via Zeroconf.

Connect using WiFi¶

You can connect to a WiFi network by temporarily enabling the UART console on your Raspberry Pi 3 and running a command to connect to your WiFi network. You’ll need a 3.3 volt USB to TTL serial adapter, such as this SparkFun FTDI Basic Breakout 3.3V.

(For size reasons, the base Linux microPlatform doesn’t have windowing support enabled, so you can’t set up the initial WiFi connection using a graphical interface.)

Warning

The serial console is disabled by default on the Raspberry Pi 3. Unfortunately, using the console requires the device to run at significantly reduced speeds, and causes serious Bluetooth instability.

Make sure to follow the steps to disable the console and reboot after connecting to the network.

Mount the micro SD card containing the SD image you flashed on your workstation PC.
Edit the config.txt file on the VFAT partition, adding a new line with the following content:
```
enable_uart=1
```
Safely unmount the micro SD card, remove it from your workstation, and insert it into the Raspberry Pi 3.
Connect the adapter to your Raspberry Pi 3’s UART and to your workstation computer via USB, e.g. by following this AdaFruit guide.
Connect a serial console program on your workstation to the adapter, and power on the Raspberry Pi 3.
When prompted, log in via the console. The default username is osf, and the default password is osf. You should change the password before connecting to the network.
Connect to the network using the following command:
```
sudo nmcli device wifi connect NETWORK_SSID password NETWORK_PASSWORD
```
Where NETWORK_SSID is your WiFi network’s SSID, and NETWORK_PASSWORD is the password.
Safely shut down the Raspberry Pi 3, re-mount the SD card on your host workstation, and delete the line you added to config.txt.
Unmount the SD card from your workstation, insert it into the Raspberry Pi 3, and reboot it.

Your board will connect to the network you’ve saved after booting. You can now log in using Zeroconf as described in the next section.

Connecting to the Board via Zeroconf¶

If, as is likely, your local network supports Zeroconf, you can log in via SSH using raspberrypi3-64.local as the hostname:

ssh osf@raspberrypi3-64.local

The board should be ready to connect within a minute or two of booting.

Remember to change the password from the default osf if you haven’t already.

Zeroconf is a set of technologies that allows automatic discovery of systems and services available on a local area network. It helps by assigning a local address name (e.g. raspberrypi3-64.local instead of 192.168.1.10), which can be used by other Zeroconf compatible services like Bonjour on macOS.

Avahi, a free Zeroconf implementation, is available by default on the Linux microPlatform, making it easy for other Zeroconf-compatible hosts to locate the IP address assigned to the board.

To use Zeroconf, simply use raspberrypi3-64.local in place of the board’s IP address when that is needed.

Deploy nginx Container¶

You’ll now finish your Linux microPlatform installation by deploying an example containerized application which provides an nginx web server. Run the command on your device.

Subscribers¶

First, log in to the Linux microPlatform container registry on your Raspberry Pi 3:

docker login hub.foundries.io --username=unused

The username is currently ignored when logging in, but a value must be provided. When prompted for the password, enter your subscriber token.

Then run the nginx container:

docker run --name nginx-demo -p 80:80 hub.foundries.io/nginx:latest

Public¶

docker run –name nginx-demo -p 80:80 opensourcefoundries/nginx:latest

Connect to nginx¶

After the image is complete, the running container will stay connected to your terminal.

You can now check that it’s working by connecting to http://raspberrypi3-64.local in your browser. You should see an nginx splash page load, as well as log messages appearing in the terminal where you typed docker run, like so:

nginx splash page

Example terminal output:

10.0.0.111 - - [09/Jan/2018:21:07:21 +0000] "GET / HTTP/1.1" 200 612 "-" "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/63.0.3239.132 Safari/537.36" "-"
2018/01/09 21:07:22 [error] 7#7: *1 open() "/usr/share/nginx/html/favicon.ico" failed (2: No such file or directory), client: 10.0.0.111, server: localhost, request: "GET /favicon.ico HTTP/1.1", host: "raspberrypi3-64.local", referrer: "http://raspberrypi3-64.local/"
10.0.0.111 - - [09/Jan/2018:21:07:22 +0000] "GET /favicon.ico HTTP/1.1" 404 571 "http://raspberrypi3-64.local/" "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/63.0.3239.132 Safari/537.36" "-"

Press Control-C to stop the container. You can now remove it using:

docker rm nginx-demo

The Linux microPlatform is now successfully deployed on your device. Move on to the next page to install the Zephyr microPlatform.

Reporting Issues¶

Please report any issues to the Open Source Foundries FreshDesk.

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

Make sure you have set up dependencies as described in Procure Dependencies before continuing.

Set up Build Environment¶

Before installing the the Zephyr microPlatform, you need to set up your workstation build environment. Instructions for each supported platform follow.

macOS¶

We test on macOS Sierra (10.12).

Install HomeBrew.

Install dependencies for the Zephyr microPlatform:

brew install dtc python3 repo gpg
pip3 install --user ply pyyaml pycrypto pyasn1 ecdsa pyelftools

Install the tools you need to flash your board.

For BLE Nano 2, you’ll need pyOCD, which you can install with Python 2 from HomeBrew:
```
brew install python cmake
pip2 install --user pyOCD
export PATH=$PATH:$HOME/Library/Python/2.7/bin
```
Otherwise, check your board’s documentation.

Configure your username and password in Git:

git config --global user.name "Your Full Name"
git config --global user.email "your-email-address@example.com"

Your build environment is now ready; continue by following the steps in Install the Zephyr microPlatform.

Windows 10 (Experimental)¶

Windows versions supporting the Windows Subsystem for Linux have experimental support. For this to work, you will need 64 bit Windows 10 Anniversary Update or later.

These instructions should let you build binaries; however, flashing support is not yet documented.

Install the Windows Subsystem for Linux, then open a Bash window to enter commands.
Change to your Windows user directory with a command like this:
```
cd /mnt/c/Users/YOUR-USER-NAME
```
You can press the Tab key after typing /Users/ to see a list of user names.

Warning

Skipping this step means you won’t be able to use the microPlatform with Windows tools like Explorer, graphical editors, etc.

As documented by Microsoft, changing files in Linux directories using Windows tools can damage your system.
We recommend making sure your Linux subsystem is up to date with these commands (which can take a while they first time they’re run):
```
apt-get update
apt-get upgrade
```
Finish by following the Ubuntu instructions in the next section.

Linux¶

Install dependencies for the Zephyr microPlatform.

On Ubuntu 16.04:
```
sudo add-apt-repository ppa:osf-maintainers/ppa
sudo apt-get update
sudo apt-get install zmp-dev
pip3 install --user pyelftools
```
On other distributions, see Appendix: Zephyr microPlatform Dependencies.
Install the tools you need to flash your board.

For BLE Nano 2, you’ll need pyOCD, which you can install with pip:
```
pip install --user pyOCD
```
On Linux platforms, you also need to install the following udev rules as root, then unplug and plug back in any boards you may have connected:
```
echo 'ATTR{idProduct}=="0204", ATTR{idVendor}=="0d28", MODE="0666", GROUP="plugdev"' > /etc/udev/rules.d/50-cmsis-dap.rules
```

Configure your username and password in Git:

git config --global user.name "Your Full Name"
git config --global user.email "your-email-address@example.com"

Your system is now ready to install the Zephyr microPlatform.

Install the Zephyr microPlatform¶

The Zephyr microPlatform can be installed in any directory on your workstation. Installation uses the Repo tool to fetch a variety of Git repositories at known-good revisions, and keep them in sync as time goes on.

If you’re new to Repo and want to know more, see Repo Primer for Zephyr microPlatform.

Subscribers¶

The latest continuous release is available to Zephyr microPlatform subscribers from source.foundries.io. Install it as follows.

Configure Git to cache usernames and passwords you enter in memory for one hour:
```
git config --global credential.helper 'cache --timeout=3600'
```
Using some credential helper is necessary for repo sync to work properly later[1].
If you haven’t already, create a subscriber token on foundries.io/s/.
Make an installation directory for the Zephyr microPlatform, and change into its directory:
```
mkdir zmp && cd zmp
```
Install the latest release using repo:
```
repo init -u https://source.foundries.io/zmp-manifest
repo sync
```
When prompted by repo init, enter your subscriber token for your username and nothing for the password.

Public¶

The latest public release is available from the Open Source Foundries GitHub organization.

Make an installation directory for the Zephyr microPlatform, and change into its directory:
```
mkdir zmp && cd zmp
```

Install the latest release using repo:

repo init -u https://github.com/OpenSourceFoundries/zmp-manifest
repo sync

Build an Application¶

Now that you’ve installed the Zephyr microPlatform, it’s time to build a demonstration application.

Since one of the main features of the microPlatform is making it easy to build application binaries which are cryptographically checked by MCUBoot, a secure bootloader, you’ll first build a simple “Hello World” application provided by MCUBoot.

Warning

This cryptographic verification uses a publicly available RSA key pair bundled with MCUBoot, for ease of demonstration. The private key is in mcuboot/root-rsa-2048.pem; the public key is embedded in the sources in boot/zephyr/keys.c. This key pair is for development use only.

For secure deployment, you must generate and use your own keys in your production image build environment.

When using a BLE Nano 2, run this from the zmp directory you made earlier:

./zmp build -b nrf52_blenano2 mcuboot/samples/zephyr/hello-world

(For more information, see Build an Application: zmp build.)

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.

If you’re using a BLE Nano 2:

Make sure it’s plugged into computer via USB. A serial port device (usually named /dev/ttyACM0 on Linux, but the number may change if you’ve got other devices plugged in) will be created when the board enumerates.
Open the device with your favorite serial console program[3] at 115200 baud.

Flash the Application¶

Now you’ll flash MCUBoot and the hello-world application to your board.

When using BLE Nano 2, run this from the the Zephyr microPlatform directory:

./zmp flash -b nrf52_blenano2 mcuboot/samples/zephyr/hello-world

(For more information, see Flash an Application to a Device: zmp flash.)

You should now see some messages printed on the board’s console.

When the board boots:

The MCUBoot bootloader runs first, and checks the cryptographic signature on the application binary.
If the signature is valid for the given binary, will run the application itself.
The application you just built will print a “Hello World” message on screen.

The combined output looks like this:

[MCUBOOT] [INF] main: Starting bootloader
[MCUBOOT] [INF] boot_status_source: Image 0: magic=good, copy_done=0xff, image_ok=0xff
[MCUBOOT] [INF] boot_status_source: Scratch: magic=unset, copy_done=0x2f, 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 v1.9.99 - BUILD: Nov  8 2017 20:38:06 *****
Hello World from Zephyr on nrf52_blenano2!

If you’re using another board, you may need to do something slightly different, but the basic idea is the same: connect a serial console at 115200 baud, and run zmp flash to flash and run the program.

The Zephyr microPlatform development environment is now set up on your workstation, and you’ve verified you can flash your device. Move on to the next page to set up the basic LWM2M system.

Reporting Issues¶

Please report any issues to the Open Source Foundries FreshDesk.

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)
Git
GNU Make
GCC and G++ with 32-bit application support
gperf
bzip2
Python 3 with the following packages:
- setuptools
- PLY
- PyYaml
- Crypto
- ECDSA
- ASN.1
- pyelftools
Google Repo

Footnotes

[1]	If you don’t want to do that, see https://git-scm.com/docs/gitcredentials for some alternatives.

[2]	Since this tutorial is meant to help you get started, the binaries are signed with keys that aren’t secret, and are not suitable for production use.

[3]	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.

Set Up Basic LWM2M System¶

Now that you have installed the Zephyr and Linux microPlatforms, it’s time to use them to set up an end-to-end IoT demonstration system using the OMA Lightweight M2M (LWM2M) protocol.

A block diagram of this system is shown here. Though it is not explicitly shown, one or more IoT devices can connect to the network through the same gateway.

The system contains Zephyr-based IoT devices, an IoT gateway, and a web application, Leshan, that is used as the LWM2M server. With Leshan you can issue commands, query data and perform firmware over the air (FOTA) updates on the IoT device(s).

Using the demonstration system described here, you can:

See live data readings from your devices using the Leshan web application.
Send commands to the device, such as turning on and off an LED.
Use Leshan to update your IoT device firmware.

For simplicity, this basic system does not secure its network communications. Instructions in the next page describe how to set up secure channels using the DTLS protocol.

Prepare the System¶

Begin by preparing the system for use.

Set up Workstation¶

Open Source Foundries provides pre-built Leshan Docker containers for use on your workstation, and Ansible playbooks and associated shell scripts you can run there which make it easier to set up your gateway.

Begin by installing Docker and Ansible on your workstation (not your gateway device).

Run Leshan on Workstation¶

Continue by starting a demonstration-grade Leshan server on your workstation.

Subscribers:

First, log in to the Open Source Foundries subscriber container registry on your worksation (not the gateway device):

docker login hub.foundries.io --username=unused

The username is currently ignored when logging in, but a value must be provided. When prompted for the password, enter your subscriber token.

Now run the latest subscriber container, again on your workstation:

docker run --restart=always -d -t -p 5683:5683/udp -p 5684:5684/udp \
  --read-only --tmpfs=/tmp -p 8081:8080 \
  --name leshan hub.foundries.io/leshan:latest

Public:

Containers for the latest public relase are available from Docker Hub. Run this on your workstation:

docker run --restart=always -d -t -p 5683:5683/udp -p 5684:5684/udp \
  --read-only --tmpfs=/tmp -p 8081:8080 \
  --name leshan opensourcefoundries/leshan:latest

After running the Leshan container, visit http://localhost:8081/ to load its web interface. Your Leshan container is now ready for use.

Set up IoT Gateway¶

You’ll now use Ansible to set up your IoT gateway to act as an LWM2M network proxy for your IoT device.

Ensure you have an SSH key on your workstation. If you’ve never done this before, the GitHub guide to SSH keys has useful instructions.
Copy your SSH key to the gateway in order to control it with Ansible:
```
ssh-copy-id osf@raspberrypi3-64.local
```
Use the password for the osf account you set earlier when installing the Linux microPlatform (the default is osf, but we recommend that you change it).
Clone gateway-ansible, a repository of Ansible playbooks, helper scripts and files, and Dockerfiles, onto your workstation.

Subscribers:

For passwordless authentication, create a file named .netrc (note the leading .) in your home directory, readable only by your user, with the following contents:
```
machine source.foundries.io
login <your-subscriber-token>
```
If you don’t createa .netrc, enter your subscriber token when prompted for a username, and leave the password blank.

Now clone the gateway-ansible repository:
```
git clone https://source.foundries.io/gateway-ansible
```
Public:
```
git clone https://github.com/OpenSourceFoundries/gateway-ansible
```

From the gateway-ansible repository cloned on your workstation, deploy the gateway containers to your gateway using Ansible.

Subscribers:
```
GW_HOSTNAME=raspberrypi3-64.local REGISTRY_PASSWD=<your-subscriber-token> ./iot-gateway.sh
```
Setting REGISTRY_PASSWD to your subscriber token is necessary to ensure your gateway device can log in to the container registry. If you’re concerned about typing it directly into the terminal, you can set it in the environment via any means you find sufficiently secure.

Public:
```
REGISTRY=hub.docker.com REGISTRY_USER=docker REGISTRY_PASSWD=docker \
   GW_HOSTNAME=raspberrypi3-64.local ./iot-gateway.sh
```
These instructions assume iot-gateway.sh is run on the same machine running the hawkBit server. Set MGMT_SERVER to the IP address of the machine running the hawkBit container if your environment is different.

Your gateway device is now ready for use.

Set up IoT Device(s)¶

Required Equipment: IoT device and workstation to flash the device.

When using BLE Nano 2, build and flash the demonstration application for this system:

./zmp build -b nrf52_blenano2 zephyr-fota-samples/dm-lwm2m
./zmp flash -b nrf52_blenano2 zephyr-fota-samples/dm-lwm2m

Flashing this board requires pyOCD. To install this dependency, run:

pip install --user pyOCD

If you don’t have pip installed, see the pip Installation documentation. On Linux platforms, you also need to install the following udev rules as root, then unplug and plug back in any boards you may have connected:

echo 'ATTR{idProduct}=="0204", ATTR{idVendor}=="0d28", MODE="0666", GROUP="plugdev"' > /etc/udev/rules.d/50-cmsis-dap.rules

Use the System¶

Now that your system is fully set up, it’s time to check that sensor data are being sent to the cloud, and do a FOTA update.

Note

The Leshan user web interface is a simple web application, which does not provide a complete end-to-end device management system. The container’s simplicity makes it useful as a demonstration and prototyping system for LWM2M devices.

Read and Write Objects¶

When a device registers with the Leshan server, Leshan will automatically render known object types in its web interface. You can interact with these objects by clicking the Read, Write, etc. buttons which appear next to them.

Read device instance information

To read general device instance information, scroll down to “Device” > “Instance 0” and click the “Read” button as shown in the following figure.

Click on the Read button following “Instance 0”.
Read current state of temperature and light objects

To read the current status of the temperature and light control objects, click the “Read” button next to each “Instance” of these objects as shown in the following figure.

Click on the Read buttons following the instances.
Change state of the light object

Click ‘Write’ buttons to bring up interfaces for changing data. An example of this interface for the light object is shown here.

Clicking the On/Off Write button brings up this interface.

Initiate a Firmware Update¶

It’s now time to update the device firmware, using the Firmware Update object view in Leshan. This involves writing a URI where the firmware update is hosted to the “Package URI” field for this object. To keep things simple, you’ll “update” the firmware using the same binary you built previously, but you can also change and rebuild the program before following these steps to write new firmware.

Start a Python 3 HTTP on your workstation from the Zephyr microPlatform binary build directory for this application:

$ cd zmp/outdir/zephyr-fota-samples/dm-lwm2m/nrf52_blenano2/app/
$ python3 -m http.server

The update will then be available at:

http://YOUR_WORKSTATION_IP:8000/zephyr/dm-lwm2m-nrf52_blenano2-signed.bin

To start the firmware update, click the Write button for the “Package URI” field in the Firmware Update object, then write this value in the resulting popup, like so.

Set the Package URI field.

Once you click the Update button, the file will begin transferring to the target.

In general, the Package URI must be hosted where it is routable from your IoT device. The URI schema can be either coap:// or http://. The length of the Package URI must be less than 255 characters.

Monitor for a Completed Transfer¶

Click the “Observe” button in the State line of the Firmware Update object:

Leshan interface showing State value equal to 1

Example State observation. Value is 1 (downloading).

The state values and their meanings are:

0: Idle

1: Downloading

2: Downloaded

3: Updating

If you’re connected to the device console, progress is logged as in the following example:

[0912360] [fota/lwm2m] [INF] firmware_block_received_cb: 77%
[0920080] [fota/lwm2m] [INF] firmware_block_received_cb: 78%
[0927350] [fota/lwm2m] [INF] firmware_block_received_cb: 79%
[0931870] [lib/lwm2m_rd_client] [INF] do_update_reply_cb: Update callback (code:2.4)
[0931870] [lib/lwm2m_rd_client] [INF] do_update_reply_cb: Update Done
[0932510] [fota/lwm2m] [INF] firmware_block_received_cb: 80%
[0939070] [fota/lwm2m] [INF] firmware_block_received_cb: 81%
[0946090] [fota/lwm2m] [INF] firmware_block_received_cb: 82%
[0951050] [fota/lwm2m] [INF] firmware_block_received_cb: 83%

Monitor the transfer until the State value is 2 (Downloaded):

Leshan interface showing State value equal to 2

State value is now 2 (Downloaded).

Download completion is logged on the device console as in the following example:

[1073870] [fota/lwm2m] [INF] firmware_block_received_cb: 98%
[1078930] [fota/lwm2m] [INF] firmware_block_received_cb: 99%
[1085540] [fota/lwm2m] [INF] firmware_block_received_cb: 100%

Execute the Update¶

After the device has downloaded the update file, initiate the update by clicking on the “Exec” button on the Update line.

The device console logs messages as it resets into the bootloader, MCUBoot, which will load the new image:

[1171230] [fota/lwm2m] [DBG] firmware_update_cb: Executing firmware update
[1171230] [fota/lwm2m] [INF] firmware_update_cb: Update Counter: current -1, update -1
[1172260] [fota/lwm2m] [INF] reboot: Rebooting device
[MCUBOOT] [INF] main: Starting bootloader
[MCUBOOT] [INF] boot_status_source: Image 0: magic=good, copy_done=0xff, image_ok=0x1
[MCUBOOT] [INF] boot_status_source: Scratch: magic=unset, copy_done=0x2f, image_ok=0xff
[MCUBOOT] [INF] boot_status_source: Boot source: slot 0
[MCUBOOT] [INF] boot_swap_type: Swap type: test
[MCUBOOT] [INF] main: Bootloader chainload address offset: 0x8000
[MCUBOOT] [INF] main: Jumping to the first image slot
***** BOOTING ZEPHYR OS v1.9.99 - BUILD: Nov  8 2017 22:04:52 *****
[0000000] [fota/main] [INF] main: Linaro FOTA LWM2M example application
[0000010] [fota/main] [INF] main: Device: nrf52_blenano2, Serial: 1ef8e685

When the update execution is complete, the device will register with Leshan again.

Congratulations! You’ve just read and written objects, and done your first FOTA update using this system. Continue to the next page to secure LWM2M communications using DTLS.

Reporting Issues¶

Please report any issues to the Open Source Foundries FreshDesk.

LWM2M System With DTLS¶

This page describes how to enable DTLS-based LWM2M communication between the gateway and IoT devices in the basic system you’ve already set up.

These instructions assume you are using a BLE Nano 2.

Warning

This is an experimental feature, with important security limitations.

The application implementation currently does not use a high-quality source of random values. Random values are commonly used throughout the DTLS protocol for various security properties.
The firmware update procedure uses plain HTTP, rather than LWM2M over DTLS. This leaks the contents of the updated firmware binary. (This can be used in denial of service and information disclosure attacks, but the MCUBoot binary will still refuse to boot unsigned binaries.)
The Leshan server still allows unauthenticated HTTP access to the IoT devices via its user interface and REST API. For example, this is used below to provision the device token, which leaks it over the local network to any eavesdropper. It also allows interacting with any device objects using an unauthenticated and unencrypted interface.

Generate Credentials Partition¶

You first need to generate a binary blob containing device credentials to use.

From the ZMP installation directory, run a command like this:

./zephyr-fota-samples/dm-lwm2m/scripts/gen_cred_partition.py --device-id=deadbeef --device-token=000102030405060708090a0b0c0d0e0f --output=cred.bin

The arguments are as follows.

--device-id is a public identifier for the device. This is currently limited to eight hexadecimal characters.
--device-token is a secret, device-specific token value (i.e., the token must be different for each device on the network). This is a sequence of 32 two-character hexadecimal values, each representing a byte. In the above example, the first byte is 0x00, the second is 0x01, etc.
--output is the output file which will contain the binary.

Build and Flash IoT Device With DTLS Enabled¶

Again from the ZMP installation directory, you now need to re-build and re-flash the application with DTLS enabled, along with the credentials partition:

rm -rf outdir/zephyr-fota-samples/dm-lwm2m/nrf52_blenano2
./zmp build -b nrf52_blenano2 --conf-file "prj_dtls.conf boards/nrf52_blenano2.conf" zephyr-fota-samples/dm-lwm2m
./zmp flash -b nrf52_blenano2 zephyr-fota-samples/dm-lwm2m
pyocd-flashtool -se -t nrf52 --address 0x7f000 cred.bin

Provision Leshan With Device Token¶

Now use the Leshan REST API to provision the device ID and token as in the following command line. (Make sure to change each occurrence of deadbeef to your device ID, and the key from 000102...0f to the key value you chose earlier.)

As noted above, this command line uses HTTP, and thus leaks the key, for example to any eavesdropper on the local network:

curl -v -X PUT -H "Content-Type: application/json" -d "{\"endpoint\":\"deadbeef\",\"psk\":{\"identity\":\"deadbeef\",\"key\":\"000102030405060708090a0b0c0d0e0f\"}}" http://localhost:8081/api/security/deadbeef

Use the System¶

You should now be able to use the system with DTLS enabled in same ways as the basic system.

Using Other Zephyr Boards¶

Warning

Content in this section is provided on a best-effort basis.

This document contains additional information related to using the system on other boards.

FRDM-K64F¶

Building for FRDM-K64F requires some configuration information which depends on your local network:

An IP address to use for the IoT gateway
Whether the board should use DHCP, or a static IP address

This information must be written to the file zephyr-fota-samples/dm-lwm2m/boards/frdm_k64f-local.conf in the Zephyr microPlatform installation directory.

To use DHCP, with gateway IP address A.B.C.D, create the file with the following contents.

CONFIG_NET_DHCPV4=y
CONFIG_NET_APP_PEER_IPV4_ADDR="A.B.C.D"

To use a static IP address X.Y.Z.W for the FRDM-K64F instead, use this.

CONFIG_NET_APP_MY_IPV4_ADDR="X.Y.Z.W"
CONFIG_NET_APP_PEER_IPV4_ADDR="A.B.C.D"

In addition, zephyr-fota-samples/dm-lwm2m/boards/frdm_k64f-local.conf must contain a line which specifies the IP address of the COAP proxy. In this case, that’s just the IP address of your gateway device. To use IP address L.M.N.O, add a line like this after the other networking configuration:

CONFIG_LWM2M_FIRMWARE_UPDATE_PULL_COAP_PROXY_ADDR="L.M.N.O"

Now you can build the binaries. From the Zephyr microPlatform installation directory:

./zmp build -b frdm_k64f zephyr-fota-samples/dm-lwm2m

Flashing this board requires pyOCD. To install this dependency, run:

pip install --user pyOCD

If you don’t have pip installed, see the pip Installation documentation. On Linux platforms, you also need to install the following udev rules as root, then unplug and plug back in any boards you may have connected:

echo 'ATTR{idProduct}=="0204", ATTR{idVendor}=="0d28", MODE="0666", GROUP="plugdev"' > /etc/udev/rules.d/50-cmsis-dap.rules

To flash the binaries, plug the K64F into your system via the USB connector labeled “SDA USB”. Then, from the Zephyr microPlatform installation directory:

./zmp flash -b frdm_k64f zephyr-fota-samples/dm-lwm2m

96Boards Nitrogen¶

Like FRDM-K64F, this board also requires pyOCD to flash.

To build the binaries, run this from the Zephyr microPlatform installation directory:

./zmp build -b 96b_nitrogen zephyr-fota-samples/dm-lwm2m

To flash the board:

./zmp flash -b 96b_nitrogen zephyr-fota-samples/dm-lwm2m

HOWTOs¶

The following pages contain detailed documentation for specific topics. The aim is to provide concrete instructions for common tasks, in contrast to the more generic references in Reference Manuals.

Zephyr microPlatform Workflows HOWTO¶

This page describes the workflows for developing and deploying embedded applications with the Zephyr microPlatform. It assumes that the Zephyr microPlatform has successfully been installed as described in Install Zephyr microPlatform.

Use Repo to Fetch Updates¶

The Zephyr microPlatform uses the Repo tool to manage its Git repositories. In Install Zephyr microPlatform, you used this tool to clone these Git repositories into a Zephyr microPlatform installation directory on a development computer. See Repo Primer for Zephyr microPlatform for more details.

After the installation, you’ll continue to use Repo to fetch upstream changes as follows.

Enter the .repo/manifests subdirectory of the Zephyr microPlatform (this is where the Repo manifest repository is installed on your system).
Use git to note the current Git commit SHA of the manifest repository. For example:
```
git --no-pager log -n1 --pretty='%H'
```
We’ll call the current SHA STARTING_MANIFEST_SHA.
Go back to the top level Zephyr microPlatform installation directory, and use Repo to sync updates:
```
repo sync
```
Warning

If you make any changes to any repositories managed by Repo, this will attempt to rebase your local branches, which can cause conflicts. Please see Managing Out of Tree Patches for more details.

You can use repo sync -n to fetch changes only, without rebasing, and then use Git to inspect the differences between your local and the upstream branches, merge or rebase appropriately, etc.

This is currently considered an advanced use case. If you are trying this during the beta period and you run into problems, please contact us.
After running repo sync, you can use the zmp helper script documented above to re-build and re-test your application, and make adjustments.

We recommend comparing your application with the updated version of the sample application you started from for relevant updates. This will let you adjust your application if needed to keep up with upstream.

If you run into problems, you can temporarily roll back to a previous Zephyr microPlatform release as follows:

$ cd .repo/manifests
$ git checkout STARTING_MANIFEST_SHA
$ cd ../..
$ repo sync

However, this defeats the purpose of receiving continuous updates from Open Source Foundries.

Managing Out of Tree Patches¶

While an upstream first approach is recommended for development, situations come up when out-of-tree patches are necessary for a microPlatform project such as Zephyr. Repo has built-in tooling to handle this workflow. The repo start command informs Repo that development will take place in a given branch name for a project. Once Repo is aware there are development branches for a project, repo sync will take care of rebasing the patch(es).

# work starts at latest microPlatform release
# A fix is required in Zephyr, the patch was submitted upstream, but is
# is still awaiting review. In the meantime, a branch can be used with:
$ repo start github-pr-XXX zephyr
$ cd zephyr
# apply the patch(es) to zephyr
$ git commit -a -m "out-of-tree patch waiting for zephyr merge #12"
...
# A new update comes in for the microPlatform
$ repo sync
...
# If no merge conflicts are detected, everything is done. Otherwise
# you will have to drop into the zephyr directory and use Git to
# resolve the merge conflict.

Zephyr microPlatform Boards HOWTO¶

This page provides information on porting a board to the Zephyr microPlatform.

Warning

Porting a board necessarily means altering the Zephyr repository, which complicates the repo sync process used to receive updates.

See Zephyr microPlatform Workflows HOWTO for more details.

Start with the Zephyr porting guides, and the existing supported boards. In addition to architecture and basic board support, you’ll need a flash driver and working networking for MCUBoot and FOTA updates. Some useful starting points:

include/flash.h and the drivers/flash directory in the Zephyr source tree for flash drivers.
The Zephyr networking documentation

Some particular areas to be aware of when porting Zephyr microPlatform-based applications to a new board follow.

Flashing hacks in the Zephyr runner infrastructure: the zmp tool currently relies on some hacks (search for ZEPHYR_HACK_OVERRIDE_BIN) to flash the signed binary for chain-loading by MCUBoot. Currently, only Zephyr boards which use pyOCD and DfuSe (USB DFU with STMicroelectronics extensions via dfu-util) support this hack. You may need to adjust your runner implementation accordingly to enable zmp flash (see the directory zmp/zephyr/scripts/support/runner)
Device tree with flash partitions: your board will need a device tree defined, which includes flash partitions for MCUBoot itself (boot_partition), a partition your application runs in (slot0_partition), a partition to download firmware updates into (slot1_partitition; this must be the same size as slot0_partition), and a scratch partition for MCUBoot to use when swapping images between slots 0 and 1 (scratch_partition; this can be as small as a single sector, but be aware of extra wear on your flash). Currently, slot0_partition, slot1_partition, and scratch_partition must be contiguous on flash. The boot_partition must be chosen so that the chip reset vector will be loaded from there.

Each supported board has a device tree with a partition layout you can use while getting started.
A device tree overlay file: your application needs a device tree .overlay file instructing the Zephyr build system to use the flash partitions defined in the device tree when linking.

See the example overlay files in the boards subdirectory of each sample application, along with the build system files which use them, for reference.

Selecting slot0_partition within your DTS overlay will ensure that your application is linked appropriately:
```
/ {
        chosen {
                zephyr,code-partition = &slot0_partition;
        };
};
```
For additional information on this, see the documentation for CONFIG_FLASH_LOAD_OFFSET and CONFIG_FLASH_LOAD_SIZE. Note that these values are set automatically by Zephyr’s scripts/dts/extract_dts_includes.py script as a consequence of your DTS overlay file.
CONFIG_TEXT_SECTION_OFFSET: On ARM targets, this is the offset from CONFIG_FLASH_LOAD_OFFSET at which your application’s vector table is stored. This is required so zmp build can place an MCUBoot header in the space between the flash load offset and the beginning of your image.

If you’re unsure, 0x200 is a generally safe default value.

Lower values (such as 0x100) may be possible depending on your chip’s vector table alignment requirements. Smaller values waste less flash space.
To port MCUBoot to your board, you also need a Zephyr flash driver, ideally (though not necessarily) with CONFIG_FLASH_PAGE_LAYOUT support.

(MCUBoot’s build system will automatically pick up the device tree partitions you define in Zephyr, and zmp will be automatically be able to build MCUBoot for your board once it’s got Zephyr support.)

For additional background information on porting MCUBoot to your board, see the MCUBoot README-zephyr.rst file.

Reference Manuals¶

Linux microPlatform Reference Manual¶

The Open Source Foundries Linux microPlatform is an extensible software and hardware platform that makes it easier to develop, secure, and maintain Internet-connected Linux-based embedded devices.

The Linux microPlatform is based on OpenEmbedded / Yocto, and adds a select set of board support package layers to enable popular development boards.

Though the Linux kernel and software used for any on of the microPlatform builds may contain out-of-tree patches or features, a fundamental goal is to run as close to the tip, or latest software, as possible so that users of the Linux microPlatform can benefit from the latest changes.

The Linux microPlatform also provides reference applications as Docker containers to enable gateway functionality, such as IPv6/IPv4 routing and MQTT message brokering.

Building the Linux microPlatform¶

This is a guide for building the base Linux microPlatform from source for Raspberry Pi 3. Additional information specific to other targets is provided in Additional Linux microPlatform Targets.

This guide assumes the reader is familiar with basic concepts of OpenEmbedded. It is not meant to be an introduction to the OpenEmbedded / Yocto Project. If you’re just getting started, it’s strongly recommended to begin with the documentation provided in References.

Get Hardware¶

You will need a x86 computer to develop on; Linux is currently natively supported. On macOS and Windows, see Linux microPlatform Development Container for information on setting up a containerized Linux build environment.

You will also require at least 50GB of storage for a complete Linux microPlatform build.

Set Up Build Environment¶

On Debian-based Linux distributions, including Ubuntu, run:

$ sudo apt-get install coreutils gawk wget git-core diffstat unzip \
    texinfo gcc-multilib build-essential chrpath socat cpio \
    python python3 python3-pip python3-pexpect xz-utils \
    debianutils iputils-ping libsdl1.2-dev xterm \
    android-tools-fsutils repo whiptail

Note

If you are running Ubuntu 16.04, make sure to enable the universe repository by adding following line to your /etc/apt/sources.list:

deb http://archive.ubuntu.com/ubuntu/ xenial universe

On other Linux distributions, please check the Yocto Project Quick Start Guide for additional guidance.

Install the Linux microPlatform¶

The Linux microPlatform can be installed in any directory on your workstation, as long it provides enough disk space for the complete build. Installation uses the Repo tool to fetch a variety of Git repositories at known-good revisions, and keep them in sync as time goes on.

(If you’re new to Repo and want to know more, see Repo Primer for Zephyr microPlatform.)

Subscribers¶

The latest continuous release is available to Linux microPlatform subscribers from source.foundries.io. Install it as follows.

Configure Git to cache usernames and passwords you enter in memory for one hour:
```
git config --global credential.helper 'cache --timeout=3600'
```
Using a credential helper is necessary for repo sync to work unprompted later.
If you haven’t already, create a subscriber token on foundries.io/s/.
Make an installation directory for the Linux microPlatform, and change into its directory:
```
mkdir lmp && cd lmp
```
Install the latest release using repo:
```
repo init -u https://source.foundries.io/lmp-manifest
repo sync
```
When prompted by repo init, enter your subscriber token for your username and nothing for the password.

Public¶

The latest public release is available from the Open Source Foundries GitHub organization.

Make an installation directory for the Linux microPlatform, and change into its directory:
```
mkdir lmp && cd lmp
```

Install the latest release using repo:

repo init -u https://github.com/OpenSourceFoundries/lmp-manifest
repo sync

Build the lmp-gateway Image¶

Now that you’ve installed the Linux microPlatform, it’s time to build the Linux microPlatform gateway image.

The supported MACHINE target used by this guide is raspberrypi3-64. (For information on other hardware platforms, see Additional Linux microPlatform Targets.)

The default distribution (DISTRO) is automatically set to lmp, which is provided by the meta-osf layer (see Linux microPlatform OpenEmbedded / Yocto Layers for more details).

Set up your work environment using the setup-environment script:

MACHINE=raspberrypi3-64 source setup-environment [BUILDDIR]

If MACHINE is not provided, the script will list all possible machines found in every enabled OpenEmbedded / Yocto Project layer, and force one to be selected. BUILDDIR is optional; if it is not specified, the script will default to build-lmp.

To build the Linux microPlatform gateway image:

bitbake lmp-gateway-image

Note

Depending on the amount of RAM and number of processors and cores in your system, the speed of your Internet connection, and other factors, the first build could take several hours. Subsequent builds run much faster since some artifacts are cached.

At the end of the build, your build artifacts will be found under deploy/images/raspberrypi3-64. The artifact you will use to flash your board is lmp-gateway-image-raspberrypi3-64.rpi-sdimg.

Install the lmp-gateway Image¶

If you’re using a Raspberry Pi 3, you can use the same procedure outlined for prebuilt binaries in Install Linux microPlatform. See Additional Linux microPlatform Targets for additional information on other targets.

References¶

The following reference material on OpenEmbedded and Yocto is recommended for those new to either project.

Additional Linux microPlatform Targets¶

This section provides information on running the Linux microPlatform for other targets. It is provided on a best-effort basis.

Prebuilt Binaries¶

Several boards have reference builds provided by Open Source Foundries in the latest Linux microPlatform release, available at https://foundries.io/r/.

Please note that these builds are provided for reference in hopes they are useful; not all receive equal testing.

BeagleBone Black¶

Set MACHINE to beaglebone when setting up your work environment with the setup-environment script:

MACHINE=beaglebone source setup-environment [BUILDDIR]

At the end of the build, your build artifacts will be found under deploy/images/beaglebone. The artifact you will use to flash your microSD card is lmp-gateway-image-beaglebone.wic.gz.

To flash your microSD card, run:

gunzip -f lmp-gateway-image-beaglebone.wic.gz
sudo dd if=lmp-gateway-image-beaglebone.wic of=/dev/mmcblkX bs=4M

Where /dev/mmcblkX is your SD card device.

Please see https://elinux.org/Beagleboard:BeagleBoneBlack for additional board documentation.

HummingBoard 2¶

Set MACHINE to cubox-i when setting up your work environment with the setup-environment script:

MACHINE=cubox-i source setup-environment [BUILDDIR]

At the end of the build, your build artifacts will be found under deploy/images/cubox-i. The artifact you will use to flash your microSD card is lmp-gateway-image-cubox-i.wic.gz.

To flash your microSD card, run:

gunzip -f lmp-gateway-image-cubox-i.wic.gz
sudo dd if=lmp-gateway-image-cubox-i.wic of=/dev/mmcblkX bs=4M

Where /dev/mmcblkX is your SD card device.

Please see https://wiki.solid-run.com/doku.php?id=products:imx6:hummingboard for additional board documentation.

96Boards HiKey¶

Set MACHINE to hikey when setting up your work environment with the setup-environment script:

MACHINE=hikey source setup-environment [BUILDDIR]

At the end of the build, your build artifacts will be found under deploy/images/hikey.

To convert the rootfs to a fastboot-compatible format, run:

gunzip -f lmp-gateway-image-hikey.ext4.gz
ext2simg -v lmp-gateway-image-hikey.ext4 lmp-gateway-image-hikey.img

To flash your HiKey over micro-USB:

fastboot flash boot boot-hikey.uefi.img
fastboot flash system lmp-gateway-image-hikey.img

Please see https://github.com/96boards/documentation/tree/master/ConsumerEdition/HiKey for additional board documentation.

96Boards DragonBoard 410c¶

Set MACHINE to dragonboard-410c when setting up your work environment with the setup-environment script:

MACHINE=dragonboard-410c source setup-environment [BUILDDIR]

At the end of the build, your build artifacts will be found under deploy/images/dragonboard-410c.

To convert the rootfs to a fastboot-compatible format:

gunzip -f lmp-gateway-image-dragonboard-410c.ext4.gz
ext2simg -v lmp-gateway-image-dragonboard-410c.ext4 lmp-gateway-image-dragonboard-410c.img

To flash your DragonBoard 410c over micro-USB:

fastboot flash boot boot.img
fastboot flash rootfs lmp-gateway-image-dragonboard-410c.img

Please see https://github.com/96boards/documentation/tree/master/ConsumerEdition/DragonBoard-410c for additional board documentation.

Linux microPlatform Kernel¶

A common and unified Linux Kernel source tree is provided and used by Linux microPlatform.

The latest continuous release is available to Linux microPlatform subscribers at source.foundries.io/linux.git.

The Linux Kernel recipe can be found in the Meta-OSF layer, under the meta-osf/recipes-kernel/linux directory (linux-osf). You can find the common Linux distro config at meta-osf/recipes-kernel/linux/linux-osf/distro.cfg, which provides the base configs required by systemd, the Docker runtime, and drivers for additional WiFi / Bluetooth adapters.

Linux microPlatform bt-joiner Container¶

This page provides additional information on the bt-joiner Linux microPlatform container which is provided by Open Source Foundries. This container is used to provide IPv6 connectivity over Bluetooth Low Energy to Zephyr microPlatform devices in the system described in Set Up Basic LWM2M System.

Whitelist Setup for IoT Gateway¶

Follow these instructions to set up a 6LoWPAN Bluetooth device whitelist. This lets you configure your gateway device so that it only attempts to connect to a subset of the Bluetooth devices in its vicinity. This can be useful to avoid interfering with other gateways or unrelated devices.

Note

It’s helpful to power off any IoT devices in your area prior to starting.

Enable the whitelist feature¶

To enable the whitelist, simply enable the whitelist function by modifying the file bluetooth_6lowpand.conf in the gateway-ansible repository. You’ll want to set USE_WL to 1, and add a WL=IOT_DEVICE_MAC_ADDRESS line for each IoT device you wish to whitelist.

Then redeploy the container on your gateway device, e.g. by using the Ansible playbook provided in that repository.

How to Find Devices for the Whitelist¶

Now that the whitelist is enabled, you can find the beaconing devices by running the following command in the gateway’s console:

sudo hcitool lescan

While leaving this command running, power on the IoT devices you wish to add to the whitelist. You should see an additional line appear as each device is powered on.

The colon-separated list of hexadecimal numbers before each line containing XXX IPSP node is that device’s Bluetooth address. You can add an address as a WL entry in bluetooth_6lowpand.conf to whitelist the device.

For example, to whitelist a device with address D6:E7:D2:E8:6C:9F, add the following line to bluetooth_6lowpand.conf:

WL=D6:E7:D2:E8:6C:9F

Disable the whitelist feature¶

To turn off the whitelist feature, set USE_WL to 0 in bluetooth_6lowpand.conf, then redeploy the container.

Linux microPlatform Development Container¶

You can install a Docker container based on Ubuntu 16.04 which provides a Linux microPlatform build environment. This is the recommended work environment for building Linux microPlatform images on macOS and Windows. It can also be useful for reproducible builds.

Install Docker.
Pull the container image.

Subscribers first need to log in to the Open Source Foundries subscriber container registry on the system which will run the development container, then fetching it:
```
docker login hub.foundries.io --username=unused
docker pull hub.foundries.io/lmp-sdk
```
The username is currently ignored when logging in, but a value must be provided. When prompted for the password, enter your subscriber token. If docker pull fails, make sure docker login succeeds and retry.

Public releases can be fetched from Docker Hub:
```
docker pull opensourcefoundries/lmp-sdk
```

Run the container as the builder user.

Subscribers:

docker run -it -u builder --name lmp-sdk hub.foundries.io/lmp-sdk

Public:

docker run -it -u builder --name lmp-sdk opensourcefoundries/lmp-sdk

Set up Git inside the container:

git config --global user.name "Your Full Name"
git config --global user.email "your-email-address@example.com"

You can now follow instructions in Building the Linux microPlatform to build the Linux microPlatform inside the running container.

Linux microPlatform OpenEmbedded / Yocto Layers¶

The Linux microPlatform is composed of several OpenEmbedded and Yocto Project layers, including the core build system, distribution, images and BSPs.

Linux microPlatform Layers¶

Layer	Description
OpenEmbedded-Core (Base)	This is the main collaboration point when working on OpenEmbedded projects and is part of the core recipes. It is distro-less and contains only emulated machine support.
Meta-OpenEmbedded	This layer houses a collection of layers and recipes for the OE-core universe. Since the reduction in recipes to the core, meta-openembedded was created for everything else. There are currently approximately 650 recipes in this layer. It is used by the Linux microPlatform for additional utilities and network support.
Meta-Linaro (Toolchain)	This layer provides OP-TEE and the Linaro Toolchain, which is the default toolchain used by the Linux microPlatform (lmp) distribution.
Meta-Virtualization	This layer provides support for building Docker, LXC, Xen, KVM, Libvirt, and associated packages necessary for constructing OE-based virtualized / container solutions. It is used by the Linux microPlatform for Docker container runtime support.
Meta-OSF (Distro)	This layer provides the Linux microPlatform distribution configuration, unified Kernel and images.
Meta-RaspberryPi (BSP)	This is the board support layer for the Raspberry Pi boards.
Meta-Yocto (BSP)	This is the board support layer for the Yocto Project hardware references, such as BeagleBone Black.
Meta-96boards (BSP)	This layer is managed by Linaro and intended for boards that do not have their own board support layer repository. Currently used for HiKey / HiKey960 Consumer Edition board support.
Meta-Qcom (BSP)	This is the board support layer for Qualcomm boards. Currently supports DragonBoard 410c and DragonBoard 820c.
Meta-Freescale (BSP)	This is the board support layer for the Freescale platforms.
Meta-Freescale-3rdparty (BSP)	This is an additional board support layer for Freescale platforms (not officially supported by Meta-Freescale maintainers).

Linux microPlatform Meta-OSF Layer¶

The Meta-OSF layer provides the Linux microPlatform distribution configuration and a base set of recipes and configs, such as a unified Linux kernel and a gateway image.

The Linux microPlatform distribution configuration can be found at conf/distro/lmp.conf and conf/distro/include/lmp.inc.

The lmp-gateway-image recipe can be found at recipes-samples/images/lmp-gateway-image.bb. You can find the default set of packages used by the image via the CORE_IMAGE_BASE_INSTALL variable.

Repo Primer for Linux microPlatform¶

This section describes Repo and how the Linux microPlatform uses it. If you’re unfamiliar with Repo, it may make things clearer.

A Linux microPlatform build tree installation contains multiple Git repositories, which are managed by a manifest file in a Repo manifest repository.

The manifest repository’s name is lmp-manifest. It’s a Git repository, just like any of the source code repositories. In Building the Linux microPlatform, repo init is given the URL for the manifest repository.

The manifest repository contains a manifest file, named default.xml. This file describes the other Git repositories in the Linux microPlatform installation, and their metadata. During installation, repo sync is run after repo init. This clones the other repositories according to the contents of the manifest.

Roughly speaking, the manifest file contains:

remotes, which specify where Linux microPlatform repositories are hosted.
projects, which specify the Git repositories that make up the microPlatform, along with the remotes to fetch them from, and Git branches to check out.

Zephyr microPlatform Reference Manual¶

The Open Source Foundries Zephyr microPlatform is an extensible software and hardware platform that makes it easier to develop, secure, and maintain Internet-connected microcontroller-based embedded devices.

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

It significantly simplifies the process of setting up a development environment compared to the “vanilla” Zephyr distribution by providing:

A Repo manifest, which automates fetching and synchronization of known-good combinations of source trees and build toolchains.
A tool called zmp, which acts as an optional front-end to the Zephyr and MCUBoot build and flash systems, and turns common tasks requiring multiple steps in the vanilla distributions into one-line shell commands.
Reference applications which can be used in concert with the Linux microPlatform and cloud system containers provided by Open Source Foundries to create functional IOT systems to use as a basis for development.

Zephyr microPlatform zmp Tool¶

This page describes the zmp tool used for developing and flashing embedded applications with the Zephyr microPlatform. It assumes that the Zephyr microPlatform has successfully been installed using Repo as described in Install Zephyr microPlatform, but provides additional information on using zmp with other boards and in additional contexts.

After installing the Zephyr microPlatform repositories and build environment, the Zephyr and mcuboot build systems and other tools can be used directly. However, these interfaces can be hard to use when first developing applications. For this reason, the Zephyr microPlatform provides a helper script, named zmp, which provides a higher-level interface.

The zmp utility is installed into the root of the Zephyr microPlatform tree by repo sync. It accepts multiple commands useful during development; they are documented below. Run ./zmp -h from the Zephyr microPlatform installation directory for additional information.

Build an Application: `zmp build`¶

Warning

As described in Build an Application, mcuboot binaries and Zephyr microPlatform applications are built and signed with development keys which are not secret. While this makes development and testing more convenient, it is not suitable for production.

However, it’s not currently possible to generate mcuboot images that trust non-dev keys without editing the mcuboot source tree.

As such, the --signing-key and --signing-key-type arguments to zmp build are misleading, as the mcuboot image won’t trust the key used to sign the application. Don’t use these for now.

The top-level command is zmp build. By default, it takes a path to an application inside the Zephyr microPlatform installation directory, and builds a signed application image, as well as an mcuboot binary capable of loading that application image. (The default behavior can be changed through various options.)

To get help, run this from the Zephyr microPlatform root directory:

./zmp build -h

The zmp build command always builds out of tree; that is, build artifacts are never generated in the source code directories. By default, they are stored under outdir in the Zephyr microPlatform top-level directory.

Examples:

To build an application some-application available in the Zephyr microPlatform tree, targeting the BLE Nano 2:
```
./zmp build -b nrf52_blenano2 some-application
```
This generates artifacts under outdir like so:
```
outdir
└── some-application
    └── nrf52_blenano2
        ├── app
        └── mcuboot
```
The application build for nrf52_blenano2 is in outdir/some-application/nrf52_blenano2/app. The mcuboot build is in mcuboot, next to app.
To build the same application for another board, e.g. frdm_k64f, use the -b option:
```
./zmp build -b frdm_k64f some-application
```
The -b option can be used in any zmp build command to target other boards.

Running this after building for BLE Nano 2 as in the above example results in a parallel set of build artifacts, like so:
```
outdir
└── some-application
    ├── frdm_k64f
    │   ├── app
    │   └── mcuboot
    └── nrf52_blenano2
        ├── app
        └── mcuboot
```
It’s fine to build application sources in a subdirectory. For example, running:
```
./zmp build some-nested/application-name
```
will generate:
```
outdir
└── some-nested
    └── application-name
        └── nrf52_blenano2
            ├── app
            └── mcuboot
```
Note that the signed image in nrf52_blenano2/app is named application-name-nrf52_blenano2-signed.bin; i.e., just the base name of the application directory is used.
To build or incrementally compile the application image only, not updating the mcuboot image, use -o:
```
./zmp build -b nrf52_blenano2 -o app some-application
```

Similarly, to build or incrementally compile mcuboot only:

./zmp build -b nrf52_blenano2 -o mcuboot some-application

Configure an Application: `zmp configure`¶

The Zephyr RTOS uses a configuration system called Kconfig, which is borrowed from the Linux kernel. The zmp configure command lets you change the configuration database for an application build, using any of the Kconfig front-ends supported on your platform.

The top-level command is zmp configure.

This command can only be run after using zmp build to create the build directory, which contains the configuration database.

To get help, run this from the Zephyr microPlatform root directory:

./zmp configure -h

Example uses:

To change the application configuration (not the mcuboot configuration) for some-application for the default board:
```
./zmp configure -o app some-application
```
To change the mcuboot (not application) configuration for another board, frdm_k64f:
```
./zmp configure -o mcuboot -b frdm_k64f some-application
```

If you don’t specify -o, then zmp configure will sequentially run the application and mcuboot configuration interfaces, in that order.

Note that zmp configure accepts many of the same options as zmp build.

For more information on Kconfig in Zephyr, see Configuration Options Reference Guide.

Flash an Application to a Device: `zmp flash`¶

After building an application and mcuboot binary with zmp build, the zmp flash command can be used to flash it to a board, usually via USB.

The zmp flash command relies on Zephyr’s build system to choose a flashing utility, and run it with the correct arguments to flash mcuboot and the application binary to an attached board.

If you experience errors using this command, make sure you can flash your board using Zephyr’s CMake build system’s flash target as described in its Zephyr documentation [1].

To get help, run this from the Zephyr microPlatform root directory:

./zmp flash -h

Basic uses:

To flash the artifacts for some-application to the default board:
```
./zmp flash some-application
```

To flash to a different board, frdm_k64f:

./zmp flash -b frdm_k64f some-application

Footnotes

[1]

If your board’s Zephyr support does not include a build system flash target, zmp flash will not work either, but adding flash support to your board’s build system configuration doesn’t necessarily enable zmp flash.

This is because zmp flash currently relies on some additional modifications to the Zephyr CMake build system’s flash target, which allow overridding the target binary to flash a signed blob which MCUBoot can chain-load. These modifications are currently only supported for the dfu-util and pyOCD flasher backends. This is a temporary measure which is being addressed in the Zephyr upstream repository.

Repo Primer for Zephyr microPlatform¶

This section describes Repo and how the Zephyr microPlatform uses it. If you’re unfamiliar with Repo, it may make things clearer.

A Zephyr microPlatform installation contains multiple Git repositories, which are managed by a manifest file in a Repo manifest repository.

The manifest repository’s name is zmp-manifest. It’s a Git repository, just like any of the source code repositories. When installing the Zephyr microPlatform, repo init is given the URL for the manifest repository (either a subscriber or public version).

The manifest repository contains a manifest file, named default.xml. This file describes the other Git repositories in the Zephyr microPlatform installation, and their metadata. During installation, repo sync is run after repo init. This clones the other repositories according to the contents of the manifest.

Roughly speaking, the manifest file contains:

remotes, which specify where Zephyr microPlatform repositories are hosted.
projects, which specify the Git repositories that make up the microPlatform, along with the remotes to fetch them from, and Git branches to check out.

The following figure ties together the various pieces.

Other Pages¶

This is a collection of additional, miscellaneous documentation that currently doesn’t fit neatly into one of the other categories.

hawkBit and MQTT Demonstration System¶

Warning

Technology demonstration system only.

While the system described below works as documented, it has important limitations that imply it should not be used as-is in production. It may also change incompatibly in the future.

Overview¶

This page documents how to set up and use a demonstration system containing IoT devices and an IoT gateway, which can publish sensor data from devices to the cloud and perform firmware over the air (FOTA) updates of the device firmware.

A block diagram of this system is shown here. One or more IoT devices can connect to the network through the same gateway.

Device Management with hawkBit System Diagram

System block diagram

The system contains Zephyr-based IoT devices, an IoT gateway, a device management and OTA system running in a container, and integration with a cloud-based MQTT service.

Using this demonstration system, you can:

See live temperature readings from your devices appear in the web console provided by a cloud MQTT broker, CloudMQTT.
Upload a cryptographically signed firmware image to a device management server, hawkBit.
Use hawkBit to install a firmware image onto an IoT device via over the air update. The device will boot the update after checking its cryptographic signature.

Limitations¶

The system as implemented has some important limitations, including:

It does not secure its network communications. The current implementation has the IoT device connecting directly to the hawkBit and MQTT servers. Securing these communications from end to end generally requires use of certificate-based TLS, which imposes infeasible resource requirements on current IoT board targets.
The hawkBit server container is demonstration-grade only, and has security issues such as the use of default administrative passwords.
The IoT device-side hawkBit implementation does not implement the complete hawkBit state machine. Features such as cancelling requested actions are not supported.

These implementation details imply that the current system should not be deployed as-is in production.

Prepare Environment¶

This system has the same dependencies as the one used in the microPlatforms tutorial. We also assume you have installed the microPlatforms as described in the tutorial.

Prepare the System¶

Set up CloudMQTT¶

Create a CloudMQTT account if you don’t have one already, and sign in. After you’ve signed in, create a new CloudMQTT instance to use with this system. The free instance plan is enough to run this demo, as shown below:

CloudMQTT instance creation user interface

Create an instance for use with this sytem.

Then click on the “Details” button next to the new instance in your control panel. Record the following information about the instance:

CLOUDMQTT_SERVER: the URL of the server
CLOUDMQTT_USER: the auto-generated username
CLOUDMQTT_PASSWORD: the auto-generated password
CLOUDMQTT_PORT: the port to connect to on the server

The information is in your instance’s details page as shown:

Instance information to collect.

Set Up the IoT Gateway¶

You’ll now use Ansible to set up your IoT gateway to act as a network proxy for your IoT device to publish sensor data to CloudMQTT, and fetch updates from hawkBit.

Ensure you have an SSH key on your workstation. If you’ve never done this before, the GitHub guide to SSH keys has useful instructions.
Copy your SSH key to the gateway in order to control it with Ansible:
```
ssh-copy-id osf@raspberrypi3-64.local
```
Use the password for the osf account you set earlier when installing the Linux microPlatform (the default is osf, but we recommend that you change it).
Clone gateway-ansible, a repository of Ansible playbooks, helper scripts and files, and Dockerfiles, onto your workstation.

Subscribers:

For passwordless authentication, create a file named .netrc (note the leading .) in your home directory, readable only by your user, with the following contents:
```
machine source.foundries.io
login <your-subscriber-token>
```
If you don’t createa .netrc, enter your subscriber token when prompted for a username, and leave the password blank.

Now clone the gateway-ansible repository:
```
git clone https://source.foundries.io/gateway-ansible
```
Public:
```
git clone https://github.com/OpenSourceFoundries/gateway-ansible
```

From the gateway-ansible repository, deploy the gateway containers using the CloudMQTT information you recorded earlier.

Subscribers:
```
CLOUDMQTT_HOST=XXX CLOUDMQTT_PORT=XXX CLOUDMQTT_USER=XXX CLOUDMQTT_PASSWD=XXX \
    GW_HOSTNAME=raspberrypi3-64.local REGISTRY_PASSWD=<subscriber-token> ./iot-gateway.sh
```
Setting REGISTRY_PASSWD to your subscriber token is necessary so your gateway device can log in to the container registry.

Public:
```
CLOUDMQTT_HOST=XXX CLOUDMQTT_PORT=XXX CLOUDMQTT_USER=XXX CLOUDMQTT_PASSWD=XXX \
    REGISTRY=hub.docker.com REGISTRY_USER=docker REGISTRY_PASSWD=docker \
    GW_HOSTNAME=raspberrypi3-64.local ./iot-gateway.sh
```
These instructions assume use of Raspberry Pi 3 on a local network supporting Zeroconf. Adjust GW_HOSTNAME as needed if your environment is different.

They also assume iot-gateway.sh is run on the same machine running the hawkBit server. Set MGMT_SERVER to the IP address of the machine running the hawkBit container if your environment is different.

Your gateway device is now ready for use.

Set up hawkBit¶

Now run a demonstration-grade hawkBit server on your workstation (not the gateway).

Warning

This hawkBit container contains an official hawkbit-update-server artifact build from Maven; however, it is for demonstration purposes only, and should not be deployed in production as-is.

Among other potential issues, the server has an insecure default administrative username/password pair. For more information, see the official documentation on building and running hawkBit and hawkBit security.

Subscribers:

First, log in to the Open Source Foundries subscriber container registry on your worksation (not the gateway device):

docker login hub.foundries.io --username=unused

The username is currently ignored when logging in, but a value must be provided. When prompted for the password, enter your subscriber token.

Now run hawkBit on your workstation:

docker run -dit --name hawkbit -p 8080:8080 hub.foundries.io/hawkbit-update-server:latest

If this command fails, ensure docker login succeeds and retry.

Public: to run the latest public release on Docker Hub:

docker run -dit --name hawkbit -p 8080:8080 opensourcefoundries/hawkbit-update-server:latest

This container can take approximately 40 seconds for the application to start for the first time.

After running the hawkBit container, visit http://localhost:8080/UI to load the administrative interface, and log in with the default username and password (admin/admin). Your browser window should look like this:

Your hawkBit container is now ready for use.

Note

For convenience, you may want to adjust the “Polling Time” in the “System Config” area. This will instruct your IoT devices to check for updates more frequently. The default is 5 minutes; the minimum value is 30 seconds.

Set Up the IoT Device(s)¶

Using BLE Nano 2, build and flash the demonstration application for this system:

./zmp build -b nrf52_blenano2 zephyr-fota-samples/dm-hawkbit-mqtt
./zmp flash -b nrf52_blenano2 zephyr-fota-samples/dm-hawkbit-mqtt

Flashing this board requires pyOCD. To install this dependency, run:

pip install --user pyOCD

If you don’t have pip installed, see the pip Installation documentation. On Linux platforms, you also need to install the following udev rules as root, then unplug and plug back in any boards you may have connected:

echo 'ATTR{idProduct}=="0204", ATTR{idVendor}=="0d28", MODE="0666", GROUP="plugdev"' > /etc/udev/rules.d/50-cmsis-dap.rules

If you don’t have a BLE Nano 2, information for other boards is provided on a best-effort basis below in Appendix: Additional IOT devices.

Use the System¶

Now that your system is fully set up, it’s time to check that sensor data are being sent to the cloud, and do a FOTA update.

Cloud Sensor Updates¶

Choose the instance you created for this demo from your CloudMQTT instances list, then click the “Websocket UI” button to get a live view of data being sent to the server. You should see new data appear every few seconds; it will look like this:

MQTT messages from BLE Nano 2 appearing in CloudMQTT Websocket UI.

You can now connect other subscribers to this CloudMQTT instance, which can act on the data.

FOTA Updates¶

Now let’s perform a FOTA update. In the hawkBit server UI, you should see the 96Boards device show up in the “Targets” pane. It will look like this:

BLE Nano 2 registered with hawkBit.

It’s time to upload a firmware binary to the server, and update it using this UI. We’ve provided a Python script to make this easier, which works with either Python 2 or 3.

Run it from the Zephyr microPlatform installation directory:

python zephyr-fota-samples/dm-hawkbit-mqtt/scripts/hawkbit.py \
                  -d 'BLE Nano 2 Update' \
                  -f outdir/zephyr-fota-samples/dm-hawkbit-mqtt/nrf52_blenano2/app/zephyr/dm-hawkbit-mqtt-nrf52_blenano2-signed.bin \
                  -sv "1.0" -p "OSF" -n "nrf52_blenano2 update" -t os

Above, 1.0 is an arbitrary version number. If hawkBit is running on a different machine, use the -ds and -sm options. For more help on using this script, run:

python zephyr-fota-samples/dm-hawkbit-mqtt/scripts/hawkbit.py -h

You will see an update in the hawkBit UI for the new image:

Distribution Set representing a signed firmware binary.

You’ll now update the device. Before doing so, you can connect to its serial console via USB at 115200 baud to see log messages during the upgrade (which should be at /dev/ttyACM0 or so on Linux systems).

Click on the distribution you uploaded, and drag it over the line in “Targets” for your IoT Device.
You’ll next need to confirm the action. Click a button towards the bottom of your screen labeled “You Have Actions”. This should now have a “1” at its top right, since you’ve assigned the distribution to your IoT device:

Click this button.
A screen will appear. Select “Save Assign” on this screen:

Choose “Save Assign”.

Your IoT devices will poll the hawkBit server periodically and will fetch the update the next time they poll.

Note

By default, devices wait five minutes between polls. If you don’t want to wait, just power cycle the IoT device; the dm-hawkbit-mqttt application checks for updates shortly after booting.

While hawkBit is waiting for the device to download and install the update, a yellow circle will appear next to it in the targets list:

Waiting for BLE Nano 2 to update.

If you’re connected to the device’s serial console, look for output like this while the update is being downloaded:

[0730950] [fota/hawkbit] [INF] hawkbit_ddi_poll: Valid action ID 1 found, proceeding with the update
[0730960] [fota/hawkbit] [INF] hawkbit_report_dep_fbk: Reporting deployment feedback success (proceeding) for action 1
[0730970] [fota/hawkbit] [DBG] hawkbit_report_dep_fbk: JSON response: {"id":"1","status":{"execution":"proceeding","result":{"finished":"success"}}}
[0730980] [fota/hawkbit] [DBG] hawkbit_query: [POST] HOST:gitci.com:8080 URL:/DEFAULT/controller/v1/nrf52_blenano2-1ef8e685/deploymentBase/1/feedback
[0731300] [fota/hawkbit] [DBG] hawkbit_query: Hawkbit query completed
[0731410] [fota/hawkbit] [INF] hawkbit_install_update: Starting the download and flash process
[0732660] [fota/hawkbit] [DBG] install_update_cb: 1%
[0733360] [fota/hawkbit] [DBG] install_update_cb: 2%
[0734260] [fota/hawkbit] [DBG] install_update_cb: 3%

[... etc.]

Finally, when the update is installed, the device will reset and MCUBoot will load the new image, which will initialize itself:

[MCUBOOT] [INF] main: Starting bootloader
[MCUBOOT] [INF] boot_status_source: Image 0: magic=good, copy_done=0xff, image_ok=0x1
[MCUBOOT] [INF] boot_status_source: Scratch: magic=unset, copy_done=0x2f, image_ok=0xff
[MCUBOOT] [INF] boot_status_source: Boot source: slot 0
[MCUBOOT] [INF] boot_swap_type: Swap type: test
[MCUBOOT] [INF] main: Bootloader chainload address offset: 0x8000
[MCUBOOT] [INF] main: Jumping to the first image slot
***** BOOTING ZEPHYR OS v1.9.99 - BUILD: Nov  8 2017 21:33:01 *****
Setting Bluetooth MAC
[0000000] [fota/main] [INF] main: Linaro FOTA example application
[0000010] [fota/main] [INF] main: Device: nrf52_blenano2, Serial: 1ef8e685
starting test - Running Built in Self Test (BIST)
Initializing Hawkbit backend
[0000020] [fota/hawkbit] [INF] hawkbit_start: ACID: current -1, update 1
[0000030] [fota/hawkbit] [INF] hawkbit_start: Current boot status ff
[0000040] [fota/hawkbit] [INF] hawkbit_start: Updated boot status to 1
[0000150] [fota/hawkbit] [DBG] hawkbit_start: Erased flash bank at offset 3c000
[0000260] [fota/hawkbit] [INF] hawkbit_start: ACID updated, current 1, update 1
[0000260] [fota/hawkbit] [INF] hawkbit_service: Starting FOTA Service Thread
PASS - hawkbit_init.

During its next poll, the IoT device will inform hawkBit that it has successfully booted:

[0031260] [fota/hawkbit] [DBG] hawkbit_ddi_poll: artifact address: /DEFAULT/controller/v1/nrf52_blenano2-1ef8e685/softwaremodules/1/artifacts/dm-hawkbit-mqtt-nrf52_blenano2-signed.bin
[0031270] [fota/hawkbit] [DBG] hawkbit_ddi_poll: artifact file size: 212992
[0031280] [fota/hawkbit] [INF] hawkbit_report_dep_fbk: Reporting deployment feedback success (closed) for action 1
[0031290] [fota/hawkbit] [DBG] hawkbit_report_dep_fbk: JSON response: {"id":"1","status":{"execution":"closed","result":{"finished":"success"}}}
[0031300] [fota/hawkbit] [DBG] hawkbit_query: [POST] HOST:gitci.com:8080 URL:/DEFAULT/controller/v1/nrf52_blenano2-1ef8e685/deploymentBase/1/feedback
[0031620] [fota/hawkbit] [DBG] hawkbit_query: Hawkbit query completed

At this point, the yellow circle will turn into a green check box:

BLE Nano 2 successfully updated.

Congratulations! You’ve just done your first FOTA update using this system.

Reporting Issues¶

Please report any issues to the Open Source Foundries FreshDesk.

Appendix: Additional IOT devices¶

FRDM-K64F¶

Building for FRDM-K64F requires some configuration information which depends on your local network:

An IP address to use for the IoT gateway
Whether the board should use DHCP, or a static IP address

This information must be written to the file zephyr-fota-samples/dm-hawkbit-mqtt/boards/frdm_k64f-local.conf in the Zephyr microPlatform installation directory.

To use DHCP, with gateway IP address A.B.C.D, create the file with the following contents.

CONFIG_NET_DHCPV4=y
CONFIG_NET_APP_PEER_IPV4_ADDR="A.B.C.D"

To use a static IP address X.Y.Z.W for the FRDM-K64F instead, use this.

CONFIG_NET_APP_MY_IPV4_ADDR="X.Y.Z.W"
CONFIG_NET_APP_PEER_IPV4_ADDR="A.B.C.D"

Now you can build the binaries. From the Zephyr microPlatform installation directory:

./zmp build -b frdm_k64f zephyr-fota-samples/dm-hawkbit-mqtt

Flashing this board requires pyOCD. To install this dependency, run:

pip install --user pyOCD

If you don’t have pip installed, see the pip Installation documentation. On Linux platforms, you also need to install the following udev rules as root, then unplug and plug back in any boards you may have connected:

echo 'ATTR{idProduct}=="0204", ATTR{idVendor}=="0d28", MODE="0666", GROUP="plugdev"' > /etc/udev/rules.d/50-cmsis-dap.rules

To flash the binaries, plug the K64F into your system via the USB connector labeled “SDA USB”. Then, from the Zephyr microPlatform installation directory:

./zmp flash -b frdm_k64f zephyr-fota-samples/dm-hawkbit-mqtt

96Boards Nitrogen¶

Like FRDM-K64F, this board also requires pyOCD to flash.

To build the binaries, run this from the Zephyr microPlatform installation directory:

./zmp build -b 96b_nitrogen zephyr-fota-samples/dm-hawkbit-mqtt

To flash the board:

./zmp flash -b 96b_nitrogen zephyr-fota-samples/dm-hawkbit-mqtt

Appendix: hawkBit References¶

This section contains additional reference material regarding hawkBit.

Upstream Github: https://github.com/eclipse/hawkbit
Data model: https://github.com/eclipse/hawkbit/wiki/Data-model
Open Source Foundries Docker container: https://github.com/OpenSourceFoundries/core-containers
Open Source Foundries Docker Hub: https://hub.docker.com/r/opensourcefoundries/hawkbit-update-server/