Navigation Example

Navigation-task C++ SDK and examples: DeepRoboticsLab/robotserver_sdk

Single-Floor Navigation

The Jueying X30 Pro uses the ROS/navigation navigation framework.

The navigation methods described in this section and multi-floor navigation require localization(≥2.0.5), nav(≥2.1.9), player(≥1.0.6), broker/robot_server(≥1.1.6), and app(≥2.3.2).

When using autonomous navigation, avoid turning on sharp terrain and watch for sudden obstacles in the robot dog’s blind spots.

Before using autonomous navigation, ensure the mapping program is not running.

After map deployment, refer to Auto-start Configuration to change autorun_slam to true and restart the robot dog to auto-start the localization/navigation program on each boot.

Start Localization and Navigation Program

Open a terminal and enter the following command:

cd ~/jy_cog/system/scripts
bash start_nav.sh

After execution, the RViz visual interface will pop up automatically, showing the map and the robot dog’s real-time LiDAR point cloud data (colored part).

If localization/navigation was already started (or auto-start is configured), open RViz directly:

bash ~/jy_cog/system/scripts/start_rviz.sh

Localization Initialization

After starting navigation, if the LiDAR point cloud does not fully overlap with the grid map (as shown above), you need to initialize the robot dog’s localization.

1. Click [2D Pose Estimate] in the top toolbar.
2. Determine the robot dog’s actual position and orientation. Move the mouse to the corresponding position on the map, hold the left button, and drag an arrow in the actual orientation direction, then release.
3. If localization initialization succeeds, the LiDAR point cloud will overlap with the grid map as shown below. If it fails, restart from step 1.

If localization fails, refer to Localization Troubleshooting.

Specify Goal Point (Single-Point Navigation)

After localization initialization, you can specify a navigation goal point on the map:

1. Click [2D Nav Goal] in the top toolbar.
2. Move the mouse to the target position on the map, hold the left button, and drag an arrow in the desired orientation, then release.
3. If the goal is set successfully, a planned path will appear. If it fails, restart from step 1.
4. Finally, switch the robot dog from manual mode to navigation mode on the gamepad, and start stepping. The robot dog will autonomously navigate to the goal, avoiding obstacles along the way.

All personnel must keep at least 2 meters away from the robot dog during autonomous navigation!

If the robot dog loses control during autonomous navigation, immediately switch from navigation mode back to manual mode, or press the soft emergency stop button (or simultaneously push up SW1 and SW4).

Multi-Point Navigation Deployment

The Jueying X30 Pro gamepad APP provides a waypoint tool for deploying multi-point navigation routes, enabling the robot dog to reach a series of waypoints in sequence and autonomously complete tasks at each point.

Deployment Preparation

1. Go to the Jueying Lab in APP settings and enable the waypoint tool.
2. Plan the robot dog’s path in advance and distribute waypoints reasonably.

Create Navigation Route

1. Ensure the robot dog is in manual or assist mode, then click [Create Navigation Route]:

2. After clicking [Create Navigation Route], you will enter the route creation page:

Button	Function
①Add Waypoint	Add a new waypoint at the end of the list and set its properties

Button	Function
②Clear Waypoints	Clear all waypoints in the current list
③Expand/Collapse waypoint list	Expand or collapse the waypoint list
④Edit waypoint	Modify properties (excluding position and orientation) of the selected waypoint
⑤Insert waypoint	Insert a new waypoint above the selected waypoint
⑥Delete waypoint	Remove the selected waypoint from the list
⑦Save Route	Save and name the current route, then exit
⑧Exit	Exit without saving

3. Remotely control the robot dog to each waypoint position in order, stop the robot dog, click [Add Waypoint], and set waypoint properties. The APP will automatically capture the robot dog’s current position and orientation. The new waypoint page:

Button	Function
⑨Switch Map ID	Select the grid map ID for the waypoint
⑩Refresh waypoint info	Refresh the waypoint’s position and orientation
⑪Save as new waypoint	Save current waypoint properties and return
⑫Waypoint properties	Set waypoint properties; scroll to view different properties; tap to select. See Waypoint Properties below
⑬Save waypoint photo toggle	Choose whether to save video stream photo at this waypoint

4. After marking all waypoints, click [Save Route] to save and name the route.

When the navigation route includes going up/down stairs, the waypoint before going upstairs must be at least 0.8m from the stair edge.

When marking a charging point entry, do not use L-walking, mountain, or silent gait. Walking or slope gait is recommended.

When deploying navigation routes using the gamepad, the first and last waypoints must not be too far apart, otherwise the navigation task cannot be executed in a loop.

Waypoint Properties

Waypoint properties are divided into path properties and point properties. Path properties take effect on the path to the waypoint. Waypoint type, waypoint number, map ID, and waypoint info are point properties. Gait, ground type, body height, speed, motion direction, navigation mode, and obstacle detection are path properties.

Property	Sub-item	Description
Map ID		Grid map ID of the waypoint
Waypoint Info		Position coordinates and orientation in the map frame
Waypoint Type	Transition	Only for overcoming terrain and constraining paths; maintains stepping or switches gait at the point, then proceeds to the next point
	Task	High arrival precision; the robot dog performs precise body adjustment upon arrival, then stops and stands for inspection tasks before proceeding
	Charging	For identifying the charging dock reflector; enters the dock for charging; exits immediately after charging (if it’s the last point, the robot stays charging and does not exit)
Body Height	Normal	Robot maintains normal height
	Crawl	Robot maintains crawl height (only walking and slope gait supported at crawl height)
