The Agent SDK is part of the Formant Python package. The Agent SDK client contains a suite of methods which allow you to ingest telemetry data, receive and respond to commands, teleoperate your device, and more.
When should I use the Agent SDK?
You should use the Agent SDK...
- If you are not using ROS and you are using Python in robot-side applications.
- If you are using ROS, but you want more control over how your application interacts with Formant.
Installation
Prerequisite: Install the Formant agent
To use the Agent SDK, the Formant agent must be installed on your device. For more information, see Install the Formant agent.
The Formant Python package can be installed via pip:
pip install formant
Usage
This section gives a broad overview of the capabilities of the Agent SDK.
The full set of methods, syntax, and return values can be found in the Agent SDK reference.
When you ingest data, a stream will automatically be created in Formant if it does not already exist. To create your streams ahead of time, or to configure existing streams, see Add a non-ROS data stream.
Instantiate the agent client
To use the methods of the Agent SDK, you'll first instantiate the client:
from formant.sdk.agent.v1 import Client as FormantClient
fclient = FormantClient()
The client will try to find and connect to the Formant agent. If this is successful, you'll see the following log:
INFO: Agent communication established.
Ingest telemetry data
The following methods of the client can be used to ingest data into Formant:
| Method |
|---|
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 example, this line:
fclient.post_numeric("Distance traveled", 0.23)
...would post a value of 0.23 to the stream "Distance traveled".
For more information, see Telemetry data ingestion.
Handle 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.
For more information, see Handling commands.
Read application configuration
Use the get_app_config method to retrieve application configuration values. For example, in this line:
walk_mode_value = fclient.get_app_config("Walk mode", None)
...walk_mode_value is set to the string value for the application configuration key "Walk mode" if it exists, and None otherwise.
For more information, see Reading application configuration.
Send real-time data to Formant's teleoperation interface
Status indicators
Use post_bitset with stream name "Status". For example:
fclient.post_bitset("Status", {
"FLIR online": False,
"Motors responsive:" True,
"Walk mode": False,
"Camera mode": True,
})
If a teleoperation session is active on your device, the bitset will be streamed to the Formant teleoperation interface in real-time.
Images and video
Use post_image to stream images. You can configure an image stream to be encoded to a video stream by the Formant agent.
For more information, see Sending image or video data.
Handle real-time data sent from the teleoperation interface
Buttons and joystick
Use the register_teleop_callback method. For 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 ("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.
For more information, see Teleop.
Create events
Use the create_event method to create new events. You can configure the severity and whether the event generates a notification in the Formant web application.
For more information, see Agent SDK: Events and Getting Started: Events and notifications.
See also
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].