Contactar Ventas
Volver a Guides

Guía de integración de API de robots: Conectar robots a su software

Cómo integrar el hardware del robot con API, servicios web y software empresarial <unk> REST API, WebSocket, puentes ROS2 y conectividad en la nube.

[← Guías]

Una guía de integración de sistemas para ingenieros que conectan hardware de robots con software empresarial que cubre el diseño de API, la comunicación en tiempo real y los patrones de conectividad en la nube.

Opciones de arquitectura de integración

Antes de escribir cualquier código, elija el patrón de integración adecuado para sus necesidades. Las cuatro opciones principales hacen diferentes compromisos entre latencia, acoplamiento y compatibilidad del ecosistema:

Pattern Latencia Coupling Best For
Direct SDK <5ms Tight — language/platform specific Safety-critical control loops, high-frequency motion
REST API 50–200ms Loose — language agnostic Task dispatch, status queries, configuration
WebSocket 5–50ms Medium — long-lived connection required Real-time telemetry, servo commands, streaming
ROS2 bridge 10–100ms Loose — uses ROS2 ecosystem ROS2-compatible software, visualization, multi-robot

La mayoría de las integraciones de producción utilizan una ** combinación**: REST API para la misión de envío y las consultas de estado (donde la latencia es aceptable), WebSocket para la transmisión de telemetría en tiempo real, y el SDK directo sólo para el bucle de control de bajo nivel que se ejecuta en la computadora de bordo del robot. Nunca exponer el SDK directo a través de una red esto evita todas las abstracciones de seguridad.

Diseño de API REST para el control de robots

Un robot bien diseñado REST API trata a los robots como recursos y tareas como objetos de primera clase.

  • POST /tasks Envía una nueva tarea. Cuerpo: T1.
  • GET /tasks/{id} Obtenga el estado de la tarea. devuelve el estado actual (colegada / ejecutada / exitosa / fallida), las métricas de ejecución y los detalles de error si no se logra.
  • GET /robots/{id}/status Obtenga la salud del robot: temperaturas articulares, batería, códigos de error, tarea actual y pose.
  • DELETE /tasks/{id} Cancelar una tarea en cola o en ejecución. Retorna 200 si se cancela con éxito, 409 Conflicto si la tarea está en un estado no cancelables (por ejemplo, inserción media).
  • Authenticación: Utilice ** API key** para integraciones máquina a máquina (simplificada, auditable) o ** OAuth2 cliente flujo de credenciales** para implementaciones de múltiples inquilinos. Pasar la clave en el encabezado T3 en todas las solicitudes.
  • Limitar la tasa: Aplicar un límite de tasa de 100 solicitudes/segundo por clave aplicado en la capa de pasarela de API. Retorna 429 Demasiadas solicitudes con un encabezado T4. La mayoría de las integraciones nunca se acercan a este límite.

Implementación de WebSocket

WebSocket proporciona el canal bidireccional de baja latencia necesario para el control de robots en tiempo real y la transmisión de telemetría. Se recomiendan dos canales separados de WebSocket uno para comandos, uno para telemetría para evitar que la latencia de comandos se vea afectada por el volumen de telemetría.

  • Comando stream (robot ← client): El cliente envía comandos JSON de formato T5\ a 50100 Hz. El controlador a bordo del robot debe reconocer cada comando dentro de 10 ms o entrar en un estado de parada segura. Utilice codificación binaria (MessagePack o CBOR) en lugar de JSON para los flujos de comandos 35× menor carga útil, 3050% menor latencia.
  • Reacción de telemetría (robot → cliente): El robot envía estado conjunto, pose de efecto final, metadatos de cámara y códigos de error a 10 Hz. 10 Hz es suficiente para la monitorización y visualización; las tasas más altas requieren codificación binaria y ancho de banda de red dedicado.
  • Rato cardíaco y reconexión: El cliente debe enviar un marco de ping cada 1 segundo. Si el robot no recibe ping durante 3 segundos, entra en un estado de parada segura. Implemente la lógica de reconexión de retroceso exponencial en el cliente (retreno a 1s, 2s, 4s, 8s) para manejar las interrupciones transitorias de la red.
  • Secuenciación de mensajes: Incluye un número de secuencia que aumenta monótono en cada mensaje. El receptor puede detectar los mensajes caídos y decidir si interpolar o esperar al siguiente mensaje.

Puente de la red ROS2

