> For the complete documentation index, see [llms.txt](https://freegrow-1.gitbook.io/product-docs-en/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://freegrow-1.gitbook.io/product-docs-en/en-mobile-kit-n1/uwb-n1-sdk/ranging-sdk/android.md).

# Android

This document introduces the **GrowSpace Android SDK**, a development kit designed to easily integrate BLE and UWB-based indoor positioning into Android apps.\
From ranging to RTLS-based positioning, all features can be controlled through a single class: `SpaceUwb`.

***

### Key Features

* BLE + UWB ranging
* RTLS-based position estimation (x, y, z calculation)
* Real-time device connect/disconnect event handling

***

### Installation

#### Gradle setup

```kotlin
dependencies {
    implementation("io.github.freegrowenterprise:SpaceSDK-Android:0.0.9")
}
```

#### Android Permission Settings (AndroidManifest.xml)

```xml
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<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" />
<uses-permission android:name="android.permission.UWB_RANGING" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
```

### Requirements

| Item       | Requirement                             |
| ---------- | --------------------------------------- |
| Android OS | Android 14 (API level 34) or higher     |
| Language   | Kotlin 1.9.22 (recommended)             |
| Device     | Android smartphone with UWB support     |
| Hardware   | GrowSpace UWB products (Tags / Anchors) |

***

### Initialization

```kotlin
val spaceUwb = SpaceUwb(context = applicationContext, activity = this)
```

***

### Start Ranging

```kotlin
spaceUwb.startUwbRanging(
    maximumConnectionCount = 4,
    replacementDistanceThreshold = 8f,
    isConnectStrongestSignalFirst = true,
    onUpdate = { result ->
        Log.d("UWB", "device=${result.deviceName}, distance=${result.distance}m")
    },
    onDisconnect = { device ->
        Log.w("UWB", "Disconnected from ${device.deviceName}")
    }
)
```

### Stop Ranging

```kotlin
spaceUwb.stopUwbRanging { result ->
    if (result.isSuccess) {
        Log.i("UWB", "Ranging stopped")
    } else {
        Log.e("UWB", "Stop failed: ${result.exceptionOrNull()?.message}")
    }
}
```

***

### Start RTLS Positioning

```kotlin
val anchorMap = mapOf(
    "FGU-0001" to Triple(0.0, 0.0, 0.0),
    "FGU-0002" to Triple(5.0, 0.0, 0.0),
    "FGU-0003" to Triple(0.0, 5.0, 0.0)
)

spaceUwb.startUwbRtls(
    anchorPositionMap = anchorMap,
    zCorrection = 1.0f,
    maximumConnectionCount = 4,
    replacementDistanceThreshold = 8f,
    isConnectStrongestSignalFirst = true,
    filterType = RtlsFilterType.AVERAGE,
    onResult = { location ->
        Log.d("RTLS", "x=${location.x}, y=${location.y}, z=${location.z}")
    },
    onFail = { error ->
        Log.e("RTLS", "Positioning failed: $error")
    },
    onDeviceRanging = { map ->
        map.forEach { (id, dist) ->
            Log.d("RTLS", "$id = $dist m")
        }
    }
)
```

***

### Test App

You can easily test SDK features using the official demo app

* [GitHub](https://github.com/freegrowenterprise/SpaceSDK-Android-TestApp)
* [Google Play](https://play.google.com/store/apps/details?id=com.growspace.testapp\&pcampaignid=web_share)