Technical Overview

Trimble Access Applications

General Survey is the main 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.

These Trimble Access applications are generally referred to as Plugins, something similar to add-ons or extensions that many common apps (such as your web browser) support.

Extending Trimble Access with Plugins

Any approved developer 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 (TSC7, TSC5, etc) provided that Trimble Access is installed. Each installed plugin will add a new application to the App Picker form in Trimble Access.

Note that new Trimble Access Plugins are supported on Trimble Android devices, but no longer on older TCU hardwares that run Windows CE. Plugins for the older devices may still be installed by users, and updated by developers as previously.

Plugin behavior

A plugin behaves just like any other Trimble Access application such as Roads, Tunnels, or Mines. It must generate it's own main menu so that it appears as a new application within the Trimble Access environment. A correctly installed plugin will appear in the Trimble Access App Chooser and can be launched by the user as they would (for instance) the Trimble Access Roads application, or General Survey.

Development

Development uses an API into Survey Core, generally referred to as Scapi. Extensive documentation can be found in the Scapi Developers' Guide here.

Plugins are currently built using Microsoft Visual Studio 2019 Professional edition, and written in C++. 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 Microsoft Developer Studio 2019 (16.11.x) plus the TASDK which is a structure of directories containing a number of header files, library files, project templates, samples, and utilities.

Windows

For Windows development we provide a static library (.LIB), built for a variety of configurations and platform types which the plugin must link with. The header and library files are installed by Trimble Installation Manager (TIM), when an API Developers license is present for the computer on which TIM is running. Note that TIM may be referred to by its old name, TAIM, in some documentation.

Each plugin is built and deployed as a Windows DLL. When selected in the App Picker by a user, Trimble Access (Survey.exe) will attempt to load and initialize the DLL that is associated with the selected app. A plugin DLL must have been built with a suitable version of the Trimble Access API library for the initialization to succeed. Any plugin initialization failure will be logged and the plugin will be ignored.

The Windows version is used both for mobile devices running Windows 10 or higher, and also for desktop and laptop computers for demonstration, testing, and development purposes.

Android

Support is provided for plugins to run with Trimble Access for Android devices. There is still work to be done to document the development environment, but apart from this plugins are fully supported on all our Android devices.

The environment and API are almost identical between Android and Windows devices. The difference is in the build and deployment; nearly everything else - including the source code and support files - is identical across all platforms.

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 Access.

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 may be difficult.

Version compatibility

Backward compatibility is built into the API. It is intended that any well-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 version of Trimble Access it is installed with, will refuse to run. Multiple plugin versions of the plugin may be made available so that a broad range of TA versions is properly catered for.

When a customer installs a plugin using TIM, internal version checking ensures that an incompatible plugin will not be installed; the latest version that is compatible with the installed Trimble Access will be chosen automatically.

Licensing

Plugins will 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, or Mines. Plugin developers 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 uniformly in UTF-8 format.

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 makes the need for additional threads unlikely though support for these is supplied as part of the API.

  • 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 Trimble Access applications.

  • Note that this API was developed before a satisfactory STL was available for older Trimble devices, so there are a number of classes which could have been implemented using the C++ std library, such as std::string. Scapi is generally compatible with std libraries, although care needs to be taken with methods that wait or sleep.

Available classes

The following summarizes the functionality available in the API:

  • Basic methods:

    • A String class, closely conforming to the .NET String class, but using UTF-8 internally.

    • A Unicode (UTF-16) string class providing conversions between UTF-8 and UTF-16 and UCS-2.

    • A variety of list classes, such as a sortable string list roughly equivalent to List.

    • A Path class, based on the .NET Path class design, which includes access to TA standard directory names.

    • File and Directory classes for easy access to the filesystem in a .NET-like manner, including some file I/O.

    • 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 Trimble Access' existing translations.

  • Survey Core access:

    • The ability to launch virtually any workflow 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 simple and high performance XML class - primarily for accessing certain SC data structures.

    • Ability to add information to the Current job Map, add items to the map's menus and process them.

    • A moderate degree of control over the Stakeout subsystem.

  • User Interface

    • Trimble Access look-alike.

    • The TA 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 TA 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.

    • Control of many map functions and the ability to add custom layers to the display.

    • Some control of the Map and the ability to draw on it, with a basic graphics supported.

  • Instrument access and control

    • Access to a connected total station, with control of all measurement functionality. Limited image (but not video) is available in this version.

    • Access to a connected GNSS receiver with full control of measurement functionality.

  • Survey Core jobs (database)

    • The ability to open or create a Trimble Access 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 Trimble Access 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, lines, arcs, and cogo results to the database.

    • Control over feature/attribute coding of database points and other entities.

    • Access to the current feature/attribute library.

    • The ability to add, read and modify custom records in the database.

  • 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 Trimble Access 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. This is also a working sample that can be built and run.

Documentation

  • The SCAPI Developers' Guide is a Google Site which documents all of the API, explaining the how of the API rather than the what, and includes release notes, setup instructions, and everything else you need to know.

  • The API header files themselves are commented with descriptions of most types and methods.

Support

There exists a web-based forum using Google Groups which allows users of the SDK to ask questions, submit bug reports, and swap stories.