Capabilities
A capability is a named thing the vehicle can do, such as driving to a latitude and longitude. Each capability takes parameters, and the vehicle checks them before it accepts a request. You ask the vehicle what it can do, queue capabilities by name, and follow them to the end.
This guide walks through listing the capabilities, queueing them, reading the queue, and reading the feedback.
Prerequisites
Set POLYMATH_ACCESS_TOKEN and POLYMATH_VEHICLE_ID as shown in Authentication
and First Steps.
The capability endpoints need the vehicle's autonomy to run the capability behavior tree. They answer
503 on a vehicle that runs the other tree. The endpoints of Tracking Commands
do the opposite: they work only on the other tree. Ask Polymath Support which tree your vehicle runs.
| Endpoints | Need |
|---|---|
/v2/capabilities/list, /v2/capabilities/enqueue, /v2/capabilities/queue_state, /v2/capabilities/feedback | The capability tree |
/v2/gps-waypoints, /v2/relative-waypoints, /v2/vehicle-command, /v2/command-queue, /v2/command-history, /v2/polymath-feedback | The other tree |
/v2/motion-command | Either tree |
List the capabilities
GET /v2/capabilities/list returns what this vehicle can do. Read it
instead of assuming names: the list is always right for the vehicle you are talking to.
curl "https://polyglot.polymathrobotics.dev/api/synapse/$POLYMATH_VEHICLE_ID/v2/capabilities/list" \
--header "Authorization: Bearer $POLYMATH_ACCESS_TOKEN"
{
"status": "success",
"message": "Resource fetched successfully",
"data": {
"capabilities": [
{
"name": "navigate_to_lat_lon",
"description": "Drive to a latitude, longitude and yaw.",
"execution": 0,
"execution_text": "PARALLEL",
"params": [
{
"name": "lat",
"type": 2,
"type_text": "DOUBLE",
"required": true,
"min": -90.0,
"max": 90.0,
"enum_values": [],
"units": "deg",
"description": "Latitude of the goal."
}
]
}
]
}
}
Each capability is PARALLEL, which may run alongside others, or SEQUENTIAL, which runs alone and holds
back everything queued behind it. The vehicle commands and the navigation capabilities are PARALLEL, so a
vehicle command does not wait for a move that is queued before it. A SEQUENTIAL capability is rare: the
only one today is scoop_at, which is on Stueve only. Each param has a type (BOOL, INT, DOUBLE, STRING or UINT),
whether it is required, its limits (null when it has none), the values a string accepts (empty accepts
any), and its units. Send a value in the unit it declares: nothing converts it.
Queue capabilities
POST /v2/capabilities/enqueue queues an ordered list of capabilities.
Give each one a name and its params as a JSON object. Write each value as its JSON type: true, 5,
37.5 or "base_link".
curl --request POST \
"https://polyglot.polymathrobotics.dev/api/synapse/$POLYMATH_VEHICLE_ID/v2/capabilities/enqueue" \
--header "Authorization: Bearer $POLYMATH_ACCESS_TOKEN" \
--header "content-type: application/json" \
--data '{
"mode": "ADD",
"capabilities": [
{"name": "navigate_to_lat_lon", "params": {"lat": 40.6342, "lon": -96.1626, "yaw": 1.57}},
{"name": "navigate_relative_to", "params": {"frame": "base_link", "x": 2.0, "y": 0.0, "yaw": 0.0}}
]
}'
The request waits until the vehicle has accepted or rejected every capability. The answer has one result per capability, in the order you sent them, each with the id to follow it by:
{
"status": "success",
"message": "Capabilities queued",
"data": {
"results": [
{"id": "2cd16280-c0ed-414e-b658-c67098b868ae", "accepted": true, "message": ""},
{"id": "7f0b1c1e-4e7e-4d58-a1a4-3d5d0c1f8d62", "accepted": true, "message": ""}
]
}
}
mode is ADD, the default, which adds to the queue, or PREEMPT, which discards what is queued and
running, then queues the request:
curl --request POST \
"https://polyglot.polymathrobotics.dev/api/synapse/$POLYMATH_VEHICLE_ID/v2/capabilities/enqueue" \
--header "Authorization: Bearer $POLYMATH_ACCESS_TOKEN" \
--header "content-type: application/json" \
--data '{
"mode": "PREEMPT",
"capabilities": [
{"name": "navigate_to_lat_lon", "params": {"lat": 40.6351, "lon": -96.1618, "yaw": 0.0}}
]
}'
When the vehicle refuses
The vehicle, not Synapse, checks names, parameters, types and limits, and says why it refuses.
| Status | Meaning |
|---|---|
200 | Every capability was accepted. |
422 | The body is not valid, or the vehicle rejected a capability. |
409 | The vehicle refused the whole request: it is stopped, or another request is still waiting. |
503 | The vehicle is not running the capability behavior tree. |
504 | The vehicle did not answer in time. Whether anything was queued is unknown: read the queue state. |
A 422 has two shapes. A body that is not valid, such as a missing name or a param that is a list, is
answered with detail, which names the field. A capability that the vehicle rejects is answered with
status: error, the vehicle's message, and a result for every capability:
curl --request POST \
"https://polyglot.polymathrobotics.dev/api/synapse/$POLYMATH_VEHICLE_ID/v2/capabilities/enqueue" \
--header "Authorization: Bearer $POLYMATH_ACCESS_TOKEN" \
--header "content-type: application/json" \
--data '{"capabilities": [{"name": "fly_to_the_moon"}]}'
{
"status": "error",
"message": "unknown capability fly_to_the_moon",
"data": {
"results": [
{
"id": "a012d668-31cf-4957-9f5a-b959d13a34fb",
"accepted": false,
"message": "unknown capability fly_to_the_moon"
}
]
}
}
An unknown name rejects the whole request. An invalid param rejects that capability and every capability
after it. The capabilities before the first rejection stay queued, so read the accepted flag of every
result before you retry.
Read the queue state
GET /v2/capabilities/queue_state returns every capability record,
queued, active and finished, newest first:
curl "https://polyglot.polymathrobotics.dev/api/synapse/$POLYMATH_VEHICLE_ID/v2/capabilities/queue_state" \
--header "Authorization: Bearer $POLYMATH_ACCESS_TOKEN"
{
"status": "success",
"message": "Resource fetched successfully",
"data": {
"records": [
{
"id": "2cd16280-c0ed-414e-b658-c67098b868ae",
"summary": "navigate_to_lat_lon lat=40.6342 lon=-96.1626 yaw=1.57",
"state": 1,
"state_text": "ACTIVE",
"outcome": 0,
"outcome_text": "OUTCOME_UNKNOWN",
"detail": "",
"queued_time": {"sec": 1786949841, "nanosec": 893512222},
"started_time": {"sec": 1786949842, "nanosec": 100000000},
"completed_time": {"sec": 0, "nanosec": 0},
"name": "navigate_to_lat_lon",
"params": {"lat": "40.6342", "lon": "-96.1626", "yaw": "1.57"}
}
]
}
}
The states and outcomes are those of Tracking Commands:
QUEUED, ACTIVE and TERMINAL, and a terminal record ends as SUCCEEDED, FAILED, CANCELED,
PREEMPTED or REJECTED, with the reason in detail.
The filters are optional query parameters and combine:
| Parameter | Effect |
|---|---|
states | Return only records in these states: queued, active or terminal. Repeat it to give several |
max_count | Return at most this many finished records. Omit or pass 0 for no limit. Queued and active records are always returned |
capability_id | Return only the record with this id, the one you kept from the enqueue answer |
curl "https://polyglot.polymathrobotics.dev/api/synapse/$POLYMATH_VEHICLE_ID/v2/capabilities/queue_state?states=queued&states=active" \
--header "Authorization: Bearer $POLYMATH_ACCESS_TOKEN"
Read the feedback
GET /v2/capabilities/feedback returns the last feedback the vehicle
published: its status, the ids of the active capabilities, the number waiting, the pose, and the navigation
and vehicle feedback.
curl "https://polyglot.polymathrobotics.dev/api/synapse/$POLYMATH_VEHICLE_ID/v2/capabilities/feedback" \
--header "Authorization: Bearer $POLYMATH_ACCESS_TOKEN"
Poll it. Read timestamp_utc to know how fresh the answer is. The endpoint answers 404 until the first
message has arrived, for example just after the vehicle starts.
Stop, pause and resume
Capabilities have no stop, pause or resume endpoint. Use
POST /v2/motion-command, as for any other command:
curl --request POST \
"https://polyglot.polymathrobotics.dev/api/synapse/$POLYMATH_VEHICLE_ID/v2/motion-command" \
--header "Authorization: Bearer $POLYMATH_ACCESS_TOKEN" \
--header "content-type: application/json" \
--data '{"motion_command": "RESUME"}'
On a vehicle that runs the capability behavior tree, STOP, PAUSE and RESUME all go to Cortex's flow service
and queue nothing, so the answer carries no command_ids.
Limits
POST /v2/reference-targets/current-locationreads the other tree's feedback, so it does not work on the capability tree.- The
command_idsof the endpoints in Tracking Commands and the ids of the capabilities are different ids for different queues: look a capability up in the queue state, not in/v2/command-history.