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.

Step 1: Provision Some Devices

Before you connect a device to OTA Connect, the device needs some temporary authentication credentials.

You can download these credentials in the form of a Provisioning Key.

You install the key on the device and the device can use provisioning key to get more permanent credentials from the OTA Connect server.

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 to copy the zip file to the file system of your device.

gsimage

The next step is to build and run the OTA Client software on your device.

There are two ways to do this:

Either way, you’ll need to leave the comfort of this user interface for a while and get your hands dirty in the Linux command line.

If your computer doesn’t run a Linux-based operating system, you can download a Linux-based software image and install it in on a virtual machine by using a free tool such as Oracle VM VirtualBox.

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.

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

Step 4: Upload Some Software Versions

Now, let’s upload some software. As with many things in life, there’s a hard way and an easy way.

  • The easy way is to upload software files in the OTA Connect user interface.

    This method is fine if you just want to try out the OTA Connection functionality.

  • The hard way is to locally build a filesystem image that is OTA-enabled and already has your software installed.

    During the build process, the filesystem image (with your new software) is automatically uploaded to the software repository on your OTA Connect server. This method is closer to how software gets installed in production.

    For an example of this method, see the instructions for building a Raspberry Pi image or building a a QEMU/VirtualBox image.

However, since this is a Get Started guide, we’re going to describe the easy way.

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.

  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.

Step 5: Install The First Version of Your Software

Now that you’ve uploaded some software, you should install it on a test device.

  • Installing the first version of software is a different process from updating software.

  • However, we can’t show you how to update software unless the device is already running that software.

To install the first version of your software on a test device, follow these steps:

  1. Open the device details that we first looked at in Step 3.

    • Navigate to the Devices page, select a device group, and select a test device within that group.

  2. Click the primary ECU, and in the SOFTWARE section, locate the software that you uploaded in the previous step.

    • If you uploaded two versions of the same software, you should see a row for each version that you uploaded.

  3. Click the first version that you uploaded.

    • In the right-hand PROPERTIES panel, you’ll see more details about the selected software version — the status should be Not Installed.

  4. Click the Install button at the bottom of the PROPERTIES section.

    • OTA Connect will remotely install the software on your test device.

gsimage

Note that this isn’t the standard way to install new software in production, but it’s a simple way to show you how OTA Connect works.

To see an example of publishing updates in production, see our guide to pushing software updates.

Step 6: Create a Software Update Unit

When you create a software update, you need to define two basic "assignment criteria".

  • The type of ECU that the software applies to.

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

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 Hardware ids, select the ECU types to update and click Continue.

  4. In the next window, define the update criteria for the 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 don’t care what software version the ECU is already running, 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…​

Step 7: Create a Campaign

When you create a campaign, you select the update that you want to deploy and define how you want to deploy it.

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 second step of our Getting Started guide, 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.

    • Click Next.

  4. Select the software 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.

    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. Click Next which takes you to the Summary step, then click Launch.

gsimage

Step 8: 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 the OTA Connect server is waiting until a previous batch of updates has completed.

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 Processed indicates devices that weren’t processed by the OTA Connect server for some strange reason.

Not Impacted indicates devices that were targeted by the campaign by were ignored because they did not 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.

Step 9: 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

Troubleshooting: 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 recall campaign to update the affected devices.

In the short term, you’ll want to prevent anyone else from installing the defective software in another software update. You do this by blacklisting the software.

If you’ve blacklisted some software, you can see how many devices or vehicles are impacted by the defective software.

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