TerraRTiOS

It's finally here: The realtime streaming framework for iOS through Terra!!!!

A Worthy Note

This packages uses Bluetooth Low Energy (BLE) and Bluetooth services. These will be requested as permissions upon initialisation of the package.

The package streams real time data through Websockets and is hosted by us! You can learn more about it here on our docs.

The data streamed to your websocket connection (as a developer) will follow the following format:

{
  "op":5,
  "d":
    {
      "ts": <String> (In ISOFormat Date Form)
       "val": <Double>
       "d" <Array<Double>>
    },
    "uid": <String> (user ID)
    "seq": <Int>,
    "t": <String> (Datatype name: Exactly the same as the name of `DataTypes` enum)
}

ts is the timestamp of the record.

For each datatype, either val or d is populated.

Datatypes:

  • HEART_RATE: val the BPM of each reading
  • STEPS: val the amount of accumulated steps
  • DISTANCE: val the accumulated distance in meters
  • FLOORS_CLIMBED: val the accumulated floors climbed
  • STEPS_CADENCE: val the amount of steps per second taken by the user
  • SPEED: val the speed in meter per second of the user
  • ACCELERATION: d the acceleration data of the device.
    • d[0] -> acceleration in x direction
    • d[1] -> acceleration in y direction
    • d[2] -> acceleration in z direction
  • GYROSCOPE: d the rotation rate of the device.
    • d[0] -> the rotation rate in x axis
    • d[1] -> the rotation rate in y axis
    • d[2] -> the rotation rate in z axis

Installation

You can use Swift Package Manager and add this github repo as a dependency to your project! You must then include this as a framework under
General -> Frameworks, Libraries, and Embedded Content.

You may now run import TerraRTiOS!

You will also need Privacy - Bluetooth Always Usage Description under your info.plist file.
You will also need Privacy - Motion Usage Description under your info.plist file if you wish to use Connections.APPLE connection!

Usage

The package is controlled mainly by a class called TerraRT

You may initialise as such:

let terraRT = TerraRT(devId: String, referenceId: String?, completion: @escaping(Bool) -> Void){

Arguments

  • devId: String -> Your developer ID from terra
  • referenceId: String? -> A user ID associated to your yours
  • completion: (Bool) -> Void -> A completion function that is called when the initialisation is complete

Next, you would need to register your current device to terra as a user. This is done through the following:

terraRT.initConnection(token: String, completion: @escaping (Bool) -> Void 

Arguments

  • token: String -> An authentication token generated from Generate Authentication Token .
  • completion: (Bool) -> Void -> A completion function that is called when the initialisation is complete.

Connecting to devices

For bluetooth devices:

let terraBLEWidget: TerraBLEWidget = terraRT.startBluetoothScan(type: Connections, callback: @escaping (Bool) -> Void)

Arguments

  • type: Connections -> An Enum signifying the connection to make.
  • callback: @escaping (Bool) -> Void -> A callback that will be called with true if the connection is successful and false if the connection is unsuccessful.

This will return a SwiftUI View! You can then display this to your user, and have them scan, and connect to a BLE Device!

In addition, you may also design your own view. The signature of this function is then:

startBluetoothScan(type: Connections, deviceCallback: @escaping (Device) -> Void)

Arguments

  • type: Connections -> An Enum signifying the connection to make.
  • deviceCallback: (Device) -> Void -> A callback that calls with a Device object containing the device's name and identifier. You can use this to display the devices in your view

Afterwards, you can pass a Device object to

 connectDevice(_ device: Device, _ connectionCallback: @escaping(Bool) -> Void)

to connect to the device.

Data Streaming 🔥🔥

Data streaming is done by the function:

terraRT.startRealtime(type: Connections, token: String, dataType: Set<DataTypes>)

Arguments

  • type: Connections -> An Enum signifying the connection to make.
  • token: String -> A user token for authentication to Websocket API. This can be generated here
  • dataType: Set -> An set of Enum signifying the datatypes you wish to stream. Note if the data type is not supported by the type Connections, then it will simply return!

You may stop the streaming as follows:

terraRT.stopRealtime(type: Connections) 

And also disconnect from the connection as follows:

terraRT.disconnect(type: Connections)

WatchOS [New Feature! From TerraRTiOS 0.1.1]

TerraRTiOS Framework supports streaming from Apple Watch as well!

Your iOS app will have to be coupled with the Watch App. This means within your iOS project, you will need to create a target to WatchOS App:

File -> New -> Target -> Watch App for iOS App.

This will generate a new app for Watch OS within the same project.

Within this app, you can add TerraRTiOS as a framework and build the app with it.

Setup

The WatchOS will require HealthKit and Background Modes Capabilities with background delivery and workout processing enabled.

You will also need to add 3 Keys to the Info.plist file with descriptions on how you will use Health Kit's data:

  • Privacy - Health Share Usage Description
  • Privacy - Health Update Usage Description
  • Privacy - Health Records Usage Description

Get Started

This half of the SDK contains functions that can only be imported from WatchOS apps. You can access these by having import TerraRTiOS on top of your file within the WatchOS App.

The Terra class here manages everything. Always Initialise one:

let terra: Terra = try? Terra()

This function can throw: TerraWatchOSErrors.WatchOSConnectioNotSupported, TerraWatchOSErrors.HealthKitNotSupported. Please catch and handle appropriately.

Upon start of the app, you should make sure the watch is connected to the phone. Run

and on the iOS app,

// Where terraRT is the TerraRT(..) class from iOS App
try? terraRT.connectWithWatchOS()

This function always throws an error: TerraError.FeatureNotSupported

When the companion app is installed on the Watch, this call will create a connection with the Watch.

If the watch failed to connect to the device or you wish to connect to a separate watch, on the watch you may also try to activate a session by:

terra.connect()

Streaming

N.B: For WatchOS Streaming, the datatypes being streamed are controlled entirely by the Watch App. On the iOS app, you will simply have to accept data through terraRT.startRealtime(...)

On the Watch App, you can start streaming data straight away to your iOS App from the sensors as:

terra.startStream( forDataTypes dTypes: Set<ReadTypes>, completion: @escaping(Bool) -> Void)

Workouts

The Watch App can stream workout details to your iOS app!

Simply start by

startExercise(forType workoutType: WorkoutTypes, completion: @escaping (Bool) -> Void)

You may also, stop, resume, and pause as such:

stopExercise(completion: @escaping (Bool) -> Void)
resumeExercise()
pauseExercise()