# pulsecoreengineering/pulsehsm architecture

> Architecture diagram of the GitHub repository pulsecoreengineering/pulsehsm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pulsecoreengineering/pulsehsm
- Repository: https://github.com/pulsecoreengineering/pulsehsm

## Overview

PulseHSM is a small, allocation-free embedded hierarchical state-machine library. A user supplies a static state table and callbacks, starts the machine with begin(), then calls update() from the main loop; the runtime dispatches queued events, runs timed and per-state update behavior, and applies requested transitions with hierarchical entry/exit semantics. The graph emphasizes this runtime workflow and its internal state-table and transition machinery. README-described capabilities are included; source excerpts do not expose every helper implementation, so uncertain internal links are omitted.

Main entry points: [`PulseHSM.cpp`](https://github.com/pulsecoreengineering/pulsehsm/blob/main/PulseHSM.cpp) (Start machine), [`PulseHSM.h`](https://github.com/pulsecoreengineering/pulsehsm/blob/main/PulseHSM.h) (Static state table)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_table["Static state table<br/>[PulseHSM.h]"]
  node_validate["Table validation<br/>[PulseHSM.h]"]
end

subgraph group_runtime["HSM runtime"]
  node_machine["PulseHSM instance<br/>[PulseHSM.h]"]
  node_begin["Start machine<br/>[PulseHSM.cpp]"]
  node_update["Update scheduler<br/>[PulseHSM.cpp]"]
end

subgraph group_state["State processing"]
  node_statecache["Active state cache<br/>[PulseHSM.cpp]"]
  node_transitions["Transition execution<br/>[PulseHSM.cpp]"]
  node_hierarchy["Hierarchy traversal<br/>[PulseHSM.cpp]"]
  node_callbacks["State callbacks<br/>[PulseHSM.h]"]
  node_timeout["Timed transitions<br/>[PulseHSM.cpp]"]
end

subgraph group_events["Event handling"]
  node_eventapi["Event enqueue API<br/>[PulseHSM.cpp]"]
  node_queue["Fixed event queue<br/>[PulseHSM.h]"]
  node_dispatch["Event dispatch<br/>[PulseHSM.cpp]"]
  node_critical["Interrupt protection<br/>[PulseHSM.h]"]
end

node_user(("Embedded application"))
node_clock(("Arduino timing"))

node_user -->|"defines states"| node_table
node_user -->|"validates table"| node_validate
node_user -->|"starts machine"| node_begin
node_user -->|"ticks runtime"| node_update
node_table -->|"configures"| node_machine
node_validate -->|"checks structure"| node_table
node_begin -->|"initializes"| node_machine
node_begin -->|"resolves initial state"| node_hierarchy
node_begin -->|"builds cache"| node_statecache
node_begin -->|"runs entry actions"| node_callbacks
node_update -->|"dispatches events"| node_dispatch
node_update -->|"checks timeout"| node_timeout
node_update -->|"runs update chain"| node_statecache
node_update -->|"applies pending state"| node_transitions
node_eventapi -->|"enqueues event"| node_queue
node_eventapi -->|"protects access"| node_critical
node_dispatch -->|"dequeues event"| node_queue
node_dispatch -->|"bubbles through"| node_hierarchy
node_dispatch -->|"invokes handlers"| node_callbacks
node_transitions -->|"finds shared ancestor"| node_hierarchy
node_transitions -->|"runs entry and exit"| node_callbacks
node_transitions -->|"refreshes cache"| node_statecache
node_hierarchy -->|"reads parent links"| node_table
node_statecache -->|"reads state rows"| node_table
node_timeout -->|"reads elapsed time"| node_clock
node_begin -->|"records entry time"| node_clock

click node_table "https://github.com/pulsecoreengineering/pulsehsm/blob/main/PulseHSM.h"
click node_validate "https://github.com/pulsecoreengineering/pulsehsm/blob/main/PulseHSM.h"
click node_machine "https://github.com/pulsecoreengineering/pulsehsm/blob/main/PulseHSM.h"
click node_begin "https://github.com/pulsecoreengineering/pulsehsm/blob/main/PulseHSM.cpp"
click node_update "https://github.com/pulsecoreengineering/pulsehsm/blob/main/PulseHSM.cpp"
click node_statecache "https://github.com/pulsecoreengineering/pulsehsm/blob/main/PulseHSM.cpp"
click node_transitions "https://github.com/pulsecoreengineering/pulsehsm/blob/main/PulseHSM.cpp"
click node_hierarchy "https://github.com/pulsecoreengineering/pulsehsm/blob/main/PulseHSM.cpp"
click node_callbacks "https://github.com/pulsecoreengineering/pulsehsm/blob/main/PulseHSM.h"
click node_timeout "https://github.com/pulsecoreengineering/pulsehsm/blob/main/PulseHSM.cpp"
click node_eventapi "https://github.com/pulsecoreengineering/pulsehsm/blob/main/PulseHSM.cpp"
click node_queue "https://github.com/pulsecoreengineering/pulsehsm/blob/main/PulseHSM.h"
click node_dispatch "https://github.com/pulsecoreengineering/pulsehsm/blob/main/PulseHSM.cpp"
click node_critical "https://github.com/pulsecoreengineering/pulsehsm/blob/main/PulseHSM.h"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_table,node_validate toneBlue
class node_machine,node_begin,node_update toneAmber
class node_statecache,node_transitions,node_hierarchy,node_callbacks,node_timeout toneMint
class node_eventapi,node_queue,node_dispatch,node_critical toneRose
class node_user,node_clock toneIndigo
```

## Components

### User interface

- [Static state table](https://github.com/pulsecoreengineering/pulsehsm/blob/main/PulseHSM.h): `PulseHSM.h`
- [Table validation](https://github.com/pulsecoreengineering/pulsehsm/blob/main/PulseHSM.h): `PulseHSM.h`

### HSM runtime

- [PulseHSM instance](https://github.com/pulsecoreengineering/pulsehsm/blob/main/PulseHSM.h): `PulseHSM.h`
- [Start machine](https://github.com/pulsecoreengineering/pulsehsm/blob/main/PulseHSM.cpp): `PulseHSM.cpp`
- [Update scheduler](https://github.com/pulsecoreengineering/pulsehsm/blob/main/PulseHSM.cpp): `PulseHSM.cpp`

### State processing

- [Active state cache](https://github.com/pulsecoreengineering/pulsehsm/blob/main/PulseHSM.cpp): `PulseHSM.cpp`
- [Transition execution](https://github.com/pulsecoreengineering/pulsehsm/blob/main/PulseHSM.cpp): `PulseHSM.cpp`
- [Hierarchy traversal](https://github.com/pulsecoreengineering/pulsehsm/blob/main/PulseHSM.cpp): `PulseHSM.cpp`
- [State callbacks](https://github.com/pulsecoreengineering/pulsehsm/blob/main/PulseHSM.h): `PulseHSM.h`
- [Timed transitions](https://github.com/pulsecoreengineering/pulsehsm/blob/main/PulseHSM.cpp): `PulseHSM.cpp`

### Event handling

- [Event enqueue API](https://github.com/pulsecoreengineering/pulsehsm/blob/main/PulseHSM.cpp): `PulseHSM.cpp`
- [Fixed event queue](https://github.com/pulsecoreengineering/pulsehsm/blob/main/PulseHSM.h): `PulseHSM.h`
- [Event dispatch](https://github.com/pulsecoreengineering/pulsehsm/blob/main/PulseHSM.cpp): `PulseHSM.cpp`
- [Interrupt protection](https://github.com/pulsecoreengineering/pulsehsm/blob/main/PulseHSM.h): `PulseHSM.h`

### Other components

- **Embedded application**
- **Arduino timing**

## Connections

- Embedded application → Static state table: defines states
- Embedded application → Table validation: validates table
- Embedded application → Start machine: starts machine
- Embedded application → Update scheduler: ticks runtime
- Static state table → PulseHSM instance: configures
- Table validation → Static state table: checks structure
- Start machine → PulseHSM instance: initializes
- Start machine → Hierarchy traversal: resolves initial state
- Start machine → Active state cache: builds cache
- Start machine → State callbacks: runs entry actions
- Update scheduler → Event dispatch: dispatches events
- Update scheduler → Timed transitions: checks timeout
- Update scheduler → Active state cache: runs update chain
- Update scheduler → Transition execution: applies pending state
- Event enqueue API → Fixed event queue: enqueues event
- Event enqueue API → Interrupt protection: protects access
- Event dispatch → Fixed event queue: dequeues event
- Event dispatch → Hierarchy traversal: bubbles through
- Event dispatch → State callbacks: invokes handlers
- Transition execution → Hierarchy traversal: finds shared ancestor
- Transition execution → State callbacks: runs entry and exit
- Transition execution → Active state cache: refreshes cache
- Hierarchy traversal → Static state table: reads parent links
- Active state cache → Static state table: reads state rows
- Timed transitions → Arduino timing: reads elapsed time
- Start machine → Arduino timing: records entry time