Objective-C Facade Integration

This guide explains how to integrate the TPSDK facade into an Xcode project.
These steps are intended as a reference—there are often multiple ways to achieve the same result.

Create a New Project

Create a new Xcode project and reference the header files included with the facade SDK. These headers define the interface for the facade component.
Unlike Android, the Objective-C SDK provides the facade as a component only (not as source code).

Copy the libCatalystFacade.a (static library) file into the libs folder of your application.

Import the Framework

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

Include the framework header files in your code using the #import directive:

#import <CatalystFacade/CatalystFacade.h>

Depending on the framework’s location, you may need to adjust the framework search path. Add the directory containing the framework to the “Framework Search Paths” option in your Xcode project settings.

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

Adjust Info.plist for TMM Custom URL Schemes

The Info.plist file requires configuration changes to support Trimble devices.

One change is the addition of custom URL schemes.

Custom URL schemes enable two-way communication between TMM and the facade.
You must register a callback URL so TMM can download the subscription file (e.g., for Trimble Catalyst) on behalf of your app.

Add the following to your Info.plist:

<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>logincatalystfacade</string>
            <string>ondemandcatalystfacade</string>
        </array>
    </dict>
    <dict>
        <key>CFBundleURLName</key>
        <string>Trimble.CatalystFacadeDemo</string>
    </dict>
</array>

See Apple’s developer guide for more details.

When calling the login, pass the Trimble.CatalystFacadeDemo URL as a parameter:

[_facade loadSubscriptionForApplicationID:ApplicationID withTMMLoginUrl:@"logincatalystfacade://Trimble.CatalystFacadeDemo"];

Finally, handle the callback in your AppDelegate.m:

- (BOOL)application:(UIApplication*)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
    if ([[url scheme] isEqual:@"logincatalystfacade"]) {
        [[MainModel instance] completeLoginWithURL:url];
    }
    return YES;
}

TMM Bookmark

At this stage, TMM can download the subscription file on behalf of your app, but it cannot store it in a folder accessible by your application.

To solve this, configure a bookmark using createTMMBookMarkWithUrl, which grants access to the file.
This bookmark should point to TMM’s document folder, where the license file will be stored. This location may also contain the NTRIP configuration file or downloaded geoid files.

The facade sample implements this using a Document Picker:

-(BOOL)createTMMBookMarkWithUrl:(NSURL* _Nonnull)url;

Add Accessory Protocols

In addition to custom URL schemes, your app must register the accessory protocols defined by Trimble.

Extend your Info.plist with the following protocols:

<key>UISupportedExternalAccessoryProtocols</key>
<array>
    <string>com.trimble.mcs.gnss</string>
    <string>com.trimble.command</string>
</array>

This is part of the Made for iPhone (MFi) process and ensures your app can communicate with Trimble devices.
It also prevents unknown devices from connecting and causing protocol errors or a poor user experience.

See Apple’s External Accessory Framework for more details.

Connect

At this point, your project is set up and you can begin implementation. The following flow is based on the MainModel.m class included with the SDK:

1. Search, pair, and connect to the receiver using iOS mechanisms.
2. Load the subscription using
   -(TSSICFDriverReturnCode)loadSubscriptionForApplicationID:(NSString *_Nonnull)applicationID withTMMLoginUrl:(NSString*_Nonnull)urlString;
3. Load the driver using initDriverWithDriverType, typically with TSSICFDriverType::Driver_TrimbleGNSS.
4. Connect using
   (TSSICFDriverReturnCode)connectAccessory:(EAAccessory*_Nonnull)accessory;

Once connected, you can:

• Request receiver details (e.g., serial number or firmware version)
• Set the antenna height
• Start an RTK survey

and more.