Recon Robots

Recon is the Rhombus security robot. The robot operations in the API (under /api/robot/, listed as Robot Webservice in the API Reference) 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.

How the pieces fit

• 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:

{ "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.

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). 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 and this helper:

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).

Permissions

Robot operations check the credential's role (Permissions) on the robot, or on the location of the map, route or waypoint:

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 returns every robot the credential can see:

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 explains the state fields.

Routes and patrols live on the robot's assigned map. Check that a robot has one with getMapAssignment before you build on it; Maps and waypoints starts there.