Cloud SDK v1 Reference¶

This section outlines the usage for each method of the Formant Cloud SDK v1.

class formant.sdk.cloud.v1.Client(admin_api='https://api.formant.io/v1/admin', ingest_api='https://api.formant.io/v1/ingest', query_api='https://api.formant.io/v1/queries')¶

A client for interacting with the Formant Cloud. There are methods for:

Ingesting telemetry datapoints for device(s)
Query telemetry datapoints
Query stream(s) last known value
Create intervention requests
Create intervention responses

To authenticate the Cloud SDK v1 client, set the following environment variables with valid Formant credentials:

FORMANT_EMAIL
FORMANT_PASSWORD

Return values

All methods of the Cloud SDK v1 client return a Dictionary object which can be parsed for response values.

create_adapter(params)¶

Create an adapter in your organization. Full parameters can be found here: Adapter POST.

from formant.sdk.cloud.v1 import Client

fclient = Client()

params = {
    "execCommand": "./start.sh",
    "path": "/tmp/model.dat"
    "name": "adapters_name"
}

response = fclient.create_adapter(params)

create_command(params)¶

Create a command. Full parameters can be found here: Command template POST.

from formant.sdk.cloud.v1 import Client

fclient = Client()

params = {
    deviceId: "abc-123"
    command: "return_to_charge_station"
    parameter: {
        "scrubberTime": "2014-11-03T19:38:34.203Z",
        "value": "A-2",
        "files": [{
            "id": "def-456",
            "name": "optional_name1"
        }]
    },
}

response = fclient.create_command(params)

create_device(device_name, publicKey='', tags=None, params=None)¶

Creates a new device.

Parameters:: device_name (str) – Device name.

create_intervention_request(params)¶

Create an intervention request. Full parameters can be found here: Intervention request POST.

Parameters:: params – Intervention request parameters.

from formant.sdk.cloud.v1 import Client

fclient = Client()

params = {
    "message": "A teleop for a customer is requested",
    "interventionType": "teleop",
    "time": "2022-02-17T11:41:33.389-08:00",
    "deviceId": "b306de84-33ca-4917-9218-f686730e24e0",
    "tags": {},
    "data": {
        "instruction": "Look at the users item on the table"
    }
}

response = fclient.create_intervention_request(params)

create_intervention_response(params)¶

Creates a response to an intervention request. Full parameters can be found here: Intervention response POST.

Parameters:: params – Intervention response parameters.

from formant.sdk.cloud.v1 import Client

fclient = Client()

params = {
"interventionId": "518e24fc-64ef-47bb-be5e-036a97aeafaa",
"interventionType": "teleop",
"data": {
    "state": "success",
    "notes": "looks good!"
    }
}

response = fclient.create_intervention_response(params)

generate_provisioning_token(id, params=None)¶

Generates a provisioning token for a device.

Parameters:: id (str) – ID of the device to provision.

get_annotation_templates()¶: Gets all annotation templates in this organization.

get_organization()¶: Get this organization ID.

get_organization_id()¶

Gets this organization ID.

Returns:: Organization ID.
Return type:: str

get_user_id()¶

Gets self user ID.

Returns:: ID of this user.
Return type:: str

ingest(params)¶

Ingests data to Formant.

Note

Administrator credentials required.

Note

For a complete syntax reference for the points parameter, see our ingest example.

from formant.sdk.cloud.v1 import Client

fclient = Client()

params = { 
    "items": {[
        "deviceId": "ced176ab-f223-4466-b958-ff8d35261529",
        "name": "engine_temp",
        "type": "numeric",
        "tags": {"location":"sf"},
        "points": [...],
    ]}
}

response = fclient.ingest(params)

patch_device(device_id, params)¶

Update device configuration. Full parameters can be found here: Device PATCH.

Parameters:

device_id (str) – ID of the device to update.
params – Device configuration parameters to update.

from formant.sdk.cloud.v1 import Client

fclient = Client()

device_id = 'abc-123'
params = {
    "desiredConfiguration": 43
}

response = fclient.patch_device(device_id, params)

post_device_configuration(device_id, params)¶

Post a device configuration.

from formant.sdk.cloud.v1 import Client

fclient = Client()

device_id = 'abc-123'
params = {
    "document": {
        adapter: [{
            id: "84f98678-5f18-478d-aed8-631d9ea043a9",
            name: "ROS-diagnostics",
            "execCommand": "./start.sh"
            }],
        tags: {},
        telemetry: {
            streams: []
        }
    }

response = fclient.post_device_configuration(device_id, params)

provision_device(provisioningToken, publicKey, params=None)¶

Provision a device given an ID and a provisioning token.

Parameters:: provisioningToken (str) – Provisioning token from generate_provisioning_token.

query(params)¶

Queries datapoints from the Formant cloud. For more information, see Cloud SDK: Querying telemetry data.

from formant.sdk.cloud.v1 import Client

fclient = Client()

params = {
    start: "2021-01-01T01:00:00.000Z",
    end: "2021-01-01T02:00:00.000Z",
    deviceIds: ["99e8ee37-0a27-4a11-bba2-521facabefa3"],
    names: ["engine_temp"],
    types: ["numeric"],
    tags: {"location":["sf","la"]},
    notNames: ["speed"],
}

response = fclient.query(params)

query_commands(params)¶

Get undelivered commands by device ID.

from formant.sdk.cloud.v1 import Client

fclient = Client()

params = {
deviceId: "abc-123",
}

response = fclient.query_commands(params)

query_devices(params)¶

Query devices in this organization. The full list of query parameters can be found here: Device QUERY.

Parameters:: params (object) – Query parameters.

from formant.sdk.cloud.v1 import Client

fclient = Client()

params = {
    name: "model00.001",
    tags: {"location":["sf", "la"]},
}

response = fclient.query_devices(params)

query_stream_current_value(params)¶

Get current value for streams which match query parameters. Full parameters can be found here: Stream current value QUERY

from formant.sdk.cloud.v1 import Client

fclient = Client()

params = {
    start: "2021-01-01T01:00:00.000Z",
    end: "2021-01-01T02:00:00.000Z",
    deviceIds: ["99e8ee37-0a27-4a11-bba2-521facabefa3"],
    names: ["engine_temp"],
    types: ["numeric"],
    tags: {"location":["sf","la"]},
    notNames: ["speed"],
}

response = fclient.query_stream_current_value(params)

query_task_summaries(params)¶: Get all task summaries

query_task_summary_formats()¶: Get all task summary formants

upload_file(params)¶

Upload a file to the Formant cloud.

from formant.sdk.cloud.v1 import Client

fclient = Client()

params = {
    path: "/tmp/model.dat"
}

response = fclient.upload_file(params)

upload_task_summary(task_summary_format_id, report, device_id, tags=None, message=None)¶

Upload a task summary.

Task summary definition can be found here: Task summary POST.

upload_task_summary_format(task_summary_format)¶

Upload a task summary format.

Task summary format definition can be found here: Task summary format POST.

Cloud SDK v1 Reference¶

Formant SDK Reference

Navigation

Related Topics