kinkymakers/ossm-hardware

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