Sorry, you need to enable JavaScript to visit this website.

Configuration options

When a reboot is required after installation

Sometimes a package requires that the device is rebooted after installation. You can specify this with each package that requires it, for example:

{‬ "name": "system-update", "path"‬:‭ "‬https://server/latest/{hw-id}/system-update-314.ttpkg", "version": "3.14", "reboot": "true"‬ }

This will reboot the device after it has successfully installed the system-update-314.ttpkg package, after which it will continue with the update process. This means that you can specify as many reboots as required, the update process will pick up where it left of after the reboot to finish the entire update.

Note that if a package was already installed, no reboot is performed.

Exclude packages from other package lists

Sometimes you will be dependent on a package-list that includes a package that you do not want on your device; for example an annoying voice or a package that clashes with something else you want to install. You can exclude it from your configuration with:

    { "name": "PackageName", "path": "…", "version": "…", "exclude": "true" },

The exclude attribute, available from schema 1 onwards, informs the "Software update" application to ignore any previously listed package named PackageName. This means that the order of package-lists in your update-locations file becomes important. If another package-list lower down adds another version of PackageName, then that version will still be installed!

Let's clarify with an example. The following table will show you how a configuration is set up by highlighting the changes to it for each package. Bold means that this package was added to the overall configuration, strike through means it was removed from the overall configuration.

Package Name Exclude Configuration step-by-step
package-list-A package-1   package-1
  package-2   package-1, package-2
  package-3   package-1, package-2, package-3
package-list-B package-4   package-1, package-2, package-3, package-4
  package-3 true package-1, package-2, package-3, package-4
package-list-C package-5 true package-1, package-2, package-4
  package-6   package-1, package-2, package-4, package-6
  package-3   package-1, package-2, package-4, package-6, package-3

Now, if the device was set up to only use package-list-A, then the configuration would consist of package-1, package-2 and package-3. If we add package-list-B after it in our update-locations file, the configuration becomes: package-1, package-2 and package-4. You will notice that package-3 is no longer part of the configuration. If we put this update-locations file onto a device, package-3 will not be installed; the second package-list has excluded it from the configuration.

If we decide to add package-list-C as the last list of our update-locations file, then the configuration is: package-1, package-2, package-4, package-6 and package-3. Notice that package-3 is now back in the configuration and if this update-locations file was put onto a device, package-3 will now be installed.

So the order of the package-lists is important when trying to exclude a package from a previous package-list.

Externally managed packages

In case if you need to manage a package yourself, you can mark any package in your package-list with the "externally_managed" option:

    { "name": "PackageName", "externally_managed": "true" }

The externally_managed attribute, available from schema 1 onwards, informs the "Software update" application to do nothing with the package named PackageName.

Let's assume that we have installed application PackageName with version 12.

    { "name": "PackageName", "path": "/path", "version": "12" }

Then we have to update packages on the device with the following package-list:

{
    "schema": "1",
    "release": {
        "title": "Base content",
        "version": "15.1.01",
        "notes": "<b>TomTom Bridge</b><br/>Voice: Serena<br/>Map: Europe"
    },
    "packages": [
        { "name": "voices.eng.serena.dri80.sam", "path": "TTS/voices.eng.serena.dri80.sam_20120327_arm.ttpkg", "version": "20120327" },
        { "name": "europe", "path": "maps/europe_926.5515_arm.ttpkg", "version": "926.5515" },
        { "name": "music", "path": "hardrock.zip", "version": "2.1.3" },
        { "name": "PackageName", "path": "packagename.apk", "version": "10" }
    ]
}

After updating, the device will have package PackageName with version 10 installed.

If you want to tell the Updater to not touch the existing PackageName with version 12, you'll need to create new package-list in your update-location. For example:

{
    "schema": "1",
    "packages": [
        { "name": "PackageName", "externally_managed": "true" }
    ]
}

To install the packages you can use the normal Android mechanism check Install Application programmatically on Android on stackoverflow.

Optional package-lists

Package-lists can be made optional, which means that when the "Software update" application cannot find the specified package-list it will silently ignore it. For example:

{
    "schema": "2",
    "files": [
        { "file": "folder_on_sd_root/package-list-example1", "optional": "false" },
        { "file": "package-list-on-sd-root", "optional": "true" }
    ],          
    "uris": [
        { "uri": "https://server/folder/package-list-example1", "optional": "false" },
        { "uri": "https://server/package-list-on-server-root", "optional": "true" }
    ]
}

Note that using the optional attribute requires schema value 2 and above. This configuration will install everything except the second file and the second URI. These will be looked for and only when they are found will they be installed. If they are not found they will simply be skipped and the update will still be successful.

Package-lists that are not optional and cannot be found will result in an error.

Special path variables

When defining your update-locations there are a few special variables you can use when defining the paths to your packages. They can help in getting certain content onto a specific device, even when the device is not physically available. These variables will be expanded:

{muid}
The MUID of the device. This is the serial number which can also be found on the sticker on the bottom of the device. Property ro.serialno.
{hw-id}
The hardware identification string of the device. Currently only bridge.
{dcp-id}
The digital content protection identification string from the factory data of the device. See also Map Region Code further down. Property ro.dcpid.
{hw-sku-id}
The first two characters of the MUID, which indicate a hardware SKU.
{sw-sku-id}
The software SKU identifier of the device. Property ro.product-specialization.

Consider this:

{ 
    "schema": "‬2",
    "‬files": [‬
       ‭ { "file": "latest/‭{‬hw-id‭}‬/default/package-list", "optional": "false" }
  ‭ ‬ ],‭
    "‬uris": [
        { "uri": "‬https://server/specific/‭{‬muid}/package-list", "optional": "true" }
    ‬] 
}

The file points to a subdirectory latest on the device's SD card/USB connected storage that contains directories for each hardware type. This package-list has to be there, otherwise the update will fail.

The URI points to an optional package-list on a server. If it exists, the packages in that list are updated on the device. This is convenient to get specific content on a certain device with its next update. This can be used in certain situations but in general its use is discouraged because it leads to differences in configurations and this can lead to hard to analyze problems on one specific device.

Controlling the frequency of update checks

This can be set by adding the following to update-locations:

	"update_scan_interval": "m|never"

Example (check every 2 minutes):

	"update_scan_interval": "2"

Where m is the number of minutes between checks. A value of never will disable automatic update checks. If not specified update checks will run every 60 minutes. Any other value will result in an error.

Important: Update checks consume data and put load on the server so it's important to test the setup chosen for your solution.