Welcome to my fork of the Klipper project, with home-able extruders, configurable extra ABC axes, and CNC-style probing!
Full changes and limitations stated further down this readme.
Use cases: as far as I can tell.
- More general CNC usage.
- Syringe extruders.
- Pipetting / liquid-handling robots / lab-automation.
Follow the discussion over at Klipper's forum: https://klipper.discourse.group/t/12249
What you can expect:
- Expect spending some time tinkering a bit and asking for help, it will then hopefully work just fine.
- The latest release should be functional, but you are still likely to find bugs lurking in my modifications. Ask for help or raise an issue if you find any.
- Many 3D-printer features in klipper are not tested (e.g. bed meshing) and most kinematics are not adapted (e.g. polar).
Critical limitations: you should know this beforehand.
- Only the cartesian kinematic has been adapted. Others could be without much work, this is a good place for contributions.
- Acceleration is shared among all axes. Abrupt speed changes in the ABC axes will cause XYZ movements to slow down accordingly.
- Note: motion on the ABC axes will not affect maximum speed of the XYZ axes, which will match the desired feedrate (
F
parameter).
- Note: motion on the ABC axes will not affect maximum speed of the XYZ axes, which will match the desired feedrate (
- Most of the modules in "extra" have not been tested and might not work.
- Limitations stated further down this readme.
Disclaimers:
- This is an EXPERIMENTAL fork. Consider asking around (e.g. reach out through the forum) before giving it a try.
- Always protect your machine (and youself) first.
Klipper is a 3d-Printer firmware. It combines the power of a general purpose computer with one or more micro-controllers. See the features document for more information on why you should use Klipper.
To begin using Klipper start by installing it.
Klipper is Free Software. See the license or read the documentation. We depend on the generous support from our sponsors.
Find the associated configuration examples at the following sections.
This fork implements:
- CNC on XYZABCE axes.
- Module: core modifications to toolhead, homing, and cartesian kinematics. New "abc" cartesian kinematics: cartesian_abc.py
- Commands:
- Move:
G1 X10 Y10 Z10 A10 B10 C10 E10
(same as a regular G1 command). - Home:
G28 A
(same as regularG28
). - Multi-probe:
MULTIPROBE2 PROBE_NAME=myprobe A=-20 B=10 F=2
(same as regularMULTIPROBE
). - And so on ...
- Move:
- Configuration: add ABC kinematics to
[printer]
and the corresponding[stepper_abc]
sections (details below).- You must use
cartesian_abc
instead ofcartesian
at your[printer]
section. - Partial axis sets are implemented (i.e.
XY
-only for laser machines,XYZE+A
for cutters, etc.).
- You must use
- Limitations:
- Needs testing on longer GCODE programs. Extra steppers not tested (i.e.
stepper_a1
). - XYZ axes seem to throttle during GCODE arcs (see notes below).
- Needs testing on longer GCODE programs. Extra steppers not tested (i.e.
- Notes:
- The feedrate is shared among all active axes, meaning that an XYA move at F200 will be "slower" in the XY plane than a XY-only move at the same feedrate.
- Module incompatibilites: probably many. Tested with
virtual_sdcard
,pause_resume
, andforce_move
. Non-cartesian kinematics are untested and will probably not work, help for porting them is welcome!
- Homing on the steppers of
[extruder]
s.- Module: extruder_home.py
- Command:
HOME_ACTIVE_EXTRUDER
. - Mux-command:
HOME_EXTRUDER EXTRUDER=extruder
(will activateextruder
and reactivate the previous extruder when done). - Configuration: add homing parameters to
[extruder]
and add[extruder_home extruder]
(details below). - Note: if "homing parameters" are added to an extruder's config, it will need to be homed (or unlocked with
SET_KINEMATIC_POSITION
) before it can be moved. - Limitations: It is untested on extruder steppers configured as
[extruder_stepper]
later synced to a particular[extruder]
. No "second home" is performed.
- Probing in arbitrary directions with
G38.2
,G38.3
,G38.4
, andG38.5
(single-probe version).- Module: probe_G38.py
- Command:
G38.2 X20 F10
- For reference, see LinuxCNC's definition of G38.n Straight Probe commands.
- Configuration: add a
[probe_G38]
section, specifying the probe pin (details below). - Note: affected by
G90
/G91
andM82
/M83
. - Module incompatibilites:
[probe_G38_multi ...]
- General probing with multiple probe pins is supported by an experimental module:
- Module: probe_G38_multi.py
- Command (multiprobe):
MULTIPROBE2 PROBE_NAME=extruder1 Z=-20 F=1
(replace the2
inMULTIPROBE2
with3
,4
, or5
for the other probing modes). - Command (monoprobe):
G38.2 X20 F10
(replace.2
by.3-.5
for the other probing modes). To choose the probe pin, this command will try to match the probe's config name to an extruder name, or fail. - Configuration: add a
[probe_G38_multi PROBENAME]
section, specifying the probe pin (details below). IfPROBENAME
matches an extruder's name (e.g.extruder
) the probe pin remains associated to it. The probe on the active extruder is used for "monoprobe" commands. - The probes can be queried with
QUERY_ENDSTOPS
(instead ofQUERY_PROBE
). - Note: affected by
G90
/G91
andM82
/M83
. - Known incompatibilites:
[probe_G38]
- The
SET_KINEMATIC_POSITION
command now works with extruder position as well.- Try this out:
SET_KINEMATIC_POSITION E=66.6
- Try this out:
- Absolute extruder moves are now absolute.
- You can now rely on absolute coordinate systems staying that way unless you update them explicitly (e.g. with
G92 E0
and similar commands). - The extruder's coordinate origin used to be altered without warning after every tool-change (i.e. extruder activation) in a way equivalent to sending
G92 E0
. This means that the extruder's origins were effectively relative to the last position of the extruder before a toolchange, which was enforced in Klipper to support the obscure expectations of old slicers. - See discussion at: https://klipper.discourse.group/t/6558
- You can now rely on absolute coordinate systems staying that way unless you update them explicitly (e.g. with
- The PID controller now uses sample averaging and linear regression to compute the P and D terms, respectively.
- This replaces the rather obscure pre-existing logic.
- This brings much improvement for noisy ADCs, such as the one in my Arduino UNO.
- The
samples
config parameter must be set to, at least,2
. I tested it with 5.
- G2/G3 arc moves are supported when using ABC axes.
- Arc move:
G2 X10 Y10 I10 J0 A10 F1000
- Note: The extra axis displacements (e.g
A
,B
,C
, etc.) are evenly split across the arc segments, just like the extruder and/or helical axes. The final feedrate is adjusted to a higher value if the move involves the extra axes. This is needed because Klipper would otherwise "distribute" the specified feedrate among axes later on according to their relative displacements. This is not expected from a "standard" GCODE Arc move, whose feedrate parameter refers exclusively to the speed of the XYZ axes. - Note: for lack of better ideas, the default feedrate for ensuing moves will be reset to the feedrate specified in the arc move, or to the feedrate that was set before the move. This is needed because feedrates are internally adjusted for arc moves involving extra axes (e.g. ABC axes).
- Limitations: only absolute arc moves are supported (same as upstream Klipper). While feedrate is scaled to compensate for the extra axes, acceleration is not, so you may observe additional "ramping" on the XYZ movement when the extra axes are involved (this is speculative so far).
- Arc move:
Other changes:
- Sending the
GET_STATUS_MSG
command will print the result oftoolhead.get_status
to Mainsail's console.
Not-so-minor modifications to Klippy's core were made to accommodate these features.
Pull requests are very welcome over here, and will be merged quickly.
Show your love for this project through Liberapay: https://liberapay.com/naikymen <3
Also consider donating to upstream Klipper and its appendages.
Let's chat over here: https://klipper.discourse.group/t/klipper-forks-for-cnc/5698
Cheers!
See examples here: https://gitlab.com/pipettin-bot/forks/firmware/klipper-stack/-/tree/pipetting/printer_data/config
These are meant as soft reference configs; you must adjust them to match your setup before using them.
Pin mappings for the Arduino CNC-Shield (v3.0) have been added to this repo: generic-cnc-shield-v3.0.cfg
Most of the configuration is "stock". Only the [printer]
section needs slightly different stuff:
kinematics
: You must use anxxx_abc
kinematic. Only thecartesian_abc
kinematic has been tested.kinematics_abc
(new): The ABC set of axes must also use one of thexxx_abc
kinematics.axis
(new): This string specifies exactly which axes need to be configured, by their common single-letter name in the CNC world.- There must be at least one stepper in the Klipper configuration for each of these letters (e.g. if
axis
containsX
, there must be a[stepper_x]
section). - Partial specification is allowed for the
cartesian_abc
kinematics (e.g. onlyXY
and noZ
, orXYZA
for a four axis machine). - The
E
axis must not be specified here. This setting is forXYZ
andABC
axes only. Extruders are configured just as in regular Klipper.
- There must be at least one stepper in the Klipper configuration for each of these letters (e.g. if
accel_limited_axes
(experimental): You can now define which axes draw acceleration from the shared pool (set bymax_accel
). Axes not included in this setting will behave (somewhat) like an extruder, scaling the total acceleration as needed.
[printer]
# Regular pritner configuration.
kinematics: cartesian_abc
# Units: mm/s and mm/s^2:
max_velocity: 5000 # F120000
max_z_velocity: 250 # F30000
max_accel: 1000
# Add ABC kinematics to the toolhead:
kinematics_abc: cartesian_abc
axis: XYZABC
# This tells the Moves which axes can "consume"
# acceleration from the above settings. It defaults
# to all axes. Any axes omitted from this setting
# will accelerate as fast as required (which might
# be impossible for your machine. BE WARNED).
# accel_limited_axes: XYZABC
Then configure the additional ABC steppers, exactly the ones specified in the axis
parameter. For example, the ABC steppers can be configured just as you would the XYZ:
[stepper_a]
# Regular stepper configuration.
# ...
[stepper_b]
# Regular stepper configuration.
# ...
[stepper_c]
# Regular stepper configuration.
# ...
Examples:
- Find here example configs. Look for folders with an A, B or C in their names.
What works:
- Movement seems to work :)
- Homing now works.
- Probing with G38 works.
- Limit checks work.
Important TODOs:
- Run tests! Only basic functionality has been covered.
- "Extra" steppers not tested (i.e.
stepper_a1
, etc.) SET_KINEMATIC_POSITION
would sometimes causeMCU 'tools' shutdown: Rescheduled timer in the past
. I find this error hard to reproduce. Maybe its my UNO's fault. Must track down the cause. See: naikymen#6- Consider if it would have been better/simpler to use multiple extruder axes instead of full "cartesian" axes. Adding axes one by one would have been simpler this way. For now, full stepper_a, stepper_b, and stepper_c config sections are mandatory.
This is meant to mitigate the effects of noisy ADCs in Arduinos, with great success. :)
The only new parameter is samples
which can be added to a heater_generic
section.
[heater_generic well_plate_heater]
# This is the new parameter.
# Set "samples" to an integer value "n". The last "n" measurements will be
# then used to compute the P term (by averaging) and the D term (by regression).
samples: 10
# The rest of the config is standard stuff.
# See: https://www.klipper3d.org/Config_Reference.html#heater_generic
# ...
Configure your extruders normally, and then add the required homing parameters. See notes below.
Any number of extruders can be configured to do homing. This requires:
- Adding homing parameters to an
[extruder]
section. - Adding a
[extruder_home extruder]
section per home-able extruder, replacingextruder
with the name of the corresponding extruder section.
[extruder]
# ...
# To enable homing on the extruder, setup all the
# usual extruder parameters above, and then add the
# usual homing parameters used by regular steppers:
# See: https://www.klipper3d.org/Config_Reference.html#stepper
position_endstop: 0.0
position_min: 0.0 # LIMITS ARE ENFORCED
position_max: 100.0 # LIMITS ARE ENFORCED
homing_speed: 25.0
homing_positive_dir: False # ADJUST TO MATCH YOUR SETUP
endstop_pin: gpio15 # REPLACE WITH THE PIN OF **YOUR** HOMING ENDSTOP
[extruder_home extruder]
# This section is required, but no parameters needed.
Usage notes:
- If "homing parameters" are added to an extruder's config, it will need to be homed (or unlocked with
SET_KINEMATIC_POSITION
) before it can be moved, even if the corresponding[extruder_home extruder]
is not set. - Note that the
[extruder]
must have an "endstop_pin" defined for it to be home-able. It is otherwise setup as a "regular" extruder, and a corresponding[extruder_home]
section will not work as exected. For instance, aHOME_EXTRUDER EXTRUDER=extruder
command fail with this error:'MCU_stepper' object has no attribute 'get_endstops'
A new configuration option was added to [extruder]
, called symmetric_speed_limits
.
Setting this parameter to True
will force speed and acceleration limits on all moves involving the extruder.
The limits are derived from max_extrude_only_velocity
and max_extrude_only_accel
as usual.
The difference is in that they will be applied to all moves (and not to "extrude only" moves).
[extruder]
# ...
# ...
# When 'True', this new parameter allows applying speed limits symmetrically
# to extruder moves, which will always be enforced. Then 'False' (the default)
# the limits remain conditional (e.g. to the direction) as it is done for
# regular 3D-printer extruders.
symmetric_speed_limits: True
# ...
Simple enough. For reference, read: https://www.klipper3d.org/Config_Reference.html#probe
[probe_G38]
# See: https://www.klipper3d.org/Config_Reference.html#probe
recovery_time: 0.4
pin: gpio19
z_offset: 0
Usage notes:
[probe_G38]
is incompatible with[probe_G38_multi extruder]
.
Note that this module also implements the regular G38.n
commands added by [probe_G38]
(hence the incompatibility), using the [probe_G38_multi]
section associated to the active extruder by name.
For example, this means that:
[probe_G38_multi extruder]
will be associated to the main[extruder]
.[probe_G38_multi]
sections with names that do not match an extruder will only be usable through theMULTIPROBE
set of commands.
Example configuration:
[probe_G38_multi extruder]
# This probe will be associated to the main [extruder] section.
recovery_time: 0.0
pin: ^tools:PC5
z_offset: 0
[probe_G38_multi my_probe]
# This probe will not be associated to an extruder (unless there is one named "my_probe").
recovery_time: 0.0
pin: ^tools:PB1
z_offset: 0
For convenience, their status can show up next to the endstops in Mainsail:
The easiest way is to use a KIAUH "klipper_repos.txt" file. Details at: https://github.com/th33xitus/kiauh/blob/master/klipper_repos.txt.example
- SSH into the Pi.
- Copy "klipper_repos.txt.example" to "klipper_repos.txt".
- Use the command:
cp kiauh/klipper_repos.txt.example kiauh/klipper_repos.txt
- Use the command:
- Edit the
kiauh/klipper_repos.txt
file to append "naikymen/klipper-for-cnc,pipetting
" after the last line.- Use the command:
echo "naikymen/klipper-for-cnc,pipetting" >> kiauh/klipper_repos.txt
- Use the command:
- Start KIAUH.
- Use the command:
./kiauh/kiauh.sh
- Use the command:
- Choose option "
6) [Settings]
". - Choose option "
1) Set custom Klipper repository
". - Choose the option corresonding to "
naikymen/klipper-for-cnc -> pipetting
" - Use KIAUH to uninstall and reinstall Klipper.
- Have fun!
Thanks to some changes in upstream moonraker, a properly configured repo can be updated from Mainsail just as the original Klipper.