Android SBeacon Framework API Reference - scopetech/Mobile-Public GitHub Wiki

API Reference

Complete reference for all public methods in the SBeacon SDK.

BLEManager

The main entry point for all SDK operations. Access via singleton:

val bleManager = BLEManager.retrieveInstance(context)

Lifecycle Methods

Method Description
retrieveInstance(context: Context): BLEManager Get singleton instance
destroy() Release all resources
login() Initialize coroutine scopes after app login
logout() Cancel coroutines and cleanup on app logout

Service Control

Method Description
startForegroundBluetoothService() Start the BLE foreground service
stopForegroundBluetoothService() Stop the BLE foreground service 
// Start service (typically in Application.onCreate or after permissions)
bleManager.startForegroundBluetoothService()

// Stop service (typically on app logout)
bleManager.stopForegroundBluetoothService()

Scanning

Method Description
startBeaconsScan() Start scanning for SBeacon devices
stopBeaconsScan() Stop beacon scanning
startQuickScan() Quick 10-second scan 
// Scan for beacons
bleManager.startBeaconsScan()

// Stop when done
bleManager.stopBeaconsScan()

Connection & Pairing

Method Returns Description
pairBeacon(beacon, subscriptionId, serialNumber) Boolean Pair a beacon (suspend)
unpairBeacon(beacon) Boolean Unpair a beacon (suspend)
isBeaconConnected(beacon) Boolean Check if beacon is connected
disconnectFromAllBeacons() Unit Disconnect all beacons (suspend) 
// Pair a beacon
lifecycleScope.launch {
    val success = bleManager.pairBeacon(
        beacon = scopeBeacon,
        subscriptionId = 12345,
        subscriptionUnitSerialNumber = "UNIT001"
    )
    if (success) {
        Log.d("Pairing", "Beacon paired successfully")
    }
}

// Unpair
lifecycleScope.launch {
    bleManager.unpairBeacon(beacon)
}

// Check connection
if (bleManager.isBeaconConnected(beacon)) {
    // Beacon is connected
}

Beacon Data

Method Returns Description
allBeacons() List<ScopeBeacon> Get all beacons (suspend)
getBeacon(macAddress) ScopeBeacon? Get beacon by MAC (suspend) 
// Get all beacons
lifecycleScope.launch {
    val beacons = bleManager.allBeacons()
    beacons.forEach { beacon ->
        Log.d("Beacon", "${beacon.name}: ${beacon.macAddress}")
    }
}

// Get specific beacon
lifecycleScope.launch {
    val beacon = bleManager.getBeacon("AA:BB:CC:DD:EE:FF")
    beacon?.let {
        Log.d("Beacon", "Found: ${it.name}, Calibrated: ${it.isCalibrated}")
    }
}

Trip Information

Method Description
requestTripInformation(beaconMac) Request trip status and unsynced counts
requestTripRecords(beaconMac) Request stored trip records
requestTripIncidents(beaconMac) Request stored incidents
setAutoFetchIncidentsOnTripInfo(enabled) Auto-fetch incidents with trip info
clearIncidentFlags() Clear incident detection flags 
// Request trip information
bleManager.requestTripInformation(beaconMac)

// Handle response via EventsReceiver
private val eventsReceiver = object : IBFHelper.EventsReceiver() {
    override fun onUnsyncedDataCounts(
        beaconMac: String,
        tripCount: Int,
        incidentCount: Int,
        dbCount: Int
    ) {
        Log.d("Sync", "Unsynced trips: $tripCount")
    }

    override fun onTripRecordsReceived(beaconMac: String, trips: ArrayList<TripRecord>) {
        trips.forEach { trip ->
            Log.d("Trip", "Trip ${trip.recordIndex}")
        }
    }
}

Driving Behavior - Feature Control

