OTA Connect Developer Guide

Client events reporting

This is a technical document describing the format of the events reported to the back-end by aktualizr during an ongoing update installation. It reflects the current state of aktualizr code. Future enhancements should be clearly marked as such (TODO), to avoid confusion.

The corresponding C++ objects and their serialization method are defined in reportqueue.h.

Common fields

  • deviceTime is a timestamp of the event emission (not transmission which can be delayed)

  • eventType contains two fields id and version which correspond the format of the custom fields

  • id is a unique identifier generated on the client side

  • event contains the custom fields as specified by the event type

  • event.correlationId (when applicable) identifies the specific update requested by back-end

  • event.ecu (when applicable) identifies the specific ECU in the vehicle which the event pertains to

Per-ECU events

EcuDownloadStarted

Emitted when the target download relating to a specific ecu has started. Note that since a target can apply to multiple ecus, more than one event can be sent for each target download.

Contains a correlation id.

Example:

{
        "deviceTime" : "2018-10-25T12:35:42Z",
        "event" :
        {
                "correlationId" : "here-ota:campaigns:c017f968-5c7e-4bf6-9992-2134ff06432c",
                "ecu" : "secondary_ecu_serial"
        },
        "eventType" :
        {
                "id" : "EcuDownloadStarted",
                "version" : 0
        },
        "id" : "313258b4-e4c6-4ce4-a4f3-011a3959d92b"
}

EcuDownloadCompleted

Emitted when the target download relating to a specific ecu has ended (success or failure). Same caveat as EcuDownloadStarted applies.

Success/failure indicated by the boolean event.success. TODO: revisit that, maybe a status code instead + free form log string

Contains a correlation id.

Example:

{
        "deviceTime" : "2018-10-25T12:35:42Z",
        "event" :
        {
                "correlationId" : "here-ota:campaigns:c017f968-5c7e-4bf6-9992-2134ff06432c",
                "ecu" : "CA:FE:A6:D2:84:9D",
                "success" : true
        },
        "eventType" :
        {
                "id" : "EcuDownloadCompleted",
                "version" : 0
        },
        "id" : "bfb0b452-ac41-4cf0-bec8-3b78469157ec"
}

EcuInstallationStarted

Emitted when installation on a specific ecu has started.

Contains a correlation id.

Example:

{
        "deviceTime" : "2018-10-25T12:35:42Z",
        "event" :
        {
                "correlationId" : "here-ota:campaigns:c017f968-5c7e-4bf6-9992-2134ff06432c",
                "ecu" : "CA:FE:A6:D2:84:9D"
        },
        "eventType" :
        {
                "id" : "EcuInstallationStarted",
                "version" : 0
        },
        "id" : "9e3ad5f6-091d-4f63-96eb-20ba2e256631"
}

EcuInstallationCompleted

Emitted when installation on a specific ecu has ended (success or failure).

Success/failure indicated by the boolean event.success. TODO: revisit that, maybe a status code instead + free form log string

Some devices need a reboot after an installation to actually have an effect on the system. TODO: use a status code NEED_REBOOT?

Contains a correlation id.

Example:

{
        "deviceTime" : "2018-10-25T12:35:42Z",
        "event" :
        {
                "correlationId" : "here-ota:campaigns:c017f968-5c7e-4bf6-9992-2134ff06432c",
                "ecu" : "CA:FE:A6:D2:84:9D",
                "success" : true
        },
        "eventType" :
        {
                "id" : "EcuInstallationCompleted",
                "version" : 0
        },
        "id" : "74060fe8-c594-4f37-b676-4d3bedcb5ca5"
}

Others

campaign_accepted

Emitted in response to a campaign confirmation request

Example:

{
                "deviceTime" : "2018-10-25T12:56:52Z",
                "event" :
                {
                        "campaignId" : "123"
                },
                "eventType" :
                {
                        "id" : "campaign_accepted",
                        "version" : 0
                },
                "id" : "4fc0fb3d-21e3-4b3b-a902-b9c80913f086"
        }
}