hawkBit FOTA and MQTT Demonstration System

Todo

add binary install instructions for all boards

Todo

add autogenerated flash layout for all boards

Warning

Technology demonstration system only.

While the system described below works as documented, it is unstable, and its behavior may change incompatibly in the future. It is also not supported.

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

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.

Get the Hardware

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

We currently recommend:

Source for other boards is provided on a best-effort basis.

Prepare the System

This is broken down into the following steps.

1. Set up hawkBit

Required Equipment: workstation which supports Docker.

Run a demonstration-grade hawkBit server:

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

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.

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:

hawkBit Administrator Interface

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.

Your hawkBit container is now ready for use.

2. Set up CloudMQTT

Required Equipment: workstation computer.

First, create a CloudMQTT account. The free CloudMQTT plan is enough to run this demo.

After logging in to your account, go to your CloudMQTT Control Panel, and create a new instance. 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_PORT: the port to connect to on the server
  • CLOUDMQTT_USER: the auto-generated username
  • CLOUDMQTT_PASSWORD: the auto-generated password

3. Install the Linux microPlatform

Required Equipment: IoT gateway and workstation to flash the board.

Follow the Linux microPlatform Getting Started to set up a 96Boards HiKey gateway for container-based application deployment.

If you don’t have a HiKey, the Getting Started guide contains information for other boards, provided on a best-effort basis.

4. Set Up the IoT Gateway

Required Equipment: IoT gateway and workstation to run Ansible.

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.

  • Follow the Basic IoT Gateway Getting Started guide to log into the Basic IoT Gateway console and change the password for the osf user. The default password is osf.

  • Connect your IoT gateway to the network.

    You can connect a HiKey to a local WiFi network[1] from its serial console as follows:

    sudo nmcli device wifi connect <NetworkSSID> password <NetworkPassword>

    After connecting to the network, record the IP address of your gateway, GATEWAY_IP_ADDRESS, which you can obtain when using WiFi with:

    ip addr show wlan0 | grep -o 'inet [.0-9]*'

    (If you’re using Ethernet, ip addr show will show all IP addresses on the system.)

  • If you don’t already have one, you now need to create 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. Do this with ssh-copy-id:

    ssh-copy-id osf@GATEWAY_IP_ADDRESS

    Use the new password for the linaro account you set earlier.

  • Install Ansible, which will let you install and control containers on your IoT gateway via SSH from your workstation.

  • Clone the gateway-ansible repository, which contains an Ansible playbook to set up the gateway for this system:

    git clone https://github.com/OpenSourceFoundries/gateway-ansible

  • From the gateway-ansible repository, deploy the gateway containers using the gateway’s IP address and CloudMQTT information you recorded earlier:

    ansible-playbook -e "mqttuser=CLOUDMQTT_USER mqttpass=CLOUDMQTT_PASSWORD \
                     mqtthost=CLOUDMQTT_SERVER mqttport=CLOUDMQTT_PORT \
                     gitci=WORKSTATION_IP_ADDRESS tag=latest" \
                 -i GATEWAY_IP_ADDRESS, -u linaro iot-gateway.yml \
                 --tags cloud

    WORKSTATION_IP_ADDRESS in the above command line is the IP address of the system which is running the hawkBit server you set up earlier. The comma after GATEWAY_IP_ADDRESS is mandatory.

5. Install the Zephyr microPlatform

Required Equipment: workstation to install the Zephyr microPlatform development environment, and IoT device to test installation.

Follow the installation steps in the Zephyr microPlatform Getting Started guide.

6. Set Up the IoT Device(s)

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

If you’re using 96Boards Nitrogen, build and flash the demonstration application:

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

Flashing this board requires pyOCD. To install:

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 Nitrogen, information for other boards is provided on a best-effort basis in 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

From your CloudMQTT Control Panel, load your instance’s Details page and 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:

../_images/cloudmqtt-websocket-ui.png

