HawkBit Integration API
General Description
This document describes the steps needed to deploy the signed rauc bundles from our dashboard. In order to use this feature, the customer has to upload the “signed” artifact using the hawkbit API calls. Customers will not have access to the shared hawkbit user interface.
In order to use our “signing service” to create the rauc bundles and sign them, it is recommended to set up the “dedicated hawkbit server”. In this we take care of bundle creation, key management for bundle signing and uploading to hawkbit.
Generally, for new customers, the first step is carried out during the onboarding process. That is the creation of “software artifact types”. For signed rauc bundles we use raucbundle as software module artifact type and testingdist or releasedist as distribution set type. This will indicate that the artifact is signed and only such artifacts are shown in the dashboard for the deployment.
Steps to Upload Signed Artifacts
Create Software Module
We can use the hawkbit API call to create software modules. Software modules should be created before uploading the signed bundles.
REST API Method | Base URL | API Call | Body |
---|---|---|---|
POST | https://api.aws.iot-suite.io/hawkbitintegration/ | createSoftwareModule | [{"name": "test_softwaremodule", "version": "1.0", "type": "raucbundle", "vendor": "vendor_name", "description": "test software module"}] |
Example:
POST https://api.aws.iot-suite.io/hawkbitintegration/createSoftwareModule
Body : [{"name": "test_softwaremodule", "version": "1.0", "type": "raucbundle", "vendor": "vendor_name", "description": "test software module"}]
Sample response:
status code : 201
Body : [{'createdBy': 'osb-aws-configrollout', 'createdAt': 1656433705759, 'lastModifiedBy': 'osb-aws-configrollout', 'lastModifiedAt': 1656433705759, 'name': 'test_softwaremodule', 'description': 'test software module', 'version': '1.0', 'type': '<customer-name>__raucbundle', 'vendor': 'vendor_name', 'deleted': False, '_links': {'self': {'href': 'https://hawkbit.prod.esec.aws.esec-experts.com/rest/v1/softwaremodules/582'}}, 'id': 582}]
Here id that is returned in the JSON response, is the key value which is needed in the next steps to upload bundles to the software module. This value is unique and only one signed bundle could be uploaded to a software module.
Note:
For signed artifacts, the software module type needs to be “raucbundle” and the customer name will be appended to the artifact type automatically. No need to specify “type”:”customer-name__raucbundle” in the API call’s body. This is also true for other software artifact types.
Upload Signed Bundle
This process is divided into two sub-steps: create a presigned URL and then upload the artifact using the presigned URL.
Currently, this step is handled via a python script that also generates a presigned URL and uploads the artifact to the same URL. Parameters for the script includes:
id_token: is the Bearer token needed for authentication.
sw_id: software module id generated in the previous step
file_local_path: path to the artifact
artifact_name: name of the artifact (*.bundle)
expired_in_sec: validity of the presigned URL (sec)
from lib2to3.pgen2
import
token
import
requests
import
json
def upload_software_module_artifact(id_token, sw_id, file_local_path, artifact_name, expires_in_sec) :
print(
"# [DEBUG] upload_software_module_artifact"
)
successful = False
url = f
"https://api.aws.iot-suite.io/hawkbitintegration/feature/hawkbit/presignedurl/{sw_id}?artifact_name={artifact_name}&expires_in_sec={expires_in_sec}"
print(url)
payload={}
headers = {
'Authorization'
:
'Bearer '
+ id_token
}
presigned_url_resp = requests.request(
"POST"
, url, headers=headers, data=payload)
if
(presigned_url_resp.ok) :
presigned_url_json = presigned_url_resp.json()
url = presigned_url_json[
"url"
]
fields = presigned_url_json[
"fields"
]
# artifact_name : does not have any effect on the file name in the hawkbit server only the name chosen when creating the presigned url is relevant
# file_local_path : does not have any effect on the file name in the hawkbit server
with open(file_local_path,
'rb'
) as f:
files = {
'file'
: (artifact_name, f)}
http_response = requests.post(url, fields, files=files)
# If successful, returns HTTP status code
204
print(f
'File upload HTTP status code: {http_response.status_code}'
)
print(f
'File upload HTTP content: {http_response.content}'
)
if
(http_response.ok) :
print(
"# [DEBUG] artifact uploaded succesfully"
)
successful = True
else
:
print(
"# [WARNING] artifact not uploaded"
)
successful = False
else
:
print(
"# [WARNING] artifact not uploaded"
)
successful = False
print(presigned_url_resp.status_code, presigned_url_resp.json() )
return
successful
token_id =
"Bearer token id"
sw_id =
"Software module id"
print(upload_software_module_artifact(id_token=token_id, sw_id=sw_id, file_local_path=
"./raucb.bundle"
, artifact_name=
"raucb.bundle"
, expires_in_sec=
300
))
Creation of Distribution Set
The last step is to create a distribution set and assign the previously generated software module to distribution set. Please provide an appropriate name, description, and version to it. Type of the distribution has to be either releasedist or testingdist for signed software artifacts.
REST API Method | Base URL | API Call | Body |
---|---|---|---|
POST | https://api.aws.iot-suite.io/hawkbitintegration/ | postDistributionSet | [{'name': 'test_distribution_set', 'description': 'test distribution set', 'type': 'releasedist', 'version': '1.0', 'modules': [{'id': 582}], 'requiredMigrationStep': False}] |
Example:
POST https://api.aws.iot-suite.io/hawkbitintegration/postDistributionSet
Body : [{'name': 'test_distribution_set', 'description': 'test distribution set', 'type': 'releasedist', 'version': '1.0', 'modules': [{'id': 582}], 'requiredMigrationStep': False}]
'modules': [{'id': 582}] , id = 582 is the software module id of the previously created software module.
Sample response:
status code: 201
Body : [{'createdBy': 'osb-aws-configrollout', 'createdAt': 1656438063786, 'lastModifiedBy': 'osb-aws-configrollout', 'lastModifiedAt': 1656438063786, 'name': 'test_distribution_set', 'description': 'test_distribution_set', 'version': '1.0', 'modules': [{'createdBy': 'osb-aws-configrollout', 'createdAt': 1656433705759, 'lastModifiedBy': 'osb-aws-configrollout', 'lastModifiedAt': 1656435319013, 'name': 'test_softwaremodule', 'description': 'test software module', 'version': '1.0', 'type': '<customer-name>__raucbundle', 'vendor': 'vendor_name', 'deleted': False, '_links': {'self': {'href': 'https://hawkbit.prod.esec.aws.esec-experts.com/rest/v1/softwaremodules/582'}}, 'id': 582}], 'requiredMigrationStep': False, 'type': '<customer-name>__releasedist', 'complete': True, 'deleted': False, '_links': {'self': {'href': 'https://hawkbit.prod.esec.aws.esec-experts.com/rest/v1/distributionsets/389'}}, 'id': 389}]
Tagging of Distribution Sets
Once the distribution is created, it needs to be tagged so that it will be displayed in our dashboard. Distribution set tag name “gui_release” is already created and it needs to be assigned. Please don’t create additional tags as we currently support only one type of tag.
To assign the tag to distribution set:
REST API Method | Base URL | API Call |
---|---|---|
POST | https://api.aws.iot-suite.io/hawkbitintegration/ | feature/hawkbit/assignDistributionSetTag/{{distribution_tag_id}}?distributionId={{distribution_id}} |
distribution_id: Distribution set ID (from previous step)
distribution_tag_id: ID of distrbution set tag (id=29)
Example:
POST https://api.aws.iot-suite.io/hawkbitintegration/feature/hawkbit/assignDistributionSetTag/{{distribution_tag_id}}?distributionId={{distribution_id}}
Deployment of the Signed Bundle
The signed bundle can de deployed to the target via our iot-suite dashboard. In the Firmware Update tab, all the images available for deployment will be listed. Once we trigger the deployment, the bundle will be downloaded and installed on the target.