Para los equipos con infraestructura ROS2 existente, rosbridge_suite expone los temas, servicios y acciones de ROS2 a través de WebSocket con codificación JSON. Esto permite que los paneles de control web y las aplicaciones noROS interactúen con el gráfico ROS2 sin ejecutar ROS2 en sí mismos.

  • rosbridge_server: Instala a través de T6. Ejecuta un servidor WebSocket en el puerto 9090 por defecto. Los clientes se conectan y suscriben/publican a los temas de ROS2 utilizando un simple protocolo JSON.
  • roslibjs: La biblioteca de clientes JavaScript para rosbridge. Permite que los paneles de control web se suscriban a T7, T8 y temas personalizados, y para llamar a los servicios ROS2 desde el navegador.
  • Codificación JSON por encima de la carga: rosbridge utiliza codificación JSON que es 510x mayor que la codificación binaria CDR nativa de ROS2. Para temas de alta frecuencia (> 10 Hz con grandes mensajes), considere un puente binario dedicado o filtro de temas antes de puentear.
  • ** Nota de seguridad:** rosbridge no tiene autenticación por defecto. Siempre ejecuta detrás de la VPN WireGuard descrita en la guía de gestión de flota, nunca expuesta directamente a Internet.

Modelos de integración de las empresas

La conexión de robots a sistemas empresariales (WMS, ERP, MES) requiere patrones que manejen la falta de fiabilidad entre los sistemas empresariales siempre en funcionamiento y los robots ocasionalmente fuera de línea:

  • ** Colas de mensajes para el envío de tareas (Kafka o RabbitMQ):** WMS publica pedidos de selección para un tema de Kafka. El gerente de flota de robots consume del tema y envía tareas a robots disponibles. Si un robot está fuera de línea cuando llega una tarea, la tarea permanece en la cola hasta que un robot esté disponible. Esto desacopla el WMS de la disponibilidad del robot.
  • ** ERP/WMS webhooks para eventos de pedidos:** Configure el WMS para publicar un webhook en su API de plataforma robot cuando los nuevos pedidos estén listos. La plataforma robot procesa el webhook y envía tareas. Implemente la verificación de firma de webhook (HMAC-SHA256) para evitar inyecciones de pedidos falsificados.
  • Database de serie temporal para telemetría (InfluxDB): Almacenar la telemetría de robots en InfluxDB para el análisis a largo plazo y la presentación de informes de cumplimiento.

Implementación de la seguridad

  • TLS 1.3 para toda comunicación de red: Todo el tráfico REST, WebSocket y rosbridge debe utilizar TLS 1.3. Configurar su proxy inverso (Nginx o Caddy) con los encabezados T9 y HSTS. Los robots que se conectan a los servicios en la nube deben validar el certificado del servidor.
  • Certificado de fijación para clientes de robots: El software de robots a bordo debe fijar la huella digital del certificado del servidor esperado y rechazar las conexiones a certificados inesperados. Esto evita ataques de hombre en medio en entornos de red de fábrica/entrepósito donde pueden estar presentes APs deshonestos.
  • VPN para entornos sensibles: Para las implementaciones en entornos de alta seguridad (farmacéutica, defensa, financiera), envía toda la comunicación en la nube del robot a través de un túnel VPN de WireGuard.
  • ** Registro de auditoría:** Registre cada llamada de API con: timestamp, clave de API ID (nunca la clave misma), punto final, estado de respuesta y IP de solicitud. Almacenar los registros de auditoría en una tienda de escritura una vez (AWS CloudTrail o GCP Cloud Audit Logs). Esto es necesario para la complimiento de SOC 2 e investigación de incidentes.

Pruebas y burlas

  • Servidor de robots simulados para el desarrollo: Construir un servidor HTTP/WebSocket simulado que responda a la API completa del robot con datos simulados realistas. Los desarrolladores pueden construir y probar integraciones contra el simulado sin necesidad de acceso físico del robot. El simulado debe reproducir sesiones de robots grabadas para pruebas de integración determinista.
  • ** Pruebas de integración basadas en simulación:** Para las pruebas de extremo a extremo de la pila completa (WMS → plataforma de robots → robot → telemetría → tablero de instrumentos), utilice un robot simulado en Gazebo o Isaac Sim. Estas pruebas se ejecutan en CI en cada solicitud de puesta y regresión de integración de captura que las pruebas de unidad omiten.
  • ** Pruebas de contrato:** Utilice el pacto o un marco de pruebas de contrato similar para verificar que el productor de API del robot (su plataforma de robots) y los consumidores de API (integración WMS, tablero de instrumentos) coinciden en el esquema de API. Esto evita que los cambios quebrantados no se detecten hasta la integración.

Diagrama de arquitectura de integración

Arquitectura típica de extremo a extremo para el despliegue de un almacén de producción:

  • Layer 1 Hardware del robot: brazo del robot + computadora a bordo con ROS2, circuito de control directo de SDK a 500 Hz, vigilancia local de seguridad.
  • Layer 2 Plataforma de robots (en el local o en la nube): API REST para la gestión de tareas, servidor WebSocket para telemetría en tiempo real, plataforma RCSV para el panel de control de la flota y la implementación de políticas.
  • Layer 3 Integración empresarial: Bus de mensajes Kafka que consume eventos de pedidos de WMS y envío a la plataforma robótica; InfluxDB para almacenamiento de telemetría; tablero de control Grafana para equipo de operaciones.
  • Layer 4 Sistemas empresariales: WMS (gestión de almacenes), ERP (inventario, finanzas), MES (sistema de ejecución de fabricación) todos se comunican solo con la capa 3, nunca directamente con robots.

