rosotacom-dev 2.5.dev65__py3-none-any.whl → 2.5.dev67__py3-none-any.whl

rosotacom/resources/ws/ota_configs/cyclonedds_scoped.xml.template

@@ -0,0 +1,87 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+One CycloneDDS configuration for both of a peer's domains, each section scoped
+to the domain it belongs to.
+
+Set it as `shared.rmw.ota.cyclone.config` and leave the local one unset: this
+file already carries the local domain's section, so nothing has to overwrite
+anything.
+
+Why it exists. The two-file arrangement renders a local profile and an OTA
+profile and exports CYCLONEDDS_URI twice, so the second replaces the first and
+every process started after it views the *local* domain through the *OTA*
+profile. On CycloneDDS 0.10.5 that was survivable: participants configured
+differently on one host and one domain still exchanged data. On 11.0.1 they do
+not — they discover each other, announce their endpoints, match, and deliver
+nothing. Measured on one host, one domain, a publisher and a subscriber:
+
+  publisher / subscriber     0.10.5     11.0.1
+  local     / local          12 B       12 B
+  local     / ota            12 B       0
+  ota       / local          12 B       0
+  ota       / ota            12 B       12 B
+
+A session whose relay publishes under one profile and whose bridge subscribes
+under the other therefore hands nothing from the local domain into the OTA
+domain, and the link carries nothing while every stage looks healthy
+(docs/findings/one-domain-two-cyclone-configs-stop-interoperating.md).
+
+Scoping fixes the cause rather than the symptom: the OTA settings apply to the
+OTA domain, the local domain keeps default discovery with room for many
+participants, and one file can be shared by every process on the host.
+
+The two-file arrangement stays exactly as it was — this is an additional
+template, not a replacement, and a session that does not name it is unchanged.
+-->
+<CycloneDDS xmlns="https://cdds.io/config">
+  <!--
+  The OTA domain: interface-pinned, unicast-only, with the datagram caps the
+  provisioned link is sized for. Identical to cyclonedds_tuned.xml except that
+  it says which domain it is for.
+  -->
+  <Domain Id="#ota_domain">
+    <General>
+      <AllowMulticast>false</AllowMulticast>
+      <Interfaces>
+        <NetworkInterface address="#host_ip"/>
+      </Interfaces>
+      <MulticastRecvNetworkInterfaceAddresses>none</MulticastRecvNetworkInterfaceAddresses>
+      <!-- Strictly below MaxMessageSize; see cyclonedds_tuned.xml for what
+           making them equal cost. -->
+      <FragmentSize>1024B</FragmentSize>
+      <MaxMessageSize>1200B</MaxMessageSize>
+      <MaxRexmitMessageSize>1200B</MaxRexmitMessageSize>
+    </General>
+
+    <Discovery>
+      <Peers>
+        <!--peer-block--><Peer Address="#peer"/><!--/peer-block-->
+      </Peers>
+      <EnableTopicDiscoveryEndpoints>false</EnableTopicDiscoveryEndpoints>
+      <LeaseDuration>60s</LeaseDuration>
+      <SPDPInterval>#spdp_interval</SPDPInterval>
+    </Discovery>
+
+    <Internal>
+      <SquashParticipants>true</SquashParticipants>
+    </Internal>
+
+    <Tracing>
+      <Verbosity>config</Verbosity>
+      <OutputFile>/tmp/cyclonedds.log</OutputFile>
+    </Tracing>
+  </Domain>
+
+  <!--
+  The local domain: default discovery, more participants. It pins no interface,
+  disables no multicast and sets no peer list, because intra-host discovery has
+  to keep working — the same reasoning as cyclonedds_local_participants.xml,
+  including why 119 and not higher.
+  -->
+  <Domain Id="#local_domain">
+    <Discovery>
+      <ParticipantIndex>auto</ParticipantIndex>
+      <MaxAutoParticipantIndex>119</MaxAutoParticipantIndex>
+    </Discovery>
+  </Domain>
+</CycloneDDS>

rosotacom/resources/ws/ota_configs/get_ota_xml.py

@@ -15,8 +15,20 @@ import re
 import sys
 import tempfile
 
-
-KNOWN_PLACEHOLDERS = {"#host_ip", "#peer", "#easy_mode_ip", "#spdp_interval"}
+KNOWN_PLACEHOLDERS = {
+    "#host_ip",
+    "#peer",
+    "#easy_mode_ip",
+    "#spdp_interval",
+    #: A template that scopes its settings to one ROS domain resolves these.
+    #: Cyclone applies a <Domain> section to the domain its Id names, so a
+    #: single configuration can hold the OTA settings for the OTA domain and
+    #: leave the local domain alone — which is what lets every process on a
+    #: host share one configuration instead of half of them carrying the OTA
+    #: profile and half the local one.
+    "#local_domain",
+    "#ota_domain",
+}
 PLACEHOLDER_PATTERN = re.compile(r"#[A-Za-z_][A-Za-z0-9_]*")
 DEFAULT_SPDP_INTERVAL = "30s"
 
@@ -48,6 +60,19 @@ def _resolved_address(value: str, label: str) -> str:
     return address
 
 
+def _resolved_domain(value: str, label: str) -> str:
+    """A ROS domain id, validated rather than pasted into the XML.
+
+    An unusable Id is worse than a missing one: Cyclone keeps a <Domain>
+    section it cannot match to any domain, so the settings vanish without a
+    word and the link comes up on defaults.
+    """
+    domain = str(value).strip()
+    if not domain.isdigit() or not 0 <= int(domain) <= 232:
+        raise ValueError(f"{label} must be a ROS domain id between 0 and 232, got {value!r}.")
+    return str(int(domain))
+
+
 def _resolved_spdp_interval(value: str) -> str:
     interval = value.strip().lower()
     if not interval:
@@ -99,9 +124,7 @@ def _expand_peer_block(content: str, peer_ips: list) -> str:
 
     has_markers = PEER_BLOCK_OPEN in content
     if has_markers and (PEER_BLOCK_CLOSE not in content):
-        raise RuntimeError(
-            f"Template has '{PEER_BLOCK_OPEN}' without matching '{PEER_BLOCK_CLOSE}'."
-        )
+        raise RuntimeError(f"Template has '{PEER_BLOCK_OPEN}' without matching '{PEER_BLOCK_CLOSE}'.")
 
     if len(peer_ips) == 1 and not has_markers:
         return content.replace("#peer", peer_ips[0])
@@ -116,9 +139,7 @@ def _expand_peer_block(content: str, peer_ips: list) -> str:
 
     matches = list(PEER_BLOCK_PATTERN.finditer(content))
     if len(matches) != 1:
-        raise RuntimeError(
-            f"Template must contain exactly one peer-block region; found {len(matches)}."
-        )
+        raise RuntimeError(f"Template must contain exactly one peer-block region; found {len(matches)}.")
     m = matches[0]
     block = m.group(1)
     if "#peer" not in block:
@@ -128,11 +149,11 @@ def _expand_peer_block(content: str, peer_ips: list) -> str:
 
     # Preserve the indentation of the marker line so duplicated blocks align.
     line_start = content.rfind("\n", 0, m.start()) + 1
-    indent = content[line_start:m.start()]
+    indent = content[line_start : m.start()]
     sep = ("\n" + indent) if not indent.strip() else ""
 
     rendered = sep.join(block.replace("#peer", ip) for ip in peer_ips)
