Robots Recon

Recon es el robot de seguridad de Rhombus. Las operaciones de robots de la API (en /api/robot/, que aparecen como Robot Webservice en la referencia de la API, en inglés) permiten que tu software vea qué hace cada robot, defina los lugares que visita, ejecute patrullas según un horario o bajo demanda y vea sus cámaras. Un WebSocket en vivo agrega telemetría y conducción en tiempo real.

Cómo encajan las piezas

• Mapa. Durante la configuración, el robot crea un mapa del espacio donde trabaja, y cada robot tiene un mapa asignado. Crear y asignar mapas no forma parte de la API; la API lee el mapa asignado y todo lo que colocas en él.
• Punto de ruta. Una pose con nombre (una posición y un rumbo) en un mapa, que puedes reutilizar en varias rutas.
• Ruta. Una lista ordenada de paradas en un mapa. Cada parada es un punto de ruta o una pose propia, con un tiempo de espera opcional y acciones que se ejecutan cuando llega el robot. Cualquier robot de ese mapa puede ejecutar la ruta.
• Patrulla. Una ruta asignada a un robot, con un horario opcional y sus propias acciones de llegada.
• Actividad. Lo que hace el robot en este momento, como ROUTE_RUN durante una patrulla o NAVIGATE_TO_HOME cuando va hacia la base de carga. Cada comando inicia una actividad, y el robot informa cada uno de sus pasos como un evento.

Convenciones

Los identificadores son los mismos UUID de 22 caracteres en Base64 seguro para URL que en el resto de la API ("AAAAAAAAAAAAAAAAAAAAAA"). Un UUID de 36 caracteres se rechaza con 400.

Las poses son dos arreglos en el sistema de coordenadas del mapa:

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

position es [x, y, z] en metros. orientation es un cuaternión unitario [x, y, z, w]; para un robot que se desplaza sobre el suelo solo importa el rumbo, un ángulo θ en sentido antihorario desde el eje x del mapa, que corresponde a [0, 0, sin(θ/2), cos(θ/2)]. Ambos arreglos deben estar completos: tres números y cuatro números.

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

Los tiempos son milisegundos de época. Los tiempos de espera son la excepción: las solicitudes usan dwellTimeSecs (segundos) y las respuestas devuelven dwellTimeMs.

Las respuestas incluyen error, errorMsg y warningMsg, como en el resto de la API (El sobre de la respuesta). La mayoría de los rechazos, como una ruta sin paradas, son 200 con "error": true, así que revisa error en cada respuesta. Un mapa, una ruta, una patrulla o un punto de ruta que la credencial no puede ver, incluido uno que no existe, se rechaza con 403.

Los ejemplos de estas guías usan una clave de API y esta función auxiliar:

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

Las organizaciones de la UE usan api2.eu.rhombussystems.com (Regiones de API).

Permisos

Las operaciones de robots revisan el rol de la credencial (Permisos) sobre el robot, o sobre la ubicación del mapa, la ruta o el punto de ruta:

Enviar un robot mueve una máquina física. Dale a la integración que envía los robots su propia clave de API, con acceso de administrador solo a las ubicaciones donde trabaja.

Lista tus robots

getMinimalStateList devuelve todos los robots que la credencial puede ver:

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

El uuid de cada robot es el deviceUuid que reciben las demás operaciones de robots. Monitorear robots explica los campos del estado.

Las rutas y las patrullas están en el mapa asignado del robot. Antes de construir sobre un robot, confirma que tiene uno con getMapAssignment; Mapas y puntos de ruta empieza por ahí.