跳到主要内容

连接第一台机器人

本教程使用只读请求，确认设备连接和 API 认证。准备一台可通过网络访问的机器人，以及交付方提供的设备地址；启用 Bearer 认证时还需要 API 令牌。

1. 设置设备地址​

默认 API 端口为 8898。将示例地址替换成实际机器人 IP。

export ORSUS_ORIGIN='http://192.168.1.50:8898'

请求发送到机器人地址。当前文档网站用于查阅文档，不是设备 API 网关。

2. 确认连接与设备身份​

curl --fail-with-body --connect-timeout 5 --max-time 15 \
  "$ORSUS_ORIGIN/healthz"

curl --fail-with-body --connect-timeout 5 --max-time 15 \
  "$ORSUS_ORIGIN/v1/api/systems/device"

确认返回的设备身份与目标机器人一致。/healthz 成功只表示服务存活，不能据此判断定位、扫描和运动控制已准备好。

3. 确认认证方式​

先请求当前 API 身份：

curl --connect-timeout 5 --max-time 15 \
  "$ORSUS_ORIGIN/v1/api/auth/me"

如果成功返回 developer，当前入口允许免 token 访问。这也可能是标准包接管的生产启动，不能直接判断为开发模式。

如果返回 HTTP 401，使用交付方提供的 API token：

export ORSUS_TOKEN='replace-with-your-device-token'
curl --fail-with-body --connect-timeout 5 --max-time 15 \
  -H "Authorization: Bearer $ORSUS_TOKEN" \
  "$ORSUS_ORIGIN/v1/api/auth/me"

Linux/SSH 用户名和密码不能替代 API token。完整规则见 通信、认证与错误处理。

4. 查询地图​

在已确认免 token 的设备上：

curl --fail-with-body --max-time 15 "$ORSUS_ORIGIN/v1/api/maps"

启用认证时，为该请求增加 -H "Authorization: Bearer $ORSUS_TOKEN"。

常规 JSON 响应使用以下信封。实际 data 取决于接口：

{"code":0,"msg":"success","data":null}

同时检查 HTTP 状态和 code。code=0 表示本次请求成功，任务提交接口还需要跟踪任务结果。

下一步​