Update API

As of the 15.6 release, applications can control the update process from start to finish. Any application can trigger the software update to check for updates, start downloading updates and start installing the software at any time.

The device can be reconfigured (called bootstrapping) by an application (16.3 or later only). There are three ways to do this.

To bootstrap the device from SD card or USB attached storage send an intent with action.
```
 com.tomtom.pnd.updater.action.BOOTSTRAP.
```
To bootstrap from a specific file, send an intent with action and an extra string to specify the file path, for example:
```
1final Intent bootstrapIntent = new Intent("com.tomtom.pnd.updater.action.BOOTSTRAP")
2bootstrapIntent.putExtra("com.tomtom.pnd.updater.action.BOOTSTRAP_EXTRA_LOCATION", "/sdcard/example_directory/update-locations");
3sendBroadcast(bootstrapIntent);
```
To bootstrap from a directory, send an intent with action and an extra string to specify the directory path, for example:
```
1final Intent bootstrapIntent = new Intent("com.tomtom.pnd.updater.action.BOOTSTRAP");
2bootstrapIntent.putExtra("com.tomtom.pnd.updater.action.BOOTSTRAP_EXTRA_LOCATION", "/sdcard/example_directory");
3sendBroadcast(bootstrapIntent);
```
In this particular example there would need to be /2/bridge/ subdirectories in /sdcard/example_directory/ (where "2" is the schema version). This is useful when you need to include the certificates that the device needs to be authenitcated by your server.

To check for updates, send an intent with action com.tomtom.pnd.updater.action.SCAN_FOR_UPDATE.

To trigger package download to begin, send an intent with action com.tomtom.pnd.updater.action.DOWNLOAD_UPDATE.

To trigger the installation to begin, send an intent with action com.tomtom.pnd.updater.action.INSTALL_UPDATE.

To abort the update at any stage other than while installing, send an intent with action com.tomtom.pnd.updater.action.RESET_UPDATER. If you abort an update, the updater will become idle and you will need to send the trigger SCAN_FOR_UPDATE to check for updates again. ( Prior to the 16.2 release, the com.tomtom.pnd.updater.action.RESET_UPDATER intent would also delete all the downloaded files.)

There are a number of important points to consider when using this API:

Apps can only bootstrap a device if the "Software update configuration" permission is enabled in the user profile settings.
All other update configurations or restrictions are respected. For example, if updates are only allowed over a WiFi network and it isn't available then the update will fail.
If the user turns on the screen then they will be able to control the update process as normal, superseding any intents that it receives.
The order of sending the actions is fixed: scan, download, then install. If this is not adhered to, you will receive an tomtom.intent.action.ACTION_NOT_ALLOWED result. Bootstrapping can only be done when the software updater is IDLE
This feature can lead to high internet data consumption if used improperly. It should be thoroughly tested with your particular solution to ensure your solution does not lead to excessive data costs.
If the download is less then 40MB it will start immediately. So after sending SCAN_FOR_UPDATE, the app will receive READY_TO_DOWNLOAD followed immediately by DOWNLOAD_STARTED, and finally READY_TO_INSTALL when the download has finished.

In some cases the device should remain silent while it is being updated, for example when a truck driver is sleeping. To mute the device while it performs one of the requests above, add an extra boolean option when sending the intent:

com.tomtom.pnd.updater.EXTRA_SILENT_MODE - true (default value: false)

The device will perform the requested task silently and leave this mode when it is done. Specifically, the TomTom drums at boot time are suppressed.

To be able to receive the responses of the actions, you need to register a broadcast receiver. These are the Intents that are broadcast by the Software updater:

After RESET_UPDATER is triggered

Action - tomtom.intent.action.UPDATER_IN_IDLE

After BOOTSTRAP is successful

Action - tomtom.intent.action.BOOTSTRAP_COMPLETED

After SCAN_FOR_UPDATE is triggered

Action - tomtom.intent.action.SCANNING_STARTED

When the updater is ready to start downloading packages

Action - tomtom.intent.action.READY_TO_DOWNLOAD
Extras -
- com.tomtom.intent.extra.UPDATE_SIZE - long, Size of the entire download.

After DOWNLOAD_UPDATE is triggered

Action - tomtom.intent.action.DOWNLOAD_STARTED

After downloading is completed or when scanning finished while doing updates from SD Card

Action - tomtom.intent.action.READY_TO_INSTALL

After INSTALL_UPDATE is triggered

Action - tomtom.intent.action.INSTALL_STARTED

After installation has completed

Action - tomtom.intent.action.INSTALL_FINISHED

When the device is up to date

Action - tomtom.intent.action.UP_TO_DATE

In case an action cannot be executed

Action - tomtom.intent.action.ACTION_NOT_ALLOWED
Extras -
- com.tomtom.intent.extra.CURRENT_STATE - string, Current state of the Software updater.

When the user has paused downloading via the UI

Action - tomtom.intent.action.DOWNLOAD_PAUSED_BY_USER

When the connection is lost

Action - tomtom.intent.action.DOWNLOAD_PAUSED_BY_CONNECTION

When the device is suspended

Action - tomtom.intent.action.DOWNLOAD_PAUSED_BY_SUSPEND

When the device is low on battery

Action - tomtom.intent.action.LOW_BATTERY_ERROR

In case of an error

Action - tomtom.intent.action.UPDATE_ERROR
Extras -
- com.tomtom.intent.extra.ERROR_TITLE - string, Error title
- com.tomtom.intent.extra.ERROR_MESSAGE - string, Error message
- com.tomtom.intent.extra.ERROR_CODE - string, Error code as specified in the error messages.
- com.tomtom.intent.extra.ERROR_RETRIABLE - boolean, True if action can be restarted. False if action cannot be restarted.

Broadcasts sent when updater runs

Currently the "Software update" application will broadcast three intents to all registered receivers:

tomtom.intent.action.UPDATE_ERROR - Sent when "Software update" application encounters an error.
tomtom.intent.action.UPDATE_STARTED - Sent when an update is started, i.e. when a screen with a progress bar for an update is first shown.
tomtom.intent.action.UPDATE_FINISHED - Sent after UPDATE_STARTED, when a system was successfully updated.

It is possible that UPDATE_STARTED intent will be sent and then device will reboot to install an update. In this case the UPDATE_FINISHED intent will be sent after a reboot, when all updates are successfully installed.