Skip to main content

Managing Routes

A route is a named graph (collection of nodes and edges) that defines where the vehicle is allowed to drive. Nodes are positions and edges are drivable segments between them. You provide a complete route, then load it to make it available for navigation.

Routes are handled as whole artifacts. You always send and receive a complete route graph, identified by its name in the URL. To edit/update a route, you replace it in full.

This guide walks through creating a route, loading it, and reading it back.

Prerequisites​

Set POLYMATH_ACCESS_TOKEN and POLYMATH_VEHICLE_ID as shown in Authentication and First Steps.

What makes up a route​

A route needs a name, at least two nodes, and the edges connecting them.

Route name​

A route name is only considered valid if it:

  • Is unique, and not already in use by another route
  • Is not empty
  • Does not start with a number or underscore
  • Contains only letters, numbers, and underscores

All route names are case-insensitive, so "TestRoute" and "testroute" refer to the same route.

Nodes​

Each node has an id, a coordinate_system, a position and an optional name.

id is an unsigned 16-bit integer unique identifier for the node.

coordinate_system selects how the node's position is interpreted:

  • 0 (WGS84) - a GPS position in wgs84_position as lat/lon. This is the system you will use most often, as Latitude and Longitude for a given location are always fixed.
  • 1 (MAP) - a position in the vehicle's map frame in map_position as x/y. This system uses a reference point that defines the map origin, which may change over time, and is more suitable for indoor environments.

You can optionally provide a name for the node, which is a human-readable string that can be used to identify the node. This name can be then used to request navigation once the route is loaded. Node names follow the same validation rules as route names.

Edges​

Edges connect nodes by their id (from_node_id → to_node_id) and carry a cost used to prefer some segments over others when navigating. They have their own separate id for identification, which is separate from the from_node_id and to_node_id.

If a segment is drivable, but not preferred, you can set the cost to a higher value to discourage the vehicle from using it. Setting all segments to a cost of 0 makes them equally preferred.

Edges are uni-directional. If you add an edge from node A to B, but not from B back to A, the vehicle will only be able to travel from A to B. To allow travel in both directions, you also need to add an edge from B back to A.

If a node is not connected to any other nodes with any edges, the vehicle will not be able to navigate to it's position.

Routes belong to a site​

A site must be created and active before a route can be created.

All route management operations are scoped to the active site only.

If you create a route when site_A is active, the route will only be available for navigation when site_A is active. If you activate site_B (by staging it and then restarting autonomy), the route from site_A will not be available.

This helps you clearly separate the artifacts for each site.

Read more about sites here.

Create a route​

Send the complete route with POST, naming the route in the URL:

curl --request POST \
  "https://polyglot.polymathrobotics.dev/api/synapse/$POLYMATH_VEHICLE_ID/v2/routes/test_route" \
  --header "Authorization: Bearer $POLYMATH_ACCESS_TOKEN" \
  --header "content-type: application/json" \
  --data '{
    "nodes": [
      {"id": 0, "coordinate_system": 0, "wgs84_position": {"lat": 40.6342, "lon": -96.1626}},
      {"id": 1, "coordinate_system": 0, "wgs84_position": {"lat": 40.6345, "lon": -96.1621}}
    ],
    "edges": [
      {"from_node_id": 0, "to_node_id": 1, "id": 0, "cost": 1}
    ]
  }'

Load a route for navigation​

Creating a route stores it. It is not available for navigation until you load it. Loading makes it the vehicle's current route for navigation.

Only one route can be loaded at a time.

curl --request POST \
  "https://polyglot.polymathrobotics.dev/api/synapse/$POLYMATH_VEHICLE_ID/v2/routes/test_route/load" \
  --header "Authorization: Bearer $POLYMATH_ACCESS_TOKEN"

Confirm which route is loaded​

Read back the currently loaded route to confirm the vehicle is using the one you expect:

curl "https://polyglot.polymathrobotics.dev/api/synapse/$POLYMATH_VEHICLE_ID/v2/loaded_route" \
     --header "Authorization: Bearer $POLYMATH_ACCESS_TOKEN"

Inspect routes​

List all routes on the vehicle by name:

curl "https://polyglot.polymathrobotics.dev/api/synapse/$POLYMATH_VEHICLE_ID/v2/routes" \
     --header "Authorization: Bearer $POLYMATH_ACCESS_TOKEN"

Read a previously created route in full by name. This returns the complete graph, the same shape you provided when creating the route:

curl "https://polyglot.polymathrobotics.dev/api/synapse/$POLYMATH_VEHICLE_ID/v2/routes/test_route" \
     --header "Authorization: Bearer $POLYMATH_ACCESS_TOKEN"

Delete a route​

Remove a route by name:

curl --request DELETE \
  "https://polyglot.polymathrobotics.dev/api/synapse/$POLYMATH_VEHICLE_ID/v2/routes/test_route" \
  --header "Authorization: Bearer $POLYMATH_ACCESS_TOKEN"

Handling errors​

Failed requests come back with an HTTP status and a JSON body of the form {"status": "error", "message": "..."}. The status tells you what happened:

  • 400 - the route was rejected as invalid by the vehicle.
  • 404 - the named route does not exist or no route is currently loaded.
  • 409 - a route with that name already exists (on create).
  • 422 - the request body was malformed or failed validation.

Next Steps​

See the API Reference for the full request and response schema of every route endpoint.