rosotacom-dev 2.5.dev53__tar.gz → 2.5.dev54__tar.gz

{rosotacom_dev-2.5.dev53 → rosotacom_dev-2.5.dev54}/PKG-INFO

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

{rosotacom_dev-2.5.dev53 → rosotacom_dev-2.5.dev54}/session-configuration.md

@@ -674,6 +674,7 @@ Declaratively, add a `playout` block to the transport:
             target_ms: 350    # fixed budget when adaptive: false
             min_ms: 100       # adaptive clamp above the observed delay floor
             max_ms: 800
+            republish: paced  # paced (default) | unpaced | both
 ```
 
 The receiving peer then runs the pacer in its own `PACE` window against the
@@ -684,6 +685,33 @@ why `playout` requires `remote_republish`: without a republish the pacer's
 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.
 
+##### `republish`: which stream reaches the display
+
+Pacing under an unchanged topic name is what keeps applications working, and it
+is also what makes the improvement invisible — nothing shows paced and unpaced
+together. `republish` names which stream the receiver decodes:
+
+| value | decodes | publishes |
+|---|---|---|
+| `paced` (default) | `<encoded>/paced` | `<encoded>/<remote_republish>` |
+| `unpaced` | `<encoded>` | `<encoded>/<remote_republish>` |
+| `both` | both | delivered as above, comparison on `<encoded>/unpaced/<remote_republish>` |
+
+**The delivered name is the same in all three.** Only what feeds the decode
+moves, so switching modes never changes what an application subscribes to.
+
+`unpaced` still runs the pacer: `/paced` and its `budget_ms` / `queue_depth`
+debug topics are published and recordable, they just do not reach the display.
+That is the A/B control — measure a pacer on a live link without changing what
+an operator sees.
+
+`both` runs the receiver's expensive stage twice (a codec decode plus, for
+`compressed`, a JPEG encode per frame) and adds one local topic; nothing extra
+crosses the link. It also consumes one of the four reverse-transport slots. It
+is a rehearsal and diagnosis switch — the comparison stream is deliberately not
+a status pipeline stage, because it is not something the link promises to
+deliver.
+
 The node also runs standalone against any packet stream:
 
 ```bash

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

@@ -230,22 +230,32 @@ parameters:
   it_4_foxglove_qmax: -1
   it_4_outgoing_suffix: # e.g. compressed (defaults to it_4_transport if not set)
 
+  # `irt_N_out_topic` overrides where a decode publishes. It exists so two slots
+  # can decode the *same* stream — the paced one under the name applications
+  # already subscribe to, an unpaced copy next to it for comparison
+  # (transport.playout.republish: both). Left unset, a decode publishes on
+  # ${irt_N_topic}/${irt_N_out_transport}, which is the only shape any session
+  # had before and the one every unpaced link still has.
   irt: false
   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_out_topic: # overrides the output remap; defaults to ${irt_1_topic}/${irt_1_out_transport}
   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_out_topic: # overrides the output remap; defaults to ${irt_2_topic}/${irt_2_out_transport}
   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_out_topic: # overrides the output remap; defaults to ${irt_3_topic}/${irt_3_out_transport}
   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_out_topic: # overrides the output remap; defaults to ${irt_4_topic}/${irt_4_out_transport}
   irt_4_paced: # "true" -> decode reads ${irt_4_topic}/paced
 
   # Receiver-side playout pacing (transport.playout in the session definition):
@@ -707,31 +717,35 @@ windows:
         - 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
+        - if [[ "${irt_1_out_topic}" != "None" ]]; then irt_out_topic="${irt_1_out_topic}"; else irt_out_topic="${irt_1_topic}/${irt_1_out_transport}"; 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_in_topic} --remap ${out_remap}:=${irt_1_topic}/${irt_1_out_transport})
+            --remap in/${irt_1_transport}:=${irt_in_topic} --remap ${out_remap}:=${irt_out_topic})
         - 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
+        - if [[ "${irt_2_out_topic}" != "None" ]]; then irt_out_topic="${irt_2_out_topic}"; else irt_out_topic="${irt_2_topic}/${irt_2_out_transport}"; 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_in_topic} --remap ${out_remap}:=${irt_2_topic}/${irt_2_out_transport})
+            --remap in/${irt_2_transport}:=${irt_in_topic} --remap ${out_remap}:=${irt_out_topic})
         - 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
