Hawkbit Reference

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

• Upstream Github: https://github.com/eclipse/hawkbit
• Docker container: https://github.com/linaro-technologies/gitci-hawkbit-container
• Docker Hub: https://hub.docker.com/r/linarotechnologies/gitci-hawkbit-container/
• Data model: https://github.com/eclipse/hawkbit/wiki/Data-model

Data Model for Demo setup

Distribution Set Type:

• Name: OS only
• Description: Firmware/OS
• Key: os

Distribution Set:

• Name: Zephyr 17.01
• Description: Zephyr 17.01 Build
• Version: 1.5
• Type: os

Software Module Type:

• Name: OS
• Description: Firmware
• Key: os

Software Module:

• Name: Zephyr Firmware
• Description: Firmware Images for Zephyr
• Vendor: Linaro
• Type: os
• Version: 1.5

Software Module Artifact:

• File: zephyr.bin

Target:

• Name: nitrogen123
• Controller ID: nitrogen123

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.

We currently produce device-specific images based on the same source (e.g. same base version).

For discussion: should we create one distribution set per device, or should we modify the os distribution set type to allow multiple software modules (that could then be hardware specific).

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 just create a rollout :-).