If you are using this product or like the project, please ★ this repository to show your support! 🤩
# Overview Printhor is a generic and hardware-agnostic (firmware) framework for FDM printers, CNC, Engravers and robots implemented in Rust. Basically, it's a GCode interpreter capable to process a stream of GCodes (position and control orders), schedule them, compute a motion profile on the fly and finally perform the hardware level instructions (step pulses, PWM signals, ... or even dataframes broadcast for a dedicated break-board) in real time. There are many productive firmwares in the community like gbrl, marlin, reprap, etc. Each single one have a concrete approach and guidelines. This one aims to provide a research environment for not strictly productive purpose, but a reliable platform with the following goals: * Robustness. * Numerical stability. * Efficient resources utilization and close-to-preemptive multitasking. * Leverage async multitasking. * Maintain busy waits to a minimum. * Ensure leverage of DMA transfers as much as possible. * Ensure of leverage of FPU when present. * Simplicity. * Clarity and readability. Which means the principal short-term goal is not to develop a productive firmware for final user rather than providing an environment in which anyone can test and experiment any concrete approach to feed the community with good quality, state-of-the-art or innovative feature increments. ## Documentation (work in progress) [Documentation and guides](doc/README.md) ## Features * "Clean" hardware abstraction. * Vector geometry / linear algebra calculus for kinematics * Smooth acceleration and jerk limited motion plan leveraging "Trajectory with Double S Velocity Profile" [1]. Briefly explained at [Plan implementation](printhor/src/bin/motion/profile.rs) and visually explained in [Printhor motion plan. A simplified overview of the velocity integration](https://www.geogebra.org/m/hwpnmhcu) (GeoGebra). "[1] Biagiotti, L., Melchiorri, C.: Trajectory Planning for Automatic Machines and Robots. Springer, Heidelberg (2008). [DOI:10.1007/978-3-540-85629-0](https://doi.org/10.1007/978-3-540-85629-0)" * High precision and deterministic kinematics and computations with configurable resolution. Briefly explained at [Stepper Task](printhor/src/bin/tasks/task_stepper.rs). * Simple and efficient cornering algorithm based on pure linear algebra. Foundation implicitly explained at [Printhor naïve cornering algorithm](https://www.geogebra.org/m/ft8svrwd) (GeoGebra). * Precise thermal control plan with PID. Briefly explained at [Temperature Task](printhor/src/bin/tasks/task_temperature.rs). * Simple, secure and efficient resource and peripherals sharing. * Clean and simple async tasks coordination/intercommunication with event based primitives. * High behavior customization. * Low level action distribution leveraging dedicated break-boards. * Wide GCode standard coverage. * Native simulation for development and benchmarking. * Many others coming. ## Overall status| Feature | Status |
|---|---|
| Simulation | Functional |
| I/O | Functional |
| State and logic | Testing |
| Motion Planner | Functional |
| Kinematics | Testing |
| Thermal Control | Incubation |
| Display | TODO |
| Laser/CNC | Draft |
## Step by step
### Checkout
```shell
git clone https://github.com/cbruiz/printhor
cd printhor
git submodule update --init --recursive
```
### Build
The minimal toolset required to build and run is:
* Rust, in order to compile
* cargo binutils, to produce the image binary that you can flash via SD card as usual.
* __[Optionally]__ probe-run, if you are willing to use a SWD/Jlink debugger (https://github.com/knurling-rs/probe-run)
* __[Optionally]__ cargo-bloat and cargo-size utils are great to analyze the code size.
* __[Optionally]__ A Rust IDE, like [Jetbrains IDE suite](https://www.jetbrains.com/) (IntelliJ, CLion or RustRover) (recommended), Visual Studio Code (also fine), or others
### Prerequisites: Rust and toolchain
This crate requires **Rust >= 1.85**.
For official guide, please see https://www.rust-lang.org/tools/install
However, if your os is unix based:
```shell
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup update
```
For microcontrollers (currently few stm32 only), the specific target toolchain and cargo binutils is also needed:
```shell
rustup target add thumbv7em-none-eabi
rustup target add thumbv7em-none-eabihf
rustup target add thumbv6m-none-eabi
rustup component add llvm-tools
cargo install cargo-binutils
```
Optionally, for debugging on baremetal microcontrollers (currently few stm32 only):
```shell
cargo install probe-run
```
## Native simulator backend
The framework with a set of mocked peripherals (most of them without any logic).
Provides a commandline GCode prompt on standard input
__Note__: A SDCard image in ./data/ is required to be open if sd-card feature is enabled in native :)
```shell
RUST_LOG=info cargo run --bin printhor
```
### Integration tests
Native backend has a special feature called integration-test which is used to perform "some kind of" integration tests. Still
pending to be matured.
```shell
RUST_LOG=info cargo run --features integration-test --bin printhor
```
Testing with GCode sender though socat
```shell
RUST_LOG=info cargo build --bin printhor
socat pty,link=printhor,rawer EXEC:target/debug/printhor,pty,rawer
```
## Supported boards and specific instructions
| Board | Status |
|---------------------------------------------------------------------------------------------------|-------------------|
| [SKR Mini E3 V3.0](hwi-boards/printhor-hwi_skr_mini_e3/README.md) | Almost Functional |
| [MKS Robin Nano v3.1](hwi-boards/printhor-hwi_mks_robin_nano/README.md) | Almost Functional |
| [Nucleo-f410rb + Arduino CNC Hat v3](hwi-boards/printhor-hwi_nucleo_64_arduino_cnc_hat/README.md) | Almost Functional |
| [Nucleo-l476rg + Arduino CNC Hat v3](hwi-boards/printhor-hwi_nucleo_64_arduino_cnc_hat/README.md) | Almost Functional |
| [Raspberry PI 2040](hwi-boards/printhor-hwi_rp_2040/README.md) | Draft |
| [ESP32-S3-WROOM](hwi-boards/printhor-hwi_esp32/README.md) | Naïve Skeleton |
## Extra utilery
A simple stand-alone std binary to experiment with motion plan and see what it does (kind of playground):
```shell
cargo run --profile release --bin s_plot --features s-plot-bin
```
### Example output with the current plotting style approach:
As Image:
As Vector:
There are (currently) two plots:
* Position:
* A continuous blue curve for the analytic __ideal__ position estimation.
* A stepped gray curve for the __real__ (discrete) position.
* Velocity:
* A continuos green curve for the online derivation of __ideal__ position datapoints.
* A slopped gray polyline for the online derivation of __real__ (discrete) position datapoints in the sampling interval.
### Example output with the deprecated plotting style:
This plot were self-explanatory, but deprecated in flavor of the previous one.
We are keeping it because it is clear and useful for a high level understanding.
# TODO
* Code productivization. Mostly based on https://dl.acm.org/doi/pdf/10.1145/3519941.3535075 and https://jamesmunns.com/blog/fmt-unreasonably-expensive/:
* Code size reduction.
* Remove unwrap/panic calls.
* Remove unsafe code (a little bit, but there it is)
* Remove trivial/redundant computation __but not compromising readability__.
* Display
* I/O control
* xonxoff
* exFAT support would be great.
# Customization
For a single board, the high-level features (hotend, hotbed, fan, SDCard, ... ) can be activated/deactivated by cargo feature selection or directly editing the main cargo.toml
In order to change pins, writing/adapting some code is required, as of now. There is not expected to be, at least in the short term any kind of configuration file.
Because of that limitation (Rust makes that hard to tackle because of the strict typing), a clean code organization it's crucial and pretty straightforward to assume slight customizations by editing code.
# Architecture
printhor is composed by the following architectural blocks
* embassy-rs, as the harware and async foundation https://github.com/embassy-rs/embassy
* async-gcode, as the core of the GCode interpretation https://github.com/ithinuel/async-gcode
* printhor-hwa-common (within the project), as the hardware abstraction layer contract and common machinery
* A set of crates (withn the project) for each harware/board. Currently:
* printhor-hwi_native : The native simulator.
* printhor-hwi_skr_mini_e3 : A BigTreeTech SKR Mini E3 V3 (See [Datasheets/SKR_MINI_E3-V3.0](datasheets/SKR_MINI_E3-V3.0)).
* printhor-hwi_mks_robin_nano_v3_1 : (See [Datasheets/MKS-ROBIN-NANO-V3.1](datasheets/MKS-ROBIN-NANO-V3.1))
* printhor-hwi_nucleo_64_arduino_cnc_hat : A Nucleo-64 development board (currently L476RG or F410RB) with Arduino CNC Shield v3.x (See [Datasheets/NUCLEO-L476RG_CNC_SHIELD_V3](datasheets/NUCLEO-L476RG))
Intentionally, traits are in general avoided in HWI layer when not strictly required in favour of defining a more decoupled and easy to evolve interface based on:
* type aliases
* module exports
# Similar, related software and shout-outs
* https://embassy.dev/ Rust Embassy; The next-generation framework for embedded applications. The most important and core framework conforming the pillars of this project.
* https://github.com/ithinuel/async-gcode This powerful GCode implementation is a fundamental piece of this project.
* https://github.com/nviennot/turbo-resin Exactly the same a printhor but focused in resin printers. The Project which inspired and motivated this one.
* https://github.com/marcbone/s_curve A really appreciated know-how. The current selected motion profile is based on this work, but intense reinterpretation were performed to make this project work.The book referenced by the author of s-curve is a key reading considered to conduct the goals of the motion plan. Nevertheless, our implementation is still un-mature/unproven to ask for a merge.
# GCode compliancy [Draft]
Gcode implementation status, as from https://reprap.org/wiki/G-code
* WIP: Work In Progress
* ILT: In the Long Term
* TODO: To Do
| M-Code | Mode | Description | Status |
|---|---|---|---|
| M | * | List all supported m-codes | DONE |
| M0 | * | Stop or Unconditional stop | WIP |
| M1 | * | Sleep or Conditional stop | WIP |
| M2 | * | Program End | WIP |
| M3 | CNC | Spindle On, Clockwise | WIP |
| LASER | Laser On | WIP | |
| M4 | CNC | Spindle On, Counter-Clockwise | WIP |
| LASER | Laser On | WIP | |
| M5 | CNC | Spindle Off | WIP |
| LASER | Laser Off | WIP | |
| M6 | * | Tool change | ILT |
| M7 | CNC | Mist Coolant On | ILT |
| M8 | CNC | Flood Coolant On | ILT |
| M9 | CNC | Coolant Off | ILT |
| M10 | CNC | Vacuum On | ILT |
| M11 | CNC | Vacuum Off | ILT |
| M13 | CNC | Spindle on (clockwise rotation) and coolant on (flood) | ILT |
| M16 | CNC | Expected Printer Check | TODO |
| M17 | * | Enable/Power all stepper motors | WIP |
| M18 | * | Disable all stepper motors | WIP |
| M20 | * | List SD card | DONE* |
| M21 | * | Initialize SD card | TODO |
| M22 | * | Release SD card | TODO |
| M23 | * | Select SD file | DONE |
| M24 | * | Start/resume SD print | DONE |
| M25 | * | Pause SD print | DONE |
| M26 | * | Set SD position | ILT |
| M27 | * | Report SD print status | TODO |
| M30 | * | Program Stop | TODO |
| M31 | * | Output time since last M109 or SD card start to serial | TODO |
| M32 | * | Select file and start SD print | TODO |
| M33 | * | Get the long name for an SD card file or folder | ILT |
| M37 | * | Simulation mode (Dry run mode) | DONE |
| M73 | * | Set/Get build percentage | TODO |
| M79 | * | Soft reset | DONE |
| M80 | * | ATX Power On | WIP |
| M81 | * | ATX Power Off | WIP |
| M82 | * | Set extruder to absolute mode | WIP |
| M83 | * | Set extruder to relative mode | WIP |
| M92 | * | Set axis_steps_per_unit | WIP |
| M104 | FFF | Set Hotend Temperature | DONE |
| M105 | FFF | Get Hotend and/or Hotbed Temperature | DONE |
| M106 | * | Fan On | WIP |
| M107 | * | Fan Off | WIP |
| M109 | FFF | Set Extruder Temperature and Wait | DONE |
| M110 | * | Set Current Line Number | WIP |
| M111 | * | Set Debug Level | WIP |
| M112 | * | Full (Emergency) Stop | WIP |
| M114 | * | Get Current Position | DONE |
| M115 | * | Get Firmware Version and Capabilities | DONE |
| M116 | * | Wait | WIP |
| M117 | * | Display message | DONE |
| M118 | * | Echo message on host | DONE |
| M119 | * | Get Endstop Status | DONE |
| M120 | * | Enable endstop detection | ILT |
| M121 | * | Disable endstop detection | ILT |
| M140 | * | Set hotbed Temperature (Fast) | DONE |
| M190 | * | Wait for hotbed temperature | DONE |
| M200 | * | Set filament diameter | WIP |
| M201 | * | Set max acceleration | WIP |
| M202 | * | Set max travel acceleration | WIP |
| M203 | * | Set maximum feedrate | WIP |
| M204 | * | Set default acceleration | WIP |
| M205 | * | Advanced settings | WIP |
| M206 | * | Offset axes | WIP |
| M207 | * | Set retract length | WIP |
| M208 | * | Set unretract length | WIP |
| M209 | FFF | Enable automatic retract | WIP |
| M210 | * | Set homing feedrates | WIP |
| M211 | * | Disable/Enable software endstops | WIP |
| M212 | * | Set Bed Level Sensor Offset | WIP |
| M218 | * | Set Hotend Offset | WIP |
| M220 | * | Set speed factor override percentage | WIP |
| M221 | * | Set extrude factor override percentage | WIP |
| M290 | * | Babystepping | WIP |
| M302 | * | Allow cold extrudes | ILT |
| M305 | * | Set thermistor and ADC parameters | ILT |
| M350 | * | Set microstepping mode | WIP |
| M360 | * | Report firmware configuration | ILT |
| M400 | * | Wait for current moves to finish | TODO |
| M401 | * | Deploy Z Probe | WIP |
| M402 | * | Stow Z Probe | WIP |
| M404 | * | Filament width and nozzle diameter | WIP |
| M407 | * | Display filament diameter | WIP |
| M410 | * | Quick-Stop | TODO |
| M422 | * | Set a G34 Point | WIP |
| M450 | * | Report Printer Mode | WIP |
| M451 | * | Select FFF Printer Mode | WIP |
| M452 | * | Select Laser Printer Mode | WIP |
| M453 | * | Select CNC Printer Mode | WIP |
| M500 | * | Store parameters in non-volatile storage | TODO |
| M501 | * | Read parameters from EEPROM | TODO |
| M502 | * | Restore Default Settings | WIP |
| M503 | * | Report Current Settings | WIP |
| M504 | * | Validate EEPROM | TODO |
| M505 | * | Clear EEPROM and RESET Printer | TODO |
| M510 | * | Lock Machine | ILT |
| M511 | * | Unlock Machine with Passcode | ILT |
| M512 | * | Set Passcode | ILT |
| M513 | * | Remove Password | ILT |
| M524 | * | Abort SD Printing | WIP |
| M555 | * | Set compatibility | ILT |
| M563 | * | Define or remove a tool | ILT |
| M851 | * | Set Z-Probe Offset | WIP |
| M862.1 | * | Check nozzle diameter | ILT |
| M862.2 | * | Check model code | ILT |
| M862.3 | * | Model name | TODO |
| M929 | * | Start/stop event logging to SD card | ILT |
| G-Code | Mode | Description | Status |
|---|---|---|---|
| G | * | List all supported g-codes | DONE |
| G0 | * | Rapid Move | WIP |
| G1 | * | Linear Move | WIP |
| G4 | * | Dwell | DONE |
| G10 | * | Retract/Set coordinate system | ILT |
| G11 | * | Unretract | TODO |
| G17 | * | Plane Selection XY (default) | TODO |
| G18 | CNC | Plane Selection ZX | ILT |
| G19 | CNC | Plane Selection YZ | ILT |
| G21 | * | Set Units to Millimeters | TODO |
| G22 | * | Firmware Retract | ILT |
| G23 | * | Firmware Recover | ILT |
| G28 | * | Move to Origin (Home) | WIP |
| G29 | * | Detailed Z-Probe | TODO |
| G29.1 | * | Set Z probe head offset | WIP |
| G29.2 | * | Set Z probe head offset calculated from toolhead position | ILT |
| G30 | * | Single Z-Probe | TODO |
| G31 | * | Set or Report Current Probe status | TODO |
| G38.2 | * | Probe toward workpiece, stop on contact, signal error if failure | ILT |
| G38.3 | * | Probe toward workpiece, stop on contact | ILT |
| G38.4 | * | Probe away from workpiece, stop on loss of contact, signal error if failure | ILT |
| G38.5 | * | Probe away from workpiece, stop on loss of contact | ILT |
| G80 | * | Mesh-based Z probe | ILT |
| G81 | * | Mesh bed leveling status | ILT |
| G82 | * | Single Z probe at current location | TODO |
| G90 | * | Set to Absolute Positioning | DONE |
| G91 | * | Set to Relative Positioning | DONE |
| G92 | * | Set Position | DONE |
| G92.1 | * | Reset axis offsets (and parameters 5211-5219) to zero. (X Y Z A B C U V W) | ILT |
| G92.2 | * | Reset axis offsets to zero | ILT |
| G93 | CNC | Feed Rate Mode (Inverse Time Mode) | ILT |
| G94 | CNC | Feed Rate Mode (Units per Minute) | ILT |