OTA Connect API Usage Guide

OTA Connect Devices API

The endpoints of the devices API allow you to get information about the devices in your environment. You can list all your devices, see detailed information about a particular device, see a device’s update queue, and list the events a device has reported.

You can also view the OpenAPI/Swagger spec, if you prefer.

Device identifiers

Every device in your OTA Connect account has two different identifiers:

  • The Device ID, which should generally be an informative name you provide. For example, if you are using device credential provisioning, the Device ID will be set equal to the CNI of the device’s X.509 certificate. If you’re using shared credential provisioning, the Device ID will be a randomly generated name—​something like easy-beetenbartsch-371 or tasty-gruenkohl-470--unless you configured it otherwise.

  • A UUID that OTA Connect uses internally for the device.

Whenever you’re referencing a particular device in the API, you’ll need to use its UUID, not its device ID.

Endpoints

There are currently four endpoints for your devices on the OTA Connect Portal.

Table 1. OTA Connect API Endpoints
Endpoint Verb Description

/devices

GET

List all devices.

/devices/{deviceUuid}

GET

List detailed information about a single device.

/devices/{deviceUuid}/queue

GET

List currently queued updates for a single device.

/devices/{deviceUuid}/events

GET

List the events reported by a single device.

/devices

This endpoint returns a paginated list of devices that are connected to the specified account on OTA Connect. The devices are sorted in descending order according to their creation date.

This endpoint returns only the Device ID, Device UUID, and creation date of the devices. To see more detailed information, use a device-specific endpoint.

  • cURL

  • Sample Response

curl "https://api.ota.here.com/v1alpha/devices" -H "accept: application/json" -H "Authorization: Bearer $ota_token" | jq .
{
  "values": [
    {
      "deviceUuid": "3a05aeb1-4a28-4fe5-8ccc-dd01e289a4a1",
      "deviceId": "tasty-gruenkohl-470",
      "createdAt": "2018-10-16T08:12:22Z"
    },
    {
      "deviceUuid": "289cf02c-9437-4d93-b48b-990ffdebef0a",
      "deviceId": "easy-beetenbartsch-371",
      "createdAt": "2019-12-03T15:23:37Z"
    },
],
  "total": 2, (1)
  "offset": 0, (1)
  "limit": 50 (1)
}
1 Note the pagination in the response JSON. For more information, see Pagination.

This endpoint will often be a starting point for integrations with external systems. Other databases or systems you might want to integrate with OTA Connect will likely have information about your fleet keyed by the Device ID, but to exercise OTA Connect’s other device endpoints you will need the device’s UUID. This endpoint gives you the mapping between those two values.

Both Device ID and UUID are invariant—​to increase the efficiency of your integration, we recommend caching the UUID so that you don’t need to look it up every time.

/devices/{deviceUuid}

This endpoint returns detailed information about the current state of a single device. This includes information about its primary ECU and the software version currently installed.

  • cURL

  • Sample Response

curl "https://api.ota.here.com/v1alpha/devices/{deviceUuid}" -H "accept: application/json" -H "Authorization: Bearer $ota_token" | jq .
{
  "deviceUuid": "3a05aeb1-4a28-4fe5-8ccc-dd01e289a4a1",
  "deviceId": "tasty-gruenkohl-470",
  "name": "tasty-gruenkohl-470",
  "lastSeen": "2018-10-16T08:32:16Z",
  "status": "UpToDate", (1)
  "primaryEcu": {
    "ecuId": "263294f8c9932374c3fb1efd89924b7d7142672c52bcf30ba055a6110453ae57",
    "ecuType": "Telematics_2AC5", (2)
    "installedSoftwareVersion": { (3)
      "filename": "acme-firmware_0.7.3",
      "hashes": {
        "sha256": "c4a239233ea6d702d3fc98f229972257354f778eed2f6efb1bce836b2db56c60"
      },
      "length": 208179287 (4)
    }
  }
}
1 Normal statuses are UpToDate, Outdated, and Error. It is also possible to have a status of NotSeen, but this will only occur if there was a problem with provisioning.
2 The hardware identifier of the ECU. By default, this is the MACHINE value of the Yocto build—​for example, raspberrypi3.
3 Information about the currently installed software version on the primary ECU.
4 Length in bytes of the primary ECU image. Note that for OSTree images, the length is always 0.

/devices/{deviceUuid}/queue

This endpoint returns the update queue for a device. Returned information includes the name, hash, and length of any queued update images, as well as an updateId, which can be used in other API calls.

Note that the ecus object in the response is a dictionary of ecuIdSoftwareVersion. When parsing the JSON, make sure to account for the possibility that it will contain more than one ecuId, even if you normally only create updates targeting one ECU.

  • cURL

  • Sample Response

curl "https://api.ota.here.com/v1alpha/devices/{deviceUuid}/queue" -H "accept: application/json" -H "Authorization: Bearer $ota_token" | jq .
[
  {
    "deviceUuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "updateId": "urn:here-ota:mtu:8a2dc7ca-3432-4423-bfc6-0cce0043291b",
    "ecus": {
      "263294f8c9932374c3fb1efd89924b7d7142672c52bcf30ba055a6110453ae57": {
        "filename": "acme-firmware_0.7.3",
        "hashes": {
          "sha256": "c4a239233ea6d702d3fc98f229972257354f778eed2f6efb1bce836b2db56c60"
        },
        "length": 208179287
      },
      "CA805E41-41E2-47F5-A417-52DF9F6BB027": {
        "filename": "acme-coprocessor_firmware_0.4.0",
        "hashes": {
          "sha256": "fb32fbde0bc172935f0971cba0955b74a40802cd80bab93524141dcc8fff6153"
        },
        "length": 509281
      }
    }
  }
]

/devices/{deviceUuid}/events

This endpoint returns all the events reported by a particular device, in order of the device-reported time of the event (newest first).

The possible reported events are EcuDownloadStarted, EcuDownloadCompleted, EcuInstallationStarted, EcuInstallationApplied, EcuInstallationCompleted, DevicePaused, DeviceResumed, CampaignAccepted, CampaignDeclined, and CampaignPostponed. (Consult libaktualizr API documentation for more information on these events.)

For each event, this endpoint lists the ECU affected, the related update ID, the time the ECU reported that the event occurred (deviceTime), and the time the server received the event (receivedTime).

  • cURL

  • Sample Response

curl "https://api.ota.here.com/v1alpha/devices/{deviceUuid}/events" -H "accept: application/json" -H "Authorization: Bearer $ota_token" | jq .
{
  "deviceUuid": "b456653b-89d8-4bf6-9ce6-e9d07ffa2b93",
  "events": [
    {
      "ecuId": "a9d8e8bb11e9c628ef8bd69298574fc2c9cc4a185aef76c2a32336c429155249",
      "updateId": "urn:here-ota:mtu:8a2dc7ca-3432-4423-bfc6-0cce0043291b",
      "name": "EcuInstallationCompleted",
      "receivedTime": "2020-02-19T14:57:45Z",
      "deviceTime": "2020-02-19T14:56:23Z"
    },
    {
      "ecuId": "a9d8e8bb11e9c628ef8bd69298574fc2c9cc4a185aef76c2a32336c429155249",
      "updateId": "urn:here-ota:mtu:8a2dc7ca-3432-4423-bfc6-0cce0043291b",
      "name": "EcuDownloadStarted",
      "receivedTime": "2020-02-19T14:55:36Z",
      "deviceTime": "2020-02-19T14:55:36Z"
    }
  ]
}