Introduction

For the truly desperate, scroll down to Building a plugin - the quick version.

A high-speed tour of the premises

We call it SCAPI. You write a library (a.k.a. app, or plugin) in C++, register it with Trimble Inc. and a user buys a license to use it.  When the user installs and runs Trimble Access (TA), they will find a new icon - your application's icon - on the Trimble Access applications page, along with Roads, Tunnels, General Survey, and other plugin apps.

The user clicks the new icon - your icon - and, well, nothing visual happens. Except that a new main menu is now present - your menu - with a collection of new things that they can do with the features supplied by your application.

Your application has access to almost all of the functionality of Trimble Access, with varying levels of control. Some functionality is supported only to the level of the ability to run it. That is, anything that appears on the main menu of General Survey, Roads, Tunnels, and Mines can be launched programmatically.

Other parts can be controlled in great detail, for instance in the calculation of coordinates, measuring points, performing station setup, stakeout, and so on.

An application can run on both Android and Windows devices. There is no 'porting' as such, the app just has to be be built separately for the two environments, and arguably the biggest barrier to get over is installation of all the tools required to build your app.

Trimble Access is installed using TIM, the Trimble Installation Manager. TIM also installs the SDK used to develop plugins, and it can install the plugins that you write, on customers' devices. There's a Trimble web site where you can upload your plugin and make it available to customers to install alongside Trimble Access, using TIM.

The Trimble Access SDK

The Trimble Access Software Development Kit (TASDK) is installed using the Trimble Installation Manager (TIM). The SDK consists of a collection of header files and a set of statically-linked libraries which implement the functions in the header files. Much of the static library part simply calls the implementation in the main Survey Core executable. The SDK is only available to appropriately licensed developers.

Libraries are available for all supported target platforms - Android or Windows, 32- or 64-bit, release or debug.

How it all hangs together

On Windows you build a DLL (.dll) and an NSIS installer package. For Android you build a dynamic library (.so), and a ZIP installation package. That is the main difference, most other things are common between Android and Windows to the extent that the exact same application source code will run on both - provided of course that your plugin isn't doing something platform specific. There is nothing platform specific in the API.

As well as the library (.dll or .so) a plugin will also need some support files to be installed on the target device. There's an xml file (<pluginName>.timxml) that tells the Trimble installer and the plugin loader what's to be installed, what it is called, the version, and other necessary information. There's also the usual collection of image files that every application needs, and there's a language translations xml file (<pluginName>.tdb). And that's about it. Any other files your application needs may easily be added to the installation.

To keep Windows and Android installations the same, we don't directly support resources in the windows dll like we once did, but if you want to use that feature then it is possible to do using the Windows API. However, this will not work on Android, so we'd discourage doing that.

Updates

So what happens when Trimble Access (TA) is updated and a new version is released?  For you and your Scapi app, usually there's nothing that must be done. We've designed the API to maintain backwards binary compatibility with plugins, so unless something huge comes along (such as when we upgraded TA from 32- to 64-bit), all the old plugins will just keep on working with the new release of TA.

You may have to do some work to support new devices and new functionality as it comes along. This will require a shift to the latest SDK version, and you should branch your source off from your previous version(s). Those previous versions will remain in use and available for installation until all users have migrated to later versions of T.A. (which, actually, is quite difficult to determine). It is prudent to keep and maintain all previous release sources and builds in case of problems. Trimble installation servers can store multiple versions of a Scapi app, and for any given installation will offer the user the highest compatible plugin version that is available for their device and TA version.

Versioning

The TA name and version number always increases numerically. TA comes in a package with a version number such as 2023.11 which applies to the entire package. Inside the package the main executable program, which we call Survey Core or SC, or Survey.exe, has the same version but without the '20' on the front - and sometimes with a build number on the end, so in TA version 2019.11 the SC build version might be 19.11-123 or similar. The API carries the same version number (19.11)  but we don't often bother with the build number once it's been released.

The Development toolchain

Microsoft Visual Studio C++ is the standard IDE for development of Trimble Access. Accordingly, plugin development also uses MSVC for both Windows and Android environments. At the time of writing (since version 23.10) we are using MSVC 2022 plus the continuing stream of updates that Microsoft roll out.

