Awesome

Overview

Printhor is a generic a hardware-agnostic firmware framework focused on FDM printers, CNC and Engravers implemented in Rust.

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.

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 and visualy explained in Printhor motion plan. A simplified overview of the velocity integration (GeoGebra).

    "[1] Biagiotti, L., Melchiorri, C.: Trajectory Planning for Automatic Machines and Robots. Springer, Heidelberg (2008). DOI:10.1007/978-3-540-85629-0"

  • High precision and deterministic kinematics and computations with configurable resolution. Briefly explained at Stepper Task.

  • Simple and efficient cornering algorithm based on pure linear algebra. Foundation implicitly explained at Printhor naïve cornering algorithm (GeoGebra).

• Precise thermal control plan with PID. Briefly exlained at Temperature Task.
• Simple, secure and efficient resource and peripherals sharing.
• Clean and simple async tasks coordination/intercommunication with event based primitives.
• Wide GCode standard coverage.
• Native simulation for development and benchmarking.
  • Many others coming.

Overall status

Assuming the following maturity convention: TODO -> Draft -> Incubation -> Testing -> Functional -> Done

Help wanted

If you are interested in this project and want to collaborate, you are welcome. A Discord server has been created for informal discussions. Otherwise, Github Issues and Pull Requests are preferred.

Checkout

git clone https://github.com/cbruiz/printhor
cd printhor
git checkout feature/motion_accuracy_and_state_5
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 (IntelliJ, CLion or RustRover) (recommended), Visual Studio Code (also fine), or others

Prerequisites: Rust and toolchain

This crate requires Rust >= 1.79.

For official guide, please see https://www.rust-lang.org/tools/install

However, if your os is unix based:

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:

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):

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 sdcard feature is enabled in native :)

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.

RUST_LOG=info cargo run --features integration-test --bin printhor

Testing with GCode sender though socat

RUST_LOG=info cargo build --bin printhor
socat pty,link=printhor,rawer EXEC:target/debug/printhor,pty,rawer

Supported boards and specific instructions

Extra utilery

A simple stand-alone std binary to experiment with motion plan and see what it does (kind of playground):

cd s-plot
cargo run

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.
• Unit test
• CoreXY support
• Display
• I/O control
  • xonxoff
• Adaptative planing cost measurement to take a decision on chaining or not and how much (AKA Cornering).
• exfat support could 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 : Two boards: V2 (See Datasheets/SKR_MINI_E3-V2.0) and V3 (See Datasheets/SKR_MINI_E3-V3.0)
  • printhor-hwi_mks_robin_nano_v3_1 : (See 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)

Intentionally, traits are in general avoided when not strictly required in favour of defining a more decoupled and easy to evolve interface based on:

• type aliases
• module exports

Diagram is Work in Progress

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

3DPrint Gcode sample

M73 P0 R87
M73 Q0 S87
M201 X1000 Y1000 Z200 E5000 ; sets maximum accelerations, mm/sec^2
M203 X200 Y200 Z12 E120 ; sets maximum feedrates, mm / sec
M204 P1250 R1250 T1500 ; sets acceleration (P, T) and retract acceleration (R), mm/sec^2
M205 X8.00 Y8.00 Z0.40 E4.50 ; sets the jerk limits, mm/sec
M205 S0 T0 ; sets the minimum extruding and travel feed rate, mm/sec
M107
;TYPE:Custom
M862.3 P "MK3" ; printer model check
M862.1 P0.4 ; nozzle diameter check
G90 ; use absolute coordinates
M83 ; extruder relative mode
M80 ; Power on
G28 W ; home all without mesh bed level
G80 ; mesh bed leveling
G28 X Y; Park
M104 S235 ; set extruder temp
M140 S60 ; set bed temp
M190 S60 ; wait for bed temp
M109 S235 ; wait for extruder temp

G1 Z0.2 F720
G1 Y-3 F1000 ; go outside print area
G92 E0
G1 X60 E9 F1000 ; intro line
G1 X100 E12.5 F1000 ; intro line

G92 E0
M221 S95

; Don't change E values below. Excessive value can damage the printer.
M907 E430 ; set extruder motor current
G21 ; set units to millimeters
G90 ; use absolute coordinates
M83 ; use relative distances for extrusion
; Filament-specific start gcode
M900 K0.2
M107
;LAYER_CHANGE
;Z:0.2
;HEIGHT:0.2
;BEFORE_LAYER_CHANGE
G92 E0.0
;0.2


G1 E-3.1 F3000
G1 Z.4 F720
;AFTER_LAYER_CHANGE
;0.2
G1 X76.782 Y74.538 F13200
G1 Z.2 F720
G1 E3.1 F3000
M204 P800
;TYPE:Skirt/Brim
;WIDTH:0.42
G1 F1200
G1 X77.609 Y73.879 E.03317
G1 X90.788 Y67.532 E.45862
G1 X91.819 Y67.297 E.03317

Laser Gcode sample

G21
G90
M206 X-45. Y-10. Z-20.; Laser offset
G28; Homing
G1 F3000. Z7.
M107;svg#svg5 > g#layer89324 > path#rect2575
G0 X12.6508 Y109.9950
M4 S255
G1 X112.6408 Y109.9950 F3000
G1 X112.6408 Y10.0050 F3000
G1 X12.6508 Y10.0050 F3000
G1 X12.6508 Y109.9950 F3000
M5
G4