Get Started

Quick start

The following steps are designed to help you quickly get started with HERE OTA Connect and to understand each step in the update process. You will learn how to install and run the latest version of the OTA Connect client (aktualizr). Some steps might not work if you use an older version of this client.

HERE OTA Connect is only supported on the Google Chrome browser.

Devices

Step 1: Provision some devices

To provision devices, you need to attach individual credentials and certificates to a device. HERE OTA Connect automates this process for you: you can use the same unmodified disk image on many different devices and register each device with OTA Connect when you boot it for the first time.

To get a provisioning key:

  1. Go to the Credentials (provisioning) tab of your profile.

  2. Click Add key.

    image
  3. In the Add new key dialog box, specify the key description, select its period of validity, and then click Add key.

    image

The .zip file is added to the list of credentials. The file contains the provisioning key and credentials that your build system uses to publish images. You do not need to unzip the file. Save it somewhere on your computer. You will need the file when you set up your Yocto build or configure the HERE OTA Connect client.

For a more in-depth technical description of device provisioning, see Device Provisioning Methods. To learn how to provision devices with a custom device ID, see Configure your own device IDs.

Now, install the OTA Connect client on the device that you want to connect:

You can simulate a device on Linux or MacOS, but you will need to use Linux if you want to build an image.

We recommend that you provision more than one test device so that you can practice grouping them.

Step 2: Find your newly provisioned devices

All provisioned devices appear on the Devices page.

To check if your devices were provisioned properly:

  1. Go to the Devices tab.

  2. On the right navigation pane, select All devices or Ungrouped devices.

  3. Click the device that you want to check.

    A page with device details opens.

Device groups

Step 3: Group your devices

You can organize devices provisioned in one environment into groups to target them in campaigns. Each provisioned device can be targeted in different groups, but you cannot target devices from different environments in one group. For more information, see What is an environment.

There are two types of device groups:

  • The fixed group type is useful if you already have a fixed list of devices that you want to update.

  • The smart group type is useful if you know the selection criteria for devices that you want to update but do not yet have a fixed list of devices.

    Even if you do have a fixed list of devices, smart groups can also come in handy when you constantly add new devices to your list. Smart groups automatically group newly provisioned devices that match certain selection criteria.

To create a smart group:

  1. Go to the Devices tab.

  2. Click Create group.

    image
  3. Select Smart device group, and then click Next.

  4. Specify the group name.

  5. In the Cluster section, define a filter for your devices.

    Filters help HERE OTA Connect match each device to a group. Currently, OTA Connect can filter based on characters in the device ID or your custom device fields. The device ID is defined in the OTA Connect client configuration and is set on the server when the device connects for the first time.[1] If no ID is configured on the device, a random ID is automatically generated.

    You cannot change the filter criteria of a smart group after you create it. If you made a mistake with the filter criteria, create another smart group.
    Example 1. Example

    You need to provision 2019 car models. Each device ID is a vehicle identification number (VIN) where the 10th character is the letter K.

    1. From the Filter list, select Device ID.

    2. Since every character in the VIN has a meaning, from the Type list, select has character equal to.

    3. In the Value field, enter the letter K, and then select in position 10 (the 10th character in a VIN is usually the model).

      OTA Connect shows how many devices match your filter criteria.

      image
  6. (Optional) Add more filters:

    • If you want to target devices that match both filters, in the same Cluster section, click Add filter, and then specify its criteria.

    • If you want to target devices that match one of the filters or filter combinations, click Add cluster, and then specify the needed filter or filters.

      Example 2. Example

      You want to target devices with the Premium value in the Trim level field and the Germany or France value in the Market field. You have already created the following custom device fields: Trim level and Market. In the Create device group dialog box, specify the following filters:

      1. In the first Cluster section, select the Market filter and the Contains type, and then specify the Germany value.

      2. Click Add filter.

      3. In the new filter fields, select the Trim level filter and the Contains type, and then specify the Premium value.

      4. Click Add cluster.

      5. In the new cluster, select the Market filter and the Contains type, and then specify the France value.

      6. Click Add filter.

      7. In the new filter fields, select the Trim level filter and the Contains type, and then specify the Premium value.

        image
  7. Click Create.

    The created group appears in the Groups pane. If a new provisioned device meets the specified filter criteria, it is automatically added to the group. If a device is deleted, it is automatically removed from the group.

Software

Step 4: Upload some software versions

Now, you can upload a software version. If you decided to build your own image in Step 1, it will be automatically uploaded to your OTA Connect account as part of the build process. If you chose the simulated device option, you will need to upload a software package.

If your software signing keys are taken offline, you won’t be able to upload new software packages via OTA Connect. Use the garage-sign tool on the command line instead.

To upload a software version:

  1. Go to the Software versions tab.

  2. In the upper-right corner, under the name of your active environment, click Upload software.

    image
  3. In Software name, specify the name of your software version.

  4. In Software version, specify the number or name of your software version.

  5. From Control unit types, select the type or types of the engine control unit for which your software version is intended.

    It’s important to select the control unit type or types because OTA Connect prevents you from installing software on control units that it’s not compatible with. A control unit type is configured on the client[2], so if you followed the guide for simulating devices, your simulated devices have a control unit type of local-fake.
  6. Click Choose a file, and then select the needed file that contains your software version.

    You can upload one file at a time. The progress bar will show how much data has been processed. You can also cancel the file upload before the data has been entirely processed.

    On the portal, the maximum file size limit for uploads is 1 GB. If you want to upload larger files (up to 15 GB), use the garage-sign tool on the command line.
    image
  7. Click Upload.

    If your software is uploaded successfully, you see the "Software uploaded" message.

    image
  8. Click Done.

