Developing for Android

Introduction

This page is describes development for deployment to Android devices. There is quite a lot of detail here, possibly too much.

• • Development for Both Android and Windows is carried out on a Windows platform, using Microsoft Visual Studio 2022 (or VS 2019)

  • Setting up your development machine (on a Windows device) please see this page.

  • Plugin development for a Windows target, and Trimble Access SDK v20.10 and later, see here.

  • You can use the same SCAPI plugin source code to run on both Windows and Android targets; the API is identical.

Android support in Trimble Access versions

• • Prior to TA version 20.00, no Android support.

  • TA 20.00 : Some Android devices supported, no Scapi plugin support.

  • TA 20.10 : Basic Android support for Scapi , Trimble internal plugins only.

  • TA 20.20 : Support for third party Android plugins, but must be installed manually.

  • TA 21.10 : Android plugins installable using TIM.

  • TA 21.20 : TDC600 and TSC5 (all Android except TCU5) upgraded to 64-bit O/S, TA, and plugins.

Getting set up

We highly recommend installing and getting a simple plugin working with Windows before attempting an Android version.

See this page for setting up the toolchain for Android. This is mostly about installing the Android SDK and NDK.

Summary of differences with Android (as opposed to Windows)

Scapi is fully supported for Android devices. Some Windows-only features (such as embedded resources) are not used so that the two platforms are consistent.

• • Image resources are always installed as individual files rather than being embedded in the DLL. Some remnants of the Windows resource ID system remain however. 

  • The tsc_Image class has a set of basic graphical operations that are consistent between the platforms.

  • The installation of plugins on the target device is internally very different between Windows and Android, although the customer will follow a similar procedure for both.

Note that earlier plugins (v19.00 to v20.01) remain binary compatible with Trimble Access Windows v20.01 and beyond, and that developers may continue to use the v19.00 SDK to create plugins to run with those versions of TA. Source-code compatibility does not extend to graphic drawing methods; plugins which use the Windows GDI++ to draw their own graphics must be updated to use the 20.10 SDK instead, along with the new graphics methods.  

Creating an Android plugin project using MS Visual Studio

On the development machine, the Android SDK and NDK must be installed. Development is still with MS Visual Studio 2019 or 2022. See the version table on the Home page for which MSVC and SDK/NDK versions to install.

The guide to installing the required Android build tools can be found here.

A new Android project is created using the New project wizard supplied in the SDK, and the files from the existing Windows project added to it.
The project wizard does not easily allow multi-project solutions to be created, so for now they are separate folder structures. Fortunately, having another project sharing the same source files does not copy the files, so almost all of the project's files are common to and shared between both platforms. It is also possible to copy the Android project into the Windows folder and add it to the solution there.

As far as possible, development for the two platforms has been kept in step so that, in general, any changes made to a Windows plugin will simply work for Android, and vice-versa.

The many steps below might look daunting. It's not that bad, we've just included a lot of detail.

Update: There are several references to sharing files between the Windows and Android projects. Those were made in relation to a Windows project created using a Windows project template from v21.10 or later. Windows projects older than v21.10 will be different and upgrading them to the latest template would be worthwhile, before starting work on an Android version.

Build (mostly about updating Windows plugins to compile for Android)

• • Android requires the same development setup as used for Windows, plus the Android SDK/NDK.

• There are Trimble Access Project Templates installed with the Scapi SDK. These add project creation wizards for both Windows and Android plugins.

• • In VS 2022 use the New project Wizard (search for Trimble) to make a new project and solution, using the same name as the Windows plugin. It is easiest if it's put in the same directory as the plugin's Windows project. They can be included into the same solution, but initially it's cleaner to create separate projects in separate directories.

• The build of the plugin must use the exact same name as the Windows dll. This is <pluginName>.dll - the build will actually produce a lib<pluginName>.so output file, which Trimble Access will expect to find in the installation zip.

• The Android build makes greater use of the MSVC property sheets:

  • • There is a PropertySheets folder in the project with all the property sheets for the build. We recommend against changing these; make custom changes in your plugin project to keeps the parts separate, or add your own property sheets if necessary.

    • The scapi.props file for the plugin should be in the same folder as your Windows project. It is described here and will work with both builds with a couple of changes in the User Macros section:

      • The ScapiSdkDir macro needs to point to the place the SDK has been installed. This is usually
        c:\Program Files\Trimble\Trimble Survey Core API v<xx.yy>\ and should be correct by default.

      • In future we may combine Windows and Android projects into one template. Meanwhile, it is not difficult to add the two projects to one solution.

• The New project wizard will have added a number of get-started files to the project. The wizard should produce a Hello world app which builds and runs without change, but for a project upgrade most of the .cpp and .h files are not useful and apart from stdafx.h and stdafx.cpp, can be deleted. 

• If you have other folders in your Windows project, add them to the Android project now.

• Add all your source files to project. You can use the same files, no need to copy your source files or resources; Visual Studio will add them as links.

