set the streamed body in the script, not the environment

The emulator read NATNET_BODY_NAME / NATNET_BODY_ID from the environment to stay in
sync with the client. The client now takes its bodies from its per-robot profile in
natnet_config.yaml, so the env hook was asymmetric and, being global, could not
describe a multi-robot scene anyway.

Both are now constants in the launch scripts, with the pairing spelled out inline,
in the emulator sim doc, and in the optitrack-development skill — including that a
mismatched id fails silently: the client connects and never publishes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: JohnYanxinLiu

.agents/skills/optitrack-development/SKILL.md

@@ -17,6 +17,7 @@ metadata:
 - Understanding **NatNet wire protocol** (connect, model def, frame streaming)
 - Capturing what **`libNatNet.so`** actually sends on the network
 - Enabling OptiTrack in sim: `LAUNCH_NATNET=true`, `natnet_config.yaml`, Docker IPs
+- Sim testing with mocap: bring the stack up with `overrides/isaac-natnet-vision.env`, which starts Isaac + the emulator and switches PX4 EKF2 to external-vision fusion (GPS/baro/range aiding off, so mocap is the only position source)
 
 ## Architecture in AirStack
 
@@ -50,7 +51,7 @@ flowchart LR
 | [`example_one_px4_pegasus_natnet_launch_script.py`](../../../simulation/isaac-sim/launch_scripts/example_one_px4_pegasus_natnet_launch_script.py) | Single drone + static ``Target`` |
 | [`example_multi_px4_pegasus_natnet_launch_script.py`](../../../simulation/isaac-sim/launch_scripts/example_multi_px4_pegasus_natnet_launch_script.py) | ``NUM_ROBOTS`` drones + shared ``Target`` (pair with 3-profile ``natnet_config.yaml``) |
 
-Helpers: [`isaac/scene_setup.py`](../../../simulation/isaac-sim/extensions/optitrack.natnet.emulator/optitrack/natnet/emulator/isaac/scene_setup.py) (`start_drone_natnet_server`, `author_static_target`). Drone body: single = ``Drone``; multi = ``Drone<i>`` (id ``i``); target = ``Target`` (id 100). Override names with ``NATNET_BODY_NAME`` / ``NATNET_TARGET_NAME``. Baseline Pegasus scripts (no NatNet) remain ``example_one_px4_pegasus_launch_script.py`` / ``example_multi_px4_pegasus_launch_script.py``.
+Helpers: [`isaac/scene_setup.py`](../../../simulation/isaac-sim/extensions/optitrack.natnet.emulator/optitrack/natnet/emulator/isaac/scene_setup.py) (`start_drone_natnet_server`, `author_static_target`). Drone body: single = ``Drone`` (id 1); multi = ``Drone<i>`` (id ``i``); target = ``Target`` (id 100). These are **constants in the launch script**, not env vars — change them there AND in the matching ``natnet_config.yaml`` profile together. The client filters frames by numeric id, so a mismatch is silent: it connects and never publishes. Baseline Pegasus scripts (no NatNet) remain ``example_one_px4_pegasus_launch_script.py`` / ``example_multi_px4_pegasus_launch_script.py``.
 
 **Default client config:** unicast, `server_ip` → Motive/emulator (use `172.31.0.200` for Isaac container), ports 1510/1511. The config is per-robot: each `robots[$ROBOT_NAME]` profile lists the bodies it tracks (each a `rigid_body_name` + `id` mapped to a relative `topic`, with `pose`/`pose_cov` toggles and per-body covariance) and an optional `vision_pose` block that drives the MAVROS bridge. See [`natnet_config.yaml`](../../../robot/ros_ws/src/perception/natnet_ros2/config/natnet_config.yaml).
 

docs/simulation/isaac_sim/natnet_emulator.md

@@ -82,11 +82,29 @@ PX4, start the NatNet emulator, and play the simulation automatically.
 | 1 | `Drone`, `Target` |
 | N > 1 | `Drone1`, `Drone2`, …, `DroneN`, `Target` |
 
-Override the base name with `NATNET_BODY_NAME` (default `Drone`) and
-`NATNET_TARGET_NAME` (default `Target`). These must match the
-`rigid_body_name` entries in your robot's
-[`natnet_config.yaml`](../../../robot/ros_ws/src/perception/natnet_ros2/config/natnet_config.yaml)
-profile.
+### Changing which body is streamed
+
+The streamed body name and streaming id are **constants in the launch script**
+(`NATNET_BODY_NAME` / `NATNET_BODY_ID` / `NATNET_TARGET_NAME`), not environment
+variables. They must match a body entry in the robot's profile in
+[`natnet_config.yaml`](../../../robot/ros_ws/src/perception/natnet_ros2/config/natnet_config.yaml),
+which is the only place the client reads its bodies from — that is what lets each robot
+in a multi-robot scene track a different body.
+
+To retarget, edit **both** together:
+
+| Where | What |
+|---|---|
+| `example_one_px4_pegasus_natnet_launch_script.py` | `NATNET_BODY_NAME`, `NATNET_BODY_ID` |
+| `natnet_config.yaml` → `robots.<robot_name>.bodies[]` | `rigid_body_name`, `id` |
+
+!!! warning "A mismatch fails silently"
+    The NatNet client filters incoming frames by **numeric id**. If the ids disagree, the
+    client connects, the emulator streams, and the pose topic never publishes — with no
+    error on either side. When debugging a silent stream, check the id first.
+
+    Deliberately not settable from an env file: one global variable cannot express
+    per-robot bodies, so it would break multi-robot.
 
 ### What the robot container needs
 