The new software version appears in the software version list.

If you want to practice updating software, you might want to repeat this process and upload another version of the file and enter a newer software version.

This way, you have two sets of software. The current version, and the version that you want to upgrade to.

Software updates

A software update is a set of instructions that you can use in a campaign. These instructions specify the software versions that should be updated. To make sure everything is compatible, it is important to install a bundle of software images on different control units at the same time. However, you can also install one image at a time per control unit.

Step 5: Create a software update

When you create an update configuration, you need to define two basic assignment criteria:

  • The type of control unit (ECU) to which the software version applies.

  • The current version of the software that you want to update.

To create a software update:

  1. Go to the Software updates tab.

  2. In the upper-right corner, under the name of your active environment, click Create update.

    image
  3. In Software update name, specify the name of your software update.

  4. (Optional) Provide a description of your software update.

  5. In Select multiple control unit types, select the control unit types that you want to update.

    image
  6. Click Continue.

  7. Define the update criteria for each control unit software package:

    • If you want to update control units that are running a specific software version only, in the From section, select the relevant items from the Software and Version lists.

    • If you want to update to the new software version on all control units, select the following option: Update to my selected version regardless of what is currently installed

      Older software versions might not upgrade properly due to version incompatibility, and devices already updated will receive the same update.
  8. To specify to which software version you want to update, in the To section, select the relevant items from the Software and Version lists.

    image
  9. Click Save.

The new software update appears in the software updates list. To learn how to send your software update to a device group, move to the next step.

Campaigns

A campaign is what sends software updates to vehicles. When you create a campaign, you get to define which update to send, which vehicles to send it to, and how it should be distributed.

Step 6: Create a campaign

You need a campaign to deploy software updates to groups of devices.

Before you create and launch a new campaign, to make sure that the offline devices get the latest updates when they connect, cancel the existing campaigns that target the older versions of the software that you want to deploy.

To create a campaign:

  1. Go to the Campaigns tab.

  2. In the upper-right corner, under the name of your active environment, click Create campaign.

    image
  3. Specify the campaign name, and then click Next.

  4. Select the device groups to which you want to deploy the software update, and then click Next.

  5. Select the software update that you want to deploy, and then click Next.

  6. If you need to request the end-user consent, select Request end user’s consent, enter the notification text, and then click Next.

  7. At the Summary step, review the campaign summary, and then do one of the following:

    • If the campaign is not configured properly, to change the configuration details, go to the needed step, and then change the details.

    • If the campaign is configured properly, to start the campaign, click Launch.

The campaign appears in the campaigns list. You can monitor the campaign status.

Step 7: Monitor your campaign

After you launch a campaign, you can open the campaign details to monitor the progress of the campaign and look for any installation issues.

To see the campaign details:

  1. Go to the Campaigns tab.

    In the campaigns list, you can find the following information about each campaign:

    • Name

    • Creation date

    • Status:

      • In preparation—your campaign is preparing for the launch.

      • Running—your campaign is still in the process and has not finished.

      • Finished—your campaign has completed.

      • Canceled—your campaign was canceled for all or several devices.

    • Number of devices that are included in the campaign

    • Percentage of devices with the Failed, Successful, Installing, and Not applicable statuses.

  2. Navigate to the needed campaign, and next to it, click More info.

    You get information on the campaign total progress.

    image

    You see a summary of all the update attempts for each device grouped by status:

    • Failed—indicates the number of devices that failed to install at least one software update. For example, a failure may be caused by a format error or low storage capacity. For more details about the failure, see the reported failure code. To get a list of individual devices affected by the failure code, next to the relevant failure code, click the export button (Icon). You can also retry failed update campaigns.

    • Success—indicates the number of devices that successfully installed the software updates.

    • Installing—indicates the number of devices that are still installing one or more software updates.

    • Not applicable—indicates the number of devices where none of the control units or software versions match the targeting criteria of the software update. It can also indicate devices that are now installing software updates from another campaign, or devices where the software update has been canceled.

Troubleshooting

Review the update history of an individual device

At some point, you may need to assist a specific customer who has trouble with a software update on their vehicle. In this case, your customer support team can use the VIN of the vehicle to find the device in OTA Connect. Then, they can inspect an individual device to get more details about the problem.

To see the update history of a device:

  1. Go to the Devices tab.

  2. In the search field, specify the VIN of the affected device.

  3. Click the device.

  4. Make sure the History tab is open.

    On this tab, you can find all the updates that were performed on the device. If applicable, you can also find information on a campaign that sent updates. Note that it is possible to update a single device, so updates do not always have an associated campaign.

    Failed updates are indicated in red with the failure code that the device reported. Once you have solved the issue, to update the device to the desired software version that you initially set in the campaign, perform a single-device update.

image

1. To learn how to configure device IDs, see the developer documentation. Note that the device ID can’t be changed after it’s set.
2. Using the provision.primary_ecu_hardware_id value; see the aktualizr configuration guide.