|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +AirStack is a comprehensive autonomous aerial robotics stack developed by AirLab CMU. It provides a complete end-to-end system for autonomous drone operations including simulation, robot control, and ground control station. |
| 8 | + |
| 9 | +## Key Components |
| 10 | + |
| 11 | +The repository is organized into four main components: |
| 12 | + |
| 13 | +- **robot/**: Onboard autonomy stack for drones (ROS 2 based) |
| 14 | +- **simulation/**: Isaac Sim integration and simulation environments |
| 15 | +- **gcs/**: Ground Control Station for mission planning and monitoring |
| 16 | +- **common/**: Shared ROS packages and utilities used across components |
| 17 | + |
| 18 | +## Development Commands |
| 19 | + |
| 20 | +### AirStack CLI Tool |
| 21 | +The project uses a custom CLI tool `./airstack.sh` for common operations: |
| 22 | + |
| 23 | +```bash |
| 24 | +# Setup and installation |
| 25 | +./airstack setup # Configure AirStack and add to PATH |
| 26 | +./airstack install # Install Docker and dependencies |
| 27 | + |
| 28 | +# Container management |
| 29 | +./airstack up [service] # Start services with Docker Compose |
| 30 | +./airstack stop [service] # Stop services |
| 31 | +./airstack status # Show container status |
| 32 | +./airstack connect [name] # Connect to running container (supports partial names) |
| 33 | +./airstack logs [name] # View container logs |
| 34 | + |
| 35 | +# Development tasks |
| 36 | +./airstack build # Build the workspace |
| 37 | +./airstack test # Run tests |
| 38 | +./airstack docs # Build documentation |
| 39 | +``` |
| 40 | + |
| 41 | +### ROS 2 Build Commands |
| 42 | +Inside robot containers, use these aliases: |
| 43 | +- `bws`: Build the ROS workspace (`colcon build`) |
| 44 | +- `sws`: Source the workspace (`source install/setup.bash`) |
| 45 | + |
| 46 | +### VSCode Integration |
| 47 | +The repository includes VSCode tasks: |
| 48 | +- **Build ros_ws Debug**: Builds ROS workspace in debug mode using `bws --cmake-args '-DCMAKE_BUILD_TYPE=Debug'` |
| 49 | + |
| 50 | +## Architecture |
| 51 | + |
| 52 | +### Robot Autonomy Stack (robot/ros_ws/src/autonomy/) |
| 53 | + |
| 54 | +The autonomy stack follows a layered architecture with numbered modules: |
| 55 | + |
| 56 | +- **0_interface/**: Robot hardware interface and safety monitors |
| 57 | + - `mavros_interface`: Communication with flight controller |
| 58 | + - `drone_safety_monitor`: Safety monitoring and emergency handling |
| 59 | + - `robot_interface`: High-level robot abstraction |
| 60 | + |
| 61 | +- **1_sensors/**: Sensor integration and processing |
| 62 | + - `camera_param_server`: Camera calibration management |
| 63 | + - `gimbal_stabilizer`: Gimbal control and stabilization |
| 64 | + - `sensor_interfaces`: Common sensor message definitions |
| 65 | + |
| 66 | +- **2_perception/**: State estimation and environment perception |
| 67 | + - `macvo_ros2`: Visual-inertial odometry system |
| 68 | + |
| 69 | +- **3_local/**: Local planning and control |
| 70 | + - `a_world_models/`: Local world representation |
| 71 | + - `disparity_expansion`: Obstacle detection from stereo |
| 72 | + - `disparity_graph`: Graph-based obstacle representation |
| 73 | + - `cost_map_interface`: Cost map utilities |
| 74 | + - `b_planners/`: Local motion planning |
| 75 | + - `droan_local_planner`: DROAN obstacle avoidance planner |
| 76 | + - `takeoff_landing_planner`: Specialized takeoff/landing |
| 77 | + - `trajectory_library`: Trajectory generation utilities |
| 78 | + - `c_controls/`: Low-level control |
| 79 | + - `trajectory_controller`: Trajectory tracking controller |
| 80 | + - `attitude_controller`: Attitude control |
| 81 | + - `pid_controller`: PID control utilities |
| 82 | + |
| 83 | +- **4_global/**: Global planning and mapping |
| 84 | + - `a_world_models/`: Global world representation |
| 85 | + - `vdb_mapping_ros2`: VDB-based 3D mapping |
| 86 | + - `b_planners/`: Global path planning |
| 87 | + - `random_walk`: Random exploration planner |
| 88 | + - `ensemble_planner`: Multi-planner coordination |
| 89 | + |
| 90 | +- **5_behavior/**: High-level mission execution |
| 91 | + - `behavior_tree`: Behavior tree framework |
| 92 | + - `behavior_executive`: Mission execution engine |
| 93 | + - `rqt_behavior_tree_command`: GUI for behavior tree control |
| 94 | + |
| 95 | +### Docker Architecture |
| 96 | + |
| 97 | +Each component has its own Docker setup: |
| 98 | +- `robot/docker/`: Robot container with ROS 2 and autonomy stack |
| 99 | +- `simulation/isaac-sim/docker/`: Isaac Sim simulation environment |
| 100 | +- `gcs/docker/`: Ground control station container |
| 101 | +- `docs/docker/`: Documentation building container |
| 102 | + |
| 103 | +The main `docker-compose.yaml` includes all component compose files for unified management. |
| 104 | + |
| 105 | +## Common Patterns |
| 106 | + |
| 107 | +### ROS 2 Launch Files |
| 108 | +- Bringup packages (`*_bringup/`) contain launch files for each subsystem |
| 109 | +- Launch files are organized by functionality and can be composed |
| 110 | +- Example: `ros2 launch robot_bringup robot.launch.py` |
| 111 | + |
| 112 | +### Configuration Management |
| 113 | +- Parameters stored in `config/` directories within packages |
| 114 | +- YAML files for node parameters and launch configurations |
| 115 | +- Environment variables configured in `.env` file |
| 116 | + |
| 117 | +### Testing |
| 118 | +- Test files located in `test/` directories within packages |
| 119 | +- Integration tests in `tests/` at repository root |
| 120 | + |
| 121 | +## Important Notes |
| 122 | + |
| 123 | +- The project uses ROS 2 Humble |
| 124 | +- Primary development is done in Docker containers |
| 125 | +- Documentation is built with MkDocs and hosted at docs.theairlab.org |
| 126 | +- The autonomy stack supports both simulation (SITL) and hardware deployment |
| 127 | +- Container networking uses custom bridge network (172.31.0.0/24) |
0 commit comments