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:

GET https://api.aws.iot-suite.io/hawkbitintegration/getTargetDistributions/0x4790700xxxxx?distribution_tag_filter=gui_release

[{"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