Ground Type	Solid ground	For solid ground scenes like concrete floors or stairs
	Hollow ground	For hollow ground scenes like steel grating industrial stairs or platforms
	Stairs without risers	For stairs without vertical risers (height locked to normal, gait to stair, speed to low)
	Accumulated frame	For scenes with mixed ground types (collision detection not supported; only stair and 45° stair gait supported)
Orientation	Forward	Arrive at the waypoint moving forward
	Backward	Arrive at the waypoint moving backward; must be set to backward when going down stairs
Gait	Walking	Walking gait
	Slope	Slope gait
	Obstacle-clearing	Obstacle-clearing gait
	Stair	Stair gait
	45° Stair	45° stair gait (only in accumulated frame mode)
	L-Walking	L-walking gait
	Mountain	Mountain gait
Speed	Low	Arrive at low speed (not supported in accumulated frame mode)
	Medium	Arrive at medium speed (not supported by some gaits)
	High	Arrive at high speed (not supported by some gaits)
Navigation Mode	Straight-line	Straight-line navigation
	Autonomous	Autonomous navigation
Obstacle Detection	Enabled	Enable navigation stop-avoidance
	Disabled	Disable navigation stop-avoidance

Note [1]: Map ID is generally used in multi-floor navigation. For a single grid map, the map ID defaults to 0. To check the map ID, navigate to the broker or robot_server folder under ~/jy_cog/system/conf and open map.toml.

Note [2]: When using RL gaits (L-walking and mountain), body height adjustment and ground type selection are not supported.

Note [3]: When using straight-line navigation, if global planning cannot be done in a straight line between two points, the navigation task will fail. When using autonomous navigation, set waypoints according to terrain complexity; higher complexity means higher risk, so set denser waypoints. Prefer multiple straight-line navigation segments over autonomous navigation.

Note [4]: Regardless of whether the navigation module’s stop-avoidance is enabled, the height map’s stop-avoidance function always remains active as the robot dog’s safety module (except in accumulated frame mode segments). When navigation stop-avoidance is enabled, for straight-line navigation it behaves as stop-at-obstacle, and for autonomous navigation it behaves as avoid-obstacle.

Multi-Point Navigation Execution

There are two ways to execute multi-point navigation: using the gamepad and using the player. The gamepad can only execute navigation tasks with a total point count (route points × loop count) not exceeding 100.

Ensure the localization/navigation program is started and initial localization is provided before execution.

Execute Navigation Directly on Gamepad

1. Click [View Route List], select a route from the list, and click the execute button.

2. Set the loop count, then click [Execute Navigation].

The total point count (route points × loop count) on the gamepad must not exceed 100.

3. During execution, click [End Execution] to exit navigation.

Execute Navigation with Player

For total point counts exceeding 100, use the player.

1. Select the route to execute, click [Sync] to sync it to the navigation host.
2. Refer to Remote Login to connect to the navigation host. Navigate to ~/jy_cog/system/data and check for the synced route file.

The synced filename is “gamepad ID + route name.json”. If the route name is in Chinese, it will be converted to pinyin after syncing.

3. Navigate to ~/jy_cog/system/conf/player and open config.toml. Change points_path to the route file path.
4. Modify other parameters in config.toml as needed:

• End_wait_time: Stop time at the last point, in seconds
• times: Loop count for navigation route execution
• charger_time: Charging duration at the charging point, in seconds

5. Save and close config.toml.
6. Open a new terminal and run the player:

   cd ~/jy_cog/player/scripts
   bash player.sh

7. To end navigation, press ctrl+c in the terminal running the player.

Localization Troubleshooting

When point cloud is missing or localization is poor, check the following topics:

Check LiDAR point cloud topic:

rostopic hz /lidar_points
# Should show data with average rate close to 10Hz

Check IMU topic:

rostopic hz /imu/data
# Should show data with average rate close to 200Hz

Check leg odometry topic:

rostopic hz /leg_odom
# Should show data with average rate close to 200Hz

If all topics are normal but localization is still abnormal, check if the 3D point cloud map matches the actual environment per View Point Cloud Map. Rebuild the map if it doesn’t match.

Indoor Multi-Floor Navigation

Please read this section after understanding single-floor navigation.

Multi-floor navigation differs from single-floor in two main ways:

1. Localization initialization must be done in the 3D point cloud map;
2. During deployment, switching between multiple grid maps is required by changing the waypoint’s map ID.

Localization Initialization

After starting navigation, if the LiDAR point cloud does not fully overlap with the grid map, initialize the robot dog’s localization.

1. Ensure the Type under Views in the right panel of RViz is Orbit.
2. Adjust the view to a top-down perspective.
3. Select the [3D Pose Estimate] tool from the toolbar.

4. Determine the position on the xy plane: Using the grid map as reference, find the corresponding position and orientation on the map based on the robot dog’s actual position and orientation. Hold the left button at the corresponding position and drag an arrow in the correct orientation direction, then release.
5. Continue adjusting the view: Hold the left button and drag to observe horizontally, determining the robot dog’s actual height (floor).

Do not use the right button to change the view at this point; dragging the right button will change the localization position.

6. Determine the z-axis height: Hold the right button and drag the mouse to move the localization arrow to the correct floor height, then release to publish the initial pose.

Map Switching

When marking navigation waypoints, click the switch map ID button and enter the map ID corresponding to the current grid map in map.toml.

When marking the first waypoint, confirm that the default map ID matches the actual grid map ID.

When marking a floor transition waypoint at the landing connecting two floors, click the switch button next to the map ID to switch to the next floor’s grid map ID.

Ensure the floor transition waypoint is reachable on both floors’ grid maps.