Get Target Distribution
Using API calls we can retrieve the distribution sets associated for a specific target.
REST API Method | Base URL | API Call |
---|---|---|
GET | https://api.aws.iot-suite.io/hawkbitintegration/ | getTargetDistributions/{{device_uid}}?distribution_tag_filter=gui_release |
device_uid : UID of the device
customer_name (optional query param) : customer name
Note: The above API call only retrieves distribution sets with type either testingdist or releasedist.
Example:
[{"createdBy": "osb-aws-configrollout", "createdAt": 1664544309073, "lastModifiedBy": "osb-aws-configrollout", "lastModifiedAt": 1664544638765, "name": "testingdist", "description": "", "version": "1", "modules": [{"createdBy": "osb-aws-configrollout", "createdAt": 1664543984447, "lastModifiedBy": "osb-aws-configrollout", "lastModifiedAt": 1664543984447, "name": "testsoftware_module", "description": "", "version": "1", "type": "<customer-name>__raucbundle", "vendor": "", "deleted": false, "_links": {"self": {"href": "http://hawkbit.prod.esec.aws.esec-experts.com/rest/v1/softwaremodules/608"}}, "id": 608}], "requiredMigrationStep": false, "type": "<customer-name>__releasedist", "complete": true, "deleted": false, "_links": {"self": {"href": "http://hawkbit.prod.esec.aws.esec-experts.com/rest/v1/distributionsets/415"}}, "id": 415, "metadata": [{"key": "compatibility", "value": "bsp-ecu"}]}]
Contact
If you have any questions please contact us via support@iot-suite.io