rosotacom-dev 2.5.dev48__tar.gz → 2.5.dev50__tar.gz

{rosotacom_dev-2.5.dev48 → rosotacom_dev-2.5.dev50}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rosotacom-dev
-Version: 2.5.dev48
+Version: 2.5.dev50
 Summary: Host CLI for ROS OTA communication sessions.
 Author: develNor
 License-Expression: BSD-3-Clause

{rosotacom_dev-2.5.dev48 → rosotacom_dev-2.5.dev50}/docs/rfcs/0004-network-profiles.md

@@ -266,6 +266,17 @@ risk — a stuck `qdisc` silently corrupts every later result on the machine.
   and outage steps, plus static distillation from a full trace or window
   (`trace_profiles.convert_trace_to_profile_yaml`). Passive throughput is omitted
   as `rate` unless the sample is marked saturated/probed/capacity-like.
+- [x] Shape without host sudo (issue #279): `--sudo-mode container` runs every
+  tc/ip argv in a short-lived `docker run --rm --network host --cap-add
+  NET_ADMIN` container on the peer, so docker-group membership is the whole
+  privilege. `--network host` keeps the target identical to the sudo modes
+  (the host netns is the netns the OTA com containers use); the safety
+  watchdog detaches as `docker run -d` under a fixed name and replaces a
+  stale predecessor at arm time; the image is `--shaping-image` or resolved
+  on the peer (running `rosotacom_` container's image, else the newest local
+  `ros-communication*` image, else an actionable exit-69). The lab benchmark
+  path needed none of this — it has always armed tc inside the peer
+  containers' own netns (`--cap-add NET_ADMIN` on the isolated network).
 - [ ] Confirm the `/proc/net/dev` link sampler (RFC 0003 / `link_bytes.py`) reports
   post-shaping wire bytes so link-overhead stays meaningful under a profile. *(Bench
   check.)*
@@ -342,6 +353,13 @@ off during implementation). Notes whether automation is feasible; privileged
   load generated YAML through `load_profiles_file`, and feed the resulting
   timeline into dry-run `ProfileShaper` command generation
   (`tests/unit/test_trace_profiles.py`). Done.
+- [x] **Sudo-free container shaping** (`--sudo-mode container`) — host unit tests
+  pin the generated shell: host-netns + NET_ADMIN on every tc/ip run, the
+  watchdog's `docker run -d` detachment and stale-predecessor replacement, the
+  on-peer image resolution with its actionable failure, and that the watchdog
+  name stays out of the `rosotacom_` conflict scan
+  (`tests/unit/test_container_shaping.py`). Arming it against a live remote pair
+  stays a bench check (same standing as the sudo modes' live half).
 - [ ] **Emulated-profile gate (rung 2)** — an example session run under one
   canonical profile in the per-promotion CI smoke, asserting a conditional bound
   that differs from the unshaped run. Automatable in the smoke matrix.

{rosotacom_dev-2.5.dev48 → rosotacom_dev-2.5.dev50}/session-configuration.md

@@ -568,13 +568,39 @@ number being reported.
 - `bit_rate` (int)
 - `encoder_av_options` (string)
 
-#### Receiver-side playout pacing (manual node)
+#### Receiver-side playout pacing
 
 A receiver that hands every packet to the decoder the moment it arrives turns
 network delay jitter into display stutter. `com_py playout_pacer` re-times a
 received packet stream to `stamp + budget` (budget adaptive above the fastest
 observed path, clock-offset-proof; late packets pass through immediately, order
-always preserved — the decoder chain sees every packet):
+always preserved — the decoder chain sees every packet). On the 2026-08-17 CCNG
+field trace this removes ~95 % of delay-caused >200 ms display gaps at ~100 ms
+median added age (adaptive mode).
+
+Declaratively, add a `playout` block to the transport:
+
+```yaml
+        transport:
+          type: "ffmpeg"
+          gop_size: 3
+          remote_republish: compressed
+          playout:            # receiver-side; requires remote_republish
+            adaptive: true    # default true; false uses target_ms as a fixed budget
+            target_ms: 350    # fixed budget when adaptive: false
+            min_ms: 100       # adaptive clamp above the observed delay floor
+            max_ms: 800
+```
+
+The receiving peer then runs the pacer in its own `PACE` window against the
+arrived encoded stream, and the reverse republish decodes `<encoded>/paced`
+instead of the raw arrival — the delivered topic name is unchanged, which is
+why `playout` requires `remote_republish`: without a republish the pacer's
+`/paced` suffix would rename what the receiving application subscribes to.
+The sender's own preview decode (`local_republish`) is never paced — it reads
+the local copy of what was just encoded, so there is no jitter to absorb.
+
+The node also runs standalone against any packet stream:
 
 ```bash
 ros2 run com_py playout_pacer --ros-args \
@@ -583,11 +609,7 @@ ros2 run com_py playout_pacer --ros-args \
 ```
 
 It republishes on `<topic>/paced` plus `.../paced/budget_ms` and
