Skip to main content

BleTerminal

Class: BleTerminal(context: Context, terminalId: String)

Represents a terminal that interact with the bluetooth BleCentral and peripheral BlePeripheral to send commands to the CTG device.

Constructor​

BleTerminal(context: Context, terminalId: String)​

Creates a new BleTerminal instance.

Parameters:

  • context - Android application context
  • terminalId - Unique identifier for the terminal: the Bluetooth name it advertises

Obtain instances through BleService.getTerminal() rather than constructing them directly.

Properties​

bleListener: BleListener? = null​

The listener that receives every callback of this terminal. A terminal has a single listener: assigning it replaces the previous one. Assign it before calling any method, since some callbacks are called before the method returns.

terminalId: String​

The name passed to BleService.getTerminal(). It is compared exactly (case-sensitive, not trimmed) with the Bluetooth name the terminal advertises.

Methods​

Authentication Methods​

saveAuthKey​

fun saveAuthKey(key: String)

Encrypts the authentication key and saves it to Shared Preferences. The SDK stores one key per app, not one per terminal: saving a key replaces the previous one, whichever BleTerminal it was saved on.

The key's format is not checked here: a key that is not 64 hexadecimal characters is saved, and scanAndConnectToPeripheral() then reports BleError.KeyInvalid.

Parameters:

  • key - The vehicle's authentication key from the Fleet API, 64 hexadecimal characters

Callbacks (called before the method returns):

  • On success: BleListener.onSaveAuthKeySuccess(terminal, authKey)
  • On error: BleListener.onError(BleError.SaveAuthKeyFailed) when the key is empty or could not be encrypted

getAuthKey​

fun getAuthKey(): String?

Retrieves the encrypted authentication key from Shared Preferences, decrypts it, and returns it.

Returns: The decrypted authentication key, or null if not found

removeAuthKey​

fun removeAuthKey()

Removes the authentication key from Shared Preferences. It does not disconnect, and it does not change the key on the terminal.

Callbacks (called before the method returns):

  • BleListener.onRemoveAuthKeySuccess()

hasKey​

fun hasKey(): Boolean

Checks if a terminal authentication key is available for secure communication.

Returns: true if key exists, false otherwise

Connection Methods​

scanAndConnectToPeripheral​

fun scanAndConnectToPeripheral(timeout: Long = 10000)

Connects to a BleTerminal device.

This function initiates the connection process by first validating the stored authentication key and then scanning for a terminal advertising terminalId. Upon finding it, it establishes a connection and performs authentication.

Error Handling: The function reports a BleError through BleListener.onError in the following scenarios:

  • BleError.KeyNotFound: No authentication key is stored.

  • BleError.KeyInvalid: The stored key is not 64 hexadecimal characters.

  • BleError.BluetoothUnsupported: The device does not support Bluetooth Low Energy.

  • BleError.BluetoothUnauthorized: Bluetooth permissions are not granted.

  • BleError.LocationUnauthorized: Location permission is not granted, or location services are off (required for BLE scanning).

  • BleError.BluetoothDisabled: Bluetooth was turned off while the SDK was in use. The SDK reports onTerminalDisconnected as soon as Bluetooth starts turning off. If Bluetooth is already off when this function is called, the scan cannot start and the attempt ends in TerminalNotFound once the timeout has passed: check that Bluetooth is on before calling it.

  • BleError.TerminalNotFound: No terminal with that name was found before the timeout. From 3.0.4, also when the terminal was found but did not accept the Bluetooth connection within the timeout.

  • BleError.GattError: The Android Bluetooth stack reported a GATT error. GATT_ERROR and GATT_FAILURE are retried three times, with onReconnect called each time, before this is reported.

  • BleError.CtgError: The terminal rejected the authentication, typically CtgError.InvalidKey when the stored key does not match the vehicle, or CtgError.Timeout when the terminal did not answer the authentication (from 3.0.4, also the handshake) in time. The SDK does not close the Bluetooth link after a CtgError: call disconnect() before trying again.

