> ## Documentation Index
> Fetch the complete documentation index at: https://avala.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# State Machine Panel

> 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.

<Info>
  The State Machine Panel is in preview. Features described on this page may change.
</Info>

## 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:

```json theme={null}
{
  "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.

```json theme={null}
[
  {
    "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:

```json theme={null}
{
  "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.

<Tip>
  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.
</Tip>

## 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

1. Open the State Machine panel settings.
2. Select a template from the **Templates** dropdown.
3. Adjust the `topic` and `state_field` to match your data.
4. 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                      |

<Note>
  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.
</Note>

## 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

<CardGroup cols={2}>
  <Card title="" icon="bug">
    <p style={{fontWeight: 600, fontSize: '18px', marginBottom: '4px', marginTop: '8px', color: 'inherit'}}>Debug stuck states</p>
    <p style={{fontSize: '14px', marginTop: '0px', opacity: 0.6}}>Identify when a navigation pipeline enters a stuck state by examining the transition history and time-in-state metrics.</p>
  </Card>

  <Card title="" icon="stopwatch">
    <p style={{fontWeight: 600, fontSize: '18px', marginBottom: '4px', marginTop: '8px', color: 'inherit'}}>Analyze manipulation timing</p>
    <p style={{fontSize: '14px', marginTop: '0px', opacity: 0.6}}>Measure the duration of each phase in a pick-and-place sequence to optimize cycle time and identify bottlenecks.</p>
  </Card>

  <Card title="" icon="triangle-exclamation">
    <p style={{fontWeight: 600, fontSize: '18px', marginBottom: '4px', marginTop: '8px', color: 'inherit'}}>Find error-prone transitions</p>
    <p style={{fontSize: '14px', marginTop: '0px', opacity: 0.6}}>Use the transition frequency matrix to discover which state transitions most often lead to error states.</p>
  </Card>

  <Card title="" icon="code-compare">
    <p style={{fontWeight: 600, fontSize: '18px', marginBottom: '4px', marginTop: '8px', color: 'inherit'}}>Compare behavior across runs</p>
    <p style={{fontSize: '14px', marginTop: '0px', opacity: 0.6}}>Open two recordings side-by-side and compare state machine analytics to see how a code change affects robot behavior.</p>
  </Card>
</CardGroup>

<Tip>
  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.
</Tip>

## Next Steps

<CardGroup cols={3}>
  <Card title="" icon="heart-pulse" href="/docs/visualization/panels/diagnostics-panel">
    <p style={{fontWeight: 600, fontSize: '18px', marginBottom: '4px', marginTop: '8px', color: 'inherit'}}>Diagnostics Panel</p>
    <p style={{fontSize: '14px', marginTop: '0px', opacity: 0.6}}>Monitor system health metrics alongside state machine visualization.</p>
  </Card>

  <Card title="" icon="play" href="/docs/visualization/multi-sensor-viewer">
    <p style={{fontWeight: 600, fontSize: '18px', marginBottom: '4px', marginTop: '8px', color: 'inherit'}}>MCAP Viewer</p>
    <p style={{fontSize: '14px', marginTop: '0px', opacity: 0.6}}>Learn about the full multi-sensor viewer that hosts the State Machine panel.</p>
  </Card>

  <Card title="" icon="satellite-dish" href="/docs/visualization/fleet/fleet-dashboard">
    <p style={{fontWeight: 600, fontSize: '18px', marginBottom: '4px', marginTop: '8px', color: 'inherit'}}>Fleet Dashboard</p>
    <p style={{fontSize: '14px', marginTop: '0px', opacity: 0.6}}>Aggregate state machine analytics across your entire fleet.</p>
  </Card>
</CardGroup>