# kinkymakers/ossm-hardware architecture

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

- Interactive diagram: https://gitdiagram.com/kinkymakers/ossm-hardware
- Repository: https://github.com/kinkymakers/ossm-hardware

## Overview

#### 1. Repository Role and Entry Points
OSSM is an open-source hardware project for a servo-driven linear actuator, with production CAD/print assets, PCB references, and ESP32 firmware. The firmware application starts at `Software/src/main.cpp`, is built through PlatformIO/CMake (`Software/platformio.ini`, `Software/CMakeLists.txt`), and is the active control-plane implementation. Mechanical release sources center on `CAD Project/MAIN/OSSM.f3z` and the versioned release package under `CAD Project/MAIN/RELEASE_02.27.2025/`.

#### 2. Physical Product Definition
The canonical mechanical design is decomposed into actuator, mounting/base, motor ring, and stand assemblies. CAD sources retain editable Fusion files and STEP exports, while `Printed Parts/` is the fabrication-facing distribution boundary (STL/STEP/3MF).
- Actuator structure and end-effector: `CAD Project/MAIN/RELEASE_02.27.2025/OSSM/Actuator/`
- Base/motor mounting: `CAD Project/MAIN/RELEASE_02.27.2025/OSSM/Base/`, `CAD Project/MAIN/RELEASE_02.27.2025/OSSM/Motor Ring/`
- Printable release artifacts: `Printed Parts/Actuator/`, `Printed Parts/Mounting/`, `Printed Parts/Stand/`

#### 3. Firmware State and Safety Control
`OSSM` is the application coordinator; its state subsystem models operational sessions, motion, calibration, errors, settings, menus, BLE state, and guards. This is the primary safety/control boundary: user or network requests should become state actions and guarded transitions before reaching motor hardware.
- Coordinator/events: `Software/src/ossm/OSSM.cpp`, `Software/src/ossm/Events.h`
- State machine and action layer: `Software/src/ossm/state/machine.h`, `Software/src/ossm/state/actions.cpp`, `Software/src/ossm/state/guards.cpp`
- Pure/isolated control logic includes homing and guard logic: `Software/lib/OSSMLogic/src/homing_logic.h`, `Software/lib/OSSMLogic/src/guard_logic.h`

#### 4. Motion Execution Pipeline
Commands select an operating mode—simple penetration, pattern playback, or streaming—then produce motion parameters/points. The stroke-engine layer calculates pattern motion; the state/motion layer and hardware stepper service enact it on the belt-driven rail. Homing establishes the physical reference required before accurate operation.
- Stroke/pattern engine: `Software/lib/StrokeEngine/src/StrokeEngine.cpp`, `Software/src/ossm/stroke_engine/stroke_engine.cpp`
- Mode controllers: `Software/src/ossm/simple_penetration/simple_penetration.cpp`, `Software/src/ossm/pattern_controls/pattern_controls.cpp`, `Software/src/ossm/streaming/streaming.cpp`
- Hardware actuation and homing: `Software/src/services/stepper.cpp`, `Software/src/ossm/homing/homing.cpp`

#### 5. Interaction, Communications, and Device Services
The firmware supports local display/encoder/LED interaction plus BLE, Wi-Fi, MQTT, GPIO, and command-queue communication. These adapters are separated from OSSM state and motion logic; they translate external inputs into commands/events and surface device status outward. MQTT is the principal named external messaging service/protocol; BLE and Wi-Fi connect companion/control clients.
- Local peripherals: `Software/src/services/display.cpp`, `Software/src/services/encoder.cpp`, `Software/src/services/led.cpp`
- Network and wireless adapters: `Software/src/services/communication/nimble.cpp`, `Software/src/services/communication/mqtt.cpp`, `Software/src/services/wm.cpp`
- Command/queue boundary: `Software/src/command/commands.hpp`, `Software/src/services/communication/queue.cpp`

