State transition visualization for robot behavior analysis
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.
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.
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.
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:
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.
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.
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.
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
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.
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
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.
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.
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.
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.
