# TRON2 自主移动操作/感知拓展套件 SDK 开发指南

> 来源: https://www.limxdynamics.com/zh/documents/910245929834123264
> 发布时间: 2026-11-16
> 更新时间: 2026-11-16
> 标签: TRON 2 EDU版

## 版本记录

| 更新日期 | 修改内容 |
| --- | --- |
| 2026-11-13 最新 | 🚀 初版正式对外 |

> [!WARNING]
> 针对2.5.7版本固件重要说明：
> 1. 如需使用感知/自主移动操作拓展套件相关软件功能，请将主控软件升级为“TRON2 拓展套件 主控软件”，其他固件保持最新即可。
> 2. 另外如需使用自主移动操作拓展套件相关软件功能，在升级主控完成后需要进入管理页面（10.192.1.2:8080），在“机器人控制” 页面，“单臂配置”选项中点击“设为带单臂”。

## 1. SDK 概述

算力模块主要用于开发机器人相关算法及应用程序，对用户完全开放。您可以通过 WiFi连接到机器人本体或有线网络连接交换机登录算力模块，具体步骤如下：

- 使用开发电脑，选择并连接您TRON2机器人的 Wi-Fi 热点，密码为：`12345678`
- 通过 SSH 登录算力模块：在开发电脑终端输入`ssh guest@10.192.1.3`，登录密码为：`123456`

## 2. 移动操作接口

### 2.1 移动操作底层接口

#### 2.1.1 TRON2本体接口

