Folder Structure

The OSSM firmware follows a modular, feature-based architecture. Each feature lives in its own namespace folder, making the codebase easier to navigate and maintain.

Browse the source code on GitHub: Software/src/

Overview

main.cpp

platformio.ini

Folder	Purpose
`include/boost/`	Header-only libraries (Boost.SML state machine)
`lib/StrokeEngine/`	Motion pattern library (modified)
`src/`	Main source code
`test/`	Unit tests

Design Philosophy

The firmware uses a feature-based organization where related code lives together:

Namespaces over classes - Features are organized as namespace functions rather than class methods
Co-located files - Each feature's header, implementation, and related code live in the same folder
Global state structs - Shared state is managed through dedicated state structs rather than class members
Stateless modules - Feature functions operate on global state, making them easier to test and reason about

The OSSM class in ossm/OSSM.h is retained for backward compatibility with BLE command handling. New features should use stateless namespace functions.

Core Application (`src/ossm/`)

The ossm/ folder contains the core application logic, organized by feature.

Events.h

OSSM.h

OSSM.cpp

Folder	Purpose
`state/`	State machine architecture
`pages/`	UI screens
`homing/`	Homing sequence
`menu/`	Menu navigation
`simple_penetration/`	Simple Penetration mode
`stroke_engine/`	Stroke Engine mode
`pattern_controls/`	Pattern selection UI
`play_controls/`	Play/pause/speed controls

State Machine (`ossm/state/`)

The state machine components are separated for clarity and testability.

File	Purpose
`machine.h`	Transition table definition using Boost.SML
`actions.h` / `actions.cpp`	State transition actions (display updates, motor control)
`guards.h` / `guards.cpp`	Conditional checks for transitions
`state.h` / `state.cpp`	State machine initialization and global instance

State structs manage different aspects of the application:

File	Purpose
`session.h`	Current session (start time, stroke count, distance)
`settings.h`	User settings (speed, stroke, sensation, depth, pattern)
`calibration.h`	Homing state (sensor offset, stroke steps, homed status)
`motion.h`	Motion targets (position, velocity, time)
`menu.h`	Current menu selection
`ble.h`	Bluetooth connection state
`error.h`	Error messages

For details on how the state machine works, see State Machine Architecture.

UI Pages (`ossm/pages/`)

Each screen in the user interface has its own module.

Module	Description
`hello.h`	Boot splash screen with animated logos
`preflight.h`	"Reduce speed to start" safety check screen
`error.h`	Error display with help option
`update.h`	OTA update screens (checking, updating, no update)
`wifi.h`	WiFi configuration portal
`help.h`	Help and support information

Operating Modes

Each operating mode is a self-contained module with its motion control logic.

Module	Description
`simple_penetration/`	Basic back-and-forth motion at controlled speed
`stroke_engine/`	Complex patterns using the StrokeEngine library

Control UIs

Module	Description
`menu/`	Main menu navigation and rendering
`pattern_controls/`	Pattern selection interface for Stroke Engine mode
`play_controls/`	Speed, stroke, depth, and sensation controls

Feature Modules

Module	Description
`homing/`	Homing sequence (forward scan, backward scan, calibration)

Hardware Services (`src/services/`)

The services/ folder provides hardware abstraction layers.

stepper.h

stepper.cpp

display.h

display.cpp

encoder.h

encoder.cpp

led.h

led.cpp

board.h

board.cpp

tasks.h

tasks.cpp

wm.h

wm.cpp

nimble.h

nimble.cpp

queue.h

queue.cpp

command.hpp

state.hpp

patterns.hpp

gpio.hpp

wifi.hpp

config.hpp

File	Purpose
`stepper.h/.cpp`	Motor control (FastAccelStepper)
`display.h/.cpp`	OLED display (U8g2)
`encoder.h/.cpp`	Rotary encoder input
`led.h/.cpp`	RGB LED status indication
`board.h/.cpp`	Board initialization
`tasks.h/.cpp`	FreeRTOS task management
`wm.h/.cpp`	WiFi Manager
`communication/`	BLE and WiFi communication

For BLE protocol details, see BLE Communication.

Constants (`src/constants/`)

Configuration values and enums are centralized in the constants/ folder.

Config.h

Pins.h

Menu.h

Version.h

UserConfig.h

Images.h

LogTags.h

File	Purpose
`Config.h`	System configuration (speeds, limits, timeouts)
`Pins.h`	GPIO pin definitions
`Menu.h`	Menu option enum
`Version.h`	Firmware version information
`UserConfig.h`	User-configurable settings
`Images.h`	Display bitmap assets
`LogTags.h`	ESP-IDF logging tags
`copy/`	Localized strings

For configuration options, see Configuration.

Utilities (`src/utils/`)

Helper functions and classes used throughout the codebase.

StateLogger.h

RecursiveMutex.h

StrokeEngineHelper.h

format.h

analog.h

update.h

ble.h

File	Purpose
`StateLogger.h`	Logs state machine transitions for debugging
`RecursiveMutex.h`	Thread-safe mutex wrapper for ESP32
`StrokeEngineHelper.h`	StrokeEngine integration utilities
`format.h`	String formatting helpers
`analog.h`	Analog input averaging and processing
`update.h`	OTA update utilities
`ble.h`	BLE helper functions

Data Structures (`src/structs/`)

Shared data types used across modules.

SettingPercents.h

LanguageStruct.h

Points.h

File	Purpose
`SettingPercents.h`	User settings as percentages (0-100)
`LanguageStruct.h`	Language configuration
`Points.h`	Coordinate and point structures

Libraries

Boost.SML (`include/boost/sml.hpp`)

Boost.SML is a header-only state machine library. It's included directly in the project for version stability.

StrokeEngine (`lib/StrokeEngine/`)

A modified version of theelims/StrokeEngine that generates motion patterns. The library is vendored and customized for OSSM-specific requirements.

Build Configuration

The platformio.ini file defines build environments:

Environment	Purpose
`development`	Local development with debug logging
`staging`	Pre-release testing
`production`	Release builds with optimizations
`test`	Unit test configuration

Folder Structure

Folder Structure

Overview

Design Philosophy

Core Application (`src/ossm/`)

State Machine (`ossm/state/`)

UI Pages (`ossm/pages/`)

Operating Modes

Control UIs

Feature Modules

Hardware Services (`src/services/`)

Constants (`src/constants/`)

Utilities (`src/utils/`)

Data Structures (`src/structs/`)

Libraries

Boost.SML (`include/boost/sml.hpp`)

StrokeEngine (`lib/StrokeEngine/`)

Build Configuration

Further Reading

State Machine

Configuration

Display Service

BLE Communication

On this page