Skip to content

Commit e0fff31

Browse files
andrewjongandrewjong
committed
Add openhands microagent
1 parent 12cec6a commit e0fff31

File tree

1 file changed

+121
-0
lines changed

1 file changed

+121
-0
lines changed

‎.openhands/microagents/repo.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# AirStack Repository Overview
2+
3+
## Purpose
4+
5+
AirStack is a comprehensive, modular autonomy stack for embodied AI and robotics developed by the [AirLab](https://theairlab.org) at Carnegie Mellon University's Robotics Institute. It provides a complete framework for developing, testing, and deploying autonomous mobile systems in both simulated and real-world environments.
6+
7+
**Key Features:**
8+
- Modular architecture allowing easy component swapping and customization
9+
- ROS 2-based inter-process communication
10+
- Integrated NVIDIA Isaac Sim support for high-fidelity simulation
11+
- Multi-robot capability for coordinated operations
12+
- Comprehensive autonomy stack covering interface, sensors, perception, planning, control, and behavior management
13+
- Ground Control Station for monitoring and control
14+
15+
**Current Status:** ALPHA - Internal usage only, requires AirLab account access
16+
17+
## General Setup
18+
19+
AirStack uses a Docker-based development environment with the following setup approach:
20+
21+
### Prerequisites
22+
- Docker with NVIDIA Container Toolkit support
23+
- NVIDIA GPU (RTX 3070 or better recommended for Isaac Sim)
24+
- At least 25GB free storage space
25+
- Ubuntu 22.04 (recommended)
26+
27+
### Installation Process
28+
1. Clone repository with submodules: `git clone --recursive -j8 git@github.com:castacks/AirStack.git`
29+
2. Install dependencies: `./airstack.sh install` (installs Docker and docker-compose)
30+
3. Setup environment: `./airstack.sh setup` (configures CLI tool and keys)
31+
4. Pull Docker images from AirLab registry or build from scratch
32+
5. Launch system: `airstack up` (starts robot, ground control station, and Isaac Sim)
33+
34+
### Docker Images
35+
- **Option 1 (Preferred):** Pull from AirLab Docker registry (`airlab-storage.andrew.cmu.edu:5001`)
36+
- **Option 2:** Build from scratch (requires NVIDIA NGC access and Ascent Spirit SITL package)
37+
38+
## Repository Structure
39+
40+
```
41+
AirStack/
42+
├── robot/ # Robot autonomy stack (ROS 2 workspace)
43+
│ ├── docker/ # Robot containerization
44+
│ ├── installation/ # Robot setup scripts
45+
│ └── ros_ws/src/autonomy/ # Layered autonomy modules:
46+
│ ├── 0_interface/ # Robot interface layer
47+
│ ├── 1_sensors/ # Sensor integration
48+
│ ├── 2_perception/ # State estimation & environment understanding
49+
│ ├── 3_local/ # Local planning, world model, and control
50+
│ ├── 4_global/ # Global planning and mapping
51+
│ └── 5_behavior/ # High-level decision making
52+
├── ground_control_station/ # Monitoring and control interface
53+
│ ├── docker/ # GCS containerization
54+
│ └── ros_ws/ # GCS ROS 2 workspace
55+
├── simulation/ # Simulation environments
56+
│ ├── isaac-sim/ # NVIDIA Isaac Sim integration
57+
│ └── gazebo/ # Gazebo simulation support
58+
├── docs/ # MkDocs documentation
59+
├── common/ # Shared libraries and utilities
60+
├── tests/ # Testing infrastructure
61+
├── git-hooks/ # Git hooks for development workflow
62+
├── .airstack/ # CLI tool modules
63+
├── airstack.sh # Main CLI tool script
64+
├── docker-compose.yaml # Top-level compose file (includes all components)
65+
├── .env # Environment configuration
66+
└── mkdocs.yml # Documentation configuration
67+
```
68+
69+
### Key Configuration Files
70+
- **docker-compose.yaml**: Top-level compose file that includes all component compose files
71+
- **.env**: Main environment configuration with Docker image tags, launch parameters, and simulation settings
72+
- **mkdocs.yml**: Documentation site configuration with comprehensive navigation structure
73+
- **airstack.sh**: Unified CLI tool for development tasks and container management
74+
75+
## CI/CD and Development Workflow
76+
77+
### GitHub Actions Workflows
78+
79+
**Docker Build Pipeline** (`.github/workflows/docker-build.yml`):
80+
- Triggers on pushes to `main` branch when Docker-related files change
81+
- Builds and pushes both x86-64 and ARM64 (L4T) images to GitHub Container Registry
82+
- Uses AirLab Docker registry credentials
83+
84+
**Documentation Deployment**:
85+
- **Main Branch** (`deploy_docs_from_main.yaml`): Deploys docs to main version on pushes to `main`
86+
- **Develop Branch** (`deploy_docs_from_develop.yaml`): Deploys docs to develop version on pushes to `develop`
87+
- **Release** (`deploy_docs_from_release.yaml`): Deploys docs to versioned release on GitHub releases
88+
- Uses MkDocs Material with mike for versioning
89+
- Deploys to `docs.theairlab.org`
90+
91+
### Development Tools
92+
93+
**Git Hooks**:
94+
- Docker versioning hook automatically updates `DOCKER_IMAGE_TAG` in `.env` with git commit hash when Docker files are modified
95+
- Ensures Docker images are tagged with exact commit for version consistency across branches
96+
97+
**CLI Tool** (`airstack.sh`):
98+
- Modular command system with extensible modules in `.airstack/modules/`
99+
- Provides unified interface for setup, installation, and container management
100+
- Color-coded output and comprehensive help system
101+
102+
**Pull Request Template**:
103+
- Structured template requiring description, implementation details, testing information, and documentation updates
104+
- Emphasizes video/image documentation and comprehensive testing
105+
106+
### Code Quality and Standards
107+
- ROS 2-based architecture with standardized package structure
108+
- Docker-first development approach for consistent environments
109+
- Comprehensive documentation with MkDocs Material
110+
- Modular design enabling component-level development and testing
111+
112+
### Building Code, Running, and Testing
113+
Because everything runs within Docker containers, testing is primarily done through tests within the containerized environment. Unit tests for individual ROS 2 packages can be added as needed.
114+
Do not run tests directly on the host machine, instead run tests within the appropriate container, e.g. any tests for anything under robot/ros_ws should run within the robot container.
115+
116+
You can launch the robot docker container with this command: `AUTOLAUNCH=false ./airstack.sh up robot`. After that, you must interact with the docker container by running docker commands, and NOT in interactive CLI mode because you get stuck on interactive prompts. So run things as `docker exec airstack-robot-1 bash -c "<command>"`.
117+
118+
The code can be built in the correct workspace with the `bws` command, and it passes appended arguments to `colcon build`, for example `--packages select`.
119+
120+
### Debugging
121+
To enable breakpointing, add the following to your colcon build : `--cmake-args -DCMAKE_BUILD_TYPE=Debug`.

0 commit comments

Comments
 (0)