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

Lists all devices.

/devices/{deviceUuid}

GET

Lists detailed information about a single device.

/devices/{deviceUuid}/queue

GET

Lists currently queued updates for a single device.

/devices/{deviceUuid}/events

GET

Lists 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.

You can also specify a device ID as a value for the deviceId parameter to get information about a specific device. To get a list of all devices that have a particular ECU type as their primary, specify the primaryEcuType parameter.

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, including information about its primary and secondary ECUs and the software version that is 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)
    }
  },
  "secondaryEcus": [
    {
      "ecuId": "0F76543a7563d702d3fc98f229972257354f778eed2f6efb1bce836b2db45f50",
      "ecuType": "PCM-EV",
      "installedSoftwareVersion": {
        "filename": "acme-secondary_0.8.3",
        "hashes": {
          "sha256": "e3b0c55398fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
        },
        "length": 3755
      }
    }
  ]
}
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"
    }
  ]
}

/devices/{deviceUuid}/installations

This endpoint returns a list of ECU and device installation reports.

You can set the maximum number of reports that you want to get using the limit parameter. The default number is 50. To specify the number of reports that you want to skip from the beginning, set the offset parameter. By default, it does not skip reports.

  • cURL

  • Sample Response

curl "https://api.ota.here.com/v1alpha/devices/{deviceUuid}/installation" -H "accept: application/json" -H "Authorization: Bearer $ota_token" | jq .
{
  "deviceUuid": "a3894592-902f-4029-a023-69f386711ebd",
  "installations": {
    "values": [
      {
        "receivedTime": "2020-08-14T13:46:13Z",
        "updateId": "urn:here-ota:campaign:fc577ffd-2c41-4735-ad57-d27f6c63778d",
        "result": {
          "success": true,
          "code": "OK",
          "description": "Device was installed successfully."
        },
        "ecuReports": {
          "4Z6eDo00R0wHB8f": {
            "result": {
              "success": true,
              "code": "OK",
              "description": "Packages were installed successfully."
            },
            "targets": [
              "9Um85P8O5W_0.0.1"
            ]
          }
        }
      },
      {
        "receivedTime": "2020-08-14T13:45:44Z",
        "updateId": "urn:here-ota:campaign:059a5945-6a3e-4e65-a47b-6502ffb41d96",
        "result": {
          "success": true,
          "code": "OK",
          "description": "Device was installed successfully."
        },
        "ecuReports": {
          "1XA4j5M2sG6mlK7": {
            "result": {
              "success": true,
              "code": "OK",
              "description": "Software was installed successfully."
            },
            "targets": [
              "4Hj7jhLQkt_0.0.1"
            ]
          }
        }
      }
    ],
    "total": 2,
    "offset": 0,
    "limit": 50
  }
}