An alternative firmware for OSSM written in rust.
- Why
- Supported hardware
- Installing firmware
- Status LED colors
- Safety and disclaimers
- Features
- Anatomy
- Contributing
- Shoulders of giants
While the original OSSM firmware does the job, rebuilding in Rust gives us a stronger foundation to grow from:
- Safety - Rust's type system and ownership model catch entire classes of bugs at compile time. For a project like this, that matters.
- Modularity - The codebase is split into small, focused crates (core library, motor drivers, board support, features) that can be developed and tested independently.
- Testability - Trait-based abstractions mean the motion controller, patterns, and drivers can all be tested without real hardware.
- Portability - The core library is
no_stdand platform-agnostic. It can target ESP32, other microcontrollers, or even compile to WebAssembly for simulation and tooling in the browser. - Telemetry - Using RS485 for motor communication lets us read back real-time data like position, current draw, voltage, and temperature. This telemetry opens the door to smarter safety checks — detecting stalls, overcurrent, or overheating before they become a problem.
Together, these make the project easier to understand, safer to modify, and more welcoming to contributions from everyone - whether you're writing a new pattern, adding a motor driver, or building a web-based remote.
Boards:
-
OSSM-ALT-Edition by @jollydodo.
A cheap, compact, powerful s3 board with built in 28v USB-PD.
-
OSSM Reference Board (ESP32, step/dir) The original OSSM PCB with step/dir motor control and current-sensing homing.
-
Industrial ESP32-S3-RS485-CAN by WaveShare
-
Seeed Studio's Xiao ESP32-S3
You'll need:
- XIAO ESP32-S3 MCU
- RS384 Breakout board for the XIAO ESP32-S3
- A power supply for the motor
Motors:
- 57AIM series motor (RS485/Modbus or step/dir)
For now, firmware must be built and flashed manually from source. See Set up your environment for instructions.
For the v1 release, pre-built binaries will be published on each tagged release. Longer term, a web flasher is planned so you can flash directly from your browser without any toolchain setup.
On boards with a configured RGB status LED, such as the OSSM Alt Edition, the LED shows a steady color:
| Color | Meaning |
|---|---|
| Dim white | Booting — initial indication while the machine is starting up. |
| Blue | Idle — stopped and waiting for a command. |
| Purple | Homing |
| Orange | Stopping — decelerating the machine. |
| Green | Ready, moving, or playing a pattern. |
| Yellow | Paused |
| Red | An error has stopped the machine. Restart it to try again. |
| Blinking red (green on WaveShare) | A known problem has stopped the machine. Count the blinks, then restart it. |
Blinking red (green on WaveShare) LED repeats a group of blinks separated by a longer pause:
| Blinks | Meaning |
|---|---|
| 1 | The motor did not respond during startup. Check motor power and wiring, then restart. |
| 2 | The motor was configured for this firmware. Power cycle the motor and the board. |
| 3 | The board could not set up its hardware. Check that the firmware matches the board, then restart. |
On boards with a single-color user LED, such as the Seeed XIAO ESP32S3, the LED stays off during normal operation. It blinks the same codes, and stays on steadily after an error.
While every precaution has been taken to make this software as safe as possible, the authors and contributors accept no responsibility or liability for any damage, injury, or harm that may result from the use or misuse of this software. This software is provided "as is", without warranty of any kind, express or implied. Use at your own risk.
- Smooth, jerk-limited motion profiles for safe predictable operation
- Hardware homing with automatic position reset
- Configurable motion limits (velocity, acceleration, jerk) per machine
- Position clamping to prevent over-travel beyond mechanical bounds
- Pattern engine with live user input (depth, stroke, velocity, sensation)
- 6 built-in patterns: Simple, Deeper, Half'n'Half, Stop'n'Go, Teasing Pounding, and Torque
- Extensible - add custom patterns, motors, or boards by implementing a trait
- Real-time motion control on a high-priority interrupt executor with fixed time-step updates
- Jerk-limited trajectory planning powered by Ruckig (S-curve acceleration profiles)
- Simple fractional API - positions and velocities expressed as 0.0-1.0, decoupled from machine geometry
- Motion state machine with safe transitions (Disabled → Enabled → Ready → Moving)
- Trait-based hardware abstraction for motors and boards
- Optional motor telemetry (position, speed, current, voltage, temperature)
- Fully async, lock-free architecture built on Embassy channels and signals
- no_std compatible - runs on bare-metal embedded targets like ESP32 and ESP32-S3
The project is split into several layers, each with a clear responsibility. Here's how they fit together from the top down:
┌──────────────────────────────────────────┐
│ Firmware │
│ (Assembles everything for a target) │
├───────────────────┬──────────────────────┤
│ Patterns │ Controller │
│ (Feature) │ (Feature) │
├───────────────────┴──────────────────────┤
│ Ossm │
│ (Public Control) │
├──────────────────────────────────────────┤
│ Motion Controller │
│ (Trajectory planning + state) │
├────────────────────┬─────────────────────┤
│ Board │ Motor Driver │
│ (Pin/peripheral │ (Hardware comms, │
│ setup) │ e.g. Modbus) │
└────────────────────┴─────────────────────┘
Ossm is the public-facing API that features and application code interact with. On its own it doesn't do anything - it simply exposes methods like enable(), disable(), home(), pause(), resume(), begin_motion(), update_motion(), and await_motion() that forward commands over a lock-free channel to the motion controller. It's up to features (like the pattern engine or a controller) to call these methods and drive the machine.
The motion controller is the real-time engine that runs on a high-priority interrupt executor. It receives commands from the Ossm channel, manages a state machine (Disabled → Enabled → Ready → Moving), and uses Ruckig for jerk-limited trajectory planning. Each update cycle it converts the planned trajectory into motor step commands. It also handles mechanical configuration (pulley teeth, belt pitch, travel limits) and motion limits (max velocity, acceleration, jerk).
A board crate handles the hardware-specific setup for a particular PCB - initialising UART peripherals, configuring GPIO pins, and providing any wrappers needed by the hardware (such as an RS485 half-duplex driver that toggles a direction-enable pin). The board produces a configured motor instance ready for use by the motion controller.
The Motor trait defines a hardware-agnostic interface that the motion controller programs against: enable, disable, home, set_absolute_position, set_speed, etc. Concrete driver crates (e.g. the M57AIM driver) implement this trait using the appropriate protocol - in the case of the 57AIM series, Modbus RTU over UART. Adding support for a new motor means writing a new implementation of the Motor trait.
A firmware crate is the final integration point that ties a specific board and motor together into a flashable binary. It initialises the board, creates the Ossm and MotionController pair, spawns the motion task on a real-time executor, runs the homing sequence, and then hands control to a pattern or application loop. Each supported hardware combination gets its own firmware crate.
Features are optional higher-level capabilities built on top of the core motion control. The pattern engine is the primary feature today - it defines a Pattern trait whose implementations describe repeating motion sequences (simple stroking, stop-and-go, teasing/pounding, etc.). Patterns read live user input (depth, stroke, velocity, sensation) and translate it into motion commands via the Ossm API. New patterns can be added by implementing the Pattern trait. Future features may include user remotes, mobile apps, or video game integrations - all built on top of the same public control layer.
-
Install Rust via rustup:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
-
Install the ESP Rust toolchain (espup):
cargo install espup espup install
This adds the
xtensatarget and the+esptoolchain needed to compile for ESP32 and ESP32-S3. -
Install just (a command runner used for build recipes):
cargo install just
Optionally, enable shell completions for
justso you can tab-complete recipe names:# zsh (add to ~/.zshrc) eval "$(just --completions zsh)" # bash (add to ~/.bashrc) eval "$(just --completions bash)" # fish (add to ~/.config/fish/config.fish) just --completions fish | source
-
Install espflash (for flashing firmware to the board):
cargo install espflash
-
You should now be able to build and flash. The variant is the first argument; supported variants are
ossm-alt(ESP32-S3, RS485),waveshare(ESP32-S3-RS485-CAN),seeed-xiao(XIAO ESP32-S3), andossm-reference(ESP32, step/dir).just build ossm-alt # build only just flash ossm-alt # build + flash + monitor just flash seeed-xiao sim # flash a build with the simulated motor
This project targets multiple architectures (ESP32-S3, ESP32, WASM), each with its own Rust target triple and toolchain settings. Since rust-analyzer can only analyze one target at a time, it needs to be told which one to use - otherwise it defaults to your host platform and will report false errors for embedded or WASM code.
The just focus command updates the VS Code and Zed rust-analyzer settings to select a firmware workspace and its features:
just focus esp32s3
just focus esp32The ESP32-S3 focus enables the RS485 motor and WS2812B status-indicator modules used by the default OSSM Alt build.
After running this, you may need to restart rust-analyzer (or reload your editor) to pick up the new settings. You only need to re-run it when switching to a different target.
The command regenerates editor settings from their templates. Put persistent customizations in the templates.
For pattern and web simulator work there's a dev container with everything the simulator needs. See So You Want to Add a Pattern. It doesn't include the ESP toolchain, so build and flash firmware on the host.
This work would not be possible without the open source community, we thank you. Specifically help from the following made this project possible.
- @orange_gem - Created the original ossm-rs that this project is based on, proving that a Rust implementation of the OSSM firmware was viable.
- @jollydodo - Designed the OSSM Alt Edition board that made Rust-based OSSM firmware possible in the first place.
- The R&D team - For pioneering the idea of an open source project like this.