klipper Documentation

Technical Documentation: Klipper3d/klipper

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

Welcome to the Klipper project!

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.

Overview (`docs/README.md`) Copy Section

Welcome to the Klipper documentation. The
overview document is a good starting point.

Code Overview (`docs/Code_Overview.md`) Copy Section

Code overview

This document describes the overall code layout and major code flow of
Klipper.

Directory Layout Copy Chapter

The src/ directory contains the C source for the micro-controller
code. The src/atsam/, src/atsamd/, src/avr/,
src/linux/, src/lpc176x/, src/pru/, and src/stm32/
directories contain architecture specific micro-controller code. The
src/simulator/ contains code stubs that allow the micro-controller
to be test compiled on other architectures. The src/generic/
directory contains helper code that may be useful across different
architectures. The build arranges for includes of "board/somefile.h"
to first look in the current architecture directory (eg,
src/avr/somefile.h) and then in the generic directory (eg,
src/generic/somefile.h).

The klippy/ directory contains the host software. Most of the host
software is written in Python, however the klippy/chelper/
directory contains some C code helpers. The klippy/kinematics/
directory contains the robot kinematics code. The klippy/extras/
directory contains the host code extensible "modules".

The lib/ directory contains external 3rd-party library code that
is necessary to build some targets.

The config/ directory contains example printer configuration
files.

The scripts/ directory contains build-time scripts useful for
compiling the micro-controller code.

The test/ directory contains automated test cases.

During compilation, the build may create an out/ directory. This
contains temporary build time objects. The final micro-controller
object that is built is out/klipper.elf.hex on AVR and
out/klipper.bin on ARM.

Micro-controller code flow Copy Chapter

Execution of the micro-controller code starts in architecture specific
code (eg, src/avr/main.c) which ultimately calls sched_main()
located in src/sched.c. The sched_main() code starts by running
all functions that have been tagged with the DECL_INIT() macro. It
then goes on to repeatedly run all functions tagged with the
DECL_TASK() macro.

One of the main task functions is command_dispatch() located in
src/command.c. This function is called from the board specific
input/output code (eg, src/avr/serial.c,
src/generic/serial_irq.c) and it runs the command functions
associated with the commands found in the input stream. Command
functions are declared using the DECL_COMMAND() macro (see the
protocol document for more information).

Task, init, and command functions always run with interrupts enabled
(however, they can temporarily disable interrupts if needed). These
functions should avoid long pauses, delays, or do work that lasts a
significant time. (Long delays in these "task" functions result in
scheduling jitter for other "tasks" - delays over 100us may become
noticeable, delays over 500us may result in command retransmissions,
delays over 100ms may result in watchdog reboots.) These functions
schedule work at specific times by scheduling timers.

Timer functions are scheduled by calling sched_add_timer() (located in
src/sched.c). The scheduler code will arrange for the given
function to be called at the requested clock time. Timer interrupts
are initially handled in an architecture specific interrupt handler
(eg, src/avr/timer.c) which calls sched_timer_dispatch() located
in src/sched.c. The timer interrupt leads to execution of schedule
timer functions. Timer functions always run with interrupts disabled.
The timer functions should always complete within a few micro-seconds.
At completion of the timer event, the function may choose to
reschedule itself.

In the event an error is detected the code can invoke shutdown() (a
macro which calls sched_shutdown() located in src/sched.c).
Invoking shutdown() causes all functions tagged with the
DECL_SHUTDOWN() macro to be run. Shutdown functions always run with
interrupts disabled.

Much of the functionality of the micro-controller involves working
with General-Purpose Input/Output pins (GPIO). In order to abstract
the low-level architecture specific code from the high-level task
code, all GPIO events are implemented in architecture specific
wrappers (eg, src/avr/gpio.c). The code is compiled with gcc's
"-flto -fwhole-program" optimization which does an excellent job of
inlining functions across compilation units, so most of these tiny
gpio functions are inlined into their callers, and there is no
run-time cost to using them.

Klippy code overview Copy Chapter

The host code (Klippy) is intended to run on a low-cost computer (such
as a Raspberry Pi) paired with the micro-controller. The code is
primarily written in Python, however it does use CFFI to implement
some functionality in C code.

Initial execution starts in klippy/klippy.py. This reads the
command-line arguments, opens the printer config file, instantiates
the main printer objects, and starts the serial connection. The main
execution of G-code commands is in the _process_commands() method in
klippy/gcode.py. This code translates the G-code commands into
printer object calls, which frequently translate the actions to
commands to be executed on the micro-controller (as declared via the
DECL_COMMAND macro in the micro-controller code).

There are several threads in the Klipper host code:

• There is a Python "main thread" that handles incoming G-Code
  commands and is the starting point for most actions. This thread
  runs the reactor
  (klippy/reactor.py) and most high-level actions originate from
  IO and timer event callbacks from that reactor.
• A thread for writing messages to the log so that the other threads
  do not block on log writes. This thread resides in the
  klippy/queuelogger.py code and its multi-threaded nature is not
  exposed to the main Python thread.
• A thread per micro-controller that performs the low-level reading
  and writing of messages to that micro-controller. It resides in the
  klippy/chelper/serialqueue.c C code and its multi-threaded
  nature is not exposed to the Python code.
• A thread per micro-controller for processing messages received from
  that micro-controller in the Python code. This thread is created in
  klippy/serialhdl.py. Care must be taken in Python callbacks
  invoked from this thread as this thread may directly interact with
  the main Python thread.
• A thread per stepper motor that calculates the timing of stepper
  motor step pulses and compresses those times. This thread resides in
  the klippy/chelper/steppersync.c C code and its multi-threaded
  nature is not exposed to the Python code.

Code flow of a move command Copy Chapter

A typical printer movement starts when a "G1" command is sent to the
Klippy host and it completes when the corresponding step pulses are
produced on the micro-controller. This section outlines the code flow
of a typical move command. The kinematics document
provides further information on the mechanics of moves.

• Processing for a move command starts in gcode.py. The goal of
  gcode.py is to translate G-code into internal calls. A G1 command
  will invoke cmd_G1() in klippy/extras/gcode_move.py. The
  gcode_move.py code handles changes in origin (eg, G92), changes in
  relative vs absolute positions (eg, G90), and unit changes (eg,
  F6000=100mm/s). The code path for a move is: _process_data() -> _process_commands() -> cmd_G1(). Ultimately the ToolHead class is
  invoked to execute the actual request: cmd_G1() -> ToolHead.move()

• The ToolHead class (in toolhead.py) handles "look-ahead" and tracks
  the timing of printing actions. The main codepath for a move is:
  ToolHead.move() -> LookAheadQueue.add_move(), then
  ToolHead.move() -> ToolHead._process_lookahead() -> LookAheadQueue.flush() -> Move.set_junction(), and then
  ToolHead._process_lookahead() -> trapq_append().

  • ToolHead.move() creates a Move() object with the parameters of the
    move (in cartesian space and in units of seconds and millimeters).
  • The kinematics class is given the opportunity to audit each move
    (ToolHead.move() -> kin.check_move()). The kinematics classes are
    located in the klippy/kinematics/ directory. The check_move() code
    may raise an error if the move is not valid. If check_move()
    completes successfully then the underlying kinematics must be able
    to handle the move.
  • LookAheadQueue.add_move() places the move object on the
    "look-ahead" queue.
  • LookAheadQueue.flush() determines the start and end velocities of
    each move.
  • Move.set_junction() implements the "trapezoid generator" on a
    move. The "trapezoid generator" breaks every move into three parts:
    a constant acceleration phase, followed by a constant velocity
    phase, followed by a constant deceleration phase. Every move
    contains these three phases in this order, but some phases may be of
    zero duration.
  • When ToolHead._process_lookahead() resumes, everything about the
    move is known - its start location, its end location, its
    acceleration, its start/cruising/end velocity, and distance traveled
    during acceleration/cruising/deceleration. All the information is
    stored in the Move() class and is in cartesian space in units of
    millimeters and seconds.
  • The moves are then placed on a "trapezoid motion queue" via
    trapq_append() (in klippy/chelper/trapq.c). The trapq stores all the
    information in the Move() class in a C struct accessible to the host
    C code.

• Note that the extruder is handled in its own kinematic class:
  ToolHead._process_lookahead() -> PrinterExtruder.process_move().
  Since the Move() class specifies the exact movement time and since
  step pulses are sent to the micro-controller with specific timing,
  stepper movements produced by the extruder class will be in sync
  with head movement even though the code is kept separate.

• For efficiency reasons, stepper motion is generated in the C code in
  a thread per stepper motor. The threads are notified when steps
  should be generated by the motion_queuing module
  (klippy/extras/motion_queuing.py):
  PrinterMotionQueuing._flush_handler() -> PrinterMotionQueuing._advance_move_time() -> steppersyncmgr_gen_steps() -> se_start_gen_steps().

• Klipper uses an
  iterative solver
  to generate the step times for each stepper. The step times are
  generated from the background thread (klippy/chelper/steppersync.c):
  se_background_thread() -> se_generate_steps() -> itersolve_generate_steps() -> itersolve_gen_steps_range() (in
  klippy/chelper/itersolve.c). The goal of the iterative solver is to
  find step times given a function that calculates a stepper position
  from a time. This is done by repeatedly "guessing" various times
  until the stepper position formula returns the desired position of
  the next step on the stepper. The feedback produced from each guess
  is used to improve future guesses so that the process rapidly
  converges to the desired time. The kinematic stepper position
  formulas are located in the klippy/chelper/ directory (eg,
  kin_cart.c, kin_corexy.c, kin_delta.c, kin_extruder.c).

• After the iterative solver calculates the step times they are added
  to an array: itersolve_gen_steps_range() -> stepcompress_append()
  (in klippy/chelper/stepcompress.c). The array (struct
  stepcompress.queue) stores the corresponding micro-controller clock
  counter times for every step. Here the "micro-controller clock
  counter" value directly corresponds to the micro-controller's
  hardware counter - it is relative to when the micro-controller was
  last powered up.

• The next major step is to compress the steps: stepcompress_flush() -> compress_bisect_add() (in klippy/chelper/stepcompress.c). This
  code generates and encodes a series of micro-controller "queue_step"
  commands that correspond to the list of stepper step times built in
  the previous stage. These "queue_step" commands are then queued,
  prioritized, and sent to the micro-controller (via
  steppersync.c:steppersync and serialqueue.c:serialqueue).

• Processing of the queue_step commands on the micro-controller starts
  in src/command.c which parses the command and calls
  command_queue_step(). The command_queue_step() code (in
  src/stepper.c) just appends the parameters of each queue_step
  command to a per stepper queue. Under normal operation the
  queue_step command is parsed and queued at least 100ms before the
  time of its first step. Finally, the generation of stepper events is
  done in stepper_event(). It's called from the hardware timer
  interrupt at the scheduled time of the first step. The
  stepper_event() code generates a step pulse and then reschedules
  itself to run at the time of the next step pulse for the given
  queue_step parameters. The parameters for each queue_step command
  are "interval", "count", and "add". At a high-level, stepper_event()
  runs the following, 'count' times: do_step(); next_wake_time = last_wake_time + interval; interval += add;

The above may seem like a lot of complexity to execute a movement.
However, the only really interesting parts are in the ToolHead and
kinematic classes. It's this part of the code which specifies the
movements and their timings. The remaining parts of the processing is
mostly just communication and plumbing.

Adding a host module Copy Chapter

The Klippy host code has a dynamic module loading capability. If a
config section named "[my_module]" is found in the printer config file
then the software will automatically attempt to load the python module
klippy/extras/my_module.py . This module system is the preferred
method for adding new functionality to Klipper.

The easiest way to add a new module is to use an existing module as a
reference - see klippy/extras/servo.py as an example.

The following may also be useful:

• Execution of the module starts in the module level load_config()
  function (for config sections of the form [my_module]) or in
  load_config_prefix() (for config sections of the form
  [my_module my_name]). This function is passed a "config" object and
  it must return a new "printer object" associated with the given
  config section.
• During the process of instantiating a new printer object, the config
  object can be used to read parameters from the given config
  section. This is done using config.get(), config.getfloat(),
  config.getint(), etc. methods. Be sure to read all values from the
  config during the construction of the printer object - if the user
  specifies a config parameter that is not read during this phase then
  it will be assumed it is a typo in the config and an error will be
  raised.
• Use the config.get_printer() method to obtain a reference to the
  main "printer" class. This "printer" class stores references to all
  the "printer objects" that have been instantiated. Use the
  printer.lookup_object() method to find references to other printer
  objects. Almost all functionality (even core kinematic modules) are
  encapsulated in one of these printer objects. Note, though, that
  when a new module is instantiated, not all other printer objects
  will have been instantiated. The "gcode" and "pins" modules will
  always be available, but for other modules it is a good idea to
  defer the lookup.
• Register event handlers using the printer.register_event_handler()
  method if the code needs to be called during "events" raised by
  other printer objects. Each event name is a string, and by
  convention it is the name of the main source module that raises the
  event along with a short name for the action that is occurring (eg,
  "klippy:connect"). The parameters passed to each event handler are
  specific to the given event (as are exception handling and execution
  context). Two common startup events are:
  • klippy:connect - This event is generated after all printer objects
    are instantiated. It is commonly used to lookup other printer
    objects, to verify config settings, and to perform an initial
    "handshake" with printer hardware.
  • klippy:ready - This event is generated after all connect handlers
    have completed successfully. It indicates the printer is
    transitioning to a state ready to handle normal operations. Do not
    raise an error in this callback.
• If there is an error in the user's config, be sure to raise it
  during the load_config() or "connect event" phases. Use either
  raise config.error("my error") or raise printer.config_error("my error") to report the error.
• Do not store a reference to the config object in a class member
  variable (nor in any similar location that may persist past initial
  module loading). The config object is a reference to a "config
  loading phase" class and it is not valid to invoke its methods after
  the "config loading phase" has completed.
• Use the "pins" module to configure a pin on a micro-controller. This
  is typically done with something similar to
  printer.lookup_object("pins").setup_pin("pwm", config.get("my_pin")). The returned object can then be commanded at
  run-time.
• If the printer object defines a get_status() method then the
  module can export status information via
  macros and via the
  API Server. The get_status() method must return a
  Python dictionary with keys that are strings and values that are
  integers, floats, strings, lists, dictionaries, True, False, or
  None. Tuples (and named tuples) may also be used (these appear as
  lists when accessed via the API Server). Lists and dictionaries that
  are exported must be treated as "immutable" - if their contents
  change then a new object must be returned from get_status(),
  otherwise the API Server will not detect those changes.
• If the module needs access to system timing or external file
  descriptors then use printer.get_reactor() to obtain access to the
  global "event reactor" class. This reactor class allows one to
  schedule timers, wait for input on file descriptors, and to "sleep"
  the host code.
• Do not use global variables. All state should be stored in the
  printer object returned from the load_config() function. This is
  important as otherwise the RESTART command may not perform as
  expected. Also, for similar reasons, if any external files (or
  sockets) are opened then be sure to register a "klippy:disconnect"
  event handler and close them from that callback.
• Avoid accessing the internal member variables (or calling methods
  that start with an underscore) of other printer objects. Observing
  this convention makes it easier to manage future changes.
• It is recommended to assign a value to all member variables in the
  Python constructor of Python classes. (And therefore avoid utilizing
  Python's ability to dynamically create new member variables.)
• If a Python variable is to store a floating point value then it is
  recommended to always assign and manipulate that variable with
  floating point constants (and never use integer constants). For
  example, prefer self.speed = 1. over self.speed = 1, and prefer
  self.speed = 2. * x over self.speed = 2 * x. Consistent use of
  floating point values can avoid hard to debug quirks in Python type
  conversions.
• If submitting the module for inclusion in the main Klipper code, be
  sure to place a copyright notice at the top of the module. See the
  existing modules for the preferred format.

Adding new kinematics Copy Chapter

This section provides some tips on adding support to Klipper for
additional types of printer kinematics. This type of activity requires
excellent understanding of the math formulas for the target
kinematics. It also requires software development skills - though one
should only need to update the host software.

Useful steps:

1. Start by studying the
   "code flow of a move" section and
   the Kinematics document.
2. Review the existing kinematic classes in the klippy/kinematics/
   directory. The kinematic classes are tasked with converting a move
   in cartesian coordinates to the movement on each stepper. One
   should be able to copy one of these files as a starting point.
3. Implement the C stepper kinematic position functions for each
   stepper if they are not already available (see kin_cart.c,
   kin_corexy.c, and kin_delta.c in klippy/chelper/). The function
   should call move_get_coord() to convert a given move time (in
   seconds) to a cartesian coordinate (in millimeters), and then
   calculate the desired stepper position (in millimeters) from that
   cartesian coordinate.
4. Implement the calc_position() method in the new kinematics class.
   This method calculates the position of the toolhead in cartesian
   coordinates from the position of each stepper. It does not need to
   be efficient as it is typically only called during homing and
   probing operations.
5. Other methods. Implement the check_move(), get_status(),
   get_steppers(), home(), clear_homing_state(), and set_position()
   methods. These functions are typically used to provide kinematic
   specific checks. However, at the start of development one can use
   boiler-plate code here.
6. Implement test cases. Create a g-code file with a series of moves
   that can test important cases for the given kinematics. Follow the
   debugging documentation to convert this g-code file
   to micro-controller commands. This is useful to exercise corner
   cases and to check for regressions.

Porting to a new micro-controller Copy Chapter

This section provides some tips on porting Klipper's micro-controller
code to a new architecture. This type of activity requires good
knowledge of embedded development and hands-on access to the target
micro-controller.

Useful steps:

1. Start by identifying any 3rd party libraries that will be used
   during the port. Common examples include "CMSIS" wrappers and
   manufacturer "HAL" libraries. All 3rd party code needs to be GNU
   GPLv3 compatible. The 3rd party code should be committed to the
   Klipper lib/ directory. Update the lib/README file with information
   on where and when the library was obtained. It is preferable to
   copy the code into the Klipper repository unchanged, but if any
   changes are required then those changes should be listed explicitly
   in the lib/README file.
2. Create a new architecture sub-directory in the src/ directory and
   add initial Kconfig and Makefile support. Use the existing
   architectures as a guide. The src/simulator provides a basic
   example of a minimum starting point.
3. The first main coding task is to bring up communication support to
   the target board. This is the most difficult step in a new port.
   Once basic communication is working, the remaining steps tend to be
   much easier. It is typical to use a UART type serial device during
   initial development as these types of hardware devices are
   generally easier to enable and control. During this phase, make
   liberal use of helper code from the src/generic/ directory (check
   how src/simulator/Makefile includes the generic C code into the
   build). It is also necessary to define timer_read_time() (which
   returns the current system clock) in this phase, but it is not
   necessary to fully support timer irq handling.
4. Get familiar with the the console.py tool (as described in the
   debugging document) and verify connectivity to the
   micro-controller with it. This tool translates the low-level
   micro-controller communication protocol to a human readable form.
5. Add support for timer dispatch from hardware interrupts. See
   Klipper
   commit 970831ee
   as an example of steps 1-5 done for the LPC176x architecture.
6. Bring up basic GPIO input and output support. See Klipper
   commit c78b9076
   as an example of this.
7. Bring up additional peripherals - for example see Klipper commit
   65613aed,
   c812a40a,
   and
   c381d03a.
8. Create a sample Klipper config file in the config/ directory. Test
   the micro-controller with the main klippy.py program.
9. Consider adding build test cases in the test/ directory.

Additional coding tips:

1. Avoid using "C bitfields" to access IO registers; prefer direct
   read and write operations of 32bit, 16bit, or 8bit integers. The C
   language specifications don't clearly specify how the compiler must
   implement C bitfields (eg, endianness, and bit layout), and it's
   difficult to determine what IO operations will occur on a C
   bitfield read or write.
2. Prefer writing explicit values to IO registers instead of using
   read-modify-write operations. That is, if updating a field in an IO
   register where the other fields have known values, then it is
   preferable to explicitly write the full contents of the register.
   Explicit writes produce code that is smaller, faster, and easier to
   debug.

Coordinate Systems Copy Chapter

Internally, Klipper primarily tracks the position of the toolhead in
cartesian coordinates that are relative to the coordinate system
specified in the config file. That is, most of the Klipper code will
never experience a change in coordinate systems. If the user makes a
request to change the origin (eg, a G92 command) then that effect is
obtained by translating future commands to the primary coordinate
system.

However, in some cases it is useful to obtain the toolhead position in
some other coordinate system and Klipper has several tools to
facilitate that. This can be seen by running the GET_POSITION
command. For example:

Send: GET_POSITION
Recv: // mcu: stepper_a:-2060 stepper_b:-1169 stepper_c:-1613
Recv: // stepper: stepper_a:457.254159 stepper_b:466.085669 stepper_c:465.382132
Recv: // kinematic: X:8.339144 Y:-3.131558 Z:233.347121
Recv: // toolhead: X:8.338078 Y:-3.123175 Z:233.347878 E:0.000000
Recv: // gcode: X:8.338078 Y:-3.123175 Z:233.347878 E:0.000000
Recv: // gcode base: X:0.000000 Y:0.000000 Z:0.000000 E:0.000000
Recv: // gcode homing: X:0.000000 Y:0.000000 Z:0.000000

The "mcu" position (stepper.get_mcu_position() in the code) is the
total number of steps the micro-controller has issued in a positive
direction minus the number of steps issued in a negative direction
since the micro-controller was last reset. If the robot is in motion
when the query is issued then the reported value includes moves
buffered on the micro-controller, but does not include moves on the
look-ahead queue.

The "stepper" position (stepper.get_commanded_position()) is the
position of the given stepper as tracked by the kinematics code. This
generally corresponds to the position (in mm) of the carriage along
its rail, relative to the position_endstop specified in the config
file. (Some kinematics track stepper positions in radians instead of
millimeters.) If the robot is in motion when the query is issued then
the reported value includes moves buffered on the micro-controller,
but does not include moves on the look-ahead queue. One may use the
toolhead.flush_step_generation() or toolhead.wait_moves() calls to
fully flush the look-ahead and step generation code.

The "kinematic" position (kin.calc_position()) is the cartesian
position of the toolhead as derived from "stepper" positions and is
relative to the coordinate system specified in the config file. This
may differ from the requested cartesian position due to the
granularity of the stepper motors. If the robot is in motion when the
"stepper" positions are taken then the reported value includes moves
buffered on the micro-controller, but does not include moves on the
look-ahead queue. One may use the toolhead.flush_step_generation()
or toolhead.wait_moves() calls to fully flush the look-ahead and
step generation code.

The "toolhead" position (toolhead.get_position()) is the last
requested position of the toolhead in cartesian coordinates relative
to the coordinate system specified in the config file. If the robot is
in motion when the query is issued then the reported value includes
all requested moves (even those in buffers waiting to be issued to the
stepper motor drivers).

The "gcode" position is the last requested position from a G1 (or
G0) command in cartesian coordinates relative to the coordinate
system specified in the config file. This may differ from the
"toolhead" position if a g-code transformation (eg, bed_mesh,
bed_tilt, skew_correction) is in effect. This may differ from the
actual coordinates specified in the last G1 command if the g-code
origin has been changed (eg, G92, SET_GCODE_OFFSET, M221). The
M114 command (gcode_move.get_status()['gcode_position']) will
report the last g-code position relative to the current g-code
coordinate system.

The "gcode base" is the location of the g-code origin in cartesian
coordinates relative to the coordinate system specified in the config
file. Commands such as G92, SET_GCODE_OFFSET, and M221 alter
this value.

The "gcode homing" is the location to use for the g-code origin (in
cartesian coordinates relative to the coordinate system specified in
the config file) after a G28 home command. The SET_GCODE_OFFSET
command can alter this value.

Time Copy Chapter

Fundamental to the operation of Klipper is the handling of clocks,
times, and timestamps. Klipper executes actions on the printer by
scheduling events to occur in the near future. For example, to turn on
a fan, the code might schedule a change to a GPIO pin in a 100ms. It
is rare for the code to attempt to take an instantaneous action. Thus,
the handling of time within Klipper is critical to correct operation.

There are three types of times tracked internally in the Klipper host
software:

• System time. The system time uses the system's monotonic clock - it
  is a floating point number stored as seconds and it is (generally)
  relative to when the host computer was last started. System times
  have limited use in the software - they are primarily used when
  interacting with the operating system. Within the host code, system
  times are frequently stored in variables named eventtime or
  curtime.
• Print time. The print time is synchronized to the main
  micro-controller clock (the micro-controller defined in the "[mcu]"
  config section). It is a floating point number stored as seconds and
  is relative to when the main mcu was last restarted. It is possible
  to convert from a "print time" to the main micro-controller's
  hardware clock by multiplying the print time by the mcu's statically
  configured frequency rate. The high-level host code uses print times
  to calculate almost all physical actions (eg, head movement, heater
  changes, etc.). Within the host code, print times are generally
  stored in variables named print_time or move_time.
• MCU clock. This is the hardware clock counter on each
  micro-controller. It is stored as an integer and its update rate is
  relative to the frequency of the given micro-controller. The host
  software translates its internal times to clocks before transmission
  to the mcu. The mcu code only ever tracks time in clock
  ticks. Within the host code, clock values are tracked as 64bit
  integers, while the mcu code uses 32bit integers. Within the host
  code, clocks are generally stored in variables with names containing
  clock or ticks.

Conversion between the different time formats is primarily implemented
in the klippy/clocksync.py code.

Some things to be aware of when reviewing the code:

• 32bit and 64bit clocks: To reduce bandwidth and to improve
  micro-controller efficiency, clocks on the micro-controller are
  tracked as 32bit integers. When comparing two clocks in the mcu
  code, the timer_is_before() function must always be used to ensure
  integer rollovers are handled properly. The host software converts
  32bit clocks to 64bit clocks by appending the high-order bits from
  the last mcu timestamp it has received - no message from the mcu is
  ever more than 2^31 clock ticks in the future or past so this
  conversion is never ambiguous. The host converts from 64bit clocks
  to 32bit clocks by simply truncating the high-order bits. To ensure
  there is no ambiguity in this conversion, the
  klippy/chelper/serialqueue.c code will buffer messages until
  they are within 2^31 clock ticks of their target time.
• Multiple micro-controllers: The host software supports using
  multiple micro-controllers on a single printer. In this case, the
  "MCU clock" of each micro-controller is tracked separately. The
  clocksync.py code handles clock drift between micro-controllers by
  modifying the way it converts from "print time" to "MCU clock". On
  secondary mcus, the mcu frequency that is used in this conversion is
  regularly updated to account for measured drift.

Overview (`docs/Overview.md`) Copy Section

Overview

Welcome to the Klipper documentation. If new to Klipper, start with
the features and installation
documents.

Overview information Copy Chapter

• Features: A high-level list of features in Klipper.
• FAQ: Frequently asked questions.
• Releases: The history of Klipper releases.
• Config changes: Recent software changes that
  may require users to update their printer config file.
• Contact: Information on bug reporting and general
  communication with the Klipper developers.

Installation and Configuration Copy Chapter

• Installation: Guide to installing Klipper.
  • Octoprint: Guide to installing Octoprint with Klipper.
• Config Reference: Description of config
  parameters.
  • Rotation Distance: Calculating the
    rotation_distance stepper parameter.
• Config checks: Verify basic pin settings in the
  config file.
• Bed level: Information on "bed leveling" in Klipper.
  • Delta calibrate: Calibration of delta
    kinematics.
  • Probe calibrate: Calibration of automatic Z
    probes.
  • BL-Touch: Configure a "BL-Touch" Z probe.
  • Manual level: Calibration of Z endstops (and
    similar).
  • Bed Mesh: Bed height correction based on XY
    locations.
  • Endstop phase: Stepper assisted Z endstop
    positioning.
  • Axis Twist Compensation: A tool to compensate
    for inaccurate probe readings due to twist in X gantry.
• Resonance compensation: A tool to
  reduce ringing in prints.
  • Measuring resonances: Information on
    using adxl345 accelerometer hardware to measure resonance.
• Pressure advance: Calibrate extruder
  pressure.
• G-Codes: Information on commands supported by Klipper.
• Command Templates: G-Code macros and
  conditional evaluation.
  • Status Reference: Information available to
    macros (and similar).
• TMC Drivers: Using Trinamic stepper motor drivers
  with Klipper.
• Multi-MCU Homing: Homing and probing using multiple micro-controllers.
• Slicers: Configure "slicer" software for Klipper.
• Skew correction: Adjustments for axes not
  perfectly square.
• PWM tools: Guide on how to use PWM controlled
  tools such as lasers or spindles.
• Exclude Object: The guide to the Exclude Objects
  implementation.

Developer Documentation Copy Chapter

• Code overview: Developers should read this
  first.
• Kinematics: Technical details on how Klipper
  implements motion.
• Protocol: Information on the low-level messaging
  protocol between host and micro-controller.
• API Server: Information on Klipper's command and
  control API.
• MCU commands: A description of low-level commands
  implemented in the micro-controller software.
• CAN bus protocol: Klipper CAN bus message
  format.
• Debugging: Information on how to test and debug
  Klipper.
• Benchmarks: Information on the Klipper benchmark
  method.
• Contributing: Information on how to submit
  improvements to Klipper.
• Packaging: Information on building OS packages.

Device Specific Documents Copy Chapter

• Example configs: Information on adding an
  example config file to Klipper.
• SDCard Updates: Flash a micro-controller by
  copying a binary to an sdcard in the micro-controller.
• Raspberry Pi as Micro-controller: Details
  for controlling devices wired to the GPIO pins of a Raspberry Pi.
• Beaglebone: Details for running Klipper on the
  Beaglebone PRU.
• Bootloaders: Developer information on
  micro-controller flashing.
• Bootloader Entry: Requesting the bootloader.
• CAN bus: Information on using CAN bus with Klipper.
  • CAN bus troubleshooting: Tips for
    troubleshooting CAN bus.
• TSL1401CL filament width sensor
• Hall filament width sensor
• Eddy Current Inductive probe
• Load Cells

Index (`docs/index.md`) Copy Section

hide:

• toc
  title: Welcome

{ .center-image }

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. Read the
documentation, see the license, or
download the software. We
depend on the generous support from our sponsors.

API Server (`docs/API_Server.md`) Copy Section

API server

This document describes Klipper's Application Programmer Interface
(API). This interface enables external applications to query and
control the Klipper host software.

Enabling the API socket Copy Chapter

In order to use the API server, the klippy.py host software must be
started with the -a parameter. For example:

~/klippy-env/bin/python ~/klipper/klippy/klippy.py ~/printer.cfg -a /tmp/klippy_uds -l /tmp/klippy.log

This causes the host software to create a Unix Domain Socket. A client
can then open a connection on that socket and send commands to
Klipper.

See the Moonraker project for
a popular tool that can forward HTTP requests to Klipper's API Server
Unix Domain Socket.

Request format Copy Chapter

Messages sent and received on the socket are JSON encoded strings
terminated by an ASCII 0x03 character:

<json_object_1><0x03><json_object_2><0x03>...

Klipper contains a scripts/whconsole.py tool that can perform the
above message framing. For example:

~/klipper/scripts/whconsole.py /tmp/klippy_uds

This tool can read a series of JSON commands from stdin, send them to
Klipper, and report the results. The tool expects each JSON command to
be on a single line, and it will automatically append the 0x03
terminator when transmitting a request. (The Klipper API server does
not have a newline requirement.)

API Protocol Copy Chapter

The command protocol used on the communication socket is inspired by
json-rpc.

A request might look like:

{"id": 123, "method": "info", "params": {}}

and a response might look like:

{"id": 123, "result": {"state_message": "Printer is ready", "klipper_path": "/home/pi/klipper", "config_file": "/home/pi/printer.cfg", "software_version": "v0.8.0-823-g883b1cb6", "hostname": "octopi", "cpu_info": "4 core ARMv7 Processor rev 4 (v7l)", "state": "ready", "python_path": "/home/pi/klippy-env/bin/python", "log_file": "/tmp/klippy.log"}}

Each request must be a JSON dictionary. (This document uses the Python
term "dictionary" to describe a "JSON object" - a mapping of key/value
pairs contained within {}.)

The request dictionary must contain a "method" parameter that is the
string name of an available Klipper "endpoint".

The request dictionary may contain a "params" parameter which must be
of a dictionary type. The "params" provide additional parameter
information to the Klipper "endpoint" handling the request. Its
content is specific to the "endpoint".

The request dictionary may contain an "id" parameter which may be of
any JSON type. If "id" is present then Klipper will respond to the
request with a response message containing that "id". If "id" is
omitted (or set to a JSON "null" value) then Klipper will not provide
any response to the request. A response message is a JSON dictionary
containing "id" and "result". The "result" is always a dictionary -
its contents are specific to the "endpoint" handling the request.

If the processing of a request results in an error, then the response
message will contain an "error" field instead of a "result" field. For
example, the request:
{"id": 123, "method": "gcode/script", "params": {"script": "G1 X200"}}
might result in an error response such as:
{"id": 123, "error": {"message": "Must home axis first: 200.000 0.000 0.000 [0.000]", "error": "WebRequestError"}}

Klipper will always start processing requests in the order that they
are received. However, some request may not complete immediately,
which could cause the associated response to be sent out of order with
respect to responses from other requests. A JSON request will never
pause the processing of future JSON requests.

Subscriptions Copy Chapter

Some Klipper "endpoint" requests allow one to "subscribe" to future
asynchronous update messages.

For example:

{"id": 123, "method": "gcode/subscribe_output", "params": {"response_template":{"key": 345}}}

may initially respond with:

{"id": 123, "result": {}}

and cause Klipper to send future messages similar to:

{"params": {"response": "ok B:22.8 /0.0 T0:22.4 /0.0"}, "key": 345}

A subscription request accepts a "response_template" dictionary in the
"params" field of the request. That "response_template" dictionary is
used as a template for future asynchronous messages - it may contain
arbitrary key/value pairs. When sending these future asynchronous
messages, Klipper will add a "params" field containing a dictionary
with "endpoint" specific contents to the response template and then
send that template. If a "response_template" field is not provided
then it defaults to an empty dictionary ({}).

Available "endpoints" Copy Chapter

By convention, Klipper "endpoints" are of the form
<module_name>/<some_name>. When making a request to an "endpoint",
the full name must be set in the "method" parameter of the request
dictionary (eg, {"method"="gcode/restart"}).

info Copy Section

The "info" endpoint is used to obtain system and version information
from Klipper. It is also used to provide the client's version
information to Klipper. For example:
{"id": 123, "method": "info", "params": { "client_info": { "version": "v1"}}}

If present, the "client_info" parameter must be a dictionary, but that
dictionary may have arbitrary contents. Clients are encouraged to
provide the name of the client and its software version when first
connecting to the Klipper API server.

emergency_stop Copy Section

The "emergency_stop" endpoint is used to instruct Klipper to
transition to a "shutdown" state. It behaves similarly to the G-Code
M112 command. For example:
{"id": 123, "method": "emergency_stop"}

register_remote_method Copy Section

This endpoint allows clients to register methods that can be called
from klipper. It will return an empty object upon success.

For example:
{"id": 123, "method": "register_remote_method", "params": {"response_template": {"action": "run_paneldue_beep"}, "remote_method": "paneldue_beep"}}
will return:
{"id": 123, "result": {}}

The remote method paneldue_beep may now be called from Klipper. Note
that if the method takes parameters they should be provided as keyword
arguments. Below is an example of how it may called from a gcode_macro:

[gcode_macro PANELDUE_BEEP]
gcode:
  {action_call_remote_method("paneldue_beep", frequency=300, duration=1.0)}

When the PANELDUE_BEEP gcode macro is executed, Klipper would send something
like the following over the socket:
{"action": "run_paneldue_beep", "params": {"frequency": 300, "duration": 1.0}}

objects/list Copy Section

This endpoint queries the list of available printer "objects" that one
may query (via the "objects/query" endpoint). For example:
{"id": 123, "method": "objects/list"}
might return:
{"id": 123, "result": {"objects": ["webhooks", "configfile", "heaters", "gcode_move", "query_endstops", "idle_timeout", "toolhead", "extruder"]}}

objects/query Copy Section

This endpoint allows one to query information from printer objects.
For example:
{"id": 123, "method": "objects/query", "params": {"objects": {"toolhead": ["position"], "webhooks": null}}}
might return:
{"id": 123, "result": {"status": {"webhooks": {"state": "ready", "state_message": "Printer is ready"}, "toolhead": {"position": [0.0, 0.0, 0.0, 0.0]}}, "eventtime": 3051555.377933684}}

The "objects" parameter in the request must be a dictionary containing
the printer objects that are to be queried - the key contains the
printer object name and the value is either "null" (to query all
fields) or a list of field names.

The response message will contain a "status" field containing a
dictionary with the queried information - the key contains the printer
object name and the value is a dictionary containing its fields. The
response message will also contain an "eventtime" field containing the
timestamp from when the query was taken.

Available fields are documented in the
Status Reference document.

objects/subscribe Copy Section

This endpoint allows one to query and then subscribe to information
from printer objects. The endpoint request and response is identical
to the "objects/query" endpoint. For example:
{"id": 123, "method": "objects/subscribe", "params": {"objects":{"toolhead": ["position"], "webhooks": ["state"]}, "response_template":{}}}
might return:
{"id": 123, "result": {"status": {"webhooks": {"state": "ready"}, "toolhead": {"position": [0.0, 0.0, 0.0, 0.0]}}, "eventtime": 3052153.382083195}}
and result in subsequent asynchronous messages such as:
{"params": {"status": {"webhooks": {"state": "shutdown"}}, "eventtime": 3052165.418815847}}

gcode/help Copy Section

This endpoint allows one to query available G-Code commands that have
a help string defined. For example:
{"id": 123, "method": "gcode/help"}
might return:
{"id": 123, "result": {"RESTORE_GCODE_STATE": "Restore a previously saved G-Code state", "PID_CALIBRATE": "Run PID calibration test", "QUERY_ADC": "Report the last value of an analog pin", ...}}

gcode/script Copy Section

This endpoint allows one to run a series of G-Code commands. For example:
{"id": 123, "method": "gcode/script", "params": {"script": "G90"}}

If the provided G-Code script raises an error, then an error response
is generated. However, if the G-Code command produces terminal output,
that terminal output is not provided in the response. (Use the
"gcode/subscribe_output" endpoint to obtain G-Code terminal output.)

If there is a G-Code command being processed when this request is
received, then the provided script will be queued. This delay could be
significant (eg, if a G-Code wait for temperature command is running).
The JSON response message is sent when the processing of the script
fully completes.

gcode/restart Copy Section

This endpoint allows one to request a restart - it is similar to
running the G-Code "RESTART" command. For example:
{"id": 123, "method": "gcode/restart"}

As with the "gcode/script" endpoint, this endpoint only completes
after any pending G-Code commands complete.

gcode/firmware_restart Copy Section

This is similar to the "gcode/restart" endpoint - it implements the
G-Code "FIRMWARE_RESTART" command. For example:
{"id": 123, "method": "gcode/firmware_restart"}

As with the "gcode/script" endpoint, this endpoint only completes
after any pending G-Code commands complete.

gcode/subscribe_output Copy Section

This endpoint is used to subscribe to G-Code terminal messages that
are generated by Klipper. For example:
{"id": 123, "method": "gcode/subscribe_output", "params": {"response_template":{}}}
might later produce asynchronous messages such as:
{"params": {"response": "// Klipper state: Shutdown"}}

This endpoint is intended to support human interaction via a "terminal
window" interface. Parsing content from the G-Code terminal output is
discouraged. Use the "objects/subscribe" endpoint to obtain updates on
Klipper's state.

motion_report/dump_stepper Copy Section

This endpoint is used to subscribe to Klipper's internal stepper
queue_step command stream for a stepper. Obtaining these low-level
motion updates may be useful for diagnostic and debugging
purposes. Using this endpoint may increase Klipper's system load.

A request may look like:
{"id": 123, "method":"motion_report/dump_stepper", "params": {"name": "stepper_x", "response_template": {}}}
and might return:
{"id": 123, "result": {"header": ["interval", "count", "add"]}}
and might later produce asynchronous messages such as:
{"params": {"first_clock": 179601081, "first_time": 8.98, "first_position": 0, "last_clock": 219686097, "last_time": 10.984, "data": [[179601081, 1, 0], [29573, 2, -8685], [16230, 4, -1525], [10559, 6, -160], [10000, 976, 0], [10000, 1000, 0], [10000, 1000, 0], [10000, 1000, 0], [9855, 5, 187], [11632, 4, 1534], [20756, 2, 9442]]}}

The "header" field in the initial query response is used to describe
the fields found in later "data" responses.

motion_report/dump_trapq Copy Section

This endpoint is used to subscribe to Klipper's internal "trapezoid
motion queue". Obtaining these low-level motion updates may be useful
for diagnostic and debugging purposes. Using this endpoint may
increase Klipper's system load.

A request may look like:
{"id": 123, "method": "motion_report/dump_trapq", "params": {"name": "toolhead", "response_template":{}}}
and might return:
{"id": 1, "result": {"header": ["time", "duration", "start_velocity", "acceleration", "start_position", "direction"]}}
and might later produce asynchronous messages such as:
{"params": {"data": [[4.05, 1.0, 0.0, 0.0, [300.0, 0.0, 0.0], [0.0, 0.0, 0.0]], [5.054, 0.001, 0.0, 3000.0, [300.0, 0.0, 0.0], [-1.0, 0.0, 0.0]]]}}

The "header" field in the initial query response is used to describe
the fields found in later "data" responses.

adxl345/dump_adxl345 Copy Section

This endpoint is used to subscribe to ADXL345 accelerometer data.
Obtaining these low-level motion updates may be useful for diagnostic
and debugging purposes. Using this endpoint may increase Klipper's
system load.

A request may look like:
{"id": 123, "method":"adxl345/dump_adxl345", "params": {"sensor": "adxl345", "response_template": {}}}
and might return:
{"id": 123,"result":{"header":["time","x_acceleration","y_acceleration", "z_acceleration"]}}
and might later produce asynchronous messages such as:
{"params":{"overflows":0,"data":[[3292.432935,-535.44309,-1529.8374,9561.4], [3292.433256,-382.45935,-1606.32927,9561.48375]]}}

The "header" field in the initial query response is used to describe
the fields found in later "data" responses.

angle/dump_angle Copy Section

This endpoint is used to subscribe to
angle sensor data. Obtaining these
low-level motion updates may be useful for diagnostic and debugging
purposes. Using this endpoint may increase Klipper's system load.

A request may look like:
{"id": 123, "method":"angle/dump_angle", "params": {"sensor": "my_angle_sensor", "response_template": {}}}
and might return:
{"id": 123,"result":{"header":["time","angle"]}}
and might later produce asynchronous messages such as:
{"params":{"position_offset":3.151562,"errors":0, "data":[[1290.951905,-5063],[1290.952321,-5065]]}}

The "header" field in the initial query response is used to describe
the fields found in later "data" responses.

load_cell/dump_force Copy Section

This endpoint is used to subscribe to force data produced by a load_cell.
Using this endpoint may increase Klipper's system load.

A request may look like:
{"id": 123, "method":"load_cell/dump_force", "params": {"sensor": "load_cell", "response_template": {}}}
and might return:
{"id": 123,"result":{"header":["time", "force (g)", "counts", "tare_counts"]}}
and might later produce asynchronous messages such as:
{"params":{"data":[[3292.432935, 40.65, 562534, -234467]]}}

The "header" field in the initial query response is used to describe
the fields found in later "data" responses.

load_cell_probe/dump_taps Copy Section

This endpoint is used to subscribe to details of probing "tap" events.
Using this endpoint may increase Klipper's system load.

A request may look like:
{"id": 123, "method":"load_cell/dump_force", "params": {"sensor": "load_cell", "response_template": {}}}
and might return:
{"id": 123,"result":{"header":["probe_tap_event"]}}
and might later produce asynchronous messages such as:

{"params":{"tap":'{
   "time": [118032.28039, 118032.2834, ...],
   "force": [-459.4213119680034, -458.1640702543264, ...],
}}}

