TRON2 Autonomous Mobile Operation / Perception Expansion Kit SDK Guide

TRON 2 EDU Ed.November 16, 2026

Version History

Updated Changes
2026-11-13
Latest
Initial public release

[!WARNING]
Important Notes for Firmware Version 2.5.7:

  1. To use software functions related to the Perception/Autonomous Mobile Manipulation Expansion Kit, please upgrade the main controller software to "TRON2 Expansion Kit Main Controller Software." Other firmware only needs to be kept up to date.
  2. In addition, to use software functions related to the Autonomous Mobile Manipulation Expansion Kit, after upgrading the main controller, go to the management page (10.192.1.2:8080). On the "Robot Control" page, under the "Single-Arm Configuration" option, click "Set as Single-Arm."

1. SDK Overview

The computing power module is mainly used for developing robot-related algorithms and application programs, and is fully open to users. You can log in to the computing power module by connecting to the robot body via WiFi or connecting to a switch via a wired network. The specific steps are as follows:

  • Using your development computer, select and connect to the Wi-Fi hotspot of your TRON2 robot, with the password: 12345678
  • Log in to the computing module via SSH: Enter the following command in the terminal of your development computer ssh guest@10.192.1.3, and the login password is: 123456

2. Moving operation interface

2.1 Low-level interface for move operations

2.1.1 TRON2 Main Unit Interface

TRON2 Main Unit Interface Documentation

2.1.2 Manipulator Arm Interface

[!TIP]
The following describes how to connect the computing power module to the robotic arm and call the interface on the Ubuntu system.

  1. First, you need to install the can module toolkit.

    pip3 install python-can    // The python-can version should be higher than 3.3.4.
    
  2. When using the CAN protocol, you need to first activate the CAN device and set the correct baud rate.

    CAN interface naming:

    interface="socketcan",channel="can0"

    Precondition before running:

    [!TIP]
    If a SendCanMessage failed error occurs, please check the CAN connection

  3. Six-axis Robotic Arm SDK Interface Documentation

    Piper API Documentation

2.1.3 ROS package for robotic arm

Robotic Arm ROS 2 Package (English README)

2.1.4 Sample Code for Robotic Arm

Robotic Arm Sample Code (pyAgxArm demos)

2.1.5 Two-finger gripper interface

AgxGripper API Documentation

2.1.6 Neuracle Gen 2 Dexterous Hand Interface

[!TIP]
Note: The dexterous hand requires a specific flashing of the CAN 2.0 version

Revo2 API Documentation

2.2 High-level Interface for Mobile Manipulation (Separated Motion Control Mode)

2.2.1 Set Separated Motion Control Mode

Request:request_yg_set_control_mode

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

Response:

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

2.2.2 Stand Up / Kneel Down (Wheeled-Legs Configuration Only)

2.2.2.1 Kneel Down

Request:

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

Response:

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

Request:

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

Response:

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

2.2.3 Fuselage Pitch Adjustment

[!WARNING]
In palm-foot configuration, adjustment is only possible when the base is at a height of 0.5 m or lower.

In wheeled-legs configuration, the robot must kneel down first before adjustment.

2.2.3.1.1 Specify absolute position control

Request:request_adjust_base_height

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

Response:

{
  "accid": "SF_TRON2A_001",
  "title": "response_adjust_head_pitch",
  "guid": "d2c6521699e035949c9276cb17b62bdb",
  "timestamp": 1762771300000,
  "data": {
    "result": "success",
    "pitch": 0.35
  }
}
2.2.3.1.2 Specified Direction Control

Request:

{
  "accid": "SF_TRON2A_001",
  "title": "request_adjust_head_pitch",
  "guid": "d2c6521699e035949c9276cb17b62bdb",
  "timestamp": 1762771300000,
  "data": {
    "direction": 1// 1: Pitch up (head up); -1: Pitch down (head down).
  }
}

Response:

{
  "accid": "SF_TRON2A_001",
  "title": "response_adjust_head_pitch",
  "guid": "d2c6521699e035949c9276cb17b62bdb",
  "timestamp": 1762771300000,
  "data": {
    "result": "success",
    "direction": 1
  }
}
2.2.3.1.3 One-click Zero Reset

Request:

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

Response:

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

2.2.4 MoveJ Control Command

Request: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: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 Control Command

Request: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: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 Control Command

It is recommended to control the movement of the robotic arm in real-time systems in accordance with the control frequency requirement of 300 Hz, so as to ensure the control effect and stability.

Request: request_yg_servoj

