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:

1{
2  "name": "system-update",
3  "path": "https://server/latest/{hw-id}/system-update-314.ttpkg",
4  "version": "3.14",
5  "reboot": "true"
6}

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.

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:

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    { "name": "PackageName", "path": "packagename.apk", "version": "10" }
21  ]
22}

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:

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

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:

1{
2  "schema": "2",
3  "files": [
4    { "file": "folder_on_sd_root/package-list-example1", "optional": "false" },
5    { "file": "package-list-on-sd-root", "optional": "true" }
6  ],
7  "uris": [
8    {
9      "uri": "https://server/folder/package-list-example1",
10      "optional": "false"
11    },
12    { "uri": "https://server/package-list-on-server-root", "optional": "true" }
13  ]
14}

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:

1{
2  "schema": "2",
3  "files": [
4    { "file": "latest/{hw-id}/default/package-list", "optional": "false" }
5  ],
6  "uris": [
7    { "uri": "https://server/specific/{muid}/package-list", "optional": "true" }
8  ]
9}

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.

Special packages

Starting with 18.4, a new key "special_packages" has been added to the package-list format, the behavior of the key "packages" has been left unchanged; this means that the list cannot be empty even if "special_packages" is present. The list of packages in "special_packages" will be treated in a similar way to the ones included in "packages", the difference is that if a package type cannot be handled by the Updater because the Updater's version doesn't support it, the package will be ignored; an unsupported package type in "packages" will cause the update to fail instead.

Runtime permissions whitelist

A runtime permissions whitelist package can be included in the "special_packages" list, an example of the package is:

1{
2  "name": "always-grant-permissions-upon-request",
3  "path": "runtimepermissionswhitelist.txt",
4  "version": "version 123"
5}

"name" must have the value "always-grant-permissions-upon-request" in order to be detected as a runtime permissions whitelist package. "path" will behave in the same way as other packages and must be the path of the whitelist-file relative to the package-list file, the file can have any name and extension. "version" must be a string that indicates the version of the whitelist, it can be an arbitrary value and it will be used to determine if the currently installed whitelist needs to be updated or removed. If the whitelist package is not included in an update configuration, the whitelist installed on the device will be removed. If the version of the whitelist provided in the package-list is different from the one installed on the device, the update will replace the installed whitelist with the one provided by the update. The format of the whitelist file is NOT validated upon installation. An example of a package-list defining a runtime permissions whitelist package:

1{
2  "schema": "1",
3  "release": {
4    "title": "System Update",
5    "version": "18.520.1179.033e0e4.135",
6    "notes": "This update will trigger a reboot."
7  },
8  "packages": [
9    {
10      "name": "system-update",
11      "path": "system-update_18.520.1179.033e0e4.135_all.ttpkg",
12      "version": "18.520.1179.033e0e4.135",
13      "reboot": "true"
14    }
15  ],
16  "special_packages": [
17    {
18      "name": "always-grant-permissions-upon-request",
19      "path": "runtimepermissionswhitelist.txt",
20      "version": "2"
21    }
22  ]
23}

For more info about the format of a whitelist package file, please check the additional features documentation.