Appendix to hawkBit FOTA and MQTT Demonstration System

Warning

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

This document contains additional information related to the hawkBit FOTA and MQTT Demonstration System.

Additional IoT Devices

96Boards Carbon

In order to use the 96Boards Carbon with this demonstration system, you’ll first need to set up a secondary chip on the board that provides Bluetooth functionality.

There are two chips on the Carbon that need firmware, an STM32 and an nRF51. The STM32 runs the bootloader and main application. The nRF51 is the secondary chip which needs to be flashed first to provide Bluetooth to the STM32, which doesn’t support it on its own.

Build the application for the secondary chip from the Zephyr microPlatform installation directory:

./genesis build -b 96b_carbon_nrf51 -c prj_96b_carbon_nrf51.conf \
                --skip-signature zephyr/samples/bluetooth/hci_spi/

This creates a firmware binary for the nRF51 at the following location:

outdir/zephyr/samples/bluetooth/hci_spi/96b_carbon_nrf51/app/zephyr.elf

Flashing the nRF51 device requires an external SWD flashing tool, such as the Black Magic Debug Probe or Segger JLink.

Before flashing this file, first put your Carbon in DFU mode by unplugging it, then plugging it back in with the BOOT0 button pressed. This ensures the STM32 firmware does not interfere with the nRF51. Then follow the Zephyr 96b_carbon_nrf51 flashing instructions to flash the binary to the nRF51.

Now run this from the Zephyr microPlatform installation directory to build the main application:

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

You’ll need to install dfu-util to flash this binary. A recent version of dfu-util is required; depending on your host operating system, you may need to build this from source.

• dfu-util URL: http://dfu-util.sourceforge.net/
• Git Repository: git://git.code.sf.net/p/dfu-util/dfu-util

To flash the STM32, first put your Carbon into DFU mode again. Then, from the Zephyr microPlatform installation directory, run:

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

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:

./genesis build -b frdm_k64f 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

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

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

Additional hawkBit Information

This section contains additional information for more complex use cases or further development.

• Upstream Github: https://github.com/eclipse/hawkbit
• Data model: https://github.com/eclipse/hawkbit/wiki/Data-model
• Docker container: https://github.com/linaro-technologies/extra-containers/tree/master/hawkbit-update-server
• Docker Hub: https://hub.docker.com/r/linarotechnologies/hawkbit-update-server

Hawkbit Restrictions

Target can only install a distribution set.

Hawkbit’s default configuration for OS/Firmware forces only one Software Module per Distribution Set. The software module can contain several artifacts, as long they don’t contain the same file name.

Rest API

The authentication header is a simply HTTP BA implementation. To use the protected APIs, first generate your authentication credentials:

echo -n "admin:admin" | base64

Then add your credentials as part of HTTP header:

curl ... -H 'Authorization: Basic YWRtaW46YWRtaW4='

Rest Commands:

Targets:

• Reference: http://sp.apps.bosch-iot-cloud.com/documentation/rest-api/targets-api-guide.html

• List all targets:

  curl 'http://your-hawkbit-server.example.com:8080/rest/v1/targets' -s -H 'Authorization: Basic YWRtaW46YWRtaW4=' | jq .
  

• Create a new target (security token generated by the server):

  curl 'http://your-hawkbit-server.example.com:8080/rest/v1/targets' -i -H 'Authorization: Basic YWRtaW46YWRtaW4=' -H 'Content-Type: application/json' -X POST -d '[ {
  "controllerId" : "nitrogen123",
  "name" : "nitrogen123",
  "description" : "Nitrogen Description"
  } ]'
  

• Create a new target specifying a custom security token:

  curl 'http://your-hawkbit-server.example.com:8080/rest/v1/targets' -i -H 'Authorization: Basic YWRtaW46YWRtaW4=' -H 'Content-Type: application/json' -X POST -d '[ {
  "controllerId" : "nitrogen123",
  "name" : "nitrogen123",
  "description" : "Nitrogen Description",
  "securityToken" : "2345678DGGDGFTDzztgf"
  } ]'
  