-`.../paced/queue_depth` debug topics; point the reverse republish (or any
-decoder) at the paced name. On the 2026-08-17 CCNG field trace this removes
-~95 % of delay-caused >200 ms display gaps at ~100 ms median added age
-(adaptive mode). Declarative wiring as a `transport.playout` block is tracked
-in issue #284.
+`.../paced/queue_depth` debug topics.
 
 `type: foxglove` supports (CompressedVideo):
 - `gop_size` (int)

{rosotacom_dev-2.5.dev48 → rosotacom_dev-2.5.dev50}/src/rosotacom/cli.py

@@ -121,7 +121,15 @@ EXTERNAL_SESSION_CONTAINER_DIR = "/session/current"
 # `anonymize_bag.py` two thousand lines below already does it this way.
 RUN_SESSION_CONTAINER_ARGV = ("python3", "/ws/session/creation/run_session.py")
 DEFAULT_SMOKE_SESSION = "1_heartbeat"
-OTA_SUDO_MODES = ("passwordless", "askpass")
+# How profile shaping obtains tc/ip privileges on a peer. `passwordless` and
+# `askpass` are the two sudo shapes. `container` needs no sudo at all: every
+# tc/ip argv runs in a short-lived `docker run --rm --network host --cap-add
+# NET_ADMIN` container on the peer, so docker-group membership is the whole
+# privilege — the mode that makes profiles runnable on a machine that has
+# Docker but no passwordless sudo (issue #279). `--network host` puts tc in
+# the host netns, which is the netns the OTA com containers use, so it shapes
+# exactly the interface sudo would.
+OTA_SUDO_MODES = ("passwordless", "askpass", "container")
 
 # How ota-smoke puts rosotacom on each peer.
 #
@@ -2663,6 +2671,59 @@ def _sudo_command(argv: Sequence[str], *, askpass: bool = False) -> str:
     return f"{mode} {shlex.join(list(argv))}"
 
 
+#: Deterministic name for the container-mode safety watchdog on a peer. Fixed
+#: (not per-run) on purpose: arming replaces a stale predecessor with
+#: `docker rm -f`, so a crashed run's watchdog cannot accumulate — and the
+#: dash spelling keeps it out of the `rosotacom_` conflict scan, whose signal
+#: for a live run is the qdisc itself, not the sleeping watchdog.
+_SHAPING_WATCHDOG_NAME = "rosotacom-shaping-watchdog"
+
+
+def _shaping_image_resolution(image: str | None) -> str:
+    """Shell preamble that leaves the shaping image in ``$img`` on the peer.
+
+    An explicit image wins. Otherwise resolve on the peer itself, because the
+    scoped image name (`<base>-<install_id>`) is a property of the peer's own
+    install that the orchestrator cannot know before that install ran: prefer
+    the image of a running `rosotacom_` container, fall back to the newest
+    local `ros-communication*` image. Exit 69 with an actionable message when
+    neither exists (a machine that never ran rosotacom): shaping needs *an*
+    image with iproute2, and the com image is the one guaranteed relevant."""
+    if image:
+        return f"img={shlex.quote(image)}; "
+    return (
+        "img=\"$(docker ps --filter name=rosotacom_ --format '{{.Image}}' | head -n1)\"; "
+        '[ -n "$img" ] || img="$(docker image ls --format \'{{.Repository}}:{{.Tag}}\''
+        " | grep -m1 '^ros-communication' || true)\"; "
+        '[ -n "$img" ] || { echo "no shaping image on this peer: run rosotacom here once'
+        ' (any smoke/start builds the com image) or pass --shaping-image" >&2; exit 69; }; '
+    )
+
+
+def _container_shaping_command(argv: Sequence[str], *, image: str | None, watchdog: bool = False) -> str:
+    """One privileged tc/ip argv as a short-lived NET_ADMIN container run.
+
+    ``--network host`` is the point: the ephemeral container shares the host
+    netns, so ``tc`` acts on the same interface sudo would — but the privilege
+    comes from docker-group membership instead of a sudoers entry. A watchdog
+    argv (``sh -c 'sleep …; tc …'``) runs detached (``-d``) under the fixed
+    name above, replacing any stale predecessor; docker itself keeps it alive
+    across an orchestrator crash, which is the fail-safe RFC 0004 demands."""
+    argv = list(argv)
+    resolve = _shaping_image_resolution(image)
+    run = "docker run --rm --network host --cap-add NET_ADMIN"
+    if watchdog:
+        run = (
+            f"docker rm -f {_SHAPING_WATCHDOG_NAME} >/dev/null 2>&1 || true; "
+            f"docker run -d --rm --name {_SHAPING_WATCHDOG_NAME} --network host --cap-add NET_ADMIN"
+        )
+    if len(argv) >= 3 and argv[0] == "sh" and argv[1] == "-c":
+        tail = f'--entrypoint sh "$img" -c {shlex.quote(str(argv[2]))}'
+    else:
+        tail = f'--entrypoint {shlex.quote(argv[0])} "$img" {shlex.join(argv[1:])}'
+    return f"{resolve}{run} {tail}"
+
+
 def _passwordless_watchdog_command(argv: Sequence[str]) -> str:
     argv = list(argv)
     if len(argv) >= 3 and argv[0] == "sh" and argv[1] == "-c":