#### 6. UI, Persistence, and Firmware Delivery
The on-device UI is a dedicated library plus OSSM page/menu controllers, rendering operational, pairing, Wi-Fi, preflight, error, and update flows. Firmware update protocol/runtime support separates update transport from application behavior. The runtime is ESP32-oriented C++ with LittleFS support and staged SDK configurations. GitHub Actions builds/releases firmware and publishes immutable artifacts.
- UI/rendering: `Software/lib/ui/src/ui.cpp`, `Software/src/ossm/menu/menu.cpp`, `Software/src/ossm/pages/update.cpp`
- Update boundary: `Software/lib/FirmwareUpdateProtocol/src/FirmwareUpdateProtocol.h`, `Software/src/utils/update.cpp`
- Build/release infrastructure: `Software/sdkconfig.production`, `.github/workflows/publish_firmware.yml`, `.github/scripts/publish_immutable_firmware.py`

Main entry points: [`Software/src/main.cpp`](https://github.com/kinkymakers/ossm-hardware/blob/main/Software/src/main.cpp) (OSSM coordinator), [`Software/src/ossm/state/machine.h`](https://github.com/kinkymakers/ossm-hardware/blob/main/Software/src/ossm/state/machine.h) (State & safety actions), [`CAD Project/MAIN/OSSM.f3z`](https://github.com/kinkymakers/ossm-hardware/blob/main/CAD%20Project/MAIN/OSSM.f3z) (Master CAD), [`Software/src/ossm/homing/homing.cpp`](https://github.com/kinkymakers/ossm-hardware/blob/main/Software/src/ossm/homing/homing.cpp) (Homing service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mechanical["Physical Product"]
  node_cad_master["Master CAD<br/>Fusion design<br/>[OSSM.f3z]"]
  node_actuator_cad["Actuator assembly<br/>release CAD"]
  node_mounting_cad["Base &amp; motor mount<br/>release CAD"]
  node_motor_ring_cad["Motor ring<br/>release CAD"]
  node_printed_parts["Printable parts<br/>STL/STEP/3MF release"]
end

subgraph group_control["Firmware Control"]
  node_firmware_app{{"OSSM coordinator<br/>ESP32 application<br/>[main.cpp]"}}
  node_state_machine{{"State &amp; safety actions<br/>state machine<br/>[machine.h]"}}
  node_control_logic["Homing &amp; guard logic<br/>isolated control logic<br/>[homing_logic.h]"]
  node_mode_controllers["Motion modes<br/>mode controllers"]
  node_stroke_engine["Stroke engine<br/>motion planner<br/>[StrokeEngine.cpp]"]
  node_homing["Homing service<br/>reference routine<br/>[homing.cpp]"]
  node_stepper["Stepper service<br/>hardware actuator<br/>[stepper.cpp]"]
end

subgraph group_interfaces["Interfaces &amp; Services"]
  node_command_queue["Command queue<br/>command boundary<br/>[commands.hpp]"]
  node_local_io["Local controls<br/>display/encoder/LED<br/>[display.cpp]"]
  node_wireless["BLE, Wi-Fi &amp; MQTT<br/>network adapters<br/>[mqtt.cpp]"]
  node_device_ui["Device UI<br/>rendering and pages<br/>[ui.cpp]"]
  node_update_runtime["Firmware update<br/>update protocol"]
end

subgraph group_delivery["Build &amp; Release"]
  node_build_config["PlatformIO/CMake build<br/>firmware build<br/>[platformio.ini]"]
  node_publish_release["Immutable firmware publish<br/>GitHub Actions release"]
end

node_cad_master -->|"releases"| node_actuator_cad
node_cad_master -->|"releases"| node_mounting_cad
node_cad_master -->|"releases"| node_motor_ring_cad
node_actuator_cad -->|"exports fabrication assets"| node_printed_parts
node_mounting_cad -->|"exports fabrication assets"| node_printed_parts
node_firmware_app -->|"dispatches events"| node_state_machine
node_state_machine -->|"evaluates guards"| node_control_logic
node_state_machine -->|"authorizes modes"| node_mode_controllers
node_mode_controllers -->|"generates motion"| node_stroke_engine
node_stroke_engine -->|"outputs motion points"| node_stepper
node_state_machine -->|"starts calibration"| node_homing
node_homing -->|"uses homing logic"| node_control_logic
node_homing -->|"references rail"| node_stepper
node_local_io -->|"submits input"| node_command_queue
node_wireless -->|"submits remote commands"| node_command_queue
node_command_queue -->|"delivers commands"| node_firmware_app
node_firmware_app -->|"publishes state"| node_device_ui
node_firmware_app -->|"coordinates update"| node_update_runtime
node_build_config -->|"builds"| node_firmware_app
node_publish_release -->|"runs build"| node_build_config
node_publish_release -->|"publishes firmware"| node_update_runtime

click node_cad_master "https://github.com/kinkymakers/ossm-hardware/blob/main/CAD%20Project/MAIN/OSSM.f3z"
click node_firmware_app "https://github.com/kinkymakers/ossm-hardware/blob/main/Software/src/main.cpp"
click node_state_machine "https://github.com/kinkymakers/ossm-hardware/blob/main/Software/src/ossm/state/machine.h"
click node_control_logic "https://github.com/kinkymakers/ossm-hardware/blob/main/Software/lib/OSSMLogic/src/homing_logic.h"
click node_mode_controllers "https://github.com/kinkymakers/ossm-hardware/blob/main/Software/src/ossm/simple_penetration/simple_penetration.cpp"
click node_stroke_engine "https://github.com/kinkymakers/ossm-hardware/blob/main/Software/lib/StrokeEngine/src/StrokeEngine.cpp"
click node_homing "https://github.com/kinkymakers/ossm-hardware/blob/main/Software/src/ossm/homing/homing.cpp"
click node_stepper "https://github.com/kinkymakers/ossm-hardware/blob/main/Software/src/services/stepper.cpp"
click node_command_queue "https://github.com/kinkymakers/ossm-hardware/blob/main/Software/src/command/commands.hpp"
click node_local_io "https://github.com/kinkymakers/ossm-hardware/blob/main/Software/src/services/display.cpp"
click node_wireless "https://github.com/kinkymakers/ossm-hardware/blob/main/Software/src/services/communication/mqtt.cpp"
click node_device_ui "https://github.com/kinkymakers/ossm-hardware/blob/main/Software/lib/ui/src/ui.cpp"
click node_update_runtime "https://github.com/kinkymakers/ossm-hardware/blob/main/Software/lib/FirmwareUpdateProtocol/src/FirmwareUpdateProtocol.h"
click node_build_config "https://github.com/kinkymakers/ossm-hardware/blob/main/Software/platformio.ini"
click node_publish_release "https://github.com/kinkymakers/ossm-hardware/blob/main/.github/workflows/publish_firmware.yml"

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_cad_master,node_actuator_cad,node_mounting_cad,node_motor_ring_cad,node_printed_parts toneBlue
class node_firmware_app,node_state_machine,node_control_logic,node_mode_controllers,node_stroke_engine,node_homing,node_stepper toneAmber
class node_command_queue,node_local_io,node_wireless,node_device_ui,node_update_runtime toneMint
class node_build_config,node_publish_release toneRose
```

## Components

### Physical Product

Release CAD and fabrication assets.

- [Master CAD](https://github.com/kinkymakers/ossm-hardware/blob/main/CAD%20Project/MAIN/OSSM.f3z): Fusion design · Canonical editable mechanical assembly. · `CAD Project/MAIN/OSSM.f3z`
- **Actuator assembly**: release CAD
- **Base & motor mount**: release CAD
- **Motor ring**: release CAD
- **Printable parts**: STL/STEP/3MF release · Fabrication-facing actuator, mounting, and stand assets.

### Firmware Control

ESP32 application, safety state, and motion execution.

- [OSSM coordinator](https://github.com/kinkymakers/ossm-hardware/blob/main/Software/src/main.cpp): ESP32 application · Application entry point and event coordinator. · `Software/src/main.cpp`
- [State & safety actions](https://github.com/kinkymakers/ossm-hardware/blob/main/Software/src/ossm/state/machine.h): state machine · Guards operational transitions before hardware motion. · `Software/src/ossm/state/machine.h`
- [Homing & guard logic](https://github.com/kinkymakers/ossm-hardware/blob/main/Software/lib/OSSMLogic/src/homing_logic.h): isolated control logic · Pure reference and safety decision logic. · `Software/lib/OSSMLogic/src/homing_logic.h`
- [Motion modes](https://github.com/kinkymakers/ossm-hardware/blob/main/Software/src/ossm/simple_penetration/simple_penetration.cpp): mode controllers · Simple, pattern, and streaming commands. · `Software/src/ossm/simple_penetration/simple_penetration.cpp`
- [Stroke engine](https://github.com/kinkymakers/ossm-hardware/blob/main/Software/lib/StrokeEngine/src/StrokeEngine.cpp): motion planner · Calculates pattern motion parameters and points. · `Software/lib/StrokeEngine/src/StrokeEngine.cpp`
- [Homing service](https://github.com/kinkymakers/ossm-hardware/blob/main/Software/src/ossm/homing/homing.cpp): reference routine · Establishes the physical rail reference. · `Software/src/ossm/homing/homing.cpp`
- [Stepper service](https://github.com/kinkymakers/ossm-hardware/blob/main/Software/src/services/stepper.cpp): hardware actuator · Drives the belt-driven linear rail. · `Software/src/services/stepper.cpp`

### Interfaces & Services

Local, wireless, messaging, UI, and update boundaries.

- [Command queue](https://github.com/kinkymakers/ossm-hardware/blob/main/Software/src/command/commands.hpp): command boundary · Queues adapter commands as firmware actions. · `Software/src/command/commands.hpp`
- [Local controls](https://github.com/kinkymakers/ossm-hardware/blob/main/Software/src/services/display.cpp): display/encoder/LED · `Software/src/services/display.cpp`
- [BLE, Wi-Fi & MQTT](https://github.com/kinkymakers/ossm-hardware/blob/main/Software/src/services/communication/mqtt.cpp): network adapters · Connects companion clients and MQTT messaging. · `Software/src/services/communication/mqtt.cpp`
- [Device UI](https://github.com/kinkymakers/ossm-hardware/blob/main/Software/lib/ui/src/ui.cpp): rendering and pages · Menus and operational, error, and update flows. · `Software/lib/ui/src/ui.cpp`
- [Firmware update](https://github.com/kinkymakers/ossm-hardware/blob/main/Software/lib/FirmwareUpdateProtocol/src/FirmwareUpdateProtocol.h): update protocol · Separates update transport from application behavior. · `Software/lib/FirmwareUpdateProtocol/src/FirmwareUpdateProtocol.h`

### Build & Release

Firmware build and immutable publication pipeline.

- [PlatformIO/CMake build](https://github.com/kinkymakers/ossm-hardware/blob/main/Software/platformio.ini): firmware build · `Software/platformio.ini`
- [Immutable firmware publish](https://github.com/kinkymakers/ossm-hardware/blob/main/.github/workflows/publish_firmware.yml): GitHub Actions release · Builds and publishes firmware artifacts. · `.github/workflows/publish_firmware.yml`

## Connections

- Master CAD → Actuator assembly: releases
- Master CAD → Base & motor mount: releases
- Master CAD → Motor ring: releases
- Actuator assembly → Printable parts: exports fabrication assets
- Base & motor mount → Printable parts: exports fabrication assets
- OSSM coordinator → State & safety actions: dispatches events
- State & safety actions → Homing & guard logic: evaluates guards
- State & safety actions → Motion modes: authorizes modes
- Motion modes → Stroke engine: generates motion
- Stroke engine → Stepper service: outputs motion points
- State & safety actions → Homing service: starts calibration
- Homing service → Homing & guard logic: uses homing logic
- Homing service → Stepper service: references rail
- Local controls → Command queue: submits input
- BLE, Wi-Fi & MQTT → Command queue: submits remote commands
- Command queue → OSSM coordinator: delivers commands
- OSSM coordinator → Device UI: publishes state
- OSSM coordinator → Firmware update: coordinates update
- PlatformIO/CMake build → OSSM coordinator: builds
- Immutable firmware publish → PlatformIO/CMake build: runs build
- Immutable firmware publish → Firmware update: publishes firmware