🔗 [查看 TRON2 本体接口文档](https://limx.cn/zh/documents/847884267345285120)

#### 2.1.2 机械臂接口

> [!TIP]
> 以下均为算力模块连接机械臂，并在ubuntu系统中调用接口的使用方式

1. 首先需要安装can模块工具包

   ```bash
   pip3 install python-can    // python-can 版本应高于 3.3.4
   ```

2. 使用 CAN 协议时，需要先激活 CAN 设备并设置正确波特率。

   can接口命名：

   `interface="socketcan"`，`channel="can0"`

   运行前前置条件：

   - 方法一：先激活 CAN（例如：`sudo ip link set can0 up type can bitrate 1000000`）
   - 方法二：也可使用脚本，见 [CAN 模块手册 - 激活单个 CAN 模块](https://github.com/agilexrobotics/pyAgxArm/blob/master/docs/can_user.md#2-%E6%BF%80%E6%B4%BB%E5%8D%95%E4%B8%AA-can-%E6%A8%A1%E5%9D%97)

   > [!TIP]
   > 若出现 `SendCanMessage failed` 错误，请检查 CAN 连接

3. 六轴机械臂sdk接口文档

   🔗 [查看 Piper 机械臂 API 使用文档](https://github.com/agilexrobotics/pyAgxArm/blob/master/docs/piper/piper_api.md#piper-%E6%9C%BA%E6%A2%B0%E8%87%82-api-%E4%BD%BF%E7%94%A8%E6%96%87%E6%A1%A3)

#### 2.1.3 机械臂ros包

🔗 [查看 agx_arm_ros（GitHub）](https://github.com/agilexrobotics/agx_arm_ros)

#### 2.1.4 机械臂示例代码

🔗 [查看机械臂示例代码（pyAgxArm demos）](https://github.com/agilexrobotics/pyAgxArm/tree/master/pyAgxArm/demos)

#### 2.1.5 二指夹爪接口

🔗 [查看二指夹爪 API 使用文档](https://github.com/agilexrobotics/pyAgxArm/blob/master/docs/effector/agx_gripper/agx_gripper_api.md#agxgripper-%E5%A4%B9%E7%88%AA-api-%E4%BD%BF%E7%94%A8%E6%96%87%E6%A1%A3)

#### 2.1.6 强脑二代灵巧手接口

> [!TIP]
> 注意：灵巧手需要特别刷can2.0版本

🔗 [查看强脑二代灵巧手 API 使用文档](https://github.com/agilexrobotics/pyAgxArm/blob/master/docs/effector/revo2/revo2_api.md#revo2-%E7%81%B5%E5%B7%A7%E6%89%8B-api-%E4%BD%BF%E7%94%A8%E6%96%87%E6%A1%A3)

### 2.2 移动操作上层接口（分离运控模式）

#### 2.2.1 设置分离运控模式

**请求：request_yg_set_control_mode**

```json
{
    "accid": "SF_TRON2A_001",
    "title": "request_yg_set_control_mode",
    "guid": "d2c6521699e035949c9276cb17b62bdb",
    "timestamp": 1762771300000,
    "data": {
    "mode": "separated"
    }
}
```

**响应：**

```json
{
    "accid": "SF_TRON2A_001",
    "title": "response_yg_set_control_mode",
    "guid": "d2c6521699e035949c9276cb17b62bdb",
    "timestamp": 1762771300000,
    "data": {
    "result": "success",
    "mode": "separated"
    }
}
```

#### 2.2.2 站起/跪下（仅限轮足形态）

##### 2.2.2.1 跪下

**请求：**

```json
{
    "accid": "WF_TRON2A_127",
    "title": "request_wf_stand_kneel",
    "guid": "d2c6521699e035949c9276cb17b62bdb",
    "timestamp": 1762771300000,
    "data": {
        "action": "kneel"
    }
}
```

**响应：**

```json
{
    "accid": "WF_TRON2A_001",
    "title": "response_wf_stand_kneel",
    "guid": "d2c6521699e035949c9276cb17b62bdb",
    "timestamp": 1762771300000,
    "data": {
        "result": "success"
    }
}
```

##### 2.2.2.2 站起

**请求：**

```json
{
    "accid": "WF_TRON2A_127",
    "title": "request_wf_stand_kneel",
    "guid": "d2c6521699e035949c9276cb17b62bdb",
    "timestamp": 1762771300000,
    "data": {
        "action": "stand"
    }
}
```

**响应：**

```json
{
    "accid": "WF_TRON2A_001",
    "title": "response_wf_stand_kneel",
    "guid": "d2c6521699e035949c9276cb17b62bdb",
    "timestamp": 1762771300000,
    "data": {
        "result": "success"
    }
}
```

#### 2.2.3 机身俯仰调节

> [!WARNING]
> 掌足形态下仅在base处于0.5m高度及更低的状态下可调
> 轮足形态下需要先跪下才可以调节

###### 2.2.3.1.1 指定绝对位置控制

**请求：request_adjust_base_height**

```json
{
  "accid": "SF_TRON2A_001",
  "title": "request_adjust_head_pitch",
  "guid": "d2c6521699e035949c9276cb17b62bdb",
  "timestamp": 1762771300000,
  "data": {
    "pitch": 0.35// pitch范围：[0.0, 0.5]rad
  }
}
```

**响应：**

```json
{
  "accid": "SF_TRON2A_001",
  "title": "response_adjust_head_pitch",
  "guid": "d2c6521699e035949c9276cb17b62bdb",
  "timestamp": 1762771300000,
  "data": {
    "result": "success",
    "pitch": 0.35
  }
}
```

###### 2.2.3.1.2 指定方向控制

**请求：**

```json
{
  "accid": "SF_TRON2A_001",
  "title": "request_adjust_head_pitch",
  "guid": "d2c6521699e035949c9276cb17b62bdb",
  "timestamp": 1762771300000,
  "data": {
    "direction": 1// 1：表示抬头，-1：表示低头
  }
}
```

**响应：**

```json
{
  "accid": "SF_TRON2A_001",
  "title": "response_adjust_head_pitch",
  "guid": "d2c6521699e035949c9276cb17b62bdb",
  "timestamp": 1762771300000,
  "data": {
    "result": "success",
    "direction": 1
  }
}
```

###### 2.2.3.1.3 一键回零

**请求：**

```json
{
  "accid": "SF_TRON2A_001",
  "title": "request_adjust_head_pitch",
  "guid": "d2c6521699e035949c9276cb17b62bdb",
  "timestamp": 1762771300000,
  "data": {
    "reset": true
  }
}
```

**响应:**

```json
{
  "accid": "SF_TRON2A_001",
  "title": "response_adjust_head_pitch",
  "guid": "d2c6521699e035949c9276cb17b62bdb",
  "timestamp": 1762771300000,
  "data": {
    "result": "success",
    "reset": true
  }
}
```

#### 2.2.4 MoveJ接口介绍

**请求：request_yg_movej**

```json
{
    "accid": "SF_TRON2A_001",
    "title": "request_yg_movej",
    "guid": "d2c6521699e035949c9276cb17b62bdb",
    "timestamp": 1762771300000,
    "data": {
    "q": [0.0, 0.5, -0.5, 0.0, 0.0, 0.0],
    "time": 3.0
    }
}
```

**响应：response_yg_movej**

```json
{
    "accid": "SF_TRON2A_001",
    "title": "response_yg_movej",
    "guid": "d2c6521699e035949c9276cb17b62bdb",
    "timestamp": 1762771300000,
    "data": {
    "result": "success",
    "success": true,
    "message": "moveJ accepted: 1500 points, 3s"
    }
}
```

#### 2.2.5 MoveP接口介绍

**请求：request_yg_movep**

```json
{
    "accid": "SF_TRON2A_001",
    "title": "request_yg_movep",
    "guid": "d2c6521699e035949c9276cb17b62bdb",
    "timestamp": 1762771300000,
    "data": {
        "pos": [0.05, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0],
        "speed": 0.1
    }
}
```

**响应：response_yg_movep**

```json
{
    "accid": "SF_TRON2A_001",
    "title": "response_yg_movep",
    "guid": "d2c6521699e035949c9276cb17b62bdb",
    "timestamp": 1762771300000,
    "data": {
        "result": "success",
        "success": true,
        "message": "moveP accepted: 500 points, 1s"
    }
}
```

#### 2.2.6 ServoJ 控制指令

推荐在实时系统中按控制频率 300Hz 要求来控制机械臂运动，以保证控制效果和稳定性。

**请求：request_yg_servoj**

```json
{
  "accid": "SF_TRON2A_001", // 机器人序列号，注意修为您机器人的序列号；
  "title": "request_yg_servoj",
  "timestamp": 1672373633989,
  "guid": "746d937cd8094f6a98c9577aaf213d98",
  "data": { "q": [0.0, 0.5, -0.5, 0.0, 0.0, 0.0] }//填写机械臂六轴位置参数
}
```

**响应：response_yg_servoj**

```json
{
    "accid": "SF_TRON2A_001",
    "title": "response_yg_servoj",
    "guid": "d2c6521699e035949c9276cb17b62bdb",
    "timestamp": 1762771300000,
    "data":{
        "result": "success"
    }
}
```

#### 2.2.7 ServoP控制指令

持续发送末端的pos数据.推荐在实时系统中按控制频率 300Hz 要求来控制机械臂运动，以保证控制效果和稳定性。

**请求：request_yg_servop**

```json
{
    "accid": "SF_TRON2A_001",
    "title": "request_yg_servop",
    "guid": "d2c6521699e035949c9276cb17b62bdb",
    "timestamp": 1762771300000,
    "data": {
        "pos": [0.238598, 0.0, 0.229199, 0.521292, 0.521292, 0.477760, -0.477760]
        //`pos`：7 元 `xyz + 四元数(wxyz)`
        }
}
```

**响应：response_yg_servop**

```json
{
    "accid": "SF_TRON2A_001",
    "title": "response_yg_servop",
    "guid": "d2c6521699e035949c9276cb17b62bdb",
    "timestamp": 1762771300000,
    "data":{
        "result": "success"
    }
}
```

#### 2.2.8 获取机械臂末端位姿

通过此接口获取机械臂末端位姿信息。

**请求：request_get_yg_arm_pose**

```json
{
  "accid": "SF_TRON2A_001", // 机器人序列号，注意修为您机器人的序列号；
  "title": "request_get_yg_arm_pose",
  "timestamp": 1672373633989,
  "guid": "746d937cd8094f6a98c9577aaf213d98",
  "data": {}
}
```

**响应：response_get_move_pose**

接收到请求后，返回双臂当前位姿的相关信息。

```json
{
    "accid": "SF_TRON2A_001",
    "title": "response_get_yg_arm_pose",
    "guid": "d2c6521699e035949c9276cb17b62bdb",
    "timestamp": 1762771300000,
    "data": {
        "result": "success",
        "timestamp": 1762771300000,
        "position": [0.0, 0.0, 0.0],
        "quat": [1.0, 0.0, 0.0, 0.0] //>`quat` 顺序为 `wxyz`，与 servop 一致；
        //尚未收到位姿时 `result=fail_no_data`。

        }
}
```

#### 2.2.9 获取机械臂关节状态

**请求：request_get_yg_arm_state**

此请求用于获取机器人的各个关节状态。

```json
{
  "accid": "SF_TRON2A_001", // 机器人序列号，注意修为您机器人的序列号；
  "title": "request_get_yg_arm_state",
  "timestamp": 1672373633989,
  "guid": "746d937cd8094f6a98c9577aaf213d98",
  "data": {}
}
```

**响应：response_get_yg_arm_state**

接收到请求后，返回机器人各个关节当前状态。

```json
{
  "accid": "SF_TRON2A_001",
  "title": "response_get_yg_arm_state",
  "timestamp": 1672373633989,
  "guid": "746d937cd8094f6a98c9577aaf213d98",
  "data": {
     "result": "success",
     "timestamp": 1762771300000,
     "names": ["joint1", "joint2", "joint3", "joint4", "joint5", "joint6"],
     "q": [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
     "dq": [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
     "tau": [0.0, 0.0, 0.0, 0.0, 0.0, 0.0]
    }
}
```

### 2.3 移动操作上层接口（全身运控模式）

#### 2.3.1 设置全身运控模式

**请求：request_yg_set_control_mode**

```json
{
    "accid": "SF_TRON2A_001",
    "title": "request_yg_set_control_mode",
    "guid": "d2c6521699e035949c9276cb17b62bdb",
    "timestamp": 1762771300000,
    "data": {
    "mode": "wbt"
    }
}
```

**响应：**

```json
{
    "accid": "SF_TRON2A_001",
    "title": "response_yg_set_control_mode",
    "guid": "d2c6521699e035949c9276cb17b62bdb",
    "timestamp": 1762771300000,
    "data": {
    "result": "success",
    "mode": "wbt"
    }
}
```

#### 2.3.2 ServoJ控制指令

推荐在实时系统中按控制频率 300Hz 要求来控制机械臂运动，以保证控制效果和稳定性。

**请求：request_yg_servoj**

```json
{
  "accid": "SF_TRON2A_001", // 机器人序列号，注意修为您机器人的序列号；
  "title": "request_yg_servoj",
  "timestamp": 1672373633989,
  "guid": "746d937cd8094f6a98c9577aaf213d98",
  "data": { "q": [0.0, 0.5, -0.5, 0.0, 0.0, 0.0] }//填写机械臂六轴位置参数
}
```

**响应：response_yg_servoj**

```json
{
    "accid": "SF_TRON2A_001",
    "title": "response_yg_servoj",
    "guid": "d2c6521699e035949c9276cb17b62bdb",
    "timestamp": 1762771300000,
    "data":{
        "result": "success"
    }
}
```

**示例：**

由于servoJ的接口特性需要连续发送指令控制机械臂运动，而postman工具只能发送单个离散动作。所以请参考“YG形态协议接口调用示例”中使用python脚本发布连续动作指令。

#### 2.3.3 ServoP控制指令

持续发送末端的pos数据.推荐在实时系统中按控制频率 300Hz 要求来控制机械臂运动，以保证控制效果和稳定性。

**请求：request_yg_servop**

```json
{
    "accid": "SF_TRON2A_001",
    "title": "request_yg_servop",
    "guid": "d2c6521699e035949c9276cb17b62bdb",
    "timestamp": 1762771300000,
    "data": {
        "pos": [0.238598, 0.0, 0.229199, 0.521292, 0.521292, 0.477760, -0.477760]
        //`pos`：7 元 `xyz + 四元数(wxyz)`
        }
}
```

**响应：response_yg_servop**

```json
{
    "accid": "SF_TRON2A_001",
    "title": "response_yg_servop",
    "guid": "d2c6521699e035949c9276cb17b62bdb",
    "timestamp": 1762771300000,
    "data":{
        "result": "success"
    }
}
```

**示例：**

由于servop的接口特性需要连续发送指令控制机械臂运动，而postman工具只能发送单个离散动作。所以请参考“双臂形态协议接口调用示例”中使用python脚本发布连续动作指令。

#### 2.3.4 获取机械臂末端位姿

通过此接口获取机械臂末端位姿信息。

**请求：request_get_yg_arm_pose**

```json
{
  "accid": "SF_TRON2A_001", // 机器人序列号，注意修为您机器人的序列号；
  "title": "request_get_yg_arm_pose",
  "timestamp": 1672373633989,
  "guid": "746d937cd8094f6a98c9577aaf213d98",
  "data": {}
}
```

**响应：response_get_move_pose**

接收到请求后，返回双臂当前位姿的相关信息。

```json
{
    "accid": "SF_TRON2A_001",
    "title": "response_get_yg_arm_pose",
    "guid": "d2c6521699e035949c9276cb17b62bdb",
    "timestamp": 1762771300000,
    "data": {
        "result": "success",
        "timestamp": 1762771300000,
        "position": [0.0, 0.0, 0.0],
        "quat": [1.0, 0.0, 0.0, 0.0] //>`quat` 顺序为 `wxyz`，与 servop 一致；
        //尚未收到位姿时 `result=fail_no_data`。

        }
}
```

#### 2.3.5 获取机械臂关节状态

**请求：**request_get_yg_arm_state

此请求用于获取机器人的各个关节状态。

```json
{
  "accid": "SF_TRON2A_001", // 机器人序列号，注意修为您机器人的序列号；
  "title": "request_get_yg_arm_state",
  "timestamp": 1672373633989,
  "guid": "746d937cd8094f6a98c9577aaf213d98",
  "data": {}
}
```

**响应：response_get_yg_arm_state**

接收到请求后，返回机器人各个关节当前状态。

```json
{
  "accid": "SF_TRON2A_001",
  "title": "response_get_yg_arm_state",
  "timestamp": 1672373633989,
  "guid": "746d937cd8094f6a98c9577aaf213d98",
  "data": {
     "result": "success",
     "timestamp": 1762771300000,
     "names": ["joint1", "joint2", "joint3", "joint4", "joint5", "joint6"],
     "q": [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
     "dq": [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
     "tau": [0.0, 0.0, 0.0, 0.0, 0.0, 0.0]
    }
}
```

### 2.4 二指夹爪接口

#### 2.4.1 二指夹爪控制

**请求：request_set_yg_claw_cmd**

此协议控制夹爪的抓取动作。

```json
{
    "accid": "SF_TRON2A_001",
    "title": "request_set_yg_claw_cmd",
    "guid": "d2c6521699e035949c9276cb17b62bdb",
    "timestamp": 1762771300000,
    "data": {
    "position": 0.05, //开度
    "max_effort": 10.0 //力矩
    }
}
```

**响应：response_set_yg_claw_cmd**

```json
{
    "accid": "SF_TRON2A_001",
    "title": "response_set_yg_claw_cmd",
    "guid": "d2c6521699e035949c9276cb17b62bdb",
    "timestamp": 1762771300000,
    "data": {
    "result": "success",
    "position": 0.05,
    "max_effort": 10.0
    }
}
```

#### 2.4.2 获取夹爪状态信息

**请求：request_get_limx_2fclaw_state**

```json
{
  "accid": "SF_TRON2A_001",
  "title": "request_get_yg_claw_state",
  "timestamp": 1672373633989,
  "guid": "746d937cd8094f6a98c9577aaf213d98",
  "data": {}
}
```

**响应：response_get_limx_2fclaw_state**

返回夹爪状态信息

```json
{
    "accid": "SF_TRON2A_001",
    "title": "response_get_yg_claw_state",
    "guid": "d2c6521699e035949c9276cb17b62bdb",
    "timestamp": 1762771300000,
    "data": {
    "result": "success",
    "timestamp": 1762771300000,
    "position": 0.05,
    "max_effort": 10.0
    }
}
```

## 3. 感知拓展套件接口

### 3.1 概述

本部分面向 Pad、前端和第三方接入方，描述客户端通过 WebSocket 发送 JSON 字符串时应使用的接口名、请求字段、响应字段、约束和错误处理。

**接口总览**

| 类别 | 序号 | 接口 | 说明 |
| --- | --- | --- | --- |
| 导航系统状态 | 1 | `request_navi_system_status` | 查询导航系统心跳状态--导航系统情形 |
| 建图 | 1 | `request_start_navi_mapping` | 开始建图 |
| 建图 | 2 | `request_get_navi_mapping_init_result` | 建图初始化结果 |
| 建图 | 3 | `request_stop_navi_mapping` | 停止建图 |
| 建图 | 4 | `request_save_navi_map` | 保存建图 |
| 地图管理 | 1 | `request_get_navi_map_list` | 获取地图列表 |
| 地图管理 | 2 | `request_delete_navi_map` | 删除指定地图 |
| 地图管理 | 3 | `request_reset_navi_map` | 重置占用栅格地图 |
| 地图管理 | 4 | `request_rename_navi_map` | 重命名地图 |
| 地图管理 | 5 | `request_active_navi_map` | 激活地图 |
| 地图管理 | 6 | `request_navi_map_info` | 获取地图信息 |
| 地图管理 | 7 | `request_get_navi_mapping_url` | 获取当前建图 URL |
| 定位 | 1 | `request_set_navi_auto_relocation` | 开始定位 |
| 定位 | 2 | `request_stop_navi_localization` | 停止定位 |
| 导航 | 1 | `request_set_navi_goal_waypoint` | 下发导航目标 |
| 导航 | 2 | `request_cancel_navi_goal` | 取消当前导航 |
| 导航 | 3 | `request_get_navi_status` | 查询导航状态 |

**通用 result**

| 值 | 说明 | 客户端建议 |
| --- | --- | --- |
| `success` | 请求成功 | 按接口字段解析响应 |
| `fail_remote` | 后端服务已被调用，但业务执行失败 | 展示或记录 `message`，必要时刷新状态后重试 |
| `fail_service_call` | 后端 mros 服务不可达、超时或调用失败 | 检查机器人端服务状态，稍后重试 |
| `fail_invalid_cmd` | 请求字段缺失、类型错误或取值不合法 | 修正请求 JSON，不建议原样重试 |
| `fail_invalid_accid` | `accid` 不正确 | 检查机器人账号或连接对象 |
| `fail_already_occupied` | 控制权被其他客户端占用 | 按响应中的占用方信息提示用户 |
| `fail_no_status` | 当前没有可查询状态缓存 | 等待状态上报后重试 |
| `fail_invalid_config` | 服务端配置缺失或为空 | 联系机器人端维护人员检查配置 |
| `fail_invalid_map_info` | 地图信息缺失、路径不可解析或路径越界 | 检查 `request_navi_map_info` 返回的数据 |
| `fail_http` | gohfs 上传或下载 HTTP 失败 | 查看 `http_status`、`file_url`、`body`，按需重试 |
| `fail_invalid_map_file` | 下载到的地图文件不是合法 PGM | 检查服务端地图文件内容 |
| `fail_encode` | 服务端 base64 编码失败 | 记录错误并上报 |
| `not_supported` | 接口当前未实现 | 不应作为正式功能调用 |

### 3.2 导航系统状态

查询导航系统心跳状态--导航系统情形(是否存活，当前导航系统状态)。

#### 3.2.1 查询导航系统状态

查询导航节点存活与当前模式

**请求：request_navi_system_status**

```json
{
"accid": "WF_TRON2A_001",
"title": "request_navi_system_status",
"guid": "d2c6521699e035949c9276cb17b62bdb",
 "timestamp": 1762771300000,
 "data": {}
 }
```

**响应：response_navi_system_status**

```json
{
"accid": "WF_TRON2A_001",
"title": "response_navi_system_status",
"guid": "d2c6521699e035949c9276cb17b62bdb",
"timestamp": 1762771300000,
  "data": {
   "result": "success",
   "success": true,
   "message": "Navigation"
   }
}
```

| 响应字段 | 类型 | 说明 |
| --- | --- | --- |
| `result` | string | 服务调用成功时固定为 `success`；服务调用失败时为 `fail_service_call` |
| `success` | boolean | `/navigation/heartbeat` 后端返回的业务成功标志，true=导航模块存活 |
| `message` | string | 后端返回信息，当前状态描述，`"Mapping"` / `"Navigation"` / `"Localization"` / `"idle"`；服务调用失败时为 `Failed to call /navigation/heartbeat` |

### 3.3 建图协议

#### 3.3.1 查询建图初始化结果

查询导航后端的建图初始化结果。

**请求：request_get_navi_mapping_init_result**

```json
{
"accid": "WF_TRON2A_001",
"title": "request_get_navi_mapping_init_result",
 "guid": "d2c6521699e035949c9276cb17b62bdb",
  "timestamp": 1762771300000,
   "data": {}
}
```

**响应：response_get_navi_mapping_init_result**

```json
{
"accid": "WF_TRON2A_001",
"title": "response_get_navi_mapping_init_result",
"guid": "d2c6521699e035949c9276cb17b62bdb",
"timestamp": 1762771300000,
"data": {
 "result": "success",
 "message": "{\"state\":\"success\",\"attempt\":1,\"gyro_delta\":0.002928,\"acc_delta_ratio\":0.005411,\"gyro_norm\":0.012158,\"acc_gravity_ratio\":0.004629,\"imu_stalled\":false,\"stationary\":true,\"static_for_sec\":56.106,\"imu_topic\":\"/rslidar_imu_data\",\"gravity\":9.81,\"odom_max_deviation_m\":0.0073,\"odom_hold_sec\":1.00,\"last_failure\":\"\",\"reason\":\"FAST-LIO initialized and Odometry stable\"}"
  }
 }
```

#### 3.3.2 开始建图

开始建图即表示当前导航进入建图状态，会实时对周围识别到的物理信息进行建图。仅 `IDLE` 态可用，成功后进入 `MAPPING`。

**请求：request_start_navi_mapping**

```json
{
"accid": "WF_TRON2A_001",
"title": "request_start_navi_mapping",
"guid": "d2c6521699e035949c9276cb17b62bdb",
"timestamp": 1762771300000,
"data": {}
}
```

**响应：response_start_navi_mapping**

```json
{ "accid": "WF_TRON2A_001",
"title": "response_start_navi_mapping",
"guid": "d2c6521699e035949c9276cb17b62bdb",
 "timestamp": 1762771300000,
  "data": {
  "result": "success",
   "message": "mapping initialization accepted (already stationary); query /navigation/get_mapping_init_result" }
}
```

| 响应字段 | 类型 | 说明 |
| --- | --- | --- |
| `result` | string | `success` / `fail_remote` / `fail_service_call` |
| `message` | string | 后端返回信息；服务调用成功时为 `mapping initialization accepted (already stationary)` |

#### 3.3.3 停止建图

结束建图过程，此时导航模块不会对当前已经建图的图像进行保存，需要调`request_save_navi_map`接口对刚刚结束的建图过程中生成的图像进行保存。

**请求：request_stop_navi_mapping**

```json
{
"accid": "WF_TRON2A_001",
"title": "request_stop_navi_mapping",
 "guid": "d2c6521699e035949c9276cb17b62bdb",
 "timestamp": 1762771300000,
 "data": {}
}
```

**响应：response_stop_navi_mapping**

```json
{
"accid": "WF_TRON2A_001",
"title": "response_stop_navi_mapping",
 "guid": "d2c6521699e035949c9276cb17b62bdb",
  "timestamp": 1762771300000,
  "data": {
   "result": "success",
   "success": true,
   "message": "mapping stopped"
   }
}
```

#### 3.3.4 保存地图

保存当前建图结果

**请求：request_save_navi_map**

```json
{
"accid": "WF_TRON2A_001",
"title": "request_save_navi_map",
"guid": "d2c6521699e035949c9276cb17b62bdb",
 "timestamp": 1762771300000,
  "data": {
  "map_name": "office_2f"
  }
}
```

| 请求字段 | 类型 | 必填 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| `map_name` | string | 是 | 需要保存的地图名 | 非空且不包含路径分隔符、`..`、`.` 或控制字符 |

**响应：response_save_navi_map**

```json
{ "accid": "WF_TRON2A_001",
 "title": "response_save_navi_map",
 "guid": "d2c6521699e035949c9276cb17b62bdb",
 "timestamp": 1762771300000,
  "data": {
  "result": "success",
   "success": true,
   "message": "/data/maps/office_2f"
    }
}
```

| 响应字段 | 类型 | 说明 |
| --- | --- | --- |
| `result` | string | `success` / `fail_remote` / `fail_service_call` / `fail_invalid_cmd` |
| `message` | string | 后端返回信息；`message` 为保存路径。
缺少 `map_name` 时通常为 `Missing map_name in request data` |

### 3.4 地图管理协议

#### 3.4.1 获取地图列表

获取当前机器人中存在的所有地图名字

**请求：request_get_navi_map_list**

```json
{
"accid": "WF_TRON2A_001",
"title": "request_get_navi_map_list",
 "guid": "d2c6521699e035949c9276cb17b62bdb",
 "timestamp": 1762771300000,
 "data": {}
}
```

**响应：response_get_navi_map_list**

```json
{ "accid": "WF_TRON2A_001",
"title": "response_get_navi_map_list",
"guid": "d2c6521699e035949c9276cb17b62bdb",
"timestamp": 1762771300000,
  "data": {
   "result": "success",
   "message": "2 maps found",
   "map_list": ["office_2f", "lab_1f"]
    }
}
```

| 响应字段 | 类型 | 说明 |
| --- | --- | --- |
| `result` | string | `success` / `fail_remote` / `fail_service_call` |
| `message` | string | 后端返回信息 |
| `map_list` | string[] | 地图名数组，只有服务调用成功时返回 |

#### 3.4.2 删除地图

删除指定地图。建议使用`request_get_navi_map_list`接口中返回的地图列表中的地图名称，否则会失败

**请求：request_delete_navi_map**

```json
{
 "accid": "WF_TRON2A_001",
"title": "request_delete_navi_map",
 "guid": "d2c6521699e035949c9276cb17b62bdb",
 "timestamp": 1762771300000,
  "data": {
  "map_name": "office_2f"
  }
}
```

| 请求字段 | 类型 | 必填 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| `map_name` | string | 是 | 要删除的地图名 | 非空 |

**响应：response_delete_navi_map**

```json
{
"accid": "WF_TRON2A_001",
"title": "response_delete_navi_map",
"guid": "d2c6521699e035949c9276cb17b62bdb",
"timestamp": 1762771300000,
  "data": {
   "result": "success",
   "success": true,
   "message": "map deleted"
   }
}
```

| 响应字段 | 类型 | 说明 |
| --- | --- | --- |
| `result` | string | `success` / `fail_remote` / `fail_service_call` / `fail_invalid_cmd` |
| `message` | string | 后端返回信息或失败原因 |

#### 3.4.3 重置占用栅格地图

**请求：request_reset_navi_map**

```json
{
"accid": "WF_TRON2A_001",
 "title": "request_reset_navi_map",
 "guid": "d2c6521699e035949c9276cb17b62bdb",
  "timestamp": 1762771300000,
  "data": {
   "map_name": "office_2f"
    }
}
```

**响应：response_reset_navi_map**

```json
{ "accid": "WF_TRON2A_001",
 "title": "response_reset_navi_map",
 "guid": "d2c6521699e035949c9276cb17b62bdb",
 "timestamp": 1762771300000,
  "data":  {
   "result": "success",
   "success": true,
   "message": ""
    }
}
```

| 响应字段 | 类型 | 说明 |
| --- | --- | --- |
| `result` | string | `success` / `fail_remote` / `fail_service_call` / `fail_invalid_cmd` |
| `message` | string | 后端返回信息；服务调用失败时为 `Failed to call /navigation/reset_occupiedMap` |

#### 3.4.4 重命名地图

重命名已保存的导航地图。

**请求：request_rename_navi_map**

```json
{
 "accid": "WF_TRON2A_001",
"title": "request_rename_navi_map",
 "guid": "d2c6521699e035949c9276cb17b62bdb",
 "timestamp": 1762771300000,
  "data": {
  "old_map_name": "office_2f",
  "new_map_name": "office_3f"
   }
}
```

| 请求字段 | 类型 | 必填 | 约束 |
| --- | --- | --- | --- |
| `old_map_name` | string | 是 | 必须通过安全校验，不能包含路径分隔符、`..`、`.` 或控制字符 |
| `new_map_name` | string | 是 | 规则同 `old_map_name`，且不能与旧地图名相同 |

**响应：response_rename_navi_map**

```json
{ "accid": "WF_TRON2A_001",
 "title": "response_rename_navi_map",
 "guid": "d2c6521699e035949c9276cb17b62bdb",
 "timestamp": 1762771300000,
  "data": {
  "result": "success",
   "message": "renamed: office_2f -> office_3f " }
}
```

| 响应字段 | 类型 | 说明 |
| --- | --- | --- |
| `result` | string | `success` / `fail_remote` / `fail_service_call` / `fail_invalid_cmd` |
| `message` | string | 后端返回信息或本地参数校验错误 |

#### 3.4.5 激活地图

定位/导航前的前置操作，标记使用哪张地图进行导航和定位。需要使用`request_get_navi_map_list`接口中返回的地图列表中的地图名称，否则会失败。

**请求：request_active_navi_map**

```json
{
"accid": "WF_TRON2A_001",
"title": "request_active_navi_map",
"guid": "d2c6521699e035949c9276cb17b62bdb",
"timestamp": 1762771300000,
     "data": {
    "map_name": "office_2f"
    }
}
```

| 请求字段 | 类型 | 必填 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| `map_name` | string | 是 | 要激活的地图名 | 建议来自 `request_get_navi_map_list` 返回列表 |

**响应：response_active_navi_map**

```json
{ "accid": "WF_TRON2A_001",
"title": "response_active_navi_map",
"guid": "d2c6521699e035949c9276cb17b62bdb",
 "timestamp": 1762771300000,
  "data": {
  "result": "success",
  "success": true,
  "message": "map activated"
  }
}
```

| 响应字段 | 类型 | 说明 |
| --- | --- | --- |
| `result` | string | `success` / `fail_remote` / `fail_service_call` / `fail_invalid_cmd` |
| `message` | string | 后端返回信息或失败原因（例如失败信息"map not found or apply failed: floor_3"） |

#### 3.4.6 获取地图信息

获取已经建好的指定地图信息，将返回JSON 格式的地图元信息（包括地图分辨率、地图尺寸、创建时间、地图所在本地地址等，需客户端自行二次解析）。同时注意，需要使用`request_get_navi_map_list`接口中返回的地图列表中的地图名称，否则会失败。

**请求：request_navi_map_info**

```json
{
  "accid": "WF_TRON2A_999",
  "title": "request_navi_map_info",
  "guid": "d2c6521699e035949c9276cb17b62bdb",
  "timestamp": 1762771300000,
  "data": {
    "map_name": "5F"
  }
}
```

| 请求字段 | 类型 | 必填 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| `map_name` | string | 是 | 地图名 | 需要来自地图列表`request_get_navi_map_list` |

**响应：response_navi_map_info**

```json
{
    "accid": "WF_TRON2A_999",
    "title": "response_navi_map_info",
    "guid": "d2c6521699e035949c9276cb17b62bdb",
    "timestamp": 1718000420000,
    "data": {
        "result": "success",
        "message": "ok",
        "map_info": "{\"name\":\"5F\",\"image\":\"limx.pgm\",\"resolution\":\"0.05\",\"origin\":\"[-47.4996, -59.5261, 0]\",\"bag_size_bytes\":94620824,\"dir\":\"/var/limx/imptdata/fast_lio_sam_sc_qn/5F\",\"pgm_bak\":\"/var/limx/imptdata/fast_lio_sam_sc_qn/5F/limx_bak.pgm\",\"path\":\"/var/limx/imptdata/fast_lio_sam_sc_qn/5F/limx.pgm\"}"
    }
}
```

| 响应字段 | 类型 | 说明 |
| --- | --- | --- |
| `result` | string | `success` / `fail_remote` / `fail_service_call` / `fail_invalid_cmd` |
| `message` | string | 后端返回信息或失败原因 |
| `map_info` | string | 后端返回的地图信息字符串：返回的原始数据是json字段，为了不影响客户端解析json会自动进行转义处理例如使用\<br>name--地图名称<br>image--当前建图完成保存下来的图片<br>resolution--分辨率<br>origin--起始点<br>bag_size_bytes--地图数据包大小<br>dir--该地图在机器人端的存储目录<br>pgm_bak--pgm地图备份文件的完整路径<br>path--当前这份地图信息所指向的PGM文件完整路径 |

#### 3.4.7 获取当前建图 URL

实时查看当前的建图图像 HTTP URL。接口只返回 URL，不通过 WebSocket 传图片内容。

启动建图后，客户端需要实时查看当前导航的建图图像，需要通过此接口获取实时建图的URL，通过该URL来显示实时建图图像，不建议客户端通过该URL显示实时建图图像超过1hz刷新率。

**请求：request_get_navi_mapping_url**

```json
{
  "accid": "SF_TRON2A_001",
  "title": "request_get_navi_mapping_url",
  "guid": "10000000000000000000000000000011",
  "timestamp": 1718000480000,
  "data": {}
}
```

**响应：response_get_navi_mapping_url**

```json
{
  "title": "response_get_navi_mapping_url",
  "guid": "10000000000000000000000000000011",
  "timestamp": 1718000480000,
  "data": {
    "result": "success",
    "map_url": "http://10.192.1.3:8090/mapping.jpeg"
  }
}
```

| 响应字段 | 类型 | 说明 |
| --- | --- | --- |
| `result` | string | `success` / `fail_invalid_config` |
| `map_url` | string | 建图图片 HTTP URL，来自 `api_urls.navi_mapping_url` |

### 3.5 定位协议

#### 3.5.1 开始定位

需已激活地图，成功后进入 `LOCALIZING`。

**请求：request_set_navi_auto_relocation**

```json
{ "accid": "WF_TRON2A_001",
"title": "request_set_navi_auto_relocation",
"guid": "d2c6521699e035949c9276cb17b62bdb",
 "timestamp": 1762771300000,
 "data": {}
}
```

**响应：response_set_navi_auto_relocation**

```json
{ "accid": "WF_TRON2A_001",
 "title": "response_set_navi_auto_relocation",
 "guid": "d2c6521699e035949c9276cb17b62bdb",
 "timestamp": 1762771300000,
  "data": {
  "result": "success",
  "success": true,
  "message": "localization started"
  }
}
```

#### 3.5.2 停止定位

让机器人结束定位和导航。`LOCALIZING` → `IDLE`。

**请求：request_stop_navi_localization**

```json
{
"accid": "WF_TRON2A_001",
"title": "request_stop_navi_localization",
"guid": "d2c6521699e035949c9276cb17b62bdb",
 "timestamp": 1762771300000, "data": {}
}
```

**响应：response_stop_navi_localization**

```json
{ "accid": "WF_TRON2A_001",
"title": "response_stop_navi_localization",
"guid": "d2c6521699e035949c9276cb17b62bdb", "timestamp": 1762771300000,
  "data": {
   "result": "success",
   "success": true,
   "message": "localization stopped"
   }
}
```

#### 3.5.3 设置巡航速度

| 档位 | 最高线速度 (m/s) | 最高角速度(rad/s) |
| --- | --- | --- |
| 低速挡 | 0.35 | 0.60 |
| 中速挡(默认) | 0.65 | 1.00 |
| 高速档 | 0.95 | 1.00 |

**请求：request_set_navi_speed_gear**

```json
{
    "accid": "WF_TRON2A_001",
    "title": "request_set_navi_speed_gear",
    "guid": "d2c6521699e035949c9276cb17b62bdb",
    "timestamp": 1762771300000,
    "data": {
        "gear": "high"
        }
}
```

`gear` 必须是小写 JSON 字符串 `low`、`medium` 或 `high`；缺失、空字符串、类型错误、其它值（含大写或前后空格）均返回 `fail_invalid_cmd`，不发布消息，也不会自动改成中档。

**响应：response_set_navi_speed_gear**

```json
{
    "accid": "WF_TRON2A_001",
    "title": "response_set_navi_speed_gear",
    "guid": "d2c6521699e035949c9276cb17b62bdb",
    "timestamp": 1762771300000,
    "data": {
        "result": "success",
        "gear": "high"
        }
}
```

### 3.6 导航协议

#### 3.6.1 下发导航目标点

`x` / `y` 单位米，`yaw` 单位弧度；三者必须是有限数值

**请求：request_set_navi_goal_waypoint**

```json
{
 "accid": "WF_TRON2A_001",
  "title": "request_set_navi_goal_waypoint",
  "guid": "d2c6521699e035949c9276cb17b62bdb",
  "timestamp": 1762771300000,
  "data": { "x": 1.5, "y": 2.0, "yaw": 1.57 }
  }
```

| 请求字段 | 类型 | 必填 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| `x` | number | 是 | 目标点 x | 单位由导航后端定义，通常为米 |
| `y` | number | 是 | 目标点 y | 单位由导航后端定义，通常为米 |
| `yaw` | number | 是 | 目标朝向 | 通常为弧度 |

**响应：response_set_navi_goal_waypoint**

```json
{
"accid": "WF_TRON2A_001",
 "title": "response_set_navi_goal_waypoint",
  "guid": "d2c6521699e035949c9276cb17b62bdb",
  "timestamp": 1762771300000,
  "data": {
  "result": "success", "success": true, "message": "goal accepted"
  }
}
```

| 响应字段 | 类型 | 说明 |
| --- | --- | --- |
| `result` | string | `success` / `fail_remote` / `fail_service_call` / `fail_invalid_cmd` |
| `message` | string | 字段缺失/类型错误/非有限数值返回 `fail_invalid_cmd`；状态不符返回 `fail_remote` |

#### 3.6.2 取消当前导航

取消当前进行中的目标，子状态转为 `GOAL_CANCEL`。

**请求：request_cancel_navi_goal**

```json
{
"accid": "WF_TRON2A_001",
"title": "request_cancel_navi_goal",
"guid": "d2c6521699e035949c9276cb17b62bdb",
"timestamp": 1762771300000, "data": {}
}
```

**响应：response_cancel_navi_goal**

```json
{
"accid": "WF_TRON2A_001",
 "title": "response_cancel_navi_goal",
  "guid": "d2c6521699e035949c9276cb17b62bdb",
  "timestamp": 1762771300000,
  "data": { "result": "success", "success": true, "message": "goal canceled"
  }
}
```

#### 3.6.3 查询导航子状态

查询当前导航子状态（读本地缓存，缓存来自 `/navigation/goal_status` topic 订阅）。

**请求：request_get_navi_status**

```json
{
"accid": "WF_TRON2A_001",
 "title": "request_get_navi_status",
 "guid": "d2c6521699e035949c9276cb17b62bdb",
 "timestamp": 1762771300000,
 "data": {}
}
```

**响应：response_get_navi_status**

```json
{
"accid": "WF_TRON2A_001",
 "title": "response_get_navi_status",
 "guid": "d2c6521699e035949c9276cb17b62bdb",
 "timestamp": 1762771300000,
  "data": {
  "result": "success",
  "code": 0,
  "navigation_status": "GOAL_RUNNING",
  "status": "GOAL_RUNNING",
  "source": "/navigation/goal_status"
  }
}
```

| 响应字段 | 类型 | 说明 |
| --- | --- | --- |
| `result` | string | `success` / `fail_no_status` |
| `code` | number | 成功时固定返回 `0` |
| `navigation_status` | string | `NO_GOAL`：当前没有导航点任务
`GOAL_RUNNING`：已经下发目标点，任务执行中
`GOAL_REACHED`：目标已到达
`GOAL_FAILED`：目标不可达或执行失败
`GOAL_CANCEL`：目标取消。 |
| `status` | string | 与 `navigation_status` 相同，便于兼容读取 |
| `source` | string | 成功时固定为 `/navigation/goal_status` |
| `message` | string | 无状态缓存时为 `No navigation status has been received` |

### 3.7 服务端主动推送

机器人导航位姿推送，约 1Hz

```json
{
"accid": "WF_TRON2A_001",
"title": "notify_navi_pose",
"guid": "", "timestamp": 0,
  "data": {
  "x": 0.89, "y": 0.01, "yaw": -0.25,
   "frame_id": "map",
  "stamp": 1778311690689
  }
}
```

字段说明：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `data.x` | number | 机器人在地图坐标系下的 x 坐标，单位米 |
| `data.y` | number | 机器人在地图坐标系下的 y 坐标，单位米 |
| `data.yaw` | number | 机器人朝向，单位弧度 |
| `data.frame_id` | string | 位姿所在坐标系，通常为 `map` |
| `data.stamp` | number | 位姿数据时间戳，单位毫秒 |

## 4. 拓展套件URDF

🔗 [查看拓展套件 URDF（tron2-robot-description）](https://github.com/limxdynamics/tron2-robot-description)

## 5. 常见问题解答

| 序号 | 问题描述 | 问题解答 |
| --- | --- | --- |
| 1 | 平时用做建图导航，能富余多少t算力给客户调用做其他任务呢？ | 内存占用一半；cpu占用80%；gpu只在重定位时占满，其余阶段基本空余 |
| 2 | 遥控器和导航指令同时发送指令时，哪个优先级更高，会不会乱掉。 | 遥控器指令优先级最高，不会冲突如果导航过程中触发遥控器指令，导航程序有可能会被中断 |
