Skip to main content

Android SDK: Getting started

This guide explains how to install the Cartrack BLE Lock SDK for Android and run the basic connection flow against a compatible BLE terminal.

Installation​

  • Add the latest CartrackBleLock_Android_SDK .aar file to your Android project (for example, under a libs/ directory).
  • In your project-level build.gradle, add flatDir { dirs 'libs' }.
allprojects {
  repositories {
    ...
    flatDir {
      dirs 'libs'
    }
  }
}
- In your app-level `build.gradle`, add the `.aar` file dependency.

```kotlin
 dependencies {
  implementation fileTree(include: ['*.aar'], dir: 'libs')
  implementation(name: 'blesdk-release_v3.0.3.aar', ext: 'aar')
}
  • For Android 12 (API 31) or higher, you must declare Bluetooth permissions.
  • Update your app-level AndroidManifest.xml.
<manifest>
    <uses-permission android:name="android.permission.BLUETOOTH"
                     android:maxSdkVersion="30" />
    <uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
        
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    ...
</manifest>

Core Classes​

BleService​

The main entry point for the Cartrack BLE SDK. Use this class to initialize the SDK and obtain terminal instances.

Key Methods:

BleTerminal​

Represents a terminal that communicates with CTG devices via Bluetooth Low Energy.

Key Methods:

BleListener​

Interface for handling BLE events and callbacks.

Key Callbacks:

How to Use​

All examples require import CartrackBleLockSDK somewhere in the source file.

Initialize CartrackBleLockSDK​

Initialize CartrackBleLockSDK with Context:

V2.4​

BleService.configure(Context, vendorId, apiKey, countryCode)

V3.0​

BleService.configure(Context)

Before starting to get the authentication key, you can create a BleTerminal variable outside the function:

var bleTerminal: BleTerminal

Get an instance of BleTerminal:

bleTerminal = BleService.getTerminal(terminalID)

Save Authentication Key​

Save the authentication key with BleTerminal.saveAuthKey():

bleTerminal.saveAuthKey()

Get Authentication Key​

Get the authentication key with BleTerminal.getAuthKey():

bleTerminal.getAuthKey()

This action requires network connection thus performing it earlier is encouraged before connecting to terminal.

Connect to Ble Terminal​

Connect to Ble Terminal with BleTerminal.scanAndConnectToPeripheral():

V2.4​

bleTerminal.scanAndConnectToPeripheral()

Under the hood, this scans peripherals around, connects and authenticates If successful, then you will get a response through BleListener.onTerminalConnected Else BleListener.onError if anything wrong happens:

  • ErrorHandler.BleConnectionError.KeyNotFound
  • ErrorHandler.BleConnectionError.KeyInvalid
  • ErrorHandler.BleConnectionError.BluetoothUnsupported
  • ErrorHandler.BleConnectionError.BluetoothUnauthorized > only if your app did not request the required permission
  • ErrorHandler.BleConnectionError.LocationUnauthorized > only if your app did not request the required permission
  • ErrorHandler.BleConnectionError.BluetoothPairingFailed > the system returned a connection error
  • ErrorHandler.BleConnectionError.TerminalNotFound > 30 seconds timeout

V3.0​

bleTerminal.scanAndConnectToPeripheral()

Under the hood, this scans peripherals around, connects and authenticates If successful, then you will get a response through BleListener.onTerminalConnected Else BleListener.onError if anything wrong happens:

  • BleError.KeyNotFound
  • BleError.KeyInvalid
  • BleError.BluetoothUnsupported
  • BleError.BluetoothUnauthorized > only if your app did not request the required permission
  • BleError.LocationUnauthorized > only if your app did not request the required permission
  • BleError.TerminalNotFound > the system returned a connection error
  • BleError.TerminalNotFound > 30 seconds timeout
  • BleError.GATTError > BluetoothGattCallback.onConnectionStateChange return other than GATT_SUCCESS

Connect to Ble Terminal with Timeout​

Set connection timeout by add duration (second) in Long. Default timeout is 10 seconds:

bleTerminal.scanAndConnectToPeripheral(20)

Disconnect from Ble Terminal​

Disconnect from Ble Terminal with BleTerminal.disconnect():

bleTerminal.disconnect()

This function will send a disconnect command to the terminal.

Fetch Authentication Key​

Fetch authentication key from API BleTerminal.fetchAuthKey() from shared preferences:

bleTerminal.fetchAuthKey()

Remove Authentication Key​

Remove the authentication key with BleTerminal.removeAuthKey() from shared preferences:

bleTerminal.removeAuthKey()

This function will not affect the authentication key on the server side.

Terminal Signal Update​

Called periodically to update the BLE signal strength to Ble Terminal:

bleListener.onSignalStrength(BleSignalStrength, rssiValue)

Check Authentication Key​

Called to checks if a terminal authentication key is available for secure communication:

bleListener.hasKey()

Send Ble Action to Terminal​

Send lock action to terminal BleAction.LOCK:

bleTerminal.sendAction(BleAction.LOCK)

Send unlock action to terminal with BleAction.UNLOCK:

bleTerminal.sendAction(BleAction.UNLOCK)

Send headlight action to terminal with BleAction.HEADLIGHT:

bleTerminal?.sendAction(BleAction.HEADLIGHT)

Send horn action to terminal with BleAction.HORN:

bleTerminal.sendAction(BleAction.HORN)

Get the current state of vehicle's lock status - possible value - locked/unlocked with BleAction.GET_LOCK_STATE:

bleTerminal.sendAction(BleAction.GET_LOCK_STATE)

Send unlock with no key fob action to terminal with BleAction.UNLOCK_NOKEYFOB:

bleTerminal.sendAction(BleAction.UNLOCK_NOKEYFOB)

Get the current state of vehicle's status with BleAction.VEHICLE_GET_CONFIG:

bleTerminal.sendAction(BleAction.VEHICLE_GET_CONFIG)

Consist of odometer, engineHours, engineRPM, fuelLevel, hazardsIsOn, indicators, brakesIsActive, handBrakeIsActive, lightsIsOn, driverDoorIsOpen, passengerDoorIsOpen, driverSeatbeltIsEngage, passengerSeatbeltIsEngage, hornIsActive field.

Get the current state of vehicle's ignition status - possible value - on/off with BleAction.VEHICLE_GET_STATUS:

bleTerminal.sendAction(BleAction.VEHICLE_GET_STATUS)

V2.4​

The response for all BleAction will be in BleListener.onTerminalCommandResult(bleAction: BleAction) and BleListener.onError(ErrorHandler.BleActionError/ErrorHandler.CtgError)

V3.0​

The response for all BleAction will be in BleListener.onTerminalCommandResult(bleAction: BleAction) and BleListener.onError(BleError/BleError.CtgError)

Possible error in Ble​

BleError​

Error Handler related to BLE Connection.

  • BluetoothUnauthorized - Bluetooth permission is not granted. Ask user to grant permission from phone settings
  • BluetoothDisabled - Bluetooth is disabled
  • BluetoothUnsupported - Device does not support Bluetooth Low Energy
  • SaveAuthKeyFailed - Failed to save authentication key in Shared Preference
  • KeyNotFound - Authentication key not found in Shared Preference
  • KeyInvalid - Authentication key in Shared Preference is invalid
  • TerminalNotFound - Unable to discover Ble Terminal, terminal might be out of range
  • NotConnected - Not connected to Ble Terminal. Call BleTerminal.connect() to connect first
  • LocationUnauthorized - Location permission is not granted
  • GattError - Gatt Error. Called when BluetoothGatt onConnectionStateChange return other than GATT_SUCCESS.
  • CtgError - Failed due to Terminal action, refer to CtgError

CtgError​

Error Handler related to CTG Terminal.

  • InvalidKey - Terminal response failed with invalid key
  • Timeout - Terminal response failed with time out
  • Fail - Terminal response failed, default return value
  • NoKey - Terminal response failed with no key
  • Unsuccessful - Terminal response failed with unsuccessful
  • ScriptFail - Terminal response failed with script fail
  • NoScript - Terminal response failed with no script
  • TooManyRequest - Terminal response failed with exceed maximum 3 concurrent commands. Any additional commands can be sent once one of the 3 previously sent commands is completed

GattError​

Gatt Error. Called when BluetoothGatt onConnectionStateChange return other than GATT_SUCCESS.

API Reference​

For complete API documentation with detailed method signatures, parameters, and examples, see:

Next Steps​

  1. Set up your development environment by following the installation steps above.
  2. Implement error handling using the error types documented above.
  3. Test with a physical device to ensure reliable BLE connectivity.