Service Interface Reference

Available service interface definitions.

Navigation Services

planning/set_waypoints

Sets the waypoint list.

Request:

Field	Type	Description
waypoints	Waypoint[]	Waypoint array
repetition	uint8	Repeat count (ignored if infinite_loop is true)
current_index	uint8	Starting index
infinite_loop	bool	Whether to repeat indefinitely

Response:

Field	Type	Description
success	bool	Success flag
message	string	Result message

Possible Response Messages:

"set waypoint success" - Success
"waypoint list is empty" - Empty waypoint list
"service timeout" - No service response

planning/get_waypoints

Queries current mission status.

Request: (empty)

Response:

Field	Type	Description
success	bool	Success flag
message	string	Result message
waypoints	Waypoint[]	Current waypoint list
repetition	uint8	Remaining laps (ignored if infinite_loop is true)
current_index	uint8	Current target index
infinite_loop	bool	Whether patrol repeats indefinitely

planning/refine_waypoints

Optimizes waypoints using A* algorithm on the graph.

Request:

Field	Type	Description
waypoints	Waypoint[]	Input waypoint array
nodes	GraphNode[]	Graph node array
edges	GraphEdge[]	Graph edge array

Response:

Field	Type	Description
success	bool	Success flag
message	string	Result message
refined_waypoints	Waypoint[]	Optimized waypoint list (follows graph path)
path_node_ids	int32[]	Node IDs forming the path

Possible Response Messages:

"Refined N waypoints" - Success
"No graph nodes provided" - Empty nodes
"service timeout" - No service response

Patrol Route Services

planning/list_waypoints_files

Lists saved patrol route files.

Request:

Field	Type	Description
directory	string	Directory to query (default directory if empty)

Response:

Field	Type	Description
success	bool	Success flag
message	string	Result message
files	string[]	File name list

Possible Response Messages:

"Found N files" - Success (N files found)
"service timeout" - No service response

planning/load_waypoints_file

Loads a saved patrol route file.

Request:

Field	Type	Description
name	string	File name to load (without extension)

Response:

Field	Type	Description
success	bool	Success flag
message	string	Result message

Possible Response Messages:

"Waypoints loaded from: filename" - Success
"File not found: filename" - File not found
"service timeout" - No service response

planning/save_waypoints_file

Saves current waypoints to a file.

Request:

Field	Type	Description
name	string	File name to save (without extension)

Response:

Field	Type	Description
success	bool	Success flag
message	string	Result message

Possible Response Messages:

"Waypoints saved to: filename" - Success
"service timeout" - No service response

planning/resume_patrol

Resumes patrol from the nearest waypoint in the currently loaded route.

Request: (empty)

Response:

Field	Type	Description
success	bool	Success flag
message	string	Result message
waypoint_index	uint8	Starting waypoint index

Possible Response Messages:

"Resuming from waypoint N" - Success (starting from waypoint N)
"No waypoints loaded" - No route loaded
"service timeout" - No service response

Note

Must load a route with planning/load_waypoints_file first.

Graph Services

save_graph_file

Saves a graph to a file.

Request:

Field	Type	Description
name	string	File name to save
nodes	GraphNode[]	Graph node array
edges	GraphEdge[]	Graph edge array

Response:

Field	Type	Description
success	bool	Success flag
message	string	Result message

Possible Response Messages:

"Graph saved to: filename" - Success
"service timeout" - No service response

load_graph_file

Loads a saved graph file.

Request:

Field	Type	Description
name	string	File name to load

Response:

Field	Type	Description
success	bool	Success flag
message	string	Result message
nodes	GraphNode[]	Loaded node array
edges	GraphEdge[]	Loaded edge array

Possible Response Messages:

"Graph loaded from: filename" - Success
"File not found: filename" - File not found
"service timeout" - No service response

Map Services

list_map_files

Lists map files saved on the robot.

Request:

Field	Type	Description
directory	string	Directory to query (default directory if empty)

Response:

Field	Type	Description
success	bool	Success flag
message	string	Result message
files	string[]	Map file name list

load_laser_map

Loads a map saved on the robot.

Request:

Field	Type	Description
name	string	Map name to load

Response:

Field	Type	Description
success	bool	Success flag
message	string	Result message

Possible Response Messages:

"Map loaded." - Success
"Map not found" - Map file not found
"service timeout" - No service response

Note

In the SDK, loadMap() method calls this service and automatically loads the graph and default route.

set_map (SetLaserMap)

Sets the initial pose for localization.

Note

In the SDK, use the setInitialPose() method to call this service. Must call loadMap() first to load the map.

