Update scaling of robots to use replicas instead, much cleaner. Can now prepend NUM_ROBOTS=N

and Update docs about airstack cli

Author: andrewjong

.env

@@ -1,11 +1,8 @@
 # This is the main .env file for AirStack, which sets docker compose variables for variable interpolation.
-# Standard Usage: docker compose --env-file .env up
+# Standard Usage: airstack --env-file .env up
 
-# See overrides/ for overriding specific variables.
-# To override, run docker compose --env-file .env --env-file overrides/<override_file>.env up. Any variables set in 
-# the following --env-file will override previous ones.
-
-# Warning: all variables get propagated to all sub-level docker-compose files, so be careful about naming conflicts.
+# Warning: even though this file is organized into sections, all variables get propagated to all sub-level 
+#  docker-compose files, so be careful about naming conflicts.
 
 # =============== PROJECT ====================
 # These variables are used to tag the docker images.
@@ -18,13 +15,15 @@ PROJECT_DOCKER_REGISTRY="airlab-storage.andrew.cmu.edu:5001/shared"
 # ============================================
 
 # ================ SIMULATION =================
-DEFAULT_ISAAC_SCENE="omniverse://airlab-storage.andrew.cmu.edu:8443/Projects/AirStack/AFCA/fire_academy_faro_with_sky.scene.usd"
+ISAAC_SIM_SCENE="omniverse://airlab-storage.andrew.cmu.edu:8443/Projects/AirStack/AFCA/fire_academy_faro_with_sky.scene.usd"
 PLAY_SIM_ON_START="true"
 # =============================================
 
 # ================= ROBOT =====================
 # See robot/docker/docker-compose.yaml for how these variables get propagated in 
 # the container's entry command.
+NUM_ROBOTS="1"
+
 ROBOT_LAUNCH_PACKAGE="robot_bringup"
 ROBOT_LAUNCH_FILE="robot.launch.xml"
 

docs/development/airstack-cli/architecture.md

@@ -1,4 +1,4 @@
-# AirStack CLI Architecture
+# Advanced: AirStack CLI Architecture
 
 This document describes the architecture of the AirStack CLI tool, explaining how it's organized and how the different components work together.
 

docs/development/docker_usage.md …development/airstack-cli/docker_usage.mddocs/development/docker_usage.md renamed to docs/development/airstack-cli/docker_usage.md docs/development/docker_usage.md renamed to docs/development/airstack-cli/docker_usage.md

@@ -1,6 +1,8 @@
 # Launch Workflow with Docker and Docker Compose
 
-To mimic interacting with multiple real world robots, we use Docker Compose to manage Docker containers that isolate the simulation, each robot, and the ground control station.
+At its core, the `airstack` CLI is simply a wrapper around Docker Compose. `airstack up` is equivalent to `docker compose up -d`, and `airstack down` is equivalent to `docker compose down`.
+
+Docker Compose is useful to mimic interacting with multiple robots in a simulated environment, such as Isaac Sim, while isolating each robot's environment and the ground control station.
 
 The details of the docker compose setup is in the project root's `docker-compose.yaml`.
 
@@ -13,7 +15,7 @@ In essence, the compose file launches:
 all get created on the same default Docker bridge network.
 This lets them communicate with ROS2 on the same network.
 
-Each robot has its own ROS_DOMAIN_ID.
+Each robot has its own ROS_DOMAIN_ID, which is extracted from the container name, e.g. `airstack-robot-1` has `ROS_DOMAIN_ID=1`. See the robot `.bashrc` for details.
 
 ## Pull Images
 
