Skip to main content

Release Notes

info

SDK packages are provided on request. See Request SDK access.

V3.0.4​

warning

Like 3.0.2, 3.0.4 needs iOS 15.0 or later: check this when upgrading from 3.0.1.

  • No API change: the public signatures and error codes are as in 3.0.2.
  • A connection attempt that times out while the app's Bluetooth permission prompt is still unanswered reports bluetoohUnauthorized (1), not terminalNotFound (7) as if the vehicle were out of range.
  • The description of bluetoohUnauthorized (1) reads Phone: Bluetooth permission is not granted, please allow it when asked or in Settings, since the prompt may still be on screen. The code is unchanged.
  • An app that declares bluetooth-central in UIBackgroundModes can connect from the background: there the SDK looks for the terminal's MiKey Bluetooth service, the only kind of search iOS answers in the background. On screen it still looks for every device, so nothing changes for an app without the background mode.
  • Connecting takes fewer wakeups and fewer Bluetooth exchanges, and is faster on some phones: on an iPhone 11, 2.0 s instead of 2.5 s from connect() to bleTerminalDidConnect.

V3.0.2​

warning

3.0.2 needs iOS 15.0 or later.

  • Every action and getVehicleStats() now gets exactly one answer: CtgError.timeout (22) when the terminal says nothing within the timeout passed to connect(timeout:). Before, a command the terminal never answered never called back.
  • bleTerminalDidConnect always comes: also when the lock state read after connecting gets no answer, with lockState .unknown. A terminal that kept answering that its lock state was unknown used to be asked again for good.
  • connect() while connected reports the connection again. disconnect() during an attempt cancels it and reports bleTerminalDisconnected once; while connected, it drops the link even when the terminal refuses or ignores the disconnect command.
  • bleTerminalDisconnected comes only for a connection that was reported; a failed attempt reports through bleTerminalDidConnect alone.
  • A failed connection and a wrong key free the terminal at once, so the next attempt can start straight away.
  • A terminal out of range reports terminalNotFound (7), also when it was seen earlier.
  • The key stays readable while the phone is locked, once it was unlocked after starting, and is never restored onto another phone from a backup; a key saved by 3.0.1 is moved the first time it is read. A failed save keeps the previous key, and saveAuthKey rejects anything but hexadecimal digits with saveAuthKeyFailed (4).
  • SDK calls made off the main thread are moved to it.
  • The framework is signed and carries its debug symbols (dSYM), so crash reports that go through the SDK can be read.

V3.0.1​

  • Fixed VehicleStats.lightsIsOn displaying an incorrect value
  • Fixed improper state handling when an invalid key is detected, ensuring the internal timer stops immediately after returning the invalidKey error (Error Code 21) to prevent subsequent timeout errors.
  • Added VehicleStats.reverseGearIsActive to get the status of reverse gear
  • Support terminal IDs up to 14 characters

V3.0​

Notice: This version has breaking changes.

Before​

From the first SDK version until version 2.4.1, the Bluetooth keys were managed by the SDK, communicating with the Cartrack servers:

  • Obtaining the key
  • Key randomisation

After​

This new SDK is simpler, and the keys can be managed at Cartrack Fleet API level. Using the API, you can fetch the Bluetooth keys ahead of time and reuse them for multiple bookings. Have a look at the following endpoints:

  • GET /mikey/:registration to get the key for a given vehicle registration
  • GET /mikey, to get the keys for all your vehicles
  • PUT /mikey/:registration, to randomise the key for a given vehicle registration

For improved security, you can randomise keys at your convenience. We recommend changing keys only when there is enough time between two users so the vehicle can receive the new key and the user can load it on the phone.

Release details​
  • Added BleTerminal.authKey to indicate the terminal authentication key
  • Added BleTerminal.saveAuthKey(authKey:) to save authentication key to keychain
  • Added BleError.actionCode to indicate the action code. The action code only use for CtgError, for other error will return -1
  • Removed BleService.configure(vendorID:apiKey:countryCode:apiUrl:)
  • Removed BleTerminal.getAuthKey()
  • Removed BleTerminal.randomAuthKey()
  • Removed BleTerminalDelegate.bleTerminalDidGetKey(terminal:error:)
  • Removed BleTerminalDelegate.bleTerminalDidRandomAuthKey(terminal:error:)
  • Removed unused error and combine BleConnectionError, BleActionError, and BleKeyError to BleError
  • Updated error code in BleError and CtgError

V2.4.1​

  • Support terminal IDs up to 12 characters
  • Fixed a bug affecting rare scenarios where the advertised BLE name is changed
  • Fixed VehicleStats.lightsIsOn display an incorrect value
  • Added VehicleStats.reverseGearIsActive to get the status of reverse gear

V2.4​

  • Added upper case method in terminalID, convert the string to upper case by default
  • Added upper case method in countryCode, convert the string to upper case by default
  • Added BleKeyError.saveKeyFailed to return the error for the key when failed to save in keychain
  • Added BleKeyError.responseError(_:_:) to return the error from API
  • Added BleKeyError.serverError(_:_:) to return the error from server
  • Added BleConnectionError.bleKeyError(_:_:) to return the error from Ble key
  • Added CtgError to indicate terminal action failed error types
  • Added BleKeyError and CtgError error response in BleConnectionError
  • Added CtgError error response in BleActionError
  • Added VehicleStats class for vehicle stats
  • Added IndicatorState for indicators in VehicleStats
  • Added a function BleTerminal.getVehicleStats() to get vehicle stats from Ble Terminal
  • Added BleAction.ignitionState to get the current state of vehicle's ignition
  • Added BleTerminal.ignitionState to indicate current vehicle's ignition state
  • Receive BleTerminal.getVehicleStats() response in BleTerminalDelegate.bleTerminalDidGetVehicleStats(terminal:vehicleStats:error:)
  • Updated error code and localized description for BleConnectionError, BleActionError, BleKeyError and CtgError

V2.3​

  • Added a function BleAction.unlockNoKeyFob to send an unlock command Unlock_0 that doesn't activate the key fob. The driver won't be able to start the engine.
  • Receive BleAction.unlockNoKeyFob response in BleTerminalDelegate.bleTerminalDidAction(terminal:action:error:)

V2.1.1​

  • Bugfix for BleService.configure(vendorID:apiKey:countryCode:apiUrl:)
  • Added BleTerminal.randomAuthKey() to random the terminal authentication key
  • Added BleTerminalDelegate.bleTerminalDidRandomAuthKey(terminal:error:) protocol to receive a response or error from BleTerminal.randomAuthKey()
  • Updated BleTerminal.removeAuthKey() to remove the authentication key from keychain without random authentication key
  • The keychain will only save one authentication key with a static name. If wish to use another terminal id or new authentication key, must remove the current authentication key before fetching the new authentication key.

V2.1​

  • Added a new parameter apiUrl in BleService.configure(vendorID:apiKey:countryCode:apiUrl:)
  • Use BleService.configure(vendorID:apiKey:countryCode:) for default API URL
  • Use BleService.configure(vendorID:apiKey:countryCode:apiUrl:) for custom API URL

V2.0​

  • Add a new parameter countryCode in BleService.configure(vendorID:apiKey:countryCode:) Please refer to https://iban.com/country-codes for the country code alpha-2 format.

V1.2​

  • Fixed intermittent CRC fail during connection

V1.1​

  • Added BleTerminal.lockState to indicate vehicle's lock state
  • Added BleAction.lockState action to get the latest vehicle's lock state

V1.0​

  • Initial release