This data can be used to render:

• The time/force graph

pause_resume/cancel Copy Section

This endpoint is similar to running the "PRINT_CANCEL" G-Code command.
For example:
{"id": 123, "method": "pause_resume/cancel"}

As with the "gcode/script" endpoint, this endpoint only completes
after any pending G-Code commands complete.

pause_resume/pause Copy Section

This endpoint is similar to running the "PAUSE" G-Code command. For
example:
{"id": 123, "method": "pause_resume/pause"}

As with the "gcode/script" endpoint, this endpoint only completes
after any pending G-Code commands complete.

pause_resume/resume Copy Section

This endpoint is similar to running the "RESUME" G-Code command. For
example:
{"id": 123, "method": "pause_resume/resume"}

As with the "gcode/script" endpoint, this endpoint only completes
after any pending G-Code commands complete.

query_endstops/status Copy Section

This endpoint will query the active endpoints and return their status.
For example:
{"id": 123, "method": "query_endstops/status"}
might return:
{"id": 123, "result": {"y": "open", "x": "open", "z": "TRIGGERED"}}

As with the "gcode/script" endpoint, this endpoint only completes
after any pending G-Code commands complete.

bed_mesh/dump_mesh Copy Section

Dumps the configuration and state for the current mesh and all
saved profiles.

For example:
{"id": 123, "method": "bed_mesh/dump_mesh"}

might return:

/* Detailed source-code truncated for AI context efficiency. */

The dump_mesh endpoint takes one optional parameter, mesh_args.
This parameter must be an object, where the keys and values are
parameters available to BED_MESH_CALIBRATE.
This will update the mesh configuration and probe points using the
supplied parameters prior to returning the result. It is recommended
to omit mesh parameters unless it is desired to visualize the probe points
and/or travel path before performing BED_MESH_CALIBRATE.

Axis Twist Compensation (`docs/Axis_Twist_Compensation.md`) Copy Section

Axis Twist Compensation

This document describes the [axis_twist_compensation] module.

Some printers may have a small twist in their X rail which can skew the results
of a probe attached to the X carriage.
This is common in printers with designs like the Prusa MK3, Sovol SV06 etc and is
further described under probe location
bias. It may result in
probe operations such as Bed Mesh,
Screws Tilt Adjust,
Z Tilt Adjust etc returning inaccurate
representations of the bed.

This module uses manual measurements by the user to correct the probe's results.
Note that if your axis is significantly twisted it is strongly recommended to
first use mechanical means to fix it prior to applying software corrections.

Warning: This module is not compatible with dockable probes yet and will
try to probe the bed without attaching the probe if you use it.

Overview of compensation usage Copy Chapter

Tip: Make sure the probe X and Y offsets are
correctly set as they greatly influence calibration.

Basic Usage: X-Axis Calibration Copy Section

1. After setting up the [axis_twist_compensation] module, run:

AXIS_TWIST_COMPENSATION_CALIBRATE

This command will calibrate the X-axis by default.

• The calibration wizard will prompt you to measure the probe Z offset at
  several points along the bed.
• By default, the calibration uses 3 points, but you can specify a different
  number with the option:
  SAMPLE_COUNT=<value>

2. Adjust Your Z Offset:
   After completing the calibration, be sure to
   adjust your Z offset.

3. Perform Bed Leveling Operations:
   Use probe-based operations as needed, such as:

• Screws Tilt Adjust
• Z Tilt Adjust

4. Finalize the Setup:

• Home all axes, and perform a Bed Mesh if necessary.
• Run a test print, followed by any
  fine-tuning
  if needed.

For Y-Axis Calibration Copy Section

The calibration process for the Y-axis is similar to the X-axis. To calibrate
the Y-axis, use:

AXIS_TWIST_COMPENSATION_CALIBRATE AXIS=Y

This will guide you through the same measuring process as for the X-axis.

Tip: Bed temperature and nozzle temperature and size do not seem to have
an influence to the calibration process.

[axis_twist_compensation] setup and commands Copy Chapter

Configuration options for [axis_twist_compensation] can be found in the
Configuration Reference.

Commands for [axis_twist_compensation] can be found in the
G-Codes Reference

BLTouch (`docs/BLTouch.md`) Copy Section

BL-Touch

Connecting BL-Touch Copy Chapter

A warning before you start: Avoid touching the BL-Touch pin with
your bare fingers, since it is quite sensitive to finger grease. And
if you do touch it, be very gentle, in order to not bend or push
anything.

Hook up the BL-Touch "servo" connector to a control_pin according to
the BL-Touch documentation or your MCU documentation. Using the
original wiring, the yellow wire from the triple is the control_pin
and the white wire from the pair is the sensor_pin. You need to
configure these pins according to your wiring. Most BL-Touch devices
require a pullup on the sensor pin (prefix the pin name with "^"). For
example:

[bltouch]
sensor_pin: ^P1.24
control_pin: P1.26

If the BL-Touch will be used to home the Z axis then set endstop_pin: probe:z_virtual_endstop and remove position_endstop in the [stepper_z] config section,
then add a [safe_z_home] config section to raise the z axis, home the xy axes,
move to the center of the bed, and home the z axis. For example:

[safe_z_home]
home_xy_position: 100, 100 # Change coordinates to the center of your print bed
speed: 50
z_hop: 10                 # Move up 10mm
z_hop_speed: 5

It's important that the z_hop movement in safe_z_home is high enough
that the probe doesn't hit anything even if the probe pin happens to
be in its lowest state.

Initial tests Copy Chapter

Before moving on, verify that the BL-Touch is mounted at the correct
height, the pin should be roughly 2 mm above the nozzle when retracted

When you turn on the printer, the BL-Touch probe should perform a
self-test and move the pin up and down a couple of times. Once the
self-test is completed, the pin should be retracted and the red LED on
the probe should be lit. If there are any errors, for example the
probe is flashing red or the pin is down instead of up, please turn
off the printer and check the wiring and configuration.

If the above is looking good, it's time to test that the control pin
is working correctly. First run BLTOUCH_DEBUG COMMAND=pin_down in
your printer terminal. Verify that the pin moves down and that the red
LED on the probe turns off. If not, check your wiring and
configuration again. Next issue a BLTOUCH_DEBUG COMMAND=pin_up,
verify that the pin moves up, and that the red light turns on
again. If it's flashing then there's some problem.

The next step is to confirm that the sensor pin is working correctly.
Run BLTOUCH_DEBUG COMMAND=pin_down, verify that the pin moves down,
run BLTOUCH_DEBUG COMMAND=touch_mode, run QUERY_PROBE, and verify
that command reports "probe: open". Then while gently pushing the pin
up slightly with the nail of your finger run QUERY_PROBE again.
Verify the command reports "probe: TRIGGERED". If either query does
not report the correct message then it usually indicates an incorrect
wiring or configuration (though some clones may
require special handling). At the completion of this test run
BLTOUCH_DEBUG COMMAND=pin_up and verify that the pin moves up.

After completing the BL-Touch control pin and sensor pin tests, it is
now time to test probing, but with a twist. Instead of letting the
probe pin touch the print bed, let it touch the nail on your finger.
Position the toolhead far from the bed, issue a G28 (or PROBE if
not using probe:z_virtual_endstop), wait until the toolhead starts to
move down, and stop the movement by very gently touching the pin with
your nail. You may have to do it twice, since the default homing
configuration probes twice. Be prepared to turn off the printer if it
doesn't stop when you touch the pin.

If that was successful, do another G28 (or PROBE) but this time
let it touch the bed as it should.

BL-Touch gone bad Copy Chapter

Once the BL-Touch is in inconsistent state, it starts blinking red.
You can force it to leave that state by issuing:

BLTOUCH_DEBUG COMMAND=reset

This may happen if its calibration is interrupted by the probe being
blocked from being extracted.

However, the BL-Touch may also not be able to calibrate itself
anymore. This happens if the screw on its top is in the wrong position
or the magnetic core inside the probe pin has moved. If it has moved
up so that it sticks to the screw, it may not be able to lower its pin
anymore. With this behavior you need to open the screw and use a
ball-point pen to push it gently back into place. Re-Insert the pin
into the BL-Touch so that it falls into the extracted position.
Carefully readjust the headless screw into place. You need to find the
right position so it is able to lower and raise the pin and the red
light turns on and of. Use the reset, pin_up and pin_down
commands to achieve this.

BL-Touch "clones" Copy Chapter

Many BL-Touch "clone" devices work correctly with Klipper using the
default configuration. However, some "clone" devices may not support
the QUERY_PROBE command and some "clone" devices may require
configuration of pin_up_reports_not_triggered or
pin_up_touch_mode_reports_triggered.

Important! Do not configure pin_up_reports_not_triggered or
pin_up_touch_mode_reports_triggered to False without first following
these directions. Do not configure either of these to False on a
genuine BL-Touch. Incorrectly setting these to False can increase
probing time and can increase the risk of damaging the printer.

Some "clone" devices do not support touch_mode and as a result the
QUERY_PROBE command does not work. Despite this, it may still be
possible to perform probing and homing with these devices. On these
devices the QUERY_PROBE command during the
initial tests will not succeed, however the
subsequent G28 (or PROBE) test does succeed. It may be possible to
use these "clone" devices with Klipper if one does not utilize the
QUERY_PROBE command and one does not enable the
probe_with_touch_mode feature.

Some "clone" devices are unable to perform Klipper's internal sensor
verification test. On these devices, attempts to home or probe can
result in Klipper reporting a "BLTouch failed to verify sensor state"
error. If this occurs, then manually run the steps to confirm the
sensor pin is working as described in the
initial tests section. If the QUERY_PROBE commands
in that test always produce the expected results and "BLTouch failed
to verify sensor state" errors still occur, then it may be necessary
to set pin_up_touch_mode_reports_triggered to False in the Klipper
config file.

A rare number of old "clone" devices are unable to report when they
have successfully raised their probe. On these devices Klipper will
report a "BLTouch failed to raise probe" error after every home or
probe attempt. One can test for these devices - move the head far from
the bed, run BLTOUCH_DEBUG COMMAND=pin_down, verify the pin has
moved down, run QUERY_PROBE, verify that command reports "probe:
open", run BLTOUCH_DEBUG COMMAND=pin_up, verify the pin has moved
up, and run QUERY_PROBE. If the pin remains up, the device does not
enter an error state, and the first query reports "probe: open" while
the second query reports "probe: TRIGGERED" then it indicates that
pin_up_reports_not_triggered should be set to False in the Klipper
config file.

BL-Touch v3 Copy Chapter

Some BL-Touch v3.0 and BL-Touch 3.1 devices may require configuring
probe_with_touch_mode in the printer config file.

If the BL-Touch v3.0 has its signal wire connected to an endstop pin
(with a noise filtering capacitor), then the BL-Touch v3.0 may not be
able to consistently send a signal during homing and probing. If the
QUERY_PROBE commands in the initial tests section
always produce the expected results, but the toolhead does not always
stop during G28/PROBE commands, then it is indicative of this issue. A
workaround is to set probe_with_touch_mode: True in the config file.

The BL-Touch v3.1 may incorrectly enter an error state after a
successful probe attempt. The symptoms are an occasional flashing
light on the BL-Touch v3.1 that lasts for a couple of seconds after it
successfully contacts the bed. Klipper should clear this error
automatically and it is generally harmless. However, one may set
probe_with_touch_mode in the config file to avoid this issue.

Important! Some "clone" devices and the BL-Touch v2.0 (and earlier)
may have reduced accuracy when probe_with_touch_mode is set to True.
Setting this to True also increases the time it takes to deploy the
probe. If configuring this value on a "clone" or older BL-Touch
device, be sure to test the probe accuracy before and after setting
this value (use the PROBE_ACCURACY command to test).

Multi-probing without stowing Copy Chapter

By default, Klipper will deploy the probe at the start of each probe
attempt and then stow the probe afterwards. This repetitive deploying
and stowing of the probe may increase the total time of calibration
sequences that involve many probe measurements. Klipper supports
leaving the probe deployed between consecutive probes, which can
reduce the total time of probing. This mode is enabled by configuring
stow_on_each_sample to False in the config file.

Important! Setting stow_on_each_sample to False can lead to Klipper
making horizontal toolhead movements while the probe is deployed. Be
sure to verify all probing operations have sufficient Z clearance
prior to setting this value to False. If there is insufficient
clearance then a horizontal move may cause the pin to catch on an
obstruction and result in damage to the printer.

Important! It is recommended to use probe_with_touch_mode configured
to True when using stow_on_each_sample configured to False. Some
"clone" devices may not detect a subsequent bed contact if
probe_with_touch_mode is not set. On all devices, using the
combination of these two settings simplifies the device signaling,
which can improve overall stability.

Note, however, that some "clone" devices and the BL-Touch v2.0 (and
earlier) may have reduced accuracy when probe_with_touch_mode is set
to True. On these devices it is a good idea to test the probe accuracy
before and after setting probe_with_touch_mode (use the
PROBE_ACCURACY command to test).

Calibrating the BL-Touch offsets Copy Chapter

Follow the directions in the Probe Calibrate
guide to set the x_offset, y_offset, and z_offset config parameters.

It's a good idea to verify that the Z offset is close to 1mm. If not,
then you probably want to move the probe up or down to fix this. You
want it to trigger well before the nozzle hits the bed, so that
possible stuck filament or a warped bed doesn't affect any probing
action. But at the same time, you want the retracted position to be as
far above the nozzle as possible to avoid it touching printed parts.
If an adjustment is made to the probe position, then rerun the probe
calibration steps.

BL-Touch output mode Copy Chapter

• A BL-Touch V3.0 supports setting a 5V or OPEN-DRAIN output mode,
  a BL-Touch V3.1 supports this too, but can also store this in its
  internal EEPROM. If your controller board needs the fixed 5V high
  logic level of the 5V mode you may set the 'set_output_mode'
  parameter in the [bltouch] section of the printer config file to
  "5V".

  *** Only use the 5V mode if your controller boards input line is
  5V tolerant. This is why the default configuration of these BL-Touch
  versions is OPEN-DRAIN mode. You could potentially damage your
  controller boards CPU ***

  So therefore:
  If a controller board NEEDs 5V mode AND it is 5V tolerant on its
  input signal line AND if

  • you have a BL-Touch Smart V3.0, you need the use 'set_output_mode: 5V'
    parameter to ensure this setting at each startup, since the probe
    cannot remember the needed setting.
  • you have a BL-Touch Smart V3.1, you have the choice of using
    'set_output_mode: 5V' or storing the mode once by use of a
    'BLTOUCH_STORE MODE=5V' command manually and NOT using the parameter
    'set_output_mode:'.
  • you have some other probe: Some probes have a trace on the circuit board
    to cut or a jumper to set in order to (permanently) set the output mode.
    In that case, omit the 'set_output_mode' parameter completely.

  If you have a V3.1, do not automate or repeat storing the output mode to
  avoid wearing out the EEPROM of the probe.The BLTouch EEPROM is good for
  about 100.000 updates. 100 stores per day would add up to about 3 years
  of operation prior to wearing it out. Thus, storing the output mode in a
  V3.1 is designed by the vendor to be a complicated operation (the factory
  default being a safe OPEN DRAIN mode) and is not suited to be repeatedly
  issued by any slicer, macro or anything else, it is preferably only to be
  used when first integrating the probe into a printers electronics.

Beaglebone (`docs/Beaglebone.md`) Copy Section

Beaglebone

This document describes the process of running Klipper on a Beaglebone
PRU.

Building an OS image Copy Chapter

Start by installing the
Debian 11.7 2023-09-02 4GB microSD IoT
image. One may run the image from either a micro-SD card or from
builtin eMMC. If using the eMMC, install it to eMMC now by following
the instructions from the above link.

Then ssh into the Beaglebone machine (ssh debian@beaglebone --
password is temppwd).

Before start installing Klipper you need to free-up additional space.
there are 3 options to do that:

1. remove some BeagleBone "Demo" resources
2. if you did boot from SD-Card, and it's bigger than 4Gb - you can expand
   current filesystem to take whole card space
3. do option #1 and #2 together.

To remove some BeagleBone "Demo" resources execute these commands

sudo apt remove bb-node-red-installer
sudo apt remove bb-code-server

To expand filesystem to full size of your SD-Card execute this command, reboot is not required.

sudo growpart /dev/mmcblk0 1
sudo resize2fs /dev/mmcblk0p1

Install Klipper by running the following
commands:

git clone https://github.com/Klipper3d/klipper.git
./klipper/scripts/install-beaglebone.sh

After installing Klipper you need to decide what kind of deployment do you need,
but take a note that BeagleBone is 3.3v based hardware and in most cases you can't
directly connect pins to 5v or 12v based hardware without conversion boards.

As Klipper have multimodule architecture on BeagleBone you can achieve many different use cases,
but general ones are following:

Use case 1: Use BeagleBone only as a host system to run Klipper and additional software
like OctoPrint/Fluidd + Moonraker/... and this configuration will be driving
external micro-controllers via serial/usb/canbus connections.

Use case 2: Use BeagleBone with extension board (cape) like CRAMPS board.
in this configuration BeagleBone will host Klipper + additional software, and
it will drive extension board with BeagleBone PRU cores (2 additional cores 200Mh, 32Bit).

Use case 3: It's same as "Use case 1" but additionally you want to drive
BeagleBone GPIOs with high speed by utilizing PRU cores to offload main CPU.

Installing Octoprint Copy Chapter

One may then install Octoprint or fully skip this section if desired other software:

git clone https://github.com/foosel/OctoPrint.git
cd OctoPrint/
virtualenv venv
./venv/bin/python setup.py install

And setup OctoPrint to start at bootup:

sudo cp ~/OctoPrint/scripts/octoprint.init /etc/init.d/octoprint
sudo chmod +x /etc/init.d/octoprint
sudo cp ~/OctoPrint/scripts/octoprint.default /etc/default/octoprint
sudo update-rc.d octoprint defaults

It is necessary to modify OctoPrint's /etc/default/octoprint
configuration file. One must change the OCTOPRINT_USER user to
debian, change NICELEVEL to 0, uncomment the BASEDIR, CONFIGFILE,
and DAEMON settings and change the references from /home/pi/ to
/home/debian/:

sudo nano /etc/default/octoprint

Then start the Octoprint service:

sudo systemctl start octoprint

Wait 1-2 minutes and make sure the OctoPrint web server is accessible - it should be at:
http://beaglebone:5000/

Building the BeagleBone PRU micro-controller code (PRU firmware) Copy Chapter

This section is required for "Use case 2" and "Use case 3" mentioned above,
you should skip it for "Use case 1".

Check that required devices are present

sudo beagle-version

