Developer

How to create a configuration

Before copying a configuration to a device you will need to create a configuration you will need to create a configuration for it. You will need to do the following:

  1. Define the packages that need to be installed.
  2. Combine packages logically to create package-lists.
  3. Combine package-lists to create a configuration.

Supported package types

The "Software update" application supports three types of packages:

  • TTPKG - Contains TomTom provided content, like maps, voices and firmware updates. The filename and version to use are stored in the meta-data of the TTPKG.
  • APK - Any APK file. Installation is done by the Android package manager, which the "Software update" application will trigger during the update process. Use the APK's package name and version code.
  • ZIP - Can contain arbitrary files and directories which will be extracted to the root of shared storage, i.e. /sdcard. Use the ZIP file's filename and a version that makes sense to you.

You will not be able to install any other type of file.

Package lists

A package list is a file that contains a list of packages that contains, per package, a unique name, path, and a version. When a user performs an update the installed packages are compared to the package-lists, any differences are rectified so that only those packages in the package-lists will be installed after the update has finished

{ "name": "…", "path": "…", "version": "…" }

This combination defines a single package. It's in JSON format, as are all the configuration files of the "Software update" application.

Be aware that the name is unique for this package and is used as an ID internally.

Please note that the path may not contain "." or ".." and it may not start with a slash.

When the defined version differs from the installed version, an update will be done. This means that you can also down grade a package if so required.

Now you have a list of packages that you want to install and maintain. Likely they can be placed into categories based on functionality or other factors, or you just want one big list. Whichever you prefer, you must list them in one or more package-lists.

A package-list is a collection of packages, plus some optional extra information concerning that particular list of file versions this includes a name for the list, its own version and release notes that inform the user of important changes that come with this list.

Let's look at a simple package-list:

1{
2  "schema": "1",
3  "release": {
4    "title": "Base content",
5    "version": "15.1.01",
6    "notes": "<b>TomTom Bridge</b><br/>Voice: Serena<br/>Map: Europe"
7  },
8  "packages": [
9    {
10      "name": "voices.eng.serena.dri80.sam",
11      "path": "TTS/voices.eng.serena.dri80.sam_20120327_arm.ttpkg",
12      "version": "20120327"
13    },
14    {
15      "name": "europe",
16      "path": "maps/europe_926.5515_arm.ttpkg",
17      "version": "926.5515"
18    },
19    { "name": "music", "path": "hardrock.zip", "version": "2.1.3" }
20  ]
21}

The mandatory schema indicates which schema version is used in this file. As more features are developed, they will only be available in higher schema numbers. This will be indicated with the release that first contains the feature. The current schema number is 1.

The release element is optional and only provides information to the end user who wants to perform an update: a summary of all changes will be shown on screen, which will include anything added to this element. All three sub-elements are optional.

Note that simple HTML can be used in the release notes. Google does not published a list of Android supported tags but you can inspect the source code.

Combine package lists to create a configuration

When your package lists are ready, you can define the complete configuration of your Bridge device by combining them in one update-locations file. This file, stored in the root of /sdcard, is read by the "Software update" application and it will perform all the necessary actions to make each mentioned package have the proper version on the device when the update is done.

For example:

1{
2  "schema": "2",
3  "files": [
4    { "file": "folder_on_sd_root/package-list-example1" },
5    { "file": "nested/folder/package-list-example2" },
6    { "file": "package-list-on-sd-root" }
7  ]
8}

The mandatory schema indicates which schema version is used in this file. As more features are developed, they will only be available in higher schema numbers. This will be indicated with the release that first contains the feature. The current schema number is 2.

The files element is an array of package-lists. These are the package-lists that you want installed onto the device so they should be present on the SD card or USB attached storage, their filenames relative to the root of that media. The path should not start with a slash, should not contain relative parts, i.e. "..", and must end with the package-list filename.

Reference package-lists on a remote server

The "Software update" application can also get the packages itself from a remote location; it just needs to know where to find them. The uris element was added for this:

1{
2  "schema": "2",
3  "uris": [
4    { "uri": "https://server/folder/package-list-example1" },
5    { "uri": "https://server/nested/folder/package-list-example2" },
6    { "uri": "https://server/package-list-on-server-root" }
7  ]
8}

The uris element is an array of URIs that point to package-lists on a server. The "Software update" application will contact the server and get the package-list definition from it. Any packages mentioned in that list are expected to be found relative to that package-list on that server. So a "path": "maps/….ttpkg" will make the software look for that file in the maps directory below the directory where the package-list is located on that server.

Both https and http can be used but we advice to use https because this provides more security and avoids some of the more serious problems which might arise when using untrusted networks.

It's important to know what happens when both files and uris are defined in an update-locations file!

The "Software update" application will first try to obtain a valid configuration from the SD card or USB attached storage, so all package-lists specified under files. If that fails, for example because a package-list is not available or just because there is no SD card/USB attached storage present, it will attempt to obtain a valid configuration from the remote package-lists, so all package-lists specified under uris. The two will never be mixed!

This feature is used for bootstrapping devices (see further down) where the bulk of the content is copied from the SD card/USB attached storage, leaving an update-locations file on the device that will get updates for this content from a remote location once the SD card/USB attached storage has been removed from the device.

"Latest" version and redirection

For remote package-lists you can define paths that point to 'latest' directories to get the most recent release, like this:

{ "uri": "https://server/latest/{hw-id}/music.package-list" }

To ensure that it is always pointing to the latest version, the server will have to redirect the URI to the location that actually contains the most recent version. The "Software update" application will respond to the HTTP/1.1 302 Found status code and use the reported location from then on for this package-list.

