Chassis Control Interface

About 3436 wordsAbout 11 min

Developers can conveniently access robot status, send control commands, and implement complex task programming and integration through standard ROS 2 communication mechanisms, including Topics, Services, and Actions.

Topic: A subscription‑based communication mechanism. Subscribers register for a specific topic, and publishers send messages to all registered subscribers based on the subscription list. This mechanism is primarily used for medium‑to‑high frequency or continuous data exchange.
Service: A request‑reply communication mechanism. Data retrieval or operations are performed via service requests. It is suitable for low‑frequency interactions or mode‑switching operations.
Action: A persistent, stateful communication mechanism designed for long‑running tasks. It supports real‑time status feedback and task cancellation during execution, making it ideal for complex motion control and task execution.

Interface Description

(1) Mapping

Service	/mapping_node/set_map_name
Effective Version	≥V0.3.2
Access Method	Service Call Custom ROS2 message format: nav_interfaces/srv/SetMapName
Interface Description	Set the map name (must be called before `start_mapping`)
Interface Parameters	Request: String map_name: Before starting the mapping, set the file name of the map output for this mapping session, which must be a non-empty string in the format of English letters, numbers, or underscores
Interface Parameters	Response: Bool success: Indicates whether the map name was successfully set. A value of 1 indicates success, and a value of 1 indicates failure; String message: Descriptive information of the returned result

Service	/mapping_node/start_mapping
Effective Version	≥V0.3.2
Access Method	Service Call Standard ROS2 message format std_srvs/srv/Trigger
Interface Description	Start mapping
Interface Parameters	Request: Empty Request
Interface Parameters	Response: Bool success: Indicates whether the map building was successful, with a value of 1 representing success and a value of 0 representing failure; String message: Descriptive information of the returned result

Service	/mapping_node/finish_mapping
Effective Version	≥V0.3.2
Access Method	Service Call Standard ROS2 message format std_srvs/srv/Trigger
Interface Description	Completed map building
Interface Parameters	Request: Empty Request
Interface Parameters	Response: Bool success: Indicates whether the map building and saving were successful. A value of 1 represents success, and a value of 0 represents failure; String message: Descriptive information of the returned result

(2) Positioning

Service	/localization_node/start_localization
Effective Version	≥V0.3.2
Access Method	Service Call Standard ROS2 message format std_srvs/srv/Trigger
Interface Description	Start positioning (automatically triggered upon power-on)
Interface Parameters	Request: Empty Request
Interface Parameters	Response: Bool success: Indicates whether the positioning startup was successful, with a value of 1 representing success and a value of 0 representing failure; String message: Descriptive information of the returned result

Service	/localization_node/stop_localization
Effective Version	≥V0.3.2
Access Method	Service Call Standard ROS2 message format std_srvs/srv/Trigger
Interface Description	Stop positioning
Interface Parameters	Request: Empty Request
Interface Parameters	Response: Bool success: Indicates whether the positioning stop was successful, with a value of 1 representing success and a value of 0 representing failure; String message: Descriptive information of the returned result

Service	/localization_node/reset_localization
Effective Version	≥V0.3.2
Access Method	Service Call Standard ROS2 message format std_srvs/srv/Trigger
Interface Description	Reset the positioning status (first turn off the current positioning, then restart positioning once)
Interface Parameters	Request: Empty Request
Interface Parameters	Response: Bool success: Indicates whether the positioning reset was successful, with a value of 1 representing success and a value of 0 representing failure; String message: Descriptive information of the returned result

Service	/localization_node/relocalization
Effective Version	≥V0.3.2
Access Method	Service Call Custom ROS2 message format nav_interfaces/srv/SetPose
Interface Description	Trigger Relocalization (given an initial pose, trigger the localization module to perform relocalization based on this initial pose)
Interface Parameters	Request: float64[] pose.position: The position coordinates of the chassis in the map, formatted as [x, y, z] (position matrix in the Cartesian coordinate system), with the unit of meters, and the values are determined according to the map coordinate system; float64[] pose.orientation: The pose of the chassis, represented by a quaternion, with the format [x,y,z,w] (quaternion, satisfying x²+y²+z²+w²=1); pose.covariance: Pose covariance matrix, representing the confidence level of the initial pose. The larger the diagonal elements, the lower the confidence level. Usually, the initial relocalization can be set to a relatively large value (e.g., [0.1, 0,..., 0.1])
Interface Parameters	Response: Bool success: Indicates whether the relocation was successfully triggered, with a value of 1 representing success and a value of 0 representing failure; String message: Descriptive information of the returned result

(3) Map Management