You should check that output contains successful "remoteproc" drivers loading and presence of PRU cores,
in Kernel 5.10 they should be "remoteproc1" and "remoteproc2" (4a334000.pru, 4a338000.pru)
Also check that many GPIOs are loaded they will look like "Allocated GPIO id=0 name='P8_03'"
Usually everything is fine and no hardware configuration is required.
If something is missing - try to play with "uboot overlays" options or with cape-overlays
Just for reference some output of working BeagleBone Black configuration with CRAMPS board:

model:[TI_AM335x_BeagleBone_Black]
UBOOT: Booted Device-Tree:[am335x-boneblack-uboot-univ.dts]
UBOOT: Loaded Overlay:[BB-ADC-00A0.bb.org-overlays]
UBOOT: Loaded Overlay:[BB-BONE-eMMC1-01-00A0.bb.org-overlays]
kernel:[5.10.168-ti-r71]
/boot/uEnv.txt Settings:
uboot_overlay_options:[enable_uboot_overlays=1]
uboot_overlay_options:[disable_uboot_overlay_video=0]
uboot_overlay_options:[disable_uboot_overlay_audio=1]
uboot_overlay_options:[disable_uboot_overlay_wireless=1]
uboot_overlay_options:[enable_uboot_cape_universal=1]
pkg:[bb-cape-overlays]:[4.14.20210821.0-0~bullseye+20210821]
pkg:[bb-customizations]:[1.20230720.1-0~bullseye+20230720]
pkg:[bb-usb-gadgets]:[1.20230414.0-0~bullseye+20230414]
pkg:[bb-wl18xx-firmware]:[1.20230414.0-0~bullseye+20230414]
.............
.............

To compile the Klipper micro-controller code, start by configuring it for the "Beaglebone PRU",
for "BeagleBone Black" additionally disable options "Support GPIO Bit-banging devices" and disable "Support LCD devices"
inside the "Optional features" because they will not fit in 8Kb PRU firmware memory,
then exit and save config:

cd ~/klipper/
make menuconfig

To build and install the new PRU micro-controller code, run:

sudo service klipper stop
make flash
sudo service klipper start

After previous commands was executed your PRU firmware should be ready and started
to check if everything was fine you can execute following command

dmesg

and compare last messages with sample one which indicate that everything started properly:

[   71.105499] remoteproc remoteproc1: 4a334000.pru is available
[   71.157155] remoteproc remoteproc2: 4a338000.pru is available
[   73.256287] remoteproc remoteproc1: powering up 4a334000.pru
[   73.279246] remoteproc remoteproc1: Booting fw image am335x-pru0-fw, size 97112
[   73.285807]  remoteproc1#vdev0buffer: registered virtio0 (type 7)
[   73.285836] remoteproc remoteproc1: remote processor 4a334000.pru is now up
[   73.286322] remoteproc remoteproc2: powering up 4a338000.pru
[   73.313717] remoteproc remoteproc2: Booting fw image am335x-pru1-fw, size 188560
[   73.313753] remoteproc remoteproc2: header-less resource table
[   73.329964] remoteproc remoteproc2: header-less resource table
[   73.348321] remoteproc remoteproc2: remote processor 4a338000.pru is now up
[   73.443355] virtio_rpmsg_bus virtio0: creating channel rpmsg-pru addr 0x1e
[   73.443727] virtio_rpmsg_bus virtio0: msg received with no recipient
[   73.444352] virtio_rpmsg_bus virtio0: rpmsg host is online
[   73.540993] rpmsg_pru virtio0.rpmsg-pru.-1.30: new rpmsg_pru device: /dev/rpmsg_pru30

take a note about "/dev/rpmsg_pru30" - it's your future serial device for main mcu configuration
this device is required to be present, if it's absent - your PRU cores did not start properly.

Building and installing Linux host micro-controller code Copy Chapter

This section is required for "Use case 2" and optional for "Use case 3" mentioned above

It is also necessary to compile and install the micro-controller code
for a Linux host process. Configure it a second time for a "Linux process":

make menuconfig

Then install this micro-controller code as well:

sudo service klipper stop
make flash
sudo service klipper start

take a note about "/tmp/klipper_host_mcu" - it will be your future serial device for "mcu host"
if that file don't exist - refer to "scripts/klipper-mcu.service" file, it was installed by
previous commands, and it's responsible for it.

Take a note for "Use case 2" about following: when you will define printer configuration you should always
use temperature sensors from "mcu host" because ADCs not present in default "mcu" (PRU cores).
Sample configuration of "sensor_pin" for extruder and heated bed are available in "generic-cramps.cfg"
You can use any other GPIO directly from "mcu host" by referencing them this way "host:gpiochip1/gpio17"
but that should be avoided because it will be creating additional load on main CPU and most probably
you can't use them for stepper control.

Remaining configuration Copy Chapter

Complete the installation by configuring Klipper
following the instructions in
the main Installation document.

Printing on the Beaglebone Copy Chapter

Unfortunately, the Beaglebone processor can sometimes struggle to run
OctoPrint well. Print stalls have been known to occur on complex
prints (the printer may move faster than OctoPrint can send movement
commands). If this occurs, consider using the "virtual_sdcard" feature
(see Config Reference for
details) to print directly from Klipper
and disable any DEBUG or VERBOSE logging options if you did enable them.

AVR micro-controller code build Copy Chapter

This environment have everything to build necessary micro-controller code except AVR,
AVR packages was removed because of conflict with PRU packages.
if you still want to build AVR micro-controller code in this environment you need to remove
PRU packages and install AVR packages by executing following commands

sudo apt-get remove gcc-pru
sudo apt-get install avrdude gcc-avr binutils-avr avr-libc

if you need to restore PRU packages - then remove ARV packages before that

sudo apt-get remove avrdude gcc-avr binutils-avr avr-libc
sudo apt-get install gcc-pru

Hardware Pin designation Copy Chapter

BeagleBone is very flexible in terms of pin designation, same pin can be configured for different function
but always single function for single pin, same function can be present on different pins.
So you can't have multiple functions on single pin or have same function on multiple pins.
Example:
P9_20 - i2c2_sda/can0_tx/spi1_cs0/gpio0_12/uart1_ctsn
P9_19 - i2c2_scl/can0_rx/spi1_cs1/gpio0_13/uart1_rtsn
P9_24 - i2c1_scl/can1_rx/gpio0_15/uart1_tx
P9_26 - i2c1_sda/can1_tx/gpio0_14/uart1_rx

Pin designation is defined by using special "overlays" which will be loaded during linux boot
they are configured by editing file /boot/uEnv.txt with elevated permissions

sudo editor /boot/uEnv.txt

and defining which functionality to load, for example to enable CAN1 you need to define overlay for it

uboot_overlay_addr4=/lib/firmware/BB-CAN1-00A0.dtbo

This overlay BB-CAN1-00A0.dtbo will reconfigure all required pins for CAN1 and create CAN device in Linux.
Any change in overlays will require system reboot to be applied.
If you need to understand which pins are involved in some overlay - you can analyze source files in
this location: /opt/sources/bb.org-overlays/src/arm/
or search info in BeagleBone forums.

Enabling hardware SPI Copy Chapter

BeagleBone usually have multiple hardware SPI buses, for example BeagleBone Black can have 2 of them,
they can work up to 48Mhz, but usually they are limited to 16Mhz by Kernel Device-tree.
By default, in BeagleBone Black some of SPI1 pins are configured for HDMI-Audio output,
to fully enable 4-wire SPI1 you need to disable HDMI Audio and enable SPI1
To do that edit file /boot/uEnv.txt with elevated permissions

sudo editor /boot/uEnv.txt

uncomment variable

disable_uboot_overlay_audio=1

next uncomment variable and define it this way

uboot_overlay_addr4=/lib/firmware/BB-SPIDEV1-00A0.dtbo

Save changes in /boot/uEnv.txt and reboot the board.
Now you have SPI1 Enabled, to verify its presence execute command

ls /dev/spidev1.*

Take a note that BeagleBone usually is 3.3v based hardware and to use 5V SPI devices
you need to add Level-Shifting chip, for example SN74CBTD3861, SN74LVC1G34 or similar.
If you are using CRAMPS board - it already contains Level-Shifting chip and SPI1 pins
will become available on P503 port, and they can accept 5v hardware,
check CRAMPS board Schematics for pin references.

Enabling hardware I2C Copy Chapter

BeagleBone usually have multiple hardware I2C buses, for example BeagleBone Black can have 3 of them,
they support speed up-to 400Kbit Fast mode.
By default, in BeagleBone Black there are two of them (i2c-1 and i2c-2) usually both are already configured and
present on P9, third ic2-0 usually reserved for internal use.
If you are using CRAMPS board then i2c-2 is present on P303 port with 3.3v level,
If you want to obtain I2c-1 in CRAMPS board - you can get them on Extruder1.Step, Extruder1.Dir pins,
they also are 3.3v based, check CRAMPS board Schematics for pin references.
Related overlays, for Hardware Pin designation:
I2C1(100Kbit): BB-I2C1-00A0.dtbo
I2C1(400Kbit): BB-I2C1-FAST-00A0.dtbo
I2C2(100Kbit): BB-I2C2-00A0.dtbo
I2C2(400Kbit): BB-I2C2-FAST-00A0.dtbo

Enabling hardware UART(Serial)/CAN Copy Chapter

BeagleBone have up to 6 hardware UART(Serial) buses (up to 3Mbit)
and up to 2 hardware CAN(1Mbit) buses.
UART1(RX,TX) and CAN1(TX,RX) and I2C2(SDA,SCL) are using same pins - so you need to chose what to use
UART1(CTSN,RTSN) and CAN0(TX,RX) and I2C1(SDA,SCL) are using same pins - so you need to chose what to use
All UART/CAN related pins are 3.3v based, so you will need to use Transceiver chips/boards like SN74LVC2G241DCUR (for UART),
SN65HVD230 (for CAN), TTL-RS485 (for RS-485) or something similar which can convert 3.3v signals to appropriate levels.

Related overlays, for Hardware Pin designation
CAN0: BB-CAN0-00A0.dtbo
CAN1: BB-CAN1-00A0.dtbo
UART0: - used for Console
UART1(RX,TX): BB-UART1-00A0.dtbo
UART1(RTS,CTS): BB-UART1-RTSCTS-00A0.dtbo
UART2(RX,TX): BB-UART2-00A0.dtbo
UART3(RX,TX): BB-UART3-00A0.dtbo
UART4(RS-485): BB-UART4-RS485-00A0.dtbo
UART5(RX,TX): BB-UART5-00A0.dtbo

Bed Level (`docs/Bed_Level.md`) Copy Section

Bed leveling

Bed leveling (sometimes also referred to as "bed tramming") is
critical to getting high quality prints. If a bed is not properly
"leveled" it can lead to poor bed adhesion, "warping", and subtle
problems throughout the print. This document serves as a guide to
performing bed leveling in Klipper.

It's important to understand the goal of bed leveling. If the printer
is commanded to a position X0 Y0 Z10 during a print, then the goal
is for the printer's nozzle to be exactly 10mm from the printer's
bed. Further, should the printer then be commanded to a position of
X50 Z10 the goal is for the nozzle to maintain an exact distance of
10mm from the bed during that entire horizontal move.

In order to get good quality prints the printer should be calibrated
so that Z distances are accurate to within about 25 microns (.025mm).
This is a small distance - significantly smaller than the width of a
typical human hair. This scale can not be measured "by eye". Subtle
effects (such as heat expansion) impact measurements at this scale.
The secret to getting high accuracy is to use a repeatable process and
to use a leveling method that leverages the high accuracy of the
printer's own motion system.

Choose the appropriate calibration mechanism Copy Chapter

Different types of printers use different methods for performing bed
leveling. All of them ultimately depend on the "paper test" (described
below). However, the actual process for a particular type of printer
is described in other documents.

Prior to running any of these calibration tools, be sure to run the
checks described in the config check document. It
is necessary to verify basic printer motion before performing bed
leveling.

For printers with an "automatic Z probe" be sure to calibrate the
probe following the directions in the
Probe Calibrate document. For delta printers,
see the Delta Calibrate document. For printers
with bed screws and traditional Z endstops, see the
Manual Level document.

During calibration it may be necessary to set the printer's Z
position_min to a negative number (eg, position_min = -2). The
printer enforces boundary checks even during calibration
routines. Setting a negative number allows the printer to move below
the nominal position of the bed, which may help when trying to
determine the actual bed position.

The "paper test" Copy Chapter

The primary bed calibration mechanism is the "paper test". It involves
placing a regular piece of "copy machine paper" between the printer's
bed and nozzle, and then commanding the nozzle to different Z heights
until one feels a small amount of friction when pushing the paper back
and forth.

It is important to understand the "paper test" even if one has an
"automatic Z probe". The probe itself often needs to be calibrated to
get good results. That probe calibration is done using this "paper
test".

In order to perform the paper test, cut a small rectangular piece of
paper using a pair of scissors (eg, 5x3 cm). The paper generally has a
thickness of around 100 microns (0.100mm). (The exact thickness of the paper
isn't crucial.)

The first step of the paper test is to inspect the printer's nozzle
and bed. Make sure there is no plastic (or other debris) on the nozzle
or bed.

Inspect the nozzle and bed to ensure no plastic is present!

If one always prints on a particular tape or printing surface then one
may perform the paper test with that tape/surface in place. However,
note that tape itself has a thickness and different tapes (or any other
printing surface) will impact Z measurements. Be sure to rerun the
paper test to measure each type of surface that is in use.

If there is plastic on the nozzle then heat up the extruder and use a
metal tweezers to remove that plastic. Wait for the extruder to fully
cool to room temperature before continuing with the paper test. While
the nozzle is cooling, use the metal tweezers to remove any plastic
that may ooze out.

Always perform the paper test when both nozzle and bed are at room
temperature!

When the nozzle is heated, its position (relative to the bed) changes
due to thermal expansion. This thermal expansion is typically around a
100 microns, which is about the same thickness as a typical piece of
printer paper. The exact amount of thermal expansion isn't crucial,
just as the exact thickness of the paper isn't crucial. Start with the
assumption that the two are equal (see below for a method of
determining the difference between the two distances).

It may seem odd to calibrate the distance at room temperature when the
goal is to have a consistent distance when heated. However, if one
calibrates when the nozzle is heated, it tends to impart small amounts
of molten plastic on to the paper, which changes the amount of
friction felt. That makes it harder to get a good calibration.
Calibrating while the bed/nozzle is hot also greatly increases the
risk of burning oneself. The amount of thermal expansion is stable, so
it is easily accounted for later in the calibration process.

Use an automated tool to determine precise Z heights!

Klipper has several helper scripts available (eg, MANUAL_PROBE,
Z_ENDSTOP_CALIBRATE, PROBE_CALIBRATE, DELTA_CALIBRATE). See the
documents
described above to
choose one of them.

Run the appropriate command in the OctoPrint terminal window. The
script will prompt for user interaction in the OctoPrint terminal
output. It will look something like:

Recv: // Starting manual Z probe. Use TESTZ to adjust position.
Recv: // Finish with ACCEPT or ABORT command.
Recv: // Z position: ?????? --> 5.000 <-- ??????

The current height of the nozzle (as the printer currently understands
it) is shown between the "--> <--". The number to the right is the
height of the last probe attempt just greater than the current height,
and to the left is the last probe attempt less than the current height
(or ?????? if no attempt has been made).

Place the paper between the nozzle and bed. It can be useful to fold a
corner of the paper so that it is easier to grab. (Try not to push
down on the bed when moving the paper back and forth.)

Use the TESTZ command to request the nozzle to move closer to the
paper. For example:

TESTZ Z=-.1

The TESTZ command will move the nozzle a relative distance from the
nozzle's current position. (So, Z=-.1 requests the nozzle to move
closer to the bed by .1mm.) After the nozzle stops moving, push the
paper back and forth to check if the nozzle is in contact with the
paper and to feel the amount of friction. Continue issuing TESTZ
commands until one feels a small amount of friction when testing with
the paper.

If too much friction is found then one can use a positive Z value to
move the nozzle up. It is also possible to use TESTZ Z=+ or TESTZ Z=- to "bisect" the last position - that is to move to a position
half way between two positions. For example, if one received the
following prompt from a TESTZ command:

Recv: // Z position: 0.130 --> 0.230 <-- 0.280

Then a TESTZ Z=- would move the nozzle to a Z position of 0.180
(half way between 0.130 and 0.230). One can use this feature to help
rapidly narrow down to a consistent friction. It is also possible to
use Z=++ and Z=-- to return directly to a past measurement - for
example, after the above prompt a TESTZ Z=-- command would move the
nozzle to a Z position of 0.130.

After finding a small amount of friction run the ACCEPT command:

ACCEPT

This will accept the given Z height and proceed with the given
calibration tool.

The exact amount of friction felt isn't crucial, just as the amount of
thermal expansion and exact width of the paper isn't crucial. Just try
to obtain the same amount of friction each time one runs the test.

If something goes wrong during the test, one can use the ABORT
command to exit the calibration tool.

Determining Thermal Expansion Copy Chapter

After successfully performing bed leveling, one may go on to calculate
a more precise value for the combined impact of "thermal expansion",
"thickness of the paper", and "amount of friction felt during the paper
test".

This type of calculation is generally not needed as most users find
the simple "paper test" provides good results.

The easiest way to make this calculation is to print a test object
that has straight walls on all sides. The large hollow square found in
docs/prints/square.stl can be used for this.
When slicing the object, make sure the slicer uses the same layer
height and extrusion widths for the first level that it does for all
subsequent layers. Use a coarse layer height (the layer height should
be around 75% of the nozzle diameter) and do not use a brim or raft.

Print the test object, wait for it to cool, and remove it from the
bed. Inspect the lowest layer of the object. (It may also be useful to
run a finger or nail along the bottom edge.) If one finds the bottom
layer bulges out slightly along all sides of the object then it
indicates the nozzle was slightly closer to the bed then it should
be. One can issue a SET_GCODE_OFFSET Z=+.010 command to increase the
height. In subsequent prints one can inspect for this behavior and
make further adjustment as needed. Adjustments of this type are
typically in 10s of microns (.010mm).

If the bottom layer consistently appears narrower than subsequent
layers then one can use the SET_GCODE_OFFSET command to make a
negative Z adjustment. If one is unsure, then one can decrease the Z
adjustment until the bottom layer of prints exhibit a small bulge, and
then back-off until it disappears.

The easiest way to apply the desired Z adjustment is to create a
START_PRINT g-code macro, arrange for the slicer to call that macro
during the start of each print, and add a SET_GCODE_OFFSET command to
that macro. See the slicers document for further
details.

Bed Mesh (`docs/Bed_Mesh.md`) Copy Section

Bed Mesh

The Bed Mesh module may be used to compensate for bed surface irregularities
to achieve a better first layer across the entire bed. It should be noted
that software based correction will not achieve perfect results, it can only
approximate the shape of the bed. Bed Mesh also cannot compensate for
mechanical and electrical issues. If an axis is skewed or a probe is not
accurate then the bed_mesh module will not receive accurate results from
the probing process.

Prior to Mesh Calibration you will need to be sure that your Probe's
Z-Offset is calibrated. If using an endstop for Z homing it will need
to be calibrated as well. See Probe Calibrate
and Z_ENDSTOP_CALIBRATE in Manual Level for more
information.

Basic Configuration Copy Chapter

Rectangular Beds Copy Section

This example assumes a printer with a 250 mm x 220 mm rectangular
bed and a probe with an x-offset of 24 mm and y-offset of 5 mm.

[bed_mesh]
speed: 120
horizontal_move_z: 5
mesh_min: 35, 6
mesh_max: 240, 198
probe_count: 5, 3

• speed: 120
  Default Value: 50
  The speed in which the tool moves between points.

• horizontal_move_z: 5
  Default Value: 5
  The Z coordinate the probe rises to prior to traveling between points.

• mesh_min: 35, 6
  Required
  The first probed coordinate, nearest to the origin. This coordinate
  is relative to the probe's location.

• mesh_max: 240, 198
  Required
  The probed coordinate farthest from the origin. This is not necessarily
  the last point probed, as the probing process occurs in a zig-zag fashion.
  As with mesh_min, this coordinate is relative to the probe's location.

• probe_count: 5, 3
  Default Value: 3, 3
  The number of points to probe on each axis, specified as X, Y integer
  values. In this example 5 points will be probed along the X axis, with
  3 points along the Y axis, for a total of 15 probed points. Note that
  if you wanted a square grid, for example 3x3, this could be specified
  as a single integer value that is used for both axes, ie probe_count: 3.
  Note that a mesh requires a minimum probe_count of 3 along each axis.

The illustration below demonstrates how the mesh_min, mesh_max, and
probe_count options are used to generate probe points. The arrows indicate
the direction of the probing procedure, beginning at mesh_min. For reference,
when the probe is at mesh_min the nozzle will be at (11, 1), and when the probe
is at mesh_max, the nozzle will be at (206, 193).

Round beds Copy Section

This example assumes a printer equipped with a round bed radius of 100mm.
We will use the same probe offsets as the rectangular example, 24 mm on X
and 5 mm on Y.

[bed_mesh]
speed: 120
horizontal_move_z: 5
mesh_radius: 75
mesh_origin: 0, 0
round_probe_count: 5

• mesh_radius: 75
  Required
  The radius of the probed mesh in mm, relative to the mesh_origin. Note
  that the probe's offsets limit the size of the mesh radius. In this example,
  a radius larger than 76 would move the tool beyond the range of the printer.

• mesh_origin: 0, 0
  Default Value: 0, 0
  The center point of the mesh. This coordinate is relative to the probe's
  location. While the default is 0, 0, it may be useful to adjust the origin
  in an effort to probe a larger portion of the bed. See the illustration
  below.

• round_probe_count: 5
  Default Value: 5
  This is an integer value that defines the maximum number of probed points
  along the X and Y axes. By "maximum", we mean the number of points probed
  along the mesh origin. This value must be an odd number, as it is required
  that the center of the mesh is probed.

The illustration below shows how the probed points are generated. As you can see,
setting the mesh_origin to (-10, 0) allows us to specify a larger mesh radius
of 85.

Advanced Configuration Copy Chapter

Below the more advanced configuration options are explained in detail. Each
example will build upon the basic rectangular bed configuration shown above.
Each of the advanced options apply to round beds in the same manner.

Mesh Interpolation Copy Section

While its possible to sample the probed matrix directly using simple bi-linear
interpolation to determine the Z-Values between probed points, it is often
useful to interpolate extra points using more advanced interpolation algorithms
to increase mesh density. These algorithms add curvature to the mesh,
attempting to simulate the material properties of the bed. Bed Mesh offers
lagrange and bicubic interpolation to accomplish this.

[bed_mesh]
speed: 120
horizontal_move_z: 5
mesh_min: 35, 6
mesh_max: 240, 198
probe_count: 5, 3
mesh_pps: 2, 3
algorithm: bicubic
bicubic_tension: 0.2

• mesh_pps: 2, 3
  Default Value: 2, 2
  The mesh_pps option is shorthand for Mesh Points Per Segment. This
  option specifies how many points to interpolate for each segment along
  the X and Y axes. Consider a 'segment' to be the space between each
  probed point. Like probe_count, mesh_pps is specified as an X, Y
  integer pair, and also may be specified a single integer that is applied
  to both axes. In this example there are 4 segments along the X axis
  and 2 segments along the Y axis. This evaluates to 8 interpolated
  points along X, 6 interpolated points along Y, which results in a 13x9
  mesh. Note that if mesh_pps is set to 0 then mesh interpolation is
  disabled and the probed matrix will be sampled directly.

• algorithm: lagrange
  Default Value: lagrange
  The algorithm used to interpolate the mesh. May be lagrange or bicubic.
  Lagrange interpolation is capped at 6 probed points as oscillation tends to
  occur with a larger number of samples. Bicubic interpolation requires a
  minimum of 4 probed points along each axis, if less than 4 points are
  specified then lagrange sampling is forced. If mesh_pps is set to 0 then
  this value is ignored as no mesh interpolation is done.

• bicubic_tension: 0.2
  Default Value: 0.2
  If the algorithm option is set to bicubic it is possible to specify the
  tension value. The higher the tension the more slope is interpolated. Be
  careful when adjusting this, as higher values also create more overshoot,
  which will result in interpolated values higher or lower than your probed
  points.

The illustration below shows how the options above are used to generate an
interpolated mesh.

Move Splitting Copy Section

Bed Mesh works by intercepting gcode move commands and applying a
transform to their Z coordinate. Long moves must be split into smaller
moves to correctly follow the shape of the bed. The options below
control the splitting behavior.

[bed_mesh]
speed: 120
horizontal_move_z: 5
mesh_min: 35, 6
mesh_max: 240, 198
probe_count: 5, 3
move_check_distance: 5
split_delta_z: .025

• move_check_distance: 5
  Default Value: 5
  The minimum distance to check for the desired change in Z before performing
  a split. In this example, a move longer than 5mm will be traversed by the
  algorithm. Each 5mm a mesh Z lookup will occur, comparing it with the Z
  value of the previous move. If the delta meets the threshold set by
  split_delta_z, the move will be split and traversal will continue. This
  process repeats until the end of the move is reached, where a final
  adjustment will be applied. Moves shorter than the move_check_distance
  have the correct Z adjustment applied directly to the move without
  traversal or splitting.

• split_delta_z: .025
  Default Value: .025
  As mentioned above, this is the minimum deviation required to trigger a
  move split. In this example, any Z value with a deviation +/- .025mm
  will trigger a split.

Generally the default values for these options are sufficient, in fact the
default value of 5mm for the move_check_distance may be overkill. However an
advanced user may wish to experiment with these options in an effort to squeeze
out the optimal first layer.

Mesh Fade Copy Section

When "fade" is enabled Z adjustment is phased out over a distance defined
by the configuration. This is accomplished by applying small adjustments
to the layer height, either increasing or decreasing depending on the shape
of the bed. When fade has completed, Z adjustment is no longer applied,
allowing the top of the print to be flat rather than mirror the shape of the
bed. Fade also may have some undesirable traits, if you fade too quickly it
can result in visible artifacts on the print. Also, if your bed is
significantly warped, fade can shrink or stretch the Z height of the print.
As such, fade is disabled by default.

[bed_mesh]
speed: 120
horizontal_move_z: 5
mesh_min: 35, 6
mesh_max: 240, 198
probe_count: 5, 3
fade_start: 1
fade_end: 10
fade_target: 0

• fade_start: 1
  Default Value: 1
  The Z height in which to start phasing out adjustment. It is a good idea
  to get a few layers down before starting the fade process.

• fade_end: 10
  Default Value: 0
  The Z height in which fade should complete. If this value is lower than
  fade_start then fade is disabled. This value may be adjusted depending
  on how warped the print surface is. A significantly warped surface should
  fade out over a longer distance. A near flat surface may be able to reduce
  this value to phase out more quickly. 10mm is a sane value to begin with if
  using the default value of 1 for fade_start.

• fade_target: 0
  Default Value: The average Z value of the mesh
  The fade_target can be thought of as an additional Z offset applied to the
  entire bed after fade completes. Generally speaking we would like this value
  to be 0, however there are circumstances where it should not be. For
  example, lets assume your homing position on the bed is an outlier, its
  .2 mm lower than the average probed height of the bed. If the fade_target
  is 0, fade will shrink the print by an average of .2 mm across the bed. By
  setting the fade_target to .2, the homed area will expand by .2 mm, however,
  the rest of the bed will be accurately sized. Generally its a good idea
  to leave fade_target out of the configuration so the average height of the
  mesh is used, however it may be desirable to manually adjust the fade target
  if one wants to print on a specific portion of the bed.

Configuring the zero reference position Copy Section

Many probes are susceptible to "drift", ie: inaccuracies in probing introduced
by heat or interference. This can make calculating the probe's z-offset
challenging, particularly at different bed temperatures. As such, some
printers use an endstop for homing the Z axis and a probe for calibrating the
mesh. In this configuration it is possible offset the mesh so that the (X, Y)
reference position applies zero adjustment. The reference position should
be the location on the bed where a
Z_ENDSTOP_CALIBRATE
paper test is performed. The bed_mesh module provides the
zero_reference_position option for specifying this coordinate:

[bed_mesh]
speed: 120
horizontal_move_z: 5
mesh_min: 35, 6
mesh_max: 240, 198
zero_reference_position: 125, 110
probe_count: 5, 3

• zero_reference_position:
  Default Value: None (disabled)
  The zero_reference_position expects an (X, Y) coordinate matching that
  of the reference position described above. If the coordinate lies within
  the mesh then the mesh will be offset so the reference position applies zero
  adjustment. If the coordinate lies outside of the mesh then the coordinate
  will be probed after calibration, with the resulting z-value used as the
  z-offset. Note that this coordinate must NOT be in a location specified as
  a faulty_region if a probe is necessary.

Faulty Regions Copy Section

It is possible for some areas of a bed to report inaccurate results when
probing due to a "fault" at specific locations. The best example of this
are beds with series of integrated magnets used to retain removable steel
sheets. The magnetic field at and around these magnets may cause an inductive
probe to trigger at a distance higher or lower than it would otherwise,
resulting in a mesh that does not accurately represent the surface at these
locations. Note: This should not be confused with probe location bias, which
produces inaccurate results across the entire bed.

The faulty_region options may be configured to compensate for this affect.
If a generated point lies within a faulty region bed mesh will attempt to
probe up to 4 points at the boundaries of this region. These probed values
will be averaged and inserted in the mesh as the Z value at the generated
(X, Y) coordinate.

[bed_mesh]
speed: 120
horizontal_move_z: 5
mesh_min: 35, 6
mesh_max: 240, 198
probe_count: 5, 3
faulty_region_1_min: 130.0, 0.0
faulty_region_1_max: 145.0, 40.0
faulty_region_2_min: 225.0, 0.0
faulty_region_2_max: 250.0, 25.0
faulty_region_3_min: 165.0, 95.0
faulty_region_3_max: 205.0, 110.0
faulty_region_4_min: 30.0, 170.0
faulty_region_4_max: 45.0, 210.0

• faulty_region_{1...99}_min
faulty_region_{1..99}_max
  Default Value: None (disabled)
  Faulty Regions are defined in a way similar to that of mesh itself, where
  minimum and maximum (X, Y) coordinates must be specified for each region.
  A faulty region may extend outside of a mesh, however the alternate points
  generated will always be within the mesh boundary. No two regions may
  overlap.

The image below illustrates how replacement points are generated when
a generated point lies within a faulty region. The regions shown match those
in the sample config above. The replacement points and their coordinates
are identified in green.

Adaptive Meshes Copy Section

Adaptive bed meshing is a way to speed up the bed mesh generation by only probing
the area of the bed used by the objects being printed. When used, the method will
automatically adjust the mesh parameters based on the area occupied by the defined
print objects.

The adapted mesh area will be computed from the area defined by the boundaries of all
the defined print objects so it covers every object, including any margins defined in
the configuration. After the area is computed, the number of probe points will be
scaled down based on the ratio of the default mesh area and the adapted mesh area. To
illustrate this consider the following example:

For a 150mmx150mm bed with mesh_min set to 25,25 and mesh_max set to 125,125,
the default mesh area is a 100mmx100mm square. An adapted mesh area of 50,50
means a ratio of 0.5x0.5 between the adapted area and default mesh area.

If the bed_mesh configuration specified probe_count as 7x7, the adapted bed
mesh will use 4x4 probe points (7 * 0.5 rounded up).

