OmindOS API

01 / 接入

快速开始

以下首次调用示例适用于机械臂与移动双臂程序。先确认已安装的交付版本。工作台程序必须保持运行，图形界面可以关闭；默认服务地址为 http://127.0.0.1:8085。

POST 请求使用 Content-Type: application/json。两套程序默认都使用 8085 端口；应分别启动，或为机械臂程序指定 --port 8086 并相应修改客户端地址。

curl --fail-with-body http://127.0.0.1:8085/v1/workbench-state

import json
from urllib.request import urlopen

with urlopen("http://127.0.0.1:8085/v1/workbench-state",
             timeout=10) as response:
    state = json.load(response)
print(state)

02 / 导航参数

导航与四足参数

用于注册机器人参数、保存版本和按编号读取。相同参数重复提交返回同一编号；修改参数生成新版本。配置注册不会使能真实电机。

先在工作台导出完整配置 robot-parameters.json；不要为未知的电机标定参数填入估计值。以下 PROFILE_ID 应替换为 POST 返回的完整 profile_id。

curl --fail-with-body \
  -X POST http://127.0.0.1:8085/v1/robot-profiles \
  -H 'Content-Type: application/json' \
  --data-binary @robot-parameters.json

curl --fail-with-body \
  http://127.0.0.1:8085/v1/robot-profiles/PROFILE_ID

成功响应包含 profile_id、robot_id、joint_names 等字段。runtime_applied 和 hardware_validated 为 false，表示配置存储成功，不代表已加载到真实控制器。

03 / 机械臂操作

机械臂与移动双臂

适用 OmindOS Manipulation 0.3.1，提供模型读取、双臂与腰部规划、差速或全向底盘几何导航。随包 RM75 模型的实际 TCP 为 left_tool0 与 right_tool0，请使用该模型返回的 mapping。

04 / 示例

调用示例

读取机械臂工作台状态

以下 Python 示例仅使用标准库，读取状态、模型目录与导航配置，不修改工作台参数。

import json
from urllib.request import urlopen

base_url = "http://127.0.0.1:8085"
for endpoint in ("/v1/workbench-state", "/v1/workbench-models",
                 "/v1/navigation-config"):
    with urlopen(base_url + endpoint, timeout=10) as response:
        print(endpoint, json.load(response))

提交导航与四足参数

先准备从工作台导出的 robot-parameters.json，再运行以下代码。配置保存在当前程序的数据目录。

import json
from pathlib import Path
from urllib.request import Request, urlopen

payload = Path("robot-parameters.json").read_bytes()
request = Request(
    "http://127.0.0.1:8085/v1/robot-profiles",
    data=payload,
    headers={"Content-Type": "application/json"},
    method="POST",
)
with urlopen(request, timeout=10) as response:
    result = json.load(response)
print(result["profile_id"])

提交准备好的规划请求

按上面的规划字段准备 planning-request.json，使用当前模型的 profile 和 mapping。收到 task_id 后继续轮询；HTTP 成功不等于规划完成。

curl --fail-with-body \
  -X POST http://127.0.0.1:8085/v1/planning-start \
  -H 'Content-Type: application/json' \
  --data-binary @planning-request.json

curl --fail-with-body \
  http://127.0.0.1:8085/v1/planning-task/TASK_ID

05 / 任务状态

状态与错误处理

规划任务：running → succeeded / failed / canceled。提交成功只表示任务已创建，必须继续读取任务状态。

导航任务：planning、navigating、aligning、parking；仅导航的成功终态为 parked。带后续操作的任务继续进入 manipulation_planning，成功终态为 succeeded。

停止与复位

发送 {"engaged":true} 到 /v1/workbench-stop 可触发软件停止。复位前重新读取当前 motion_epoch，将该整数放入 expected_epoch，并发送 {"engaged":false,"expected_epoch":当前值}。复位不会自动续跑；软件停止不代替硬件急停。

06 / 兼容性

版本与适用范围

机械臂文档的正式版本范围为本机软件功能。真机驱动、动力学、力控、连续碰撞和载荷碰撞不在本版验收范围内。导航参数 API 不代表四足整机已经完成标定。

接入前请确认程序版本、机器人型号、参数与任务场景。

文档更新：2026-10-11