版本记录
[!WARNING]
针对2.5.7版本固件重要说明:
- 如需使用感知/自主移动操作拓展套件相关软件功能,请将主控软件升级为“TRON2 拓展套件 主控软件”,其他固件保持最新即可。
- 另外如需使用自主移动操作拓展套件相关软件功能,在升级主控完成后需要进入管理页面(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本体接口
2.1.2 机械臂接口
[!TIP]
以下均为算力模块连接机械臂,并在ubuntu系统中调用接口的使用方式
-
首先需要安装can模块工具包
pip3 install python-can // python-can 版本应高于 3.3.4 -
使用 CAN 协议时,需要先激活 CAN 设备并设置正确波特率。
can接口命名:
interface="socketcan",channel="can0"运行前前置条件:
- 方法一:先激活 CAN(例如:
sudo ip link set can0 up type can bitrate 1000000) - 方法二:也可使用脚本,见 CAN 模块手册 - 激活单个 CAN 模块
[!TIP]
若出现SendCanMessage failed错误,请检查 CAN 连接 - 方法一:先激活 CAN(例如:
-
六轴机械臂sdk接口文档
2.1.3 机械臂ros包
2.1.4 机械臂示例代码
2.1.5 二指夹爪接口
2.1.6 强脑二代灵巧手接口
[!TIP]
注意:灵巧手需要特别刷can2.0版本
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 | 遥控器和导航指令同时发送指令时,哪个优先级更高,会不会乱掉。 | 遥控器指令优先级最高,不会冲突如果导航过程中触发遥控器指令,导航程序有可能会被中断 |