-    return content[:m.start()] + rendered + content[m.end():]
+    return content[: m.start()] + rendered + content[m.end() :]
 
 
 def main(
@@ -141,12 +162,14 @@ def main(
     peer: str = None,
     easy_mode_ip: str = None,
     spdp_interval: str = DEFAULT_SPDP_INTERVAL,
+    local_domain: str = None,
+    ota_domain: str = None,
 ) -> str:
     path = _template_path(config)
     if not os.path.exists(path):
         raise FileNotFoundError(f"Template not found: {path}")
 
-    with open(path, "r", encoding="utf-8") as f:
+    with open(path, encoding="utf-8") as f:
         content = f.read()
 
     found = set(PLACEHOLDER_PATTERN.findall(content))
@@ -159,9 +182,7 @@ def main(
 
     if "#host_ip" in found:
         if not host_ip:
-            raise RuntimeError(
-                f"Template '{os.path.basename(path)}' uses #host_ip but --host-ip was not provided."
-            )
+            raise RuntimeError(f"Template '{os.path.basename(path)}' uses #host_ip but --host-ip was not provided.")
         content = content.replace("#host_ip", _resolved_address(host_ip, "Host IP"))
 
     if "#easy_mode_ip" in found:
@@ -169,45 +190,60 @@ def main(
             raise RuntimeError(
                 f"Template '{os.path.basename(path)}' uses #easy_mode_ip but --easy-mode-ip was not provided."
             )
-        content = content.replace(
-            "#easy_mode_ip", _resolved_address(easy_mode_ip, "Easy Mode IP")
-        )
+        content = content.replace("#easy_mode_ip", _resolved_address(easy_mode_ip, "Easy Mode IP"))
 
     if "#spdp_interval" in found:
         content = content.replace("#spdp_interval", _resolved_spdp_interval(spdp_interval))
 
+    for placeholder, value, option in (
+        ("#local_domain", local_domain, "--local-domain"),
+        ("#ota_domain", ota_domain, "--ota-domain"),
+    ):
+        if placeholder in found:
+            if value is None or not str(value).strip():
+                raise RuntimeError(
+                    f"Template '{os.path.basename(path)}' uses {placeholder} but {option} was not provided."
+                )
+            content = content.replace(placeholder, _resolved_domain(value, placeholder))
+
     if "#peer" in found:
         if not peer:
-            raise RuntimeError(
-                f"Template '{os.path.basename(path)}' uses #peer but --peer was not provided."
-            )
+            raise RuntimeError(f"Template '{os.path.basename(path)}' uses #peer but --peer was not provided.")
         content = _expand_peer_block(content, _resolve_peer_ips(peer))
 
     return content
 
 
 if __name__ == "__main__":
-    parser = argparse.ArgumentParser(
-        description="Resolve placeholders in an OTA DDS XML template."
-    )
+    parser = argparse.ArgumentParser(description="Resolve placeholders in an OTA DDS XML template.")
     parser.add_argument(
-        "-c", "--config", required=True,
+        "-c",
+        "--config",
+        required=True,
         help="Template name (e.g. fastdds_v1.xml, cyclonedds.xml, fastdds_easy_mode.xml).",
     )
     parser.add_argument(
-        "-i", "--host-ip", dest="host_ip",
+        "-i",
+        "--host-ip",
+        dest="host_ip",
         help="Resolved local host address (#host_ip).",
     )
     parser.add_argument(
-        "-p", "--peer", dest="peer",
+        "-p",
+        "--peer",
+        dest="peer",
         help="Resolved peer address, or comma-separated addresses (#peer).",
     )
     parser.add_argument(
-        "-e", "--easy-mode-ip", dest="easy_mode_ip",
+        "-e",
+        "--easy-mode-ip",
+        dest="easy_mode_ip",
         help="Resolved Fast DDS Easy Mode address (#easy_mode_ip).",
     )
     parser.add_argument(
-        "-o", "--output", dest="output",
+        "-o",
+        "--output",
+        dest="output",
         help=(
             "Write the rendered XML to this path, atomically. Prefer this over a shell "
             "redirect: `> file` truncates the target before this script runs, so a "
@@ -216,6 +252,16 @@ if __name__ == "__main__":
             "comes up carrying nothing."
         ),
     )
+    parser.add_argument(
+        "--local-domain",
+        dest="local_domain",
+        help="Local ROS domain id, for a template that scopes a section to it (#local_domain).",
+    )
+    parser.add_argument(
+        "--ota-domain",
+        dest="ota_domain",
+        help="OTA ROS domain id, for a template that scopes a section to it (#ota_domain).",
+    )
     parser.add_argument(
         "--spdp-interval",
         dest="spdp_interval",
@@ -224,8 +270,7 @@ if __name__ == "__main__":
     )
     args = parser.parse_args()
     output = args.output
-    rendered = main(**{k: v for k, v in vars(args).items()
-                       if v is not None and k != "output"})
+    rendered = main(**{k: v for k, v in vars(args).items() if v is not None and k != "output"})
     if not output:
         print(rendered)
         raise SystemExit(0)

rosotacom/resources/ws/ros2src/com_py/com_py/ota_pcap.py

@@ -0,0 +1,402 @@
+"""Header-only packet capture of the OTA link, beside the link trace.
+
+Runs inside the communication container for the lifetime of one peer, started
+by `status_overview` when a session definition asks for it:
+
+    shared:
+      use_status_overview: true
+      ota_pcap:
+        enabled: true
+
+    python3 -m com_py.ota_pcap --iface tun0 --out .../ota.pcap [--peer 10.254.0.37]
+
+WHAT IT ANSWERS THAT `link_trace.jsonl` CANNOT
+----------------------------------------------
+The link trace counts `/proc/net/dev` bytes per direction once a second, which
+localises loss to a *direction* and no further. It cannot say which fragment of
+which sample was lost, whether a retransmit followed, or how one sample's
+sub-messages were spaced on the wire. Those are the questions a header-only
+capture answers, at roughly 1 % of payload volume.
+
+It is passive and local: nothing is transmitted, so it costs no link capacity,
+and the interface is never put into promiscuous mode — everything of interest
+is addressed to or from this host, and promiscuous mode on a control-centre LAN
+port would collect other people's traffic. `CAP_NET_ADMIN`, which the
+originating issue assumed was needed, buys only that.
+
+WHY IT LIVES HERE AND NOT NEXT TO A RECORDER
+--------------------------------------------
+The first implementation of this sat beside the recording tool in the
+downstream project, and had to rebuild what this container already knows:
+which interface carries the link, and to which peer. `link_bytes` answers both
+from the peer's own OTA address — including the refusal that matters most, a
+loopback interface for a non-loopback address, which once read 28 Gbit/s next
+to a 6 Mbit/s link and survived a field session (#267). A capture that has to
+re-derive link knowledge is in the wrong place; this one asks the same
+resolution the status snapshot's own link block uses.
+
+It also needs no privilege here. This container already runs as root with
+`CAP_NET_RAW` in the default docker set, so the option adds no capability, no
+image change and no container.
+
+THE FILE
+--------
+`SOCK_DGRAM` rather than `SOCK_RAW`, which is what makes one code path work on
+both link types the fleet uses: a VPN `tun` device is layer 3 and has no
+link-layer header at all, while a LAN port is Ethernet. The kernel hands a
+`SOCK_DGRAM` packet socket the network-layer packet either way, plus the
+`sockaddr_ll` that says what the link layer was.
+
+That is exactly the input `LINKTYPE_LINUX_SLL` (113) is defined over, so the
+16-byte SLL pseudo-header is synthesized from the address tuple and the file
+reads in Wireshark, tshark and scapy without a hint. It carries the field the
+analysis is actually for: `pkttype` distinguishes PACKET_OUTGOING from
+PACKET_HOST, so **every packet in the file is labelled uplink or downlink** —
+which is the direction question the per-second counters answer only coarsely,
+and the one a direction-blind `LINKTYPE_RAW` capture would have thrown away.
+
+Timestamps come from the kernel (`SO_TIMESTAMPNS`), not from the moment python
+got round to the packet, and are written at microsecond resolution — the
+classic `0xa1b2c3d4` magic, because every reader takes it and a millisecond
+phenomenon does not need nanoseconds.
+
+HONESTY ABOUT WHAT IT MISSED
+----------------------------
+A capture that quietly drops packets is worse than none: the analysis would
+read the gap as radio loss. So `PACKET_STATISTICS` is read from the kernel and
+the sidecar `.json` reports `kernel_drops` next to `packets`. A non-zero drop
+count means this process fell behind, not that the link did.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import signal
+import socket
+import struct
+import sys
+import time
+from pathlib import Path
+
+#: Capture every ethertype; the protocol filter is applied below, on the
+#: network-layer header the kernel hands a SOCK_DGRAM packet socket.
+ETH_P_ALL = 0x0003
+
+ETH_P_IP = 0x0800
+ETH_P_IPV6 = 0x86DD
+IPPROTO_UDP = 17
+
+#: linux/if_packet.h. Only the outgoing one is load-bearing — it is what makes
+#: a packet uplink rather than downlink — but all five are written through so a
+#: reader sees what the kernel saw.
+PACKET_OUTGOING = 4
+
+SOL_PACKET = 263
+PACKET_STATISTICS = 6
+
+#: CPython does not export these on every build — 3.12 in the recorder image
+#: has neither, which cost the first capture its kernel timestamps and left it
+#: stamping packets when python got round to them. The numbers are the
+#: asm-generic ones every architecture the fleet runs uses, and `SCM_` shares
+#: the `SO_` value by definition (linux/socket.h).
+SO_TIMESTAMPNS = getattr(socket, "SO_TIMESTAMPNS", 35)
+SCM_TIMESTAMPNS = getattr(socket, "SCM_TIMESTAMPNS", 35)
+
+#: pcap, classic microsecond magic (LE). Every reader takes it.
+PCAP_MAGIC = 0xA1B2C3D4
+LINKTYPE_LINUX_SLL = 113
+
+#: `-s 96` in the issue: enough for the link, network, UDP and RTPS sub-message
+#: headers, and short of any payload.
+DEFAULT_SNAPLEN = 96
+
+#: Not part of the recorder's own disk budget, and deliberately far above what
+#: a drive produces: header-only at 500 packets/s is ~6 MB per minute, so a
+#: two-hour drive is well under a gigabyte. It exists to bound a mistake — a
+#: capture pointed at a busy control-centre LAN port — not to shape a drive.
+DEFAULT_MAX_MB = 2000
+
+#: 4 MiB of kernel socket buffer. The default is a few hundred kilobytes, which
+#: is where `kernel_drops` comes from on a burst.
+RCVBUF_BYTES = 4 << 20
+
+
+def log(message: str) -> None:
+    print(f"[ota_pcap] {message}", flush=True)
+
+
+# ------------------------------------------------------------------ the file
+
+
+def pcap_header(snaplen: int) -> bytes:
+    return struct.pack(
+        "<IHHiIII",
+        PCAP_MAGIC,
+        2,  # version_major
+        4,  # version_minor
+        0,  # thiszone: timestamps are UTC
+        0,  # sigfigs, as every writer leaves it
+        snaplen,
+        LINKTYPE_LINUX_SLL,
+    )
+
+
+def sll_header(pkttype: int, hatype: int, addr: bytes, protocol: int) -> bytes:
+    """The 16-byte pseudo-header LINKTYPE_LINUX_SLL is defined over.
+
+    Big-endian, unlike the pcap headers around it — that is the format, not an
+    oversight. `addr` is padded to the fixed 8 bytes and its true length is
+    written next to it, which is how a reader tells a 6-byte MAC from the empty
+    address a layer-3 tunnel has.
+    """
+    address = (addr or b"")[:8]
+    return struct.pack(
+        "!HHH8sH",
+        pkttype,
+        hatype,
+        len(address),
+        address.ljust(8, b"\0"),
+        protocol,
+    )
+
+
+def record_header(seconds: int, micros: int, incl_len: int, orig_len: int) -> bytes:
+    return struct.pack("<IIII", seconds, micros, incl_len, orig_len)
+
+
+# --------------------------------------------------------------- the filter
+
+
+def is_udp(protocol: int, packet: bytes) -> bool:
+    """UDP, judged from the network-layer header the packet socket handed us.
+
+    Both branches read a fixed offset of the header the kernel guarantees is
+    there, so a truncated or malformed packet is answered `False` rather than
+    raising inside the capture loop.
+
+    IPv4 fragments after the first carry no UDP header, and are still matched:
+    the protocol field is in the IP header of every fragment, which is what
+    keeps a fragmented sample whole in the file.
+    """
+    if protocol == ETH_P_IP:
+        return len(packet) > 9 and packet[9] == IPPROTO_UDP
+    if protocol == ETH_P_IPV6:
+        # Next Header. An extension-header chain would hide the UDP behind it;
+        # nothing on this link uses one, and guessing past it would be the kind
+        # of cleverness that silently drops traffic.
+        return len(packet) > 6 and packet[6] == IPPROTO_UDP
+    return False
+
+
+def addresses_of(protocol: int, packet: bytes) -> tuple[str, str] | None:
+    """Source and destination, for the optional peer filter."""
+    try:
+        if protocol == ETH_P_IP and len(packet) >= 20:
+            return (
+                socket.inet_ntop(socket.AF_INET, packet[12:16]),
+                socket.inet_ntop(socket.AF_INET, packet[16:20]),
+            )
+        if protocol == ETH_P_IPV6 and len(packet) >= 40:
+            return (
+                socket.inet_ntop(socket.AF_INET6, packet[8:24]),
+                socket.inet_ntop(socket.AF_INET6, packet[24:40]),
+            )
+    except (ValueError, OSError):
+        return None
+    return None
+
+
+def wanted(protocol: int, packet: bytes, peer: str | None) -> bool:
+    if not is_udp(protocol, packet):
+        return False
+    if peer is None:
+        return True
+    pair = addresses_of(protocol, packet)
+    return bool(pair) and peer in pair
+
+
+# ---------------------------------------------------------------- capturing
+
+
+def open_socket(iface: str) -> socket.socket:
+    """A non-promiscuous packet socket, bound to one interface.
+
+    `SOCK_DGRAM` normalises the two link types the fleet has — see the module
+    header. No `PACKET_ADD_MEMBERSHIP`, so the interface is never put into
+    promiscuous mode and only this host's own traffic is seen.
+    """
+    sock = socket.socket(socket.AF_PACKET, socket.SOCK_DGRAM, socket.htons(ETH_P_ALL))
+    try:
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_RCVBUF, RCVBUF_BYTES)
+    except OSError:  # a smaller buffer is a worse capture, not a broken one
+        pass
+    try:
+        sock.setsockopt(socket.SOL_SOCKET, SO_TIMESTAMPNS, 1)
+    except OSError:
+        log("WARN the kernel refused SO_TIMESTAMPNS — timestamps are taken in "
+            "userspace, so they carry this process's scheduling delay")
+    sock.bind((iface, ETH_P_ALL))
+    return sock
+
+
+def kernel_timestamp(ancdata) -> tuple[int, int] | None:
+    """(seconds, microseconds) out of SCM_TIMESTAMPNS, if the kernel sent it."""
+    for level, kind, data in ancdata:
+        if level == socket.SOL_SOCKET and kind == SCM_TIMESTAMPNS:
+            if len(data) >= 16:
+                seconds, nanos = struct.unpack("qq", data[:16])
+                return int(seconds), int(nanos) // 1000
+    return None
+
+
+def packet_statistics(sock: socket.socket) -> tuple[int, int]:
+    """(seen, dropped) since the last call — reading resets the counters."""
+    try:
+        raw = sock.getsockopt(SOL_PACKET, PACKET_STATISTICS, 8)
+    except OSError:
+        return 0, 0
+    seen, dropped = struct.unpack("II", raw)
+    return int(seen), int(dropped)
+
+
+class Capture:
+    """One pcap file, and the counts needed to trust it."""
+
+    def __init__(self, iface: str, out: Path, *, snaplen: int = DEFAULT_SNAPLEN,
+                 peer: str | None = None, max_bytes: int = DEFAULT_MAX_MB * 1000 * 1000):
+        self.iface = iface
+        self.out = out
+        self.snaplen = snaplen
+        self.peer = peer
+        self.max_bytes = max_bytes
+        self.packets = 0
+        self.bytes_written = 0
+        self.kernel_drops = 0
+        self.kernel_seen = 0
+        self.first_ts: float | None = None
+        self.last_ts: float | None = None
+        self.stopped_because = "signal"
+
+    def sidecar(self) -> dict:
+        """What the file is, and what it is missing. Written next to the pcap."""
+        return {
+            "interface": self.iface,
+            "snaplen": self.snaplen,
+            "linktype": "LINKTYPE_LINUX_SLL",
+            "filter": "udp" + (f" and host {self.peer}" if self.peer else ""),
+            "promiscuous": False,
+            "packets": self.packets,
+            "bytes": self.bytes_written,
+            # Packets the kernel dropped because this process fell behind. A
+            # non-zero value here is a gap in the FILE, not in the link, and
+            # any loss analysis has to subtract it rather than report it.
+            "kernel_drops": self.kernel_drops,
+            "kernel_seen": self.kernel_seen,
+            "first_timestamp": self.first_ts,
+            "last_timestamp": self.last_ts,
+            "stopped_because": self.stopped_because,
+        }
+
+    def run(self, stop: list) -> None:
+        sock = open_socket(self.iface)
+        packet_statistics(sock)  # zero the counters; the run owns them from here
+        ancillary = socket.CMSG_SPACE(16)
+        self.out.parent.mkdir(parents=True, exist_ok=True)
+        with open(self.out, "wb", buffering=1 << 20) as handle:
+            handle.write(pcap_header(self.snaplen))
+            self.bytes_written = 24
+            sock.settimeout(0.5)
+            while not stop:
+                try:
+                    packet, ancdata, _flags, address = sock.recvmsg(65535, ancillary)
+                except socket.timeout:
+                    continue
+                except OSError as error:
+                    log(f"WARN capture socket: {error}")
+                    self.stopped_because = f"socket error: {error}"
+                    break
+                # (ifname, protocol, pkttype, hatype, addr) — everything the
+                # SLL header needs, which is why SOCK_DGRAM is enough.
+                _name, protocol, pkttype, hatype, addr = address
+                if not wanted(protocol, packet, self.peer):
+                    continue
+                stamp = kernel_timestamp(ancdata)
+                if stamp is None:
+                    now = time.time()
+                    stamp = (int(now), int((now % 1) * 1_000_000))
+                body = sll_header(pkttype, hatype, addr, protocol) + packet
+                orig_len = len(body)
+                clipped = body[: self.snaplen]
+                handle.write(record_header(stamp[0], stamp[1], len(clipped), orig_len))
+                handle.write(clipped)
+                self.packets += 1
+                self.bytes_written += 16 + len(clipped)
+                seconds = stamp[0] + stamp[1] / 1_000_000
+                if self.first_ts is None:
+                    self.first_ts = seconds
+                self.last_ts = seconds
+                if self.bytes_written >= self.max_bytes:
+                    log(f"stopping at the {self.max_bytes // 1000 // 1000} MB ceiling "
+                        f"after {self.packets} packets — the recording is untouched")
+                    self.stopped_because = "size ceiling"
+                    break
+                if self.packets % 20000 == 0:
+                    self._collect(sock)
+        self._collect(sock)
+        sock.close()
+
+    def _collect(self, sock: socket.socket) -> None:
+        seen, dropped = packet_statistics(sock)
+        self.kernel_seen += seen
+        self.kernel_drops += dropped
+
+
+# --------------------------------------------------------------------- main
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Header-only UDP capture on one interface, written as pcap.")
+    parser.add_argument("--iface", required=True, help="interface to capture on")
+    parser.add_argument("--out", required=True, type=Path, help="pcap file to write")
+    parser.add_argument("--snaplen", type=int, default=DEFAULT_SNAPLEN,
+                        help=f"bytes kept per packet (default {DEFAULT_SNAPLEN})")
+    parser.add_argument("--peer", help="keep only packets to or from this address")
+    parser.add_argument("--max-mb", type=int, default=DEFAULT_MAX_MB,
+                        help=f"stop after this many MB (default {DEFAULT_MAX_MB})")
+    args = parser.parse_args(argv)
+
+    capture = Capture(args.iface, args.out, snaplen=args.snaplen, peer=args.peer,
+                      max_bytes=args.max_mb * 1000 * 1000)
+
+    stop: list = []
+    for name in (signal.SIGINT, signal.SIGTERM):
+        signal.signal(name, lambda *_: stop.append(True))
+
+    log(f"{args.iface} -> {args.out} (-s {args.snaplen}, udp"
+        f"{f' and host {args.peer}' if args.peer else ''})")
+    try:
+        capture.run(stop)
+    except PermissionError:
+        log("FAIL no permission to open a packet socket. Inside the recorder "
+            "container this should not happen — CAP_NET_RAW is in docker's "
+            "default set. Outside it, run as root.")
+        return 3
+    except OSError as error:
+        log(f"FAIL {error}")
+        return 3
+
+    sidecar = capture.sidecar()
+    args.out.with_suffix(".json").write_text(
+        json.dumps(sidecar, indent=2) + "\n", encoding="utf-8")
+    log(f"{sidecar['packets']} packets, {sidecar['bytes'] / 1e6:.1f} MB, "
+        f"{sidecar['kernel_drops']} dropped by the kernel")
+    if sidecar["kernel_drops"]:
+        log("WARN the kernel dropped packets: that is a gap in THIS FILE, not "
+            "on the link. Subtract it before reading any loss out of the pcap.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

rosotacom/resources/ws/ros2src/com_py/com_py/status_overview.py

@@ -54,6 +54,9 @@
 from __future__ import annotations
 
 import os
+import signal
+import subprocess
+import sys
 import threading
 from typing import Dict, Optional
 
@@ -375,6 +378,14 @@ class StatusOverview(Node):
         # (the snapshot's `link` block is null).
         self.declare_parameter("ota_interface", "")
         self.declare_parameter("ota_local_ip", "")
+        # Header-only capture of the OTA link, beside the link trace. Off
+        # unless a session definition asks for it; it needs the same interface
+        # resolution as the link sampler above and nothing else.
+        self.declare_parameter("ota_pcap", False)
+        self.declare_parameter("ota_pcap_snaplen", 96)
+        self.declare_parameter("ota_pcap_max_mb", 2000)
+        self.declare_parameter("ota_pcap_peer_filter", True)
+        self.declare_parameter("ota_pcap_peer_ip", "")
         self.declare_parameter("link_trace", False)
         self.declare_parameter("link_trace_interval_s", 1.0)
         self.declare_parameter("link_trace_modem_command", "")
@@ -475,6 +486,10 @@ class StatusOverview(Node):
                     f"'{ota_interface}' ({provenance})"
                 )
 
+        self._pcap: Optional[subprocess.Popen] = None
+        if bool(self.get_parameter("ota_pcap").value):
+            self._start_ota_pcap(output_dir, ota_interface if link_sampler else "")
+
         link_trace_recorder = None
         if bool(self.get_parameter("link_trace").value):
             link_trace_path = os.path.join(output_dir, "link_trace.jsonl")
@@ -518,10 +533,88 @@ class StatusOverview(Node):
         ):
             executor.add_node(self._ota_observer)
 
+    def _start_ota_pcap(self, output_dir: str, interface: str) -> None:
+        """Begin the header-only capture, or say why there is none.
+
+        A separate process, not a thread: this node writes the status snapshot
+        every interval and is the thing an operator watches, so a capture that
+        misbehaves must not be able to reach it. It is still the same container
+        — no capability, no image and no `docker ps` line is added by the
+        option — which is the whole reason the capture lives here rather than
+        beside a recorder.
+
+        Never raises. The capture is a sidecar to the link, not a precondition
+        for it, and a session that cannot capture must still run.
+        """
+        if not interface:
+            # `ota_local_ip`/`ota_interface` are what resolve it, and the
+            # resolution above already said why it failed — including the
+            # loopback refusal, which is the failure worth repeating (#267).
+            self.get_logger().warning(
+                "status_overview: ota_pcap is enabled but no OTA interface was "
+                "resolved; capturing nothing. Set shared.ota_pcap only where "
+                "ota_local_ip resolves, and read the warning above for why."
+            )
+            return
+
+        path = os.path.join(output_dir, "ota.pcap")
+        argv = [
+            sys.executable, "-m", "com_py.ota_pcap",
+            "--iface", interface,
+            "--out", path,
+            "--snaplen", str(int(self.get_parameter("ota_pcap_snaplen").value)),
+            "--max-mb", str(int(self.get_parameter("ota_pcap_max_mb").value)),
+        ]
+        # Narrowed to the remote peer by default. On a VPN tunnel the whole
+        # device is the link and the filter changes nothing; on a LAN port it
+        # is the difference between the link and every other conversation the
+        # machine is having.
+        peer_ip = str(self.get_parameter("ota_pcap_peer_ip").value or "").strip()
+        if bool(self.get_parameter("ota_pcap_peer_filter").value) and peer_ip:
+            argv += ["--peer", peer_ip]
+
+        try:
+            self._pcap = subprocess.Popen(argv, start_new_session=True)
+        except OSError as exc:  # noqa: BLE001 - a sidecar may not stop a session
+            self.get_logger().warning(
+                f"status_overview: ota_pcap could not start ({exc}); "
+                "the session runs without a capture"
+            )
+            self._pcap = None
+            return
+        self.get_logger().info(
+            f"status_overview: ota_pcap capturing {interface} -> {path}"
+            + (f" (to/from {peer_ip})" if peer_ip and
+               bool(self.get_parameter("ota_pcap_peer_filter").value) else "")
+        )
+
+    def _stop_ota_pcap(self) -> None:
+        """SIGINT and wait, so the sidecar JSON and the drop counts are written.
+
+        Killed instead, the pcap on disk is still readable — it is written as
+        it goes — but `kernel_drops` never lands, and that is the one number
+        that separates a gap in the file from a gap on the link.
+        """
+        child, self._pcap = self._pcap, None
+        if child is None or child.poll() is not None:
+            return
+        try:
+            child.send_signal(signal.SIGINT)
+            child.wait(timeout=20.0)
+        except subprocess.TimeoutExpired:
+            child.kill()
+            try:
+                child.wait(timeout=5.0)
+            except subprocess.TimeoutExpired:
+                pass
+        except OSError:
+            pass
+
     def _on_write(self) -> None:
         self.aggregator.write()
 
     def shutdown(self) -> None:
+        self._stop_ota_pcap()
         if self._ota_executor is not None:
             try:
                 self._ota_executor.shutdown()

rosotacom/resources/ws/session/content/base/session_plugin_base.yaml

@@ -71,6 +71,13 @@ parameters:
   link_trace_interval_s: 1.0
   link_trace_modem_command: ""
   link_trace_modem_timeout_s: 2.0
+  # Header-only capture of the OTA link (docs/ota-pcap.md). Off here, so a
+  # session that does not ask for it renders the same command line it always
+  # did; `shared.ota_pcap.enabled` is what turns it on.
+  ota_pcap: false
+  ota_pcap_snaplen: 96
+  ota_pcap_max_mb: 2000
+  ota_pcap_peer_filter: true
   metric_stage_bag: false
   metric_stage_topics:
 
@@ -292,7 +299,7 @@ common:
   before_commands:
     - if [ '${local_domain_id}' != "None" ] && [ -n '${local_domain_id}' ]; then export ROS_DOMAIN_ID='${local_domain_id}'; fi
     - if [ '${rmw_local}' != "None" ]; then case ${rmw_local} in cyclone) export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp;; fastdds) export RMW_IMPLEMENTATION=rmw_fastrtps_cpp; export FASTDDS_BUILTIN_TRANSPORTS=${FASTDDS_BUILTIN_TRANSPORTS:-UDPv4};; zenoh) export RMW_IMPLEMENTATION=rmw_zenoh_cpp;; *) export RMW_IMPLEMENTATION='${rmw_local}';; esac; fi
-    - if [ '${local_config_template}' != "None" ] && [ -n '${local_config_template}' ]; then local_args=(--config "${local_config_template}" --host-ip "${ip_local}" --peer "${ip_remote}"); [ '${local_easy_mode_ip}' != "None" ] && [ -n '${local_easy_mode_ip}' ] && local_args+=(--easy-mode-ip "${local_easy_mode_ip}"); [ '${local_spdp_interval}' != "None" ] && [ -n '${local_spdp_interval}' ] && local_args+=(--spdp-interval "${local_spdp_interval}"); python3 /ws/ota_configs/get_ota_xml.py "${local_args[@]}" --output "${local_config_file}" || { echo "FATAL - could not render the local DDS profile ${local_config_template}; refusing to start on defaults." >&2; exit 1; }; case ${rmw_local} in cyclone) export CYCLONEDDS_URI="file://${local_config_file}";; fastdds) export FASTDDS_DEFAULT_PROFILES_FILE="${local_config_file}"; export RMW_FASTRTPS_USE_QOS_FROM_XML=1;; esac; fi
+    - if [ '${local_config_template}' != "None" ] && [ -n '${local_config_template}' ]; then local_args=(--config "${local_config_template}" --host-ip "${ip_local}" --peer "${ip_remote}"); [ '${local_domain_id}' != "None" ] && [ -n '${local_domain_id}' ] && local_args+=(--local-domain "${local_domain_id}"); [ '${ota_domain_id}' != "None" ] && [ -n '${ota_domain_id}' ] && local_args+=(--ota-domain "${ota_domain_id}"); [ '${local_easy_mode_ip}' != "None" ] && [ -n '${local_easy_mode_ip}' ] && local_args+=(--easy-mode-ip "${local_easy_mode_ip}"); [ '${local_spdp_interval}' != "None" ] && [ -n '${local_spdp_interval}' ] && local_args+=(--spdp-interval "${local_spdp_interval}"); python3 /ws/ota_configs/get_ota_xml.py "${local_args[@]}" --output "${local_config_file}" || { echo "FATAL - could not render the local DDS profile ${local_config_template}; refusing to start on defaults." >&2; exit 1; }; case ${rmw_local} in cyclone) export CYCLONEDDS_URI="file://${local_config_file}";; fastdds) export FASTDDS_DEFAULT_PROFILES_FILE="${local_config_file}"; export RMW_FASTRTPS_USE_QOS_FROM_XML=1;; esac; fi
     - if [ '${before_command}' != "None" ]; then ${before_command}; fi
 
 windows:
@@ -338,7 +345,7 @@ windows:
     if: use_domain_bridge
     splits:
       - commands:
-        - if [ '${ota_config_template}' != "None" ] && [ -n '${ota_config_template}' ]; then ota_args=(--config "${ota_config_template}" --host-ip "${ip_local}" --peer "${ip_remote}"); [ '${ota_easy_mode_ip}' != "None" ] && [ -n '${ota_easy_mode_ip}' ] && ota_args+=(--easy-mode-ip "${ota_easy_mode_ip}"); [ '${ota_spdp_interval}' != "None" ] && [ -n '${ota_spdp_interval}' ] && ota_args+=(--spdp-interval "${ota_spdp_interval}"); python3 /ws/ota_configs/get_ota_xml.py "${ota_args[@]}" --output "${ota_config_file}" || { echo "FATAL - could not render the OTA DDS profile ${ota_config_template}; refusing to start on defaults." >&2; exit 1; }; case ${rmw_ota} in cyclone) export CYCLONEDDS_URI="file://${ota_config_file}";; fastdds) export FASTDDS_DEFAULT_PROFILES_FILE="${ota_config_file}"; export RMW_FASTRTPS_USE_QOS_FROM_XML=1;; esac; fi
+        - if [ '${ota_config_template}' != "None" ] && [ -n '${ota_config_template}' ]; then ota_args=(--config "${ota_config_template}" --host-ip "${ip_local}" --peer "${ip_remote}"); [ '${local_domain_id}' != "None" ] && [ -n '${local_domain_id}' ] && ota_args+=(--local-domain "${local_domain_id}"); [ '${ota_domain_id}' != "None" ] && [ -n '${ota_domain_id}' ] && ota_args+=(--ota-domain "${ota_domain_id}"); [ '${ota_easy_mode_ip}' != "None" ] && [ -n '${ota_easy_mode_ip}' ] && ota_args+=(--easy-mode-ip "${ota_easy_mode_ip}"); [ '${ota_spdp_interval}' != "None" ] && [ -n '${ota_spdp_interval}' ] && ota_args+=(--spdp-interval "${ota_spdp_interval}"); python3 /ws/ota_configs/get_ota_xml.py "${ota_args[@]}" --output "${ota_config_file}" || { echo "FATAL - could not render the OTA DDS profile ${ota_config_template}; refusing to start on defaults." >&2; exit 1; }; case ${rmw_ota} in cyclone) export CYCLONEDDS_URI="file://${ota_config_file}";; fastdds) export FASTDDS_DEFAULT_PROFILES_FILE="${ota_config_file}"; export RMW_FASTRTPS_USE_QOS_FROM_XML=1;; esac; fi
         - ros2 run domain_bridge domain_bridge --wait-for-publisher false ${domain_bridge_config_file}
   - name: IN
     if: in
@@ -346,7 +353,7 @@ windows:
       - commands:
         - if [ '${ota_domain_id}' != "None" ] && [ -n '${ota_domain_id}' ]; then export ROS_DOMAIN_ID='${ota_domain_id}'; fi
         - case ${rmw_ota} in cyclone) export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp;; fastdds) export RMW_IMPLEMENTATION=rmw_fastrtps_cpp; export FASTDDS_BUILTIN_TRANSPORTS=${FASTDDS_BUILTIN_TRANSPORTS:-UDPv4};; zenoh) export RMW_IMPLEMENTATION=rmw_zenoh_cpp;; esac
-        - if [ '${ota_config_template}' != "None" ] && [ -n '${ota_config_template}' ]; then ota_args=(--config "${ota_config_template}" --host-ip "${ip_local}" --peer "${ip_remote}"); [ '${ota_easy_mode_ip}' != "None" ] && [ -n '${ota_easy_mode_ip}' ] && ota_args+=(--easy-mode-ip "${ota_easy_mode_ip}"); [ '${ota_spdp_interval}' != "None" ] && [ -n '${ota_spdp_interval}' ] && ota_args+=(--spdp-interval "${ota_spdp_interval}"); python3 /ws/ota_configs/get_ota_xml.py "${ota_args[@]}" --output "${ota_config_file}" || { echo "FATAL - could not render the OTA DDS profile ${ota_config_template}; refusing to start on defaults." >&2; exit 1; }; case ${rmw_ota} in cyclone) export CYCLONEDDS_URI="file://${ota_config_file}";; fastdds) export FASTDDS_DEFAULT_PROFILES_FILE="${ota_config_file}"; export RMW_FASTRTPS_USE_QOS_FROM_XML=1;; esac; fi
+        - if [ '${ota_config_template}' != "None" ] && [ -n '${ota_config_template}' ]; then ota_args=(--config "${ota_config_template}" --host-ip "${ip_local}" --peer "${ip_remote}"); [ '${local_domain_id}' != "None" ] && [ -n '${local_domain_id}' ] && ota_args+=(--local-domain "${local_domain_id}"); [ '${ota_domain_id}' != "None" ] && [ -n '${ota_domain_id}' ] && ota_args+=(--ota-domain "${ota_domain_id}"); [ '${ota_easy_mode_ip}' != "None" ] && [ -n '${ota_easy_mode_ip}' ] && ota_args+=(--easy-mode-ip "${ota_easy_mode_ip}"); [ '${ota_spdp_interval}' != "None" ] && [ -n '${ota_spdp_interval}' ] && ota_args+=(--spdp-interval "${ota_spdp_interval}"); python3 /ws/ota_configs/get_ota_xml.py "${ota_args[@]}" --output "${ota_config_file}" || { echo "FATAL - could not render the OTA DDS profile ${ota_config_template}; refusing to start on defaults." >&2; exit 1; }; case ${rmw_ota} in cyclone) export CYCLONEDDS_URI="file://${ota_config_file}";; fastdds) export FASTDDS_DEFAULT_PROFILES_FILE="${ota_config_file}"; export RMW_FASTRTPS_USE_QOS_FROM_XML=1;; esac; fi
         # For zenoh_ros2dds the OTA domain is loopback-only (zenoh is the inter-host
         # transport), so confine discovery to localhost instead of statically peering
         # the remote host — otherwise the OTA-domain DDS double-delivers alongside zenoh.
@@ -373,7 +380,7 @@ windows:
       - commands:
         - if [ '${ota_domain_id}' != "None" ] && [ -n '${ota_domain_id}' ]; then export ROS_DOMAIN_ID='${ota_domain_id}'; fi
         - case ${rmw_ota} in cyclone) export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp;; fastdds) export RMW_IMPLEMENTATION=rmw_fastrtps_cpp; export FASTDDS_BUILTIN_TRANSPORTS=${FASTDDS_BUILTIN_TRANSPORTS:-UDPv4};; zenoh) export RMW_IMPLEMENTATION=rmw_zenoh_cpp;; esac
-        - if [ '${ota_config_template}' != "None" ] && [ -n '${ota_config_template}' ]; then ota_args=(--config "${ota_config_template}" --host-ip "${ip_local}" --peer "${ip_remote}"); [ '${ota_easy_mode_ip}' != "None" ] && [ -n '${ota_easy_mode_ip}' ] && ota_args+=(--easy-mode-ip "${ota_easy_mode_ip}"); [ '${ota_spdp_interval}' != "None" ] && [ -n '${ota_spdp_interval}' ] && ota_args+=(--spdp-interval "${ota_spdp_interval}"); python3 /ws/ota_configs/get_ota_xml.py "${ota_args[@]}" --output "${ota_config_file}" || { echo "FATAL - could not render the OTA DDS profile ${ota_config_template}; refusing to start on defaults." >&2; exit 1; }; case ${rmw_ota} in cyclone) export CYCLONEDDS_URI="file://${ota_config_file}";; fastdds) export FASTDDS_DEFAULT_PROFILES_FILE="${ota_config_file}"; export RMW_FASTRTPS_USE_QOS_FROM_XML=1;; esac; fi
+        - if [ '${ota_config_template}' != "None" ] && [ -n '${ota_config_template}' ]; then ota_args=(--config "${ota_config_template}" --host-ip "${ip_local}" --peer "${ip_remote}"); [ '${local_domain_id}' != "None" ] && [ -n '${local_domain_id}' ] && ota_args+=(--local-domain "${local_domain_id}"); [ '${ota_domain_id}' != "None" ] && [ -n '${ota_domain_id}' ] && ota_args+=(--ota-domain "${ota_domain_id}"); [ '${ota_easy_mode_ip}' != "None" ] && [ -n '${ota_easy_mode_ip}' ] && ota_args+=(--easy-mode-ip "${ota_easy_mode_ip}"); [ '${ota_spdp_interval}' != "None" ] && [ -n '${ota_spdp_interval}' ] && ota_args+=(--spdp-interval "${ota_spdp_interval}"); python3 /ws/ota_configs/get_ota_xml.py "${ota_args[@]}" --output "${ota_config_file}" || { echo "FATAL - could not render the OTA DDS profile ${ota_config_template}; refusing to start on defaults." >&2; exit 1; }; case ${rmw_ota} in cyclone) export CYCLONEDDS_URI="file://${ota_config_file}";; fastdds) export FASTDDS_DEFAULT_PROFILES_FILE="${ota_config_file}"; export RMW_FASTRTPS_USE_QOS_FROM_XML=1;; esac; fi
         # For zenoh_ros2dds the OTA domain is loopback-only (zenoh is the inter-host
         # transport), so confine discovery to localhost instead of statically peering
         # the remote host — otherwise the OTA-domain DDS double-delivers alongside zenoh.
@@ -427,6 +434,11 @@ windows:
             -p link_trace_interval_s:=${link_trace_interval_s}
             -p "link_trace_modem_command:='${link_trace_modem_command}'"
             -p link_trace_modem_timeout_s:=${link_trace_modem_timeout_s}
+            -p ota_pcap:=${ota_pcap}
+            -p ota_pcap_snaplen:=${ota_pcap_snaplen}
+            -p ota_pcap_max_mb:=${ota_pcap_max_mb}
+            -p ota_pcap_peer_filter:=${ota_pcap_peer_filter}
+            -p ota_pcap_peer_ip:=${ip_remote}
       - commands:
         - status_out_dir="$(dirname "${ROSOTACOM_CATMUX_LOG_DIR:-/tmp/rosotacom_logs/catmux}")/status"
         - status_txt="$status_out_dir/status.txt"

rosotacom/resources/ws/session/creation/generate_session_files.py

@@ -1063,6 +1063,7 @@ def _validate_session_template_cfg(cfg: Dict[str, Any]) -> None:
                 "heartbeat",
                 "metric_backbone",
                 "link_trace",
+                "ota_pcap",
                 "use_in",
                 "use_out",
                 "rmw",
@@ -1135,6 +1136,27 @@ def _validate_session_template_cfg(cfg: Dict[str, Any]) -> None:
                         "shared.link_trace.modem_metrics_timeout_s must be a positive number if provided."
                     )
 
+        if "ota_pcap" in shared and shared["ota_pcap"] is not None:
+            ota_pcap = _assert_mapping(shared.get("ota_pcap"), "shared.ota_pcap")
+            _assert_allowed_keys(
+                "shared.ota_pcap",
+                ota_pcap,
+                {"enabled", "snaplen", "max_mb", "peer_filter"},
+            )
+            if "enabled" in ota_pcap and not isinstance(ota_pcap["enabled"], bool):
+                raise RuntimeError("shared.ota_pcap.enabled must be boolean if provided.")
+            if "peer_filter" in ota_pcap and not isinstance(ota_pcap["peer_filter"], bool):
+                raise RuntimeError("shared.ota_pcap.peer_filter must be boolean if provided.")
+            for key, low, high in (("snaplen", 40, 65535), ("max_mb", 1, 1_000_000)):
+                if key in ota_pcap and ota_pcap[key] is not None:
+                    value = ota_pcap[key]
+                    if not isinstance(value, int) or isinstance(value, bool) \
+                            or not (low <= value <= high):
+                        raise RuntimeError(
+                            f"shared.ota_pcap.{key} must be an integer between "
+                            f"{low} and {high} if provided."
+                        )
+
     # peer_settings is optional
     if "peer_settings" in cfg and cfg["peer_settings"] is not None:
         peer_settings = _assert_mapping(cfg.get("peer_settings"), "peer_settings")
@@ -2135,6 +2157,19 @@ def func(
     link_trace_modem_timeout_s = float(link_trace.get("modem_metrics_timeout_s", 2.0))
     if link_trace_enabled and not use_status_overview:
         raise RuntimeError("shared.link_trace.enabled requires shared.use_status_overview=true.")
+    ota_pcap = shared.get("ota_pcap", {}) or {}
+    if not isinstance(ota_pcap, dict):
+        raise RuntimeError("shared.ota_pcap must be a mapping if provided.")
+    ota_pcap_enabled = bool(ota_pcap.get("enabled", False))
+    ota_pcap_snaplen = int(ota_pcap.get("snaplen", 96))
+    ota_pcap_max_mb = int(ota_pcap.get("max_mb", 2000))
+    ota_pcap_peer_filter = bool(ota_pcap.get("peer_filter", True))
+    if ota_pcap_enabled and not use_status_overview:
+        # The capture is started by the status_overview node, which is also
+        # what resolves the OTA interface from the peer's own address — the
+        # resolution that refuses loopback (#267). Without it there is nothing
+        # to hang the capture on and no safe way to name an interface.
+        raise RuntimeError("shared.ota_pcap.enabled requires shared.use_status_overview=true.")
     shared_use_in = shared.get("use_in", None)
     shared_use_out = shared.get("use_out", None)
 
@@ -3168,6 +3203,16 @@ def func(
                         ]
                         if link_trace_enabled
                         else []
+                    )
+                    + (
+                        [
+                            ("ota_pcap", True),
+                            ("ota_pcap_snaplen", ota_pcap_snaplen),
+                            ("ota_pcap_max_mb", ota_pcap_max_mb),
+                            ("ota_pcap_peer_filter", ota_pcap_peer_filter),
+                        ]
+                        if ota_pcap_enabled
+                        else []
                     ),
                 )
             )

{rosotacom_dev-2.5.dev65.dist-info → rosotacom_dev-2.5.dev67.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rosotacom-dev
-Version: 2.5.dev65
+Version: 2.5.dev67
 Summary: Host CLI for ROS OTA communication sessions.
 Author: develNor
 License-Expression: BSD-3-Clause
@@ -684,6 +684,13 @@ the [link trace recorder](docs/link-trace.md). It writes
 `link_trace.jsonl` under the same status directory with `/proc/net/dev` counter
 deltas, echo-heartbeat RTT/loss provenance, and an optional modem-metrics hook.
 
+Those counters localise loss to a *direction* and no further. When the question
+is which fragment was lost, whether a retransmit followed, or how one sample's
+sub-messages were spaced, enable the [header-only OTA capture](docs/ota-pcap.md)
+next to them — `shared.ota_pcap.enabled`, off by default, roughly 1 % of payload
+volume, and every packet labelled uplink or downlink. It needs no capability,
+no image change and no extra container.
+
 Convert a recorded link trace into a profiles-file entry when you want to replay
 the same drive conditions in a repeatable benchmark:
 

{rosotacom_dev-2.5.dev65.dist-info → rosotacom_dev-2.5.dev67.dist-info}/RECORD

@@ -113,12 +113,13 @@ rosotacom/resources/ws/.vscode/settings.json,sha256=xNEQ9qGmUhxkLXYDJj4QVt4l3Btg
 rosotacom/resources/ws/ota_configs/create_zenoh_json5.py,sha256=um2xU1SfNVo_FvlS8iYeAauu67I1N1Z8x-Ckw7KUAAk,2356
 rosotacom/resources/ws/ota_configs/cyclonedds_local_participants.xml.template,sha256=_PAy5sj9_pk2If7xQ_iHF2Oi1tC6HaZe3dDyl8fRSoo,1708
 rosotacom/resources/ws/ota_configs/cyclonedds_minimal.xml.template,sha256=YspSB4xbk2C_CODoowBQUkqsehdGYEd9I0YCjdGN1dc,197
+rosotacom/resources/ws/ota_configs/cyclonedds_scoped.xml.template,sha256=tjHTn2SSaCgPT_3JRTuievvu7rV8nJoYGChPo-kUtOM,3532
 rosotacom/resources/ws/ota_configs/cyclonedds_tuned.xml.template,sha256=e6XmnP3WpqxCc_las62SIB9yUuCYZQ4Zxc3KMk6g0a8,2027
 rosotacom/resources/ws/ota_configs/fastdds_easy_mode.xml.template,sha256=NsQfwrf2JoqKaD0j_cEp2LCLNsRcdjKoReuQ_ow9Txk,2037
 rosotacom/resources/ws/ota_configs/fastdds_local.xml.template,sha256=KhLMd_vYe8o_sb5WqBNDNvdsFDJ1BmHwmpLpJ9WginY,3326
 rosotacom/resources/ws/ota_configs/fastdds_tuned.xml.template,sha256=pl8dskuk4cBRU4t9fhyA4ZyeQ-KpcWRhHTsm2Gn4TSc,6504
 rosotacom/resources/ws/ota_configs/fastdds_unicast.xml.template,sha256=NZGt5mP9IWBk0drx0FOLCuySTamvQ9s8B5gPjHJbtG4,3838
-rosotacom/resources/ws/ota_configs/get_ota_xml.py,sha256=IjZNuIt1opHlGcURWuKAaFFDqDTghqyutbCSBUwQP-k,8772
+rosotacom/resources/ws/ota_configs/get_ota_xml.py,sha256=jzVchlCFah2wkia5nTtYDYOM4slt9XzpaPW3-IaSWyA,10625
 rosotacom/resources/ws/ota_configs/utils.py,sha256=HS-n4AUGFEVd1YmIjFUjD0TMI22M6PUMKaTac30qfd4,3109
 rosotacom/resources/ws/ota_configs/zenoh.json5.template,sha256=XDsugd411skY6lepBq5DoNIWcw8cpY922ZgfR3DOLvA,798
 rosotacom/resources/ws/ota_configs/archive/fastdds_easy_mode.xml.template,sha256=UNpcu-JTIvNBR5AfE4ILwXCdWVdwtF22zsttjUdg4eY,1350
@@ -162,6 +163,7 @@ rosotacom/resources/ws/ros2src/com_py/com_py/link_trace.py,sha256=elVggfIe4YXCnq
 rosotacom/resources/ws/ros2src/com_py/com_py/local_global_frame_bridge.py,sha256=BCuq_njJ_sXgdSGJ1J9FtH6sxqvELTU0UdXAw13XqhA,18724
 rosotacom/resources/ws/ros2src/com_py/com_py/localization_map_split_reduce_saver.py,sha256=m6lMb51q5pUYTyHVWiss8vPlsbYRpKMDwHG9gG_fY4E,9088
 rosotacom/resources/ws/ros2src/com_py/com_py/msg_transform.py,sha256=gdSYrvMUKuBOG5UePm6EGxkHz-QNfZ00PIR9IYEr8ao,9629
+rosotacom/resources/ws/ros2src/com_py/com_py/ota_pcap.py,sha256=2UrUI9X-sIOezpXW-SwJ2BhTULNeCpPrJF0HhFJHnC8,16536
 rosotacom/resources/ws/ros2src/com_py/com_py/pair_management.py,sha256=DfNNsX09GEKwIFolXFKj0blYQTNhoHQTj09Cat3zKZ8,3765
 rosotacom/resources/ws/ros2src/com_py/com_py/playout_pacer.py,sha256=Kr5T_pBPjJP4DgEaDSINv5TkaiBrs6HF-J6GhlxzEYs,4813
 rosotacom/resources/ws/ros2src/com_py/com_py/playout_pacer_core.py,sha256=d9omGcz9a7rT1smA2ROIsOiL0rqXHZTAA0NRj81V9UA,4675
@@ -173,7 +175,7 @@ rosotacom/resources/ws/ros2src/com_py/com_py/restamp.py,sha256=S8LjtZs_WBdnvL5oN
 rosotacom/resources/ws/ros2src/com_py/com_py/sized_publisher.py,sha256=prpmQf_cXp3KMYw3FlBZfNhq0Rrz56YUjWOunVF6xL8,9259
 rosotacom/resources/ws/ros2src/com_py/com_py/stage_latency.py,sha256=su_oWQBeDeLHdCy08YzzsASPgYoWID-syqqVkrjSg4g,2768
 rosotacom/resources/ws/ros2src/com_py/com_py/stage_latency_core.py,sha256=VXR0EN8EdExxLSb8UbY4mTv94khLZi6weqJpQtRMbd8,2600
-rosotacom/resources/ws/ros2src/com_py/com_py/status_overview.py,sha256=cF1AbEWJao5lz4rP4bdyngBGi1wN9e0oIXbDcZXevAc,24963
+rosotacom/resources/ws/ros2src/com_py/com_py/status_overview.py,sha256=GhoKic8WBwJDqw0kn5Zfc41SdpR7nXBpbUESugDrTvI,29268
 rosotacom/resources/ws/ros2src/com_py/com_py/status_overview_core.py,sha256=1g_wULJGfcBL9lIkkxWVfYDGnGuiuTVnWEo3ZdvnZ_Q,64146
 rosotacom/resources/ws/ros2src/com_py/com_py/tf_map_to_cart_saver.py,sha256=eWq0D-pVDadj186e2ZC4kZpxTBkXMzi24BfBj3NjGXc,3777
 rosotacom/resources/ws/ros2src/com_py/com_py/topic_monitor.py,sha256=5iNoHU3SiiDwzsOj7tudh5d801ELVxaHiGKmTCP3JFw,16320
@@ -193,19 +195,19 @@ rosotacom/resources/ws/ros2src/com_py/resource/com_py,sha256=47DEQpj8HBSa-_TImW-
 rosotacom/resources/ws/ros2src/com_py/test/test_copyright.py,sha256=6nG7vGJHtcFNF27QnznuJ01WPMmy7DVYKOpFHO_zF1c,962
 rosotacom/resources/ws/ros2src/com_py/test/test_flake8.py,sha256=N6gToFB_DOUaLQtXMS0swHigMHo8qFWA6oAbDS-XVdI,884
 rosotacom/resources/ws/ros2src/com_py/test/test_pep257.py,sha256=6LiNSe4paYextABp-BAZtfoJsaob_umh-q5Fu1z1Pto,803
-rosotacom/resources/ws/session/content/base/session_plugin_base.yaml,sha256=dDX5xswpiy54cLwjDIbsmokuHBqO1PSpzZaVbzkLvwc,49635
+rosotacom/resources/ws/session/content/base/session_plugin_base.yaml,sha256=uCO6m1cPW9LLxzrnTFmOsLIGijqT24OCQiHx6qjqpUU,51101
 rosotacom/resources/ws/session/content/network/up_connectivity.py,sha256=-a6E97Uw159DfRXxYA0MBWRUPA6mQhuAA7pSjASM9qU,13593
 rosotacom/resources/ws/session/content/network/wifi_network_analysis_2.py,sha256=UVRtGdbHYayXM0OFkXs2BV2lW0CsY0m_NTlbPO1J9oE,8682
 rosotacom/resources/ws/session/creation/anonymize_bag.py,sha256=jxOTKFjmde-pyoVWE9-9icpSjf4nh97-q2Eqx-BDUl8,6154
 rosotacom/resources/ws/session/creation/catmux_log_setup.sh,sha256=VyBAFqmhQcIziSnDCRDNUsT5QpbLzKWU-DqRzaj_WQs,5243
 rosotacom/resources/ws/session/creation/create_session_yaml.py,sha256=8cfzkUxK7IebIBC36Vu7lcWtogM8fG0zveBCUGeiVdU,5727
-rosotacom/resources/ws/session/creation/generate_session_files.py,sha256=ryp8trvjjFpmpHMgsDaeGvLitroaiVJfAZI4gmYO10I,158711
+rosotacom/resources/ws/session/creation/generate_session_files.py,sha256=eosnUYSwVzkaP_Bra5CStJ6qt9sduqhRNmUudXwlFLo,161258
 rosotacom/resources/ws/session/creation/run_session.py,sha256=G2hJhrmLp11gm3JZ6_C-zZcqu_reXlE_wmobB7BiCfU,16849
 rosotacom/resources/ws/session/creation/run_session_in_external_terminal.py,sha256=Ub_5f-ttUUc-rAPrZmg_Op34s8Z4C91hTyEn8fgyt-E,2633
 rosotacom/resources/ws/session/creation/strip_ansi.py,sha256=vNjpemcq4xHr0VG4x0bZqvgwEBEfOgN-b4PzbrM5nfM,851
-rosotacom_dev-2.5.dev65.dist-info/licenses/LICENSE.txt,sha256=FDB3-fao3lqZ94wsJHKAH7U88kAnfvZhZC8Hm5rN__g,1459
-rosotacom_dev-2.5.dev65.dist-info/METADATA,sha256=o6cZxZ1dKwy1UWWYV6NSuSNnxXGHIhBNncxUiJzdmro,58350
-rosotacom_dev-2.5.dev65.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-rosotacom_dev-2.5.dev65.dist-info/entry_points.txt,sha256=im11ZWqBbgjQUBz2Ik2RNfMu54wlMwgiVpsBKeI7dCI,49
-rosotacom_dev-2.5.dev65.dist-info/top_level.txt,sha256=BZrtQcIVDWn_pQZR3Mlssqy5SaRXHjOa6B-1D9Fy4Ao,10
-rosotacom_dev-2.5.dev65.dist-info/RECORD,,
+rosotacom_dev-2.5.dev67.dist-info/licenses/LICENSE.txt,sha256=FDB3-fao3lqZ94wsJHKAH7U88kAnfvZhZC8Hm5rN__g,1459
+rosotacom_dev-2.5.dev67.dist-info/METADATA,sha256=RsQ3qETER7_LuJ0JB46k0IG5EZmMgoIQxbeejhYlnCc,58792
+rosotacom_dev-2.5.dev67.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+rosotacom_dev-2.5.dev67.dist-info/entry_points.txt,sha256=im11ZWqBbgjQUBz2Ik2RNfMu54wlMwgiVpsBKeI7dCI,49
+rosotacom_dev-2.5.dev67.dist-info/top_level.txt,sha256=BZrtQcIVDWn_pQZR3Mlssqy5SaRXHjOa6B-1D9Fy4Ao,10
+rosotacom_dev-2.5.dev67.dist-info/RECORD,,