# SDK Setup

Install the igloohome BLE SDK and make your first lock operation.

---

## Requirements

| Requirement | Version |
|-------------|---------|
| Android minSdk | 24 (Android 7.0) |
| Android compileSdk | 35 |
| Kotlin | 2.0.21+ |
| Java compatibility | 1.8 |
| iOS deployment target | 15.0+ |
| Xcode | 16+ |
| Swift | 6.0+ (Swift 6 language mode) |

> BLE requires a physical iOS device — the iOS Simulator does not support Bluetooth.

---

## Installation (Android)

### 1. Add the GitLab Maven Repository

In your project-level `settings.gradle.kts`:

```kotlin
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("https://gitlab.com/api/v4/projects/64441730/packages/maven")
            credentials(HttpHeaderCredentials::class) {
                name = "Private-Token"
                value = providers.gradleProperty("iglooGitlabToken").get()
            }
            authentication {
                create<HttpHeaderAuthentication>("header")
            }
        }
    }
}
```

Add your GitLab Personal Access Token to `gradle.properties`:

```properties
iglooGitlabToken=glpat-XXXXXXXXXXXXXXXXXXXX
```

> **Security:** Do not commit `gradle.properties` with tokens to version control. Add it to `.gitignore`.

### 2. Add the SDK Dependency

In your module-level `build.gradle.kts`:

```kotlin
dependencies {
    implementation("co.igloo.home:sdk:3.5.0-build.2")
}
```

---

## Installation (iOS)

### 1. Add the Package

Via Swift Package Manager, in Xcode: **File → Add Package Dependencies…**, or in `Package.swift`:

```swift
dependencies: [
    .package(url: "https://gitlab.com/igloohome/iglooaccess-ios-sdk.git", from: "3.5.0")
]
```

Add the `IgloohomeSDK` product to your target's dependencies.

> **Note:** the package repo is private — Xcode must be configured with credentials (SSH key or a GitLab personal access token) that can read `gitlab.com/igloohome/iglooaccess-ios-sdk`.

Alternatively, via CocoaPods:

```ruby
pod 'IgloohomeSDK', :git => 'https://gitlab.com/igloohome/iglooaccess-ios-sdk.git', :tag => '3.5.0'
```

Set **Build Libraries for Distribution** (`BUILD_LIBRARY_FOR_DISTRIBUTION = YES`) on your app target — the SDK links a prebuilt `IglooSDKCore.xcframework`.

### 2. Import

```swift
import IgloohomeSDK
import IglooSDKCore
```

`IglooSDKCore` provides the shared enums/structs used across the API (`ScanResult`, `LockingDirection`, `CalibrationStep`, etc.) and must be imported alongside `IgloohomeSDK` even though the entry point (`IglooPlugin`) lives in `IgloohomeSDK`.

---

## Permissions

### AndroidManifest.xml

```xml
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
```

### Info.plist (iOS)

```xml
<key>NSBluetoothAlwaysUsageDescription</key>
<string>This application uses Bluetooth to connect to the Lock</string>
<key>NSBluetoothPeripheralUsageDescription</key>
<string>This application uses Bluetooth peripherals</string>
```

### Runtime Permissions

Request BLE permissions before calling any SDK method:

```kotlin
private val blePermissions = arrayOf(
    Manifest.permission.BLUETOOTH_SCAN,
    Manifest.permission.BLUETOOTH_CONNECT,
    Manifest.permission.ACCESS_FINE_LOCATION,
)

private val permissionLauncher = registerForActivityResult(
    ActivityResultContracts.RequestMultiplePermissions()
) { grants ->
    if (grants.values.all { it }) {
        // All permissions granted — safe to use SDK
    }
}

// Call before first SDK use
permissionLauncher.launch(blePermissions)
```

There is no iOS equivalent of this step — just declare the `Info.plist` keys above and call SDK methods directly; the OS handles prompting.

---

## Initialization

### OAuth Authentication

```kotlin
val sdk = IglooPlugin(context)
// Pass accessToken to each method that requires it
```

```swift
let sdk = IglooPlugin()
// Pass accessToken to each method that requires it
```

> **Important:** Only one `IglooPlugin` instance should exist at a time. Multiple instances cause undefined BLE behavior — each holds its own connection state.

---

## Quick Start

```kotlin
// 1. Initialize
val sdk = IglooPlugin(context)

// 2. Scan for nearby locks
try {
    sdk.scanDevice().collect { result ->
        println("Found: ${result.deviceId}, paired=${result.isPaired}, rssi=${result.rssi}")
    }
} catch (e: IglooHomeException.BluetoothException) {
    println("Please enable Bluetooth")
} catch (e: IglooHomeException) {
    println("Scan failed: ${e.message}")
}

// 3. Lock a device
try {
    sdk.lock(deviceId = "IGM401abc123", key = guestKey)
    println("Locked")
} catch (e: IglooHomeException.TimeoutException) {
    println("Lock not in range")
} catch (e: IglooHomeException) {
    println("Error: ${e.message}")
}

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

// 5. Disconnect when done
sdk.disconnect("IGM401abc123")
```

```swift
// 1. Initialize
let sdk = IglooPlugin()

// 2. Scan for nearby locks
let scanTask = Task {
    do {
        for try await result in sdk.scansLock() {
            print("Found: \(result.bluetoothDeviceName), paired=\(result.isPaired)")
        }
    } catch IgloohomeError.bluetoothIsTurnedOff {
        print("Please enable Bluetooth")
    } catch {
        print("Scan failed: \(error.localizedDescription)")
    }
}
// Stop scanning once you've found what you need:
sdk.stopScan()
scanTask.cancel()

// 3. Lock a device
do {
    try await sdk.lock("IGM401abc123", key: guestKey)
    print("Locked")
} catch IgloohomeError.timeout {
    print("Lock not in range")
} catch {
    print("Error: \(error.localizedDescription)")
}

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

// 5. Disconnect when done
try? await sdk.disconnect("IGM401abc123")
```

---

## Next Steps

- [Lock & Unlock](/home/sdk_lock_unlock) — Control locks via BLE
- [Scanning](/home/sdk_scanning) — Discover nearby devices
- [Pairing](/home/sdk_pairing) — Register new locks
- [Error Reference](/home/sdk_errors) — All exception types and codes