Method Description
enableDrivingBehavior(beaconMac) Enable with all filters
disableDrivingBehavior(beaconMac) Disable feature
requestDrivingBehaviorConfig(beaconMac) Read current configuration
setDrivingBehaviorConfig(beaconMac, configValue) Set config byte (bits 0-2)
writeDrivingBehaviorConfig(beaconMac, config) Write complete config 
// Enable driving behavior detection
bleManager.enableDrivingBehavior(beaconMac)

// Read configuration
bleManager.requestDrivingBehaviorConfig(beaconMac)

// Write custom configuration
val config = DrivingBehaviorConfig(
    enabled = true,
    highPassFilterEnabled = true,
    lowPassFilterEnabled = true,
    corneringThreshold = 450,
    brakingThreshold = 400,
    accelerationThreshold = 250,
    durationThreshold = 500
)
bleManager.writeDrivingBehaviorConfig(beaconMac, config)

Driving Behavior - Threshold Configuration

Method Description
configureDrivingBehaviorThresholds(beaconMac, cornering, braking, acceleration, duration) Set all thresholds
setCorneringThreshold(beaconMac, threshold) Set cornering threshold (milli-Gs)
setBrakingThreshold(beaconMac, threshold) Set braking threshold (milli-Gs)
setAccelerationThreshold(beaconMac, threshold) Set acceleration threshold (milli-Gs)
setDurationThreshold(beaconMac, threshold) Set duration threshold (ms)
requestDrivingBehaviorThresholds(beaconMac) Read all threshold values 
// Configure all thresholds at once
bleManager.configureDrivingBehaviorThresholds(
    beaconMac = beaconMac,
    corneringThreshold = 450,      // 0.45g
    brakingThreshold = 400,        // 0.40g
    accelerationThreshold = 250,   // 0.25g
    durationThreshold = 500        // 500ms
)

// Or set individual thresholds
bleManager.setCorneringThreshold(beaconMac, 500)  // 0.50g

Threshold Ranges:

Parameter Min Max Default Unit
Cornering 50 5000 450 milli-Gs
Braking 50 5000 400 milli-Gs
Acceleration 50 5000 250 milli-Gs
Duration 1 10000 500 milliseconds

Driving Behavior - Event Management

Method Description
requestDrivingBehaviorEvents(beaconMac) Retrieve stored events
clearDrivingBehaviorEvent(beaconMac, index) Clear specific event (0-79)
clearAllDrivingBehaviorEvents(beaconMac) Clear all stored events 
// Request stored events
bleManager.requestDrivingBehaviorEvents(beaconMac)

// Handle response via EventsReceiver
private val eventsReceiver = object : IBFHelper.EventsReceiver() {
    override fun onDrivingBehaviorEventsReceived(
        beaconMac: String,
        events: ArrayList<DrivingBehaviorEvent>
    ) {
        events.forEach { dbEvent ->
            // Process event
            Log.d("DB", "${dbEvent.eventType}: ${dbEvent.averageMagnitude}g")
        }
        // Clear after sync
        bleManager.clearAllDrivingBehaviorEvents(beaconMac)
    }

    override fun onDrivingBehaviorEventsClearConfirmed(
        beaconMac: String,
        clearedIndex: Int
    ) {
        Log.d("DB", "Events cleared")
    }
}

Accelerometer Calibration

Method Description
requestAccelerometerCalibration(beaconMac) Start calibration process
requestAccelerometerConfig(beaconMac) Query calibration state 
// Check calibration status
bleManager.requestAccelerometerConfig(beaconMac)

// Start calibration (vehicle must be stationary)
bleManager.requestAccelerometerCalibration(beaconMac)

// Handle events via EventsReceiver
private val eventsReceiver = object : IBFHelper.EventsReceiver() {
    override fun onUpdateBeaconCalibrationStateReceived(
        mac: String,
        isCalibrated: Boolean
    ) {
        Log.d("Calibration", "Calibrated: $isCalibrated")
    }

    override fun onAutoCalibrationReceived(mac: String) {
        Log.d("Calibration", "Calibration complete!")
    }
}

Firmware Management