• You will probably need to merge your stdafx.h/.cpp with the ones generated by the wizard, since there are small changes in the generated ones that need to be incorporated.

• Note that the language build only needs to be done once, the output is the same and used by both projects.

• • Where different C++ code is required between Windows and Android platforms, use #if PLATFORM_WINDOWS and/or #if PLATFORM_ANDROID.

  • Compile and fix up the errors, such as adding (void)argname to a function where the compiler grumbles about unused function parameters.
    The CLANG compiler is generally a bit fussier than MSVC.

  • Initialisation lists in constructors may be the most time-consuming. Consider moving to inline initialisers, or a mix. Or specify -Wreorder in the compiler command line (Project->Properties-> C++).

  • Pragma statements will also need to be fixed. There is a Clang (C++ standard) equivalent for many of the Microsoft ones, which will work in both environments.

  • Most significantly, graphics has changed from Windows GDI+, and there are some new built-in drawing functions in tsc_Image for both Windows and Android. More info below.

Resources and installation directories:

• 1. Installation of a plugin places all files into a unique subdirectory of the Trimble Access application directory (sandbox), and are not accessible to any other app or the user. This is an Android thing. On this page we'll refer to this installation directory as <pluginDir> or $(PluginDir).

  2. By default, all plugin resources will go into the base installation directory <pluginDir>. They may be deployed to a subdirectory of that if desired.

  3. The plugin's name, including the .dll extension, in the VS project's scapi.props (and consequently in the .timxml file) should stay the same as now,. This is important, as the same .props and .timxml file are used for both platforms. Scapi will automatically add 'lib' to the front and change the extension to .so before trying to load it on Android devices.

  4. Check that capitalisation in the scapi.props (and thus the .timxml file) is correct, particularly for the plugin dll (so) name.

  5. All paths in the timxml file are now relative to the timxml file's location, which is the same location as <pluginDir>.

  6. The path macros $(PluginDllDir) and $(PluginDir) are obsolete. If used, they will return the directory containing the timxml file, not the .so directory (though they are mostly the same).

  7. The path macro $(PluginResDir) is the replacement and also returns the timxml directory path, which is <pluginDir>. If your resources are in a subdirectory, this will not be reflected in $(PluginResDir), you must add the sub directory name yourself.

  8. At startup, Scapi will search for timxml files in all <pluginDir> sub-directories to locate installed plugins, and expect each plugin's other installation files to be relative to its timxml.

  9. The build by default will name the .timxml file <plugin_name>.timxml - the name must be the same as the Windows dll and the middle part of the Android .so filename.

  10. The .tdb file goes into <pluginDir>/<name>.tdb  using the same filename as the .tdb in the windows version. 

  11. Plugins are no longer loaded at TA startup. When populating the Trimble Access applications form, Scapi will add installed plugins as well as plugin installers of uninstalled plugins to the list of apps. The library is installed as necessary, but only when the user selects the app for the first time after starting Trimble Access.

Installation : Deploying a plugin to Android

Installation is now covered on this page.

Resources

1. Resources in both Android and Windows are treated the same way. Resources are identified by number in the plugin, and a mapping from the number to the filename is made in the InitializePlugin function described below.

2. To bind a useful name to the each resource number you can use any scheme (enum, #defines, etc), or simply use the resource.h header as it was previously used with Windows. Note that the Windows build has been changed to the same scheme described here for Android so there is no need to strictly observe the old format. Ultimately, we just need an integer to reference a resource.

3. In the plugin tsc_InitializePlugin function, create a table of resource ID and filename for all resource files, by calling tsc_SurveyCore::RegisterAssets and pass in an initializer list containing the names and numbers. See the example below.

4. The MSVC project template - installed with the Scapi SDK - can be used to make a plugin project which will output an installable Zip file, as already described.

   1. In the build's Post-build event, the library and all resource files are copied to the output directory and zipped up into a single installation file.

   2. So when built, you should end up with something like: $(ProjectDir)<pluginName>_ARM_Release_v1.2.3.0.zip in your plugin's project directory.

   3. For testing, simply copy the installation Zip to the Android device into the directory: /Trimble Data/System Files/plugins/ and (re)start Trimble Access on the device. To update the plugin, drop the same (rebuilt) zip file there again and restart TA. The device must have a Scapi development license for this to work.

5. For final deployment, ensure everything (and particularly the updated version number) are correct, then build and upload the zip file using the form on the TCC developers' site, in the usual way.

Example of code (the bold part) to be added to existing tsc_InitializePlugin function (use the same code for both Windows and Android):

extern void tsc_InitializePlugin ()

{

    tsc_SurveyCore::RegisterApplication (...);  

    tsc_SurveyCore::RegisterUITask (...);

    ...

    tsc_SurveyCore::RegisterAssets (

    {

        {IDB_FolderIcon,  "FolderPic.png"}, 

        {IDB_Pencil,      "Pencil.png"},

        {...},

        {IDF_TemplateXml, "CustomDataTemplate.xml"} 

    });

}

Using QImage & QPainter

These methods are no longer supported.