{
  "accid": "SF_TRON2A_001", // Robot Serial Number: replace it with your robot's actual serial number.
  "title": "request_yg_servoj",
  "timestamp": 1672373633989,
  "guid": "746d937cd8094f6a98c9577aaf213d98",
  "data": { "q": [0.0, 0.5, -0.5, 0.0, 0.0, 0.0] } //Enter the six-axis position parameters of the robot arm.
}

Response: response_yg_servoj

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

2.2.7 ServoP Control Command

Continuously send the end-effector pos data. It is recommended to control the motion of the robotic arm in the real-time system in accordance with the control frequency requirement of 300 Hz to ensure the control effect and stability.

Request: 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-element    xyz + quaternion (wxyz)
        } 
}

Response: response_yg_servop

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

2.2.8 Obtain the pose of the robotic arm end-effector

Obtain the pose information of the robotic arm end effector through this interface.

Request:request_get_yg_arm_pose

{
  "accid": "SF_TRON2A_001", // Robot Serial Number: replace it with your robot's actual serial number.
  "title": "request_get_yg_arm_pose",
  "timestamp": 1672373633989,
  "guid": "746d937cd8094f6a98c9577aaf213d98",
  "data": {}
}

Response:response_get_move_pose

After receiving the request, return the relevant information of the current pose of the dual-arm.

{ 
    "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] //The quat order is wxyz, consistent with servop;
        //When the pose has not yet been received, result=fail_no_data.
        } 
}

2.2.9 Obtain the status of the robotic arm joints

Request:request_get_yg_arm_state

This request is used to obtain the status of each joint of the robot.

{
  "accid": "SF_TRON2A_001", // Robot Serial Number: replace it with your robot's actual serial number.
  "title": "request_get_yg_arm_state",
  "timestamp": 1672373633989,
  "guid": "746d937cd8094f6a98c9577aaf213d98",
  "data": {}
}

Response:response_get_yg_arm_state

Upon receiving the request, return the current status of each joint of the robot.

{
  "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 High-level Interface for Mobile Manipulation (Whole-Body Control Mode)

2.3.1 Set Whole-Body Control Mode

Request:request_yg_set_control_mode

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

Response:

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

2.3.2 ServoJ Control Command

It is recommended to control the robot arm motion at a control frequency of 300 Hz in a real-time system to ensure control performance and stability.

Request:request_yg_servoj

{
  "accid": "SF_TRON2A_001", // Robot Serial Number: replace it with your robot's actual serial number.
  "title": "request_yg_servoj",
  "timestamp": 1672373633989,
  "guid": "746d937cd8094f6a98c9577aaf213d98",
  "data": { "q": [0.0, 0.5, -0.5, 0.0, 0.0, 0.0] }//Enter the six-axis position parameters of the robot arm.
}

Response:response_yg_servoj

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

2.3.3 ServoP Control Command

It is recommended to control the robot arm motion at a control frequency of 300 Hz in a real-time system to ensure control performance and stability.

Request: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-element `xyz + quaternion (wxyz)`
        } 
}

Response:response_yg_servop

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

2.3.4 Obtain the pose of the robotic arm end-effector

This interface is used to obtain the end-effector pose of the robot arm.

Request:request_get_yg_arm_pose

{
  "accid": "SF_TRON2A_001", // Robot Serial Number: replace it with your robot's actual serial number.
  "title": "request_get_yg_arm_pose",
  "timestamp": 1672373633989,
  "guid": "746d937cd8094f6a98c9577aaf213d98",
  "data": {}
}

Response:response_get_move_pose

After receiving the request, it returns information on the current poses of both arms.

{ 
    "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` order is `wxyz`, consistent with servop;
        //When the pose has not yet been received, `result=fail_no_data`.

        } 
}

2.3.5 Obtain the status of the robotic arm joints

Request:request_get_yg_arm_state

This request is used to obtain the status of each joint of the robot.

{
  "accid": "SF_TRON2A_001", // Robot Serial Number: replace it with your robot's actual serial number.
  "title": "request_get_yg_arm_state",
  "timestamp": 1672373633989,
  "guid": "746d937cd8094f6a98c9577aaf213d98",
  "data": {}
}

Response:response_get_yg_arm_state

Upon receiving the request, returns the current status of each joint of the robot.