We also use a development framework called Qt. That's for all our UI and a few other purposes such as dealing with images. We don't use the Qt event model in TA code - we have our own that was invented a long time ago and the application is thoroughly marinated in it. This has some implications for plugin writing (like, we use a lot of threads for UI) but mostly that gets handled as though by magic. Anyway, the requirements of Qt are taken care of by TA, and a plugin developer will rarely need the Qt environment to build a plugin. If you wish to use Qt features, then it is possible but you'll need to obtain your own Qt licence and install Qt on your development machine.

Another part of the puzzle is developing for Android. There is some information currently being written (as at October 2023) and we're working on that. For Windows, you just need MSVC of the appropriate version to match the TA version, which you can determine from the version table on the home page.

Building a plugin - the quick version

So if you are ready to start, what's next? In a nutshell, you'll need to do these things:

1. The following steps are the brief ones. For a more detailed version, see here. Note that "TA" is often used here to denote Trimble Access.

2. Get TIM for your Windows PC. That's a program available from trimble.com, the Trimble Installation Manager - run it and it'll tell you your machine's serial number.

3. Get licensed. You'll need to contact Trimble for that, and supply your Windows 10 or 11 development computer's serial number from (2).

4. With a serial number and your Trimble contact you can get a subscription for your computer. When that is done, run TIM which will list what you need including the Survey Core API (Scapi) SDK.

5. Pick a TA version from the dropdown (upper right). You can use any of those available, but avoid anything before version 20.10 unless you're specifically targeting some old version. If you are targeting an old version, you should be using the older Developers' Guide for that version, not this one. Plugins will generally work with any version of TA greater or equal to the SDK version used to build the plugin, with the exception of some major updates prior to version 20.10.

6. Check which version of Microsoft Visual Studio you need (see version listing on the home page of this site), and install it. NOTE: If you might require an older version of Visual Studio, install that one first. Older versions of MSVC installed after a later version have caused problems in the past.

7. Install Trimble Access and the Scapi SDK on your development machine using TIM. You'll need to tick the checkboxes for General Survey (Emulator), Survey Core API, a language pack you can understand, and anything else you might need. You will only see software you are licensed for, so if anything is missing, talk to Trimble about your licence (or more correctly, the subscriptions in your licence).

8. That's about it for installing - for Windows at least. Fire up Visual Studio and let's get started. 

9. Note that it is possible, and generally much easier, to do your plugin testing on your Windows development computer. If a plugin works there it will most likely work much the same on all supported devices.

