Sync

Synchronize device state via Bluetooth.

sync

Syncs the lock via Bluetooth: sets the lock's internal clock, retrieves battery level, uploads activity logs, and updates the device on the server.

Signature

suspend fun sync(
    deviceId: String,
    key: String,
    timeInSeconds: Long? = null,
    getDeviceToken: String,
    storeLogsToken: String,
    updateDeviceToken: String,
    operationId: Int? = null,
): SyncResult

func sync(
    _ deviceId: String,
    key: String,
    getDeviceToken deviceToken: String,
    storeLogsToken storeToken: String,
    updateDeviceToken updateToken: String,
    timeInSeconds time: Int? = nil
) async throws -> SyncResult

Parameters

Name	Type	Required	Description
`deviceId`	`String`	Yes	Bluetooth device name of the lock.
`key`	`String`	Yes	eKey with `GET_TIME`, `SET_TIME`, `GET_BATTERY_LEVEL`, `GET_LOGS` permissions.
`timeInSeconds`	`Long?`	No	Unix timestamp (seconds) to set on the lock. If omitted, SDK uses last server time.
`getDeviceToken`	`String`	Yes	OAuth access token for fetching device info.
`storeLogsToken`	`String`	Yes	OAuth access token for uploading activity logs.
`updateDeviceToken`	`String`	Yes	OAuth access token for updating device state on the server.
`operationId`	`Int?`	No	Operation ID for tracking.

Return Type

data class SyncResult(val batteryLevel: Int)

public struct SyncResult: Sendable {
    public let batteryLevel: Int
}

Field	Description
`batteryLevel`	Battery level as percentage (0-100).

Error Codes

Exception	Code	Description
`BluetoothException`	708	Bluetooth is off or unavailable.
`ConnectionException`	12	Device disconnected during sync.
`TimeoutException`	703	BLE operation exceeded the timeout.
`ApiException`	varies	Activity log upload or device update failed.

Example

try {
    val result = sdk.sync(
        deviceId = "IGM401abc123",
        key = guestKey,
        getDeviceToken = accessToken,
        storeLogsToken = accessToken,
        updateDeviceToken = accessToken,
    )
    println("Battery: ${result.batteryLevel}%")
} catch (e: IglooHomeException.ConnectionException) {
    showError("unexpected bluetooth connection issue")
} catch (e: IglooHomeException.TimeoutException) {
    showError("Timed out, try again")
} catch (e: IglooHomeException) {
    showError("Sync failed: ${e.message}")
}

do {
    let result = try await sdk.sync(
        "IGM401abc123",
        key: guestKey,
        getDeviceToken: accessToken,
        storeLogsToken: accessToken,
        updateDeviceToken: accessToken)
    print("Battery: \(result.batteryLevel)%")
} catch {
    showError(message: "Sync failed: \(error.localizedDescription)")
}

Notes

Sync reads all pending activity logs from the lock in a loop until no more remain.
Logs are stored in a local database first, then batch-uploaded to the server.
If timeInSeconds is omitted and no cached server time is available, the lock time is not updated.
The three token parameters (getDeviceToken, storeLogsToken, updateDeviceToken) can be the same token if it has all required scopes, or different tokens with scoped permissions.