@@ -42,33 +44,27 @@ docker compose build
 Start
 
 ```bash
-docker compose up --scale robot=[NUM_ROBOTS] -d
+airstack up  # or equivalently: docker compose up -d
 
 # see running containers
-docker ps -a
-```
-
-Stop
-
-```bash
-docker compose stop
+airstack status  # or equivalently: docker ps -a
 ```
 
 Remove
 
 ```bash
-docker compose down
+airstack down  # or equivalently: docker compose down
 ```
 
 Launch only specific services:
 
 ```bash
 # only robot
-docker compose up robot --scale robot=[NUM_ROBOTS] -d
+airstack up robot  # or equivalently: docker compose up robot -d
 # only isaac
-docker compose up isaac-sim -d
+airstack up isaac-sim  # or equivalently: docker compose up isaac-sim -d
 # only ground control station
-docker compose up gcs -d
+airstack up gcs  # or equivalently: docker compose up gcs -d
 ```
 
 
@@ -79,9 +75,7 @@ Start a bash shell in the Isaac Sim container:
 
 ```bash
 # if the isaac container is already running, execute a bash shell in it
-docker exec -it isaac-sim bash
-# or if not, start a new container
-docker compose run isaac-sim bash
+airstack connect isaac-sim  # or equivalently: docker exec -it isaac-sim bash
 ```
 
 Within the isaac-sim Docker container, the alias `runapp` launches Isaac Sim.
@@ -96,10 +90,17 @@ The container also has the isaacsim ROS2 package within that can be launched wit
 Start a bash shell in a robot container, e.g. for robot_1:
 
 ```bash
-docker exec -it airstack-robot-1 bash
+airstack connect robot  # or equivalently: docker exec -it airstack-robot-1 bash
 ```
 
-The previous `docker compose up` launches robot_bringup in a tmux session. To attach to the session within the docker container, e.g. to inspect output, run `tmux attach`.
+To launch more than one robot, prepend with the `NUM_ROBOTS=[NUM]` environment variable, e.g. to launch 2 robots (along with the ground control station and Isaac Sim):
+```bash
+NUM_ROBOTS=2 airstack up
+airstack connect robot-1  # to connect to robot 1
+airstack connect robot-2  # to connect to robot 2
+```
+
+The previous `docker compose up` launches robot_bringup in a tmux session. To attach to the session within the docker container, e.g. to inspect output, run `tmux a`.
 
 The following commands are available within the robot container:
 
@@ -112,7 +113,7 @@ sws  # sources workspace
 ros2 launch robot_bringup robot.launch.xml  # top-level launch
 ```
 
-These aliases are in `AirStack/robot/.bashrc`.
+These aliases are defined in `AirStack/robot/.bashrc`.
 
 Each robot has `ROS_DOMAIN_ID` set to its ID number. `ROBOT_NAME` is set to `robot_$ROS_DOMAIN_ID`.
 
@@ -123,7 +124,7 @@ Currently the ground control station uses the same image as the robot container.
 Start a bash shell in a robot container:
 
 ```bash
-docker exec -it ground-control-station bash
+airstack connect gcs  # or equivalently: docker exec -it ground-control-station bash
 ```
 
 The available aliases within the container are currently the same.
@@ -181,27 +182,31 @@ docker compose up autotest
 This command will spin up a `robot` container, build the ROS2 workspace, source the workspace and run all the configured tests for the provided packages using `colcon test`. Excessive output log from the build process is presently piped away to preserve readability.
 
 ## Docker Compose Variable Overrides
-Sometimes you may want to test different configurations of the autonomy stack. For example, you may want to disable automatically playing the sim on startup, 
-or to change a child launch file.
-
-The `docker compose` workflow is designed to support these overrides for local development.
-`docker compose` uses `.env` files to set docker-compose variables that get propagated and interpolated into `docker-compose.yaml` files.
-See the [docker compose documentation](https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/) for more details.
+As mentioned above, the `airstack` CLI is a wrapper around Docker Compose.
+Therefore, it supports [variable interpolation](https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/) in the `docker-compose.yaml` file, allowing you to adjust project settings by modifying environment variables.
 
-The default `.env` file is in the project root directory. 
-When no `--env-file` argument is passed to `docker compose`, it automatically uses this default `.env` file.
-
-To override the default `.env` file, you can pass the `--env-file` argument to `docker compose` with a path to your custom `.env` file.
+For example, to disable playing the simulation on startup, you can set the `PLAY_SIM_ON_START` variable to `false`:
+```bash
+PLAY_SIM_ON_START=false airstack up 
+```
 
-For example, this command disables playing the simulation on startup by overriding the `PLAY_SIM_ON_START` variable:
+To change the Isaac Sim scene:
 ```bash
