iOS HMTelematics
HMTelematics is used to send and receive commands to and from a vehicle, or an emulator. Instead of Bluetooth, the connection is made through the Internet connection.
Type Methods
Download access certificate(s) for an access token
Declaration
class func downloadAccessCertificate(accessToken: String, completionWithSerial completion: @escaping HMTelematicsResultBlock<[UInt8]>) throws
Parameters
| accessToken | (String) token received through vehicle owner's authorisation |
| completion | (HMTelematicsResultBlock<[UInt8]>) typealias for Result with vehicle serial as success |
Discussion
If a prerequisite is not fulfilled, an Error is thrown.
Successful completion returns the vehicle's serial number and automatically stores the access certificate(s) on the device.
Read More
Example
import HMKit
/*
HMLocalDevice is initialised beforehand
*/
let accessToken: String = "imzDKyM-oklBaSIIv...EiXqBy3eBum9QLcMTrqzYg"
do {
try HMTelematics.downloadAccessCertificate(accessToken: accessToken) {
switch $0 {
case .failure(let error):
print("Failed to download access certificate(s), because \(error)")
case .success(let vehicleSerial):
let serialHex = vehicleSerial.map { String(format: "%02X", $0) }.joined()
print("Received access certificate(s) for vehicle: \(serialHex)")
}
}
}
catch {
print("Failed to start downloading access certificate(s), error: \(error)")
}
Check if there is a certificate stored for a given vehicle
Declaration
class func isAuthorisedToVehicle<C>(serial: C) throws -> Bool where C : Collection, C.Element == UInt8
Parameters
| serial | (UInt8 Collection) vehicle serial number |
Returns
Bool
Discussion
If a prerequisite is not fulfilled, an HMTelematicsError is thrown.
Is authorised, if there exists an access certificate with a matching gaining serial and the providing serial matches the device's serial.
Read More
Example
import HMKit
/*
HMLocalDevice is initialised beforehand
*/
let serial: [UInt8] = [0x11, 0x22...0x88, 0x99]
do {
let isAuthorised = try HMTelematics.isAuthorisedToVehicle(serial: serial)
}
catch {
print("Failed to check authorised status, error: \(error)")
}
Send a command to a vehicle
Declaration
class func sendCommand<C>(_ command: C, contentType: HMContainerContentType = .autoAPI, requestID: [UInt8] = [], serial: [UInt8], completionWithResponse completion: @escaping HMTelematicsResultBlock<HMTelematicsRequestSuccess>) throws where C : Collection, C.Element == UInt8
Parameters
| command | (UInt8 Collection) command to send to the vehicle |
| contentType | (HMContainerContentType) type of data sent as content - defaults to .autoAPI |
| requestID | ([UInt8]) ID to keep track of a specific command (response will contain the same ID) |
| serial | ([UInt8]) serial number |
| completion | (HMTelematicsResultBlock) typealias for Result with HMTelematicsRequestSuccess for success |
Discussion
If a prerequisite is not fulfilled, an Error is thrown.
Successful completion returns the vehicle's response for the command – this could take up to 30 seconds. Response's associated value could also be nil, if the vehicle does not return a response for a given command.
Read More
Example
import HMKit
/*
HMLocalDevice is initialised beforehand
*/
let command: [UInt8] = [0x00, 0x11, 0x00]
let serial: [UInt8] = [0x11, 0x22...0x88, 0x99]
do {
try HMTelematics.sendCommand(command, serial: serial) {
switch $0 {
case .failure(let error):
print("Failed to send telematics command, error: \(error)")
case .success(let response, _, _):
let hex = response.map { String(format: "%02X", $0) }.joined()
print("Telematics command sent and a response received: \(hex)")
}
}
catch {
print("Failed to start sending telematics command, error: \(error)")
}
Properties
Types of logs printed to the console
Declaration
static var loggingOptions: HMLoggingOptions = [.general] { get set }
Discussion
This is shared with HMLocalDevice
Read More
Requests base url
Declaration
static var urlBasePath: String
Discussion
Stores the base url for sending telematics requests.
Types
HMTelematicsResult
Declaration
typealias HMTelematicsResult<Success> = Result<Success, HMTelematicsError>
Discussion
HMTelematicsResult is a typealias for Result with HMTelematicsError for failure.
Read More
HMTelematicsResultBlock
Declaration
typealias HMTelematicsResultBlock<Success> = (HMTelematicsResult<Success>) -> Void
Discussion
HMTelematicsRequestResult is a typealias for a block that returns an HMTelematicsResult.
Read More
HMTelematicsRequestSuccess
Declaration
typealias HMTelematicsRequestSuccess = (response: [UInt8], contentType: HMContainerContentType, requestID: [UInt8])
Parameters
| response | ([UInt8]) representing the response |
| contentType | (HMContainerContentType) type of data received as content |
| requestID | ([UInt8]) ID of the sent command |
Discussion
HMTelematicsRequestSuccess is a typealias for a tuple.