See: Description
Interface | Description |
---|---|
ClientProtocolDefinition.ActivationFinished |
Indicates the activation was successfully finalized.
|
ClientProtocolDefinition.ActivationStart |
Indicates that a new activation was initiated.
|
ClientProtocolDefinition.ClockSyncReasonForDeviceSetupRequest |
Sends a reason entered by the user for a dongle that was disconnected in the meantime.
|
ClientProtocolDefinition.ClockSyncReasonForDeviceSetupResponse |
Indicates sending the reason was successful.
|
ClientProtocolDefinition.ClockSyncReasonForDownloadRequest |
Returns a reason entered by the user for a dongle that was disconnected in the meantime.
|
ClientProtocolDefinition.ClockSyncReasonForDownloadRequired |
Indicates a reason is required to be entered by the user for a dongle that was disconnected in the meantime.
|
ClientProtocolDefinition.ClockSyncReasonForDownloadResponse |
Indicates sending the reason for downloading the driving data was successful.
|
ClientProtocolDefinition.ConnectionStatusDongle |
Indicates the current connection status of the dongle.
|
ClientProtocolDefinition.ConnectionStatusServer |
Indicates the current connection status of WEBFLEET MESSAGING.
|
ClientProtocolDefinition.CoreBoot |
This command must be the first message the client needs to send after having established an Android service connection to the core service.
|
ClientProtocolDefinition.CoreBooted |
This message is sent back from the core to the client upon successful initialization.
|
ClientProtocolDefinition.CoreStateRequest |
Requests the current internal state of the core.
|
ClientProtocolDefinition.CoreStateResponse |
Returns the current internal state of the core.
|
ClientProtocolDefinition.CrashDetectedDatagramTransmission |
A transmission of a 'crash detected' datagram.
|
ClientProtocolDefinition.DeviceStatusRequest |
Requests status data information from the dongle.
|
ClientProtocolDefinition.DeviceStatusResponse |
Returns device status information of the dongle.
|
ClientProtocolDefinition.DisconnectFromDongle |
Disconnects from dongle.
|
ClientProtocolDefinition.DisconnectFromServer |
Disconnects from server.
|
ClientProtocolDefinition.DongleDisconnectOnIdleTimeout |
Requests an update of the odometer value of the dongle.
|
ClientProtocolDefinition.DownloadFromDongleFailed |
Indicates the download of data from dongle has failed on the dongle.
|
ClientProtocolDefinition.DownloadFromDongleFinished |
Indicates the download of data from dongle has finished.
|
ClientProtocolDefinition.DownloadFromDongleProgress |
Indicates the download of data from dongle is progressing.
|
ClientProtocolDefinition.DownloadFromDongleStarted |
Indicates the download of data from dongle has started.
|
ClientProtocolDefinition.Error |
This message is sent in case of an error.
|
ClientProtocolDefinition.FirmwareUpdateAvailable |
Indicates that a new firmware is ready for download.
|
ClientProtocolDefinition.FirmwareUpdateDownloadFailed |
Indicates that the smartphone failed to download the new firmware.
|
ClientProtocolDefinition.FirmwareUpdateDownloadFinished |
Indicates that the smartphone finished downloading the new firmware.
|
ClientProtocolDefinition.FirmwareUpdateDownloadProgress |
Indicates that the smartphone progressed downloading the new firmware.
|
ClientProtocolDefinition.FirmwareUpdateDownloadStarted |
Indicates that the smartphone started to download a new firmware.
|
ClientProtocolDefinition.FirmwareUpdateUploadFailed |
Indicates that the smartphone failed to upload the new firmware.
|
ClientProtocolDefinition.FirmwareUpdateUploadFinished |
Indicates that the smartphone finished uploading the new firmware.
|
ClientProtocolDefinition.FirmwareUpdateUploadProgress |
Indicates that the smartphone progressed uploading the new firmware.
|
ClientProtocolDefinition.FirmwareUpdateUploadStarted |
Indicates that the smartphone started to upload the new firmware.
|
ClientProtocolDefinition.InboundMessage |
Marker interface for indicating inbound messages.
|
ClientProtocolDefinition.ObdDtcRequest |
Requests current DTC information from the dongle.
|
ClientProtocolDefinition.ObdDtcResponse |
Returns current DTC information from the dongle.
|
ClientProtocolDefinition.ObdRealTimeDatagramTransmission |
A transmission of a OBD real time datagram.
|
ClientProtocolDefinition.OdometerChangeRequest |
Requests an update of the odometer value of the dongle.
|
ClientProtocolDefinition.OdometerChangeResponse |
Returns the status of the requested change of the odometer value.
|
ClientProtocolDefinition.OutboundMessage |
Marker interface for indicating outbound messages.
|
ClientProtocolDefinition.OutboundQueueStatusUpdateDongle |
Indicates the current status of the outbound queue of the dongle side.
|
ClientProtocolDefinition.OutboundQueueStatusUpdateServer |
Indicates the current status of the outbound queue of the WFM server side.
|
ClientProtocolDefinition.ReconnectToDongle |
Reconnects manually to the dongle if currently disconnected.
|
ClientProtocolDefinition.ReconnectToServer |
Reconnects manually to the WEBLFEET MESSAGING if currently disconnected.
|
ClientProtocolDefinition.SendFcmRegistrationToken |
Sends the FCM registration token.
|
ClientProtocolDefinition.StartActivation |
Starts the activation of the dongle.
|
ClientProtocolDefinition.StartDrivingProfileRealTimeDataTransmission |
Initiates the driving profile data stream.
|
ClientProtocolDefinition.StartEngineStatusUpdateTransmission |
Starts the engine status updates.
|
ClientProtocolDefinition.StartObdRealTimeDataTransmission |
Initiates the real time data stream.
|
ClientProtocolDefinition.StartSynchronisation |
Starts the data download from dongle and upload process to WEBFLEET MESSAGING.
|
ClientProtocolDefinition.StopDrivingProfileRealTimeDataTransmission |
Stops the real time data stream.
|
ClientProtocolDefinition.StopEngineStatusUpdateTransmission |
Stops the engine status updates.
|
ClientProtocolDefinition.StopObdRealTimeDataTransmission |
Stops the real time data stream.
|
ClientProtocolDefinition.TransmissionFromDongle |
Indicates that the dongle sent a message to the smartphone.
|
ClientProtocolDefinition.TransmissionFromServer |
Indicates that the WFM sent a message to the smartphone.
|
ClientProtocolDefinition.TransmissionToDongle |
Indicates that the smartphone sent a message to the dongle.
|
ClientProtocolDefinition.TransmissionToServer |
Indicates that the smartphone sent a message to the dongle.
|
ClientProtocolDefinition.UpdateFirmware |
Indicates that the client side confirmed starting the firmware update.
|
ClientProtocolDefinition.UploadToServerFinished |
Indicates the upload of data to the server has finished.
|
Core |
This interface is the main entry point of the TomTom UBI Core component if used as Android library.
|
ServiceClient |
This interface is the main access point for an external client.
|
ServiceClientCallback |
This interface serves as callback for any communication from the Core component to the custom app.
|
Class | Description |
---|---|
AppVersionInfo |
Contains version information of the Core.
Copyright (c) 2013 - 2016 TomTom Telematics, all rights reserved. |
ClientProtocolDefinition |
This protocol definition lists all message id's and additional data fields for all inbound and outbound messages.
Copyright (c) 2013 - 2016 TomTom Telematics, all rights reserved. |
CoreBootParameter |
Contains all data needed to start the Core and activate a dongle with WEBFLEET.
|
CoreBootParameter.Builder | |
CoreState |
This structure keeps some state-related data like version information and activation status.
|
CrashDetectedDatagram |
Contains crash detection data.
See ServiceClientCallback.onCrashDetectedDatagram(com.tomtom.business.ubi.commons.api.ServiceClientCallback.CrashDetectedDatagramResponse) .Copyright (c) 2013 - 2016 TomTom Telematics, all rights reserved. |
DeviceStatus |
Contains the additional device status information like odometer and the like.
|
DisconnectReasonParameter |
Used to wrap arbitrary disconnect reasons.
|
DongleVersionInfo |
Contains version information about the software and hardware of the dongle.
Copyright (c) 2013 - 2016 TomTom Telematics, all rights reserved. |
DrivingProfileRealTimeDatagram |
A profile of driving behaviour related to a certain time frame.
|
FcmRegistrationParameter |
Wraps the FCM registration values.
|
FirmwareUpdateParameter |
Needed for initiating the firmware update.
Copyright (c) 2013 - 2016 TomTom Telematics, all rights reserved. |
GcmRegistrationParameter | Deprecated
use
FcmRegistrationParameter instead |
ObdRealTimeDatagram |
Contains real-time OBD data.
|
OdometerValueParameter |
Wraps the odometer value.
|
ServiceClientCallback.ClockSyncForActionResponse |
Encapsulates the cause of the successful synchronisation of the clock.
|
ServiceClientCallback.ConnectionStatusResponse |
Contains the current connection state of the end point specified by
the
ServiceClientCallback.ConnectionStatusResponse.endPoint parameter. |
ServiceClientCallback.CoreStateResponse |
Contains the current state of the Core.
|
ServiceClientCallback.CrashDetectedDatagramResponse |
Contains a datagram containing crash-related data received via
ServiceClientCallback.onCrashDetectedDatagram(CrashDetectedDatagramResponse) . |
ServiceClientCallback.DeviceStatusResponse |
Encapsulates the current device status.
|
ServiceClientCallback.DownloadStatusResponse |
Encapsulates the current progress after calling
ServiceClient.startSync() . |
ServiceClientCallback.DrivingProfileRealTimeDatagramResponse |
Contains a OBD real-time datagram received via
ServiceClientCallback.onObdRealTimeDatagram(ObdRealTimeDatagramResponse) . |
ServiceClientCallback.EngineStatusResponse |
Contains a boolean whether the engine was switched on or off.
|
ServiceClientCallback.FirmwareUpdateAvailableResponse |
Encapsulates the information that a firmware update is available.
|
ServiceClientCallback.FirmwareUpdateStatusResponse |
Encapsulates the current progress after a firmware update has been initiated.
|
ServiceClientCallback.ObdDtcListResponse |
Contains a list of DTCs received via
ServiceClientCallback.onObdDtcList(ObdDtcListResponse) . |
ServiceClientCallback.ObdRealTimeDatagramResponse |
Contains a OBD real-time datagram received via
ServiceClientCallback.onObdRealTimeDatagram(ObdRealTimeDatagramResponse) . |
ServiceClientCallback.OdometerChangeResponse |
Encapsulates the result of a call to
ServiceClient.changeOdometer(OdometerValueParameter) |
ServiceClientCallback.OutboundQueueStatusUpdateResponse |
Contains the current number of messages in the queue specified by
the
ServiceClientCallback.OutboundQueueStatusUpdateResponse.outboundQueue parameter. |
ServiceClientCallback.TransmissionResponse |
Encapsulates a transmission state.
|
ServiceClientCallback.UbiErrorCodeResponse |
Upon each error in the Core an error message is also sent back to the custom app.
|
ServiceClientCallback.UploadToServerFinishedResponse |
Encapsulates the creation time of the last UBI data in the dongle.
|
Enum | Description |
---|---|
ActivationStatus |
Enumerates the possible activation stages.
|
ConnectionStatus |
Indicates the current state of connection to the other side.
Copyright (c) 2013 - 2016 TomTom Telematics, all rights reserved. |
CoreInitializationStatus |
Lists the possible initialization states of the Core.
Copyright (c) 2013 - 2016 TomTom Telematics, all rights reserved. |
EndpointConnectedStatus |
Lists "connected" states of the Core to both dongle and server.
Copyright (c) 2013 - 2016 TomTom Telematics, all rights reserved. |
FirmwareUpdateStatus |
Enumerates the different firmware update states sent with
ServiceClientCallback.onFirmwareUpdateStatusUpdate(FirmwareUpdateStatusResponse) .Copyright (c) 2013 - 2016 TomTom Telematics, all rights reserved. |
OdometerChangeStatus |
Indicates the state of the change of the odometer on the dongle side.
|
ServiceClientCallback.ClockSyncForAction |
A list of actions denoting the cause of a synchronisation of the clock in the dongle.
|
ServiceClientCallback.DownloadProgressState |
A list of states that indicate the current progress of downloading of driving data from the dongle.
|
ServiceClientCallback.EndPoint |
Definition of end points.
|
ServiceClientCallback.TransmissionState |
Indicates that a piece of communication took place.
|
UbiErrorCode |
Enumeration of possible error codes.
Copyright (c) 2013 - 2016 TomTom Telematics, all rights reserved. |
Core
is a component that handles the communication between the TomTom dongle (Bluetooth), all
back-end systems (TCP and others) and the custom client application (IPC). It is implemented as an Android service that can be run in
a remote service process independent from the client application or as service embedded in the client application.
Core
for more information. This approach lets a client deeply integrate with the Core component.
A comprehensive API based on the Request/Reply pattern eases the integration. Multiple concurrent clients are not supported at the moment.
A client-local service that binds to the Core can be used to keep the Core running without UI if background processing is desired.
ConnectivityManager.CONNECTIVITY_ACTION
broadcast.
If desired a client has to catch this event and call ServiceClient.reconnectToDongle()
and
ServiceClient.reconnectToServer()
.CoreBootParameters
for the connection 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
WEBFLEET.connect API Key: UBI-ROBIN-SINGLEOBJECT
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
WEBFLEET.connect API Key: This is handed to the developer on a per-company basis.
ServiceClientCallback.onFirmwareUpdateAvailable(ServiceClientCallback.FirmwareUpdateAvailableResponse)
is called the client should discard any further 'firmware-available' callbacks until the user has finally finished the update process,
that is either the user declined the request for firmware update or the firmware update was eventually carried out
no matter if successful or not.
ServiceClient.bootCore(CoreBootParameter)
.
Among others user name, password and a Bluetooth device (the dongle) are required when connecting. The Bluetooth device can be acquired using the
recommendations regarding Bluetooth in the Android documentation. Upon successful initialization
ServiceClientCallback.onCoreBooted()
is called.
After this callback the client can call arbitrary functions in the Core. Please note: The client may not call any other methods in the Core until
ServiceClientCallback.onCoreBooted()
was called. The
'core-booted' callback doesn't mean the activation was successful but only that all internal subsystems of the Core have properly been started.
Depending on the current state of the activation internal communication takes place between dongle and WEBFLEET.
Upon successful activation the Core calls ServiceClientCallback.onActivationFinished()
.
CoreBootParameter.reset
flag with
ServiceClient.bootCore(CoreBootParameter)
. Then the activation will be carried out from scratch.
Please note: Any local data - even downloaded driving data - will be erased when the reset flag is sent!
ServiceClientCallback.onConnectionStatusUpdate(ServiceClientCallback.ConnectionStatusResponse)
on every change of the connection status to either WEBFLEET or dongle. Upon ServiceClient.bootCore(CoreBootParameter)
the Core attempts to connect to both sides, dongle and WEBFLEET. The Core stops to connect if a defined number (10) of connection attempts failed and yields
ConnectionStatus.CONNECTING_FINALLY_FAILED
. Any further function call that requires a connection to either side will try to reconnect then again, so the
user doesn't need to care for reconnection manually.
ServiceClient.requestCoreState()
.
The Core answers with
ServiceClientCallback.onCoreState(ServiceClientCallback.CoreStateResponse)
containing the current state of the Core.
ServiceClient.startSync()
.
Before being able to download the driving data the dongle checks its local clock. If the clock in the dongle needs
synchronization the Core calls ServiceClientCallback.onClockSyncReasonForDownloadRequired()
.
The client must then let the user enter a reason for the clock synchronisation and send this reason back to the Core via
ServiceClient.sendClockSyncReasonForDownload(DisconnectReasonParameter)
.
After that several callbacks (ServiceClientCallback.onDownloadStatusUpdate(ServiceClientCallback.DownloadStatusResponse)
)
indicating the current progress of the download are being called by the Core. It is recommendable to show the progress in the UI while downloading.
Keep the download process shielded from other processes! So in order to not interfere with the sensitive download process stop possibly running OBD real-time feeds or firmware updates or other long-running tasks. The download process informs you about all state changes and thus you can resume the other tasks once the download has completed.
ServiceClientCallback.onFirmwareUpdateAvailable(ServiceClientCallback.FirmwareUpdateAvailableResponse)
is triggered. The firmware file ID contained in this response should only be used once for the next firmware update.
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 update available" state. It's recommended to give the
user the possibility to accept or decline the firmware update once it was announced by the SDK instead of running
the update in background.ServiceClient.updateFirmware(FirmwareUpdateParameter)
a FirmwareUpdateStatus.DOWNLOAD_STARTED
is sent via ServiceClientCallback.onFirmwareUpdateStatusUpdate(ServiceClientCallback.FirmwareUpdateStatusResponse)
.
This status contains the max. progress for the download process and can be used for progress indicators in the app as
the current download progress is reported via FirmwareUpdateStatus.DOWNLOAD_PROGRESS
status updates. The same applies to the upload process where the FirmwareUpdateStatus.UPLOAD_STARTED
status update contains the max. progress for the whole upload procedure of the firmware to the dongle. Keep the firmware update process shielded from other processes! So in order to not interfere with the sensitive firmware update process stop possibly running OBD real-time feeds or continuous downloads from the Dongle or other long-running tasks. The firmware update process informs you about all state changes and thus you can resume the other tasks once the firmware update has been carried out.
ServiceClient.startObdRealtimeTransmission()
.
After this message N ServiceClientCallback.onObdRealTimeDatagram(ServiceClientCallback.ObdRealTimeDatagramResponse)
are triggered periodically if a dongle is currently connected. These callbacks contain various OBD data that can be processed as required. If the client wants to stop the transmission it can
call ServiceClient.stopObdRealtimeTransmission()
.
Please note: To have the transmission of real-time OBD data fully functional and running - even when the device falls asleep, that is the screen is
switched off - the use of a partial wake lock is recommended (acquire the partial wake lock before starting real-time transmission and release it after
real-time transmission has been stopped). However, not all devices directly fall asleep when switching off the device.
Note that keeping a wake lock may drain the battery when poorly implemented, so be cautious here.
Since the firmware update process or the download of driving data from the dongle are sensitive processes stop possibly running OBD real-time feeds as long as there are long-running tasks to do.
ServiceClient.requestDeviceStatus()
.
The Core will answer with ServiceClientCallback.onDeviceStatus(ServiceClientCallback.DeviceStatusResponse)
.
At the moment the device status consists of information about the current number and duration of disconnected periods of the dongle from the
vehicle and the virtual odometer provided by the dongle.
It is recommended to request the vehicle's odometer from the user when the dongle was disconnected. The vehicle could have moved without the dongle installed and so both odometer
values from car and dongle might diverge quickly.
ServiceClient.changeOdometer(OdometerValueParameter)
with a proper odometer value set.
Note: Setting the odometer requires a WEBFLEET connection. A
ServiceClientCallback.onOdometerChange(ServiceClientCallback.OdometerChangeResponse)
is sent back by the dongle upon completion containing the result of the change request.
ServiceClient.sendGcmRegistrationToken(GcmRegistrationParameter)
and
register a GcmListenerService
in its manifest (for more information on this topic please refer to the Android GCM client documentation).
The intent that is sent from WEBFLEET via PN contains an extra (key = 'action', value = 'uploadHint').
ServiceClientCallback.onError(ServiceClientCallback.UbiErrorCodeResponse)
is called by the Core. It returns an UbiErrorCode
and an optional ServiceClientCallback.UbiErrorCodeResponse.errorCodeDescription
.
android.bluetooth.device.action.ACL_CONNECTED
.
See the following example from an Android manifest:
<receiver android:name="com.business.app.DongleWakeupReceiver"> <intent-filter><action android:name="android.bluetooth.device.action.ACL_CONNECTED"/></intent-filter> </receiver>The BroadcastReceiver also returns within the extra's of the Intent the Bluetooth address of the dongle that attempts to connect. The client app can look up this Bluetooth address in its local storage and retrieve the corresponding user credentials. These credentials can then be used to start the Core, initiate the download of driving data and stop the Core if done. The client app can either start an client-local service upon capturing the Intent mentioned above and bind to the Core and control it the normal way or it can use a simple Intent-based interface. Please note, the calls to the BroadcastReceiver listening for
android.bluetooth.device.action.ACL_CONNECTED
may happen quite frequently.
To avoid repeatedly booting the Core and running into concurrency issues the BroadcastReceiver should track the last start time of the Core and reject further
connection requests if the Core was just started. Otherwise the Core would stop and restart itself each time upon each new call to boot.
It is also possible to trigger another connection attempt using ServiceClient.reconnectToDongle()
or
ServiceClient.reconnectToServer()
.
ClientProtocolDefinition.INTENT_CORE_BOOT_ACTION
via
Context.sendBroadcast(Intent)
.
ClientProtocolDefinition.INTENT_CORE_CALLBACK_ACTION
. The Intent that is delivered to such a BroadcastReceiver
contains an extra named ClientProtocolDefinition.EXTRA_MESSAGE_ID
which refers to a message id
listed in ClientProtocolDefinition
.
ClientProtocolDefinition.INTENT_CORE_START_SYNC_ACTION
.
ClientProtocolDefinition.INTENT_CORE_START_OBD_RT_TRANSMISSION_ACTION
.
Context.stopService(Intent)
.