@@ -2744,6 +2805,7 @@ def _ota_preflight(
     require_network_shaping_sudo: bool = False,
     sudo_mode: str = OTA_DEFAULT_SUDO_MODE,
     sudo_passwords: Mapping[str, str] | None = None,
+    shaping_image: str | None = None,
     check_conflicts: bool = True,
 ) -> None:
     sudo_mode = _validate_ota_sudo_mode(sudo_mode)
@@ -2771,6 +2833,27 @@ def _ota_preflight(
         )
         _ota_run(peer, "docker ps >/dev/null", label=f"{peer.name}: docker access", dry_run=dry_run, batch=True)
         if require_network_shaping_sudo:
+            if sudo_mode == "container":
+                # tc/ip live in the shaping image, not on the host, and no sudo
+                # is involved: the one thing to prove is that a NET_ADMIN
+                # host-netns container can run and sees the tools. This also
+                # fails early — with the actionable exit-69 message — on a
+                # machine that has no candidate image yet.
+                _ota_run(
+                    peer,
+                    _container_shaping_command(
+                        [
+                            "sh",
+                            "-c",
+                            "command -v tc >/dev/null && command -v ip >/dev/null && tc qdisc show >/dev/null",
+                        ],
+                        image=shaping_image,
+                    ),
+                    label=f"{peer.name}: containerized network shaping (docker run, NET_ADMIN, tc in image)",
+                    dry_run=dry_run,
+                    batch=True,
+                )
+                continue
             _ota_run(
                 peer,
                 "command -v tc >/dev/null 2>&1 && command -v ip >/dev/null 2>&1",
@@ -3241,13 +3324,21 @@ def _ota_resolve_interfaces(peer: OtaSmokePeer, peer_addr: str, *, dry_run: bool
 
 
 def _peer_command_runner(
-    peer: OtaSmokePeer, *, dry_run: bool, sudo_password: str | None = None
+    peer: OtaSmokePeer,
+    *,
+    dry_run: bool,
+    sudo_password: str | None = None,
+    sudo_mode: str = OTA_DEFAULT_SUDO_MODE,
+    shaping_image: str | None = None,
 ) -> Callable[[Sequence[str]], None]:
     """A CommandRunner that runs one privileged argv on ``peer`` via the SSH path."""
 
     def run(argv: Sequence[str]) -> None:
         label = f"{peer.name}: tc/netem"
-        if sudo_password is None:
+        if sudo_mode == "container":
+            script = _container_shaping_command(argv, image=shaping_image)
+            _ota_run(peer, script, label=label, dry_run=dry_run)
+        elif sudo_password is None:
             script = _sudo_command(argv)
             _ota_run(peer, script, label=label, dry_run=dry_run)
         else:
@@ -3265,12 +3356,23 @@ def _peer_command_runner(
 
 
 def _peer_watchdog_launcher(
-    peer: OtaSmokePeer, *, dry_run: bool, sudo_password: str | None = None
+    peer: OtaSmokePeer,
+    *,
+    dry_run: bool,
+    sudo_password: str | None = None,
+    sudo_mode: str = OTA_DEFAULT_SUDO_MODE,
+    shaping_image: str | None = None,
 ) -> Callable[[Sequence[str]], None]:
     """Launch the safety-watchdog argv detached on ``peer`` so it survives a crash."""
 
     def launch(argv: Sequence[str]) -> None:
-        if sudo_password is None:
+        if sudo_mode == "container":
+            # `docker run -d` is the detachment: the daemon owns the sleeping
+            # watchdog, so it survives the SSH session, the orchestrator, and
+            # every rosotacom container on the machine.
+            detached = _container_shaping_command(argv, image=shaping_image, watchdog=True)
+            _ota_run(peer, detached, label=f"{peer.name}: profile safety watchdog", dry_run=dry_run, check=False)
+        elif sudo_password is None:
             detached = _passwordless_watchdog_command(argv)
             _ota_run(peer, detached, label=f"{peer.name}: profile safety watchdog", dry_run=dry_run, check=False)
         else:
@@ -3297,6 +3399,8 @@ def _ota_arm_profile(
     *,
     dry_run: bool,
     sudo_passwords: Mapping[str, str] | None = None,
+    sudo_mode: str = OTA_DEFAULT_SUDO_MODE,
+    shaping_image: str | None = None,
 ) -> list[Any]:
     """Arm the static profile per direction on every peer's OTA egress (RFC 0004),
     returning the ``ProfileShaper`` handles to revert in the run's ``finally``."""
@@ -3320,10 +3424,22 @@ def _ota_arm_profile(
         sudo_password = (sudo_passwords or {}).get(peer_name)
         shaper = ProfileShaper(
             ota_iface,
-            _peer_command_runner(peer, dry_run=dry_run, sudo_password=sudo_password),
+            _peer_command_runner(
+                peer,
+                dry_run=dry_run,
+                sudo_password=sudo_password,
+                sudo_mode=sudo_mode,
+                shaping_image=shaping_image,
+            ),
             control_interface=control_iface,
             safety_max_duration_s=_PROFILE_SAFETY_MAX_S,
-            watchdog_launcher=_peer_watchdog_launcher(peer, dry_run=dry_run, sudo_password=sudo_password),
+            watchdog_launcher=_peer_watchdog_launcher(
+                peer,
+                dry_run=dry_run,
+                sudo_password=sudo_password,
+                sudo_mode=sudo_mode,
+                shaping_image=shaping_image,
+            ),
         )
         # Register before arming so a mid-arm failure is still reverted in `finally`.
         shapers.append(shaper)
@@ -4085,7 +4201,20 @@ def _start_noninteractive_ota_smoke(args: argparse.Namespace) -> int:
     errors: list[str] = []
     try:
         if profile is not None:
-            shapers = _ota_arm_profile(plan, profile, directions, dry_run=dry_run)
+            shapers = _ota_arm_profile(
+                plan,
+                profile,
+                directions,
+                dry_run=dry_run,
+                sudo_passwords=_ota_network_sudo_passwords(
+                    plan,
+                    sudo_mode=getattr(args, "sudo_mode", OTA_DEFAULT_SUDO_MODE),
+                    require_network_shaping_sudo=True,
+                    dry_run=dry_run,
+                ),
+                sudo_mode=getattr(args, "sudo_mode", OTA_DEFAULT_SUDO_MODE),
+                shaping_image=getattr(args, "shaping_image", None),
+            )
         _ota_start_peers(
             target,
             plan,
@@ -9039,6 +9168,24 @@ def main(argv: list[str] | None = None) -> int:
         action="store_true",
         help="Keep staged source and project files after cleanup.",
     )
+    ota_smoke_parser.add_argument(
+        "--sudo-mode",
+        choices=OTA_SUDO_MODES,
+        default=OTA_DEFAULT_SUDO_MODE,
+        help=(
+            "How profile shaping obtains tc/ip privileges on the peers "
+            "(passwordless: require sudo -n; askpass: prompt locally per peer and feed sudo -S; "
+            "container: no sudo -- run each tc/ip in a short-lived NET_ADMIN host-netns container, "
+            "for peers with Docker but no passwordless sudo)."
+        ),
+    )
+    ota_smoke_parser.add_argument(
+        "--shaping-image",
+        help=(
+            "Image for --sudo-mode container (must contain tc/ip). Default: resolve on the peer -- "
+            "the image of a running rosotacom_ container, else the newest local ros-communication* image."
+        ),
+    )
     ota_smoke_parser.add_argument("--skip-preflight", action="store_true", help="Skip SSH/Docker readiness checks.")
     ota_smoke_parser.add_argument(
         "--skip-conflict-check",

{rosotacom_dev-2.5.dev48 → rosotacom_dev-2.5.dev50}/src/rosotacom/cli_benchmark.py

@@ -4981,8 +4981,17 @@ def _add_benchmark_common_args(parser: argparse.ArgumentParser, *, ota_benchmark
         choices=OTA_SUDO_MODES,
         default=OTA_DEFAULT_SUDO_MODE,
         help=(
-            "How OTA benchmark profile shaping obtains sudo for tc/ip "
-            "(passwordless: require sudo -n; askpass: prompt locally per peer and feed sudo -S)."
+            "How OTA benchmark profile shaping obtains tc/ip privileges "
+            "(passwordless: require sudo -n; askpass: prompt locally per peer and feed sudo -S; "
+            "container: no sudo -- run each tc/ip in a short-lived NET_ADMIN host-netns container, "
+            "for peers with Docker but no passwordless sudo)."
+        ),
+    )
+    parser.add_argument(
+        "--shaping-image",
+        help=(
+            "Image for --sudo-mode container (must contain tc/ip). Default: resolve on the peer -- "
+            "the image of a running rosotacom_ container, else the newest local ros-communication* image."
         ),
     )
     parser.add_argument("--interactive", action="store_true", help="Open a tmux operator view for this benchmark run.")
@@ -5148,6 +5157,7 @@ def _make_live_run_point(args: argparse.Namespace, session_name: str) -> RunPoin
                 profile=profile,
                 benchmark_stepping=True,
                 sudo_mode=getattr(args, "sudo_mode", "passwordless"),
+                shaping_image=getattr(args, "shaping_image", None),
             )
 
             runtime, plan, target = _resolve_ota_smoke_context(smoke_args)
@@ -5170,6 +5180,7 @@ def _make_live_run_point(args: argparse.Namespace, session_name: str) -> RunPoin
                     require_network_shaping_sudo=profile_obj is not None,
                     sudo_mode=smoke_args.sudo_mode,
                     sudo_passwords=sudo_passwords,
+                    shaping_image=smoke_args.shaping_image,
                     check_conflicts=not getattr(args, "skip_conflict_check", False),
                 )
             _ota_prepare_hosts(smoke_args, runtime, plan)
@@ -5210,12 +5221,20 @@ def _make_live_run_point(args: argparse.Namespace, session_name: str) -> RunPoin
                             shaper = ProfileShaper(
                                 ota_iface,
                                 _peer_command_runner(
-                                    peer, dry_run=dry_run, sudo_password=sudo_passwords.get(peer_name)
+                                    peer,
+                                    dry_run=dry_run,
+                                    sudo_password=sudo_passwords.get(peer_name),
+                                    sudo_mode=smoke_args.sudo_mode,
+                                    shaping_image=smoke_args.shaping_image,
                                 ),
                                 control_interface=control_iface,
                                 safety_max_duration_s=_PROFILE_SAFETY_MAX_S,
                                 watchdog_launcher=_peer_watchdog_launcher(
-                                    peer, dry_run=dry_run, sudo_password=sudo_passwords.get(peer_name)
+                                    peer,
+                                    dry_run=dry_run,
+                                    sudo_password=sudo_passwords.get(peer_name),
+                                    sudo_mode=smoke_args.sudo_mode,
+                                    shaping_image=smoke_args.shaping_image,
                                 ),
                             )
                             shapers.append(shaper)
@@ -5226,7 +5245,13 @@ def _make_live_run_point(args: argparse.Namespace, session_name: str) -> RunPoin
                             shaper.arm([])
                     else:
                         shapers = _ota_arm_profile(
-                            plan, profile_obj, directions, dry_run=dry_run, sudo_passwords=sudo_passwords
+                            plan,
+                            profile_obj,
+                            directions,
+                            dry_run=dry_run,
+                            sudo_passwords=sudo_passwords,
+                            sudo_mode=smoke_args.sudo_mode,
+                            shaping_image=smoke_args.shaping_image,
                         )
 
                 _ota_start_peers(target, plan, instance.instance_id, dry_run=dry_run)

{rosotacom_dev-2.5.dev48 → rosotacom_dev-2.5.dev50}/src/rosotacom/resources/ws/session/content/base/session_plugin_base.yaml

@@ -232,15 +232,49 @@ parameters:
   irt_1_topic: # e.g. /sensors/camera/front_wide/image_color
   irt_1_transport: # e.g. raw
   irt_1_out_transport: compressed # e.g. raw, compressed – determines the output remap format
+  irt_1_paced: # "true" -> decode reads ${irt_1_topic}/paced (playout pacer, PACE window)
   irt_2_topic: # e.g. /sensors/front_camera/image_raw/compressed
   irt_2_transport: # e.g. raw
   irt_2_out_transport: compressed # e.g. raw, compressed – determines the output remap format
+  irt_2_paced: # "true" -> decode reads ${irt_2_topic}/paced
   irt_3_topic: # e.g. /sensor/front_camera/image_color/compressed
   irt_3_transport: # e.g. raw
   irt_3_out_transport: compressed # e.g. raw, compressed – determines the output remap format
+  irt_3_paced: # "true" -> decode reads ${irt_3_topic}/paced
   irt_4_topic: # e.g. /sensor/front_camera/image_color/compressed
   irt_4_transport: # e.g. raw
   irt_4_out_transport: compressed # e.g. raw, compressed – determines the output remap format
+  irt_4_paced: # "true" -> decode reads ${irt_4_topic}/paced
+
+  # Receiver-side playout pacing (transport.playout in the session definition):
+  # re-times the arrived encoded stream on '<topic>/paced' so the decode sees a
+  # steady cadence instead of the network's delay jitter. Never reorders, never
+  # drops; late packets pass through immediately.
+  pace: false
+  pace_1_topic: # the arrived encoded stream, e.g. /camera/image/ffmpeg
+  pace_1_msg_type: # e.g. ffmpeg_image_transport_msgs/msg/FFMPEGPacket
+  pace_1_adaptive: # "true" | "false"
+  pace_1_target_ms: # fixed budget when adaptive is "false"
+  pace_1_min_ms: # adaptive clamp above the observed delay floor
+  pace_1_max_ms:
+  pace_2_topic:
+  pace_2_msg_type:
+  pace_2_adaptive:
+  pace_2_target_ms:
+  pace_2_min_ms:
+  pace_2_max_ms:
+  pace_3_topic:
+  pace_3_msg_type:
+  pace_3_adaptive:
+  pace_3_target_ms:
+  pace_3_min_ms:
+  pace_3_max_ms:
+  pace_4_topic:
+  pace_4_msg_type:
+  pace_4_adaptive:
+  pace_4_target_ms:
+  pace_4_min_ms:
+  pace_4_max_ms:
 
 common:
   before_commands:
@@ -623,6 +657,30 @@ windows:
         - args+=(--remap "${in_remap}:=${it_4_topic}" --remap "out/${it_4_transport}:=${it_4_topic}/${outgoing_suffix}")
         - echo ${args[@]}
         - ${args[@]}
+  - name: PACE
+    if: pace
+    layout: even-vertical
+    splits:
+      - commands:
+        - if [ '${pace_1_topic}' = "None" ]; then exit; fi
+        - args=(ros2 run com_py playout_pacer --ros-args -p topic:=${pace_1_topic} -p msg_type:=${pace_1_msg_type} -p adaptive:=${pace_1_adaptive} -p target_ms:=${pace_1_target_ms} -p min_ms:=${pace_1_min_ms} -p max_ms:=${pace_1_max_ms} -p qos_config_file:='${qos_config_file}')
+        - echo ${args[@]}
+        - ${args[@]}
+      - commands:
+        - if [ '${pace_2_topic}' = "None" ]; then exit; fi
+        - args=(ros2 run com_py playout_pacer --ros-args -p topic:=${pace_2_topic} -p msg_type:=${pace_2_msg_type} -p adaptive:=${pace_2_adaptive} -p target_ms:=${pace_2_target_ms} -p min_ms:=${pace_2_min_ms} -p max_ms:=${pace_2_max_ms} -p qos_config_file:='${qos_config_file}')
+        - echo ${args[@]}
+        - ${args[@]}
+      - commands:
+        - if [ '${pace_3_topic}' = "None" ]; then exit; fi
+        - args=(ros2 run com_py playout_pacer --ros-args -p topic:=${pace_3_topic} -p msg_type:=${pace_3_msg_type} -p adaptive:=${pace_3_adaptive} -p target_ms:=${pace_3_target_ms} -p min_ms:=${pace_3_min_ms} -p max_ms:=${pace_3_max_ms} -p qos_config_file:='${qos_config_file}')
+        - echo ${args[@]}
+        - ${args[@]}
+      - commands:
+        - if [ '${pace_4_topic}' = "None" ]; then exit; fi
+        - args=(ros2 run com_py playout_pacer --ros-args -p topic:=${pace_4_topic} -p msg_type:=${pace_4_msg_type} -p adaptive:=${pace_4_adaptive} -p target_ms:=${pace_4_target_ms} -p min_ms:=${pace_4_min_ms} -p max_ms:=${pace_4_max_ms} -p qos_config_file:='${qos_config_file}')
+        - echo ${args[@]}
+        - ${args[@]}
   - name: IRT
     if: irt
     layout: even-vertical
@@ -630,28 +688,32 @@ windows:
       - commands:
         - if [ '${irt_1_topic}' = "None" ]; then exit; fi
         - if [[ "${irt_1_out_transport}" == "raw" ]]; then out_remap="out"; else out_remap="out/${irt_1_out_transport}"; fi
+        - if [[ "${irt_1_paced}" != "None" ]]; then irt_in_topic="${irt_1_topic}/paced"; else irt_in_topic="${irt_1_topic}"; fi
         - args=(ros2 run image_transport republish --ros-args -r __node:=irt_republish1 -p in_transport:=${irt_1_transport} -p out_transport:=${irt_1_out_transport}
-            --remap in/${irt_1_transport}:=${irt_1_topic} --remap ${out_remap}:=${irt_1_topic}/${irt_1_out_transport})
+            --remap in/${irt_1_transport}:=${irt_in_topic} --remap ${out_remap}:=${irt_1_topic}/${irt_1_out_transport})
         - echo ${args[@]}
         - ${args[@]}
       - commands:
         - if [ '${irt_2_topic}' = "None" ]; then exit; fi
         - if [[ "${irt_2_out_transport}" == "raw" ]]; then out_remap="out"; else out_remap="out/${irt_2_out_transport}"; fi
+        - if [[ "${irt_2_paced}" != "None" ]]; then irt_in_topic="${irt_2_topic}/paced"; else irt_in_topic="${irt_2_topic}"; fi
         - args=(ros2 run image_transport republish --ros-args -r __node:=irt_republish2 -p in_transport:=${irt_2_transport} -p out_transport:=${irt_2_out_transport}
-            --remap in/${irt_2_transport}:=${irt_2_topic} --remap ${out_remap}:=${irt_2_topic}/${irt_2_out_transport})
+            --remap in/${irt_2_transport}:=${irt_in_topic} --remap ${out_remap}:=${irt_2_topic}/${irt_2_out_transport})
         - echo ${args[@]}
         - ${args[@]}
       - commands:
         - if [ '${irt_3_topic}' = "None" ]; then exit; fi
         - if [[ "${irt_3_out_transport}" == "raw" ]]; then out_remap="out"; else out_remap="out/${irt_3_out_transport}"; fi
+        - if [[ "${irt_3_paced}" != "None" ]]; then irt_in_topic="${irt_3_topic}/paced"; else irt_in_topic="${irt_3_topic}"; fi
         - args=(ros2 run image_transport republish --ros-args -r __node:=irt_republish3 -p in_transport:=${irt_3_transport} -p out_transport:=${irt_3_out_transport}
-            --remap in/${irt_3_transport}:=${irt_3_topic} --remap ${out_remap}:=${irt_3_topic}/${irt_3_out_transport})
+            --remap in/${irt_3_transport}:=${irt_in_topic} --remap ${out_remap}:=${irt_3_topic}/${irt_3_out_transport})
         - echo ${args[@]}
         - ${args[@]}
       - commands:
         - if [ '${irt_4_topic}' = "None" ]; then exit; fi
         - if [[ "${irt_4_out_transport}" == "raw" ]]; then out_remap="out"; else out_remap="out/${irt_4_out_transport}"; fi