+        - if [[ "${irt_3_out_topic}" != "None" ]]; then irt_out_topic="${irt_3_out_topic}"; else irt_out_topic="${irt_3_topic}/${irt_3_out_transport}"; 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_in_topic} --remap ${out_remap}:=${irt_3_topic}/${irt_3_out_transport})
+            --remap in/${irt_3_transport}:=${irt_in_topic} --remap ${out_remap}:=${irt_out_topic})
         - 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
+        - if [[ "${irt_4_out_topic}" != "None" ]]; then irt_out_topic="${irt_4_out_topic}"; else irt_out_topic="${irt_4_topic}/${irt_4_out_transport}"; 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_in_topic} --remap ${out_remap}:=${irt_4_topic}/${irt_4_out_transport})
+            --remap in/${irt_4_transport}:=${irt_in_topic} --remap ${out_remap}:=${irt_out_topic})
         - echo ${args[@]}
         - ${args[@]}

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

@@ -101,6 +101,44 @@ class TransportSpec:
     playout: Optional[Dict[str, Any]] = None
 
 
+#: What `transport.playout.republish` may say, and what each answer decodes.
+#: The delivered topic name is the same in all three -- only what feeds the
+#: decode moves, and `both` adds a second decode under a name of its own.
+PLAYOUT_REPUBLISH_MODES = ("paced", "unpaced", "both")
+PLAYOUT_REPUBLISH_DEFAULT = "paced"
+
+
+def playout_republish(playout: Dict[str, Any]) -> str:
+    """Which stream the receiver decodes, for a link that declares `playout`.
+
+    Only meaningful where a pacer runs. A link without `playout` has no paced
+    copy to read, so callers decide that case before asking -- passing None here
+    would answer 'paced' for a stream nothing paces.
+    """
+    return str((playout or {}).get("republish", PLAYOUT_REPUBLISH_DEFAULT))
+
+
+@dataclass
+class IrtSlot:
+    """One reverse-transport decode: what it reads, and where it publishes.
+
+    Four of these fit in the base plugin. Most links use one per direction, but
+    a comparison decode (`playout.republish: both`) is a second slot on the same
+    topic -- which is the only reason `out_topic` exists, since two decodes of
+    one stream would otherwise remap onto the same output name.
+    """
+
+    topic: str
+    ttype: str
+    out_transport: str
+    #: Set only for the slot that a pacer feeds; the pacer is configured from it.
+    playout: Optional[Dict[str, Any]] = None
+    #: Read '<topic>/paced' rather than '<topic>'.
+    reads_paced: bool = False
+    #: Override the output remap; None means '<topic>/<out_transport>'.
+    out_topic: Optional[str] = None
+
+
 @dataclass
 class TopicEntry:
     base: str