10. We ship a Visual Studio project template along with the SDK. Find that in MSVC menu: File → New → Project → Search for trimble (but don't press Enter).

11. You should find "Trimble Access Plugin Application". These should have version numbers but some older ones don't. If the version you need is not shown and there's more than one without a version number, you'll have to experiment. We are displaying the version number in this list starting with the 2020.20 release.
    Note that deploying a plugin that uses an older version of the SDK will allow that plugin to run with the same older version of Trimble Access, as well as later versions. This should be true for future versions too, but cannot be guaranteed.

12. Highlight the Windows template for the platform and version you want to use and click Next. 

13. Give your plugin a name but be careful, this name ends up in many places and changing it usually means starting again with the project template. Once again, experiment - there is no downside to having dozens of trial plugin projects, they can be easily deleted. 

14. Click Create and you'll get a project for the Hello World application. Yes we know, highly original.

15. Choose the Debug x64 configuration and it should build and run (on Windows at least, Android needs more effort).

16. Note that the debug build will automatically "install" your plugin in a folder on your PC in the folder: \Users\<user>\AppData\Roaming\Trimble\Trimble Survey Core API V24.00 Plugins\<yourFolder>
    Trimble Access will be able to find it there. The version number will vary, of course.

17. Modify the Hello World until it becomes your app. You will need to stop calling it Hello World at some point.

More details - configure, build, deploy

The scapi.props file

Central to configuring the build for a plugin is the scapi.props file. It's a low-tech control panel in the form of an XML file. You could edit it by hand but you'll find a reasonable GUI in MSVC by opening the Property Manager (not the Properties window or pages), which is found in View → Other windows → Property Manager. Open the plugin project and look under Debug or Release - it doesn't matter which, they both lead to the same scapi.props file. 

Adjusting the various settings mostly happens in the User macros property page, selected using the navigation on the left. The settings on the property page are fully described here.

You can change the version of SDK you are using by changing the SDK version macros. Big version shifts are better done by creating a new project and shifting all your files across but in general, just tweaking these numbers will work; check out the release notes to decide. You must first have installed Trimble Access and the SDK for the version you are targeting.

The <pluginName>.timxml file

The <pluginName>.timxml file describes your plugin for the installer, and is generated automatically from information in the scapi.props file when the project is built. It is used by the installer and by TA to handle your plugin correctly. In particular, keep incrementing your plugin version number (though not necessarily for every build) in the scapi.props file. When you come to installation testing and release, this number is important, and must increase for each public release. You can make your own decisions about how to use the version numbers, so long as they go upwards. It is prudent to use two-digit numbers in versions, since a version like 5.1.0 is ambiguous - it could be 5.10.00 or 5.01.00.

When Trimble Access is run on Windows, it searches in \Program Files\Trimble\General Survey\Plugin (or the equivalent in your language) for timxml files. It also looks under your user AppData folder (see below). Any timxml file it finds is treated as a potential plugin. TA expects all installed files for a plugin to be located relative to its timxml file. Only plugins for which a user is licensed are loaded and appear on the TA applications page. As a developer, you will be able to see and run every plugin that TA finds, regardless of licenses.

Windows installation

When you build a release configuration, an installation .exe file is also built. If you have extra files to be placed into the installation (or other) folders then the NSIS installer script will need to be adjusted (the <pluginName>.nsi file). In both builds, the files required to run the app are copied to an app test directory, and this is done in the post-link build event. If you add your own files, you will have to add copy steps for these files as well.

On Windows, plugins are normally installed within the plugin directory which is in the same directory as Survey.exe, which is found in in \Program Files. While developing a plugin, this directory is difficult to use because of its security settings, so additionally TA looks for plugins in the following location:
C:\Users\you\AppData\Roaming\Trimble\Trimble Survey Core API Vxx.yy Plugins\companyName\pluginName\<files>

This is where the post-build event copies them so they can be easily tested. This directory may get filled with many old test plugins, so give it a clean-out periodically or it can cause problems running TA.

Android installation

You'll notice how we skirted around Android. Time to address that now. As mentioned above, an Android plugin should be identical to a Windows one in the source code, provided you don't access any platform-specific functionality outside of the Scapi SDK.

We still use Microsoft Visual Studio for editing and building, but with a completely separate project that builds the required zip file for installation.

The toolchain is different - underneath Visual Studio it's the Clang compiler and the Android NDK (C++ native development kit). Getting all that installed and working might be the biggest (or only) challenge for getting Android plugins to work. The smaller screen sizes can be difficult but our Qt-based UI layer plus the work by some clever people has taken much of the pain out of that.

To build an Android version, use the Project Template as described for Windows but choose the Android template. After the project is created, copy the file scapi.props from your plugin's Windows project - this will ensure you have the correct configuration and GUID.

Plugin installation for Android is another challenge. Because an APK gets installed into its own isolated "sandpit", there is no easy way to install a plugin that way and still be accessible to Trimble Access, and so they are instead installed as ZIP files. The zip file simply contains all the files required by the plugin, without absolute directory names (relative sub-directories are ok). On Android, the plugin's zip file is downloaded by the Trimble Installation Manager and stored in Trimble Data/System Files/plugins/.  The plugin is not installed until the user launches the plugin application in Trimble Access for the first time. 

For security, the plugin must be signed with an RSA signature which we place in a .sig file along with the plugin zip file onto the device, by means of the Trimble Installation Manager. The signature is checked at the time the plugin is installed, before any unzipping occurs. The .sig file is generated automatically when the plugin is uploaded to Trimble servers, and the secret key is known only to the signing proces on the server.

For testing on Android, you can either use the Trimble plugin upload site to create the .sig file, or (much simpler) have your Trimble representative generate a TASDK development subscription (license) for the device which allows any valid plugin zip file to be installed, with or without a .sig file.

That's about it for the quick intro, although it wasn't all that quick. Good luck.