+        - if [[ "${irt_4_paced}" != "None" ]]; then irt_in_topic="${irt_4_topic}/paced"; else irt_in_topic="${irt_4_topic}"; fi
         - args=(ros2 run image_transport republish --ros-args -r __node:=irt_republish4 -p in_transport:=${irt_4_transport} -p out_transport:=${irt_4_out_transport}
-            --remap in/${irt_4_transport}:=${irt_4_topic} --remap ${out_remap}:=${irt_4_topic}/${irt_4_out_transport})
+            --remap in/${irt_4_transport}:=${irt_in_topic} --remap ${out_remap}:=${irt_4_topic}/${irt_4_out_transport})
         - echo ${args[@]}
         - ${args[@]}

{rosotacom_dev-2.5.dev48 → rosotacom_dev-2.5.dev50}/src/rosotacom/resources/ws/session/creation/generate_session_files.py

@@ -92,6 +92,13 @@ class TransportSpec:
     #: image_transport itself, or one that only forwards or records packets,
     #: does not want a second copy of every frame.
     remote_republish: Optional[str] = None
+    #: Receiver-side playout pacing (issue #284): re-time the arrived packet
+    #: stream to smooth network delay jitter before the reverse republish
+    #: decodes it. Keys: adaptive / target_ms / min_ms / max_ms (validated in
+    #: the parser; defaults live in the playout_pacer node). Requires
+    #: `remote_republish`, because the pacer publishes on `<encoded>/paced`
+    #: and only the republish remap keeps the delivered topic name unchanged.
+    playout: Optional[Dict[str, Any]] = None
 
 
 @dataclass