@@ -1746,7 +1784,7 @@ def _compute_pipeline(
         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"}
+            allowed = {"adaptive", "target_ms", "min_ms", "max_ms", "republish"}
             unknown = sorted(set(playout_cfg) - allowed)
             if unknown:
                 raise ValueError(
@@ -1769,6 +1807,15 @@ def _compute_pipeline(
                 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}'")
+            if "republish" in playout_cfg and playout_cfg["republish"] not in PLAYOUT_REPUBLISH_MODES:
+                raise ValueError(
+                    f"transport.playout.republish for topic '{entry.base}' is "
+                    f"{playout_cfg['republish']!r}; allowed: {list(PLAYOUT_REPUBLISH_MODES)}. "
+                    "'paced' decodes the paced copy (the default), 'unpaced' runs the pacer "
+                    "without putting it on the display path, and 'both' adds a second decode "
+                    "on '<encoded>/unpaced/<transport>' for comparison. The delivered topic "
+                    "name is the same in all three."
+                )
             playout = dict(playout_cfg)
 
         params = {k: v for k, v in t.items() if k not in ("type", "playout", *republish_keys)}
@@ -2781,11 +2828,12 @@ def func(
             nor_items.append((base, suffix))
 
         # Hard limits from session_plugin_base.yaml.
-        def _assert_max(label: str, items: List[Any], limit: int) -> None:
+        def _assert_max(label: str, items: List[Any], limit: int, note: str = "") -> None:
             if len(items) > limit:
                 raise RuntimeError(
                     f"peer '{local}': too many '{label}' entries ({len(items)}). "
                     f"The base session plugin supports at most {limit}."
+                    + (f" Note: {note}." if note else "")
                 )
 
         _assert_max("drp", drp_items, 8)
@@ -3319,31 +3367,58 @@ def func(
         # 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]]]] = []
+        irt_all: List[IrtSlot] = []
         for t, tspec in irt_items_local:
             assert tspec is not None
-            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
+            irt_all.append(IrtSlot(t, tspec.type, str(tspec.local_republish)))
+        for topic, tspec in irt_items_remote:
+            out_transport = str(tspec.remote_republish)
+            if tspec.playout is None:
+                # No pacer on this link: the decode reads what arrived. Asking
+                # it for '<topic>/paced' would give it a name nothing publishes,
+                # which advertises an output and then never fills it.
+                irt_all.append(IrtSlot(topic, tspec.type, out_transport))
+                continue
+            mode = playout_republish(tspec.playout)
+            # The decode an application reads keeps its name in every mode; only
+            # what feeds it moves. `unpaced` still runs the pacer -- it publishes
+            # '<topic>/paced' and its debug topics for measurement -- and simply
+            # does not put it on the display path.
+            irt_all.append(
+                IrtSlot(topic, tspec.type, out_transport, playout=tspec.playout, reads_paced=mode != "unpaced")
+            )
+            if mode == "both":
+                # The comparison branch: same stream, undelayed, under a name of
+                # its own. `<topic>/unpaced` is a valid image_transport base, so
+                # a viewer subscribes to it exactly like the delivered one.
+                irt_all.append(
+                    IrtSlot(topic, tspec.type, out_transport, out_topic=f"{topic}/unpaced/{out_transport}")
+                )
+        _assert_max(
+            "irt",
+            irt_all,
+            4,
+            note="a `playout.republish: both` comparison decode consumes a slot of its own",
         )
-        _assert_max("irt", irt_all, 4)
         if irt_all:
             items2 = [("irt", True)]
-            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, 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:
+            for i, slot in enumerate(irt_all, 1):
+                items2.append((f"irt_{i}_topic", slot.topic))
+            for i, slot in enumerate(irt_all, 1):
+                items2.append((f"irt_{i}_transport", slot.ttype))
+                items2.append((f"irt_{i}_out_transport", slot.out_transport))
+                if slot.out_topic is not None:
+                    items2.append((f"irt_{i}_out_topic", slot.out_topic))
+                if slot.reads_paced:
                     # 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
+            (i, slot.topic, slot.ttype, slot.playout)
+            for i, slot in enumerate(irt_all, 1)
+            if slot.playout is not None
         ]
         if paced_entries:
             items_pace: List[Tuple[str, Any]] = [("pace", True)]

{rosotacom_dev-2.5.dev53 → rosotacom_dev-2.5.dev54}/src/rosotacom_dev.egg-info/PKG-INFO

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

{rosotacom_dev-2.5.dev53 → rosotacom_dev-2.5.dev54}/src/rosotacom_dev.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
   "tag": "2.4",
-  "distance": 53,
-  "node": "g05d5905a4728651003afe5bc2feb657a96a1d395",
+  "distance": 54,
+  "node": "g28ff3da22234e297b05850ec0df7553546665959",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-19"

{rosotacom_dev-2.5.dev53 → rosotacom_dev-2.5.dev54}/tests/unit/test_session_pipeline.py

@@ -306,3 +306,91 @@ def test_generated_peer_files_wire_the_pacer(tmp_path: Path) -> None:
     sender = (tmp_path / "b" / "plugin.yaml").read_text(encoding="utf-8")
     assert "pace" not in sender or "pace_1_topic" not in sender
     assert "irt_1_paced" not in sender
+
+
+# `transport.playout.republish` — which stream the receiver decodes (#302).
+#
+# The improvement a pacer makes is invisible while it replaces the picture under
+# the same name: there is no moment where paced and unpaced are on screen
+# together. `both` puts them there. What must hold across all three modes is
+# that the *delivered* name never moves — an application subscribes to
+# `<encoded>/<out_transport>` whatever the mode, which is the rule #276 exists
+# to protect and exactly what a comparison switch could break in silence.
+
+
+def _receiver_plugin(tmp_path: Path, playout: dict | None) -> str:
+    transport: dict = {"type": "ffmpeg", "remote_republish": "compressed"}
+    if playout is not None:
+        transport["playout"] = playout
+    generator.func(
+        session_config_obj=_camera_cfg({"transport": transport, "use_ota_wrapper": True}),
+        output_dir=str(tmp_path),
+        force=True,
+        peer_addresses={"a": "127.0.0.1", "b": "127.0.0.2"},
+    )
+    return (tmp_path / "a" / "plugin.yaml").read_text(encoding="utf-8")
+
+
+def test_a_receiver_without_playout_decodes_what_arrived(tmp_path: Path) -> None:
+    """A link that paces nothing has no '/paced' for its decode to read.
+
+    Worth its own test because of how it fails: `image_transport republish`
+    advertises its output whether or not its input exists, so a decode pointed
+    at a name nobody publishes looks alive and delivers nothing. That is what
+    the `17_synthetic_camera_quality` slice caught while the whole unit suite
+    stayed green — the receiver's *unpaced* case had no assertion at all.
+    """
+    receiver = _receiver_plugin(tmp_path, None)
+
+    assert "irt_1_topic: /camera/image/ffmpeg" in receiver
+    assert "irt_1_paced" not in receiver
+    assert "irt_1_out_topic" not in receiver
+    assert "pace_1_topic" not in receiver
+
+
+def test_republish_rejects_a_mode_that_is_not_one_of_the_three() -> None:
+    with pytest.raises(ValueError, match="allowed: \\['paced', 'unpaced', 'both'\\]"):
+        _pipeline(_ffmpeg(playout={"republish": "compare"}))
+
+
+def test_paced_is_the_default_and_needs_no_output_override() -> None:
+    _entry, pipe = _pipeline(_ffmpeg(playout={}))
+    assert generator.playout_republish(pipe["transport"].playout) == "paced"
+
+
+def test_unpaced_runs_the_pacer_but_keeps_it_off_the_display_path(tmp_path: Path) -> None:
+    """The measurement mode: '/paced' and its debug topics exist, nothing reads them."""
+    receiver = _receiver_plugin(tmp_path, {"republish": "unpaced"})
+
+    assert "pace_1_topic: /camera/image/ffmpeg" in receiver
+    assert "irt_1_paced" not in receiver
+    assert "irt_1_out_topic" not in receiver
+
+
+def test_both_adds_a_second_decode_under_a_name_of_its_own(tmp_path: Path) -> None:
+    receiver = _receiver_plugin(tmp_path, {"republish": "both"})
+
+    # Slot 1 is the delivered one: paced input, unchanged output name.
+    assert "irt_1_topic: /camera/image/ffmpeg" in receiver
+    assert "irt_1_paced" in receiver
+    assert "irt_1_out_topic" not in receiver
+    # Slot 2 is the comparison: same stream, undelayed, qualified output.
+    assert "irt_2_topic: /camera/image/ffmpeg" in receiver
+    assert "irt_2_out_topic: /camera/image/ffmpeg/unpaced/compressed" in receiver
+    assert "irt_2_paced" not in receiver
+    # One pacer, not two -- the second decode reads what the first one's pacer
+    # was fed, and a second pacer on the same topic would publish onto the same
+    # '/paced' name.
+    assert "pace_2_topic" not in receiver
+
+
+def test_every_mode_delivers_the_same_topic_name(tmp_path: Path) -> None:
+    """The one invariant a comparison switch must not break."""
+    delivered = set()
+    for mode in ("paced", "unpaced", "both"):
+        _entry, pipe = _pipeline(_ffmpeg(playout={"republish": mode}))
+        delivered.add(generator._delivered_topic(pipe, pipe["final"]))
+    _entry, unpaced_link = _pipeline(_ffmpeg())
+    delivered.add(generator._delivered_topic(unpaced_link, unpaced_link["final"]))
+
+    assert len(delivered) == 1, delivered