amaze-nav

Documentation: README · Setup · Framework · Methodology · Perception strategy · Perception API · Task ownership · Development plan · Ground-truth survey · Controller debug · Navigator tests · Offline tests · RViz & debugging

Perception Module v1.1 — standalone LiDAR perception and trajectory planning baseline. This is the component version, not a release version for the overall amaze-nav project.

LiDAR-based perception, obstacle avoidance, and autonomous TurtleBot maze navigation with ROS 2.

Course project for MEC-E5012 Vehicle Mechatronics: Control, Aalto University.

The TurtleBot must navigate a 5 × 5 graph maze without collisions. Node positions are known, but some passages are blocked or require steering around obstacles. We combine LiDAR perception, local control, and A* replanning; the implementation must generalize to different obstacle configurations, not rely on a prerecorded obstacle map.

The provided navigator uses FOLLOW → BACKTRACK → REPLAN → FOLLOW for blocked passages and DONE on arrival. Status (12 October 2026): Perception, local motion planning, and ROS 2 navigation/control are integrated in an executable Gazebo baseline. One observed setup reached three checkpoints in approximately 2 min 30 s. This is a partial-run observation, not a full-track completion time or evidence of repeatable collision-free operation.

• Perception Module v1.1 — planning strategy — start here: destination-first decisions, LiDAR gap detection, trajectory rejection, opening fallbacks, recovery, and replanning.
• Perception Module v1.1 — API and integration — exact functions, motion plans, 14 strategy labels, and controller contract.
• Environment setup — clone the repository, configure ROS 2 and Gazebo model paths, build, launch, and troubleshoot.
• Provided framework & function guide — what's already implemented versus TODOs, modes, ROS interfaces.
• Perception & navigation methodology — two-stage passability (cross-sectional gap screening + short-horizon motion clearance), pure pursuit, optional LiDAR centering, and alternatives.
• Team responsibilities — suggested owners, deliverables, definitions of done, interface agreements.
• Two-day implementation plan — integration sequence, priorities, risks, lightweight collaboration.
• Edge passability ground-truth survey — manually investigate all 40 edges and record evidence before evaluating perception.
• Controller-only debug tests — reversible straight, turn, and loop mocked paths in the obstacle-free world.
• Offline navigation tests — ROS-free unit and state-machine integration tests (scenarios A–E).
• Navigator acceptance tests — repeatable teleport tests, four priority edges, integration checks.
• RViz & debugging — available topics, optional markers, and data to monitor.

The repository already contains the extracted vmc2_project/, project_track/, and project_track_no_obs/ directories. No separate archive download or extraction is required. In the course's Ubuntu / ROS 2 Humble environment, use the documented layout: repo root $HOME/shared/amaze-nav (assumed current directory), ROS workspace $HOME/shared/ros2_ws, and Gazebo models $HOME/.gazebo/models. Follow Environment setup to install the package and models.

After following that guide to install the local ROS package and models, set GAZEBO_MODEL_PATH, build/source the workspace, and launch:

export REPO_ROOT="$HOME/shared/amaze-nav"
export ROS_WS="$HOME/shared/ros2_ws"
export MAZE_MODELS="$HOME/.gazebo/models"
export GAZEBO_MODEL_PATH="$MAZE_MODELS${GAZEBO_MODEL_PATH:+:$GAZEBO_MODEL_PATH}"
cd "$ROS_WS"
colcon build --symlink-install --packages-select vmc2_project
source "$ROS_WS/install/setup.bash"
ros2 launch vmc2_project project.launch.py

Then open a second sourced terminal to run the autonomous navigator:

PYTHONPATH="/usr/lib/python3/dist-packages${PYTHONPATH:+:$PYTHONPATH}" \
  ros2 run vmc2_project navigator.py

For interactive LiDAR / trajectory inspection, run cd "$HOME/shared/amaze-nav" && bash tools/run_lidar_explorer.sh in a separate ROS-sourced terminal. The updated launcher resolves the sibling workspace $HOME/shared/ros2_ws and runs tools/lidar_explorer.py and requires tools/perception_geometry.py plus the installed workspace’s perception.py. The explorer visualizes candidate paths but does not drive the robot. Explorer mnemonics include a (auto current-edge tracking once per second, refreshing the passability slice on every update), c (current forward edge, node-aware heading selection, and passability rejection slice (or narrowest relevant forward gap slice)), t (trajectory), p (profile), b (blockage check), and v (view); Vim-style j/k adjust the slice and h/l change the edge; z/x adjust curvature. See the complete key table. Detailed prerequisites, controls, ROS terminal setup, and troubleshooting: Setup — run navigator and explorer and RViz & debugging. Never run teleoperation alongside autonomous navigation.

Use the ground-truth survey for teleoperation or navigator tests for repeatable acceptance tests. Use the obstacle-free model for initial controller tests; consult the launch file for how that world is selected.

• Implemented: Fresh LiDAR observations, gap/passability analysis, local motion plans, pure-pursuit tracking, PID-assisted rotation and selective narrow-passage centering, in-place turning, forward-only return to the previous node, and A* rerouting after a confirmed blockage.
• Narrow entrance handling: The current experimental planner can propose a short, observed-return-checked repositioning approach toward the opening center axis, followed by heading alignment, a new scan, and entry planning. This is not a sideways translation and must not bypass clearance guards.
• Observed progress: The integrated setup achieved 3 checkpoints in roughly 2 minutes 30 seconds in Gazebo. The precise checkpoint identities, simulation-versus-wall-clock timing basis, and run conditions were not provided; record these in future runs for reproducibility.
• Still to validate: Full-track completion, runtime consistency across fresh worlds, correct blocked-edge decisions, and clearance at the narrowest passages.

Navigate without hitting walls, aim for the 2 min 30 s simulation-time full-run target (distinct from the observed three-checkpoint run of roughly the same duration), and achieve repeatable performance. Submit the course package and video evidence as specified in the assignment; see the test guide.

• Ki Chun Tong
• Shaan Salian
• Vo Dinh Nhan

Developed as part of MEC-E5012 Vehicle Mechatronics: Control at Aalto University. The initial ROS 2 navigation framework and Gazebo maze models are course materials.

The Sensor/Odom diagnostic windows use fixed-scale 340 × 340 px views (no per-scan zoom); the Edge Frame remains full-sized. They are shown immediately at startup and request always-on-top placement where supported.

LiDAR Explorer always uses the robot base pose from /odom (within 0.3 seconds of the LiDAR scan) for trajectory proposals. t runs the shared plan_motion() and logs both the planner result and the passability assessment. A compact NAV CHECK: UNKNOWN / BLOCKED / CLEAR label appears in the top-right of the Edge Frame; NO POSE means a sufficiently recent base pose is unavailable. The a key enables or disables once-per-second current-edge tracking and refreshes the passability slice even when the edge is unchanged. c still manually refreshes the edge and slice. The slice coordinate s is displayed in the bottom-right corner.

The defaults match the navigator's 0.089 m robot radius, 0.03 m safety margin, and 8.0 1/m maximum curvature. z/x and m/n still adjust local trajectory experiments; the NAV CHECK passability label uses the navigator's fixed default clearance threshold, so it is not affected by the experimental controls. b logs the detailed passability reason. An UNKNOWN status does not mean the edge is clear.

Important: The status applies to the explorer's selected edge, not necessarily the navigator's live A* edge. It is a navigator-like perception diagnostic, not a replay of the navigation state machine, plan acceptance, collision guards, or pure-pursuit/PID commands. Feasible candidates are not guarantees that the navigator will execute them.