# ermi77/revovfirmware architecture

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

- Interactive diagram: https://gitdiagram.com/ermi77/revovfirmware
- Repository: https://github.com/ermi77/revovfirmware

## Overview

RevoV is vending-machine firmware split between an ESP32 order/planning brain and an Arduino Mega motion controller, coordinated through a shared pin protocol. The principal path is backend order intake, queueing and per-drink planning on the ESP32, command dispatch and READY synchronization, then physical motion on the Mega. The README also documents a browser simulation/trace console and conveyor advancement. Some implementation links rely on the source index or README rather than complete excerpts, so uncertain internal wiring is omitted or marked dashed.

Main entry points: [`mega/src/main.cpp`](https://github.com/ermi77/revovfirmware/blob/main/mega/src/main.cpp) (Mega runtime), [`esp/src/Core/StateMachine.cpp`](https://github.com/ermi77/revovfirmware/blob/main/esp/src/Core/StateMachine.cpp) (Order state machine), [`mega/src/Core/StateMachine.cpp`](https://github.com/ermi77/revovfirmware/blob/main/mega/src/Core/StateMachine.cpp) (Command state machine), [`esp/src/main.cpp`](https://github.com/ermi77/revovfirmware/blob/main/esp/src/main.cpp) (ESP runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_esp["ESP32 brain"]
  node_esp_main["ESP runtime<br/>[main.cpp]"]
  node_websocket["WebSocket client<br/>[WebSocket.cpp]"]
  node_queue["Order queue<br/>[OrderQueue.cpp]"]
  node_inventory["Slot inventory<br/>[Inventory.cpp]"]
  node_planner["Trajectory planner<br/>[Planner.cpp]"]
  node_esp_sm["Order state machine<br/>[StateMachine.cpp]"]
  node_webui["Web console<br/>[Ui.cpp]"]
  node_eventbus["Trace event bus<br/>[EventBus.cpp]"]
  node_tracker["Machine state tracker<br/>[StateTracker.cpp]"]
end

subgraph group_link["Board protocol"]
  node_pin_driver["Command pin driver<br/>[PinDriver.cpp]"]
  node_ready["READY handler<br/>[ReadyHandler.cpp]"]
end

subgraph group_mega["Mega motion"]
  node_mega_main["Mega runtime<br/>[main.cpp]"]
  node_mega_sm["Command state machine<br/>[StateMachine.cpp]"]
  node_pin_reader["Pin command reader<br/>[PinReader.cpp]"]
  node_scheduler["Motion scheduler<br/>[Scheduler.cpp]"]
  node_axes["Motion axes<br/>[Axes.cpp]"]
  node_stepper["Stepper control<br/>[StepperAxis.cpp]"]
  node_gripper["Gripper assembly<br/>[Gripper.cpp]"]
  node_door["Dispense door<br/>[Door.cpp]"]
  node_conveyor["Shelf conveyor<br/>[Conveyor.cpp]"]
  node_homing["Homing routine<br/>[Home.cpp]"]
end

subgraph group_shared["Shared contract"]
  node_protocol["Wire protocol<br/>[RevoVProtocol.h]"]
end

node_backend(("Order backend"))
node_operator(("Operator"))
node_hardware{{"Machine actuators"}}

node_backend -->|"sends orders"| node_websocket
node_websocket -->|"polls orders"| node_esp_main
node_esp_main -->|"updates control"| node_esp_sm
node_esp_sm -->|"enqueues orders"| node_queue
node_esp_sm -->|"publishes outcomes"| node_websocket
node_esp_sm -->|"plans commands"| node_planner
node_esp_sm -->|"updates slots"| node_inventory
node_esp_sm -->|"dispatches commands"| node_pin_driver
node_esp_sm -->|"publishes trace"| node_eventbus
node_esp_main -->|"initializes bus"| node_eventbus
node_esp_main -->|"initializes console"| node_webui
node_operator -->|"uses console"| node_webui
node_webui -->|"subscribes to trace"| node_eventbus
node_pin_driver -->|"sends commands"| node_mega_main
node_mega_main -->|"waits for READY"| node_ready
node_ready -->|"signals settled"| node_esp_sm
node_mega_main -->|"initializes reader"| node_pin_reader
node_mega_main -->|"initializes axes"| node_axes
node_mega_main -->|"initializes conveyor"| node_conveyor
node_mega_main -->|"initializes door"| node_door
node_mega_main -->|"initializes gripper"| node_gripper
node_mega_main -->|"initializes control"| node_mega_sm
node_mega_main -->|"updates scheduler"| node_scheduler
node_mega_sm -.->|"dispatches motion"| node_axes
node_mega_sm -.->|"dispatches handling"| node_gripper
node_mega_sm -.->|"controls door"| node_door
node_mega_sm -.->|"advances shelf"| node_conveyor
node_mega_sm -.->|"requests homing"| node_homing
node_scheduler -.->|"services motion"| node_stepper
node_axes -->|"uses axes"| node_stepper
node_mega_main -->|"drives"| node_hardware
node_protocol -->|"defines commands"| node_pin_driver
node_protocol -->|"defines actions"| node_conveyor

click node_esp_main "https://github.com/ermi77/revovfirmware/blob/main/esp/src/main.cpp"
click node_websocket "https://github.com/ermi77/revovfirmware/blob/main/esp/src/Net/WebSocket.cpp"
click node_queue "https://github.com/ermi77/revovfirmware/blob/main/esp/src/Order/OrderQueue.cpp"
click node_inventory "https://github.com/ermi77/revovfirmware/blob/main/esp/src/Order/Inventory.cpp"
click node_planner "https://github.com/ermi77/revovfirmware/blob/main/esp/src/Trajectory/Planner.cpp"
click node_esp_sm "https://github.com/ermi77/revovfirmware/blob/main/esp/src/Core/StateMachine.cpp"
click node_webui "https://github.com/ermi77/revovfirmware/blob/main/esp/src/Web/Ui.cpp"
click node_eventbus "https://github.com/ermi77/revovfirmware/blob/main/esp/src/Core/EventBus.cpp"
click node_tracker "https://github.com/ermi77/revovfirmware/blob/main/esp/src/Core/StateTracker.cpp"
click node_pin_driver "https://github.com/ermi77/revovfirmware/blob/main/esp/src/Protocol/PinDriver.cpp"
click node_ready "https://github.com/ermi77/revovfirmware/blob/main/esp/src/Protocol/ReadyHandler.cpp"
click node_protocol "https://github.com/ermi77/revovfirmware/blob/main/shared/RevoVProtocol.h"
click node_mega_main "https://github.com/ermi77/revovfirmware/blob/main/mega/src/main.cpp"
click node_mega_sm "https://github.com/ermi77/revovfirmware/blob/main/mega/src/Core/StateMachine.cpp"
click node_pin_reader "https://github.com/ermi77/revovfirmware/blob/main/mega/src/Protocol/PinReader.cpp"
click node_scheduler "https://github.com/ermi77/revovfirmware/blob/main/mega/src/Core/Scheduler.cpp"
click node_axes "https://github.com/ermi77/revovfirmware/blob/main/mega/src/Motion/Axes.cpp"
click node_stepper "https://github.com/ermi77/revovfirmware/blob/main/mega/src/Motion/StepperAxis.cpp"
click node_gripper "https://github.com/ermi77/revovfirmware/blob/main/mega/src/EndEffector/Gripper.cpp"
click node_door "https://github.com/ermi77/revovfirmware/blob/main/mega/src/EndEffector/Door.cpp"
click node_conveyor "https://github.com/ermi77/revovfirmware/blob/main/mega/src/Shelf/Conveyor.cpp"
click node_homing "https://github.com/ermi77/revovfirmware/blob/main/mega/src/Homing/Home.cpp"

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_esp_main,node_websocket,node_queue,node_inventory,node_planner,node_esp_sm,node_webui,node_eventbus,node_tracker toneBlue
class node_pin_driver,node_ready toneAmber
class node_mega_main,node_mega_sm,node_pin_reader,node_scheduler,node_axes,node_stepper,node_gripper,node_door,node_conveyor,node_homing toneMint
class node_protocol toneRose
class node_backend,node_operator,node_hardware toneIndigo
```

## Components

### ESP32 brain

- [ESP runtime](https://github.com/ermi77/revovfirmware/blob/main/esp/src/main.cpp): `esp/src/main.cpp`
- [WebSocket client](https://github.com/ermi77/revovfirmware/blob/main/esp/src/Net/WebSocket.cpp): `esp/src/Net/WebSocket.cpp`
- [Order queue](https://github.com/ermi77/revovfirmware/blob/main/esp/src/Order/OrderQueue.cpp): `esp/src/Order/OrderQueue.cpp`
- [Slot inventory](https://github.com/ermi77/revovfirmware/blob/main/esp/src/Order/Inventory.cpp): `esp/src/Order/Inventory.cpp`
- [Trajectory planner](https://github.com/ermi77/revovfirmware/blob/main/esp/src/Trajectory/Planner.cpp): `esp/src/Trajectory/Planner.cpp`
- [Order state machine](https://github.com/ermi77/revovfirmware/blob/main/esp/src/Core/StateMachine.cpp): `esp/src/Core/StateMachine.cpp`
- [Web console](https://github.com/ermi77/revovfirmware/blob/main/esp/src/Web/Ui.cpp): `esp/src/Web/Ui.cpp`
- [Trace event bus](https://github.com/ermi77/revovfirmware/blob/main/esp/src/Core/EventBus.cpp): `esp/src/Core/EventBus.cpp`
- [Machine state tracker](https://github.com/ermi77/revovfirmware/blob/main/esp/src/Core/StateTracker.cpp): `esp/src/Core/StateTracker.cpp`

### Board protocol

- [Command pin driver](https://github.com/ermi77/revovfirmware/blob/main/esp/src/Protocol/PinDriver.cpp): `esp/src/Protocol/PinDriver.cpp`
- [READY handler](https://github.com/ermi77/revovfirmware/blob/main/esp/src/Protocol/ReadyHandler.cpp): `esp/src/Protocol/ReadyHandler.cpp`

### Mega motion

- [Mega runtime](https://github.com/ermi77/revovfirmware/blob/main/mega/src/main.cpp): `mega/src/main.cpp`
- [Command state machine](https://github.com/ermi77/revovfirmware/blob/main/mega/src/Core/StateMachine.cpp): `mega/src/Core/StateMachine.cpp`
- [Pin command reader](https://github.com/ermi77/revovfirmware/blob/main/mega/src/Protocol/PinReader.cpp): `mega/src/Protocol/PinReader.cpp`
- [Motion scheduler](https://github.com/ermi77/revovfirmware/blob/main/mega/src/Core/Scheduler.cpp): `mega/src/Core/Scheduler.cpp`
- [Motion axes](https://github.com/ermi77/revovfirmware/blob/main/mega/src/Motion/Axes.cpp): `mega/src/Motion/Axes.cpp`
- [Stepper control](https://github.com/ermi77/revovfirmware/blob/main/mega/src/Motion/StepperAxis.cpp): `mega/src/Motion/StepperAxis.cpp`
- [Gripper assembly](https://github.com/ermi77/revovfirmware/blob/main/mega/src/EndEffector/Gripper.cpp): `mega/src/EndEffector/Gripper.cpp`
- [Dispense door](https://github.com/ermi77/revovfirmware/blob/main/mega/src/EndEffector/Door.cpp): `mega/src/EndEffector/Door.cpp`
- [Shelf conveyor](https://github.com/ermi77/revovfirmware/blob/main/mega/src/Shelf/Conveyor.cpp): `mega/src/Shelf/Conveyor.cpp`
- [Homing routine](https://github.com/ermi77/revovfirmware/blob/main/mega/src/Homing/Home.cpp): `mega/src/Homing/Home.cpp`

### Shared contract

- [Wire protocol](https://github.com/ermi77/revovfirmware/blob/main/shared/RevoVProtocol.h): `shared/RevoVProtocol.h`

### Other components

- **Order backend**
- **Operator**
- **Machine actuators**

## Connections

- Order backend → WebSocket client: sends orders (evidence: `README.md`)
- WebSocket client → ESP runtime: polls orders (evidence: `esp/src/main.cpp`)
- ESP runtime → Order state machine: updates control (evidence: `esp/src/main.cpp`)
- Order state machine → Order queue: enqueues orders (evidence: `esp/src/Core/StateMachine.cpp`)
- Order state machine → WebSocket client: publishes outcomes (evidence: `esp/src/Core/StateMachine.cpp`)
- Order state machine → Trajectory planner: plans commands (evidence: `esp/src/Core/StateMachine.cpp`)
- Order state machine → Slot inventory: updates slots (evidence: `esp/src/Core/StateMachine.cpp`)
- Order state machine → Command pin driver: dispatches commands (evidence: `esp/src/Core/StateMachine.cpp`)
- Order state machine → Trace event bus: publishes trace (evidence: `esp/src/Core/StateMachine.cpp`)
- ESP runtime → Trace event bus: initializes bus (evidence: `esp/src/main.cpp`)
- ESP runtime → Web console: initializes console (evidence: `esp/src/main.cpp`)
- Operator → Web console: uses console (evidence: `README.md`)
- Web console → Trace event bus: subscribes to trace (evidence: `README.md`)
- Command pin driver → Mega runtime: sends commands (evidence: `README.md`)
- Mega runtime → READY handler: waits for READY (evidence: `README.md`)
- READY handler → Order state machine: signals settled (evidence: `README.md`)
- Mega runtime → Pin command reader: initializes reader (evidence: `mega/src/main.cpp`)
- Mega runtime → Motion axes: initializes axes (evidence: `mega/src/main.cpp`)
- Mega runtime → Shelf conveyor: initializes conveyor (evidence: `mega/src/main.cpp`)
- Mega runtime → Dispense door: initializes door (evidence: `mega/src/main.cpp`)
- Mega runtime → Gripper assembly: initializes gripper (evidence: `mega/src/main.cpp`)
- Mega runtime → Command state machine: initializes control (evidence: `mega/src/main.cpp`)
- Mega runtime → Motion scheduler: updates scheduler (evidence: `mega/src/main.cpp`)
- Command state machine → Motion axes: dispatches motion
- Command state machine → Gripper assembly: dispatches handling
- Command state machine → Dispense door: controls door
- Command state machine → Shelf conveyor: advances shelf
- Command state machine → Homing routine: requests homing
- Motion scheduler → Stepper control: services motion
- Motion axes → Stepper control: uses axes
- Mega runtime → Machine actuators: drives (evidence: `README.md`)
- Wire protocol → Command pin driver: defines commands
- Wire protocol → Shelf conveyor: defines actions (evidence: `mega/src/Shelf/Conveyor.cpp`)