Request:

Field	Type	Description
name	string	Map frame name (map name loaded via loadMap)
initial_pose	Pose	Initial robot pose

Response:

Field	Type	Description
success	bool	Success flag
message	string	Result message

Possible Response Messages:

"Map saved." - Success
"service timeout" - Fast-LIO plugin not loaded

Locomotion Services

stand_up

Makes the robot stand up.

Request: (empty)

Response:

Field	Type	Description
success	bool	Success flag
message	string	Result message

Possible Response Messages:

"Trigger: started" - Success
"service timeout" - No service response

sit_down

Makes the robot sit down.

Request: (empty)

Response:

Field	Type	Description
success	bool	Success flag
message	string	Result message

Possible Response Messages:

"Trigger: started" - Success
"service timeout" - No service response

Control Mode Services

set_listen (Joy Control)

Enables/disables manual joystick control.

Request:

Field	Type	Description
data	string	Control command string

Request data format:

Enable manual control: "joy/gui<&>network_id"
Enable autonomous control: "vel_cmd/autonomy"
Release control: "topic_name<&><CLOSE>" (e.g., "joy/gui<&><CLOSE>")

Response:

Field	Type	Description
success	bool	Success flag
message	string	Result message

Message Types

Waypoint

string frame      # Coordinate frame: "map_name", "gps", "odom"
float64 x         # X coordinate (GPS: latitude)
float64 y         # Y coordinate (GPS: longitude)
float64 z         # Z coordinate (GPS: altitude)
bool use_z        # Whether to check Z coordinate

GraphNode

int32 id          # Node ID
float64 x         # X coordinate
float64 y         # Y coordinate
float64 z         # Z coordinate

GraphEdge

int32 from_node   # Start node ID
int32 to_node     # End node ID
float64 cost      # Edge cost (distance)

Topics

robot_state

Topic that publishes robot state information.

Topic name: robot_state

Message fields:

Field	Type	Description
actuator_states	ActuatorState[]	Actuator (motor) status array
base_pos	double[3]	Base position [x, y, z]
base_quat	double[4]	Base quaternion [x, y, z, w]
base_lin_vel	double[3]	Linear velocity [vx, vy, vz]
base_ang_vel	double[3]	Angular velocity [wx, wy, wz]
voltage	double	Current battery voltage (V)
current	double	Current (A)
max_voltage	double	Maximum voltage
min_voltage	double	Minimum voltage
body_temperature	double	Body temperature (C)
state	int32	Locomotion state (0-9)
joy_listen_type	int32	Joy source type (0=JOY, 1=VEL_CMD, 2=NONE)

ActuatorState message:

Field	Type	Description
name	string	Motor name (e.g., “FR_hip”)
position	double	Joint position (rad)
velocity	double	Joint velocity (rad/s)
effort	double	Joint torque (Nm)
status	uint16	CiA402 status code (see below)
temperature	double	Motor temperature (C)

Actuator Status Codes (CiA402 EtherCAT Standard):

Value	State	Description
0	NOT_READY_TO_SWITCH_ON	Not ready (error)
8	FAULT	Fault (error)
33	READY_TO_SWITCH_ON	Ready to switch on (normal standby)
35	SWITCHED_ON	Switched on (normal)
39	OPERATION_ENABLED	Operation enabled (normal operation)
99	ECAT_CONN_ERROR	EtherCAT connection error (error)

Warning

Status interpretation:

status == 0 is NOT “normal”! It’s a NOT_READY error state.
Normal operation state is status == 39 (OPERATION_ENABLED).
Error detection: status == 0 || status == 8 || status == 99

Locomotion State values:

Value	State
0	COMM_DISABLED (Communication disabled)
1	COMM_ENABLED (Communication enabled)
2	MOTOR_READY (Motor ready)
3	MOTOR_COMMUTATION (Motor commutation in progress)
4	MOTOR_ENABLED (Motor enabled)
5	IN_TEST_MODE (Test mode)
6	STANDING_MODE (Standing)
7	IN_CONTROL (In control/walking)
8	SITDOWN_MODE (Sitting)
9	MOTOR_DISABLED (Motor disabled)

/Odometry

Raw odometry topic from Fast-LIO output.

Topic name: /Odometry

Message type: nav_msgs/Odometry

Note

To get position in map frame, use subscribeMapOdometry(). It subscribes to /{map_name}/{robot_id}/Odometry topic.

/cloud_registered

Real-time LiDAR point cloud topic.

Topic name: /cloud_registered

Message type: sensor_msgs/PointCloud2