Allow launch overrides

.env

@@ -1,14 +1,60 @@
+# This is the main .env file for AirStack, which sets docker compose variables for variable interpolation.
+# Standard Usage: docker compose --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.
+
+# =============== PROJECT ====================
 # This top-level .env file under AirStack/ defines variables that are propagated through docker-compose.yaml
 PROJECT_NAME="airstack"
-# auto-generated from git commit hash
+# Auto-generated from git commit hash
 DOCKER_IMAGE_TAG="f3f93a5"
-# can replace with your docker hub username
+# Can replace with your docker hub username
 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"
 PLAY_SIM_ON_START="true"
-# the file under robot/docker/ that contains the robot's environment variables
-ROBOT_ENV_FILE_NAME="robot.env"
+# =============================================
+
+# ================= ROBOT =====================
+# See robot/docker/docker-compose.yaml for how these variables get propagated in 
+# the container's entry command.
+ROBOT_LAUNCH_PACKAGE="robot_bringup"
+ROBOT_LAUNCH_FILE="robot.launch.xml"
+
+# See robot-base-docker-compose.yaml for how these variables get propagated. 
+# We use relative launch path (not file) because these are launch files get included
+# from the top level robot launch file, and the include-format requires a path.
+AUTONOMY_LAUNCH_PACKAGE="autonomy_bringup"
+AUTONOMY_LAUNCH_PATH="launch/autonomy.launch.xml"
+# --
+INTERFACE_LAUNCH_PACKAGE="interface_bringup"
+INTERFACE_LAUNCH_PATH="launch/interface.launch.xml"
+# --
+SENSORS_LAUNCH_PACKAGE="sensors_bringup"
+SENSORS_LAUNCH_PATH="launch/sensors.launch.xml"
+# --
+PERCEPTION_LAUNCH_PACKAGE="perception_bringup"
+PERCEPTION_LAUNCH_PATH="launch/perception.launch.xml"
+# --
+LOCAL_LAUNCH_PACKAGE="local_bringup"
+LOCAL_LAUNCH_PATH="launch/local.launch.xml"
+# --
+GLOBAL_LAUNCH_PACKAGE="global_bringup"
+GLOBAL_LAUNCH_PATH="launch/global.launch.xml"
+# --
+BEHAVIOR_LAUNCH_PACKAGE="behavior_bringup"
+BEHAVIOR_LAUNCH_PATH="launch/behavior.launch.xml"
+# ===============================================
 
-# format as "[package_name] [launch_file_name]"
-ROBOT_MAIN_LAUNCH="robot_bringup robot.launch.xml"
-GCS_MAIN_LAUNCH="gcs_bringup gcs.launch.xml"
+# =========== GROUND CONTROL STATION ============
+# See ground_control_station/docker/docker-compose.yaml for how these variables 
+# get propagated in the container's entry command.
+GCS_LAUNCH_PACKAGE="gcs_bringup"
+GCS_LAUNCH_FILE="gcs.launch.xml"
+# ===============================================

airstack.sh