@@ -1692,12 +1699,45 @@ def _compute_pipeline(
                 )
             return str(value)
 
-        params = {k: v for k, v in t.items() if k not in ("type", *republish_keys)}
+        remote_republish = _republish("remote_republish")
+
+        playout: Optional[Dict[str, Any]] = None
+        playout_cfg = t.get("playout")
+        if playout_cfg is not None:
+            if not isinstance(playout_cfg, dict):
+                raise ValueError(f"transport.playout must be a mapping for topic '{entry.base}'")
+            allowed = {"adaptive", "target_ms", "min_ms", "max_ms"}
+            unknown = sorted(set(playout_cfg) - allowed)
+            if unknown:
+                raise ValueError(
+                    f"transport.playout for topic '{entry.base}' has unknown keys {unknown}; "
+                    f"allowed: {sorted(allowed)}"
+                )
+            if remote_republish is None:
+                raise ValueError(
+                    f"transport.playout for topic '{entry.base}' requires remote_republish: "
+                    "the pacer publishes on '<encoded>/paced', and only the reverse republish's "
+                    "input remap keeps the delivered topic name unchanged. Without a republish "
+                    "the receiver would have to subscribe a renamed topic."
+                )
+            for key in ("target_ms", "min_ms", "max_ms"):
+                if key in playout_cfg and (not isinstance(playout_cfg[key], (int, float)) or playout_cfg[key] <= 0):
+                    raise ValueError(f"transport.playout.{key} must be a positive number for topic '{entry.base}'")
+            min_ms = float(playout_cfg.get("min_ms", 100.0))
+            max_ms = float(playout_cfg.get("max_ms", 800.0))
+            if max_ms < min_ms:
+                raise ValueError(f"transport.playout.max_ms must be >= min_ms for topic '{entry.base}'")
+            if "adaptive" in playout_cfg and not isinstance(playout_cfg["adaptive"], bool):
+                raise ValueError(f"transport.playout.adaptive must be a boolean for topic '{entry.base}'")
+            playout = dict(playout_cfg)
+
+        params = {k: v for k, v in t.items() if k not in ("type", "playout", *republish_keys)}
         transport = TransportSpec(
             type=ttype,
             params=params,
             local_republish=_republish("local_republish"),
-            remote_republish=_republish("remote_republish"),
+            remote_republish=remote_republish,
+            playout=playout,
         )
 
     topic = entry.base