[bed_mesh]
speed: 120
horizontal_move_z: 5
mesh_min: 35, 6
mesh_max: 240, 198
probe_count: 5, 3
adaptive_margin: 5

• adaptive_margin
  Default Value: 0
  Margin (in mm) to add around the area of the bed used by the defined objects. The diagram
  below shows the adapted bed mesh area with an adaptive_margin of 5mm. The adapted mesh
  area (area in green) is computed as the used bed area (area in blue) plus the defined margin.

By nature, adaptive bed meshes use the objects defined by the Gcode file being printed.
Therefore, it is expected that each Gcode file will generate a mesh that probes a different
area of the print bed. Therefore, adapted bed meshes should not be re-used. The expectation
is that a new mesh will be generated for each print if adaptive meshing is used.

It is also important to consider that adaptive bed meshing is best used on machines that can
normally probe the entire bed and achieve a maximum variance less than or equal to 1 layer
height. Machines with mechanical issues that a full bed mesh normally compensates for may
have undesirable results when attempting print moves outside of the probed area. If a
full bed mesh has a variance greater than 1 layer height, caution must be taken when using
adaptive bed meshes and attempting print moves outside of the meshed area.

Surface Scans Copy Chapter

Some probes, such as the Eddy Current Probe, are capable of
"scanning" the surface of the bed. That is, these probes can sample a mesh
without lifting the tool between samples. To activate scanning mode, the
METHOD=scan or METHOD=rapid_scan probe parameter should be passed in the
BED_MESH_CALIBRATE gcode command.

Scan Height Copy Section

The scan height is set by the horizontal_move_z option in [bed_mesh]. In
addition it can be supplied with the BED_MESH_CALIBRATE gcode command via the
HORIZONTAL_MOVE_Z parameter.

The scan height must be sufficiently low to avoid scanning errors. Typically
a height of 2mm (ie: HORIZONTAL_MOVE_Z=2) should work well, presuming that the
probe is mounted correctly.

It should be noted that if the probe is more than 4mm above the surface then the
results will be invalid. Thus, scanning is not possible on beds with severe
surface deviation or beds with extreme tilt that hasn't been corrected.

Rapid (Continuous) Scanning Copy Section

When performing a rapid_scan one should keep in mind that the results will
have some amount of error. This error should be low enough to be useful on
large print areas with reasonably thick layer heights. Some probes may be
more prone to error than others.

It is not recommended that rapid mode be used to scan a "dense" mesh. Some of
the error introduced during a rapid scan may be gaussian noise from the sensor,
and a dense mesh will reflect this noise (ie: there will be peaks and valleys).

Bed Mesh will attempt to optimize the travel path to provide the best possible
result based on the configuration. This includes avoiding faulty regions
when collecting samples and "overshooting" the mesh when changing direction.
This overshoot improves sampling at the edges of a mesh, however it requires
that the mesh be configured in a way that allows the tool to travel outside
of the mesh.

[bed_mesh]
speed: 120
horizontal_move_z: 5
mesh_min: 35, 6
mesh_max: 240, 198
probe_count: 5
scan_overshoot: 8

• scan_overshoot
  Default Value: 0 (disabled)
  The maximum amount of travel (in mm) available outside of the mesh.
  For rectangular beds this applies to travel on the X axis, and for round beds
  it applies to the entire radius. The tool must be able to travel the amount
  specified outside of the mesh. This value is used to optimize the travel
  path when performing a "rapid scan". The minimum value that may be specified
  is 1. The default is no overshoot.

If no scan overshoot is configured then travel path optimization will not
be applied to changes in direction.

Bed Mesh Gcodes Copy Chapter

Calibration Copy Section

BED_MESH_CALIBRATE PROFILE=<name> METHOD=[manual | automatic | scan | rapid_scan] \ [=<value>] [<mesh_parameter>=<value>] [ADAPTIVE=[0|1] \ [ADAPTIVE_MARGIN=<value>]
Default Profile: default
Default Method: automatic if a probe is detected, otherwise manual
Default Adaptive: 0
Default Adaptive Margin: 0

Initiates the probing procedure for Bed Mesh Calibration.

The mesh will be immediately ready to use when the command completes and saved
into a profile specified by the PROFILE parameter,
or default if unspecified. The METHOD parameter takes one of the following
values:

• METHOD=manual: enables manual probing using the nozzle and the paper test
• METHOD=automatic: Automatic (standard) probing. This is the default.
• METHOD=scan: Enables surface scanning. The tool will pause over each position
  to collect a sample.
• METHOD=rapid_scan: Enables continuous surface scanning.

XY positions are automatically adjusted to include the X and/or Y offsets
when a probing method other than manual is selected.

It is possible to specify mesh parameters to modify the probed area. The
following parameters are available:

• Rectangular beds (cartesian):
  • MESH_MIN
  • MESH_MAX
  • PROBE_COUNT
• Round beds (delta):
  • MESH_RADIUS
  • MESH_ORIGIN
  • ROUND_PROBE_COUNT
• All beds:
  • MESH_PPS
  • ALGORITHM
  • ADAPTIVE
  • ADAPTIVE_MARGIN

See the configuration documentation above for details on how each parameter
applies to the mesh.

Profiles Copy Section

BED_MESH_PROFILE SAVE=<name> LOAD=<name> REMOVE=<name>

After a BED_MESH_CALIBRATE has been performed, it is possible to save the
current mesh state into a named profile. This makes it possible to load
a mesh without re-probing the bed. After a profile has been saved using
BED_MESH_PROFILE SAVE=<name> the SAVE_CONFIG gcode may be executed
to write the profile to printer.cfg.

Profiles can be loaded by executing BED_MESH_PROFILE LOAD=<name>.

It should be noted that each time a BED_MESH_CALIBRATE occurs, the current
state is automatically saved to the default profile. The default profile can be removed as follows:

BED_MESH_PROFILE REMOVE=default

Any other saved profile can be removed in the same fashion, replacing
default with the named profile you wish to remove.

Loading the default profile

Previous versions of bed_mesh always loaded the profile named default
on startup if it was present. This behavior has been removed in favor of
allowing the user to determine when a profile is loaded. If a user wishes to
load the default profile it is recommended to add
BED_MESH_PROFILE LOAD=default to either their START_PRINT macro or their
slicer's "Start G-Code" configuration, whichever is applicable.

Note that this is not required if a new mesh is generated with
BED_MESH_CALIBRATE in the START_PRINT macro or the slicer's "Start G-Code"
and may produce unexpected results, especially with adaptive meshing.

Alternatively the old behavior of loading a profile at startup can be
restored with a [delayed_gcode]:

[delayed_gcode bed_mesh_init]
initial_duration: .01
gcode:
  BED_MESH_PROFILE LOAD=default

Output Copy Section

BED_MESH_OUTPUT PGP=[0 | 1]

Outputs the current mesh state to the terminal. Note that the mesh itself
is output

The PGP parameter is shorthand for "Print Generated Points". If PGP=1 is
set, the generated probed points will be output to the terminal:

// bed_mesh: generated points
// Index | Tool Adjusted | Probe
// 0 | (11.0, 1.0) | (35.0, 6.0)
// 1 | (62.2, 1.0) | (86.2, 6.0)
// 2 | (113.5, 1.0) | (137.5, 6.0)
// 3 | (164.8, 1.0) | (188.8, 6.0)
// 4 | (216.0, 1.0) | (240.0, 6.0)
// 5 | (216.0, 97.0) | (240.0, 102.0)
// 6 | (164.8, 97.0) | (188.8, 102.0)
// 7 | (113.5, 97.0) | (137.5, 102.0)
// 8 | (62.2, 97.0) | (86.2, 102.0)
// 9 | (11.0, 97.0) | (35.0, 102.0)
// 10 | (11.0, 193.0) | (35.0, 198.0)
// 11 | (62.2, 193.0) | (86.2, 198.0)
// 12 | (113.5, 193.0) | (137.5, 198.0)
// 13 | (164.8, 193.0) | (188.8, 198.0)
// 14 | (216.0, 193.0) | (240.0, 198.0)

The "Tool Adjusted" points refer to the nozzle location for each point, and
the "Probe" points refer to the probe location. Note that when manually
probing the "Probe" points will refer to both the tool and nozzle locations.

Clear Mesh State Copy Section

BED_MESH_CLEAR

This gcode may be used to clear the internal mesh state.

Apply X/Y offsets Copy Section

BED_MESH_OFFSET [X=<value>] [Y=<value>] [ZFADE=<value>]

This is useful for printers with multiple independent extruders, as an offset
is necessary to produce correct Z adjustment after a tool change. Offsets
should be specified relative to the primary extruder. That is, a positive
X offset should be specified if the secondary extruder is mounted to the
right of the primary extruder, a positive Y offset should be specified
if the secondary extruder is mounted "behind" the primary extruder, and
a positive ZFADE offset should be specified if the secondary extruder's
nozzle is above the primary extruder's.

Note that a ZFADE offset does NOT directly apply additional adjustment. It
is intended to compensate for a gcode offset when mesh fade
is enabled. For example, if a secondary extruder is higher than the primary
and needs a negative gcode offset, ie: SET_GCODE_OFFSET Z=-.2, it can be
accounted for in bed_mesh with BED_MESH_OFFSET ZFADE=.2.

Bed Mesh Webhooks APIs Copy Chapter

Dumping mesh data Copy Section

{"id": 123, "method": "bed_mesh/dump_mesh"}

Dumps the configuration and state for the current mesh and all
saved profiles.

The dump_mesh endpoint takes one optional parameter, mesh_args.
This parameter must be an object, where the keys and values are
parameters available to BED_MESH_CALIBRATE.
This will update the mesh configuration and probe points using the
supplied parameters prior to returning the result. It is recommended
to omit mesh parameters unless it is desired to visualize the probe points
and/or travel path before performing BED_MESH_CALIBRATE.

Visualization and analysis Copy Chapter

Most users will likely find that the visualizers included with
applications such as Mainsail, Fluidd, and Octoprint are sufficient
for basic analysis. However, Klipper's scripts folder contains the
graph_mesh.py script that may be used to perform additional
visualizations and more detailed analysis, particularly useful
for debugging hardware or the results produced by bed_mesh:

usage: graph_mesh.py [-h] {list,plot,analyze,dump} ...

Graph Bed Mesh Data

positional arguments:
  {list,plot,analyze,dump}
    list                List available plot types
    plot                Plot a specified type
    analyze             Perform analysis on mesh data
    dump                Dump API response to json file

options:
  -h, --help            show this help message and exit

Pre-requisites Copy Section

Like most graphing tools provided by Klipper, graph_mesh.py requires
the matplotlib and numpy python dependencies. In addition, connecting
to Klipper via Moonraker's websocket requires the websockets python
dependency. While all visualizations can be output to an svg file, most of
the visualizations offered by graph_mesh.py are better viewed in live
preview mode on a desktop class PC. For example, the 3D visualizations may be
rotated and zoomed in preview mode, and the path visualizations can optionally
be animated in preview mode.

Plotting Mesh data Copy Section

The graph_mesh.py tool can plot several types of visualizations.
Available types can be shown by running graph_mesh.py list:

graph_mesh.py list
points    Plot original generated points
path      Plot probe travel path
rapid     Plot rapid scan travel path
probedz   Plot probed Z values
meshz     Plot mesh Z values
overlay   Plots the current probed mesh overlaid with a profile
delta     Plots the delta between current probed mesh and a profile

Several options are available when plotting visualizations:

usage: graph_mesh.py plot [-h] [-a] [-s] [-p PROFILE_NAME] [-o OUTPUT] <plot type> <input>

positional arguments:
  <plot type>           Type of data to graph
  <input>               Path/url to Klipper Socket or path to json file

options:
  -h, --help            show this help message and exit
  -a, --animate         Animate paths in live preview
  -s, --scale-plot      Use axis limits reported by Klipper to scale plot X/Y
  -p PROFILE_NAME, --profile-name PROFILE_NAME
                        Optional name of a profile to plot for 'probedz'
  -o OUTPUT, --output OUTPUT
                        Output file path

Below is a description of each argument:

• plot type: A required positional argument designating the type of
  visualization to generate. Must be one of the types output by the
  graph_mesh.py list command.
• input: A required positional argument containing a path or url
  to the input source. This must be one of the following:
  • A path to Klipper's Unix Domain Socket
  • A url to an instance of Moonraker
  • A path to a json file produced by graph_mesh.py dump
• -a: Optional animation for the path and rapid visualization types.
  Animations only apply to a live preview.
• -s: Optionally scales a plot using the axis_minimum and axis_maximum
  values reported by Klipper's toolhead object when the dump file was
  generated.
• -p: A profile name that may be specified when generating the
  probedz 3D mesh visualization. When generating an overlay or
  delta visualization this argument must be provided.
• -o: An optional file path indicating that the script should save the
  visualization to this location rather than run in preview mode. Images
  are saved in svg format.

For example, to plot an animated rapid path, connecting via Klipper's unix
socket:

graph_mesh.py plot -a rapid ~/printer_data/comms/klippy.sock

Or to plot a 3d visualization of the mesh, connecting via Moonraker:

graph_mesh.py plot meshz http://my-printer.local

Bed Mesh Analysis Copy Section

The graph_mesh.py tool may also be used to perform an analysis on the
data provided by the bed_mesh/dump_mesh API:

graph_mesh.py analyze <input>

As with the plot command, the `` must be a path to Klipper's
unix socket, a URL to an instance of Moonraker, or a path to a json file
generated by the dump command.

To begin, the analysis will perform various checks on the points and
probe paths generated by bed_mesh at the time of the dump. This
includes the following:

• The number of probe points generated, without any additions
• The number of probe points generated including any points generated
  as the result faulty regions and/or a configured zero reference position.
• The number of probe points generated when performing a rapid scan.
• The total number of moves generated for a rapid scan.
• A validation that the probe points generated for a rapid scan are
  identical to the probe points generated for a standard probing procedure.
• A "backtracking" check for both the standard probe path and a rapid scan
  path. Backtracking can be defined as moving to the same position more than
  once during the probing procedure. Backtracking should never occur during a
  standard probe. Faulty regions can result in backtracking during a rapid
  scan in an attempt to avoid entering a faulty region when approaching or
  leaving a probe location, however should never occur otherwise.

Next each probed mesh present in the dump will by analyzed, beginning with
the mesh loaded at the time of the dump (if present) and followed by any
saved profiles. The following data is extracted:

• Mesh shape (Min X,Y, Max X,Y Probe Count)
• Mesh Z range, (Minimum Z, Maximum Z)
• Mean Z value in the mesh
• Standard Deviation of the Z values in the Mesh

In addition to the above, a delta analysis is performed between meshes
with the same shape, reporting the following:

• The range of the delta between to meshes (Minimum and Maximum)
• The mean delta
• Standard Deviation of the delta
• The absolute maximum difference
• The absolute mean

Save mesh data to a file Copy Section

The dump command may be used to save the response to a file which
can be shared for analysis when troubleshooting:

graph_mesh.py dump -o <output file name> <input>

The `` should be a path to Klipper's unix socket or
a URL to an instance of Moonraker. The -o option may be used to
specify the path to the output file. If omitted, the file will be
saved in the working directory, with a file name in the following
format:

klipper-bedmesh-{year}{month}{day}{hour}{minute}{second}.json

Benchmarks (`docs/Benchmarks.md`) Copy Section

Benchmarks

This document describes Klipper benchmarks.

Micro-controller Benchmarks Copy Chapter

This section describes the mechanism used to generate the Klipper
micro-controller step rate benchmarks.

The primary goal of the benchmarks is to provide a consistent
mechanism for measuring the impact of coding changes within the
software. A secondary goal is to provide high-level metrics for
comparing the performance between chips and between software
platforms.

The step rate benchmark is designed to find the maximum stepping rate
that the hardware and software can reach. This benchmark stepping rate
is not achievable in day-to-day use as Klipper needs to perform other
tasks (eg, mcu/host communication, temperature reading, endstop
checking) in any real-world usage.

In general, the pins for the benchmark tests are chosen to flash LEDs
or other innocuous pins. Always verify that it is safe to drive the
configured pins prior to running a benchmark. It is not recommended
to drive an actual stepper during a benchmark.

Step rate benchmark test Copy Section

The test is performed using the console.py tool (described in
Debugging.md). The micro-controller is configured for
the particular hardware platform (see below) and then the following is
cut-and-paste into the console.py terminal window:

SET start_clock {clock+freq}
SET ticks 1000

reset_step_clock oid=0 clock={start_clock}
set_next_step_dir oid=0 dir=0
queue_step oid=0 interval={ticks} count=60000 add=0
set_next_step_dir oid=0 dir=1
queue_step oid=0 interval=3000 count=1 add=0

reset_step_clock oid=1 clock={start_clock}
set_next_step_dir oid=1 dir=0
queue_step oid=1 interval={ticks} count=60000 add=0
set_next_step_dir oid=1 dir=1
queue_step oid=1 interval=3000 count=1 add=0

reset_step_clock oid=2 clock={start_clock}
set_next_step_dir oid=2 dir=0
queue_step oid=2 interval={ticks} count=60000 add=0
set_next_step_dir oid=2 dir=1
queue_step oid=2 interval=3000 count=1 add=0

The above tests three steppers simultaneously stepping. If running the
above results in a "Rescheduled timer in the past" or "Stepper too far
in past" error then it indicates the ticks parameter is too low (it
results in a stepping rate that is too fast). The goal is to find the
lowest setting of the ticks parameter that reliably results in a
successful completion of the test. It should be possible to bisect the
ticks parameter until a stable value is found.

On a failure, one can copy-and-paste the following to clear the error
in preparation for the next test:

clear_shutdown

To obtain the single stepper benchmarks, the same configuration
sequence is used, but only the first block of the above test is
cut-and-paste into the console.py window.

To produce the benchmarks found in the Features document, the total
number of steps per second is calculated by multiplying the number of
active steppers with the nominal mcu frequency and dividing by the
final ticks parameter. The results are rounded to the nearest K. For
example, with three active steppers:

ECHO Test result is: {"%.0fK" % (3. * freq / ticks / 1000.)}

The benchmarks are run with parameters suitable for TMC Drivers. For
micro-controllers that support STEPPER_BOTH_EDGE=1 (as reported in
the MCU config line when console.py first starts) use
step_pulse_duration=0 and invert_step=-1 to enable optimized
stepping on both edges of the step pulse. For other micro-controllers
use a step_pulse_duration corresponding to 100ns.

AVR step rate benchmark Copy Section

The following configuration sequence is used on AVR chips:

allocate_oids count=3
config_stepper oid=0 step_pin=PA5 dir_pin=PA4 invert_step=0 step_pulse_ticks=32
config_stepper oid=1 step_pin=PA3 dir_pin=PA2 invert_step=0 step_pulse_ticks=32
config_stepper oid=2 step_pin=PC7 dir_pin=PC6 invert_step=0 step_pulse_ticks=32
finalize_config crc=0

The test was last run on commit 59314d99 with gcc version avr-gcc (GCC) 5.4.0. Both the 16Mhz and 20Mhz tests were run using simulavr
configured for an atmega644p (previous tests have confirmed simulavr
results match tests on both a 16Mhz at90usb and a 16Mhz atmega2560).

Arduino Due step rate benchmark Copy Section

The following configuration sequence is used on the Due:

allocate_oids count=3
config_stepper oid=0 step_pin=PB27 dir_pin=PA21 invert_step=-1 step_pulse_ticks=0
config_stepper oid=1 step_pin=PB26 dir_pin=PC30 invert_step=-1 step_pulse_ticks=0
config_stepper oid=2 step_pin=PA21 dir_pin=PC30 invert_step=-1 step_pulse_ticks=0
finalize_config crc=0

The test was last run on commit 59314d99 with gcc version
arm-none-eabi-gcc (Fedora 10.2.0-4.fc34) 10.2.0.

Duet Maestro step rate benchmark Copy Section

The following configuration sequence is used on the Duet Maestro:

allocate_oids count=3
config_stepper oid=0 step_pin=PC26 dir_pin=PC18 invert_step=-1 step_pulse_ticks=0
config_stepper oid=1 step_pin=PC26 dir_pin=PA8 invert_step=-1 step_pulse_ticks=0
config_stepper oid=2 step_pin=PC26 dir_pin=PB4 invert_step=-1 step_pulse_ticks=0
finalize_config crc=0

The test was last run on commit 59314d99 with gcc version
arm-none-eabi-gcc (Fedora 10.2.0-4.fc34) 10.2.0.

Duet Wifi step rate benchmark Copy Section

The following configuration sequence is used on the Duet Wifi:

allocate_oids count=3
config_stepper oid=0 step_pin=PD6 dir_pin=PD11 invert_step=-1 step_pulse_ticks=0
config_stepper oid=1 step_pin=PD7 dir_pin=PD12 invert_step=-1 step_pulse_ticks=0
config_stepper oid=2 step_pin=PD8 dir_pin=PD13 invert_step=-1 step_pulse_ticks=0
finalize_config crc=0

The test was last run on commit 59314d99 with gcc version
gcc version 10.3.1 20210621 (release) (GNU Arm Embedded Toolchain 10.3-2021.07).

Beaglebone PRU step rate benchmark Copy Section

The following configuration sequence is used on the PRU:

allocate_oids count=3
config_stepper oid=0 step_pin=gpio0_23 dir_pin=gpio1_12 invert_step=0 step_pulse_ticks=20
config_stepper oid=1 step_pin=gpio1_15 dir_pin=gpio0_26 invert_step=0 step_pulse_ticks=20
config_stepper oid=2 step_pin=gpio0_22 dir_pin=gpio2_1 invert_step=0 step_pulse_ticks=20
finalize_config crc=0

The test was last run on commit 59314d99 with gcc version pru-gcc (GCC) 8.0.0 20170530 (experimental).

STM32F042 step rate benchmark Copy Section

The following configuration sequence is used on the STM32F042:

allocate_oids count=3
config_stepper oid=0 step_pin=PA1 dir_pin=PA2 invert_step=-1 step_pulse_ticks=0
config_stepper oid=1 step_pin=PA3 dir_pin=PA2 invert_step=-1 step_pulse_ticks=0
config_stepper oid=2 step_pin=PB8 dir_pin=PA2 invert_step=-1 step_pulse_ticks=0
finalize_config crc=0

The test was last run on commit 59314d99 with gcc version
arm-none-eabi-gcc (Fedora 10.2.0-4.fc34) 10.2.0.

STM32F103 step rate benchmark Copy Section

The following configuration sequence is used on the STM32F103:

allocate_oids count=3
config_stepper oid=0 step_pin=PC13 dir_pin=PB5 invert_step=-1 step_pulse_ticks=0
config_stepper oid=1 step_pin=PB3 dir_pin=PB6 invert_step=-1 step_pulse_ticks=0
config_stepper oid=2 step_pin=PA4 dir_pin=PB7 invert_step=-1 step_pulse_ticks=0
finalize_config crc=0

The test was last run on commit 59314d99 with gcc version
arm-none-eabi-gcc (Fedora 10.2.0-4.fc34) 10.2.0.

STM32F4 step rate benchmark Copy Section

The following configuration sequence is used on the STM32F4:

allocate_oids count=3
config_stepper oid=0 step_pin=PA5 dir_pin=PB5 invert_step=-1 step_pulse_ticks=0
config_stepper oid=1 step_pin=PB2 dir_pin=PB6 invert_step=-1 step_pulse_ticks=0
config_stepper oid=2 step_pin=PB3 dir_pin=PB7 invert_step=-1 step_pulse_ticks=0
finalize_config crc=0

The test was last run on commit 59314d99 with gcc version
arm-none-eabi-gcc (Fedora 10.2.0-4.fc34) 10.2.0. The STM32F407
results were obtained by running an STM32F407 binary on an STM32F446
(and thus using a 168Mhz clock).

STM32H7 step rate benchmark Copy Section

The following configuration sequence is used on STM32H723:

allocate_oids count=3
config_stepper oid=0 step_pin=PA13 dir_pin=PB5 invert_step=-1 step_pulse_ticks=52
config_stepper oid=1 step_pin=PB2 dir_pin=PB6 invert_step=-1 step_pulse_ticks=52
config_stepper oid=2 step_pin=PB3 dir_pin=PB7 invert_step=-1 step_pulse_ticks=52
finalize_config crc=0

The test was last run on commit 554ae78d with gcc version
arm-none-eabi-gcc (Fedora 14.1.0-1.fc40) 14.1.0.

STM32G0B1 step rate benchmark Copy Section

The following configuration sequence is used on the STM32G0B1:

allocate_oids count=3
config_stepper oid=0 step_pin=PB13 dir_pin=PB12 invert_step=-1 step_pulse_ticks=0
config_stepper oid=1 step_pin=PB10 dir_pin=PB2 invert_step=-1 step_pulse_ticks=0
config_stepper oid=2 step_pin=PB0 dir_pin=PC5 invert_step=-1 step_pulse_ticks=0
finalize_config crc=0

The test was last run on commit 247cd753 with gcc version
arm-none-eabi-gcc (Fedora 10.2.0-4.fc34) 10.2.0.

STM32G4 step rate benchmark Copy Section

The following configuration sequence is used on the STM32G431:

allocate_oids count=3
config_stepper oid=0 step_pin=PA0 dir_pin=PB5 invert_step=-1 step_pulse_ticks=17
config_stepper oid=1 step_pin=PB2 dir_pin=PB6 invert_step=-1 step_pulse_ticks=17
config_stepper oid=2 step_pin=PB3 dir_pin=PB7 invert_step=-1 step_pulse_ticks=17
finalize_config crc=0

The test was last run on commit cfa48fe3 with gcc version
arm-none-eabi-gcc (Fedora 14.1.0-1.fc40) 14.1.0.

LPC176x step rate benchmark Copy Section

The following configuration sequence is used on the LPC176x:

allocate_oids count=3
config_stepper oid=0 step_pin=P1.20 dir_pin=P1.18 invert_step=-1 step_pulse_ticks=0
config_stepper oid=1 step_pin=P1.21 dir_pin=P1.18 invert_step=-1 step_pulse_ticks=0
config_stepper oid=2 step_pin=P1.23 dir_pin=P1.18 invert_step=-1 step_pulse_ticks=0
finalize_config crc=0

The test was last run on commit 59314d99 with gcc version
arm-none-eabi-gcc (Fedora 10.2.0-4.fc34) 10.2.0. The 120Mhz LPC1769
results were obtained by overclocking an LPC1768 to 120Mhz.

SAMD21 step rate benchmark Copy Section

The following configuration sequence is used on the SAMD21:

allocate_oids count=3
config_stepper oid=0 step_pin=PA27 dir_pin=PA20 invert_step=-1 step_pulse_ticks=0
config_stepper oid=1 step_pin=PB3 dir_pin=PA21 invert_step=-1 step_pulse_ticks=0
config_stepper oid=2 step_pin=PA17 dir_pin=PA21 invert_step=-1 step_pulse_ticks=0
finalize_config crc=0

The test was last run on commit 59314d99 with gcc version
arm-none-eabi-gcc (Fedora 10.2.0-4.fc34) 10.2.0 on a SAMD21G18
micro-controller.

SAMD51 step rate benchmark Copy Section

The following configuration sequence is used on the SAMD51:

allocate_oids count=3
config_stepper oid=0 step_pin=PA22 dir_pin=PA20 invert_step=-1 step_pulse_ticks=0
config_stepper oid=1 step_pin=PA22 dir_pin=PA21 invert_step=-1 step_pulse_ticks=0
config_stepper oid=2 step_pin=PA22 dir_pin=PA19 invert_step=-1 step_pulse_ticks=0
finalize_config crc=0

The test was last run on commit 59314d99 with gcc version
arm-none-eabi-gcc (Fedora 10.2.0-4.fc34) 10.2.0 on a SAMD51J19A
micro-controller.

SAME70 step rate benchmark Copy Section

The following configuration sequence is used on the SAME70:

allocate_oids count=3
config_stepper oid=0 step_pin=PC18 dir_pin=PB5 invert_step=-1 step_pulse_ticks=0
config_stepper oid=1 step_pin=PC16 dir_pin=PD10 invert_step=-1 step_pulse_ticks=0
config_stepper oid=2 step_pin=PC28 dir_pin=PA4 invert_step=-1 step_pulse_ticks=0
finalize_config crc=0

The test was last run on commit 34e9ea55 with gcc version
arm-none-eabi-gcc (NixOS 10.3-2021.10) 10.3.1 on a SAME70Q20B
micro-controller.

AR100 step rate benchmark Copy Section

The following configuration sequence is used on AR100 CPU (Allwinner A64):

allocate_oids count=3
config_stepper oid=0 step_pin=PL10 dir_pin=PE14 invert_step=-1 step_pulse_ticks=0
config_stepper oid=1 step_pin=PL11 dir_pin=PE15 invert_step=-1 step_pulse_ticks=0
config_stepper oid=2 step_pin=PL12 dir_pin=PE16 invert_step=-1 step_pulse_ticks=0
finalize_config crc=0

The test was last run on commit b7978d37 with gcc version
or1k-linux-musl-gcc (GCC) 9.2.0 on an Allwinner A64-H
micro-controller.

RPxxxx step rate benchmark Copy Section

The following configuration sequence is used on the RP2040 and RP2350:

allocate_oids count=3
config_stepper oid=0 step_pin=gpio25 dir_pin=gpio3 invert_step=-1 step_pulse_ticks=0
config_stepper oid=1 step_pin=gpio26 dir_pin=gpio4 invert_step=-1 step_pulse_ticks=0
config_stepper oid=2 step_pin=gpio27 dir_pin=gpio5 invert_step=-1 step_pulse_ticks=0
finalize_config crc=0

The test was last run on commit 14c105b8 with gcc version
arm-none-eabi-gcc (Fedora 14.1.0-1.fc40) 14.1.0 on Raspberry Pi
Pico and Pico 2 boards.

(*) Note that the reported rp2040 ticks are relative to a 12Mhz
scheduling timer and do not correspond to its 200Mhz internal ARM
processing rate. It is expected that 3 scheduling ticks corresponds to
~42 ARM core cycles and 14 scheduling ticks corresponds to ~225 ARM
core cycles.

Linux MCU step rate benchmark Copy Section

The following configuration sequence is used on a Raspberry Pi:

allocate_oids count=3
config_stepper oid=0 step_pin=gpio2 dir_pin=gpio3 invert_step=0 step_pulse_ticks=5
config_stepper oid=1 step_pin=gpio4 dir_pin=gpio5 invert_step=0 step_pulse_ticks=5
config_stepper oid=2 step_pin=gpio6 dir_pin=gpio17 invert_step=0 step_pulse_ticks=5
finalize_config crc=0

The test was last run on commit 59314d99 with gcc version
gcc (Raspbian 8.3.0-6+rpi1) 8.3.0 on a Raspberry Pi 3 (revision
a02082). It was difficult to get stable results in this benchmark.

Command dispatch benchmark Copy Chapter

The command dispatch benchmark tests how many "dummy" commands the
micro-controller can process. It is primarily a test of the hardware
communication mechanism. The test is run using the console.py tool
(described in Debugging.md). The following is
cut-and-paste into the console.py terminal window:

DELAY {clock + 2*freq} get_uptime
FLOOD 100000 0.0 debug_nop
get_uptime

When the test completes, determine the difference between the clocks
reported in the two "uptime" response messages. The total number of
commands per second is then 100000 * mcu_frequency / clock_diff.