• Delete a target:

  curl 'http://your-hawkbit-server.example.com:8080/rest/v1/targets/nitrogen123' -i -H 'Authorization: Basic YWRtaW46YWRtaW4=' -X DELETE
  

• Retrieve details from a single target::

  curl 'http://your-hawkbit-server.example.com:8080/rest/v1/targets/nitrogen123' -s -H 'Authorization: Basic YWRtaW46YWRtaW4=' | jq .
  

• Assign a distribution set:

  curl 'http://your-hawkbit-server.example.com:8080/rest/v1/targets/nitrogen123/assignedDS' -i -H 'Authorization: Basic YWRtaW46YWRtaW4=' -H 'Content-Type: application/json' -X POST -d '{
  "forcetime" : 1472465267347,
  "id" : 1,
  "type" : "timeforced"
  }'
  

• Retrieve assigned distribution set:

  curl 'http://your-hawkbit-server.example.com:8080/rest/v1/targets/nitrogen123/assignedDS' -s -H 'Authorization: Basic YWRtaW46YWRtaW4=' | jq .
  

Distribution Sets:

• Reference: http://sp.apps.bosch-iot-cloud.com/documentation/rest-api/distributionsets-api-guide.html

• List all distribution sets:

  curl 'http://your-hawkbit-server.example.com:8080/rest/v1/distributionsets' -s -H 'Authorization: Basic YWRtaW46YWRtaW4=' | jq .
  

• Create a new distribution set:

  curl 'http://your-hawkbit-server.example.com:8080/rest/v1/distributionsets' -i -H 'Authorization: Basic YWRtaW46YWRtaW4=' -H 'Content-Type: application/json' -X POST -d '[ {
  "name" : "Zephyr 17.01",
  "description" : "Zephyr 17.01 Build",
  "version" : "1.5",
  "requiredMigrationStep" : false,
  "type" : "os"
  } ]'
  

• Delete a distribution set:

  curl 'http://your-hawkbit-server.example.com:8080/rest/v1/distributionsets/1' -i -H 'Authorization: Basic YWRtaW46YWRtaW4=' -X DELETE
  

• Retrieve assigned software modules:

  curl 'http://your-hawkbit-server.example.com:8080/rest/v1/distributionsets/1/assignedSM' -s -H 'Authorization: Basic YWRtaW46YWRtaW4=' | jq .
  

• Assign a software module:

  curl 'http://your-hawkbit-server.example.com:8080/rest/v1/distributionsets/1/assignedSM' -i -H 'Authorization: Basic YWRtaW46YWRtaW4=' -H 'Content-Type: application/json' -X POST -d '[ { "id" : 1 } ]'
  

• Retrieve assigned targets to a distribution set:

  curl 'http://your-hawkbit-server.example.com:8080/rest/v1/distributionsets/1/assignedTargets' -s -H 'Authorization: Basic YWRtaW46YWRtaW4=' | jq .
  

• Assign targets to a distribution set:

  curl 'http://your-hawkbit-server.example.com:8080/rest/v1/distributionsets/1/assignedTargets' -i -H 'Authorization: Basic YWRtaW46YWRtaW4=' -H 'Content-Type: application/json' -X POST -d '[
  { "id" : 1 },
  { "id" : 2 },
  { "id" : 3 }
  ]'
  

Software Modules:

• Reference: http://sp.apps.bosch-iot-cloud.com/documentation/rest-api/softwaremodules-api-guide.html

• List all software modules:

  curl 'http://your-hawkbit-server.example.com:8080/rest/v1/softwaremodules' -s -H 'Authorization: Basic YWRtaW46YWRtaW4=' | jq .
  

