Flutter

Connection

enum Connection {
  ble,          // Bluetooth Low Energy
  apple,        // iPhone's built-in sensors (iOS only)
  wearOs,       // Wear OS watches (Android only)
  android,      // Phone's built-in sensors (Android only)
  ant,          // ANT+ protocol (Android only)
  watchOs,      // Apple Watch via WatchConnectivity (iOS only)
  allDevices,   // Combined BLE + ANT scanning (Android only)
}

Platform availability:

Value	iOS	Android
ble	Yes	Yes
apple	Yes	No
watchOs	Yes	No
wearOs	No	Yes
android	No	Yes
ant	No	Yes
allDevices	No (maps to ble)	Yes

DataType

enum DataType {
  heartRate, ecg, steps, hrv, calories, location,
  speed, distance, stepsCadence, floorsClimbed,
  gyroscope, acceleration
}

Types

Update

Data points delivered via streaming callbacks.

class Update {
  final String ts;           // ISO 8601 timestamp
  final DataType type;       // Data type enum value
  final double? val;         // Scalar value (e.g. heart rate BPM)
  final List<double>? d;     // Array for multi-axis data (e.g. [x, y, z])
}

Device

class Device {
  final String deviceId;
  final String deviceName;
}

Callbacks

typedef UpdateCallback = void Function(Update);
typedef DeviceCallback = void Function(Device);
typedef ConnectionCallback = void Function(bool);

---

Initialization

init

Creates and authenticates the RT SDK instance. Makes a network call.

static Future<bool?> init(String devId, String? referenceId) async

• devId ➡ Your developer ID.

• referenceId ➡ Optional user identifier in your system.

initConnection

Authenticates the SDK user. Makes a network call. Token should be generated server-side.

static Future<bool?> initConnection(String token) async

getUserId

Returns the Terra user ID, or null if not initialized.

static Future<String?> getUserId() async

disconnect

Disconnects from the given connection type.

static Future<bool?> disconnect(Connection connection) async

Device Scanning

startDeviceScan

Starts scanning with the built-in UI. On iOS, this renders a native SwiftUI BLE scanner view (use the iOSScanView widget). On Android, this uses the native device picker.

static Future<bool?> startDeviceScan(
    Connection connection,
    {bool useCache = false,
     ConnectionCallback? connectionCallback}) async

• connection ➡ The connection type to scan for.

• useCache ➡ Reconnect to a previously paired device if available.

• connectionCallback ➡ Optional callback fired when a device connection changes.

startDeviceScanToCallback

Starts scanning and delivers discovered devices via deviceCallback. Use connectDevice() to connect to a chosen device.

static Future<bool?> startDeviceScanToCallback(
    Connection connection,
    DeviceCallback deviceCallback,
    {ConnectionCallback? connectionCallback}) async

connectDevice

Connects to a specific Device discovered via startDeviceScanToCallback.

static Future<bool?> connectDevice(Device device) async

iOSScanView (iOS only)

A Flutter widget that embeds the native iOS BLE scanner UI. Renders an empty Container on non-iOS platforms.

class iOSScanView extends StatelessWidget

Usage:

iOSScanView()  // Place in your widget tree

Data Streaming

startRealtimeToServer

Streams data to Terra's websocket server. Data is sent to the server but not delivered locally.

static Future<bool?> startRealtimeToServer(
    Connection connection,
    List<DataType> types,
    String token) async

startRealtimeToApp

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

static Future<bool?> startRealtimeToApp(
    Connection connection,
    List<DataType> types,
    UpdateCallback callback) async

stopRealtime

Stops streaming for the given connection type.

static Future<bool?> stopRealtime(Connection connection) async

WatchOS (iOS only)

These methods return false on Android.

connectWatchOS

Establishes a WatchConnectivity session with the paired Apple Watch.

static Future<bool> connectWatchOS() async

resumeWatchOSWorkout

Resumes a paused workout on the Apple Watch.

static Future<bool> resumeWatchOSWorkout() async

pauseWatchOSWorkout

Pauses the current workout on the Apple Watch.

static Future<bool> pauseWatchOSWorkout() async

stopWatchOSWorkout

Stops the current workout on the Apple Watch.

static Future<bool> stopWatchOSWorkout() async