Pairing

pair

Pairs an Igloo lock via Bluetooth and registers it on the server. Protocol (G2/G3) is auto-detected from the lock's firmware.

The SDK orchestrates the full flow: timezone resolution, DST data fetch, BLE handshake, server registration, and commit. If commit fails after server registration, the device is automatically rolled back (deleted from server).

Signature

suspend fun pair(
    deviceId: String,
    name: String,
    propertyIds: List<String>,
    accessToken: String,
): PairResult

func pair(
    deviceId: String,
    lockName: String,
    propertyIds: [String],
    accessToken token: String
) async throws -> PairResult

Parameters

Name	Type	Required	Description
`deviceId`	`String`	Yes	Bluetooth device name of the lock (e.g. `"SP2Xo01231"`).
`name`	`String`	Yes	User-assigned name for the lock.
`propertyIds`	`List<String>`	Yes	IDs of properties to assign this lock to. Must be non-empty. All properties must share the same timezone.
`accessToken`	`String`	Yes	OAuth access token for server calls.

Return Type

data class PairResult(
    val type: String,
    val deviceId: String,
    val name: String,
    val pairedAt: String,
    val properties: List<PairResultProperty>,
)

data class PairResultProperty(
    val name: String,
    val timezone: String,
    val id: String,
)

public struct PairResult: Sendable {
    public let type: String
    public let bluetoothDeviceName: String
    public let name: String
    public let pairedAt: String
    public let properties: [Property]
}

public struct Property: Sendable {
    public let name: String
    public let timezone: String
    public let id: String
}

Error Codes

Exception	Code	Description
`BluetoothException`	708	Bluetooth is off or unavailable.
`ConnectionException`	12	BLE connection failed or device disconnected during pairing.
`TimeoutException`	703	BLE operation exceeded the timeout.
`DevicePairedException`	910	Device is already paired (detected server-side or via BLE scan).
`ApiException`	varies	Server API call failed.
`GenericException`	1	Property IDs empty, timezone conflict, or unsupported protocol.

Example

try {
    val result = sdk.pair(
        deviceId = "SP2Xo01231",
        name = "Front Door Lock",
        propertyIds = listOf("prop-123"),
        accessToken = accessToken,
    )
    println("Paired: ${result.name} at ${result.pairedAt}")
    println("Properties: ${result.properties.map { it.name }}")
} catch (e: IglooHomeException.DevicePairedException) {
    showError("This lock is already paired")
} catch (e: IglooHomeException.HasLinkedDeviceException) {
    showError("Unlink accessories first: ${e.linkedDeviceIds}")
} catch (e: IglooHomeException) {
    showError("Pairing failed: ${e.message}")
}

do {
    let result = try await sdk.pair(
        deviceId: "SP2Xo01231",
        lockName: "Front Door Lock",
        propertyIds: ["prop-123"],
        accessToken: accessToken)
    print("Paired: \(result.name) at \(result.pairedAt)")
    print("Properties: \(result.properties.map(\.name))")
} catch IgloohomeError.devicePaired {
    showError(message: "This lock is already paired")
} catch IgloohomeError.hasLinkedDevice(let linkedDeviceIds) {
    showError(message: "Unlink accessories first: \(linkedDeviceIds)")
} catch {
    showError(message: "Pairing failed: \(error.localizedDescription)")
}

Notes

The device must be in pairing mode (unpaired state).
All propertyIds must share the same timezone — the SDK fetches DST data based on this shared timezone.
G3 locks (protocol version 2) use certificate-based pairing with an additional server round-trip.
If the BLE commit step fails after server registration, the SDK automatically deletes the server record.

unpair

Unpairs a lock via Bluetooth and removes it from the server.

The SDK checks for linked devices first. If the lock has linked accessories (keypads, fobs, bridges), it throws HasLinkedDeviceException — you must unlink them first.

Signature

suspend fun unpair(
    deviceId: String,
    accessToken: String,
)

func unpair(
    deviceId: String, 
    accessToken token: String
) async throws

Parameters

Name	Type	Required	Description
`deviceId`	`String`	Yes	Bluetooth device name of the lock.
`accessToken`	`String`	Yes	OAuth access token for server calls.

