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.

Import framework

To include a framework in your Xcode project, choose Project > Add to Project and select the framework directory.

You include framework header files in your code using the #import directive.

#include <CatalystFacade/CatalystFacade.h>

Depending on the location of the framework you may need to adjust the search path for frameworks. To specify the location, add the directory containing the framework to the “Framework Search Paths” option of your Xcode project.

Note: The standard locations for frameworks are the /System/Library/Frameworks directory and the /Library/Frameworks directory on the local system

Adjust plist to make TMMs custom URL schemes known

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 protocols

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:

0. Search, pair and connect via the mechanisms provided by iOS.
1. Load subscription via -(TSSICFDriverReturnCode)loadSubscriptionForApplicationID:(NSString *_Nonnull) applicationID withTMMLoginUrl:(NSString*_Nonnull)urlString;
2. Load driver via initDriverWithDriverType, with a high likelihood a developer wants to use TSSICFDriverType::Driver_TrimbleGNSS
3. 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.