Agent SDK installation and overview

Overview

The Agent SDK is a Python module which runs locally on your device. It wraps the Formant Agent API and provides additional utilities. The SDK allows developers to interact with telemetry, teleop, commands, events, and application configuration.

When to use the Agent SDK

Use the Agent SDK if you are not using ROS and your team uses Python in robot-side applications.

If you are using ROS, many teams still use the Agent SDK to have more control over how their application interacts with Formant. Many integrations use both ROS configuration and the Agent SDK.

If you do not use Python in robot-side applications, it is possible to interact directly with the agent's gRPC or HTTP API.

Agent SDK installation

1. pip install formant, or
   pip3 install formant

2. Make sure Formant Agent is running. To install the Formant agent, refer to Installing the Formant agent.

Using the Agent SDK

This document gives a very broad overview of the capabilities of the Agent SDK, as well as a link to the docs for each capability.

For a complete reference, see Reference.

Instantiating the Formant Agent client

Each of the following requires an instantiated, connected Formant Agent API client. That can be done with the following snippet:

from formant.sdk.agent.v1 import Client as FormantClient
fclient = FormantClient()

If your client find and connects to the Formant Agent, a simple log will print confirming the connection:

INFO: Agent communication established.

Telemetry data ingestion

Use the following methods of the client to ingest data into Formant:

post_image
post_numeric
post_numericset
post_bitset
post_text
post_geolocation
post_battery
post_json

Each method takes a stream name as its first argument, and the data value as its second. For instance, fclient.post_numeric("Distance traveled", 0.23) would post a value of 0.23 to the stream "Distance traveled".

See more: Telemetry data ingestion

Handling commands

Use the register_command_request_callback and send_command_response methods to handle commands sent from the Formant application on your device. Refer to the examples for usage.

See more: Handling commands

Reading application configuration

Use the get_app_config method to retrieve application configuration values. For instance, fclient.get_app_config("Walk mode", None) returns the string value for the application configuration key "Walk mode" if it exists, and None otherwise.

See more: Reading application configuration

Teleop

Sending real-time data from the agent to Formant's teleop interface

Status Indicators

Use post_bitset with stream name "Status". For instance:

fclient.post_bitset("Status", {
    "FLIR online": False,
    "Motors responsive:" True,
    "Walk mode": False,
    "Camera mode": True,
})

The bitset will be streamed to the Formant teleop interface in real-time when a teleop session is active.

Video

Use post_image to stream images. If configured on the Formant app, the image stream will be encoded to a video stream by the Formant agent.

See more: Sending image or video data

Receiving and handling real-time data sent from Formant's teleop interface to the device

Buttons and joystick

Use the register_teleop_callback method. Example:

def handle_teleop_controls(datapoint):
    if datapoint.stream == "Buttons":
        handle_button(datapoint.bitset)
    elif datapoint.stream == "Joystick":
        handle_joystick(datapoint.twist)

fclient.register_teleop_callback(handle_teleop_controls)

Control datapoints will be streamed to the provided callback. Control datapoints with the stream name "Buttons" will contain Bitsets with the button control information. Joystick control datapoints have a user-configured stream name (although "Joystick" is a common choice) and they will contain Twists.

Refer to our public protos for the exact data model of Bitset and Twist:

github.com

formant/datapoint.proto at master · FormantIO/formant

Unregister a callback function with the unregister_teleop_callback method.

Please refer to this doc for more information: Teleop

Creating events

Use the create_event method to create new events with levels of severity. Create an in-app notification with the notify keyword argument.

create_event method parameters:

message : str
notify=False : bool
tags=None : Optional[Dict[str,str]]
timestamp=None : Optional[int]
end_timestamp=None : Optional[int]
severity="info" : Literal["info", "warning", "critical", "error"]

See more: Events