Installing plugins on Windows

Installation overview

Please remember the Trimble Visual Studio project creation wizard can create an installer for your plugin and it is recommended that you use this option.  It is much easier to customize a working installer than to build your own from scratch. In most cases, the installer should "just work out of the box", though you will probably need to add your resources (e.g. images) to the the installation.

The installation workflow in Trimble Access is performed by the Trimble Installation Manager (TIM) software.  This software uses the serial number of the PC or controller to obtain license details to determine what Trimble software should be offered for installation.

It then determines what versions are installed and what needs to be updated.  The installs are then sequentially downloaded and installed.

The Scapi plugin build process runs NSIS which uses a .nsi (text) file to produce an .exe installer file. TIM will download and run that file on the target device to install the plugin. If the Trimble Visual Studio wizard is used to create the project, the build will be already configured to create the installer which greatly simplifies the process for the plugin programmer.  For more detail about the installation process, read on.

In more detail

The plugin installer places the plugin DLL, the .timxml file, and all other related files (such as image resources, a translation .tdb, help content) in a directory named to uniquely identify the plugin.  Multiple plugins should avoid sharing the same directory. It is possible to put each in its own directory along with support files such as language translations and resources. Plugin directories must be located under the c:\Program Files\General Survey\Plugin\companyName\pluginName\ folder (or the equivalent in your language).

Things to note when writing or modifying install scripts:

• All installs use the freeware NSIS scripted install system.  You can extend and customize these installers. 

  • Note that for installation on Android devices, the install is a zip file which will be created by the build in a similar manner. Please see the relevant Android Installation page for details.

  • The Trimble Access emulator supports the installation of multiple versions of Trimble Access and has a slightly different install location to that used for dedicated customer platforms which can have only one version at a time.

  • TIM runs with elevated privileges to enable spawned installers to write to protected locations such as the registry's HKLM and the Program files folder on Windows.

  • TIM installs for All Users always; be aware that per-user settings are not necessarily available. 

  • TIM expects installers to run silently, installers provide basic UI which TIM will discourage with the silent command line switch.  This does not mean you cannot perform necessary UI but please keep such 'interruptions' to a minimum.

  • TAIM finds installed versions of software by retrieving version information from the file specified by a pre-known registry key.  This is set up by Trimble when adding an install to TIM and is currently not available to API developers - Trimble will set this up when evaluating product acceptance.

  • The version number TIM uses is obtained from the .timxml file. The version should be updated for every new release.  TIM will only overwrite an installed plugin if the new version number is higher.

  • The installers do not support Unicode.  Trying to install a registry key string that requires a unicode representation will not work correctly.

Registry

In HKLM "Software/Trimble Mobile/Applications/YourPluginName"  the following name-value pair is created:

• timxml

  • Contains a string, the full path to the .timxml file in your installation folder. This file describes your application, and is used by the Trimble Installer (TIM).

The YourPluginName part of the key should be well named as you will share the containing key with all other products.  Consider making your company name part of it - it is not displayed to the user.  Your uninstall should remove the key you created, only remove the shared host keys (e.g.: 'Applications') if they are empty.

Launcher Icons

The Icon system is greatly simplified from earlier versions.  When presenting your application on the Trimble Access apps picker form, you will need an icon for the plugin's button.  This icon should be a png file with a transparent background so that selection colors will show through. Size is not crucial, but 96 x 96 pixels is good. 

Supply a .png file, installed in the same directory as the timxml file. For the filename use the plugin name followed by .png, which should be the same name as given in the .timxml file (which is supplied by the scapi.props MSVC properties file).

Product Name

The translated product name should be included in the translations (.tdb) file with a token name of ProductFullName. The name will be presented to the user in the correct language or as the plugin name if no translation is available.

Multiple plugins

It is not uncommon, especially during development, for Trimble Access to find multiple copies of an identically named plugin DLL when initializing.

This is usually caused by having a development version available to Trimble Access at the same time an installed copy of the plugin is available in the Program Files area - this is a natural result of developing your plugin and then testing the installer on the development machine.

When this occurs, TA will present a dialog to the user allowing the user to select which file to use: the development copy or the installed copy.  For convenience there are options which allow all such conflicts to be similarly resolved for the rest of the load.

If differently named plugins have cloned tsc_Application instances (by renaming a copy of an existing plugin for example) then this conflict will not occur.  Instead the duplicate will be detected at registration time within the code.  In all cases look at the sc.log file to get more information.