Interfaz ROS2 de OpenArm 1: temas específicos

El OpenArm 1 proporciona un controlador ROS2 nativo con la siguiente estructura de temas. Esto sirve como una implementación de referencia para integrar cualquier brazo a través de los patrones descritos anteriormente.

  • T10 -- sensor_msgs/JointState a 50 Hz. 7 campos: 6 juntas + 1 apertura del agarre. Interfaz de estado: posición, velocidad, esfuerzo.
  • T11 -- trayectoria_msgs/JointTrajectory. El modo de posición se ordena a hasta 50 Hz a través del controlador de trayectoria conjunta de ros2_control.
  • T12 -- geometría_msgs/Clipe Estampado a 100 Hz (cuando el sensor F/T está conectado). Fuerza/torque de 6 ejes en la flange de muñeca.
  • T13 -- std_msgs/Float64. Comando de apertura del pegadizón de 0.0 (cerrado) a 1.0 (aberto completamente).
  • T14 -- diagnóstico_msgs/DiagnosticArray. Temperaturas del motor, códigos de error, versión de firmware. Publicado a 1 Hz.
  • ** Servicio de ROS2:** T15 -- interruptores entre los modos de control de posición, velocidad e impedancia.
  • ** Acción ROS2:** T16 -- acepta una posición de efecto final objetivo y se ejecuta a través de la línea de planificación MoveIt2.

Ejemplo de cliente Python: Integración de API REST

Un cliente Python mínimo que envía una tarea, monitorea la finalización y recupera la telemetría:

import requests, time

API_URL = "https://platform.roboticscenter.ai/api/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# 1. Submit a task
task = requests.post(f"{API_URL}/tasks", json={
    "task_type": "pick_and_place",
    "robot_id": "arm-001",
    "parameters": {
        "pick_pose": [0.3, 0.1, 0.05, 0, 0, 0, 1],
        "place_pose": [0.3, -0.2, 0.05, 0, 0, 0, 1]
    },
    "priority": 1
}, headers=HEADERS).json()

task_id = task["task_id"]
print(f"Task submitted: {task_id}")

# 2. Poll for completion
while True:
    status = requests.get(
        f"{API_URL}/tasks/{task_id}", headers=HEADERS
    ).json()
    if status["status"] in ("succeeded", "failed"):
        break
    time.sleep(1.0)

print(f"Result: {status['status']}")

# 3. Get robot telemetry
health = requests.get(
    f"{API_URL}/robots/arm-001/status", headers=HEADERS
).json()
print(f"Joint temps: {health['joint_temperatures']}")
print(f"Battery: {health['battery_pct']}%")

Tratamiento de errores y estrategia de retrocesión

  • Idempotency: Todas las solicitudes de POST /tasks deben incluir una T17 (UUID) generada por el cliente. El servidor devuelve la tarea existente si se reexpone la misma clave, evitando la creación de tareas duplicadas en los intentos de red.
  • ** Retro con retroceso exponencial:** Para errores de servidor 5xx y tiempos de red, retro en intervalos de 1, 2, 4, 8s con un máximo de 4 retro. Para errores de cliente 4xx, no retro - fija la solicitud.
  • Reconexión de WebSocket: Cuando se desconecte el telemetrio WebSocket, el cliente debe: (1) esperar 1 segundo, (2) intentar reconectar, (3) volver a suscribirse a todos los temas, (4) solicitar los últimos 10 segundos de falta de telemetría a través del punto final de retroalimentación REST T18.
  • ** Patrón de interruptor de circuito:** Si un robot devuelve errores en 5 llamadas consecutivas de API, abra un interruptor de circuito durante 60 segundos. Durante este período, todas las solicitudes a ese robot devuelven un estado de obsolescencia almacenado en caché. Después de 60 segundos, envíe una sola solicitud de verificación de salud. Si tiene éxito, cierre el interruptor y reanude las operaciones normales.

Guías relacionados

Trabajar con el RCSV

La plataforma RCSV proporciona APIs de grado de producción para el control de robots, la gestión de flotas e integración empresarial.

  • Plataforma de datos -- REST y WebSocket API para el despacho de tareas, la telemetría y la gestión de flotas
  • Servicios de recogida de datos -- Recopilación de datos basada en API con la presentación y entrega de tareas programáticas
  • Tienda de hardware -- OpenArm 1 barcos con un controlador ROS2 preconstruido y un paquete de integración de API
  • [Contacta con nosotros] T32) -- solicitar una revisión de la arquitectura de integración para su despliegue

Integrar más rápido con la plataforma RCSV

La plataforma RCSV proporciona API REST y WebSocket preconstruidas, gestión de flotas y conectores de integración empresarial para las implementaciones de robots.

[Explora la plataforma]