eventcatalog-generator-ros

An EventCatalog generator plugin that automatically documents ROS (Robot Operating System) nodes, topics, message types, and their publish/subscribe relationships. It scans your ROS system — either live, from launch files, or from a pre-captured snapshot — and generates a fully interactive EventCatalog with services, events, domains, and JSON Schemas.

Table of Contents

• Why This Plugin?
• How It Works
• Installation
• Quick Start
• Configuration Reference
• CLI Reference
• Snapshot Format
• Architecture & Mapping
• Examples
• Development
• License

Why This Plugin?

ROS systems can grow to hundreds of nodes and topics. Understanding which node publishes what, which node subscribes to what, and how data flows through the system becomes a challenge. This plugin:

• Auto-generates browsable documentation from your running ROS system or codebase
• Visualizes pub/sub relationships through EventCatalog's built-in service/event diagrams
• Organizes nodes into logical groups (Navigation, Perception, Control, etc.)
• Simplifies message types into human-readable descriptions while preserving full JSON Schema definitions
• Works in CI/CD via snapshot files — no running ROS system needed for doc generation

How It Works

┌─────────────────────────────────────────────────────────────┐
│                     Input Sources                           │
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │  Live Scan   │  │ Launch Files │  │  YAML/JSON       │  │
│  │  rosnode list │  │ .launch XML  │  │  Snapshot        │  │
│  │  ros2 node   │  │ .launch.py   │  │  (recommended)   │  │
│  └──────┬───────┘  └──────┬───────┘  └────────┬─────────┘  │
│         └──────────────────┼──────────────────┘             │
└────────────────────────────┼────────────────────────────────┘
                             ▼
                    ┌─────────────────┐
                    │   ROS Graph     │
                    │  (Nodes+Topics  │
                    │   +Messages)    │
                    └────────┬────────┘
                             ▼
                    ┌─────────────────┐
                    │ Grouping Engine │
                    │  (glob-based +  │
                    │  package-based) │
                    └────────┬────────┘
                             ▼
                    ┌─────────────────┐
                    │  Catalog Writer │
                    │ (EventCatalog   │
                    │     SDK)        │
                    └────────┬────────┘
                             ▼
                    ┌─────────────────┐
                    │  EventCatalog   │
                    │  Domains,       │
                    │  Services,      │
                    │  Events,        │
                    │  Schemas        │
                    └─────────────────┘

Three Input Modes

| Mode | Best For | How It Works | |------|----------|--------------| | live | Development / exploration | Shells out to rosnode list, rostopic info, rosmsg show (ROS 1) or ros2 node list, ros2 topic info, ros2 interface show (ROS 2) | | launch-file | Static codebase analysis | Parses .launch XML (ROS 1) and .launch.py Python (ROS 2) files to extract <node> declarations and Node() calls | | snapshot | CI/CD, reproducible builds | Loads a YAML/JSON file describing the full ROS graph — capture once, generate anywhere |

Installation

npm install eventcatalog-generator-ros

Prerequisites:

• Node.js ≥ 18
• An EventCatalog project (for generator mode)
• A sourced ROS workspace (only for live scanning mode)

Quick Start

Option A: From a Snapshot (Recommended)

Step 1. Initialize a config file:

npx ros-catalog init

Step 2. Create (or capture) a snapshot of your ROS system:

# If you have a running ROS system:
npx ros-catalog scan --ros-version 2 --output ros-graph.yaml

# Or copy the included example:
cp node_modules/eventcatalog-generator-ros/examples/ros-system.yaml ./ros-graph.yaml

Step 3. Edit ros-catalog.config.yaml to point at your snapshot and define groups:

source: snapshot
rosVersion: 2
snapshotPath: ./ros-graph.yaml

groups:
  - id: navigation
    name: Navigation
    description: "Path planning and localization"
    nodes: ["/move_base*", "/amcl*", "/map_server*"]

  - id: perception
    name: Perception
    description: "Sensor processing and obstacle detection"
    nodes: ["/camera*", "/lidar*", "/pointcloud*"]

  - id: control
    name: Control
    description: "Motor control and actuation"
    nodes: ["/motor*", "/joint*"]

domain:
  id: my-robot
  name: My Robot System
  version: "1.0.0"

Step 4. Add to your EventCatalog project's eventcatalog.config.js:

module.exports = {
  // ... other EventCatalog config
  generators: [
    [
      'eventcatalog-generator-ros',
      {
        source: 'snapshot',
        rosVersion: 2,
        snapshotPath: './ros-graph.yaml',
        groups: [
          { id: 'navigation', name: 'Navigation', nodes: ['/move_base*', '/amcl*'] },
          { id: 'perception', name: 'Perception', nodes: ['/camera*', '/lidar*'] },
        ],
        domain: { id: 'my-robot', name: 'My Robot System', version: '1.0.0' },
      },
    ],
  ],
};

Step 5. Generate:

npm run generate

Option B: Live Scan

# Source your ROS workspace first
source /opt/ros/humble/setup.bash  # ROS 2
# or: source /opt/ros/noetic/setup.bash  # ROS 1

# Scan and export
npx ros-catalog scan --source live --ros-version 2 --output ros-graph.yaml

Option C: From Launch Files

npx ros-catalog scan \
  --source launch-file \
  --launch-files src/my_robot/launch/robot.launch.py \
  --output ros-graph.yaml

Configuration Reference

Top-Level Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | source | 'live' \| 'launch-file' \| 'snapshot' | 'snapshot' | How to discover the ROS graph | | rosVersion | 1 \| 2 | 2 | ROS version (affects CLI commands and launch file parsing) | | snapshotPath | string | — | Path to YAML/JSON snapshot file | | launchFiles | string[] | — | Glob patterns for launch files to parse | | rosPackagePaths | string[] | — | Directories containing ROS packages for static .msg parsing | | groups | GroupDefinition[] | — | Custom logical groups (→ EventCatalog domains) | | messageDescriptions | Record<string, string> | — | User-provided simplified descriptions by message type | | messageTemplates | Record<string, string> | — | Override templates for message documentation | | services.version | string | '1.0.0' | Version string for generated services/events | | domain | { id, name, version } | — | Root domain that wraps all groups | | debug | boolean | false | Enable verbose logging |

Group Definition

Groups map ROS nodes and topics to EventCatalog domains for logical organization.

groups:
  - id: navigation           # Unique group ID → EventCatalog domain ID
    name: Navigation          # Display name
    description: "..."        # Optional markdown description
    nodes:                    # Glob patterns matching node names
      - "/move_base*"
      - "/amcl*"
    topics:                   # Glob patterns matching topic names
      - "/cmd_vel"
      - "/map"
    children:                 # Nested sub-groups (hierarchical domains)
      - id: localization
        name: Localization
        nodes: ["/amcl*"]

How matching works:

• Patterns use glob syntax via minimatch
• Topics connected to matched nodes are automatically included in the group
• When no custom groups are defined, nodes are grouped by their ROS package name

Message Descriptions

Override auto-generated message descriptions with concise summaries:

messageDescriptions:
  geometry_msgs/Twist: "Velocity command with linear (x,y,z) and angular (x,y,z) components"
  sensor_msgs/LaserScan: "2D planar laser range scan with angle and range arrays"
  nav_msgs/Odometry: "Robot pose and velocity from wheel odometry"

CLI Reference

The plugin includes a standalone CLI tool for working outside of EventCatalog.

ros-catalog scan

Discover a ROS graph and save it as a snapshot file.

ros-catalog scan [options]

Options:
  -s, --source <type>         Source: live, launch-file, snapshot (default: "live")
  -r, --ros-version <ver>     ROS version: 1 or 2 (default: "2")
  -l, --launch-files <files>  Launch file paths (for launch-file source)
  -i, --snapshot <path>       Input snapshot path (for snapshot source)
  -o, --output <path>         Output file path (default: "./ros-graph.yaml")
  -f, --format <fmt>          Output format: yaml or json (default: "yaml")
  --debug                     Enable debug logging

Examples:

# Scan a live ROS 2 system
ros-catalog scan --ros-version 2 --output my-robot.yaml

# Scan ROS 1 system
ros-catalog scan --ros-version 1 --output my-robot.yaml

# Parse launch files
ros-catalog scan --source launch-file --launch-files robot.launch bringup.launch.py

# Convert between formats
ros-catalog scan --source snapshot --snapshot graph.yaml --output graph.json --format json

ros-catalog generate

Run the full EventCatalog generator from a config file.

ros-catalog generate [options]

Options:
  -c, --config <path>       Config file path (default: "./ros-catalog.config.yaml")
  -d, --catalog-dir <path>  EventCatalog project directory (default: ".")
  --debug                   Enable debug logging

ros-catalog init

Create a starter configuration file with example groupings.

ros-catalog init [options]

Options:
  -o, --output <path>  Output path (default: "./ros-catalog.config.yaml")

Snapshot Format

The snapshot is a YAML or JSON file that fully describes your ROS computational graph. This is the recommended input for CI/CD pipelines.

metadata:
  rosVersion: 2
  scannedAt: "2026-03-23T12:00:00Z"
  source: "snapshot"

nodes:
  - name: /move_base
    package: move_base          # ROS package name
    namespace: /navigation      # Optional namespace
    publishers:
      - topic: /cmd_vel
        messageType: geometry_msgs/Twist
    subscribers:
      - topic: /odom
        messageType: nav_msgs/Odometry
      - topic: /scan
        messageType: sensor_msgs/LaserScan

topics:
  - name: /cmd_vel
    messageType: geometry_msgs/Twist
    publishers: [/move_base]
    subscribers: [/motor_controller]

messages:
  - type: geometry_msgs/Twist
    fields:
      - name: linear
        type: geometry_msgs/Vector3
        isArray: false
        comment: "Linear velocity (m/s)"
      - name: angular
        type: geometry_msgs/Vector3
        isArray: false
        comment: "Angular velocity (rad/s)"
    constants: []

The snapshot is validated at load time against a strict Zod schema — any structural errors are reported with clear messages.

Architecture & Mapping

The plugin maps ROS concepts to EventCatalog concepts:

| ROS Concept | EventCatalog Concept | What You Get | |---|---|---| | Topic | Event | Rich docs with publisher/subscriber lists, message description, badge with message type | | Node | Service | Docs with sends (published topics) and receives (subscribed topics), package info | | Group / Package | Domain | Hierarchical organization with node/topic listings | | Message type (.msg) | Schema (JSON Schema) | Auto-generated JSON Schema attached to events | | Node publishes topic | Service → sends → Event | Visualized in EventCatalog's service diagram | | Node subscribes topic | Service → receives → Event | Visualized in EventCatalog's service diagram |

Generated Documentation

For each node (service), the plugin generates markdown with:

• Node name, package, and namespace
• Table of published topics with message types
• Table of subscribed topics with message types
• Badge showing the ROS package

For each topic (event), the plugin generates markdown with:

• Topic name and message type
• List of publishers and subscribers
• Simplified human-readable description of the message
• JSON Schema derived from the .msg definition

Examples

The plugin ships with a complete example in the examples/ directory:

| File | Description | |------|-------------| | ros-system.yaml | Snapshot of a mobile robot with 9 nodes, 15 topics, and 5 message types across navigation, perception, control, and telemetry subsystems | | ros-catalog.config.yaml | Configuration with 4 groups, message descriptions, and domain settings | | example.launch | ROS 1 XML launch file demonstrating the launch parser |

Try it:

# Generate from the example snapshot
npx ros-catalog scan --source snapshot \
  --snapshot node_modules/eventcatalog-generator-ros/examples/ros-system.yaml \
  --output ros-graph.yaml

Development

# Clone the repo
git clone https://github.com/someshsandbox/eventcatalog-generator-ros.git
cd eventcatalog-generator-ros

# Install dependencies
npm install

# Run tests (42 tests)
npm test

# Build (outputs to dist/)
npm run build

# Run CLI in dev mode
npx tsx src/cli.ts scan --help

Project Structure

src/
├── index.ts                    # EventCatalog generator entry point
├── cli.ts                      # CLI (scan / generate / init)
├── types.ts                    # TypeScript interfaces
├── schemas.ts                  # Zod validation schemas
├── catalog-writer.ts           # Writes to EventCatalog via SDK
├── discovery/
│   ├── index.ts                # Factory: picks discovery strategy
│   ├── live-scanner.ts         # ROS 1 + ROS 2 CLI wrappers
│   ├── launch-parser.ts        # XML (.launch) + Python (.launch.py)
│   ├── snapshot-loader.ts      # YAML/JSON with Zod validation
│   └── message-parser.ts       # .msg → JSON Schema + descriptions
├── grouping/
│   └── grouping-engine.ts      # Glob + package-based grouping
├── utils/
│   ├── logger.ts               # Colored console output
│   └── naming.ts               # Name sanitization utilities
└── __tests__/                  # 42 tests across 5 files

License

MIT © someshsandbox