Skip to main content

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.

EndpointsNeed
/v2/capabilities/list, /v2/capabilities/enqueue, /v2/capabilities/queue_state, /v2/capabilities/feedbackThe capability tree
/v2/gps-waypoints, /v2/relative-waypoints, /v2/vehicle-command, /v2/command-queue, /v2/command-history, /v2/polymath-feedbackThe other tree
/v2/motion-commandEither 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.

StatusMeaning
200Every capability was accepted.
422The body is not valid, or the vehicle rejected a capability.
409The vehicle refused the whole request: it is stopped, or another request is still waiting.
503The vehicle is not running the capability behavior tree.
504The 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:

ParameterEffect
statesReturn only records in these states: queued, active or terminal. Repeat it to give several
max_countReturn at most this many finished records. Omit or pass 0 for no limit. Queued and active records are always returned
capability_idReturn 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-location reads the other tree's feedback, so it does not work on the capability tree.
  • The command_ids of 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.