Technical overview
Trimble Access Applications
General Survey is the surveying application that ships with Trimble Access. Other optional applications that the customer may install as part of Trimble Access include Tunnels, Roads, and Mines. Underpinning General Survey and the various other applications is a software framework known as Survey Core (SC), which provides the functionality required to run them.
Extending Trimble Access with Plugins
Any approved developer now has the ability to develop plugin applications for Trimble Access that leverage the large body of functionality provided by the Survey Core framework.
Supported Platforms
A Trimble Access end-user may install Survey Core Plugins on most devices approved to run Trimble Access (includes TSC7, Trimble Tablets, TSC5, and so on) provided that Trimble Access is installed. Each installed plugin will add a new application to the Applications picker in Trimble Access.
From version 21.10 up, the supported devices include selected Trimble Android devices, and the Windows 10 or 11 based controllers such as the TSC7.
Prior to version 4.00, Survey Core Plugins are supported for most handheld devices except older TCU hardwares. Please see the relevant SCAPI Guide version for more pertinent information.
Plugin behaviour
A plugin behaves like any other Trimble Access application such as Roads, Tunnels, or Mines. It must generate its own main screen so that it appears as a new application within the Trimble Access environment. A correctly installed plugin will appear in the list of apps and be able to be launched by the user as they would launch (for instance) the Roads or Tunnels application.
Development
As at version 23.10, plugins are written in C++ and built using Microsoft Visual Studio 2022 Professional edition. The primary reason for the language choice is because Survey Core is itself written in native C++.
It is conceivable that other versions or brands of IDE that support C++ would also function correctly, but none have been tested at this point in time. All that is presently required is MSVC 2022 plus the SDK which is a structure of directories containing a number of header files, library files, samples and other utilities, and a current installation of Trimble Access. There is a single library (.LIB), built for a variety of configurations, which the plugin must link with. The header and library files are installed by Trimble Access Installation Manager (TAIM), when an API Developers licence is present for the computer on which TAIM is run.
In some cases, class designs found in the .NET framework have been exploited in the API to avoid reinvention. Unfortunately, because the API is written using native C++, there are some .NET designs that are simply not possible to implement due to language restrictions.
Each plugin is implemented as a Windows DLL. Each plugin has a .timxml file that is generated by the build and installed along with the DLL. At startup, Trimble Access (Survey.exe) will look for *.timxml files in certain folders and add them to the Application picker's list of apps. The plugin is loaded and run when the user selects the app. A plugin DLL must have been built with a suitable version of the SC API library for this to succeed. Any plugin startup failure will be logged and the plugin will be ignored (see ...\Trimble Data\System Files\sc.log).
Android support
As of version 20.20, Trimble Access supports plugins on the Android platform.
The interface on Android is unchanged from the Windows interface, with a single exception - the support for drawing graphics using the Windows GDI+ API has been removed, and in its place we are using Qt, a GUI framework which works across a large number of platforms. A number of new graphics drawing methods have been added to the tsc_Image class so that developers need not install Qt just to draw on an image.
Software developer skills
Programmers intending to develop plugin applications using SCAPI will need good Object-oriented C++ skills, and be reasonably familiar with the operation of Trimble General Survey. Although some .NET principles have been used in the API design the language is still native C++, and not C#. Developers lacking native C++ experience may struggle with the peculiarities of the language.
The API is intimately connected to Trimble Survey Core, which is made visible to an end-user through the General Survey application. If there is not a high level of General Survey competency within the development team, the creation of a quality survey application is not assured.
Version compatibility
Backward compatibility is built into the API. It is intended that any properly-written plugin will continue to function when later versions of Survey Core are installed by the customer. At some point when the plugin becomes very old, this compatibility may cease to be beneficial and at that point the plugin will fail gracefully. The API does not provide forward compatibility; a plugin built with an SDK version more recent than the Survey Core it is installed with will fail - also gracefully.
When a customer installs a plugin using TAIM, internal version checking ensures that an incompatible plugin will not be installed.
Note that at version 4.00 binary compatibility was disrupted with the move to the Qt UI. Plugins that must run with version 4.00 and upwards must be rebuilt using at least version 4.00 API. The same occurred at version 19.00, when we moved Trimble access to a 64-bit platform and plainly there was no possibility of compatibility with 32-bit versions.
Licensing
Plugins use the Trimble Access licensing system. This allows an end-user to purchase a license for the plugin on a mobile device, and to have the plugin downloaded and installed automatically, just as he or she would purchase other applications such as Roads, Tunnels, and Mines. Plugin developers will have the ability to upload their plugin installation files to either a "sandbox" area for installation testing, or into the production area to be available for licensed customers to install.
Programming interface technology
Internally, the API uses an interface method based on pure virtual C++ classes, which gives very good performance because of the simplicity of the cross-interface calls. However, the interface layer is completely hidden to the API programmer, who only needs to deal with the abstracted API classes which are supplied as part of the SDK.
It should be noted that all strings in the API are in UTF-8 format. Conversion methods between UTF-8 and UCS-2 are provided by the API.
Functionality exposed by the API
For a plugin to appear to be fully integrated into the Survey Core environment, it needs access to much of the basic framework that Survey Core uses, and also to observe the restrictions imposed by this framework. This means a plugin will be expected to:
Use Survey Core API methods for all User Interface (UI) operations.
Conform to the SC threading model. The SC architecture lessens the need for additional threads.
Use the SC event handling system and avoid calls to any operating system methods that block for significant periods of time.
Be a good neighbor and behave correctly towards the other applications that may be concurrently using the same framework.
Conform to the general look and feel of Survey Core applications.
Use the standard C runtime calls, where functionality is not provided by the API.
Avoid using O/S- or compiler-specific code wherever possible, as this could limit compatibility with some devices.
Available classes
The following summarizes the functionality available in the API:
Basic methods
A String class, closely conformant with the .NET String class, but UTF-8 instead of UCS-2.
A Unicode (UCS-2) string class providing conversions to and from UTF-8.
A variety of list classes, such as a sortable string list roughly equivalent to List<String>.
A Path class, also closely conformant with .NET Path class, which includes access to SC standard directories.
File and Directory classes for easy access to the filesystem in a .NET-like manner. Some simple file I/O is included.
Application settings for global persistent storage of small items.
A rich set of utility methods such as Plugin Registration, timing and sleep methods, logging, etc.
A complete language translation system for strings, including access to Survey Core's existing translations.
Survey Core access
The ability to launch virtually any task that can be found within General Survey's existing UI.
Access to global events such as database and configuration changes.
String formatting methods that conform to SC standards and obey the current configuration.
A high performance XML class - primarily for accessing certain SC data structures.
Ability to add layers to the Current job Map, add items to menus and process them, intercept user actions such as menu choices, object selections, and clicks/taps.
A moderate degree of control over the Stakeout subsystem.
User Interface
Survey Core look-alike.
The Survey Core MessageBox for simple dialogs with one to four buttons.
A complete form system with a range of controls, layout management, and event handling.
A set of standard form field types, such as the AzimuthField, which behave exactly like the corresponding SC fields.
A wizard form system, built on top of the form system, to make wizard-style UI easy to implement.
A menu form system used to create "button forms" with both standard and custom functionality.
Instrument access and control
Access to a connected total station, with control of all measurement functionality. Image and video is not available in this version.
Limited access to a GNSS receiver. No control is available at this time but any existing SC functionality may be invoked.
Survey Core jobs (database)
The ability to open or create a Survey Core database either as a stand-alone database or as the current job.
Access to all positions (points) stored in the database of the current job or any other Survey Core job.
The means to obtain the computed coordinates of a point in various forms.
Access to all information stored with a point in the database.
Access to current configuration data as stored in the database.
The ability to add points to the database.
Control over feature/attribute coding of database points and other entities.
Access to the current feature/attribute library.
Access to lines and arcs in the database, and the ability to store new ones.
The ability to add custom data records to the database, or attach custom records to an existing database object.
Workflows
To measure a point using a total station, perform preprocessing on the point data, and store the result in the database as a new observation.
To perform a station setup by a variety of methods, such as resection (free station), single backsight, etc.
Integration of wizard forms to perform a mix of standard Survey Core tasks and custom tasks.
Sample applications
Sample applications are included with the SDK, illustrating how to write complete applications, such as measuring rounds on a total station. These samples are complete working applications which show the use of API calls involving the database, total stations, and UI.
To illustrate simply how individual parts of the API may be used, a "HowTo" sample application is provided, that contains many simple (and generally useless) forms showing how to program with a wide variety of controls, add custom records to the database, etc. This is also a working sample that can be built and run.
Documentation
Four documentation sets are available:
The SCAPI Developers' Guide is a Wiki which documents the API, explaining the how of the API rather than the what. The guide allows users to add comments about any part of the API, or to add hints, tips, and document peculiarities.
The API header files themselves are commented with descriptions of most types and methods.
Support
A web-based forum allows users of the SDK to ask questions and swap stories, and there is an area for submitting bugs and files with examples of incorrect behaviour.