Get Started

Quick Start

To get started, it’s good to have an overview of all the steps you need to get your first device up and running with HERE OTA Connect. The following steps are designed to help you get started quickly and understand every step in the update process.

In these instructions, you’ll 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.

Devices

Step 1: Provision Some Devices

To register a device with your OTA Connect account, the device will need an authentication credential that is linked to your account.

You can download this credential in the form of a Provisioning Key.

You can install the key on many devices, and the devices will use it to register the first time they connect. The OTA Connect server will then issue them more permanent credentials, unique to each device, that they will use from then on.

To download a provisioning key, follow these steps:

  1. Open the OTA Connect Portal, open the menu for your user profile and click Provisioning Keys.

  2. On the page that appears, click Add Key, give the key a name and click Add key again.

  3. Click the download button Icon next to your new key and save the zip file on your computer.

You’ll need make sure that zip file is on any device you want to connect to your account.

gsimage

Now you’ll need to install the OTA Connect client on the device you want to connect.

For this guide, we give you a couple of options:

  • If you just want to see what it’s like to use the OTA Connect Portal with a few devices, and you don’t really want to bother with setting up a real embedded Linux device, you can download and run the client on your computer to simulate a real device.

  • If you want to see everything that OTA Connect can do, you should build a complete device device image. That means building a whole Linux system from scratch, but don’t worry—​we’ll take you through the whole process step by step. For this guide, you can either build a virtualized image for QEMU, or build a real image for raspberry Pi.

You can simulate a device on Linux or MacOS, but you will need to use Linux if you want to build an image. Either way, you’ll need to leave the comfort of this user interface for a while and get your hands dirty on the command line.

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

Step 2: Find Your Newly Provisioned Devices

Once you have provisioned your devices, you should see them show up in the OTA Connect user interface.

gsimage

To check if your devices have been provisioned properly, follow this step:

  • Navigate to the Devices page and select the All Devices or Ungrouped Devices menu items.

Because we haven’t created any device groups yet, all your provisioned devices should show up as "ungrouped".

Click the name of a device in the main list to see more details for that device.

Device Groups

Step 3: Group Your Devices

Hopefully you’ve managed to provision a few devices which should now show up in the OTA Connect user interface.

You should practice organizing them into groups, because this is how you’ll organize your vehicle fleet which you move to production.

There have two types of group, but the smart group type is better for organizing large fleets that are constantly changing.

To create a smart group, follow these steps:

  1. Open the Devices tab and click +Add group.

  2. Select Smart Group and click Next.

  3. In the next window, enter a group name and define a filter for your devices.

    A filter helps OTA Connect assign each vehicle to a fleet. Currently, OTA Connect can filter based on characters in the Device ID — this is usually the VIN number of the connected vehicle.

    • To create a filter, select Device ID from the Data dropdown.

    • In the Filter dropdown, select your filter criteria.

      Since every character in the VIN number has a meaning, we could select Has character equal to, enter the letter M, and select in position 10 (the 10th character in a VIN number is usually the model).

    • OTA Connect will tell you how many devices match this criteria.

  4. Assuming you have devices that match, click Create to create your smart group.

    The smart group is "smart" because any new vehicles that register with OTA Connect will be filtered into this group as long as they also match the filter criteria.

gsimage

Software

Step 4: Upload Some Software Versions

Now, let’s upload some software. If you decided to build your own image in Step 1, it will have been 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 some software.

To upload some software, follow these steps:

  1. In the main menu, click Software Repository (this is the OTAConnect software repository).

  2. Click the +Add software button on the top right.

  3. In the window that appears, enter a name for your software, the software version, and in the ECU Types dropdown, select the type of ECU that your software is intended for.

    It’s important to select the ECU type or types, because OTA Connect prevents you from installing software on ECUs that it’s not compatible with. An ECU’s type is configured on the client[1], so if you followed the guide for simulating devices, your simulated devices have an ECU type of local-fake.
  4. Click Choose File, browse for the software file, and click Add to upload the software.

gsimage

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 usually a collection of files to install together. This is especially important for vehicles. To make sure everything is compatible, it’s important to install a bundle of software images on different ECUs at the same time. It’s also useful to group updates so that they can all get done at once instead of having to prompt the driver to install many different individual updates. However, software update can also consist of a single update for a single ECU.

Step 5: Create a Software Update

To create a software update, there are two basic things we need to know:

  • The types of ECU that each image in the update can apply to

  • The specific versions of the images from the software repository that we are going to send

Additionally, we might want to make sure that we only allow a particular update path—​that is, only send the v1.6 update to vehicles that are running v1.5.

