A tour of the Data SDK

Everything below can be accessed using the data-sdk library of formant toolkit.

The Device object

Most of your use of the Data SDK, especially in a custom view or module, will be centered around the Device object. The full reference for the device object can be found here.

Some highlights:

Telemetry

getLatestTelemetry(): Promise<JSON>

This function will get all of the latest instances of each telemetry data. Note, this call may be performed before it has seen any telemetry information. If you'd like the latest value to persist between each sessions, this option must be enabled in the configuration settings for each stream.

getTelemetryStreams(): Promise<TelemetryStream[]>

This will list all of the streams available.

getTelemetry(streamNameOrStreamNames: string | string[], start: Date, end: Date, tags?: {}): Promise<TelemetryResult[]>

This allows you to get all of the telemetry data for one or multiple streams over a given time frame. Optional tags can be used for filtering the streams.

sendCommand(name: string, data?: string, time?: Date, metadata?: {}): Promise<void>

Manually send a command. You can use getAvailableCommands(): Promise<Command[]> to get a list of them.

enableRealtimeTelemetryPriorityIngestion(streamName: string): Promise<void>

Data uploaded to Formant gets placed on a queue. If you have a particular data stream that you want to jump to the front of the queue, enable it this way. The Priority Ingestion stream can be turned off with disableRealtimeTelemetryPriorityIngestion(streamName: string)

Realtime Data

A lot of realtime functionality is available. See Real-Time Connections with WebRTC for more information.

The App object

The App object will allow you to control app-level behavior and communication. For using the App object to send/receive data between different processes, see Intermodule Communication.

Determining if the running code is in an embedded module

This is useful for enabling certain behaviors if running as a module, or for ensuring that you are so. For an example of this, see this recipe.

import { App } from "@formant/data-sdk";

const isModule: boolean = App.isModule();

Getting the name of the current module

This is also useful for determining if the source of data comes from the same module.

import { App } from "@formant/data-sdk";

const moduleName: string | null = App.getCurrentModuleContext();

Scrolling to a specific time on the timeline

If you want to use your custom module to adjust the timeline, you can do that here. The function App.goToTime() takes a JavaScript Date object:

import { App } from "@formant/data-sdk";

const tenSecondsAgo = new Date();
tenSecondsAgo.setTime(Date.now() - 10 * 1000); // 10 sec * 1000 ms per sec
App.goToTime(tenSecondsAgo);

Requesting data from a certain timeframe

By default, a view will only show the last 15 minutes of data. If you'd like your view's timeline to access data outside of that frame, you can use App.setModuleDateTimeRange(beforeInMilliseconds: number, afterInMilliseconds?: number)

Go to a device

If you have the device ID of another device in your fleet. The device ID can be found in many ways, including the HTTP API, the Python SDK, the Fleet object, or even in the URL while viewing a device (e.g. https://app.formant.io/devices/<device id here>).

When called, the page will go to the default view of that device.

import { App } from "@formant/data-sdk";

App.goToDevice('device ID string');

The Authentication object

This facility allows you to authenticate your code or query your logged in status.

Get logged in status

Below are some examples of seeing if the current program is authenticated and which user and organization they have access to.

import { Authentication, User } from "@formant/data-sdk";

const isLoggedIn: boolean = Authentication.isAuthenticated();

const user: User | undefined = Authentication.getCurrentUser(); 
// or Authenication.currentUser;

const org: string | undefined = Authentication.currentOrganization;

There are three main ways to login:

1. Login with token
2. Login with a username/password
3. Login from a custom view/module embedded within Formant

Login with Token

Service tokens are used to give somebody API access but not login access to the Formant app. To authenticate a service account, use:

import { Authentication } from "@formant/data-sdk";

await succeeded = Authentication.loginWithToken("my-token-goes-here");

Login with username/password

To login a standard Formant application account, use a username and password directly.

❗️

Never store a password unencrypted or otherwise readable by third parties

Consider using an environment variable, form, or other safe technique for retrieving the user's password.

import { Authentication } from "@formant/data-sdk";

await succeeded = Authentication.login("[email protected]", "password");

Login from a custom view or module

If you will be calling the Data SDK from a view or module embedded within Formant, Formant can pass along the authentication information automatically. For more information, see the auth parameter in URL Query Parameters.

import { Authentication, Fleet, App } from "@formant/data-sdk";

// must have the "?auth={auth}" query param set
const succeeded = await Authentication.waitTilAuthenticated();

The Fleet object

The Fleet object provides lookup access to devices and streams. See the full reference documentation of capabilities here.

Getting devices

There are various ways to get devices, as exampled below:

import { Fleet } from "@formant/data-sdk";

// If embedded in a view or module, this will return a Device
const currentDevice = await Fleet.getCurrentDevice();

// Access a specific device with its device ID
const specificDevice = await Fleet.getDevice('device ID string');

// Get all devices
const allDevices = await Fleet.getDevices();

// Get all online devices only
const onlineDevices = await Fleet.getOnlineDevices();

// Get all realtime-enabled devices
const realtimeDevices = await Fleet.getRealtimeDevices();

Reading Events and Telemetry information

Events and Telemetry instances can be accessed directly or queried. See the query-able event parameters here and query-able telemetry parameters here.

import { Fleet } from "@formant/data-sdk";

// Get a specific event
const event = await Fleet.getEvent('event ID here');

// Query Events with IEventQuery:
const events = await Fleet.queryEvents({deviceIds:["device ID"]});

// Get a specific Telemetry datum
const latestTelemetryData = await Fleet.getTelemetry('device ID or device IDs');

// Query telemetry data with IQuery. Requires start and end dates as ISO strings
const telemetryData = await Fleet.queryTelemetry({start: 'IsoDate', end: 'IsoDate'});

Working with Capture Streams

Capture sessions can be initiated through the Formant interface (see Ingest from Capture). But you can also use the Data SDK to create your own completely generic capture sessions.

How to create and ingest to a capture stream:

import { Fleet } from "@formant/data-sdk";

const device = await Fleet.getCurrentDevice();
const captureStream = await device.createCaptureStream("my_stream");

captureStream.ingestJson({key: "value"});

The KeyValue Object

You can use the KeyValue object to store arbitrary strings (up to 10,000 characters) on your organization. This allows you to keep stateful information that can be accessed in other views. Think of it like a database, or if you're familiar with ROS, like ROS Params.

import { KeyValue, App } from "@formant/data-sdk";

const lastRun = await KeyValue.get("last_run");

App.showMessage("Welcome back! We haven't seen you since " + lastRun);

KeyValue.set("last_run", (new Date()).toString());

👋

If you notice an issue with this page or need help, please reach out to us! Use the 'Did this page help you?' buttons below, or get in contact with our Customer Success team via the Intercom messenger in the bottom-right corner of this page, or at [email protected].