Welcome to my fork of the Klipper project, with home-able extruders, configurable extra ABC axes, and CNC-style probing!

This fork matches upstream Klipper features up to version 0.13.

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.
• Many 3D-printer features in klipper are not tested (e.g. bed meshing) and most kinematics are not adapted (e.g. polar, delta, ...).

Critical limitations: you should know this beforehand.

• Only the cartesian kinematic has been adapted, and core-xy may work too. Others could be adapted without much work, this is a good place for contributions.
• Acceleration is shared among all axes by default. Abrupt speed changes in the ABC axes will cause XYZ movements to slow down accordingly.
  • Note: This has been mitigated somewhat with accel_limited_axes.
  • Note: motion on the ABC axes will not affect maximum speed of the XYZ axes, which will match the desired feedrate (F parameter).
• Most of the modules in "extra" have not been tested and might not work as expected (e.g. the arcs module).
• Limitations stated further down this readme.

Roadmap:

• Klipper v0.13 has also started to modularize code to support additional axes without much hassle (through manual_stepper). Once that work is complete, I'll merge the rest of the CNC features found here to a clean master branch.
• Until then, I won't merge new commits from upstream, but will be active testing and pushing fixes.
• After moving to the new multi-axis setup, I'll continue to maintain this fork (without the huge overhead of merging multi-axis code).

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.

Simple demo on YouTube:

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 regular G28).
    • Multi-probe: MULTIPROBE2 PROBE_NAME=myprobe A=-20 B=10 F=2 (same as regular MULTIPROBE).
    • And so on ...
  • Configuration: add ABC kinematics to [printer] and the corresponding [stepper_abc] sections (details below).
    • You must use cartesian_abc instead of cartesian at your [printer] section.
    • Partial axis sets are implemented (i.e. XY-only for laser machines, XYZE+A for cutters, etc.).
  • 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).
  • 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, and force_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 activate extruder 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, and G38.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 and M82/ 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 the 2 in MULTIPROBE2 with 3, 4, or 5 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). If PROBENAME 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 of QUERY_PROBE).
  • Note: affected by G90/G91 and M82/ 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
• Implemented the M211 command, as defined in Marlin.
  • Execute M211 S0 to disable kinematic limit checks, which will let you crash and damage your machine if you're not careful.
  • Execute M211 S1 to enable kinematic limit checks, which will prevent you from crashing and damaging your machine.
• 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
• A new relative_e_restore configuration parameter for the [printer] section was added. It allows to skip the restoration of the 'relative extruder "E" position' during a RESTORE_GCODE_STATE command, wich normally offsets the GCODE base_position of the extruder (making subsequent absolute moves relative to the restored position).
  • By default, the effect of RESTORE_GCODE_STATE is equivalent to a G92 command with the saved position of the extruder.
  • This means that absolute moves will be interpreted relatively to the restored extruder coordinate.
  • For extruders this might make sense (at least in Klipper), but results in a problem with Mainsail, which saves and restores the GCODE state around manual move (e.g. after homing to 0 and a relative move to +3, an absolute move to 0 would do nothing against expectations).
  • Maybe this is related to interrupting GCODE programs that use absolute coordinates for extruders, without messing them up when they resume if the extruder was moved (e.g. for a filament change).
  • Set relative_e_restore: False under [printer] to disable this, or hack Mainsail's macros
• 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).

Other changes:

• Sending the GET_STATUS_MSG command will print the result of toolhead.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.

I've added some notes on running the tests from the tests directory. Have a look at the README there.

The tests are currently focused on the new features added by this fork.

Relevant configuration and test definition files are:

• k4cnc.cfg
• k4cnc.test
• atmega644p.dict

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!

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

1. SSH into the Pi.
2. Copy "klipper_repos.txt.example" to "klipper_repos.txt".
   • Use the command: cp kiauh/klipper_repos.txt.example kiauh/klipper_repos.txt
3. 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
4. Start KIAUH.
   • Use the command: ./kiauh/kiauh.sh
5. Choose option "6) [Settings]".
6. Choose option "1) Set custom Klipper repository".
7. Choose the option corresonding to "naikymen/klipper-for-cnc -> pipetting"
8. Use KIAUH to uninstall and reinstall Klipper.
9. Have fun!

Thanks to some changes in upstream moonraker, a properly configured repo can be updated from Mainsail just as the original Klipper.

See examples here:

• https://gitlab.com/pipettin-bot/pipettin-bot/-/tree/master/code/klipper-setup/configs

These are meant as soft reference configs; you must adjust them to match your setup before using them. Some of them may be outdated.

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 an xxx_abc kinematic. Only the cartesian_abc kinematic has been tested.
• kinematics_abc (new): The ABC set of axes must also use one of the xxx_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 contains X, there must be a [stepper_x] section).
  • Partial specification is allowed for the cartesian_abc kinematics (e.g. only XY and no Z, or XYZA for a four axis machine).
  • The E axis must not be specified here. This setting is for XYZ and ABC axes only. Extruders are configured just as in regular Klipper.
• accel_limited_axes (experimental): You can now define which axes draw acceleration from the shared pool (set by max_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 cause MCU '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: #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, replacing extruder 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, a HOME_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].
• This registers a probe object under the usual "probe" name. This means that it can be used by other components, such as bed mesh.

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 the MULTIPROBE set of commands.

Example command (equivalent to G38.2): MULTIPROBE2 PROBE_NAME=extruder1 Z=-20 F=1

To use a different G38 flavor, replace the 2 in MULTIPROBE2 with 3, 4, or 5 for the other probing modes.

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

Usage notes:

• [probe_G38] is incompatible with [probe_G38_multi extruder].
• This registers a probe object under the provided name, prefixed by "probe_". This means that it can not be used by other components, such as bed mesh.

For convenience, their status can show up next to the endstops in Mainsail:

https://www.klipper3d.org/

The Klipper firmware controls 3d-Printers. 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 the Klipper software.

Start by installing Klipper software.

Klipper software is Free Software. See the license or read the documentation. We depend on the generous support from our sponsors.