Lock & Unlock

Control Igloohome smart locks via BLE.

lock

Locks the device via Bluetooth. Optionally sets the lock's internal clock before locking.

Signature

suspend fun lock(
    deviceId: String,
    key: String,
    timeInSeconds: Long? = null,
    operationId: Int? = null,
)

func lock(
    _ deviceId: String,
    key: String,
    operationId: Int? = nil
) async throws

Parameters

Name	Type	Required	Description
`deviceId`	`String`	Yes	Bluetooth device name of the lock (e.g. `"IGM4-XXXX"`).
`key`	`String`	Yes	Guest key for BLE authentication. Required permission: `LOCK`.
`timeInSeconds`	`Long?`	No	Unix timestamp (seconds) to set on the lock before locking. If omitted, the SDK uses the last server time if available.
`operationId`	`Int?`	No	Operation ID for tracking the BLE command in activity logs.

Error Codes

Exception	Code	Description
`BluetoothException`	708	Bluetooth is off or unavailable.
`ConnectionException`	12	BLE connection failed or device disconnected.
`TimeoutException`	703	Operation exceeded the 15-second BLE timeout.
`GenericException`	1	Any other unhandled error.

On iOS, lock/unlock throw IgloohomeError — see Error Reference.

Example

try {
    sdk.lock(
        deviceId = "IGM4-XXXX",
        key = guestKey,
    )
    showSuccess("Door locked")
} catch (e: IglooHomeException) {
    when (e) {
        is IglooHomeException.BluetoothException -> showError("Please enable Bluetooth")
        is IglooHomeException.ConnectionException -> showError("unexpected bluetooth connection issue")
        is IglooHomeException.TimeoutException -> showError("Operation timed out, try again")
        else -> showError("Failed: ${e.message}")
    }
}

do {
    try await sdk.lock("IGM4-XXXX", key: guestKey)
    showSuccess(message: "Door locked")
} catch IgloohomeError.bluetoothIsTurnedOff {
    showError(message: "Please enable Bluetooth")
} catch IgloohomeError.connection {
    showError(message: "unexpected bluetooth connection issue")
} catch IgloohomeError.timeout {
    showError(message: "Operation timed out, try again")
} catch {
    showError(message: "Failed: \(error.localizedDescription)")
}

unlock

Unlocks the device via Bluetooth. Optionally sets the lock's internal clock before unlocking.

Signature

suspend fun unlock(
    deviceId: String,
    key: String,
    timeInSeconds: Long? = null,
    operationId: Int? = null,
)

func unlock(
    _ deviceId: String, 
    key: String, 
    operationId: Int? = nil
) async throws

Parameters

Name	Type	Required	Description
`deviceId`	`String`	Yes	Bluetooth device name of the lock.
`key`	`String`	Yes	Guest key for BLE authentication. Required permission: `UNLOCK`.
`timeInSeconds`	`Long?`	No	Unix timestamp (seconds) to set on the lock before unlocking.
`operationId`	`Int?`	No	Operation ID for tracking the BLE command in activity logs.

Error Codes

Exception	Code	Description
`BluetoothException`	708	Bluetooth is off or unavailable.
`ConnectionException`	12	BLE connection failed or device disconnected.
`TimeoutException`	703	Operation exceeded the 15-second BLE timeout.
`GenericException`	1	Any other unhandled error.

Example

try {
    sdk.unlock(
        deviceId = "IGM4-XXXX",
        key = guestKey,
    )
    showSuccess("Door unlocked")
} catch (e: IglooHomeException) {
    when (e) {
        is IglooHomeException.ConnectionException -> showError("unexpected bluetooth connection issue")
        is IglooHomeException.TimeoutException -> showError("Timed out, try again")
        else -> showError("Failed: ${e.message}")
    }
}

do {
    try await sdk.unlock("IGM4-XXXX", key: guestKey)
    showSuccess(message: "Door unlocked")
} catch IgloohomeError.connection {
    showError(message: "unexpected bluetooth connection issue")
} catch IgloohomeError.timeout {
    showError(message: "Timed out, try again")
} catch {
    showError(message: "Failed: \(error.localizedDescription)")
}

disconnect

Closes the BLE connection to a specific lock. Safe to call even if not connected.

Signature

suspend fun disconnect(deviceId: String)

func disconnect(_ deviceId: String) async throws

Parameters

Name	Type	Required	Description
`deviceId`	`String`	Yes	Bluetooth device name of the lock to disconnect from.

Example

sdk.disconnect("IGM4-XXXX")

try? await sdk.disconnect("IGM4-XXXX")

disconnectAll

Closes all active BLE connections.

Signature

suspend fun disconnectAll()

Example

sdk.disconnectAll()

Notes

The default BLE timeout is 15 seconds for lock/unlock operations.
The SDK automatically connects to the lock when lock() or unlock() is called — there is no separate connect() method.
Always call disconnect() or disconnectAll() when done to free BLE resources. On iOS, call disconnect(_:) for each device you connected to.
If the lock disconnects during an operation, ConnectionException (Android) / IgloohomeError.connection (iOS) is thrown immediately.