{
  "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 Two-finger gripper interface

2.4.1 Two-finger gripper control

Request: request_set_yg_claw_cmd

This protocol controls the gripping action of the gripper.

{ 
    "accid": "SF_TRON2A_001", 
    "title": "request_set_yg_claw_cmd", 
    "guid": "d2c6521699e035949c9276cb17b62bdb", 
    "timestamp": 1762771300000,
    "data": { 
    "position": 0.05, //Opening
    "max_effort": 10.0 //Torque
    } 
}

Response: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 Obtain gripper status information

Request:request_get_limx_2fclaw_state

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

Response:response_get_limx_2fclaw_state

Return gripper status information

{ 
    "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. Sensing Expansion Kit Interface

3.1 Overview

This section is intended for Pad, front-end and third-party access parties, and describes the interface names, request fields, response fields, constraints and error handling that Client should use when sending JSON strings via WebSocket.

API Overview

Serial No. API Description
Navigation System Status 1 request_navi_system_status Query the heartbeat status of the navigation system -- the status of the navigation system
Graph Construction 1 request_start_navi_mapping Start mapping
Graph Construction 2 request_get_navi_mapping_init_result Mapping Initialization Result
Graph Construction 3 request_stop_navi_mapping Stop mapping
Graph Construction 4 request_save_navi_map Save Map
Map Administration 1 request_get_navi_map_list Get the map list
Map Administration 2 request_delete_navi_map Delete the specified map
Map Administration 3 request_reset_navi_map Reset the occupancy grid map
Map Administration 4 request_rename_navi_map Rename Map
Map Administration 5 request_active_navi_map Activate Map
Map Administration 6 request_navi_map_info Obtain map information
Map Administration 7 request_get_navi_mapping_url Get the current mapping URL
Positioning 1 request_set_navi_auto_relocation Start positioning
Positioning 2 request_stop_navi_localization Stop Location
Navigation 1 request_set_navi_goal_waypoint Send navigation target
Navigation 2 request_cancel_navi_goal Cancel current navigation
Navigation 3 request_get_navi_status Query navigation status

Generic Result

value Description Client Suggestions
success Request successful Parse the response according to the interface fields
fail_remote The backend service has been invoked, but the business execution has failed
Display or log the message, and retry after refreshing the status if necessary
fail_service_call The backend mros service is unreachable, timed out, or failed to be invoked. Check the service status on the robot side and try again later
fail_invalid_cmd Missing request field, incorrect type, or invalid value Correct the request JSON; retrying as-is is not recommended
fail_invalid_accid accid incorrect Check robot accounts or connection objects
fail_already_occupied Control is occupied by another Client Prompt the user based on the occupant information in the response
fail_no_status There is currently no status cache available for query. Retry after the status report is received
fail_invalid_config Missing or empty server-side configuration Contact the robot-side maintenance personnel to check the configuration
fail_invalid_map_info Missing map information, unparseable path, or out-of-bounds path Check request_navi_map_info the returned data
fail_http gohfs HTTP upload or download failed Check http_status, file_url, and body, and retry as needed
fail_invalid_map_file The downloaded map file is not a valid PGM file Check the content of the server-side map file
fail_encode Server-side base64 encoding failed Log errors and report them
not_supported The interface is not currently implemented Should not be called as an official function

3.2 Navigation System Status

Query the heartbeat status of the navigation system -- the status of the navigation system (whether it is alive, the current status of the navigation system).

3.2.1 Query the status of the navigation system

Query the liveness and current mode of the navigation node

Request:request_navi_system_status

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

Response:response_navi_system_status

{ 
"accid": "WF_TRON2A_001", 
"title": "response_navi_system_status", 
"guid": "d2c6521699e035949c9276cb17b62bdb", 
"timestamp": 1762771300000,
  "data": {
   "result": "success", 
   "success": true, 
   "message": "Navigation"
   } 
}
Response Field Type Description
result string Fixed to success when the service call succeeds; set to fail_service_call when the service call fails.
success boolean /navigation/heartbeat The service success flag returned by the backend; true indicates that the navigation module is alive
message string Backend return message, description of current status:"Mapping" / "Navigation" / "Localization" / "idle"; when service invocation fails, it will be Failed to call /navigation/heartbeat

3.3 Map Construction Protocol

3.3.1 Start mapping

Starting map building indicates that the current navigation has entered the map building state, and it will build a map based on the physically recognized surrounding information in real time. This function is only IDLE state available, and the system will enter MAPPING after successful execution.

Request:request_start_navi_mapping

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

Response:response_start_navi_mapping

{ "accid": "WF_TRON2A_001", 
"title": "response_start_navi_mapping", 
"guid": "d2c6521699e035949c9276cb17b62bdb",
 "timestamp": 1762771300000,
  "data": { 
  "result": "success",
   "success": true, 
   "message": "mapping started" } 
}
Response Field Type Description
result string success / fail_remote / fail_service_call
message string Backend return message; when the service call succeeds, it is mapping started

3.3.2 Query the graph construction initialization result

Query the map construction initialization result of the navigation backend.

Request:request_get_navi_mapping_init_result

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

Response:response_get_navi_mapping_init_result

{ 
"accid": "WF_TRON2A_001",
"title": "response_get_navi_mapping_init_result",
"guid": "d2c6521699e035949c9276cb17b62bdb",
"timestamp": 1762771300000,
"data": {
 "result": "success", 
 "success": true, 
 "message": "{\"state\":\"ok\",\"attempt\":1,\"gyro_delta\":0.02}"
  } 
 }
Response Field Type Description
result string success / fail_remote / fail_service_call
message string

3.3.3 Stop mapping

End the mapping process. At this point, the navigation module will not save the images that have already been mapped, and you need to call the request_save_navi_map interface to save the images generated during the just-concluded mapping process.

Request:request_stop_navi_mapping

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

Response: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 Save Map

Save the current mapping result

Request:request_save_navi_map

{ 
"accid": "WF_TRON2A_001", 
"title": "request_save_navi_map", 
"guid": "d2c6521699e035949c9276cb17b62bdb",
 "timestamp": 1762771300000,
  "data": { 
  "map_name": "office_2f" 
  } 
}
Request Field Type Required Description Constraints
map_name string Yes Map name to be saved non-empty and does not contain path separators,..,., or control characters

Response: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"
    }
}
Response Field Type Description
result string success / fail_remote / fail_service_call / fail_invalid_cmd
message string Backend return information;message is the save path.
When map_name is missing, the common error is Missing map_name in request data

