Skip to main content

Release Notes

info

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

V3.0.5​

No API change: all public signatures and error codes are as in 3.0.4. A key saved with an earlier version of the SDK stays readable, so your app does not have to save it again.

Upgrading from 3.0.3 or earlier? If your app uses the network, declare INTERNET in your own manifest

Since 3.0.4 the SDK no longer declares the INTERNET and ACCESS_NETWORK_STATE permissions, which it never used. An app that uses the network without declaring them itself, and does not get them from another library, will have its network calls fail at runtime after the upgrade. Nothing warns at build time. See V3.0.4 for the details, and add what is missing to your app's AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />
<!-- Only if your app checks the network state -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Improvements​

  • The saved key is encrypted with a new random IV every time it is saved, under a Keystore entry named for the SDK. Up to 3.0.4 every save reused the same IV, and the Keystore entry was named KEY_ALIAS, a name your app may also use. The first time 3.0.5 reads a key saved by an earlier version, it re-encrypts it in the new format. The old KEY_ALIAS entry is left untouched, in case your app uses it
Going back to an earlier SDK version

Earlier versions cannot read a key saved or re-encrypted by 3.0.5. If you ship an app update that goes back from 3.0.5 to an earlier SDK, hasKey() returns false and your app has to call saveAuthKey() again, as after a new install.

V3.0.4​

No API change: all public signatures and error codes are as in 3.0.3.

If your app uses the network, declare INTERNET in your own manifest before upgrading

Up to 3.0.3 the SDK declared the INTERNET and ACCESS_NETWORK_STATE permissions, and Android copies a library's permissions into every app that includes it. The SDK never used them: it talks only to the terminal, over Bluetooth, and they were left over from network libraries it declared but never called. 3.0.4 removes them, so the SDK no longer gives your app permissions it does not need.

An app that uses the network without declaring these permissions itself, and does not get them from another library, will have its network calls fail at runtime after the upgrade. Nothing warns at build time. Check your app's own AndroidManifest.xml and add what is missing:

<uses-permission android:name="android.permission.INTERNET" />
<!-- Only if your app checks the network state -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Improvements​

  • The connection attempt is time-boxed end to end. If the terminal does not accept the Bluetooth connection, or does not answer the handshake, within the timeout given to scanAndConnectToPeripheral, the SDK reports BleError.TerminalNotFound or CtgError.Timeout instead of waiting indefinitely
  • BleError.GattError.gattError and BleError.CtgError.ctgError expose the underlying error, so the exact cause can be matched without relying on errorCode
  • The unused Retrofit and Gson dependencies, and the INTERNET and ACCESS_NETWORK_STATE permissions, are no longer pulled into your app by the SDK: see the warning above. If your app relied on getting Retrofit or Gson through the SDK, declare them in your own build.gradle
  • SecurityKey, EncryptionKeyGenerator and Context.checkBluetoothPermission are deprecated: they are internal helpers and will become internal in a future release
  • Connecting is about twice as fast (3.5 to 5 s instead of 7 to 8 s from scanAndConnectToPeripheral to onTerminalConnected on the bench): the SDK opens a direct Bluetooth LE connection instead of Android's slower background autoConnect mode, and spaces write chunks by 100 ms instead of 500 ms now that each write waits for its acknowledgement
  • A scan started with the screen off can find the terminal when your app holds ACCESS_BACKGROUND_LOCATION. From Android 8.1, a scan without a filter gets no results while the screen is off, so for such an app a scan started with the screen off now filters on the MiKey Bluetooth service, which Android keeps running, and finds terminals that advertise that service. Without that permission, and for every scan started with the screen on, the scan is unfiltered as before. Every scan now runs in Android's low-latency mode instead of the default low-power mode; it lasts at most the timeout given to scanAndConnectToPeripheral and stops as soon as the terminal is found

Bug Fixes​

  • Packets of some sizes could crash the app while being split into BLE writes
  • A terminal whose Bluetooth name could not be read back stalled the connection without any callback
  • The Bluetooth state receiver was registered once per connection attempt, so BleError.BluetoothDisabled could be delivered several times
  • BleError.BluetoothUnauthorized is reported up front when only one of BLUETOOTH_SCAN and BLUETOOTH_CONNECT is granted
  • Commands sent while another command was in flight were lost: their Bluetooth writes collided with the first command's and the stack dropped them without any callback. Writes are now queued, so up to 3 concurrent commands are all delivered
  • When the same command was sent twice, the first answer cancelled both timeouts, so a lost second command never reported CtgError.Timeout
  • onTerminalDisconnected was delivered twice for one disconnect() call, once immediately and once when the Bluetooth stack confirmed the disconnection
  • A stored key that could not be read (a corrupt value, or a Keystore error on some phones) could crash the app in hasKey() or scanAndConnectToPeripheral(). It now reads as no key: hasKey() returns false and connecting reports BleError.KeyNotFound
  • When the key could not be encrypted, saveAuthKey() reported onSaveAuthKeySuccess and deleted the previously saved key. It now reports BleError.SaveAuthKeyFailed, as documented, and keeps the previous key
  • The random challenge sent during authentication comes from a cryptographic random generator

V3.0.3​

New Features​

  • Implemented reverse gear in Vehicle Status
  • Created an enum class GattError to represent GATT errors with descriptive names and descriptions

Bug Fixes​

  • Corrected the VehicleStatus.lightIsOn to display the accurate value
  • Resolved slow connection issues
  • Addressed ANR (Application Not Responding) problems related to connection
  • Prevented heartbeat calls when an action has not received a response to avoid timeout

