lcm-cli 0.1.0__py3-none-any.whl

lcm_tools/display/echo_display.py

@@ -0,0 +1,233 @@
+"""Rich-based real-time echo display for ``lcm topic echo``.
+
+Supports three display modes:
+1. Default — Rich Panel with channel, seq, size, fingerprint, hex dump
+2. Raw — compact plain-text output for piping/scripting
+3. Decoded — attempt to decode payload via an lcm-gen generated class
+"""
+
+from __future__ import annotations
+
+import importlib
+import time
+from datetime import datetime
+from typing import Any, Optional
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.text import Text
+
+from lcm_tools.protocol import PacketInfo, extract_fingerprint, fingerprint_to_hex
+
+# TYPE_CHECKING import for TypeRegistry (avoid circular imports)
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from lcm_tools.core.lcm_type_builder import TypeRegistry
+
+_console = Console()
+
+
+def echo_packet_default(pkt: PacketInfo, msg_index: int) -> None:
+    """Display a single packet using Rich Panel (default mode)."""
+    fp = extract_fingerprint(pkt.payload)
+    fp_str = fingerprint_to_hex(fp) if fp is not None else "N/A"
+
+    ts_str = datetime.now().strftime("%H:%M:%S.%f")[:-3]
+
+    # Build payload preview (first 128 bytes as hex, wrapped)
+    preview_bytes = pkt.payload[:128]
+    hex_lines = [
+        preview_bytes[i : i + 16].hex(" ")
+        for i in range(0, len(preview_bytes), 16)
+    ]
+    hex_preview = "\n".join(hex_lines)
+    if len(pkt.payload) > 128:
+        hex_preview += f"\n... ({len(pkt.payload) - 128} more bytes)"
+
+    body = Text.from_markup(
+        f"[bold]channel:[/bold]    [cyan]{pkt.channel}[/cyan]\n"
+        f"[bold]seq:[/bold]        {pkt.seqno}\n"
+        f"[bold]size:[/bold]       {len(pkt.payload)} bytes "
+        f"(packet: {pkt.packet_size} B)\n"
+        f"[bold]time:[/bold]       {ts_str}\n"
+        f"[bold]fingerprint:[/bold] {fp_str}\n"
+        f"[bold]sender:[/bold]     {pkt.sender_addr[0]}:{pkt.sender_addr[1]}\n"
+        f"\n[dim]payload (hex):[/dim]\n{hex_preview}"
+    )
+
+    panel = Panel(
+        body,
+        title=f"[bold green]Message #{msg_index}[/bold green]",
+        border_style="blue",
+        expand=False,
+    )
+    _console.print(panel)
+
+
+def echo_packet_raw(pkt: PacketInfo, msg_index: int) -> None:
+    """Display a packet in compact raw text mode."""
+    ts = datetime.now().strftime("%H:%M:%S.%f")[:-3]
+    fp = extract_fingerprint(pkt.payload)
+    fp_str = fingerprint_to_hex(fp) if fp is not None else "N/A"
+    _console.print(
+        f"[{ts}] #{msg_index} {pkt.channel}  "
+        f"seq={pkt.seqno}  size={len(pkt.payload)}B  "
+        f"fp={fp_str}  from={pkt.sender_addr[0]}:{pkt.sender_addr[1]}"
+    )
+
+
+def _format_value(value: Any, indent: int = 1) -> str:
+    """Recursively format a field value, expanding nested LCM structs.
+
+    Args:
+        value: The field value to format.
+        indent: Current indentation level (each level = 2 spaces).
+
+    Returns:
+        A formatted string representation of the value.
+    """
+    prefix = "  " * indent
+
+    # Handle nested LCM struct objects (have __slots__ or custom attributes)
+    if hasattr(value, "__slots__") or (
+        hasattr(value, "__dict__")
+        and not isinstance(value, (list, tuple, dict, str, bytes))
+        and not hasattr(value, "__len__")
+    ):
+        nested_fields = _extract_fields(value)
+        if nested_fields:
+            lines = []
+            for k, v in nested_fields:
+                formatted_v = _format_value(v, indent + 1)
+                lines.append(f"{prefix}  {k}: {formatted_v}")
+            return "\n" + "\n".join(lines)
+
+    # Handle lists / tuples (e.g., arrays of structs or primitives)
+    if isinstance(value, (list, tuple)):
+        if not value:
+            return "[]"
+        # Check if elements are nested structs
+        first = value[0]
+        if hasattr(first, "__slots__") or (
+            hasattr(first, "__dict__")
+            and not isinstance(first, (list, tuple, dict, str, bytes))
+            and not hasattr(first, "__len__")
+        ):
+            lines = []
+            for i, item in enumerate(value):
+                nested_fields = _extract_fields(item)
+                if nested_fields:
+                    lines.append(f"{prefix}  [{i}]:")
+                    for k, v in nested_fields:
+                        formatted_v = _format_value(v, indent + 2)
+                        lines.append(f"{prefix}    {k}: {formatted_v}")
+                else:
+                    lines.append(f"{prefix}  [{i}]: {item}")
+            return "\n" + "\n".join(lines)
+        return repr(value)
+
+    # Handle dicts
+    if isinstance(value, dict):
+        if not value:
+            return "{}"
+        lines = []
+        for k, v in value.items():
+            formatted_v = _format_value(v, indent + 1)
+            lines.append(f"{prefix}  {k}: {formatted_v}")
+        return "\n" + "\n".join(lines)
+
+    # Primitive types
+    return repr(value)
+
+
+def _extract_fields(obj: Any) -> list[tuple[str, Any]]:
+    """Extract (name, value) pairs from an LCM struct-like object."""
+    # Prefer __slots__ if available (lcm-gen generated classes use __slots__)
+    if hasattr(obj, "__slots__"):
+        return [
+            (k, getattr(obj, k))
+            for k in obj.__slots__
+            if not k.startswith("_")
+        ]
+    # Fall back to dir(), filtering out callables and private attrs
+    return [
+        (k, getattr(obj, k))
+        for k in dir(obj)
+        if not k.startswith("_") and not callable(getattr(obj, k))
+    ]
+
+
+def echo_packet_decoded(
+    pkt: PacketInfo, msg_index: int, decode_cls: Any
+) -> None:
+    """Display a decoded LCM message with recursive nested struct expansion."""
+    ts = datetime.now().strftime("%H:%M:%S.%f")[:-3]
+    try:
+        msg = decode_cls.decode(pkt.payload)
+        fields = _extract_fields(msg)
+        body_lines = []
+        for k, v in fields:
+            formatted_v = _format_value(v, indent=1)
+            body_lines.append(f"  {k}: {formatted_v}")
+        body = "\n".join(body_lines)
+    except Exception as exc:
+        body = f"[decode error: {exc}]\nRaw hex: {pkt.payload[:64].hex(' ')}"
+
+    _console.print(
+        Panel(
+            body,
+            title=f"[bold green]#{msg_index}[/bold green] "
+            f"[cyan]{pkt.channel}[/cyan] [{ts}]",
+            border_style="blue",
+            expand=False,
+        )
+    )
+
+
+def echo_packet_auto_decode(
+    pkt: PacketInfo, msg_index: int, registry: "TypeRegistry"
+) -> None:
+    """Auto-decode a packet using fingerprint matching from a TypeRegistry.
+
+    If the fingerprint matches a registered type, decode and display.
+    Otherwise, fall back to default display with a hint.
+    """
+    fp = extract_fingerprint(pkt.payload)
+    decode_cls = None
+    if fp is not None:
+        decode_cls = registry.find_by_fingerprint(fp)
+
+    if decode_cls is not None:
+        echo_packet_decoded(pkt, msg_index, decode_cls)
+    else:
+        # Fall back to default display with fingerprint info
+        echo_packet_default(pkt, msg_index)
+        if fp is not None:
+            _console.print(
+                f"  [dim](no matching type for fingerprint "
+                f"{fingerprint_to_hex(fp)})[/dim]"
+            )
+
+
+def load_decode_class(type_path: str) -> Any:
+    """Dynamically import an lcm-gen generated class.
+
+    Args:
+        type_path: Dotted path like ``exlcm.example_t``.
+
+    Returns:
+        The class object (must have a ``decode(data)`` classmethod).
+
+    Raises:
+        ImportError: If the module cannot be imported.
+        AttributeError: If the class is not found in the module.
+    """
+    parts = type_path.rsplit(".", 1)
+    if len(parts) != 2:
+        raise ValueError(
+            f"Expected 'module.ClassName' format, got: {type_path!r}"
+        )
+    module_path, class_name = parts
+    mod = importlib.import_module(module_path)
+    return getattr(mod, class_name)

