# sefu202/pren-firmware architecture

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

- Interactive diagram: https://gitdiagram.com/sefu202/pren-firmware
- Repository: https://github.com/sefu202/pren-firmware

## Overview

PREN-Firmware is STM32 firmware for an object-placement machine, controlled over Ethernet by a Python client. The workflow is: client commands cross the TCP protocol boundary, update the process image, and drive axis or actuator state; the firmware loop samples safety inputs and hardware state, updates motion and outputs, and exposes status for client polling. The README documents additional motion, safety, and indicator capabilities. Some internal communication and peripheral links are based on the documented architecture and tree; unsampled wiring is omitted.

Main entry points: [`Core/Src/application.cpp`](https://github.com/sefu202/pren-firmware/blob/master/Core/Src/application.cpp) (Main Control Loop), [`Core/Src/LinearAxis/LinearAxis.cpp`](https://github.com/sefu202/pren-firmware/blob/master/Core/Src/LinearAxis/LinearAxis.cpp) (Linear Axes), [`Core/Src/ProcessImage/ProcessImage.cpp`](https://github.com/sefu202/pren-firmware/blob/master/Core/Src/ProcessImage/ProcessImage.cpp) (Process Image), [`Core/Src/Comm/ProtocolServer.cpp`](https://github.com/sefu202/pren-firmware/blob/master/Core/Src/Comm/ProtocolServer.cpp) (Protocol Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Runtime Control"]
  node_main["Firmware Entry<br/>[main.c]"]
  node_application["Main Control Loop<br/>[application.cpp]"]
  node_process_image["Process Image<br/>[ProcessImage.cpp]"]
end

subgraph group_communication["Network Interface"]
  node_client["Python Control Unit<br/>[ControlUnit.py]"]
  node_protocol_server["Protocol Server<br/>[ProtocolServer.cpp]"]
  node_protocol["Binary Protocol<br/>[Protocol.cpp]"]
  node_tcp["TCP Server<br/>[TcpServer.cpp]"]
end

subgraph group_motion["Motion System"]
  node_linear_axis["Linear Axes<br/>[LinearAxis.cpp]"]
  node_ramp["Motion Ramp<br/>[LinearAxisRamp.cpp]"]
  node_motion_timer["Motion Timer<br/>[MotionTimer.cpp]"]
  node_stepper["Stepper Drivers<br/>[Stepper.cpp]"]
end

subgraph group_hardware["Machine I/O"]
  node_input_filter["Input Debounce<br/>[Debounce.cpp]"]
  node_edge_position["Edge Detection<br/>[EdgePos.cpp]"]
  node_vacuum["Vacuum Actuator<br/>[Vacuum.cpp]"]
  node_confetti["Confetti Cannon<br/>[ConfettiCannon.cpp]"]
  node_led_flash["LED Indicators<br/>[LedFlash.cpp]"]
  node_soft_pwm["Software PWM<br/>[SoftPWM.cpp]"]
end

node_operator(("Machine Operator"))
node_machine["Machine Hardware"]

node_operator -->|"operates"| node_client
node_client -->|"sends commands"| node_tcp
node_tcp -->|"receives data"| node_protocol_server
node_protocol_server -->|"decodes messages"| node_protocol
node_protocol_server -->|"reads and writes"| node_process_image
node_process_image -->|"provides status"| node_protocol_server
node_main -->|"starts loop"| node_application
node_application -->|"updates server"| node_protocol_server
node_application -->|"updates state"| node_process_image
node_application -->|"filters inputs"| node_input_filter
node_application -->|"updates axes"| node_linear_axis
node_application -->|"updates vacuum"| node_vacuum
node_application -->|"updates cannon"| node_confetti
node_application -->|"updates indicators"| node_led_flash
node_process_image -->|"sets targets"| node_linear_axis
node_process_image -->|"sets rotation"| node_stepper
node_linear_axis -->|"queues steps"| node_stepper
node_linear_axis -->|"sets speed"| node_ramp
node_linear_axis -->|"requests timing"| node_motion_timer
node_linear_axis -->|"detects switch edges"| node_edge_position
node_application -->|"controls PWM"| node_soft_pwm
node_vacuum -->|"drives pump and valve"| node_machine
node_confetti -.->|"fires cannon"| node_machine
node_stepper -->|"drives motors"| node_machine
node_input_filter -->|"samples switches"| node_machine
node_led_flash -->|"drives LEDs"| node_machine
node_soft_pwm -->|"modulates outputs"| node_machine

click node_client "https://github.com/sefu202/pren-firmware/blob/master/Core/Src/Comm/ControlUnit.py"
click node_main "https://github.com/sefu202/pren-firmware/blob/master/Core/Src/main.c"
click node_application "https://github.com/sefu202/pren-firmware/blob/master/Core/Src/application.cpp"
click node_protocol_server "https://github.com/sefu202/pren-firmware/blob/master/Core/Src/Comm/ProtocolServer.cpp"
click node_protocol "https://github.com/sefu202/pren-firmware/blob/master/Core/Src/Comm/Protocol.cpp"
click node_tcp "https://github.com/sefu202/pren-firmware/blob/master/Core/Src/Comm/TcpServer.cpp"
click node_process_image "https://github.com/sefu202/pren-firmware/blob/master/Core/Src/ProcessImage/ProcessImage.cpp"
click node_linear_axis "https://github.com/sefu202/pren-firmware/blob/master/Core/Src/LinearAxis/LinearAxis.cpp"
click node_ramp "https://github.com/sefu202/pren-firmware/blob/master/Core/Src/LinearAxis/LinearAxisRamp.cpp"
click node_motion_timer "https://github.com/sefu202/pren-firmware/blob/master/Core/Src/LinearAxis/MotionTimer.cpp"
click node_stepper "https://github.com/sefu202/pren-firmware/blob/master/Core/Src/Stepper/Stepper.cpp"
click node_input_filter "https://github.com/sefu202/pren-firmware/blob/master/Core/Src/Util/Debounce.cpp"
click node_edge_position "https://github.com/sefu202/pren-firmware/blob/master/Core/Src/Util/EdgePos.cpp"
click node_vacuum "https://github.com/sefu202/pren-firmware/blob/master/Core/Src/Actuators/Vacuum.cpp"
click node_confetti "https://github.com/sefu202/pren-firmware/blob/master/Core/Src/Actuators/ConfettiCannon.cpp"
click node_led_flash "https://github.com/sefu202/pren-firmware/blob/master/Core/Src/Actuators/LedFlash.cpp"
click node_soft_pwm "https://github.com/sefu202/pren-firmware/blob/master/Core/Src/Util/SoftPWM.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_main,node_application,node_process_image toneBlue
class node_client,node_protocol_server,node_protocol,node_tcp toneAmber
class node_linear_axis,node_ramp,node_motion_timer,node_stepper toneMint
class node_input_filter,node_edge_position,node_vacuum,node_confetti,node_led_flash,node_soft_pwm toneRose
class node_operator,node_machine toneIndigo
```

## Components

### Runtime Control

- [Firmware Entry](https://github.com/sefu202/pren-firmware/blob/master/Core/Src/main.c): `Core/Src/main.c`
- [Main Control Loop](https://github.com/sefu202/pren-firmware/blob/master/Core/Src/application.cpp): `Core/Src/application.cpp`
- [Process Image](https://github.com/sefu202/pren-firmware/blob/master/Core/Src/ProcessImage/ProcessImage.cpp): `Core/Src/ProcessImage/ProcessImage.cpp`

### Network Interface

- [Python Control Unit](https://github.com/sefu202/pren-firmware/blob/master/Core/Src/Comm/ControlUnit.py): `Core/Src/Comm/ControlUnit.py`
- [Protocol Server](https://github.com/sefu202/pren-firmware/blob/master/Core/Src/Comm/ProtocolServer.cpp): `Core/Src/Comm/ProtocolServer.cpp`
- [Binary Protocol](https://github.com/sefu202/pren-firmware/blob/master/Core/Src/Comm/Protocol.cpp): `Core/Src/Comm/Protocol.cpp`
- [TCP Server](https://github.com/sefu202/pren-firmware/blob/master/Core/Src/Comm/TcpServer.cpp): `Core/Src/Comm/TcpServer.cpp`

### Motion System

- [Linear Axes](https://github.com/sefu202/pren-firmware/blob/master/Core/Src/LinearAxis/LinearAxis.cpp): `Core/Src/LinearAxis/LinearAxis.cpp`
- [Motion Ramp](https://github.com/sefu202/pren-firmware/blob/master/Core/Src/LinearAxis/LinearAxisRamp.cpp): `Core/Src/LinearAxis/LinearAxisRamp.cpp`
- [Motion Timer](https://github.com/sefu202/pren-firmware/blob/master/Core/Src/LinearAxis/MotionTimer.cpp): `Core/Src/LinearAxis/MotionTimer.cpp`
- [Stepper Drivers](https://github.com/sefu202/pren-firmware/blob/master/Core/Src/Stepper/Stepper.cpp): `Core/Src/Stepper/Stepper.cpp`

### Machine I/O

- [Input Debounce](https://github.com/sefu202/pren-firmware/blob/master/Core/Src/Util/Debounce.cpp): `Core/Src/Util/Debounce.cpp`
- [Edge Detection](https://github.com/sefu202/pren-firmware/blob/master/Core/Src/Util/EdgePos.cpp): `Core/Src/Util/EdgePos.cpp`
- [Vacuum Actuator](https://github.com/sefu202/pren-firmware/blob/master/Core/Src/Actuators/Vacuum.cpp): `Core/Src/Actuators/Vacuum.cpp`
- [Confetti Cannon](https://github.com/sefu202/pren-firmware/blob/master/Core/Src/Actuators/ConfettiCannon.cpp): `Core/Src/Actuators/ConfettiCannon.cpp`
- [LED Indicators](https://github.com/sefu202/pren-firmware/blob/master/Core/Src/Actuators/LedFlash.cpp): `Core/Src/Actuators/LedFlash.cpp`
- [Software PWM](https://github.com/sefu202/pren-firmware/blob/master/Core/Src/Util/SoftPWM.cpp): `Core/Src/Util/SoftPWM.cpp`

### Other components

- **Machine Operator**
- **Machine Hardware**

## Connections

- Machine Operator → Python Control Unit: operates
- Python Control Unit → TCP Server: sends commands
- TCP Server → Protocol Server: receives data
- Protocol Server → Binary Protocol: decodes messages
- Protocol Server → Process Image: reads and writes
- Process Image → Protocol Server: provides status
- Firmware Entry → Main Control Loop: starts loop
- Main Control Loop → Protocol Server: updates server
- Main Control Loop → Process Image: updates state
- Main Control Loop → Input Debounce: filters inputs
- Main Control Loop → Linear Axes: updates axes
- Main Control Loop → Vacuum Actuator: updates vacuum
- Main Control Loop → Confetti Cannon: updates cannon
- Main Control Loop → LED Indicators: updates indicators
- Process Image → Linear Axes: sets targets
- Process Image → Stepper Drivers: sets rotation
- Linear Axes → Stepper Drivers: queues steps
- Linear Axes → Motion Ramp: sets speed
- Linear Axes → Motion Timer: requests timing
- Linear Axes → Edge Detection: detects switch edges
- Main Control Loop → Software PWM: controls PWM
- Vacuum Actuator → Machine Hardware: drives pump and valve
- Confetti Cannon → Machine Hardware: fires cannon
- Stepper Drivers → Machine Hardware: drives motors
- Input Debounce → Machine Hardware: samples switches
- LED Indicators → Machine Hardware: drives LEDs
- Software PWM → Machine Hardware: modulates outputs