> ## Documentation index
> Fetch the complete documentation index at: https://developer.rhombus.com/llms.txt
> Use it to discover all available pages before exploring further.

# Recon Robots

> What you can build with Recon, the Rhombus security robot, through the API: how maps, waypoints, routes and patrols fit together, the conventions every robot operation shares, and the permissions they need.

Recon is the Rhombus security robot. The robot operations in the API (under `/api/robot/`, listed as **Robot Webservice** in the [API Reference](https://developer.rhombus.com/api-reference/overview)) let your software see what each robot is doing, lay out the places it visits, run patrols on a schedule or on demand, and watch its cameras. A live WebSocket adds real-time telemetry and driving.

| Guide                                                                         | What it covers                                                                                             |
| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| [Monitor robots](https://developer.rhombus.com/robots/monitor)                | Battery, connection, current activity and progress for the fleet, and the history of what each robot did   |
| [Maps and waypoints](https://developer.rhombus.com/robots/maps-and-waypoints) | The robot's map image, converting between pixels and map coordinates, keep-out zones, and saved waypoints  |
| [Routes and patrols](https://developer.rhombus.com/robots/routes-and-patrols) | Ordered stops with dwell times and arrival actions, and patrols that run a route on a robot, on a schedule |
| [Dispatch and track](https://developer.rhombus.com/robots/dispatch)           | Sending a robot on a patrol, to a point or back to its charging pad, and following the run to its outcome  |
| [Video and audio](https://developer.rhombus.com/robots/video-and-audio)       | Live and recorded video from each of the robot's cameras, and live audio                                   |
| [Robot live socket](https://developer.rhombus.com/robots/live-socket)         | Driving the robot and reading its telemetry in real time                                                   |

## How the pieces fit

```mermaid
flowchart LR
  M[Map] --> W[Waypoints]
  M --> R[Routes]
  W -. referenced by .-> R
  R --> P[Patrols]
  B[Robot] --> P
  P -- schedule or deploy --> A[Activity]
  A --> E[Events]
```

- **Map.** A robot builds a map of the space it works in during setup, and each robot has one assigned map. Creating and assigning maps aren't part of the API; the API reads the assigned map and everything you place on it.
- **Waypoint.** A named pose (a position and a heading) on a map, reusable across routes.
- **Route.** An ordered list of stops on one map. Each stop is a waypoint or a pose of its own, with an optional dwell time and actions that run when the robot arrives. Any robot on that map can run the route.
- **Patrol.** A route assigned to one robot, with an optional schedule and arrival actions of its own.
- **Activity.** What the robot is doing right now, such as `ROUTE_RUN` for a patrol or `NAVIGATE_TO_HOME` on its way to the charging pad. Every command starts an activity, and the robot reports each step of it as an event.

## Conventions

**Identifiers** are the same 22-character URL-safe Base64 UUIDs as in the rest of the API (`"AAAAAAAAAAAAAAAAAAAAAA"`). A 36-character UUID is rejected with `400`.

**Poses** are two arrays in the map's coordinate frame:

```json
{ "position": [12.4, -3.1, 0.0], "orientation": [0.0, 0.0, 0.7071068, 0.7071068] }
```

`position` is `[x, y, z]` in meters. `orientation` is a unit quaternion `[x, y, z, w]`; for a robot on a floor only the heading matters, an angle θ counterclockwise from the map's x axis, which is `[0, 0, sin(θ/2), cos(θ/2)]`. Both arrays must be complete: three numbers and four numbers.

```python Python
import math

def heading_to_orientation(theta):
    """Quaternion [x, y, z, w] for a heading in radians, counterclockwise from the map's x axis."""
    return [0.0, 0.0, math.sin(theta / 2), math.cos(theta / 2)]

def orientation_to_heading(q):
    """Heading in radians from a quaternion [x, y, z, w]."""
    x, y, z, w = q
    return math.atan2(2 * (w * z + x * y), 1 - 2 * (y * y + z * z))
```

**Times** are epoch milliseconds. Dwell times are the exception: requests take `dwellTimeSecs` (seconds) and responses return `dwellTimeMs`.

**Responses** carry `error`, `errorMsg` and `warningMsg` like the rest of the API ([The response envelope](https://developer.rhombus.com/errors#the-response-envelope)). Most refusals, such as a route with no stops, are `200` with `"error": true`, so check `error` on every response. A map, route, patrol or waypoint that the credential can't see, including one that doesn't exist, is refused with `403`.

The examples in these guides use an [API key](https://developer.rhombus.com/authentication/api-keys) and this helper:

```python Python
import os
import requests

API = "https://api2.rhombussystems.com/api/robot"
HEADERS = {"x-auth-scheme": "api-token", "x-auth-apikey": os.environ["RHOMBUS_API_KEY"]}

def robot_api(operation, body):
    response = requests.post(f"{API}/{operation}", headers=HEADERS, json=body, timeout=30)
    response.raise_for_status()
    data = response.json()
    if data.get("error"):
        raise RuntimeError(f"{operation}: {data.get('errorMsg') or 'refused'}")
    return data
```

Organizations in the EU use `api2.eu.rhombussystems.com` ([API Regions](https://developer.rhombus.com/api-regions)).

## Permissions

Robot operations check the credential's role ([Permissions](https://developer.rhombus.com/authentication/permissions)) on the robot, or on the location of the map, route or waypoint:

| To                                                                                                 | The role needs                                                  |
| -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| Read state, events, maps, waypoints, routes and patrols                                            | Read-only access to the robot or its location                   |
| Watch live video and listen to audio                                                               | Live-only access or more; recorded video needs read-only access |
| Create, change or delete waypoints and routes                                                      | Admin access to the map's location                              |
| Create, change or delete patrols, dispatch the robot, send it home, change its details or settings | Admin access to the robot                                       |
| Remove the robot from the organization                                                             | Admin access and the permission to delete devices               |

Dispatching moves a physical machine. Give the integration that sends robots out its own API key, with admin access only to the locations it works in.

## List your robots

[`getMinimalStateList`](https://developer.rhombus.com/api-reference/robot-webservice/get-minimal-robot-state-list) returns every robot the credential can see:

```python Python
for robot in robot_api("getMinimalStateList", {})["minimalStates"]:
    print(robot["name"], robot["uuid"], robot["connectionStatus"], robot.get("batteryPercent"), robot.get("activity"))
```

Each robot's `uuid` is the `deviceUuid` that the other robot operations take. [Monitor robots](https://developer.rhombus.com/robots/monitor) explains the state fields.

Routes and patrols live on the robot's assigned map. Check that a robot has one with [`getMapAssignment`](https://developer.rhombus.com/api-reference/robot-webservice/retrieve-the-robots-map-assignment-record) before you build on it; [Maps and waypoints](https://developer.rhombus.com/robots/maps-and-waypoints) starts there.