TTLServiceClient Class Reference

Inherits from NSObject
Declared in TTLServiceClient.h

Overview

Main access point interacting with the TomTom ubi service (combination of LINK100 device and backend)

This represents all commanding opportunities which the service offers. the service will answer using the TTLServiceEventDelegate and the TTLServiceOBDRealTimeDelegate.

+ sharedInstance

Delivers a shared instance of the service.

+ (TTLServiceClient *_Nonnull)sharedInstance

Discussion

Delivers a shared instance of the service.

This creates an shared instance with either a default configuration or the configuration that was configured by calling [TTLServiceClient configureServiceClient:] BEFORE [TTLServiceClient sharedInstance] was called.

Declared In

TTLServiceClient.h

+ configureServiceClient:

Allows the upfront configuration of the TTLServiceClient.

+ (void)configureServiceClient:(TTLServiceClientConfiguration *_Nonnull)configuration

Discussion

Allows the upfront configuration of the TTLServiceClient.

This needs to be called BEFORE [TTLServiceClient sharedInstance] is called. Also mind that configuration is only possible once. An exception is thrown when not following these rules.

The given TTLServiceClientConfiguration instance is copied, so changes to it won’t be reflected in the configuration.

Declared In

TTLServiceClient.h

  serviceDelegate

Delegate to callback on general service events (Deprecated: Since 1.2.0)

@property id<TTLServiceEventDelegate> _Nullable serviceDelegate

Discussion

Delegate to callback on general service events

This property is DEPRECATED! Use [TTLServiceClient addServiceDelegate:] and [TTLServiceClient removeServiceDelegate:].

Declared In

TTLServiceClient.h

  obdRealTimeDelegate

Delegate to callback on OBD real time transmission events.

@property id<TTLServiceOBDRealTimeDelegate> _Nullable obdRealTimeDelegate

Discussion

Delegate to callback on OBD real time transmission events.

This delegate is separated from other service event callbacks to make it possible to have a separated implementation for handling OBD real time information. It is also possible to put the delegate execution on it’s own dispatch queue. Use setObdRealTimeDelegate to do this.

Declared In

TTLServiceClient.h

  realTimeDataInterval

Milliseconds between real time datagrams are send by the LINK device. Default is 1000ms.

@property int realTimeDataInterval

Discussion

Milliseconds between real time datagrams are send by the LINK device. Default is 1000ms.

Declared In

TTLServiceClient.h

  drivingProfileRealTimeDelegate

Delegate to receive real time driving profiles.

@property id<TTLServiceDrivingProfileRealTimeDelegate> _Nullable drivingProfileRealTimeDelegate

Discussion

Delegate to receive real time driving profiles.

This delegate is separated from other service event callbacks to make it possible to have a separated implementation for handling real time driving profile information. It is also possible to put the delegate execution on it’s own dispatch queue. Use [setDrivingProfileRealTimeDelegate] (setDrivingProfileRealTimeDelegate:queue:) to do this.

Declared In

TTLServiceClient.h

  automaticActivation

Property that tells if automated activation is active or not.

@property (nonatomic, readonly) BOOL automaticActivation

Discussion

Property that tells if automated activation is active or not.

See TTLServiceClientConfiguration for more information about automatic or manual activation.

Declared In

TTLServiceClient.h

– addServiceDelegate:

- (void)addServiceDelegate:(id<TTLServiceEventDelegate> _Nonnull)delegate

Discussion

Registers a TTLServiceEventDelegate.

Delegates will be removed automatically once they are no longer referenced elsewhere.

Declared In

TTLServiceClient.h

– removeServiceDelegate:

- (void)removeServiceDelegate:(id<TTLServiceEventDelegate> _Nonnull)delegate

Discussion

Removes a TTLServiceEventDelegate.

Can be used if the a delegate stays around but should be removed manually.

Declared In

TTLServiceClient.h

– setObdRealTimeDelegate:queue:

Set the delegate for OBD real time transmission handling. (Deprecated: since 1.3.4, use subscribeToOBDData or subscribeToAccelerationData instead)

- (void)setObdRealTimeDelegate:(id<TTLServiceOBDRealTimeDelegate> _Nonnull)aDelegate queue:(dispatch_queue_t _Nullable)aQueue

Parameters

aDelegate

Delegate to receive OBD real time information.

aQueue

Dispatch queue for executing calls to the delegate. The main queue is used if set to nil.

Discussion

Set the delegate for OBD real time transmission handling.

It is also possible to define a dispatch queue which will be used to execute calls to the delegate. If there is no dispatch queue specified, the main queue is used.

Declared In

TTLServiceClient.h

– setDrivingProfileRealTimeDelegate:queue:

since 1.3.4, use subscribeToFromDrivingProfileData instead (Deprecated: since 1.3.4, use subscribeToFromDrivingProfileData instead)

- (void)setDrivingProfileRealTimeDelegate:(id<TTLServiceDrivingProfileRealTimeDelegate> _Nonnull)aDelegate queue:(dispatch_queue_t _Nullable)aQueue

Declared In

TTLServiceClient.h

– activateEngineStatusUpdates:

Activates engine state updates.

- (void)activateEngineStatusUpdates:(NSString *_Nonnull)deviceIdentifier

Discussion

Activates engine state updates.

Updates of the engine state will be propagated via [TTLServiceEventDelegate onEngineUpdateStatusUpdate:response:]

Declared In

TTLServiceClient.h

– deactivateEngineStatusUpdates:

Deactivates engine state updates.

- (void)deactivateEngineStatusUpdates:(NSString *_Nonnull)deviceIdentifier

Discussion

Deactivates engine state updates.

Updates of the engine state will be propagated via [TTLServiceEventDelegate onEngineUpdateStatusUpdate:response:]

Declared In

TTLServiceClient.h

– activateObdRealTimeTransmission:

Activates the real time transmission of a LINK identified by its identifier. (Deprecated: since 1.3.4, use subscribeToOBDData or subscribeToAccelerationData instead)

- (void)activateObdRealTimeTransmission:(NSString *_Nonnull)deviceIdentifier

Parameters

deviceIdentifier

Unique identifier for LINK device.

Discussion

Activates the real time transmission of a LINK identified by its identifier.

This will try to send a message to the LINK to start real time transmission. If successful [TTLServiceOBDRealTimeDelegate onObdRealTimeDatagram:deviceId:] will be called periodically providing a TTLServiceOBDRealTimeDatagramResponse to deliver OBD real time information. This is also done if the LINK is not able to access the OBD bus.

If the LINK is not connected when calling this method or message sending times out, there will be no failure message or retries.

Declared In

TTLServiceClient.h

– activateRealTimeTransmission:

Method has been renamed to better reflect its behaviour. (Deprecated: Since 1.2.0)

- (void)activateRealTimeTransmission:(NSString *_Nonnull)deviceIdentifier

Discussion

Method has been renamed to better reflect its behaviour.

This method is DEPRECATED! Use [TTLServiceClient activateObdRealTimeTransmission:].

Declared In

TTLServiceClient.h

– deactivateRealTimeTransmission:

Method has been renamed to better reflect its behaviour. (Deprecated: Since 1.2.0)

- (void)deactivateRealTimeTransmission:(NSString *_Nonnull)deviceIdentifier

Discussion

Method has been renamed to better reflect its behaviour.

This method is DEPRECATED! Use [TTLServiceClient deactivateObdRealTimeTransmission:].

Declared In

TTLServiceClient.h

– deactivateObdRealTimeTransmission:

Deactivates the real time transmission of a LINK identified by its identifier. (Deprecated: since 1.3.4, use unsubscribeFromOBDData or unsubscribeFromAccelerationData instead)

- (void)deactivateObdRealTimeTransmission:(NSString *_Nonnull)deviceIdentifier

Parameters

deviceIdentifier

Unique identifier for LINK device.

Discussion

Deactivates the real time transmission of a LINK identified by its identifier.

This will try to send a message to the LINK to stop real time transmission. If successful the LINK will stop sending OBD real time information. It is possible that TTLServiceOBDRealTimeDatagramResponses still arrive after successfully deactivating OBD real time transmission.

Declared In

TTLServiceClient.h

– activateDrivingProfileRealTimeTransmission:

Activates the Driving Profile Transmission. (Deprecated: since 1.3.4, use subscribeToFromDrivingProfileData instead)

- (void)activateDrivingProfileRealTimeTransmission:(NSString *_Nonnull)deviceIdentifier

Parameters

deviceIdentifier

Unique identifier for LINK device.

Discussion

Activates the Driving Profile Transmission.

Driving Profiles contain information about the driving behaviour like cornering, speed-ups or breaking.

Declared In

TTLServiceClient.h

– deactivateDrivingProfileRealTimeTransmission:

Deactivates the Driving Profile Transmission. (Deprecated: since 1.3.4, use unsubscribeFromDrivingProfileData instead)