3.4 Map Management Protocol

3.4.1 Get the map list

Get all map names that exist in the current robot

Request:request_get_navi_map_list

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

Response: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"]
    } 
}
Response Field Type Description
result string success / fail_remote / fail_service_call
message string Backend response information
map_list string[] Map name array, returned only when the service call succeeds

3.4.2 Delete Map

Delete the specified map. It is recommended to use the map name from the map list returned by the request_get_navi_map_list interface; otherwise, the operation will fail.

Request:request_delete_navi_map

{
 "accid": "WF_TRON2A_001", 
"title": "request_delete_navi_map",
 "guid": "d2c6521699e035949c9276cb17b62bdb", 
 "timestamp": 1762771300000,
  "data": { 
  "map_name": "office_2f" 
  } 
}
Request Field Type Required Description Constraints
map_name string Yes Name of the map to be deleted not empty

Response: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" 
   } 
}
Response Field Type Description
result string success / fail_remote / fail_service_call / fail_invalid_cmd
message string Backend return information or failure reason

3.4.3 Reset the occupancy grid map

Request:request_reset_navi_map

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

Response:response_reset_navi_map

{ "accid": "WF_TRON2A_001",
 "title": "response_reset_navi_map", 
 "guid": "d2c6521699e035949c9276cb17b62bdb", 
 "timestamp": 1762771300000,
  "data":  {
   "result": "success", 
   "success": true, 
   "message": ""
    }
}
Response Field Type Description
result string success / fail_remote / fail_service_call / fail_invalid_cmd
message string Backend return information; when the service call fails, it will be Failed to call /navigation/reset_occupiedMap

3.4.4 Rename Map

Rename the saved navigation map.

Request: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"
   } 
}
Request Field Type Required Constraints
old_map_name string Yes
Must pass security validation and cannot contain path separators,..,., or control characters.
new_map_name string Yes The rules are the same as old_map_name, and it cannot be the same as the old map name

Response: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 " }
}
Response Field Type Description
result string success / fail_remote / fail_service_call / fail_invalid_cmd
message string Backend returned information or local parameter validation error

3.4.5 Activate Map

Pre-operation before positioning/navigation, which marks which map to use for navigation and positioning. It is required to use request_get_navi_map_list the map name in the map list returned by the interface, otherwise the operation will fail.

Request:request_active_navi_map

{ 
"accid": "WF_TRON2A_001", 
"title": "request_active_navi_map", 
"guid": "d2c6521699e035949c9276cb17b62bdb",
"timestamp": 1762771300000,
     "data": { 
    "map_name": "office_2f" 
    } 
}
Request Field Type Required Description Constraints
map_name string Yes Name of the map to be activated Suggestions from the request_get_navi_map_list returned list

Response: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" 
  } 
}
Response Field Type Description
result string success / fail_remote / fail_service_call / fail_invalid_cmd
message string Backend return information or failure reason (e. g., failure message "map not found or apply failed: floor_3")

3.4.6 Obtain map information

Obtains the specified map information and returns map metadata in JSON format (including resolution, dimensions, creation time, local storage path of the map, etc. , which requires secondary parsing by the Client on its own). It is required to use request_get_navi_map_list the map name from the map list returned by the interface, otherwise the request will fail.

