接入概览
1.1 服务地址与接口形态
Orsus 运行在机器人本体上，负责设备状态聚合、导航与建图环境管理、任务队列、资源管理和云端指令执行。外部应用通过本章的北向接口接入；导航算法、扫描、运动控制等下游服务由 Orsus 调用。
| 项目 | 约定 |
|---|---|
| API Origin | http://<机器人IP>:8898；实际以设备的监听配置为准 |
| REST Base URL | http://<机器人IP>:8898/v1/api |
| JSON 编码 | UTF-8；有 JSON 请求体时发送 Content-Type: application/json |
| 认证 | 由启动入口决定；普通 prod 校验 Bearer，dev、标准包接管及制造放行兼容路径可免 token，详见 2.3 |
| 系统 SSE | GET /v1/api/systems/stream |
| 语音 SSE | POST /v1/api/interact/asr，multipart 上传音频 |
| 终端 WebSocket | ws://<机器人IP>:8898/v1/api/terminal/ws，有效终端令牌与启动入口规则见 20.2 |
| MQTT | 连接部署方提供的 Broker；HTTP Bearer 令牌不是 MQTT 口令 |
| 局域网发现 | mDNS _gshub._tcp.local. |
| Swagger | 仅开发模式：http://<机器人IP>:8898/swagger/index.html |
当前仓库配置端口为 8898。旧资料中的 8899 是遗留值，不应直接用于当前设备。 不要把 Agent 的 9090、客户云的 8080 或 Factory 的 8900 当成 Orsus 端侧 API 端口。
1.2 三步验证连接
以下命令只查询状态，演示启用 Bearer 的设备。先将 IP 和令牌替换为部署值；免 token 设备可省略 ORSUS_TOKEN 和全部 Authorization 请求头（运行方式见 2.3）：
export ORSUS_ORIGIN='http://192.168.1.50:8898'
export ORSUS_TOKEN='replace-with-your-device-token'
curl -sS "$ORSUS_ORIGIN/v1/api/systems/device"
curl -sS -H "Authorization: Bearer $ORSUS_TOKEN" "$ORSUS_ORIGIN/v1/api/auth/me"
curl -sS -H "Authorization: Bearer $ORSUS_TOKEN" "$ORSUS_ORIGIN/v1/api/maps"
身份校验成功示例：
{"code":0,"msg":"success","data":{"username":"operator"}}
1.3 按业务选择接口
| 目标 | 推荐入口 | 后续确认 |
|---|---|---|
| 导航到一点、按路线巡航、多步任务 | /nav/startup → /nav/missions | 通过 mission ID 查询，直到终态 |
| 建立新地图 | /mapping/container/start → /mapping/container/stop | /tasks/{id} 确认保存结果，再查 /maps |
| 保存可复用导航内容 | /nav/landmarks、/nav/mission-templates | 保存成功不会执行导航 |
| 修改导航参数 | /nav/set_nav_params 或 /nav/params/set | 检查逐参数结果；启动后检查 apply_status |
| 编辑地图 | 下载 PGM → 上传 PGM | 启用内容同步时携带父版本并检查返回版本 |
| 按时间自动执行 | /schedules | 计划执行记录及关联的本机任务 |
| 设备面板 | /systems/* 或系统 SSE | 进程健康不代表全部算法和硬件就绪 |
| 接收任务事件 | MQTT /task/uplink | 断连恢复后用 REST 补查任务最终状态 |
1.4 身份与版本术语
| 字段 | 含义 |
|---|---|
sn / device_id | 业务设备身份，来自 device.info_path 指向的 device_info.json 的 SN；默认路径 /workspace/.info/device_info.json |
hardware_type / hardware_value | 独立于 SN 的硬件身份；沿用已有 Mender 上报契约；不是密码或 Bearer 令牌 |
device_type | Mender 设备类型，例如 rk、sy，用于选择设备类型配置及匹配软件 |
model | 业务型号；不能替代 device_type 或 SN |
runtime_version | 导航/建图容器运行时版本；与文档版本、Orsus 软件包版本分开 |
scene_name / map_name | 地图名称；不同接口沿用各自字段名 |
map_revision | 导航资源绑定使用的地图修订标识；不要自行与其他 ID 互换 |
release_id | 地图内容版本标识；installed_release_id 只证明磁盘副本已安装 |
mission_id / task_id | Missions 是本机 navigation 任务的视图，二者可对应同一个任务 ID |
升级任务 id | OTA 升级服务的整数任务 ID，不属于 /tasks 本机任务队列 |