-docker compose --env-file .env --env-file overrides/no_play_sim_on_start.env up -d
+ISAAC_SIM_SCENE=path/to/your_scene.usd airstack up
 ```
 
-As another example, this command changes the perception launch file to `perception_no_macvo.launch.xml`:
+A list of all available environment variables is in the default `.env` file in the project root directory, which allows specifying all the variables in one place.
+When no `--env-file` argument is passed to `docker compose`, it automatically uses this default `.env` file.
+
+The top-level env file is reproduced below:
 ```bash
-docker compose --env-file .env --env-file overrides/no_macvo.env up -d
+--8<-- ".env"
 ```
 
+To override the default `.env` file, you can pass the `--env-file` argument with the syntax `airstack --env-file [env_file] up` (or `docker compose --env-file [env_file] up -d`).
+
+Multiple `--env-file` arguments can be passed to compose overriding sets of variables.env` file.
+When overriding, the default `.env` file must be loaded first. The overrides are applied on top of it.
+
+
 
-When overriding, the default `.env` file must be loaded first. The overrides are applied on top of it.

docs/development/airstack-cli/extending.md

@@ -1,4 +1,4 @@
-# Extending the AirStack CLI
+# Advanced: Extending the AirStack CLI
 
 The AirStack CLI tool is designed to be easily extensible through modules. This guide explains how to create new modules and add commands to the AirStack CLI.
 

docs/development/airstack-cli/index.md

@@ -11,6 +11,8 @@ The AirStack CLI tool is designed to be:
 - **Helpful**: Includes detailed help text and error messages
 - **Extensible**: New commands can be added without modifying the core script
 
+At its core, `airstack.sh` is simply a light wrapper around [docker compose](https://docs.docker.com/compose/), providing additional functionality and convenience for AirStack development.
+
 ## Basic Usage
 
 ```bash
@@ -29,6 +31,18 @@ To get help for a specific command:
 ./airstack.sh help <command>
 ```
 
+## Adding to Shell Profile
+
+For convenience, you can add the AirStack CLI to your shell profile to make it available from any directory:
+
+```bash
+./airstack.sh setup
+# now you can use `airstack` instead of `./airstack.sh`
+airstack commands
+```
+
+This will add the necessary aliases to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.) so you can use the `airstack` command from any directory.
+
 ## Core Commands
 
 The AirStack CLI includes several built-in commands:
@@ -49,7 +63,7 @@ The AirStack CLI includes several built-in commands:
 The `install` command sets up the necessary dependencies for AirStack development:
 
 ```bash
-./airstack.sh install [options]
+airstack install [options]
 ```
 
 Options:
@@ -62,7 +76,7 @@ Options:
 The `setup` command configures your environment for AirStack development:
 
 ```bash
-./airstack.sh setup [options]
+airstack setup [options]
 ```
 
 Options:
@@ -75,19 +89,23 @@ The AirStack CLI provides several commands for managing Docker containers:
 
 ```bash
 # Start services
-./airstack.sh up [service...]
+airstack up [service...]
+airstack up robot  # start only the robot service
+airstack up isaac-sim  # start only the Isaac Sim service
+airstack up gcs  # start only the Ground Control Station service
+airstack up docs # start only the documentation service
 
 # Stop services
-./airstack.sh down [service...]
+airstack down [service...]
 
 # Show container status
-./airstack.sh status
+airstack status
 
-# Connect to a container shell
-./airstack.sh connect <container_name>
+# Connect to a container shell, supports partial name matching
+airstack connect <container_name>
 
 # View container logs
-./airstack.sh logs <container_name>
+airstack logs <container_name>
 ```
 
 ## Module-Specific Commands
