Skip to main content

Managing Sites

A site is a named geographic area that defines where the vehicle operates: a boundary polygon marking the extent of a physical location. You provide a complete site, then stage it for activation to make it the vehicle's operating context at the next restart.

To edit/update a site, you replace the boundary in full.

caution
  • A site must be active at all times to use any autonomy features.
  • Only one site can be active at a time

Staging a site for activation gives you the option to set a default route and zone set, which will be loaded every time the vehicle restarts while the site remains active. This establishes the full navigation context for that location.

This guide walks through creating a site, staging it for activation, reading it back, and managing the sites on a vehicle.

Prerequisites​

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

What makes up a site​

A site needs a name and a boundary while creating it.

Site name​

The site name is the identifier you pass in the URL, and it is how you refer to the site when reading, activating, or deleting it.

A site name is only considered valid if it:

  • Is unique, and not already in use by another site
  • Is not empty
  • Does not start with a number or underscore
  • Contains only letters, numbers, and underscores
  • Is not the reserved keyword: active

All site names are case-insensitive, so "MainSite" and "mainsite" refer to the same site.

Boundary​

The boundary outlines the extent of the site, given as a list of WGS84 points (latitude/longitude).

The boundary is a list of at least 3 points (2-Dimensional). Do NOT repeat the first point as the last point to close the polygon.

Create a site​

Send the complete site with POST, naming the site in the URL. The example below creates a site whose boundary encloses the operating area:

curl --request POST \
  "https://polyglot.polymathrobotics.dev/api/synapse/$POLYMATH_VEHICLE_ID/v2/sites/main_site" \
  --header "Authorization: Bearer $POLYMATH_ACCESS_TOKEN" \
  --header "content-type: application/json" \
  --data '{
    "boundary": [
      {"latitude": 37.828258, "longitude": -122.425726},
      {"latitude": 37.828385, "longitude": -122.420642},
      {"latitude": 37.825124, "longitude": -122.420416},
      {"latitude": 37.825183, "longitude": -122.425443}
    ]
  }'

Stage a site for activation​

Creating a site stores it. It does not take effect until it is activated.

How activation works:

  • The below mentioned endpoint will only stage the site for activation. A staged site does not take effect immediately.
  • The vehicle continues to operate in the previously active site until it is restarted.
  • When the vehicle restarts, the staged site is activated and takes effect.
curl --request POST \
  "https://polyglot.polymathrobotics.dev/api/synapse/$POLYMATH_VEHICLE_ID/v2/sites/main_site/activate" \
  --header "Authorization: Bearer $POLYMATH_ACCESS_TOKEN" \
  --header "content-type: application/json" \
  --data '{}'

Optionally, name a route and/or zone_set to bring up alongside the site when it is activated:

curl --request POST \
  "https://polyglot.polymathrobotics.dev/api/synapse/$POLYMATH_VEHICLE_ID/v2/sites/main_site/activate" \
  --header "Authorization: Bearer $POLYMATH_ACCESS_TOKEN" \
  --header "content-type: application/json" \
  --data '{
    "route": "main_loop",
    "zone_set": "site_zones"
  }'

Both route and zone_set are optional. The named route and zone set must already exist. Activating a site with a route or zone set that is not found returns a 404 error.

Restarting for activation​

To allow the staged site to take effect, autonomy must be restarted. The easiest way to do this is to restart the Polymath Robotics computer by power cycling it.

Alternatively, you can restart the autonomy service manually via the vehicle's Polyglot page, under the Diagnostics > systemd services tab.

Confirm which site is active​

Read back the currently active site to confirm the vehicle is using the one you expect. If no site is currently active, this returns a 404 error.

Remember, this will not return the site that is staged for activation. This is only the site that is currently active/in-effect.

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

If no site is currently active, this returns 404.

Inspect sites​

List all sites on the vehicle by name:

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

Read a previously created site in full by name:

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

Update a site​

Updating a site means replacing it in full. Send the complete, updated site with PUT to the same name:

curl --request PUT \
  "https://polyglot.polymathrobotics.dev/api/synapse/$POLYMATH_VEHICLE_ID/v2/sites/main_site" \
  --header "Authorization: Bearer $POLYMATH_ACCESS_TOKEN" \
  --header "content-type: application/json" \
  --data '{
    "boundary": [
      {"latitude": 37.828258, "longitude": -122.425726},
      {"latitude": 37.828385, "longitude": -122.420642},
      {"latitude": 37.825124, "longitude": -122.420416},
      {"latitude": 37.825183, "longitude": -122.425443}
    ]
  }'

Delete a site​

Remove a site by name:

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

Staged and active sites can NOT be deleted.

caution

The delete operation cannot be reversed. Deleting a site removes all routes and zone sets associated with it.

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 site was rejected as invalid by the vehicle.
  • 404 - the named site does not exist, no site is currently active, or a route or zone set named on activation was not found.
  • 409 - a site 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 site endpoint.