For example, if the above package-list URI redirects to https://server/version-10/{hw-id}/music.package-list, all further packages of this list are retrieved relative to this redirected location. So, if music.package-list contains an entry with "path": "music/rock.zip" it will get it from https://server/version-10/{hw-id}/music/rock.zip directly and not try https://server/latest/{hw-id}/music/rock.zip again. This was done to prevent when the redirection was changed while updating.

Updating devices before first use

The software updater can be configured to read updates from an SD card/USB attached storage, a remote server or both sources. If the updater is configured to read updates from both sources then the SD card will always have precedence over USB attached storage and the remote server. If a valid update cannot be found on the SD card or there is no SD card present, then the server USB attached storage will be checked for updates, followed by the remote server if no configuration is found. This allows the same configuration to be created and put on both sd card/USB attached storage and server.

By doing so administrators can update to the latest software/content from SD card or USB attached storage before giving the device to the user, after this point the device will then check via the internet to get the latest version. Or at a bare minimum the administrator can install the security on the device so the user only has access to update the device. Note: It is not possible to receive (partial) updates from an SD card/USB attached storage and a server at the same time.

Large maps and system updates can take up a lot of space (some 6.5GB + 270MB) and performing an update via a remote server might be quite time consuming. It is recommended in this situation to update the content via an SD card/USB attached storage before giving it to the user.

To summarize:

If the TomTom Bridge device is configured to receive updates from SD cards/USB attached storage _ and_ remote servers and the "Software Update" application has been started:

  • The device will first check an SD card/USB attached storage for software updates. If it is available, update from an SD card/USB attached storage will be performed.
  • Otherwise,
  • The device will check a remote server for software updates. If the server is available, the device will be updated from the server.

Example

Let's use the default TomTom configuration from the Releases page as an example. To configure TomTom bridge devices with a default TomTom configuration follow these steps:

  1. Download the latest TomTom Bridge device configuration from the Releases page according to your region.
  2. Unpack the zip archive.
  3. Extract the zip content to the root of an SD card/USB attached storage.
  4. Insert the SD card/attach USB attached storage to a TomTom Bridge device.
  5. Start the "Software Update" application and perform an update.

The latest configuration from the SD card/USB attached storage will be copied and installed on the device.

Now, let's change the configuration to check from SD card/USB attached storage or a remote server:

  1. Copy the contents from the SD card/USB attached storage to your remote server (/boot is not required).
  2. On the SD card/USB attached storage open <zip-root>/boot/2/bridge/update-locations file. For Australia/New Zealand region it should look like: 
    1{
    2  "schema": "2",
    3  "files": [
    4    { "file": "package-list.system" },
    5    { "file": "package-list.content.aus-nz" }
    6  ]
    7}
  3. Modify and save it in the following way: 
    1{
    2  "schema": "2",
    3  "files": [
    4    { "file": "package-list.system" },
    5    { "file": "package-list.content.aus-nz" }
    6  ],
    7  "uris": [
    8    {
    9      "uri": "https://<location of your server>/package-list.system",
    10      "optional": "false"
    11    },
    12    {
    13      "uri": "https://<location of your server>/package-list.content.aus-nz",
    14      "optional": "false"
    15    }
    16  ]
    17}
  4. Insert the SD card/connect USB storage device to TomTom Bridge device.
  5. Start "Software Update" application and perform an update.

The latest configuration will be copied and installed from SD card/USB storage to the device. If the SD card/USB storage is not present, the device will now also be configured to receive updates from the server.

If there is a new version of TomTom software, maps or content after the device has been given to the user, you can simply copy it to your server and make sure that package-list.system and package-list.content.aus-nz contain updated information.

After the new content is copied to the server, the device will receive a notification that a new software update is available for download.

Example: add your custom content to the configuration

Then add your packages to your package-list and the package-list to update-locations and your configuration is customised:

1{
2  "schema": "1",
3  "release": {
4    "title": "<Custom content>",
5    "version": "<any version>",
6    "notes": "<Release notes for users>"
7  },
8  "packages": [
9    {
10      "name": "custom package 1",
11      "path": "<path of custom package including file name relative to this file>",
12      "version": "<version of custom package>"
13    },
14    {
15      "name": "custom package 2",
16      "path": "<path of custom package including file name relative to this file>",
17      "version": "<version of custom package>"
18    }
19  ]
20}
1{
2  "schema": "2",
3  "files": [
4    { "file": "package-list.system" },
5    { "file": "package-list.content.aus-nz" },
6    { "file": "package-list.custom-content" }
7  ],
8  "uris": [
9    {
10      "uri": "https://<location of your server>/package-list.system",
11      "optional": "false"
12    },
13    {
14      "uri": "https://<location of your server>/package-list.content.aus-nz",
15      "optional": "false"
16    },
17    {
18      "uri": "https://<location of your server>/package-list.custom-content",
19      "optional": "false"
20    }
21  ]
22}
  1. Create a text file package-list.custom-content in <zip-root> folder and modify it in the following way:
  2. Place your custom content (zip files or android applications) to the <zip-root>/<path specified in package-list.custom-content>/
  3. Copy the new content together with package-list.custom-content and newly added content to your SD card/USB storage and server.
  4. Open <zip-root>/boot/2/bridge/update-locations file and modify the file in the following way:
  5. Insert the SD card/USB storage in the TomTom Bridge device.
  6. Start the "Software Update" application and perform an update.

The latest configuration (with your custom software) will be copied and installed from an SD card/USB storage to the device. If the SD card/USB storage is not present, the device will now also be configured to receive updates from the server.