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

API Reference

iOS SBeacon Framework v1.0.8

Complete API reference for the iOS SBeacon Framework.

Singleton Access

All managers use singleton pattern:

let sbeaconManager = SBeaconManager.shared
let beaconManager = SCPBeaconManager.shared
let coreDataManager = BeaconCoreDataManager.shared

Scanning Methods

startScan()

Start scanning for unpaired SBeacon devices.

func startScan()

Returns: Void

Side Effects:

  • Increments scan request counter
  • Subscribes to BLE scanner if first request
  • Starts device expiration timer (20 seconds)

Example:

SBeaconManager.shared.startScan()

stopScan()

Stop scanning for unpaired SBeacon devices.

func stopScan()

Returns: Void

Side Effects:

  • Decrements scan request counter
  • Unsubscribes from BLE scanner if counter reaches 0
  • Stops device expiration timer

Example:

SBeaconManager.shared.stopScan()

scanForBeacons()

Perform a timed scan (10 seconds).

func scanForBeacons()

Returns: Void

Behavior: Automatically starts scan and stops after 10 seconds

Example:

SBeaconManager.shared.scanForBeacons()  // Auto-stops after 10s

resetScan()

Reset scan counter to zero and stop scanning.

func resetScan()

Returns: Void

Example:

SBeaconManager.shared.resetScan()

Pairing Methods

beaconPaired(beacon:)

Initiate pairing workflow for unpaired beacon.

func beaconPaired(beacon: UnpairedSBeacon)

Parameters:

  • beacon: Unpaired beacon to pair

Side Effects:

  • Removes beacon from unpairedSBeacons array
  • Initiates BLE connection
  • Starts MAC address retrieval process

Callback: macAddressReceived when MAC is retrieved

Example:

SBeaconManager.shared.beaconPaired(beacon: unpairedBeacon)

beaconUnpaired(beacon:)

Disconnect and remove paired beacon.

func beaconUnpaired(beacon: SCPBeacon)

Parameters:

  • beacon: Paired beacon to unpair

Side Effects:

  • Cancels BLE connection
  • Removes from discovered peripherals
  • Posts beaconUnpairedNotification

Example:

SBeaconManager.shared.beaconUnpaired(beacon: pairedBeacon)

Connection Methods

getConnectedBeacons()

Get all currently connected beacons.

func getConnectedBeacons() -> [SCPBeacon]

Returns: Array of connected SCPBeacon objects

Example:

let connectedBeacons = SBeaconManager.shared.getConnectedBeacons()
print("Connected: \(connectedBeacons.count) beacons")

beaconIsConnected(beacon:)

Check if specific beacon is connected.

func beaconIsConnected(beacon: SCPBeacon) -> Bool

Parameters:

  • beacon: Beacon to check

Returns: true if connected, false otherwise

Example:

if SBeaconManager.shared.beaconIsConnected(beacon: myBeacon) {
    print("Beacon is connected")
}

Trip Management Methods

requestTripInformation(beacon:)

Request trip data counts from beacon.

func requestTripInformation(beacon: SCPBeacon)

Parameters:

  • beacon: Connected beacon

Callback: tripInformationReceived(Int, Int, Int)

  • Parameter 1: Trip count
  • Parameter 2: Incident count
  • Parameter 3: Driving behavior event count

Example:

SBeaconManager.shared.requestTripInformation(beacon: myBeacon)

requestTripRecords(beacon:)

Request all trip records from beacon.

func requestTripRecords(beacon: SCPBeacon)

Parameters:

  • beacon: Connected beacon

Callback: tripRecordsReceived([TripRecord])

Example:

SBeaconManager.shared.requestTripRecords(beacon: myBeacon)

Driving Behavior Methods

requestDrivingBehaviorEvents(beacon:)

Request all driving behavior events from beacon.

func requestDrivingBehaviorEvents(beacon: SCPBeacon)

Parameters:

  • beacon: Connected beacon

Callback: drivingBehaviorEventsReceived([DrivingBehaviorEvent])

Max Events: 80 (circular buffer, index 0-79)

Example:

SBeaconManager.shared.requestDrivingBehaviorEvents(beacon: myBeacon)

clearDrivingBehaviorEvent(index:beacon:)

Clear specific driving behavior event.

func clearDrivingBehaviorEvent(index: UInt8, beacon: SCPBeacon)

Parameters:

  • index: Event index (0-79)
  • beacon: Connected beacon

Validation: Index must be 0-79

Example:

SBeaconManager.shared.clearDrivingBehaviorEvent(index: 5, beacon: myBeacon)

clearAllDrivingBehaviorEvents(beacon:)

Clear all driving behavior events from beacon.

func clearAllDrivingBehaviorEvents(beacon: SCPBeacon)

Parameters:

  • beacon: Connected beacon

Example:

SBeaconManager.shared.clearAllDrivingBehaviorEvents(beacon: myBeacon)

