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 theOther Linker Flags
of your targets/project. This is needed to link categories code correctly. - add the
SystemConfiguration.framework
andMobileCoreServices.framework
to the project. This is used by AFNetworking. - Add
UISupportedExternalAccessoryProtocols
to yourInfo.plist
and set it to the following valuecom.tomtom.business.ubi
- Enable the following capabilities for your XCode project
Background Modes
, modeExternal 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.
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.
- Localized errors are only in english, also not all errors are localized yet.
- the framework contains open source code that may create linking conflicts when the same third party code is used. that is:
AFNetworking
, github commit:806d8702078eff458239cfa05cf19631f383c688
, https://github.com/AFNetworking/AFNetworkingCSVKit
, github commit:bb0e51549015fba35890e91dbf001282b3b24b2d
, https://github.com/booyah/CSVKitGCDAsyncSocket
, github commit:d7296b3277892ba769d075405987991be3d4181b
, https://github.com/robbiehanson/CocoaAsyncSocketCocoaLumberjack
, github commit:8d55aa76f5dc7e18762d4c3888a449323c4c4b44
, https://github.com/CocoaLumberjack/CocoaLumberjack
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.
Changed class names
TTLDeviceVersionInfo
=> TTLServiceDeviceVersionInfo
TTLServiceDownloadStateResponse
=> TTLServiceDownloadStatusResponse
TTLDisconnectReason
=> TTLServiceDeviceUnplugReason
TTLObdRealTimeDatagram
=> TTLServiceOBDRealTimeDatagram
TTLObdRealTimeDatagramResponse
=> TTLServiceOBDRealTimeDatagramResponse
1.0.0 => 1.0.1
- Added [TTLServiceEventDelegate onServerConnectionSuccessful:] & [TTLServiceEventDelegate onServerConnectionFailed:reason:] to be able to specific track connection attempts.
- The device data download process was enhanced to notify the client app when the data downloaded from the LINK 100 device was successfully uploaded to the backend.
For that [TTLServiceDownloadStatusResponse progressState] now has an additional status
TTLServiceUploadSuccessful
- fixed a wrong respondToSelector check which prevents [TTLServiceEventDelegate onDTCList:response:] from being called
- A failed server connection because of wrong credentials (username, password) or wrong device identifier can now be detected using the reason param of [TTLServiceEventDelegate onServerConnectionFailed:reason:]
- In the case of wrong credentials [TTLServiceServerConnectionFailedReason error] contains an error with the code
TTL_SERVICE_ERROR_CODE_SERVER_CONNECTION_WRONG_CREDENTIALS
. - In the case of using a wrong device identifier with valid credentials [TTLServiceServerConnectionFailedReason error] contains an error with the code
TTL_SERVICE_ERROR_CODE_SERVER_CONNECTION_WRONG_DEVICE_ID
.
- In the case of wrong credentials [TTLServiceServerConnectionFailedReason error] contains an error with the code
1.0.1 => 1.1.0
- Added [TTLServiceClient sendAPNDeviceToken:] to transport the APN token to the backend.
- Added [TTLServiceClient deviceVersionInfo:] as convenient method to access the cached device information of the LINK 100.
- Added a description method to most of the API domain objects to better support debugging.
- Added a TTLServiceFirmwareInstallRequested status to TTLServiceFirmwareUpdateStatus to reflect when SDK requested the LINK 100 to install the uploaded firmware.
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
- empty credentials will now create an [TTLServiceEventDelegate onServerConnectionFailed:reason:] call with the error code
TTL_SERVICE_ERROR_CODE_SERVER_CONNECTION_WRONG_CREDENTIALS
- further improved the detection of invalid user and device combinations.
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
- Support for multiple TTLServiceClient delegates – see [TTLServiceClient addServiceDelegate:]
- Bugfix for wrong handling of parallel firmware updates
- raised the version of GCDAsyncSocket to 7.4.1 (commit
d7296b3277892ba769d075405987991be3d4181b
) - Bugfix for missing error reporting to app on failed data upload in case of delayed transmission or slow server
processing. Reported via [TTLServiceEventDelegate onDownloadStatusUpdate:response:] with status
TTLServiceDownloadFailed
New features when used with LINK 100 Firmware 1.5 or newer:
- Real time profile data feed – see [TTLServiceClient setDrivingProfileRealTimeDelegate:queue:].
This allows an application to provide real time feedback about the driving performance/driving score. The profile data is reset after a downtime (engine off) of more than two hours. - Engine status notifications – see [TTLServiceEventDelegate onEngineUpdateStatusUpdate:response:].
Using this callback, the application can be notified by the SDK about engine on/off events. Note that (depending on the vehicle) the engine off notification might only be reported up to 10 seconds after the vehicle’s engine is turned off - Extended OBD real time feed, see TTLServiceOBDRealTimeDatagram
Additional values are only delivered if supported by the vehicle.
1.2.0 => 1.2.1
- Fixed concurrency issues when adding multiple delegates to TTLServiceClient.
1.2.1 => 1.2.2
- Workaround for iOS 9 beta issues when reconnecting the LINK 100.
1.2.2 => 1.3.0
- Added new subscription model for real time data streams allowing for several listeners, see
- Fixed LINK 100 firmware update issues on iOS 9.2
- Improved LINK 100 accessory recognition, reducing the amount of [TTLServiceEventDelegate onDeviceDidAppear:] calls
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
- TTLBackendConnectionSetup
- TTLDrivingProfileHistogram
- TTLServiceActivationFailedReason
- TTLServiceClient
- TTLServiceClientConfiguration
- TTLServiceClockSyncFailedReason
- TTLServiceClockSyncForActionResponse
- TTLServiceCrashDatagram
- TTLServiceCrashDatagramResponse
- TTLServiceDTCListResponse
- TTLServiceDeviceStateResponse
- TTLServiceDeviceUnplugReason
- TTLServiceDeviceVersionInfo
- TTLServiceDownloadStatusResponse
- TTLServiceDrivingProfileDatagram
- TTLServiceDrivingProfileRealTimeResponse
- TTLServiceEngineStatusResponse
- TTLServiceFirmwareUpdateAvailableResponse
- TTLServiceFirmwareUpdateParameter
- TTLServiceFirmwareUpdateStatusResponse
- TTLServiceMutableDrivingProfileDatagram
- TTLServiceMutableOBDRealTimeDatagram
- TTLServiceOBDRealTimeDatagram
- TTLServiceOBDRealTimeDatagramResponse
- TTLServiceOdometerChangeResponse
- TTLServiceOdometerValueParameter
- TTLServiceServerConnectionFailedReason
- TTLServiceStateResponse
- TTLServiceTransmissionResponse
Protocol References
- TTLAccelerationDatagram
- TTLDrivingProfileDatagram
- TTLOBDDatagram
- TTLServiceAccelerationDataSubscriptionProtocol
- TTLServiceDrivingProfileDataSubscriptionProtocol
- TTLServiceDrivingProfileRealTimeDelegate
- TTLServiceEventDelegate
- TTLServiceOBDRealTimeDelegate
- TTLServiceODBDataSubscriptionProtocol