Android (Kotlin)

Connections

enum class Connections {
    BLE,          // Bluetooth Low Energy devices (heart rate monitors, etc.)
    WEAR_OS,      // Wear OS watches via classic Bluetooth
    ANDROID,      // Phone's built-in sensors (accelerometer, gyroscope)
    ANT,          // ANT+ protocol devices
    ALL_DEVICES,  // Combined BLE + ANT scanning/connection
}

DataTypes

enum class DataTypes {
    HEART_RATE, ECG, STEPS, HRV, CALORIES, LOCATION, DISTANCE,
    ACTIVITY, ACCELERATION, GYROSCOPE, FLOORS_CLIMBED, STEPS_CADENCE,
    SPEED, POWER, BIKE_CADENCE, MET, RR_INTERVAL,
    CORE_TEMPERATURE, SKIN_TEMPERATURE
}

Update

Data points delivered via streaming callbacks.

data class Update(
    var ts: String? = null,           // ISO 8601 timestamp
    var `val`: Double? = null,        // Scalar value (e.g. heart rate BPM)
    var type: String? = null,         // Data type identifier (e.g. "HEART_RATE")
    var d: ArrayList<Double>? = null  // Array for multi-axis data (e.g. [x, y, z])
)

For scalar metrics (heart rate, steps), the value is in val. For vector metrics (acceleration, gyroscope), the values are in d. Note: val is a Kotlin reserved keyword — access it with backticks: update.`val`.

Device

Represents a discovered BLE/ANT device.

data class Device(
    val deviceId: String,       // Device identifier
    val deviceName: String?,    // Human-readable name (nullable)
)

ConnectedDevice

Represents a currently connected device.

data class ConnectedDevice(
    val id: String,      // Device identifier
    val name: String?,   // Device name (nullable)
    val type: String,    // "BLE", "BT", or "ANT"
)

ConnectionState

enum class ConnectionState {
    DISCONNECTED, CONNECTING, CONNECTED
}

---

Initialization

TerraRT

Creates and authenticates a TerraRT instance. Makes a network call to Terra's servers. Requests required Android permissions (Bluetooth, location, activity recognition, body sensors) if not already granted.

class TerraRT(
    devId: String,
    context: Context,
    referenceId: String?,
    completion: (Boolean) -> Unit
)

• devId ➡ Your developer ID from the Terra Dashboard.

• context ➡ Activity context (required for permission dialogs).

• referenceId ➡ Optional user identifier in your system. Appears as reference_id in webhooks.

• completion ➡ true if initialization succeeded.

Connection Setup

initConnection

Authenticates the SDK user with Terra's backend. Makes a network call. The token should be generated server-side via the Generate Authentication Token endpoint.

fun initConnection(token: String, callback: (Boolean) -> Unit)

getUserId

Returns the Terra user ID, or null if not yet initialized. Synchronous, no network call.

fun getUserId(): String?

disconnect

Disconnects from the given connection type.

fun disconnect(type: Connections)

Device Scanning

Two overloads for different scanning workflows:

startDeviceScan (with device callback)

Starts scanning and calls deviceCallback for each discovered device. You then call connectDevice() to connect to a chosen device.

fun startDeviceScan(type: Connections,
                    deviceCallback: (Device) -> Unit)

startDeviceScan (with built-in UI)

Starts scanning with automatic connection handling. If useCache is true, reconnects to a previously paired device. If not found and showWidgetIfCacheNotFound is true, shows the built-in device picker UI.

fun startDeviceScan(type: Connections,
                    useCache: Boolean = false,
                    showWidgetIfCacheNotFound: Boolean = true,
                    callback: (Boolean) -> Unit = { _ -> })

connectDevice

Connects to a specific Device returned from the device-callback startDeviceScan overload.

fun connectDevice(device: Device,
                  connectionCallback: (Boolean) -> Unit)

getConnectedDevices

Returns the set of currently connected devices.

fun getConnectedDevices(): Set<ConnectedDevice>

Data Streaming

Three startRealtime overloads for different streaming modes:

startRealtime (server + local)

Streams data to both Terra's websocket server and a local updateHandler callback.

fun startRealtime(type: Connections,
                  dataTypes: Set<DataTypes> = setOf(),
                  token: String,
                  updateHandler: (Update) -> Unit,
                  connectionCallback: (Boolean) -> Unit = { _ -> })

startRealtime (local only)

Streams data to a local callback only. No server connection.

fun startRealtime(type: Connections,
                  dataTypes: Set<DataTypes> = setOf(),
                  updateHandler: (Update) -> Unit)

startRealtime (server only)

Streams data to Terra's websocket server only. No local callback.

Note the different parameter order from the dual-mode overload: token is the 2nd parameter here.

fun startRealtime(type: Connections,
                  token: String,
                  dataTypes: Set<DataTypes> = setOf(),
                  connectionCallback: (Boolean) -> Unit = { _ -> })

Parameters:

• type ➡ The connection type.

• dataTypes ➡ Set of data types to stream. Defaults to empty (streams all available).

• token ➡ Authentication token for the websocket connection.

• updateHandler ➡ Called with each Update data point.

• connectionCallback ➡ Called when the websocket connection state changes.

stopRealtime

Stops streaming for a given connection type.

fun stopRealtime(type: Connections)

Static Methods

setWebsocketEventListener

Sets a global listener for websocket connection events.

companion object {
    fun setWebsocketEventListener(listener: (Boolean, Error?) -> Unit)
}