State Machine Panel

The State Machine panel visualizes robot state machines extracted from recording data. See the current state, full transition history, and interactive state graph — all synchronized with the MCAP timeline. Scrub through a recording and watch the state machine animate in real time.

The State Machine Panel is in preview. Features described on this page may change.

State Graph

The panel renders an interactive directed graph where nodes represent states and edges represent transitions.

Nodes are labeled with the state name (e.g., idle, navigating, grasping, placing)
Edges connect source and target states with directional arrows
The current state is highlighted during playback and updates as the timeline advances
Transition counts are displayed on each edge, showing how many times that transition occurred in the recording
Animated transitions sync with timeline scrubbing — drag the playback head and watch the active state change in the graph

Graph Layout

The graph layout is computed automatically using a force-directed algorithm. States with more transitions between them are positioned closer together. You can manually drag nodes to rearrange the layout, and the panel remembers your arrangement for the session.

Visual Element	Meaning
Filled node	Current active state
Outlined node	Inactive state
Solid edge	Observed transition
Dashed edge	Defined but not yet observed transition
Edge label	Transition count
Red node border	Error state
Pulsing edge	Transition that just occurred (animation)
Dimmed node	State not reachable from the current state

Graph Interaction

Action	Control
Pan	Click and drag on background
Zoom	Scroll wheel
Select state	Click a node
Move state	Drag a node
Inspect transition	Click an edge
Reset layout	Double-click background
Toggle labels	Press `L`

When you select a state node, the panel highlights all incoming and outgoing transitions and dims unrelated parts of the graph. The analytics tab filters to show only metrics for the selected state. When you click a transition edge, a tooltip shows the transition details: source state, target state, occurrence count, and the most recent metadata fields for that transition.

Configuration

Define state machines by mapping topic data to states and transitions.

State Definition

Parameter	Type	Description	Example
`topic`	string	Source topic for state data	`/robot/state`
`state_field`	string	Field path containing the state value	`data.current_state`
`timestamp_field`	string	Field path containing the transition time	`header.stamp`
`metadata_fields`	array	Additional fields to display on transitions	`["data.duration", "data.reason"]`

Transition Definition

You can either define transitions explicitly or let the panel infer them from the data. Explicit definitions enable the panel to show dashed edges for transitions that are possible but have not occurred, which is useful for identifying missing coverage. Example configuration:

{
  "topic": "/robot/state",
  "state_field": "data.current_state",
  "timestamp_field": "header.stamp",
  "metadata_fields": ["data.duration", "data.reason"],
  "states": ["idle", "navigating", "grasping", "placing", "error"],
  "transitions": {
    "idle": ["navigating"],
    "navigating": ["grasping", "idle", "error"],
    "grasping": ["placing", "error"],
    "placing": ["idle", "error"],
    "error": ["idle"]
  }
}

Auto-Detection

A topic is assigned to the State Machine panel when:

Its topic name contains state_machine, fsm, or behavior_tree, or
Its schema name matches *StateMachine* or *BehaviorState*

When auto-detected, the panel infers states and transitions from the observed data. You can refine this by providing an explicit configuration.

Multiple State Machines

A single recording may contain multiple state machines (e.g., one for navigation and one for manipulation). Add multiple configurations to monitor them simultaneously. Each state machine renders as a separate graph within the panel.

[
  {
    "name": "Navigation",
    "topic": "/nav/state",
    "state_field": "data.state",
    "states": ["idle", "planning", "navigating", "arrived", "stuck"]
  },
  {
    "name": "Manipulation",
    "topic": "/manip/state",
    "state_field": "data.phase",
    "states": ["idle", "approaching", "grasping", "lifting", "placing"]
  }
]

Use the tab bar at the top of the panel to switch between state machines, or enable split view to display them side by side.

Nested States

For hierarchical state machines, use dot notation in state names to represent nested states. The panel renders these as grouped clusters in the graph.

State Name	Rendered As
`navigating`	Top-level node
`navigating.planning`	Child node inside `navigating` group
`navigating.executing`	Child node inside `navigating` group
`navigating.recovering`	Child node inside `navigating` group

Transitions between nested states are rendered within the parent cluster. Transitions that cross cluster boundaries are rendered as edges between clusters.

History View

The History view renders a horizontal bar chart alongside the timeline, showing the duration of each state as colored bars. This view is designed to be stacked with other panels for cross-referencing.

Reading the History

Each row corresponds to one state
Bar width represents time spent in that state
Colors are assigned deterministically per state name and remain consistent across recordings
Hover over a bar segment to see transition metadata: the reason for entering the state, the duration in that state, and the trigger that caused the exit transition
Click a bar segment to seek the timeline to that state transition

State Color Assignment

State Category	Default Color	Examples
Idle / waiting	Blue	`idle`, `standby`, `waiting`
Active / moving	Green	`navigating`, `executing`, `running`
Manipulating	Teal	`grasping`, `placing`, `lifting`
Error / fault	Red	`error`, `fault`, `emergency_stop`
Custom	Auto-assigned	Any other state name

You can override colors in the panel settings by providing a state_colors map:

{
  "state_colors": {
    "idle": "#4A90D9",
    "navigating": "#27AE60",
    "grasping": "#16A085",
    "error": "#E74C3C"
  }
}

Timeline Integration

The History view is synchronized with the shared timeline. During playback, a vertical cursor moves across the bars to indicate the current time. Click anywhere in the History view to seek the entire viewer to that timestamp. The History view can also be stacked below the Plot panel to correlate state transitions with numeric sensor signals. For example, a transition to error that aligns with an IMU spike suggests the error was caused by a physical disturbance.

State Analytics