The USB tests may exceed the CPU capacity of a Raspberry Pi. If
running on a Raspberry Pi, Beaglebone, or similar host computer then
increase the delay (eg, DELAY {clock + 20*freq} get_uptime). Where
applicable, the benchmarks below are with console.py running on a
desktop class machine with the device connected via a super-speed hub.

The CAN bus tests may saturate the USB host controller of a Raspberry
Pi (when testing via a standard gs_usb USB to CAN bus adapter). Where
applicable, the CAN bus benchmarks below are with console.py running
on a desktop class machine with a USB to CAN bus adapter connected via
a super-speed USB hub.

Host Benchmarks Copy Chapter

It is possible to run timing tests on the host software using the
"batch mode" processing mechanism (described in
Debugging.md). This is typically done by choosing a
large and complex G-Code file and timing how long it takes for the
host software to process it. For example:

time ~/klippy-env/bin/python ./klippy/klippy.py config/example-cartesian.cfg -i something_complex.gcode -o /dev/null -d out/klipper.dict

Bootloader Entry (`docs/Bootloader_Entry.md`) Copy Section

Bootloader Entry

Klipper can be instructed to reboot into a Bootloader in one
of the following ways:

Requesting the bootloader Copy Chapter

Virtual Serial Copy Section

If a virtual (USB-ACM) serial port is in use, pulsing DTR while at 1200 baud
will request the bootloader.

Python (with `flash_usb`)

To enter the bootloader using python (using flash_usb):

> cd klipper/scripts
> python3 -c 'import flash_usb as u; u.enter_bootloader("<DEVICE>")'
Entering bootloader on <DEVICE>

Where <DEVICE> is your serial device, such as
/dev/serial.by-id/usb-Klipper[...] or /dev/ttyACM0

Note that if this fails, no output will be printed, success is indicated by
printing Entering bootloader on <DEVICE>.

Picocom

picocom -b 1200 <DEVICE>
<Ctrl-A><Ctrl-P>

Where <DEVICE> is your serial device, such as
/dev/serial.by-id/usb-Klipper[...] or /dev/ttyACM0

<Ctrl-A><Ctrl-P> means
holding Ctrl, pressing and releasing a, pressing and releasing p, then
releasing Ctrl

Physical serial Copy Section

If a physical serial port is being used on the MCU (even if a USB serial adapter
is being used to connect to it), sending the string
<SPACE><FS><SPACE>Request Serial Bootloader!!<SPACE>~ requests the bootloader.

<SPACE> is an ASCII literal space, 0x20.

<FS> is the ASCII File Separator,
0x1c.

Note that this is not a valid message as per the
MCU Protocol, but sync characters(~)
are still respected.

Because this message must be the only thing in the "block"
it is received in, prefixing an extra sync character can increase reliability if
other tools were previously accessing the serial port.

Shell

stty <BAUD> < /dev/<DEVICE>
echo $'~ \x1c Request Serial Bootloader!! ~' >> /dev/<DEVICE>

Where <DEVICE> is your serial port, such as /dev/ttyS0, or
/dev/serial/by-id/gpio-serial2, and

`` is the baud rate of the serial
port, such as 115200.

CANBUS Copy Section

If CANBUS is in use, a special
admin message will request the bootloader.
This message will be respected even if the device already has a nodeid, and will
also be processed if the mcu is shutdown.

This method also applies to devices operating in
CANBridge mode.

Katapult's flashtool.py

python3 ./katapult/scripts/flashtool.py -i <CAN_IFACE> -u <UUID> -r

Where <CAN_IFACE> is the can interface to use. If using can0, both the -i
and <CAN_IFACE> may be omitted.

`` is the UUID of your CAN device.

See the
CANBUS Documentation
for information on finding the CAN UUID of your devices.

Entering the bootloader Copy Chapter

When klipper receives one of the above bootloader requests:

If Katapult (formerly known as CANBoot) is available, klipper will request that
Katapult stay active on the next boot, then reset the MCU (therefore entering
Katapult).

If Katapult is not available, klipper will then try to enter a
platform-specific bootloader, such as STM32's DFU
mode(see note).

In short, Klipper will reboot to Katapult if installed, then a hardware specific
bootloader if available.

For details about the specific bootloaders on various platforms see
Bootloaders

Notes Copy Chapter

STM32 DFU Warning Copy Section

Note that on some boards, like the Octopus Pro v1, entering DFU mode can cause
undesired actions (such as powering the heater while in DFU mode). It is
recommended to disconnect heaters, and otherwise prevent undesired operations
when using DFU mode. Consult the documentation for your board for more details.

Bootloaders (`docs/Bootloaders.md`) Copy Section

Bootloaders

This document provides information on common bootloaders found on
micro-controllers that Klipper supports.

The bootloader is 3rd-party software that runs on the micro-controller
when it is first powered on. It is typically used to flash a new
application (eg, Klipper) to the micro-controller without requiring
specialized hardware. Unfortunately, there is no industry wide
standard for flashing a micro-controller, nor is there a standard
bootloader that works across all micro-controllers. Worse, it is
common for each bootloader to require a different set of steps to
flash an application.

If one can flash a bootloader to a micro-controller then one can
generally also use that mechanism to flash an application, but care
should be taken when doing this as one may inadvertently remove the
bootloader. In contrast, a bootloader will generally only permit a
user to flash an application. It is therefore recommended to use a
bootloader to flash an application where possible.

This document attempts to describe common bootloaders, the steps
needed to flash a bootloader, and the steps needed to flash an
application. This document is not an authoritative reference; it is
intended as a collection of useful information that the Klipper
developers have accumulated.

AVR micro-controllers Copy Chapter

In general, the Arduino project is a good reference for bootloaders
and flashing procedures on the 8-bit Atmel Atmega micro-controllers.
In particular, the "boards.txt" file:
https://github.com/arduino/Arduino/blob/1.8.5/hardware/arduino/avr/boards.txt
is a useful reference.

To flash a bootloader itself, the AVR chips require an external
hardware flashing tool (which communicates with the chip using
SPI). This tool can be purchased (for example, do a web search for
"avr isp", "arduino isp", or "usb tiny isp"). It is also possible to
use another Arduino or Raspberry Pi to flash an AVR bootloader (for
example, do a web search for "program an avr using raspberry pi"). The
examples below are written assuming an "AVR ISP Mk2" type device is in
use.

The "avrdude" program is the most common tool used to flash atmega
chips (both bootloader flashing and application flashing).

Atmega2560 Copy Section

This chip is typically found in the "Arduino Mega" and is very common
in 3d printer boards.

To flash the bootloader itself use something like:

wget 'https://github.com/arduino/Arduino/raw/1.8.5/hardware/arduino/avr/bootloaders/stk500v2/stk500boot_v2_mega2560.hex'

avrdude -cavrispv2 -patmega2560 -P/dev/ttyACM0 -b115200 -e -u -U lock:w:0x3F:m -U efuse:w:0xFD:m -U hfuse:w:0xD8:m -U lfuse:w:0xFF:m
avrdude -cavrispv2 -patmega2560 -P/dev/ttyACM0 -b115200 -U flash:w:stk500boot_v2_mega2560.hex
avrdude -cavrispv2 -patmega2560 -P/dev/ttyACM0 -b115200 -U lock:w:0x0F:m

To flash an application use something like:

avrdude -cwiring -patmega2560 -P/dev/ttyACM0 -b115200 -D -Uflash:w:out/klipper.elf.hex:i

Atmega1280 Copy Section

This chip is typically found in earlier versions of the "Arduino
Mega".

To flash the bootloader itself use something like:

wget 'https://github.com/arduino/Arduino/raw/1.8.5/hardware/arduino/avr/bootloaders/atmega/ATmegaBOOT_168_atmega1280.hex'

avrdude -cavrispv2 -patmega1280 -P/dev/ttyACM0 -b115200 -e -u -U lock:w:0x3F:m -U efuse:w:0xF5:m -U hfuse:w:0xDA:m -U lfuse:w:0xFF:m
avrdude -cavrispv2 -patmega1280 -P/dev/ttyACM0 -b115200 -U flash:w:ATmegaBOOT_168_atmega1280.hex
avrdude -cavrispv2 -patmega1280 -P/dev/ttyACM0 -b115200 -U lock:w:0x0F:m

To flash an application use something like:

avrdude -carduino -patmega1280 -P/dev/ttyACM0 -b57600 -D -Uflash:w:out/klipper.elf.hex:i

Atmega1284p Copy Section

This chip is commonly found in "Melzi" style 3d printer boards.

To flash the bootloader itself use something like:

wget 'https://github.com/Lauszus/Sanguino/raw/1.0.2/bootloaders/optiboot/optiboot_atmega1284p.hex'

avrdude -cavrispv2 -patmega1284p -P/dev/ttyACM0 -b115200 -e -u -U lock:w:0x3F:m -U efuse:w:0xFD:m -U hfuse:w:0xDE:m -U lfuse:w:0xFF:m
avrdude -cavrispv2 -patmega1284p -P/dev/ttyACM0 -b115200 -U flash:w:optiboot_atmega1284p.hex
avrdude -cavrispv2 -patmega1284p -P/dev/ttyACM0 -b115200 -U lock:w:0x0F:m

To flash an application use something like:

avrdude -carduino -patmega1284p -P/dev/ttyACM0 -b115200 -D -Uflash:w:out/klipper.elf.hex:i

Note that a number of "Melzi" style boards come preloaded with a
bootloader that uses a baud rate of 57600. In this case, to flash an
application use something like this instead:

avrdude -carduino -patmega1284p -P/dev/ttyACM0 -b57600 -D -Uflash:w:out/klipper.elf.hex:i

At90usb1286 Copy Section

This document does not cover the method to flash a bootloader to the
At90usb1286 nor does it cover general application flashing to this
device.

The Teensy++ device from pjrc.com comes with a proprietary bootloader.
It requires a custom flashing tool from
https://github.com/PaulStoffregen/teensy_loader_cli.
One can flash an application with it using something like:

teensy_loader_cli --mcu=at90usb1286 out/klipper.elf.hex -v

Atmega168 Copy Section

The atmega168 has limited flash space. If using a bootloader, it is
recommended to use the Optiboot bootloader. To flash that bootloader
use something like:

wget 'https://github.com/arduino/Arduino/raw/1.8.5/hardware/arduino/avr/bootloaders/optiboot/optiboot_atmega168.hex'

avrdude -cavrispv2 -patmega168 -P/dev/ttyACM0 -b115200 -e -u -U lock:w:0x3F:m -U efuse:w:0x04:m -U hfuse:w:0xDD:m -U lfuse:w:0xFF:m
avrdude -cavrispv2 -patmega168 -P/dev/ttyACM0 -b115200 -U flash:w:optiboot_atmega168.hex
avrdude -cavrispv2 -patmega168 -P/dev/ttyACM0 -b115200 -U lock:w:0x0F:m

To flash an application via the Optiboot bootloader use something
like:

avrdude -carduino -patmega168 -P/dev/ttyACM0 -b115200 -D -Uflash:w:out/klipper.elf.hex:i

SAM3 micro-controllers (Arduino Due) Copy Chapter

It is not common to use a bootloader with the SAM3 mcu. The chip
itself has a ROM that allows the flash to be programmed from 3.3V
serial port or from USB.

To enable the ROM, the "erase" pin is held high during a reset, which
erases the flash contents, and causes the ROM to run. On an Arduino
Due, this sequence can be accomplished by setting a baud rate of 1200
on the "programming usb port" (the USB port closest to the power
supply).

The code at
https://github.com/shumatech/BOSSA
can be used to program the SAM3. It is recommended to use version 1.9
or later.

To flash an application use something like:

bossac -U -p /dev/ttyACM0 -a -e -w out/klipper.bin -v -b
bossac -U -p /dev/ttyACM0 -R

SAM4 micro-controllers (Duet Wifi) Copy Chapter

It is not common to use a bootloader with the SAM4 mcu. The chip
itself has a ROM that allows the flash to be programmed from 3.3V
serial port or from USB.

To enable the ROM, the "erase" pin is held high during a reset, which
erases the flash contents, and causes the ROM to run.

The code at
https://github.com/shumatech/BOSSA
can be used to program the SAM4. It is necessary to use version
1.8.0 or higher.

To flash an application use something like:

bossac --port=/dev/ttyACM0 -b -U -e -w -v -R out/klipper.bin

SAMDC21 micro-controllers (Duet3D Toolboard 1LC) Copy Chapter

The SAMC21 is flashed via the ARM Serial Wire Debug (SWD) interface.
This is commonly done with a dedicated SWD hardware dongle.
Alternatively, one can use a
Raspberry Pi with OpenOCD.

When using OpenOCD with the SAMC21, extra steps must be taken to first
put the chip into Cold Plugging mode if the board makes use of the
SWD pins for other purposes. If using OpenOCD on a Raspberry Pi, this
can be done by running the following commands before invoking OpenOCD.

SWCLK=25
SWDIO=24
SRST=18

echo "Exporting SWCLK and SRST pins."
echo $SWCLK > /sys/class/gpio/export
echo $SRST > /sys/class/gpio/export
echo "out" > /sys/class/gpio/gpio$SWCLK/direction
echo "out" > /sys/class/gpio/gpio$SRST/direction

echo "Setting SWCLK low and pulsing SRST."
echo "0" > /sys/class/gpio/gpio$SWCLK/value
echo "0" > /sys/class/gpio/gpio$SRST/value
echo "1" > /sys/class/gpio/gpio$SRST/value

echo "Unexporting SWCLK and SRST pins."
echo $SWCLK > /sys/class/gpio/unexport
echo $SRST > /sys/class/gpio/unexport

To flash a program with OpenOCD use the following chip config:

source [find target/at91samdXX.cfg]

Obtain a program; for instance, klipper can be built for this chip.
Flash with OpenOCD commands similar to:

at91samd chip-erase
at91samd bootloader 0
program out/klipper.elf verify

SAMD21 micro-controllers (Arduino Zero) Copy Chapter

The SAMD21 bootloader is flashed via the ARM Serial Wire Debug (SWD)
interface. This is commonly done with a dedicated SWD hardware dongle.
Alternatively, one can use a
Raspberry Pi with OpenOCD.

To flash a bootloader with OpenOCD use the following chip config:

source [find target/at91samdXX.cfg]

Obtain a bootloader - for example:

wget 'https://github.com/arduino/ArduinoCore-samd/raw/1.8.3/bootloaders/zero/samd21_sam_ba.bin'

Flash with OpenOCD commands similar to:

at91samd bootloader 0
program samd21_sam_ba.bin verify

The most common bootloader on the SAMD21 is the one found on the
"Arduino Zero". It uses an 8KiB bootloader (the application must be
compiled with a start address of 8KiB). One can enter this bootloader
by double clicking the reset button. To flash an application use
something like:

bossac -U -p /dev/ttyACM0 --offset=0x2000 -w out/klipper.bin -v -b -R

In contrast, the "Arduino M0" uses a 16KiB bootloader (the application
must be compiled with a start address of 16KiB). To flash an
application on this bootloader, reset the micro-controller and run the
flash command within the first few seconds of boot - something like:

avrdude -c stk500v2 -p atmega2560 -P /dev/ttyACM0 -u -Uflash:w:out/klipper.elf.hex:i

SAMD51 micro-controllers (Adafruit Metro-M4 and similar) Copy Chapter

Like the SAMD21, the SAMD51 bootloader is flashed via the ARM Serial
Wire Debug (SWD) interface. To flash a bootloader with
OpenOCD on a Raspberry Pi use
the following chip config:

source [find target/atsame5x.cfg]

Obtain a bootloader - several bootloaders are available from
https://github.com/adafruit/uf2-samdx1/releases/latest. For example:

wget 'https://github.com/adafruit/uf2-samdx1/releases/download/v3.7.0/bootloader-itsybitsy_m4-v3.7.0.bin'

Flash with OpenOCD commands similar to:

at91samd bootloader 0
program bootloader-itsybitsy_m4-v3.7.0.bin verify
at91samd bootloader 16384

The SAMD51 uses a 16KiB bootloader (the application must be compiled
with a start address of 16KiB). To flash an application use something
like:

bossac -U -p /dev/ttyACM0 --offset=0x4000 -w out/klipper.bin -v -b -R

STM32F103 micro-controllers (Blue Pill devices) Copy Chapter

The STM32F103 devices have a ROM that can flash a bootloader or
application via 3.3V serial. Typically one would wire the PA10 (MCU
Rx) and PA9 (MCU Tx) pins to a 3.3V UART adapter. To access the ROM,
one should connect the "boot 0" pin to high and "boot 1" pin to low,
and then reset the device. The "stm32flash" package can then be used
to flash the device using something like:

stm32flash -w out/klipper.bin -v -g 0 /dev/ttyAMA0

Note that if one is using a Raspberry Pi for the 3.3V serial, the
stm32flash protocol uses a serial parity mode which the Raspberry Pi's
"mini UART" does not support. See
https://www.raspberrypi.com/documentation/computers/configuration.html#configuring-uarts
for details on enabling the full uart on the Raspberry Pi GPIO pins.

After flashing, set both "boot 0" and "boot 1" back to low so that
future resets boot from flash.

STM32F103 with stm32duino bootloader Copy Section

The "stm32duino" project has a USB capable bootloader - see:
https://github.com/rogerclarkmelbourne/STM32duino-bootloader

This bootloader can be flashed via 3.3V serial with something like:

wget 'https://github.com/rogerclarkmelbourne/STM32duino-bootloader/raw/master/binaries/generic_boot20_pc13.bin'

stm32flash -w generic_boot20_pc13.bin -v -g 0 /dev/ttyAMA0

This bootloader uses 8KiB of flash space (the application must be
compiled with a start address of 8KiB). Flash an application with
something like:

dfu-util -d 1eaf:0003 -a 2 -R -D out/klipper.bin

The bootloader typically runs for only a short period after boot. It
may be necessary to time the above command so that it runs while the
bootloader is still active (the bootloader will flash a board led
while it is running). Alternatively, set the "boot 0" pin to low and
"boot 1" pin to high to stay in the bootloader after a reset.

STM32F103 with HID bootloader Copy Section

The HID bootloader is a
compact, driverless bootloader capable of flashing over USB. Also available
is a fork with builds specific to the SKR Mini E3 1.2.

For generic STM32F103 boards such as the blue pill it is possible to flash
the bootloader via 3.3V serial using stm32flash as noted in the stm32duino
section above, substituting the file name for the desired hid bootloader binary
(ie: hid_generic_pc13.bin for the blue pill).

It is not possible to use stm32flash for the SKR Mini E3 as the boot0 pin is
tied directly to ground and not broken out via header pins. It is recommended
to use a STLink V2 with STM32Cubeprogrammer to flash the bootloader. If you
don't have access to a STLink it is also possible to use a
Raspberry Pi and OpenOCD with
the following chip config:

source [find target/stm32f1x.cfg]

If you wish you can make a backup of the current flash with the following
command. Note that it may take some time to complete:

flash read_bank 0 btt_skr_mini_e3_backup.bin

finally, you can flash with commands similar to:

stm32f1x mass_erase 0
program hid_btt_skr_mini_e3.bin verify 0x08000000

NOTES:

• The example above erases the chip then programs the bootloader. Regardless
  of the method chosen to flash it is recommended to erase the chip prior to
  flashing.
• Prior flashing the SKR Mini E3 with this bootloader you should be aware
  that you will no longer be able to update firmware via the sdcard.
• You may need to hold down the reset button on the board while launching
  OpenOCD. It should display something like:
  text Copy

  Open On-Chip Debugger 0.10.0+dev-01204-gc60252ac-dirty (2020-04-27-16:00)
  Licensed under GNU GPL v2
  For bug reports, read
          http://openocd.org/doc/doxygen/bugs.html
  DEPRECATED! use 'adapter speed' not 'adapter_khz'
  Info : BCM2835 GPIO JTAG/SWD bitbang driver
  Info : JTAG and SWD modes enabled
  Info : clock speed 40 kHz
  Info : SWD DPIDR 0x1ba01477
  Info : stm32f1x.cpu: hardware has 6 breakpoints, 4 watchpoints
  Info : stm32f1x.cpu: external reset detected
  Info : starting gdb server for stm32f1x.cpu on 3333
  Info : Listening on port 3333 for gdb connections

  After which you can release the reset button.

This bootloader requires 2KiB of flash space (the application
must be compiled with a start address of 2KiB).

The hid-flash program is used to upload a binary to the bootloader. You
can install this software with the following commands:

sudo apt install libusb-1.0
cd ~/klipper/lib/hidflash
make

If the bootloader is running you can flash with something like:

~/klipper/lib/hidflash/hid-flash ~/klipper/out/klipper.bin

alternatively, you can use make flash to flash klipper directly:

make flash FLASH_DEVICE=1209:BEBA

OR if klipper has been previously flashed:

make flash FLASH_DEVICE=/dev/ttyACM0

It may be necessary to manually enter the bootloader, this can be done by
setting "boot 0" low and "boot 1" high. On the SKR Mini E3 "Boot 1" is
not available, so it may be done by setting pin PA2 low if you flashed
"hid_btt_skr_mini_e3.bin". This pin is labeled "TX0" on the TFT header in
the SKR Mini E3's "PIN" document. There is a ground pin next to PA2
which you can use to pull PA2 low.

STM32F103/STM32F072 with MSC bootloader Copy Section

The MSC bootloader is a driverless bootloader capable of flashing over USB.

It is possible to flash the bootloader via 3.3V serial using stm32flash as noted
in the stm32duino section above, substituting the file name for the desired
MSC bootloader binary (ie: MSCboot-Bluepill.bin for the blue pill).

For STM32F072 boards it is also possible to flash the bootloader over USB (via DFU)
with something like:

dfu-util -d 0483:df11 -a 0 -R -D  MSCboot-STM32F072.bin -s0x08000000:leave

This bootloader uses 8KiB or 16KiB of flash space, see description of the bootloader
(the application must be compiled with with the corresponding starting address).

The bootloader can be activated by pressing the reset button of the board twice.
As soon as the bootloader is activated, the board appears as a USB flash drive
onto which the klipper.bin file can be copied.

STM32F103/STM32F0x2 with CanBoot bootloader Copy Section

The CanBoot bootloader provides an option
for uploading Klipper firmware over the CANBUS. The bootloader itself is
derived from Klipper's source code. Currently CanBoot supports the STM32F103,
STM32F042, and STM32F072 models.

It is recommended to use a ST-Link Programmer to flash CanBoot, however it
should be possible to flash using stm32flash on STM32F103 devices, and
dfu-util on STM32F042/STM32F072 devices. See the previous sections in this
document for instructions on these flashing methods, substituting canboot.bin
for the file name where appropriate. The CanBoot repository linked above provides
instructions for building the bootloader.

The first time CanBoot has been flashed it should detect that no application
is present and enter the bootloader. If this doesn't occur it is possible to
enter the bootloader by pressing the reset button twice in succession.

The flashtool.py utility supplied in the lib/katapult folder may be used to
upload Klipper firmware. The device UUID is necessary to flash. If you do not
have a UUID it is possible to query nodes currently running the bootloader:

python3 flash_can.py -q

This will return UUIDs for all connected nodes not currently assigned a UUID.
This should include all nodes currently in the bootloader.

Once you have a UUID, you may upload firmware with following command:

python3 flash_can.py -i can0 -f ~/klipper/out/klipper.bin -u aabbccddeeff

Where aabbccddeeff is replaced by your UUID. Note that the -i and -f
options may be omitted, they default to can0 and ~/klipper/out/klipper.bin
respectively.

When building Klipper for use with CanBoot, select the 8 KiB Bootloader option.

STM32F4 micro-controllers (SKR Pro 1.1) Copy Chapter

STM32F4 micro-controllers come equipped with a built-in system bootloader
capable of flashing over USB (via DFU), 3.3V Serial, and various other
methods (see STM Document AN2606 for more information). Some
STM32F4 boards, such as the SKR Pro 1.1, are not able to enter the DFU
bootloader. The HID bootloader is available for STM32F405/407
based boards should the user prefer flashing over USB over using the sdcard.
Note that you may need to configure and build a version specific to your
board, a build for the SKR Pro 1.1 is available here.

Unless your board is DFU capable the most accessible flashing method
is likely via 3.3V serial, which follows the same procedure as
flashing the STM32F103 using stm32flash.
For example:

wget https://github.com/Arksine/STM32_HID_Bootloader/releases/download/v0.5-beta/hid_bootloader_SKR_PRO.bin

stm32flash -w hid_bootloader_SKR_PRO.bin -v -g 0 /dev/ttyAMA0

This bootloader requires 16Kib of flash space on the STM32F4 (the application
must be compiled with a start address of 16KiB).

As with the STM32F1, the STM32F4 uses the hid-flash tool to upload binaries to
the MCU. See the instructions above for details on how to build and use
hid-flash.

It may be necessary to manually enter the bootloader, this can be done by
setting "boot 0" low, "boot 1" high and plugging in the device. After
programming is complete unplug the device and set "boot 1" back to low
so the application will be loaded.

LPC176x micro-controllers (Smoothieboards) Copy Chapter

This document does not describe the method to flash a bootloader
itself - see:
http://smoothieware.org/flashing-the-bootloader
for further information on that topic.

It is common for Smoothieboards to come with a bootloader from:
https://github.com/triffid/LPC17xx-DFU-Bootloader.
When using this bootloader the application must be compiled with a
start address of 16KiB. The easiest way to flash an application with
this bootloader is to copy the application file (eg,
out/klipper.bin) to a file named firmware.bin on an SD card, and
then to reboot the micro-controller with that SD card.

Running OpenOCD on the Raspberry PI Copy Chapter

OpenOCD is a software package that can perform low-level chip flashing
and debugging. It can use the GPIO pins on a Raspberry Pi to
communicate with a variety of ARM chips.

This section describes how one can install and launch OpenOCD. It is
derived from the instructions at:
https://learn.adafruit.com/programming-microcontrollers-using-openocd-on-raspberry-pi

Begin by downloading and compiling the software (each step may take
several minutes and the "make" step may take 30+ minutes):

sudo apt-get update
sudo apt-get install autoconf libtool telnet
mkdir ~/openocd
cd ~/openocd/
git clone http://openocd.zylin.com/openocd
cd openocd
./bootstrap
./configure --enable-sysfsgpio --enable-bcm2835gpio --prefix=/home/pi/openocd/install
make
make install

Configure OpenOCD Copy Section

Create an OpenOCD config file:

nano ~/openocd/openocd.cfg

Use a config similar to the following:

# Uses RPi pins: GPIO25 for SWDCLK, GPIO24 for SWDIO, GPIO18 for nRST
source [find interface/raspberrypi2-native.cfg]
bcm2835gpio_swd_nums 25 24
bcm2835gpio_srst_num 18
transport select swd

# Use hardware reset wire for chip resets
reset_config srst_only
adapter_nsrst_delay 100
adapter_nsrst_assert_width 100

# Specify the chip type
source [find target/atsame5x.cfg]

# Set the adapter speed
adapter_khz 40

# Connect to chip
init
targets
reset halt

Wire the Raspberry Pi to the target chip Copy Section

Poweroff both the the Raspberry Pi and the target chip before wiring!
Verify the target chip uses 3.3V prior to connecting to a Raspberry
Pi!

Connect GND, SWDCLK, SWDIO, and RST on the target chip to GND, GPIO25,
GPIO24, and GPIO18 respectively on the Raspberry Pi.

Then power up the Raspberry Pi and provide power to the target chip.

Run OpenOCD Copy Section

Run OpenOCD:

cd ~/openocd/
sudo ~/openocd/install/bin/openocd -f ~/openocd/openocd.cfg

The above should cause OpenOCD to emit some text messages and then
wait (it should not immediately return to the Unix shell prompt). If
OpenOCD exits on its own or if it continues to emit text messages then
double check the wiring.

Once OpenOCD is running and is stable, one can send it commands via
telnet. Open another ssh session and run the following:

telnet 127.0.0.1 4444

(One can exit telnet by pressing ctrl+] and then running the "quit"
command.)

OpenOCD and gdb Copy Section

It is possible to use OpenOCD with gdb to debug Klipper. The following
commands assume one is running gdb on a desktop class machine.

Add the following to the OpenOCD config file:

bindto 0.0.0.0
gdb_port 44444

Restart OpenOCD on the Raspberry Pi and then run the following Unix
command on the desktop machine:

cd /path/to/klipper/
gdb out/klipper.elf

Within gdb run:

target remote octopi:44444

(Replace "octopi" with the host name of the Raspberry Pi.) Once gdb is
running it is possible to set breakpoints and to inspect registers.

CANBUS (`docs/CANBUS.md`) Copy Section

CANBUS

This document describes Klipper's CAN bus support.

Device Hardware Copy Chapter

Klipper currently supports CAN on stm32, SAME5x, and rp2040 chips. In
addition, the micro-controller chip must be on a board that has a CAN
transceiver.

To compile for CAN, run make menuconfig and select "CAN bus" as the
communication interface. Finally, compile the micro-controller code
and flash it to the target board.

Host Hardware Copy Chapter

