Skip to content

SETUP.md

Latest commit

 

History

History
220 lines (156 loc) · 5.94 KB

SETUP.md

File metadata and controls

220 lines (156 loc) · 5.94 KB
Raw

AP1 Developer Setup Guide

Prerequisites

  • Ubuntu (with ROS2 Jazzy installed at /opt/ros/jazzy)
  • uv installed (install guide)
  • zsh or bash
  • colcon build tool

Option 1 -- Script (Recommended)

This script will auto detect if you're using zsh or bash and other environment variables. You may need to give sudo permissions to the script.s

chmod +x ap1_setup.sh
./ap1_setup.sh

By default, the script imports any missing repos from ap1.repos using vcs import --skip-existing, builds the workspace, and prints the source/export commands to run in your terminal. It does not edit your shell rc file unless you opt in:

./ap1_setup.sh --write-rc

If you already imported the repos yourself and want setup to skip that step:

./ap1_setup.sh --no-vcs

Option 2 -- Manually (If Script Doesn't Work)

1. Clone the Workspace

mkdir -p ~/Documents/ap1
cd ~/Documents/ap1

vcs import < ap1.repos

Run vcs import from the workspace root. The paths in ap1.repos already include src/, so importing from inside src/ creates nested paths such as src/src/perception.

2. Set Up the Perception Python Environment

The perception package uses uv to manage its Python dependencies (ultralytics, onnxruntime, PyQt5, torch, etc.).

cd ~/path_to_ap1/ap1/src/perception
uv sync

This creates a .venv inside the perception folder with all pinned dependencies from uv.lock.

3. Expose the Perception venv to ROS2

ROS2 uses the system Python (/usr/bin/python3) to launch nodes, so it does not respect the active venv automatically. You need to add the venv's site-packages to PYTHONPATH in each terminal where you run AP1.

export PYTHONPATH=/home/$USER/rest_of_path/ap1/src/perception/.venv/lib/python3.12/site-packages:$PYTHONPATH

⚠️ If your username or workspace path differs, adjust accordingly.

4. Build the Workspace

Important: Always run colcon build from the workspace root (~/Documents/ap1), NOT from inside src/. Building from inside src/ puts build/, install/, and log/ in the wrong place and ROS2 won't find your packages.

cd ~/Documents/ap1

source /opt/ros/jazzy/setup.bash
rosdep install --from-paths src --ignore-src -r -y

colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release

Tip: For C++ IDE support (clangd autocomplete in ap1_control/ap1_planning, i.e., this is mainly for planning & control team):

colcon build --cmake-args -DCMAKE_EXPORT_COMPILE_COMMANDS=1
cp build/compile_commands.json .

5. Source the Workspace

After a successful build, source the overlay. Do this in every new terminal before running any ROS2 commands.

source /opt/ros/jazzy/setup.bash
source ~/Documents/ap1/install/setup.bash

💡 To avoid doing this manually every time, add these lines to your ~/.zshrc or ~/.bashrc, or run ./ap1_setup.sh --write-rc:

echo 'source /opt/ros/jazzy/setup.bash' >> ~/.zshrc
echo 'source ~/Documents/ap1/install/setup.bash' >> ~/.zshrc

6. Launch the System

Full System (all nodes)

ros2 launch ap1_bringup full_system.launch.py

Planning & Control only

ros2 launch ap1_bringup pnc_backend.launch.py

Mapping & Localization pipeline only

ros2 launch mapping_localization_python mapping_pipeline.launch.py

# With Kitware SLAM enabled:
ros2 launch mapping_localization_python mapping_pipeline.launch.py use_kitware_slam:=true

# With synthetic perception data (no real sensors needed):
ros2 launch mapping_localization_python mapping_pipeline.launch.py use_synthetic_perception:=true

Console UI only

ros2 run ap1_console console

7. Replay a Recorded RealSense Bag

RealSense .bag files are not ROS2 bags, so replay them through realsense2_camera instead of ros2 bag play.

source /opt/ros/jazzy/setup.bash
source ~/Documents/ap1/install/setup.bash

ros2 launch realsense2_camera rs_launch.py \
  rosbag_filename:=/absolute/path/to/recording.bag \
  align_depth.enable:=true \
  pointcloud.enable:=true \
  rosbag_loop:=false

Use pointcloud.enable:=true so perception nodes that subscribe to /camera/camera/depth/color/points receive data. Prefer rosbag_loop:=false for integration testing; looping can replay/reset quickly and make logs hard to read.

Quick topic checks:

ros2 topic hz /camera/camera/color/image_raw
ros2 topic hz /camera/camera/depth/color/points
ros2 topic echo --once /ap1/perception/lanes
ros2 topic echo --once /ap1/mapping/lanes

8. Verify Everything is Running

# List all active nodes
ros2 node list

# Expected nodes on fullsystem launch:
# /ap1_control
# /ap1_planning
# /ap1_yolo
# /ap1_ufld_ground
# /ap1_console
# /perception_pipeline
# /stored_point_registry
# /slam_bridge
# /base_to_lidar_tf

# Check a topic is publishing
ros2 topic echo /ap1/localization/slam_pose

Quick Reference — Every New Terminal

source /opt/ros/jazzy/setup.bash
source ~/Documents/ap1/install/setup.bash
ros2 launch ap1_bringup full_system.launch.py

Troubleshooting

Error Cause Fix
Package 'ap1_bringup' not found colcon build was run from inside src/ rm -rf src/build src/install src/log then rebuild from workspace root
No module named 'ultralytics' Perception venv not on PYTHONPATH Add venv site-packages to PYTHONPATH (see Step 3)
No module named 'onnxruntime' Same as above Same fix
No module named 'PyQt6' Console requires PyQt6 pip install PyQt6 into the active venv
All nodes shut down immediately A CriticalNode crashed (usually yolo_node) Fix the crashing node first — it takes down the whole system on exit
WARN: Velocity is null / necessary field is null Normal at startup Nodes are waiting for sensor data — not an error