Improvements​

  • Added new log message for onConnectionStateChange to provide information about the GATT status and connection state: GattStatus = [gatt description], Connection State = [Connect/Disconnect]

V3.0.2​

New Features​

  • Reintroduced BleTerminal.hasKey()
  • Added BleError.LocationUnauthorised to return an error when the user disallows location permission
  • Added BleError.CtgError.TooManyRequest to return an error when exceeding more than 3 concurrent commands
  • Added BleError.GATTError to return Bluetooth Gatt errors

Bug Fixes​

  • Fixed SDK failure to compile
  • Fixed BleListener.onSignalStrength to read the RSSI for a connected remote device

V3.0.1​

  • Added BleError.LocationUnauthorised to return an error when the user disallows location permission

V3.0​

Notice: This version has breaking changes

Before​

The management of Bluetooth keys was handled by the SDK, which communicated with the Cartrack servers from the initial version to version 2.4:

  • Obtaining the key
  • Key randomisation

This increased complexity for mobile integrations, and keys could only be fetched (or randomized) while the smartphone had the app open. In many cases, users may be in environments with limited cellular connectivity (for example, parking garages), which made the process cumbersome.

After​

This new SDK is more straightforward, and we have exported the key management into the Cartrack Fleet API. Using the API, you can now 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

  • API documentation: https://developer.cartrack.com/fleet-api

To enhance security, it is advisable to randomize keys periodically. We suggest rotating keys when there is enough time between two users, allowing the vehicle to receive the new key and the user to load it on their phone.

You can then provide the key to the user’s smartphone using the SDK key functions.

  • BleListener.onSaveAuthKeySuccess called when save authentication key successfully
  • BleTerminal.saveAuthKey, BleTerminal.getAuthKey and BleTerminal.removeAuthKey to handle authentication key
Release details​
  • Remove VendorId,API keyandcountry code
  • Remove Random Key,Fetch Key,Save KeyandRemove Key from API
  • Combine BleConnectionError,BleActionErrorandBleKeyError to BleError
  • Remove unused Error
  • Added connection timeout parameter for scanAndConnectToPeripheral

V2.4.2​

  • Added ErrorHandler.BleConnectionError.LocationUnauthorised to return an error when the user disallows location permission

V2.4.1​

  • Reintroducing BleTerminal.hasKey()

2.4​

  • Added ErrorHandler to handle all possible errors
  • Added ErrorHandler.BleConnectionError to indicate bluetooth connection and authentication failures and provide an error type
  • Added ErrorHandler.BleActionError to indicate when a BLE action failed and provide an error type
  • Added ErrorHandler.CtgError to indicate when a terminal action failed and provide an error type
  • Added BleListener.onError to return all error from BleListener
  • Added BleAction.VEHICLE_GET_STATUS to get the current state of the vehicle’s ignition
  • Removed BleListener.onTerminalConnectionFailed and merge it to BleListener.onError
  • Changed BleListerner.onGetAuthKey to BleListener.onGetAuthKeySuccess to return success API, failure will return in BleListener.onError
  • Changed BleListerner.onRemoveAuthKey to BleListener.onRemoveAuthKeySuccess to return success API, failure will return in BleListener.onError
  • Changed BleListerner.onRandomAuthKey to BleListener.onRandomAuthKeySuccess to return success API, failure will return in BleListener.onError
  • Moved errors so that they are returned in BleListener.onError
  • Added BleListener.onTerminalDidGetVehicleStatus for showing IgnitionState
  • Updated error code and localized description for Error Handler

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.2.1​

  • Add BleTerminal.removeAuthKey() to remove authentication key from local memory
  • Add BleListener.onRemoveAuthKey(error: String?, success: Boolean?) to receive a call back when removeAuthKey() called
  • Add BleTerminal.randomAuthKey() to random the terminal authentication key , call back will be received in BleListener.onGetAuthKey (error: String?, success: Boolean?)
  • We now have two separate functions removeAuthKey and randomAuthKey, please consider it when upgrading to this new version.
  • The Shared Preference will only save one authentication key with a static name. If you want to use another it for a different vehicle or a new authentication key, you will need to remove the current authentication key before fetching the new one.
  • Bugfix for the default url

V2.2​

  • Add a new parameter apiUrl in BleService.configure().
  • Add BleService.setApiUrl(apiUrl: String) for changing the apiUrl at runtime.
  • Add BleService.setDefaultApiUrl() for changing the apiUrl to the default apiUrl at runtime.

V2.1​

  • Fix unicode characters which fail to convert to proper bytes.

V2.0​

  • Add a new parameter countryCode in BleService.configure().
    • Please refer to iban.com/country-codes for the country code alpha-2 format.
  • Add BleService.clear() for clearing BleService instance.

V1.5​

  • Fix a situation where the terminal name is null on specific smartphones, causing a crash

V1.4​

  • Fix an issue where the SDK fails to fetch the key, when the smartphone does not have stable connection

V1.3​

  • Fix a crash when phone goes outside of the terminal BLE antenna's range

V1.2​

  • Add BleTerminal.getBleConnectionState() to indicate the state of the BLE
  • Fix an intermittent CRC fail at the connection between smartphone and terminal

V1.1​

  • Add BleTerminal.getLockState() to indicate vehicle’s lock state
  • Add BleAction.GET_LOCK_STATE action to get the latest vehicle’s lock state

V1.0​

  • Initial release