Update AirSim launch instructions and add headless mode support

Author: OasisArtisan

.env

@@ -11,7 +11,7 @@
 PROJECT_NAME="airstack"
 # If you've run ./airstack.sh setup, then this will auto-generate from the git commit hash every time a change is made 
 # to a Dockerfile or docker-compose.yaml file. Otherwise this can also be set explicitly to make a release version.
-VERSION="0.18.0-alpha.2"
+VERSION="0.18.0-alpha.3"
 # Choose "dev" or "prebuilt". "dev" is for mounted code that must be built live. "prebuilt" is for built ros_ws baked into the image
 DOCKER_IMAGE_BUILD_MODE="dev"  
 # Where to push and pull images from. Can replace with your docker hub username if using docker hub.

docs/simulation/index.md

@@ -86,7 +86,7 @@ An open-source drone simulator built on Unreal Engine with native PX4 SITL integ
 - Depth-based obstacle avoidance testing (DROAN)
 - Environments from the Unreal Engine ecosystem
 
-**Launch:** Set `SIM_IP=172.31.0.201` in `.env`, then `docker compose --profile ms-airsim --profile desktop up`
+**Launch:** `airstack up --env-file overrides/ms-airsim.env`
 
 **Location:** `simulation/ms-airsim/`
 

docs/simulation/ms-airsim/docker.md

@@ -69,8 +69,9 @@ The container runs `entrypoint.sh`, which:
 | `AUTOLAUNCH` | `true` | Auto-start on container launch |
 | `MS_AIRSIM_BINARY_PATH` | `/ms-airsim-env/Blocks.sh` | Path to UE4 binary inside container |
 | `MS_AIRSIM_ENV_DIR` | `../environments` | Host path to extracted UE4 environment |
+| `MS_AIRSIM_HEADLESS` | `false` | Run UE4 without a window (`-RenderOffScreen -nosound`) |
 | `NUM_ROBOTS` | `1` | Number of vehicles and PX4 SITL instances |
-| `SIM_IP` | *(set in `.env`)* | Must be `172.31.0.201` for Microsoft AirSim (legacy) |
+| `SIM_IP` | `172.31.0.200` | Simulator IP on `airstack_network` |
 
 **Camera template variables** (override in `.env` to regenerate `settings.json`):
 
@@ -88,9 +89,12 @@ The container runs `entrypoint.sh`, which:
 **Example overrides:**
 
 ```bash
-# Headless launch with two robots
+# Two robots
 NUM_ROBOTS=2 airstack up --profile ms-airsim
 
+# Headless (no GUI, uses UE4's -RenderOffScreen)
+MS_AIRSIM_HEADLESS=true airstack up --profile ms-airsim
+
 # Custom environment binary
 MS_AIRSIM_ENV_DIR=/data/airsim_envs MS_AIRSIM_BINARY_PATH=/ms-airsim-env/CityEnviron.sh airstack up --profile ms-airsim
 ```
@@ -117,12 +121,9 @@ NUM_ROBOTS=2 python3 generate_settings.py
 **Network configuration:**
 
 - **Network:** `airstack_network` (172.31.0.0/24)
-- **Fixed IP:** 172.31.0.201
+- **Fixed IP:** 172.31.0.200
 - **Purpose:** Communicate with robot containers via ROS 2 DDS and MAVLink UDP
 
-!!! note
-    Microsoft AirSim (legacy) uses `172.31.0.201` (Isaac Sim uses `172.31.0.200`). Only one simulator should be active at a time. Set `SIM_IP=172.31.0.201` in `.env` when using Microsoft AirSim (legacy).
-
 **Port usage:**
 
 | Port | Protocol | Purpose |
@@ -312,15 +313,15 @@ AIRSIM_CAM_FOV=120 airstack up --profile ms-airsim
 
 **MAVROS won't connect (robot container):**
 