Error Codes

Exception	Code	Description
`BluetoothException`	708	Bluetooth is off or unavailable.
`ConnectionException`	12	Device disconnected during unpair.
`TimeoutException`	703	BLE operation exceeded the timeout.
`HasLinkedDeviceException`	910	Device has linked accessories. Contains `linkedDeviceIds: List<String>`.
`ApiException`	varies	Server API call failed.

Example

try {
    sdk.unpair(
        deviceId = "SP2Xo01231",
        accessToken = accessToken,
    )
    showSuccess("Lock removed")
} catch (e: IglooHomeException.HasLinkedDeviceException) {
    showError("Unlink these devices first: ${e.linkedDeviceIds}")
} catch (e: IglooHomeException) {
    showError("Unpair failed: ${e.message}")
}

do {
    try await sdk.unpair(deviceId: "SP2Xo01231", accessToken: accessToken)
    showSuccess(message: "Lock removed")
} catch IgloohomeError.hasLinkedDevice(let linkedDeviceIds) {
    showError(message: "Unlink these devices first: \(linkedDeviceIds)")
} catch {
    showError(message: "Unpair failed: \(error.localizedDescription)")
}

Notes

The SDK automatically fetches the correct key for BLE unpair (ekey for G3, admin key for G2). Unlike lock/unlock, unpair on both platforms does not take a key parameter — it is resolved internally.
Server deletion retries up to 3 times with 5-second delays on failure.
After unpair, all access credentials (PINs, keycards, fingerprints) are removed.

setWifiConfig

Configures WiFi on an Igloo Bridge device via Bluetooth.

After sending WiFi credentials via BLE, the SDK generates a CSR on the bridge and polls the server until the bridge is provisioned and online.

Signature

suspend fun setWifiConfig(
    deviceId: String,
    key: String,
    ssid: String,
    networkPassword: String,
    accessToken: String,
)

func setWifiConfig(
    deviceId: String,
    key: String,
    ssid: String,
    networkPassword: String,
    accessToken token: String
) async throws

Parameters

Name	Type	Required	Description
`deviceId`	`String`	Yes	Bluetooth device name of the bridge (e.g. `"EB1-XXXX"`).
`key`	`String`	Yes	Admin key for BLE authentication.
`ssid`	`String`	Yes	WiFi network SSID.
`networkPassword`	`String`	Yes	WiFi network password.
`accessToken`	`String`	Yes	OAuth access token for server calls.

Error Codes

Exception	Code	Description
`BluetoothException`	708	Bluetooth is off or unavailable.
`ConnectionException`	12	Device disconnected during setup.
`TimeoutException`	703	Bridge was not provisioned or online after all polling retries (15s, 30s, 45s).

Example

try {
    sdk.setWifiConfig(
        deviceId = "EB1-XXXX",
        key = adminKey,
        ssid = "Office-WiFi",
        networkPassword = "password123",
        accessToken = accessToken,
    )
    showSuccess("Bridge WiFi configured and online")
} catch (e: IglooHomeException.TimeoutException) {
    showError("Bridge did not come online — check WiFi credentials")
} catch (e: IglooHomeException) {
    showError("WiFi setup failed: ${e.message}")
}

do {
    try await sdk.setWifiConfig(
        deviceId: "EB1-XXXX",
        key: adminKey,
        ssid: "Office-WiFi",
        networkPassword: "password123",
        accessToken: accessToken)
    showSuccess(message: "Bridge WiFi configured and online")
} catch IgloohomeError.timeout {
    showError(message: "Bridge did not come online — check WiFi credentials")
} catch {
    showError(message: "WiFi setup failed: \(error.localizedDescription)")
}

Notes

The SDK sends WiFi credentials + MQTT broker config to the bridge in a single BLE command.
After the BLE write, the SDK generates a private key CSR on the bridge.
The SDK then polls the server at 15s, 30s, and 45s intervals until isProvisioned and isOnline are both true.
If the bridge doesn't come online after all retries, TimeoutException (Android) / IgloohomeError.timeout (iOS) is thrown.