• Create a new software module:

  curl 'http://your-hawkbit-server.example.com:8080/rest/v1/softwaremodules' -i -H 'Authorization: Basic YWRtaW46YWRtaW4=' -H 'Content-Type: application/json' -X POST -d '[ {
  "name" : "Zephyr Firmware",
  "vendor" : "Linaro",
  "description" : "Firmware Images for Zephyr",
  "type" : "os",
  "version" : "1.5"
  } ]'
  

• Delete a software module:

  curl 'http://your-hawkbit-server.example.com:8080/rest/v1/softwaremodules/1' -i -H 'Authorization: Basic YWRtaW46YWRtaW4=' -X DELETE
  

• List artifacts from a software module:

  curl 'http://your-hawkbit-server.example.com:8080/rest/v1/softwaremodules/2/artifacts' -s -H 'Authorization: Basic YWRtaW46YWRtaW4=' | jq .
  

• Upload a new artifact to a software module:

  curl 'http://your-hawkbit-server.example.com:8080/rest/v1/softwaremodules/2/artifacts' -i -H 'Authorization: Basic YWRtaW46YWRtaW4=' -H 'Content-Type: multipart/form-data' -X POST -F 'file=@/tmp/zephyr.hex'
  

• Download an artifact:

  curl 'http://your-hawkbit-server.example.com:8080/rest/v1/softwaremodules/2/artifacts/1/download' -s -H 'Authorization: Basic YWRtaW46YWRtaW4=' -H 'Accept: application/octet-stream'
  

Rollout:

• Reference: http://sp.apps.bosch-iot-cloud.com/documentation/rest-api/rollout-api-guide.html

Bootstrap Example

• Create new target:

  curl 'http://your-hawkbit-server.example.com:8080/rest/v1/targets' -i -H 'Authorization: Basic YWRtaW46YWRtaW4=' -H 'Content-Type: application/json' -X POST -d '[ {
  "controllerId" : "nitrogen123",
  "name" : "nitrogen123",
  "description" : "Nitrogen Description"
  } ]'
  

• Create new distribution set:

  curl 'http://your-hawkbit-server.example.com:8080/rest/v1/distributionsets' -i -H 'Authorization: Basic YWRtaW46YWRtaW4=' -H 'Content-Type: application/json' -X POST -d '[ {
  "name" : "Zephyr 17.01",
  "description" : "Zephyr 17.01 Build",
  "version" : "1.5",
  "requiredMigrationStep" : false,
  "type" : "os"
  } ]'
  

• Create new software module:

  curl 'http://your-hawkbit-server.example.com:8080/rest/v1/softwaremodules' -i -H 'Authorization: Basic YWRtaW46YWRtaW4=' -H 'Content-Type: application/json' -X POST -d '[ {
  "name" : "Zephyr Firmware",
  "vendor" : "Linaro",
  "description" : "Firmware Images for Zephyr",
  "type" : "os",
  "version" : "1.5"
  } ]'
  

• Upload artifact to the software module:

  curl 'http://your-hawkbit-server.example.com:8080/rest/v1/softwaremodules/2/artifacts' -i -H 'Authorization: Basic YWRtaW46YWRtaW4=' -H 'Content-Type: multipart/form-data' -X POST -F 'file=@/tmp/zephyr.hex'
  

• Assign software module to the distribution set:

  curl 'http://your-hawkbit-server.example.com:8080/rest/v1/distributionsets/1/assignedSM' -i -H 'Authorization: Basic YWRtaW46YWRtaW4=' -H 'Content-Type: application/json' -X POST -d '[ { "id" : 1 } ]'
  

• Assign distribution set to the desired target:

  curl 'http://your-hawkbit-server.example.com:8080/rest/v1/targets/nitrogen123/assignedDS' -i -H 'Authorization: Basic YWRtaW46YWRtaW4=' -H 'Content-Type: application/json' -X POST -d '{
  "forcetime" : 1472465267347,
  "id" : 1,
  "type" : "timeforced"
  }'
  

  Now create a rollout.