lcm-cli 0.1.0__tar.gz → 0.2.0__tar.gz

lcm_cli-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,104 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags:
+      - 'v*'
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }}, ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
+        os: [ubuntu-latest, macOS-latest]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint with Ruff
+        run: |
+          ruff check src/lcm_cli tests
+
+      - name: Type check with mypy
+        run: |
+          mypy src/lcm_cli --ignore-missing-imports
+
+      - name: Run tests
+        run: |
+          pytest tests/ -v --cov=lcm_cli --cov-report=xml
+
+      - name: Upload coverage to Codecov
+        if: matrix.python-version == '3.12' && matrix.os == 'ubuntu-latest'
+        uses: codecov/codecov-action@v4
+        with:
+          file: ./coverage.xml
+          fail_ci_if_error: false
+
+  build:
+    name: Build distribution
+    needs: test
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install build tools
+        run: |
+          pip install build twine
+
+      - name: Build package
+        run: |
+          python -m build
+
+      - name: Check package
+        run: |
+          twine check dist/*
+
+      - name: Upload dist
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment:
+      name: pypi
+      url: https://pypi.org/p/lcm-cli
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

lcm_cli-0.2.0/.gitignore

@@ -0,0 +1,59 @@
+# Byte-compiled / cache
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+
+# Distribution / packaging
+dist/
+build/
+*.tar.gz
+*.whl
+
+# Tests & coverage
+.pytest_cache/
+htmlcov/
+.coverage
+coverage.xml
+
+# Type checking
+.mypy_cache/
+
+# Linting
+.ruff_cache/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# LCM reference repo (not part of this project)
+lcm_ref/
+
+# lcm-gen generated Python types
+gen_types/
+
+# Test LCM types (sample files)
+test_lcm_types/
+
+# Virtual environments
+venv/
+.venv-build/
+.env/
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+
+# Development scripts and internal docs
+scripts/
+docs/superpowers/
+
+# Temporary files
+tmp/
+temp/

{lcm_cli-0.1.0 → lcm_cli-0.2.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 lcm-tools contributors
+Copyright (c) 2024 lcm-cli contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{lcm_cli-0.1.0 → lcm_cli-0.2.0}/PKG-INFO

@@ -1,14 +1,14 @@
 Metadata-Version: 2.4
 Name: lcm-cli
-Version: 0.1.0
-Summary: ROS2-like command line tools for LCM (Lightweight Communications and Marshalling)
-Project-URL: Homepage, https://github.com/lcm-tools/lcm-tools
-Project-URL: Repository, https://github.com/lcm-tools/lcm-tools
-Project-URL: Issues, https://github.com/lcm-tools/lcm-tools/issues
-Author: lcm-tools contributors
+Version: 0.2.0
+Summary: Command line tools for monitoring and debugging LCM (Lightweight Communications and Marshalling)
+Project-URL: Homepage, https://github.com/Joyserr/lcm-cli
+Project-URL: Repository, https://github.com/Joyserr/lcm-cli
+Project-URL: Issues, https://github.com/Joyserr/lcm-cli/issues
+Author: lcm-cli contributors
 License-Expression: MIT
 License-File: LICENSE
-Keywords: cli,debugging,lcm,middleware,multicast,robotics,ros2
+Keywords: cli,debugging,lcm,middleware,multicast,robotics
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -33,40 +33,56 @@ Requires-Dist: typer>=0.12.0
 Provides-Extra: decode
 Requires-Dist: lcm>=1.5.0; extra == 'decode'
 Provides-Extra: dev
+Requires-Dist: build>=0.10; extra == 'dev'
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
 Requires-Dist: pytest-timeout>=2.1; extra == 'dev'
 Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: twine>=4.0; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # LCM CLI Tools
 
 **[English](README.md)** | [中文](README_zh.md)
 
-> ROS2-style command line tools for monitoring and debugging LCM (Lightweight Communications and Marshalling) networks.
+> Command line tools for monitoring and debugging LCM (Lightweight Communications and Marshalling) networks.
 
 ## Features
 
 ```
-lcm topic echo <channel>   — View real-time topic data (like ros2 topic echo)
-lcm topic list             — List active topics/channels (like ros2 topic list)
-lcm topic stats            — Real-time topic stats: rate, bandwidth, msg count (like ros2 topic hz)
-lcm node list              — List discovered publisher nodes (like ros2 node list)
+lcm topic echo <channel>   — View real-time topic data
+lcm topic list             — List active topics/channels
+lcm topic stats            — Real-time topic stats: rate, bandwidth, msg count
+lcm topic bw <channel>     — Monitor bandwidth for a single channel with sparkline graph
+lcm topic info <channel>   — Detailed channel information with type structure
+lcm node list              — List discovered publisher nodes
+lcm type list              — List all registered LCM types
+lcm type show <type>       — Show type field structure
+lcm record                 — Record live LCM traffic to .log file
+lcm play <file.log>        — Replay .log file to multicast
 ```
 
-**Highlight**: Built-in pure-Python `.lcm` file parser — no `lcm-gen` or `PYTHONPATH` needed. Just point to your `.lcm` files and messages are decoded automatically.
+**Highlights**:
+- Built-in pure-Python `.lcm` file parser — no `lcm-gen` or `PYTHONPATH` needed
+- **Message Export**: CSV/JSONL export with field extraction (`--csv`, `--jsonl`, `--field`)
+- **Advanced Monitoring**: Sort/filter stats (`--sort`, `--top`, `--freeze`, `--spark`)
+- **Live Watch Mode**: Continuous refresh for topic/node list (`--watch`)
+- **Recording & Playback**: Full log file support compatible with `lcm-logger`
 
 ## Installation
 
 ```bash
 # From PyPI
-pip install lcm-tools
+pip install lcm-cli
 
 # From source (development)
-git clone https://github.com/your-username/lcm-tools.git
-cd lcm-tools
+git clone https://github.com/Joyserr/lcm-cli.git
+cd lcm-cli
 pip install -e .
 
 # Optional: traditional lcm-gen Python package decode support
-pip install lcm-tools[decode]
+pip install lcm-cli[decode]
 ```
 
 **Requirements**: Python >= 3.9, `typer`, `rich` (`lcm` package is optional, only for legacy `--type module.Class` decoding).
@@ -77,9 +93,15 @@ pip install lcm-tools[decode]
 # Show all subcommands
 lcm --help
 
+# Show version
+lcm --version
+
 # List active channels (listens for 5 seconds)
 lcm topic list
 
+# Continuous watch mode (live refresh)
+lcm topic list --watch
+
 # View messages on a channel (raw hex format)
 lcm topic echo EXAMPLE
 
@@ -92,15 +114,106 @@ lcm topic echo "CAM.*"
 # Monitor real-time statistics for all channels
 lcm topic stats
 
-# Monitor a specific channel only
-lcm topic stats CAMERA
+# Sort by bandwidth, show top 5
+lcm topic stats --sort bw --top 5
+
+# Freeze mode (single snapshot)
+lcm topic stats --freeze
+
+# Monitor bandwidth with sparkline graph
+lcm topic bw CAMERA --spark
+
+# Detailed channel information
+lcm topic info CAMERA --lcm-file types/
 
 # List discovered publisher nodes
 lcm node list
 ```
 
+## Recording & Playback
+
+```bash
+# Record all channels to a .log file
+lcm record
+
+# Record specific channels with regex
+lcm record --channel "CAM.*" -o camera.log
+
+# Record for a fixed duration
+lcm record -d 60  # 60 seconds
+
+# Replay a .log file
+lcm play camera.log
+
+# Replay at 2x speed
+lcm play camera.log --speed 2.0
+
+# Loop playback
+lcm play camera.log --loop
+```
+
+## Message Export
+
+```bash
+# Export to CSV (headers auto-determined from first message)
+lcm topic echo EXAMPLE --csv output.csv
+
+# Export to JSON Lines
+lcm topic echo EXAMPLE --jsonl output.jsonl
+
+# Extract specific fields
+lcm topic echo EXAMPLE --field position --field velocity --csv data.csv
+
+# Extract nested fields
+lcm topic echo EXAMPLE --field imu.accel.x --field imu.gyro.y
+
+# Extract array slices
+lcm topic echo EXAMPLE --field "position[0:2]"
+
+# Custom timestamp format
+lcm topic echo EXAMPLE --csv data.csv --ts-format iso
+```
+
+## Advanced Statistics
+
+```bash
+# Sort channels by message rate
+lcm topic stats --sort rate
+
+# Show top 10 channels by bandwidth
+lcm topic stats --sort bw --top 10
+
+# Single snapshot (non-interactive)
+lcm topic stats --freeze
+
+# Add sparkline trend visualization
+lcm topic stats --spark
+
+# Monitor bandwidth for a single channel
+lcm topic bw CAMERA --window 10 --spark
+
+# Read stats from log file
+lcm topic stats --from recording.log
+```
+
 ## Message Decoding
 
+### Type Diagnostics
+
+```bash
+# List all registered types
+lcm type list
+
+# Filter by package
+lcm type list --package exlcm
+
+# Show type structure
+lcm type show example_t --lcm-file types/
+
+# Grep search types
+lcm type list --grep "sensor"
+```
+
 ### Method 1: Specify `.lcm` files directly (recommended)
 
 No `lcm-gen` installation, no `PYTHONPATH` configuration. The tool includes a built-in pure-Python parser:
@@ -133,7 +246,7 @@ Supports the complete LCM type system:
 
 ```bash
 # Install the lcm Python package
-pip install lcm-tools[decode]
+pip install lcm-cli[decode]
 
 # Generate Python files with lcm-gen, then configure PYTHONPATH
 lcm-gen --python -d types/ types/example_t.lcm
@@ -195,6 +308,8 @@ Reference: [LCM UDP Multicast Protocol](https://lcm-proj.github.io/lcm/content/u
 
 ## LCM vs ROS2 Concepts
 
+LCM and ROS2 share similar pub/sub communication patterns. Here's a concept mapping:
+
 | LCM Concept | ROS2 Equivalent | Description |
 |-------------|----------------|-------------|
 | Channel | Topic | Message publish/subscribe conduit |
@@ -204,13 +319,21 @@ Reference: [LCM UDP Multicast Protocol](https://lcm-proj.github.io/lcm/content/u
 ## Project Structure
 
 ```
-src/lcm_tools/
+src/lcm_cli/
+├── __init__.py                  # Package definition + version
+├── __main__.py                  # python -m lcm_cli entry point
 ├── cli.py                       # Typer entry point, registers subcommands
 ├── commands/
-│   ├── topic_echo.py            # lcm topic echo
-│   ├── topic_list.py            # lcm topic list
-│   ├── topic_stats.py           # lcm topic stats
-│   └── node_list.py             # lcm node list
+│   ├── topic_echo.py            # lcm topic echo (with --csv/--jsonl export)
+│   ├── topic_list.py            # lcm topic list (with --watch mode)
+│   ├── topic_stats.py           # lcm topic stats (with --sort/--top/--freeze)
+│   ├── topic_bw.py              # lcm topic bw (bandwidth monitor)
+│   ├── topic_info.py            # lcm topic info (channel details)
+│   ├── node_list.py             # lcm node list (with --watch mode)
+│   ├── type_list.py             # lcm type list
+│   ├── type_show.py             # lcm type show
+│   ├── record.py                # lcm record
+│   └── play.py                  # lcm play
 ├── core/
 │   ├── discovery.py             # Passive channel/node discovery
 │   ├── stats.py                 # Real-time statistics (rate, bandwidth)
@@ -218,9 +341,13 @@ src/lcm_tools/
 │   └── lcm_type_builder.py      # Runtime decode class generation + TypeRegistry
 ├── display/
 │   ├── echo_display.py          # Rich panel display (with recursive nesting)
-│   └── stats_display.py         # Statistics table display
+│   ├── stats_display.py         # Statistics table display (with sparkline)
+│   └── type_display.py          # Type structure table display
+├── export.py                    # Field extraction + CSV/JSONL writers
+├── lcm_log.py                   # LCM log file reader/writer (lcm-logger compatible)
 ├── listener.py                  # UDP multicast listener thread
-└── protocol.py                  # LCM Wire Protocol parser
+├── protocol.py                  # LCM Wire Protocol parser
+└── source.py                    # PacketSource abstraction (live/offline)
 ```
 
 ## Testing

{lcm_cli-0.1.0 → lcm_cli-0.2.0}/README.md

@@ -2,32 +2,43 @@
 
 **[English](README.md)** | [中文](README_zh.md)
 
-> ROS2-style command line tools for monitoring and debugging LCM (Lightweight Communications and Marshalling) networks.
+> Command line tools for monitoring and debugging LCM (Lightweight Communications and Marshalling) networks.
 
 ## Features
 
 ```
-lcm topic echo <channel>   — View real-time topic data (like ros2 topic echo)
-lcm topic list             — List active topics/channels (like ros2 topic list)
-lcm topic stats            — Real-time topic stats: rate, bandwidth, msg count (like ros2 topic hz)
-lcm node list              — List discovered publisher nodes (like ros2 node list)
+lcm topic echo <channel>   — View real-time topic data
+lcm topic list             — List active topics/channels
+lcm topic stats            — Real-time topic stats: rate, bandwidth, msg count
+lcm topic bw <channel>     — Monitor bandwidth for a single channel with sparkline graph
+lcm topic info <channel>   — Detailed channel information with type structure
+lcm node list              — List discovered publisher nodes
+lcm type list              — List all registered LCM types
+lcm type show <type>       — Show type field structure
+lcm record                 — Record live LCM traffic to .log file
+lcm play <file.log>        — Replay .log file to multicast
 ```
 
-**Highlight**: Built-in pure-Python `.lcm` file parser — no `lcm-gen` or `PYTHONPATH` needed. Just point to your `.lcm` files and messages are decoded automatically.
+**Highlights**:
+- Built-in pure-Python `.lcm` file parser — no `lcm-gen` or `PYTHONPATH` needed
+- **Message Export**: CSV/JSONL export with field extraction (`--csv`, `--jsonl`, `--field`)
+- **Advanced Monitoring**: Sort/filter stats (`--sort`, `--top`, `--freeze`, `--spark`)
+- **Live Watch Mode**: Continuous refresh for topic/node list (`--watch`)
+- **Recording & Playback**: Full log file support compatible with `lcm-logger`
 
 ## Installation
 
 ```bash
 # From PyPI
-pip install lcm-tools
+pip install lcm-cli
 
 # From source (development)
-git clone https://github.com/your-username/lcm-tools.git
-cd lcm-tools
+git clone https://github.com/Joyserr/lcm-cli.git
+cd lcm-cli
 pip install -e .
 
 # Optional: traditional lcm-gen Python package decode support
-pip install lcm-tools[decode]
+pip install lcm-cli[decode]
 ```
 
 **Requirements**: Python >= 3.9, `typer`, `rich` (`lcm` package is optional, only for legacy `--type module.Class` decoding).
@@ -38,9 +49,15 @@ pip install lcm-tools[decode]
 # Show all subcommands
 lcm --help
 
+# Show version
+lcm --version
+
 # List active channels (listens for 5 seconds)
 lcm topic list
 
+# Continuous watch mode (live refresh)
+lcm topic list --watch
+
 # View messages on a channel (raw hex format)
 lcm topic echo EXAMPLE
 
@@ -53,15 +70,106 @@ lcm topic echo "CAM.*"
 # Monitor real-time statistics for all channels
 lcm topic stats
 
-# Monitor a specific channel only
-lcm topic stats CAMERA
+# Sort by bandwidth, show top 5
+lcm topic stats --sort bw --top 5
+
+# Freeze mode (single snapshot)
+lcm topic stats --freeze
+
+# Monitor bandwidth with sparkline graph
+lcm topic bw CAMERA --spark
+
+# Detailed channel information
+lcm topic info CAMERA --lcm-file types/
 
 # List discovered publisher nodes
 lcm node list
 ```
 
+## Recording & Playback
+
+```bash
+# Record all channels to a .log file
+lcm record
+
+# Record specific channels with regex
+lcm record --channel "CAM.*" -o camera.log
+
+# Record for a fixed duration
+lcm record -d 60  # 60 seconds
+
+# Replay a .log file
+lcm play camera.log
+
+# Replay at 2x speed
+lcm play camera.log --speed 2.0
+
+# Loop playback
+lcm play camera.log --loop
+```
+
+## Message Export
+
+```bash
+# Export to CSV (headers auto-determined from first message)
+lcm topic echo EXAMPLE --csv output.csv
+
+# Export to JSON Lines
+lcm topic echo EXAMPLE --jsonl output.jsonl
+
+# Extract specific fields
+lcm topic echo EXAMPLE --field position --field velocity --csv data.csv
+
+# Extract nested fields
+lcm topic echo EXAMPLE --field imu.accel.x --field imu.gyro.y
+
+# Extract array slices
+lcm topic echo EXAMPLE --field "position[0:2]"
+
+# Custom timestamp format
+lcm topic echo EXAMPLE --csv data.csv --ts-format iso
+```
+
+## Advanced Statistics
+
+```bash
+# Sort channels by message rate
+lcm topic stats --sort rate
+
+# Show top 10 channels by bandwidth
+lcm topic stats --sort bw --top 10
+
+# Single snapshot (non-interactive)
+lcm topic stats --freeze
+
+# Add sparkline trend visualization
+lcm topic stats --spark
+
+# Monitor bandwidth for a single channel
+lcm topic bw CAMERA --window 10 --spark
+
+# Read stats from log file
+lcm topic stats --from recording.log
+```
+
 ## Message Decoding
 
+### Type Diagnostics
+
+```bash
+# List all registered types
+lcm type list
+
+# Filter by package
+lcm type list --package exlcm
+
+# Show type structure
+lcm type show example_t --lcm-file types/
+
+# Grep search types
+lcm type list --grep "sensor"
+```
+
 ### Method 1: Specify `.lcm` files directly (recommended)
 
 No `lcm-gen` installation, no `PYTHONPATH` configuration. The tool includes a built-in pure-Python parser:
@@ -94,7 +202,7 @@ Supports the complete LCM type system:
 
 ```bash
 # Install the lcm Python package
-pip install lcm-tools[decode]
+pip install lcm-cli[decode]
 
 # Generate Python files with lcm-gen, then configure PYTHONPATH
 lcm-gen --python -d types/ types/example_t.lcm
@@ -156,6 +264,8 @@ Reference: [LCM UDP Multicast Protocol](https://lcm-proj.github.io/lcm/content/u
 
 ## LCM vs ROS2 Concepts
 
+LCM and ROS2 share similar pub/sub communication patterns. Here's a concept mapping:
+
 | LCM Concept | ROS2 Equivalent | Description |
 |-------------|----------------|-------------|
 | Channel | Topic | Message publish/subscribe conduit |
@@ -165,13 +275,21 @@ Reference: [LCM UDP Multicast Protocol](https://lcm-proj.github.io/lcm/content/u
 ## Project Structure
 
 ```
-src/lcm_tools/
+src/lcm_cli/
+├── __init__.py                  # Package definition + version
+├── __main__.py                  # python -m lcm_cli entry point
 ├── cli.py                       # Typer entry point, registers subcommands
 ├── commands/
-│   ├── topic_echo.py            # lcm topic echo
-│   ├── topic_list.py            # lcm topic list
-│   ├── topic_stats.py           # lcm topic stats
-│   └── node_list.py             # lcm node list
+│   ├── topic_echo.py            # lcm topic echo (with --csv/--jsonl export)
+│   ├── topic_list.py            # lcm topic list (with --watch mode)
+│   ├── topic_stats.py           # lcm topic stats (with --sort/--top/--freeze)
+│   ├── topic_bw.py              # lcm topic bw (bandwidth monitor)
+│   ├── topic_info.py            # lcm topic info (channel details)
+│   ├── node_list.py             # lcm node list (with --watch mode)
+│   ├── type_list.py             # lcm type list
+│   ├── type_show.py             # lcm type show
+│   ├── record.py                # lcm record
+│   └── play.py                  # lcm play
 ├── core/
 │   ├── discovery.py             # Passive channel/node discovery
 │   ├── stats.py                 # Real-time statistics (rate, bandwidth)
@@ -179,9 +297,13 @@ src/lcm_tools/
 │   └── lcm_type_builder.py      # Runtime decode class generation + TypeRegistry
 ├── display/
 │   ├── echo_display.py          # Rich panel display (with recursive nesting)
-│   └── stats_display.py         # Statistics table display
+│   ├── stats_display.py         # Statistics table display (with sparkline)
+│   └── type_display.py          # Type structure table display
+├── export.py                    # Field extraction + CSV/JSONL writers
+├── lcm_log.py                   # LCM log file reader/writer (lcm-logger compatible)
 ├── listener.py                  # UDP multicast listener thread
-└── protocol.py                  # LCM Wire Protocol parser
+├── protocol.py                  # LCM Wire Protocol parser
+└── source.py                    # PacketSource abstraction (live/offline)
 ```
 
 ## Testing