lcm_tools/display/stats_display.py

@@ -0,0 +1,103 @@
+"""Rich Live table display for ``lcm topic stats`` and ``lcm topic list``.
+
+Uses ``rich.live.Live`` to render a continuously updating table of
+per-channel statistics in the terminal.
+"""
+
+from __future__ import annotations
+
+from typing import List
+
+from rich.console import Console
+from rich.live import Live
+from rich.table import Table
+
+from lcm_tools.core.discovery import ChannelInfo, NodeInfo
+from lcm_tools.core.stats import StatsSnapshot, _ChannelSnapshot
+
+_console = Console()
+
+
+def build_stats_table(snap: StatsSnapshot) -> Table:
+    """Build a Rich Table from a stats snapshot."""
+    table = Table(
+        title="LCM Channel Statistics",
+        show_lines=False,
+        show_header=True,
+        header_style="bold magenta",
+    )
+    table.add_column("Channel", style="cyan", min_width=18)
+    table.add_column("Messages", justify="right", style="bold")
+    table.add_column("Rate (Hz)", justify="right", style="green")
+    table.add_column("BW (KB/s)", justify="right", style="yellow")
+    table.add_column("Avg Size (B)", justify="right")
+    table.add_column("Total (KB)", justify="right", style="blue")
+
+    for ch in snap.channels:
+        table.add_row(
+            ch.channel,
+            str(ch.msg_count),
+            f"{ch.frequency_hz:.1f}",
+            f"{ch.bandwidth_kbps:.2f}",
+            f"{ch.avg_msg_size:.0f}",
+            f"{ch.total_bytes / 1024:.1f}",
+        )
+
+    # Summary row
+    table.add_section()
+    table.add_row(
+        f"[bold]{snap.total_channels} channels[/bold]",
+        f"[bold]{snap.total_messages}[/bold]",
+        "",
+        f"[bold]{snap.total_bandwidth_kbps:.2f}[/bold]",
+        "",
+        f"[bold]{snap.total_bytes / 1024:.1f}[/bold]",
+    )
+    return table
+
+
+def build_channel_table(channels: List[ChannelInfo]) -> Table:
+    """Build a Rich Table listing discovered channels."""
+    table = Table(
+        title=f"Active LCM Channels ({len(channels)} found)",
+        show_lines=False,
+        show_header=True,
+        header_style="bold magenta",
+    )
+    table.add_column("Channel", style="cyan", min_width=18)
+    table.add_column("Messages", justify="right")
+    table.add_column("Total Size", justify="right", style="blue")
+    table.add_column("Publishers", justify="right", style="dim")
+
+    for ch in channels:
+        table.add_row(
+            ch.name,
+            str(ch.msg_count),
+            f"{ch.total_bytes / 1024:.1f} KB",
+            ", ".join(sorted(ch.publishers)) if ch.publishers else "-",
+        )
+    return table
+
+
+def build_node_table(nodes: List[NodeInfo]) -> Table:
+    """Build a Rich Table listing discovered publisher nodes."""
+    table = Table(
+        title=f"LCM Publisher Nodes ({len(nodes)} found)",
+        show_lines=False,
+        show_header=True,
+        header_style="bold magenta",
+    )
+    table.add_column("Node (IP:port)", style="cyan", min_width=22)
+    table.add_column("Channels", style="green")
+    table.add_column("Messages", justify="right")
+    table.add_column("Total Size", justify="right", style="blue")
+
+    for node in nodes:
+        channels_str = ", ".join(sorted(node.channels)) or "-"
+        table.add_row(
+            node.address,
+            channels_str,
+            str(node.msg_count),
+            f"{node.total_bytes / 1024:.1f} KB",
+        )
+    return table