-- Verify `SIM_IP=172.31.0.201` is set in `.env`
+- Verify `SIM_IP=172.31.0.200` is set in `.env`
 - Ensure PX4 SITL has started (look for `[mavlink]` output in the PX4 tmux window)
 - Check MAVLink ports match: offboard `24541+i`, onboard `24581+i`
 
 **No depth images on ROS 2 topics:**
 
 - Verify the camera names in `settings.json` match those in `bridge.yaml`
 - Check bridge node output for connection errors (tmux bridge window)
-- Echo the topic: `ros2 topic echo /robot_1/sensors/front_camera/depth --once`
+- Echo the topic: `ros2 topic echo /robot_1/sensors/front_stereo/depth --once`
 
 **ROS 2 topics not visible from robot container:**
 

docs/simulation/ms-airsim/index.md

@@ -43,9 +43,10 @@ To build the images first:
 airstack image-build --profile ms-airsim
 ```
 
-The container runs two tmux windows:
+The container runs `1 + 2*NUM_ROBOTS` tmux windows:
 - **Window 0**: AirSim binary (Unreal Engine rendering)
-- **Window 1**: ROS 2 bridge node (depth + camera_info publisher)
+- **Windows 1..N**: one PX4 SITL instance per robot
+- **Windows N+1..2N**: one ROS 2 bridge node per robot (depth + stereo RGB + camera_info)
 
 To attach to the tmux session:
 
@@ -61,31 +62,29 @@ A video is below:
 ## Architecture
 
 ```