MQTT messages from 96Boards Nitrogen 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:

../_images/96b-target.png

96Boards Nitrogen registered with hawkBit.

It’s time to upload a firmware binary to the server, and update it using this UI. To make uploading the binaries to the demonstration hawkBit server easier, download this Python script to your Zephyr microPlatform installation directory:

https://raw.githubusercontent.com/linaro-technologies/hawkbit/master/hawkbit.py

Todo

hawkbit.py should be a versioned part of the release

From the Zephyr microPlatform installation directory:

python /path/to/hawkbit.py \
                  -ds 'http://localhost:8080/rest/v1/distributionsets' \
                  -sm 'http://localhost:8080/rest/v1/softwaremodules' \
                  -d 'Nitrogen End-to-end IoT system' \
                  -f outdir/zephyr-fota-samples/dm-hawkbit-mqtt/96b_nitrogen/app/dm-hawkbit-mqtt-96b_nitrogen-signed.bin \
                  -sv "1.0" -p "Linaro" -n "Nitrogen E2E preview" -t os

Above, 1.0 is an arbitrary version number.

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

../_images/distribution.png

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 Nitrogen:

    ../_images/you-have-actions.png

    Click this button.

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

    ../_images/action-details.png

    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 and are using 96Boards Nitrogen, you can press the “RST” button on the board to reset it; it will check 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:

../_images/96b-nitrogen-waiting.png

Waiting for 96Boards Nitrogen to update.

When the device informs hawkBit that the download has been successfully installed, this will turn into a green check box:

../_images/96b-nitrogen-ok.png

96Boards Nitrogen successfully updated.

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

[0031200] [fota/hawkbit] [INF] hawkbit_report_update_status: Reporting action ID feedback: success
[0031210] [fota/hawkbit] [DBG] hawkbit_query:

POST /DEFAULT/controller/v1/96b_nitrogen-4c1906d0/deploymentBase/1/feedback HTTP/1.1
Host: gitci.com:8080
Content-Type: application/json
Content-Length: 78
Connection: close

{"id":"1","status":{"result":{"finished":"success"},"execution":"proceeding"}}
[0031570] [fota/tcp] [DBG] tcp_received_cb: FIN received, closing network context
[0031580] [fota/hawkbit] [DBG] hawkbit_query: Hawkbit query completed
[0031690] [fota/hawkbit] [INF] hawkbit_install_update: Starting the download and flash process
[0032990] [fota/hawkbit] [DBG] hawkbit_download_cb: 1%
[0033740] [fota/hawkbit] [DBG] hawkbit_download_cb: 2%
[0034440] [fota/hawkbit] [DBG] hawkbit_download_cb: 3%
[0035290] [fota/hawkbit] [DBG] hawkbit_download_cb: 4%
[...]
[0627620] [fota/hawkbit] [DBG] hawkbit_download_cb: 98%
[0628470] [fota/hawkbit] [DBG] hawkbit_download_cb: 99%
[0629060] [fota/hawkbit] [INF] hawkbit_install_update: Download: downloaded bytes 212992
[0629070] [fota/hawkbit] [INF] hawkbit_ddi_poll: Triggering OTA update.
[0629180] [fota/hawkbit] [INF] hawkbit_ddi_poll: Image id 4 flashed successfuly, rebooting now
[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=0x23, 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] [WRN] zephyr_flash_area_warn_on_open: area 1 has 1 users
[MCUBOOT] [INF] main: Jumping to the first image slot
***** BOOTING ZEPHYR OS v1.8.99 - BUILD: Aug  3 2017 13:28:24 *****
[0000000] [fota/main] [INF] main: Linaro FOTA example application

[Startup output omitted]

{"id":"1","status":{"result":{"finished":"success"},"execution":"closed"}}

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

Known Issues

Issues and observations are logged within Linaro’s Bugzilla issue tracker.

Footnotes

[1]You can also use a USB Ethernet dongle.