Configuration Methods

enableDrivingBehavior(_:beacon:commit:)

Enable or disable all driving behavior detection.

func enableDrivingBehavior(
    _ enabled: Bool,
    beacon: SCPBeacon,
    commit: Bool = true
)

Parameters:

  • enabled: true to enable, false to disable
  • beacon: Connected beacon
  • commit: Auto-commit changes (default: true)

Example:

SBeaconManager.shared.enableDrivingBehavior(true, beacon: myBeacon)

setCorneringThreshold(_:beacon:commit:)

Set cornering detection threshold.

func setCorneringThreshold(
    _ threshold: UInt16,
    beacon: SCPBeacon,
    commit: Bool = true
)

Parameters:

  • threshold: Threshold in milli-G (50-5000)
  • beacon: Connected beacon
  • commit: Auto-commit changes (default: true)

Validation: 50 ≤ threshold ≤ 5000

Example:

SBeaconManager.shared.setCorneringThreshold(300, beacon: myBeacon)  // 0.3G

setBrakingThreshold(_:beacon:commit:)

Set braking detection threshold.

func setBrakingThreshold(
    _ threshold: UInt16,
    beacon: SCPBeacon,
    commit: Bool = true
)

Parameters:

  • threshold: Threshold in milli-G (50-5000)
  • beacon: Connected beacon
  • commit: Auto-commit changes (default: true)

Validation: 50 ≤ threshold ≤ 5000

Example:

SBeaconManager.shared.setBrakingThreshold(400, beacon: myBeacon)  // 0.4G

setAccelerationThreshold(_:beacon:commit:)

Set acceleration detection threshold.

func setAccelerationThreshold(
    _ threshold: UInt16,
    beacon: SCPBeacon,
    commit: Bool = true
)

Parameters:

  • threshold: Threshold in milli-G (50-5000)
  • beacon: Connected beacon
  • commit: Auto-commit changes (default: true)

Validation: 50 ≤ threshold ≤ 5000

Example:

SBeaconManager.shared.setAccelerationThreshold(350, beacon: myBeacon)  // 0.35G

setDurationThreshold(_:beacon:commit:)

Set minimum event duration threshold.

func setDurationThreshold(
    _ threshold: UInt16,
    beacon: SCPBeacon,
    commit: Bool = true
)

Parameters:

  • threshold: Threshold in milliseconds (1-10000)
  • beacon: Connected beacon
  • commit: Auto-commit changes (default: true)

Validation: 1 ≤ threshold ≤ 10000

Example:

SBeaconManager.shared.setDurationThreshold(500, beacon: myBeacon)  // 500ms

applyDrivingBehaviorConfig(_:beacon:)

Apply complete driving behavior configuration.

func applyDrivingBehaviorConfig(
    _ config: DrivingBehaviorConfig,
    beacon: SCPBeacon
)

Parameters:

  • config: Configuration object with all thresholds
  • beacon: Connected beacon

Behavior: Writes all settings sequentially, then commits

Duration: ~1.2 seconds

Example:

let config = DrivingBehaviorConfig(
    corneringThreshold: 300,
    brakingThreshold: 400,
    accelerationThreshold: 350,
    durationThreshold: 500,
    enableFlagsValue: DrivingBehaviorConfig.enableAllValue
)

SBeaconManager.shared.applyDrivingBehaviorConfig(config, beacon: myBeacon)

commitConfiguration(beacon:delay:)

Manually commit pending configuration changes.

func commitConfiguration(
    beacon: SCPBeacon,
    delay: TimeInterval = 0
)

Parameters:

  • beacon: Connected beacon
  • delay: Delay before committing (seconds)

Use Case: After multiple writes with commit: false

Example:

// Multiple changes without committing
SBeaconManager.shared.setCorneringThreshold(300, beacon: myBeacon, commit: false)
SBeaconManager.shared.setBrakingThreshold(400, beacon: myBeacon, commit: false)

// Commit all at once
SBeaconManager.shared.commitConfiguration(beacon: myBeacon, delay: 0.3)

readDrivingBehaviorEnableFlags(beacon:)

Read current enable flags from beacon.

func readDrivingBehaviorEnableFlags(beacon: SCPBeacon)

Parameters:

  • beacon: Connected beacon

Callback: drivingBehaviorEnableFlagsReceived(DrivingBehaviorEnableFlags)

Example:

SBeaconManager.shared.readDrivingBehaviorEnableFlags(beacon: myBeacon)

readCorneringThreshold(beacon:)

Read current cornering threshold from beacon.

func readCorneringThreshold(beacon: SCPBeacon)

Parameters:

  • beacon: Connected beacon

Example:

SBeaconManager.shared.readCorneringThreshold(beacon: myBeacon)

readBrakingThreshold(beacon:)

Read current braking threshold from beacon.

