Installing plugins on Android

Overview

All regular Android app installations are done using an APK file. When an APK is installed, Android creates a private (sandbox) area on the device's storage which is accessible only to the installed app. This means it is not possible to deploy a TA plugin in a separate plugin APK, since Trimble Access would be unable to access it from its own private sandbox.

Instead, we use a zip file of the plugin installation placed in the /Trimble Data/System Files/plugins/ folder, and TA will install it into its own sandbox area when it is first accessed by the user.

The installer zip file may arrive in the plugins folder by any means:

• • Downloading the plugin using Trimble Installation Manager, which runs on the Android device. This is the usual customer experience.

  • Placed there manually by a plugin developer. Used for testing and debugging.

  • Loaded on to a customer or in-house device by any other means devised by the developer. Otherwise known as side-loading (as in Android apk side-loading).

Every installer zip file must be paired with a sig file of the same name, such as MyPlugin_arm_v1.02.03.zip and MyPlugin_arm_v1.02.03.sig. The sig file contains a cryptographically strong signature of the zip file to prevent tampering, and is generated online by the plugin submission form. 

To streamline debugging, developers using Scapi may bypass the signing / verification process by obtaining a Scapi development license for the device, from Trimble. 

Trimble Access at startup

• 1. Searches the /Trimble Data/System Files/plugins folder for zip files, examines them, and makes a list of possible installers.

  2. Searches for *.timxml recursively in its private sandbox to locate all plugins that have already been installed.

  3. Matches the two lists. (Each installed plugin has a record of the zip file name it was installed from, to help with this.)

  4. Goes through an intricate process to decide what needs to be installed, reinstalled, uninstalled, or cleaned up.

  5. Deletes all zip and sig files from the plugins directory that do not relate to either an installed plugin or a plugin needing to be installed. Message: Don't leave anything extraneous there, it will disappear.

  6. Completely removes any plugin for which an uninstall file was present.

  7. Continues with the startup. At this point nothing new has been installed.

Reinstallation decisions are based on the plugin version. In the case of identical version numbers between an installed plugin and an installer zip file, installation will always occur on the assumption that the installer zip is a replacement.

Installation when the app is first used

1. The application picker form in TA displays a button for every plugin, whether already installed or available for installation from the plugins directory. Plugins which have no valid subscription (licence) will be visible but disabled (grayed-out).

2. User taps a plugin app button.

   1. If the plugin is not installed, or there exists a more recent installer for the plugin, then it is installed as follows:

      • A valid signature (<plugin>.sig) file must exist and contain the correct RSA signature to validate the corresponding <plugin>.zip file.

      • Any existing installation of the plugin is removed.

      • Installation simply unzips the plugin into an app directory within the Trimble Access private sandbox. 

      • After installation, the installer zip is renamed to <plugin>.installed.zip

   2. The plugin is loaded, initialised, and run.

The installer Zip file

The name of the zip file from the plugin build process should preferably be: <plugin_name>_<platform>_<configuration>_<version>.zip  For example: Pipelines_ARM_Release_v2.0.6.0.zip (or perhaps Pipelines_armv7_release_v2.0.6.zip). 

The name is for identification, uniqueness, and readability, and has no hard formatting rules.

For the zip file to work with Trimble's plugin submission system, every version and configuration must have a unique filename, which is the main reason for including the hardware type and version number.

Note that when the Trimble Installation Manager downloads the plugin to the Android device, there will be two files called simply <plugin_name>.zip and <plugin_name>.sig. This is for internal simplicity. The name itself is unimportant though the .zip and .sig must have the same name. Trimble Access will aggressively clean up multiple installations of a plugin, and keep only the one that is currently installed, or due to to be installed when selected.

The zip file itself contains the usual plugin files (resources, language, and the timxml file), plus the lib<name>.so file, a dynamically-loaded Android library. These files all normally reside in the top-level directory within the zip (in other words, do not include the full directory path).

If the plugin library has other .so dependencies then they must also exist in the zip along with a .dep file of the same name as the plugin library (lib<plugin>.so.dep), containing the library names, one per line in the order they should be loaded prior to loading the plugin itself.

Subdirectories are supported in the zip for resource files, but library files (.so) should be in the root directory in the zip.

After installation, the zip file remains in the plugins directory but is renamed to <name>.installed.zip to prevent it being reinstalled every time. The .sig file remains also. To uninstall a plugin, you can rename the zip file to <name>.uninstall.zip which causes the plugin and all of its installation files to be removed at the next Trimble Access startup. 

Putting a replacement .zip file in the plugins directory will uninstall the previous plugin of the same GUID and install the new one, if the version is equal or greater.

Reinstalling Trimble Access

Trimble Access is configured to delete its private sandbox files when uninstalled or reinstalled (or rather, they are not backed up in the Google cloud). This means a TA reinstall, which will download the TA application but not plugin installers, would not reinstall plugins. When TA starts, it checks for .installed.zip files that do not have a matching installation, and renames any back to .zip - which will get them reinstalled.

Signing the installer zip

To simplify development, any Android device which has a Trimble Scapi developers' license will not require a signature for any installer. If a signature file is present it will be checked and the result (verified, failed, or missing) will be logged in sc.log, and the plugin will be installed and run regardless.

On a device with a normal customer subscription purchased from Trimble, the zip file will be signed by Trimble before downloading via TIM, by adding a second file called <name>.sig, where<name> is exactly the same base file name as the zip file. The sig file contains the plugin version, GUID, and RSA signature. Plugin installation will only proceed on a customer's device if the signature verifies the zip file is correct. 

Plugin signing service

Plugin developers have access to the Plugin submission page used to upload plugins for customer installation. This same service may be used to obtain a valid signature file for a plugin zip. Simply upload the the zip installer file, submit the form, and then download the plugin using the download link on the Applications page. This will download a zip file containing the supplied plugin zip file plus a matching signature file.