Objective-C facade integration
The following few steps explain how to integrated the TPSDK facade into a Xcode project. Note that the following steps are meant to guide the developer - as always there are multiple ways to achieve the same.
Create a new Project
Create a new project and reference the header files shipping with the facade SDK. Those headers define the interface of the facade component. In contrast to Android the Objective-C SDK contains the facade as component only - so not as source code.
You can copy & paste the libCatalystFacade.a
(static library) file into the libs
folder of your application.
Project setup
Next step is making the linker aware of the static library via the project configuration:
TMM and facade plist
The information property list file (Info.plist
) requires configuration changes in order to support Trimble devices.
One change is the addition of custom URL schemes.
Custom URL schemes are used to implement the two-way communication between TMM and the facade. TMM specific information need to get added - to allow TMM to download the subscription file for e.g. Trimble Catalyst on behalf of the calling application.
Due to this the application implementing the SDK must register a callback URL:
<array>
<dict>
<key>CFBundleURLSchemes</key>
<array>
<string>logincatalystfacade</string>
<string>ondemandcatalystfacade</string>
</array>
</dict>
<dict>
<key>CFBundleURLName</key>
<string>Trimble.CatalystFacadeDemo</string>
</dict>
</array>
More details can be found in Apples developer guide.
The Trimble.CatalystFacadeDemo
URL should be passed as a parameter when calling the login like this:
[_facade loadSubscriptionForApplicationID:ApplicationID withTMMLoginUrl:@"logincatalystfacade://Trimble.CatalystFacadeDemo"];
Finally the callback of the URL scheme must be handled via adding the appropriate handler in the AppDelegate.m
class.
(BOOL)application:(UIApplication*) app openURL:(nonnull NSURL *)url options:(nonnull NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
if([[url scheme] isEqual: @"logincatalystfacade"])
{
[[MainModel instance] completeLoginWithURL:url];
}
return true;
TMM bookmark
At this stage TMM can download the subscription file on behalf of the calling application - but it can’t be stored inside a folder accessible by the application.
For that purpose the application must configure a bookmark via createTMMBookMarkWithUrl
which allows access to the file. This bookmark must point to TMMs document folder as this is the location where the license file will get stored.
The same location will also contain e.g. the NTRIP configuration file or downloaded geoid files.
The facade sample implements this via a Document Picker
-(BOOL)createTMMBookMarkWithUrl:(NSURL* _Nonnull) url;
Add accessory protocol
Next to the custom URL schemes the application must also register to the accessory protocols defined by Trimble.
To do so the Info.plist
must be extended by the following protocols:
<key>UISupportedExternalAccessoryProtocols</key>
<array>
<string>com.trimble.mcs.gnss</string>
<string>com.trimble.command</string>
</array>
This is part of the Manufactured For iPhone
(MFi) process and basically ensures that your application understands ‘Trimble speech’.
At ensures that no unknown device can connect to your device causing protocol errors and hence bad user experience.
Further details can be found in Apples External Accessory Framework.
Connect
At this stage the project is finally set up correctly and the actual implementation can start. The following code is based on the MainModel.m
class shipping with the SDK.
Generally speaking the flow that needs to be performed is:
- Search, pair and connect via the mechanisms provided by iOS.
- Load subscription via
-(TSSICFDriverReturnCode)loadSubscriptionForApplicationID:(NSString *_Nonnull) applicationID withTMMLoginUrl:(NSString*_Nonnull)urlString;
- Load driver via
initDriverWithDriverType
, with a high likelihood a developer wants to useTSSICFDriverType::Driver_TrimbleGNSS
- Connect via
(TSSICFDriverReturnCode)connectAccessory:(EAAccessory*_Nonnull)accessory;
At this stage a connection to the receiver is established and further actions like
- Requesting receiver details like SN or FW
- Setting the antenna height
- Starting an RTK survey
can be started.