联系销售
返回Guides

机器人API集成指南:将机器人连接到软件堆<unk>

如何将机器人硬件与API,网络服务和企业软件集成 <unk> REST API,WebSocket,ROS2桥梁和云连接.

系统集成指南,用于将机器人硬件连接到企业软件的工程师,涵盖API设计,实时通信和云连接模式.

集成架构选项

在编写任何代码之前,请选择适合您的需求的集成模式.

Pattern 延迟 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

大多数生产集成使用组合:REST API用于任务发送和状态查询 (延迟可接受),WebSocket用于实时远程传输,以及仅用于机器人的机器人载载电脑上运行的低级控制循环的直接SDK.永远不要通过网络暴露直接SDK这绕过所有安全抽象.

机器人控制的REST API设计

一个设计良好的机器人REST API将机器人视为资源和任务,视为一流的对象.以下是覆盖大多数使用情况的最小 API 表面:

  • 提交一个新任务. 身体: T1. 返回: T2.
  • GET /tasks/{id} 获取任务状态. 返回当前状态 (排列/运行/成功/失败),执行指标和失败时的错误详情.
  • GET /robots/{id}/status 获取机器人的健康:关节温度,电池,错误代码,当前任务和姿势.
  • DELETE /tasks/{id} 取消排列或运行任务. 如果成功取消,返回200, 409 冲突如果任务处于不可取消状态 (例如,插入中).
  • 认证:用于机器对机器集成 (简单,可审计) 或OAuth2客户端凭证流**用于多租户部署. 在所有请求中,请在T3标题中传递钥匙.
  • ** 速度限制:** 在API门口层执行 100请求/秒每键速度限制. 返回 429 过多请求,使用T4头.大多数集成都不会接近这个限制.

网络软件的实现

网络Socket提供了用于实时机器人控制和远程传输所需的双向,低延迟频道. 推两个单独的网络Socket频道:一个用于命令,一个用于远程传输,以防止命令延迟受到远程传输量影响.

  • **命令流 (机器人 ←客户端):**客户端在 50100Hz上发送T5\格式JSON命令.机器人的载控器必须在10ms内确认每个命令或进入安全停止状态.使用二进制编码 (MessagePack或CBOR) 而不是JSON来命令流35×小的有效载荷,延迟3050%较低.
  • **电气流 (机器人 →客户端):**机器人在 10 Hz上发送联合状态,终端效应器姿势,摄像头元数据和错误码.
  • **心跳和重连:**客户端必须每1秒发送一个ping框.如果机器人3秒内没有收到ping,它进入安全停止状态.在客户端中实现指数式后退重连接逻辑 (重试1s,2s,4s,8s) 处理过渡网络中断.
  • 消息序列: 每个消息中包含一个单调增长的序列号.接收器可以检测丢弃的消息,并决定是否进行插曲或等待下一个消息.

网络桥 ROS2

对于现有ROS2基础设施的团队, rosbridge_suite可通过JSON编码通过 WebSocket 暴露ROS2主题,服务和操作.这允许网络仪表板和非ROS应用程序与ROS2图表进行交互,而不会运行ROS2本身.

  • rosbridge_server: 通过T6安装.默认运行WebSocket服务器在9090端口上.客户端连接并订阅/发布使用简单的JSON协议.
  • roslibjs: 罗斯布里奇的JavaScript客户端库. 允许网页仪表板订阅T7,T8,以及自定义主题,并从浏览器中调用ROS2服务.
  • JSON编码上层费用: rosbridge使用了510x大于ROS2的本土CDR二进制编码的JSON编码.对于高频主题 (>10Hz带大信息),在桥接之前考虑专用二进制桥梁或过主题.
  • 安全注意: rosbridge默认没有身份验证. 始终在 [舰队管理指南] 描述的WireGuard VPN 后面运行,从未直接接触到互联网.

企业集成模式

连接机器人到企业系统 (WMS,ERP,MES) 需要处理始终开放的企业系统和偶尔离线机器人之间的可靠性不匹配模式:

  • 任务发送的消息队列 (Kafka或RabbitMQ): WMS 发布了对卡夫卡主题的选购订单.机器人舰队经理从主题中消耗并将任务发送给可用的机器人.如果机器人在任务到达时离线,任务将在队列中留下,直到机器人可用.这将 WMS 与机器人可用性分离.
  • ERP/WMS 网络连接器用于订单事件: 配置WMS在新订单准备时将网络连接器到机器人平台API上发布.机器人平台处理网络连接器和发送任务.执行网络连接签名验证 (HMAC-SHA256) 防止伪造订单注射.
  • 时间系列远程测量数据库 (InfluxDB): 存储机器人远程测量数据在InfluxDB中,以便进行长期分析和报告合规性. 使用InfluxDB的数据保留政策,在7天后自动到期100Hz原始数据,同时保留1分钟的总数据为2年.