-┌──────────────────────┐     ┌──────────────────────┐
-│  MS-AirSim Container │     │   Robot Container     │
-│   (172.31.0.201)     │     │                       │
-│                      │     │                       │
-│  AirSim Binary       │     │  MAVROS ◄──── MAVLink UDP ────► PX4 SITL
-│    │                 │     │    │                  │
-│    ▼                 │     │    ▼                  │
-│  PX4 SITL            │     │  Interface Layer      │
-│    (TCP lockstep)    │     │    │                  │
-│                      │     │    ▼                  │
-│  Bridge Node ────────ROS 2 DDS────►  Perception    │
-│    (depth +          │     │    │                  │
-│     camera_info)     │     │    ▼                  │
-│                      │     │  DROAN (disparity     │
-│                      │     │   expansion + planner)│
-└──────────────────────┘     └──────────────────────┘
-         airstack_network (172.31.0.0/24)
+┌────────────────────────────────┐     ┌──────────────────────┐
+│     MS-AirSim Container        │     │   Robot Container    │
+│       (172.31.0.200)           │     │                      │
+│                                │     │                      │
+│   AirSim Binary (UE4)          │     │  MAVROS              │
+│      ▲    │                    │     │    ▲                 │
+│      │    │ TCP 4560+i         │     │    │                 │
+│      │    ▼ (lockstep)         │     │    │                 │
+│   PX4 SITL ×N ─── MAVLink UDP ─┼─────┼─► 24540+i/24580+i    │
+│      ▲                         │     │    │                 │
+│      │                         │     │    ▼                 │
+│   Bridge Node ×N ─── ROS 2 DDS─┼─────┼─► Perception → DROAN │
+│   (stereo RGB + depth + info)  │     │                      │
+└────────────────────────────────┘     └──────────────────────┘
+            airstack_network (172.31.0.0/24)
 ```
 
 **Data flow:**
 
-1. Microsoft AirSim (legacy) simulates physics and renders depth images
-2. PX4 SITL runs in lockstep with AirSim via TCP (port 4560)
-3. Robot container connects to PX4 via MAVROS (UDP 14540/14580)
-4. Bridge node publishes depth + camera_info to ROS 2 topics
+1. AirSim simulates physics and renders stereo RGB + depth for each vehicle
+2. N PX4 SITL instances run in lockstep with AirSim via TCP (port `4560+i`)
+3. MAVROS in the robot container connects to PX4 SITL via MAVLink UDP (offboard `24540+i`, onboard `24580+i`)
+4. Bridge nodes (one per robot) publish stereo RGB + depth + camera_info to ROS 2 topics
 5. `disparity_expansion` converts depth to disparity for DROAN
 
 ## Configuration
@@ -101,65 +100,55 @@ Key settings:
 | `SimMode` | `Multirotor` | Drone simulation |
 | `ClockType` | `SteppableClock` | Lockstep with PX4 |
 | `VehicleType` | `PX4Multirotor` | PX4 SITL vehicle |
-| `TcpPort` | `4560` | PX4 lockstep connection |
-| `ControlPortLocal` | `14540` | MAVLink offboard port |
-| `ControlPortRemote` | `14580` | MAVLink onboard port |
+| `TcpPort` | `4560 + i` | PX4 lockstep connection (per robot `i`) |
+| `ControlPortLocal` | `24540 + i` | AirSim MAVLink proxy local port (moved off `14540+i` so it doesn't intercept PX4 ↔ MAVROS traffic) |
+| `ControlPortRemote` | `24580 + i` | AirSim MAVLink proxy remote port |
 
-### Camera
+`settings.json` is generated at container start from [`settings.json.j2`](https://github.com/.../simulation/ms-airsim/config/settings.json.j2) via [`generate_settings.py`](https://github.com/.../simulation/ms-airsim/config/generate_settings.py), which expands per-robot port offsets, spawn positions, and camera parameters.
 
-The default configuration uses a single forward-facing depth camera:
+### Cameras
 
-- Resolution: 480x300
-- FOV: 90 degrees
-- Position: 20cm forward, 10cm up from body center
+The default configuration is a forward-facing **stereo pair** (left + right) plus aligned depth:
 
-To modify camera settings, edit `settings.json` under `Vehicles.drone1.Cameras.front_camera`.
+| Property | Default | `.env` override |
+|----------|---------|-----------------|
+| Resolution | 480×300 | `AIRSIM_CAM_WIDTH`, `AIRSIM_CAM_HEIGHT` |
+| FOV | 110° | `AIRSIM_CAM_FOV` |
+| Baseline (2 × Y offset) | 0.12 m | `AIRSIM_CAM_Y` |
+| Forward (X) offset | 0.4 m | `AIRSIM_CAM_X` |
+| Pitch | 0° | `AIRSIM_CAM_PITCH` |
+
+Cameras are defined per vehicle in the generated `settings.json` under `Vehicles.drone<i>.Cameras`.
 
 ### Bridge node parameters
 
 Located at `simulation/ms-airsim/ros_ws/src/ms_airsim_ros_bridge/config/bridge.yaml`:
 
 | Parameter | Default | Description |
 |-----------|---------|-------------|
-| `ms_airsim_ip` | `127.0.0.1` | AirSim API address |
-| `camera_name` | `front_camera` | AirSim camera name |
-| `vehicle_name` | `drone1` | AirSim vehicle name |
-| `publish_rate` | `15.0` | Depth publish rate (Hz) |
-| `robot_name` | `robot_1` | ROS 2 topic namespace |
+| `ms_airsim_ip` | `127.0.0.1` | AirSim API address (same container, so localhost) |
+| `publish_rate` | `15.0` | Camera / depth publish rate (Hz) |
+| `robot_name` | `robot_1` | ROS 2 topic namespace (set per-instance by the entrypoint to `robot_<i>`) |
+| `clock_rate` | `50.0` | `/clock` publish rate (Hz) |
 
 ### Environment variables
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `SIM_IP` | `172.31.0.200` | Simulation container IP. Set to `172.31.0.201` for Microsoft AirSim (legacy) |
+| `SIM_IP` | `172.31.0.200` | Simulation container IP |
 | `MS_AIRSIM_ENV_DIR` | `simulation/ms-airsim/environments` | Host path to extracted AirSim environment |
 | `MS_AIRSIM_BINARY_PATH` | `/ms-airsim-env/LinuxNoEditor/Blocks.sh` | Path to binary inside container |
 
 ## Published ROS 2 Topics
 
 | Topic | Type | Description |
 |-------|------|-------------|
-| `/{robot_name}/sensors/front_camera/depth` | `sensor_msgs/Image` | Depth image (32FC1, meters) |
-| `/{robot_name}/sensors/front_camera/camera_info` | `sensor_msgs/CameraInfo` | Camera intrinsics (P matrix) |
-
-## Adding Stereo Cameras
-
-To switch from depth-only to stereo (for full disparity-based DROAN), add a second camera to `settings.json`:
-
-```json
-"Cameras": {
-  "front_left": {
-    "CaptureSettings": [{"ImageType": 0, "Width": 480, "Height": 300, "FOV_Degrees": 90}],
-    "X": 0.2, "Y": -0.06, "Z": -0.1
-  },
-  "front_right": {
-    "CaptureSettings": [{"ImageType": 0, "Width": 480, "Height": 300, "FOV_Degrees": 90}],
-    "X": 0.2, "Y": 0.06, "Z": -0.1
-  }
-}
-```
-
-This creates a stereo pair with 12cm baseline (matching ZED cameras). The bridge node would need to be extended to publish rectified stereo images.
+| `/{robot_name}/sensors/front_stereo/left/image_rect` | `sensor_msgs/Image` | Left RGB image |
+| `/{robot_name}/sensors/front_stereo/left/camera_info` | `sensor_msgs/CameraInfo` | Left camera intrinsics |
+| `/{robot_name}/sensors/front_stereo/right/image_rect` | `sensor_msgs/Image` | Right RGB image |
+| `/{robot_name}/sensors/front_stereo/right/camera_info` | `sensor_msgs/CameraInfo` | Right camera intrinsics |
+| `/{robot_name}/sensors/front_stereo/depth` | `sensor_msgs/Image` | Depth image (32FC1, meters) |
+| `/clock` | `rosgraph_msgs/Clock` | Simulation clock from AirSim |
 
 ### Project status
 
@@ -179,6 +168,6 @@ Microsoft archived AirSim. For a maintained successor, see [Project AirSim](http
 
 **MAVROS won't connect:**
 
-- Verify `SIM_IP=172.31.0.201` is set in `.env`
+- Verify `SIM_IP=172.31.0.200` is set in `.env` (default)
 - Ensure PX4 SITL has started (check AirSim console for MAVLink messages)
-- Check port configuration: offboard=14540, onboard=14580
+- Check port configuration: offboard=24540+i, onboard=24580+i

simulation/ms-airsim/docker/docker-compose.yaml

@@ -26,6 +26,7 @@ services:
       - NUM_ROBOTS=${NUM_ROBOTS:-1}
       - AUTOLAUNCH=${AUTOLAUNCH:-true}
       - MS_AIRSIM_BINARY_PATH=${MS_AIRSIM_BINARY_PATH:-/ms-airsim-env/Blocks.sh}
+      - MS_AIRSIM_HEADLESS=${MS_AIRSIM_HEADLESS:-false}
     deploy:
       resources:
         reservations:

simulation/ms-airsim/docker/entrypoint.sh

@@ -3,15 +3,20 @@ set -e
 
 NUM_ROBOTS="${NUM_ROBOTS:-1}"
 MS_AIRSIM_BINARY_PATH="${MS_AIRSIM_BINARY_PATH:-/ms-airsim-env/LinuxNoEditor/Blocks.sh}"
+MS_AIRSIM_HEADLESS="${MS_AIRSIM_HEADLESS:-false}"
 
 # Generate settings.json from template
 python3 /home/ms-airsim/Documents/AirSim/generate_settings.py
 
 # Start tmux session
 tmux new -d -s ms-airsim
 
-# Launch Microsoft AirSim (legacy) UE4 binary
-tmux send-keys -t ms-airsim "sudo -u ms-airsim $MS_AIRSIM_BINARY_PATH" ENTER
+# Launch Microsoft AirSim (legacy) UE4 binary (optionally headless via -RenderOffScreen)
+UE4_FLAGS=""
+if [ "$MS_AIRSIM_HEADLESS" = "true" ]; then
+    UE4_FLAGS="-RenderOffScreen -nosound"
+fi
+tmux send-keys -t ms-airsim "sudo -u ms-airsim $MS_AIRSIM_BINARY_PATH $UE4_FLAGS" ENTER
 
 # Wait for AirSim API to be ready
 python3 -c "