Skip to main content
The OSSM firmware uses a set of configuration constants that define motion limits, hardware properties, and user preferences. This reference documents all configurable parameters and how to modify them for custom builds.
Modifying configuration values incorrectly can damage your hardware or cause unsafe operation. Only change values if you understand their effects and have verified your hardware specifications.

​
Motion system configuration

These parameters define how the OSSM moves and are found in src/constants/Config.h under the Config::Driver namespace.

​
Speed and acceleration

ParameterDefaultUnitDescription
maxSpeedMmPerSecond900.0mm/sMaximum linear speed of the actuator
maxAcceleration10000.0mm/s²Maximum acceleration/deceleration rate
These limits apply to all operating modes. The actual speed achieved depends on your motor, power supply, and mechanical setup.

​
Motor configuration

ParameterDefaultUnitDescription
motorStepPerRevolution800.0steps/revMotor steps per full revolution
pulleyToothCount20.0teethNumber of teeth on the drive pulley
beltPitchMm2.0mmDistance between belt teeth (GT2 standard)
These values combine to calculate stepsPerMM: 
stepsPerMM = motorStepPerRevolution / (pulleyToothCount * beltPitchMm)
// Default: 800 / (20 * 2) = 20 steps/mm
If you’re using different hardware (e.g., a 16-tooth pulley or GT3 belt), update these values to match. Incorrect values cause the firmware to miscalculate positions.

​
Stroke limits

ParameterDefaultUnitDescription
maxStrokeSteps500.0mmMaximum usable stroke length
minStrokeLengthMm50.0mmMinimum stroke to pass homing validation
maxStrokeSteps defines the absolute maximum travel. Set this to your rail length minus the linear block holder (75mm on standard OSSM) minus a 20mm safety margin.

​
Homing configuration

ParameterDefaultUnitDescription
sensorlessCurrentLimit1.5%Current threshold that indicates end-of-travel
The OSSM uses sensorless homing—it detects when the actuator hits the end of travel by monitoring motor current. When current exceeds this threshold, the firmware knows the actuator has reached a physical stop.

​
Advanced configuration

These parameters fine-tune firmware behavior and are found in Config::Advanced.
ParameterDefaultUnitDescription
strokeZeroOffsetMm6.0mmBuffer distance from physical home position
commandDeadZonePercentage1.0%Potentiometer dead zone to prevent noise
accelerationScaling100.0-Affects motion aggressiveness in Simple Penetration
After homing, the actuator backs off from the physical endstop by this distance. This prevents the actuator from repeatedly hitting the endstop during normal operation.
Analog potentiometers can produce noisy readings near zero. This dead zone ensures the speed knob registers as “zero” when turned fully counterclockwise, even if the electrical reading is slightly above 0%.
In Simple Penetration mode, acceleration is calculated as:
acceleration = maxSpeedMmPerSecond * speed * speed / accelerationScaling
Higher values produce gentler acceleration curves.

​
User configuration

User preferences are defined in src/constants/UserConfig.h.

​
Language

static LanguageStruct language = enUs;  // or 'fr' for French
Available languages:
  • enUs — English (US)
  • fr — French
Language selection currently requires recompiling the firmware. A runtime language selector is planned for future releases.

​
Display units

static bool displayMetric = true;
When true, distances display in meters. When false, distances display in feet.

​
Pin definitions

Hardware pins are defined in src/constants/Pins.h. Modify these if you’re building custom hardware.

​
Display pins

PinDefault GPIODescription
oledReset-1OLED reset pin (-1 if shared with board reset)
ledPin25RGB LED data pin (WS2812B)

​
Driver pins

PinDefault GPIODescription
motorStepPin14Stepper/servo STEP signal
motorDirectionPin27Stepper/servo DIR signal
motorEnablePin26Stepper/servo ENA signal
currentSensorPin36Analog current sensing input
stopPin19Emergency stop switch (optional)
limitSwitchPin12Limit switch input (optional)

​
Remote pins

PinDefault GPIODescription
speedPotPin34Speed potentiometer analog input
encoderSwitch35Encoder button input
encoderA18Encoder channel A
encoderB5Encoder channel B
displayData21I2C SDA for OLED
displayClock19I2C SCL for OLED

​
GPIO expansion pins

These pins are available for accessories via BLE GPIO control:
Logical PinGPIODescription
Pin 1GPIO 2General purpose output
Pin 2GPIO 15General purpose output
Pin 3GPIO 22General purpose output
Pin 4GPIO 33General purpose output

​
Modifying configuration

1

Clone the repository

If you haven’t already, clone the OSSM firmware repository:
git clone https://github.com/KinkyMakers/OSSM-hardware.git
cd OSSM-hardware/Software
2

Edit configuration files

Open the relevant configuration file in your editor:
  • src/constants/Config.h — Motion and advanced parameters
  • src/constants/UserConfig.h — User preferences
  • src/constants/Pins.h — Hardware pin assignments
3

Rebuild and upload

Use PlatformIO to compile and upload the modified firmware:
  1. Click the Build button to verify your changes compile
  2. Click Upload to flash the new firmware
After uploading, the OSSM will restart and use your new configuration.
Always test configuration changes carefully. Start with low speeds and verify homing completes successfully before normal operation.

PlatformIO Setup

Set up your development environment to modify and upload firmware.

Safety Features

Understand how configuration values affect safety systems.