# Flutter

## 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 via 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.** Token should be generated server-side.

```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 delivers discovered devices via `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 via `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. Data is sent to the server but not delivered locally.

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

### startRealtimeToApp

Streams data to a local callback only. 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
```