User Guide

To use Drogue Ajour you need to run a stand-alone version of Drogue Cloud. Have a look in the the Admin Guide for installation instructions. The public Drogue Cloud Sandbox does not have Drogue Ajour installed.

Prerequisites

The following examples require that your a logged in to your Drogue Cloud cluster with drg.

Enabling firmware delivery

Drogue Ajour makes use of the Application and Device types from Drogue Cloud.

To enable firmware delivery for a given application or device, you must modify the spec section of the resource. You can have firmware delivered from a container registry, Eclipse Hawkbit or a file locally available to the Drogue Ajour server.

From container registry

Edit a device:

drg edit device --app my-app my-device-1

Make sure the device definition contains the following:

spec:
    firmware:
        oci:
            image: my-firmware:latest

Firmware images can only be retrieved from the container registry Drogue Ajour was configured for, and the image reference is therefore relative to the configured registry. See expected container format for what the image must look like.

Save the new definition. When the device connects to the update service, the update service will make sure the device is updated from the firmware contained within the container image.

From Eclipse Hawkbit

Edit a device:

drg edit device --app my-app my-device-1

Make sure the device definition contains the following:

spec:
    firmware:
        hawkbit:
            controller: controllername

Controller name is a concept from Eclise Hawkbit. The controller must be created in Eclipse Hawkbit before Drogue Ajour can use it to retrieve firmware.

Enabling firmware build

Firmware builds are only enabled for container registry firmwares for the time being. This also requires that the firmware build components are installed for Drogue Ajour.

Edit a device:

drg edit device --app my-app my-device-1

Make sure the device definition contains the following:

spec:
    firmware:
        oci:
            image: my-firmware:latest
            build:
                # An image reference to a container image used to build your project
                image: docker.io/myorg/firmware-builder-image:latest
                source:
                    git:
                        # Git repository URI
                        uri: https://github.com/myorg/example-project
                        # Project folder within repository
                        project: repo/sub/folder
                        # Git revision to use
                        rev: main
                # Arguments passed to the builder image
                args:
                - flag1
                - flag2
                artifact:
                    # Path to artifact generated by builder image
                    path: myartifact.bin

When the firmware is built, these parameters will be passed to the tekton pipeline, and the image will be pushed to the configured registry.

Triggering a build

You can trigger a build from the Drogue Ajour console, or the command line as follows if you’re logged in:

# Retrieving an auth token
TOKEN=$(drg whoami -t)
# URL is the Drogue Ajour API server
curl -X POST -H "Authorization: Bearer ${TOKEN}" https://build-api/api/build/v1alpha1/apps/my-app/devices/my-device-1/trigger

This will trigger the Tekton pipeline and publish the new firmware to the configured container registry.

To retrieve the current status of a firmware build, you can query the same API:

# Retrieving an auth token
TOKEN=$(drg whoami -t)

# URL is the Drogue Ajour API server
curl -X GET -H "Authorization: Bearer ${TOKEN}" https://build-api/api/build/v1alpha1/apps/my-app/devices/my-device-1

You can also use the Drogue Ajour console to check the status of your firmware builds.