Method Description
downloadLatestFirmware(hardware, manufacturer) Download firmware (suspend)
runFirmwareUpdate() Start firmware update
onFirmwareUpdateCompleted() Called when update finishes
updateBeaconFirmware(macAddress) Update specific beacon (suspend) 
// Check and download firmware
lifecycleScope.launch {
    bleManager.downloadLatestFirmware(
        hardware = beacon.hardwareRevision,
        manufacturer = beacon.manufacturer
    )
}

// Run update
bleManager.runFirmwareUpdate()

Event Responses

All request methods trigger events via IBFHelper.EventsReceiver. Register your receiver before calling:

Request Method Response Event
requestTripInformation UnsyncedDataCounts, TripStatusChanges
requestTripRecords TripRecordsReceived
requestTripIncidents TripIncidentsReceived
requestDrivingBehaviorEvents DrivingBehaviorEventsReceived
requestDrivingBehaviorConfig DrivingBehaviorConfigReceived
requestAccelerometerConfig BeaconCalibrationStateReceived
requestAccelerometerCalibration AccelerometerCalibrationComplete
clearDrivingBehaviorEvent DrivingBehaviorEventsClearConfirmed
clearAllDrivingBehaviorEvents DrivingBehaviorEventsClearConfirmed

Method Signatures Summary

Suspend Functions

These methods must be called from a coroutine:

suspend fun pairBeacon(beacon: ScopeBeacon, subscriptionId: Int, subscriptionUnitSerialNumber: String): Boolean
suspend fun unpairBeacon(beacon: ScopeBeacon): Boolean
suspend fun allBeacons(): List<ScopeBeacon>
suspend fun getBeacon(macAddress: String): ScopeBeacon?
suspend fun disconnectFromAllBeacons()
suspend fun downloadLatestFirmware(hardware: String, manufacturer: String): Any
suspend fun updateBeaconFirmware(macAddress: String)

Regular Functions

These can be called from any context:

fun startBeaconsScan()
fun stopBeaconsScan()
fun startQuickScan()
fun isBeaconConnected(beacon: ScopeBeacon): Boolean

// Trip
fun requestTripInformation(beaconMac: String)
fun requestTripRecords(beaconMac: String)
fun requestTripIncidents(beaconMac: String)
fun setAutoFetchIncidentsOnTripInfo(enabled: Boolean)
fun clearIncidentFlags()

// Driving Behavior
fun enableDrivingBehavior(beaconMac: String)
fun disableDrivingBehavior(beaconMac: String)
fun requestDrivingBehaviorEvents(beaconMac: String)
fun requestDrivingBehaviorConfig(beaconMac: String)
fun setDrivingBehaviorConfig(beaconMac: String, configValue: Int)
fun writeDrivingBehaviorConfig(beaconMac: String, config: DrivingBehaviorConfig)
fun configureDrivingBehaviorThresholds(beaconMac: String, corneringThreshold: Int = 450, brakingThreshold: Int = 400, accelerationThreshold: Int = 250, durationThreshold: Int = 500)
fun setCorneringThreshold(beaconMac: String, threshold: Int)
fun setBrakingThreshold(beaconMac: String, threshold: Int)
fun setAccelerationThreshold(beaconMac: String, threshold: Int)
fun setDurationThreshold(beaconMac: String, threshold: Int)
fun requestDrivingBehaviorThresholds(beaconMac: String)
fun clearDrivingBehaviorEvent(beaconMac: String, index: Int)
fun clearAllDrivingBehaviorEvents(beaconMac: String)

// Calibration
fun requestAccelerometerCalibration(beaconMac: String)
fun requestAccelerometerConfig(beaconMac: String)

// Service
fun startForegroundBluetoothService()
fun stopForegroundBluetoothService()

// Lifecycle
fun destroy()
fun login()
fun logout()

// Firmware
fun runFirmwareUpdate()
fun onFirmwareUpdateCompleted()

Related Pages

⚠️ **GitHub.com Fallback** ⚠️