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
-
pip install formant, or
pip3 install formant -
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:
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
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].