func readBrakingThreshold(beacon: SCPBeacon)

Parameters:

  • beacon: Connected beacon

Example:

SBeaconManager.shared.readBrakingThreshold(beacon: myBeacon)

readAccelerationThreshold(beacon:)

Read current acceleration threshold from beacon.

func readAccelerationThreshold(beacon: SCPBeacon)

Parameters:

  • beacon: Connected beacon

Example:

SBeaconManager.shared.readAccelerationThreshold(beacon: myBeacon)

readDurationThreshold(beacon:)

Read current duration threshold from beacon.

func readDurationThreshold(beacon: SCPBeacon)

Parameters:

  • beacon: Connected beacon

Example:

SBeaconManager.shared.readDurationThreshold(beacon: myBeacon)

Calibration Methods

calibrateBeacon()

Initiate beacon accelerometer calibration.

func calibrateBeacon()

Returns: Void

Prerequisites: Beacon on flat, stable surface

Callback: calibrationComplete(CalibrationError?)

Duration: ~5-15 seconds

Example:

SBeaconManager.shared.calibrateBeacon()

checkBeaconCalibration()

Check if beacon is calibrated.

func checkBeaconCalibration()

Returns: Void

Side Effects: Updates beacon.isCalibrated property

Example:

SBeaconManager.shared.checkBeaconCalibration()

// Check result after delay
DispatchQueue.main.asyncAfter(deadline: .now() + 1.0) {
    if myBeacon.isCalibrated {
        print("Beacon is calibrated")
    }
}

SCPBeaconManager Methods

createBeacon(...)

Create new beacon in CoreData.

func createBeacon(
    name: String,
    proximityUUID: String,
    major: NSNumber,
    minor: NSNumber,
    activities: Set<SCPActivity>?,
    location: CLLocation?,
    subscriptionId: Int,
    subscriptionUnitSerialNumber: String?,
    range: NSNumber?,
    macAddress: String?
) -> SCPBeacon?

Returns: Created SCPBeacon or nil on failure

Example:

let beacon = SCPBeaconManager.shared.createBeacon(
    name: "",
    proximityUUID: unpairedBeacon.uuid.uuidString,
    major: unpairedBeacon.major,
    minor: unpairedBeacon.minor,
    activities: nil,
    location: nil,
    subscriptionId: 0,
    subscriptionUnitSerialNumber: nil,
    range: unpairedBeacon.range,
    macAddress: unpairedBeacon.macAddressEnding
)

deleteBeacon(id:)

Delete beacon from CoreData.

func deleteBeacon(id: NSManagedObjectID)

Parameters:

  • id: Beacon's CoreData object ID

Example:

SCPBeaconManager.shared.deleteBeacon(id: beacon.objectID)

getAllSBeacons()

Get all paired SBeacons.

func getAllSBeacons() -> [SCPBeacon]

Returns: Array of all paired SCPBeacon objects

Example:

let beacons = SCPBeaconManager.shared.getAllSBeacons()

isCarBeacon(_:)

Check if beacon is designated as car beacon.

func isCarBeacon(_ beacon: SCPBeacon) -> Bool

Parameters:

  • beacon: Beacon to check

Returns: true if car beacon (receives trip status updates)

Example:

if SCPBeaconManager.shared.isCarBeacon(myBeacon) {
    // This beacon will receive trip status updates
}

Callback Properties

All callbacks are optional closures on SBeaconManager.shared:

// Pairing
var macAddressReceived: ((String) -> Void)?

// Trip management
var tripStatusChanged: ((TripStatus) -> Void)?
var tripInformationReceived: ((Int, Int, Int) -> Void)?
var tripRecordsReceived: (([TripRecord]) -> Void)?
var incidentRecordsReceived: (([IncidentRecord]) -> Void)?

// Driving behavior
var drivingBehaviorEventsReceived: (([DrivingBehaviorEvent]) -> Void)?
var realTimeDrivingBehaviorEventDetected: ((RealTimeDrivingBehaviorEvent) -> Void)?
var drivingBehaviorEnableFlagsReceived: ((DrivingBehaviorEnableFlags) -> Void)?

// Calibration
var calibrationComplete: ((CalibrationError?) -> Void)?

// Connection
var onBeaconConnecting: (() -> Void)?

Notification Names

Framework posts NotificationCenter notifications:

SBeaconManager.beaconConnectedNotification
SBeaconManager.beaconDisconnectedNotification
SBeaconManager.batteryStatusChangedNotification
SBeaconManager.beaconPairedNotification
SBeaconManager.beaconUnpairedNotification
SBeaconManager.beaconInRangeNotification
SBeaconManager.beaconOutOfRangeNotification

Example:

NotificationCenter.default.addObserver(
    forName: SBeaconManager.beaconConnectedNotification,
    object: nil,
    queue: .main
) { _ in
    print("Beacon connected")
}

Related Pages