overrides/isaac-natnet-vision.env

@@ -35,12 +35,6 @@ LAUNCH_NATNET="true"
 # between sim and a real deployment, where it is the Motive host's address.
 NATNET_SERVER_IP="172.31.0.200"
 
-# Must agree between the emulator (launch script) and the client (natnet_config.yaml),
-# which both read these. The client filters incoming frames by NUMERIC id, so a mismatch
-# yields a connected client that never publishes.
-NATNET_BODY_NAME="Drone"
-NATNET_BODY_ID="1"
-
 # --- PX4 EKF2 external-vision fusion -----------------------------------------
 # Without these PX4 ignores the vision stream entirely — EKF2_EV_CTRL defaults to 0 — and
 # flies on sim GPS, so the emulator can be streaming perfectly and change nothing.

simulation/isaac-sim/launch_scripts/example_multi_px4_pegasus_natnet_launch_script.py

@@ -22,7 +22,6 @@
  - ``NUM_ROBOTS`` (default 1)
  - ``ENABLE_LIDAR`` (default false)
  - ``PLAY_SIM_ON_START`` (default true)
- - ``NATNET_BODY_NAME`` / ``NATNET_TARGET_NAME`` (optional name overrides)
 """
 
 import asyncio
@@ -73,8 +72,12 @@
 
 NUM_ROBOTS = int(os.environ.get("NUM_ROBOTS", "1"))
 ENABLE_LIDAR = os.environ.get("ENABLE_LIDAR", "false").lower() == "true"
-NATNET_BODY_NAME = os.environ.get("NATNET_BODY_NAME", "Drone")
-NATNET_TARGET_NAME = os.environ.get("NATNET_TARGET_NAME", "Target")
+# Base name for the streamed drone bodies; drone i is streamed with id i (see
+# _drone_body_name below). These must match the body entries in the per-robot profiles
+# in natnet_config.yaml — the client filters frames by numeric id. Set them here, not in
+# an env file.
+NATNET_BODY_NAME = "Drone"
+NATNET_TARGET_NAME = "Target"
 
 _NATNET_SERVER_KWARGS = {
     "pose_noise_enabled": True,

simulation/isaac-sim/launch_scripts/example_one_px4_pegasus_natnet_launch_script.py

@@ -108,13 +108,17 @@
     {"domain_id": 1, "x_m": 0.0, "y_m": 0.0, "z_m": 0.07},
 ]
 
-NATNET_BODY_NAME = os.environ.get("NATNET_BODY_NAME", "Drone")
-# Streaming id the emulator advertises for the drone. The NatNet client filters incoming
-# frames by NUMERIC id, so this must match the body id in natnet_config.yaml, which reads
-# the same env var — a mismatch yields a connected client that never publishes. Both
-# default to 1, so the sim path works unconfigured.
-NATNET_BODY_ID = int(os.environ.get("NATNET_BODY_ID", "1"))
-NATNET_TARGET_NAME = os.environ.get("NATNET_TARGET_NAME", "Target")
+# Rigid body this scene streams, and the streaming id it advertises.
+#
+# These MUST match a body entry in the robot's profile in
+# robot/ros_ws/src/perception/natnet_ros2/config/natnet_config.yaml — the NatNet client
+# filters incoming frames by NUMERIC id, so a mismatch gives a client that connects and
+# then never publishes, with no error on either side. Change them here and in that file
+# together, never in an env file: the client reads the body from its per-robot profile
+# so that multiple robots can each track their own body.
+NATNET_BODY_NAME = "Drone"
+NATNET_BODY_ID = 1
+NATNET_TARGET_NAME = "Target"
 
 _NATNET_SERVER_KWARGS = {
     "pose_noise_enabled": True,

tests/integration/natnet/README.md

@@ -103,8 +103,8 @@ The matching **system** check is
 - Asserts `/{robot_n}/{natnet pose topic}/pose_cov` ≥ 5 Hz per robot (the drone
   body's configured topic — default `perception/optitrack/drone`).
 - Override the checked topic with `NATNET_POSE_TOPIC` (default
-  `perception/optitrack/drone`). The sim body name (`NATNET_BODY_NAME`, default
-  `Drone`) is decoupled from the published topic, which the robot profile sets.
+  `perception/optitrack/drone`). The body name and the published topic are decoupled;
+  both are set in the robot's `natnet_config.yaml` profile.
 
 Sim auto-start: set `ISAAC_SIM_SCRIPT_NAME` to a NatNet launch script and
 `LAUNCH_NATNET=true` on the robot. Convenience bundle: