OBD.connect SDK Reference

Installation & Project Setup

  • Drag the file LINK100-SDK.framework into your Xcode project (and mark all targets in which you want to use it).
  • add the option -ObjC to the Other Linker Flags of your targets/project. This is needed to link categories code correctly.
  • add the SystemConfiguration.framework and MobileCoreServices.framework to the project. This is used by AFNetworking.
  • Add UISupportedExternalAccessoryProtocols to your Info.plist and set it to the following value com.tomtom.business.ubi
  • Enable the following capabilities for your XCode project
    • Background Modes, mode External accessory communication
    • Wireless Accessory Configuration
  • If you used an older version of the SDK please delete your derived data folders of Xcode or AppCode. Otherwise the cached files may create false compile/link errors.

Connections

For testing purposes please use the following parameters to connect to WEBFLEET:

  • WEBFLEET Messaging Server Host Name: its-robin-gprs.business.tomtom.com
  • WEBFLEET Messaging Server Port: 443
  • WEBFLEET.connect Server Host Name: https://its-wfc.business.tomtom.com/extern
  • WEBFLEET.connect API Key: UBI-ROBIN-SINGLEOBJECT

When you are done with testing and want to switch to production environment please use the following parameters to connect to WEBFLEET:

  • WEBFLEET Messaging Server Host Name: robin-gprs.business.tomtom.com
  • WEBFLEET Messaging Server Port: 443
  • WEBFLEET.connect Server Host Name: https://csv.business.tomtom.com/extern
  • WEBFLEET.connect API Key: handed to the sdk user on a per-company basis

See TTLBackendConnectionSetup for details.

Firmware Update

A firmware check is automatically done upon successful connection to backend and device. The activation of the device must be finished and valid.

Firmware update state machine
Firmware update state machine

It’s recommended to use a state machine to handle the firmware update process properly (like the one above).

If a new firmware is available [TTLServiceEventDelegate onFirmwareUpdateAvailable:response:] is triggered. The firmwareFileId contained in the response should only be used once for the firmware update process. In case the update fails (for any reason) it’s NOT recommended to restart the firmware update process, but to forget about the available firmware update and switch back to the “No firmware update available” state. A firmware update can be initiated by WEBFLEET at any time so it is recommended to give the user the possibility to accept or decline the firmware update during normal operation.

As soon as the update has been started (from orange state - see above) via [TTLServiceClient updateFirmware:deviceIdentifier:], the download of the new firmware from the TomTom server starts. The download start is reported by a call to [TTLServiceEventDelegate onFirmwareUpdateStatusUpdate:response:] with status TTLServiceFirmwareDownloadStarted. After that there are several subsequent calls to [TTLServiceEventDelegate onFirmwareUpdateStatusUpdate:response:] with status TTLServiceFirmwareDownloadProgress reporting the progress of the download from 0 to 100% which can be used for progress indication in your app. The download ends when status TTLServiceFirmwareDownloadFinished is reported.

Subsequently the upload of the firmware to the device starts. Status and progress is reported similarly by several calls to [TTLServiceEventDelegate onFirmwareUpdateStatusUpdate:response:]. The status passes from TTLServiceFirmwareUploadStarted to TTLServiceFirmwareUploadProgress and eventually to TTLServiceFirmwareUploadFinished when the upload is completed.

The firmware installation process starts when the status TTLServiceFirmwareInstallRequested is reported. Before actually starting the firmware installation all remaining collected driving data on the device is automatically transmitted to WEBFLEET via the smartphone. When sending of the messages is done the firmware is finally being installed on the device. The device preforms an automatic restart for the new firmware to take effect. After restart the device tries to reconnect to the last known bluetooth address. Thus as soon as the device has been reconnected the firmware update process is finished.

NOTE
During firmware upload real time streams are disabled automatically by the sdk and resumed afterwards. However it is generally a good practice to stop all other interaction with the sdk during the firmware update process.

Known Issues

The following is a list areas were work needs to be done.

NOTE: Please mind to integrate 3rd party licence notices into your App.

Definition of Terms

The following terms are used in the documentation with following meaning:

  • device always means the device talking to the smartphone, like a LINK100 UBI. The term ‘LINK’, ‘LINK device’ and ‘LINK100’ are equivalent.
  • TomTom UBI Service the combination of a backend service and a LINK100 device to deliver services for UBI. The term ‘service’ is used as equivalent.

Release Notes

1.0.0beta => 1.0.0

The following changes may create the need of adopt already written code.

1.0.0 => 1.0.1

1.0.1 => 1.1.0

1.0.1 => 1.1.1

  • Fixed: uncommon setting for the app version numbers could create problems in communication with the LINK100 device during activation.

1.1.1 => 1.1.2

1.1.2 => 1.1.3

  • Fixed a bug that could create a crash when parsing broken UTF-8 string (e.g. sometimes OBD returns broken VINs)
  • Added support for OBD fuel level
  • Improved support for exchanging hardware.

1.1.3 => 1.1.4

  • Fixed a bug which prevented the SDK from connecting in certain conditions.

1.1.4 => 1.1.5

  • Fixed a bug that could slow down the firmware upload to the LINK 100 device

1.1.5 => 1.2.0

New features when used with LINK 100 Firmware 1.5 or newer:

1.2.0 => 1.2.1

1.2.1 => 1.2.2

  • Workaround for iOS 9 beta issues when reconnecting the LINK 100.

1.2.2 => 1.3.0

1.3.0 => 1.3.1

  • Fixed missing header TTLServiceRealTimeDataSubscriptionProtocol.h on framework container

1.3.1 => 1.3.2

  • improved firmware update process and extended documentation, including a complete description of the firmware update process
  • fixed a bug that causes real time feed not to work after a failed firmware update

1.3.2 => 1.3.3

  • updated AFNetworking to 2.6.3 (806d8702078eff458239cfa05cf19631f383c688)
  • Increaesed API usability for swift (genericification and nullability informations added)
  • Fixed a bug that preveted the VIN from showing up in TTLServiceStateResponse in some cases
  • FIxed a bug that preveted onOdometerChange to be called in certain cases
  • Fixed a bug that preveted eventDownloadFromDeviceFailed and eventDownloadFromDeviceProgress from being published in certain cases
  • Improvement: Disconnecting from the backend will now wait until the message queue is drained before the connection is finally closed

1.3.3 => 1.3.4

  • Improvement: Disconnect now waits a fixed amount of time (additionally to waiting for all message to be sent) before actually disconnecting. This improves sync behavior for instance, as there is more chance of handling backend replies.
  • Improvement: Add deprecation warnings to [TTLServiceClient setObdRealTimeDelegate:queue:], [TTLServiceClient setDrivingProfileRealTimeDelegate:queue:] and related methods
  • Improvement: Update on project setup instructions
  • Improvement: Include bitcode into SDK framework build
  • Fix: Remove code coverage instrumentation on SDK build. Code coverage linker flags are not needed anymore on client projects for release builds.
  • Fix: Realtime data streams automatically resume after device reconnection, as indicated by documentation. There is no need to resume manually anymore. See [TTLServiceClient subscribeToOBDData:deviceIdentifier:] for details.
  • Update: Switch from docset to HTML documentation, as docset build is no longer available

Class References

Protocol References

Constant References