Setting up the development environment

Comprehensively revised for Trimble Access v20.10 on 1st August 2020. Updated May 2021. Updated April 2024.

Microsoft Visual Studio (MSVC)

The SC API requires Microsoft Visual Studio Professional Edition (otherwise known as MSVC or Visual Studio). The recommended version number varies with the TA release version and can be found in the list about half way down the front page. You also need to have the correct MSVC toolset version installed, as well as the NDK if you are also developing for Android devices. The SDK installation should already contain the appropriate MSVC toolset for Windows, although it was missing from version 2023.10 and several earlier releases.

It is possible that other recent versions of MSVC will work, and it is possible that other brands of C++ compiler will also though none have been tested;  the Visual Studio templates and samples are configured for the listed MSVC version given for the installed TA version.  Editions other than the Professional Edition may also work.  You will need to have the C++ compiler component of MSVC installed to cater for the Plugin code and the SDK. Whatever version of MSVC is used, the toolset version that matches the SDK must be installed.

The Trimble Access SDK consists of this documentation, a directory containing the library and header files, a set of runnable sample applications (plugins), and some Visual Studio Project templates to help get you started.  The project templates create a complete and runnable "Hello world" application using the Visual Studio New Project wizard; we strongly recommend you start your application development in this way.

The API is currently supported only on Windows 10 and 11 for both development and the target device. 

Windows CE (a.k.a. Windows embedded) is no longer supported.

Android has basic support from SCAPI version 20.10, and full support from v21.10, but please see the separate setup page for this.

Installation and SDK directory structure

Run Trimble Installation Manager (download from here) to install the version of Trimble Access you wish to develop with. Be sure to choose the Survey Core API component. If anything you require does not appear in the downloads list, please check with your Trimble representative that your computer is correctly licensed and all necessary subscriptions are in place. Note that a device with a SCAPI Development subscription will run any plugin with or without a specific subscription for that plugin.

The SDK installation will place all the files required to create a TA application into the folder chosen at installation time.  The default (and recommended) location for this is C:\Program Files\Trimble\Trimble Survey Core API vx.yy\  This location may vary in name (but not structure) on computers localised for languages other than English.

The sample applications are zipped with the correct directory structure for building them. You can either use the MSVC New project wizard, or unzip the one(s) you wish to build into a suitable development location.  Many of the sample apps are for older versions of the SDK. In general the code will work however they are not routinely kept up to date and many do not build correctly.

The API is not particular about file paths for development, provided they are configured correctly in the project properties.  

The structure of the SDK installation is shown below:

\Program Files\Trimble\Trimble Survey Core API vx.yy\
    Docs
        Documentation files
    Include
        SC API Header files
        SC API Library files
    Samples
        Sample application projects (zipped)
    Tools
        Utility programs 

New project templates

An MSVC New project template is a specialised zip file containing all the files required by MSVC to create a new SCAPI project. When you use the File -> New -> Project... menu item in Visual Studio, you can choose a template and enter a project name and location.  Note that for reasons known only to Microsoft, the plugin templates do not appear in the C++ filter. We suggest you simply type Trimble into the search box. Occasionally this does not work either and MSVC needs to be encouraged to scan the templates folder. One way is to change the folder location and save it, then revert it back to the original. The folder location setting can be found here:

MSVC ➽Tools menu ➽ Options ➽ Projects and Solutions ➽ Locations : User project template location

The SDK installer puts the project templates into the following directory, where MSVC will find them. The version number will change for each release, and multiple versions are allowed (remember that a given version of the SDK will create plugins runnable on that version of Trimble Access, and higher):

\Users\<username>\Documents\Visual Studio 2022\Templates\ProjectTemplates\Visual C++ Project\Trimble Access SDK v24.00\<templateName>.zip

It is possible to customise the templates by editing the files within the zip, though it is advisable to make a copy and edit the copy, to avoid being replaced by subsequent reinstalls or uninstalls. The Visual Studio website has details (search for Visual Studio 2022 Project Templates).

When you choose the New project template and some information is filled in on the form, Visual Studio unzips the template into the chosen location, renames files and substitutes some values within the files, and opens the resulting project ready for you to start development. With only a few configuration steps and no further effort, the application should be able to be built, debugged, installed, and run.

Do not open the project in the zip file. Doing so will make it useless as a template project; it must be edited by hand.

Creating a new project, and selecting SDK versions

We strongly suggest you use the supplied Visual Studio project wizard which will create a functionally complete Trimble Access "Hello world" Application plugin project as described above.

When choosing an SDK version, remember that equal and later versions of Trimble Access will run your plugin, but not earlier versions.  For instance, a plugin built with v23.10 of the SDK would run under TA version 23.10 and later, but not (e.g.) TA version 22.10 or earlier. You may build and offer multiple plugins (built with different SDK versions) to customers to cater for whatever version of Trimble Access they are using. 

