> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/reference/streaming-api/flutter.md).

# Flutter SDK

Every type and function in the Flutter RT SDK, with what each platform supports.

The Flutter RT SDK wraps the iOS and Android RT SDKs. This page lists its types and functions, and notes where a call works on one platform only.

## Connection

```dart
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

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

## Types

### Update

Data points delivered through streaming callbacks.

```dart
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

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

### Callbacks

```dart
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.

```dart
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. Generate the `token` on your backend with [`POST /auth/generateAuthToken`](https://docs.tryterra.co/reference/streaming-api/api-endpoints.md).

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

### getUserId

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

```dart
static Future<String?> getUserId() async
```

### disconnect

Disconnects from the given connection type.

```dart
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.

```dart
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 passes each discovered device to `deviceCallback`. Use `connectDevice()` to connect to a chosen device.

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

### connectDevice

Connects to a specific `Device` discovered by `startDeviceScanToCallback`.

```dart
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.

```dart
class iOSScanView extends StatelessWidget
```

Usage:

```dart
iOSScanView()  // Place in your widget tree
```

## Data streaming

### startRealtimeToServer

Streams data to Terra's WebSocket server. The app does not receive the data locally.

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

### startRealtimeToApp

Streams data to a local callback only. There is no server connection.

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

### stopRealtime

Stops streaming for the given connection type.

```dart
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.

```dart
static Future<bool> connectWatchOS() async
```

### resumeWatchOSWorkout

Resumes a paused workout on the Apple Watch.

```dart
static Future<bool> resumeWatchOSWorkout() async
```

### pauseWatchOSWorkout

Pauses the current workout on the Apple Watch.

```dart
static Future<bool> pauseWatchOSWorkout() async
```

### stopWatchOSWorkout

Stops the current workout on the Apple Watch.

```dart
static Future<bool> stopWatchOSWorkout() async
```