lcm_tools/listener.py

@@ -0,0 +1,157 @@
+"""UDP multicast socket management for LCM traffic capture.
+
+Creates and manages a UDP socket that joins the LCM multicast group,
+receives raw datagrams, parses them via the protocol module, and
+dispatches PacketInfo objects to registered callbacks.
+"""
+
+from __future__ import annotations
+
+import select
+import socket
+import struct
+import sys
+import threading
+from typing import Callable, Optional
+
+from lcm_tools.protocol import (
+    DEFAULT_MC_ADDR,
+    DEFAULT_MC_PORT,
+    PacketInfo,
+    parse_lcm_packet,
+)
+
+# 4 MB receive buffer — helps avoid packet loss under burst traffic
+_RCVBUF_SIZE: int = 4 * 1024 * 1024
+
+PacketCallback = Callable[[PacketInfo], None]
+
+
+def create_multicast_socket(
+    mc_addr: str = DEFAULT_MC_ADDR,
+    mc_port: int = DEFAULT_MC_PORT,
+    interface: Optional[str] = None,
+) -> socket.socket:
+    """Create a UDP socket and join the given multicast group.
+
+    Args:
+        mc_addr: Multicast group address (e.g. "239.255.76.67").
+        mc_port: Multicast port (e.g. 7667).
+        interface: Local interface IP to bind to.  ``None`` means
+            ``INADDR_ANY`` (let the OS choose).
+
+    Returns:
+        A configured, non-blocking UDP socket ready to receive
+        multicast datagrams.
+
+    Raises:
+        OSError: If the socket cannot be created or the group cannot
+            be joined (e.g. no route to multicast address).
+    """
+    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM, socket.IPPROTO_UDP)
+    sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+
+    # macOS / FreeBSD require SO_REUSEPORT in addition to SO_REUSEADDR
+    if sys.platform == "darwin" or "freebsd" in sys.platform:
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEPORT, 1)
+
+    sock.bind(("", mc_port))
+
+    # Build the IP_ADD_MEMBERSHIP request
+    group_bin = socket.inet_aton(mc_addr)
+    if interface:
+        iface_bin = socket.inet_aton(interface)
+    else:
+        iface_bin = struct.pack("=I", socket.INADDR_ANY)
+
+    mreq = group_bin + iface_bin
+    sock.setsockopt(socket.IPPROTO_IP, socket.IP_ADD_MEMBERSHIP, mreq)
+
+    # Enlarge receive buffer
+    try:
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_RCVBUF, _RCVBUF_SIZE)
+    except OSError:
+        pass  # OS may refuse; proceed with default
+
+    sock.setblocking(False)
+    return sock
+
+
+def drop_multicast_membership(
+    sock: socket.socket,
+    mc_addr: str = DEFAULT_MC_ADDR,
+    interface: Optional[str] = None,
+) -> None:
+    """Leave the multicast group before closing the socket."""
+    group_bin = socket.inet_aton(mc_addr)
+    iface_bin = (
+        socket.inet_aton(interface)
+        if interface
+        else struct.pack("=I", socket.INADDR_ANY)
+    )
+    mreq = group_bin + iface_bin
+    try:
+        sock.setsockopt(socket.IPPROTO_IP, socket.IP_DROP_MEMBERSHIP, mreq)
+    except OSError:
+        pass
+
+
+def listen_packets(
+    sock: socket.socket,
+    callback: PacketCallback,
+    stop_event: threading.Event,
+    timeout: float = 0.5,
+) -> None:
+    """Read packets from *sock* and invoke *callback* until *stop_event* is set.
+
+    This function is designed to run in a dedicated thread.
+
+    Args:
+        sock: A non-blocking multicast socket from :func:`create_multicast_socket`.
+        callback: Called for every successfully parsed LCM packet.
+        stop_event: Set this event to request a clean shutdown.
+        timeout: ``select`` timeout in seconds; controls how quickly the
+            function checks *stop_event*.
+    """
+    while not stop_event.is_set():
+        readable, _, _ = select.select([sock], [], [], timeout)
+        if not readable:
+            continue
+
+        try:
+            data, sender_addr = sock.recvfrom(65536)
+        except OSError:
+            # Socket may have been closed during shutdown
+            break
+
+        pkt = parse_lcm_packet(data, sender_addr)
+        if pkt is not None:
+            callback(pkt)
+
+
+def run_listener(
+    callback: PacketCallback,
+    mc_addr: str = DEFAULT_MC_ADDR,
+    mc_port: int = DEFAULT_MC_PORT,
+    interface: Optional[str] = None,
+    stop_event: Optional[threading.Event] = None,
+) -> threading.Event:
+    """Convenience: start a background listener thread.
+
+    Returns the ``threading.Event`` that can be set to stop the listener.
+    """
+    if stop_event is None:
+        stop_event = threading.Event()
+
+    sock = create_multicast_socket(mc_addr, mc_port, interface)
+
+    def _worker() -> None:
+        try:
+            listen_packets(sock, callback, stop_event)
+        finally:
+            drop_multicast_membership(sock, mc_addr, interface)
+            sock.close()
+
+    t = threading.Thread(target=_worker, daemon=True, name="lcm-listener")
+    t.start()
+    return stop_event