- (void)deactivateDrivingProfileRealTimeTransmission:(NSString *_Nonnull)deviceIdentifier

Discussion

Deactivates the Driving Profile Transmission.

Declared In

TTLServiceClient.h

– subscribeToOBDData:deviceIdentifier:

Subscribe to OBD data stream to receive OBD data.

- (void)subscribeToOBDData:(id<TTLServiceODBDataSubscriptionProtocol> _Nonnull)subscriber deviceIdentifier:(NSString *_Nonnull)deviceIdentifier

Discussion

Subscribe to OBD data stream to receive OBD data.

This will activate OBD data transmission from the dongle. The SDK will take care of keeping the transmission activated as long as at least on subscriber is registered. This is also true when the dongle disconnects and connects again.

Declared In

TTLServiceClient.h

– subscribeToAccelerationData:deviceIdentifier:

Subscribe to acceleration data stream to receive acceleration data.

- (void)subscribeToAccelerationData:(id<TTLServiceAccelerationDataSubscriptionProtocol> _Nonnull)subscriber deviceIdentifier:(NSString *_Nonnull)deviceIdentifier

Discussion

Subscribe to acceleration data stream to receive acceleration data.

This will activate acceleration data transmission from the dongle. The SDK will take care of keeping the transmission activated as long as at least on subscriber is registered. This is also true when the dongle disconnects and connects again.

Declared In

TTLServiceClient.h

– subscribeToDrivingProfileData:deviceIdentifier:

Subscribe to driving profile data stream to receive driving profile data.

- (void)subscribeToDrivingProfileData:(id<TTLServiceDrivingProfileDataSubscriptionProtocol> _Nonnull)subscriber deviceIdentifier:(NSString *_Nonnull)deviceIdentifier

Discussion

Subscribe to driving profile data stream to receive driving profile data.

This will activate driving profile data transmission from the dongle. The SDK will take care of keeping the transmission activated as long as at least on subscriber is registered. This is also true when the dongle disconnects and connects again.

Declared In

TTLServiceClient.h

– unsubscribeFromOBDData:deviceIdentifier:

Unsubscribe from OBD data stream.

- (void)unsubscribeFromOBDData:(id<TTLServiceODBDataSubscriptionProtocol> _Nonnull)subscriber deviceIdentifier:(NSString *_Nonnull)deviceIdentifier

Discussion

Unsubscribe from OBD data stream.

Stop the notification of the give subscriber. This will stop the transmission on the dongle when last subscriber was unsubscribed.

Declared In

TTLServiceClient.h

– unsubscribeFromAccelerationData:deviceIdentifier:

Unsubscribe from acceleration data stream.

- (void)unsubscribeFromAccelerationData:(id<TTLServiceAccelerationDataSubscriptionProtocol> _Nonnull)subscriber deviceIdentifier:(NSString *_Nonnull)deviceIdentifier

Discussion

Unsubscribe from acceleration data stream.

Stop the notification of the give subscriber. This will stop the transmission on the dongle when last subscriber was unsubscribed.

Declared In

TTLServiceClient.h

– unsubscribeFromDrivingProfileData:deviceIdentifier:

Unsubscribe from driving profile data stream.

- (void)unsubscribeFromDrivingProfileData:(id<TTLServiceDrivingProfileDataSubscriptionProtocol> _Nonnull)subscriber deviceIdentifier:(NSString *_Nonnull)deviceIdentifier

Discussion

Unsubscribe from driving profile data stream.

Stop the notification of the give subscriber. This will stop the transmission on the dongle when last subscriber was unsubscribed.

Declared In

TTLServiceClient.h

– connectToServer:

Connect to TomTom UBI backend system.

- (void)connectToServer:(TTLBackendConnectionSetup *_Nonnull)serverInfo

Parameters

serverInfo

Information needed to establish a connection to the TomTom UBI backend. See TTLBackendConnectionSetup

Discussion

Connect to TomTom UBI backend system.

This configures internal components for communication to the TomTom UBI backend system and then tries to connect to it. If successful the state change is published via [TTLServiceEventDelegate onServiceState:]. There is no error message in case of errors.

Calling this method when a connection is already in place the following scenarios have to considered: - If the serverInfo has not changed, the call will be ignored, [TTLServiceEventDelegate onServiceState:] won’t be called, but [TTLServiceEventDelegate onServerConnectionSuccessful:] will be called. - If the serverInfo has changed, the current connection will be disconnected and the system tries to establish a new one.

Declared In