Service	/map_manager/get_map_list
Effective Version	≥V0.3.2
Access Method	Service Call Custom ROS2 message format nav_interfaces/srv/GetMapList
Interface Description	Get all valid maps in the current map directory
Interface Parameters	Request: Empty Request
Interface Parameters	Response: String[] map_list: A list of names of all valid maps, with an empty array indicating no valid maps; Bool success: Indicates whether the query was successful, with a value of 1 representing success and a value of 0 representing failure; String message: Descriptive information of the returned result

Service	/map_manager/get_map_folder
Effective Version	≥V0.3.2
Access Method	Service Call Custom ROS2 message format nav_interfaces/srv/GetString
Interface Description	Get the storage directory of the current map
Interface Parameters	Request: Empty Request
Interface Parameters	Response: String data: Absolute/relative path where the map is saved Bool success: Indicates whether the query was successful, with a value of 1 representing success and a value of 0 representing failure; String message: Descriptive information of the returned result

Service	/map_manager/get_map_name
Effective Version	≥V0.3.2
Access Method	Service Call Custom ROS2 message format nav_interfaces/srv/GetString
Interface Description	Get the name of the map currently loaded in the location
Interface Parameters	Request: Empty Request
Interface Parameters	Response: String data: Name of the currently loaded map Bool success: Indicates whether the query was successful, with a value of 1 representing success and a value of 0 representing failure; String message: Descriptive information of the returned result

Service	/map_manager/get_current_map_info
Effective Version	≥V0.3.2
Access Method	Service Call Custom ROS2 message format nav_interfaces/srv/GetMapInfo
Interface Description	Get information about the currently loaded map
Interface Parameters	Request: Empty Request
Interface Parameters	Response: map_info: map metadata, containing subfields map_load_time, resolution, width, height, and origin; String map_name: current map name; String map_path: The full path of the current map file; Bool success: Indicates whether the query was successful, with a value of 1 representing success and a value of 0 representing failure; String message: Descriptive information of the returned result

Service	/map_manager/load_map
Effective Version	≥V0.3.2
Access Method	Service Call Custom ROS2 message format nav_interfaces/srv/LoadMap
Interface Description	Load the map with the specified name
Interface Parameters	Request: String map_name: The name of the map to be loaded (must be a valid map name returned by `get_map_list`)
Interface Parameters	Response: Bool success: Indicates whether the loading was successful, with a value of 1 representing success and a value of 0 representing failure; String message: Descriptive information of the returned result

Service	/map_manager/remove_map
Effective Version	≥V0.3.2
Access Method	Service Call Custom ROS2 message format nav_interfaces/srv/DeleteMap
Interface Description	Delete the map with the specified name
Interface Parameters	Request: String map_name: The name of the map to be deleted (must be a valid map name returned by `get_map_list`)
Interface Parameters	Response: Bool success: Indicates whether the deletion was successful, with a value of 1 representing success and a value of 0 representing failure; String message: Descriptive information of the returned result

(4) Differential Chassis Control Interface

The message format follows the geometry_msgs/Twist standard

Topic	/feedback/odom
Effective Version	≥V0.3
Access Method	Subscribe Standard ROS2 message nav_msgs/msg/Odometry
Interface Description	Obtain the current odometry information (Odometry) of the robot, which includes information about the robot's pose and motion speed. Velocity information is located at: msg.twist.twist
Interface Parameters	float64 twist.twist.linear.x: Obtain the linear velocity in the X-axis direction, with the unit of m/s and a value range of [-1.0, 1.0]
Interface Parameters	float64 twist.twist.angular.z: Obtain the angular velocity around the Z-axis, with the unit of rad/s and a value range of [-1.0, 1.0]

Topic	/control/cmd_vel
Effective Version	≥V0.2
Access Method	Publish
Interface Description	Issue commands to control the speed of the robot, and control the robot's motion trajectory and attitude adjustment by setting linear velocity and angular velocity
Interface Parameters	float64 linear.x: Obtain the linear velocity in the X-axis direction, with the unit of m/s and a value range of [-1.0, 1.0]
Interface Parameters	float64 angular.z: Get the angular velocity around the Z-axis, with the unit of rad/s and a value range of [-1.0, 1.0]

(5) Omnidirectional Mobile Chassis Control Interface

The omnidirectional mobile chassis control interface is used to obtain the operating status of the chassis' 8 motors in real time and issue commands.