lcm_tools/protocol.py

@@ -0,0 +1,172 @@
+"""LCM UDP Multicast wire protocol parser.
+
+Reference: https://lcm-proj.github.io/lcm/content/udp-multicast-protocol.html
+
+Two packet formats:
+- Small message (short header, 8 bytes): magic=0x4c433032 + seqno + channel\0 + payload
+- Fragmented message (long header, 20 bytes): magic=0x4c433033 + seqno + payload_size
+  + fragment_offset + fragment_no(2B) + n_fragments(2B) + [if frag==0: channel\0] + payload
+"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass
+from typing import Optional, Tuple
+
+# LCM protocol constants
+LCM2_MAGIC_SHORT: int = 0x4C433032  # "LC02" - small single-packet messages
+LCM2_MAGIC_LONG: int = 0x4C433033  # "LC03" - fragmented messages
+
+DEFAULT_MC_ADDR: str = "239.255.76.67"
+DEFAULT_MC_PORT: int = 7667
+
+# Maximum channel name length (sanity check)
+_MAX_CHANNEL_LEN: int = 256
+
+
+@dataclass
+class PacketInfo:
+    """Parsed information from a single LCM UDP datagram."""
+
+    channel: Optional[str] = None
+    seqno: int = 0
+    payload: bytes = b""
+    fragment_no: int = 0
+    n_fragments: int = 1
+    packet_size: int = 0
+    sender_addr: Tuple[str, int] = ("", 0)
+    is_fragment: bool = False
+
+    @property
+    def is_first_fragment(self) -> bool:
+        return self.is_fragment and self.fragment_no == 0
+
+    @property
+    def has_channel(self) -> bool:
+        """True if this packet contains a channel name."""
+        return self.channel is not None
+
+
+def parse_lcm_packet(
+    data: bytes, sender_addr: Tuple[str, int] = ("", 0)
+) -> Optional[PacketInfo]:
+    """Parse a raw UDP datagram as an LCM packet.
+
+    Args:
+        data: Raw bytes received from the UDP socket.
+        sender_addr: (ip, port) of the sender.
+
+    Returns:
+        PacketInfo on success, None if the packet is malformed or unrecognised.
+    """
+    if len(data) < 8:
+        return None
+
+    magic, seqno = struct.unpack("!II", data[:8])
+
+    if magic == LCM2_MAGIC_SHORT:
+        return _parse_short_message(data, seqno, sender_addr)
+    elif magic == LCM2_MAGIC_LONG:
+        return _parse_fragmented_message(data, seqno, sender_addr)
+    else:
+        return None
+
+
+def _parse_short_message(
+    data: bytes, seqno: int, sender_addr: Tuple[str, int]
+) -> Optional[PacketInfo]:
+    """Parse a small (non-fragmented) LCM message."""
+    # Header: 8 bytes already read; channel name starts at offset 8
+    null_pos = data.find(b"\x00", 8)
+    if null_pos == -1 or null_pos - 8 > _MAX_CHANNEL_LEN:
+        return None
+
+    try:
+        channel = data[8:null_pos].decode("utf-8")
+    except UnicodeDecodeError:
+        return None
+
+    payload = data[null_pos + 1 :]
+
+    return PacketInfo(
+        channel=channel,
+        seqno=seqno,
+        payload=payload,
+        fragment_no=0,
+        n_fragments=1,
+        packet_size=len(data),
+        sender_addr=sender_addr,
+        is_fragment=False,
+    )
+
+
+def _parse_fragmented_message(
+    data: bytes, seqno: int, sender_addr: Tuple[str, int]
+) -> Optional[PacketInfo]:
+    """Parse a fragmented LCM message (first fragment has channel name)."""
+    if len(data) < 20:
+        return None
+
+    _payload_size, _frag_offset, frag_no, n_frags = struct.unpack(
+        "!IIHH", data[8:20]
+    )
+
+    if frag_no == 0:
+        # First fragment: contains channel name
+        null_pos = data.find(b"\x00", 20)
+        if null_pos == -1 or null_pos - 20 > _MAX_CHANNEL_LEN:
+            return None
+
+        try:
+            channel = data[20:null_pos].decode("utf-8")
+        except UnicodeDecodeError:
+            return None
+
+        payload = data[null_pos + 1 :]
+
+        return PacketInfo(
+            channel=channel,
+            seqno=seqno,
+            payload=payload,
+            fragment_no=0,
+            n_fragments=n_frags,
+            packet_size=len(data),
+            sender_addr=sender_addr,
+            is_fragment=True,
+        )
+    else:
+        # Subsequent fragments: no channel name, payload only
+        payload = data[20:]
+        return PacketInfo(
+            channel=None,
+            seqno=seqno,
+            payload=payload,
+            fragment_no=frag_no,
+            n_fragments=n_frags,
+            packet_size=len(data),
+            sender_addr=sender_addr,
+            is_fragment=True,
+        )
+
+
+def extract_fingerprint(payload: bytes) -> Optional[int]:
+    """Extract the LCM type fingerprint from a message payload.
+
+    The fingerprint is the first 8 bytes of the payload, encoded as a
+    big-endian unsigned 64-bit integer.
+
+    Args:
+        payload: The message payload bytes.
+
+    Returns:
+        The fingerprint as an integer, or None if the payload is too short.
+    """
+    if len(payload) < 8:
+        return None
+    return struct.unpack(">Q", payload[:8])[0]
+
+
+def fingerprint_to_hex(fp: int) -> str:
+    """Format a fingerprint integer as a hex string."""
+    return f"0x{fp:016x}"