The analytics tab provides aggregate statistics computed over the entire recording.

Per-State Metrics

Metric	Description
Total time	Cumulative time spent in this state
Average duration	Mean duration per visit
Min duration	Shortest visit to this state
Max duration	Longest visit to this state
Visit count	Number of times the state was entered
% of recording	Percentage of total recording time in this state

Transition Frequency Matrix

A heatmap showing how often each transition occurs. Rows are source states, columns are target states, and cell values are transition counts. Darker cells indicate more frequent transitions. This matrix is useful for identifying:

Hot paths — the most common state sequences
Anomalous transitions — unexpected state changes that indicate bugs or edge cases
Dead transitions — defined transitions that never fire, suggesting unreachable logic

Anomaly Detection

The panel flags transitions that were not defined in the configuration but were observed in the data. These are marked with a warning icon in the graph and highlighted in the transition matrix.

Anomalous transitions often indicate bugs in state machine logic. If you see unexpected transitions, inspect the metadata fields for the trigger and reason to understand the root cause.

Pre-built Templates

Common robot state machine templates are available to get started quickly. Select a template from the panel settings to pre-populate the state and transition definitions.

Template	States	Use Case
Navigation	`idle`, `planning`, `navigating`, `arrived`, `stuck`	Mobile robot navigation
Manipulation	`idle`, `approaching`, `grasping`, `lifting`, `placing`, `releasing`	Pick-and-place tasks
Inspection	`idle`, `scanning`, `analyzing`, `reporting`	Automated visual inspection
Delivery	`idle`, `loading`, `in_transit`, `unloading`, `returning`	Delivery and logistics
Charging	`active`, `low_battery`, `docking`, `charging`, `undocking`	Battery management

Applying a Template

Open the State Machine panel settings.
Select a template from the Templates dropdown.
Adjust the topic and state_field to match your data.
Optionally add or remove states and transitions for your specific robot.

Templates provide a starting point — you can customize every aspect of the state machine definition after applying one.

Exporting State Data

Export the full state transition log or analytics summary from the panel settings menu.

Export Formats

Format	Contents	Use Case
CSV	One row per transition with timestamp, source, target, duration, metadata	Offline analysis in spreadsheets or pandas
JSON	Structured array of transition objects	Programmatic processing
Summary PDF	State analytics tables and transition matrix as a formatted report	Sharing with stakeholders

Transition Log Schema

Each row in the exported transition log contains:

Column	Type	Description
`timestamp`	ISO 8601	When the transition occurred
`from_state`	string	Source state
`to_state`	string	Target state
`duration_in_state_seconds`	number	How long the system was in `from_state` before transitioning
`reason`	string	Transition reason (from metadata, if available)
`metadata`	JSON	All metadata fields for this transition

Exported data includes all transitions in the recording, not just the currently visible time range. Use the time range filter in the export dialog to narrow the output.

Keyboard Shortcuts

Shortcut	Action
`G`	Toggle between graph view and history view
`A`	Open the analytics tab
`L`	Toggle edge labels
`F`	Fit graph to panel bounds
`N`	Step to next transition
`P`	Step to previous transition
`Esc`	Deselect current node or edge

Use Cases

Debug stuck states

Identify when a navigation pipeline enters a stuck state by examining the transition history and time-in-state metrics.

Analyze manipulation timing

Measure the duration of each phase in a pick-and-place sequence to optimize cycle time and identify bottlenecks.

Find error-prone transitions

Use the transition frequency matrix to discover which state transitions most often lead to error states.

Compare behavior across runs

Open two recordings side-by-side and compare state machine analytics to see how a code change affects robot behavior.

Combine the State Machine panel with the Plot panel to correlate state transitions with sensor signals. For example, overlay the state history with IMU data to see whether navigation failures correspond to sudden acceleration events.

Next Steps

Diagnostics Panel

Monitor system health metrics alongside state machine visualization.

MCAP Viewer

Learn about the full multi-sensor viewer that hosts the State Machine panel.

Fleet Dashboard

Aggregate state machine analytics across your entire fleet.

Overview

MCAP & ROS

Panels & Layout

3D Rendering

Fleet Management

Extensions

Guides

State Graph

Graph Layout

Graph Interaction

Configuration

State Definition

Transition Definition

Auto-Detection

Multiple State Machines

Nested States

History View

Reading the History

State Color Assignment

Timeline Integration

State Analytics

Per-State Metrics

Transition Frequency Matrix

Anomaly Detection

Pre-built Templates

Applying a Template

Exporting State Data

Export Formats

Transition Log Schema

Keyboard Shortcuts

Use Cases

Next Steps

Overview

MCAP & ROS

Panels & Layout

3D Rendering

Fleet Management

Extensions

Guides

​State Graph

​Graph Layout

​Graph Interaction

​Configuration

​State Definition

​Transition Definition

​Auto-Detection

​Multiple State Machines

​Nested States

​History View

​Reading the History

​State Color Assignment

​Timeline Integration

​State Analytics

​Per-State Metrics

​Transition Frequency Matrix

​Anomaly Detection

​Pre-built Templates

​Applying a Template

​Exporting State Data

​Export Formats

​Transition Log Schema

​Keyboard Shortcuts

​Use Cases

​Next Steps

State Graph

Graph Layout

Graph Interaction

Configuration

State Definition

Transition Definition

Auto-Detection

Multiple State Machines

Nested States

History View

Reading the History

State Color Assignment

Timeline Integration

State Analytics

Per-State Metrics

Transition Frequency Matrix

Anomaly Detection

Pre-built Templates

Applying a Template

Exporting State Data

Export Formats

Transition Log Schema

Keyboard Shortcuts

Use Cases

Next Steps