Topic	/feedback/omni_chassis_motors
Effective Version	≥V0.2
Access Method	Subscribe
Interface Description	Real-time acquisition of the motor speed of the omnidirectional chassis and the angle of the steering motor
Interface Parameters	header: Standard message header, containing metadata such as timestamp (stamp), coordinate system (frame_id), etc.
	float64[] position: The steering motor angles of the omnidirectional chassis, formatted as [left front wheel angle, right front wheel angle, left rear wheel angle, right rear wheel angle], with a value range of [-π/2, π/2] and the unit being radians (rad)
	float64[] speed: The motor speeds of the omnidirectional chassis, formatted as [left front wheel linear speed, right front wheel linear speed, left rear wheel linear speed, right rear wheel linear speed], with a value range of [-1.0, 1.0] and a unit of meters per second (m/s)

Topic	/control/omni_chassis
Effective Version	≥V0.2
Access Method	Publish
Interface Description	Issue commands to achieve omnidirectional chassis movement
Interface Parameters	header: Standard message header, containing metadata such as timestamp (stamp), coordinate system (frame_id), etc.
	float64[] position: The steering motor angles of the omnidirectional chassis, formatted as [left front wheel angle, right front wheel angle, left rear wheel angle, right rear wheel angle], with a value range of [-π/2, π/2] and the unit being radians (rad)
	float64[] speed: The motor speeds of the omnidirectional chassis, formatted as [left front wheel linear speed, right front wheel linear speed, left rear wheel linear speed, right rear wheel linear speed], with a value range of [-1.0, 1.0] and a unit of meters per second (m/s)

(6) Chassis Position Interface

Topic	/feedback/chassis_pose
Effective Version	≥V0.2
Access Method	Subscribe Interaction based on the standard ROS2 message geometry_msgs/PoseStamped
Interface Description	Obtain the real-time pose of the chassis in the map (navigation function needs to be enabled)
Interface Parameters	header: Standard message header, containing metadata such as timestamp (stamp), coordinate system (frame_id), etc.
	float64[] pose.position: The position coordinates of the chassis in the map, formatted as [x, y, z] (position matrix in the Cartesian coordinate system), with the unit of m
	float64[] pose.orientation: The pose of the chassis, formatted as [x, y, z, w] (quaternion, satisfying x²+y²+z²+w²=1)

Topic	/control/nav2_pose
Effective Version	≥V0.2
Access Method	Publish Interaction based on the standard ROS2 message geometry_msgs/PoseStamped
Interface Description	Issue a command to control the chassis to move to the target position (navigation function needs to be enabled). The pose accuracy upon reaching the target position is relatively low, and it has autonomous obstacle avoidance capabilities.
Interface Parameters	header: Standard message header, containing metadata such as timestamp (stamp), coordinate system (frame_id), etc.
	float64[] pose.position: The target position of the chassis in the map, formatted as [x, y, z] (position matrix in Cartesian coordinates), with the unit of m
	float64[] pose.orientation: The pose of the chassis, formatted as [x, y, z, w] (quaternion, satisfying x²+y²+z²+w²=1)

Topic	/control/ctrl_pose
Effective Version	≥V0.2
Access Method	Publish Standard ROS2 message geometry_msgs/PoseStamped
Interface Description	Issue commands to control the chassis to move to the target position (navigation function needs to be enabled), only supporting linear movement and in-place rotation, without autonomous obstacle avoidance capabilities, with the origin of the coordinate system being the current point;
Interface Parameters	header: Standard Message Header
	float64[] pose.position: Cartesian coordinates (positions on the X/Y/Z axes) of the target position, formatted as [x, y, z], with the range determined by the robot's workspace (map), and the unit is m
	float64[] pose.orientation: Quaternion representation of the target pose (used to describe the spatial orientation of the robot), formatted as [x, y, z, w], and must satisfy the quaternion constraint: x²+y²+z²+w²=1

(7) Chassis Basic Service Interface

Service	/save_charging_pose
Effective Version	≥V0.3
Access Method	Service Call Based on the ROS standard std_srvs/srv/Empty format - the Client sends a request, and the server returns a response
Interface Description	Save the recharge point, setting the current position of the robot as the reference point for automatic recharging (0.7m - 1m directly in front of the charging pile)
Interface Parameters	Request: Empty request, usually triggered by sending `{}` or an empty string.
Interface Parameters	Response: Bool success: Indicates whether the location was successfully saved, where "1" represents success and "0" represents failure. String message: The returned prompt message, usually containing the saved recharge point coordinate information.

Action	/auto_charing
Effective Version	≥V0.3
Access Method	Action Call
Interface Description	Control the robot to automatically search for and dock with the charging pile, issue the return-to-charge command through this interface, and obtain the robot's return-to-charge status in real time.
Interface Parameters	Request: Object goal: Issue commands, example: {force: true}, force return to charging dock
Interface Parameters	Response: String feedback: Feedback on the current state, including running / success / failure Bool result: Whether the return charging was ultimately successful