Reduce update size

When a package gets updated, much of the new data will be the same as the old version of that package. Downloading everything again could be considered wasteful. To reduce the size of these updates, the option to use differential updates for APKs was added in the 16.2 Volta release. For TTPKG the option is available from 16.6 Raphael release.

This functionality is only available for APK and TTPKG files. ZIP files are not yet supported.

Differential updates are a means of reducing the size of the update, which lowers both transfer time and data costs.

Differential packages are created using the VCDIFF data format, as defined in RFC3284 which describes a general, efficient and portable data format suitable for encoding compressed data and/or for differencing data. VCDIFF defines the to-be-updated version of the package as a source of data from which the new target version can be constructed using the delta information in the VCDIFF file.

The procedure for using this method of updating is as follows:

1. Have a copy of the old and the new package available
2. Create a VCDIFF file (differential update) using the old and new packages;
3. Modify the package list to specify a path to the differential update;
4. Install the update on your target devices.

Create differential update (diff) file

A number of tools are available to create diff files, but we advise using XDelta3. It is readily available on Ubuntu and you can find executables for Windows and OSX. It's a fast tool and it produced smaller diff files in our tests; for instance, we've seen 10.1MB APK updates be reduced to 1.5MB patch files, which results in 85% less data transfer.

Use the following on the command line to create the diff file:

xdelta3 -n -A -S none -e -s SOURCE TARGET VCDIFF

SOURCE is the old version of your package; TARGET is the new version of your package (the one you want installed on your devices). VCDIFF is the resulting update file that you need to put on your server and refer to in your package list. We suggest using a .vcdiff extension for these files so it's clear that these are differential update files.

Note: Please make sure to use these exact parameters. XDelta3 has other modes that are incompatible with the Software Updater, which will result in errors when trying to update your device.

An alternative tool is open-vcdiff, which you need to build yourself, that will also create a compatible diff file by using this command line:

vcdiff encode -dictionary SOURCE <TARGET > VCDIFF

In the 10.1MB APK file example specified earlier, open-vcdiff will translate into approximately 83% less network traffic, as the resulting diff file is 1.7MB in size.

Using a differential update file in a package-list

For a non-differential update, you would add your file to a package-list using the path field. VCDIFF files are specified in a field called diff_path.

In order for the Software Updater to know which versions a diff file pertains to, the file path needs to be specified. The two path variables that are used for this are:

{from-version}Will expand to the version number of the currently installed package.{to-version} Will expand to the version number as specified in the version field in the package-list.

For example, you might add something like this to your package-list:

1{
2  "schema": "1",
3  "packages": [
4    {
5      "name": "PackageName",
6      "version": "5.1",
7      "diff_path": "updates/PackageName_{from-version}_to_{to-version}.vcdiff"
8    }
9  ]
10}

If the installed package on the device has version number 3.12, then this will make the Software Updater look for a file named updates/PackageName_3.12_to_5.1.vcdiff on the server, relative to the location of the package-list. If the source package is a different version than the one specified in the version field, an error will be shown, as both the correct source package and the corresponding diff file are required to create the new package.

Note: It is strongly recommended to only use characters 'a'-'z', 'A'-'Z', '0'-'9' , '-' (dash), '_' (underscore), '.' (dot) in any package version field. Any of the following characters in the expanded value of the fields {from-version} and {to-version} are translated to underscores by the "Software update" application: '<' (less than), '>' (greater than), ':' (colon), '"' (double quote), '/' (forward slash), '\' (backslash) , '|' (vertical bar or pipe), '?' (question mark), '*' (asterisk). This restriction is necessary since the expanded field value will be part of a file path and as such cannot contain any special file path characters.

When the diff-path is used, the source package is stored locally on the device in /sdcard/diff-update-sources. Diff updates are applied to the source package, which is then retained for future updates. When the source package is not available locally, the full path needs to be specified in the package-list.

Removing the diff_path field from the package list will result in the stored source package being removed next time a software update is performed. `

In order to take full advantage of the data-saving potential of this update method, it is recommended that path and diff-path fields are specified during initial configuration from SD card or USB attached storage. In this way, the source package will already be available locally and will not be required to be downloaded over a network.

When using differential update files, you need to provide the diff_path. You can also provide the regular path value as a fallback mechanism. There are three possible scenarios: