Overview

Custom message mappings let you visualize any ROS 2 message type in Rerun without writing code. Define a JSON5 file that maps message fields to Rerun archetypes, and Rewire handles the rest.

Usage

rewire record --mappings mappings.json5

Generating a template

Use rewire mappings generate to scaffold a mappings file from the types currently discoverable on the network. Rewire inspects each topic, resolves custom message schemas, and writes a JSON5 template you can edit.

rewire mappings generate --output mappings.json5

Basic example

[
  {
    type: "my_robot/MotorStatus",
    entity: "motor",
    fields: {
      temperature: { archetype: "Scalars" },
      rpm: { archetype: "Scalars" },
      status_text: { archetype: "TextLog" },
    }
  },
]

This maps the my_robot/MotorStatus message so that:

• temperature is logged as a Scalars entity
• rpm is logged as a Scalars entity
• status_text is logged as a TextLog entity

Mapping entry structure

Each entry in the mappings array has:

Field mapping types

Fields can be mapped in four ways:

1. Leaf — single value to a simple archetype (Scalars, TextLog, TextDocument)
2. Composite — multiple sub-fields to a complex archetype (Points3D, Boxes2D, etc.)
3. Expansion — iterate over arrays with each
4. Nested — recurse into sub-messages with fields