@@ -34,7 +34,7 @@ function print_usage {
     echo "Available commands:"
 
     # Sort commands alphabetically
-    local sorted_ommands=($(echo "${!COMMANDS[@]}" | tr ' ' '\n' | sort))
+    local sorted_commands=($(echo "${!COMMANDS[@]}" | tr ' ' '\n' | sort))
 
     # Calculate the longest command name for padding
     local max_len=0
@@ -505,9 +505,58 @@ function cmd_setup {
 function cmd_up {
     check_docker
 
-    # Build docker-compose command
-    local cmd="docker compose -f $PROJECT_ROOT/docker-compose.yaml up $@ -d"
+    local env_files=()
+    local other_args=()
+
+    # Convert arguments to array for easier processing
+    local args=("$@")
+    local i=0
+
+    while [ $i -lt ${#args[@]} ]; do
+        local arg="${args[$i]}"
+
+        if [[ "$arg" == "--env-file" ]]; then
+            # Get the next argument as the env file path
+            i=$((i+1))
+            if [ $i -lt ${#args[@]} ]; then
+                env_files+=("--env-file" "${args[$i]}")
+            else
+                log_error "Missing value for --env-file argument"
+                return 1
+            fi
+        elif [[ "$arg" == "--env-file="* ]]; then
+            # Handle --env-file=path format
+            env_files+=("$arg")
+        else
+            # Skip the command name 'up' itself
+            if [[ "$arg" != "up" ]]; then
+                other_args+=("$arg")
+            fi
+        fi
+
+        i=$((i+1))
+    done
+
+    # Build docker-compose command with env files before the 'up' command
+    local cmd="docker compose -f $PROJECT_ROOT/docker-compose.yaml"
+
+    # Add all env files
+    for env_file in "${env_files[@]}"; do
+        cmd="$cmd $env_file"
+    done
+
+    # Add the 'up' command and other arguments
+    cmd="$cmd up"
 
+    # Add other arguments if any
+    if [ ${#other_args[@]} -gt 0 ]; then
+        cmd="$cmd ${other_args[*]}"
+    fi
+
+    # Add -d flag
+    cmd="$cmd -d"
+
+    log_info "Executing: $cmd"
     eval "$cmd"
     log_info "Services brought up successfully"
 }
@@ -775,13 +824,41 @@ if [ $# -eq 0 ]; then
     exit 0
 fi
 
-command="$1"
-shift
+# Simple command detection - just look for the first argument that matches a command
+command=""
+
+# First check if the first argument is a command
+if [[ -n "${COMMANDS[$1]}" || "$1" == "commands" || "$1" == "help" ]]; then
+    command="$1"
+else
+    # Otherwise, look through all arguments for a command
+    for arg in "$@"; do
+        if [[ -n "${COMMANDS[$arg]}" || "$arg" == "commands" || "$arg" == "help" ]]; then
+            command="$arg"
+            break
+        fi
+    done
+
+    # If still no command found, show usage
+    if [ -z "$command" ]; then
+        print_usage
+        exit 1
+    fi
+fi
 
 # Check if command exists
 if [[ -n "${COMMANDS[$command]}" ]]; then
-    # Execute the command function
-    ${COMMANDS[$command]} "$@"
+    # Execute the command function with filtered arguments
+    # We need to remove the command name from the arguments
+    filtered_args=()
+    for arg in "$@"; do
+        if [[ "$arg" != "$command" ]]; then
+            filtered_args+=("$arg")
+        fi
+    done
+
+    # Execute the command with the filtered arguments
+    ${COMMANDS[$command]} "${filtered_args[@]}"
 elif [ "$command" == "commands" ]; then
     # Special case for listing all commands
     list_commands

docs/development/docker_usage.md

@@ -1,4 +1,4 @@
-# Workflow with Docker and Docker Compose
+# 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.
 
@@ -163,3 +163,32 @@ graph TD
     style D fill:#fbf,stroke:#333,stroke-width:2px
 
 ```
+
+## 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.
+
+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, this command disables playing the simulation on startup by overriding the `PLAY_SIM_ON_START` variable:
+```bash
+docker compose --env-file .env --env-file overrides/no_play_sim_on_start.env up -d
+```
+
+As another example, this command changes the perception launch file to `perception_no_macvo.launch.xml`:
+```bash
+docker compose --env-file .env --env-file overrides/no_macvo.env up -d
+```
+
+
+When overriding, the default `.env` file must be loaded first. The overrides are applied on top of it.
+
+
+

docs/getting_started.md

@@ -3,6 +3,10 @@
 !!! warning ""
 
     AirStack is currently in ALPHA and only meant for internal usage. 
+
+    We'd really appreciate your feedback and contributions to improve this project for everyone! 
+    Please join our #airstack channel on Slack to contribute or ask questions.
+
     You will need to have an account with AirLab to access the AirLab Docker registry, Nucleus server, and other resources.
     The API and functionality are not stable and are subject to change. 
 
@@ -16,6 +20,8 @@ You need at least 25GB free to install the Docker image.
 Check the hardware requirements for the NVIDIA Isaac Sim [here](https://docs.isaacsim.omniverse.nvidia.com/latest/installation/requirements.html).
 A GPU of GeForce RTX 4080 or higher is recommended for the best performance.
 
+AirStack is primarily tested on Ubuntu 22.04. 
+
 ## Clone
 ```bash
 git clone --recursive -j8 git@github.com:castacks/AirStack.git

ground_control_station/docker/ground-control-station-base-docker-compose.yaml

@@ -12,7 +12,7 @@ services:
       bash -c "ssh service restart;
       tmux new -d -s gcs_bringup
       && tmux send-keys -t gcs_bringup 
-      'bws && sws; ros2 launch ${GCS_MAIN_LAUNCH}' ENTER
+      'bws && sws; ros2 launch ${GCS_LAUNCH_PACKAGE} ${GCS_LAUNCH_FILE}' ENTER
       && sleep infinity"
     # Interactive shell
     stdin_open: true # docker run -i

overrides/no_macvo.env

@@ -0,0 +1,2 @@
+# run as docker compose --env-file .env --env-file overrides/no_macvo.env up
+PERCEPTION_LAUNCH_FILE="perception_no_macvo.launch.xml"

overrides/no_play_sim_on_start.env

@@ -0,0 +1,2 @@
+# run as docker compose --env-file .env --env-file overrides/no_play_sim_on_start.env up
+PLAY_SIM_ON_START="false"

robot/docker/docker-compose.yaml

@@ -23,7 +23,7 @@ services:
       tmux new -d -s robot_bringup
       && tmux send-keys -t robot_bringup 
       'bws && sws && 
-      ros2 launch ${ROBOT_MAIN_LAUNCH}' ENTER
+      ros2 launch ${ROBOT_LAUNCH_PACKAGE} ${ROBOT_LAUNCH_FILE}' ENTER
       && sleep infinity"
     # assumes you're connected to work internet, so creates a network to isolate from other developers on your work internet
     networks:
@@ -65,7 +65,7 @@ services:
       tmux new -d -s robot_bringup
       && tmux send-keys -t robot_bringup 
       'bws && sws && 
-      DATE=$(date | sed \"s/ /_/g\" | sed \"s/:/_/g\") ros2 launch robot_bringup robot.launch.xml sim:="false" ' ENTER
+      DATE=$(date | sed \"s/ /_/g\" | sed \"s/:/_/g\") ros2 launch ${ROBOT_LAUNCH_PACKAGE} ${ROBOT_LAUNCH_FILE} sim:="false" ' ENTER
       && sleep infinity"
     runtime: nvidia
     # assumes network isolation via a physical router, so uses network_mode=host

robot/docker/robot-base-docker-compose.yaml

@@ -10,8 +10,27 @@ services:
     environment:
       - DISPLAY
       - QT_X11_NO_MITSHM=1
-    env_file:
-      - ${ROBOT_ENV_FILE_NAME}
+      # docker compose interpolation to env variables
+      - AUTONOMY_LAUNCH_PACKAGE=${AUTONOMY_LAUNCH_PACKAGE}
+      - AUTONOMY_LAUNCH_PATH=${AUTONOMY_LAUNCH_PATH}
+      # --
+      - INTERFACE_LAUNCH_PACKAGE=${INTERFACE_LAUNCH_PACKAGE}
+      - INTERFACE_LAUNCH_PATH=${INTERFACE_LAUNCH_PATH}
+      # --
+      - SENSORS_LAUNCH_PACKAGE=${SENSORS_LAUNCH_PACKAGE}
+      - SENSORS_LAUNCH_PATH=${SENSORS_LAUNCH_PATH}
+      # --
+      - PERCEPTION_LAUNCH_PACKAGE=${PERCEPTION_LAUNCH_PACKAGE}
+      - PERCEPTION_LAUNCH_PATH=${PERCEPTION_LAUNCH_PATH}
+      # --
+      - LOCAL_LAUNCH_PACKAGE=${LOCAL_LAUNCH_PACKAGE}
+      - LOCAL_LAUNCH_PATH=${LOCAL_LAUNCH_PATH}
+      # --
+      - GLOBAL_LAUNCH_PACKAGE=${GLOBAL_LAUNCH_PACKAGE}
+      - GLOBAL_LAUNCH_PATH=${GLOBAL_LAUNCH_PATH}
+      # --
+      - BEHAVIOR_LAUNCH_PACKAGE=${BEHAVIOR_LAUNCH_PACKAGE}
+      - BEHAVIOR_LAUNCH_PATH=${BEHAVIOR_LAUNCH_PATH}
     deploy:
       # let it use the GPU
       resources:

robot/ros_ws/src/autonomy/2_perception/perception_bringup/launch/perception.launch.xml

@@ -4,7 +4,7 @@
     <!-- State Estimation -->
     <!-- Visual Odometry -->
 
-    <!-- <node pkg="macvo" exec="macvo" if="$(env USE_MACVO)">
+    <!-- <node pkg="macvo" exec="macvo">
         <param name="camera_config" value="$(find-pkg-share macvo)/config/model_config.yaml" />
         <param from="$(find-pkg-share macvo)/config/interface_config.yaml" />
         <remap from="left/image_rect"
@@ -19,7 +19,7 @@
             to="/$(env ROBOT_NAME)/perception/visual_odometry_points" />
         <remap from="visual_odometry_img" to="/$(env ROBOT_NAME)/perception/visual_odometry_img" />
     </node> -->
-    <node pkg="macvo2" exec="macvo2" if="$(env USE_MACVO)">
+    <node pkg="macvo2" exec="macvo2">
         <param name="camera_config" value="$(find-pkg-share macvo2)/config/model_config.yaml" />
         <param from="$(find-pkg-share macvo2)/config/interface_config.yaml" />
         <remap from="left/image_rect"

robot/ros_ws/src/autonomy/2_perception/perception_bringup/launch/perception_no_macvo.launch.xml

@@ -0,0 +1,20 @@
+<!-- PERCEPTION -->
+<launch>
+    <!-- Depth Estimation -->
+    <!-- Disparity -->
+    <node pkg="stereo_image_proc" exec="disparity_node"
+        namespace="stereo_image_proc">
+        <remap from="left/image_rect" to="/$(env ROBOT_NAME)/sensors/front_stereo/left/image_rect" />
+        <remap from="left/camera_info" to="/$(env ROBOT_NAME)/sensors/front_stereo/left/camera_info" />
+        <remap from="right/image_rect" to="/$(env ROBOT_NAME)/sensors/front_stereo/right/image_rect" />
+        <remap from="right/camera_info"
+            to="/$(env ROBOT_NAME)/sensors/front_stereo/right/camera_info" />
+    </node>
+
+    <!-- Visualizer -->
+    <node pkg="image_view" exec="disparity_view"
+        namespace="disparity_view">
+        <remap from="image" to="/$(env ROBOT_NAME)/stereo_image_proc/disparity" />
+    </node>
+
+</launch>