There have been two versions of Trimble Access where backward compatibility has been unavoidably broken. These occurred at versions 4.00 and 19.00.  At present (i.e. as of v21.00), any plugin built with an SDK version of 19.00 or higher will run with all later versions of Trimble Access.

Project options and settings

Most of the configuration for the project is carried out in one place, the SCAPI property sheet. This is a Visual Studio-specific xml file containing a number of name/value pairs which can be edited in the Visual Studio property manager (View -> Other windows -> Property Manager). Note that the debug and release configurations both use the same file, called scapi.props in the project folder. Details about setting the properties and their values can be found here.

Note: This step is done for you by the project template, if you use it.
Speaking of properties, it is useful in a SCAPI project under Project -> Properties -> Debugging, to set Command  to the path where survey.exe is installed (typically within Program Files).  You can also use the macro $(ScapiSdkDebugPath). This makes debugging and running possible directly from the plugin project. Including the argument app=$(PluginGUID) will start up with your application already selected, and autoopenjob will skip the project opening stuff and reopen the previous job. This makes the many restarts required for testing somewhat less of a hassle.

Header files

There is a header file for each set of related interface classes.  To simplify #includes, the header tsc_PluginApi.h contains includes for all API modules.  The stdafx.h file contained in the sample applications already contains this include to generate a precompiled header file, which means that only stdafx.h needs to be included in your own modules.

You can either add the headers for your application directly to stdafx.h, or use your own system of #includes. The stdafx.cpp module is also required in the project.

Libraries

There is one library (.lib file) that implements the API.  It consists almost entirely of code to direct API function calls to the correct place within Survey Core, and to direct SC events back to plugin callback functions.  Several variants of the library are shipped:

For Android, ARM libraries are shipped:

libPluginApi_ARM_Debug.a
libPluginApi_ARM64_Debug.a
libPluginApi_ARM_Release.a
libPluginApi_ARM64_Release.a

For Windows targets the following files are shipped :

ScPluginApi_x64.lib
ScPluginApi_x64.pdb
ScPluginApi_x64D.lib
ScPluginApi_x64D.pdb

Note that the tsc_PluginApi.h header file detects the Windows configuration being built and includes the correct library via a linker command. For Android, the correct library is included in the project properties when the New Project wizard is used.

Survey Core setup for testing

By far the easiest way to set up Trimble Access to be ready to run, is to use Trimble Installation Manager (TIM) to install Trimble Access (which includes Survey Core) on your device.  You will need to install the Trimble Access version that matches your SDK version - this will occur automatically when you install both the SDK and Trimble Access at the same time; more care needs to be taken with a mobile device since the versions may be chosen independently from your development platform.

Your mobile device (or laptop/desktop PC) must be licensed for plugin development before you can install or run Trimble Access.  You should have received this licence when signing up for the SDK, but if you wish to add devices then ask your Trimble representative for additional licences (you will need the device serial numbers as reported by the Installation Manager).  TAIM will download your licence(s) as part of the installation.  You will need a SCAPI developer license on any device you wish to test on even though you are not developing on those platforms;  SurveyCore needs the developer license to allow your unreleased SCAPI applications to run. This license allows any SCAPI application to be run on a mobile or desktop device, regardless of the origin and state of the app.

TIM will install Trimble Access, which includes the Survey Core components, to your device.  Before deploying any plugin, make sure that Trimble Access runs correctly.

Plugin installation directory

On a customer's device, the Trimble Installation Manager will deploy and install plugins in the same directory structure as Trimble Access, directly below the folder containing Survey.exe, which is the Survey Core executable.  Language differences aside, this folder will be something like:

C:\Program Files\Trimble\Trimble Access\General Survey\Plugin\<company>\<pluginName>\<plugin files>

For development however, Windows restricts modifications to the Program Files folders and it can be problematic to copy plugins there.  Instead, Survey Core will look for .timxml files in the Program files path, as well as the following path in the current user's AppData folder:

C:\Users\<user>\AppData\Roaming\Trimble\Trimble Survey Core API Vxx.xx Plugins\<company>\<pluginName>\<plugin files>

The version number will echo what version you are working with instead of xx.xx. Multiple versions may be installed at the same time.

The sample applications and the MSVC new project wizard contain a build step to create and copy the necessary files to the user's AppData location, so that the plugin being developed will be found and loaded by Survey Core. If a plugin appears in both AppData and Program Files, a dialog asks you which to use.  Important: Never deploy a plugin to the AppData location in a customer's install.

The installed plugin directory and file structure goes something like this:

...Vxx.xx plugins\
    \CoolSurveySoftwareLtd\
        \MyCoolPlugin\
            MyCoolPlugin.dll
            MyCoolPlugin.tdb
            MyCoolPlugin.timxml
            Uncool.png

            ...

Using Visual Studio on Windows and setting the debug options in the Project property pages as shown above will allow you to simply press F5 in MSVC to start Trimble Access. Your plugin will be already selected due to the "app=..." parameter.