# TRON2 Autonomous Mobile Operation / Perception Expansion Kit SDK Guide

> Source: https://www.limxdynamics.com/en/documents/910246171287621632
> Published: 2026-11-16
> Tags:  TRON 2 EDU Ed.

## 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](https://www.limxdynamics.com/en/documents/856848486581276672)

#### 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.

   ```bash
   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:

   - Method 1: Activate CAN first (e. g., `sudo ip link set can0 up type can bitrate 1000000`)
   - Method 2: You may also use a script, see [CAN Module Manual - Activate a Single CAN Module](https://github.com/agilexrobotics/pyAgxArm/blob/master/docs/can_user.md#2-activate-a-single-can-module)

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

3. Six-axis Robotic Arm SDK Interface Documentation

   [Piper API Documentation](https://github.com/agilexrobotics/pyAgxArm/blob/master/docs/piper/piper_api.md#piper-api-documentation)

#### 2.1.3 ROS package for robotic arm

[Robotic Arm ROS 2 Package (English README)](https://github.com/agilexrobotics/agx_arm_ros/blob/ros2/README_EN.md)

#### 2.1.4 Sample Code for Robotic Arm

[Robotic Arm Sample Code (pyAgxArm demos)](https://github.com/agilexrobotics/pyAgxArm/tree/master/pyAgxArm/demos)

#### 2.1.5 Two-finger gripper interface

[AgxGripper API Documentation](https://github.com/agilexrobotics/pyAgxArm/blob/master/docs/effector/agx_gripper/agx_gripper_api.md#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](https://github.com/agilexrobotics/pyAgxArm/blob/master/docs/effector/revo2/revo2_api.md#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

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

Response：

```json
{
    "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：

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

Response：

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

##### 2.2.2.2 Stand Up

Request：

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

Response：

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

```json
{
  "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:

```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 Specified Direction Control

Request:

```json
{
  "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:

```json
{
  "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:

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

Response:

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

```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：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 Control Command

Request：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：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 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

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

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

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

Response: response_yg_servop

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

```json
{
  "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.

```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] //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.

```json
{
  "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.

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

#### 2.3.1 Set Whole-Body Control Mode

Request：request_yg_set_control_mode

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

Response：

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

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

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

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

Response：response_yg_servop

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

```json
{
  "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.

```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` 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.

```json
{
  "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.

```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 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.

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

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

Request：request_get_limx_2fclaw_state

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

```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. 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<br> | 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

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

Response：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"
   }
}
```

| 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

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

Response：response_start_navi_mapping

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

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

Response：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",
 "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

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

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

Save the current mapping result

Request：request_save_navi_map

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

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

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

Response：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"]
    }
}
```

| 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

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

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

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

Response：response_reset_navi_map

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

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

| Request Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| `old_map_name` | string | Yes<br> | 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

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

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

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

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

```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\"}"
    }
}
```

| 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<br> | 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

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

Response：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"
  }
}
```

| 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

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

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

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

Request：request_stop_navi_localization

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

Response：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 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

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

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

```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 }
  }
```

| 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

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

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

Response：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 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

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

Response：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"
  }
}
```

| 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

```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
  }
}
```

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. |
