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

TRON 2 EDU版2026/11/16

版本记录

更新日期 修改内容
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 本体接口文档

2.1.2 机械臂接口

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

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

    pip3 install python-can    // python-can 版本应高于 3.3.4
    
  2. 使用 CAN 协议时,需要先激活 CAN 设备并设置正确波特率。

    can接口命名:

    interface="socketcan",channel="can0"

    运行前前置条件:

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

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

    🔗 查看 Piper 机械臂 API 使用文档

2.1.3 机械臂ros包

🔗 查看 agx_arm_ros(GitHub)

2.1.4 机械臂示例代码

🔗 查看机械臂示例代码(pyAgxArm demos)

2.1.5 二指夹爪接口

🔗 查看二指夹爪 API 使用文档

2.1.6 强脑二代灵巧手接口

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

🔗 查看强脑二代灵巧手 API 使用文档

2.2 移动操作上层接口(分离运控模式)

2.2.1 设置分离运控模式

请求:request_yg_set_control_mode

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

响应:

{ 
    "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 跪下

请求:

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

响应:

{ 
    "accid": "WF_TRON2A_001", 
    "title": "response_wf_stand_kneel", 
    "guid": "d2c6521699e035949c9276cb17b62bdb", 
    "timestamp": 1762771300000,
    "data": { 
        "result": "success"
    } 
}
2.2.2.2 站起

请求:

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

响应:

{ 
    "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

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

响应:

{
  "accid": "SF_TRON2A_001",
  "title": "response_adjust_head_pitch",
  "guid": "d2c6521699e035949c9276cb17b62bdb",
  "timestamp": 1762771300000,
  "data": {
    "result": "success",
    "pitch": 0.35
  }
}
2.2.3.1.2 指定方向控制

请求:

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

响应:

{
  "accid": "SF_TRON2A_001",
  "title": "response_adjust_head_pitch",
  "guid": "d2c6521699e035949c9276cb17b62bdb",
  "timestamp": 1762771300000,
  "data": {
    "result": "success",
    "direction": 1
  }
}
2.2.3.1.3 一键回零

请求:

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

响应:

{
  "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

{ 
    "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

{ 
    "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

{ 
    "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

{ 
    "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

{
  "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

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

2.2.7 ServoP控制指令

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

请求:request_yg_servop

{ 
    "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

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

2.2.8 获取机械臂末端位姿

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

请求:request_get_yg_arm_pose

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

响应:response_get_move_pose

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

{ 
    "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

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

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

响应:response_get_yg_arm_state

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

{
  "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

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

响应:

{ 
    "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

{
  "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

{ 
    "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

{ 
    "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

{ 
    "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

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

响应:response_get_move_pose

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

{ 
    "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

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

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

响应:response_get_yg_arm_state

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

{
  "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

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

{ 
    "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

{
    "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

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

响应:response_get_limx_2fclaw_state

返回夹爪状态信息

{ 
    "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

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

响应:response_navi_system_status

{ 
"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

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

响应:response_get_navi_mapping_init_result

{ 
"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

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

响应:response_start_navi_mapping

{ "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

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

响应:response_stop_navi_mapping

{ 
"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

{ 
"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

{ "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

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

响应:response_get_navi_map_list

{ "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

{
 "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

{
"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

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

响应:response_reset_navi_map

{ "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

{
 "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

{ "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

{ 
"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

{ "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

{
  "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

{
    "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--地图名称
image--当前建图完成保存下来的图片
resolution--分辨率
origin--起始点
bag_size_bytes--地图数据包大小
dir--该地图在机器人端的存储目录
pgm_bak--pgm地图备份文件的完整路径
path--当前这份地图信息所指向的PGM文件完整路径

3.4.7 获取当前建图 URL

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

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

请求:request_get_navi_mapping_url

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

响应:response_get_navi_mapping_url

{
  "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

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

响应:response_set_navi_auto_relocation

{ "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

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

响应:response_stop_navi_localization

{ "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

{ 
    "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

{ 
    "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

{
 "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

{ 
"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

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

响应:response_cancel_navi_goal

{ 
"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

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

响应:response_get_navi_status

{ 
"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

{ 
"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)

5. 常见问题解答

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