安全实施

  • **所有网络通信的TLS1.3:**所有REST,WebSocket和rosbridge流量都必须使用TLS1.3. 用T9和HSTS头配置反向代理 (Nginx或Caddy).连接到云服务的机器人必须验证服务器证书.
  • 机器人客户端的证书点机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器人机器
  • **敏感环境的VPN:**对于高安全环境 (制药,国防,金融) 的部署,通过WireGuard VPN道路由所有机器人云通信.机器人的云连接是一个单独的身份证,加密道而不是多个个别安全的连接.
  • **审计记录:**记录每次API调用时刻标签,API密钥ID (永远不会是API密钥本身),终端点,响应状态和请求IP.存储审计记录在一次性存储中 (AWS CloudTrail或GCP云审计记录).这是SOC 2合规性和事件调查所需的.

测试和嘲笑

  • 开发的假机器人服务器: 构建一个假 HTTP/WebSocket服务器,它可以用现实模拟数据响应完整机器人 API.开发人员可以在不需要物理机器人访问的情况下构建和测试对假机器人的集成.假机器人应重播记录的机器人会议进行确定性集成测试.
  • **基于模拟的集成测试:**对于完整堆的端到端测试 (WMS →机器人平台 →机器人 →遥测 →仪表板),使用加西博或艾萨克西姆中的模拟机器人.这些测试在每次拉动请求中都运行在CI中,并捕获了单元测试错过的集成回归.
  • 合同测试: 使用 Pact 或类似的合同测试框架来验证机器人API生产商 (你的机器人平台) 和API消费者 (WMS集成,仪表板) 在API方案上一致. 这可以防止到集成之前,任何变化都不会被发现.

集成架构图

生产仓库部署的典型端到端架构:

  • **层1 机器人硬件:**机器人臂+运行ROS2的机器上电脑,500Hz的 SDK直接控制循环,局部安全监督犬.
  • 层2 机器人平台 (本地或云): REST API用于任务管理,WebSocket服务器用于实时远程测量, RCSV平台用于舰队仪表板和政策部署.
  • **3层 企业集成:**卡夫卡消息公交,消耗WMS订单事件和发送到机器人平台;InfluxDB用于远程测量存储;Grafana仪表板用于操作团队.
  • **4层 企业系统:**WMS (仓库管理),ERP (库存,金融),MES (制造业执行系统) 所有系统只与3层通信,从来没有直接与机器人进行通信.

开放手臂1 ROS2 接口:具体话题

[OpenArm 1]T22) 提供了以下主题结构的本土ROS2驱动程序.这作为通过上述模式整合任何臂的参考实现.

  • T10 --传感器_msgs/JointState在50Hz. 7个场: 6个关节 + 1个抓住器开口.状态界面:位置,速度,努力.
  • T11 --轨迹_msgs/JointTrajectory. 位置模式通过ros2_control 联合轨迹控制器以50Hz为止进行命令.
  • T12 -- 几何_msgs/关键 标记在100Hz (当F/T传感器连接时).
  • T13 -- std_msgs/Float64. 抓紧器开口命令0.0 (关闭) 到1.0 (完全开放).
  • T14 -- 诊断_msgs/诊断阵列. 发动机温度,错误代码,固件版本. 发布于1Hz.
  • ROS2服务: T15 -- 位置,速度和阻力控制模式之间的切换.
  • ROS2行动: T16 -- 接受目标终端效应器姿势并通过MoveIt2规划管道执行.

Python 客户端 例子: REST API 集成

简单的 Python 客户端,可发送任务,监控完成,并检索远程测量:

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']}%")

错误处理和重试策略

  • ** 独立性:** 所有POST/任务请求都应该包含客户端生成的T17 (UUID). 如果重新提交相同的密钥,服务器将返回现有任务,防止网络重复尝试时重复任务创建.
  • ** 复制以指数式后备:** 对于5xx服务器错误和网络时间,再尝试在1s,2s,4s,8s间隔,最大4次复制.对于4xx客户端错误,不要再尝试 - 修复请求.
  • WebSocket连接: 当远程测量WebSocket断开连接时,客户端必须: (1) 等待1秒, (2) 尝试重新连接, (3) 重新订阅所有主题, (4) 通过REST后填点T18请求错过的最后10秒远程测量.
  • ** 电路断路器模式:** 如果机器人在连续5次API调用中返回错误,打开电路断路器60秒. 在此期间,所有请求返回该机器人的缓存状态.60秒后,发送一次健康检查请求.如果成功,关闭断路器并恢复正常运行.

相关指南

  • ROS2和MoveIt2集成 --低级ROS2集成用于手臂控制
  • [远程舰队管理]T24) --舰队规模的API集成和监测
  • [政策部署到生产]T25) -- 部署和监测政策的API模式
  • [仓库部署检查清单]T26) -- WMS和企业集成计划
  • [机器人安全风险评估]T27) -- API终端点的安全要求

与RCSV合作

斯威尔士航空航天委员会 (RCSV) 平台为机器人控制,机队管理和企业集成提供生产级API.

快速与RCSV平台集成

斯威尔斯集团平台为机器人部署提供预建的REST和WebSocketAPI,舰队管理和企业集成连接器.

T33)