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.
- To bootstrap from a specific file, send an intent with action and an extra string to specify the file path, for example:
final Intent bootstrapIntent = new Intent("com.tomtom.pnd.updater.action.BOOTSTRAP"); bootstrapIntent.putExtra("com.tomtom.pnd.updater.action.BOOTSTRAP_EXTRA_LOCATION", "/sdcard/example_directory/update-locations"); sendBroadcast(bootstrapIntent);
- To bootstrap from a directory, send an intent with action and an extra string to specify the directory path, for example:
final Intent bootstrapIntent = new Intent("com.tomtom.pnd.updater.action.BOOTSTRAP"); bootstrapIntent.putExtra("com.tomtom.pnd.updater.action.BOOTSTRAP_EXTRA_LOCATION", "/sdcard/example_directory"); sendBroadcast(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
To trigger package download to begin, send an intent with action
To trigger the installation to begin, send an intent with action
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_ALLOWEDresult. 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_DOWNLOADfollowed immediately by
DOWNLOAD_STARTED, and finally
READY_TO_INSTALLwhen 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:
- 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
After BOOTSTRAP is successful
After SCAN_FOR_UPDATE is triggered
When the updater is ready to start downloading packages
long, Size of the entire download.
After DOWNLOAD_UPDATE is triggered
After downloading is completed or when scanning finished while doing updates from SD Card
After INSTALL_UPDATE is triggered
After installation has completed
When the device is up to date
In case an action cannot be executed
string, Current state of the Software updater.
When the user has paused downloading via the UI
When the connection is lost
When the device is suspended
When the device is low on battery
In case of an error
string, Error title
string, Error message
string, Error code as specified in the error messages.
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:
- Sent when "Software update" application encounters an error.
- Sent when an update is started, i.e. when a screen with a progress bar for an update is first shown.
- 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.