In order to use a CAN bus, it is necessary to have a host adapter. It
is recommended to use a "USB to CAN adapter". There are many different
USB to CAN adapters available from different manufacturers. When
choosing one, we recommend verifying that the firmware can be updated
on it. (Unfortunately, we've found some USB adapters run defective
firmware and are locked down, so verify before purchasing.) Look for
adapters that can run Klipper directly (in its "USB to CAN bridge
mode") or that run the
candlelight firmware.

It is also necessary to configure the host operating system to use the
adapter. This is typically done by creating a new file named
/etc/network/interfaces.d/can0 with the following contents:

allow-hotplug can0
iface can0 can static
    bitrate 1000000
    up ip link set $IFACE txqueuelen 128

Terminating Resistors Copy Chapter

A CAN bus should have two 120 ohm resistors between the CANH and CANL
wires. Ideally, one resistor located at each the end of the bus.

Note that some devices have a builtin 120 ohm resistor that can not be
easily removed. Some devices do not include a resistor at all. Other
devices have a mechanism to select the resistor (typically by
connecting a "pin jumper"). Be sure to check the schematics of all
devices on the CAN bus to verify that there are two and only two 120
Ohm resistors on the bus.

To test that the resistors are correct, one can remove power to the
printer and use a multi-meter to check the resistance between the CANH
and CANL wires - it should report ~60 ohms on a correctly wired CAN
bus.

Finding the canbus_uuid for new micro-controllers Copy Chapter

Each micro-controller on the CAN bus is assigned a unique id based on
the factory chip identifier encoded into each micro-controller. To
find each micro-controller device id, make sure the hardware is
powered and wired correctly, and then run:

~/klippy-env/bin/python ~/klipper/scripts/canbus_query.py can0

If uninitialized CAN devices are detected the above command will
report lines like the following:

Found canbus_uuid=11aa22bb33cc, Application: Klipper

Each device will have a unique identifier. In the above example,
11aa22bb33cc is the micro-controller's "canbus_uuid".

Note that the canbus_query.py tool will only report uninitialized
devices - if Klipper (or a similar tool) configures the device then it
will no longer appear in the list.

Configuring Klipper Copy Chapter

Update the Klipper mcu configuration to use
the CAN bus to communicate with the device - for example:

[mcu my_can_mcu]
canbus_uuid: 11aa22bb33cc

USB to CAN bus bridge mode Copy Chapter

Some micro-controllers support selecting "USB to CAN bus bridge" mode
during Klipper's "make menuconfig". This mode may allow one to use a
micro-controller as both a "USB to CAN bus adapter" and as a Klipper
node.

When Klipper uses this mode the micro-controller appears as a "USB CAN
bus adapter" under Linux. The "Klipper bridge mcu" itself will appear
as if it was on this CAN bus - it can be identified via
canbus_query.py and it must be configured like other CAN bus Klipper
nodes.

Some important notes when using this mode:

• It is necessary to configure the can0 (or similar) interface in
  Linux in order to communicate with the bus. However, Linux CAN bus
  speed and CAN bus bit-timing options are ignored by Klipper.
  Currently, the CAN bus frequency is specified during "make
  menuconfig" and the bus speed specified in Linux is ignored.

• Whenever the "bridge mcu" is reset, Linux will disable the
  corresponding can0 interface. To ensure proper handling of
  FIRMWARE_RESTART and RESTART commands, it is recommended to use
  allow-hotplug in the /etc/network/interfaces.d/can0 file. For
  example:

allow-hotplug can0
iface can0 can static
    bitrate 1000000
    up ip link set $IFACE txqueuelen 128

• The "bridge mcu" is not actually on the CAN bus. Messages to and
  from the bridge mcu will not be seen by other adapters that may be
  on the CAN bus.

• The available bandwidth to both the "bridge mcu" itself and all
  devices on the CAN bus is effectively limited by the CAN bus
  frequency. As a result, it is recommended to use a CAN bus frequency
  of 1000000 when using "USB to CAN bus bridge mode".

• It is only valid to use USB to CAN bridge mode if there is a
  functioning CAN bus with at least one other node available (in
  addition to the bridge node itself). Use a standard USB
  configuration if the goal is to communicate only with the single USB
  device. Using USB to CAN bridge mode without a fully functioning CAN
  bus (including terminating resistors and an additional node) may
  result in sporadic errors even when communicating with the bridge
  node.

• A USB to CAN bridge board will not appear as a USB serial device, it
  will not show up when running ls /dev/serial/by-id, and it can not
  be configured in Klipper's printer.cfg file with a serial:
  parameter. The bridge board appears as a "USB CAN adapter" and it is
  configured in the printer.cfg as a CAN node.

Tips for troubleshooting Copy Chapter

See the CAN bus troubleshooting document.

CANBUS Troubleshooting (`docs/CANBUS_Troubleshooting.md`) Copy Section

CANBUS Troubleshooting

This document provides information on troubleshooting communication
issues when using Klipper with CAN bus.

Verify CAN bus wiring Copy Chapter

The first step in troubleshooting communication issues is to verify
the CAN bus wiring.

Be sure there are exactly two 120 Ohm terminating
resistors on the CAN bus. If the
resistors are not properly installed then messages may not be able to
be sent at all or the connection may have sporadic instability.

The CANH and CANL bus wiring should be twisted around each other. At a
minimum, the wiring should have a twist every few centimeters. Avoid
twisting the CANH and CANL wiring around power wires and ensure that
power wires that travel parallel to the CANH and CANL wires do not
have the same amount of twists.

Verify that all plugs and wire crimps on the CAN bus wiring are fully
secured. Movement of the printer toolhead may jostle the CAN bus
wiring causing a bad wire crimp or unsecured plug to result in
intermittent communication errors.

Check for incrementing bytes_invalid counter Copy Chapter

The Klipper log file will report a Stats line once a second when the
printer is active. These "Stats" lines will have a bytes_invalid
counter for each micro-controller. This counter should not increment
during normal printer operation (it is normal for the counter to be
non-zero after a RESTART and it is not a concern if the counter
increments once a month or so). If this counter increments on a CAN
bus micro-controller during normal printing (it increments every few
hours or more frequently) then it is an indication of a severe
problem.

Incrementing bytes_invalid on a CAN bus connection is a symptom of
reordered messages on the CAN bus. If seen, make sure to:

• Use a Linux kernel version 6.6.0 or later.
• If using a USB-to-CANBUS adapter running candlelight firmware, use
  v2.0 or later of candleLight_fw.
• If using Klipper's USB-to-CANBUS bridge mode, make sure the bridge
  node is flashed with Klipper v0.12.0 or later.

Reordered messages is a severe problem that must be fixed. It will
result in unstable behavior and can lead to confusing errors at any
part of a print. An incrementing bytes_invalid is not caused by
wiring or similar hardware issues and can only be fixed by identifying
and updating the faulty software.

Older versions of the Linux kernel had a bug in the gs_usb canbus
driver code that could cause reordered canbus packets. The issue is
thought to be fixed in
Linux commit 24bc41b4
which was released in v6.6.0. In some cases, older Linux versions may
not show the problem (due to how hardware interrupts are configured),
however if problems are seen the recommended solution is to upgrade to
a newer kernel.

Older versions of candlelight firmware could reorder canbus packets,
and the issue is thought to be fixed in
candlelight_fw commit 8b3a7b45.

Older versions of Klipper's USB-to-CANBUS bridge code could
incorrectly drop canbus messages. This is not as severe as reordering
messages, but it should still be fixed. It is thought to be fixed with
Klipper PR #6175.

Use an appropriate txqueuelen setting Copy Chapter

The Klipper code uses the Linux kernel to manage CAN bus traffic. By
default, the kernel will only queue 10 CAN transmit packets. It is
recommended to configure the can0 device
with a txqueuelen 128 to increase that size.

If Klipper transmits a packet and Linux has filled all of its transmit
queue space then Linux will drop that packet and messages like the
following will appear in the Klipper log:

Got error -1 in can write: (105)No buffer space available

Klipper will automatically retransmit the lost messages as part of its
normal application level message retransmit system. Thus, this log
message is a warning and it does not indicate an unrecoverable error.

If a complete CAN bus failure occurs (such as a CAN wire break) then
Linux will not be able to transmit any messages on the CAN bus and it
is common to find the above message in the Klipper log. In this case,
the log message is a symptom of a larger problem (the inability to
transmit any messages) and is not directly related to Linux
txqueuelen.

One may check the current queue size by running the Linux command ip link show can0. It should report a bunch of text including the
snippet qlen 128. If one sees something like qlen 10 then it
indicates the CAN device has not been properly configured.

It is not recommended to use a txqueuelen significantly larger
than 128. A CAN bus running at a frequency of 1000000 will typically
take around 120us to transmit a CAN packet. Thus a queue of 128
packets is likely to take around 15-20ms to drain. A substantially
larger queue could cause excessive spikes in message round-trip-time
which could lead to unrecoverable errors. Said another way, Klipper's
application retransmit system is more robust if it does not have to
wait for Linux to drain an excessively large queue of possibly stale
data. This is analogous to the problem of
bufferbloat on internet
routers.

Under normal circumstances Klipper may utilize ~25 queue slots per
MCU - typically only utilizing more slots during retransmits.
(Specifically, the Klipper host may transmit up to 192 bytes to each
Klipper MCU before receiving an acknowledgment from that MCU.) If a
single CAN bus has 5 or more Klipper MCUs on it, then it might be
necessary to increase the txqueuelen above the recommended value
of 128. However, as above, care should be taken when selecting a new
value to avoid excessive round-trip-time latency.

Use `canbus_query.py` only to identify nodes never previously seen Copy Chapter

It is only valid to use the
canbus_query.py tool
to identify micro-controllers that have never been previously
identified. Once all nodes on a bus are identified, record the
resulting uuids in the printer.cfg, and avoid running the tool
unnecessarily.

The tool is implemented using a low-level mechanism that can cause
nodes to internally observe bus errors. These internal errors may
result in communication interruptions and may result is some nodes
disconnecting from the bus.

It is not valid to use the tool to "ping" if a node is connected. Do
not run the tool during an active print.

Obtaining candump logs Copy Chapter

The CAN bus messages sent to and from the micro-controller are handled
by the Linux kernel. It is possible to capture these messages from the
kernel for debugging purposes. A log of these messages may be of use
in diagnostics.

The Linux can-utils tool
provides the capture software. It is typically installed on a machine
by running:

sudo apt-get update && sudo apt-get install can-utils

Once installed, one may obtain a capture of all CAN bus messages on an
interface with the following command:

candump -tz -Ddex can0,#FFFFFFFF > mycanlog

One can view the resulting log file (mycanlog in the example above)
to see each raw CAN bus message that was sent and received by Klipper.
Understanding the content of these messages will likely require
low-level knowledge of Klipper's CANBUS protocol
and Klipper's MCU commands.

Parsing Klipper messages in a candump log Copy Section

One may use the parsecandump.py tool to parse the low-level Klipper
micro-controller messages contained in a candump log. Using this tool
is an advanced topic that requires knowledge of Klipper
MCU commands. For example:

./scripts/parsecandump.py mycanlog 108 ./out/klipper.dict

This tool produces output similar to the parsedump
tool. See
the documentation for that tool for information on generating the
Klipper micro-controller data dictionary.

In the above example, 108 is the CAN bus
id. It is a
hexadecimal number. The id 108 is assigned by Klipper to the first
micro-controller. If the CAN bus has multiple micro-controllers on it,
then the second micro-controller would be 10a, the third would be
10c, and so on.

The candump log must be produced using the -tz -Ddex command-line
arguments (for example: candump -tz -Ddex can0,#FFFFFFFF) in order
to use the parsecandump.py tool.

Using a logic analyzer on the canbus wiring Copy Chapter

The Sigrok Pulseview software
along with a low-cost
logic analyzer can be
useful for diagnosing CAN bus signaling. This is an advanced topic
likely only of interest to experts.

One can often find "USB logic analyzers" for under $15 (US pricing as
of 2023). These devices are often listed as "Saleae logic clones" or
as "24MHz 8 channel USB logic analyzers".

The above picture was taken while using Pulseview with a "Saleae
clone" logic analyzer. The Sigrok and Pulseview software was installed
on a desktop machine (also install the "fx2lafw" firmware if that is
packaged separately). The CH0 pin on the logic analyzer was routed to
the CAN Rx line, the CH1 pin was wired to the CAN Tx pin, and GND was
wired to GND. Pulseview was configured to only display the D0 and D1
lines (red "probe" icon center top toolbar). The number of samples was
set to 5 million (top toolbar) and the sample rate was set to 24Mhz
(top toolbar). The CAN decoder was added (yellow and green "bubble
icon" right top toolbar). The D0 channel was labeled as RX and set to
trigger on a falling edge (click on black D0 label at left). The D1
channel was labeled as TX (click on brown D1 label at left). The CAN
decoder was configured for 1Mbit rate (click on green CAN label at
left). The CAN decoder was moved to the top of the display (click and
drag green CAN label). Finally, the capture was started (click "Run"
at top left) and a packet was transmitted on the CAN bus (cansend can0 123#121212121212).

The logic analyzer provides an independent tool for capturing packets
and verifying bit timing.

CANBUS Protocol (`docs/CANBUS_protocol.md`) Copy Section

CANBUS protocol

This document describes the protocol Klipper uses to communicate over
CAN bus. See
CANBUS.md for information on configuring Klipper with CAN
bus.

Micro-controller id assignment Copy Chapter

Klipper uses only CAN 2.0A standard size CAN bus packets, which are
limited to 8 data bytes and an 11-bit CAN bus identifier. In order to
support efficient communication, each micro-controller is assigned at
run-time a unique 1-byte CAN bus nodeid (canbus_nodeid) for general
Klipper command and response traffic. Klipper command messages going
from host to micro-controller use the CAN bus id of canbus_nodeid * 2 + 256, while Klipper response messages from micro-controller to
host use canbus_nodeid * 2 + 256 + 1.

Each micro-controller has a factory assigned unique chip identifier
that is used during id assignment. This identifier can exceed the
length of one CAN packet, so a hash function is used to generate a
unique 6-byte id (canbus_uuid) from the factory id.

Admin messages Copy Chapter

Admin messages are used for id assignment. Admin messages sent from
host to micro-controller use the CAN bus id 0x3f0 and messages sent
from micro-controller to host use the CAN bus id 0x3f1. All
micro-controllers listen to messages on id 0x3f0; that id can be
thought of as a "broadcast address".

CMD_QUERY_UNASSIGNED message Copy Section

This command queries all micro-controllers that have not yet been
assigned a canbus_nodeid. Unassigned micro-controllers will respond
with a RESP_NEED_NODEID response message.

The CMD_QUERY_UNASSIGNED message format is:
<1-byte message_id = 0x00>

CMD_SET_KLIPPER_NODEID message Copy Section

This command assigns a canbus_nodeid to the micro-controller with a
given canbus_uuid.

The CMD_SET_KLIPPER_NODEID message format is:
<1-byte message_id = 0x01><6-byte canbus_uuid><1-byte canbus_nodeid>

RESP_NEED_NODEID message Copy Section

The RESP_NEED_NODEID message format is:
<1-byte message_id = 0x20><6-byte canbus_uuid><1-byte set_klipper_nodeid = 0x01>

Data Packets Copy Chapter

A micro-controller that has been assigned a nodeid via the
CMD_SET_KLIPPER_NODEID command can send and receive data packets.

The packet data in messages using the node's receive CAN bus id
(canbus_nodeid * 2 + 256) are simply appended to a buffer, and when
a complete mcu protocol message is found its contents
are parsed and processed. The data is treated as a byte stream - there
is no requirement for the start of a Klipper message block to align
with the start of a CAN bus packet.

Similarly, mcu protocol message responses are sent from
micro-controller to host by copying the message data into one or more
packets with the node's transmit CAN bus id (canbus_nodeid * 2 + 256 + 1).

CONTRIBUTING (`docs/CONTRIBUTING.md`) Copy Section

Contributing to Klipper

Thank you for contributing to Klipper! This document describes the
process for contributing changes to Klipper.

Please see the contact page for information on reporting
an issue or for details on contacting the developers.

Overview of Contribution Process Copy Chapter

Contributions to Klipper generally follow a high-level process:

1. A submitter starts by creating a
   GitHub Pull Request
   when a submission is ready for widespread deployment.
2. When a reviewer is available to
   review the submission, they will
   assign themselves to the Pull Request on GitHub. The goal of the
   review is to look for defects and to check that the submission
   follows documented guidelines.
3. After a successful review, the reviewer will "approve the review"
   on GitHub and a maintainer will commit the change to
   the Klipper master branch.

When working on enhancements, consider starting (or contributing to) a
topic on Klipper Discourse. An ongoing discussion on the
forum can improve visibility of development work and may attract
others interested in testing new work.

What to expect in a review Copy Chapter

Contributions to Klipper are reviewed before merging. The primary goal
of the review process is to check for defects and to check that the
submission follows guidelines specified in the Klipper documentation.

It is understood that there are many ways to accomplish a task; it is
not the intent of the review to discuss the "best" implementation.
Where possible, review discussions focused on facts and measurements
are preferable.

The majority of submissions will result in feedback from a review. Be
prepared to obtain feedback, provide further details, and to update
the submission if needed.

Common things a reviewer will look for:

1. Is the submission free of defects and is it ready to be widely
   deployed?

   Submitters are expected to test their changes prior to submission.
   The reviewers look for errors, but they don't, in general, test
   submissions. An accepted submission is often deployed to thousands
   of printers within a few weeks of acceptance. Quality of
   submissions is therefore considered a priority.

   The main Klipper3d/klipper
   GitHub repository does not accept experimental work. Submitters
   should perform experimentation, debugging, and testing in their own
   repositories. The Klipper Discourse server is a good
   place to raise awareness of new work and to find users interested
   in providing real-world feedback.

   Submissions must pass all regression test cases.

   When fixing a defect in the code, submitters should have a general
   understanding of the root cause of that defect, and the fix should
   target that root cause.

   Code submissions should not contain excessive debugging code,
   debugging options, nor run-time debug logging.

   Comments in code submissions should focus on enhancing code
   maintenance. Submissions should not contain "commented out code"
   nor excessive comments describing past implementations. There
   should not be excessive "todo" comments.

   Updates to documentation should not declare that they are a "work
   in progress".

2. Does the submission provide a "high impact" benefit to real-world
   users performing real-world tasks?

   Reviewers need to identify, at least in their own minds, roughly
   "who the target audience is", a rough scale of "the size of that
   audience", the "benefit" they will obtain, how the "benefit is
   measured", and the "results of those measurement tests". In most
   cases this will be obvious to both the submitter and the reviewer,
   and it is not explicitly stated during a review.

   Submissions to the master Klipper branch are expected to have a
   noteworthy target audience. As a general "rule of thumb",
   submissions should target a user base of at least a 100 real-world
   users.

   If a reviewer asks for details on the "benefit" of a submission,
   please don't consider it criticism. Being able to understand the
   real-world benefits of a change is a natural part of a review.

   When discussing benefits it is preferable to discuss "facts and
   measurements". In general, reviewers are not looking for responses
   of the form "someone may find option X useful", nor are they
   looking for responses of the form "this submission adds a feature
   that firmware X implements". Instead, it is generally preferable to
   discuss details on how the quality improvement was measured and
   what were the results of those measurements - for example, "tests
   on Acme X1000 printers show improved corners as seen in picture
   ...", or for example "print time of real-world object X on a
   Foomatic X900 printer went from 4 hours to 3.5 hours". It is
   understood that testing of this type can take significant time and
   effort. Some of Klipper's most notable features took months of
   discussion, rework, testing, and documentation prior to being
   merged into the master branch.

   All new modules, config options, commands, command parameters, and
   documents should have "high impact". We do not want to burden users
   with options that they can not reasonably configure nor do we want
   to burden them with options that don't provide a notable benefit.

   A reviewer may ask for clarification on how a user is to configure
   an option - an ideal response will contain details on the process -
   for example, "users of the MegaX500 are expected to set option X to
   99.3 while users of the Elite100Y are expected to calibrate option
   X using procedure ...".

   If the goal of an option is to make the code more modular then
   prefer using code constants instead of user facing config options.

   New modules, new options, and new parameters should not provide
   similar functionality to existing modules - if the differences are
   arbitrary than it's preferable to utilize the existing system or
   refactor the existing code.

3. Is the copyright of the submission clear, non-gratuitous, and
   compatible?

   New C files and Python files should have an unambiguous copyright
   statement. See the existing files for the preferred format.
   Declaring a copyright on an existing file when making minor changes
   to that file is discouraged.

   Code taken from 3rd party sources must be compatible with the
   Klipper license (GNU GPLv3). Large 3rd party code additions should
   be added to the lib/ directory (and follow the format described
   in lib/README).

   Submitters must provide a
   Signed-off-by line using their full
   real name. It indicates the submitter agrees with the
   developer certificate of origin.

4. Does the submission follow guidelines specified in the Klipper
   documentation?

   In particular, code should follow the guidelines in
   Code_Overview.md and config files should follow
   the guidelines in Example_Configs.md.

5. Is the Klipper documentation updated to reflect new changes?

   At a minimum, the reference documentation must be updated with
   corresponding changes to the code:

   • All commands and command parameters must be documented in
     G-Codes.md.
   • All user facing modules and their config parameters must be
     documented in Config_Reference.md.
   • All exported "status variables" must be documented in
     Status_Reference.md.
   • All new "webhooks" and their parameters must be documented in
     API_Server.md.
   • Any change that makes a non-backwards compatible change to a
     command or config file setting must be documented in
     Config_Changes.md.

   New documents should be added to Overview.md and be
   added to the website index
   docs/_klipper3d/mkdocs.yml.

6. Are commits well formed, address a single topic per commit, and
   independent?

   Commit messages should follow the
   preferred format.

   Commits must not have a merge conflict. New additions to the
   Klipper master branch are always done via a "rebase" or "squash and
   rebase". It is generally not necessary for submitters to re-merge
   their submission on every update to the Klipper master repository.
   However, if there is a merge conflict, then submitters are
   recommended to use git rebase to address the conflict.

   Each commit should address a single high-level change. Large
   changes should be broken up into multiple independent commits. Each
   commit should "stand on its own" so that tools like git bisect
   and git revert work reliably.

   Whitespace changes should not be mixed with functional changes. In
   general, gratuitous whitespace changes are not accepted unless they
   are from the established "owner" of the code being modified.

Klipper does not implement a strict "coding style guide", but
modifications to existing code should follow the high-level code flow,
code indentation style, and format of that existing code. Submissions
of new modules and systems have more flexibility in coding style, but
it is preferable for that new code to follow an internally consistent
style and to generally follow industry wide coding norms.

It is not a goal of a review to discuss "better implementations".
However, if a reviewer struggles to understand the implementation of a
submission, then they may ask for changes to make the implementation
more transparent. In particular, if reviewers can not convince
themselves that a submission is free of defects then changes may be
necessary.

As part of a review, a reviewer may create an alternate Pull Request
for a topic. This may be done to avoid excessive "back and forth" on
minor procedural items and thus streamline the submission process. It
may also be done because the discussion inspires a reviewer to build
an alternative implementation. Both situations are a normal result of
a review and should not be considered criticism of the original
submission.

Helping with reviews Copy Section

We appreciate help with reviews! It is not necessary to be a
listed reviewer to perform a review. Submitters of
GitHub Pull Requests are also encouraged to review their own
submissions.

To help with a review, follow the steps outlined in
what to expect in a review to verify
the submission. After completing the review, add a comment to the
GitHub Pull Request with your findings. If the submission passes the
review then please state that explicitly in the comment - for example
something like "I reviewed this change according to the steps in the
CONTRIBUTING document and everything looks good to me". If unable to
complete some steps in the review then please explicitly state which
steps were reviewed and which steps were not reviewed - for example
something like "I didn't check the code for defects, but I reviewed
everything else in the CONTRIBUTING document and it looks good".

We also appreciate testing of submissions. If the code was tested then
please add a comment to the GitHub Pull Request with the results of
your test - success or failure. Please explicitly state that the code
was tested and the results - for example something like "I tested this
code on my Acme900Z printer with a vase print and the results were
good".

Reviewers Copy Section

The Klipper "reviewers" are:

Please do not "ping" any of the reviewers and please do not direct
submissions at them. All of the reviewers monitor the forums and PRs,
and will take on reviews when they have time to.

The Klipper "maintainers" are:

Format of commit messages Copy Chapter

Each commit should have a commit message formatted similar to the
following:

module: Capitalized, short (50 chars or less) summary

More detailed explanatory text, if necessary.  Wrap it to about 75
characters or so.  In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body.  The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.

Further paragraphs come after blank lines..

Signed-off-by: My Name <[email protected]>

In the above example, module should be the name of a file or
directory in the repository (without a file extension). For example,
clocksync: Fix typo in pause() call at connect time. The purpose of
specifying a module name in the commit message is to help provide
context for the commit comments.

It is important to have a "Signed-off-by" line on each commit - it
certifies that you agree to the
developer certificate of origin. It
must contain your real name (sorry, no pseudonyms or anonymous
contributions) and contain a current email address.

Contributing to Klipper Translations Copy Chapter

Klipper-translations Project
is a project dedicated to translating Klipper to different languages.
Weblate hosts all the
Gettext strings for translating and reviewing. Locales can be displayed on
klipper3d.org once they satisfy the following requirements:

• 75% Total coverage
• All titles (H1) are translated
• An updated navigation hierarchy PR in klipper-translations.

To reduce the frustration of translating domain-specific terms and
gain awareness of the ongoing translations, you can submit a PR
modifying the
Klipper-translations Project
readme.md. Once a translation is ready, the corresponding
modification to the Klipper project can be made.

If a translation already exists in the Klipper repository and no
longer meets the checklist above, it will be marked out-of-date after
a month without updates.

Once the requirements are met, you need to:

1. update klipper-translations repository
   active_translations
2. Optional: add a manual-index.md file in klipper-translations repository's
   docs\locals\<lang> folder to replace the language specific index.md (generated
   index.md does not render correctly).

Known Issues:

1. Currently, there isn't a method for correctly translating pictures in
   the documentation
2. It is impossible to translate titles in mkdocs.yml.

Command Templates (`docs/Command_Templates.md`) Copy Section

Commands templates

This document provides information on implementing G-Code command
sequences in gcode_macro (and similar) config sections.

G-Code Macro Naming Copy Chapter

Case is not important for the G-Code macro name - MY_MACRO and
my_macro will evaluate the same and may be called in either upper or
lower case. If any numbers are used in the macro name then they must
all be at the end of the name (eg, TEST_MACRO25 is valid, but
MACRO25_TEST3 is not).

Formatting of G-Code in the config Copy Chapter

Indentation is important when defining a macro in the config file. To
specify a multi-line G-Code sequence it is important for each line to
have proper indentation. For example:

[gcode_macro blink_led]
gcode:
  SET_PIN PIN=my_led VALUE=1
  G4 P2000
  SET_PIN PIN=my_led VALUE=0

Note how the gcode: config option always starts at the beginning of
the line and subsequent lines in the G-Code macro never start at the
beginning.

Add a description to your macro Copy Chapter

To help identify the functionality a short description can be added.
Add description: with a short text to describe the functionality.
Default is "G-Code macro" if not specified.
For example:

[gcode_macro blink_led]
description: Blink my_led one time
gcode:
  SET_PIN PIN=my_led VALUE=1
  G4 P2000
  SET_PIN PIN=my_led VALUE=0

The terminal will display the description when you use the HELP command or the autocomplete function.

Save/Restore state for G-Code moves Copy Chapter

Unfortunately, the G-Code command language can be challenging to use.
The standard mechanism to move the toolhead is via the G1 command
(the G0 command is an alias for G1 and it can be used
interchangeably with it). However, this command relies on the "G-Code
parsing state" setup by M82, M83, G90, G91, G92, and
previous G1 commands. When creating a G-Code macro it is a good
idea to always explicitly set the G-Code parsing state prior to
issuing a G1 command. (Otherwise, there is a risk the G1 command
will make an undesirable request.)

A common way to accomplish that is to wrap the G1 moves in
SAVE_GCODE_STATE, G91, and RESTORE_GCODE_STATE. For example:

[gcode_macro MOVE_UP]
gcode:
  SAVE_GCODE_STATE NAME=my_move_up_state
  G91
  G1 Z10 F300
  RESTORE_GCODE_STATE NAME=my_move_up_state

The G91 command places the G-Code parsing state into "relative move
mode" and the RESTORE_GCODE_STATE command restores the state to what
it was prior to entering the macro. Be sure to specify an explicit
speed (via the F parameter) on the first G1 command.

Template expansion Copy Chapter

The gcode_macro gcode: config section is evaluated using the Jinja2
template language. One can evaluate expressions at run-time by
wrapping them in { } characters or use conditional statements
wrapped in {% %}. See the
Jinja2 documentation
for further information on the syntax.

An example of a complex macro:

[gcode_macro clean_nozzle]
gcode:
  {% set wipe_count = 8 %}
  SAVE_GCODE_STATE NAME=clean_nozzle_state
  G90
  G0 Z15 F300
  {% for wipe in range(wipe_count) %}
    {% for coordinate in [(275, 4),(235, 4)] %}
      G0 X{coordinate[0]} Y{coordinate[1] + 0.25 * wipe} Z9.7 F12000
    {% endfor %}
  {% endfor %}
  RESTORE_GCODE_STATE NAME=clean_nozzle_state

Macro parameters Copy Section

It is often useful to inspect parameters passed to the macro when
it is called. These parameters are available via the params
pseudo-variable. For example, if the macro:

[gcode_macro SET_PERCENT]
gcode:
  M117 Now at { params.VALUE|float * 100 }%

were invoked as SET_PERCENT VALUE=.2 it would evaluate to M117 Now at 20%. Note that parameter names are always in upper-case when
evaluated in the macro and are always passed as strings. If performing
math then they must be explicitly converted to integers or floats.

It's common to use the Jinja2 set directive to use a default
parameter and assign the result to a local name. For example:

[gcode_macro SET_BED_TEMPERATURE]
gcode:
  {% set bed_temp = params.TEMPERATURE|default(40)|float %}
  M140 S{bed_temp}

The "rawparams" variable Copy Section

The full unparsed parameters for the running macro can be access via the
rawparams pseudo-variable.

Note that this will include any comments that were part of the original command.

See the sample-macros.cfg file for an example
showing how to override the M117 command using rawparams.

The "printer" Variable Copy Section

It is possible to inspect (and alter) the current state of the printer
via the printer pseudo-variable. For example:

[gcode_macro slow_fan]
gcode:
  M106 S{ printer.fan.speed * 0.9 * 255}

Available fields are defined in the
Status Reference document.

Important! Macros are first evaluated in entirety and only then are
the resulting commands executed. If a macro issues a command that
alters the state of the printer, the results of that state change will
not be visible during the evaluation of the macro. This can also
result in subtle behavior when a macro generates commands that call
other macros, as the called macro is evaluated when it is invoked
(which is after the entire evaluation of the calling macro).

By convention, the name immediately following printer is the name of
a config section. So, for example, printer.fan refers to the fan
object created by the [fan] config section. There are some
exceptions to this rule - notably the gcode_move and toolhead
objects. If the config section contains spaces in it, then one can
access it via the [ ] accessor - for example:
printer["generic_heater my_chamber_heater"].temperature.

Note that the Jinja2 set directive can assign a local name to an
object in the printer hierarchy. This can make macros more readable
and reduce typing. For example:

[gcode_macro QUERY_HTU21D]
gcode:
    {% set sensor = printer["htu21d my_sensor"] %}
    M117 Temp:{sensor.temperature} Humidity:{sensor.humidity}

Actions Copy Chapter

There are some commands available that can alter the state of the
printer. For example, { action_emergency_stop() } would cause the
printer to go into a shutdown state. Note that these actions are taken
at the time that the macro is evaluated, which may be a significant
amount of time before the generated g-code commands are executed.

Available "action" commands:

• action_respond_info(msg): Write the given msg to the
  /tmp/printer pseudo-terminal. Each line of msg will be sent with a
  "// " prefix.
• action_raise_error(msg): Abort the current macro (and any calling
  macros) and write the given msg to the /tmp/printer
  pseudo-terminal. The first line of msg will be sent with a "!! "
  prefix and subsequent lines will have a "// " prefix.
• action_emergency_stop(msg): Transition the printer to a shutdown
  state. The msg parameter is optional, it may be useful to describe
  the reason for the shutdown.
• action_call_remote_method(method_name): Calls a method registered
  by a remote client. If the method takes parameters they should
  be provided via keyword arguments, ie:
  action_call_remote_method("print_stuff", my_arg="hello_world")

Variables Copy Chapter

The SET_GCODE_VARIABLE command may be useful for saving state between
macro calls. Variable names may not contain any upper case characters.
For example:

[gcode_macro start_probe]
variable_bed_temp: 0
gcode:
  # Save target temperature to bed_temp variable
  SET_GCODE_VARIABLE MACRO=start_probe VARIABLE=bed_temp VALUE={printer.heater_bed.target}
  # Disable bed heater
  M140
  # Perform probe
  PROBE
  # Call finish_probe macro at completion of probe
  finish_probe

[gcode_macro finish_probe]
gcode:
  # Restore temperature
  M140 S{printer["gcode_macro start_probe"].bed_temp}

Be sure to take the timing of macro evaluation and command execution
into account when using SET_GCODE_VARIABLE.

Delayed Gcodes Copy Chapter

The [delayed_gcode] configuration option can be used to execute a delayed
gcode sequence:

[delayed_gcode clear_display]
gcode:
  M117

[gcode_macro load_filament]
gcode:
 G91
 G1 E50
 G90
 M400
 M117 Load Complete!
 UPDATE_DELAYED_GCODE ID=clear_display DURATION=10

When the load_filament macro above executes, it will display a
"Load Complete!" message after the extrusion is finished. The
last line of gcode enables the "clear_display" delayed_gcode, set
to execute in 10 seconds.

The initial_duration config option can be set to execute the
delayed_gcode on printer startup. The countdown begins when the
printer enters the "ready" state. For example, the below delayed_gcode
will execute 5 seconds after the printer is ready, initializing
the display with a "Welcome!" message:

[delayed_gcode welcome]
initial_duration: 5.
gcode:
  M117 Welcome!

Its possible for a delayed gcode to repeat by updating itself in
the gcode option:

[delayed_gcode report_temp]
initial_duration: 2.
gcode:
  {action_respond_info("Extruder Temp: %.1f" % (printer.extruder0.temperature))}
  UPDATE_DELAYED_GCODE ID=report_temp DURATION=2

The above delayed_gcode will send "// Extruder Temp: [ex0_temp]" to
Octoprint every 2 seconds. This can be canceled with the following
gcode:

UPDATE_DELAYED_GCODE ID=report_temp DURATION=0

Menu templates Copy Chapter

If a display config section is enabled,
then it is possible to customize the menu with
menu config sections.

The following read-only attributes are available in menu templates:

• menu.width - element width (number of display columns)
• menu.ns - element namespace
• menu.event - name of the event that triggered the script
• menu.input - input value, only available in input script context

The following actions are available in menu templates:

• menu.back(force, update): will execute menu back command, optional
  boolean parameters <force> and ``.
  • When <force> is set True then it will also stop editing. Default
    value is False.
  • When `` is set False then parent container items are not
    updated. Default value is True.
• menu.exit(force) - will execute menu exit command, optional
  boolean parameter <force> default value False.
  • When <force> is set True then it will also stop editing. Default
    value is False.

Save Variables to disk Copy Chapter

If a
save_variables config section
has been enabled, SAVE_VARIABLE VARIABLE=<name> VALUE=<value> can be
used to save the variable to disk so that it can be used across
restarts. All stored variables are loaded into the
printer.save_variables.variables dict at startup and can be used in
gcode macros. to avoid overly long lines you can add the following at
the top of the macro:

{% set svv = printer.save_variables.variables %}

As an example, it could be used to save the state of 2-in-1-out hotend
and when starting a print ensure that the active extruder is used,
instead of T0:

[gcode_macro T1]
gcode:
  ACTIVATE_EXTRUDER extruder=extruder1
  SAVE_VARIABLE VARIABLE=currentextruder VALUE='"extruder1"'

[gcode_macro T0]
gcode:
  ACTIVATE_EXTRUDER extruder=extruder
  SAVE_VARIABLE VARIABLE=currentextruder VALUE='"extruder"'

[gcode_macro START_GCODE]
gcode:
  {% set svv = printer.save_variables.variables %}
  ACTIVATE_EXTRUDER extruder={svv.currentextruder}

Config Changes (`docs/Config_Changes.md`) Copy Section

Configuration Changes

This document covers recent software changes to the config file that
are not backwards compatible. It is a good idea to review this
document when upgrading the Klipper software.

All dates in this document are approximate.

Changes Copy Chapter

20260915: Support for the TEMPERATURE_PROBE_CALIBRATE METHOD=tap
parameter has been removed. Use
TEMPERATURE_PROBE_CALIBRATE MANUAL_METHOD=tap instead.

20260525: The internal implementation of "probe:z_virtual_endstop" has
changed. Most users will not observe a change in behavior. Previously
it was technically possible to mix "probe:z_virtual_endstop" with
other types of Z endstops and this behavior is no longer valid.

20260501: The handling of the [probe_eddy_current] tap_threshold
config option and associated TAP_THRESHOLD G-Code parameter has
changed. It will be necessary to recalibrate the value. See the
eddy probe documentation for calibration directions.

20260408: The script lib/canboot/flash_can.py has been updated to
the most current version from
Katapult and as such renamed to
lib/katapult/flashtool.py. If you call this script directly instead
of using the existing Makefiles, you will need to change the path to
the script to lib/katapult/flashtool.py.

20260318: The [probe_eddy_current] config options speed,
lift_speed, samples, sample_retract_dist, samples_result,
samples_tolerance, and samples_tolerance_retries no longer apply
to probe commands using METHOD=scan, METHOD=rapid_scan, nor
METHOD=tap. To use different settings, supply the equivalent
PROBE_SPEED, LIFT_SPEED, SAMPLES, SAMPLE_RETRACT_DIST,
SAMPLES_RESULT, SAMPLES_TOLERANCE, or SAMPLES_TOLERANCE_RETRIES
parameter with the probe command.

20260318: The [probe_eddy_current] config option z_offset has been
renamed to descend_z. Using the old name is deprecated and it will
be removed in the near future.

20260214: The MANUAL_STEPPER G-Code command STOP_ON_ENDSTOP
parameter has changed. See the
MANUAL_STEPPER documentation for
details. Using the previous integer values (-2, -1, 1, 2) is
deprecated and support will be removed in the near future.

20260207: The low-level i2c behavior of sx1509 and uc1701 devices has
changed. Previously an i2c error would result in a shutdown, and now
i2c errors when communicating with these devices will only generate
warnings in the log file.

20260109: The status value {printer.probe.last_z_result} is
deprecated; it will be removed in the near future. Use
{printer.probe.last_probe_position} instead, and note that this new
value already has the probe's configured xyz offsets applied.

20260109: The g-code console text output from the PROBE,
PROBE_ACCURACY, and similar commands has changed. Now Z heights are
reported relative to the nominal bed Z position instead of relative to
the probe's configured z_offset. Similarly, intermediate probe x and
y console reports will also have the probe's configured x_offset and
y_offset applied.

20260109: The [screws_tilt_adjust] module now reports the status
variable {printer.screws_tilt_adjust.result.screw1.z} with the
probe's z_offset applied. That is, one would previously need to
subtract the probe's configured z_offset to find the absolute Z
deviation at the given screw location and now one must not apply the
z_offset.

20251122: An option axis has been added to [carriage <name>]
sections for generic_cartesian kinematics, allowing arbitrary names
for primary carriages. Users are encouraged to explicitly specify
axis option now.

20251106: The status fields {printer.toolhead.position},
{printer.gcode_move.position},
{printer.gcode_move.gcode_position}, and
{printer.motion_report.live_position} are changing. These
coordinates used to always contain four components, but now may
contain additional components. The ordering and number of components
may change at run-time - see the
status reference for
important details. Accessing any of these coordinates in macros using
the ".e" accessor is deprecated - use something like
{printer.toolhead.position[printer.gcode_move.axis_map.E]} as an
alternative.

20251106: The status fields {printer.gcode_move.homing_origin},
{printer.toolhead.axis_min}, and {printer.toolhead.axis_max}
currently contain four components where the fourth component is always
zero. This behavior is deprecated. In the future these coordinates may
contain only three components. For additional information see the
status reference.

20251010: During normal printing the command processing will now
attempt to stay one second ahead of printer movement (reduced from two
seconds previously).

20251003: Support for the undocumented max_stepper_error option in
the [printer] config section has been removed.

20250916: The definitions of EI, 2HUMP_EI, and 3HUMP_EI input shapers
were updated. For best performance it is recommended to recalibrate
input shapers, especially if some of these shapers are currently used.

20250811: Support for the max_accel_to_decel parameter in the
[printer] config section has been removed and support for the
ACCEL_TO_DECEL parameter in the SET_VELOCITY_LIMIT command has
been removed. These capabilities were deprecated on 20240313.

20250721: The [pca9632] and [mcp4018] modules no longer accept the
scl_pin and sda_pin options. Use i2c_software_scl_pin and
i2c_software_sda_pin instead.

20250428: The maximum cycle_time for pwm [output_pin],
[pwm_cycle_time], [pwm_tool], and similar config sections is now 3
seconds (reduced from 5 seconds). The maximum_mcu_duration in
[pwm_tool] is now also 3 seconds.

20250418: The manual_stepper STOP_ON_ENDSTOP feature may now take
less time to complete. Previously, the command would wait the entire
time the move could possibly take even if the endstop triggered
earlier. Now, the command finishes shortly after the endstop trigger.

20250417: SPI devices using "software SPI" are now rate limited.
Previously, the spi_speed in the config was ignored and the
transmission speed was only limited by the processing speed of the
micro-controller. Now, speeds are limited by the spi_speed config
parameter (actual hardware speeds are likely to be lower than the
configured value due to software overhead).

20250411: Klipper v0.13.0 released.

20250308: The AUTO parameter of the
AXIS_TWIST_COMPENSATION_CALIBRATE command has been removed.

20250131: Option VARIABLE=<name> in SAVE_VARIABLE requires lowercase
value. For example, extruder instead of mixedcase Extruder or
uppercase EXTRUDER. Using any uppercase letter will raise an error.

20241203: The resonance test has been changed to include slow sweeping
moves. This change requires that testing point(s) have some clearance
in X/Y plane (+/- 30 mm from the test point should suffice when using
the default settings). The new test should generally produce more
accurate and reliable test results. However, if required, the previous
test behavior can be restored by adding options sweeping_period: 0 and
accel_per_hz: 75 to the [resonance_tester] config section.

20241201: In some cases Klipper may have ignored leading characters or
spaces in a traditional G-Code command. For example, "99M123" may have
been interpreted as "M123" and "M 321" may have been interpreted as
"M321". Klipper will now report these cases with an "Unknown command"
warning.

20241112: Option CHIPS=<chip_name> in TEST_RESONANCES and
SHAPER_CALIBRATE requires specifying the full name(s) of the accel
chip(s). For example, adxl345 rpi instead of short name - rpi.

20240912: SET_PIN, SET_SERVO, SET_FAN_SPEED, M106, and M107
commands are now collated. Previously, if many updates to the same
object were issued faster than the minimum scheduling time (typically
100ms) then actual updates could be queued far into the future. Now if
many updates are issued in rapid succession then it is possible that
only the latest request will be applied. If the previous behavior is
required then consider adding explicit G4 delay commands between
updates.

20240912: Support for maximum_mcu_duration and static_value
parameters in [output_pin] config sections have been removed. These
options have been deprecated since 20240123.

20240415: The on_error_gcode parameter in the [virtual_sdcard]
config section now has a default. If this parameter is not specified
it now defaults to TURN_OFF_HEATERS. If the previous behavior is
desired (take no default action on an error during a virtual_sdcard
print) then define on_error_gcode with an empty value.

20240313: The max_accel_to_decel parameter in the [printer] config
section has been deprecated. The ACCEL_TO_DECEL parameter of the
SET_VELOCITY_LIMIT command has been deprecated. The
printer.toolhead.max_accel_to_decel status has been removed. Use the
minimum_cruise_ratio parameter
instead. The deprecated features will be removed in the near future,
and using them in the interim may result in subtly different behavior.

20240215: Several deprecated features have been removed. Using "NTC
100K beta 3950" as a thermistor name has been removed (deprecated on
20211110). The SYNC_STEPPER_TO_EXTRUDER and
SET_EXTRUDER_STEP_DISTANCE commands have been removed, and the
extruder shared_heater config option has been removed (deprecated on
20220210). The bed_mesh relative_reference_index option has been
removed (deprecated on 20230619).

20240123: The output_pin SET_PIN CYCLE_TIME parameter has been
removed. Use the new
pwm_cycle_time module if it is
necessary to dynamically change a pwm pin's cycle time.

20240123: The output_pin maximum_mcu_duration parameter is
deprecated. Use a pwm_tool config section
instead. The option will be removed in the near future.

20240123: The output_pin static_value parameter is deprecated.
Replace with value and shutdown_value parameters. The option will
be removed in the near future.

20231216: The [hall_filament_width_sensor] is changed to trigger filament runout
when the thickness of the filament exceeds max_diameter. The maximum diameter
defaults to default_nominal_filament_diameter + max_difference. See
[hall_filament_width_sensor] configuration
reference for more details.

20231207: Several undocumented config parameters in the [printer]
config section have been removed (the buffer_time_low,
buffer_time_high, buffer_time_start, and move_flush_time parameters).

20231110: Klipper v0.12.0 released.

20230826: If safe_distance is set or calculated to be 0 in [dual_carriage],
the carriages proximity checks will be disabled as per documentation. A user
may wish to configure safe_distance explicitly to prevent accidental crashes
of the carriages with each other. Additionally, the homing order of the primary
and the dual carriage is changed in some configurations (certain configurations
when both carriages home in the same direction, see
[dual_carriage] configuration reference
for more details).

20230810: The flash-sdcard.sh script now supports both variants of the
Bigtreetech SKR-3, STM32H743 and STM32H723. For this, the original tag
of btt-skr-3 now has changed to be either btt-skr-3-h743 or btt-skr-3-h723.

20230729: The exported status for dual_carriage is changed. Instead of
exporting mode and active_carriage, the individual modes for each
carriage are exported as printer.dual_carriage.carriage_0 and
printer.dual_carriage.carriage_1.

20230619: The relative_reference_index option has been deprecated
and superseded by the zero_reference_position option. Refer to the
Bed Mesh Documentation
for details on how to update the configuration. With this deprecation
the RELATIVE_REFERENCE_INDEX is no longer available as a parameter
for the BED_MESH_CALIBRATE gcode command.

20230530: The default canbus frequency in "make menuconfig" is
now 1000000. If using canbus and using canbus with some other
frequency is required, then be sure to select "Enable extra low-level
configuration options" and specify the desired "CAN bus speed" in
"make menuconfig" when compiling and flashing the micro-controller.

20230525: SHAPER_CALIBRATE command immediately applies input shaper
parameters if [input_shaper] was enabled already.

20230407: The stalled_bytes counter in the log and in the
printer.mcu.last_stats field has been renamed to upcoming_bytes.

20230323: On tmc5160 drivers multistep_filt is now enabled by default. Set
driver_MULTISTEP_FILT: False in the tmc5160 config for the previous behavior.

20230304: The SET_TMC_CURRENT command now properly adjusts the globalscaler
register for drivers that have it. This removes a limitation where on tmc5160,
the currents could not be raised higher with SET_TMC_CURRENT than the
run_current value set in the config file.
However, this has a side effect: After running SET_TMC_CURRENT, the stepper
must be held at standstill for >130ms in case StealthChop2 is used so that the
AT#1 calibration gets executed by the driver.

20230202: The format of the printer.screws_tilt_adjust status
information has changed. The information is now stored as a dictionary of
screws with the resulting measurements. See the
status reference for details.

20230201: The [bed_mesh] module no longer loads the default profile
on startup. It is recommended that users who use the default profile
add BED_MESH_PROFILE LOAD=default to their START_PRINT macro (or
to their slicer's "Start G-Code" configuration when applicable).

20230103: It is now possible with the flash-sdcard.sh script to flash
both variants of the Bigtreetech SKR-2, STM32F407 and STM32F429.
This means that the original tag of btt-skr2 now has changed to either
btt-skr-2-f407 or btt-skr-2-f429.

20221128: Klipper v0.11.0 released.

20221122: Previously, with safe_z_home, it was possible that the
z_hop after the g28 homing would go in the negative z direction.
Now, a z_hop is performed after g28 only if it results in a positive
hop, mirroring the behavior of the z_hop that occurs before
the g28 homing.

20220616: It was previously possible to flash an rp2040 in bootloader
mode by running make flash FLASH_DEVICE=first. The equivalent
command is now make flash FLASH_DEVICE=2e8a:0003.

20220612: The rp2040 micro-controller now has a workaround for the
"rp2040-e5" USB errata. This should make initial USB connections more
reliable. However, it may result in a change in behavior for the
gpio15 pin. It is unlikely the gpio15 behavior change will be
noticeable.

20220407: The temperature_fan pid_integral_max config option has
been removed (it was deprecated on 20210612).

20220407: The default color order for pca9632 LEDs is now "RGBW". Add
an explicit color_order: RBGW setting to the pca9632 config section
to obtain the previous behavior.

20220330: The format of the printer.neopixel.color_data status
information for neopixel and dotstar modules has changed. The
information is now stored as a list of color lists (instead of a list
of dictionaries). See the status reference
for details.

20220307: M73 will no longer set print progress to 0 if P is missing.

20220304: There is no longer a default for the extruder parameter of
extruder_stepper config
sections. If desired, specify extruder: extruder explicitly to
associate the stepper motor with the "extruder" motion queue at
startup.

20220210: The SYNC_STEPPER_TO_EXTRUDER command is deprecated; the
SET_EXTRUDER_STEP_DISTANCE command is deprecated; the
extruder shared_heater config option
is deprecated. These features will be removed in the near future.
Replace SET_EXTRUDER_STEP_DISTANCE with
SET_EXTRUDER_ROTATION_DISTANCE. Replace SYNC_STEPPER_TO_EXTRUDER
with SYNC_EXTRUDER_MOTION. Replace extruder config sections using
shared_heater with
extruder_stepper config
sections and update any activation macros to use
SYNC_EXTRUDER_MOTION.

20220116: The tmc2130, tmc2208, tmc2209, and tmc2660 run_current
calculation code has changed. For some run_current settings the
drivers may now be configured differently. This new configuration
should be more accurate, but it may invalidate previous tmc driver
tuning.

20211230: Scripts to tune input shaper (scripts/calibrate_shaper.py
and scripts/graph_accelerometer.py) were migrated to use Python3
by default. As a result, users must install Python3 versions of certain
packages (e.g. sudo apt install python3-numpy python3-matplotlib) to
continue using these scripts. For more details, refer to
Software installation.
Alternatively, users can temporarily force the execution of these scripts
under Python 2 by explicitly calling Python2 interpretor in the console:
python2 ~/klipper/scripts/calibrate_shaper.py ...

20211110: The "NTC 100K beta 3950" temperature sensor is deprecated.
This sensor will be removed in the near future. Most users will find
the "Generic 3950" temperature sensor more accurate. To continue to
use the older (typically less accurate) definition, define a custom
thermistor with temperature1: 25,
resistance1: 100000, and beta: 3950.

20211104: The "step pulse duration" option in "make menuconfig" has
been removed. The default step duration for TMC drivers configured in
UART or SPI mode is now 100ns. A new step_pulse_duration setting in
the stepper config section should be
set for all steppers that need a custom pulse duration.

20211102: Several deprecated features have been removed. The stepper
step_distance option has been removed (deprecated on 20201222). The
rpi_temperature sensor alias has been removed (deprecated on
20210219). The mcu pin_map option has been removed (deprecated on
20210325). The gcode_macro default_parameter_<name> and macro
access to command parameters other than via the params
pseudo-variable has been removed (deprecated on 20210503). The heater
pid_integral_max option has been removed (deprecated on 20210612).

20210929: Klipper v0.10.0 released.

20210903: The default smooth_time
for heaters has changed to 1 second (from 2 seconds). For most
printers this will result in more stable temperature control.

20210830: The default adxl345 name is now "adxl345". The default CHIP
parameter for the ACCELEROMETER_MEASURE and ACCELEROMETER_QUERY is
now also "adxl345".

20210830: The adxl345 ACCELEROMETER_MEASURE command no longer supports
a RATE parameter. To alter the query rate, update the printer.cfg
file and issue a RESTART command.

20210821: Several config settings in printer.configfile.settings
will now be reported as lists instead of raw strings. If the actual
raw string is desired, use printer.configfile.config instead.

20210819: In some cases, a G28 homing move may end in a position
that is nominally outside the valid movement range. In rare
situations this may result in confusing "Move out of range" errors
after homing. If this occurs, change your start scripts to move the
toolhead to a valid position immediately after homing.

20210814: The analog only pseudo-pins on the atmega168 and atmega328
have been renamed from PE0/PE1 to PE2/PE3.

20210720: A controller_fan section now monitors all stepper motors by
default (not just the kinematic stepper motors). If the previous
behavior is desired, see the stepper config option in the
config reference.

20210703: A samd_sercom config section must now specify the sercom
bus it is configuring via the sercom option.

20210612: The pid_integral_max config option in heater and
temperature_fan sections is deprecated. The option will be removed in
the near future.

20210503: The gcode_macro default_parameter_<name> config option is
deprecated. Use the params pseudo-variable to access macro
parameters. Other methods for accessing macro parameters will be
removed in the near future. Most users can replace a
default_parameter_NAME: VALUE config option with a line like the
following in the start of the macro: {% set NAME = params.NAME|default(VALUE)|float %}. See the Command Templates
document for examples.

20210430: The SET_VELOCITY_LIMIT (and M204) command may now set a
velocity, acceleration, and square_corner_velocity larger than the
specified values in the config file.

20210325: Support for the pin_map config option is deprecated. Use
the sample-aliases.cfg file to
translate to the actual micro-controller pin names. The pin_map
config option will be removed in the near future.

20210313: Klipper's support for micro-controllers that communicate
with CAN bus has changed. If using CAN bus then all micro-controllers
must be reflashed and the
Klipper configuration must be updated.

20210310: The TMC2660 default for driver_SFILT has been changed from 1
to 0.

20210227: TMC stepper motor drivers in UART or SPI mode are now
queried once per second whenever they are enabled - if the driver can
not be contacted or if the driver reports an error, then Klipper will
transition to a shutdown state.

20210219: The rpi_temperature module has been renamed to
temperature_host. Replace any occurrences of sensor_type: rpi_temperature with sensor_type: temperature_host. The path to
the temperature file may be specified in the sensor_path config
variable. The rpi_temperature name is deprecated and will be
removed in the near future.

20210201: The TEST_RESONANCES command will now disable input shaping
if it was previously enabled (and re-enable it after the test). In order
to override this behavior and keep the input shaping enabled, one can
pass an additional parameter INPUT_SHAPING=1 to the command.

20210201: The ACCELEROMETER_MEASURE command will now append the name
of the accelerometer chip to the output file name if the chip was given
a name in the corresponding adxl345 section of the printer.cfg.

20201222: The step_distance setting in the stepper config sections
is deprecated. It is advised to update the config to use the
rotation_distance setting. Support for
step_distance will be removed in the near future.

20201218: The endstop_phase setting in the endstop_phase module has
been replaced with trigger_phase. If using the endstop phases module
then it will be necessary to convert to
rotation_distance and recalibrate any
endstop phases by running the ENDSTOP_PHASE_CALIBRATE command.

20201218: Rotary delta and polar printers must now specify a
gear_ratio for their rotary steppers, and they may no longer specify
a step_distance parameter. See the
config reference for the format of the
new gear_ratio parameter.

20201213: It is not valid to specify a Z "position_endstop" when using
"probe:z_virtual_endstop". An error will now be raised if a Z
"position_endstop" is specified with "probe:z_virtual_endstop".
Remove the Z "position_endstop" definition to fix the error.

20201120: The [board_pins] config section now specifies the mcu name
in an explicit mcu: parameter. If using board_pins for a secondary
mcu, then the config must be updated to specify that name. See the
config reference for further
details.

20201112: The time reported by print_stats.print_duration has
changed. The duration prior to the first detected extrusion is
now excluded.

20201029: The neopixel color_order_GRB config option has been
removed. If necessary, update the config to set the new color_order
option to RGB, GRB, RGBW, or GRBW.

20201029: The serial option in the mcu config section no longer
defaults to /dev/ttyS0. In the rare situation where /dev/ttyS0 is the
desired serial port, it must be specified explicitly.

20201020: Klipper v0.9.0 released.

20200902: The RTD resistance-to-temperature calculation for MAX31865
converters has been corrected to not read low. If you are using such a
device, you should recalibrate your print temperature and PID settings.

20200816: The gcode macro printer.gcode object has been renamed to
printer.gcode_move. Several undocumented variables in
printer.toolhead and printer.gcode have been removed. See
docs/Command_Templates.md for a list of available template variables.

20200816: The gcode macro "action_" system has changed. Replace any
calls to printer.gcode.action_emergency_stop() with
action_emergency_stop(), printer.gcode.action_respond_info() with
action_respond_info(), and printer.gcode.action_respond_error()
with action_raise_error().

20200809: The menu system has been rewritten. If the menu has been
customized then it will be necessary to update to the new
configuration. See config/example-menu.cfg for configuration details
and see klippy/extras/display/menu.cfg for examples.

20200731: The behavior of the progress attribute reported by
the virtual_sdcard printer object has changed. Progress is no
longer reset to 0 when a print is paused. It will now always report
progress based on the internal file position, or 0 if no file is
currently loaded.

20200725: The servo enable config parameter and the SET_SERVO
ENABLE parameter have been removed. Update any macros to use
SET_SERVO SERVO=my_servo WIDTH=0 to disable a servo.

20200608: The LCD display support has changed the name of some
internal "glyphs". If a custom display layout was implemented it may
be necessary to update to the latest glyph names (see
klippy/extras/display/display.cfg for a list of available glyphs).

20200606: The pin names on linux mcu have changed. Pins now have names
of the form gpiochip<chipid>/gpio<gpio>. For gpiochip0 you can also
use a short gpio<gpio>. For example, what was previously referred
to as P20 now becomes gpio20 or gpiochip0/gpio20.

20200603: The default 16x4 LCD layout will no longer show the
estimated time remaining in a print. (Only the elapsed time will be
shown.) If the old behavior is desired one can customize the menu
display with that information (see the description of display_data in
config/example-extras.cfg for details).

20200531: The default USB vendor/product id is now 0x1d50/0x614e.
These new ids are reserved for Klipper (thanks to the openmoko
project). This change should not require any config changes, but the
new ids may appear in system logs.

20200524: The default value for the tmc5160 pwm_freq field is now zero
(instead of one).

20200425: The gcode_macro command template variable printer.heater
was renamed to printer.heaters.

20200313: The default lcd layout for multi-extruder printers with a
16x4 screen has changed. The single extruder screen layout is now the
default and it will show the currently active extruder. To use the
previous display layout set "display_group: _multiextruder_16x4" in
the [display] section of the printer.cfg file.

20200308: The default __test menu item was removed. If the config
file has a custom menu then be sure to remove all references to this
__test menu item.

20200308: The menu "deck" and "card" options were removed. To
customize the layout of an lcd screen use the new display_data config
sections (see config/example-extras.cfg for the details).

20200109: The bed_mesh module now references the probe's location
in for the mesh configuration. As such, some configuration options
have been renamed to more accurately reflect their intended
functionality. For rectangular beds, min_point and max_point
have been renamed to mesh_min and mesh_max respectively. For
round beds, bed_radius has been renamed to mesh_radius. A new
mesh_origin option has also been added for round beds. Note that
these changes are also incompatible with previously saved mesh profiles.
If an incompatible profile is detected it will be ignored and scheduled
for removal. The removal process can be completed by issuing the
SAVE_CONFIG command. The user will need to re-calibrate each profile.

20191218: The display config section no longer supports "lcd_type:
st7567". Use the "uc1701" display type instead - set "lcd_type:
uc1701" and change the "rs_pin: some_pin" to "rst_pin: some_pin". It
may also be necessary to add a "contrast: 60" config setting.

20191210: The builtin T0, T1, T2, ... commands have been removed. The
extruder activate_gcode and deactivate_gcode config options have been
removed. If these commands (and scripts) are needed then define
individual [gcode_macro T0] style macros that call the
ACTIVATE_EXTRUDER command. See the config/sample-idex.cfg and
sample-multi-extruder.cfg files for examples.

20191210: Support for the M206 command has been removed. Replace with
calls to SET_GCODE_OFFSET. If support for M206 is needed, add a
[gcode_macro M206] config section that calls SET_GCODE_OFFSET. (For
example "SET_GCODE_OFFSET Z=-{params.Z}".)

20191202: Support for the undocumented "S" parameter of the "G4"
command has been removed. Replace any occurrences of S with the
standard "P" parameter (the delay specified in milliseconds).

20191126: The USB names have changed on micro-controllers with native
USB support. They now use a unique chip id by default (where
available). If an "mcu" config section uses a "serial" setting that
starts with "/dev/serial/by-id/" then it may be necessary to update
the config. Run "ls /dev/serial/by-id/*" in an ssh terminal to
determine the new id.

20191121: The pressure_advance_lookahead_time parameter has been
removed. See example.cfg for alternate configuration settings.

20191112: The tmc stepper driver virtual enable capability is now
automatically enabled if the stepper does not have a dedicated stepper
enable pin. Remove references to tmcXXXX:virtual_enable from the
config. The ability to control multiple pins in the stepper
enable_pin config has been removed. If multiple pins are needed then
use a multi_pin config section.

20191107: The primary extruder config section must be specified as
"extruder" and may no longer be specified as "extruder0". Gcode
command templates that query the extruder status are now accessed via
"{printer.extruder}".

20191021: Klipper v0.8.0 released

20191003: The move_to_previous option in [safe_z_homing] now defaults
to False. (It was effectively False prior to 20190918.)

20190918: The zhop option in [safe_z_homing] is always re-applied
after Z axis homing completed. This might need users to update custom
scripts based on this module.

20190806: The SET_NEOPIXEL command has been renamed to SET_LED.

20190726: The mcp4728 digital-to-analog code has changed. The default
i2c_address is now 0x60 and the voltage reference is now relative to
the mcp4728's internal 2.048 volt reference.

20190710: The z_hop option was removed from the [firmware_retract]
config section. The z_hop support was incomplete and could cause
incorrect behavior with several common slicers.

20190710: The optional parameters of the PROBE_ACCURACY command have
changed. It may be necessary to update any macros or scripts that use
that command.

20190628: All configuration options have been removed from the
[skew_correction] section. Configuration for skew_correction
is now done via the SET_SKEW gcode. See Skew Correction
for recommended usage.

20190607: The "variable_X" parameters of gcode_macro (along with the
VALUE parameter of SET_GCODE_VARIABLE) are now parsed as Python
literals. If a value needs to be assigned a string then wrap the value
in quotes so that it is evaluated as a string.

20190606: The "samples", "samples_result", and "sample_retract_dist"
config options have been moved to the "probe" config section. These
options are no longer supported in the "delta_calibrate", "bed_tilt",
"bed_mesh", "screws_tilt_adjust", "z_tilt", or "quad_gantry_level"
config sections.

20190528: The magic "status" variable in gcode_macro template
evaluation has been renamed to "printer".

20190520: The SET_GCODE_OFFSET command has changed; update any g-code
macros accordingly. The command will no longer apply the requested
offset to the next G1 command. The old behavior may be approximated by
using the new "MOVE=1" parameter.

20190404: The Python host software packages were updated. Users will
need to rerun the ~/klipper/scripts/install-octopi.sh script (or
otherwise upgrade the python dependencies if not using a standard
OctoPi installation).

20190404: The i2c_bus and spi_bus parameters (in various config
sections) now take a bus name instead of a number.

20190404: The sx1509 config parameters have changed. The 'address'
parameter is now 'i2c_address' and it must be specified as a decimal
number. Where 0x3E was previously used, specify 62.

20190328: The min_speed value in [temperature_fan] config
will now be respected and the fan will always run at this
speed or higher in PID mode.

20190322: The default value for "driver_HEND" in [tmc2660] config
sections was changed from 6 to 3. The "driver_VSENSE" field was
removed (it is now automatically calculated from run_current).

20190310: The [controller_fan] config section now always takes a name
(such as [controller_fan my_controller_fan]).

20190308: The "driver_BLANK_TIME_SELECT" field in [tmc2130] and
[tmc2208] config sections has been renamed to "driver_TBL".

20190308: The [tmc2660] config section has changed. A new
sense_resistor config parameter must now be provided. The meaning of
several of the driver_XXX parameters has changed.

20190228: Users of SPI or I2C on SAMD21 boards must now specify the
bus pins via a [samd_sercom] config section.

20190224: The bed_shape option has been removed from bed_mesh. The
radius option has been renamed to bed_radius. Users with round beds
should supply the bed_radius and round_probe_count options.

20190107: The i2c_address parameter in the mcp4451 config section
changed. This is a common setting on Smoothieboards. The new value is
half the old value (88 should be changed to 44, and 90 should be
changed to 45).

20181220: Klipper v0.7.0 released

Config Reference (`docs/Config_Reference.md`) Copy Section

Configuration reference

This document is a reference for options available in the Klipper
config file.

The descriptions in this document are formatted so that it is possible
to cut-and-paste them into a printer config file. See the
installation document for information on setting up
Klipper and choosing an initial config file.

Micro-controller configuration Copy Chapter

Format of micro-controller pin names Copy Section

Many config options require the name of a micro-controller pin.
Klipper uses the hardware names for these pins - for example PA4.

Pin names may be preceded by ! to indicate that a reverse polarity
should be used (eg, trigger on low instead of high).

Input pins may be preceded by ^ to indicate that a hardware pull-up
resistor should be enabled for the pin. If the micro-controller
supports pull-down resistors then an input pin may alternatively be
preceded by ~.

Note, some config sections may "create" additional pins. Where this
occurs, the config section defining the pins must be listed in the
config file before any sections using those pins.

[mcu] Copy Section

Configuration of the primary micro-controller.

[mcu]
serial:
#   The serial port to connect to the MCU. If unsure (or if it
#   changes) see the "Where's my serial port?" section of the FAQ.
#   This parameter must be provided when using a serial port.
#baud: 250000
#   The baud rate to use. The default is 250000.
#canbus_uuid:
#   If using a device connected to a CAN bus then this sets the unique
#   chip identifier to connect to. This value must be provided when using
#   CAN bus for communication.
#canbus_interface:
#   If using a device connected to a CAN bus then this sets the CAN
#   network interface to use. The default is 'can0'.
#restart_method:
#   This controls the mechanism the host will use to reset the
#   micro-controller. The choices are 'arduino', 'cheetah', 'rpi_usb',
#   and 'command'. The 'arduino' method (toggle DTR) is common on
#   Arduino boards and clones. The 'cheetah' method is a special
#   method needed for some Fysetc Cheetah boards. The 'rpi_usb' method
#   is useful on Raspberry Pi boards with micro-controllers powered
#   over USB - it briefly disables power to all USB ports to
#   accomplish a micro-controller reset. The 'command' method involves
#   sending a Klipper command to the micro-controller so that it can
#   reset itself. The default is 'arduino' if the micro-controller
#   communicates over a serial port, 'command' otherwise.

[mcu my_extra_mcu] Copy Section

Additional micro-controllers (one may define any number of sections
with an "mcu" prefix). Additional micro-controllers introduce
additional pins that may be configured as heaters, steppers, fans,
etc.. For example, if an "[mcu extra_mcu]" section is introduced, then
pins such as "extra_mcu:ar9" may then be used elsewhere in the config
(where "ar9" is a hardware pin name or alias name on the given mcu).

[mcu my_extra_mcu]
# See the "mcu" section for configuration parameters.

Common kinematic settings Copy Chapter

[printer] Copy Section

The printer section controls high level printer settings.

/* Detailed source-code truncated for AI context efficiency. */

[stepper] Copy Section

Stepper motor definitions. Different printer types (as specified by
the "kinematics" option in the [printer] config section) require
different names for the stepper (eg, stepper_x vs stepper_a).
Below are common stepper definitions.

See the rotation distance document for
information on calculating the rotation_distance parameter. See the
Multi-MCU homing document for information on
homing using multiple micro-controllers.

/* Detailed source-code truncated for AI context efficiency. */

Cartesian Kinematics Copy Section

See example-cartesian.cfg for an
example cartesian kinematics config file.

Only parameters specific to cartesian printers are described here -
see common kinematic settings for
available parameters.

[printer]
kinematics: cartesian
max_z_velocity:
#   This sets the maximum velocity (in mm/s) of movement along the z
#   axis. This setting can be used to restrict the maximum speed of
#   the z stepper motor. The default is to use max_velocity for
#   max_z_velocity.
max_z_accel:
#   This sets the maximum acceleration (in mm/s^2) of movement along
#   the z axis. It limits the acceleration of the z stepper motor. The
#   default is to use max_accel for max_z_accel.

# The stepper_x section is used to describe the stepper controlling
# the X axis in a cartesian robot.
[stepper_x]

# The stepper_y section is used to describe the stepper controlling
# the Y axis in a cartesian robot.
[stepper_y]

# The stepper_z section is used to describe the stepper controlling
# the Z axis in a cartesian robot.
[stepper_z]

Linear Delta Kinematics Copy Section

See example-delta.cfg for an example
linear delta kinematics config file. See the
delta calibrate guide for information on
calibration.

Only parameters specific to linear delta printers are described here -
see common kinematic settings for
available parameters.

/* Detailed source-code truncated for AI context efficiency. */

Deltesian Kinematics Copy Section

See example-deltesian.cfg for an
example deltesian kinematics config file.

Only parameters specific to deltesian printers are described here - see
common kinematic settings for available
parameters.

/* Detailed source-code truncated for AI context efficiency. */

CoreXY Kinematics Copy Section

See example-corexy.cfg for an example
corexy (and h-bot) kinematics file.

Only parameters specific to corexy printers are described here - see
common kinematic settings for available
parameters.

[printer]
kinematics: corexy
max_z_velocity:
#   This sets the maximum velocity (in mm/s) of movement along the z
#   axis. This setting can be used to restrict the maximum speed of
#   the z stepper motor. The default is to use max_velocity for
#   max_z_velocity.
max_z_accel:
#   This sets the maximum acceleration (in mm/s^2) of movement along
#   the z axis. It limits the acceleration of the z stepper motor. The
#   default is to use max_accel for max_z_accel.

# The stepper_x section is used to describe the X axis as well as the
# stepper controlling the X+Y movement.
[stepper_x]

# The stepper_y section is used to describe the Y axis as well as the
# stepper controlling the X-Y movement.
[stepper_y]

# The stepper_z section is used to describe the stepper controlling
# the Z axis.
[stepper_z]

CoreXZ Kinematics Copy Section

See example-corexz.cfg for an example
corexz kinematics config file.

Only parameters specific to corexz printers are described here - see
common kinematic settings for available
parameters.

[printer]
kinematics: corexz
max_z_velocity:
#   This sets the maximum velocity (in mm/s) of movement along the z
#   axis. The default is to use max_velocity for max_z_velocity.
max_z_accel:
#   This sets the maximum acceleration (in mm/s^2) of movement along
#   the z axis. The default is to use max_accel for max_z_accel.

# The stepper_x section is used to describe the X axis as well as the
# stepper controlling the X+Z movement.
[stepper_x]

# The stepper_y section is used to describe the stepper controlling
# the Y axis.
[stepper_y]

# The stepper_z section is used to describe the Z axis as well as the
# stepper controlling the X-Z movement.
[stepper_z]

Hybrid-CoreXY Kinematics Copy Section

See example-hybrid-corexy.cfg
for an example hybrid corexy kinematics config file.

This kinematic is also known as Markforged kinematic.

Only parameters specific to hybrid corexy printers are described here
see common kinematic settings for available
parameters.

[printer]
kinematics: hybrid_corexy
max_z_velocity:
#   This sets the maximum velocity (in mm/s) of movement along the z
#   axis. The default is to use max_velocity for max_z_velocity.
max_z_accel:
#   This sets the maximum acceleration (in mm/s^2) of movement along
#   the z axis. The default is to use max_accel for max_z_accel.

# The stepper_x section is used to describe the X axis as well as the
# stepper controlling the X-Y movement.
[stepper_x]

# The stepper_y section is used to describe the stepper controlling
# the Y axis.
[stepper_y]

# The stepper_z section is used to describe the stepper controlling
# the Z axis.
[stepper_z]

Hybrid-CoreXZ Kinematics Copy Section

See example-hybrid-corexz.cfg
for an example hybrid corexz kinematics config file.

This kinematic is also known as Markforged kinematic.

Only parameters specific to hybrid corexy printers are described here
see common kinematic settings for available
parameters.

[printer]
kinematics: hybrid_corexz
max_z_velocity:
#   This sets the maximum velocity (in mm/s) of movement along the z
#   axis. The default is to use max_velocity for max_z_velocity.
max_z_accel:
#   This sets the maximum acceleration (in mm/s^2) of movement along
#   the z axis. The default is to use max_accel for max_z_accel.

# The stepper_x section is used to describe the X axis as well as the
# stepper controlling the X-Z movement.
[stepper_x]

# The stepper_y section is used to describe the stepper controlling
# the Y axis.
[stepper_y]

# The stepper_z section is used to describe the stepper controlling
# the Z axis.
[stepper_z]

Polar Kinematics Copy Section

See example-polar.cfg for an example
polar kinematics config file.

Only parameters specific to polar printers are described here - see
common kinematic settings for available
parameters.

POLAR KINEMATICS ARE A WORK IN PROGRESS. Moves around the 0, 0
position are known to not work properly.

[printer]
kinematics: polar
max_z_velocity:
#   This sets the maximum velocity (in mm/s) of movement along the z
#   axis. This setting can be used to restrict the maximum speed of
#   the z stepper motor. The default is to use max_velocity for
#   max_z_velocity.
max_z_accel:
#   This sets the maximum acceleration (in mm/s^2) of movement along
#   the z axis. It limits the acceleration of the z stepper motor. The
#   default is to use max_accel for max_z_accel.
# max_angular_velocity: 0
#   This limits the maximum angular velocity (in rad/s) of a move.
#   Lower values will result in longer print times, but prevents too
#   fast motions near the center. A value of 0 deactivates the
#   scaling. The default is to not apply maximum angular velocity limits.

# The stepper_bed section is used to describe the stepper controlling
# the bed.
[stepper_bed]
gear_ratio:
#   A gear_ratio must be specified and rotation_distance may not be
#   specified. For example, if the bed has an 80 toothed pulley driven
#   by a stepper with a 16 toothed pulley then one would specify a
#   gear ratio of "80:16". This parameter must be provided.

# The stepper_arm section is used to describe the stepper controlling
# the carriage on the arm.
[stepper_arm]

# The stepper_z section is used to describe the stepper controlling
# the Z axis.
[stepper_z]

Rotary delta Kinematics Copy Section

See example-rotary-delta.cfg for
an example rotary delta kinematics config file.

Only parameters specific to rotary delta printers are described here -
see common kinematic settings for
available parameters.

ROTARY DELTA KINEMATICS ARE A WORK IN PROGRESS. Homing moves may
timeout and some boundary checks are not implemented.

/* Detailed source-code truncated for AI context efficiency. */

Cable winch Kinematics Copy Section

See the example-winch.cfg for an
example cable winch kinematics config file.

Only parameters specific to cable winch printers are described here -
see common kinematic settings for
available parameters.

CABLE WINCH SUPPORT IS EXPERIMENTAL. Homing is not implemented on
cable winch kinematics. In order to home the printer, manually send
movement commands until the toolhead is at 0, 0, 0 and then issue a
G28 command.

[printer]
kinematics: winch

# The stepper_a section describes the stepper connected to the first
# cable winch. A minimum of 3 and a maximum of 26 cable winches may be
# defined (stepper_a to stepper_z) though it is common to define 4.
[stepper_a]
rotation_distance:
#   The rotation_distance is the nominal distance (in mm) the toolhead
#   moves towards the cable winch for each full rotation of the
#   stepper motor. This parameter must be provided.
anchor_x:
anchor_y:
anchor_z:
#   The X, Y, and Z position of the cable winch in cartesian space.
#   These parameters must be provided.

Generic Cartesian Kinematics Copy Section

See example-generic-cartesian.cfg
for an example generic Cartesian kinematics config file.

This printer kinematic class allows a user to define in a pretty flexible
manner an arbitrary Cartesian-style kinematics. In principle, the regular
cartesian, corexy, hybrid_corexy can be defined this way too. However,
more importantly, various otherwise unsupported kinematics such as
inverted hybrid_corexy or corexyuv can be defined using this kinematic.

Notably, the definition of a generic Cartesian kinematic deviates
significantly from the other kinematic types. It follows the following
convention: a user defines a set of carriages with certain range of motion
that can move independently from each other (they should move over the
Cartesian axes X, Y, and Z, hence the name of the kinematic) and
corresponding endstops that allow the firmware to determine the position
of carriages during homing, as well as a set of steppers that move those
carriages. The [printer] section must specify the kinematic and
other printer-level settings same as the regular Cartesian kinematic:

[printer]
kinematics: generic_cartesian
max_velocity:
max_accel:
#minimum_cruise_ratio:
#square_corner_velocity:
#max_z_velocity:
#max_z_accel:

Then a user must define three primary carriages for X, Y, and Z axes, e.g.:

/* Detailed source-code truncated for AI context efficiency. */

Afterwards, a user specifies the stepper motors that move these carriages,
for instance

[stepper my_stepper]
carriages:
#   A string describing the carriages the stepper moves. All defined
#   carriages can be specified here, as well as their linear combinations,
#   e.g. carriage_x, carriage_x+carriage_y, carriage_y-0.5*carriage_z,
#   carriage_x-carriage_z, etc. This parameter must be provided.
step_pin:
dir_pin:
enable_pin:
rotation_distance:
microsteps:
#full_steps_per_rotation: 200
#gear_ratio:
#step_pulse_duration:

See stepper section for more information on the regular
stepper parameters. The carriages parameter defines how the stepper
affects the motion of the carriages. For example, carriage_x+carriage_y
indicates that the motion of the stepper in the positive direction by the
distance d moves the carriages carriage_x and carriage_y by the same
distance d in the positive direction, while carriage_x-0.5*carriage_y
means the motion of the stepper in the positive direction by the distance
d moves the carriage carriage_x by the distance d in the positive
direction, but the carriage carriage_y will travel distance d/2 in
the negative direction.

More than a single stepper motor can be defined to drive the same axis
or belt. For example, on a CoreXY AWD setups two motors driving the same
belt can be defined as

[carriage carriage_x]
endstop_pin: ...
...

[carriage carriage_y]
endstop_pin: ...
...

[stepper a0]
carriages: carriage_x-carriage_y
step_pin: ...
dir_pin: ...
enable_pin: ...
rotation_distance: ...
...

[stepper a1]
carriages: carriage_x-carriage_y
step_pin: ...
dir_pin: ...
enable_pin: ...
rotation_distance: ...
...

with a0 and a1 steppers having their own control pins, but
sharing the same carriages and corresponding endstops.

There are situations when a user wants to have more than one endstop
per axis. Examples of such configurations include Y axis driven by
two independent stepper motors with belts attached to both ends of the
X gantry, with effectively two carriages on Y axis each having an
independent endstop, and multi-stepper Z axis with each stepper having
its own endstop (not to be confused with the configurations with
multiple Z motors but only a single endstop). These configurations
can be declared by specifying additional carriage(s) with their endstops:

[extra_carriage my_carriage]
primary_carriage:
#   The name of the primary carriage this carriage corresponds to.
#   It also effectively defines the axis the carriage moves over.
#   This parameter must be provided.
endstop_pin:
#   Endstop switch detection pin. This parameter must be provided.

and the corresponding stepper motors, for example:

[extra_carriage carriage_y1]
primary_carriage: carriage_y
endstop_pin: ...

[stepper sy1]
carriages: carriage_y1
...

Notably, an [extra_carriage] does not define parameters such as
position_min, position_max, and position_endstop, but instead
inherits them from the specified primary_carriage, thus sharing
the same range of motion with the primary carriage.

For the references on how to configure IDEX setups, see the
dual carriage section.

None Kinematics Copy Section

It is possible to define a special "none" kinematics to disable
kinematic support in Klipper. This may be useful for controlling
devices that are not typical 3d-printers or for debugging purposes.

[printer]
kinematics: none
max_velocity: 1
max_accel: 1
#   The max_velocity and max_accel parameters must be defined. The
#   values are not used for "none" kinematics.

Common extruder and heated bed support Copy Chapter

[extruder] Copy Section

The extruder section is used to describe the heater parameters for the
nozzle hotend along with the stepper controlling the extruder. See the
command reference for additional information.
See the pressure advance guide for information
on tuning pressure advance.

/* Detailed source-code truncated for AI context efficiency. */

[heater_bed] Copy Section

The heater_bed section describes a heated bed. It uses the same heater
settings described in the "extruder" section.

[heater_bed]
heater_pin:
sensor_type:
sensor_pin:
control:
min_temp:
max_temp:
#   See the "extruder" section for a description of the above parameters.

Bed level support Copy Chapter

[bed_mesh] Copy Section

Mesh Bed Leveling. One may define a bed_mesh config section to enable
move transformations that offset the z axis based on a mesh generated
from probed points. When using a probe to home the z-axis, it is
recommended to define a safe_z_home section in printer.cfg to home
toward the center of the print area.

See the bed mesh guide and
command reference for additional information.

Visual Examples:

rectangular bed, probe_count = 3, 3:
             x---x---x (max_point)
             |
             x---x---x
                     |
 (min_point) x---x---x

 round bed, round_probe_count = 5, bed_radius = r:
                 x (0, r) end
               /
             x---x---x
                       \
 (-r, 0) x---x---x---x---x (r, 0)
           \
             x---x---x
                   /
                 x  (0, -r) start

/* Detailed source-code truncated for AI context efficiency. */

[bed_tilt] Copy Section

Bed tilt compensation. One may define a bed_tilt config section to
enable move transformations that account for a tilted bed. Note that
bed_mesh and bed_tilt are incompatible; both cannot be defined.

See the command reference for additional
information.

[bed_tilt]
#x_adjust: 0
#   The amount to add to each move's Z height for each mm on the X
#   axis. The default is 0.
#y_adjust: 0
#   The amount to add to each move's Z height for each mm on the Y
#   axis. The default is 0.
#z_adjust: 0
#   The amount to add to the Z height when the nozzle is nominally at
#   0, 0. The default is 0.
# The remaining parameters control a BED_TILT_CALIBRATE extended
# g-code command that may be used to calibrate appropriate x and y
# adjustment parameters.
#points:
#   A list of X, Y coordinates (one per line; subsequent lines
#   indented) that should be probed during a BED_TILT_CALIBRATE
#   command. Specify coordinates of the nozzle and be sure the probe
#   is above the bed at the given nozzle coordinates. The default is
#   to not enable the command.
#speed: 50
#   The speed (in mm/s) of non-probing moves during the calibration.
#   The default is 50.
#horizontal_move_z: 5
#   The height (in mm) that the head should be commanded to move to
#   just prior to starting a probe operation. The default is 5.

[bed_screws] Copy Section

Tool to help adjust bed leveling screws. One may define a [bed_screws]
config section to enable a BED_SCREWS_ADJUST g-code command.

See the
leveling guide and
command reference for additional information.

[bed_screws]
#screw1:
#   The X, Y coordinate of the first bed leveling screw. This is a
#   position to command the nozzle to that is directly above the bed
#   screw (or as close as possible while still being above the bed).
#   This parameter must be provided.
#screw1_name:
#   An arbitrary name for the given screw. This name is displayed when
#   the helper script runs. The default is to use a name based upon
#   the screw XY location.
#screw1_fine_adjust:
#   An X, Y coordinate to command the nozzle to so that one can fine
#   tune the bed leveling screw. The default is to not perform fine
#   adjustments on the bed screw.
#screw2:
#screw2_name:
#screw2_fine_adjust:
#...
#   Additional bed leveling screws. At least three screws must be
#   defined.
#horizontal_move_z: 5
#   The height (in mm) that the head should be commanded to move to
#   when moving from one screw location to the next. The default is 5.
#probe_height: 0
#   The height of the probe (in mm) after adjusting for the thermal
#   expansion of bed and nozzle. The default is zero.
#speed: 50
#   The speed (in mm/s) of non-probing moves during the calibration.
#   The default is 50.
#probe_speed: 5
#   The speed (in mm/s) when moving from a horizontal_move_z position
#   to a probe_height position. The default is 5.

[screws_tilt_adjust] Copy Section

Tool to help adjust bed screws tilt using Z probe. One may define a
screws_tilt_adjust config section to enable a SCREWS_TILT_CALCULATE
g-code command.

See the
leveling guide
and command reference for additional
information.

[screws_tilt_adjust]
#screw1:
#   The (X, Y) coordinate of the first bed leveling screw. This is a
#   position to command the nozzle to so that the probe is directly
#   above the bed screw (or as close as possible while still being
#   above the bed). This is the base screw used in calculations. This
#   parameter must be provided.
#screw1_name:
#   An arbitrary name for the given screw. This name is displayed when
#   the helper script runs. The default is to use a name based upon
#   the screw XY location.
#screw2:
#screw2_name:
#...
#   Additional bed leveling screws. At least two screws must be
#   defined.
#speed: 50
#   The speed (in mm/s) of non-probing moves during the calibration.
#   The default is 50.
#horizontal_move_z: 5
#   The height (in mm) that the head should be commanded to move to
#   just prior to starting a probe operation. The default is 5.
#screw_thread: CW-M3
#   The type of screw used for bed leveling, M3, M4, or M5, and the
#   rotation direction of the knob that is used to level the bed.
#   Accepted values: CW-M3, CCW-M3, CW-M4, CCW-M4, CW-M5, CCW-M5.
#   Default value is CW-M3 which most printers use. A clockwise
#   rotation of the knob decreases the gap between the nozzle and the
#   bed. Conversely, a counter-clockwise rotation increases the gap.

[z_tilt] Copy Section

Multiple Z stepper tilt adjustment. This feature enables independent
adjustment of multiple z steppers (see the "stepper_z1" section) to
adjust for tilt. If this section is present then a Z_TILT_ADJUST
extended G-Code command becomes available.

/* Detailed source-code truncated for AI context efficiency. */

[quad_gantry_level] Copy Section

Moving gantry leveling using 4 independently controlled Z motors.
Corrects hyperbolic parabola effects (potato chip) on moving gantry
which is more flexible.
WARNING: Using this on a moving bed may lead to undesirable results.
If this section is present then a QUAD_GANTRY_LEVEL extended G-Code
command becomes available. This routine assumes the following Z motor
configuration:

----------------
 |Z1          Z2|
 |  ---------   |
 |  |       |   |
 |  |       |   |
 |  x--------   |
 |Z           Z3|
 ----------------

Where x is the 0, 0 point on the bed

[quad_gantry_level]
#gantry_corners:
#   A newline separated list of X, Y coordinates describing the two
#   opposing corners of the gantry. The first entry corresponds to Z,
#   the second to Z2. This parameter must be provided.
#points:
#   A newline separated list of four X, Y points that should be probed
#   during a QUAD_GANTRY_LEVEL command. Order of the locations is
#   important, and should correspond to Z, Z1, Z2, and Z3 location in
#   order. This parameter must be provided. For maximum accuracy,
#   ensure your probe offsets are configured.
#speed: 50
#   The speed (in mm/s) of non-probing moves during the calibration.
#   The default is 50.
#horizontal_move_z: 5
#   The height (in mm) that the head should be commanded to move to
#   just prior to starting a probe operation. The default is 5.
#max_adjust: 4
#   Safety limit if an adjustment greater than this value is requested
#   quad_gantry_level will abort.
#retries: 0
#   Number of times to retry if the probed points aren't within
#   tolerance.
#retry_tolerance: 0
#   If retries are enabled then retry if largest and smallest probed
#   points differ more than retry_tolerance.

[skew_correction] Copy Section

Printer Skew Correction. It is possible to use software to correct
printer skew across 3 planes, xy, xz, yz. This is done by printing a
calibration model along a plane and measuring three lengths. Due to
the nature of skew correction these lengths are set via gcode. See
Skew Correction and
Command Reference for details.

[skew_correction]

[z_thermal_adjust] Copy Section

Temperature-dependant toolhead Z position adjustment. Compensate for vertical
toolhead movement caused by thermal expansion of the printer's frame in
real-time using a temperature sensor (typically coupled to a vertical section
of frame).

See also: extended g-code commands.

[z_thermal_adjust]
#temp_coeff:
#   The temperature coefficient of expansion, in mm/degC. For example, a
#   temp_coeff of 0.01 mm/degC will move the Z axis downwards by 0.01 mm for
#   every degree Celsius that the temperature sensor increases. Defaults to
#   0.0 mm/degC, which applies no adjustment.
#smooth_time:
#   Smoothing window applied to the temperature sensor, in seconds. Can reduce
#   motor noise from excessive small corrections in response to sensor noise.
#   The default is 2.0 seconds.
#z_adjust_off_above:
#   Disables adjustments above this Z height [mm]. The last computed correction
#   will remain applied until the toolhead moves below the specified Z height
#   again. The default is 99999999.0 mm (always on).
#max_z_adjustment:
#   Maximum absolute adjustment that can be applied to the Z axis [mm]. The
#   default is 99999999.0 mm (unlimited).
#sensor_type:
#sensor_pin:
#min_temp:
#max_temp:
#   Temperature sensor configuration.
#   See the "extruder" section for the definition of the above
#   parameters.
#gcode_id:
#   See the "heater_generic" section for the definition of this
#   parameter.

Customized homing Copy Chapter

[safe_z_home] Copy Section

Safe Z homing. One may use this mechanism to home the Z axis at a
specific X, Y coordinate. This is useful if the toolhead, for example
has to move to the center of the bed before Z can be homed.

[safe_z_home]
home_xy_position:
#   A X, Y coordinate (e.g. 100, 100) where the Z homing should be
#   performed. This parameter must be provided.
#speed: 50.0
#   Speed at which the toolhead is moved to the safe Z home
#   coordinate. The default is 50 mm/s
#z_hop:
#   Distance (in mm) to lift the Z axis prior to homing. This is
#   applied to any homing command, even if it doesn't home the Z axis.
#   If the Z axis is already homed and the current Z position is less
#   than z_hop, then this will lift the head to a height of z_hop. If
#   the Z axis is not already homed the head is lifted by z_hop.
#   The default is to not implement Z hop.
#z_hop_speed: 15.0
#   Speed (in mm/s) at which the Z axis is lifted prior to homing. The
#   default is 15 mm/s.
#move_to_previous: False
#   When set to True, the X and Y axes are reset to their previous
#   positions after Z axis homing. The default is False.

[homing_override] Copy Section

Homing override. One may use this mechanism to run a series of g-code
commands in place of a G28 found in the normal g-code input. This may
be useful on printers that require a specific procedure to home the
machine.

[homing_override]
gcode:
#   A list of G-Code commands to execute in place of G28 commands
#   found in the normal g-code input. See docs/Command_Templates.md
#   for G-Code format. If a G28 is contained in this list of commands
#   then it will invoke the normal homing procedure for the printer.
#   The commands listed here must home all axes. This parameter must
#   be provided.
#axes: xyz
#   The axes to override. For example, if this is set to "z" then the
#   override script will only be run when the z axis is homed (eg, via
#   a "G28" or "G28 Z0" command). Note, the override script should
#   still home all axes. The default is "xyz" which causes the
#   override script to be run in place of all G28 commands.
#set_position_x:
#set_position_y:
#set_position_z:
#   If specified, the printer will assume the axis is at the specified
#   position prior to running the above g-code commands. Setting this
#   disables homing checks for that axis. This may be useful if the
#   head must move prior to invoking the normal G28 mechanism for an
#   axis. The default is to not force a position for an axis.

[endstop_phase] Copy Section

Stepper phase adjusted endstops. To use this feature, define a config
section with an "endstop_phase" prefix followed by the name of the
corresponding stepper config section (for example,
"[endstop_phase stepper_z]"). This feature can improve the accuracy of
endstop switches. Add a bare "[endstop_phase]" declaration to enable
the ENDSTOP_PHASE_CALIBRATE command.

See the endstop phases guide and
command reference for additional
information.

[endstop_phase stepper_z]
#endstop_accuracy:
#   Sets the expected accuracy (in mm) of the endstop. This represents
#   the maximum error distance the endstop may trigger (eg, if an
#   endstop may occasionally trigger 100um early or up to 100um late
#   then set this to 0.200 for 200um). The default is
#   4*rotation_distance/full_steps_per_rotation.
#trigger_phase:
#   This specifies the phase of the stepper motor driver to expect
#   when hitting the endstop. It is composed of two numbers separated
#   by a forward slash character - the phase and the total number of
#   phases (eg, "7/64"). Only set this value if one is sure the
#   stepper motor driver is reset every time the mcu is reset. If this
#   is not set, then the stepper phase will be detected on the first
#   home and that phase will be used on all subsequent homes.
#endstop_align_zero: False
#   If true then the position_endstop of the axis will effectively be
#   modified so that the zero position for the axis occurs at a full
#   step on the stepper motor. (If used on the Z axis and the print
#   layer height is a multiple of a full step distance then every
#   layer will occur on a full step.) The default is False.

G-Code macros and events Copy Chapter

[gcode_macro] Copy Section

G-Code macros (one may define any number of sections with a
"gcode_macro" prefix). See the
command template guide for more information.

[gcode_macro my_cmd]
#gcode:
#   A list of G-Code commands to execute in place of "my_cmd". See
#   docs/Command_Templates.md for G-Code format. This parameter must
#   be provided.
#variable_<name>:
#   One may specify any number of options with a "variable_" prefix.
#   The given variable name will be assigned the given value (parsed
#   as a Python literal) and will be available during macro expansion.
#   For example, a config with "variable_fan_speed = 75" might have
#   gcode commands containing "M106 S{ fan_speed * 255 }". Variables
#   can be changed at run-time using the SET_GCODE_VARIABLE command
#   (see docs/Command_Templates.md for details). Variable names may
#   not use upper case characters.
#rename_existing:
#   This option will cause the macro to override an existing G-Code
#   command and provide the previous definition of the command via the
#   name provided here. This can be used to override builtin G-Code
#   commands. Care should be taken when overriding commands as it can
#   cause complex and unexpected results. The default is to not
#   override an existing G-Code command.
#description: G-Code macro
#   This will add a short description used at the HELP command or while
#   using the auto completion feature. Default "G-Code macro"

[delayed_gcode] Copy Section

Execute a gcode on a set delay. See the
command template guide and
command reference for more information.

[delayed_gcode my_delayed_gcode]
gcode:
#   A list of G-Code commands to execute when the delay duration has
#   elapsed. G-Code templates are supported. This parameter must be
#   provided.
#initial_duration: 0.0
#   The duration of the initial delay (in seconds). If set to a
#   non-zero value the delayed_gcode will execute the specified number
#   of seconds after the printer enters the "ready" state. This can be
#   useful for initialization procedures or a repeating delayed_gcode.
#   If set to 0 the delayed_gcode will not execute on startup.
#   Default is 0.

[save_variables] Copy Section

Support saving variables to disk so that they are retained across
restarts. See
command templates and
G-Code reference for further information.

[save_variables]
filename:
#   Required - provide a filename that would be used to save the
#   variables to disk e.g. ~/variables.cfg

[idle_timeout] Copy Section

Idle timeout. An idle timeout is automatically enabled - add an
explicit idle_timeout config section to change the default settings.