TPSDK for Android and iOS
Overview
Trimble® Precision SDKTM (TPSDK) is available in different flavors depending on the targeting operating system.
The default outputs are
- Objective-C for iOS
- Java for Android
- C# for Android
Although the same core is shared between all outputs the actual interface changes per platform due to the platform specific technologies.
A simple example is Bluetooth communication - which is quite different between Android and iOS and hence requires platform specific adoption.
Before starting with the actual implementation it may be worth considering the different integration strategies offered by TMM and TPSDK. Based on the application needs a web socket approach might prove to be more convenient and effective compared to e.g. the SDK integration.
Options
Before diving into any of the offered TPSDK APIs a developer should consider the different integration methods available:
- Android mock locations and location extras (Android only, not recommended anymore)
- Web socket server (ws and wss)
- TPSDK Facade on iOS and Android
- TPSDK on Android
Generally speaking apps that only need a position typically work nicely with either the mock location framework (if available) or websockets.
Applications which aim for higher control want to look into the facade layer - which is a wrapper around the SDK encapsulating the most common use cases.
Applications going for full control or less common receiver features want to extend the facade by implementing the missing functionality or just implement the SDK.
Each approach has different pros and cons.
Feature overview
A none-extensive overview can be found in the following comparison
| Integration | Mock locations | WebSocket server | TPSDK |
|---|---|---|---|
| Supports Trimble receivers | yes | yes | yes |
| Position access | Android location API | localhost ws and json | API |
| Position meta data | Check documentation | Check documentation | Check documentation |
| Complexity | low | low | med-high |
| Access to all features | no | no | yes |
| Allows datum transformation | yes, via TMM | yes, via TMM | yes, via the API and/or TMM |
| Allows going static | no, just 1Hz snapshot positions | no, just 1Hz snapshot positions | yes |
| Allows undulation values | yes | yes | yes |
| Allows tilted measurements | no | no | yes |
Mock locations
Many applications are in need of precise positions - but can happily live with the information detail level as provided via the Google Mock locations aka the corresponding the location object.
To overwrite mock locations you can enable the corresponding feature in Trimble Mobile Manager (TMM). This approach requires no development effort on your part - your application behaves just as it normally would, and can benefit from receiving higher accuracy positions from the Trimble GNSS receivers.
TMM also adds additional meta information to the location.extras - accessible via known Android techniques. Detailed information on the available data can be found in the TMM developer documentation.
Downside: The problem with Android mock locations is that it has become hard to differentiate between a ‘Trimble’ position and a fused position as provided by the Android OS. If an application does not parse location.extras its not possible to filter - meaning an application receives a mix of positions.
Also some HTML5/ JS frameworks don’t provide access to location.extras which can result in futher position mixes.
Hence we do not recommend to use Mock Locations at all.
Web sockets
Web sockets are from a data perspective identical to TMMs mock location output plus location extras - although combined in a single object.
The advantage of web sockets are that the Android OS does not inject fused locations - this is a ‘Trimble only’ position stream.
Additionally progressive web apps often have issues accessing mock locations as they can’t define the location provider. For those apps the web socket server is ideal as it provides a json based output stream that can be easily parsed by apps.
More details on the web socket and its behavior can be found in the TMM developer documentation or the TPSDK documentation
TPSDK and the Facade
Facade
The term facade is used quite heavily within the context of TPSDK.
In short the facade is a wrapper layer around several components of TPSDK. This wrapper exposes the most common functions like connecting via Bluetooth and starting a NTRIP survey. It also acts as sample as it shows how to use the interfaces exposed by TPSDK.
The facade ships in source code form for Android and as component for iOS - so ideally the facade project is copy/ pasted to the solution. This allows drop-in replacements when new version of TPSDK go live.
Enhancements to the facade ideally happen in a derived class so that the drag & drop update process still works.
TPSDK
TPSDK and its core components Sensor Software Interface (SSI) and Licensing Software Interface (LSI) create the foundation of all SDK related things.
SSI exposes a vast set of GNSS receiver features ranging from the configuration of the receiver internal UHF radio to tilted measurements and more.
The SDK has a component oriented design based on interfaces.
In essence this means that feature are linked to an interface.
For example, say the possibility to start RTK - if this is supported or not depends on the availability and properties of the corresponding ISsiStartRtkSurvey interface.
The availability is determined dynamically during runtime.
For more details please take a look at the TPSDK documentation.