TTLServiceClient.h

– disconnectFromServer

Disconnect from the TomTom UBI backend system.

- (void)disconnectFromServer

Discussion

Disconnect from the TomTom UBI backend system.

Declared In

TTLServiceClient.h

– deviceVersionInfoForDeviceId:

Returns the last TTLServiceDeviceVersionInfo known for the that device

- (TTLServiceDeviceVersionInfo *_Nullable)deviceVersionInfoForDeviceId:(NSString *_Nonnull)deviceIdentifier

Discussion

Returns the last TTLServiceDeviceVersionInfo known for the that device

This is a convenient method to get the last know device information for a device. It does not ask the device, so it may be outdated. However, that should rarely be a problem, since the device information changes only when a firmware update was done and during that process the SDK renews it internal representation.

Declared In

TTLServiceClient.h

– deviceVersionInfo:

DEPRECATED Use [TTLServiceClient deviceVersionInfoForDeviceId:] (Deprecated: Since 1.2.0)

- (TTLServiceDeviceVersionInfo *_Nullable)deviceVersionInfo:(NSString *_Nonnull)deviceIdentifier

Declared In

TTLServiceClient.h

– hasBufferedData:

Indicates if the smart phone holds data which still has to be submitted to the UBI backend service.

- (BOOL)hasBufferedData:(NSString *_Nonnull)deviceIdentifier

Discussion

Indicates if the smart phone holds data which still has to be submitted to the UBI backend service.

For example this can be the case when the sync process was start without a connection to the UBI backend service.

Declared In

TTLServiceClient.h

– requestServiceState

Requesting the state of the LINK UBI Service.

- (void)requestServiceState

Discussion

Requesting the state of the LINK UBI Service.

This will be answered by [TTLServiceEventDelegate onServiceState:] which provides an array of TTLServiceStateResponse. TTLServiceStateResponse contains information about connection state for a LINK devices and UBI backend servers.

Declared In

TTLServiceClient.h

– requestDeviceState

Requesting the state of the LINK device.

- (void)requestDeviceState

Discussion

Requesting the state of the LINK device.

This will be answered by [TTLServiceEventDelegate onDeviceState:response:] for every connected device. See TTLServiceDeviceStateResponse for more information about what this state is about.

[TTLServiceEventDelegate onDeviceState:response:] will only be called for devices that are currently connected, not for devices that connected after the request. Also [TTLServiceEventDelegate onDeviceState:response:] is only called for devices that are activated. So be aware that [TTLServiceEventDelegate onDeviceState:response:] may not be called at all depending on the connected devices and their activation state.

Declared In

TTLServiceClient.h

– scanForDevices

Looks for connected LINK devices

- (void)scanForDevices

Discussion

Looks for connected LINK devices

This can be useful in the case a LINK device was connected before the app was started. Calling this method behaves like if the LINK device is connects while the app is already running. For every connected device [TTLServiceEventDelegate onDeviceDidAppear:] is called

Note: This may be removed in the future and replaced by automatic mechanism.

Declared In

TTLServiceClient.h

– sendAPNDeviceToken:

Sends the APN Token to the backend to enable it to send push notifications

- (void)sendAPNDeviceToken:(NSData *_Nonnull)apnToken

Discussion

Sends the APN Token to the backend to enable it to send push notifications

The token has to be generated by the app and is specific for the app bundle id and device

Also be aware that the backend has to be configured with your certificates for the app.

Declared In

TTLServiceClient.h

– changeOdometer:deviceIdentifier:

The client can change the value of the virtual odometer of the dongle. The service will answer with [TTLServiceEventDelegate onOdometerChange:response:]

- (void)changeOdometer:(TTLServiceOdometerValueParameter *_Nonnull)parameter deviceIdentifier:(NSString *_Nonnull)deviceIdentifier

Discussion

The client can change the value of the virtual odometer of the dongle. The service will answer with [TTLServiceEventDelegate onOdometerChange:response:]

Declared In

TTLServiceClient.h

– requestDTCList:

Requests a list with DTCs (OBD Diagnostic Trouble Codes) from the dongle. The Core answers with [TTLServiceEventDelegate onDTCList:response:]

- (void)requestDTCList:(NSString *_Nonnull)deviceIdentifier

Discussion

Requests a list with DTCs (OBD Diagnostic Trouble Codes) from the dongle. The Core answers with [TTLServiceEventDelegate onDTCList:response:]

Declared In

TTLServiceClient.h

– sendClockSyncReasonForDownload:deviceIdentifier:

Sends a reason for a clock sync requested by the LINK device before a download of driving data can be initiated. The reason itself can be an arbitrary id.

- (void)sendClockSyncReasonForDownload:(TTLServiceDeviceUnplugReason *_Nonnull)reason deviceIdentifier:(NSString *_Nonnull)deviceIdentifier

Parameters

reason

Represents a arbitrary reason why a clock sync is needed. The value of [TTLServiceDeviceUnplugReason.reason] can freely chosen by the app.

Discussion

Sends a reason for a clock sync requested by the LINK device before a download of driving data can be initiated. The reason itself can be an arbitrary id.

The LINK device requests a clock sync via [TTLServiceEventDelegate onClockSyncReasonWhileDownloadRequired:]. If the user of the custom app has entered a reason the custom app uses this method to send back the reason after which the Core will initiate the download of the driving data. Since the clock sync is started immediately a connection to the LINK device and the UBI backend is required.

If the clock was successfully synchronized [TTLServiceEventDelegate onClockSyncSuccessful:reason:] is called.

Declared In

TTLServiceClient.h

– sendClockSyncReasonForDeviceSetup:deviceIdentifier:

Sends a reason for a clock sync request. In case the LINK device is set up initially or after a the TomTom UBI service recognized a disconnect of the LINK device in the meantime. The reason itself can be an arbitrary id.

- (void)sendClockSyncReasonForDeviceSetup:(TTLServiceDeviceUnplugReason *_Nonnull)reason deviceIdentifier:(NSString *_Nonnull)deviceIdentifier

Parameters

reason

Represents a arbitrary reason why a clock sync is needed. The value of [TTLServiceDeviceUnplugReason.reason] can freely chosen by the app.

Discussion

Sends a reason for a clock sync request. In case the LINK device is set up initially or after a the TomTom UBI service recognized a disconnect of the LINK device in the meantime. The reason itself can be an arbitrary id.

If the clock was successfully synchronized [TTLServiceEventDelegate onClockSyncSuccessful:reason:] is called.

Declared In

TTLServiceClient.h

– startActivationForDevice:

Starts the activation of the LINK device.

- (void)startActivationForDevice:(NSString *_Nonnull)deviceIdentifier

Discussion

Starts the activation of the LINK device.

The activation is a verification process which authenticates the device against the backend.

The App (client) is responsible for checking that the device and the backend are connected. If one of the connection is missing the activation will fail and [TTLServiceEventDelegate onActivationFailed:reason:] will be called.

If one of the connections got lost before [TTLServiceEventDelegate onActivationFailed:reason:] or [TTLServiceEventDelegate onActivationSuccessful:] was called, you can consider the activation as failed. However, it is possible that the activation finishes successful or with failure when the connections are established again.

It is safe to do repeat an activation.

Declared In

TTLServiceClient.h

– startSyncForDevice:

Request syncing the LINK device with UBI backend services.

- (void)startSyncForDevice:(NSString *_Nonnull)deviceIdentifier

Parameters

deviceIdentifier

Unique identifier for LINK device.

Discussion

Request syncing the LINK device with UBI backend services.

A client can trigger the download of driving data with this method. The Service answers with several calls to [TTLServiceEventDelegate onDownloadStatusUpdate:response:]

Note, that the download of driving data does not necessarily need a dual connection to the LINK device and server at the same time. A user could download the driving data from the LINK device in an underground parking lot without connection to the Internet. Afterwards when he again gains access to the Internet the downloaded driving data will be automatically uploaded to the server.

Note also, that the Service could answer with [TTLServiceEventDelegate onClockSyncReasonWhileDownloadRequired:] requesting a reason for the synchronisation of the clock of the LINK device before actually starting to download the driving data from the LINK device. This happens, when the device lost power for a period of time, for example because it was unplugged from the OBD port. The synchronization requires that the app is are connected to the LINK device and the UBI backend service.

Declared In

TTLServiceClient.h

– updateFirmware:deviceIdentifier:

Initiates the firmware update after having received the required firmware file id via [TTLServiceEventDelegate onFirmwareUpdateAvailable:response:]

- (void)updateFirmware:(TTLServiceFirmwareUpdateParameter *_Nonnull)firmwareUpdateParameter deviceIdentifier:(NSString *_Nonnull)deviceIdentifier

Discussion

Initiates the firmware update after having received the required firmware file id via [TTLServiceEventDelegate onFirmwareUpdateAvailable:response:]

Declared In

TTLServiceClient.h