Request:request_navi_map_info

{
  "accid": "WF_TRON2A_999",
  "title": "request_navi_map_info",
  "guid": "d2c6521699e035949c9276cb17b62bdb",
  "timestamp": 1762771300000,
  "data": {
    "map_name": "5F"
  }
}
Request Field Type Required Description Constraints
map_name string Yes Map Name Suggestions from the map list request_get_navi_map_list

Response: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\"}"
    }
}
Response Field Type Description
result
string success / fail_remote / fail_service_call / fail_invalid_cmd
message string Backend return information or failure reason
map_info string
Map information string returned by the backend; usually contains path, map_path or file_path; the returned raw data is a json field, and automatic escaping processing will be performed to avoid affecting Client parsing of json, for example using \

3.4.7 Get the current mapping URL

Obtain the HTTP URL of the current mapping image. This interface only returns the URL and does not transmit the image content via WebSocket.

After starting the mapping process, the Client needs to view the real-time mapping image for the current navigation. It is required to obtain the URL of the real-time mapping through this interface, and then display the real-time mapping image via this URL. It is not recommended for the Client to display the real-time mapping image through this URL with a refresh rate exceeding 1 Hz.

Request:request_get_navi_mapping_url

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

Response: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"
  }
}
Response Field Type Description
result string success / fail_invalid_config
map_url string HTTP URL of the mapping image, from api_urls. navi_mapping_url

3.5 Location Protocol

3.5.1 Start positioning

The map must be activated beforehand, and you will enter LOCALIZING after the activation succeeds.

Request:request_set_navi_auto_relocation

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

Response: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 Stop Location

Make the robot end localization and navigation. LOCALIZING → IDLE.

Request:request_stop_navi_localization

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

Response: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 Set Cruise Speed

Maximum Linear Velocity (m/s) Maximum Angular Velocity (rad/s)
Low 0.35 0.60
Medium (Default) 0.65 1.00
High 0.95 1.00

Request:request_set_navi_speed_gear

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

The gear must be a lowercase JSON string: low, medium, or high. If it is missing, an empty string, of the wrong type, or any other value (including uppercase or leading/trailing spaces), fail_invalid_cmd is returned, no message is published, and it will not automatically be changed to medium.

Response: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 Navigation Protocol

3.6.1 Send navigation target point

x / y in meters, yaw in radians; all three must be finite values

Request: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 } 
  }
Request Field Type Required Description Constraints
x number Yes Target point x The unit is defined by the navigation backend, usually in meters
y number Yes Target point y The unit is defined by the navigation backend, usually in meters
yaw number Yes Target Orientation usually in radians

Response: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" 
  } 
}
Response Field Type Description
result string success / fail_remote / fail_service_call / fail_invalid_cmd
message string Field missing / type error / non-finite value returned fail_invalid_cmd; Mismatched status returned fail_remote

3.6.2 Cancel current navigation

Cancel the ongoing current target, and the sub-state will change to GOAL_CANCEL.

Request:request_cancel_navi_goal

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

Response: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 Query navigation sub-state

Query the current navigation sub-status (read the local cache, which comes from the subscription of /navigation/goal_status topic).

Request:request_get_navi_status

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

Response: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" 
  } 
}
Response Field Type Description
result string success / fail_no_status
code number Returns fixed value on success 0
navigation_status string NO_GOAL: No navigation point task is currently available
GOAL_RUNNING: Target points have been issued, and the task is in progress
GOAL_REACHED: Target Reached
GOAL_FAILED: The target is unreachable or the execution has failed
GOAL_CANCEL: Target cancellation.
status string Same as navigation_status for compatibility in reading
source string Fixed to /navigation/goal_status on success
message string When there is no stateless cache, it is No navigation status has been received

3.7 Server-side Active Push

Robot Navigation Pose Publishing, approx. 1 Hz

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

Field Description

Response Field Type Description
data.x number The x-coordinate of the robot in the map coordinate system, in meters.
data.y number The y-coordinate of the robot in the map coordinate system, in meters.
data.yaw number Robot heading, in radians.
data.frame_id string Coordinate frame of the pose, usually map.
data.stamp number Timestamp of the pose data, in milliseconds.

4. Frequently Asked Questions

Serial No. Problem Description FAQ
1 When it is normally used for mapping and navigation, how many teraflops of computing power can be spared for clients to call for other tasks? Memory usage stands at 50%; CPU usage reaches 80%; the GPU is fully occupied only during relocation, and remains mostly idle in other phases.