Successful Connection: Upon successful connection and authentication, the BleListener.onTerminalConnected callback is invoked. Right after it, the SDK reads the lock state itself and reports it through BleListener.onTerminalCommandResult(BleAction.GET_LOCK_STATE).

A call made while the SDK is already scanning is ignored, without any callback.

Parameters:

  • timeout - Timeout in milliseconds (default 10000), applied to each step in turn: the scan, then (from 3.0.4) the Bluetooth connection and handshake, then each authentication message. Once connected, the same value is how long the SDK waits for the terminal to answer each command before reporting CtgError.Timeout.

Callbacks:

  • On success: BleListener.onTerminalConnected()
  • On error: BleListener.onError() with one of the BleError types above

disconnect()​

fun disconnect()

Disconnects the peripheral from the BleTerminal.

This function stops any scan in progress, closes the Bluetooth connection and triggers a callback to BleListener.onTerminalDisconnected. The callback is delivered even when nothing was connected. From 3.0.4 it is delivered once per call; with 3.0.3 it was delivered twice, once immediately and once when the Bluetooth stack confirmed the disconnection.

Status Methods​

getBleConnectionState()​

fun getBleConnectionState(): BleConnectionState

Retrieves the Bluetooth Low Energy (BLE) connection state of the device.

This function indicates whether the Android device is currently connected to the terminal.

Possible values are:

  • BleConnectionState.CONNECTED: The terminal has accepted the key and actions can be sent.
  • BleConnectionState.DISCONNECTED: No connection. This is also the value during a connection attempt (scan, Bluetooth connection and authentication): CONNECTING is not reported for a connection attempt, so track the attempt in your app from scanAndConnectToPeripheral() until onTerminalConnected or onError.

This function should be called before initiating a BLE connection or disconnection to ensure the desired operation is performed in the correct state.

Returns: The current BLE connection state as a BleConnectionState enum.

getLockState()​

fun getLockState(): LockState

Gets the current lock state of the vehicle.

Returns: Current LockState

The lock state of the vehicle as last reported by the terminal. It is refreshed after connecting and after LOCK, UNLOCK and GET_LOCK_STATE, once BleListener.onTerminalCommandResult has been called. Possible values are:

  • LOCKED: The vehicle is locked.
  • UNLOCKED: The vehicle is unlocked.
  • UNKNOWN: The lock state has not been received yet, or the terminal reported it as unknown. It is reset to UNKNOWN when the connection ends.

Action Methods​

sendAction(action: BleAction)​

fun sendAction(action: BleAction)

Executes a Bluetooth Low Energy (BLE) action on the connected peripheral.

Parameters:

  • action - The BLE action to execute

Available Actions:

  • BleAction.LOCK - Lock the vehicle
  • BleAction.UNLOCK - Unlock the vehicle
  • BleAction.UNLOCK_NOKEYFOB - Unlock without activating the key fob: the driver cannot start the engine
  • BleAction.HEADLIGHT - Flash headlights
  • BleAction.HORN - Sound horn
  • BleAction.GET_LOCK_STATE - Refresh the lock state
  • BleAction.VEHICLE_GET_CONFIG - Get the vehicle statistics
  • BleAction.VEHICLE_GET_STATUS - Get the ignition state

Callbacks:

  • VEHICLE_GET_CONFIG: BleListener.onTerminalDidGetVehicleStats()
  • VEHICLE_GET_STATUS: BleListener.onTerminalDidGetVehicleStatus()
  • All other actions: BleListener.onTerminalCommandResult(). For LOCK and UNLOCK it is called once the SDK has read the new lock state.
  • Error: BleListener.onError() with BleError.NotConnected (called before the method returns) when no terminal is connected, or BleError.CtgError when the terminal refuses the action or the SDK gives up on it: CtgError.Timeout when the terminal does not answer, CtgError.TooManyRequest when 3 commands are already waiting for an answer (the SDK does not send this one). A CtgError does not close the connection.

See Also​