@@ -98,37 +116,27 @@ In addition to the core commands, the AirStack CLI includes several module-speci
 
 ```bash
 # Run all configuration tasks
-./airstack.sh config
+airstack config
 
 # Configure Isaac Sim
-./airstack.sh config:isaac-sim
+airstack config:isaac-sim
 
 # Configure Nucleus
-./airstack.sh config:nucleus
+airstack config:nucleus
 
 # Configure Git hooks
-./airstack.sh config:git-hooks
+airstack config:git-hooks
 ```
 
 ### WinTAK Commands
 
 ```bash
 # Install WinTAK
-./airstack.sh wintak:install
+airstack wintak:install
 
 # Start WinTAK VM
-./airstack.sh wintak:start
+airstack wintak:start
 
 # Stop WinTAK VM
-./airstack.sh wintak:stop
+airstack wintak:stop
 ```
-
-## Adding to Shell Profile
-
-For convenience, you can add the AirStack CLI to your shell profile to make it available from any directory:
-
-```bash
-./airstack.sh setup
-```
-
-This will add the necessary aliases to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.) so you can use the `airstack` command from any directory.

docs/development/project_configuration.md

@@ -2,8 +2,8 @@
 
 Start containers
 ```bash
-# optionally pass the --scale robot=N argument to start N robots
-dc compose up -d  # --scale robot=2
+# optionally prepend NUM_ROBOTS=N argument to start N robots
+airstack up -d
 ```
 
 Open AirStack folder

docs/development/vscode/index.md

@@ -28,16 +28,6 @@ At a high level, the launch files are organized as follows:
 ### Desktop vs Jetson
 If you look at the `robot/docker/docker-compose.yaml` file, you'll see it contains two services. `robot` is meant for x86-64 desktop development whereas `robot_l4t` is meant to run on NVIDIA Jetson devices. Both extend a base service in `robot/docker/robot-base-docker-compose.yaml`.
 
-### Environment Variables
-Environment variables are used to configure the robot Docker container. The top level `AirStack/.env` file points to a `ROBOT_ENV_FILE_NAME` (default: `robot.env`), that in turn is used to load environment variables for the robot Docker container. The file that `ROBOT_ENV_FILE_NAME` points to gets added into the container under `robot/docker/robot-base-docker-compose.yaml`.
-
-The environment variables can be used to trigger nodes to launch. For example, the `USE_MACVO` environmental variable is checked by `perception.launch.xml` to determine whether to launch the `macvo` node.
-
-The file `robot.env` is reproduced below:
-```bash
---8<-- "robot/docker/robot.env"
-```
-
 ## Common Topics
 | Topic                          | Type              | Description                                                                                                                             |
 | -------------------------------| ------------------| ---------------------------------------------------------------------------------------------------------------------------|

docs/robot/index.md

@@ -49,11 +49,10 @@ nav:
       - docs/development/index.md
       - AirStack CLI Tool:
           - docs/development/airstack-cli/index.md
+          - docs/development/airstack-cli/docker_usage.md
           - docs/development/airstack-cli/extending.md
           - docs/development/airstack-cli/architecture.md
-      - docs/development/docker_usage.md
       - docs/development/vscode/index.md
-      - docs/development/project_configuration.md
       - Testing:
           - docs/development/testing/index.md
           - docs/development/testing/testing_frameworks.md

mkdocs.yml

@@ -32,6 +32,9 @@ services:
     ports:
       # for ssh, starting from 2223-2243 on the host port all map to 22 in the container. Assumes no more than 21 robots
       - "2223-2243:22"
+    # for multiple robots
+    deploy:
+      replicas: ${NUM_ROBOTS:-1}
 
   # -------------------------------------------------------------------------------------------------------------------
   # dev container for developer debugging