@@ -3201,21 +3241,46 @@ def func(
         # it encoded and (b) the decode of what arrived. Both run on *this* peer;
         # what differs is which copy they decode and which transport the session
         # asked each of them to publish in.
-        irt_all: List[Tuple[str, str, str]] = []
+        # The sender's own preview decode is never paced: it reads the local
+        # copy of what it just encoded, so there is no network jitter to
+        # absorb. Playout pacing exists on the receiving side only.
+        irt_all: List[Tuple[str, str, str, Optional[Dict[str, Any]]]] = []
         for t, tspec in irt_items_local:
             assert tspec is not None
-            irt_all.append((t, tspec.type, str(tspec.local_republish)))
-        irt_all.extend((topic, tspec.type, str(tspec.remote_republish)) for topic, tspec in irt_items_remote)
+            irt_all.append((t, tspec.type, str(tspec.local_republish), None))
+        irt_all.extend(
+            (topic, tspec.type, str(tspec.remote_republish), tspec.playout) for topic, tspec in irt_items_remote
+        )
         _assert_max("irt", irt_all, 4)
         if irt_all:
             items2 = [("irt", True)]
-            for i, (topic, _ttype, _out_transport) in enumerate(irt_all, 1):
+            for i, (topic, _ttype, _out_transport, _playout) in enumerate(irt_all, 1):
                 items2.append((f"irt_{i}_topic", topic))
-            for i, (_topic, ttype, out_transport) in enumerate(irt_all, 1):
+            for i, (_topic, ttype, out_transport, playout) in enumerate(irt_all, 1):
                 items2.append((f"irt_{i}_transport", ttype))
                 items2.append((f"irt_{i}_out_transport", out_transport))
+                if playout is not None:
+                    # Points the decode's input remap at '<topic>/paced'; the
+                    # pacer itself runs in the PACE window below.
+                    items2.append((f"irt_{i}_paced", "true"))
             blocks.append(PluginBlock("irt", items2))
 
+        paced_entries = [
+            (i, topic, ttype, playout)
+            for i, (topic, ttype, _out_transport, playout) in enumerate(irt_all, 1)
+            if playout is not None
+        ]
+        if paced_entries:
+            items_pace: List[Tuple[str, Any]] = [("pace", True)]
+            for i, topic, ttype, playout in paced_entries:
+                items_pace.append((f"pace_{i}_topic", topic))
+                items_pace.append((f"pace_{i}_msg_type", TRANSPORT_OUTPUT_TYPES[ttype]))
+                items_pace.append((f"pace_{i}_adaptive", "true" if playout.get("adaptive", True) else "false"))
+                items_pace.append((f"pace_{i}_target_ms", float(playout.get("target_ms", 350.0))))
+                items_pace.append((f"pace_{i}_min_ms", float(playout.get("min_ms", 100.0))))
+                items_pace.append((f"pace_{i}_max_ms", float(playout.get("max_ms", 800.0))))
+            blocks.append(PluginBlock("pace", items_pace))
+
         if nor_items:
             items2 = [("nor", True)]
             nor_prefix = f"/{peer_name[remote]}" if bool(inbound_cfg.get("keep_source_prefix", False)) else ""

{rosotacom_dev-2.5.dev48 → rosotacom_dev-2.5.dev50}/src/rosotacom_dev.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rosotacom-dev
-Version: 2.5.dev48
+Version: 2.5.dev50
 Summary: Host CLI for ROS OTA communication sessions.
 Author: develNor
 License-Expression: BSD-3-Clause