To create a software update, follow these steps:

  1. Click Updates, and in the top right, click Create update.

  2. In the window that appears, give your update a name and add a brief description.

  3. In the section Select ECU types, select all of the ECU types to update and click Continue.

  4. In the next window, define the update criteria for each ECU’s current software.

    • If you want to update ECU’s that are running a specific software version only, select the relevant items from the Software and Version dropdowns in the From section.

    • If you want update all compatible ECU types, select the option: Update to my selected version regardless of what is currently installed

  5. Next, define the software version that you want to update to.

    • Select the relevant items from the Software and Version dropdowns in the To section.

  6. Click Save.

gsimage

You might be wondering how to select the vehicle fleet that is supposed to receive this update.

That step is covered when you create a Campaign which we’ll get to next…​

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

To create a campaign, follow these steps:

  1. Click Campaigns and click Create Campaign.

  2. In the wizard that appears, enter a campaign name and click Next.

  3. Select the device groups that you want to deploy the update to.

    • In the Step 2, we showed you how to create a smart group. If you created a smart group for a test vehicle fleet, you can select it here. Otherwise, select a manual group.

    • Click Next.

  4. Select the update that you created previously and click Next.

  5. The Distribution settings step is optional for now, so we’re going to leave it with the default settings. Click Next.

    In this step you can configure the campaign so that end users must consent to the update. You can define your own notification text for the end user to read.
  6. Review all the details of the campaign. If you’re satisfied, click Launch. If you want to change anything, you can go back to previous steps.

gsimage

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, follow these steps:

Click Campaigns and click a status tab.

  • Assuming your campaign is still running you would click the Running tab.

  • If your campaign is a test campaign, it might finish quickly, in which case, you’ll find it on the Finished tab

In the campaign list, click your campaign.

You should see the progress details for your campaign.

gsimage

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

Success indicates the number of devices where the software was successfully updated.

Queued indicates the number of devices that are still waiting to be updated.

  • These devices might be offline, or there might be a previous batch of updates that needs to complete before this one can start.

Failure indicates the number of devices where the update attempt failed.

  • If there are update failures, the campaign details include a breakdown by individual failure code.

  • To get a list of individual devices affected by the failure code, click the Export Icon button next to the relevant failure code.

Not Impacted indicates devices that were targeted by the campaign but were ignored because they didn’t match the criteria of the selected update.

  • A common cause for this status is when the device is not running the same version of the software that is defined in the From criteria of the update.

Canceled indicates updates that were canceled either on the device itself or from the device details page of an individual device.

Troubleshooting

Review the Update History on an Individual Device

At some point you might need to assist a specific customer who is having trouble with the software on their vehicle.

In this case, your customer support team can use the VIN number 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 for an individual device, follow these steps:

  1. Open the device details:

    • Navigate to the Devices page.

    • Search for the affected device by entering the VIN number in the search box.

    • Click the device name to open the device details.

  2. If it isn’t open already, click the History tab.

    On this tab, you can see all the updates that were performed on the device. If applicable, you also see the campaign that the update was associated with. Note that it’s possible to update a single device, so updates don’t always have an associated campaign.

    Failed updates are indicated in red with the failure code that the device reported.

gsimage

Impact Analysis

After you upload and deploy software, you might receive reports that a particular software version has a defect. Eventually, you’ll need to deploy a campaign to update the affected devices with a fix.

If you already know the specific images that have the defect, you can simply target an update to all vehicles running those images. But even if there is a defect in a particular library or software component and you aren’t sure which images are affected, OTA Connect can help. The Impact Analysis tab lets you blacklist individual libraries or software packages within an image, and then see which devices are affected, letting you monitor the incident until you have rolled out a fix across your whole fleet.

To blacklist a piece of software, follow these steps:

  1. Navigate to the Devices page.

  2. Search for a device that you know is running the defective software and open the device details for that device

  3. In the HARDWARE section, locate the primary ECU and click the info icon Icon.

  4. In the window that appears, click the Packages tab and use the search box to filter for the defective software version.

  5. Click the blacklist icon Icon next to the version number.

To see the impact of blacklisted software, open the Impact analysis page:

  • In the left-hand pane, you can see the total number of devices that are running the defective software package.

  • The main graph shows you the proportion of devices running the blacklisted software package in relation to all devices running any kind of blacklisted software.

  • For example:

    • Suppose that you have 18 devices running the blacklisted software "IVI-Bluetooth_V2-1".

    • In total, you have 33 devices running some kind of blacklisted software.

    • That means, out of all the devices that are running blacklisted software, 54% are running the blacklisted software "IVI-Bluetooth_V2-1".

gsimage

1. Using the provision.primary_ecu_hardware_id value; see the aktualizr configuration guide.