From 0938a85bf6eb25e8032712cab040b2c7ff0f03f1 Mon Sep 17 00:00:00 2001
From: KevinOConnor <kevin@koconnor.net>
Date: Tue, 16 Sep 2025 16:23:25 +0000
Subject: [PATCH] =?UTF-8?q?Deploying=20to=20gh-pages=20from=20@=20Klipper3?=
 =?UTF-8?q?d/klipper@8db5d254e077e10583cfaff0d9e70e08263383e5=20?=
 =?UTF-8?q?=F0=9F=9A=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 Code_Overview.html                            |  92 +++++++++++-------
 .../__pycache__/mkdocs_hooks.cpython-38.pyc   | Bin 983 -> 983 bytes
 .../__pycache__/mkdocs_hooks.cpython-38.pyc   | Bin 983 -> 983 bytes
 fr/sitemap.xml.gz                             | Bin 229 -> 229 bytes
 .../__pycache__/mkdocs_hooks.cpython-38.pyc   | Bin 983 -> 983 bytes
 hu/sitemap.xml.gz                             | Bin 229 -> 229 bytes
 .../__pycache__/mkdocs_hooks.cpython-38.pyc   | Bin 983 -> 983 bytes
 it/sitemap.xml.gz                             | Bin 229 -> 229 bytes
 search/search_index.json                      |   2 +-
 sitemap.xml.gz                                | Bin 229 -> 229 bytes
 .../__pycache__/mkdocs_hooks.cpython-38.pyc   | Bin 983 -> 983 bytes
 zh-Hant/sitemap.xml.gz                        | Bin 229 -> 229 bytes
 .../__pycache__/mkdocs_hooks.cpython-38.pyc   | Bin 983 -> 983 bytes
 zh/sitemap.xml.gz                             | Bin 229 -> 229 bytes
 14 files changed, 59 insertions(+), 35 deletions(-)

diff --git a/Code_Overview.html b/Code_Overview.html
index 223931422..99891df85 100644
--- a/Code_Overview.html
+++ b/Code_Overview.html
@@ -1605,19 +1605,36 @@ some functionality in C code.</p>
 <p>Initial execution starts in <strong>klippy/klippy.py</strong>. 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
+execution of G-code commands is in the _process_commands() method in
 <strong>klippy/gcode.py</strong>. 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).</p>
-<p>There are four threads in the Klippy host code. The main thread
-handles incoming gcode commands. A second thread (which resides
-entirely in the <strong>klippy/chelper/serialqueue.c</strong> C code) handles
-low-level IO with the serial port. The third thread is used to process
-response messages from the micro-controller in the Python code (see
-<strong>klippy/serialhdl.py</strong>). The fourth thread writes debug messages to
-the log (see <strong>klippy/queuelogger.py</strong>) so that the other threads
-never block on log writes.</p>
+<p>There are several threads in the Klipper host code:</p>
+<ul>
+<li>There is a Python "main thread" that handles incoming G-Code
+  commands and is the starting point for most actions. This thread
+  runs the <a href="https://en.wikipedia.org/wiki/Reactor_pattern">reactor</a>
+  (<strong>klippy/reactor.py</strong>) and most high-level actions originate from
+  IO and timer event callbacks from that reactor.</li>
+<li>A thread for writing messages to the log so that the other threads
+  do not block on log writes. This thread resides entirely in the
+  <strong>klippy/queuelogger.py</strong> code and its operation is generally not
+  exposed to the main Python thread.</li>
+<li>A thread per micro-controller that performs the low-level reading
+  and writing of messages to that micro-controller. It resides in the
+  <strong>klippy/chelper/serialqueue.c</strong> C code and its operation is
+  generally not exposed to the Python code.</li>
+<li>A thread per micro-controller for processing messages received from
+  that micro-controller in the Python code. This thread is created in
+  <strong>klippy/serialhdl.py</strong>. Care must be taken in Python callbacks
+  invoked from this thread as this thread may directly interact with
+  the main Python thread.</li>
+<li>A thread per stepper motor that calculates the timing of stepper
+  motor step pulses and compresses those times. This thread resides in
+  the <strong>klippy/chelper/stepcompress.c</strong> C code and its operation is
+  generally not exposed to the Python code.</li>
+</ul>
 <h2 id="code-flow-of-a-move-command">Code flow of a move command<a class="headerlink" href="#code-flow-of-a-move-command" title="Permanent link">&para;</a></h2>
 <p>A typical printer movement starts when a "G1" command is sent to the
 Klippy host and it completes when the corresponding step pulses are
@@ -1639,7 +1656,7 @@ provides further information on the mechanics of moves.</p>
   the timing of printing actions. The main codepath for a move is:
   <code>ToolHead.move() -&gt; LookAheadQueue.add_move() -&gt;
   LookAheadQueue.flush() -&gt; Move.set_junction() -&gt;
-  ToolHead._process_moves()</code>.<ul>
+  ToolHead._process_moves() -&gt; trapq_append()</code>.<ul>
 <li>ToolHead.move() creates a Move() object with the parameters of the
 move (in cartesian space and in units of seconds and millimeters).</li>
 <li>The kinematics class is given the opportunity to audit each move
@@ -1664,37 +1681,44 @@ 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.</li>
+<li>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.</li>
 </ul>
 </li>
 </ul>
 <ul>
+<li>Note that the extruder is handled in its own kinematic class:
+  <code>ToolHead._process_moves() -&gt; PrinterExtruder.process_move()</code>. 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.</li>
+</ul>
+<ul>
 <li>Klipper uses an
   <a href="https://en.wikipedia.org/wiki/Root-finding_algorithm">iterative solver</a>
   to generate the step times for each stepper. For efficiency reasons,
-  the stepper pulse times are generated in C code. The moves are first
-  placed on a "trapezoid motion queue": <code>ToolHead._process_moves() -&gt;
-  trapq_append()</code> (in klippy/chelper/trapq.c). The step times are then
-  generated: <code>ToolHead._process_moves() -&gt;
-  ToolHead._advance_move_time() -&gt; ToolHead._advance_flush_time() -&gt;
-  MCU_Stepper.generate_steps() -&gt; itersolve_generate_steps() -&gt;
-  itersolve_gen_steps_range()</code> (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).</li>
-</ul>
-<ul>
-<li>Note that the extruder is handled in its own kinematic class:
-  <code>ToolHead._process_moves() -&gt; PrinterExtruder.move()</code>. 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.</li>
+  the stepper pulse times are generated in C code in a thread per
+  stepper motor. The threads are notified of new activity by the
+  motion_queuing module (klippy/extras/motion_queuing.py):
+  <code>PrinterMotionQueuing._flush_handler() -&gt;
+  PrinterMotionQueuing._advance_move_time() -&gt;
+  steppersync_start_gen_steps() -&gt;
+  stepcompress_start_gen_steps()</code>. The step times are then generated
+  from that thread (klippy/chelper/stepcompress.c):
+  <code>sc_background_thread() -&gt; stepcompress_generate_steps() -&gt;
+  itersolve_generate_steps() -&gt; itersolve_gen_steps_range()</code> (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).</li>
 </ul>
 <ul>
 <li>After the iterative solver calculates the step times they are added
diff --git a/_klipper3d/__pycache__/mkdocs_hooks.cpython-38.pyc b/_klipper3d/__pycache__/mkdocs_hooks.cpython-38.pyc
index feced514a009e58c06eda54ecdafe44a6178c40c..1c44076110e218c19b9c30fa172169a1eb6c8f2a 100644
GIT binary patch
delta 20
acmcc4ex02=l$V!_0SNB(o!rQMh8X}lPX+-1

delta 20
acmcc4ex02=l$V!_0SK0^Jh74c3^M>ZT?OI*

diff --git a/fr/_klipper3d/__pycache__/mkdocs_hooks.cpython-38.pyc b/fr/_klipper3d/__pycache__/mkdocs_hooks.cpython-38.pyc
index feced514a009e58c06eda54ecdafe44a6178c40c..1c44076110e218c19b9c30fa172169a1eb6c8f2a 100644
GIT binary patch
delta 20
acmcc4ex02=l$V!_0SNB(o!rQMh8X}lPX+-1

delta 20
acmcc4ex02=l$V!_0SK0^Jh74c3^M>ZT?OI*

diff --git a/fr/sitemap.xml.gz b/fr/sitemap.xml.gz
index 8aadf379595105594b238400dcd241a474067298..f488c145a63839ef6e595c8a720348652288ce09 100644
GIT binary patch
delta 15
WcmaFL_>_@dzMF&Nci+j0?DqgJeg;+m

delta 15
XcmaFL_>_@dzMF&N=*kll+3x`WExiUh

diff --git a/hu/_klipper3d/__pycache__/mkdocs_hooks.cpython-38.pyc b/hu/_klipper3d/__pycache__/mkdocs_hooks.cpython-38.pyc
index feced514a009e58c06eda54ecdafe44a6178c40c..1c44076110e218c19b9c30fa172169a1eb6c8f2a 100644
GIT binary patch
delta 20
acmcc4ex02=l$V!_0SNB(o!rQMh8X}lPX+-1

delta 20
acmcc4ex02=l$V!_0SK0^Jh74c3^M>ZT?OI*

diff --git a/hu/sitemap.xml.gz b/hu/sitemap.xml.gz
index d777f3961fb6f60600b91fe3832957c8862f3855..5202cd3db1cc0d3707e9ef9710f026646fd285ee 100644
GIT binary patch
delta 15
WcmaFL_>_@dzMF&Nd*8{4?DqgJW(HCK

delta 15
XcmaFL_>_@dzMF&N;K~yd+3x`WEu{uF

diff --git a/it/_klipper3d/__pycache__/mkdocs_hooks.cpython-38.pyc b/it/_klipper3d/__pycache__/mkdocs_hooks.cpython-38.pyc
index feced514a009e58c06eda54ecdafe44a6178c40c..1c44076110e218c19b9c30fa172169a1eb6c8f2a 100644
GIT binary patch
delta 20
acmcc4ex02=l$V!_0SNB(o!rQMh8X}lPX+-1

delta 20
acmcc4ex02=l$V!_0SK0^Jh74c3^M>ZT?OI*

diff --git a/it/sitemap.xml.gz b/it/sitemap.xml.gz
index 41394661077eb71f1183677000ff9a90832f9e6d..195ea3c21aefeb51f2b9341a829228e06e05d471 100644
GIT binary patch
delta 15
WcmaFL_>_@dzMF&NXWz+*?DqgJat2fY

delta 15
XcmaFL_>_@dzMF&N@X8Yt+3x`WEwKhT

diff --git a/search/search_index.json b/search/search_index.json
index e1ca20a74..115928a9b 100644
--- a/search/search_index.json
+++ b/search/search_index.json
@@ -1 +1 @@
-{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"index.html","text":"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 .","title":"Welcome"},{"location":"API_Server.html","text":"API server \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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\" \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 Dumps the configuration and state for the current mesh and all saved profiles. For example: {\"id\": 123, \"method\": \"bed_mesh/dump_mesh\"} might return: { \"current_mesh\": { \"name\": \"eddy-scan-test\", \"probed_matrix\": [...], \"mesh_matrix\": [...], \"mesh_params\": { \"x_count\": 9, \"y_count\": 9, \"mesh_x_pps\": 2, \"mesh_y_pps\": 2, \"algo\": \"bicubic\", \"tension\": 0.5, \"min_x\": 20, \"max_x\": 330, \"min_y\": 30, \"max_y\": 320 } }, \"profiles\": { \"default\": { \"points\": [...], \"mesh_params\": { \"min_x\": 20, \"max_x\": 330, \"min_y\": 30, \"max_y\": 320, \"x_count\": 9, \"y_count\": 9, \"mesh_x_pps\": 2, \"mesh_y_pps\": 2, \"algo\": \"bicubic\", \"tension\": 0.5 } }, \"eddy-scan-test\": { \"points\": [...], \"mesh_params\": { \"x_count\": 9, \"y_count\": 9, \"mesh_x_pps\": 2, \"mesh_y_pps\": 2, \"algo\": \"bicubic\", \"tension\": 0.5, \"min_x\": 20, \"max_x\": 330, \"min_y\": 30, \"max_y\": 320 } }, \"eddy-rapid-test\": { \"points\": [...], \"mesh_params\": { \"x_count\": 9, \"y_count\": 9, \"mesh_x_pps\": 2, \"mesh_y_pps\": 2, \"algo\": \"bicubic\", \"tension\": 0.5, \"min_x\": 20, \"max_x\": 330, \"min_y\": 30, \"max_y\": 320 } } }, \"calibration\": { \"points\": [...], \"config\": { \"x_count\": 9, \"y_count\": 9, \"mesh_x_pps\": 2, \"mesh_y_pps\": 2, \"algo\": \"bicubic\", \"tension\": 0.5, \"mesh_min\": [ 20, 30 ], \"mesh_max\": [ 330, 320 ], \"origin\": null, \"radius\": null }, \"probe_path\": [...], \"rapid_path\": [...] }, \"probe_offsets\": [ 0, 25, 0.5 ], \"axis_minimum\": [ 0, 0, -5, 0 ], \"axis_maximum\": [ 351, 358, 330, 0 ] } 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 .","title":"API server"},{"location":"API_Server.html#api-server","text":"This document describes Klipper's Application Programmer Interface (API). This interface enables external applications to query and control the Klipper host software.","title":"API server"},{"location":"API_Server.html#enabling-the-api-socket","text":"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.","title":"Enabling the API socket"},{"location":"API_Server.html#request-format","text":"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.)","title":"Request format"},{"location":"API_Server.html#api-protocol","text":"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.","title":"API Protocol"},{"location":"API_Server.html#subscriptions","text":"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 ( {} ).","title":"Subscriptions"},{"location":"API_Server.html#available-endpoints","text":"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\"} ).","title":"Available \"endpoints\""},{"location":"API_Server.html#info","text":"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.","title":"info"},{"location":"API_Server.html#emergency_stop","text":"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\"}","title":"emergency_stop"},{"location":"API_Server.html#register_remote_method","text":"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}}","title":"register_remote_method"},{"location":"API_Server.html#objectslist","text":"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\"]}}","title":"objects/list"},{"location":"API_Server.html#objectsquery","text":"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.","title":"objects/query"},{"location":"API_Server.html#objectssubscribe","text":"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}}","title":"objects/subscribe"},{"location":"API_Server.html#gcodehelp","text":"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\", ...}}","title":"gcode/help"},{"location":"API_Server.html#gcodescript","text":"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.","title":"gcode/script"},{"location":"API_Server.html#gcoderestart","text":"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.","title":"gcode/restart"},{"location":"API_Server.html#gcodefirmware_restart","text":"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.","title":"gcode/firmware_restart"},{"location":"API_Server.html#gcodesubscribe_output","text":"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.","title":"gcode/subscribe_output"},{"location":"API_Server.html#motion_reportdump_stepper","text":"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.","title":"motion_report/dump_stepper"},{"location":"API_Server.html#motion_reportdump_trapq","text":"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.","title":"motion_report/dump_trapq"},{"location":"API_Server.html#adxl345dump_adxl345","text":"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.","title":"adxl345/dump_adxl345"},{"location":"API_Server.html#angledump_angle","text":"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.","title":"angle/dump_angle"},{"location":"API_Server.html#load_celldump_force","text":"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.","title":"load_cell/dump_force"},{"location":"API_Server.html#load_cell_probedump_taps","text":"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","title":"load_cell_probe/dump_taps"},{"location":"API_Server.html#pause_resumecancel","text":"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.","title":"pause_resume/cancel"},{"location":"API_Server.html#pause_resumepause","text":"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.","title":"pause_resume/pause"},{"location":"API_Server.html#pause_resumeresume","text":"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.","title":"pause_resume/resume"},{"location":"API_Server.html#query_endstopsstatus","text":"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.","title":"query_endstops/status"},{"location":"API_Server.html#bed_meshdump_mesh","text":"Dumps the configuration and state for the current mesh and all saved profiles. For example: {\"id\": 123, \"method\": \"bed_mesh/dump_mesh\"} might return: { \"current_mesh\": { \"name\": \"eddy-scan-test\", \"probed_matrix\": [...], \"mesh_matrix\": [...], \"mesh_params\": { \"x_count\": 9, \"y_count\": 9, \"mesh_x_pps\": 2, \"mesh_y_pps\": 2, \"algo\": \"bicubic\", \"tension\": 0.5, \"min_x\": 20, \"max_x\": 330, \"min_y\": 30, \"max_y\": 320 } }, \"profiles\": { \"default\": { \"points\": [...], \"mesh_params\": { \"min_x\": 20, \"max_x\": 330, \"min_y\": 30, \"max_y\": 320, \"x_count\": 9, \"y_count\": 9, \"mesh_x_pps\": 2, \"mesh_y_pps\": 2, \"algo\": \"bicubic\", \"tension\": 0.5 } }, \"eddy-scan-test\": { \"points\": [...], \"mesh_params\": { \"x_count\": 9, \"y_count\": 9, \"mesh_x_pps\": 2, \"mesh_y_pps\": 2, \"algo\": \"bicubic\", \"tension\": 0.5, \"min_x\": 20, \"max_x\": 330, \"min_y\": 30, \"max_y\": 320 } }, \"eddy-rapid-test\": { \"points\": [...], \"mesh_params\": { \"x_count\": 9, \"y_count\": 9, \"mesh_x_pps\": 2, \"mesh_y_pps\": 2, \"algo\": \"bicubic\", \"tension\": 0.5, \"min_x\": 20, \"max_x\": 330, \"min_y\": 30, \"max_y\": 320 } } }, \"calibration\": { \"points\": [...], \"config\": { \"x_count\": 9, \"y_count\": 9, \"mesh_x_pps\": 2, \"mesh_y_pps\": 2, \"algo\": \"bicubic\", \"tension\": 0.5, \"mesh_min\": [ 20, 30 ], \"mesh_max\": [ 330, 320 ], \"origin\": null, \"radius\": null }, \"probe_path\": [...], \"rapid_path\": [...] }, \"probe_offsets\": [ 0, 25, 0.5 ], \"axis_minimum\": [ 0, 0, -5, 0 ], \"axis_maximum\": [ 351, 358, 330, 0 ] } 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 .","title":"bed_mesh/dump_mesh"},{"location":"Axis_Twist_Compensation.html","text":"Axis Twist Compensation \u00b6 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 \u00b6 Tip: Make sure the probe X and Y offsets are correctly set as they greatly influence calibration. Basic Usage: X-Axis Calibration \u00b6 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> Adjust Your Z Offset: After completing the calibration, be sure to adjust your Z offset . Perform Bed Leveling Operations: Use probe-based operations as needed, such as: - Screws Tilt Adjust - Z Tilt Adjust 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 \u00b6 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 \u00b6 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","title":"Axis Twist Compensation"},{"location":"Axis_Twist_Compensation.html#axis-twist-compensation","text":"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.","title":"Axis Twist Compensation"},{"location":"Axis_Twist_Compensation.html#overview-of-compensation-usage","text":"Tip: Make sure the probe X and Y offsets are correctly set as they greatly influence calibration.","title":"Overview of compensation usage"},{"location":"Axis_Twist_Compensation.html#basic-usage-x-axis-calibration","text":"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> Adjust Your Z Offset: After completing the calibration, be sure to adjust your Z offset . Perform Bed Leveling Operations: Use probe-based operations as needed, such as: - Screws Tilt Adjust - Z Tilt Adjust Finalize the Setup: Home all axes, and perform a Bed Mesh if necessary. Run a test print, followed by any fine-tuning if needed.","title":"Basic Usage: X-Axis Calibration"},{"location":"Axis_Twist_Compensation.html#for-y-axis-calibration","text":"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.","title":"For Y-Axis Calibration"},{"location":"Axis_Twist_Compensation.html#axis_twist_compensation-setup-and-commands","text":"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","title":"[axis_twist_compensation] setup and commands"},{"location":"BLTouch.html","text":"BL-Touch \u00b6 Connecting BL-Touch \u00b6 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 \u00b6 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 \u00b6 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\" \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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.","title":"BL-Touch"},{"location":"BLTouch.html#bl-touch","text":"","title":"BL-Touch"},{"location":"BLTouch.html#connecting-bl-touch","text":"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.","title":"Connecting BL-Touch"},{"location":"BLTouch.html#initial-tests","text":"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.","title":"Initial tests"},{"location":"BLTouch.html#bl-touch-gone-bad","text":"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.","title":"BL-Touch gone bad"},{"location":"BLTouch.html#bl-touch-clones","text":"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.","title":"BL-Touch \"clones\""},{"location":"BLTouch.html#bl-touch-v3","text":"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).","title":"BL-Touch v3"},{"location":"BLTouch.html#multi-probing-without-stowing","text":"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).","title":"Multi-probing without stowing"},{"location":"BLTouch.html#calibrating-the-bl-touch-offsets","text":"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.","title":"Calibrating the BL-Touch offsets"},{"location":"BLTouch.html#bl-touch-output-mode","text":"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.","title":"BL-Touch output mode"},{"location":"Beaglebone.html","text":"Beaglebone \u00b6 This document describes the process of running Klipper on a Beaglebone PRU. Building an OS image \u00b6 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: remove some BeagleBone \"Demo\" resources if you did boot from SD-Card, and it's bigger than 4Gb - you can expand current filesystem to take whole card space 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 \u00b6 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) \u00b6 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 \u00b6 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 \u00b6 Complete the installation by configuring Klipper following the instructions in the main Installation document. Printing on the Beaglebone \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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","title":"Beaglebone"},{"location":"Beaglebone.html#beaglebone","text":"This document describes the process of running Klipper on a Beaglebone PRU.","title":"Beaglebone"},{"location":"Beaglebone.html#building-an-os-image","text":"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: remove some BeagleBone \"Demo\" resources if you did boot from SD-Card, and it's bigger than 4Gb - you can expand current filesystem to take whole card space 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.","title":"Building an OS image"},{"location":"Beaglebone.html#installing-octoprint","text":"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/","title":"Installing Octoprint"},{"location":"Beaglebone.html#building-the-beaglebone-pru-micro-controller-code-pru-firmware","text":"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.","title":"Building the BeagleBone PRU micro-controller code (PRU firmware)"},{"location":"Beaglebone.html#building-and-installing-linux-host-micro-controller-code","text":"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.","title":"Building and installing Linux host micro-controller code"},{"location":"Beaglebone.html#remaining-configuration","text":"Complete the installation by configuring Klipper following the instructions in the main Installation document.","title":"Remaining configuration"},{"location":"Beaglebone.html#printing-on-the-beaglebone","text":"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.","title":"Printing on the Beaglebone"},{"location":"Beaglebone.html#avr-micro-controller-code-build","text":"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","title":"AVR micro-controller code build"},{"location":"Beaglebone.html#hardware-pin-designation","text":"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.","title":"Hardware Pin designation"},{"location":"Beaglebone.html#enabling-hardware-spi","text":"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.","title":"Enabling hardware SPI"},{"location":"Beaglebone.html#enabling-hardware-i2c","text":"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","title":"Enabling hardware I2C"},{"location":"Beaglebone.html#enabling-hardware-uartserialcan","text":"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","title":"Enabling hardware UART(Serial)/CAN"},{"location":"Bed_Level.html","text":"Bed leveling \u00b6 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 \u00b6 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\" \u00b6 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 \u00b6 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.","title":"Bed leveling"},{"location":"Bed_Level.html#bed-leveling","text":"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.","title":"Bed leveling"},{"location":"Bed_Level.html#choose-the-appropriate-calibration-mechanism","text":"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.","title":"Choose the appropriate calibration mechanism"},{"location":"Bed_Level.html#the-paper-test","text":"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.","title":"The \"paper test\""},{"location":"Bed_Level.html#determining-thermal-expansion","text":"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.","title":"Determining Thermal Expansion"},{"location":"Bed_Mesh.html","text":"Bed Mesh \u00b6 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 \u00b6 Rectangular Beds \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 Calibration \u00b6 BED_MESH_CALIBRATE PROFILE=<name> METHOD=[manual | automatic | scan | rapid_scan] <br> [<probe_parameter>=<value>] [<mesh_parameter>=<value>] [ADAPTIVE=[0|1] <br> [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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 BED_MESH_CLEAR This gcode may be used to clear the internal mesh state. Apply X/Y offsets \u00b6 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 \u00b6 Dumping mesh data \u00b6 {\"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 \u00b6 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 \u00b6 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 \u00b6 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 <input> -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 \u00b6 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 <input> 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 \u00b6 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 <input> 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","title":"Bed Mesh"},{"location":"Bed_Mesh.html#bed-mesh","text":"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.","title":"Bed Mesh"},{"location":"Bed_Mesh.html#basic-configuration","text":"","title":"Basic Configuration"},{"location":"Bed_Mesh.html#rectangular-beds","text":"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).","title":"Rectangular Beds"},{"location":"Bed_Mesh.html#round-beds","text":"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.","title":"Round beds"},{"location":"Bed_Mesh.html#advanced-configuration","text":"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.","title":"Advanced Configuration"},{"location":"Bed_Mesh.html#mesh-interpolation","text":"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.","title":"Mesh Interpolation"},{"location":"Bed_Mesh.html#move-splitting","text":"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.","title":"Move Splitting"},{"location":"Bed_Mesh.html#mesh-fade","text":"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.","title":"Mesh Fade"},{"location":"Bed_Mesh.html#configuring-the-zero-reference-position","text":"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.","title":"Configuring the zero reference position"},{"location":"Bed_Mesh.html#faulty-regions","text":"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.","title":"Faulty Regions"},{"location":"Bed_Mesh.html#adaptive-meshes","text":"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.","title":"Adaptive Meshes"},{"location":"Bed_Mesh.html#surface-scans","text":"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.","title":"Surface Scans"},{"location":"Bed_Mesh.html#scan-height","text":"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.","title":"Scan Height"},{"location":"Bed_Mesh.html#rapid-continuous-scanning","text":"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.","title":"Rapid (Continuous) Scanning"},{"location":"Bed_Mesh.html#bed-mesh-gcodes","text":"","title":"Bed Mesh Gcodes"},{"location":"Bed_Mesh.html#calibration","text":"BED_MESH_CALIBRATE PROFILE=<name> METHOD=[manual | automatic | scan | rapid_scan] <br> [<probe_parameter>=<value>] [<mesh_parameter>=<value>] [ADAPTIVE=[0|1] <br> [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.","title":"Calibration"},{"location":"Bed_Mesh.html#profiles","text":"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.","title":"Profiles"},{"location":"Bed_Mesh.html#loading-the-default-profile","text":"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","title":"Loading the default profile"},{"location":"Bed_Mesh.html#output","text":"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.","title":"Output"},{"location":"Bed_Mesh.html#clear-mesh-state","text":"BED_MESH_CLEAR This gcode may be used to clear the internal mesh state.","title":"Clear Mesh State"},{"location":"Bed_Mesh.html#apply-xy-offsets","text":"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 .","title":"Apply X/Y offsets"},{"location":"Bed_Mesh.html#bed-mesh-webhooks-apis","text":"","title":"Bed Mesh Webhooks APIs"},{"location":"Bed_Mesh.html#dumping-mesh-data","text":"{\"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 .","title":"Dumping mesh data"},{"location":"Bed_Mesh.html#visualization-and-analysis","text":"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","title":"Visualization and analysis"},{"location":"Bed_Mesh.html#pre-requisites","text":"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.","title":"Pre-requisites"},{"location":"Bed_Mesh.html#plotting-mesh-data","text":"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 <input> -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","title":"Plotting Mesh data"},{"location":"Bed_Mesh.html#bed-mesh-analysis","text":"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 <input> 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","title":"Bed Mesh Analysis"},{"location":"Bed_Mesh.html#save-mesh-data-to-a-file","text":"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 <input> 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","title":"Save mesh data to a file"},{"location":"Benchmarks.html","text":"Benchmarks \u00b6 This document describes Klipper benchmarks. Micro-controller Benchmarks \u00b6 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 \u00b6 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 \u00b6 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). avr ticks 1 stepper 102 3 stepper 486 Arduino Due step rate benchmark \u00b6 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 . sam3x8e ticks 1 stepper 66 3 stepper 257 Duet Maestro step rate benchmark \u00b6 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 . sam4s8c ticks 1 stepper 71 3 stepper 260 Duet Wifi step rate benchmark \u00b6 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) . sam4e8e ticks 1 stepper 48 3 stepper 215 Beaglebone PRU step rate benchmark \u00b6 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) . pru ticks 1 stepper 231 3 stepper 847 STM32F042 step rate benchmark \u00b6 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 . stm32f042 ticks 1 stepper 59 3 stepper 249 STM32F103 step rate benchmark \u00b6 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 . stm32f103 ticks 1 stepper 61 3 stepper 264 STM32F4 step rate benchmark \u00b6 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). stm32f446 ticks 1 stepper 46 3 stepper 205 stm32f407 ticks 1 stepper 46 3 stepper 205 STM32H7 step rate benchmark \u00b6 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 . stm32h723 ticks 1 stepper 70 3 stepper 181 STM32G0B1 step rate benchmark \u00b6 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 . stm32g0b1 ticks 1 stepper 58 3 stepper 243 STM32G4 step rate benchmark \u00b6 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 . stm32g431 ticks 1 stepper 47 3 stepper 208 LPC176x step rate benchmark \u00b6 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. lpc1768 ticks 1 stepper 52 3 stepper 222 lpc1769 ticks 1 stepper 51 3 stepper 222 SAMD21 step rate benchmark \u00b6 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. samd21 ticks 1 stepper 70 3 stepper 306 SAMD51 step rate benchmark \u00b6 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. samd51 ticks 1 stepper 39 3 stepper 191 1 stepper (200Mhz) 39 3 stepper (200Mhz) 181 SAME70 step rate benchmark \u00b6 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. same70 ticks 1 stepper 45 3 stepper 190 AR100 step rate benchmark \u00b6 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. AR100 R_PIO ticks 1 stepper 85 3 stepper 359 RPxxxx step rate benchmark \u00b6 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. rp2040 (*) ticks 1 stepper 3 3 stepper 14 rp2350 ticks 1 stepper 36 3 stepper 169 (*) 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 \u00b6 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. Linux (RPi3) ticks 1 stepper 160 3 stepper 380 Command dispatch benchmark \u00b6 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. MCU Rate Build Build compiler atmega2560 (serial) 23K b161a69e avr-gcc (GCC) 4.8.1 sam3x8e (serial) 23K b161a69e arm-none-eabi-gcc (Fedora 7.1.0-5.fc27) 7.1.0 rp2350 (CAN) 59K 17b8ce4c arm-none-eabi-gcc (Fedora 14.1.0-1.fc40) 14.1.0 at90usb1286 (USB) 75K 01d2183f avr-gcc (GCC) 5.4.0 ar100 (serial) 138K 08d037c6 or1k-linux-musl-gcc 9.3.0 samd21 (USB) 223K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 pru (shared memory) 260K c5968a08 pru-gcc (GCC) 8.0.0 20170530 (experimental) stm32f103 (USB) 355K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 sam3x8e (USB) 418K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 lpc1768 (USB) 534K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 lpc1769 (USB) 628K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 sam4s8c (USB) 650K 8d4a5c16 arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 samd51 (USB) 864K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 stm32f446 (USB) 870K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 rp2040 (USB) 885K f6718291 arm-none-eabi-gcc (Fedora 14.1.0-1.fc40) 14.1.0 rp2350 (USB) 885K f6718291 arm-none-eabi-gcc (Fedora 14.1.0-1.fc40) 14.1.0 Host Benchmarks \u00b6 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","title":"Benchmarks"},{"location":"Benchmarks.html#benchmarks","text":"This document describes Klipper benchmarks.","title":"Benchmarks"},{"location":"Benchmarks.html#micro-controller-benchmarks","text":"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.","title":"Micro-controller Benchmarks"},{"location":"Benchmarks.html#step-rate-benchmark-test","text":"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.","title":"Step rate benchmark test"},{"location":"Benchmarks.html#avr-step-rate-benchmark","text":"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). avr ticks 1 stepper 102 3 stepper 486","title":"AVR step rate benchmark"},{"location":"Benchmarks.html#arduino-due-step-rate-benchmark","text":"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 . sam3x8e ticks 1 stepper 66 3 stepper 257","title":"Arduino Due step rate benchmark"},{"location":"Benchmarks.html#duet-maestro-step-rate-benchmark","text":"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 . sam4s8c ticks 1 stepper 71 3 stepper 260","title":"Duet Maestro step rate benchmark"},{"location":"Benchmarks.html#duet-wifi-step-rate-benchmark","text":"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) . sam4e8e ticks 1 stepper 48 3 stepper 215","title":"Duet Wifi step rate benchmark"},{"location":"Benchmarks.html#beaglebone-pru-step-rate-benchmark","text":"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) . pru ticks 1 stepper 231 3 stepper 847","title":"Beaglebone PRU step rate benchmark"},{"location":"Benchmarks.html#stm32f042-step-rate-benchmark","text":"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 . stm32f042 ticks 1 stepper 59 3 stepper 249","title":"STM32F042 step rate benchmark"},{"location":"Benchmarks.html#stm32f103-step-rate-benchmark","text":"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 . stm32f103 ticks 1 stepper 61 3 stepper 264","title":"STM32F103 step rate benchmark"},{"location":"Benchmarks.html#stm32f4-step-rate-benchmark","text":"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). stm32f446 ticks 1 stepper 46 3 stepper 205 stm32f407 ticks 1 stepper 46 3 stepper 205","title":"STM32F4 step rate benchmark"},{"location":"Benchmarks.html#stm32h7-step-rate-benchmark","text":"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 . stm32h723 ticks 1 stepper 70 3 stepper 181","title":"STM32H7 step rate benchmark"},{"location":"Benchmarks.html#stm32g0b1-step-rate-benchmark","text":"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 . stm32g0b1 ticks 1 stepper 58 3 stepper 243","title":"STM32G0B1 step rate benchmark"},{"location":"Benchmarks.html#stm32g4-step-rate-benchmark","text":"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 . stm32g431 ticks 1 stepper 47 3 stepper 208","title":"STM32G4 step rate benchmark"},{"location":"Benchmarks.html#lpc176x-step-rate-benchmark","text":"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. lpc1768 ticks 1 stepper 52 3 stepper 222 lpc1769 ticks 1 stepper 51 3 stepper 222","title":"LPC176x step rate benchmark"},{"location":"Benchmarks.html#samd21-step-rate-benchmark","text":"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. samd21 ticks 1 stepper 70 3 stepper 306","title":"SAMD21 step rate benchmark"},{"location":"Benchmarks.html#samd51-step-rate-benchmark","text":"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. samd51 ticks 1 stepper 39 3 stepper 191 1 stepper (200Mhz) 39 3 stepper (200Mhz) 181","title":"SAMD51 step rate benchmark"},{"location":"Benchmarks.html#same70-step-rate-benchmark","text":"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. same70 ticks 1 stepper 45 3 stepper 190","title":"SAME70 step rate benchmark"},{"location":"Benchmarks.html#ar100-step-rate-benchmark","text":"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. AR100 R_PIO ticks 1 stepper 85 3 stepper 359","title":"AR100 step rate benchmark"},{"location":"Benchmarks.html#rpxxxx-step-rate-benchmark","text":"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. rp2040 (*) ticks 1 stepper 3 3 stepper 14 rp2350 ticks 1 stepper 36 3 stepper 169 (*) 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.","title":"RPxxxx step rate benchmark"},{"location":"Benchmarks.html#linux-mcu-step-rate-benchmark","text":"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. Linux (RPi3) ticks 1 stepper 160 3 stepper 380","title":"Linux MCU step rate benchmark"},{"location":"Benchmarks.html#command-dispatch-benchmark","text":"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. MCU Rate Build Build compiler atmega2560 (serial) 23K b161a69e avr-gcc (GCC) 4.8.1 sam3x8e (serial) 23K b161a69e arm-none-eabi-gcc (Fedora 7.1.0-5.fc27) 7.1.0 rp2350 (CAN) 59K 17b8ce4c arm-none-eabi-gcc (Fedora 14.1.0-1.fc40) 14.1.0 at90usb1286 (USB) 75K 01d2183f avr-gcc (GCC) 5.4.0 ar100 (serial) 138K 08d037c6 or1k-linux-musl-gcc 9.3.0 samd21 (USB) 223K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 pru (shared memory) 260K c5968a08 pru-gcc (GCC) 8.0.0 20170530 (experimental) stm32f103 (USB) 355K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 sam3x8e (USB) 418K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 lpc1768 (USB) 534K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 lpc1769 (USB) 628K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 sam4s8c (USB) 650K 8d4a5c16 arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 samd51 (USB) 864K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 stm32f446 (USB) 870K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 rp2040 (USB) 885K f6718291 arm-none-eabi-gcc (Fedora 14.1.0-1.fc40) 14.1.0 rp2350 (USB) 885K f6718291 arm-none-eabi-gcc (Fedora 14.1.0-1.fc40) 14.1.0","title":"Command dispatch benchmark"},{"location":"Benchmarks.html#host-benchmarks","text":"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","title":"Host Benchmarks"},{"location":"Bootloader_Entry.html","text":"Bootloader Entry \u00b6 Klipper can be instructed to reboot into a Bootloader in one of the following ways: Requesting the bootloader \u00b6 Virtual Serial \u00b6 If a virtual (USB-ACM) serial port is in use, pulsing DTR while at 1200 baud will request the bootloader. Python (with flash_usb ) \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 <BAUD> is the baud rate of the serial port, such as 115200 . CANBUS \u00b6 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 \u00b6 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. <UUID> is the UUID of your CAN device. See the CANBUS Documentation for information on finding the CAN UUID of your devices. Entering the bootloader \u00b6 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 \u00b6 STM32 DFU Warning \u00b6 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.","title":"Bootloader Entry"},{"location":"Bootloader_Entry.html#bootloader-entry","text":"Klipper can be instructed to reboot into a Bootloader in one of the following ways:","title":"Bootloader Entry"},{"location":"Bootloader_Entry.html#requesting-the-bootloader","text":"","title":"Requesting the bootloader"},{"location":"Bootloader_Entry.html#virtual-serial","text":"If a virtual (USB-ACM) serial port is in use, pulsing DTR while at 1200 baud will request the bootloader.","title":"Virtual Serial"},{"location":"Bootloader_Entry.html#python-with-flash_usb","text":"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> .","title":"Python (with flash_usb)"},{"location":"Bootloader_Entry.html#picocom","text":"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","title":"Picocom"},{"location":"Bootloader_Entry.html#physical-serial","text":"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.","title":"Physical serial"},{"location":"Bootloader_Entry.html#shell","text":"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 <BAUD> is the baud rate of the serial port, such as 115200 .","title":"Shell"},{"location":"Bootloader_Entry.html#canbus","text":"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.","title":"CANBUS"},{"location":"Bootloader_Entry.html#katapults-flashtoolpy","text":"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. <UUID> is the UUID of your CAN device. See the CANBUS Documentation for information on finding the CAN UUID of your devices.","title":"Katapult's flashtool.py"},{"location":"Bootloader_Entry.html#entering-the-bootloader","text":"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","title":"Entering the bootloader"},{"location":"Bootloader_Entry.html#notes","text":"","title":"Notes"},{"location":"Bootloader_Entry.html#stm32-dfu-warning","text":"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.","title":"STM32 DFU Warning"},{"location":"Bootloaders.html","text":"Bootloaders \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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) \u00b6 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) \u00b6 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) \u00b6 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) \u00b6 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) \u00b6 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) \u00b6 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 \u00b6 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 \u00b6 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: 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 \u00b6 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 \u00b6 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 flash_can.py utility supplied in the lib/canboot 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) \u00b6 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) \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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.","title":"Bootloaders"},{"location":"Bootloaders.html#bootloaders","text":"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.","title":"Bootloaders"},{"location":"Bootloaders.html#avr-micro-controllers","text":"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).","title":"AVR micro-controllers"},{"location":"Bootloaders.html#atmega2560","text":"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","title":"Atmega2560"},{"location":"Bootloaders.html#atmega1280","text":"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","title":"Atmega1280"},{"location":"Bootloaders.html#atmega1284p","text":"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","title":"Atmega1284p"},{"location":"Bootloaders.html#at90usb1286","text":"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","title":"At90usb1286"},{"location":"Bootloaders.html#atmega168","text":"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","title":"Atmega168"},{"location":"Bootloaders.html#sam3-micro-controllers-arduino-due","text":"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","title":"SAM3 micro-controllers (Arduino Due)"},{"location":"Bootloaders.html#sam4-micro-controllers-duet-wifi","text":"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","title":"SAM4 micro-controllers (Duet Wifi)"},{"location":"Bootloaders.html#samdc21-micro-controllers-duet3d-toolboard-1lc","text":"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","title":"SAMDC21 micro-controllers (Duet3D Toolboard 1LC)"},{"location":"Bootloaders.html#samd21-micro-controllers-arduino-zero","text":"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","title":"SAMD21 micro-controllers (Arduino Zero)"},{"location":"Bootloaders.html#samd51-micro-controllers-adafruit-metro-m4-and-similar","text":"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","title":"SAMD51 micro-controllers (Adafruit Metro-M4 and similar)"},{"location":"Bootloaders.html#stm32f103-micro-controllers-blue-pill-devices","text":"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.","title":"STM32F103 micro-controllers (Blue Pill devices)"},{"location":"Bootloaders.html#stm32f103-with-stm32duino-bootloader","text":"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.","title":"STM32F103 with stm32duino bootloader"},{"location":"Bootloaders.html#stm32f103-with-hid-bootloader","text":"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: 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.","title":"STM32F103 with HID bootloader"},{"location":"Bootloaders.html#stm32f103stm32f072-with-msc-bootloader","text":"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.","title":"STM32F103/STM32F072 with MSC bootloader"},{"location":"Bootloaders.html#stm32f103stm32f0x2-with-canboot-bootloader","text":"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 flash_can.py utility supplied in the lib/canboot 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.","title":"STM32F103/STM32F0x2 with CanBoot bootloader"},{"location":"Bootloaders.html#stm32f4-micro-controllers-skr-pro-11","text":"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.","title":"STM32F4 micro-controllers (SKR Pro 1.1)"},{"location":"Bootloaders.html#lpc176x-micro-controllers-smoothieboards","text":"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.","title":"LPC176x micro-controllers (Smoothieboards)"},{"location":"Bootloaders.html#running-openocd-on-the-raspberry-pi","text":"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","title":"Running OpenOCD on the Raspberry PI"},{"location":"Bootloaders.html#configure-openocd","text":"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","title":"Configure OpenOCD"},{"location":"Bootloaders.html#wire-the-raspberry-pi-to-the-target-chip","text":"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.","title":"Wire the Raspberry Pi to the target chip"},{"location":"Bootloaders.html#run-openocd","text":"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.)","title":"Run OpenOCD"},{"location":"Bootloaders.html#openocd-and-gdb","text":"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.","title":"OpenOCD and gdb"},{"location":"CANBUS.html","text":"CANBUS \u00b6 This document describes Klipper's CAN bus support. Device Hardware \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 See the CAN bus troubleshooting document.","title":"CANBUS"},{"location":"CANBUS.html#canbus","text":"This document describes Klipper's CAN bus support.","title":"CANBUS"},{"location":"CANBUS.html#device-hardware","text":"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.","title":"Device Hardware"},{"location":"CANBUS.html#host-hardware","text":"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","title":"Host Hardware"},{"location":"CANBUS.html#terminating-resistors","text":"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.","title":"Terminating Resistors"},{"location":"CANBUS.html#finding-the-canbus_uuid-for-new-micro-controllers","text":"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.","title":"Finding the canbus_uuid for new micro-controllers"},{"location":"CANBUS.html#configuring-klipper","text":"Update the Klipper mcu configuration to use the CAN bus to communicate with the device - for example: [mcu my_can_mcu] canbus_uuid: 11aa22bb33cc","title":"Configuring Klipper"},{"location":"CANBUS.html#usb-to-can-bus-bridge-mode","text":"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 .","title":"USB to CAN bus bridge mode"},{"location":"CANBUS.html#tips-for-troubleshooting","text":"See the CAN bus troubleshooting document.","title":"Tips for troubleshooting"},{"location":"CANBUS_Troubleshooting.html","text":"CANBUS Troubleshooting \u00b6 This document provides information on troubleshooting communication issues when using Klipper with CAN bus . Verify CAN bus wiring \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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.","title":"CANBUS Troubleshooting"},{"location":"CANBUS_Troubleshooting.html#canbus-troubleshooting","text":"This document provides information on troubleshooting communication issues when using Klipper with CAN bus .","title":"CANBUS Troubleshooting"},{"location":"CANBUS_Troubleshooting.html#verify-can-bus-wiring","text":"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.","title":"Verify CAN bus wiring"},{"location":"CANBUS_Troubleshooting.html#check-for-incrementing-bytes_invalid-counter","text":"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 .","title":"Check for incrementing bytes_invalid counter"},{"location":"CANBUS_Troubleshooting.html#use-an-appropriate-txqueuelen-setting","text":"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.","title":"Use an appropriate txqueuelen setting"},{"location":"CANBUS_Troubleshooting.html#use-canbus_querypy-only-to-identify-nodes-never-previously-seen","text":"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.","title":"Use canbus_query.py only to identify nodes never previously seen"},{"location":"CANBUS_Troubleshooting.html#obtaining-candump-logs","text":"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 .","title":"Obtaining candump logs"},{"location":"CANBUS_Troubleshooting.html#parsing-klipper-messages-in-a-candump-log","text":"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.","title":"Parsing Klipper messages in a candump log"},{"location":"CANBUS_Troubleshooting.html#using-a-logic-analyzer-on-the-canbus-wiring","text":"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.","title":"Using a logic analyzer on the canbus wiring"},{"location":"CANBUS_protocol.html","text":"CANBUS protocol \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 The RESP_NEED_NODEID message format is: <1-byte message_id = 0x20><6-byte canbus_uuid><1-byte set_klipper_nodeid = 0x01> Data Packets \u00b6 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 ).","title":"CANBUS protocol"},{"location":"CANBUS_protocol.html#canbus-protocol","text":"This document describes the protocol Klipper uses to communicate over CAN bus . See CANBUS.md for information on configuring Klipper with CAN bus.","title":"CANBUS protocol"},{"location":"CANBUS_protocol.html#micro-controller-id-assignment","text":"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.","title":"Micro-controller id assignment"},{"location":"CANBUS_protocol.html#admin-messages","text":"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\".","title":"Admin messages"},{"location":"CANBUS_protocol.html#cmd_query_unassigned-message","text":"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>","title":"CMD_QUERY_UNASSIGNED message"},{"location":"CANBUS_protocol.html#cmd_set_klipper_nodeid-message","text":"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>","title":"CMD_SET_KLIPPER_NODEID message"},{"location":"CANBUS_protocol.html#resp_need_nodeid-message","text":"The RESP_NEED_NODEID message format is: <1-byte message_id = 0x20><6-byte canbus_uuid><1-byte set_klipper_nodeid = 0x01>","title":"RESP_NEED_NODEID message"},{"location":"CANBUS_protocol.html#data-packets","text":"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 ).","title":"Data Packets"},{"location":"CONTRIBUTING.html","text":"Contributing to Klipper \u00b6 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 \u00b6 Contributions to Klipper generally follow a high-level process: A submitter starts by creating a GitHub Pull Request when a submission is ready for widespread deployment. 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. 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 \u00b6 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: 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\". 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. 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 . 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 . 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 . 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 \u00b6 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 \u00b6 The Klipper \"reviewers\" are: Name GitHub Id Areas of interest Dmitry Butyugin @dmbutyugin Input shaping, resonance testing, kinematics Eric Callahan @Arksine Bed leveling, MCU flashing James Hartley @JamesH1978 Configuration files Kevin O'Connor @KevinOConnor Core motion system, Micro-controller code 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: Name GitHub name Kevin O'Connor @KevinOConnor Format of commit messages \u00b6 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 <myemail@example.org> 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 \u00b6 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: update klipper-translations repository active_translations 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: Currently, there isn't a method for correctly translating pictures in the documentation It is impossible to translate titles in mkdocs.yml.","title":"Contributing to Klipper"},{"location":"CONTRIBUTING.html#contributing-to-klipper","text":"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.","title":"Contributing to Klipper"},{"location":"CONTRIBUTING.html#overview-of-contribution-process","text":"Contributions to Klipper generally follow a high-level process: A submitter starts by creating a GitHub Pull Request when a submission is ready for widespread deployment. 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. 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.","title":"Overview of Contribution Process"},{"location":"CONTRIBUTING.html#what-to-expect-in-a-review","text":"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: 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\". 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. 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 . 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 . 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 . 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.","title":"What to expect in a review"},{"location":"CONTRIBUTING.html#helping-with-reviews","text":"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\".","title":"Helping with reviews"},{"location":"CONTRIBUTING.html#reviewers","text":"The Klipper \"reviewers\" are: Name GitHub Id Areas of interest Dmitry Butyugin @dmbutyugin Input shaping, resonance testing, kinematics Eric Callahan @Arksine Bed leveling, MCU flashing James Hartley @JamesH1978 Configuration files Kevin O'Connor @KevinOConnor Core motion system, Micro-controller code 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: Name GitHub name Kevin O'Connor @KevinOConnor","title":"Reviewers"},{"location":"CONTRIBUTING.html#format-of-commit-messages","text":"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 <myemail@example.org> 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.","title":"Format of commit messages"},{"location":"CONTRIBUTING.html#contributing-to-klipper-translations","text":"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: update klipper-translations repository active_translations 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: Currently, there isn't a method for correctly translating pictures in the documentation It is impossible to translate titles in mkdocs.yml.","title":"Contributing to Klipper Translations"},{"location":"Code_Overview.html","text":"Code overview \u00b6 This document describes the overall code layout and major code flow of Klipper. Directory Layout \u00b6 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 \u00b6 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 \u00b6 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 four threads in the Klippy host code. The main thread handles incoming gcode commands. A second thread (which resides entirely in the klippy/chelper/serialqueue.c C code) handles low-level IO with the serial port. The third thread is used to process response messages from the micro-controller in the Python code (see klippy/serialhdl.py ). The fourth thread writes debug messages to the log (see klippy/queuelogger.py ) so that the other threads never block on log writes. Code flow of a move command \u00b6 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() -> LookAheadQueue.flush() -> Move.set_junction() -> ToolHead._process_moves() . 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_moves() is called, 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. Klipper uses an iterative solver to generate the step times for each stepper. For efficiency reasons, the stepper pulse times are generated in C code. The moves are first placed on a \"trapezoid motion queue\": ToolHead._process_moves() -> trapq_append() (in klippy/chelper/trapq.c). The step times are then generated: ToolHead._process_moves() -> ToolHead._advance_move_time() -> ToolHead._advance_flush_time() -> MCU_Stepper.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). Note that the extruder is handled in its own kinematic class: ToolHead._process_moves() -> PrinterExtruder.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. 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 stepcompress.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 \u00b6 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 \u00b6 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: Start by studying the \" code flow of a move \" section and the Kinematics document . 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. 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. 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. 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. 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 \u00b6 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: 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. 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. 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. 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. Add support for timer dispatch from hardware interrupts. See Klipper commit 970831ee as an example of steps 1-5 done for the LPC176x architecture. Bring up basic GPIO input and output support. See Klipper commit c78b9076 as an example of this. Bring up additional peripherals - for example see Klipper commit 65613aed , c812a40a , and c381d03a . Create a sample Klipper config file in the config/ directory. Test the micro-controller with the main klippy.py program. Consider adding build test cases in the test/ directory. Additional coding tips: 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. 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 \u00b6 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 \u00b6 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.","title":"Code overview"},{"location":"Code_Overview.html#code-overview","text":"This document describes the overall code layout and major code flow of Klipper.","title":"Code overview"},{"location":"Code_Overview.html#directory-layout","text":"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.","title":"Directory Layout"},{"location":"Code_Overview.html#micro-controller-code-flow","text":"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.","title":"Micro-controller code flow"},{"location":"Code_Overview.html#klippy-code-overview","text":"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 four threads in the Klippy host code. The main thread handles incoming gcode commands. A second thread (which resides entirely in the klippy/chelper/serialqueue.c C code) handles low-level IO with the serial port. The third thread is used to process response messages from the micro-controller in the Python code (see klippy/serialhdl.py ). The fourth thread writes debug messages to the log (see klippy/queuelogger.py ) so that the other threads never block on log writes.","title":"Klippy code overview"},{"location":"Code_Overview.html#code-flow-of-a-move-command","text":"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() -> LookAheadQueue.flush() -> Move.set_junction() -> ToolHead._process_moves() . 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_moves() is called, 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. Klipper uses an iterative solver to generate the step times for each stepper. For efficiency reasons, the stepper pulse times are generated in C code. The moves are first placed on a \"trapezoid motion queue\": ToolHead._process_moves() -> trapq_append() (in klippy/chelper/trapq.c). The step times are then generated: ToolHead._process_moves() -> ToolHead._advance_move_time() -> ToolHead._advance_flush_time() -> MCU_Stepper.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). Note that the extruder is handled in its own kinematic class: ToolHead._process_moves() -> PrinterExtruder.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. 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 stepcompress.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.","title":"Code flow of a move command"},{"location":"Code_Overview.html#adding-a-host-module","text":"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.","title":"Adding a host module"},{"location":"Code_Overview.html#adding-new-kinematics","text":"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: Start by studying the \" code flow of a move \" section and the Kinematics document . 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. 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. 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. 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. 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.","title":"Adding new kinematics"},{"location":"Code_Overview.html#porting-to-a-new-micro-controller","text":"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: 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. 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. 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. 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. Add support for timer dispatch from hardware interrupts. See Klipper commit 970831ee as an example of steps 1-5 done for the LPC176x architecture. Bring up basic GPIO input and output support. See Klipper commit c78b9076 as an example of this. Bring up additional peripherals - for example see Klipper commit 65613aed , c812a40a , and c381d03a . Create a sample Klipper config file in the config/ directory. Test the micro-controller with the main klippy.py program. Consider adding build test cases in the test/ directory. Additional coding tips: 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. 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.","title":"Porting to a new micro-controller"},{"location":"Code_Overview.html#coordinate-systems","text":"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.","title":"Coordinate Systems"},{"location":"Code_Overview.html#time","text":"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.","title":"Time"},{"location":"Command_Templates.html","text":"Commands templates \u00b6 This document provides information on implementing G-Code command sequences in gcode_macro (and similar) config sections. G-Code Macro Naming \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 <update> . When <force> is set True then it will also stop editing. Default value is False. When <update> 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 \u00b6 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}","title":"Commands templates"},{"location":"Command_Templates.html#commands-templates","text":"This document provides information on implementing G-Code command sequences in gcode_macro (and similar) config sections.","title":"Commands templates"},{"location":"Command_Templates.html#g-code-macro-naming","text":"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).","title":"G-Code Macro Naming"},{"location":"Command_Templates.html#formatting-of-g-code-in-the-config","text":"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.","title":"Formatting of G-Code in the config"},{"location":"Command_Templates.html#add-a-description-to-your-macro","text":"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.","title":"Add a description to your macro"},{"location":"Command_Templates.html#saverestore-state-for-g-code-moves","text":"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.","title":"Save/Restore state for G-Code moves"},{"location":"Command_Templates.html#template-expansion","text":"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","title":"Template expansion"},{"location":"Command_Templates.html#macro-parameters","text":"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}","title":"Macro parameters"},{"location":"Command_Templates.html#the-rawparams-variable","text":"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 .","title":"The \"rawparams\" variable"},{"location":"Command_Templates.html#the-printer-variable","text":"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}","title":"The \"printer\" Variable"},{"location":"Command_Templates.html#actions","text":"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\")","title":"Actions"},{"location":"Command_Templates.html#variables","text":"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.","title":"Variables"},{"location":"Command_Templates.html#delayed-gcodes","text":"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","title":"Delayed Gcodes"},{"location":"Command_Templates.html#menu-templates","text":"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 <update> . When <force> is set True then it will also stop editing. Default value is False. When <update> 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.","title":"Menu templates"},{"location":"Command_Templates.html#save-variables-to-disk","text":"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}","title":"Save Variables to disk"},{"location":"Config_Changes.html","text":"Configuration Changes \u00b6 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 \u00b6 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","title":"Configuration Changes"},{"location":"Config_Changes.html#configuration-changes","text":"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.","title":"Configuration Changes"},{"location":"Config_Changes.html#changes","text":"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","title":"Changes"},{"location":"Config_Reference.html","text":"Configuration reference \u00b6 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 \u00b6 Format of micro-controller pin names \u00b6 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] \u00b6 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] \u00b6 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 \u00b6 [printer] \u00b6 The printer section controls high level printer settings. [printer] kinematics: # The type of printer in use. This option may be one of: cartesian, # corexy, corexz, hybrid_corexy, hybrid_corexz, generic_cartesian, # rotary_delta, delta, deltesian, polar, winch, or none. # This parameter must be specified. max_velocity: # Maximum velocity (in mm/s) of the toolhead (relative to the # print). This value may be changed at runtime using the # SET_VELOCITY_LIMIT command. This parameter must be specified. max_accel: # Maximum acceleration (in mm/s^2) of the toolhead (relative to the # print). Although this parameter is described as a \"maximum\" # acceleration, in practice most moves that accelerate or decelerate # will do so at the rate specified here. The value specified here # may be changed at runtime using the SET_VELOCITY_LIMIT command. # This parameter must be specified. #minimum_cruise_ratio: 0.5 # Most moves will accelerate to a cruising speed, travel at that # cruising speed, and then decelerate. However, some moves that # travel a short distance could nominally accelerate and then # immediately decelerate. This option reduces the top speed of these # moves to ensure there is always a minimum distance traveled at a # cruising speed. That is, it enforces a minimum distance traveled # at cruising speed relative to the total distance traveled. It is # intended to reduce the top speed of short zigzag moves (and thus # reduce printer vibration from these moves). For example, a # minimum_cruise_ratio of 0.5 would ensure that a standalone 1.5mm # move would have a minimum cruising distance of 0.75mm. Specify a # ratio of 0.0 to disable this feature (there would be no minimum # cruising distance enforced between acceleration and deceleration). # The value specified here may be changed at runtime using the # SET_VELOCITY_LIMIT command. The default is 0.5. #square_corner_velocity: 5.0 # The maximum velocity (in mm/s) that the toolhead may travel a 90 # degree corner at. A non-zero value can reduce changes in extruder # flow rates by enabling instantaneous velocity changes of the # toolhead during cornering. This value configures the internal # centripetal velocity cornering algorithm; corners with angles # larger than 90 degrees will have a higher cornering velocity while # corners with angles less than 90 degrees will have a lower # cornering velocity. If this is set to zero then the toolhead will # decelerate to zero at each corner. The value specified here may be # changed at runtime using the SET_VELOCITY_LIMIT command. The # default is 5mm/s. [stepper] \u00b6 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. [stepper_x] step_pin: # Step GPIO pin (triggered high). This parameter must be provided. dir_pin: # Direction GPIO pin (high indicates positive direction). This # parameter must be provided. enable_pin: # Enable pin (default is enable high; use ! to indicate enable # low). If this parameter is not provided then the stepper motor # driver must always be enabled. rotation_distance: # Distance (in mm) that the axis travels with one full rotation of # the stepper motor (or final gear if gear_ratio is specified). # This parameter must be provided. microsteps: # The number of microsteps the stepper motor driver uses. This # parameter must be provided. #full_steps_per_rotation: 200 # The number of full steps for one rotation of the stepper motor. # Set this to 200 for a 1.8 degree stepper motor or set to 400 for a # 0.9 degree motor. The default is 200. #gear_ratio: # The gear ratio if the stepper motor is connected to the axis via a # gearbox. For example, one may specify \"5:1\" if a 5 to 1 gearbox is # in use. If the axis has multiple gearboxes one may specify a comma # separated list of gear ratios (for example, \"57:11, 2:1\"). If a # gear_ratio is specified then rotation_distance specifies the # distance the axis travels for one full rotation of the final gear. # The default is to not use a gear ratio. #step_pulse_duration: # The minimum time between the step pulse signal edge and the # following \"unstep\" signal edge. This is also used to set the # minimum time between a step pulse and a direction change signal. # The default is 0.000000100 (100ns) for TMC steppers that are # configured in UART or SPI mode, and the default is 0.000002 (which # is 2us) for all other steppers. endstop_pin: # Endstop switch detection pin. If this endstop pin is on a # different mcu than the stepper motor then it enables \"multi-mcu # homing\". This parameter must be provided for the X, Y, and Z # steppers on cartesian style printers. #position_min: 0 # Minimum valid distance (in mm) the user may command the stepper to # move to. The default is 0mm. position_endstop: # Location of the endstop (in mm). This parameter must be provided # for the X, Y, and Z steppers on cartesian style printers. position_max: # Maximum valid distance (in mm) the user may command the stepper to # move to. This parameter must be provided for the X, Y, and Z # steppers on cartesian style printers. #homing_speed: 5.0 # Maximum velocity (in mm/s) of the stepper when homing. The default # is 5mm/s. #homing_retract_dist: 5.0 # Distance to backoff (in mm) before homing a second time during # homing. Set this to zero to disable the second home. The default # is 5mm. #homing_retract_speed: # Speed to use on the retract move after homing in case this should # be different from the homing speed, which is the default for this # parameter #second_homing_speed: # Velocity (in mm/s) of the stepper when performing the second home. # The default is homing_speed/2. #homing_positive_dir: # If true, homing will cause the stepper to move in a positive # direction (away from zero); if false, home towards zero. It is # better to use the default than to specify this parameter. The # default is true if position_endstop is near position_max and false # if near position_min. Cartesian Kinematics \u00b6 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 \u00b6 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. [printer] kinematics: delta max_z_velocity: # For delta printers this limits the maximum velocity (in mm/s) of # moves with z axis movement. This setting can be used to reduce the # maximum speed of up/down moves (which require a higher step rate # than other moves on a delta printer). 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. Setting this may be useful if the printer can reach higher # acceleration on XY moves than Z moves (eg, when using input shaper). # The default is to use max_accel for max_z_accel. #minimum_z_position: 0 # The minimum Z position that the user may command the head to move # to. The default is 0. delta_radius: # Radius (in mm) of the horizontal circle formed by the three linear # axis towers. This parameter may also be calculated as: # delta_radius = smooth_rod_offset - effector_offset - carriage_offset # This parameter must be provided. #print_radius: # The radius (in mm) of valid toolhead XY coordinates. One may use # this setting to customize the range checking of toolhead moves. If # a large value is specified here then it may be possible to command # the toolhead into a collision with a tower. The default is to use # delta_radius for print_radius (which would normally prevent a # tower collision). # The stepper_a section describes the stepper controlling the front # left tower (at 210 degrees). This section also controls the homing # parameters (homing_speed, homing_retract_dist) for all towers. [stepper_a] position_endstop: # Distance (in mm) between the nozzle and the bed when the nozzle is # in the center of the build area and the endstop triggers. This # parameter must be provided for stepper_a; for stepper_b and # stepper_c this parameter defaults to the value specified for # stepper_a. arm_length: # Length (in mm) of the diagonal rod that connects this tower to the # print head. This parameter must be provided for stepper_a; for # stepper_b and stepper_c this parameter defaults to the value # specified for stepper_a. #angle: # This option specifies the angle (in degrees) that the tower is # at. The default is 210 for stepper_a, 330 for stepper_b, and 90 # for stepper_c. # The stepper_b section describes the stepper controlling the front # right tower (at 330 degrees). [stepper_b] # The stepper_c section describes the stepper controlling the rear # tower (at 90 degrees). [stepper_c] # The delta_calibrate section enables a DELTA_CALIBRATE extended # g-code command that can calibrate the tower endstop positions and # angles. [delta_calibrate] radius: # Radius (in mm) of the area that may be probed. This is the radius # of nozzle coordinates to be probed; if using an automatic probe # with an XY offset then choose a radius small enough so that the # probe always fits over the bed. This parameter must be provided. #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. Deltesian Kinematics \u00b6 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. [printer] kinematics: deltesian max_z_velocity: # For deltesian printers, this limits the maximum velocity (in mm/s) of # moves with z axis movement. This setting can be used to reduce the # maximum speed of up/down moves (which require a higher step rate # than other moves on a deltesian printer). 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. Setting this may be useful if the printer can reach higher # acceleration on XY moves than Z moves (eg, when using input shaper). # The default is to use max_accel for max_z_accel. #minimum_z_position: 0 # The minimum Z position that the user may command the head to move # to. The default is 0. #min_angle: 5 # This represents the minimum angle (in degrees) relative to horizontal # that the deltesian arms are allowed to achieve. This parameter is # intended to restrict the arms from becoming completely horizontal, # which would risk accidental inversion of the XZ axis. The default is 5. #print_width: # The distance (in mm) of valid toolhead X coordinates. One may use # this setting to customize the range checking of toolhead moves. If # a large value is specified here then it may be possible to command # the toolhead into a collision with a tower. This setting usually # corresponds to bed width (in mm). #slow_ratio: 3 # The ratio used to limit velocity and acceleration on moves near the # extremes of the X axis. If vertical distance divided by horizontal # distance exceeds the value of slow_ratio, then velocity and # acceleration are limited to half their nominal values. If vertical # distance divided by horizontal distance exceeds twice the value of # the slow_ratio, then velocity and acceleration are limited to one # quarter of their nominal values. The default is 3. # The stepper_left section is used to describe the stepper controlling # the left tower. This section also controls the homing parameters # (homing_speed, homing_retract_dist) for all towers. [stepper_left] position_endstop: # Distance (in mm) between the nozzle and the bed when the nozzle is # in the center of the build area and the endstops are triggered. This # parameter must be provided for stepper_left; for stepper_right this # parameter defaults to the value specified for stepper_left. arm_length: # Length (in mm) of the diagonal rod that connects the tower carriage to # the print head. This parameter must be provided for stepper_left; for # stepper_right, this parameter defaults to the value specified for # stepper_left. arm_x_length: # Horizontal distance between the print head and the tower when the # printers is homed. This parameter must be provided for stepper_left; # for stepper_right, this parameter defaults to the value specified for # stepper_left. # The stepper_right section is used to describe the stepper controlling the # right tower. [stepper_right] # The stepper_y section is used to describe the stepper controlling # the Y axis in a deltesian robot. [stepper_y] CoreXY Kinematics \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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. # 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 \u00b6 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. [printer] kinematics: rotary_delta max_z_velocity: # For delta printers this limits the maximum velocity (in mm/s) of # moves with z axis movement. This setting can be used to reduce the # maximum speed of up/down moves (which require a higher step rate # than other moves on a delta printer). The default is to use # max_velocity for max_z_velocity. #minimum_z_position: 0 # The minimum Z position that the user may command the head to move # to. The default is 0. shoulder_radius: # Radius (in mm) of the horizontal circle formed by the three # shoulder joints, minus the radius of the circle formed by the # effector joints. This parameter may also be calculated as: # shoulder_radius = (delta_f - delta_e) / sqrt(12) # This parameter must be provided. shoulder_height: # Distance (in mm) of the shoulder joints from the bed, minus the # effector toolhead height. This parameter must be provided. # The stepper_a section describes the stepper controlling the rear # right arm (at 30 degrees). This section also controls the homing # parameters (homing_speed, homing_retract_dist) for all arms. [stepper_a] gear_ratio: # A gear_ratio must be specified and rotation_distance may not be # specified. For example, if the arm has an 80 toothed pulley driven # by a pulley with 16 teeth, which is in turn connected to a 60 # toothed pulley driven by a stepper with a 16 toothed pulley, then # one would specify a gear ratio of \"80:16, 60:16\". This parameter # must be provided. position_endstop: # Distance (in mm) between the nozzle and the bed when the nozzle is # in the center of the build area and the endstop triggers. This # parameter must be provided for stepper_a; for stepper_b and # stepper_c this parameter defaults to the value specified for # stepper_a. upper_arm_length: # Length (in mm) of the arm connecting the \"shoulder joint\" to the # \"elbow joint\". This parameter must be provided for stepper_a; for # stepper_b and stepper_c this parameter defaults to the value # specified for stepper_a. lower_arm_length: # Length (in mm) of the arm connecting the \"elbow joint\" to the # \"effector joint\". This parameter must be provided for stepper_a; # for stepper_b and stepper_c this parameter defaults to the value # specified for stepper_a. #angle: # This option specifies the angle (in degrees) that the arm is at. # The default is 30 for stepper_a, 150 for stepper_b, and 270 for # stepper_c. # The stepper_b section describes the stepper controlling the rear # left arm (at 150 degrees). [stepper_b] # The stepper_c section describes the stepper controlling the front # arm (at 270 degrees). [stepper_c] # The delta_calibrate section enables a DELTA_CALIBRATE extended # g-code command that can calibrate the shoulder endstop positions. [delta_calibrate] radius: # Radius (in mm) of the area that may be probed. This is the radius # of nozzle coordinates to be probed; if using an automatic probe # with an XY offset then choose a radius small enough so that the # probe always fits over the bed. This parameter must be provided. #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. Cable winch Kinematics \u00b6 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 \u00b6 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 the following three carriages: [carriage x] , [carriage y] , and [carriage z] , e.g. [carriage x] endstop_pin: # Endstop switch detection pin. If this endstop pin is on a # different mcu than the stepper motor(s) moving this carriage, # then it enables \"multi-mcu homing\". This parameter must be provided. #position_min: 0 # Minimum valid distance (in mm) the user may command the carriage to # move to. The default is 0mm. position_endstop: # Location of the endstop (in mm). This parameter must be provided. position_max: # Maximum valid distance (in mm) the user may command the stepper to # move to. This parameter must be provided. #homing_speed: 5.0 # Maximum velocity (in mm/s) of the carriage when homing. The default # is 5mm/s. #homing_retract_dist: 5.0 # Distance to backoff (in mm) before homing a second time during # homing. Set this to zero to disable the second home. The default # is 5mm. #homing_retract_speed: # Speed to use on the retract move after homing in case this should # be different from the homing speed, which is the default for this # parameter #second_homing_speed: # Velocity (in mm/s) of the carriage when performing the second home. # The default is homing_speed/2. #homing_positive_dir: # If true, homing will cause the carriage to move in a positive # direction (away from zero); if false, home towards zero. It is # better to use the default than to specify this parameter. The # default is true if position_endstop is near position_max and false # if near position_min. 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. x, x+y, y-0.5*z, x-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, x+y indicates that the motion of the stepper in the positive direction by the distance d moves the carriages x and y by the same distance d in the positive direction, while x-0.5*y means the motion of the stepper in the positive direction by the distance d moves the carriage x by the distance d in the positive direction, but the 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 x] endstop_pin: ... ... [carriage y] endstop_pin: ... ... [stepper a0] carriages: x-y step_pin: ... dir_pin: ... enable_pin: ... rotation_distance: ... ... [stepper a1] carriages: x-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 beam, 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 y1] primary_carriage: y endstop_pin: ... [stepper sy1] carriages: 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 \u00b6 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 \u00b6 [extruder] \u00b6 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. [extruder] step_pin: dir_pin: enable_pin: microsteps: rotation_distance: #full_steps_per_rotation: #gear_ratio: # See the \"stepper\" section for a description of the above # parameters. If none of the above parameters are specified then no # stepper will be associated with the nozzle hotend (though a # SYNC_EXTRUDER_MOTION command may associate one at run-time). nozzle_diameter: # Diameter of the nozzle orifice (in mm). This parameter must be # provided. filament_diameter: # The nominal diameter of the raw filament (in mm) as it enters the # extruder. This parameter must be provided. #max_extrude_cross_section: # Maximum area (in mm^2) of an extrusion cross section (eg, # extrusion width multiplied by layer height). This setting prevents # excessive amounts of extrusion during relatively small XY moves. # If a move requests an extrusion rate that would exceed this value # it will cause an error to be returned. The default is: 4.0 * # nozzle_diameter^2 #instantaneous_corner_velocity: 1.000 # The maximum instantaneous velocity change (in mm/s) of the # extruder during the junction of two moves. The default is 1mm/s. #max_extrude_only_distance: 50.0 # Maximum length (in mm of raw filament) that a retraction or # extrude-only move may have. If a retraction or extrude-only move # requests a distance greater than this value it will cause an error # to be returned. The default is 50mm. #max_extrude_only_velocity: #max_extrude_only_accel: # Maximum velocity (in mm/s) and acceleration (in mm/s^2) of the # extruder motor for retractions and extrude-only moves. These # settings do not have any impact on normal printing moves. If not # specified then they are calculated to match the limit an XY # printing move with a cross section of 4.0*nozzle_diameter^2 would # have. #pressure_advance: 0.0 # The amount of raw filament to push into the extruder during # extruder acceleration. An equal amount of filament is retracted # during deceleration. It is measured in millimeters per # millimeter/second. The default is 0, which disables pressure # advance. #pressure_advance_smooth_time: 0.040 # A time range (in seconds) to use when calculating the average # extruder velocity for pressure advance. A larger value results in # smoother extruder movements. This parameter may not exceed 200ms. # This setting only applies if pressure_advance is non-zero. The # default is 0.040 (40 milliseconds). # # The remaining variables describe the extruder heater. heater_pin: # PWM output pin controlling the heater. This parameter must be # provided. #max_power: 1.0 # The maximum power (expressed as a value from 0.0 to 1.0) that the # heater_pin may be set to. The value 1.0 allows the pin to be set # fully enabled for extended periods, while a value of 0.5 would # allow the pin to be enabled for no more than half the time. This # setting may be used to limit the total power output (over extended # periods) to the heater. The default is 1.0. sensor_type: # Type of sensor - common thermistors are \"EPCOS 100K B57560G104F\", # \"ATC Semitec 104GT-2\", \"ATC Semitec 104NT-4-R025H42G\", \"Generic # 3950\",\"Honeywell 100K 135-104LAG-J01\", \"NTC 100K MGB18-104F39050L32\", # \"SliceEngineering 450\", and \"TDK NTCG104LH104JT1\". See the # \"Temperature sensors\" section for other sensors. This parameter # must be provided. sensor_pin: # Analog input pin connected to the sensor. This parameter must be # provided. #pullup_resistor: 4700 # The resistance (in ohms) of the pullup attached to the thermistor. # This parameter is only valid when the sensor is a thermistor. The # default is 4700 ohms. #smooth_time: 1.0 # A time value (in seconds) over which temperature measurements will # be smoothed to reduce the impact of measurement noise. The default # is 1 seconds. control: # Control algorithm (either pid or watermark). This parameter must # be provided. pid_Kp: pid_Ki: pid_Kd: # The proportional (pid_Kp), integral (pid_Ki), and derivative # (pid_Kd) settings for the PID feedback control system. Klipper # evaluates the PID settings with the following general formula: # heater_pwm = (Kp*error + Ki*integral(error) - Kd*derivative(error)) / 255 # Where \"error\" is \"requested_temperature - measured_temperature\" # and \"heater_pwm\" is the requested heating rate with 0.0 being full # off and 1.0 being full on. Consider using the PID_CALIBRATE # command to obtain these parameters. The pid_Kp, pid_Ki, and pid_Kd # parameters must be provided for PID heaters. #max_delta: 2.0 # On 'watermark' controlled heaters this is the number of degrees in # Celsius above the target temperature before disabling the heater # as well as the number of degrees below the target before # re-enabling the heater. The default is 2 degrees Celsius. #pwm_cycle_time: 0.100 # Time in seconds for each software PWM cycle of the heater. It is # not recommended to set this unless there is an electrical # requirement to switch the heater faster than 10 times a second. # The default is 0.100 seconds. #min_extrude_temp: 170 # The minimum temperature (in Celsius) at which extruder move # commands may be issued. The default is 170 Celsius. min_temp: max_temp: # The maximum range of valid temperatures (in Celsius) that the # heater must remain within. This controls a safety feature # implemented in the micro-controller code - should the measured # temperature ever fall outside this range then the micro-controller # will go into a shutdown state. This check can help detect some # heater and sensor hardware failures. Set this range just wide # enough so that reasonable temperatures do not result in an error. # These parameters must be provided. [heater_bed] \u00b6 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 \u00b6 [bed_mesh] \u00b6 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 [bed_mesh] #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. #mesh_radius: # Defines the radius of the mesh to probe for round beds. Note that # the radius is relative to the coordinate specified by the # mesh_origin option. This parameter must be provided for round beds # and omitted for rectangular beds. #mesh_origin: # Defines the center X, Y coordinate of the mesh for round beds. This # coordinate is relative to the probe's location. It may be useful # to adjust the mesh_origin in an effort to maximize the size of the # mesh radius. Default is 0, 0. This parameter must be omitted for # rectangular beds. #mesh_min: # Defines the minimum X, Y coordinate of the mesh for rectangular # beds. This coordinate is relative to the probe's location. This # will be the first point probed, nearest to the origin. This # parameter must be provided for rectangular beds. #mesh_max: # Defines the maximum X, Y coordinate of the mesh for rectangular # beds. Adheres to the same principle as mesh_min, however this will # be the furthest point probed from the bed's origin. This parameter # must be provided for rectangular beds. #probe_count: 3, 3 # For rectangular beds, this is a comma separate pair of integer # values X, Y defining the number of points to probe along each # axis. A single value is also valid, in which case that value will # be applied to both axes. Default is 3, 3. #round_probe_count: 5 # For round beds, this integer value defines the maximum number of # points to probe along each axis. This value must be an odd number. # Default is 5. #fade_start: 1.0 # The gcode z position in which to start phasing out z-adjustment # when fade is enabled. Default is 1.0. #fade_end: 0.0 # The gcode z position in which phasing out completes. When set to a # value below fade_start, fade is disabled. It should be noted that # fade may add unwanted scaling along the z-axis of a print. If a # user wishes to enable fade, a value of 10.0 is recommended. # Default is 0.0, which disables fade. #fade_target: # The z position in which fade should converge. When this value is # set to a non-zero value it must be within the range of z-values in # the mesh. Users that wish to converge to the z homing position # should set this to 0. Default is the average z value of the mesh. #split_delta_z: .025 # The amount of Z difference (in mm) along a move that will trigger # a split. Default is .025. #move_check_distance: 5.0 # The distance (in mm) along a move to check for split_delta_z. # This is also the minimum length that a move can be split. Default # is 5.0. #mesh_pps: 2, 2 # A comma separated pair of integers X, Y defining the number of # points per segment to interpolate in the mesh along each axis. A # \"segment\" can be defined as the space between each probed point. # The user may enter a single value which will be applied to both # axes. Default is 2, 2. #algorithm: lagrange # The interpolation algorithm to use. May be either \"lagrange\" or # \"bicubic\". This option will not affect 3x3 grids, which are forced # to use lagrange sampling. Default is lagrange. #bicubic_tension: .2 # When using the bicubic algorithm the tension parameter above may # be applied to change the amount of slope interpolated. Larger # numbers will increase the amount of slope, which results in more # curvature in the mesh. Default is .2. #zero_reference_position: # An optional X,Y coordinate that specifies the location on the bed # where Z = 0. When this option is specified the mesh will be offset # so that zero Z adjustment occurs at this location. The default is # no zero reference. #faulty_region_1_min: #faulty_region_1_max: # Optional points that define a faulty region. See docs/Bed_Mesh.md # for details on faulty regions. Up to 99 faulty regions may be added. # By default no faulty regions are set. #adaptive_margin: # An optional margin (in mm) to be added around the bed area used by # the defined print objects when generating an adaptive mesh. #scan_overshoot: # 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. [bed_tilt] \u00b6 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] \u00b6 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] \u00b6 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] \u00b6 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. [z_tilt] #z_positions: # A list of X, Y coordinates (one per line; subsequent lines # indented) describing the location of each bed \"pivot point\". The # \"pivot point\" is the point where the bed attaches to the given Z # stepper. It is described using nozzle coordinates (the X, Y position # of the nozzle if it could move directly above the point). The # first entry corresponds to stepper_z, the second to stepper_z1, # the third to stepper_z2, etc. This parameter must be provided. #points: # A list of X, Y coordinates (one per line; subsequent lines # indented) that should be probed during a Z_TILT_ADJUST command. # Specify coordinates of the nozzle and be sure the probe is above # the bed at the given nozzle coordinates. This parameter must be # provided. #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. #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. Note the smallest unit of # change here would be a single step. However if you are probing # more points than steppers then you will likely have a fixed # minimum value for the range of probed points which you can learn # by observing command output. [quad_gantry_level] \u00b6 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] \u00b6 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] \u00b6 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 \u00b6 [safe_z_home] \u00b6 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] \u00b6 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] \u00b6 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 \u00b6 [gcode_macro] \u00b6 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] \u00b6 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] \u00b6 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] \u00b6 Idle timeout. An idle timeout is automatically enabled - add an explicit idle_timeout config section to change the default settings. [idle_timeout] #gcode: # A list of G-Code commands to execute on an idle timeout. See # docs/Command_Templates.md for G-Code format. The default is to run # \"TURN_OFF_HEATERS\" and \"M84\". #timeout: 600 # Idle time (in seconds) to wait before running the above G-Code # commands. The default is 600 seconds. Optional G-Code features \u00b6 [virtual_sdcard] \u00b6 A virtual sdcard may be useful if the host machine is not fast enough to run OctoPrint well. It allows the Klipper host software to directly print gcode files stored in a directory on the host using standard sdcard G-Code commands (eg, M24). [virtual_sdcard] path: # The path of the local directory on the host machine to look for # g-code files. This is a read-only directory (sdcard file writes # are not supported). One may point this to OctoPrint's upload # directory (generally ~/.octoprint/uploads/ ). This parameter must # be provided. #on_error_gcode: # A list of G-Code commands to execute when an error is reported. # See docs/Command_Templates.md for G-Code format. The default is to # run TURN_OFF_HEATERS. [sdcard_loop] \u00b6 Some printers with stage-clearing features, such as a part ejector or a belt printer, can find use in looping sections of the sdcard file. (For example, to print the same part over and over, or repeat the a section of a part for a chain or other repeated pattern). See the command reference for supported commands. See the sample-macros.cfg file for a Marlin compatible M808 G-Code macro. [sdcard_loop] [force_move] \u00b6 Support manually moving stepper motors for diagnostic purposes. Note, using this feature may place the printer in an invalid state - see the command reference for important details. [force_move] #enable_force_move: False # Set to true to enable FORCE_MOVE and SET_KINEMATIC_POSITION # extended G-Code commands. The default is false. [pause_resume] \u00b6 Pause/Resume functionality with support of position capture and restore. See the command reference for more information. [pause_resume] #recover_velocity: 50. # When capture/restore is enabled, the speed at which to return to # the captured position (in mm/s). Default is 50.0 mm/s. [firmware_retraction] \u00b6 Firmware filament retraction. This enables G10 (retract) and G11 (unretract) GCODE commands issued by many slicers. The parameters below provide startup defaults, although the values can be adjusted via the SET_RETRACTION command ), allowing per-filament settings and runtime tuning. [firmware_retraction] #retract_length: 0 # The length of filament (in mm) to retract when G10 is activated, # and to unretract when G11 is activated (but see # unretract_extra_length below). The default is 0 mm. #retract_speed: 20 # The speed of retraction, in mm/s. The default is 20 mm/s. #unretract_extra_length: 0 # The length (in mm) of *additional* filament to add when # unretracting. #unretract_speed: 10 # The speed of unretraction, in mm/s. The default is 10 mm/s. [gcode_arcs] \u00b6 Support for gcode arc (G2/G3) commands. [gcode_arcs] #resolution: 1.0 # An arc will be split into segments. Each segment's length will # equal the resolution in mm set above. Lower values will produce a # finer arc, but also more work for your machine. Arcs smaller than # the configured value will become straight lines. The default is # 1mm. [respond] \u00b6 Enable the \"M118\" and \"RESPOND\" extended commands . [respond] #default_type: echo # Sets the default prefix of the \"M118\" and \"RESPOND\" output to one # of the following: # echo: \"echo: \" (This is the default) # command: \"// \" # error: \"!! \" #default_prefix: echo: # Directly sets the default prefix. If present, this value will # override the \"default_type\". [exclude_object] \u00b6 Enables support to exclude or cancel individual objects during the printing process. See the exclude objects guide and command reference for additional information. See the sample-macros.cfg file for a Marlin/RepRapFirmware compatible M486 G-Code macro. [exclude_object] Resonance compensation \u00b6 [input_shaper] \u00b6 Enables resonance compensation . Also see the command reference . [input_shaper] #shaper_freq_x: 0 # A frequency (in Hz) of the input shaper for X axis. This is # usually a resonance frequency of X axis that the input shaper # should suppress. For more complex shapers, like 2- and 3-hump EI # input shapers, this parameter can be set from different # considerations. The default value is 0, which disables input # shaping for X axis. #shaper_freq_y: 0 # A frequency (in Hz) of the input shaper for Y axis. This is # usually a resonance frequency of Y axis that the input shaper # should suppress. For more complex shapers, like 2- and 3-hump EI # input shapers, this parameter can be set from different # considerations. The default value is 0, which disables input # shaping for Y axis. #shaper_type: mzv # A type of the input shaper to use for both X and Y axes. Supported # shapers are zv, mzv, zvd, ei, 2hump_ei, and 3hump_ei. The default # is mzv input shaper. #shaper_type_x: #shaper_type_y: # If shaper_type is not set, these two parameters can be used to # configure different input shapers for X and Y axes. The same # values are supported as for shaper_type parameter. #damping_ratio_x: 0.1 #damping_ratio_y: 0.1 # Damping ratios of vibrations of X and Y axes used by input shapers # to improve vibration suppression. Default value is 0.1 which is a # good all-round value for most printers. In most circumstances this # parameter requires no tuning and should not be changed. [adxl345] \u00b6 Support for ADXL345 accelerometers. This support allows one to query accelerometer measurements from the sensor. This enables an ACCELEROMETER_MEASURE command (see G-Codes for more information). The default chip name is \"default\", but one may specify an explicit name (eg, [adxl345 my_chip_name]). [adxl345] cs_pin: # The SPI enable pin for the sensor. This parameter must be provided. #spi_speed: 5000000 # The SPI speed (in hz) to use when communicating with the chip. # The default is 5000000. #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #axes_map: x, y, z # The accelerometer axis for each of the printer's X, Y, and Z axes. # This may be useful if the accelerometer is mounted in an # orientation that does not match the printer orientation. For # example, one could set this to \"y, x, z\" to swap the X and Y axes. # It is also possible to negate an axis if the accelerometer # direction is reversed (eg, \"x, z, -y\"). The default is \"x, y, z\". #rate: 3200 # Output data rate for ADXL345. ADXL345 supports the following data # rates: 3200, 1600, 800, 400, 200, 100, 50, and 25. Note that it is # not recommended to change this rate from the default 3200, and # rates below 800 will considerably affect the quality of resonance # measurements. [icm20948] \u00b6 Support for icm20948 accelerometers. [icm20948] #i2c_address: # Default is 104 (0x68). If AD0 is high, it would be 0x69 instead. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: 400000 # See the \"common I2C settings\" section for a description of the # above parameters. The default \"i2c_speed\" is 400000. #axes_map: x, y, z # See the \"adxl345\" section for information on this parameter. [lis2dw] \u00b6 Support for LIS2DW accelerometers. [lis2dw] #cs_pin: # The SPI enable pin for the sensor. This parameter must be provided # if using SPI. #spi_speed: 5000000 # The SPI speed (in hz) to use when communicating with the chip. # The default is 5000000. #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #i2c_address: # Default is 25 (0x19). If SA0 is high, it would be 24 (0x18) instead. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: 400000 # See the \"common I2C settings\" section for a description of the # above parameters. The default \"i2c_speed\" is 400000. #axes_map: x, y, z # See the \"adxl345\" section for information on this parameter. [lis3dh] \u00b6 Support for LIS3DH accelerometers. [lis3dh] #cs_pin: # The SPI enable pin for the sensor. This parameter must be provided # if using SPI. #spi_speed: 5000000 # The SPI speed (in hz) to use when communicating with the chip. # The default is 5000000. #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #i2c_address: # Default is 25 (0x19). If SA0 is high, it would be 24 (0x18) instead. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: 400000 # See the \"common I2C settings\" section for a description of the # above parameters. The default \"i2c_speed\" is 400000. #axes_map: x, y, z # See the \"adxl345\" section for information on this parameter. [mpu9250] \u00b6 Support for MPU-9250, MPU-9255, MPU-6515, MPU-6050, and MPU-6500 accelerometers (one may define any number of sections with an \"mpu9250\" prefix). [mpu9250 my_accelerometer] #i2c_address: # Default is 104 (0x68). If AD0 is high, it would be 0x69 instead. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: 400000 # See the \"common I2C settings\" section for a description of the # above parameters. The default \"i2c_speed\" is 400000. #axes_map: x, y, z # See the \"adxl345\" section for information on this parameter. [resonance_tester] \u00b6 Support for resonance testing and automatic input shaper calibration. In order to use most of the functionality of this module, additional software dependencies must be installed; refer to Measuring Resonances and the command reference for more information. See the Max smoothing section of the measuring resonances guide for more information on max_smoothing parameter and its use. [resonance_tester] #probe_points: # A list of X, Y, Z coordinates of points (one point per line) to test # resonances at. At least one point is required. Make sure that all # points with some safety margin in XY plane (~a few centimeters) # are reachable by the toolhead. #accel_chip: # A name of the accelerometer chip to use for measurements. If # adxl345 chip was defined without an explicit name, this parameter # can simply reference it as \"accel_chip: adxl345\", otherwise an # explicit name must be supplied as well, e.g. \"accel_chip: adxl345 # my_chip_name\". Either this, or the next two parameters must be # set. #accel_chip_x: #accel_chip_y: # Names of the accelerometer chips to use for measurements for each # of the axis. Can be useful, for instance, on bed slinger printer, # if two separate accelerometers are mounted on the bed (for Y axis) # and on the toolhead (for X axis). These parameters have the same # format as 'accel_chip' parameter. Only 'accel_chip' or these two # parameters must be provided. #max_smoothing: # Maximum input shaper smoothing to allow for each axis during shaper # auto-calibration (with 'SHAPER_CALIBRATE' command). By default no # maximum smoothing is specified. Refer to Measuring_Resonances guide # for more details on using this feature. #move_speed: 50 # The speed (in mm/s) to move the toolhead to and between test points # during the calibration. The default is 50. #min_freq: 5 # Minimum frequency to test for resonances. The default is 5 Hz. #max_freq: 133.33 # Maximum frequency to test for resonances. The default is 133.33 Hz. #accel_per_hz: 60 # This parameter is used to determine which acceleration to use to # test a specific frequency: accel = accel_per_hz * freq. Higher the # value, the higher is the energy of the oscillations. Can be set to # a lower than the default value if the resonances get too strong on # the printer. However, lower values make measurements of # high-frequency resonances less precise. The default value is 75 # (mm/sec). #hz_per_sec: 1 # Determines the speed of the test. When testing all frequencies in # range [min_freq, max_freq], each second the frequency increases by # hz_per_sec. Small values make the test slow, and the large values # will decrease the precision of the test. The default value is 1.0 # (Hz/sec == sec^-2). #sweeping_accel: 400 # An acceleration of slow sweeping moves. The default is 400 mm/sec^2. #sweeping_period: 1.2 # A period of slow sweeping moves. Setting this parameter to 0 # disables slow sweeping moves. Avoid setting it to a too small # non-zero value in order to not poison the measurements. # The default is 1.2 sec which is a good all-round choice. Config file helpers \u00b6 [board_pins] \u00b6 Board pin aliases (one may define any number of sections with a \"board_pins\" prefix). Use this to define aliases for the pins on a micro-controller. [board_pins my_aliases] mcu: mcu # A comma separated list of micro-controllers that may use the # aliases. The default is to apply the aliases to the main \"mcu\". aliases: aliases_<name>: # A comma separated list of \"name=value\" aliases to create for the # given micro-controller. For example, \"EXP1_1=PE6\" would create an # \"EXP1_1\" alias for the \"PE6\" pin. However, if \"value\" is enclosed # in \"<>\" then \"name\" is created as a reserved pin (for example, # \"EXP1_9=<GND>\" would reserve \"EXP1_9\"). Any number of options # starting with \"aliases_\" may be specified. [include] \u00b6 Include file support. One may include additional config file from the main printer config file. Wildcards may also be used (eg, \"configs/*.cfg\"). [include my_other_config.cfg] [duplicate_pin_override] \u00b6 This tool allows a single micro-controller pin to be defined multiple times in a config file without normal error checking. This is intended for diagnostic and debugging purposes. This section is not needed where Klipper supports using the same pin multiple times, and using this override may cause confusing and unexpected results. [duplicate_pin_override] pins: # A comma separated list of pins that may be used multiple times in # a config file without normal error checks. This parameter must be # provided. Bed probing hardware \u00b6 [probe] \u00b6 Z height probe. One may define this section to enable Z height probing hardware. When this section is enabled, PROBE and QUERY_PROBE extended g-code commands become available. Also, see the probe calibrate guide . The probe section also creates a virtual \"probe:z_virtual_endstop\" pin. One may set the stepper_z endstop_pin to this virtual pin on cartesian style printers that use the probe in place of a z endstop. If using \"probe:z_virtual_endstop\" then do not define a position_endstop in the stepper_z config section. [probe] pin: # Probe detection pin. If the pin is on a different microcontroller # than the Z steppers then it enables \"multi-mcu homing\". This # parameter must be provided. #deactivate_on_each_sample: True # This determines if Klipper should execute deactivation gcode # between each probe attempt when performing a multiple probe # sequence. The default is True. #x_offset: 0.0 # The distance (in mm) between the probe and the nozzle along the # x-axis. The default is 0. #y_offset: 0.0 # The distance (in mm) between the probe and the nozzle along the # y-axis. The default is 0. z_offset: # The distance (in mm) between the bed and the nozzle when the probe # triggers. This parameter must be provided. #speed: 5.0 # Speed (in mm/s) of the Z axis when probing. The default is 5mm/s. #samples: 1 # The number of times to probe each point. The probed z-values will # be averaged. The default is to probe 1 time. #sample_retract_dist: 2.0 # The distance (in mm) to lift the toolhead between each sample (if # sampling more than once). The default is 2mm. #lift_speed: # Speed (in mm/s) of the Z axis when lifting the probe between # samples. The default is to use the same value as the 'speed' # parameter. #samples_result: average # The calculation method when sampling more than once - either # \"median\" or \"average\". The default is average. #samples_tolerance: 0.100 # The maximum Z distance (in mm) that a sample may differ from other # samples. If this tolerance is exceeded then either an error is # reported or the attempt is restarted (see # samples_tolerance_retries). The default is 0.100mm. #samples_tolerance_retries: 0 # The number of times to retry if a sample is found that exceeds # samples_tolerance. On a retry, all current samples are discarded # and the probe attempt is restarted. If a valid set of samples are # not obtained in the given number of retries then an error is # reported. The default is zero which causes an error to be reported # on the first sample that exceeds samples_tolerance. #activate_gcode: # A list of G-Code commands to execute prior to each probe attempt. # See docs/Command_Templates.md for G-Code format. This may be # useful if the probe needs to be activated in some way. Do not # issue any commands here that move the toolhead (eg, G1). The # default is to not run any special G-Code commands on activation. #deactivate_gcode: # A list of G-Code commands to execute after each probe attempt # completes. See docs/Command_Templates.md for G-Code format. Do not # issue any commands here that move the toolhead. The default is to # not run any special G-Code commands on deactivation. [bltouch] \u00b6 BLTouch probe. One may define this section (instead of a probe section) to enable a BLTouch probe. See BL-Touch guide and command reference for further information. A virtual \"probe:z_virtual_endstop\" pin is also created (see the \"probe\" section for the details). [bltouch] sensor_pin: # Pin connected to the BLTouch sensor pin. Most BLTouch devices # require a pullup on the sensor pin (prefix the pin name with \"^\"). # This parameter must be provided. control_pin: # Pin connected to the BLTouch control pin. This parameter must be # provided. #pin_move_time: 0.680 # The amount of time (in seconds) to wait for the BLTouch pin to # move up or down. The default is 0.680 seconds. #stow_on_each_sample: True # This determines if Klipper should command the pin to move up # between each probe attempt when performing a multiple probe # sequence. Read the directions in docs/BLTouch.md before setting # this to False. The default is True. #probe_with_touch_mode: False # If this is set to True then Klipper will probe with the device in # \"touch_mode\". The default is False (probing in \"pin_down\" mode). #pin_up_reports_not_triggered: True # Set if the BLTouch consistently reports the probe in a \"not # triggered\" state after a successful \"pin_up\" command. This should # be True for all genuine BLTouch devices. Read the directions in # docs/BLTouch.md before setting this to False. The default is True. #pin_up_touch_mode_reports_triggered: True # Set if the BLTouch consistently reports a \"triggered\" state after # the commands \"pin_up\" followed by \"touch_mode\". This should be # True for all genuine BLTouch devices. Read the directions in # docs/BLTouch.md before setting this to False. The default is True. #set_output_mode: # Request a specific sensor pin output mode on the BLTouch V3.0 (and # later). This setting should not be used on other types of probes. # Set to \"5V\" to request a sensor pin output of 5 Volts (only use if # the controller board needs 5V mode and is 5V tolerant on its input # signal line). Set to \"OD\" to request the sensor pin output use # open drain mode. The default is to not request an output mode. #x_offset: #y_offset: #z_offset: #speed: #lift_speed: #samples: #sample_retract_dist: #samples_result: #samples_tolerance: #samples_tolerance_retries: # See the \"probe\" section for information on these parameters. [smart_effector] \u00b6 The \"Smart Effector\" from Duet3d implements a Z probe using a force sensor. One may define this section instead of [probe] to enable the Smart Effector specific features. This also enables runtime commands to adjust the parameters of the Smart Effector at run time. [smart_effector] pin: # Pin connected to the Smart Effector Z Probe output pin (pin 5). Note that # pullup resistor on the board is generally not required. However, if the # output pin is connected to the board pin with a pullup resistor, that # resistor must be high value (e.g. 10K Ohm or more). Some boards have a low # value pullup resistor on the Z probe input, which will likely result in an # always-triggered probe state. In this case, connect the Smart Effector to # a different pin on the board. This parameter is required. #control_pin: # Pin connected to the Smart Effector control input pin (pin 7). If provided, # Smart Effector sensitivity programming commands become available. #probe_accel: # If set, limits the acceleration of the probing moves (in mm/sec^2). # A sudden large acceleration at the beginning of the probing move may # cause spurious probe triggering, especially if the hotend is heavy. # To prevent that, it may be necessary to reduce the acceleration of # the probing moves via this parameter. #recovery_time: 0.4 # A delay between the travel moves and the probing moves in seconds. A fast # travel move prior to probing may result in a spurious probe triggering. # This may cause 'Probe triggered prior to movement' errors if no delay # is set. Value 0 disables the recovery delay. # Default value is 0.4. #x_offset: #y_offset: # Should be left unset (or set to 0). z_offset: # Trigger height of the probe. Start with -0.1 (mm), and adjust later using # `PROBE_CALIBRATE` command. This parameter must be provided. #speed: # Speed (in mm/s) of the Z axis when probing. It is recommended to start # with the probing speed of 20 mm/s and adjust it as necessary to improve # the accuracy and repeatability of the probe triggering. #samples: #sample_retract_dist: #samples_result: #samples_tolerance: #samples_tolerance_retries: #activate_gcode: #deactivate_gcode: #deactivate_on_each_sample: # See the \"probe\" section for more information on the parameters above. [probe_eddy_current] \u00b6 Support for eddy current inductive probes. One may define this section (instead of a probe section) to enable this probe. See the command reference for further information. [probe_eddy_current my_eddy_probe] sensor_type: ldc1612 # The sensor chip used to perform eddy current measurements. This # parameter must be provided and must be set to ldc1612. #frequency: # The external crystal frequency (in Hz) of the LDC1612 chip. # The default is 12000000. #intb_pin: # MCU gpio pin connected to the ldc1612 sensor's INTB pin (if # available). The default is to not use the INTB pin. #z_offset: # The nominal distance (in mm) between the nozzle and bed that a # probing attempt should stop at. This parameter must be provided. #i2c_address: #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # The i2c settings for the sensor chip. See the \"common I2C # settings\" section for a description of the above parameters. #x_offset: #y_offset: #speed: #lift_speed: #samples: #sample_retract_dist: #samples_result: #samples_tolerance: #samples_tolerance_retries: # See the \"probe\" section for information on these parameters. [axis_twist_compensation] \u00b6 A tool to compensate for inaccurate probe readings due to twist in X or Y gantry. See the Axis Twist Compensation Guide for more detailed information regarding symptoms, configuration and setup. [axis_twist_compensation] #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. calibrate_start_x: 20 # Defines the minimum X coordinate of the calibration # This should be the X coordinate that positions the nozzle at the starting # calibration position. calibrate_end_x: 200 # Defines the maximum X coordinate of the calibration # This should be the X coordinate that positions the nozzle at the ending # calibration position. calibrate_y: 112.5 # Defines the Y coordinate of the calibration # This should be the Y coordinate that positions the nozzle during the # calibration process. This parameter is recommended to # be near the center of the bed # For Y-axis twist compensation, specify the following parameters: calibrate_start_y: ... # Defines the minimum Y coordinate of the calibration # This should be the Y coordinate that positions the nozzle at the starting # calibration position for the Y axis. This parameter must be provided if # compensating for Y axis twist. calibrate_end_y: ... # Defines the maximum Y coordinate of the calibration # This should be the Y coordinate that positions the nozzle at the ending # calibration position for the Y axis. This parameter must be provided if # compensating for Y axis twist. calibrate_x: ... # Defines the X coordinate of the calibration for Y axis twist compensation # This should be the X coordinate that positions the nozzle during the # calibration process for Y axis twist compensation. This parameter must be # provided and is recommended to be near the center of the bed. Additional stepper motors and extruders \u00b6 [stepper_z1] \u00b6 Multi-stepper axes. On a cartesian style printer, the stepper controlling a given axis may have additional config blocks defining steppers that should be stepped in concert with the primary stepper. One may define any number of sections with a numeric suffix starting at 1 (for example, \"stepper_z1\", \"stepper_z2\", etc.). [stepper_z1] #step_pin: #dir_pin: #enable_pin: #microsteps: #rotation_distance: # See the \"stepper\" section for the definition of the above parameters. #endstop_pin: # If an endstop_pin is defined for the additional stepper then the # stepper will home until the endstop is triggered. Otherwise, the # stepper will home until the endstop on the primary stepper for the # axis is triggered. [extruder1] \u00b6 In a multi-extruder printer add an additional extruder section for each additional extruder. The additional extruder sections should be named \"extruder1\", \"extruder2\", \"extruder3\", and so on. See the \"extruder\" section for a description of available parameters. See sample-multi-extruder.cfg for an example configuration. [extruder1] #step_pin: #dir_pin: #... # See the \"extruder\" section for available stepper and heater # parameters. #shared_heater: # This option is deprecated and should no longer be specified. [dual_carriage] \u00b6 Support for cartesian, generic_cartesian and hybrid_corexy/z printers with dual carriages on a single axis. The carriage mode can be set via the SET_DUAL_CARRIAGE extended g-code command. For example, \"SET_DUAL_CARRIAGE CARRIAGE=1\" command will activate the carriage defined in this section (CARRIAGE=0 will return activation to the primary carriage). Dual carriage support is typically combined with extra extruders - the SET_DUAL_CARRIAGE command is often called at the same time as the ACTIVATE_EXTRUDER command. Be sure to park the carriages during deactivation. Note that during G28 homing, typically the primary carriage is homed first followed by the carriage defined in the [dual_carriage] config section. However, the [dual_carriage] carriage will be homed first if both carriages home in a positive direction and the [dual_carriage] carriage has a position_endstop greater than the primary carriage, or if both carriages home in a negative direction and the [dual_carriage] carriage has a position_endstop less than the primary carriage. Additionally, one could use \"SET_DUAL_CARRIAGE CARRIAGE=1 MODE=COPY\" or \"SET_DUAL_CARRIAGE CARRIAGE=1 MODE=MIRROR\" commands to activate either copying or mirroring mode of the dual carriage, in which case it will follow the motion of the carriage 0 accordingly. These commands can be used to print two parts simultaneously - either two identical parts (in COPY mode) or mirrored parts (in MIRROR mode). Note that COPY and MIRROR modes also require appropriate configuration of the extruder on the dual carriage, which can typically be achieved with \"SYNC_EXTRUDER_MOTION MOTION_QUEUE=extruder EXTRUDER= \" or a similar command. See sample-idex.cfg for an example configuration with a regular Cartesian kinematic. [dual_carriage] axis: # The axis this extra carriage is on (either x or y). This parameter # must be provided. #safe_distance: # The minimum distance (in mm) to enforce between the dual and the primary # carriages. If a G-Code command is executed that will bring the carriages # closer than the specified limit, such a command will be rejected with an # error. If safe_distance is not provided, it will be inferred from # position_min and position_max for the dual and primary carriages. If set # to 0 (or safe_distance is unset and position_min and position_max are # identical for the primary and dual carriages), the carriages proximity # checks will be disabled. #step_pin: #dir_pin: #enable_pin: #microsteps: #rotation_distance: #endstop_pin: #position_endstop: #position_min: #position_max: # See the \"stepper\" section for the definition of the above parameters. For an example of dual carriage configuration with generic_cartesian kinematic, see the following configuration sample . Please note that in this case the [dual_carriage] configuration deviates from the configuration described above: [dual_carriage my_dc_carriage] primary_carriage: # Defines the matching primary carriage of this dual carriage and # the corresponding IDEX axis. Valid choices are x, y, z. # This parameter must be provided. #safe_distance: # The minimum distance (in mm) to enforce between the dual and the primary # carriages. If a G-Code command is executed that will bring the carriages # closer than the specified limit, such a command will be rejected with an # error. If safe_distance is not provided, it will be inferred from # position_min and position_max for the dual and primary carriages. If set # to 0 (or safe_distance is unset and position_min and position_max are # identical for the primary and dual carriages), the carriages proximity # checks will be disabled. endstop_pin: #position_min: position_endstop: position_max: #homing_speed: #homing_retract_dist: #homing_retract_speed: #second_homing_speed: #homing_positive_dir: ... Refer to generic cartesian section for more information on the regular carriage parameters. Then a user must define one or more stepper motors moving the dual carriage (and other carriages as appropriate), for instance [carriage x] ... [carriage y] ... [dual_carriage u] primary_carriage: x ... [stepper dc_stepper] carriages: u-y ... [dual_carriage] requires special configuration for the input shaper. In general, it is necessary to run input shaper calibration twice - for the dual_carriage and its primary_carriage for the axis they share. Then the input shaper can be configured as follows, assuming the example above: [input_shaper] # Intentionally empty [delayed_gcode init_shaper] initial_duration: 0.1 gcode: SET_DUAL_CARRIAGE CARRIAGE=u SET_INPUT_SHAPER SHAPER_TYPE_X=<dual_carriage_x_shaper> SHAPER_FREQ_X=<dual_carriage_x_freq> SHAPER_TYPE_Y=<y_shaper> SHAPER_FREQ_Y=<y_freq> SET_DUAL_CARRIAGE CARRIAGE=x SET_INPUT_SHAPER SHAPER_TYPE_X=<primary_carriage_x_shaper> SHAPER_FREQ_X=<primary_carriage_x_freq> SHAPER_TYPE_Y=<y_shaper> SHAPER_FREQ_Y=<y_freq> Note that SHAPER_TYPE_Y and SHAPER_FREQ_Y must be the same in both commands in this case, since the same motors drive Y axis when either of the x and u carriages are active. It is worth noting that generic_cartesian kinematic can support two dual carriages for X and Y axes. For reference, see for instance a sample of CoreXYUV configuration. [extruder_stepper] \u00b6 Support for additional steppers synchronized to the movement of an extruder (one may define any number of sections with an \"extruder_stepper\" prefix). See the command reference for more information. [extruder_stepper my_extra_stepper] extruder: # The extruder this stepper is synchronized to. If this is set to an # empty string then the stepper will not be synchronized to an # extruder. This parameter must be provided. #step_pin: #dir_pin: #enable_pin: #microsteps: #rotation_distance: # See the \"stepper\" section for the definition of the above # parameters. [manual_stepper] \u00b6 Manual steppers (one may define any number of sections with a \"manual_stepper\" prefix). These are steppers that are controlled by the MANUAL_STEPPER g-code command. For example: \"MANUAL_STEPPER STEPPER=my_stepper MOVE=10 SPEED=5\". See G-Codes file for a description of the MANUAL_STEPPER command. The steppers are not connected to the normal printer kinematics. [manual_stepper my_stepper] #step_pin: #dir_pin: #enable_pin: #microsteps: #rotation_distance: # See the \"stepper\" section for a description of these parameters. #velocity: # Set the default velocity (in mm/s) for the stepper. This value # will be used if a MANUAL_STEPPER command does not specify a SPEED # parameter. The default is 5mm/s. #accel: # Set the default acceleration (in mm/s^2) for the stepper. An # acceleration of zero will result in no acceleration. This value # will be used if a MANUAL_STEPPER command does not specify an ACCEL # parameter. The default is zero. #endstop_pin: # Endstop switch detection pin. If specified, then one may perform # \"homing moves\" by adding a STOP_ON_ENDSTOP parameter to # MANUAL_STEPPER movement commands. #position_min: #position_max: # The minimum and maximum position the stepper can be commanded to # move to. If specified then one may not command the stepper to move # past the given position. Note that these limits do not prevent # setting an arbitrary position with the `MANUAL_STEPPER # SET_POSITION=x` command. The default is to not enforce a limit. Custom heaters and sensors \u00b6 [verify_heater] \u00b6 Heater and temperature sensor verification. Heater verification is automatically enabled for each heater that is configured on the printer. Use verify_heater sections to change the default settings. [verify_heater heater_config_name] #max_error: 120 # The maximum \"cumulative temperature error\" before raising an # error. Smaller values result in stricter checking and larger # values allow for more time before an error is reported. # Specifically, the temperature is inspected once a second and if it # is close to the target temperature then an internal \"error # counter\" is reset; otherwise, if the temperature is below the # target range then the counter is increased by the amount the # reported temperature differs from that range. Should the counter # exceed this \"max_error\" then an error is raised. The default is # 120. #check_gain_time: # This controls heater verification during initial heating. Smaller # values result in stricter checking and larger values allow for # more time before an error is reported. Specifically, during # initial heating, as long as the heater increases in temperature # within this time frame (specified in seconds) then the internal # \"error counter\" is reset. The default is 20 seconds for extruders # and 60 seconds for heater_bed. #hysteresis: 5 # The maximum temperature difference (in Celsius) to a target # temperature that is considered in range of the target. This # controls the max_error range check. It is rare to customize this # value. The default is 5. #heating_gain: 2 # The minimum temperature (in Celsius) that the heater must increase # by during the check_gain_time check. It is rare to customize this # value. The default is 2. [homing_heaters] \u00b6 Tool to disable heaters when homing or probing an axis. [homing_heaters] #steppers: # A comma separated list of steppers that should cause heaters to be # disabled. The default is to disable heaters for any homing/probing # move. # Typical example: stepper_z #heaters: # A comma separated list of heaters to disable during homing/probing # moves. The default is to disable all heaters. # Typical example: extruder, heater_bed [thermistor] \u00b6 Custom thermistors (one may define any number of sections with a \"thermistor\" prefix). A custom thermistor may be used in the sensor_type field of a heater config section. (For example, if one defines a \"[thermistor my_thermistor]\" section then one may use a \"sensor_type: my_thermistor\" when defining a heater.) Be sure to place the thermistor section in the config file above its first use in a heater section. [thermistor my_thermistor] #temperature1: #resistance1: #temperature2: #resistance2: #temperature3: #resistance3: # Three resistance measurements (in Ohms) at the given temperatures # (in Celsius). The three measurements will be used to calculate the # Steinhart-Hart coefficients for the thermistor. These parameters # must be provided when using Steinhart-Hart to define the # thermistor. #beta: # Alternatively, one may define temperature1, resistance1, and beta # to define the thermistor parameters. This parameter must be # provided when using \"beta\" to define the thermistor. [adc_temperature] \u00b6 Custom ADC temperature sensors (one may define any number of sections with an \"adc_temperature\" prefix). This allows one to define a custom temperature sensor that measures a voltage on an Analog to Digital Converter (ADC) pin and uses linear interpolation between a set of configured temperature/voltage (or temperature/resistance) measurements to determine the temperature. The resulting sensor can be used as a sensor_type in a heater section. (For example, if one defines a \"[adc_temperature my_sensor]\" section then one may use a \"sensor_type: my_sensor\" when defining a heater.) Be sure to place the sensor section in the config file above its first use in a heater section. [adc_temperature my_sensor] #temperature1: #voltage1: #temperature2: #voltage2: #... # A set of temperatures (in Celsius) and voltages (in Volts) to use # as reference when converting a temperature. A heater section using # this sensor may also specify adc_voltage and voltage_offset # parameters to define the ADC voltage (see \"Common temperature # amplifiers\" section for details). At least two measurements must # be provided. #temperature1: #resistance1: #temperature2: #resistance2: #... # Alternatively one may specify a set of temperatures (in Celsius) # and resistance (in Ohms) to use as reference when converting a # temperature. A heater section using this sensor may also specify a # pullup_resistor parameter (see \"extruder\" section for details). At # least two measurements must be provided. [heater_generic] \u00b6 Generic heaters (one may define any number of sections with a \"heater_generic\" prefix). These heaters behave similarly to standard heaters (extruders, heated beds). Use the SET_HEATER_TEMPERATURE command (see G-Codes for details) to set the target temperature. [heater_generic my_generic_heater] #gcode_id: # The id to use when reporting the temperature in the M105 command. # This parameter must be provided. #heater_pin: #max_power: #sensor_type: #sensor_pin: #smooth_time: #control: #pid_Kp: #pid_Ki: #pid_Kd: #pwm_cycle_time: #min_temp: #max_temp: # See the \"extruder\" section for the definition of the above # parameters. [temperature_sensor] \u00b6 Generic temperature sensors. One can define any number of additional temperature sensors that are reported via the M105 command. [temperature_sensor my_sensor] #sensor_type: #sensor_pin: #min_temp: #max_temp: # See the \"extruder\" section for the definition of the above # parameters. #gcode_id: # See the \"heater_generic\" section for the definition of this # parameter. [temperature_probe] \u00b6 Reports probe coil temperature. Includes optional thermal drift calibration for eddy current based probes. A [temperature_probe] section may be linked to a [probe_eddy_current] by using the same postfix for both sections. [temperature_probe my_probe] #sensor_type: #sensor_pin: #min_temp: #max_temp: # Temperature sensor configuration. # See the \"extruder\" section for the definition of the above # parameters. #smooth_time: # A time value (in seconds) over which temperature measurements will # be smoothed to reduce the impact of measurement noise. The default # is 2.0 seconds. #gcode_id: # See the \"heater_generic\" section for the definition of this # parameter. #speed: # The travel speed [mm/s] for xy moves during calibration. Default # is the speed defined by the probe. #horizontal_move_z: # The z distance [mm] from the bed at which xy moves will occur # during calibration. Default is 2mm. #resting_z: # The z distance [mm] from the bed at which the tool will rest # to heat the probe coil during calibration. Default is .4mm #calibration_position: # The X, Y, Z position where the tool should be moved when # probe drift calibration initializes. This is the location # where the first manual probe will occur. If omitted, the # default behavior is not to move the tool prior to the first # manual probe. #calibration_bed_temp: # The maximum safe bed temperature (in C) used to heat the probe # during probe drift calibration. When set, the calibration # procedure will turn on the bed after the first sample is # taken. When the calibration procedure is complete the bed # temperature will be set to zero. When omitted the default # behavior is not to set the bed temperature. #calibration_extruder_temp: # The extruder temperature (in C) set probe during drift calibration. # When this option is supplied the procedure will wait for until the # specified temperature is reached before requesting the first manual # probe. When the calibration procedure is complete the extruder # temperature will be set to 0. When omitted the default behavior is # not to set the extruder temperature. #extruder_heating_z: 50. # The Z location where extruder heating will occur if the # \"calibration_extruder_temp\" option is set. Its recommended to heat # the extruder some distance from the bed to minimize its impact on # the probe coil temperature. The default is 50. #max_validation_temp: 60. # The maximum temperature used to validate the calibration. It is # recommended to set this to a value between 100 and 120 for enclosed # printers. The default is 60. Temperature sensors \u00b6 Klipper includes definitions for many types of temperature sensors. These sensors may be used in any config section that requires a temperature sensor (such as an [extruder] or [heater_bed] section). Common thermistors \u00b6 Common thermistors. The following parameters are available in heater sections that use one of these sensors. sensor_type: # One of \"EPCOS 100K B57560G104F\", \"ATC Semitec 104GT-2\", # \"ATC Semitec 104NT-4-R025H42G\", \"Generic 3950\", # \"Honeywell 100K 135-104LAG-J01\", \"NTC 100K MGB18-104F39050L32\", # \"SliceEngineering 450\", or \"TDK NTCG104LH104JT1\" sensor_pin: # Analog input pin connected to the thermistor. This parameter must # be provided. #pullup_resistor: 4700 # The resistance (in ohms) of the pullup attached to the thermistor. # The default is 4700 ohms. #inline_resistor: 0 # The resistance (in ohms) of an extra (not heat varying) resistor # that is placed inline with the thermistor. It is rare to set this. # The default is 0 ohms. Common temperature amplifiers \u00b6 Common temperature amplifiers. The following parameters are available in heater sections that use one of these sensors. sensor_type: # One of \"PT100 INA826\", \"AD595\", \"AD597\", \"AD8494\", \"AD8495\", # \"AD8496\", or \"AD8497\". sensor_pin: # Analog input pin connected to the sensor. This parameter must be # provided. #adc_voltage: 5.0 # The ADC comparison voltage (in Volts). The default is 5 volts. #voltage_offset: 0 # The ADC voltage offset (in Volts). The default is 0. Directly connected PT1000 sensor \u00b6 Directly connected PT1000 sensor. The following parameters are available in heater sections that use one of these sensors. sensor_type: PT1000 sensor_pin: # Analog input pin connected to the sensor. This parameter must be # provided. #pullup_resistor: 4700 # The resistance (in ohms) of the pullup attached to the sensor. The # default is 4700 ohms. MAXxxxxx temperature sensors \u00b6 MAXxxxxx serial peripheral interface (SPI) temperature based sensors. The following parameters are available in heater sections that use one of these sensor types. sensor_type: # One of \"MAX6675\", \"MAX31855\", \"MAX31856\", or \"MAX31865\". sensor_pin: # The chip select line for the sensor chip. This parameter must be # provided. #spi_speed: 4000000 # The SPI speed (in hz) to use when communicating with the chip. # The default is 4000000. #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #tc_type: K #tc_use_50Hz_filter: False #tc_averaging_count: 1 # The above parameters control the sensor parameters of MAX31856 # chips. The defaults for each parameter are next to the parameter # name in the above list. #rtd_nominal_r: 100 #rtd_reference_r: 430 #rtd_num_of_wires: 2 #rtd_use_50Hz_filter: False # The above parameters control the sensor parameters of MAX31865 # chips. The defaults for each parameter are next to the parameter # name in the above list. BMP180/BMP280/BME280/BMP388/BME680 temperature sensor \u00b6 BMP180/BMP280/BME280/BMP388/BME680 two wire interface (I2C) environmental sensors. Note that these sensors are not intended for use with extruders and heater beds, but rather for monitoring ambient temperature (C), pressure (hPa), relative humidity and in case of the BME680 gas level. See sample-macros.cfg for a gcode_macro that may be used to report pressure and humidity in addition to temperature. sensor_type: BME280 #i2c_address: # Default is 118 (0x76). The BMP180, BMP388 and some BME280 sensors # have an address of 119 (0x77). #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. AHT10/AHT20/AHT21 temperature sensor \u00b6 AHT10/AHT20/AHT21 two wire interface (I2C) environmental sensors. Note that these sensors are not intended for use with extruders and heater beds, but rather for monitoring ambient temperature (C) and relative humidity. See sample-macros.cfg for a gcode_macro that may be used to report humidity in addition to temperature. sensor_type: AHT10 # Also use AHT10 for AHT20 and AHT21 sensors. #i2c_address: # Default is 56 (0x38). Some AHT10 sensors give the option to use # 57 (0x39) by moving a resistor. #i2c_mcu: #i2c_bus: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #aht10_report_time: # Interval in seconds between readings. Default is 30, minimum is 5 HTU21D sensor \u00b6 HTU21D family two wire interface (I2C) environmental sensor. Note that this sensor is not intended for use with extruders and heater beds, but rather for monitoring ambient temperature (C) and relative humidity. See sample-macros.cfg for a gcode_macro that may be used to report humidity in addition to temperature. sensor_type: # Must be \"HTU21D\" , \"SI7013\", \"SI7020\", \"SI7021\" or \"SHT21\" #i2c_address: # Default is 64 (0x40). #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #htu21d_hold_master: # If the sensor can hold the I2C buf while reading. If True no other # bus communication can be performed while reading is in progress. # Default is False. #htu21d_resolution: # The resolution of temperature and humidity reading. # Valid values are: # 'TEMP14_HUM12' -> 14bit for Temp and 12bit for humidity # 'TEMP13_HUM10' -> 13bit for Temp and 10bit for humidity # 'TEMP12_HUM08' -> 12bit for Temp and 08bit for humidity # 'TEMP11_HUM11' -> 11bit for Temp and 11bit for humidity # Default is: \"TEMP11_HUM11\" #htu21d_report_time: # Interval in seconds between readings. Default is 30 SHT3X sensor \u00b6 SHT3X family two wire interface (I2C) environmental sensor. These sensors have a range of -55~125 C, so are usable for e.g. chamber temperature monitoring. They can also function as simple fan/heater controllers. sensor_type: SHT3X #i2c_address: # Default is 68 (0x44). #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. LM75 temperature sensor \u00b6 LM75/LM75A two wire (I2C) connected temperature sensors. These sensors have a range of -55~125 C, so are usable for e.g. chamber temperature monitoring. They can also function as simple fan/heater controllers. sensor_type: LM75 #i2c_address: # Default is 72 (0x48). Normal range is 72-79 (0x48-0x4F) and the 3 # low bits of the address are configured via pins on the chip # (usually with jumpers or hard wired). #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #lm75_report_time: # Interval in seconds between readings. Default is 0.8, with minimum # 0.5. Builtin micro-controller temperature sensor \u00b6 The atsam, atsamd, stm32 and rp2040 micro-controllers contain an internal temperature sensor. One can use the \"temperature_mcu\" sensor to monitor these temperatures. sensor_type: temperature_mcu #sensor_mcu: mcu # The micro-controller to read from. The default is \"mcu\". #sensor_temperature1: #sensor_adc1: # Specify the above two parameters (a temperature in Celsius and an # ADC value as a float between 0.0 and 1.0) to calibrate the # micro-controller temperature. This may improve the reported # temperature accuracy on some chips. A typical way to obtain this # calibration information is to completely remove power from the # printer for a few hours (to ensure it is at the ambient # temperature), then power it up and use the QUERY_ADC command to # obtain an ADC measurement. Use some other temperature sensor on # the printer to find the corresponding ambient temperature. The # default is to use the factory calibration data on the # micro-controller (if applicable) or the nominal values from the # micro-controller specification. #sensor_temperature2: #sensor_adc2: # If sensor_temperature1/sensor_adc1 is specified then one may also # specify sensor_temperature2/sensor_adc2 calibration data. Doing so # may provide calibrated \"temperature slope\" information. The # default is to use the factory calibration data on the # micro-controller (if applicable) or the nominal values from the # micro-controller specification. Host temperature sensor \u00b6 Temperature from the machine (eg Raspberry Pi) running the host software. sensor_type: temperature_host #sensor_path: # The path to temperature system file. The default is # \"/sys/class/thermal/thermal_zone0/temp\" which is the temperature # system file on a Raspberry Pi computer. DS18B20 temperature sensor \u00b6 DS18B20 is a 1-wire (w1) digital temperature sensor. Note that this sensor is not intended for use with extruders and heater beds, but rather for monitoring ambient temperature (C). These sensors have range up to 125 C, so are usable for e.g. chamber temperature monitoring. They can also function as simple fan/heater controllers. DS18B20 sensors are only supported on the \"host mcu\", e.g. the Raspberry Pi. The w1-gpio Linux kernel module must be installed. sensor_type: DS18B20 serial_no: # Each 1-wire device has a unique serial number used to identify the device, # usually in the format 28-031674b175ff. This parameter must be provided. # Attached 1-wire devices can be listed using the following Linux command: # ls /sys/bus/w1/devices/ #ds18_report_time: # Interval in seconds between readings. Default is 3.0, with a minimum of 1.0 #sensor_mcu: # The micro-controller to read from. Must be the host_mcu Combined temperature sensor \u00b6 Combined temperature sensor is a virtual temperature sensor based on several other sensors. This sensor can be used with extruders, heater_generic and heater beds. sensor_type: temperature_combined #sensor_list: # Must be provided. List of sensors to combine to new \"virtual\" # sensor. # E.g. 'temperature_sensor sensor1,extruder,heater_bed' #combination_method: # Must be provided. Combination method used for the sensor. # Available options are 'max', 'min', 'mean'. #maximum_deviation: # Must be provided. Maximum permissible deviation between the sensors # to combine (e.g. 5 degrees). To disable it, use a large value (e.g. 999.9) Fans \u00b6 [fan] \u00b6 Print cooling fan. [fan] pin: # Output pin controlling the fan. This parameter must be provided. #max_power: 1.0 # The maximum power (expressed as a value from 0.0 to 1.0) that the # pin may be set to. The value 1.0 allows the pin to be set fully # enabled for extended periods, while a value of 0.5 would allow the # pin to be enabled for no more than half the time. This setting may # be used to limit the total power output (over extended periods) to # the fan. If this value is less than 1.0 then fan speed requests # will be scaled between zero and max_power (for example, if # max_power is .9 and a fan speed of 80% is requested then the fan # power will be set to 72%). The default is 1.0. #shutdown_speed: 0 # The desired fan speed (expressed as a value from 0.0 to 1.0) if # the micro-controller software enters an error state. The default # is 0. #cycle_time: 0.010 # The amount of time (in seconds) for each PWM power cycle to the # fan. It is recommended this be 10 milliseconds or greater when # using software based PWM. The default is 0.010 seconds. #hardware_pwm: False # Enable this to use hardware PWM instead of software PWM. Most fans # do not work well with hardware PWM, so it is not recommended to # enable this unless there is an electrical requirement to switch at # very high speeds. When using hardware PWM the actual cycle time is # constrained by the implementation and may be significantly # different than the requested cycle_time. The default is False. #kick_start_time: 0.100 # Time (in seconds) to run the fan at full speed when either first # enabling or increasing it by more than 50% (helps get the fan # spinning). The default is 0.100 seconds. #off_below: 0.0 # The minimum input speed which will power the fan (expressed as a # value from 0.0 to 1.0). When a speed lower than off_below is # requested the fan will instead be turned off. This setting may be # used to prevent fan stalls and to ensure kick starts are # effective. The default is 0.0. # # This setting should be recalibrated whenever max_power is adjusted. # To calibrate this setting, start with off_below set to 0.0 and the # fan spinning. Gradually lower the fan speed to determine the lowest # input speed which reliably drives the fan without stalls. Set # off_below to the duty cycle corresponding to this value (for # example, 12% -> 0.12) or slightly higher. #tachometer_pin: # Tachometer input pin for monitoring fan speed. A pullup is generally # required. This parameter is optional. #tachometer_ppr: 2 # When tachometer_pin is specified, this is the number of pulses per # revolution of the tachometer signal. For a BLDC fan this is # normally half the number of poles. The default is 2. #tachometer_poll_interval: 0.0015 # When tachometer_pin is specified, this is the polling period of the # tachometer pin, in seconds. The default is 0.0015, which is fast # enough for fans below 10000 RPM at 2 PPR. This must be smaller than # 30/(tachometer_ppr*rpm), with some margin, where rpm is the # maximum speed (in RPM) of the fan. #enable_pin: # Optional pin to enable power to the fan. This can be useful for fans # with dedicated PWM inputs. Some of these fans stay on even at 0% PWM # input. In such a case, the PWM pin can be used normally, and e.g. a # ground-switched FET(standard fan pin) can be used to control power to # the fan. [heater_fan] \u00b6 Heater cooling fans (one may define any number of sections with a \"heater_fan\" prefix). A \"heater fan\" is a fan that will be enabled whenever its associated heater is active. By default, a heater_fan has a shutdown_speed equal to max_power. [heater_fan heatbreak_cooling_fan] #pin: #max_power: #shutdown_speed: #cycle_time: #hardware_pwm: #kick_start_time: #off_below: #tachometer_pin: #tachometer_ppr: #tachometer_poll_interval: #enable_pin: # See the \"fan\" section for a description of the above parameters. #heater: extruder # Name of the config section defining the heater that this fan is # associated with. If a comma separated list of heater names is # provided here, then the fan will be enabled when any of the given # heaters are enabled. The default is \"extruder\". #heater_temp: 50.0 # A temperature (in Celsius) that the heater must drop below before # the fan is disabled. The default is 50 Celsius. #fan_speed: 1.0 # The fan speed (expressed as a value from 0.0 to 1.0) that the fan # will be set to when its associated heater is enabled. The default # is 1.0 [controller_fan] \u00b6 Controller cooling fan (one may define any number of sections with a \"controller_fan\" prefix). A \"controller fan\" is a fan that will be enabled whenever its associated heater or its associated stepper driver is active. The fan will stop whenever an idle_timeout is reached to ensure no overheating will occur after deactivating a watched component. [controller_fan my_controller_fan] #pin: #max_power: #shutdown_speed: #cycle_time: #hardware_pwm: #kick_start_time: #off_below: #tachometer_pin: #tachometer_ppr: #tachometer_poll_interval: #enable_pin: # See the \"fan\" section for a description of the above parameters. #fan_speed: 1.0 # The fan speed (expressed as a value from 0.0 to 1.0) that the fan # will be set to when a heater or stepper driver is active. # The default is 1.0 #idle_timeout: # The amount of time (in seconds) after a stepper driver or heater # was active and the fan should be kept running. The default # is 30 seconds. #idle_speed: # The fan speed (expressed as a value from 0.0 to 1.0) that the fan # will be set to when a heater or stepper driver was active and # before the idle_timeout is reached. The default is fan_speed. #heater: #stepper: # Name of the config section defining the heater/stepper that this fan # is associated with. If a comma separated list of heater/stepper names # is provided here, then the fan will be enabled when any of the given # heaters/steppers are enabled. The default heater is \"extruder\", the # default stepper is all of them. [temperature_fan] \u00b6 Temperature-triggered cooling fans (one may define any number of sections with a \"temperature_fan\" prefix). A \"temperature fan\" is a fan that will be enabled whenever its associated sensor is above a set temperature. By default, a temperature_fan has a shutdown_speed equal to max_power. See the command reference for additional information. [temperature_fan my_temp_fan] #pin: #max_power: #shutdown_speed: #cycle_time: #hardware_pwm: #kick_start_time: #off_below: #tachometer_pin: #tachometer_ppr: #tachometer_poll_interval: #enable_pin: # See the \"fan\" section for a description of the above parameters. #sensor_type: #sensor_pin: #control: #max_delta: #min_temp: #max_temp: # See the \"extruder\" section for a description of the above parameters. #pid_Kp: #pid_Ki: #pid_Kd: # The proportional (pid_Kp), integral (pid_Ki), and derivative # (pid_Kd) settings for the PID feedback control system. Klipper # evaluates the PID settings with the following general formula: # fan_pwm = max_power - (Kp*e + Ki*integral(e) - Kd*derivative(e)) / 255 # Where \"e\" is \"target_temperature - measured_temperature\" and # \"fan_pwm\" is the requested fan rate with 0.0 being full off and # 1.0 being full on. The pid_Kp, pid_Ki, and pid_Kd parameters must # be provided when the PID control algorithm is enabled. #pid_deriv_time: 2.0 # A time value (in seconds) over which temperature measurements will # be smoothed when using the PID control algorithm. This may reduce # the impact of measurement noise. The default is 2 seconds. #target_temp: 40.0 # A temperature (in Celsius) that will be the target temperature. # The default is 40 degrees. #max_speed: 1.0 # The fan speed (expressed as a value from 0.0 to 1.0) that the fan # will be set to when the sensor temperature exceeds the set value. # The default is 1.0. #min_speed: 0.3 # The minimum fan speed (expressed as a value from 0.0 to 1.0) that # the fan will be set to for PID temperature fans. # The default is 0.3. #gcode_id: # If set, the temperature will be reported in M105 queries using the # given id. The default is to not report the temperature via M105. [fan_generic] \u00b6 Manually controlled fan (one may define any number of sections with a \"fan_generic\" prefix). The speed of a manually controlled fan is set with the SET_FAN_SPEED gcode command . [fan_generic extruder_partfan] #pin: #max_power: #shutdown_speed: #cycle_time: #hardware_pwm: #kick_start_time: #off_below: #tachometer_pin: #tachometer_ppr: #tachometer_poll_interval: #enable_pin: # See the \"fan\" section for a description of the above parameters. LEDs \u00b6 [led] \u00b6 Support for LEDs (and LED strips) controlled via micro-controller PWM pins (one may define any number of sections with an \"led\" prefix). See the command reference for more information. [led my_led] #red_pin: #green_pin: #blue_pin: #white_pin: # The pin controlling the given LED color. At least one of the above # parameters must be provided. #cycle_time: 0.010 # The amount of time (in seconds) per PWM cycle. It is recommended # this be 10 milliseconds or greater when using software based PWM. # The default is 0.010 seconds. #hardware_pwm: False # Enable this to use hardware PWM instead of software PWM. When # using hardware PWM the actual cycle time is constrained by the # implementation and may be significantly different than the # requested cycle_time. The default is False. #initial_RED: 0.0 #initial_GREEN: 0.0 #initial_BLUE: 0.0 #initial_WHITE: 0.0 # Sets the initial LED color. Each value should be between 0.0 and # 1.0. The default for each color is 0. [neopixel] \u00b6 Neopixel (aka WS2812) LED support (one may define any number of sections with a \"neopixel\" prefix). See the command reference for more information. Note that the linux mcu implementation does not currently support directly connected neopixels. The current design using the Linux kernel interface does not allow this scenario because the kernel GPIO interface is not fast enough to provide the required pulse rates. [neopixel my_neopixel] pin: # The pin connected to the neopixel. This parameter must be # provided. #chain_count: # The number of Neopixel chips that are \"daisy chained\" to the # provided pin. The default is 1 (which indicates only a single # Neopixel is connected to the pin). #color_order: GRB # Set the pixel order required by the LED hardware (using a string # containing the letters R, G, B, W with W optional). Alternatively, # this may be a comma separated list of pixel orders - one for each # LED in the chain. The default is GRB. #initial_RED: 0.0 #initial_GREEN: 0.0 #initial_BLUE: 0.0 #initial_WHITE: 0.0 # See the \"led\" section for information on these parameters. [dotstar] \u00b6 Dotstar (aka APA102) LED support (one may define any number of sections with a \"dotstar\" prefix). See the command reference for more information. [dotstar my_dotstar] data_pin: # The pin connected to the data line of the dotstar. This parameter # must be provided. clock_pin: # The pin connected to the clock line of the dotstar. This parameter # must be provided. #chain_count: # See the \"neopixel\" section for information on this parameter. #initial_RED: 0.0 #initial_GREEN: 0.0 #initial_BLUE: 0.0 # See the \"led\" section for information on these parameters. [pca9533] \u00b6 PCA9533 LED support. The PCA9533 is used on the mightyboard. [pca9533 my_pca9533] #i2c_address: 98 # The i2c address that the chip is using on the i2c bus. Use 98 for # the PCA9533/1, 99 for the PCA9533/2. The default is 98. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #initial_RED: 0.0 #initial_GREEN: 0.0 #initial_BLUE: 0.0 #initial_WHITE: 0.0 # See the \"led\" section for information on these parameters. [pca9632] \u00b6 PCA9632 LED support. The PCA9632 is used on the FlashForge Dreamer. [pca9632 my_pca9632] #i2c_address: 98 # The i2c address that the chip is using on the i2c bus. This may be # 96, 97, 98, or 99. The default is 98. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #color_order: RGBW # Set the pixel order of the LED (using a string containing the # letters R, G, B, W). The default is RGBW. #initial_RED: 0.0 #initial_GREEN: 0.0 #initial_BLUE: 0.0 #initial_WHITE: 0.0 # See the \"led\" section for information on these parameters. Additional servos, buttons, and other pins \u00b6 [servo] \u00b6 Servos (one may define any number of sections with a \"servo\" prefix). The servos may be controlled using the SET_SERVO g-code command . For example: SET_SERVO SERVO=my_servo ANGLE=180 [servo my_servo] pin: # PWM output pin controlling the servo. This parameter must be # provided. #maximum_servo_angle: 180 # The maximum angle (in degrees) that this servo can be set to. The # default is 180 degrees. #minimum_pulse_width: 0.001 # The minimum pulse width time (in seconds). This should correspond # with an angle of 0 degrees. The default is 0.001 seconds. #maximum_pulse_width: 0.002 # The maximum pulse width time (in seconds). This should correspond # with an angle of maximum_servo_angle. The default is 0.002 # seconds. #initial_angle: # Initial angle (in degrees) to set the servo to. The default is to # not send any signal at startup. #initial_pulse_width: # Initial pulse width time (in seconds) to set the servo to. (This # is only valid if initial_angle is not set.) The default is to not # send any signal at startup. [gcode_button] \u00b6 Execute gcode when a button is pressed or released (or when a pin changes state). You can check the state of the button by using QUERY_BUTTON button=my_gcode_button . [gcode_button my_gcode_button] pin: # The pin on which the button is connected. This parameter must be # provided. #analog_range: # Two comma separated resistances (in Ohms) specifying the minimum # and maximum resistance range for the button. If analog_range is # provided then the pin must be an analog capable pin. The default # is to use digital gpio for the button. #analog_pullup_resistor: # The pullup resistance (in Ohms) when analog_range is specified. # The default is 4700 ohms. #press_gcode: # A list of G-Code commands to execute when the button is pressed. # G-Code templates are supported. This parameter must be provided. #release_gcode: # A list of G-Code commands to execute when the button is released. # G-Code templates are supported. The default is to not run any # commands on a button release. #debounce_delay: # A period of time in seconds to debounce events prior to running the # button gcode. If the button is pressed and released during this # delay, the entire button press is ignored. Default is 0. [output_pin] \u00b6 Run-time configurable output pins (one may define any number of sections with an \"output_pin\" prefix). Pins configured here will be setup as output pins and one may modify them at run-time using \"SET_PIN PIN=my_pin VALUE=.1\" type extended g-code commands . [output_pin my_pin] pin: # The pin to configure as an output. This parameter must be # provided. #pwm: False # Set if the output pin should be capable of pulse-width-modulation. # If this is true, the value fields should be between 0 and 1; if it # is false the value fields should be either 0 or 1. The default is # False. #value: # The value to initially set the pin to during MCU configuration. # The default is 0 (for low voltage). #shutdown_value: # The value to set the pin to on an MCU shutdown event. The default # is 0 (for low voltage). #cycle_time: 0.100 # The amount of time (in seconds) per PWM cycle. It is recommended # this be 10 milliseconds or greater when using software based PWM. # The default is 0.100 seconds for pwm pins. #hardware_pwm: False # Enable this to use hardware PWM instead of software PWM. When # using hardware PWM the actual cycle time is constrained by the # implementation and may be significantly different than the # requested cycle_time. The default is False. #scale: # This parameter can be used to alter how the 'value' and # 'shutdown_value' parameters are interpreted for pwm pins. If # provided, then the 'value' parameter should be between 0.0 and # 'scale'. This may be useful when configuring a PWM pin that # controls a stepper voltage reference. The 'scale' can be set to # the equivalent stepper amperage if the PWM were fully enabled, and # then the 'value' parameter can be specified using the desired # amperage for the stepper. The default is to not scale the 'value' # parameter. #maximum_mcu_duration: #static_value: # These options are deprecated and should no longer be specified. [pwm_tool] \u00b6 Pulse width modulation digital output pins capable of high speed updates (one may define any number of sections with an \"output_pin\" prefix). Pins configured here will be setup as output pins and one may modify them at run-time using \"SET_PIN PIN=my_pin VALUE=.1\" type extended g-code commands . [pwm_tool my_tool] pin: # The pin to configure as an output. This parameter must be provided. #maximum_mcu_duration: # The maximum duration a non-shutdown value may be driven by the MCU # without an acknowledge from the host. # If host can not keep up with an update, the MCU will shutdown # and set all pins to their respective shutdown values. # Default: 0 (disabled) # Usual values are around 5 seconds. #value: #shutdown_value: #cycle_time: 0.100 #hardware_pwm: False #scale: # See the \"output_pin\" section for the definition of these parameters. [pwm_cycle_time] \u00b6 Run-time configurable output pins with dynamic pwm cycle timing (one may define any number of sections with an \"pwm_cycle_time\" prefix). Pins configured here will be setup as output pins and one may modify them at run-time using \"SET_PIN PIN=my_pin VALUE=.1 CYCLE_TIME=0.100\" type extended g-code commands . [pwm_cycle_time my_pin] pin: #value: #shutdown_value: #cycle_time: 0.100 #scale: # See the \"output_pin\" section for information on these parameters. [static_digital_output] \u00b6 Statically configured digital output pins (one may define any number of sections with a \"static_digital_output\" prefix). Pins configured here will be setup as a GPIO output during MCU configuration. They can not be changed at run-time. [static_digital_output my_output_pins] pins: # A comma separated list of pins to be set as GPIO output pins. The # pin will be set to a high level unless the pin name is prefaced # with \"!\". This parameter must be provided. [multi_pin] \u00b6 Multiple pin outputs (one may define any number of sections with a \"multi_pin\" prefix). A multi_pin output creates an internal pin alias that can modify multiple output pins each time the alias pin is set. For example, one could define a \"[multi_pin my_fan]\" object containing two pins and then set \"pin=multi_pin:my_fan\" in the \"[fan]\" section - on each fan change both output pins would be updated. These aliases may not be used with stepper motor pins. [multi_pin my_multi_pin] pins: # A comma separated list of pins associated with this alias. This # parameter must be provided. TMC stepper driver configuration \u00b6 Configuration of Trinamic stepper motor drivers in UART/SPI mode. Additional information is in the TMC Drivers guide and in the command reference . [tmc2130] \u00b6 Configure a TMC2130 stepper motor driver via SPI bus. To use this feature, define a config section with a \"tmc2130\" prefix followed by the name of the corresponding stepper config section (for example, \"[tmc2130 stepper_x]\"). [tmc2130 stepper_x] cs_pin: # The pin corresponding to the TMC2130 chip select line. This pin # will be set to low at the start of SPI messages and raised to high # after the message completes. This parameter must be provided. #spi_speed: #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #chain_position: #chain_length: # These parameters configure an SPI daisy chain. The two parameters # define the stepper position in the chain and the total chain length. # Position 1 corresponds to the stepper that connects to the MOSI signal. # The default is to not use an SPI daisy chain. #interpolate: True # If true, enable step interpolation (the driver will internally # step at a rate of 256 micro-steps). This interpolation does # introduce a small systemic positional deviation - see # TMC_Drivers.md for details. The default is True. run_current: # The amount of current (in amps RMS) to configure the driver to use # during stepper movement. This parameter must be provided. #hold_current: # The amount of current (in amps RMS) to configure the driver to use # when the stepper is not moving. Setting a hold_current is not # recommended (see TMC_Drivers.md for details). The default is to # not reduce the current. #sense_resistor: 0.110 # The resistance (in ohms) of the motor sense resistor. The default # is 0.110 ohms. #stealthchop_threshold: 0 # The velocity (in mm/s) to set the \"stealthChop\" threshold to. When # set, \"stealthChop\" mode will be enabled if the stepper motor # velocity is below this value. Note that the \"sensorless homing\" # code may temporarily override this setting during homing # operations. The default is 0, which disables \"stealthChop\" mode. #coolstep_threshold: # The velocity (in mm/s) to set the TMC driver internal \"CoolStep\" # threshold to. If set, the coolstep feature will be enabled when # the stepper motor velocity is near or above this value. Important # - if coolstep_threshold is set and \"sensorless homing\" is used, # then one must ensure that the homing speed is above the coolstep # threshold! The default is to not enable the coolstep feature. #high_velocity_threshold: # The velocity (in mm/s) to set the TMC driver internal \"high # velocity\" threshold (THIGH) to. This is typically used to disable # the \"CoolStep\" feature at high speeds. The default is to not set a # TMC \"high velocity\" threshold. #driver_MSLUT0: 2863314260 #driver_MSLUT1: 1251300522 #driver_MSLUT2: 608774441 #driver_MSLUT3: 269500962 #driver_MSLUT4: 4227858431 #driver_MSLUT5: 3048961917 #driver_MSLUT6: 1227445590 #driver_MSLUT7: 4211234 #driver_W0: 2 #driver_W1: 1 #driver_W2: 1 #driver_W3: 1 #driver_X1: 128 #driver_X2: 255 #driver_X3: 255 #driver_START_SIN: 0 #driver_START_SIN90: 247 # These fields control the Microstep Table registers directly. The optimal # wave table is specific to each motor and might vary with current. An # optimal configuration will have minimal print artifacts caused by # non-linear stepper movement. The values specified above are the default # values used by the driver. The value must be specified as a decimal integer # (hex form is not supported). In order to compute the wave table fields, # see the tmc2130 \"Calculation Sheet\" from the Trinamic website. #driver_IHOLDDELAY: 8 #driver_TPOWERDOWN: 0 #driver_TBL: 1 #driver_TOFF: 4 #driver_HEND: 7 #driver_HSTRT: 0 #driver_VHIGHFS: 0 #driver_VHIGHCHM: 0 #driver_PWM_AUTOSCALE: True #driver_PWM_FREQ: 1 #driver_PWM_GRAD: 4 #driver_PWM_AMPL: 128 #driver_FREEWHEEL: 0 #driver_SGT: 0 #driver_SEMIN: 0 #driver_SEUP: 0 #driver_SEMAX: 0 #driver_SEDN: 0 #driver_SEIMIN: 0 #driver_SFILT: 0 # Set the given register during the configuration of the TMC2130 # chip. This may be used to set custom motor parameters. The # defaults for each parameter are next to the parameter name in the # above list. #diag0_pin: #diag1_pin: # The micro-controller pin attached to one of the DIAG lines of the # TMC2130 chip. Only a single diag pin should be specified. The pin # is \"active low\" and is thus normally prefaced with \"^!\". Setting # this creates a \"tmc2130_stepper_x:virtual_endstop\" virtual pin # which may be used as the stepper's endstop_pin. Doing this enables # \"sensorless homing\". (Be sure to also set driver_SGT to an # appropriate sensitivity value.) The default is to not enable # sensorless homing. [tmc2208] \u00b6 Configure a TMC2208 (or TMC2224) stepper motor driver via single wire UART. To use this feature, define a config section with a \"tmc2208\" prefix followed by the name of the corresponding stepper config section (for example, \"[tmc2208 stepper_x]\"). [tmc2208 stepper_x] uart_pin: # The pin connected to the TMC2208 PDN_UART line. This parameter # must be provided. #tx_pin: # If using separate receive and transmit lines to communicate with # the driver then set uart_pin to the receive pin and tx_pin to the # transmit pin. The default is to use uart_pin for both reading and # writing. #select_pins: # A comma separated list of pins to set prior to accessing the # tmc2208 UART. This may be useful for configuring an analog mux for # UART communication. The default is to not configure any pins. #interpolate: True # If true, enable step interpolation (the driver will internally # step at a rate of 256 micro-steps). This interpolation does # introduce a small systemic positional deviation - see # TMC_Drivers.md for details. The default is True. run_current: # The amount of current (in amps RMS) to configure the driver to use # during stepper movement. This parameter must be provided. #hold_current: # The amount of current (in amps RMS) to configure the driver to use # when the stepper is not moving. Setting a hold_current is not # recommended (see TMC_Drivers.md for details). The default is to # not reduce the current. #sense_resistor: 0.110 # The resistance (in ohms) of the motor sense resistor. The default # is 0.110 ohms. #stealthchop_threshold: 0 # The velocity (in mm/s) to set the \"stealthChop\" threshold to. When # set, \"stealthChop\" mode will be enabled if the stepper motor # velocity is below this value. Note that the \"sensorless homing\" # code may temporarily override this setting during homing # operations. The default is 0, which disables \"stealthChop\" mode. #driver_MULTISTEP_FILT: True #driver_IHOLDDELAY: 8 #driver_TPOWERDOWN: 20 #driver_TBL: 2 #driver_TOFF: 3 #driver_HEND: 0 #driver_HSTRT: 5 #driver_PWM_AUTOGRAD: True #driver_PWM_AUTOSCALE: True #driver_PWM_LIM: 12 #driver_PWM_REG: 8 #driver_PWM_FREQ: 1 #driver_PWM_GRAD: 14 #driver_PWM_OFS: 36 #driver_FREEWHEEL: 0 # Set the given register during the configuration of the TMC2208 # chip. This may be used to set custom motor parameters. The # defaults for each parameter are next to the parameter name in the # above list. [tmc2209] \u00b6 Configure a TMC2209 stepper motor driver via single wire UART. To use this feature, define a config section with a \"tmc2209\" prefix followed by the name of the corresponding stepper config section (for example, \"[tmc2209 stepper_x]\"). [tmc2209 stepper_x] uart_pin: #tx_pin: #select_pins: #interpolate: True run_current: #hold_current: #sense_resistor: 0.110 #stealthchop_threshold: 0 # See the \"tmc2208\" section for the definition of these parameters. #coolstep_threshold: # The velocity (in mm/s) to set the TMC driver internal \"CoolStep\" # threshold to. If set, the coolstep feature will be enabled when # the stepper motor velocity is near or above this value. Important # - if coolstep_threshold is set and \"sensorless homing\" is used, # then one must ensure that the homing speed is above the coolstep # threshold! The default is to not enable the coolstep feature. #uart_address: # The address of the TMC2209 chip for UART messages (an integer # between 0 and 3). This is typically used when multiple TMC2209 # chips are connected to the same UART pin. The default is zero. #driver_MULTISTEP_FILT: True #driver_IHOLDDELAY: 8 #driver_TPOWERDOWN: 20 #driver_TBL: 2 #driver_TOFF: 3 #driver_HEND: 0 #driver_HSTRT: 5 #driver_PWM_AUTOGRAD: True #driver_PWM_AUTOSCALE: True #driver_PWM_LIM: 12 #driver_PWM_REG: 8 #driver_PWM_FREQ: 1 #driver_PWM_GRAD: 14 #driver_PWM_OFS: 36 #driver_FREEWHEEL: 0 #driver_SGTHRS: 0 #driver_SEMIN: 0 #driver_SEUP: 0 #driver_SEMAX: 0 #driver_SEDN: 0 #driver_SEIMIN: 0 # Set the given register during the configuration of the TMC2209 # chip. This may be used to set custom motor parameters. The # defaults for each parameter are next to the parameter name in the # above list. #diag_pin: # The micro-controller pin attached to the DIAG line of the TMC2209 # chip. The pin is normally prefaced with \"^\" to enable a pullup. # Setting this creates a \"tmc2209_stepper_x:virtual_endstop\" virtual # pin which may be used as the stepper's endstop_pin. Doing this # enables \"sensorless homing\". (Be sure to also set driver_SGTHRS to # an appropriate sensitivity value.) The default is to not enable # sensorless homing. [tmc2660] \u00b6 Configure a TMC2660 stepper motor driver via SPI bus. To use this feature, define a config section with a tmc2660 prefix followed by the name of the corresponding stepper config section (for example, \"[tmc2660 stepper_x]\"). [tmc2660 stepper_x] cs_pin: # The pin corresponding to the TMC2660 chip select line. This pin # will be set to low at the start of SPI messages and set to high # after the message transfer completes. This parameter must be # provided. #spi_speed: 4000000 # SPI bus frequency used to communicate with the TMC2660 stepper # driver. The default is 4000000. #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #interpolate: True # If true, enable step interpolation (the driver will internally # step at a rate of 256 micro-steps). This only works if microsteps # is set to 16. Interpolation does introduce a small systemic # positional deviation - see TMC_Drivers.md for details. The default # is True. run_current: # The amount of current (in amps RMS) used by the driver during # stepper movement. This parameter must be provided. #sense_resistor: # The resistance (in ohms) of the motor sense resistor. This # parameter must be provided. #idle_current_percent: 100 # The percentage of the run_current the stepper driver will be # lowered to when the idle timeout expires (you need to set up the # timeout using a [idle_timeout] config section). The current will # be raised again once the stepper has to move again. Make sure to # set this to a high enough value such that the steppers do not lose # their position. There is also small delay until the current is # raised again, so take this into account when commanding fast moves # while the stepper is idling. The default is 100 (no reduction). #driver_TBL: 2 #driver_RNDTF: 0 #driver_HDEC: 0 #driver_CHM: 0 #driver_HEND: 3 #driver_HSTRT: 3 #driver_TOFF: 4 #driver_SEIMIN: 0 #driver_SEDN: 0 #driver_SEMAX: 0 #driver_SEUP: 0 #driver_SEMIN: 0 #driver_SFILT: 0 #driver_SGT: 0 #driver_SLPH: 0 #driver_SLPL: 0 #driver_DISS2G: 0 #driver_TS2G: 3 # Set the given parameter during the configuration of the TMC2660 # chip. This may be used to set custom driver parameters. The # defaults for each parameter are next to the parameter name in the # list above. See the TMC2660 datasheet about what each parameter # does and what the restrictions on parameter combinations are. Be # especially aware of the CHOPCONF register, where setting CHM to # either zero or one will lead to layout changes (the first bit of # HDEC) is interpreted as the MSB of HSTRT in this case). [tmc2240] \u00b6 Configure a TMC2240 stepper motor driver via SPI bus or UART. To use this feature, define a config section with a \"tmc2240\" prefix followed by the name of the corresponding stepper config section (for example, \"[tmc2240 stepper_x]\"). [tmc2240 stepper_x] cs_pin: # The pin corresponding to the TMC2240 chip select line. This pin # will be set to low at the start of SPI messages and raised to high # after the message completes. This parameter must be provided. #spi_speed: #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #uart_pin: # The pin connected to the TMC2240 DIAG1/SW line. If this parameter # is provided UART communication is used rather then SPI. #chain_position: #chain_length: # These parameters configure an SPI daisy chain. The two parameters # define the stepper position in the chain and the total chain length. # Position 1 corresponds to the stepper that connects to the MOSI signal. # The default is to not use an SPI daisy chain. #interpolate: True # If true, enable step interpolation (the driver will internally # step at a rate of 256 micro-steps). The default is True. run_current: # The amount of current (in amps RMS) to configure the driver to use # during stepper movement. This parameter must be provided. #hold_current: # The amount of current (in amps RMS) to configure the driver to use # when the stepper is not moving. Setting a hold_current is not # recommended (see TMC_Drivers.md for details). The default is to # not reduce the current. #rref: 12000 # The resistance (in ohms) of the resistor between IREF and GND. The # default is 12000. #stealthchop_threshold: 0 # The velocity (in mm/s) to set the \"stealthChop\" threshold to. When # set, \"stealthChop\" mode will be enabled if the stepper motor # velocity is below this value. Note that the \"sensorless homing\" # code may temporarily override this setting during homing # operations. The default is 0, which disables \"stealthChop\" mode. #coolstep_threshold: # The velocity (in mm/s) to set the TMC driver internal \"CoolStep\" # threshold to. If set, the coolstep feature will be enabled when # the stepper motor velocity is near or above this value. Important # - if coolstep_threshold is set and \"sensorless homing\" is used, # then one must ensure that the homing speed is above the coolstep # threshold! The default is to not enable the coolstep feature. #high_velocity_threshold: # The velocity (in mm/s) to set the TMC driver internal \"high # velocity\" threshold (THIGH) to. This is typically used to disable # the \"CoolStep\" feature at high speeds. The default is to not set a # TMC \"high velocity\" threshold. #driver_MSLUT0: 2863314260 #driver_MSLUT1: 1251300522 #driver_MSLUT2: 608774441 #driver_MSLUT3: 269500962 #driver_MSLUT4: 4227858431 #driver_MSLUT5: 3048961917 #driver_MSLUT6: 1227445590 #driver_MSLUT7: 4211234 #driver_W0: 2 #driver_W1: 1 #driver_W2: 1 #driver_W3: 1 #driver_X1: 128 #driver_X2: 255 #driver_X3: 255 #driver_START_SIN: 0 #driver_START_SIN90: 247 #driver_OFFSET_SIN90: 0 # These fields control the Microstep Table registers directly. The optimal # wave table is specific to each motor and might vary with current. An # optimal configuration will have minimal print artifacts caused by # non-linear stepper movement. The values specified above are the default # values used by the driver. The value must be specified as a decimal integer # (hex form is not supported). In order to compute the wave table fields, # see the tmc2130 \"Calculation Sheet\" from the Trinamic website. # Additionally, this driver also has the OFFSET_SIN90 field which can be used # to tune a motor with unbalanced coils. See the `Sine Wave Lookup Table` # section in the datasheet for information about this field and how to tune # it. #driver_MULTISTEP_FILT: True #driver_IHOLDDELAY: 6 #driver_IRUNDELAY: 4 #driver_TPOWERDOWN: 10 #driver_TBL: 2 #driver_TOFF: 3 #driver_HEND: 2 #driver_HSTRT: 5 #driver_FD3: 0 #driver_TPFD: 4 #driver_CHM: 0 #driver_VHIGHFS: 0 #driver_VHIGHCHM: 0 #driver_DISS2G: 0 #driver_DISS2VS: 0 #driver_PWM_AUTOSCALE: True #driver_PWM_AUTOGRAD: True #driver_PWM_FREQ: 0 #driver_FREEWHEEL: 0 #driver_PWM_GRAD: 0 #driver_PWM_OFS: 29 #driver_PWM_REG: 4 #driver_PWM_LIM: 12 #driver_SGT: 0 #driver_SEMIN: 0 #driver_SEUP: 0 #driver_SEMAX: 0 #driver_SEDN: 0 #driver_SEIMIN: 0 #driver_SFILT: 0 #driver_SG4_ANGLE_OFFSET: 1 #driver_SLOPE_CONTROL: 0 # Set the given register during the configuration of the TMC2240 # chip. This may be used to set custom motor parameters. The # defaults for each parameter are next to the parameter name in the # above list. #diag0_pin: #diag1_pin: # The micro-controller pin attached to one of the DIAG lines of the # TMC2240 chip. Only a single diag pin should be specified. The pin # is \"active low\" and is thus normally prefaced with \"^!\". Setting # this creates a \"tmc2240_stepper_x:virtual_endstop\" virtual pin # which may be used as the stepper's endstop_pin. Doing this enables # \"sensorless homing\". (Be sure to also set driver_SGT to an # appropriate sensitivity value.) The default is to not enable # sensorless homing. [tmc5160] \u00b6 Configure a TMC5160 stepper motor driver via SPI bus. To use this feature, define a config section with a \"tmc5160\" prefix followed by the name of the corresponding stepper config section (for example, \"[tmc5160 stepper_x]\"). [tmc5160 stepper_x] cs_pin: # The pin corresponding to the TMC5160 chip select line. This pin # will be set to low at the start of SPI messages and raised to high # after the message completes. This parameter must be provided. #spi_speed: #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #chain_position: #chain_length: # These parameters configure an SPI daisy chain. The two parameters # define the stepper position in the chain and the total chain length. # Position 1 corresponds to the stepper that connects to the MOSI signal. # The default is to not use an SPI daisy chain. #interpolate: True # If true, enable step interpolation (the driver will internally # step at a rate of 256 micro-steps). The default is True. run_current: # The amount of current (in amps RMS) to configure the driver to use # during stepper movement. This parameter must be provided. #hold_current: # The amount of current (in amps RMS) to configure the driver to use # when the stepper is not moving. Setting a hold_current is not # recommended (see TMC_Drivers.md for details). The default is to # not reduce the current. #sense_resistor: 0.075 # The resistance (in ohms) of the motor sense resistor. The default # is 0.075 ohms. #stealthchop_threshold: 0 # The velocity (in mm/s) to set the \"stealthChop\" threshold to. When # set, \"stealthChop\" mode will be enabled if the stepper motor # velocity is below this value. Note that the \"sensorless homing\" # code may temporarily override this setting during homing # operations. The default is 0, which disables \"stealthChop\" mode. #coolstep_threshold: # The velocity (in mm/s) to set the TMC driver internal \"CoolStep\" # threshold to. If set, the coolstep feature will be enabled when # the stepper motor velocity is near or above this value. Important # - if coolstep_threshold is set and \"sensorless homing\" is used, # then one must ensure that the homing speed is above the coolstep # threshold! The default is to not enable the coolstep feature. #high_velocity_threshold: # The velocity (in mm/s) to set the TMC driver internal \"high # velocity\" threshold (THIGH) to. This is typically used to disable # the \"CoolStep\" feature at high speeds. The default is to not set a # TMC \"high velocity\" threshold. #driver_MSLUT0: 2863314260 #driver_MSLUT1: 1251300522 #driver_MSLUT2: 608774441 #driver_MSLUT3: 269500962 #driver_MSLUT4: 4227858431 #driver_MSLUT5: 3048961917 #driver_MSLUT6: 1227445590 #driver_MSLUT7: 4211234 #driver_W0: 2 #driver_W1: 1 #driver_W2: 1 #driver_W3: 1 #driver_X1: 128 #driver_X2: 255 #driver_X3: 255 #driver_START_SIN: 0 #driver_START_SIN90: 247 # These fields control the Microstep Table registers directly. The optimal # wave table is specific to each motor and might vary with current. An # optimal configuration will have minimal print artifacts caused by # non-linear stepper movement. The values specified above are the default # values used by the driver. The value must be specified as a decimal integer # (hex form is not supported). In order to compute the wave table fields, # see the tmc2130 \"Calculation Sheet\" from the Trinamic website. #driver_MULTISTEP_FILT: True #driver_IHOLDDELAY: 6 #driver_TPOWERDOWN: 10 #driver_TBL: 2 #driver_TOFF: 3 #driver_HEND: 2 #driver_HSTRT: 5 #driver_FD3: 0 #driver_TPFD: 4 #driver_CHM: 0 #driver_VHIGHFS: 0 #driver_VHIGHCHM: 0 #driver_DISS2G: 0 #driver_DISS2VS: 0 #driver_PWM_AUTOSCALE: True #driver_PWM_AUTOGRAD: True #driver_PWM_FREQ: 0 #driver_FREEWHEEL: 0 #driver_PWM_GRAD: 0 #driver_PWM_OFS: 30 #driver_PWM_REG: 4 #driver_PWM_LIM: 12 #driver_SGT: 0 #driver_SEMIN: 0 #driver_SEUP: 0 #driver_SEMAX: 0 #driver_SEDN: 0 #driver_SEIMIN: 0 #driver_SFILT: 0 #driver_DRVSTRENGTH: 0 #driver_BBMCLKS: 4 #driver_BBMTIME: 0 #driver_FILT_ISENSE: 0 # Set the given register during the configuration of the TMC5160 # chip. This may be used to set custom motor parameters. The # defaults for each parameter are next to the parameter name in the # above list. #diag0_pin: #diag1_pin: # The micro-controller pin attached to one of the DIAG lines of the # TMC5160 chip. Only a single diag pin should be specified. The pin # is \"active low\" and is thus normally prefaced with \"^!\". Setting # this creates a \"tmc5160_stepper_x:virtual_endstop\" virtual pin # which may be used as the stepper's endstop_pin. Doing this enables # \"sensorless homing\". (Be sure to also set driver_SGT to an # appropriate sensitivity value.) The default is to not enable # sensorless homing. Run-time stepper motor current configuration \u00b6 [ad5206] \u00b6 Statically configured AD5206 digipots connected via SPI bus (one may define any number of sections with an \"ad5206\" prefix). [ad5206 my_digipot] enable_pin: # The pin corresponding to the AD5206 chip select line. This pin # will be set to low at the start of SPI messages and raised to high # after the message completes. This parameter must be provided. #spi_speed: #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #channel_1: #channel_2: #channel_3: #channel_4: #channel_5: #channel_6: # The value to statically set the given AD5206 channel to. This is # typically set to a number between 0.0 and 1.0 with 1.0 being the # highest resistance and 0.0 being the lowest resistance. However, # the range may be changed with the 'scale' parameter (see below). # If a channel is not specified then it is left unconfigured. #scale: # This parameter can be used to alter how the 'channel_x' parameters # are interpreted. If provided, then the 'channel_x' parameters # should be between 0.0 and 'scale'. This may be useful when the # AD5206 is used to set stepper voltage references. The 'scale' can # be set to the equivalent stepper amperage if the AD5206 were at # its highest resistance, and then the 'channel_x' parameters can be # specified using the desired amperage value for the stepper. The # default is to not scale the 'channel_x' parameters. [mcp4451] \u00b6 Statically configured MCP4451 digipot connected via I2C bus (one may define any number of sections with an \"mcp4451\" prefix). [mcp4451 my_digipot] i2c_address: # The i2c address that the chip is using on the i2c bus. This # parameter must be provided. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #wiper_0: #wiper_1: #wiper_2: #wiper_3: # The value to statically set the given MCP4451 \"wiper\" to. This is # typically set to a number between 0.0 and 1.0 with 1.0 being the # highest resistance and 0.0 being the lowest resistance. However, # the range may be changed with the 'scale' parameter (see below). # If a wiper is not specified then it is left unconfigured. #scale: # This parameter can be used to alter how the 'wiper_x' parameters # are interpreted. If provided, then the 'wiper_x' parameters should # be between 0.0 and 'scale'. This may be useful when the MCP4451 is # used to set stepper voltage references. The 'scale' can be set to # the equivalent stepper amperage if the MCP4451 were at its highest # resistance, and then the 'wiper_x' parameters can be specified # using the desired amperage value for the stepper. The default is # to not scale the 'wiper_x' parameters. [mcp4728] \u00b6 Statically configured MCP4728 digital-to-analog converter connected via I2C bus (one may define any number of sections with an \"mcp4728\" prefix). [mcp4728 my_dac] #i2c_address: 96 # The i2c address that the chip is using on the i2c bus. The default # is 96. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #channel_a: #channel_b: #channel_c: #channel_d: # The value to statically set the given MCP4728 channel to. This is # typically set to a number between 0.0 and 1.0 with 1.0 being the # highest voltage (2.048V) and 0.0 being the lowest voltage. # However, the range may be changed with the 'scale' parameter (see # below). If a channel is not specified then it is left # unconfigured. #scale: # This parameter can be used to alter how the 'channel_x' parameters # are interpreted. If provided, then the 'channel_x' parameters # should be between 0.0 and 'scale'. This may be useful when the # MCP4728 is used to set stepper voltage references. The 'scale' can # be set to the equivalent stepper amperage if the MCP4728 were at # its highest voltage (2.048V), and then the 'channel_x' parameters # can be specified using the desired amperage value for the # stepper. The default is to not scale the 'channel_x' parameters. [mcp4018] \u00b6 Statically configured MCP4018 digipot connected via i2c (one may define any number of sections with an \"mcp4018\" prefix). [mcp4018 my_digipot] #i2c_address: 47 # The i2c address that the chip is using on the i2c bus. The default # is 47. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. wiper: # The value to statically set the given MCP4018 \"wiper\" to. This is # typically set to a number between 0.0 and 1.0 with 1.0 being the # highest resistance and 0.0 being the lowest resistance. However, # the range may be changed with the 'scale' parameter (see below). # This parameter must be provided. #scale: # This parameter can be used to alter how the 'wiper' parameter is # interpreted. If provided, then the 'wiper' parameter should be # between 0.0 and 'scale'. This may be useful when the MCP4018 is # used to set stepper voltage references. The 'scale' can be set to # the equivalent stepper amperage if the MCP4018 is at its highest # resistance, and then the 'wiper' parameter can be specified using # the desired amperage value for the stepper. The default is to not # scale the 'wiper' parameter. Display support \u00b6 [display] \u00b6 Support for a display attached to the micro-controller. [display] lcd_type: # The type of LCD chip in use. This may be \"hd44780\", \"hd44780_spi\", # \"aip31068_spi\", \"st7920\", \"emulated_st7920\", \"uc1701\", \"ssd1306\", or # \"sh1106\". # See the display sections below for information on each type and # additional parameters they provide. This parameter must be # provided. #display_group: # The name of the display_data group to show on the display. This # controls the content of the screen (see the \"display_data\" section # for more information). The default is _default_20x4 for hd44780 or # aip31068_spi displays and _default_16x4 for other displays. #menu_timeout: # Timeout for menu. Being inactive this amount of seconds will # trigger menu exit or return to root menu when having autorun # enabled. The default is 0 seconds (disabled) #menu_root: # Name of the main menu section to show when clicking the encoder # on the home screen. The defaults is __main, and this shows the # the default menus as defined in klippy/extras/display/menu.cfg #menu_reverse_navigation: # When enabled it will reverse up and down directions for list # navigation. The default is False. This parameter is optional. #encoder_pins: # The pins connected to encoder. 2 pins must be provided when using # encoder. This parameter must be provided when using menu. #encoder_steps_per_detent: # How many steps the encoder emits per detent (\"click\"). If the # encoder takes two detents to move between entries or moves two # entries from one detent, try changing this. Allowed values are 2 # (half-stepping) or 4 (full-stepping). The default is 4. #click_pin: # The pin connected to 'enter' button or encoder 'click'. This # parameter must be provided when using menu. The presence of an # 'analog_range_click_pin' config parameter turns this parameter # from digital to analog. #back_pin: # The pin connected to 'back' button. This parameter is optional, # menu can be used without it. The presence of an # 'analog_range_back_pin' config parameter turns this parameter from # digital to analog. #up_pin: # The pin connected to 'up' button. This parameter must be provided # when using menu without encoder. The presence of an # 'analog_range_up_pin' config parameter turns this parameter from # digital to analog. #down_pin: # The pin connected to 'down' button. This parameter must be # provided when using menu without encoder. The presence of an # 'analog_range_down_pin' config parameter turns this parameter from # digital to analog. #kill_pin: # The pin connected to 'kill' button. This button will call # emergency stop. The presence of an 'analog_range_kill_pin' config # parameter turns this parameter from digital to analog. #analog_pullup_resistor: 4700 # The resistance (in ohms) of the pullup attached to the analog # button. The default is 4700 ohms. #analog_range_click_pin: # The resistance range for a 'enter' button. Range minimum and # maximum comma-separated values must be provided when using analog # button. #analog_range_back_pin: # The resistance range for a 'back' button. Range minimum and # maximum comma-separated values must be provided when using analog # button. #analog_range_up_pin: # The resistance range for a 'up' button. Range minimum and maximum # comma-separated values must be provided when using analog button. #analog_range_down_pin: # The resistance range for a 'down' button. Range minimum and # maximum comma-separated values must be provided when using analog # button. #analog_range_kill_pin: # The resistance range for a 'kill' button. Range minimum and # maximum comma-separated values must be provided when using analog # button. hd44780 display \u00b6 Information on configuring hd44780 displays (which is used in \"RepRapDiscount 2004 Smart Controller\" type displays). [display] lcd_type: hd44780 # Set to \"hd44780\" for hd44780 displays. rs_pin: e_pin: d4_pin: d5_pin: d6_pin: d7_pin: # The pins connected to an hd44780 type lcd. These parameters must # be provided. #hd44780_protocol_init: True # Perform 8-bit/4-bit protocol initialization on an hd44780 display. # This is necessary on real hd44780 devices. However, one may need # to disable this on some \"clone\" devices. The default is True. #line_length: # Set the number of characters per line for an hd44780 type lcd. # Possible values are 20 (default) and 16. The number of lines is # fixed to 4. ... hd44780_spi display \u00b6 Information on configuring an hd44780_spi display - a 20x04 display controlled via a hardware \"shift register\" (which is used in mightyboard based printers). [display] lcd_type: hd44780_spi # Set to \"hd44780_spi\" for hd44780_spi displays. latch_pin: spi_software_sclk_pin: spi_software_mosi_pin: spi_software_miso_pin: # The pins connected to the shift register controlling the display. # The spi_software_miso_pin needs to be set to an unused pin of the # printer mainboard as the shift register does not have a MISO pin, # but the software spi implementation requires this pin to be # configured. #hd44780_protocol_init: True # Perform 8-bit/4-bit protocol initialization on an hd44780 display. # This is necessary on real hd44780 devices. However, one may need # to disable this on some \"clone\" devices. The default is True. #line_length: # Set the number of characters per line for an hd44780 type lcd. # Possible values are 20 (default) and 16. The number of lines is # fixed to 4. ... aip31068_spi display \u00b6 Information on configuring an aip31068_spi display - a very similar to hd44780_spi a 20x04 (20 symbols by 4 lines) display with slightly different internal protocol. [display] lcd_type: aip31068_spi latch_pin: spi_software_sclk_pin: spi_software_mosi_pin: spi_software_miso_pin: # The pins connected to the shift register controlling the display. # The spi_software_miso_pin needs to be set to an unused pin of the # printer mainboard as the shift register does not have a MISO pin, # but the software spi implementation requires this pin to be # configured. #line_length: # Set the number of characters per line for an hd44780 type lcd. # Possible values are 20 (default) and 16. The number of lines is # fixed to 4. ... st7920 display \u00b6 Information on configuring st7920 displays (which is used in \"RepRapDiscount 12864 Full Graphic Smart Controller\" type displays). [display] lcd_type: st7920 # Set to \"st7920\" for st7920 displays. cs_pin: sclk_pin: sid_pin: # The pins connected to an st7920 type lcd. These parameters must be # provided. ... emulated_st7920 display \u00b6 Information on configuring an emulated st7920 display - found in some \"2.4 inch touchscreen devices\" and similar. [display] lcd_type: emulated_st7920 # Set to \"emulated_st7920\" for emulated_st7920 displays. en_pin: spi_software_sclk_pin: spi_software_mosi_pin: spi_software_miso_pin: # The pins connected to an emulated_st7920 type lcd. The en_pin # corresponds to the cs_pin of the st7920 type lcd, # spi_software_sclk_pin corresponds to sclk_pin and # spi_software_mosi_pin corresponds to sid_pin. The # spi_software_miso_pin needs to be set to an unused pin of the # printer mainboard as the st7920 as no MISO pin but the software # spi implementation requires this pin to be configured. ... uc1701 display \u00b6 Information on configuring uc1701 displays (which is used in \"MKS Mini 12864\" type displays). [display] lcd_type: uc1701 # Set to \"uc1701\" for uc1701 displays. cs_pin: a0_pin: # The pins connected to a uc1701 type lcd. These parameters must be # provided. #rst_pin: # The pin connected to the \"rst\" pin on the lcd. If it is not # specified then the hardware must have a pull-up on the # corresponding lcd line. #contrast: # The contrast to set. The value may range from 0 to 63 and the # default is 40. ... ssd1306 and sh1106 displays \u00b6 Information on configuring ssd1306 and sh1106 displays. [display] lcd_type: # Set to either \"ssd1306\" or \"sh1106\" for the given display type. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # Optional parameters available for displays connected via an i2c # bus. See the \"common I2C settings\" section for a description of # the above parameters. #cs_pin: #dc_pin: #spi_speed: #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # The pins connected to the lcd when in \"4-wire\" spi mode. See the # \"common SPI settings\" section for a description of the parameters # that start with \"spi_\". The default is to use i2c mode for the # display. #reset_pin: # A reset pin may be specified on the display. If it is not # specified then the hardware must have a pull-up on the # corresponding lcd line. #contrast: # The contrast to set. The value may range from 0 to 256 and the # default is 239. #vcomh: 0 # Set the Vcomh value on the display. This value is associated with # a \"smearing\" effect on some OLED displays. The value may range # from 0 to 63. Default is 0. #invert: False # TRUE inverts the pixels on certain OLED displays. The default is # False. #x_offset: 0 # Set the horizontal offset value on SH1106 displays. The default is # 0. ... [display_data] \u00b6 Support for displaying custom data on an lcd screen. One may create any number of display groups and any number of data items under those groups. The display will show all the data items for a given group if the display_group option in the [display] section is set to the given group name. A default set of display groups are automatically created. One can replace or extend these display_data items by overriding the defaults in the main printer.cfg config file. [display_data my_group_name my_data_name] position: # Comma separated row and column of the display position that should # be used to display the information. This parameter must be # provided. text: # The text to show at the given position. This field is evaluated # using command templates (see docs/Command_Templates.md). This # parameter must be provided. [display_template] \u00b6 Display data text \"macros\" (one may define any number of sections with a display_template prefix). See the command templates document for information on template evaluation. This feature allows one to reduce repetitive definitions in display_data sections. One may use the builtin render() function in display_data sections to evaluate a template. For example, if one were to define [display_template my_template] then one could use { render('my_template') } in a display_data section. This feature can also be used for continuous LED updates using the SET_LED_TEMPLATE command. [display_template my_template_name] #param_<name>: # One may specify any number of options with a \"param_\" prefix. The # given name will be assigned the given value (parsed as a Python # literal) and will be available during macro expansion. If the # parameter is passed in the call to render() then that value will # be used during macro expansion. For example, a config with # \"param_speed = 75\" might have a caller with # \"render('my_template_name', param_speed=80)\". Parameter names may # not use upper case characters. text: # The text to return when the this template is rendered. This field # is evaluated using command templates (see # docs/Command_Templates.md). This parameter must be provided. [display_glyph] \u00b6 Display a custom glyph on displays that support it. The given name will be assigned the given display data which can then be referenced in the display templates by their name surrounded by two \"tilde\" symbols i.e. ~my_display_glyph~ See sample-glyphs.cfg for some examples. [display_glyph my_display_glyph] #data: # The display data, stored as 16 lines consisting of 16 bits (1 per # pixel) where '.' is a blank pixel and '*' is an on pixel (e.g., # \"****************\" to display a solid horizontal line). # Alternatively, one can use '0' for a blank pixel and '1' for an on # pixel. Put each display line into a separate config line. The # glyph must consist of exactly 16 lines with 16 bits each. This # parameter is optional. #hd44780_data: # Glyph to use on 20x4 hd44780 displays. The glyph must consist of # exactly 8 lines with 5 bits each. This parameter is optional. #hd44780_slot: # The hd44780 hardware index (0..7) to store the glyph at. If # multiple distinct images use the same slot then make sure to only # use one of those images in any given screen. This parameter is # required if hd44780_data is specified. [display my_extra_display] \u00b6 If a primary [display] section has been defined in printer.cfg as shown above it is possible to define multiple auxiliary displays. Note that auxiliary displays do not currently support menu functionality, thus they do not support the \"menu\" options or button configuration. [display my_extra_display] # See the \"display\" section for available parameters. [menu] \u00b6 Customizable lcd display menus. A default set of menus are automatically created. One can replace or extend the menu by overriding the defaults in the main printer.cfg config file. See the command template document for information on menu attributes available during template rendering. # Common parameters available for all menu config sections. #[menu __some_list __some_name] #type: disabled # Permanently disabled menu element, only required attribute is 'type'. # Allows you to easily disable/hide existing menu items. #[menu some_name] #type: # One of command, input, list, text: # command - basic menu element with various script triggers # input - same like 'command' but has value changing capabilities. # Press will start/stop edit mode. # list - it allows for menu items to be grouped together in a # scrollable list. Add to the list by creating menu # configurations using \"some_list\" as a prefix - for # example: [menu some_list some_item_in_the_list] # vsdlist - same as 'list' but will append files from virtual sdcard # (will be removed in the future) #name: # Name of menu item - evaluated as a template. #enable: # Template that evaluates to True or False. #index: # Position where an item needs to be inserted in list. By default # the item is added at the end. #[menu some_list] #type: list #name: #enable: # See above for a description of these parameters. #[menu some_list some_command] #type: command #name: #enable: # See above for a description of these parameters. #gcode: # Script to run on button click or long click. Evaluated as a # template. #[menu some_list some_input] #type: input #name: #enable: # See above for a description of these parameters. #input: # Initial value to use when editing - evaluated as a template. # Result must be float. #input_min: # Minimum value of range - evaluated as a template. Default -99999. #input_max: # Maximum value of range - evaluated as a template. Default 99999. #input_step: # Editing step - Must be a positive integer or float value. It has # internal fast rate step. When \"(input_max - input_min) / # input_step > 100\" then fast rate step is 10 * input_step else fast # rate step is same input_step. #realtime: # This attribute accepts static boolean value. When enabled then # gcode script is run after each value change. The default is False. #gcode: # Script to run on button click, long click or value change. # Evaluated as a template. The button click will trigger the edit # mode start or end. Filament sensors \u00b6 [filament_switch_sensor] \u00b6 Filament Switch Sensor. Support for filament insert and runout detection using a switch sensor, such as an endstop switch. See the command reference for more information. [filament_switch_sensor my_sensor] #pause_on_runout: True # When set to True, a PAUSE will execute immediately after a runout # is detected. Note that if pause_on_runout is False and the # runout_gcode is omitted then runout detection is disabled. Default # is True. #runout_gcode: # A list of G-Code commands to execute after a filament runout is # detected. See docs/Command_Templates.md for G-Code format. If # pause_on_runout is set to True this G-Code will run after the # PAUSE is complete. The default is not to run any G-Code commands. #insert_gcode: # A list of G-Code commands to execute after a filament insert is # detected. See docs/Command_Templates.md for G-Code format. The # default is not to run any G-Code commands, which disables insert # detection. #event_delay: 3.0 # The minimum amount of time in seconds to delay between events. # Events triggered during this time period will be silently # ignored. The default is 3 seconds. #pause_delay: 0.5 # The amount of time to delay, in seconds, between the pause command # dispatch and execution of the runout_gcode. It may be useful to # increase this delay if OctoPrint exhibits strange pause behavior. # Default is 0.5 seconds. #debounce_delay: # A period of time in seconds to debounce events prior to running the # switch gcode. The switch must he held in a single state for at least # this long to activate. If the switch is toggled on/off during this delay, # the event is ignored. Default is 0. #switch_pin: # The pin on which the switch is connected. This parameter must be # provided. [filament_motion_sensor] \u00b6 Filament Motion Sensor. Support for filament insert and runout detection using an encoder that toggles the output pin during filament movement through the sensor. See the command reference for more information. [filament_motion_sensor my_sensor] detection_length: 7.0 # The minimum length of filament pulled through the sensor to trigger # a state change on the switch_pin # Default is 7 mm. extruder: # The name of the extruder or extruder_stepper section this sensor # is associated with. This parameter must be provided. switch_pin: #pause_on_runout: #runout_gcode: #insert_gcode: #event_delay: #pause_delay: # See the \"filament_switch_sensor\" section for a description of the # above parameters. [tsl1401cl_filament_width_sensor] \u00b6 TSLl401CL Based Filament Width Sensor. See the guide for more information. [tsl1401cl_filament_width_sensor] #pin: #default_nominal_filament_diameter: 1.75 # (mm) # Maximum allowed filament diameter difference as mm. #max_difference: 0.2 # The distance from sensor to the melting chamber as mm. #measurement_delay: 100 [hall_filament_width_sensor] \u00b6 Hall filament width sensor (see Hall Filament Width Sensor ). [hall_filament_width_sensor] adc1: adc2: # Analog input pins connected to the sensor. These parameters must # be provided. #cal_dia1: 1.50 #cal_dia2: 2.00 # The calibration values (in mm) for the sensors. The default is # 1.50 for cal_dia1 and 2.00 for cal_dia2. #raw_dia1: 9500 #raw_dia2: 10500 # The raw calibration values for the sensors. The default is 9500 # for raw_dia1 and 10500 for raw_dia2. #default_nominal_filament_diameter: 1.75 # The nominal filament diameter. This parameter must be provided. #max_difference: 0.200 # Maximum allowed filament diameter difference in millimeters (mm). # If difference between nominal filament diameter and sensor output # is more than +- max_difference, extrusion multiplier is set back # to %100. The default is 0.200. #measurement_delay: 70 # The distance from sensor to the melting chamber/hot-end in # millimeters (mm). The filament between the sensor and the hot-end # will be treated as the default_nominal_filament_diameter. Host # module works with FIFO logic. It keeps each sensor value and # position in an array and POP them back in correct position. This # parameter must be provided. #enable: False # Sensor enabled or disabled after power on. The default is to # disable. #measurement_interval: 10 # The approximate distance (in mm) between sensor readings. The # default is 10mm. #logging: False # Out diameter to terminal and klipper.log can be turn on|of by # command. #min_diameter: 1.0 # Minimal diameter for trigger virtual filament_switch_sensor. #max_diameter: # Maximum diameter for triggering virtual filament_switch_sensor. # The default is default_nominal_filament_diameter + max_difference. #use_current_dia_while_delay: False # Use the current diameter instead of the nominal diameter while # the measurement delay has not run through. #pause_on_runout: #runout_gcode: #insert_gcode: #event_delay: #pause_delay: # See the \"filament_switch_sensor\" section for a description of the # above parameters. Load Cells \u00b6 [load_cell] \u00b6 Load Cell. Uses an ADC sensor attached to a load cell to create a digital scale. [load_cell] sensor_type: # This must be one of the supported sensor types, see below. #counts_per_gram: # The floating point number of sensor counts that indicates 1 gram of force. # This value is calculated by the LOAD_CELL_CALIBRATE command. #reference_tare_counts: # The integer tare value, in raw sensor counts, taken when LOAD_CELL_CALIBRATE # is run. This is the default tare value when klipper starts up. #sensor_orientation: # Change the sensor's orientation. Can be either 'normal' or 'inverted'. # The default is 'normal'. Use 'inverted' if the sensor reports a # decreasing force value when placed under load. HX711 \u00b6 This is a 24 bit low sample rate chip using \"bit-bang\" communications. It is suitable for filament scales. [load_cell] sensor_type: hx711 sclk_pin: # The pin connected to the HX711 clock line. This parameter must be provided. dout_pin: # The pin connected to the HX711 data output line. This parameter must be # provided. #gain: A-128 # Valid values for gain are: A-128, A-64, B-32. The default is A-128. # 'A' denotes the input channel and the number denotes the gain. Only the 3 # listed combinations are supported by the chip. Note that changing the gain # setting also selects the channel being read. #sample_rate: 80 # Valid values for sample_rate are 80 or 10. The default value is 80. # This must match the wiring of the chip. The sample rate cannot be changed # in software. HX717 \u00b6 This is the 4x higher sample rate version of the HX711, suitable for probing. [load_cell] sensor_type: hx717 sclk_pin: # The pin connected to the HX717 clock line. This parameter must be provided. dout_pin: # The pin connected to the HX717 data output line. This parameter must be # provided. #gain: A-128 # Valid values for gain are A-128, B-64, A-64, B-8. # 'A' denotes the input channel and the number denotes the gain setting. # Only the 4 listed combinations are supported by the chip. Note that # changing the gain setting also selects the channel being read. #sample_rate: 320 # Valid values for sample_rate are: 10, 20, 80, 320. The default is 320. # This must match the wiring of the chip. The sample rate cannot be changed # in software. ADS1220 \u00b6 The ADS1220 is a 24 bit ADC supporting up to a 2Khz sample rate configurable in software. [load_cell] sensor_type: ads1220 cs_pin: # The pin connected to the ADS1220 chip select line. This parameter must # be provided. #spi_speed: 512000 # This chip supports 2 speeds: 256000 or 512000. The faster speed is only # enabled when one of the Turbo sample rates is used. The correct spi_speed # is selected based on the sample rate. #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. data_ready_pin: # Pin connected to the ADS1220 data ready line. This parameter must be # provided. #gain: 128 # Valid gain values are 128, 64, 32, 16, 8, 4, 2, 1 # The default is 128 #pga_bypass: False # Disable the internal Programmable Gain Amplifier. If # True the PGA will be disabled for gains 1, 2, and 4. The PGA is always # enabled for gain settings 8 to 128, regardless of the pga_bypass setting. # If AVSS is used as an input pga_bypass is forced to True. # The default is False. #sample_rate: 660 # This chip supports two ranges of sample rates, Normal and Turbo. In turbo # mode the chip's internal clock runs twice as fast and the SPI communication # speed is also doubled. # Normal sample rates: 20, 45, 90, 175, 330, 600, 1000 # Turbo sample rates: 40, 90, 180, 350, 660, 1200, 2000 # The default is 660 #input_mux: # Input multiplexer configuration, select a pair of pins to use. The first pin # is the positive, AINP, and the second pin is the negative, AINN. Valid # values are: 'AIN0_AIN1', 'AIN0_AIN2', 'AIN0_AIN3', 'AIN1_AIN2', 'AIN1_AIN3', # 'AIN2_AIN3', 'AIN1_AIN0', 'AIN3_AIN2', 'AIN0_AVSS', 'AIN1_AVSS', 'AIN2_AVSS' # and 'AIN3_AVSS'. If AVSS is used the PGA is bypassed and the pga_bypass # setting will be forced to True. # The default is AIN0_AIN1. #vref: # The selected voltage reference. Valid values are: 'internal', 'REF0', 'REF1' # and 'analog_supply'. Default is 'internal'. [load_cell_probe] \u00b6 Load Cell Probe. This combines the functionality of a [probe] and a [load_cell]. [load_cell_probe] sensor_type: # This must be one of the supported bulk ADC sensor types and support # load cell endstops on the mcu. #counts_per_gram: #reference_tare_counts: #sensor_orientation: # These parameters must be configured before the probe will operate. # See the [load_cell] section for further details. #force_safety_limit: 2000 # The safe limit for probing force relative to the reference_tare_counts on # the load_cell. The default is +/-2Kg. #trigger_force: 75.0 # The force that the probe will trigger at. 75g is the default. #drift_filter_cutoff_frequency: 0.8 # Enable optional continuous taring while homing & probing to reject drift. # The value is a frequency, in Hz, below which drift will be ignored. This # option requires the SciPy library. Default: None #drift_filter_delay: 2 # The delay, or 'order', of the drift filter. This controls the number of # samples required to make a trigger detection. Can be 1 or 2, the default # is 2. #buzz_filter_cutoff_frequency: 100.0 # The value is a frequency, in Hz, above which high frequency noise in the # load cell will be igfiltered outnored. This option requires the SciPy # library. Default: None #buzz_filter_delay: 2 # The delay, or 'order', of the buzz filter. This controls the number of # samples required to make a trigger detection. Can be 1 or 2, the default # is 2. #notch_filter_frequencies: 50, 60 # 1 or 2 frequencies, in Hz, to filter out of the load cell data. This is # intended to reject power line noise. This option requires the SciPy # library. Default: None #notch_filter_quality: 2.0 # Controls how narrow the range of frequencies are that the notch filter # removes. Larger numbers produce a narrower filter. Minimum value is 0.5 and # maximum is 3.0. Default: 2.0 #tare_time: # The rime in seconds used for taring the load_cell before each probe. The # default value is: 4 / 60 = 0.066. This collects samples from 4 cycles of # 60Hz mains power to cancel power line noise. #z_offset: #speed: #samples: #sample_retract_dist: #lift_speed: #samples_result: #samples_tolerance: #samples_tolerance_retries: #activate_gcode: #deactivate_gcode: # See the \"[probe]\" section for a description of the above parameters. Board specific hardware support \u00b6 [sx1509] \u00b6 Configure an SX1509 I2C to GPIO expander. Due to the delay incurred by I2C communication you should NOT use SX1509 pins as stepper enable, step or dir pins or any other pin that requires fast bit-banging. They are best used as static or gcode controlled digital outputs or hardware-pwm pins for e.g. fans. One may define any number of sections with an \"sx1509\" prefix. Each expander provides a set of 16 pins (sx1509_my_sx1509:PIN_0 to sx1509_my_sx1509:PIN_15) which can be used in the printer configuration. See the generic-duet2-duex.cfg file for an example. [sx1509 my_sx1509] i2c_address: # I2C address used by this expander. Depending on the hardware # jumpers this is one out of the following addresses: 62 63 112 # 113. This parameter must be provided. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. [samd_sercom] \u00b6 SAMD SERCOM configuration to specify which pins to use on a given SERCOM. One may define any number of sections with a \"samd_sercom\" prefix. Each SERCOM must be configured prior to using it as SPI or I2C peripheral. Place this config section above any other section that makes use of SPI or I2C buses. [samd_sercom my_sercom] sercom: # The name of the sercom bus to configure in the micro-controller. # Available names are \"sercom0\", \"sercom1\", etc.. This parameter # must be provided. tx_pin: # MOSI pin for SPI communication, or SDA (data) pin for I2C # communication. The pin must have a valid pinmux configuration # for the given SERCOM peripheral. This parameter must be provided. #rx_pin: # MISO pin for SPI communication. This pin is not used for I2C # communication (I2C uses tx_pin for both sending and receiving). # The pin must have a valid pinmux configuration for the given # SERCOM peripheral. This parameter is optional. clk_pin: # CLK pin for SPI communication, or SCL (clock) pin for I2C # communication. The pin must have a valid pinmux configuration # for the given SERCOM peripheral. This parameter must be provided. [adc_scaled] \u00b6 Duet2 Maestro analog scaling by vref and vssa readings. Defining an adc_scaled section enables virtual adc pins (such as \"my_name:PB0\") that are automatically adjusted by the board's vref and vssa monitoring pins. Be sure to define this config section above any config sections that use one these virtual pins. See the generic-duet2-maestro.cfg file for an example. [adc_scaled my_name] vref_pin: # The ADC pin to use for VREF monitoring. This parameter must be # provided. vssa_pin: # The ADC pin to use for VSSA monitoring. This parameter must be # provided. #smooth_time: 2.0 # A time value (in seconds) over which the vref and vssa # measurements will be smoothed to reduce the impact of measurement # noise. The default is 2 seconds. [ads1x1x] \u00b6 ADS1013, ADS1014, ADS1015, ADS1113, ADS1114 and ADS1115 are I2C based Analog to Digital Converters that can be used for temperature sensors. They provide 4 analog input pins either as single line or as differential input. Note: Use caution if using this sensor to control heaters. The heater min_temp and max_temp are only verified in the host and only if the host is running and operating normally. (ADC inputs directly connected to the micro-controller verify min_temp and max_temp within the micro-controller and do not require a working connection to the host.) [ads1x1x my_ads1x1x] chip: ADS1115 #pga: 4.096V # Default value is 4.096V. The maximum voltage range used for the input. This # scales all values read from the ADC. Options are: 6.144V, 4.096V, 2.048V, # 1.024V, 0.512V, 0.256V #adc_voltage: 3.3 # The supply voltage for the device. This allows additional software scaling # for all values read from the ADC. i2c_mcu: host i2c_bus: i2c.1 #address_pin: GND # Default value is GND. There can be up to four addressed devices depending # upon wiring of the device. Check the datasheet for details. The i2c_address # can be specified directly instead of using the address_pin. The chip provides pins that can be used on other sensors. sensor_type: ... # Can be any thermistor or adc_temperature. sensor_pin: my_ads1x1x:AIN0 # A combination of the name of the ads1x1x chip and the pin. Possible # pin values are AIN0, AIN1, AIN2 and AIN3 for single ended lines and # DIFF01, DIFF03, DIFF13 and DIFF23 for differential between their # corresponding lines. For example # DIFF03 measures the differential between line 0 and 3. Only specific # combinations for the differentials are allowed. [replicape] \u00b6 Replicape support - see the beaglebone guide and the generic-replicape.cfg file for an example. # The \"replicape\" config section adds \"replicape:stepper_x_enable\" # virtual stepper enable pins (for steppers X, Y, Z, E, and H) and # \"replicape:power_x\" PWM output pins (for hotbed, e, h, fan0, fan1, # fan2, and fan3) that may then be used elsewhere in the config file. [replicape] revision: # The replicape hardware revision. Currently only revision \"B3\" is # supported. This parameter must be provided. #enable_pin: !gpio0_20 # The replicape global enable pin. The default is !gpio0_20 (aka # P9_41). host_mcu: # The name of the mcu config section that communicates with the # Klipper \"linux process\" mcu instance. This parameter must be # provided. #standstill_power_down: False # This parameter controls the CFG6_ENN line on all stepper # motors. True sets the enable lines to \"open\". The default is # False. #stepper_x_microstep_mode: #stepper_y_microstep_mode: #stepper_z_microstep_mode: #stepper_e_microstep_mode: #stepper_h_microstep_mode: # This parameter controls the CFG1 and CFG2 pins of the given # stepper motor driver. Available options are: disable, 1, 2, # spread2, 4, 16, spread4, spread16, stealth4, and stealth16. The # default is disable. #stepper_x_current: #stepper_y_current: #stepper_z_current: #stepper_e_current: #stepper_h_current: # The configured maximum current (in Amps) of the stepper motor # driver. This parameter must be provided if the stepper is not in a # disable mode. #stepper_x_chopper_off_time_high: #stepper_y_chopper_off_time_high: #stepper_z_chopper_off_time_high: #stepper_e_chopper_off_time_high: #stepper_h_chopper_off_time_high: # This parameter controls the CFG0 pin of the stepper motor driver # (True sets CFG0 high, False sets it low). The default is False. #stepper_x_chopper_hysteresis_high: #stepper_y_chopper_hysteresis_high: #stepper_z_chopper_hysteresis_high: #stepper_e_chopper_hysteresis_high: #stepper_h_chopper_hysteresis_high: # This parameter controls the CFG4 pin of the stepper motor driver # (True sets CFG4 high, False sets it low). The default is False. #stepper_x_chopper_blank_time_high: #stepper_y_chopper_blank_time_high: #stepper_z_chopper_blank_time_high: #stepper_e_chopper_blank_time_high: #stepper_h_chopper_blank_time_high: # This parameter controls the CFG5 pin of the stepper motor driver # (True sets CFG5 high, False sets it low). The default is True. Other Custom Modules \u00b6 [palette2] \u00b6 Palette 2 multimaterial support - provides a tighter integration supporting Palette 2 devices in connected mode. This modules also requires [virtual_sdcard] and [pause_resume] for full functionality. If you use this module, do not use the Palette 2 plugin for Octoprint as they will conflict, and 1 will fail to initialize properly likely aborting your print. If you use Octoprint and stream gcode over the serial port instead of printing from virtual_sd, then remove M1 and M0 from Pausing commands in Settings > Serial Connection > Firmware & protocol will prevent the need to start print on the Palette 2 and unpausing in Octoprint for your print to begin. [palette2] serial: # The serial port to connect to the Palette 2. #baud: 115200 # The baud rate to use. The default is 115200. #feedrate_splice: 0.8 # The feedrate to use when splicing, default is 0.8 #feedrate_normal: 1.0 # The feedrate to use after splicing, default is 1.0 #auto_load_speed: 2 # Extrude feedrate when autoloading, default is 2 (mm/s) #auto_cancel_variation: 0.1 # Auto cancel print when ping variation is above this threshold [angle] \u00b6 Magnetic hall angle sensor support for reading stepper motor angle shaft measurements using a1333, as5047d, mt6816, mt6826s, or tle5012b SPI chips. The measurements are available via the API Server and motion analysis tool . See the G-Code reference for available commands. [angle my_angle_sensor] sensor_type: # The type of the magnetic hall sensor chip. Available choices are # \"a1333\", \"as5047d\", \"mt6816\", \"mt6826s\", and \"tle5012b\". This parameter must be # specified. #sample_period: 0.000400 # The query period (in seconds) to use during measurements. The # default is 0.000400 (which is 2500 samples per second). #stepper: # The name of the stepper that the angle sensor is attached to (eg, # \"stepper_x\"). Setting this value enables an angle calibration # tool. To use this feature, the Python \"numpy\" package must be # installed. The default is to not enable angle calibration for the # angle sensor. cs_pin: # The SPI enable pin for the sensor. This parameter must be provided. #spi_speed: #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. Common bus parameters \u00b6 Common SPI settings \u00b6 The following parameters are generally available for devices using an SPI bus. #spi_speed: # The SPI speed (in hz) to use when communicating with the device. # The default depends on the type of device. #spi_bus: # If the micro-controller supports multiple SPI busses then one may # specify the micro-controller bus name here. The default depends on # the type of micro-controller. #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # Specify the above parameters to use \"software based SPI\". This # mode does not require micro-controller hardware support (typically # any general purpose pins may be used). The default is to not use # \"software spi\". Common I2C settings \u00b6 The following parameters are generally available for devices using an I2C bus. Note that Klipper's current micro-controller support for I2C is generally not tolerant to line noise. Unexpected errors on the I2C wires may result in Klipper raising a run-time error. Klipper's support for error recovery varies between each micro-controller type. It is generally recommended to only use I2C devices that are on the same printed circuit board as the micro-controller. Most Klipper micro-controller implementations only support an i2c_speed of 100000 ( standard mode , 100kbit/s). The Klipper \"Linux\" micro-controller supports a 400000 speed ( fast mode , 400kbit/s), but it must be set in the operating system and the i2c_speed parameter is otherwise ignored. The Klipper \"RP2040\" micro-controller and ATmega AVR family and some STM32 (F0, G0, G4, L4, F7, H7) support a rate of 400000 via the i2c_speed parameter. All other Klipper micro-controllers use a 100000 rate and ignore the i2c_speed parameter. #i2c_address: # The i2c address of the device. This must specified as a decimal # number (not in hex). The default depends on the type of device. #i2c_mcu: # The name of the micro-controller that the chip is connected to. # The default is \"mcu\". #i2c_bus: # If the micro-controller supports multiple I2C busses then one may # specify the micro-controller bus name here. The default depends on # the type of micro-controller. #i2c_software_scl_pin: #i2c_software_sda_pin: # Specify these parameters to use micro-controller software based # I2C \"bit-banging\" support. The two parameters should the two pins # on the micro-controller to use for the scl and sda wires. The # default is to use hardware based I2C support as specified by the # i2c_bus parameter. #i2c_speed: # The I2C speed (in Hz) to use when communicating with the device. # The Klipper implementation on most micro-controllers is hard-coded # to 100000 and changing this value has no effect. The default is # 100000. Linux, RP2040 and ATmega support 400000.","title":"Configuration reference"},{"location":"Config_Reference.html#configuration-reference","text":"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.","title":"Configuration reference"},{"location":"Config_Reference.html#micro-controller-configuration","text":"","title":"Micro-controller configuration"},{"location":"Config_Reference.html#format-of-micro-controller-pin-names","text":"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.","title":"Format of micro-controller pin names"},{"location":"Config_Reference.html#mcu","text":"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.","title":"[mcu]"},{"location":"Config_Reference.html#mcu-my_extra_mcu","text":"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.","title":"[mcu my_extra_mcu]"},{"location":"Config_Reference.html#common-kinematic-settings","text":"","title":"Common kinematic settings"},{"location":"Config_Reference.html#printer","text":"The printer section controls high level printer settings. [printer] kinematics: # The type of printer in use. This option may be one of: cartesian, # corexy, corexz, hybrid_corexy, hybrid_corexz, generic_cartesian, # rotary_delta, delta, deltesian, polar, winch, or none. # This parameter must be specified. max_velocity: # Maximum velocity (in mm/s) of the toolhead (relative to the # print). This value may be changed at runtime using the # SET_VELOCITY_LIMIT command. This parameter must be specified. max_accel: # Maximum acceleration (in mm/s^2) of the toolhead (relative to the # print). Although this parameter is described as a \"maximum\" # acceleration, in practice most moves that accelerate or decelerate # will do so at the rate specified here. The value specified here # may be changed at runtime using the SET_VELOCITY_LIMIT command. # This parameter must be specified. #minimum_cruise_ratio: 0.5 # Most moves will accelerate to a cruising speed, travel at that # cruising speed, and then decelerate. However, some moves that # travel a short distance could nominally accelerate and then # immediately decelerate. This option reduces the top speed of these # moves to ensure there is always a minimum distance traveled at a # cruising speed. That is, it enforces a minimum distance traveled # at cruising speed relative to the total distance traveled. It is # intended to reduce the top speed of short zigzag moves (and thus # reduce printer vibration from these moves). For example, a # minimum_cruise_ratio of 0.5 would ensure that a standalone 1.5mm # move would have a minimum cruising distance of 0.75mm. Specify a # ratio of 0.0 to disable this feature (there would be no minimum # cruising distance enforced between acceleration and deceleration). # The value specified here may be changed at runtime using the # SET_VELOCITY_LIMIT command. The default is 0.5. #square_corner_velocity: 5.0 # The maximum velocity (in mm/s) that the toolhead may travel a 90 # degree corner at. A non-zero value can reduce changes in extruder # flow rates by enabling instantaneous velocity changes of the # toolhead during cornering. This value configures the internal # centripetal velocity cornering algorithm; corners with angles # larger than 90 degrees will have a higher cornering velocity while # corners with angles less than 90 degrees will have a lower # cornering velocity. If this is set to zero then the toolhead will # decelerate to zero at each corner. The value specified here may be # changed at runtime using the SET_VELOCITY_LIMIT command. The # default is 5mm/s.","title":"[printer]"},{"location":"Config_Reference.html#stepper","text":"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. [stepper_x] step_pin: # Step GPIO pin (triggered high). This parameter must be provided. dir_pin: # Direction GPIO pin (high indicates positive direction). This # parameter must be provided. enable_pin: # Enable pin (default is enable high; use ! to indicate enable # low). If this parameter is not provided then the stepper motor # driver must always be enabled. rotation_distance: # Distance (in mm) that the axis travels with one full rotation of # the stepper motor (or final gear if gear_ratio is specified). # This parameter must be provided. microsteps: # The number of microsteps the stepper motor driver uses. This # parameter must be provided. #full_steps_per_rotation: 200 # The number of full steps for one rotation of the stepper motor. # Set this to 200 for a 1.8 degree stepper motor or set to 400 for a # 0.9 degree motor. The default is 200. #gear_ratio: # The gear ratio if the stepper motor is connected to the axis via a # gearbox. For example, one may specify \"5:1\" if a 5 to 1 gearbox is # in use. If the axis has multiple gearboxes one may specify a comma # separated list of gear ratios (for example, \"57:11, 2:1\"). If a # gear_ratio is specified then rotation_distance specifies the # distance the axis travels for one full rotation of the final gear. # The default is to not use a gear ratio. #step_pulse_duration: # The minimum time between the step pulse signal edge and the # following \"unstep\" signal edge. This is also used to set the # minimum time between a step pulse and a direction change signal. # The default is 0.000000100 (100ns) for TMC steppers that are # configured in UART or SPI mode, and the default is 0.000002 (which # is 2us) for all other steppers. endstop_pin: # Endstop switch detection pin. If this endstop pin is on a # different mcu than the stepper motor then it enables \"multi-mcu # homing\". This parameter must be provided for the X, Y, and Z # steppers on cartesian style printers. #position_min: 0 # Minimum valid distance (in mm) the user may command the stepper to # move to. The default is 0mm. position_endstop: # Location of the endstop (in mm). This parameter must be provided # for the X, Y, and Z steppers on cartesian style printers. position_max: # Maximum valid distance (in mm) the user may command the stepper to # move to. This parameter must be provided for the X, Y, and Z # steppers on cartesian style printers. #homing_speed: 5.0 # Maximum velocity (in mm/s) of the stepper when homing. The default # is 5mm/s. #homing_retract_dist: 5.0 # Distance to backoff (in mm) before homing a second time during # homing. Set this to zero to disable the second home. The default # is 5mm. #homing_retract_speed: # Speed to use on the retract move after homing in case this should # be different from the homing speed, which is the default for this # parameter #second_homing_speed: # Velocity (in mm/s) of the stepper when performing the second home. # The default is homing_speed/2. #homing_positive_dir: # If true, homing will cause the stepper to move in a positive # direction (away from zero); if false, home towards zero. It is # better to use the default than to specify this parameter. The # default is true if position_endstop is near position_max and false # if near position_min.","title":"[stepper]"},{"location":"Config_Reference.html#cartesian-kinematics","text":"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]","title":"Cartesian Kinematics"},{"location":"Config_Reference.html#linear-delta-kinematics","text":"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. [printer] kinematics: delta max_z_velocity: # For delta printers this limits the maximum velocity (in mm/s) of # moves with z axis movement. This setting can be used to reduce the # maximum speed of up/down moves (which require a higher step rate # than other moves on a delta printer). 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. Setting this may be useful if the printer can reach higher # acceleration on XY moves than Z moves (eg, when using input shaper). # The default is to use max_accel for max_z_accel. #minimum_z_position: 0 # The minimum Z position that the user may command the head to move # to. The default is 0. delta_radius: # Radius (in mm) of the horizontal circle formed by the three linear # axis towers. This parameter may also be calculated as: # delta_radius = smooth_rod_offset - effector_offset - carriage_offset # This parameter must be provided. #print_radius: # The radius (in mm) of valid toolhead XY coordinates. One may use # this setting to customize the range checking of toolhead moves. If # a large value is specified here then it may be possible to command # the toolhead into a collision with a tower. The default is to use # delta_radius for print_radius (which would normally prevent a # tower collision). # The stepper_a section describes the stepper controlling the front # left tower (at 210 degrees). This section also controls the homing # parameters (homing_speed, homing_retract_dist) for all towers. [stepper_a] position_endstop: # Distance (in mm) between the nozzle and the bed when the nozzle is # in the center of the build area and the endstop triggers. This # parameter must be provided for stepper_a; for stepper_b and # stepper_c this parameter defaults to the value specified for # stepper_a. arm_length: # Length (in mm) of the diagonal rod that connects this tower to the # print head. This parameter must be provided for stepper_a; for # stepper_b and stepper_c this parameter defaults to the value # specified for stepper_a. #angle: # This option specifies the angle (in degrees) that the tower is # at. The default is 210 for stepper_a, 330 for stepper_b, and 90 # for stepper_c. # The stepper_b section describes the stepper controlling the front # right tower (at 330 degrees). [stepper_b] # The stepper_c section describes the stepper controlling the rear # tower (at 90 degrees). [stepper_c] # The delta_calibrate section enables a DELTA_CALIBRATE extended # g-code command that can calibrate the tower endstop positions and # angles. [delta_calibrate] radius: # Radius (in mm) of the area that may be probed. This is the radius # of nozzle coordinates to be probed; if using an automatic probe # with an XY offset then choose a radius small enough so that the # probe always fits over the bed. This parameter must be provided. #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.","title":"Linear Delta Kinematics"},{"location":"Config_Reference.html#deltesian-kinematics","text":"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. [printer] kinematics: deltesian max_z_velocity: # For deltesian printers, this limits the maximum velocity (in mm/s) of # moves with z axis movement. This setting can be used to reduce the # maximum speed of up/down moves (which require a higher step rate # than other moves on a deltesian printer). 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. Setting this may be useful if the printer can reach higher # acceleration on XY moves than Z moves (eg, when using input shaper). # The default is to use max_accel for max_z_accel. #minimum_z_position: 0 # The minimum Z position that the user may command the head to move # to. The default is 0. #min_angle: 5 # This represents the minimum angle (in degrees) relative to horizontal # that the deltesian arms are allowed to achieve. This parameter is # intended to restrict the arms from becoming completely horizontal, # which would risk accidental inversion of the XZ axis. The default is 5. #print_width: # The distance (in mm) of valid toolhead X coordinates. One may use # this setting to customize the range checking of toolhead moves. If # a large value is specified here then it may be possible to command # the toolhead into a collision with a tower. This setting usually # corresponds to bed width (in mm). #slow_ratio: 3 # The ratio used to limit velocity and acceleration on moves near the # extremes of the X axis. If vertical distance divided by horizontal # distance exceeds the value of slow_ratio, then velocity and # acceleration are limited to half their nominal values. If vertical # distance divided by horizontal distance exceeds twice the value of # the slow_ratio, then velocity and acceleration are limited to one # quarter of their nominal values. The default is 3. # The stepper_left section is used to describe the stepper controlling # the left tower. This section also controls the homing parameters # (homing_speed, homing_retract_dist) for all towers. [stepper_left] position_endstop: # Distance (in mm) between the nozzle and the bed when the nozzle is # in the center of the build area and the endstops are triggered. This # parameter must be provided for stepper_left; for stepper_right this # parameter defaults to the value specified for stepper_left. arm_length: # Length (in mm) of the diagonal rod that connects the tower carriage to # the print head. This parameter must be provided for stepper_left; for # stepper_right, this parameter defaults to the value specified for # stepper_left. arm_x_length: # Horizontal distance between the print head and the tower when the # printers is homed. This parameter must be provided for stepper_left; # for stepper_right, this parameter defaults to the value specified for # stepper_left. # The stepper_right section is used to describe the stepper controlling the # right tower. [stepper_right] # The stepper_y section is used to describe the stepper controlling # the Y axis in a deltesian robot. [stepper_y]","title":"Deltesian Kinematics"},{"location":"Config_Reference.html#corexy-kinematics","text":"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]","title":"CoreXY Kinematics"},{"location":"Config_Reference.html#corexz-kinematics","text":"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]","title":"CoreXZ Kinematics"},{"location":"Config_Reference.html#hybrid-corexy-kinematics","text":"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]","title":"Hybrid-CoreXY Kinematics"},{"location":"Config_Reference.html#hybrid-corexz-kinematics","text":"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]","title":"Hybrid-CoreXZ Kinematics"},{"location":"Config_Reference.html#polar-kinematics","text":"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. # 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]","title":"Polar Kinematics"},{"location":"Config_Reference.html#rotary-delta-kinematics","text":"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. [printer] kinematics: rotary_delta max_z_velocity: # For delta printers this limits the maximum velocity (in mm/s) of # moves with z axis movement. This setting can be used to reduce the # maximum speed of up/down moves (which require a higher step rate # than other moves on a delta printer). The default is to use # max_velocity for max_z_velocity. #minimum_z_position: 0 # The minimum Z position that the user may command the head to move # to. The default is 0. shoulder_radius: # Radius (in mm) of the horizontal circle formed by the three # shoulder joints, minus the radius of the circle formed by the # effector joints. This parameter may also be calculated as: # shoulder_radius = (delta_f - delta_e) / sqrt(12) # This parameter must be provided. shoulder_height: # Distance (in mm) of the shoulder joints from the bed, minus the # effector toolhead height. This parameter must be provided. # The stepper_a section describes the stepper controlling the rear # right arm (at 30 degrees). This section also controls the homing # parameters (homing_speed, homing_retract_dist) for all arms. [stepper_a] gear_ratio: # A gear_ratio must be specified and rotation_distance may not be # specified. For example, if the arm has an 80 toothed pulley driven # by a pulley with 16 teeth, which is in turn connected to a 60 # toothed pulley driven by a stepper with a 16 toothed pulley, then # one would specify a gear ratio of \"80:16, 60:16\". This parameter # must be provided. position_endstop: # Distance (in mm) between the nozzle and the bed when the nozzle is # in the center of the build area and the endstop triggers. This # parameter must be provided for stepper_a; for stepper_b and # stepper_c this parameter defaults to the value specified for # stepper_a. upper_arm_length: # Length (in mm) of the arm connecting the \"shoulder joint\" to the # \"elbow joint\". This parameter must be provided for stepper_a; for # stepper_b and stepper_c this parameter defaults to the value # specified for stepper_a. lower_arm_length: # Length (in mm) of the arm connecting the \"elbow joint\" to the # \"effector joint\". This parameter must be provided for stepper_a; # for stepper_b and stepper_c this parameter defaults to the value # specified for stepper_a. #angle: # This option specifies the angle (in degrees) that the arm is at. # The default is 30 for stepper_a, 150 for stepper_b, and 270 for # stepper_c. # The stepper_b section describes the stepper controlling the rear # left arm (at 150 degrees). [stepper_b] # The stepper_c section describes the stepper controlling the front # arm (at 270 degrees). [stepper_c] # The delta_calibrate section enables a DELTA_CALIBRATE extended # g-code command that can calibrate the shoulder endstop positions. [delta_calibrate] radius: # Radius (in mm) of the area that may be probed. This is the radius # of nozzle coordinates to be probed; if using an automatic probe # with an XY offset then choose a radius small enough so that the # probe always fits over the bed. This parameter must be provided. #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.","title":"Rotary delta Kinematics"},{"location":"Config_Reference.html#cable-winch-kinematics","text":"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.","title":"Cable winch Kinematics"},{"location":"Config_Reference.html#generic-cartesian-kinematics","text":"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 the following three carriages: [carriage x] , [carriage y] , and [carriage z] , e.g. [carriage x] endstop_pin: # Endstop switch detection pin. If this endstop pin is on a # different mcu than the stepper motor(s) moving this carriage, # then it enables \"multi-mcu homing\". This parameter must be provided. #position_min: 0 # Minimum valid distance (in mm) the user may command the carriage to # move to. The default is 0mm. position_endstop: # Location of the endstop (in mm). This parameter must be provided. position_max: # Maximum valid distance (in mm) the user may command the stepper to # move to. This parameter must be provided. #homing_speed: 5.0 # Maximum velocity (in mm/s) of the carriage when homing. The default # is 5mm/s. #homing_retract_dist: 5.0 # Distance to backoff (in mm) before homing a second time during # homing. Set this to zero to disable the second home. The default # is 5mm. #homing_retract_speed: # Speed to use on the retract move after homing in case this should # be different from the homing speed, which is the default for this # parameter #second_homing_speed: # Velocity (in mm/s) of the carriage when performing the second home. # The default is homing_speed/2. #homing_positive_dir: # If true, homing will cause the carriage to move in a positive # direction (away from zero); if false, home towards zero. It is # better to use the default than to specify this parameter. The # default is true if position_endstop is near position_max and false # if near position_min. 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. x, x+y, y-0.5*z, x-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, x+y indicates that the motion of the stepper in the positive direction by the distance d moves the carriages x and y by the same distance d in the positive direction, while x-0.5*y means the motion of the stepper in the positive direction by the distance d moves the carriage x by the distance d in the positive direction, but the 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 x] endstop_pin: ... ... [carriage y] endstop_pin: ... ... [stepper a0] carriages: x-y step_pin: ... dir_pin: ... enable_pin: ... rotation_distance: ... ... [stepper a1] carriages: x-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 beam, 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 y1] primary_carriage: y endstop_pin: ... [stepper sy1] carriages: 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.","title":"Generic Cartesian Kinematics"},{"location":"Config_Reference.html#none-kinematics","text":"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.","title":"None Kinematics"},{"location":"Config_Reference.html#common-extruder-and-heated-bed-support","text":"","title":"Common extruder and heated bed support"},{"location":"Config_Reference.html#extruder","text":"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. [extruder] step_pin: dir_pin: enable_pin: microsteps: rotation_distance: #full_steps_per_rotation: #gear_ratio: # See the \"stepper\" section for a description of the above # parameters. If none of the above parameters are specified then no # stepper will be associated with the nozzle hotend (though a # SYNC_EXTRUDER_MOTION command may associate one at run-time). nozzle_diameter: # Diameter of the nozzle orifice (in mm). This parameter must be # provided. filament_diameter: # The nominal diameter of the raw filament (in mm) as it enters the # extruder. This parameter must be provided. #max_extrude_cross_section: # Maximum area (in mm^2) of an extrusion cross section (eg, # extrusion width multiplied by layer height). This setting prevents # excessive amounts of extrusion during relatively small XY moves. # If a move requests an extrusion rate that would exceed this value # it will cause an error to be returned. The default is: 4.0 * # nozzle_diameter^2 #instantaneous_corner_velocity: 1.000 # The maximum instantaneous velocity change (in mm/s) of the # extruder during the junction of two moves. The default is 1mm/s. #max_extrude_only_distance: 50.0 # Maximum length (in mm of raw filament) that a retraction or # extrude-only move may have. If a retraction or extrude-only move # requests a distance greater than this value it will cause an error # to be returned. The default is 50mm. #max_extrude_only_velocity: #max_extrude_only_accel: # Maximum velocity (in mm/s) and acceleration (in mm/s^2) of the # extruder motor for retractions and extrude-only moves. These # settings do not have any impact on normal printing moves. If not # specified then they are calculated to match the limit an XY # printing move with a cross section of 4.0*nozzle_diameter^2 would # have. #pressure_advance: 0.0 # The amount of raw filament to push into the extruder during # extruder acceleration. An equal amount of filament is retracted # during deceleration. It is measured in millimeters per # millimeter/second. The default is 0, which disables pressure # advance. #pressure_advance_smooth_time: 0.040 # A time range (in seconds) to use when calculating the average # extruder velocity for pressure advance. A larger value results in # smoother extruder movements. This parameter may not exceed 200ms. # This setting only applies if pressure_advance is non-zero. The # default is 0.040 (40 milliseconds). # # The remaining variables describe the extruder heater. heater_pin: # PWM output pin controlling the heater. This parameter must be # provided. #max_power: 1.0 # The maximum power (expressed as a value from 0.0 to 1.0) that the # heater_pin may be set to. The value 1.0 allows the pin to be set # fully enabled for extended periods, while a value of 0.5 would # allow the pin to be enabled for no more than half the time. This # setting may be used to limit the total power output (over extended # periods) to the heater. The default is 1.0. sensor_type: # Type of sensor - common thermistors are \"EPCOS 100K B57560G104F\", # \"ATC Semitec 104GT-2\", \"ATC Semitec 104NT-4-R025H42G\", \"Generic # 3950\",\"Honeywell 100K 135-104LAG-J01\", \"NTC 100K MGB18-104F39050L32\", # \"SliceEngineering 450\", and \"TDK NTCG104LH104JT1\". See the # \"Temperature sensors\" section for other sensors. This parameter # must be provided. sensor_pin: # Analog input pin connected to the sensor. This parameter must be # provided. #pullup_resistor: 4700 # The resistance (in ohms) of the pullup attached to the thermistor. # This parameter is only valid when the sensor is a thermistor. The # default is 4700 ohms. #smooth_time: 1.0 # A time value (in seconds) over which temperature measurements will # be smoothed to reduce the impact of measurement noise. The default # is 1 seconds. control: # Control algorithm (either pid or watermark). This parameter must # be provided. pid_Kp: pid_Ki: pid_Kd: # The proportional (pid_Kp), integral (pid_Ki), and derivative # (pid_Kd) settings for the PID feedback control system. Klipper # evaluates the PID settings with the following general formula: # heater_pwm = (Kp*error + Ki*integral(error) - Kd*derivative(error)) / 255 # Where \"error\" is \"requested_temperature - measured_temperature\" # and \"heater_pwm\" is the requested heating rate with 0.0 being full # off and 1.0 being full on. Consider using the PID_CALIBRATE # command to obtain these parameters. The pid_Kp, pid_Ki, and pid_Kd # parameters must be provided for PID heaters. #max_delta: 2.0 # On 'watermark' controlled heaters this is the number of degrees in # Celsius above the target temperature before disabling the heater # as well as the number of degrees below the target before # re-enabling the heater. The default is 2 degrees Celsius. #pwm_cycle_time: 0.100 # Time in seconds for each software PWM cycle of the heater. It is # not recommended to set this unless there is an electrical # requirement to switch the heater faster than 10 times a second. # The default is 0.100 seconds. #min_extrude_temp: 170 # The minimum temperature (in Celsius) at which extruder move # commands may be issued. The default is 170 Celsius. min_temp: max_temp: # The maximum range of valid temperatures (in Celsius) that the # heater must remain within. This controls a safety feature # implemented in the micro-controller code - should the measured # temperature ever fall outside this range then the micro-controller # will go into a shutdown state. This check can help detect some # heater and sensor hardware failures. Set this range just wide # enough so that reasonable temperatures do not result in an error. # These parameters must be provided.","title":"[extruder]"},{"location":"Config_Reference.html#heater_bed","text":"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.","title":"[heater_bed]"},{"location":"Config_Reference.html#bed-level-support","text":"","title":"Bed level support"},{"location":"Config_Reference.html#bed_mesh","text":"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 [bed_mesh] #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. #mesh_radius: # Defines the radius of the mesh to probe for round beds. Note that # the radius is relative to the coordinate specified by the # mesh_origin option. This parameter must be provided for round beds # and omitted for rectangular beds. #mesh_origin: # Defines the center X, Y coordinate of the mesh for round beds. This # coordinate is relative to the probe's location. It may be useful # to adjust the mesh_origin in an effort to maximize the size of the # mesh radius. Default is 0, 0. This parameter must be omitted for # rectangular beds. #mesh_min: # Defines the minimum X, Y coordinate of the mesh for rectangular # beds. This coordinate is relative to the probe's location. This # will be the first point probed, nearest to the origin. This # parameter must be provided for rectangular beds. #mesh_max: # Defines the maximum X, Y coordinate of the mesh for rectangular # beds. Adheres to the same principle as mesh_min, however this will # be the furthest point probed from the bed's origin. This parameter # must be provided for rectangular beds. #probe_count: 3, 3 # For rectangular beds, this is a comma separate pair of integer # values X, Y defining the number of points to probe along each # axis. A single value is also valid, in which case that value will # be applied to both axes. Default is 3, 3. #round_probe_count: 5 # For round beds, this integer value defines the maximum number of # points to probe along each axis. This value must be an odd number. # Default is 5. #fade_start: 1.0 # The gcode z position in which to start phasing out z-adjustment # when fade is enabled. Default is 1.0. #fade_end: 0.0 # The gcode z position in which phasing out completes. When set to a # value below fade_start, fade is disabled. It should be noted that # fade may add unwanted scaling along the z-axis of a print. If a # user wishes to enable fade, a value of 10.0 is recommended. # Default is 0.0, which disables fade. #fade_target: # The z position in which fade should converge. When this value is # set to a non-zero value it must be within the range of z-values in # the mesh. Users that wish to converge to the z homing position # should set this to 0. Default is the average z value of the mesh. #split_delta_z: .025 # The amount of Z difference (in mm) along a move that will trigger # a split. Default is .025. #move_check_distance: 5.0 # The distance (in mm) along a move to check for split_delta_z. # This is also the minimum length that a move can be split. Default # is 5.0. #mesh_pps: 2, 2 # A comma separated pair of integers X, Y defining the number of # points per segment to interpolate in the mesh along each axis. A # \"segment\" can be defined as the space between each probed point. # The user may enter a single value which will be applied to both # axes. Default is 2, 2. #algorithm: lagrange # The interpolation algorithm to use. May be either \"lagrange\" or # \"bicubic\". This option will not affect 3x3 grids, which are forced # to use lagrange sampling. Default is lagrange. #bicubic_tension: .2 # When using the bicubic algorithm the tension parameter above may # be applied to change the amount of slope interpolated. Larger # numbers will increase the amount of slope, which results in more # curvature in the mesh. Default is .2. #zero_reference_position: # An optional X,Y coordinate that specifies the location on the bed # where Z = 0. When this option is specified the mesh will be offset # so that zero Z adjustment occurs at this location. The default is # no zero reference. #faulty_region_1_min: #faulty_region_1_max: # Optional points that define a faulty region. See docs/Bed_Mesh.md # for details on faulty regions. Up to 99 faulty regions may be added. # By default no faulty regions are set. #adaptive_margin: # An optional margin (in mm) to be added around the bed area used by # the defined print objects when generating an adaptive mesh. #scan_overshoot: # 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.","title":"[bed_mesh]"},{"location":"Config_Reference.html#bed_tilt","text":"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.","title":"[bed_tilt]"},{"location":"Config_Reference.html#bed_screws","text":"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.","title":"[bed_screws]"},{"location":"Config_Reference.html#screws_tilt_adjust","text":"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.","title":"[screws_tilt_adjust]"},{"location":"Config_Reference.html#z_tilt","text":"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. [z_tilt] #z_positions: # A list of X, Y coordinates (one per line; subsequent lines # indented) describing the location of each bed \"pivot point\". The # \"pivot point\" is the point where the bed attaches to the given Z # stepper. It is described using nozzle coordinates (the X, Y position # of the nozzle if it could move directly above the point). The # first entry corresponds to stepper_z, the second to stepper_z1, # the third to stepper_z2, etc. This parameter must be provided. #points: # A list of X, Y coordinates (one per line; subsequent lines # indented) that should be probed during a Z_TILT_ADJUST command. # Specify coordinates of the nozzle and be sure the probe is above # the bed at the given nozzle coordinates. This parameter must be # provided. #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. #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. Note the smallest unit of # change here would be a single step. However if you are probing # more points than steppers then you will likely have a fixed # minimum value for the range of probed points which you can learn # by observing command output.","title":"[z_tilt]"},{"location":"Config_Reference.html#quad_gantry_level","text":"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.","title":"[quad_gantry_level]"},{"location":"Config_Reference.html#skew_correction","text":"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]","title":"[skew_correction]"},{"location":"Config_Reference.html#z_thermal_adjust","text":"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.","title":"[z_thermal_adjust]"},{"location":"Config_Reference.html#customized-homing","text":"","title":"Customized homing"},{"location":"Config_Reference.html#safe_z_home","text":"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.","title":"[safe_z_home]"},{"location":"Config_Reference.html#homing_override","text":"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.","title":"[homing_override]"},{"location":"Config_Reference.html#endstop_phase","text":"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.","title":"[endstop_phase]"},{"location":"Config_Reference.html#g-code-macros-and-events","text":"","title":"G-Code macros and events"},{"location":"Config_Reference.html#gcode_macro","text":"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\"","title":"[gcode_macro]"},{"location":"Config_Reference.html#delayed_gcode","text":"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.","title":"[delayed_gcode]"},{"location":"Config_Reference.html#save_variables","text":"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","title":"[save_variables]"},{"location":"Config_Reference.html#idle_timeout","text":"Idle timeout. An idle timeout is automatically enabled - add an explicit idle_timeout config section to change the default settings. [idle_timeout] #gcode: # A list of G-Code commands to execute on an idle timeout. See # docs/Command_Templates.md for G-Code format. The default is to run # \"TURN_OFF_HEATERS\" and \"M84\". #timeout: 600 # Idle time (in seconds) to wait before running the above G-Code # commands. The default is 600 seconds.","title":"[idle_timeout]"},{"location":"Config_Reference.html#optional-g-code-features","text":"","title":"Optional G-Code features"},{"location":"Config_Reference.html#virtual_sdcard","text":"A virtual sdcard may be useful if the host machine is not fast enough to run OctoPrint well. It allows the Klipper host software to directly print gcode files stored in a directory on the host using standard sdcard G-Code commands (eg, M24). [virtual_sdcard] path: # The path of the local directory on the host machine to look for # g-code files. This is a read-only directory (sdcard file writes # are not supported). One may point this to OctoPrint's upload # directory (generally ~/.octoprint/uploads/ ). This parameter must # be provided. #on_error_gcode: # A list of G-Code commands to execute when an error is reported. # See docs/Command_Templates.md for G-Code format. The default is to # run TURN_OFF_HEATERS.","title":"[virtual_sdcard]"},{"location":"Config_Reference.html#sdcard_loop","text":"Some printers with stage-clearing features, such as a part ejector or a belt printer, can find use in looping sections of the sdcard file. (For example, to print the same part over and over, or repeat the a section of a part for a chain or other repeated pattern). See the command reference for supported commands. See the sample-macros.cfg file for a Marlin compatible M808 G-Code macro. [sdcard_loop]","title":"[sdcard_loop]"},{"location":"Config_Reference.html#force_move","text":"Support manually moving stepper motors for diagnostic purposes. Note, using this feature may place the printer in an invalid state - see the command reference for important details. [force_move] #enable_force_move: False # Set to true to enable FORCE_MOVE and SET_KINEMATIC_POSITION # extended G-Code commands. The default is false.","title":"[force_move]"},{"location":"Config_Reference.html#pause_resume","text":"Pause/Resume functionality with support of position capture and restore. See the command reference for more information. [pause_resume] #recover_velocity: 50. # When capture/restore is enabled, the speed at which to return to # the captured position (in mm/s). Default is 50.0 mm/s.","title":"[pause_resume]"},{"location":"Config_Reference.html#firmware_retraction","text":"Firmware filament retraction. This enables G10 (retract) and G11 (unretract) GCODE commands issued by many slicers. The parameters below provide startup defaults, although the values can be adjusted via the SET_RETRACTION command ), allowing per-filament settings and runtime tuning. [firmware_retraction] #retract_length: 0 # The length of filament (in mm) to retract when G10 is activated, # and to unretract when G11 is activated (but see # unretract_extra_length below). The default is 0 mm. #retract_speed: 20 # The speed of retraction, in mm/s. The default is 20 mm/s. #unretract_extra_length: 0 # The length (in mm) of *additional* filament to add when # unretracting. #unretract_speed: 10 # The speed of unretraction, in mm/s. The default is 10 mm/s.","title":"[firmware_retraction]"},{"location":"Config_Reference.html#gcode_arcs","text":"Support for gcode arc (G2/G3) commands. [gcode_arcs] #resolution: 1.0 # An arc will be split into segments. Each segment's length will # equal the resolution in mm set above. Lower values will produce a # finer arc, but also more work for your machine. Arcs smaller than # the configured value will become straight lines. The default is # 1mm.","title":"[gcode_arcs]"},{"location":"Config_Reference.html#respond","text":"Enable the \"M118\" and \"RESPOND\" extended commands . [respond] #default_type: echo # Sets the default prefix of the \"M118\" and \"RESPOND\" output to one # of the following: # echo: \"echo: \" (This is the default) # command: \"// \" # error: \"!! \" #default_prefix: echo: # Directly sets the default prefix. If present, this value will # override the \"default_type\".","title":"[respond]"},{"location":"Config_Reference.html#exclude_object","text":"Enables support to exclude or cancel individual objects during the printing process. See the exclude objects guide and command reference for additional information. See the sample-macros.cfg file for a Marlin/RepRapFirmware compatible M486 G-Code macro. [exclude_object]","title":"[exclude_object]"},{"location":"Config_Reference.html#resonance-compensation","text":"","title":"Resonance compensation"},{"location":"Config_Reference.html#input_shaper","text":"Enables resonance compensation . Also see the command reference . [input_shaper] #shaper_freq_x: 0 # A frequency (in Hz) of the input shaper for X axis. This is # usually a resonance frequency of X axis that the input shaper # should suppress. For more complex shapers, like 2- and 3-hump EI # input shapers, this parameter can be set from different # considerations. The default value is 0, which disables input # shaping for X axis. #shaper_freq_y: 0 # A frequency (in Hz) of the input shaper for Y axis. This is # usually a resonance frequency of Y axis that the input shaper # should suppress. For more complex shapers, like 2- and 3-hump EI # input shapers, this parameter can be set from different # considerations. The default value is 0, which disables input # shaping for Y axis. #shaper_type: mzv # A type of the input shaper to use for both X and Y axes. Supported # shapers are zv, mzv, zvd, ei, 2hump_ei, and 3hump_ei. The default # is mzv input shaper. #shaper_type_x: #shaper_type_y: # If shaper_type is not set, these two parameters can be used to # configure different input shapers for X and Y axes. The same # values are supported as for shaper_type parameter. #damping_ratio_x: 0.1 #damping_ratio_y: 0.1 # Damping ratios of vibrations of X and Y axes used by input shapers # to improve vibration suppression. Default value is 0.1 which is a # good all-round value for most printers. In most circumstances this # parameter requires no tuning and should not be changed.","title":"[input_shaper]"},{"location":"Config_Reference.html#adxl345","text":"Support for ADXL345 accelerometers. This support allows one to query accelerometer measurements from the sensor. This enables an ACCELEROMETER_MEASURE command (see G-Codes for more information). The default chip name is \"default\", but one may specify an explicit name (eg, [adxl345 my_chip_name]). [adxl345] cs_pin: # The SPI enable pin for the sensor. This parameter must be provided. #spi_speed: 5000000 # The SPI speed (in hz) to use when communicating with the chip. # The default is 5000000. #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #axes_map: x, y, z # The accelerometer axis for each of the printer's X, Y, and Z axes. # This may be useful if the accelerometer is mounted in an # orientation that does not match the printer orientation. For # example, one could set this to \"y, x, z\" to swap the X and Y axes. # It is also possible to negate an axis if the accelerometer # direction is reversed (eg, \"x, z, -y\"). The default is \"x, y, z\". #rate: 3200 # Output data rate for ADXL345. ADXL345 supports the following data # rates: 3200, 1600, 800, 400, 200, 100, 50, and 25. Note that it is # not recommended to change this rate from the default 3200, and # rates below 800 will considerably affect the quality of resonance # measurements.","title":"[adxl345]"},{"location":"Config_Reference.html#icm20948","text":"Support for icm20948 accelerometers. [icm20948] #i2c_address: # Default is 104 (0x68). If AD0 is high, it would be 0x69 instead. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: 400000 # See the \"common I2C settings\" section for a description of the # above parameters. The default \"i2c_speed\" is 400000. #axes_map: x, y, z # See the \"adxl345\" section for information on this parameter.","title":"[icm20948]"},{"location":"Config_Reference.html#lis2dw","text":"Support for LIS2DW accelerometers. [lis2dw] #cs_pin: # The SPI enable pin for the sensor. This parameter must be provided # if using SPI. #spi_speed: 5000000 # The SPI speed (in hz) to use when communicating with the chip. # The default is 5000000. #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #i2c_address: # Default is 25 (0x19). If SA0 is high, it would be 24 (0x18) instead. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: 400000 # See the \"common I2C settings\" section for a description of the # above parameters. The default \"i2c_speed\" is 400000. #axes_map: x, y, z # See the \"adxl345\" section for information on this parameter.","title":"[lis2dw]"},{"location":"Config_Reference.html#lis3dh","text":"Support for LIS3DH accelerometers. [lis3dh] #cs_pin: # The SPI enable pin for the sensor. This parameter must be provided # if using SPI. #spi_speed: 5000000 # The SPI speed (in hz) to use when communicating with the chip. # The default is 5000000. #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #i2c_address: # Default is 25 (0x19). If SA0 is high, it would be 24 (0x18) instead. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: 400000 # See the \"common I2C settings\" section for a description of the # above parameters. The default \"i2c_speed\" is 400000. #axes_map: x, y, z # See the \"adxl345\" section for information on this parameter.","title":"[lis3dh]"},{"location":"Config_Reference.html#mpu9250","text":"Support for MPU-9250, MPU-9255, MPU-6515, MPU-6050, and MPU-6500 accelerometers (one may define any number of sections with an \"mpu9250\" prefix). [mpu9250 my_accelerometer] #i2c_address: # Default is 104 (0x68). If AD0 is high, it would be 0x69 instead. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: 400000 # See the \"common I2C settings\" section for a description of the # above parameters. The default \"i2c_speed\" is 400000. #axes_map: x, y, z # See the \"adxl345\" section for information on this parameter.","title":"[mpu9250]"},{"location":"Config_Reference.html#resonance_tester","text":"Support for resonance testing and automatic input shaper calibration. In order to use most of the functionality of this module, additional software dependencies must be installed; refer to Measuring Resonances and the command reference for more information. See the Max smoothing section of the measuring resonances guide for more information on max_smoothing parameter and its use. [resonance_tester] #probe_points: # A list of X, Y, Z coordinates of points (one point per line) to test # resonances at. At least one point is required. Make sure that all # points with some safety margin in XY plane (~a few centimeters) # are reachable by the toolhead. #accel_chip: # A name of the accelerometer chip to use for measurements. If # adxl345 chip was defined without an explicit name, this parameter # can simply reference it as \"accel_chip: adxl345\", otherwise an # explicit name must be supplied as well, e.g. \"accel_chip: adxl345 # my_chip_name\". Either this, or the next two parameters must be # set. #accel_chip_x: #accel_chip_y: # Names of the accelerometer chips to use for measurements for each # of the axis. Can be useful, for instance, on bed slinger printer, # if two separate accelerometers are mounted on the bed (for Y axis) # and on the toolhead (for X axis). These parameters have the same # format as 'accel_chip' parameter. Only 'accel_chip' or these two # parameters must be provided. #max_smoothing: # Maximum input shaper smoothing to allow for each axis during shaper # auto-calibration (with 'SHAPER_CALIBRATE' command). By default no # maximum smoothing is specified. Refer to Measuring_Resonances guide # for more details on using this feature. #move_speed: 50 # The speed (in mm/s) to move the toolhead to and between test points # during the calibration. The default is 50. #min_freq: 5 # Minimum frequency to test for resonances. The default is 5 Hz. #max_freq: 133.33 # Maximum frequency to test for resonances. The default is 133.33 Hz. #accel_per_hz: 60 # This parameter is used to determine which acceleration to use to # test a specific frequency: accel = accel_per_hz * freq. Higher the # value, the higher is the energy of the oscillations. Can be set to # a lower than the default value if the resonances get too strong on # the printer. However, lower values make measurements of # high-frequency resonances less precise. The default value is 75 # (mm/sec). #hz_per_sec: 1 # Determines the speed of the test. When testing all frequencies in # range [min_freq, max_freq], each second the frequency increases by # hz_per_sec. Small values make the test slow, and the large values # will decrease the precision of the test. The default value is 1.0 # (Hz/sec == sec^-2). #sweeping_accel: 400 # An acceleration of slow sweeping moves. The default is 400 mm/sec^2. #sweeping_period: 1.2 # A period of slow sweeping moves. Setting this parameter to 0 # disables slow sweeping moves. Avoid setting it to a too small # non-zero value in order to not poison the measurements. # The default is 1.2 sec which is a good all-round choice.","title":"[resonance_tester]"},{"location":"Config_Reference.html#config-file-helpers","text":"","title":"Config file helpers"},{"location":"Config_Reference.html#board_pins","text":"Board pin aliases (one may define any number of sections with a \"board_pins\" prefix). Use this to define aliases for the pins on a micro-controller. [board_pins my_aliases] mcu: mcu # A comma separated list of micro-controllers that may use the # aliases. The default is to apply the aliases to the main \"mcu\". aliases: aliases_<name>: # A comma separated list of \"name=value\" aliases to create for the # given micro-controller. For example, \"EXP1_1=PE6\" would create an # \"EXP1_1\" alias for the \"PE6\" pin. However, if \"value\" is enclosed # in \"<>\" then \"name\" is created as a reserved pin (for example, # \"EXP1_9=<GND>\" would reserve \"EXP1_9\"). Any number of options # starting with \"aliases_\" may be specified.","title":"[board_pins]"},{"location":"Config_Reference.html#include","text":"Include file support. One may include additional config file from the main printer config file. Wildcards may also be used (eg, \"configs/*.cfg\"). [include my_other_config.cfg]","title":"[include]"},{"location":"Config_Reference.html#duplicate_pin_override","text":"This tool allows a single micro-controller pin to be defined multiple times in a config file without normal error checking. This is intended for diagnostic and debugging purposes. This section is not needed where Klipper supports using the same pin multiple times, and using this override may cause confusing and unexpected results. [duplicate_pin_override] pins: # A comma separated list of pins that may be used multiple times in # a config file without normal error checks. This parameter must be # provided.","title":"[duplicate_pin_override]"},{"location":"Config_Reference.html#bed-probing-hardware","text":"","title":"Bed probing hardware"},{"location":"Config_Reference.html#probe","text":"Z height probe. One may define this section to enable Z height probing hardware. When this section is enabled, PROBE and QUERY_PROBE extended g-code commands become available. Also, see the probe calibrate guide . The probe section also creates a virtual \"probe:z_virtual_endstop\" pin. One may set the stepper_z endstop_pin to this virtual pin on cartesian style printers that use the probe in place of a z endstop. If using \"probe:z_virtual_endstop\" then do not define a position_endstop in the stepper_z config section. [probe] pin: # Probe detection pin. If the pin is on a different microcontroller # than the Z steppers then it enables \"multi-mcu homing\". This # parameter must be provided. #deactivate_on_each_sample: True # This determines if Klipper should execute deactivation gcode # between each probe attempt when performing a multiple probe # sequence. The default is True. #x_offset: 0.0 # The distance (in mm) between the probe and the nozzle along the # x-axis. The default is 0. #y_offset: 0.0 # The distance (in mm) between the probe and the nozzle along the # y-axis. The default is 0. z_offset: # The distance (in mm) between the bed and the nozzle when the probe # triggers. This parameter must be provided. #speed: 5.0 # Speed (in mm/s) of the Z axis when probing. The default is 5mm/s. #samples: 1 # The number of times to probe each point. The probed z-values will # be averaged. The default is to probe 1 time. #sample_retract_dist: 2.0 # The distance (in mm) to lift the toolhead between each sample (if # sampling more than once). The default is 2mm. #lift_speed: # Speed (in mm/s) of the Z axis when lifting the probe between # samples. The default is to use the same value as the 'speed' # parameter. #samples_result: average # The calculation method when sampling more than once - either # \"median\" or \"average\". The default is average. #samples_tolerance: 0.100 # The maximum Z distance (in mm) that a sample may differ from other # samples. If this tolerance is exceeded then either an error is # reported or the attempt is restarted (see # samples_tolerance_retries). The default is 0.100mm. #samples_tolerance_retries: 0 # The number of times to retry if a sample is found that exceeds # samples_tolerance. On a retry, all current samples are discarded # and the probe attempt is restarted. If a valid set of samples are # not obtained in the given number of retries then an error is # reported. The default is zero which causes an error to be reported # on the first sample that exceeds samples_tolerance. #activate_gcode: # A list of G-Code commands to execute prior to each probe attempt. # See docs/Command_Templates.md for G-Code format. This may be # useful if the probe needs to be activated in some way. Do not # issue any commands here that move the toolhead (eg, G1). The # default is to not run any special G-Code commands on activation. #deactivate_gcode: # A list of G-Code commands to execute after each probe attempt # completes. See docs/Command_Templates.md for G-Code format. Do not # issue any commands here that move the toolhead. The default is to # not run any special G-Code commands on deactivation.","title":"[probe]"},{"location":"Config_Reference.html#bltouch","text":"BLTouch probe. One may define this section (instead of a probe section) to enable a BLTouch probe. See BL-Touch guide and command reference for further information. A virtual \"probe:z_virtual_endstop\" pin is also created (see the \"probe\" section for the details). [bltouch] sensor_pin: # Pin connected to the BLTouch sensor pin. Most BLTouch devices # require a pullup on the sensor pin (prefix the pin name with \"^\"). # This parameter must be provided. control_pin: # Pin connected to the BLTouch control pin. This parameter must be # provided. #pin_move_time: 0.680 # The amount of time (in seconds) to wait for the BLTouch pin to # move up or down. The default is 0.680 seconds. #stow_on_each_sample: True # This determines if Klipper should command the pin to move up # between each probe attempt when performing a multiple probe # sequence. Read the directions in docs/BLTouch.md before setting # this to False. The default is True. #probe_with_touch_mode: False # If this is set to True then Klipper will probe with the device in # \"touch_mode\". The default is False (probing in \"pin_down\" mode). #pin_up_reports_not_triggered: True # Set if the BLTouch consistently reports the probe in a \"not # triggered\" state after a successful \"pin_up\" command. This should # be True for all genuine BLTouch devices. Read the directions in # docs/BLTouch.md before setting this to False. The default is True. #pin_up_touch_mode_reports_triggered: True # Set if the BLTouch consistently reports a \"triggered\" state after # the commands \"pin_up\" followed by \"touch_mode\". This should be # True for all genuine BLTouch devices. Read the directions in # docs/BLTouch.md before setting this to False. The default is True. #set_output_mode: # Request a specific sensor pin output mode on the BLTouch V3.0 (and # later). This setting should not be used on other types of probes. # Set to \"5V\" to request a sensor pin output of 5 Volts (only use if # the controller board needs 5V mode and is 5V tolerant on its input # signal line). Set to \"OD\" to request the sensor pin output use # open drain mode. The default is to not request an output mode. #x_offset: #y_offset: #z_offset: #speed: #lift_speed: #samples: #sample_retract_dist: #samples_result: #samples_tolerance: #samples_tolerance_retries: # See the \"probe\" section for information on these parameters.","title":"[bltouch]"},{"location":"Config_Reference.html#smart_effector","text":"The \"Smart Effector\" from Duet3d implements a Z probe using a force sensor. One may define this section instead of [probe] to enable the Smart Effector specific features. This also enables runtime commands to adjust the parameters of the Smart Effector at run time. [smart_effector] pin: # Pin connected to the Smart Effector Z Probe output pin (pin 5). Note that # pullup resistor on the board is generally not required. However, if the # output pin is connected to the board pin with a pullup resistor, that # resistor must be high value (e.g. 10K Ohm or more). Some boards have a low # value pullup resistor on the Z probe input, which will likely result in an # always-triggered probe state. In this case, connect the Smart Effector to # a different pin on the board. This parameter is required. #control_pin: # Pin connected to the Smart Effector control input pin (pin 7). If provided, # Smart Effector sensitivity programming commands become available. #probe_accel: # If set, limits the acceleration of the probing moves (in mm/sec^2). # A sudden large acceleration at the beginning of the probing move may # cause spurious probe triggering, especially if the hotend is heavy. # To prevent that, it may be necessary to reduce the acceleration of # the probing moves via this parameter. #recovery_time: 0.4 # A delay between the travel moves and the probing moves in seconds. A fast # travel move prior to probing may result in a spurious probe triggering. # This may cause 'Probe triggered prior to movement' errors if no delay # is set. Value 0 disables the recovery delay. # Default value is 0.4. #x_offset: #y_offset: # Should be left unset (or set to 0). z_offset: # Trigger height of the probe. Start with -0.1 (mm), and adjust later using # `PROBE_CALIBRATE` command. This parameter must be provided. #speed: # Speed (in mm/s) of the Z axis when probing. It is recommended to start # with the probing speed of 20 mm/s and adjust it as necessary to improve # the accuracy and repeatability of the probe triggering. #samples: #sample_retract_dist: #samples_result: #samples_tolerance: #samples_tolerance_retries: #activate_gcode: #deactivate_gcode: #deactivate_on_each_sample: # See the \"probe\" section for more information on the parameters above.","title":"[smart_effector]"},{"location":"Config_Reference.html#probe_eddy_current","text":"Support for eddy current inductive probes. One may define this section (instead of a probe section) to enable this probe. See the command reference for further information. [probe_eddy_current my_eddy_probe] sensor_type: ldc1612 # The sensor chip used to perform eddy current measurements. This # parameter must be provided and must be set to ldc1612. #frequency: # The external crystal frequency (in Hz) of the LDC1612 chip. # The default is 12000000. #intb_pin: # MCU gpio pin connected to the ldc1612 sensor's INTB pin (if # available). The default is to not use the INTB pin. #z_offset: # The nominal distance (in mm) between the nozzle and bed that a # probing attempt should stop at. This parameter must be provided. #i2c_address: #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # The i2c settings for the sensor chip. See the \"common I2C # settings\" section for a description of the above parameters. #x_offset: #y_offset: #speed: #lift_speed: #samples: #sample_retract_dist: #samples_result: #samples_tolerance: #samples_tolerance_retries: # See the \"probe\" section for information on these parameters.","title":"[probe_eddy_current]"},{"location":"Config_Reference.html#axis_twist_compensation","text":"A tool to compensate for inaccurate probe readings due to twist in X or Y gantry. See the Axis Twist Compensation Guide for more detailed information regarding symptoms, configuration and setup. [axis_twist_compensation] #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. calibrate_start_x: 20 # Defines the minimum X coordinate of the calibration # This should be the X coordinate that positions the nozzle at the starting # calibration position. calibrate_end_x: 200 # Defines the maximum X coordinate of the calibration # This should be the X coordinate that positions the nozzle at the ending # calibration position. calibrate_y: 112.5 # Defines the Y coordinate of the calibration # This should be the Y coordinate that positions the nozzle during the # calibration process. This parameter is recommended to # be near the center of the bed # For Y-axis twist compensation, specify the following parameters: calibrate_start_y: ... # Defines the minimum Y coordinate of the calibration # This should be the Y coordinate that positions the nozzle at the starting # calibration position for the Y axis. This parameter must be provided if # compensating for Y axis twist. calibrate_end_y: ... # Defines the maximum Y coordinate of the calibration # This should be the Y coordinate that positions the nozzle at the ending # calibration position for the Y axis. This parameter must be provided if # compensating for Y axis twist. calibrate_x: ... # Defines the X coordinate of the calibration for Y axis twist compensation # This should be the X coordinate that positions the nozzle during the # calibration process for Y axis twist compensation. This parameter must be # provided and is recommended to be near the center of the bed.","title":"[axis_twist_compensation]"},{"location":"Config_Reference.html#additional-stepper-motors-and-extruders","text":"","title":"Additional stepper motors and extruders"},{"location":"Config_Reference.html#stepper_z1","text":"Multi-stepper axes. On a cartesian style printer, the stepper controlling a given axis may have additional config blocks defining steppers that should be stepped in concert with the primary stepper. One may define any number of sections with a numeric suffix starting at 1 (for example, \"stepper_z1\", \"stepper_z2\", etc.). [stepper_z1] #step_pin: #dir_pin: #enable_pin: #microsteps: #rotation_distance: # See the \"stepper\" section for the definition of the above parameters. #endstop_pin: # If an endstop_pin is defined for the additional stepper then the # stepper will home until the endstop is triggered. Otherwise, the # stepper will home until the endstop on the primary stepper for the # axis is triggered.","title":"[stepper_z1]"},{"location":"Config_Reference.html#extruder1","text":"In a multi-extruder printer add an additional extruder section for each additional extruder. The additional extruder sections should be named \"extruder1\", \"extruder2\", \"extruder3\", and so on. See the \"extruder\" section for a description of available parameters. See sample-multi-extruder.cfg for an example configuration. [extruder1] #step_pin: #dir_pin: #... # See the \"extruder\" section for available stepper and heater # parameters. #shared_heater: # This option is deprecated and should no longer be specified.","title":"[extruder1]"},{"location":"Config_Reference.html#dual_carriage","text":"Support for cartesian, generic_cartesian and hybrid_corexy/z printers with dual carriages on a single axis. The carriage mode can be set via the SET_DUAL_CARRIAGE extended g-code command. For example, \"SET_DUAL_CARRIAGE CARRIAGE=1\" command will activate the carriage defined in this section (CARRIAGE=0 will return activation to the primary carriage). Dual carriage support is typically combined with extra extruders - the SET_DUAL_CARRIAGE command is often called at the same time as the ACTIVATE_EXTRUDER command. Be sure to park the carriages during deactivation. Note that during G28 homing, typically the primary carriage is homed first followed by the carriage defined in the [dual_carriage] config section. However, the [dual_carriage] carriage will be homed first if both carriages home in a positive direction and the [dual_carriage] carriage has a position_endstop greater than the primary carriage, or if both carriages home in a negative direction and the [dual_carriage] carriage has a position_endstop less than the primary carriage. Additionally, one could use \"SET_DUAL_CARRIAGE CARRIAGE=1 MODE=COPY\" or \"SET_DUAL_CARRIAGE CARRIAGE=1 MODE=MIRROR\" commands to activate either copying or mirroring mode of the dual carriage, in which case it will follow the motion of the carriage 0 accordingly. These commands can be used to print two parts simultaneously - either two identical parts (in COPY mode) or mirrored parts (in MIRROR mode). Note that COPY and MIRROR modes also require appropriate configuration of the extruder on the dual carriage, which can typically be achieved with \"SYNC_EXTRUDER_MOTION MOTION_QUEUE=extruder EXTRUDER= \" or a similar command. See sample-idex.cfg for an example configuration with a regular Cartesian kinematic. [dual_carriage] axis: # The axis this extra carriage is on (either x or y). This parameter # must be provided. #safe_distance: # The minimum distance (in mm) to enforce between the dual and the primary # carriages. If a G-Code command is executed that will bring the carriages # closer than the specified limit, such a command will be rejected with an # error. If safe_distance is not provided, it will be inferred from # position_min and position_max for the dual and primary carriages. If set # to 0 (or safe_distance is unset and position_min and position_max are # identical for the primary and dual carriages), the carriages proximity # checks will be disabled. #step_pin: #dir_pin: #enable_pin: #microsteps: #rotation_distance: #endstop_pin: #position_endstop: #position_min: #position_max: # See the \"stepper\" section for the definition of the above parameters. For an example of dual carriage configuration with generic_cartesian kinematic, see the following configuration sample . Please note that in this case the [dual_carriage] configuration deviates from the configuration described above: [dual_carriage my_dc_carriage] primary_carriage: # Defines the matching primary carriage of this dual carriage and # the corresponding IDEX axis. Valid choices are x, y, z. # This parameter must be provided. #safe_distance: # The minimum distance (in mm) to enforce between the dual and the primary # carriages. If a G-Code command is executed that will bring the carriages # closer than the specified limit, such a command will be rejected with an # error. If safe_distance is not provided, it will be inferred from # position_min and position_max for the dual and primary carriages. If set # to 0 (or safe_distance is unset and position_min and position_max are # identical for the primary and dual carriages), the carriages proximity # checks will be disabled. endstop_pin: #position_min: position_endstop: position_max: #homing_speed: #homing_retract_dist: #homing_retract_speed: #second_homing_speed: #homing_positive_dir: ... Refer to generic cartesian section for more information on the regular carriage parameters. Then a user must define one or more stepper motors moving the dual carriage (and other carriages as appropriate), for instance [carriage x] ... [carriage y] ... [dual_carriage u] primary_carriage: x ... [stepper dc_stepper] carriages: u-y ... [dual_carriage] requires special configuration for the input shaper. In general, it is necessary to run input shaper calibration twice - for the dual_carriage and its primary_carriage for the axis they share. Then the input shaper can be configured as follows, assuming the example above: [input_shaper] # Intentionally empty [delayed_gcode init_shaper] initial_duration: 0.1 gcode: SET_DUAL_CARRIAGE CARRIAGE=u SET_INPUT_SHAPER SHAPER_TYPE_X=<dual_carriage_x_shaper> SHAPER_FREQ_X=<dual_carriage_x_freq> SHAPER_TYPE_Y=<y_shaper> SHAPER_FREQ_Y=<y_freq> SET_DUAL_CARRIAGE CARRIAGE=x SET_INPUT_SHAPER SHAPER_TYPE_X=<primary_carriage_x_shaper> SHAPER_FREQ_X=<primary_carriage_x_freq> SHAPER_TYPE_Y=<y_shaper> SHAPER_FREQ_Y=<y_freq> Note that SHAPER_TYPE_Y and SHAPER_FREQ_Y must be the same in both commands in this case, since the same motors drive Y axis when either of the x and u carriages are active. It is worth noting that generic_cartesian kinematic can support two dual carriages for X and Y axes. For reference, see for instance a sample of CoreXYUV configuration.","title":"[dual_carriage]"},{"location":"Config_Reference.html#extruder_stepper","text":"Support for additional steppers synchronized to the movement of an extruder (one may define any number of sections with an \"extruder_stepper\" prefix). See the command reference for more information. [extruder_stepper my_extra_stepper] extruder: # The extruder this stepper is synchronized to. If this is set to an # empty string then the stepper will not be synchronized to an # extruder. This parameter must be provided. #step_pin: #dir_pin: #enable_pin: #microsteps: #rotation_distance: # See the \"stepper\" section for the definition of the above # parameters.","title":"[extruder_stepper]"},{"location":"Config_Reference.html#manual_stepper","text":"Manual steppers (one may define any number of sections with a \"manual_stepper\" prefix). These are steppers that are controlled by the MANUAL_STEPPER g-code command. For example: \"MANUAL_STEPPER STEPPER=my_stepper MOVE=10 SPEED=5\". See G-Codes file for a description of the MANUAL_STEPPER command. The steppers are not connected to the normal printer kinematics. [manual_stepper my_stepper] #step_pin: #dir_pin: #enable_pin: #microsteps: #rotation_distance: # See the \"stepper\" section for a description of these parameters. #velocity: # Set the default velocity (in mm/s) for the stepper. This value # will be used if a MANUAL_STEPPER command does not specify a SPEED # parameter. The default is 5mm/s. #accel: # Set the default acceleration (in mm/s^2) for the stepper. An # acceleration of zero will result in no acceleration. This value # will be used if a MANUAL_STEPPER command does not specify an ACCEL # parameter. The default is zero. #endstop_pin: # Endstop switch detection pin. If specified, then one may perform # \"homing moves\" by adding a STOP_ON_ENDSTOP parameter to # MANUAL_STEPPER movement commands. #position_min: #position_max: # The minimum and maximum position the stepper can be commanded to # move to. If specified then one may not command the stepper to move # past the given position. Note that these limits do not prevent # setting an arbitrary position with the `MANUAL_STEPPER # SET_POSITION=x` command. The default is to not enforce a limit.","title":"[manual_stepper]"},{"location":"Config_Reference.html#custom-heaters-and-sensors","text":"","title":"Custom heaters and sensors"},{"location":"Config_Reference.html#verify_heater","text":"Heater and temperature sensor verification. Heater verification is automatically enabled for each heater that is configured on the printer. Use verify_heater sections to change the default settings. [verify_heater heater_config_name] #max_error: 120 # The maximum \"cumulative temperature error\" before raising an # error. Smaller values result in stricter checking and larger # values allow for more time before an error is reported. # Specifically, the temperature is inspected once a second and if it # is close to the target temperature then an internal \"error # counter\" is reset; otherwise, if the temperature is below the # target range then the counter is increased by the amount the # reported temperature differs from that range. Should the counter # exceed this \"max_error\" then an error is raised. The default is # 120. #check_gain_time: # This controls heater verification during initial heating. Smaller # values result in stricter checking and larger values allow for # more time before an error is reported. Specifically, during # initial heating, as long as the heater increases in temperature # within this time frame (specified in seconds) then the internal # \"error counter\" is reset. The default is 20 seconds for extruders # and 60 seconds for heater_bed. #hysteresis: 5 # The maximum temperature difference (in Celsius) to a target # temperature that is considered in range of the target. This # controls the max_error range check. It is rare to customize this # value. The default is 5. #heating_gain: 2 # The minimum temperature (in Celsius) that the heater must increase # by during the check_gain_time check. It is rare to customize this # value. The default is 2.","title":"[verify_heater]"},{"location":"Config_Reference.html#homing_heaters","text":"Tool to disable heaters when homing or probing an axis. [homing_heaters] #steppers: # A comma separated list of steppers that should cause heaters to be # disabled. The default is to disable heaters for any homing/probing # move. # Typical example: stepper_z #heaters: # A comma separated list of heaters to disable during homing/probing # moves. The default is to disable all heaters. # Typical example: extruder, heater_bed","title":"[homing_heaters]"},{"location":"Config_Reference.html#thermistor","text":"Custom thermistors (one may define any number of sections with a \"thermistor\" prefix). A custom thermistor may be used in the sensor_type field of a heater config section. (For example, if one defines a \"[thermistor my_thermistor]\" section then one may use a \"sensor_type: my_thermistor\" when defining a heater.) Be sure to place the thermistor section in the config file above its first use in a heater section. [thermistor my_thermistor] #temperature1: #resistance1: #temperature2: #resistance2: #temperature3: #resistance3: # Three resistance measurements (in Ohms) at the given temperatures # (in Celsius). The three measurements will be used to calculate the # Steinhart-Hart coefficients for the thermistor. These parameters # must be provided when using Steinhart-Hart to define the # thermistor. #beta: # Alternatively, one may define temperature1, resistance1, and beta # to define the thermistor parameters. This parameter must be # provided when using \"beta\" to define the thermistor.","title":"[thermistor]"},{"location":"Config_Reference.html#adc_temperature","text":"Custom ADC temperature sensors (one may define any number of sections with an \"adc_temperature\" prefix). This allows one to define a custom temperature sensor that measures a voltage on an Analog to Digital Converter (ADC) pin and uses linear interpolation between a set of configured temperature/voltage (or temperature/resistance) measurements to determine the temperature. The resulting sensor can be used as a sensor_type in a heater section. (For example, if one defines a \"[adc_temperature my_sensor]\" section then one may use a \"sensor_type: my_sensor\" when defining a heater.) Be sure to place the sensor section in the config file above its first use in a heater section. [adc_temperature my_sensor] #temperature1: #voltage1: #temperature2: #voltage2: #... # A set of temperatures (in Celsius) and voltages (in Volts) to use # as reference when converting a temperature. A heater section using # this sensor may also specify adc_voltage and voltage_offset # parameters to define the ADC voltage (see \"Common temperature # amplifiers\" section for details). At least two measurements must # be provided. #temperature1: #resistance1: #temperature2: #resistance2: #... # Alternatively one may specify a set of temperatures (in Celsius) # and resistance (in Ohms) to use as reference when converting a # temperature. A heater section using this sensor may also specify a # pullup_resistor parameter (see \"extruder\" section for details). At # least two measurements must be provided.","title":"[adc_temperature]"},{"location":"Config_Reference.html#heater_generic","text":"Generic heaters (one may define any number of sections with a \"heater_generic\" prefix). These heaters behave similarly to standard heaters (extruders, heated beds). Use the SET_HEATER_TEMPERATURE command (see G-Codes for details) to set the target temperature. [heater_generic my_generic_heater] #gcode_id: # The id to use when reporting the temperature in the M105 command. # This parameter must be provided. #heater_pin: #max_power: #sensor_type: #sensor_pin: #smooth_time: #control: #pid_Kp: #pid_Ki: #pid_Kd: #pwm_cycle_time: #min_temp: #max_temp: # See the \"extruder\" section for the definition of the above # parameters.","title":"[heater_generic]"},{"location":"Config_Reference.html#temperature_sensor","text":"Generic temperature sensors. One can define any number of additional temperature sensors that are reported via the M105 command. [temperature_sensor my_sensor] #sensor_type: #sensor_pin: #min_temp: #max_temp: # See the \"extruder\" section for the definition of the above # parameters. #gcode_id: # See the \"heater_generic\" section for the definition of this # parameter.","title":"[temperature_sensor]"},{"location":"Config_Reference.html#temperature_probe","text":"Reports probe coil temperature. Includes optional thermal drift calibration for eddy current based probes. A [temperature_probe] section may be linked to a [probe_eddy_current] by using the same postfix for both sections. [temperature_probe my_probe] #sensor_type: #sensor_pin: #min_temp: #max_temp: # Temperature sensor configuration. # See the \"extruder\" section for the definition of the above # parameters. #smooth_time: # A time value (in seconds) over which temperature measurements will # be smoothed to reduce the impact of measurement noise. The default # is 2.0 seconds. #gcode_id: # See the \"heater_generic\" section for the definition of this # parameter. #speed: # The travel speed [mm/s] for xy moves during calibration. Default # is the speed defined by the probe. #horizontal_move_z: # The z distance [mm] from the bed at which xy moves will occur # during calibration. Default is 2mm. #resting_z: # The z distance [mm] from the bed at which the tool will rest # to heat the probe coil during calibration. Default is .4mm #calibration_position: # The X, Y, Z position where the tool should be moved when # probe drift calibration initializes. This is the location # where the first manual probe will occur. If omitted, the # default behavior is not to move the tool prior to the first # manual probe. #calibration_bed_temp: # The maximum safe bed temperature (in C) used to heat the probe # during probe drift calibration. When set, the calibration # procedure will turn on the bed after the first sample is # taken. When the calibration procedure is complete the bed # temperature will be set to zero. When omitted the default # behavior is not to set the bed temperature. #calibration_extruder_temp: # The extruder temperature (in C) set probe during drift calibration. # When this option is supplied the procedure will wait for until the # specified temperature is reached before requesting the first manual # probe. When the calibration procedure is complete the extruder # temperature will be set to 0. When omitted the default behavior is # not to set the extruder temperature. #extruder_heating_z: 50. # The Z location where extruder heating will occur if the # \"calibration_extruder_temp\" option is set. Its recommended to heat # the extruder some distance from the bed to minimize its impact on # the probe coil temperature. The default is 50. #max_validation_temp: 60. # The maximum temperature used to validate the calibration. It is # recommended to set this to a value between 100 and 120 for enclosed # printers. The default is 60.","title":"[temperature_probe]"},{"location":"Config_Reference.html#temperature-sensors","text":"Klipper includes definitions for many types of temperature sensors. These sensors may be used in any config section that requires a temperature sensor (such as an [extruder] or [heater_bed] section).","title":"Temperature sensors"},{"location":"Config_Reference.html#common-thermistors","text":"Common thermistors. The following parameters are available in heater sections that use one of these sensors. sensor_type: # One of \"EPCOS 100K B57560G104F\", \"ATC Semitec 104GT-2\", # \"ATC Semitec 104NT-4-R025H42G\", \"Generic 3950\", # \"Honeywell 100K 135-104LAG-J01\", \"NTC 100K MGB18-104F39050L32\", # \"SliceEngineering 450\", or \"TDK NTCG104LH104JT1\" sensor_pin: # Analog input pin connected to the thermistor. This parameter must # be provided. #pullup_resistor: 4700 # The resistance (in ohms) of the pullup attached to the thermistor. # The default is 4700 ohms. #inline_resistor: 0 # The resistance (in ohms) of an extra (not heat varying) resistor # that is placed inline with the thermistor. It is rare to set this. # The default is 0 ohms.","title":"Common thermistors"},{"location":"Config_Reference.html#common-temperature-amplifiers","text":"Common temperature amplifiers. The following parameters are available in heater sections that use one of these sensors. sensor_type: # One of \"PT100 INA826\", \"AD595\", \"AD597\", \"AD8494\", \"AD8495\", # \"AD8496\", or \"AD8497\". sensor_pin: # Analog input pin connected to the sensor. This parameter must be # provided. #adc_voltage: 5.0 # The ADC comparison voltage (in Volts). The default is 5 volts. #voltage_offset: 0 # The ADC voltage offset (in Volts). The default is 0.","title":"Common temperature amplifiers"},{"location":"Config_Reference.html#directly-connected-pt1000-sensor","text":"Directly connected PT1000 sensor. The following parameters are available in heater sections that use one of these sensors. sensor_type: PT1000 sensor_pin: # Analog input pin connected to the sensor. This parameter must be # provided. #pullup_resistor: 4700 # The resistance (in ohms) of the pullup attached to the sensor. The # default is 4700 ohms.","title":"Directly connected PT1000 sensor"},{"location":"Config_Reference.html#maxxxxxx-temperature-sensors","text":"MAXxxxxx serial peripheral interface (SPI) temperature based sensors. The following parameters are available in heater sections that use one of these sensor types. sensor_type: # One of \"MAX6675\", \"MAX31855\", \"MAX31856\", or \"MAX31865\". sensor_pin: # The chip select line for the sensor chip. This parameter must be # provided. #spi_speed: 4000000 # The SPI speed (in hz) to use when communicating with the chip. # The default is 4000000. #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #tc_type: K #tc_use_50Hz_filter: False #tc_averaging_count: 1 # The above parameters control the sensor parameters of MAX31856 # chips. The defaults for each parameter are next to the parameter # name in the above list. #rtd_nominal_r: 100 #rtd_reference_r: 430 #rtd_num_of_wires: 2 #rtd_use_50Hz_filter: False # The above parameters control the sensor parameters of MAX31865 # chips. The defaults for each parameter are next to the parameter # name in the above list.","title":"MAXxxxxx temperature sensors"},{"location":"Config_Reference.html#bmp180bmp280bme280bmp388bme680-temperature-sensor","text":"BMP180/BMP280/BME280/BMP388/BME680 two wire interface (I2C) environmental sensors. Note that these sensors are not intended for use with extruders and heater beds, but rather for monitoring ambient temperature (C), pressure (hPa), relative humidity and in case of the BME680 gas level. See sample-macros.cfg for a gcode_macro that may be used to report pressure and humidity in addition to temperature. sensor_type: BME280 #i2c_address: # Default is 118 (0x76). The BMP180, BMP388 and some BME280 sensors # have an address of 119 (0x77). #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters.","title":"BMP180/BMP280/BME280/BMP388/BME680 temperature sensor"},{"location":"Config_Reference.html#aht10aht20aht21-temperature-sensor","text":"AHT10/AHT20/AHT21 two wire interface (I2C) environmental sensors. Note that these sensors are not intended for use with extruders and heater beds, but rather for monitoring ambient temperature (C) and relative humidity. See sample-macros.cfg for a gcode_macro that may be used to report humidity in addition to temperature. sensor_type: AHT10 # Also use AHT10 for AHT20 and AHT21 sensors. #i2c_address: # Default is 56 (0x38). Some AHT10 sensors give the option to use # 57 (0x39) by moving a resistor. #i2c_mcu: #i2c_bus: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #aht10_report_time: # Interval in seconds between readings. Default is 30, minimum is 5","title":"AHT10/AHT20/AHT21 temperature sensor"},{"location":"Config_Reference.html#htu21d-sensor","text":"HTU21D family two wire interface (I2C) environmental sensor. Note that this sensor is not intended for use with extruders and heater beds, but rather for monitoring ambient temperature (C) and relative humidity. See sample-macros.cfg for a gcode_macro that may be used to report humidity in addition to temperature. sensor_type: # Must be \"HTU21D\" , \"SI7013\", \"SI7020\", \"SI7021\" or \"SHT21\" #i2c_address: # Default is 64 (0x40). #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #htu21d_hold_master: # If the sensor can hold the I2C buf while reading. If True no other # bus communication can be performed while reading is in progress. # Default is False. #htu21d_resolution: # The resolution of temperature and humidity reading. # Valid values are: # 'TEMP14_HUM12' -> 14bit for Temp and 12bit for humidity # 'TEMP13_HUM10' -> 13bit for Temp and 10bit for humidity # 'TEMP12_HUM08' -> 12bit for Temp and 08bit for humidity # 'TEMP11_HUM11' -> 11bit for Temp and 11bit for humidity # Default is: \"TEMP11_HUM11\" #htu21d_report_time: # Interval in seconds between readings. Default is 30","title":"HTU21D sensor"},{"location":"Config_Reference.html#sht3x-sensor","text":"SHT3X family two wire interface (I2C) environmental sensor. These sensors have a range of -55~125 C, so are usable for e.g. chamber temperature monitoring. They can also function as simple fan/heater controllers. sensor_type: SHT3X #i2c_address: # Default is 68 (0x44). #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters.","title":"SHT3X sensor"},{"location":"Config_Reference.html#lm75-temperature-sensor","text":"LM75/LM75A two wire (I2C) connected temperature sensors. These sensors have a range of -55~125 C, so are usable for e.g. chamber temperature monitoring. They can also function as simple fan/heater controllers. sensor_type: LM75 #i2c_address: # Default is 72 (0x48). Normal range is 72-79 (0x48-0x4F) and the 3 # low bits of the address are configured via pins on the chip # (usually with jumpers or hard wired). #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #lm75_report_time: # Interval in seconds between readings. Default is 0.8, with minimum # 0.5.","title":"LM75 temperature sensor"},{"location":"Config_Reference.html#builtin-micro-controller-temperature-sensor","text":"The atsam, atsamd, stm32 and rp2040 micro-controllers contain an internal temperature sensor. One can use the \"temperature_mcu\" sensor to monitor these temperatures. sensor_type: temperature_mcu #sensor_mcu: mcu # The micro-controller to read from. The default is \"mcu\". #sensor_temperature1: #sensor_adc1: # Specify the above two parameters (a temperature in Celsius and an # ADC value as a float between 0.0 and 1.0) to calibrate the # micro-controller temperature. This may improve the reported # temperature accuracy on some chips. A typical way to obtain this # calibration information is to completely remove power from the # printer for a few hours (to ensure it is at the ambient # temperature), then power it up and use the QUERY_ADC command to # obtain an ADC measurement. Use some other temperature sensor on # the printer to find the corresponding ambient temperature. The # default is to use the factory calibration data on the # micro-controller (if applicable) or the nominal values from the # micro-controller specification. #sensor_temperature2: #sensor_adc2: # If sensor_temperature1/sensor_adc1 is specified then one may also # specify sensor_temperature2/sensor_adc2 calibration data. Doing so # may provide calibrated \"temperature slope\" information. The # default is to use the factory calibration data on the # micro-controller (if applicable) or the nominal values from the # micro-controller specification.","title":"Builtin micro-controller temperature sensor"},{"location":"Config_Reference.html#host-temperature-sensor","text":"Temperature from the machine (eg Raspberry Pi) running the host software. sensor_type: temperature_host #sensor_path: # The path to temperature system file. The default is # \"/sys/class/thermal/thermal_zone0/temp\" which is the temperature # system file on a Raspberry Pi computer.","title":"Host temperature sensor"},{"location":"Config_Reference.html#ds18b20-temperature-sensor","text":"DS18B20 is a 1-wire (w1) digital temperature sensor. Note that this sensor is not intended for use with extruders and heater beds, but rather for monitoring ambient temperature (C). These sensors have range up to 125 C, so are usable for e.g. chamber temperature monitoring. They can also function as simple fan/heater controllers. DS18B20 sensors are only supported on the \"host mcu\", e.g. the Raspberry Pi. The w1-gpio Linux kernel module must be installed. sensor_type: DS18B20 serial_no: # Each 1-wire device has a unique serial number used to identify the device, # usually in the format 28-031674b175ff. This parameter must be provided. # Attached 1-wire devices can be listed using the following Linux command: # ls /sys/bus/w1/devices/ #ds18_report_time: # Interval in seconds between readings. Default is 3.0, with a minimum of 1.0 #sensor_mcu: # The micro-controller to read from. Must be the host_mcu","title":"DS18B20 temperature sensor"},{"location":"Config_Reference.html#combined-temperature-sensor","text":"Combined temperature sensor is a virtual temperature sensor based on several other sensors. This sensor can be used with extruders, heater_generic and heater beds. sensor_type: temperature_combined #sensor_list: # Must be provided. List of sensors to combine to new \"virtual\" # sensor. # E.g. 'temperature_sensor sensor1,extruder,heater_bed' #combination_method: # Must be provided. Combination method used for the sensor. # Available options are 'max', 'min', 'mean'. #maximum_deviation: # Must be provided. Maximum permissible deviation between the sensors # to combine (e.g. 5 degrees). To disable it, use a large value (e.g. 999.9)","title":"Combined temperature sensor"},{"location":"Config_Reference.html#fans","text":"","title":"Fans"},{"location":"Config_Reference.html#fan","text":"Print cooling fan. [fan] pin: # Output pin controlling the fan. This parameter must be provided. #max_power: 1.0 # The maximum power (expressed as a value from 0.0 to 1.0) that the # pin may be set to. The value 1.0 allows the pin to be set fully # enabled for extended periods, while a value of 0.5 would allow the # pin to be enabled for no more than half the time. This setting may # be used to limit the total power output (over extended periods) to # the fan. If this value is less than 1.0 then fan speed requests # will be scaled between zero and max_power (for example, if # max_power is .9 and a fan speed of 80% is requested then the fan # power will be set to 72%). The default is 1.0. #shutdown_speed: 0 # The desired fan speed (expressed as a value from 0.0 to 1.0) if # the micro-controller software enters an error state. The default # is 0. #cycle_time: 0.010 # The amount of time (in seconds) for each PWM power cycle to the # fan. It is recommended this be 10 milliseconds or greater when # using software based PWM. The default is 0.010 seconds. #hardware_pwm: False # Enable this to use hardware PWM instead of software PWM. Most fans # do not work well with hardware PWM, so it is not recommended to # enable this unless there is an electrical requirement to switch at # very high speeds. When using hardware PWM the actual cycle time is # constrained by the implementation and may be significantly # different than the requested cycle_time. The default is False. #kick_start_time: 0.100 # Time (in seconds) to run the fan at full speed when either first # enabling or increasing it by more than 50% (helps get the fan # spinning). The default is 0.100 seconds. #off_below: 0.0 # The minimum input speed which will power the fan (expressed as a # value from 0.0 to 1.0). When a speed lower than off_below is # requested the fan will instead be turned off. This setting may be # used to prevent fan stalls and to ensure kick starts are # effective. The default is 0.0. # # This setting should be recalibrated whenever max_power is adjusted. # To calibrate this setting, start with off_below set to 0.0 and the # fan spinning. Gradually lower the fan speed to determine the lowest # input speed which reliably drives the fan without stalls. Set # off_below to the duty cycle corresponding to this value (for # example, 12% -> 0.12) or slightly higher. #tachometer_pin: # Tachometer input pin for monitoring fan speed. A pullup is generally # required. This parameter is optional. #tachometer_ppr: 2 # When tachometer_pin is specified, this is the number of pulses per # revolution of the tachometer signal. For a BLDC fan this is # normally half the number of poles. The default is 2. #tachometer_poll_interval: 0.0015 # When tachometer_pin is specified, this is the polling period of the # tachometer pin, in seconds. The default is 0.0015, which is fast # enough for fans below 10000 RPM at 2 PPR. This must be smaller than # 30/(tachometer_ppr*rpm), with some margin, where rpm is the # maximum speed (in RPM) of the fan. #enable_pin: # Optional pin to enable power to the fan. This can be useful for fans # with dedicated PWM inputs. Some of these fans stay on even at 0% PWM # input. In such a case, the PWM pin can be used normally, and e.g. a # ground-switched FET(standard fan pin) can be used to control power to # the fan.","title":"[fan]"},{"location":"Config_Reference.html#heater_fan","text":"Heater cooling fans (one may define any number of sections with a \"heater_fan\" prefix). A \"heater fan\" is a fan that will be enabled whenever its associated heater is active. By default, a heater_fan has a shutdown_speed equal to max_power. [heater_fan heatbreak_cooling_fan] #pin: #max_power: #shutdown_speed: #cycle_time: #hardware_pwm: #kick_start_time: #off_below: #tachometer_pin: #tachometer_ppr: #tachometer_poll_interval: #enable_pin: # See the \"fan\" section for a description of the above parameters. #heater: extruder # Name of the config section defining the heater that this fan is # associated with. If a comma separated list of heater names is # provided here, then the fan will be enabled when any of the given # heaters are enabled. The default is \"extruder\". #heater_temp: 50.0 # A temperature (in Celsius) that the heater must drop below before # the fan is disabled. The default is 50 Celsius. #fan_speed: 1.0 # The fan speed (expressed as a value from 0.0 to 1.0) that the fan # will be set to when its associated heater is enabled. The default # is 1.0","title":"[heater_fan]"},{"location":"Config_Reference.html#controller_fan","text":"Controller cooling fan (one may define any number of sections with a \"controller_fan\" prefix). A \"controller fan\" is a fan that will be enabled whenever its associated heater or its associated stepper driver is active. The fan will stop whenever an idle_timeout is reached to ensure no overheating will occur after deactivating a watched component. [controller_fan my_controller_fan] #pin: #max_power: #shutdown_speed: #cycle_time: #hardware_pwm: #kick_start_time: #off_below: #tachometer_pin: #tachometer_ppr: #tachometer_poll_interval: #enable_pin: # See the \"fan\" section for a description of the above parameters. #fan_speed: 1.0 # The fan speed (expressed as a value from 0.0 to 1.0) that the fan # will be set to when a heater or stepper driver is active. # The default is 1.0 #idle_timeout: # The amount of time (in seconds) after a stepper driver or heater # was active and the fan should be kept running. The default # is 30 seconds. #idle_speed: # The fan speed (expressed as a value from 0.0 to 1.0) that the fan # will be set to when a heater or stepper driver was active and # before the idle_timeout is reached. The default is fan_speed. #heater: #stepper: # Name of the config section defining the heater/stepper that this fan # is associated with. If a comma separated list of heater/stepper names # is provided here, then the fan will be enabled when any of the given # heaters/steppers are enabled. The default heater is \"extruder\", the # default stepper is all of them.","title":"[controller_fan]"},{"location":"Config_Reference.html#temperature_fan","text":"Temperature-triggered cooling fans (one may define any number of sections with a \"temperature_fan\" prefix). A \"temperature fan\" is a fan that will be enabled whenever its associated sensor is above a set temperature. By default, a temperature_fan has a shutdown_speed equal to max_power. See the command reference for additional information. [temperature_fan my_temp_fan] #pin: #max_power: #shutdown_speed: #cycle_time: #hardware_pwm: #kick_start_time: #off_below: #tachometer_pin: #tachometer_ppr: #tachometer_poll_interval: #enable_pin: # See the \"fan\" section for a description of the above parameters. #sensor_type: #sensor_pin: #control: #max_delta: #min_temp: #max_temp: # See the \"extruder\" section for a description of the above parameters. #pid_Kp: #pid_Ki: #pid_Kd: # The proportional (pid_Kp), integral (pid_Ki), and derivative # (pid_Kd) settings for the PID feedback control system. Klipper # evaluates the PID settings with the following general formula: # fan_pwm = max_power - (Kp*e + Ki*integral(e) - Kd*derivative(e)) / 255 # Where \"e\" is \"target_temperature - measured_temperature\" and # \"fan_pwm\" is the requested fan rate with 0.0 being full off and # 1.0 being full on. The pid_Kp, pid_Ki, and pid_Kd parameters must # be provided when the PID control algorithm is enabled. #pid_deriv_time: 2.0 # A time value (in seconds) over which temperature measurements will # be smoothed when using the PID control algorithm. This may reduce # the impact of measurement noise. The default is 2 seconds. #target_temp: 40.0 # A temperature (in Celsius) that will be the target temperature. # The default is 40 degrees. #max_speed: 1.0 # The fan speed (expressed as a value from 0.0 to 1.0) that the fan # will be set to when the sensor temperature exceeds the set value. # The default is 1.0. #min_speed: 0.3 # The minimum fan speed (expressed as a value from 0.0 to 1.0) that # the fan will be set to for PID temperature fans. # The default is 0.3. #gcode_id: # If set, the temperature will be reported in M105 queries using the # given id. The default is to not report the temperature via M105.","title":"[temperature_fan]"},{"location":"Config_Reference.html#fan_generic","text":"Manually controlled fan (one may define any number of sections with a \"fan_generic\" prefix). The speed of a manually controlled fan is set with the SET_FAN_SPEED gcode command . [fan_generic extruder_partfan] #pin: #max_power: #shutdown_speed: #cycle_time: #hardware_pwm: #kick_start_time: #off_below: #tachometer_pin: #tachometer_ppr: #tachometer_poll_interval: #enable_pin: # See the \"fan\" section for a description of the above parameters.","title":"[fan_generic]"},{"location":"Config_Reference.html#leds","text":"","title":"LEDs"},{"location":"Config_Reference.html#led","text":"Support for LEDs (and LED strips) controlled via micro-controller PWM pins (one may define any number of sections with an \"led\" prefix). See the command reference for more information. [led my_led] #red_pin: #green_pin: #blue_pin: #white_pin: # The pin controlling the given LED color. At least one of the above # parameters must be provided. #cycle_time: 0.010 # The amount of time (in seconds) per PWM cycle. It is recommended # this be 10 milliseconds or greater when using software based PWM. # The default is 0.010 seconds. #hardware_pwm: False # Enable this to use hardware PWM instead of software PWM. When # using hardware PWM the actual cycle time is constrained by the # implementation and may be significantly different than the # requested cycle_time. The default is False. #initial_RED: 0.0 #initial_GREEN: 0.0 #initial_BLUE: 0.0 #initial_WHITE: 0.0 # Sets the initial LED color. Each value should be between 0.0 and # 1.0. The default for each color is 0.","title":"[led]"},{"location":"Config_Reference.html#neopixel","text":"Neopixel (aka WS2812) LED support (one may define any number of sections with a \"neopixel\" prefix). See the command reference for more information. Note that the linux mcu implementation does not currently support directly connected neopixels. The current design using the Linux kernel interface does not allow this scenario because the kernel GPIO interface is not fast enough to provide the required pulse rates. [neopixel my_neopixel] pin: # The pin connected to the neopixel. This parameter must be # provided. #chain_count: # The number of Neopixel chips that are \"daisy chained\" to the # provided pin. The default is 1 (which indicates only a single # Neopixel is connected to the pin). #color_order: GRB # Set the pixel order required by the LED hardware (using a string # containing the letters R, G, B, W with W optional). Alternatively, # this may be a comma separated list of pixel orders - one for each # LED in the chain. The default is GRB. #initial_RED: 0.0 #initial_GREEN: 0.0 #initial_BLUE: 0.0 #initial_WHITE: 0.0 # See the \"led\" section for information on these parameters.","title":"[neopixel]"},{"location":"Config_Reference.html#dotstar","text":"Dotstar (aka APA102) LED support (one may define any number of sections with a \"dotstar\" prefix). See the command reference for more information. [dotstar my_dotstar] data_pin: # The pin connected to the data line of the dotstar. This parameter # must be provided. clock_pin: # The pin connected to the clock line of the dotstar. This parameter # must be provided. #chain_count: # See the \"neopixel\" section for information on this parameter. #initial_RED: 0.0 #initial_GREEN: 0.0 #initial_BLUE: 0.0 # See the \"led\" section for information on these parameters.","title":"[dotstar]"},{"location":"Config_Reference.html#pca9533","text":"PCA9533 LED support. The PCA9533 is used on the mightyboard. [pca9533 my_pca9533] #i2c_address: 98 # The i2c address that the chip is using on the i2c bus. Use 98 for # the PCA9533/1, 99 for the PCA9533/2. The default is 98. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #initial_RED: 0.0 #initial_GREEN: 0.0 #initial_BLUE: 0.0 #initial_WHITE: 0.0 # See the \"led\" section for information on these parameters.","title":"[pca9533]"},{"location":"Config_Reference.html#pca9632","text":"PCA9632 LED support. The PCA9632 is used on the FlashForge Dreamer. [pca9632 my_pca9632] #i2c_address: 98 # The i2c address that the chip is using on the i2c bus. This may be # 96, 97, 98, or 99. The default is 98. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #color_order: RGBW # Set the pixel order of the LED (using a string containing the # letters R, G, B, W). The default is RGBW. #initial_RED: 0.0 #initial_GREEN: 0.0 #initial_BLUE: 0.0 #initial_WHITE: 0.0 # See the \"led\" section for information on these parameters.","title":"[pca9632]"},{"location":"Config_Reference.html#additional-servos-buttons-and-other-pins","text":"","title":"Additional servos, buttons, and other pins"},{"location":"Config_Reference.html#servo","text":"Servos (one may define any number of sections with a \"servo\" prefix). The servos may be controlled using the SET_SERVO g-code command . For example: SET_SERVO SERVO=my_servo ANGLE=180 [servo my_servo] pin: # PWM output pin controlling the servo. This parameter must be # provided. #maximum_servo_angle: 180 # The maximum angle (in degrees) that this servo can be set to. The # default is 180 degrees. #minimum_pulse_width: 0.001 # The minimum pulse width time (in seconds). This should correspond # with an angle of 0 degrees. The default is 0.001 seconds. #maximum_pulse_width: 0.002 # The maximum pulse width time (in seconds). This should correspond # with an angle of maximum_servo_angle. The default is 0.002 # seconds. #initial_angle: # Initial angle (in degrees) to set the servo to. The default is to # not send any signal at startup. #initial_pulse_width: # Initial pulse width time (in seconds) to set the servo to. (This # is only valid if initial_angle is not set.) The default is to not # send any signal at startup.","title":"[servo]"},{"location":"Config_Reference.html#gcode_button","text":"Execute gcode when a button is pressed or released (or when a pin changes state). You can check the state of the button by using QUERY_BUTTON button=my_gcode_button . [gcode_button my_gcode_button] pin: # The pin on which the button is connected. This parameter must be # provided. #analog_range: # Two comma separated resistances (in Ohms) specifying the minimum # and maximum resistance range for the button. If analog_range is # provided then the pin must be an analog capable pin. The default # is to use digital gpio for the button. #analog_pullup_resistor: # The pullup resistance (in Ohms) when analog_range is specified. # The default is 4700 ohms. #press_gcode: # A list of G-Code commands to execute when the button is pressed. # G-Code templates are supported. This parameter must be provided. #release_gcode: # A list of G-Code commands to execute when the button is released. # G-Code templates are supported. The default is to not run any # commands on a button release. #debounce_delay: # A period of time in seconds to debounce events prior to running the # button gcode. If the button is pressed and released during this # delay, the entire button press is ignored. Default is 0.","title":"[gcode_button]"},{"location":"Config_Reference.html#output_pin","text":"Run-time configurable output pins (one may define any number of sections with an \"output_pin\" prefix). Pins configured here will be setup as output pins and one may modify them at run-time using \"SET_PIN PIN=my_pin VALUE=.1\" type extended g-code commands . [output_pin my_pin] pin: # The pin to configure as an output. This parameter must be # provided. #pwm: False # Set if the output pin should be capable of pulse-width-modulation. # If this is true, the value fields should be between 0 and 1; if it # is false the value fields should be either 0 or 1. The default is # False. #value: # The value to initially set the pin to during MCU configuration. # The default is 0 (for low voltage). #shutdown_value: # The value to set the pin to on an MCU shutdown event. The default # is 0 (for low voltage). #cycle_time: 0.100 # The amount of time (in seconds) per PWM cycle. It is recommended # this be 10 milliseconds or greater when using software based PWM. # The default is 0.100 seconds for pwm pins. #hardware_pwm: False # Enable this to use hardware PWM instead of software PWM. When # using hardware PWM the actual cycle time is constrained by the # implementation and may be significantly different than the # requested cycle_time. The default is False. #scale: # This parameter can be used to alter how the 'value' and # 'shutdown_value' parameters are interpreted for pwm pins. If # provided, then the 'value' parameter should be between 0.0 and # 'scale'. This may be useful when configuring a PWM pin that # controls a stepper voltage reference. The 'scale' can be set to # the equivalent stepper amperage if the PWM were fully enabled, and # then the 'value' parameter can be specified using the desired # amperage for the stepper. The default is to not scale the 'value' # parameter. #maximum_mcu_duration: #static_value: # These options are deprecated and should no longer be specified.","title":"[output_pin]"},{"location":"Config_Reference.html#pwm_tool","text":"Pulse width modulation digital output pins capable of high speed updates (one may define any number of sections with an \"output_pin\" prefix). Pins configured here will be setup as output pins and one may modify them at run-time using \"SET_PIN PIN=my_pin VALUE=.1\" type extended g-code commands . [pwm_tool my_tool] pin: # The pin to configure as an output. This parameter must be provided. #maximum_mcu_duration: # The maximum duration a non-shutdown value may be driven by the MCU # without an acknowledge from the host. # If host can not keep up with an update, the MCU will shutdown # and set all pins to their respective shutdown values. # Default: 0 (disabled) # Usual values are around 5 seconds. #value: #shutdown_value: #cycle_time: 0.100 #hardware_pwm: False #scale: # See the \"output_pin\" section for the definition of these parameters.","title":"[pwm_tool]"},{"location":"Config_Reference.html#pwm_cycle_time","text":"Run-time configurable output pins with dynamic pwm cycle timing (one may define any number of sections with an \"pwm_cycle_time\" prefix). Pins configured here will be setup as output pins and one may modify them at run-time using \"SET_PIN PIN=my_pin VALUE=.1 CYCLE_TIME=0.100\" type extended g-code commands . [pwm_cycle_time my_pin] pin: #value: #shutdown_value: #cycle_time: 0.100 #scale: # See the \"output_pin\" section for information on these parameters.","title":"[pwm_cycle_time]"},{"location":"Config_Reference.html#static_digital_output","text":"Statically configured digital output pins (one may define any number of sections with a \"static_digital_output\" prefix). Pins configured here will be setup as a GPIO output during MCU configuration. They can not be changed at run-time. [static_digital_output my_output_pins] pins: # A comma separated list of pins to be set as GPIO output pins. The # pin will be set to a high level unless the pin name is prefaced # with \"!\". This parameter must be provided.","title":"[static_digital_output]"},{"location":"Config_Reference.html#multi_pin","text":"Multiple pin outputs (one may define any number of sections with a \"multi_pin\" prefix). A multi_pin output creates an internal pin alias that can modify multiple output pins each time the alias pin is set. For example, one could define a \"[multi_pin my_fan]\" object containing two pins and then set \"pin=multi_pin:my_fan\" in the \"[fan]\" section - on each fan change both output pins would be updated. These aliases may not be used with stepper motor pins. [multi_pin my_multi_pin] pins: # A comma separated list of pins associated with this alias. This # parameter must be provided.","title":"[multi_pin]"},{"location":"Config_Reference.html#tmc-stepper-driver-configuration","text":"Configuration of Trinamic stepper motor drivers in UART/SPI mode. Additional information is in the TMC Drivers guide and in the command reference .","title":"TMC stepper driver configuration"},{"location":"Config_Reference.html#tmc2130","text":"Configure a TMC2130 stepper motor driver via SPI bus. To use this feature, define a config section with a \"tmc2130\" prefix followed by the name of the corresponding stepper config section (for example, \"[tmc2130 stepper_x]\"). [tmc2130 stepper_x] cs_pin: # The pin corresponding to the TMC2130 chip select line. This pin # will be set to low at the start of SPI messages and raised to high # after the message completes. This parameter must be provided. #spi_speed: #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #chain_position: #chain_length: # These parameters configure an SPI daisy chain. The two parameters # define the stepper position in the chain and the total chain length. # Position 1 corresponds to the stepper that connects to the MOSI signal. # The default is to not use an SPI daisy chain. #interpolate: True # If true, enable step interpolation (the driver will internally # step at a rate of 256 micro-steps). This interpolation does # introduce a small systemic positional deviation - see # TMC_Drivers.md for details. The default is True. run_current: # The amount of current (in amps RMS) to configure the driver to use # during stepper movement. This parameter must be provided. #hold_current: # The amount of current (in amps RMS) to configure the driver to use # when the stepper is not moving. Setting a hold_current is not # recommended (see TMC_Drivers.md for details). The default is to # not reduce the current. #sense_resistor: 0.110 # The resistance (in ohms) of the motor sense resistor. The default # is 0.110 ohms. #stealthchop_threshold: 0 # The velocity (in mm/s) to set the \"stealthChop\" threshold to. When # set, \"stealthChop\" mode will be enabled if the stepper motor # velocity is below this value. Note that the \"sensorless homing\" # code may temporarily override this setting during homing # operations. The default is 0, which disables \"stealthChop\" mode. #coolstep_threshold: # The velocity (in mm/s) to set the TMC driver internal \"CoolStep\" # threshold to. If set, the coolstep feature will be enabled when # the stepper motor velocity is near or above this value. Important # - if coolstep_threshold is set and \"sensorless homing\" is used, # then one must ensure that the homing speed is above the coolstep # threshold! The default is to not enable the coolstep feature. #high_velocity_threshold: # The velocity (in mm/s) to set the TMC driver internal \"high # velocity\" threshold (THIGH) to. This is typically used to disable # the \"CoolStep\" feature at high speeds. The default is to not set a # TMC \"high velocity\" threshold. #driver_MSLUT0: 2863314260 #driver_MSLUT1: 1251300522 #driver_MSLUT2: 608774441 #driver_MSLUT3: 269500962 #driver_MSLUT4: 4227858431 #driver_MSLUT5: 3048961917 #driver_MSLUT6: 1227445590 #driver_MSLUT7: 4211234 #driver_W0: 2 #driver_W1: 1 #driver_W2: 1 #driver_W3: 1 #driver_X1: 128 #driver_X2: 255 #driver_X3: 255 #driver_START_SIN: 0 #driver_START_SIN90: 247 # These fields control the Microstep Table registers directly. The optimal # wave table is specific to each motor and might vary with current. An # optimal configuration will have minimal print artifacts caused by # non-linear stepper movement. The values specified above are the default # values used by the driver. The value must be specified as a decimal integer # (hex form is not supported). In order to compute the wave table fields, # see the tmc2130 \"Calculation Sheet\" from the Trinamic website. #driver_IHOLDDELAY: 8 #driver_TPOWERDOWN: 0 #driver_TBL: 1 #driver_TOFF: 4 #driver_HEND: 7 #driver_HSTRT: 0 #driver_VHIGHFS: 0 #driver_VHIGHCHM: 0 #driver_PWM_AUTOSCALE: True #driver_PWM_FREQ: 1 #driver_PWM_GRAD: 4 #driver_PWM_AMPL: 128 #driver_FREEWHEEL: 0 #driver_SGT: 0 #driver_SEMIN: 0 #driver_SEUP: 0 #driver_SEMAX: 0 #driver_SEDN: 0 #driver_SEIMIN: 0 #driver_SFILT: 0 # Set the given register during the configuration of the TMC2130 # chip. This may be used to set custom motor parameters. The # defaults for each parameter are next to the parameter name in the # above list. #diag0_pin: #diag1_pin: # The micro-controller pin attached to one of the DIAG lines of the # TMC2130 chip. Only a single diag pin should be specified. The pin # is \"active low\" and is thus normally prefaced with \"^!\". Setting # this creates a \"tmc2130_stepper_x:virtual_endstop\" virtual pin # which may be used as the stepper's endstop_pin. Doing this enables # \"sensorless homing\". (Be sure to also set driver_SGT to an # appropriate sensitivity value.) The default is to not enable # sensorless homing.","title":"[tmc2130]"},{"location":"Config_Reference.html#tmc2208","text":"Configure a TMC2208 (or TMC2224) stepper motor driver via single wire UART. To use this feature, define a config section with a \"tmc2208\" prefix followed by the name of the corresponding stepper config section (for example, \"[tmc2208 stepper_x]\"). [tmc2208 stepper_x] uart_pin: # The pin connected to the TMC2208 PDN_UART line. This parameter # must be provided. #tx_pin: # If using separate receive and transmit lines to communicate with # the driver then set uart_pin to the receive pin and tx_pin to the # transmit pin. The default is to use uart_pin for both reading and # writing. #select_pins: # A comma separated list of pins to set prior to accessing the # tmc2208 UART. This may be useful for configuring an analog mux for # UART communication. The default is to not configure any pins. #interpolate: True # If true, enable step interpolation (the driver will internally # step at a rate of 256 micro-steps). This interpolation does # introduce a small systemic positional deviation - see # TMC_Drivers.md for details. The default is True. run_current: # The amount of current (in amps RMS) to configure the driver to use # during stepper movement. This parameter must be provided. #hold_current: # The amount of current (in amps RMS) to configure the driver to use # when the stepper is not moving. Setting a hold_current is not # recommended (see TMC_Drivers.md for details). The default is to # not reduce the current. #sense_resistor: 0.110 # The resistance (in ohms) of the motor sense resistor. The default # is 0.110 ohms. #stealthchop_threshold: 0 # The velocity (in mm/s) to set the \"stealthChop\" threshold to. When # set, \"stealthChop\" mode will be enabled if the stepper motor # velocity is below this value. Note that the \"sensorless homing\" # code may temporarily override this setting during homing # operations. The default is 0, which disables \"stealthChop\" mode. #driver_MULTISTEP_FILT: True #driver_IHOLDDELAY: 8 #driver_TPOWERDOWN: 20 #driver_TBL: 2 #driver_TOFF: 3 #driver_HEND: 0 #driver_HSTRT: 5 #driver_PWM_AUTOGRAD: True #driver_PWM_AUTOSCALE: True #driver_PWM_LIM: 12 #driver_PWM_REG: 8 #driver_PWM_FREQ: 1 #driver_PWM_GRAD: 14 #driver_PWM_OFS: 36 #driver_FREEWHEEL: 0 # Set the given register during the configuration of the TMC2208 # chip. This may be used to set custom motor parameters. The # defaults for each parameter are next to the parameter name in the # above list.","title":"[tmc2208]"},{"location":"Config_Reference.html#tmc2209","text":"Configure a TMC2209 stepper motor driver via single wire UART. To use this feature, define a config section with a \"tmc2209\" prefix followed by the name of the corresponding stepper config section (for example, \"[tmc2209 stepper_x]\"). [tmc2209 stepper_x] uart_pin: #tx_pin: #select_pins: #interpolate: True run_current: #hold_current: #sense_resistor: 0.110 #stealthchop_threshold: 0 # See the \"tmc2208\" section for the definition of these parameters. #coolstep_threshold: # The velocity (in mm/s) to set the TMC driver internal \"CoolStep\" # threshold to. If set, the coolstep feature will be enabled when # the stepper motor velocity is near or above this value. Important # - if coolstep_threshold is set and \"sensorless homing\" is used, # then one must ensure that the homing speed is above the coolstep # threshold! The default is to not enable the coolstep feature. #uart_address: # The address of the TMC2209 chip for UART messages (an integer # between 0 and 3). This is typically used when multiple TMC2209 # chips are connected to the same UART pin. The default is zero. #driver_MULTISTEP_FILT: True #driver_IHOLDDELAY: 8 #driver_TPOWERDOWN: 20 #driver_TBL: 2 #driver_TOFF: 3 #driver_HEND: 0 #driver_HSTRT: 5 #driver_PWM_AUTOGRAD: True #driver_PWM_AUTOSCALE: True #driver_PWM_LIM: 12 #driver_PWM_REG: 8 #driver_PWM_FREQ: 1 #driver_PWM_GRAD: 14 #driver_PWM_OFS: 36 #driver_FREEWHEEL: 0 #driver_SGTHRS: 0 #driver_SEMIN: 0 #driver_SEUP: 0 #driver_SEMAX: 0 #driver_SEDN: 0 #driver_SEIMIN: 0 # Set the given register during the configuration of the TMC2209 # chip. This may be used to set custom motor parameters. The # defaults for each parameter are next to the parameter name in the # above list. #diag_pin: # The micro-controller pin attached to the DIAG line of the TMC2209 # chip. The pin is normally prefaced with \"^\" to enable a pullup. # Setting this creates a \"tmc2209_stepper_x:virtual_endstop\" virtual # pin which may be used as the stepper's endstop_pin. Doing this # enables \"sensorless homing\". (Be sure to also set driver_SGTHRS to # an appropriate sensitivity value.) The default is to not enable # sensorless homing.","title":"[tmc2209]"},{"location":"Config_Reference.html#tmc2660","text":"Configure a TMC2660 stepper motor driver via SPI bus. To use this feature, define a config section with a tmc2660 prefix followed by the name of the corresponding stepper config section (for example, \"[tmc2660 stepper_x]\"). [tmc2660 stepper_x] cs_pin: # The pin corresponding to the TMC2660 chip select line. This pin # will be set to low at the start of SPI messages and set to high # after the message transfer completes. This parameter must be # provided. #spi_speed: 4000000 # SPI bus frequency used to communicate with the TMC2660 stepper # driver. The default is 4000000. #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #interpolate: True # If true, enable step interpolation (the driver will internally # step at a rate of 256 micro-steps). This only works if microsteps # is set to 16. Interpolation does introduce a small systemic # positional deviation - see TMC_Drivers.md for details. The default # is True. run_current: # The amount of current (in amps RMS) used by the driver during # stepper movement. This parameter must be provided. #sense_resistor: # The resistance (in ohms) of the motor sense resistor. This # parameter must be provided. #idle_current_percent: 100 # The percentage of the run_current the stepper driver will be # lowered to when the idle timeout expires (you need to set up the # timeout using a [idle_timeout] config section). The current will # be raised again once the stepper has to move again. Make sure to # set this to a high enough value such that the steppers do not lose # their position. There is also small delay until the current is # raised again, so take this into account when commanding fast moves # while the stepper is idling. The default is 100 (no reduction). #driver_TBL: 2 #driver_RNDTF: 0 #driver_HDEC: 0 #driver_CHM: 0 #driver_HEND: 3 #driver_HSTRT: 3 #driver_TOFF: 4 #driver_SEIMIN: 0 #driver_SEDN: 0 #driver_SEMAX: 0 #driver_SEUP: 0 #driver_SEMIN: 0 #driver_SFILT: 0 #driver_SGT: 0 #driver_SLPH: 0 #driver_SLPL: 0 #driver_DISS2G: 0 #driver_TS2G: 3 # Set the given parameter during the configuration of the TMC2660 # chip. This may be used to set custom driver parameters. The # defaults for each parameter are next to the parameter name in the # list above. See the TMC2660 datasheet about what each parameter # does and what the restrictions on parameter combinations are. Be # especially aware of the CHOPCONF register, where setting CHM to # either zero or one will lead to layout changes (the first bit of # HDEC) is interpreted as the MSB of HSTRT in this case).","title":"[tmc2660]"},{"location":"Config_Reference.html#tmc2240","text":"Configure a TMC2240 stepper motor driver via SPI bus or UART. To use this feature, define a config section with a \"tmc2240\" prefix followed by the name of the corresponding stepper config section (for example, \"[tmc2240 stepper_x]\"). [tmc2240 stepper_x] cs_pin: # The pin corresponding to the TMC2240 chip select line. This pin # will be set to low at the start of SPI messages and raised to high # after the message completes. This parameter must be provided. #spi_speed: #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #uart_pin: # The pin connected to the TMC2240 DIAG1/SW line. If this parameter # is provided UART communication is used rather then SPI. #chain_position: #chain_length: # These parameters configure an SPI daisy chain. The two parameters # define the stepper position in the chain and the total chain length. # Position 1 corresponds to the stepper that connects to the MOSI signal. # The default is to not use an SPI daisy chain. #interpolate: True # If true, enable step interpolation (the driver will internally # step at a rate of 256 micro-steps). The default is True. run_current: # The amount of current (in amps RMS) to configure the driver to use # during stepper movement. This parameter must be provided. #hold_current: # The amount of current (in amps RMS) to configure the driver to use # when the stepper is not moving. Setting a hold_current is not # recommended (see TMC_Drivers.md for details). The default is to # not reduce the current. #rref: 12000 # The resistance (in ohms) of the resistor between IREF and GND. The # default is 12000. #stealthchop_threshold: 0 # The velocity (in mm/s) to set the \"stealthChop\" threshold to. When # set, \"stealthChop\" mode will be enabled if the stepper motor # velocity is below this value. Note that the \"sensorless homing\" # code may temporarily override this setting during homing # operations. The default is 0, which disables \"stealthChop\" mode. #coolstep_threshold: # The velocity (in mm/s) to set the TMC driver internal \"CoolStep\" # threshold to. If set, the coolstep feature will be enabled when # the stepper motor velocity is near or above this value. Important # - if coolstep_threshold is set and \"sensorless homing\" is used, # then one must ensure that the homing speed is above the coolstep # threshold! The default is to not enable the coolstep feature. #high_velocity_threshold: # The velocity (in mm/s) to set the TMC driver internal \"high # velocity\" threshold (THIGH) to. This is typically used to disable # the \"CoolStep\" feature at high speeds. The default is to not set a # TMC \"high velocity\" threshold. #driver_MSLUT0: 2863314260 #driver_MSLUT1: 1251300522 #driver_MSLUT2: 608774441 #driver_MSLUT3: 269500962 #driver_MSLUT4: 4227858431 #driver_MSLUT5: 3048961917 #driver_MSLUT6: 1227445590 #driver_MSLUT7: 4211234 #driver_W0: 2 #driver_W1: 1 #driver_W2: 1 #driver_W3: 1 #driver_X1: 128 #driver_X2: 255 #driver_X3: 255 #driver_START_SIN: 0 #driver_START_SIN90: 247 #driver_OFFSET_SIN90: 0 # These fields control the Microstep Table registers directly. The optimal # wave table is specific to each motor and might vary with current. An # optimal configuration will have minimal print artifacts caused by # non-linear stepper movement. The values specified above are the default # values used by the driver. The value must be specified as a decimal integer # (hex form is not supported). In order to compute the wave table fields, # see the tmc2130 \"Calculation Sheet\" from the Trinamic website. # Additionally, this driver also has the OFFSET_SIN90 field which can be used # to tune a motor with unbalanced coils. See the `Sine Wave Lookup Table` # section in the datasheet for information about this field and how to tune # it. #driver_MULTISTEP_FILT: True #driver_IHOLDDELAY: 6 #driver_IRUNDELAY: 4 #driver_TPOWERDOWN: 10 #driver_TBL: 2 #driver_TOFF: 3 #driver_HEND: 2 #driver_HSTRT: 5 #driver_FD3: 0 #driver_TPFD: 4 #driver_CHM: 0 #driver_VHIGHFS: 0 #driver_VHIGHCHM: 0 #driver_DISS2G: 0 #driver_DISS2VS: 0 #driver_PWM_AUTOSCALE: True #driver_PWM_AUTOGRAD: True #driver_PWM_FREQ: 0 #driver_FREEWHEEL: 0 #driver_PWM_GRAD: 0 #driver_PWM_OFS: 29 #driver_PWM_REG: 4 #driver_PWM_LIM: 12 #driver_SGT: 0 #driver_SEMIN: 0 #driver_SEUP: 0 #driver_SEMAX: 0 #driver_SEDN: 0 #driver_SEIMIN: 0 #driver_SFILT: 0 #driver_SG4_ANGLE_OFFSET: 1 #driver_SLOPE_CONTROL: 0 # Set the given register during the configuration of the TMC2240 # chip. This may be used to set custom motor parameters. The # defaults for each parameter are next to the parameter name in the # above list. #diag0_pin: #diag1_pin: # The micro-controller pin attached to one of the DIAG lines of the # TMC2240 chip. Only a single diag pin should be specified. The pin # is \"active low\" and is thus normally prefaced with \"^!\". Setting # this creates a \"tmc2240_stepper_x:virtual_endstop\" virtual pin # which may be used as the stepper's endstop_pin. Doing this enables # \"sensorless homing\". (Be sure to also set driver_SGT to an # appropriate sensitivity value.) The default is to not enable # sensorless homing.","title":"[tmc2240]"},{"location":"Config_Reference.html#tmc5160","text":"Configure a TMC5160 stepper motor driver via SPI bus. To use this feature, define a config section with a \"tmc5160\" prefix followed by the name of the corresponding stepper config section (for example, \"[tmc5160 stepper_x]\"). [tmc5160 stepper_x] cs_pin: # The pin corresponding to the TMC5160 chip select line. This pin # will be set to low at the start of SPI messages and raised to high # after the message completes. This parameter must be provided. #spi_speed: #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #chain_position: #chain_length: # These parameters configure an SPI daisy chain. The two parameters # define the stepper position in the chain and the total chain length. # Position 1 corresponds to the stepper that connects to the MOSI signal. # The default is to not use an SPI daisy chain. #interpolate: True # If true, enable step interpolation (the driver will internally # step at a rate of 256 micro-steps). The default is True. run_current: # The amount of current (in amps RMS) to configure the driver to use # during stepper movement. This parameter must be provided. #hold_current: # The amount of current (in amps RMS) to configure the driver to use # when the stepper is not moving. Setting a hold_current is not # recommended (see TMC_Drivers.md for details). The default is to # not reduce the current. #sense_resistor: 0.075 # The resistance (in ohms) of the motor sense resistor. The default # is 0.075 ohms. #stealthchop_threshold: 0 # The velocity (in mm/s) to set the \"stealthChop\" threshold to. When # set, \"stealthChop\" mode will be enabled if the stepper motor # velocity is below this value. Note that the \"sensorless homing\" # code may temporarily override this setting during homing # operations. The default is 0, which disables \"stealthChop\" mode. #coolstep_threshold: # The velocity (in mm/s) to set the TMC driver internal \"CoolStep\" # threshold to. If set, the coolstep feature will be enabled when # the stepper motor velocity is near or above this value. Important # - if coolstep_threshold is set and \"sensorless homing\" is used, # then one must ensure that the homing speed is above the coolstep # threshold! The default is to not enable the coolstep feature. #high_velocity_threshold: # The velocity (in mm/s) to set the TMC driver internal \"high # velocity\" threshold (THIGH) to. This is typically used to disable # the \"CoolStep\" feature at high speeds. The default is to not set a # TMC \"high velocity\" threshold. #driver_MSLUT0: 2863314260 #driver_MSLUT1: 1251300522 #driver_MSLUT2: 608774441 #driver_MSLUT3: 269500962 #driver_MSLUT4: 4227858431 #driver_MSLUT5: 3048961917 #driver_MSLUT6: 1227445590 #driver_MSLUT7: 4211234 #driver_W0: 2 #driver_W1: 1 #driver_W2: 1 #driver_W3: 1 #driver_X1: 128 #driver_X2: 255 #driver_X3: 255 #driver_START_SIN: 0 #driver_START_SIN90: 247 # These fields control the Microstep Table registers directly. The optimal # wave table is specific to each motor and might vary with current. An # optimal configuration will have minimal print artifacts caused by # non-linear stepper movement. The values specified above are the default # values used by the driver. The value must be specified as a decimal integer # (hex form is not supported). In order to compute the wave table fields, # see the tmc2130 \"Calculation Sheet\" from the Trinamic website. #driver_MULTISTEP_FILT: True #driver_IHOLDDELAY: 6 #driver_TPOWERDOWN: 10 #driver_TBL: 2 #driver_TOFF: 3 #driver_HEND: 2 #driver_HSTRT: 5 #driver_FD3: 0 #driver_TPFD: 4 #driver_CHM: 0 #driver_VHIGHFS: 0 #driver_VHIGHCHM: 0 #driver_DISS2G: 0 #driver_DISS2VS: 0 #driver_PWM_AUTOSCALE: True #driver_PWM_AUTOGRAD: True #driver_PWM_FREQ: 0 #driver_FREEWHEEL: 0 #driver_PWM_GRAD: 0 #driver_PWM_OFS: 30 #driver_PWM_REG: 4 #driver_PWM_LIM: 12 #driver_SGT: 0 #driver_SEMIN: 0 #driver_SEUP: 0 #driver_SEMAX: 0 #driver_SEDN: 0 #driver_SEIMIN: 0 #driver_SFILT: 0 #driver_DRVSTRENGTH: 0 #driver_BBMCLKS: 4 #driver_BBMTIME: 0 #driver_FILT_ISENSE: 0 # Set the given register during the configuration of the TMC5160 # chip. This may be used to set custom motor parameters. The # defaults for each parameter are next to the parameter name in the # above list. #diag0_pin: #diag1_pin: # The micro-controller pin attached to one of the DIAG lines of the # TMC5160 chip. Only a single diag pin should be specified. The pin # is \"active low\" and is thus normally prefaced with \"^!\". Setting # this creates a \"tmc5160_stepper_x:virtual_endstop\" virtual pin # which may be used as the stepper's endstop_pin. Doing this enables # \"sensorless homing\". (Be sure to also set driver_SGT to an # appropriate sensitivity value.) The default is to not enable # sensorless homing.","title":"[tmc5160]"},{"location":"Config_Reference.html#run-time-stepper-motor-current-configuration","text":"","title":"Run-time stepper motor current configuration"},{"location":"Config_Reference.html#ad5206","text":"Statically configured AD5206 digipots connected via SPI bus (one may define any number of sections with an \"ad5206\" prefix). [ad5206 my_digipot] enable_pin: # The pin corresponding to the AD5206 chip select line. This pin # will be set to low at the start of SPI messages and raised to high # after the message completes. This parameter must be provided. #spi_speed: #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #channel_1: #channel_2: #channel_3: #channel_4: #channel_5: #channel_6: # The value to statically set the given AD5206 channel to. This is # typically set to a number between 0.0 and 1.0 with 1.0 being the # highest resistance and 0.0 being the lowest resistance. However, # the range may be changed with the 'scale' parameter (see below). # If a channel is not specified then it is left unconfigured. #scale: # This parameter can be used to alter how the 'channel_x' parameters # are interpreted. If provided, then the 'channel_x' parameters # should be between 0.0 and 'scale'. This may be useful when the # AD5206 is used to set stepper voltage references. The 'scale' can # be set to the equivalent stepper amperage if the AD5206 were at # its highest resistance, and then the 'channel_x' parameters can be # specified using the desired amperage value for the stepper. The # default is to not scale the 'channel_x' parameters.","title":"[ad5206]"},{"location":"Config_Reference.html#mcp4451","text":"Statically configured MCP4451 digipot connected via I2C bus (one may define any number of sections with an \"mcp4451\" prefix). [mcp4451 my_digipot] i2c_address: # The i2c address that the chip is using on the i2c bus. This # parameter must be provided. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #wiper_0: #wiper_1: #wiper_2: #wiper_3: # The value to statically set the given MCP4451 \"wiper\" to. This is # typically set to a number between 0.0 and 1.0 with 1.0 being the # highest resistance and 0.0 being the lowest resistance. However, # the range may be changed with the 'scale' parameter (see below). # If a wiper is not specified then it is left unconfigured. #scale: # This parameter can be used to alter how the 'wiper_x' parameters # are interpreted. If provided, then the 'wiper_x' parameters should # be between 0.0 and 'scale'. This may be useful when the MCP4451 is # used to set stepper voltage references. The 'scale' can be set to # the equivalent stepper amperage if the MCP4451 were at its highest # resistance, and then the 'wiper_x' parameters can be specified # using the desired amperage value for the stepper. The default is # to not scale the 'wiper_x' parameters.","title":"[mcp4451]"},{"location":"Config_Reference.html#mcp4728","text":"Statically configured MCP4728 digital-to-analog converter connected via I2C bus (one may define any number of sections with an \"mcp4728\" prefix). [mcp4728 my_dac] #i2c_address: 96 # The i2c address that the chip is using on the i2c bus. The default # is 96. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #channel_a: #channel_b: #channel_c: #channel_d: # The value to statically set the given MCP4728 channel to. This is # typically set to a number between 0.0 and 1.0 with 1.0 being the # highest voltage (2.048V) and 0.0 being the lowest voltage. # However, the range may be changed with the 'scale' parameter (see # below). If a channel is not specified then it is left # unconfigured. #scale: # This parameter can be used to alter how the 'channel_x' parameters # are interpreted. If provided, then the 'channel_x' parameters # should be between 0.0 and 'scale'. This may be useful when the # MCP4728 is used to set stepper voltage references. The 'scale' can # be set to the equivalent stepper amperage if the MCP4728 were at # its highest voltage (2.048V), and then the 'channel_x' parameters # can be specified using the desired amperage value for the # stepper. The default is to not scale the 'channel_x' parameters.","title":"[mcp4728]"},{"location":"Config_Reference.html#mcp4018","text":"Statically configured MCP4018 digipot connected via i2c (one may define any number of sections with an \"mcp4018\" prefix). [mcp4018 my_digipot] #i2c_address: 47 # The i2c address that the chip is using on the i2c bus. The default # is 47. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. wiper: # The value to statically set the given MCP4018 \"wiper\" to. This is # typically set to a number between 0.0 and 1.0 with 1.0 being the # highest resistance and 0.0 being the lowest resistance. However, # the range may be changed with the 'scale' parameter (see below). # This parameter must be provided. #scale: # This parameter can be used to alter how the 'wiper' parameter is # interpreted. If provided, then the 'wiper' parameter should be # between 0.0 and 'scale'. This may be useful when the MCP4018 is # used to set stepper voltage references. The 'scale' can be set to # the equivalent stepper amperage if the MCP4018 is at its highest # resistance, and then the 'wiper' parameter can be specified using # the desired amperage value for the stepper. The default is to not # scale the 'wiper' parameter.","title":"[mcp4018]"},{"location":"Config_Reference.html#display-support","text":"","title":"Display support"},{"location":"Config_Reference.html#display","text":"Support for a display attached to the micro-controller. [display] lcd_type: # The type of LCD chip in use. This may be \"hd44780\", \"hd44780_spi\", # \"aip31068_spi\", \"st7920\", \"emulated_st7920\", \"uc1701\", \"ssd1306\", or # \"sh1106\". # See the display sections below for information on each type and # additional parameters they provide. This parameter must be # provided. #display_group: # The name of the display_data group to show on the display. This # controls the content of the screen (see the \"display_data\" section # for more information). The default is _default_20x4 for hd44780 or # aip31068_spi displays and _default_16x4 for other displays. #menu_timeout: # Timeout for menu. Being inactive this amount of seconds will # trigger menu exit or return to root menu when having autorun # enabled. The default is 0 seconds (disabled) #menu_root: # Name of the main menu section to show when clicking the encoder # on the home screen. The defaults is __main, and this shows the # the default menus as defined in klippy/extras/display/menu.cfg #menu_reverse_navigation: # When enabled it will reverse up and down directions for list # navigation. The default is False. This parameter is optional. #encoder_pins: # The pins connected to encoder. 2 pins must be provided when using # encoder. This parameter must be provided when using menu. #encoder_steps_per_detent: # How many steps the encoder emits per detent (\"click\"). If the # encoder takes two detents to move between entries or moves two # entries from one detent, try changing this. Allowed values are 2 # (half-stepping) or 4 (full-stepping). The default is 4. #click_pin: # The pin connected to 'enter' button or encoder 'click'. This # parameter must be provided when using menu. The presence of an # 'analog_range_click_pin' config parameter turns this parameter # from digital to analog. #back_pin: # The pin connected to 'back' button. This parameter is optional, # menu can be used without it. The presence of an # 'analog_range_back_pin' config parameter turns this parameter from # digital to analog. #up_pin: # The pin connected to 'up' button. This parameter must be provided # when using menu without encoder. The presence of an # 'analog_range_up_pin' config parameter turns this parameter from # digital to analog. #down_pin: # The pin connected to 'down' button. This parameter must be # provided when using menu without encoder. The presence of an # 'analog_range_down_pin' config parameter turns this parameter from # digital to analog. #kill_pin: # The pin connected to 'kill' button. This button will call # emergency stop. The presence of an 'analog_range_kill_pin' config # parameter turns this parameter from digital to analog. #analog_pullup_resistor: 4700 # The resistance (in ohms) of the pullup attached to the analog # button. The default is 4700 ohms. #analog_range_click_pin: # The resistance range for a 'enter' button. Range minimum and # maximum comma-separated values must be provided when using analog # button. #analog_range_back_pin: # The resistance range for a 'back' button. Range minimum and # maximum comma-separated values must be provided when using analog # button. #analog_range_up_pin: # The resistance range for a 'up' button. Range minimum and maximum # comma-separated values must be provided when using analog button. #analog_range_down_pin: # The resistance range for a 'down' button. Range minimum and # maximum comma-separated values must be provided when using analog # button. #analog_range_kill_pin: # The resistance range for a 'kill' button. Range minimum and # maximum comma-separated values must be provided when using analog # button.","title":"[display]"},{"location":"Config_Reference.html#hd44780-display","text":"Information on configuring hd44780 displays (which is used in \"RepRapDiscount 2004 Smart Controller\" type displays). [display] lcd_type: hd44780 # Set to \"hd44780\" for hd44780 displays. rs_pin: e_pin: d4_pin: d5_pin: d6_pin: d7_pin: # The pins connected to an hd44780 type lcd. These parameters must # be provided. #hd44780_protocol_init: True # Perform 8-bit/4-bit protocol initialization on an hd44780 display. # This is necessary on real hd44780 devices. However, one may need # to disable this on some \"clone\" devices. The default is True. #line_length: # Set the number of characters per line for an hd44780 type lcd. # Possible values are 20 (default) and 16. The number of lines is # fixed to 4. ...","title":"hd44780 display"},{"location":"Config_Reference.html#hd44780_spi-display","text":"Information on configuring an hd44780_spi display - a 20x04 display controlled via a hardware \"shift register\" (which is used in mightyboard based printers). [display] lcd_type: hd44780_spi # Set to \"hd44780_spi\" for hd44780_spi displays. latch_pin: spi_software_sclk_pin: spi_software_mosi_pin: spi_software_miso_pin: # The pins connected to the shift register controlling the display. # The spi_software_miso_pin needs to be set to an unused pin of the # printer mainboard as the shift register does not have a MISO pin, # but the software spi implementation requires this pin to be # configured. #hd44780_protocol_init: True # Perform 8-bit/4-bit protocol initialization on an hd44780 display. # This is necessary on real hd44780 devices. However, one may need # to disable this on some \"clone\" devices. The default is True. #line_length: # Set the number of characters per line for an hd44780 type lcd. # Possible values are 20 (default) and 16. The number of lines is # fixed to 4. ...","title":"hd44780_spi display"},{"location":"Config_Reference.html#aip31068_spi-display","text":"Information on configuring an aip31068_spi display - a very similar to hd44780_spi a 20x04 (20 symbols by 4 lines) display with slightly different internal protocol. [display] lcd_type: aip31068_spi latch_pin: spi_software_sclk_pin: spi_software_mosi_pin: spi_software_miso_pin: # The pins connected to the shift register controlling the display. # The spi_software_miso_pin needs to be set to an unused pin of the # printer mainboard as the shift register does not have a MISO pin, # but the software spi implementation requires this pin to be # configured. #line_length: # Set the number of characters per line for an hd44780 type lcd. # Possible values are 20 (default) and 16. The number of lines is # fixed to 4. ...","title":"aip31068_spi display"},{"location":"Config_Reference.html#st7920-display","text":"Information on configuring st7920 displays (which is used in \"RepRapDiscount 12864 Full Graphic Smart Controller\" type displays). [display] lcd_type: st7920 # Set to \"st7920\" for st7920 displays. cs_pin: sclk_pin: sid_pin: # The pins connected to an st7920 type lcd. These parameters must be # provided. ...","title":"st7920 display"},{"location":"Config_Reference.html#emulated_st7920-display","text":"Information on configuring an emulated st7920 display - found in some \"2.4 inch touchscreen devices\" and similar. [display] lcd_type: emulated_st7920 # Set to \"emulated_st7920\" for emulated_st7920 displays. en_pin: spi_software_sclk_pin: spi_software_mosi_pin: spi_software_miso_pin: # The pins connected to an emulated_st7920 type lcd. The en_pin # corresponds to the cs_pin of the st7920 type lcd, # spi_software_sclk_pin corresponds to sclk_pin and # spi_software_mosi_pin corresponds to sid_pin. The # spi_software_miso_pin needs to be set to an unused pin of the # printer mainboard as the st7920 as no MISO pin but the software # spi implementation requires this pin to be configured. ...","title":"emulated_st7920 display"},{"location":"Config_Reference.html#uc1701-display","text":"Information on configuring uc1701 displays (which is used in \"MKS Mini 12864\" type displays). [display] lcd_type: uc1701 # Set to \"uc1701\" for uc1701 displays. cs_pin: a0_pin: # The pins connected to a uc1701 type lcd. These parameters must be # provided. #rst_pin: # The pin connected to the \"rst\" pin on the lcd. If it is not # specified then the hardware must have a pull-up on the # corresponding lcd line. #contrast: # The contrast to set. The value may range from 0 to 63 and the # default is 40. ...","title":"uc1701 display"},{"location":"Config_Reference.html#ssd1306-and-sh1106-displays","text":"Information on configuring ssd1306 and sh1106 displays. [display] lcd_type: # Set to either \"ssd1306\" or \"sh1106\" for the given display type. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # Optional parameters available for displays connected via an i2c # bus. See the \"common I2C settings\" section for a description of # the above parameters. #cs_pin: #dc_pin: #spi_speed: #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # The pins connected to the lcd when in \"4-wire\" spi mode. See the # \"common SPI settings\" section for a description of the parameters # that start with \"spi_\". The default is to use i2c mode for the # display. #reset_pin: # A reset pin may be specified on the display. If it is not # specified then the hardware must have a pull-up on the # corresponding lcd line. #contrast: # The contrast to set. The value may range from 0 to 256 and the # default is 239. #vcomh: 0 # Set the Vcomh value on the display. This value is associated with # a \"smearing\" effect on some OLED displays. The value may range # from 0 to 63. Default is 0. #invert: False # TRUE inverts the pixels on certain OLED displays. The default is # False. #x_offset: 0 # Set the horizontal offset value on SH1106 displays. The default is # 0. ...","title":"ssd1306 and sh1106 displays"},{"location":"Config_Reference.html#display_data","text":"Support for displaying custom data on an lcd screen. One may create any number of display groups and any number of data items under those groups. The display will show all the data items for a given group if the display_group option in the [display] section is set to the given group name. A default set of display groups are automatically created. One can replace or extend these display_data items by overriding the defaults in the main printer.cfg config file. [display_data my_group_name my_data_name] position: # Comma separated row and column of the display position that should # be used to display the information. This parameter must be # provided. text: # The text to show at the given position. This field is evaluated # using command templates (see docs/Command_Templates.md). This # parameter must be provided.","title":"[display_data]"},{"location":"Config_Reference.html#display_template","text":"Display data text \"macros\" (one may define any number of sections with a display_template prefix). See the command templates document for information on template evaluation. This feature allows one to reduce repetitive definitions in display_data sections. One may use the builtin render() function in display_data sections to evaluate a template. For example, if one were to define [display_template my_template] then one could use { render('my_template') } in a display_data section. This feature can also be used for continuous LED updates using the SET_LED_TEMPLATE command. [display_template my_template_name] #param_<name>: # One may specify any number of options with a \"param_\" prefix. The # given name will be assigned the given value (parsed as a Python # literal) and will be available during macro expansion. If the # parameter is passed in the call to render() then that value will # be used during macro expansion. For example, a config with # \"param_speed = 75\" might have a caller with # \"render('my_template_name', param_speed=80)\". Parameter names may # not use upper case characters. text: # The text to return when the this template is rendered. This field # is evaluated using command templates (see # docs/Command_Templates.md). This parameter must be provided.","title":"[display_template]"},{"location":"Config_Reference.html#display_glyph","text":"Display a custom glyph on displays that support it. The given name will be assigned the given display data which can then be referenced in the display templates by their name surrounded by two \"tilde\" symbols i.e. ~my_display_glyph~ See sample-glyphs.cfg for some examples. [display_glyph my_display_glyph] #data: # The display data, stored as 16 lines consisting of 16 bits (1 per # pixel) where '.' is a blank pixel and '*' is an on pixel (e.g., # \"****************\" to display a solid horizontal line). # Alternatively, one can use '0' for a blank pixel and '1' for an on # pixel. Put each display line into a separate config line. The # glyph must consist of exactly 16 lines with 16 bits each. This # parameter is optional. #hd44780_data: # Glyph to use on 20x4 hd44780 displays. The glyph must consist of # exactly 8 lines with 5 bits each. This parameter is optional. #hd44780_slot: # The hd44780 hardware index (0..7) to store the glyph at. If # multiple distinct images use the same slot then make sure to only # use one of those images in any given screen. This parameter is # required if hd44780_data is specified.","title":"[display_glyph]"},{"location":"Config_Reference.html#display-my_extra_display","text":"If a primary [display] section has been defined in printer.cfg as shown above it is possible to define multiple auxiliary displays. Note that auxiliary displays do not currently support menu functionality, thus they do not support the \"menu\" options or button configuration. [display my_extra_display] # See the \"display\" section for available parameters.","title":"[display my_extra_display]"},{"location":"Config_Reference.html#menu","text":"Customizable lcd display menus. A default set of menus are automatically created. One can replace or extend the menu by overriding the defaults in the main printer.cfg config file. See the command template document for information on menu attributes available during template rendering. # Common parameters available for all menu config sections. #[menu __some_list __some_name] #type: disabled # Permanently disabled menu element, only required attribute is 'type'. # Allows you to easily disable/hide existing menu items. #[menu some_name] #type: # One of command, input, list, text: # command - basic menu element with various script triggers # input - same like 'command' but has value changing capabilities. # Press will start/stop edit mode. # list - it allows for menu items to be grouped together in a # scrollable list. Add to the list by creating menu # configurations using \"some_list\" as a prefix - for # example: [menu some_list some_item_in_the_list] # vsdlist - same as 'list' but will append files from virtual sdcard # (will be removed in the future) #name: # Name of menu item - evaluated as a template. #enable: # Template that evaluates to True or False. #index: # Position where an item needs to be inserted in list. By default # the item is added at the end. #[menu some_list] #type: list #name: #enable: # See above for a description of these parameters. #[menu some_list some_command] #type: command #name: #enable: # See above for a description of these parameters. #gcode: # Script to run on button click or long click. Evaluated as a # template. #[menu some_list some_input] #type: input #name: #enable: # See above for a description of these parameters. #input: # Initial value to use when editing - evaluated as a template. # Result must be float. #input_min: # Minimum value of range - evaluated as a template. Default -99999. #input_max: # Maximum value of range - evaluated as a template. Default 99999. #input_step: # Editing step - Must be a positive integer or float value. It has # internal fast rate step. When \"(input_max - input_min) / # input_step > 100\" then fast rate step is 10 * input_step else fast # rate step is same input_step. #realtime: # This attribute accepts static boolean value. When enabled then # gcode script is run after each value change. The default is False. #gcode: # Script to run on button click, long click or value change. # Evaluated as a template. The button click will trigger the edit # mode start or end.","title":"[menu]"},{"location":"Config_Reference.html#filament-sensors","text":"","title":"Filament sensors"},{"location":"Config_Reference.html#filament_switch_sensor","text":"Filament Switch Sensor. Support for filament insert and runout detection using a switch sensor, such as an endstop switch. See the command reference for more information. [filament_switch_sensor my_sensor] #pause_on_runout: True # When set to True, a PAUSE will execute immediately after a runout # is detected. Note that if pause_on_runout is False and the # runout_gcode is omitted then runout detection is disabled. Default # is True. #runout_gcode: # A list of G-Code commands to execute after a filament runout is # detected. See docs/Command_Templates.md for G-Code format. If # pause_on_runout is set to True this G-Code will run after the # PAUSE is complete. The default is not to run any G-Code commands. #insert_gcode: # A list of G-Code commands to execute after a filament insert is # detected. See docs/Command_Templates.md for G-Code format. The # default is not to run any G-Code commands, which disables insert # detection. #event_delay: 3.0 # The minimum amount of time in seconds to delay between events. # Events triggered during this time period will be silently # ignored. The default is 3 seconds. #pause_delay: 0.5 # The amount of time to delay, in seconds, between the pause command # dispatch and execution of the runout_gcode. It may be useful to # increase this delay if OctoPrint exhibits strange pause behavior. # Default is 0.5 seconds. #debounce_delay: # A period of time in seconds to debounce events prior to running the # switch gcode. The switch must he held in a single state for at least # this long to activate. If the switch is toggled on/off during this delay, # the event is ignored. Default is 0. #switch_pin: # The pin on which the switch is connected. This parameter must be # provided.","title":"[filament_switch_sensor]"},{"location":"Config_Reference.html#filament_motion_sensor","text":"Filament Motion Sensor. Support for filament insert and runout detection using an encoder that toggles the output pin during filament movement through the sensor. See the command reference for more information. [filament_motion_sensor my_sensor] detection_length: 7.0 # The minimum length of filament pulled through the sensor to trigger # a state change on the switch_pin # Default is 7 mm. extruder: # The name of the extruder or extruder_stepper section this sensor # is associated with. This parameter must be provided. switch_pin: #pause_on_runout: #runout_gcode: #insert_gcode: #event_delay: #pause_delay: # See the \"filament_switch_sensor\" section for a description of the # above parameters.","title":"[filament_motion_sensor]"},{"location":"Config_Reference.html#tsl1401cl_filament_width_sensor","text":"TSLl401CL Based Filament Width Sensor. See the guide for more information. [tsl1401cl_filament_width_sensor] #pin: #default_nominal_filament_diameter: 1.75 # (mm) # Maximum allowed filament diameter difference as mm. #max_difference: 0.2 # The distance from sensor to the melting chamber as mm. #measurement_delay: 100","title":"[tsl1401cl_filament_width_sensor]"},{"location":"Config_Reference.html#hall_filament_width_sensor","text":"Hall filament width sensor (see Hall Filament Width Sensor ). [hall_filament_width_sensor] adc1: adc2: # Analog input pins connected to the sensor. These parameters must # be provided. #cal_dia1: 1.50 #cal_dia2: 2.00 # The calibration values (in mm) for the sensors. The default is # 1.50 for cal_dia1 and 2.00 for cal_dia2. #raw_dia1: 9500 #raw_dia2: 10500 # The raw calibration values for the sensors. The default is 9500 # for raw_dia1 and 10500 for raw_dia2. #default_nominal_filament_diameter: 1.75 # The nominal filament diameter. This parameter must be provided. #max_difference: 0.200 # Maximum allowed filament diameter difference in millimeters (mm). # If difference between nominal filament diameter and sensor output # is more than +- max_difference, extrusion multiplier is set back # to %100. The default is 0.200. #measurement_delay: 70 # The distance from sensor to the melting chamber/hot-end in # millimeters (mm). The filament between the sensor and the hot-end # will be treated as the default_nominal_filament_diameter. Host # module works with FIFO logic. It keeps each sensor value and # position in an array and POP them back in correct position. This # parameter must be provided. #enable: False # Sensor enabled or disabled after power on. The default is to # disable. #measurement_interval: 10 # The approximate distance (in mm) between sensor readings. The # default is 10mm. #logging: False # Out diameter to terminal and klipper.log can be turn on|of by # command. #min_diameter: 1.0 # Minimal diameter for trigger virtual filament_switch_sensor. #max_diameter: # Maximum diameter for triggering virtual filament_switch_sensor. # The default is default_nominal_filament_diameter + max_difference. #use_current_dia_while_delay: False # Use the current diameter instead of the nominal diameter while # the measurement delay has not run through. #pause_on_runout: #runout_gcode: #insert_gcode: #event_delay: #pause_delay: # See the \"filament_switch_sensor\" section for a description of the # above parameters.","title":"[hall_filament_width_sensor]"},{"location":"Config_Reference.html#load-cells","text":"","title":"Load Cells"},{"location":"Config_Reference.html#load_cell","text":"Load Cell. Uses an ADC sensor attached to a load cell to create a digital scale. [load_cell] sensor_type: # This must be one of the supported sensor types, see below. #counts_per_gram: # The floating point number of sensor counts that indicates 1 gram of force. # This value is calculated by the LOAD_CELL_CALIBRATE command. #reference_tare_counts: # The integer tare value, in raw sensor counts, taken when LOAD_CELL_CALIBRATE # is run. This is the default tare value when klipper starts up. #sensor_orientation: # Change the sensor's orientation. Can be either 'normal' or 'inverted'. # The default is 'normal'. Use 'inverted' if the sensor reports a # decreasing force value when placed under load.","title":"[load_cell]"},{"location":"Config_Reference.html#hx711","text":"This is a 24 bit low sample rate chip using \"bit-bang\" communications. It is suitable for filament scales. [load_cell] sensor_type: hx711 sclk_pin: # The pin connected to the HX711 clock line. This parameter must be provided. dout_pin: # The pin connected to the HX711 data output line. This parameter must be # provided. #gain: A-128 # Valid values for gain are: A-128, A-64, B-32. The default is A-128. # 'A' denotes the input channel and the number denotes the gain. Only the 3 # listed combinations are supported by the chip. Note that changing the gain # setting also selects the channel being read. #sample_rate: 80 # Valid values for sample_rate are 80 or 10. The default value is 80. # This must match the wiring of the chip. The sample rate cannot be changed # in software.","title":"HX711"},{"location":"Config_Reference.html#hx717","text":"This is the 4x higher sample rate version of the HX711, suitable for probing. [load_cell] sensor_type: hx717 sclk_pin: # The pin connected to the HX717 clock line. This parameter must be provided. dout_pin: # The pin connected to the HX717 data output line. This parameter must be # provided. #gain: A-128 # Valid values for gain are A-128, B-64, A-64, B-8. # 'A' denotes the input channel and the number denotes the gain setting. # Only the 4 listed combinations are supported by the chip. Note that # changing the gain setting also selects the channel being read. #sample_rate: 320 # Valid values for sample_rate are: 10, 20, 80, 320. The default is 320. # This must match the wiring of the chip. The sample rate cannot be changed # in software.","title":"HX717"},{"location":"Config_Reference.html#ads1220","text":"The ADS1220 is a 24 bit ADC supporting up to a 2Khz sample rate configurable in software. [load_cell] sensor_type: ads1220 cs_pin: # The pin connected to the ADS1220 chip select line. This parameter must # be provided. #spi_speed: 512000 # This chip supports 2 speeds: 256000 or 512000. The faster speed is only # enabled when one of the Turbo sample rates is used. The correct spi_speed # is selected based on the sample rate. #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. data_ready_pin: # Pin connected to the ADS1220 data ready line. This parameter must be # provided. #gain: 128 # Valid gain values are 128, 64, 32, 16, 8, 4, 2, 1 # The default is 128 #pga_bypass: False # Disable the internal Programmable Gain Amplifier. If # True the PGA will be disabled for gains 1, 2, and 4. The PGA is always # enabled for gain settings 8 to 128, regardless of the pga_bypass setting. # If AVSS is used as an input pga_bypass is forced to True. # The default is False. #sample_rate: 660 # This chip supports two ranges of sample rates, Normal and Turbo. In turbo # mode the chip's internal clock runs twice as fast and the SPI communication # speed is also doubled. # Normal sample rates: 20, 45, 90, 175, 330, 600, 1000 # Turbo sample rates: 40, 90, 180, 350, 660, 1200, 2000 # The default is 660 #input_mux: # Input multiplexer configuration, select a pair of pins to use. The first pin # is the positive, AINP, and the second pin is the negative, AINN. Valid # values are: 'AIN0_AIN1', 'AIN0_AIN2', 'AIN0_AIN3', 'AIN1_AIN2', 'AIN1_AIN3', # 'AIN2_AIN3', 'AIN1_AIN0', 'AIN3_AIN2', 'AIN0_AVSS', 'AIN1_AVSS', 'AIN2_AVSS' # and 'AIN3_AVSS'. If AVSS is used the PGA is bypassed and the pga_bypass # setting will be forced to True. # The default is AIN0_AIN1. #vref: # The selected voltage reference. Valid values are: 'internal', 'REF0', 'REF1' # and 'analog_supply'. Default is 'internal'.","title":"ADS1220"},{"location":"Config_Reference.html#load_cell_probe","text":"Load Cell Probe. This combines the functionality of a [probe] and a [load_cell]. [load_cell_probe] sensor_type: # This must be one of the supported bulk ADC sensor types and support # load cell endstops on the mcu. #counts_per_gram: #reference_tare_counts: #sensor_orientation: # These parameters must be configured before the probe will operate. # See the [load_cell] section for further details. #force_safety_limit: 2000 # The safe limit for probing force relative to the reference_tare_counts on # the load_cell. The default is +/-2Kg. #trigger_force: 75.0 # The force that the probe will trigger at. 75g is the default. #drift_filter_cutoff_frequency: 0.8 # Enable optional continuous taring while homing & probing to reject drift. # The value is a frequency, in Hz, below which drift will be ignored. This # option requires the SciPy library. Default: None #drift_filter_delay: 2 # The delay, or 'order', of the drift filter. This controls the number of # samples required to make a trigger detection. Can be 1 or 2, the default # is 2. #buzz_filter_cutoff_frequency: 100.0 # The value is a frequency, in Hz, above which high frequency noise in the # load cell will be igfiltered outnored. This option requires the SciPy # library. Default: None #buzz_filter_delay: 2 # The delay, or 'order', of the buzz filter. This controls the number of # samples required to make a trigger detection. Can be 1 or 2, the default # is 2. #notch_filter_frequencies: 50, 60 # 1 or 2 frequencies, in Hz, to filter out of the load cell data. This is # intended to reject power line noise. This option requires the SciPy # library. Default: None #notch_filter_quality: 2.0 # Controls how narrow the range of frequencies are that the notch filter # removes. Larger numbers produce a narrower filter. Minimum value is 0.5 and # maximum is 3.0. Default: 2.0 #tare_time: # The rime in seconds used for taring the load_cell before each probe. The # default value is: 4 / 60 = 0.066. This collects samples from 4 cycles of # 60Hz mains power to cancel power line noise. #z_offset: #speed: #samples: #sample_retract_dist: #lift_speed: #samples_result: #samples_tolerance: #samples_tolerance_retries: #activate_gcode: #deactivate_gcode: # See the \"[probe]\" section for a description of the above parameters.","title":"[load_cell_probe]"},{"location":"Config_Reference.html#board-specific-hardware-support","text":"","title":"Board specific hardware support"},{"location":"Config_Reference.html#sx1509","text":"Configure an SX1509 I2C to GPIO expander. Due to the delay incurred by I2C communication you should NOT use SX1509 pins as stepper enable, step or dir pins or any other pin that requires fast bit-banging. They are best used as static or gcode controlled digital outputs or hardware-pwm pins for e.g. fans. One may define any number of sections with an \"sx1509\" prefix. Each expander provides a set of 16 pins (sx1509_my_sx1509:PIN_0 to sx1509_my_sx1509:PIN_15) which can be used in the printer configuration. See the generic-duet2-duex.cfg file for an example. [sx1509 my_sx1509] i2c_address: # I2C address used by this expander. Depending on the hardware # jumpers this is one out of the following addresses: 62 63 112 # 113. This parameter must be provided. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters.","title":"[sx1509]"},{"location":"Config_Reference.html#samd_sercom","text":"SAMD SERCOM configuration to specify which pins to use on a given SERCOM. One may define any number of sections with a \"samd_sercom\" prefix. Each SERCOM must be configured prior to using it as SPI or I2C peripheral. Place this config section above any other section that makes use of SPI or I2C buses. [samd_sercom my_sercom] sercom: # The name of the sercom bus to configure in the micro-controller. # Available names are \"sercom0\", \"sercom1\", etc.. This parameter # must be provided. tx_pin: # MOSI pin for SPI communication, or SDA (data) pin for I2C # communication. The pin must have a valid pinmux configuration # for the given SERCOM peripheral. This parameter must be provided. #rx_pin: # MISO pin for SPI communication. This pin is not used for I2C # communication (I2C uses tx_pin for both sending and receiving). # The pin must have a valid pinmux configuration for the given # SERCOM peripheral. This parameter is optional. clk_pin: # CLK pin for SPI communication, or SCL (clock) pin for I2C # communication. The pin must have a valid pinmux configuration # for the given SERCOM peripheral. This parameter must be provided.","title":"[samd_sercom]"},{"location":"Config_Reference.html#adc_scaled","text":"Duet2 Maestro analog scaling by vref and vssa readings. Defining an adc_scaled section enables virtual adc pins (such as \"my_name:PB0\") that are automatically adjusted by the board's vref and vssa monitoring pins. Be sure to define this config section above any config sections that use one these virtual pins. See the generic-duet2-maestro.cfg file for an example. [adc_scaled my_name] vref_pin: # The ADC pin to use for VREF monitoring. This parameter must be # provided. vssa_pin: # The ADC pin to use for VSSA monitoring. This parameter must be # provided. #smooth_time: 2.0 # A time value (in seconds) over which the vref and vssa # measurements will be smoothed to reduce the impact of measurement # noise. The default is 2 seconds.","title":"[adc_scaled]"},{"location":"Config_Reference.html#ads1x1x","text":"ADS1013, ADS1014, ADS1015, ADS1113, ADS1114 and ADS1115 are I2C based Analog to Digital Converters that can be used for temperature sensors. They provide 4 analog input pins either as single line or as differential input. Note: Use caution if using this sensor to control heaters. The heater min_temp and max_temp are only verified in the host and only if the host is running and operating normally. (ADC inputs directly connected to the micro-controller verify min_temp and max_temp within the micro-controller and do not require a working connection to the host.) [ads1x1x my_ads1x1x] chip: ADS1115 #pga: 4.096V # Default value is 4.096V. The maximum voltage range used for the input. This # scales all values read from the ADC. Options are: 6.144V, 4.096V, 2.048V, # 1.024V, 0.512V, 0.256V #adc_voltage: 3.3 # The supply voltage for the device. This allows additional software scaling # for all values read from the ADC. i2c_mcu: host i2c_bus: i2c.1 #address_pin: GND # Default value is GND. There can be up to four addressed devices depending # upon wiring of the device. Check the datasheet for details. The i2c_address # can be specified directly instead of using the address_pin. The chip provides pins that can be used on other sensors. sensor_type: ... # Can be any thermistor or adc_temperature. sensor_pin: my_ads1x1x:AIN0 # A combination of the name of the ads1x1x chip and the pin. Possible # pin values are AIN0, AIN1, AIN2 and AIN3 for single ended lines and # DIFF01, DIFF03, DIFF13 and DIFF23 for differential between their # corresponding lines. For example # DIFF03 measures the differential between line 0 and 3. Only specific # combinations for the differentials are allowed.","title":"[ads1x1x]"},{"location":"Config_Reference.html#replicape","text":"Replicape support - see the beaglebone guide and the generic-replicape.cfg file for an example. # The \"replicape\" config section adds \"replicape:stepper_x_enable\" # virtual stepper enable pins (for steppers X, Y, Z, E, and H) and # \"replicape:power_x\" PWM output pins (for hotbed, e, h, fan0, fan1, # fan2, and fan3) that may then be used elsewhere in the config file. [replicape] revision: # The replicape hardware revision. Currently only revision \"B3\" is # supported. This parameter must be provided. #enable_pin: !gpio0_20 # The replicape global enable pin. The default is !gpio0_20 (aka # P9_41). host_mcu: # The name of the mcu config section that communicates with the # Klipper \"linux process\" mcu instance. This parameter must be # provided. #standstill_power_down: False # This parameter controls the CFG6_ENN line on all stepper # motors. True sets the enable lines to \"open\". The default is # False. #stepper_x_microstep_mode: #stepper_y_microstep_mode: #stepper_z_microstep_mode: #stepper_e_microstep_mode: #stepper_h_microstep_mode: # This parameter controls the CFG1 and CFG2 pins of the given # stepper motor driver. Available options are: disable, 1, 2, # spread2, 4, 16, spread4, spread16, stealth4, and stealth16. The # default is disable. #stepper_x_current: #stepper_y_current: #stepper_z_current: #stepper_e_current: #stepper_h_current: # The configured maximum current (in Amps) of the stepper motor # driver. This parameter must be provided if the stepper is not in a # disable mode. #stepper_x_chopper_off_time_high: #stepper_y_chopper_off_time_high: #stepper_z_chopper_off_time_high: #stepper_e_chopper_off_time_high: #stepper_h_chopper_off_time_high: # This parameter controls the CFG0 pin of the stepper motor driver # (True sets CFG0 high, False sets it low). The default is False. #stepper_x_chopper_hysteresis_high: #stepper_y_chopper_hysteresis_high: #stepper_z_chopper_hysteresis_high: #stepper_e_chopper_hysteresis_high: #stepper_h_chopper_hysteresis_high: # This parameter controls the CFG4 pin of the stepper motor driver # (True sets CFG4 high, False sets it low). The default is False. #stepper_x_chopper_blank_time_high: #stepper_y_chopper_blank_time_high: #stepper_z_chopper_blank_time_high: #stepper_e_chopper_blank_time_high: #stepper_h_chopper_blank_time_high: # This parameter controls the CFG5 pin of the stepper motor driver # (True sets CFG5 high, False sets it low). The default is True.","title":"[replicape]"},{"location":"Config_Reference.html#other-custom-modules","text":"","title":"Other Custom Modules"},{"location":"Config_Reference.html#palette2","text":"Palette 2 multimaterial support - provides a tighter integration supporting Palette 2 devices in connected mode. This modules also requires [virtual_sdcard] and [pause_resume] for full functionality. If you use this module, do not use the Palette 2 plugin for Octoprint as they will conflict, and 1 will fail to initialize properly likely aborting your print. If you use Octoprint and stream gcode over the serial port instead of printing from virtual_sd, then remove M1 and M0 from Pausing commands in Settings > Serial Connection > Firmware & protocol will prevent the need to start print on the Palette 2 and unpausing in Octoprint for your print to begin. [palette2] serial: # The serial port to connect to the Palette 2. #baud: 115200 # The baud rate to use. The default is 115200. #feedrate_splice: 0.8 # The feedrate to use when splicing, default is 0.8 #feedrate_normal: 1.0 # The feedrate to use after splicing, default is 1.0 #auto_load_speed: 2 # Extrude feedrate when autoloading, default is 2 (mm/s) #auto_cancel_variation: 0.1 # Auto cancel print when ping variation is above this threshold","title":"[palette2]"},{"location":"Config_Reference.html#angle","text":"Magnetic hall angle sensor support for reading stepper motor angle shaft measurements using a1333, as5047d, mt6816, mt6826s, or tle5012b SPI chips. The measurements are available via the API Server and motion analysis tool . See the G-Code reference for available commands. [angle my_angle_sensor] sensor_type: # The type of the magnetic hall sensor chip. Available choices are # \"a1333\", \"as5047d\", \"mt6816\", \"mt6826s\", and \"tle5012b\". This parameter must be # specified. #sample_period: 0.000400 # The query period (in seconds) to use during measurements. The # default is 0.000400 (which is 2500 samples per second). #stepper: # The name of the stepper that the angle sensor is attached to (eg, # \"stepper_x\"). Setting this value enables an angle calibration # tool. To use this feature, the Python \"numpy\" package must be # installed. The default is to not enable angle calibration for the # angle sensor. cs_pin: # The SPI enable pin for the sensor. This parameter must be provided. #spi_speed: #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters.","title":"[angle]"},{"location":"Config_Reference.html#common-bus-parameters","text":"","title":"Common bus parameters"},{"location":"Config_Reference.html#common-spi-settings","text":"The following parameters are generally available for devices using an SPI bus. #spi_speed: # The SPI speed (in hz) to use when communicating with the device. # The default depends on the type of device. #spi_bus: # If the micro-controller supports multiple SPI busses then one may # specify the micro-controller bus name here. The default depends on # the type of micro-controller. #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # Specify the above parameters to use \"software based SPI\". This # mode does not require micro-controller hardware support (typically # any general purpose pins may be used). The default is to not use # \"software spi\".","title":"Common SPI settings"},{"location":"Config_Reference.html#common-i2c-settings","text":"The following parameters are generally available for devices using an I2C bus. Note that Klipper's current micro-controller support for I2C is generally not tolerant to line noise. Unexpected errors on the I2C wires may result in Klipper raising a run-time error. Klipper's support for error recovery varies between each micro-controller type. It is generally recommended to only use I2C devices that are on the same printed circuit board as the micro-controller. Most Klipper micro-controller implementations only support an i2c_speed of 100000 ( standard mode , 100kbit/s). The Klipper \"Linux\" micro-controller supports a 400000 speed ( fast mode , 400kbit/s), but it must be set in the operating system and the i2c_speed parameter is otherwise ignored. The Klipper \"RP2040\" micro-controller and ATmega AVR family and some STM32 (F0, G0, G4, L4, F7, H7) support a rate of 400000 via the i2c_speed parameter. All other Klipper micro-controllers use a 100000 rate and ignore the i2c_speed parameter. #i2c_address: # The i2c address of the device. This must specified as a decimal # number (not in hex). The default depends on the type of device. #i2c_mcu: # The name of the micro-controller that the chip is connected to. # The default is \"mcu\". #i2c_bus: # If the micro-controller supports multiple I2C busses then one may # specify the micro-controller bus name here. The default depends on # the type of micro-controller. #i2c_software_scl_pin: #i2c_software_sda_pin: # Specify these parameters to use micro-controller software based # I2C \"bit-banging\" support. The two parameters should the two pins # on the micro-controller to use for the scl and sda wires. The # default is to use hardware based I2C support as specified by the # i2c_bus parameter. #i2c_speed: # The I2C speed (in Hz) to use when communicating with the device. # The Klipper implementation on most micro-controllers is hard-coded # to 100000 and changing this value has no effect. The default is # 100000. Linux, RP2040 and ATmega support 400000.","title":"Common I2C settings"},{"location":"Config_checks.html","text":"Configuration checks \u00b6 This document provides a list of steps to help confirm the pin settings in the Klipper printer.cfg file. It is a good idea to run through these steps after following the steps in the installation document . During this guide, it may be necessary to make changes to the Klipper config file. Be sure to issue a RESTART command after every change to the config file to ensure that the change takes effect (type \"restart\" in the Octoprint terminal tab and then click \"Send\"). It's also a good idea to issue a STATUS command after every RESTART to verify that the config file is successfully loaded. Verify temperature \u00b6 Start by verifying that temperatures are being properly reported. Navigate to the temperature graph section in the user interface. Verify that the temperature of the nozzle and bed (if applicable) are present and not increasing. If it is increasing, remove power from the printer. If the temperatures are not accurate, review the \"sensor_type\" and \"sensor_pin\" settings for the nozzle and/or bed. Verify M112 \u00b6 Navigate to the command console and issue an M112 command in the terminal box. This command requests Klipper to go into a \"shutdown\" state. It will cause an error to show, which can be cleared with a FIRMWARE_RESTART command in the command console. Octoprint will also require a reconnect. Then navigate to the temperature graph section and verify that temperatures continue to update and the temperatures are not increasing. If temperatures are increasing, remove power from the printer. Verify heaters \u00b6 Navigate to the temperature graph section and type in 50 followed by enter in the extruder/tool temperature box. The extruder temperature in the graph should start to increase (within about 30 seconds or so). Then go to the extruder temperature drop-down box and select \"Off\". After several minutes the temperature should start to return to its initial room temperature value. If the temperature does not increase then verify the \"heater_pin\" setting in the config. If the printer has a heated bed then perform the above test again with the bed. Verify stepper motor enable pin \u00b6 Verify that all of the printer axes can manually move freely (the stepper motors are disabled). If not, issue an M84 command to disable the motors. If any of the axes still can not move freely, then verify the stepper \"enable_pin\" configuration for the given axis. On most commodity stepper motor drivers, the motor enable pin is \"active low\" and therefore the enable pin should have a \"!\" before the pin (for example, \"enable_pin: !PA1\"). Verify endstops \u00b6 Manually move all the printer axes so that none of them are in contact with an endstop. Send a QUERY_ENDSTOPS command via the command console. It should respond with the current state of all of the configured endstops and they should all report a state of \"open\". For each of the endstops, rerun the QUERY_ENDSTOPS command while manually triggering the endstop. The QUERY_ENDSTOPS command should report the endstop as \"TRIGGERED\". If the endstop appears inverted (it reports \"open\" when triggered and vice-versa) then add a \"!\" to the pin definition (for example, \"endstop_pin: ^!PA2\"), or remove the \"!\" if there is already one present. If the endstop does not change at all then it generally indicates that the endstop is connected to a different pin. However, it may also require a change to the pullup setting of the pin (the '^' at the start of the endstop_pin name - most printers will use a pullup resistor and the '^' should be present). Verify stepper motors \u00b6 Use the STEPPER_BUZZ command to verify the connectivity of each stepper motor. Start by manually positioning the given axis to a midway point and then run STEPPER_BUZZ STEPPER=stepper_x in the command console. The STEPPER_BUZZ command will cause the given stepper to move one millimeter in a positive direction and then it will return to its starting position. (If the endstop is defined at position_endstop=0 then at the start of each movement the stepper will move away from the endstop.) It will perform this oscillation ten times. If the stepper does not move at all, then verify the \"enable_pin\" and \"step_pin\" settings for the stepper. If the stepper motor moves but does not return to its original position then verify the \"dir_pin\" setting. If the stepper motor oscillates in an incorrect direction, then it generally indicates that the \"dir_pin\" for the axis needs to be inverted. This is done by adding a '!' to the \"dir_pin\" in the printer config file (or removing it if one is already there). If the motor moves significantly more or significantly less than one millimeter then verify the \"rotation_distance\" setting. Run the above test for each stepper motor defined in the config file. (Set the STEPPER parameter of the STEPPER_BUZZ command to the name of the config section that is to be tested.) If there is no filament in the extruder then one can use STEPPER_BUZZ to verify the extruder motor connectivity (use STEPPER=extruder). Otherwise, it's best to test the extruder motor separately (see the next section). After verifying all endstops and verifying all stepper motors the homing mechanism should be tested. Issue a G28 command to home all axes. Remove power from the printer if it does not home properly. Rerun the endstop and stepper motor verification steps if necessary. Verify extruder motor \u00b6 To test the extruder motor it will be necessary to heat the extruder to a printing temperature. Navigate to the temperature graph section and select a target temperature from the temperature drop-down box (or manually enter an appropriate temperature). Wait for the printer to reach the desired temperature. Then navigate to the command console and click the \"Extrude\" button. Verify that the extruder motor turns in the correct direction. If it does not, see the troubleshooting tips in the previous section to confirm the \"enable_pin\", \"step_pin\", and \"dir_pin\" settings for the extruder. Calibrate PID settings \u00b6 Klipper supports PID control for the extruder and bed heaters. In order to use this control mechanism, it is necessary to calibrate the PID settings on each printer (PID settings found in other firmwares or in the example configuration files often work poorly). To calibrate the extruder, navigate to the command console and run the PID_CALIBRATE command. For example: PID_CALIBRATE HEATER=extruder TARGET=170 At the completion of the tuning test run SAVE_CONFIG to update the printer.cfg file the new PID settings. If the printer has a heated bed and it supports being driven by PWM (Pulse Width Modulation) then it is recommended to use PID control for the bed. (When the bed heater is controlled using the PID algorithm it may turn on and off ten times a second, which may not be suitable for heaters using a mechanical switch.) A typical bed PID calibration command is: PID_CALIBRATE HEATER=heater_bed TARGET=60 Next steps \u00b6 This guide is intended to help with basic verification of pin settings in the Klipper configuration file. Be sure to read the bed leveling guide. Also see the Slicers document for information on configuring a slicer with Klipper. After one has verified that basic printing works, it is a good idea to consider calibrating pressure advance . It may be necessary to perform other types of detailed printer calibration - a number of guides are available online to help with this (for example, do a web search for \"3d printer calibration\"). As an example, if you experience the effect called ringing, you may try following resonance compensation tuning guide.","title":"Configuration checks"},{"location":"Config_checks.html#configuration-checks","text":"This document provides a list of steps to help confirm the pin settings in the Klipper printer.cfg file. It is a good idea to run through these steps after following the steps in the installation document . During this guide, it may be necessary to make changes to the Klipper config file. Be sure to issue a RESTART command after every change to the config file to ensure that the change takes effect (type \"restart\" in the Octoprint terminal tab and then click \"Send\"). It's also a good idea to issue a STATUS command after every RESTART to verify that the config file is successfully loaded.","title":"Configuration checks"},{"location":"Config_checks.html#verify-temperature","text":"Start by verifying that temperatures are being properly reported. Navigate to the temperature graph section in the user interface. Verify that the temperature of the nozzle and bed (if applicable) are present and not increasing. If it is increasing, remove power from the printer. If the temperatures are not accurate, review the \"sensor_type\" and \"sensor_pin\" settings for the nozzle and/or bed.","title":"Verify temperature"},{"location":"Config_checks.html#verify-m112","text":"Navigate to the command console and issue an M112 command in the terminal box. This command requests Klipper to go into a \"shutdown\" state. It will cause an error to show, which can be cleared with a FIRMWARE_RESTART command in the command console. Octoprint will also require a reconnect. Then navigate to the temperature graph section and verify that temperatures continue to update and the temperatures are not increasing. If temperatures are increasing, remove power from the printer.","title":"Verify M112"},{"location":"Config_checks.html#verify-heaters","text":"Navigate to the temperature graph section and type in 50 followed by enter in the extruder/tool temperature box. The extruder temperature in the graph should start to increase (within about 30 seconds or so). Then go to the extruder temperature drop-down box and select \"Off\". After several minutes the temperature should start to return to its initial room temperature value. If the temperature does not increase then verify the \"heater_pin\" setting in the config. If the printer has a heated bed then perform the above test again with the bed.","title":"Verify heaters"},{"location":"Config_checks.html#verify-stepper-motor-enable-pin","text":"Verify that all of the printer axes can manually move freely (the stepper motors are disabled). If not, issue an M84 command to disable the motors. If any of the axes still can not move freely, then verify the stepper \"enable_pin\" configuration for the given axis. On most commodity stepper motor drivers, the motor enable pin is \"active low\" and therefore the enable pin should have a \"!\" before the pin (for example, \"enable_pin: !PA1\").","title":"Verify stepper motor enable pin"},{"location":"Config_checks.html#verify-endstops","text":"Manually move all the printer axes so that none of them are in contact with an endstop. Send a QUERY_ENDSTOPS command via the command console. It should respond with the current state of all of the configured endstops and they should all report a state of \"open\". For each of the endstops, rerun the QUERY_ENDSTOPS command while manually triggering the endstop. The QUERY_ENDSTOPS command should report the endstop as \"TRIGGERED\". If the endstop appears inverted (it reports \"open\" when triggered and vice-versa) then add a \"!\" to the pin definition (for example, \"endstop_pin: ^!PA2\"), or remove the \"!\" if there is already one present. If the endstop does not change at all then it generally indicates that the endstop is connected to a different pin. However, it may also require a change to the pullup setting of the pin (the '^' at the start of the endstop_pin name - most printers will use a pullup resistor and the '^' should be present).","title":"Verify endstops"},{"location":"Config_checks.html#verify-stepper-motors","text":"Use the STEPPER_BUZZ command to verify the connectivity of each stepper motor. Start by manually positioning the given axis to a midway point and then run STEPPER_BUZZ STEPPER=stepper_x in the command console. The STEPPER_BUZZ command will cause the given stepper to move one millimeter in a positive direction and then it will return to its starting position. (If the endstop is defined at position_endstop=0 then at the start of each movement the stepper will move away from the endstop.) It will perform this oscillation ten times. If the stepper does not move at all, then verify the \"enable_pin\" and \"step_pin\" settings for the stepper. If the stepper motor moves but does not return to its original position then verify the \"dir_pin\" setting. If the stepper motor oscillates in an incorrect direction, then it generally indicates that the \"dir_pin\" for the axis needs to be inverted. This is done by adding a '!' to the \"dir_pin\" in the printer config file (or removing it if one is already there). If the motor moves significantly more or significantly less than one millimeter then verify the \"rotation_distance\" setting. Run the above test for each stepper motor defined in the config file. (Set the STEPPER parameter of the STEPPER_BUZZ command to the name of the config section that is to be tested.) If there is no filament in the extruder then one can use STEPPER_BUZZ to verify the extruder motor connectivity (use STEPPER=extruder). Otherwise, it's best to test the extruder motor separately (see the next section). After verifying all endstops and verifying all stepper motors the homing mechanism should be tested. Issue a G28 command to home all axes. Remove power from the printer if it does not home properly. Rerun the endstop and stepper motor verification steps if necessary.","title":"Verify stepper motors"},{"location":"Config_checks.html#verify-extruder-motor","text":"To test the extruder motor it will be necessary to heat the extruder to a printing temperature. Navigate to the temperature graph section and select a target temperature from the temperature drop-down box (or manually enter an appropriate temperature). Wait for the printer to reach the desired temperature. Then navigate to the command console and click the \"Extrude\" button. Verify that the extruder motor turns in the correct direction. If it does not, see the troubleshooting tips in the previous section to confirm the \"enable_pin\", \"step_pin\", and \"dir_pin\" settings for the extruder.","title":"Verify extruder motor"},{"location":"Config_checks.html#calibrate-pid-settings","text":"Klipper supports PID control for the extruder and bed heaters. In order to use this control mechanism, it is necessary to calibrate the PID settings on each printer (PID settings found in other firmwares or in the example configuration files often work poorly). To calibrate the extruder, navigate to the command console and run the PID_CALIBRATE command. For example: PID_CALIBRATE HEATER=extruder TARGET=170 At the completion of the tuning test run SAVE_CONFIG to update the printer.cfg file the new PID settings. If the printer has a heated bed and it supports being driven by PWM (Pulse Width Modulation) then it is recommended to use PID control for the bed. (When the bed heater is controlled using the PID algorithm it may turn on and off ten times a second, which may not be suitable for heaters using a mechanical switch.) A typical bed PID calibration command is: PID_CALIBRATE HEATER=heater_bed TARGET=60","title":"Calibrate PID settings"},{"location":"Config_checks.html#next-steps","text":"This guide is intended to help with basic verification of pin settings in the Klipper configuration file. Be sure to read the bed leveling guide. Also see the Slicers document for information on configuring a slicer with Klipper. After one has verified that basic printing works, it is a good idea to consider calibrating pressure advance . It may be necessary to perform other types of detailed printer calibration - a number of guides are available online to help with this (for example, do a web search for \"3d printer calibration\"). As an example, if you experience the effect called ringing, you may try following resonance compensation tuning guide.","title":"Next steps"},{"location":"Contact.html","text":"Contact \u00b6 This document provides contact information for Klipper. Discourse Forum \u00b6 There is a Klipper Community Discourse server for \"forum\" style discussions on Klipper. Note that Discourse is not Discord. Discord Chat \u00b6 There is a Discord server dedicated to Klipper at: https://discord.klipper3d.org . Note that Discord is not Discourse. This server is run by a community of Klipper enthusiasts dedicated to discussions on Klipper. It allows users to chat with other users in real-time. I have a question about Klipper \u00b6 Many questions we receive are already answered in the Klipper documentation . Please be sure to to read the documentation and follow the directions provided there. It is also possible to search for similar questions in the Klipper Discourse Forum . If you are interested in sharing your knowledge and experience with other Klipper users then you can join the Klipper Discourse Forum or Klipper Discord Chat . Both are communities where Klipper users can discuss Klipper with other users. If you have a general question or are experiencing general printing problems, then also consider a general 3d-printing forum or a forum dedicated to the printer hardware. I have a feature request \u00b6 All new features require someone interested and able to implement that feature. If you are interested in helping to implement or test a new feature, you can search for ongoing developments in the Klipper Discourse Forum . There is also Klipper Discord Chat for discussions between collaborators. Help! It doesn't work! \u00b6 If you are experiencing problems we recommend you carefully read the Klipper documentation and double check that all steps were followed. If you are experiencing a printing problem, then we recommend carefully inspecting the printer hardware (all joints, wires, screws, etc.) and verify nothing is abnormal. We find most printing problems are not related to the Klipper software. If you do find a problem with the printer hardware then consider searching general 3d-printing forums or forums dedicated to the printer hardware. It is also possible to search for similar issues in the Klipper Discourse Forum . If you are interested in sharing your knowledge and experience with other Klipper users then you can join the Klipper Discourse Forum or Klipper Discord Chat . Both are communities where Klipper users can discuss Klipper with other users. I found a bug in the Klipper software \u00b6 Klipper is an open-source project and we appreciate when collaborators diagnose errors in the software. Problems should be reported in the Klipper Discourse Forum . There is important information that will be needed in order to fix a bug. Please follow these steps: Make sure you are running unmodified code from https://github.com/Klipper3d/klipper . If the code has been modified or is obtained from another source, then you should reproduce the problem on the unmodified code from https://github.com/Klipper3d/klipper prior to reporting. If possible, run an M112 command immediately after the undesirable event occurs. This causes Klipper to go into a \"shutdown state\" and it will cause additional debugging information to be written to the log file. Obtain the Klipper log file from the event. The log file has been engineered to answer common questions the Klipper developers have about the software and its environment (software version, hardware type, configuration, event timing, and hundreds of other questions). Dedicated Klipper web interfaces have the ability to directly obtain the Klipper log file. It's the easiest way to obtain the log when using one of these interfaces. Otherwise, an \"scp\" or \"sftp\" utility is needed to copy the log file to your desktop computer. The \"scp\" utility comes standard with Linux and MacOS desktops. There are freely available scp utilities for other desktops (eg, WinSCP). The log file may be located in the ~/printer_data/logs/klippy.log file (if using a graphical scp utility, look for the \"printer_data\" folder, then the \"logs\" folder under that, then the klippy.log file). The log file may alternatively be located in the /tmp/klippy.log file (if using a graphical scp utility that can not directly copy /tmp/klippy.log then repeatedly click on .. or \"parent folder\" until reaching the root directory, click on the tmp folder, and then select the klippy.log file). Copy the log file to your desktop so that it can be attached to an issue report. Do not modify the log file in any way; do not provide a snippet of the log. Only the full unmodified log file provides the necessary information. It is a good idea to compress the log file with zip or gzip. Open a new topic on the Klipper Discourse Forum and provide a clear description of the problem. Other Klipper contributors will need to understand what steps were taken, what the desired outcome was, and what outcome actually occurred. The compressed Klipper log file should be attached to that topic. I am making changes that I'd like to include in Klipper \u00b6 Klipper is open-source software and we appreciate new contributions. See the CONTRIBUTING document for information. There are several documents for developers . If you have questions on the code then you can also ask in the Klipper Discourse Forum or on the Klipper Discord Chat . Professional Services \u00b6 Custom software development, software support, and solutions: https://ko-fi.com/koconnor","title":"Contact"},{"location":"Contact.html#contact","text":"This document provides contact information for Klipper.","title":"Contact"},{"location":"Contact.html#discourse-forum","text":"There is a Klipper Community Discourse server for \"forum\" style discussions on Klipper. Note that Discourse is not Discord.","title":"Discourse Forum"},{"location":"Contact.html#discord-chat","text":"There is a Discord server dedicated to Klipper at: https://discord.klipper3d.org . Note that Discord is not Discourse. This server is run by a community of Klipper enthusiasts dedicated to discussions on Klipper. It allows users to chat with other users in real-time.","title":"Discord Chat"},{"location":"Contact.html#i-have-a-question-about-klipper","text":"Many questions we receive are already answered in the Klipper documentation . Please be sure to to read the documentation and follow the directions provided there. It is also possible to search for similar questions in the Klipper Discourse Forum . If you are interested in sharing your knowledge and experience with other Klipper users then you can join the Klipper Discourse Forum or Klipper Discord Chat . Both are communities where Klipper users can discuss Klipper with other users. If you have a general question or are experiencing general printing problems, then also consider a general 3d-printing forum or a forum dedicated to the printer hardware.","title":"I have a question about Klipper"},{"location":"Contact.html#i-have-a-feature-request","text":"All new features require someone interested and able to implement that feature. If you are interested in helping to implement or test a new feature, you can search for ongoing developments in the Klipper Discourse Forum . There is also Klipper Discord Chat for discussions between collaborators.","title":"I have a feature request"},{"location":"Contact.html#help-it-doesnt-work","text":"If you are experiencing problems we recommend you carefully read the Klipper documentation and double check that all steps were followed. If you are experiencing a printing problem, then we recommend carefully inspecting the printer hardware (all joints, wires, screws, etc.) and verify nothing is abnormal. We find most printing problems are not related to the Klipper software. If you do find a problem with the printer hardware then consider searching general 3d-printing forums or forums dedicated to the printer hardware. It is also possible to search for similar issues in the Klipper Discourse Forum . If you are interested in sharing your knowledge and experience with other Klipper users then you can join the Klipper Discourse Forum or Klipper Discord Chat . Both are communities where Klipper users can discuss Klipper with other users.","title":"Help! It doesn't work!"},{"location":"Contact.html#i-found-a-bug-in-the-klipper-software","text":"Klipper is an open-source project and we appreciate when collaborators diagnose errors in the software. Problems should be reported in the Klipper Discourse Forum . There is important information that will be needed in order to fix a bug. Please follow these steps: Make sure you are running unmodified code from https://github.com/Klipper3d/klipper . If the code has been modified or is obtained from another source, then you should reproduce the problem on the unmodified code from https://github.com/Klipper3d/klipper prior to reporting. If possible, run an M112 command immediately after the undesirable event occurs. This causes Klipper to go into a \"shutdown state\" and it will cause additional debugging information to be written to the log file. Obtain the Klipper log file from the event. The log file has been engineered to answer common questions the Klipper developers have about the software and its environment (software version, hardware type, configuration, event timing, and hundreds of other questions). Dedicated Klipper web interfaces have the ability to directly obtain the Klipper log file. It's the easiest way to obtain the log when using one of these interfaces. Otherwise, an \"scp\" or \"sftp\" utility is needed to copy the log file to your desktop computer. The \"scp\" utility comes standard with Linux and MacOS desktops. There are freely available scp utilities for other desktops (eg, WinSCP). The log file may be located in the ~/printer_data/logs/klippy.log file (if using a graphical scp utility, look for the \"printer_data\" folder, then the \"logs\" folder under that, then the klippy.log file). The log file may alternatively be located in the /tmp/klippy.log file (if using a graphical scp utility that can not directly copy /tmp/klippy.log then repeatedly click on .. or \"parent folder\" until reaching the root directory, click on the tmp folder, and then select the klippy.log file). Copy the log file to your desktop so that it can be attached to an issue report. Do not modify the log file in any way; do not provide a snippet of the log. Only the full unmodified log file provides the necessary information. It is a good idea to compress the log file with zip or gzip. Open a new topic on the Klipper Discourse Forum and provide a clear description of the problem. Other Klipper contributors will need to understand what steps were taken, what the desired outcome was, and what outcome actually occurred. The compressed Klipper log file should be attached to that topic.","title":"I found a bug in the Klipper software"},{"location":"Contact.html#i-am-making-changes-that-id-like-to-include-in-klipper","text":"Klipper is open-source software and we appreciate new contributions. See the CONTRIBUTING document for information. There are several documents for developers . If you have questions on the code then you can also ask in the Klipper Discourse Forum or on the Klipper Discord Chat .","title":"I am making changes that I'd like to include in Klipper"},{"location":"Contact.html#professional-services","text":"Custom software development, software support, and solutions: https://ko-fi.com/koconnor","title":"Professional Services"},{"location":"Debugging.html","text":"Debugging \u00b6 This document describes some of the Klipper debugging tools. Running the regression tests \u00b6 The main Klipper GitHub repository uses \"github actions\" to run a series of regression tests. It can be useful to run some of these tests locally. The source code \"whitespace check\" can be run with: ./scripts/check_whitespace.sh The Klippy regression test suite requires \"data dictionaries\" from many platforms. The easiest way to obtain them is to download them from github . Once the data dictionaries are downloaded, use the following to run the regression suite: tar xfz klipper-dict-20??????.tar.gz ~/klippy-env/bin/python ~/klipper/scripts/test_klippy.py -d dict/ ~/klipper/test/klippy/*.test Manually sending commands to the micro-controller \u00b6 Normally, the host klippy.py process would be used to translate gcode commands to Klipper micro-controller commands. However, it's also possible to manually send these MCU commands (functions marked with the DECL_COMMAND() macro in the Klipper source code). To do so, run: ~/klippy-env/bin/python ./klippy/console.py /tmp/pseudoserial See the \"HELP\" command within the tool for more information on its functionality. Some command-line options are available. For more information run: ~/klippy-env/bin/python ./klippy/console.py --help Translating gcode files to micro-controller commands \u00b6 The Klippy host code can run in a batch mode to produce the low-level micro-controller commands associated with a gcode file. Inspecting these low-level commands is useful when trying to understand the actions of the low-level hardware. It can also be useful to compare the difference in micro-controller commands after a code change. To run Klippy in this batch mode, there is a one time step necessary to generate the micro-controller \"data dictionary\". This is done by compiling the micro-controller code to obtain the out/klipper.dict file: make menuconfig make Once the above is done it is possible to run Klipper in batch mode (see installation for the steps necessary to build the python virtual environment and a printer.cfg file): ~/klippy-env/bin/python ./klippy/klippy.py ~/printer.cfg -i test.gcode -o test.serial -v -d out/klipper.dict The above will produce a file test.serial with the binary serial output. This output can be translated to readable text with: ~/klippy-env/bin/python ./klippy/parsedump.py out/klipper.dict test.serial > test.txt The resulting file test.txt contains a human readable list of micro-controller commands. The batch mode disables certain response / request commands in order to function. As a result, there will be some differences between actual commands and the above output. The generated data is useful for testing and inspection; it is not useful for sending to a real micro-controller. Motion analysis and data logging \u00b6 Klipper supports logging its internal motion history, which can be later analyzed. To use this feature, Klipper must be started with the API Server enabled. Data logging is enabled with the data_logger.py tool. For example: ~/klipper/scripts/motan/data_logger.py /tmp/klippy_uds mylog This command will connect to the Klipper API Server, subscribe to status and motion information, and log the results. Two files are generated - a compressed data file and an index file (eg, mylog.json.gz and mylog.index.gz ). After starting the logging, it is possible to complete prints and other actions - the logging will continue in the background. When done logging, hit ctrl-c to exit from the data_logger.py tool. The resulting files can be read and graphed using the motan_graph.py tool. To generate graphs on a Raspberry Pi, a one time step is necessary to install the \"matplotlib\" package: sudo apt-get update sudo apt-get install python-matplotlib However, it may be more convenient to copy the data files to a desktop class machine along with the Python code in the scripts/motan/ directory. The motion analysis scripts should run on any machine with a recent version of Python and Matplotlib installed. Graphs can be generated with a command like the following: ~/klipper/scripts/motan/motan_graph.py mylog -o mygraph.png One can use the -g option to specify the datasets to graph (it takes a Python literal containing a list of lists). For example: ~/klipper/scripts/motan/motan_graph.py mylog -g '[[\"trapq(toolhead,velocity)\"], [\"trapq(toolhead,accel)\"]]' The list of available datasets can be found using the -l option - for example: ~/klipper/scripts/motan/motan_graph.py -l It is also possible to specify matplotlib plot options for each dataset: ~/klipper/scripts/motan/motan_graph.py mylog -g '[[\"trapq(toolhead,velocity)?color=red&alpha=0.4\"]]' Many matplotlib options are available; some examples are \"color\", \"label\", \"alpha\", and \"linestyle\". The motan_graph.py tool supports several other command-line options - use the --help option to see a list. It may also be convenient to view/modify the motan_graph.py script itself. The raw data logs produced by the data_logger.py tool follow the format described in the API Server . It may be useful to inspect the data with a Unix command like the following: gunzip < mylog.json.gz | tr '\\03' '\\n' | less Generating load graphs \u00b6 The Klippy log file (/tmp/klippy.log) stores statistics on bandwidth, micro-controller load, and host buffer load. It can be useful to graph these statistics after a print. To generate a graph, a one time step is necessary to install the \"matplotlib\" package: sudo apt-get update sudo apt-get install python-matplotlib Then graphs can be produced with: ~/klipper/scripts/graphstats.py /tmp/klippy.log -o loadgraph.png One can then view the resulting loadgraph.png file. Different graphs can be produced. For more information run: ~/klipper/scripts/graphstats.py --help Extracting information from the klippy.log file \u00b6 The Klippy log file (/tmp/klippy.log) also contains debugging information. There is a logextract.py script that may be useful when analyzing a micro-controller shutdown or similar problem. It is typically run with something like: mkdir work_directory cd work_directory cp /tmp/klippy.log . ~/klipper/scripts/logextract.py ./klippy.log The script will extract the printer config file and will extract MCU shutdown information. The information dumps from an MCU shutdown (if present) will be reordered by timestamp to assist in diagnosing cause and effect scenarios. Testing with simulavr \u00b6 The simulavr tool enables one to simulate an Atmel ATmega micro-controller. This section describes how one can run test gcode files through simulavr. It is recommended to run this on a desktop class machine (not a Raspberry Pi) as it does require significant cpu to run efficiently. To use simulavr, download the simulavr package and compile with python support. Note that the build system may need to have some packages (such as swig) installed in order to build the python module. git clone git://git.savannah.nongnu.org/simulavr.git cd simulavr make python make build Make sure a file like ./build/pysimulavr/_pysimulavr.*.so is present after the above compilation: ls ./build/pysimulavr/_pysimulavr.*.so This command should report a specific file (e.g. ./build/pysimulavr/_pysimulavr.cpython-39-x86_64-linux-gnu.so ) and not an error. If you are on a Debian-based system (Debian, Ubuntu, etc.) you can install the following packages and generate *.deb files for system-wide installation of simulavr: sudo apt update sudo apt install g++ make cmake swig rst2pdf help2man texinfo make cfgclean python debian sudo dpkg -i build/debian/python3-simulavr*.deb To compile Klipper for use in simulavr, run: cd /path/to/klipper make menuconfig and compile the micro-controller software for an AVR atmega644p and select SIMULAVR software emulation support. Then one can compile Klipper (run make ) and then start the simulation with: PYTHONPATH=/path/to/simulavr/build/pysimulavr/ ./scripts/avrsim.py out/klipper.elf Note that if you have installed python3-simulavr system-wide, you do not need to set PYTHONPATH , and can simply run the simulator as ./scripts/avrsim.py out/klipper.elf Then, with simulavr running in another window, one can run the following to read gcode from a file (eg, \"test.gcode\"), process it with Klippy, and send it to Klipper running in simulavr (see installation for the steps necessary to build the python virtual environment): ~/klippy-env/bin/python ./klippy/klippy.py config/generic-simulavr.cfg -i test.gcode -v Using simulavr with gtkwave \u00b6 One useful feature of simulavr is its ability to create signal wave generation files with the exact timing of events. To do this, follow the directions above, but run avrsim.py with a command-line like the following: PYTHONPATH=/path/to/simulavr/src/python/ ./scripts/avrsim.py out/klipper.elf -t PORTA.PORT,PORTC.PORT The above would create a file avrsim.vcd with information on each change to the GPIOs on PORTA and PORTB. This could then be viewed using gtkwave with: gtkwave avrsim.vcd","title":"Debugging"},{"location":"Debugging.html#debugging","text":"This document describes some of the Klipper debugging tools.","title":"Debugging"},{"location":"Debugging.html#running-the-regression-tests","text":"The main Klipper GitHub repository uses \"github actions\" to run a series of regression tests. It can be useful to run some of these tests locally. The source code \"whitespace check\" can be run with: ./scripts/check_whitespace.sh The Klippy regression test suite requires \"data dictionaries\" from many platforms. The easiest way to obtain them is to download them from github . Once the data dictionaries are downloaded, use the following to run the regression suite: tar xfz klipper-dict-20??????.tar.gz ~/klippy-env/bin/python ~/klipper/scripts/test_klippy.py -d dict/ ~/klipper/test/klippy/*.test","title":"Running the regression tests"},{"location":"Debugging.html#manually-sending-commands-to-the-micro-controller","text":"Normally, the host klippy.py process would be used to translate gcode commands to Klipper micro-controller commands. However, it's also possible to manually send these MCU commands (functions marked with the DECL_COMMAND() macro in the Klipper source code). To do so, run: ~/klippy-env/bin/python ./klippy/console.py /tmp/pseudoserial See the \"HELP\" command within the tool for more information on its functionality. Some command-line options are available. For more information run: ~/klippy-env/bin/python ./klippy/console.py --help","title":"Manually sending commands to the micro-controller"},{"location":"Debugging.html#translating-gcode-files-to-micro-controller-commands","text":"The Klippy host code can run in a batch mode to produce the low-level micro-controller commands associated with a gcode file. Inspecting these low-level commands is useful when trying to understand the actions of the low-level hardware. It can also be useful to compare the difference in micro-controller commands after a code change. To run Klippy in this batch mode, there is a one time step necessary to generate the micro-controller \"data dictionary\". This is done by compiling the micro-controller code to obtain the out/klipper.dict file: make menuconfig make Once the above is done it is possible to run Klipper in batch mode (see installation for the steps necessary to build the python virtual environment and a printer.cfg file): ~/klippy-env/bin/python ./klippy/klippy.py ~/printer.cfg -i test.gcode -o test.serial -v -d out/klipper.dict The above will produce a file test.serial with the binary serial output. This output can be translated to readable text with: ~/klippy-env/bin/python ./klippy/parsedump.py out/klipper.dict test.serial > test.txt The resulting file test.txt contains a human readable list of micro-controller commands. The batch mode disables certain response / request commands in order to function. As a result, there will be some differences between actual commands and the above output. The generated data is useful for testing and inspection; it is not useful for sending to a real micro-controller.","title":"Translating gcode files to micro-controller commands"},{"location":"Debugging.html#motion-analysis-and-data-logging","text":"Klipper supports logging its internal motion history, which can be later analyzed. To use this feature, Klipper must be started with the API Server enabled. Data logging is enabled with the data_logger.py tool. For example: ~/klipper/scripts/motan/data_logger.py /tmp/klippy_uds mylog This command will connect to the Klipper API Server, subscribe to status and motion information, and log the results. Two files are generated - a compressed data file and an index file (eg, mylog.json.gz and mylog.index.gz ). After starting the logging, it is possible to complete prints and other actions - the logging will continue in the background. When done logging, hit ctrl-c to exit from the data_logger.py tool. The resulting files can be read and graphed using the motan_graph.py tool. To generate graphs on a Raspberry Pi, a one time step is necessary to install the \"matplotlib\" package: sudo apt-get update sudo apt-get install python-matplotlib However, it may be more convenient to copy the data files to a desktop class machine along with the Python code in the scripts/motan/ directory. The motion analysis scripts should run on any machine with a recent version of Python and Matplotlib installed. Graphs can be generated with a command like the following: ~/klipper/scripts/motan/motan_graph.py mylog -o mygraph.png One can use the -g option to specify the datasets to graph (it takes a Python literal containing a list of lists). For example: ~/klipper/scripts/motan/motan_graph.py mylog -g '[[\"trapq(toolhead,velocity)\"], [\"trapq(toolhead,accel)\"]]' The list of available datasets can be found using the -l option - for example: ~/klipper/scripts/motan/motan_graph.py -l It is also possible to specify matplotlib plot options for each dataset: ~/klipper/scripts/motan/motan_graph.py mylog -g '[[\"trapq(toolhead,velocity)?color=red&alpha=0.4\"]]' Many matplotlib options are available; some examples are \"color\", \"label\", \"alpha\", and \"linestyle\". The motan_graph.py tool supports several other command-line options - use the --help option to see a list. It may also be convenient to view/modify the motan_graph.py script itself. The raw data logs produced by the data_logger.py tool follow the format described in the API Server . It may be useful to inspect the data with a Unix command like the following: gunzip < mylog.json.gz | tr '\\03' '\\n' | less","title":"Motion analysis and data logging"},{"location":"Debugging.html#generating-load-graphs","text":"The Klippy log file (/tmp/klippy.log) stores statistics on bandwidth, micro-controller load, and host buffer load. It can be useful to graph these statistics after a print. To generate a graph, a one time step is necessary to install the \"matplotlib\" package: sudo apt-get update sudo apt-get install python-matplotlib Then graphs can be produced with: ~/klipper/scripts/graphstats.py /tmp/klippy.log -o loadgraph.png One can then view the resulting loadgraph.png file. Different graphs can be produced. For more information run: ~/klipper/scripts/graphstats.py --help","title":"Generating load graphs"},{"location":"Debugging.html#extracting-information-from-the-klippylog-file","text":"The Klippy log file (/tmp/klippy.log) also contains debugging information. There is a logextract.py script that may be useful when analyzing a micro-controller shutdown or similar problem. It is typically run with something like: mkdir work_directory cd work_directory cp /tmp/klippy.log . ~/klipper/scripts/logextract.py ./klippy.log The script will extract the printer config file and will extract MCU shutdown information. The information dumps from an MCU shutdown (if present) will be reordered by timestamp to assist in diagnosing cause and effect scenarios.","title":"Extracting information from the klippy.log file"},{"location":"Debugging.html#testing-with-simulavr","text":"The simulavr tool enables one to simulate an Atmel ATmega micro-controller. This section describes how one can run test gcode files through simulavr. It is recommended to run this on a desktop class machine (not a Raspberry Pi) as it does require significant cpu to run efficiently. To use simulavr, download the simulavr package and compile with python support. Note that the build system may need to have some packages (such as swig) installed in order to build the python module. git clone git://git.savannah.nongnu.org/simulavr.git cd simulavr make python make build Make sure a file like ./build/pysimulavr/_pysimulavr.*.so is present after the above compilation: ls ./build/pysimulavr/_pysimulavr.*.so This command should report a specific file (e.g. ./build/pysimulavr/_pysimulavr.cpython-39-x86_64-linux-gnu.so ) and not an error. If you are on a Debian-based system (Debian, Ubuntu, etc.) you can install the following packages and generate *.deb files for system-wide installation of simulavr: sudo apt update sudo apt install g++ make cmake swig rst2pdf help2man texinfo make cfgclean python debian sudo dpkg -i build/debian/python3-simulavr*.deb To compile Klipper for use in simulavr, run: cd /path/to/klipper make menuconfig and compile the micro-controller software for an AVR atmega644p and select SIMULAVR software emulation support. Then one can compile Klipper (run make ) and then start the simulation with: PYTHONPATH=/path/to/simulavr/build/pysimulavr/ ./scripts/avrsim.py out/klipper.elf Note that if you have installed python3-simulavr system-wide, you do not need to set PYTHONPATH , and can simply run the simulator as ./scripts/avrsim.py out/klipper.elf Then, with simulavr running in another window, one can run the following to read gcode from a file (eg, \"test.gcode\"), process it with Klippy, and send it to Klipper running in simulavr (see installation for the steps necessary to build the python virtual environment): ~/klippy-env/bin/python ./klippy/klippy.py config/generic-simulavr.cfg -i test.gcode -v","title":"Testing with simulavr"},{"location":"Debugging.html#using-simulavr-with-gtkwave","text":"One useful feature of simulavr is its ability to create signal wave generation files with the exact timing of events. To do this, follow the directions above, but run avrsim.py with a command-line like the following: PYTHONPATH=/path/to/simulavr/src/python/ ./scripts/avrsim.py out/klipper.elf -t PORTA.PORT,PORTC.PORT The above would create a file avrsim.vcd with information on each change to the GPIOs on PORTA and PORTB. This could then be viewed using gtkwave with: gtkwave avrsim.vcd","title":"Using simulavr with gtkwave"},{"location":"Delta_Calibrate.html","text":"Delta calibration \u00b6 This document describes Klipper's automatic calibration system for \"delta\" style printers. Delta calibration involves finding the tower endstop positions, tower angles, delta radius, and delta arm lengths. These settings control printer motion on a delta printer. Each one of these parameters has a non-obvious and non-linear impact and it is difficult to calibrate them manually. In contrast, the software calibration code can provide excellent results with just a few minutes of time. No special probing hardware is necessary. Ultimately, the delta calibration is dependent on the precision of the tower endstop switches. If one is using Trinamic stepper motor drivers then consider enabling endstop phase detection to improve the accuracy of those switches. Automatic vs manual probing \u00b6 Klipper supports calibrating the delta parameters via a manual probing method or via an automatic Z probe. A number of delta printer kits come with automatic Z probes that are not sufficiently accurate (specifically, small differences in arm length can cause effector tilt which can skew an automatic probe). If using an automatic probe then first calibrate the probe and then check for a probe location bias . If the automatic probe has a bias of more than 25 microns (.025mm) then use manual probing instead. Manual probing only takes a few minutes and it eliminates error introduced by the probe. If using a probe that is mounted on the side of the hotend (that is, it has an X or Y offset) then note that performing delta calibration will invalidate the results of probe calibration. These types of probes are rarely suitable for use on a delta (because minor effector tilt will result in a probe location bias). If using the probe anyway, then be sure to rerun probe calibration after any delta calibration. Basic delta calibration \u00b6 Klipper has a DELTA_CALIBRATE command that can perform basic delta calibration. This command probes seven different points on the bed and calculates new values for the tower angles, tower endstops, and delta radius. In order to perform this calibration the initial delta parameters (arm lengths, radius, and endstop positions) must be provided and they should have an accuracy to within a few millimeters. Most delta printer kits will provide these parameters - configure the printer with these initial defaults and then go on to run the DELTA_CALIBRATE command as described below. If no defaults are available then search online for a delta calibration guide that can provide a basic starting point. During the delta calibration process it may be necessary for the printer to probe below what would otherwise be considered the plane of the bed. It is typical to permit this during calibration by updating the config so that the printer's minimum_z_position=-5 . (Once calibration completes, one can remove this setting from the config.) There are two ways to perform the probing - manual probing ( DELTA_CALIBRATE METHOD=manual ) and automatic probing ( DELTA_CALIBRATE ). The manual probing method will move the head near the bed and then wait for the user to follow the steps described at \"the paper test\" to determine the actual distance between the nozzle and bed at the given location. To perform the basic probe, make sure the config has a [delta_calibrate] section defined and then run the tool: G28 DELTA_CALIBRATE METHOD=manual After probing the seven points new delta parameters will be calculated. Save and apply these parameters by running: SAVE_CONFIG The basic calibration should provide delta parameters that are accurate enough for basic printing. If this is a new printer, this is a good time to print some basic objects and verify general functionality. Enhanced delta calibration \u00b6 The basic delta calibration generally does a good job of calculating delta parameters such that the nozzle is the correct distance from the bed. However, it does not attempt to calibrate X and Y dimensional accuracy. It's a good idea to perform an enhanced delta calibration to verify dimensional accuracy. This calibration procedure requires printing a test object and measuring parts of that test object with digital calipers. Prior to running an enhanced delta calibration one must run the basic delta calibration (via the DELTA_CALIBRATE command) and save the results (via the SAVE_CONFIG command). Make sure there hasn't been any notable change to the printer configuration nor hardware since last performing a basic delta calibration (if unsure, rerun the basic delta calibration , including SAVE_CONFIG, just prior to printing the test object described below.) Use a slicer to generate G-Code from the docs/prints/calibrate_size.stl file. Slice the object using a slow speed (eg, 40mm/s). If possible, use a stiff plastic (such as PLA) for the object. The object has a diameter of 140mm. If this is too large for the printer then one can scale it down (but be sure to uniformly scale both the X and Y axes). If the printer supports significantly larger prints then this object can also be increased in size. A larger size can improve the measurement accuracy, but good print adhesion is more important than a larger print size. Print the test object and wait for it to fully cool. The commands described below must be run with the same printer settings used to print the calibration object (don't run DELTA_CALIBRATE between printing and measuring, or do something that would otherwise change the printer configuration). If possible, perform the measurements described below while the object is still attached to the print bed, but don't worry if the part detaches from the bed - just try to avoid bending the object when performing the measurements. Start by measuring the distance between the center pillar and the pillar next to the \"A\" label (which should also be pointing towards the \"A\" tower). Then go counterclockwise and measure the distances between the center pillar and the other pillars (distance from center to pillar across from C label, distance from center to pillar with B label, etc.). Enter these parameters into Klipper with a comma separated list of floating point numbers: DELTA_ANALYZE CENTER_DISTS=<a_dist>,<far_c_dist>,<b_dist>,<far_a_dist>,<c_dist>,<far_b_dist> Provide the values without spaces between them. Then measure the distance between the A pillar and the pillar across from the C label. Then go counterclockwise and measure the distance between the pillar across from C to the B pillar, the distance between the B pillar and the pillar across from A, and so on. Enter these parameters into Klipper: DELTA_ANALYZE OUTER_DISTS=<a_to_far_c>,<far_c_to_b>,<b_to_far_a>,<far_a_to_c>,<c_to_far_b>,<far_b_to_a> At this point it is okay to remove the object from the bed. The final measurements are of the pillars themselves. Measure the size of the center pillar along the A spoke, then the B spoke, and then the C spoke. Enter them into Klipper: DELTA_ANALYZE CENTER_PILLAR_WIDTHS=<a>,<b>,<c> The final measurements are of the outer pillars. Start by measuring the distance of the A pillar along the line from A to the pillar across from C. Then go counterclockwise and measure the remaining outer pillars (pillar across from C along the line to B, B pillar along the line to pillar across from A, etc.). And enter them into Klipper: DELTA_ANALYZE OUTER_PILLAR_WIDTHS=<a>,<far_c>,<b>,<far_a>,<c>,<far_b> If the object was scaled to a smaller or larger size then provide the scale factor that was used when slicing the object: DELTA_ANALYZE SCALE=1.0 (A scale value of 2.0 would mean the object is twice its original size, 0.5 would be half its original size.) Finally, perform the enhanced delta calibration by running: DELTA_ANALYZE CALIBRATE=extended This command can take several minutes to complete. After completion it will calculate updated delta parameters (delta radius, tower angles, endstop positions, and arm lengths). Use the SAVE_CONFIG command to save and apply the settings: SAVE_CONFIG The SAVE_CONFIG command will save both the updated delta parameters and information from the distance measurements. Future DELTA_CALIBRATE commands will also utilize this distance information. Do not attempt to reenter the raw distance measurements after running SAVE_CONFIG, as this command changes the printer configuration and the raw measurements no longer apply. Additional notes \u00b6 If the delta printer has good dimensional accuracy then the distance between any two pillars should be around 74mm and the width of every pillar should be around 9mm. (Specifically, the goal is for the distance between any two pillars minus the width of one of the pillars to be exactly 65mm.) Should there be a dimensional inaccuracy in the part then the DELTA_ANALYZE routine will calculate new delta parameters using both the distance measurements and the previous height measurements from the last DELTA_CALIBRATE command. DELTA_ANALYZE may produce delta parameters that are surprising. For example, it may suggest arm lengths that do not match the printer's actual arm lengths. Despite this, testing has shown that DELTA_ANALYZE often produces superior results. It is believed that the calculated delta parameters are able to account for slight errors elsewhere in the hardware. For example, small differences in arm length may result in a tilt to the effector and some of that tilt may be accounted for by adjusting the arm length parameters. Using Bed Mesh on a Delta \u00b6 It is possible to use bed mesh on a delta. However, it is important to obtain good delta calibration prior to enabling a bed mesh. Running bed mesh with poor delta calibration will result in confusing and poor results. Note that performing delta calibration will invalidate any previously obtained bed mesh. After performing a new delta calibration be sure to rerun BED_MESH_CALIBRATE.","title":"Delta calibration"},{"location":"Delta_Calibrate.html#delta-calibration","text":"This document describes Klipper's automatic calibration system for \"delta\" style printers. Delta calibration involves finding the tower endstop positions, tower angles, delta radius, and delta arm lengths. These settings control printer motion on a delta printer. Each one of these parameters has a non-obvious and non-linear impact and it is difficult to calibrate them manually. In contrast, the software calibration code can provide excellent results with just a few minutes of time. No special probing hardware is necessary. Ultimately, the delta calibration is dependent on the precision of the tower endstop switches. If one is using Trinamic stepper motor drivers then consider enabling endstop phase detection to improve the accuracy of those switches.","title":"Delta calibration"},{"location":"Delta_Calibrate.html#automatic-vs-manual-probing","text":"Klipper supports calibrating the delta parameters via a manual probing method or via an automatic Z probe. A number of delta printer kits come with automatic Z probes that are not sufficiently accurate (specifically, small differences in arm length can cause effector tilt which can skew an automatic probe). If using an automatic probe then first calibrate the probe and then check for a probe location bias . If the automatic probe has a bias of more than 25 microns (.025mm) then use manual probing instead. Manual probing only takes a few minutes and it eliminates error introduced by the probe. If using a probe that is mounted on the side of the hotend (that is, it has an X or Y offset) then note that performing delta calibration will invalidate the results of probe calibration. These types of probes are rarely suitable for use on a delta (because minor effector tilt will result in a probe location bias). If using the probe anyway, then be sure to rerun probe calibration after any delta calibration.","title":"Automatic vs manual probing"},{"location":"Delta_Calibrate.html#basic-delta-calibration","text":"Klipper has a DELTA_CALIBRATE command that can perform basic delta calibration. This command probes seven different points on the bed and calculates new values for the tower angles, tower endstops, and delta radius. In order to perform this calibration the initial delta parameters (arm lengths, radius, and endstop positions) must be provided and they should have an accuracy to within a few millimeters. Most delta printer kits will provide these parameters - configure the printer with these initial defaults and then go on to run the DELTA_CALIBRATE command as described below. If no defaults are available then search online for a delta calibration guide that can provide a basic starting point. During the delta calibration process it may be necessary for the printer to probe below what would otherwise be considered the plane of the bed. It is typical to permit this during calibration by updating the config so that the printer's minimum_z_position=-5 . (Once calibration completes, one can remove this setting from the config.) There are two ways to perform the probing - manual probing ( DELTA_CALIBRATE METHOD=manual ) and automatic probing ( DELTA_CALIBRATE ). The manual probing method will move the head near the bed and then wait for the user to follow the steps described at \"the paper test\" to determine the actual distance between the nozzle and bed at the given location. To perform the basic probe, make sure the config has a [delta_calibrate] section defined and then run the tool: G28 DELTA_CALIBRATE METHOD=manual After probing the seven points new delta parameters will be calculated. Save and apply these parameters by running: SAVE_CONFIG The basic calibration should provide delta parameters that are accurate enough for basic printing. If this is a new printer, this is a good time to print some basic objects and verify general functionality.","title":"Basic delta calibration"},{"location":"Delta_Calibrate.html#enhanced-delta-calibration","text":"The basic delta calibration generally does a good job of calculating delta parameters such that the nozzle is the correct distance from the bed. However, it does not attempt to calibrate X and Y dimensional accuracy. It's a good idea to perform an enhanced delta calibration to verify dimensional accuracy. This calibration procedure requires printing a test object and measuring parts of that test object with digital calipers. Prior to running an enhanced delta calibration one must run the basic delta calibration (via the DELTA_CALIBRATE command) and save the results (via the SAVE_CONFIG command). Make sure there hasn't been any notable change to the printer configuration nor hardware since last performing a basic delta calibration (if unsure, rerun the basic delta calibration , including SAVE_CONFIG, just prior to printing the test object described below.) Use a slicer to generate G-Code from the docs/prints/calibrate_size.stl file. Slice the object using a slow speed (eg, 40mm/s). If possible, use a stiff plastic (such as PLA) for the object. The object has a diameter of 140mm. If this is too large for the printer then one can scale it down (but be sure to uniformly scale both the X and Y axes). If the printer supports significantly larger prints then this object can also be increased in size. A larger size can improve the measurement accuracy, but good print adhesion is more important than a larger print size. Print the test object and wait for it to fully cool. The commands described below must be run with the same printer settings used to print the calibration object (don't run DELTA_CALIBRATE between printing and measuring, or do something that would otherwise change the printer configuration). If possible, perform the measurements described below while the object is still attached to the print bed, but don't worry if the part detaches from the bed - just try to avoid bending the object when performing the measurements. Start by measuring the distance between the center pillar and the pillar next to the \"A\" label (which should also be pointing towards the \"A\" tower). Then go counterclockwise and measure the distances between the center pillar and the other pillars (distance from center to pillar across from C label, distance from center to pillar with B label, etc.). Enter these parameters into Klipper with a comma separated list of floating point numbers: DELTA_ANALYZE CENTER_DISTS=<a_dist>,<far_c_dist>,<b_dist>,<far_a_dist>,<c_dist>,<far_b_dist> Provide the values without spaces between them. Then measure the distance between the A pillar and the pillar across from the C label. Then go counterclockwise and measure the distance between the pillar across from C to the B pillar, the distance between the B pillar and the pillar across from A, and so on. Enter these parameters into Klipper: DELTA_ANALYZE OUTER_DISTS=<a_to_far_c>,<far_c_to_b>,<b_to_far_a>,<far_a_to_c>,<c_to_far_b>,<far_b_to_a> At this point it is okay to remove the object from the bed. The final measurements are of the pillars themselves. Measure the size of the center pillar along the A spoke, then the B spoke, and then the C spoke. Enter them into Klipper: DELTA_ANALYZE CENTER_PILLAR_WIDTHS=<a>,<b>,<c> The final measurements are of the outer pillars. Start by measuring the distance of the A pillar along the line from A to the pillar across from C. Then go counterclockwise and measure the remaining outer pillars (pillar across from C along the line to B, B pillar along the line to pillar across from A, etc.). And enter them into Klipper: DELTA_ANALYZE OUTER_PILLAR_WIDTHS=<a>,<far_c>,<b>,<far_a>,<c>,<far_b> If the object was scaled to a smaller or larger size then provide the scale factor that was used when slicing the object: DELTA_ANALYZE SCALE=1.0 (A scale value of 2.0 would mean the object is twice its original size, 0.5 would be half its original size.) Finally, perform the enhanced delta calibration by running: DELTA_ANALYZE CALIBRATE=extended This command can take several minutes to complete. After completion it will calculate updated delta parameters (delta radius, tower angles, endstop positions, and arm lengths). Use the SAVE_CONFIG command to save and apply the settings: SAVE_CONFIG The SAVE_CONFIG command will save both the updated delta parameters and information from the distance measurements. Future DELTA_CALIBRATE commands will also utilize this distance information. Do not attempt to reenter the raw distance measurements after running SAVE_CONFIG, as this command changes the printer configuration and the raw measurements no longer apply.","title":"Enhanced delta calibration"},{"location":"Delta_Calibrate.html#additional-notes","text":"If the delta printer has good dimensional accuracy then the distance between any two pillars should be around 74mm and the width of every pillar should be around 9mm. (Specifically, the goal is for the distance between any two pillars minus the width of one of the pillars to be exactly 65mm.) Should there be a dimensional inaccuracy in the part then the DELTA_ANALYZE routine will calculate new delta parameters using both the distance measurements and the previous height measurements from the last DELTA_CALIBRATE command. DELTA_ANALYZE may produce delta parameters that are surprising. For example, it may suggest arm lengths that do not match the printer's actual arm lengths. Despite this, testing has shown that DELTA_ANALYZE often produces superior results. It is believed that the calculated delta parameters are able to account for slight errors elsewhere in the hardware. For example, small differences in arm length may result in a tilt to the effector and some of that tilt may be accounted for by adjusting the arm length parameters.","title":"Additional notes"},{"location":"Delta_Calibrate.html#using-bed-mesh-on-a-delta","text":"It is possible to use bed mesh on a delta. However, it is important to obtain good delta calibration prior to enabling a bed mesh. Running bed mesh with poor delta calibration will result in confusing and poor results. Note that performing delta calibration will invalidate any previously obtained bed mesh. After performing a new delta calibration be sure to rerun BED_MESH_CALIBRATE.","title":"Using Bed Mesh on a Delta"},{"location":"Eddy_Probe.html","text":"Eddy Current Inductive probe \u00b6 This document describes how to use an eddy current inductive probe in Klipper. Currently, an eddy current probe can not be used for Z homing. The sensor can only be used for Z probing. Start by declaring a probe_eddy_current config section in the printer.cfg file. It is recommended to set the z_offset to 0.5mm. It is typical for the sensor to require an x_offset and y_offset . If these values are not known, one should estimate the values during initial calibration. The first step in calibration is to determine the appropriate DRIVE_CURRENT for the sensor. Home the printer and navigate the toolhead so that the sensor is near the center of the bed and is about 20mm above the bed. Then issue an LDC_CALIBRATE_DRIVE_CURRENT CHIP=<config_name> command. For example, if the config section was named [probe_eddy_current my_eddy_probe] then one would run LDC_CALIBRATE_DRIVE_CURRENT CHIP=my_eddy_probe . This command should complete in a few seconds. After it completes, issue a SAVE_CONFIG command to save the results to the printer.cfg and restart. The second step in calibration is to correlate the sensor readings to the corresponding Z heights. Home the printer and navigate the toolhead so that the nozzle is near the center of the bed. Then run an PROBE_EDDY_CURRENT_CALIBRATE CHIP=my_eddy_probe command. Once the tool starts, follow the steps described at \"the paper test\" to determine the actual distance between the nozzle and bed at the given location. Once those steps are complete one can ACCEPT the position. The tool will then move the the toolhead so that the sensor is above the point where the nozzle used to be and run a series of movements to correlate the sensor to Z positions. This will take a couple of minutes. After the tool completes, issue a SAVE_CONFIG command to save the results to the printer.cfg and restart. After initial calibration it is a good idea to verify that the x_offset and y_offset are accurate. Follow the steps to calibrate probe x and y offsets . If either the x_offset or y_offset is modified then be sure to run the PROBE_EDDY_CURRENT_CALIBRATE command (as described above) after making the change. Once calibration is complete, one may use all the standard Klipper tools that use a Z probe. Note that eddy current sensors (and inductive probes in general) are susceptible to \"thermal drift\". That is, changes in temperature can result in changes in reported Z height. Changes in either the bed surface temperature or sensor hardware temperature can skew the results. It is important that calibration and probing is only done when the printer is at a stable temperature. Thermal Drift Calibration \u00b6 As with all inductive probes, eddy current probes are subject to significant thermal drift. If the eddy probe has a temperature sensor on the coil it is possible to configure a [temperature_probe] to report coil temperature and enable software drift compensation. To link a temperature probe to an eddy current probe the [temperature_probe] section must share a name with the [probe_eddy_current] section. For example: [probe_eddy_current my_probe] # eddy probe configuration... [temperature_probe my_probe] # temperature probe configuration... See the configuration reference for further details on how to configure a temperature_probe . It is advised to configure the calibration_position , calibration_extruder_temp , extruder_heating_z , and calibration_bed_temp options, as doing so will automate some of the steps outlined below. If the printer to be calibrated is enclosed, it is strongly recommended to set the max_validation_temp option to a value between 100 and 120. Eddy probe manufacturers may offer a stock drift calibration that can be manually added to drift_calibration option of the [probe_eddy_current] section. If they do not, or if the stock calibration does not perform well on your system, the temperature_probe module offers a manual calibration procedure via the TEMPERATURE_PROBE_CALIBRATE gcode command. Prior to performing calibration the user should have an idea of what the maximum attainable temperature probe coil temperature is. This temperature should be used to set the TARGET parameter of the TEMPERATURE_PROBE_CALIBRATE command. The goal is to calibrate across the widest temperature range possible, thus its desirable to start with the printer cold and finish with the coil at the maximum temperature it can reach. Once a [temperature_probe] is configured, the following steps may be taken to perform thermal drift calibration: The probe must be calibrated using PROBE_EDDY_CURRENT_CALIBRATE when a [temperature_probe] is configured and linked. This captures the temperature during calibration which is necessary to perform thermal drift compensation. Make sure the nozzle is free of debris and filament. The bed, nozzle, and probe coil should be cold prior to calibration. The following steps are required if the calibration_position , calibration_extruder_temp , and extruder_heating_z options in [temperature_probe] are NOT configured: Move the tool to the center of the bed. Z should be 30mm+ above the bed. Heat the extruder to a temperature above the maximum safe bed temperature. 150-170C should be sufficient for most configurations. The purpose of heating the extruder is to avoid nozzle expansion during calibration. When the extruder temperature has settled, move the Z axis down to about 1mm above the bed. Start drift calibration. If the probe's name is my_probe and the maximum probe temperature we can achieve is 80C, the appropriate gcode command is TEMPERATURE_PROBE_CALIBRATE PROBE=my_probe TARGET=80 . If configured, the tool will move to the X,Y coordinate specified by the calibration_position and the Z value specified by extruder_heating_z . After heating the extruder to the specified temperature the tool will move to the Z value specified by the calibration_position . The procedure will request a manual probe. Perform the manual probe with the paper test and ACCEPT . The calibration procedure will take the first set of samples with the probe then park the probe in the heating position. If the calibration_bed_temp is NOT configured turn on the bed heat to the maximum safe temperature. Otherwise this step will be performed automatically. By default the calibration procedure will request a manual probe every 2C between samples until the TARGET is reached. The temperature delta between samples can be customized by setting the STEP parameter in TEMPERATURE_PROBE_CALIBRATE . Care should be taken when setting a custom STEP value, a value too high may request too few samples resulting in a poor calibration. The following additional gcode commands are available during drift calibration: TEMPERATURE_PROBE_NEXT may be used to force a new sample before the step delta has been reached. TEMPERATURE_PROBE_COMPLETE may be used to complete calibration before the TARGET has been reached. ABORT may be used to end calibration and discard results. When calibration is finished use SAVE_CONFIG to store the drift calibration. As one may conclude, the calibration process outlined above is more challenging and time consuming than most other procedures. It may require practice and several attempts to achieve an optimal calibration.","title":"Eddy Current Inductive probe"},{"location":"Eddy_Probe.html#eddy-current-inductive-probe","text":"This document describes how to use an eddy current inductive probe in Klipper. Currently, an eddy current probe can not be used for Z homing. The sensor can only be used for Z probing. Start by declaring a probe_eddy_current config section in the printer.cfg file. It is recommended to set the z_offset to 0.5mm. It is typical for the sensor to require an x_offset and y_offset . If these values are not known, one should estimate the values during initial calibration. The first step in calibration is to determine the appropriate DRIVE_CURRENT for the sensor. Home the printer and navigate the toolhead so that the sensor is near the center of the bed and is about 20mm above the bed. Then issue an LDC_CALIBRATE_DRIVE_CURRENT CHIP=<config_name> command. For example, if the config section was named [probe_eddy_current my_eddy_probe] then one would run LDC_CALIBRATE_DRIVE_CURRENT CHIP=my_eddy_probe . This command should complete in a few seconds. After it completes, issue a SAVE_CONFIG command to save the results to the printer.cfg and restart. The second step in calibration is to correlate the sensor readings to the corresponding Z heights. Home the printer and navigate the toolhead so that the nozzle is near the center of the bed. Then run an PROBE_EDDY_CURRENT_CALIBRATE CHIP=my_eddy_probe command. Once the tool starts, follow the steps described at \"the paper test\" to determine the actual distance between the nozzle and bed at the given location. Once those steps are complete one can ACCEPT the position. The tool will then move the the toolhead so that the sensor is above the point where the nozzle used to be and run a series of movements to correlate the sensor to Z positions. This will take a couple of minutes. After the tool completes, issue a SAVE_CONFIG command to save the results to the printer.cfg and restart. After initial calibration it is a good idea to verify that the x_offset and y_offset are accurate. Follow the steps to calibrate probe x and y offsets . If either the x_offset or y_offset is modified then be sure to run the PROBE_EDDY_CURRENT_CALIBRATE command (as described above) after making the change. Once calibration is complete, one may use all the standard Klipper tools that use a Z probe. Note that eddy current sensors (and inductive probes in general) are susceptible to \"thermal drift\". That is, changes in temperature can result in changes in reported Z height. Changes in either the bed surface temperature or sensor hardware temperature can skew the results. It is important that calibration and probing is only done when the printer is at a stable temperature.","title":"Eddy Current Inductive probe"},{"location":"Eddy_Probe.html#thermal-drift-calibration","text":"As with all inductive probes, eddy current probes are subject to significant thermal drift. If the eddy probe has a temperature sensor on the coil it is possible to configure a [temperature_probe] to report coil temperature and enable software drift compensation. To link a temperature probe to an eddy current probe the [temperature_probe] section must share a name with the [probe_eddy_current] section. For example: [probe_eddy_current my_probe] # eddy probe configuration... [temperature_probe my_probe] # temperature probe configuration... See the configuration reference for further details on how to configure a temperature_probe . It is advised to configure the calibration_position , calibration_extruder_temp , extruder_heating_z , and calibration_bed_temp options, as doing so will automate some of the steps outlined below. If the printer to be calibrated is enclosed, it is strongly recommended to set the max_validation_temp option to a value between 100 and 120. Eddy probe manufacturers may offer a stock drift calibration that can be manually added to drift_calibration option of the [probe_eddy_current] section. If they do not, or if the stock calibration does not perform well on your system, the temperature_probe module offers a manual calibration procedure via the TEMPERATURE_PROBE_CALIBRATE gcode command. Prior to performing calibration the user should have an idea of what the maximum attainable temperature probe coil temperature is. This temperature should be used to set the TARGET parameter of the TEMPERATURE_PROBE_CALIBRATE command. The goal is to calibrate across the widest temperature range possible, thus its desirable to start with the printer cold and finish with the coil at the maximum temperature it can reach. Once a [temperature_probe] is configured, the following steps may be taken to perform thermal drift calibration: The probe must be calibrated using PROBE_EDDY_CURRENT_CALIBRATE when a [temperature_probe] is configured and linked. This captures the temperature during calibration which is necessary to perform thermal drift compensation. Make sure the nozzle is free of debris and filament. The bed, nozzle, and probe coil should be cold prior to calibration. The following steps are required if the calibration_position , calibration_extruder_temp , and extruder_heating_z options in [temperature_probe] are NOT configured: Move the tool to the center of the bed. Z should be 30mm+ above the bed. Heat the extruder to a temperature above the maximum safe bed temperature. 150-170C should be sufficient for most configurations. The purpose of heating the extruder is to avoid nozzle expansion during calibration. When the extruder temperature has settled, move the Z axis down to about 1mm above the bed. Start drift calibration. If the probe's name is my_probe and the maximum probe temperature we can achieve is 80C, the appropriate gcode command is TEMPERATURE_PROBE_CALIBRATE PROBE=my_probe TARGET=80 . If configured, the tool will move to the X,Y coordinate specified by the calibration_position and the Z value specified by extruder_heating_z . After heating the extruder to the specified temperature the tool will move to the Z value specified by the calibration_position . The procedure will request a manual probe. Perform the manual probe with the paper test and ACCEPT . The calibration procedure will take the first set of samples with the probe then park the probe in the heating position. If the calibration_bed_temp is NOT configured turn on the bed heat to the maximum safe temperature. Otherwise this step will be performed automatically. By default the calibration procedure will request a manual probe every 2C between samples until the TARGET is reached. The temperature delta between samples can be customized by setting the STEP parameter in TEMPERATURE_PROBE_CALIBRATE . Care should be taken when setting a custom STEP value, a value too high may request too few samples resulting in a poor calibration. The following additional gcode commands are available during drift calibration: TEMPERATURE_PROBE_NEXT may be used to force a new sample before the step delta has been reached. TEMPERATURE_PROBE_COMPLETE may be used to complete calibration before the TARGET has been reached. ABORT may be used to end calibration and discard results. When calibration is finished use SAVE_CONFIG to store the drift calibration. As one may conclude, the calibration process outlined above is more challenging and time consuming than most other procedures. It may require practice and several attempts to achieve an optimal calibration.","title":"Thermal Drift Calibration"},{"location":"Endstop_Phase.html","text":"Endstop phase \u00b6 This document describes Klipper's stepper phase adjusted endstop system. This functionality can improve the accuracy of traditional endstop switches. It is most useful when using a Trinamic stepper motor driver that has run-time configuration. A typical endstop switch has an accuracy of around 100 microns. (Each time an axis is homed the switch may trigger slightly earlier or slightly later.) Although this is a relatively small error, it can result in unwanted artifacts. In particular, this positional deviation may be noticeable when printing the first layer of an object. In contrast, typical stepper motors can obtain significantly higher precision. The stepper phase adjusted endstop mechanism can use the precision of the stepper motors to improve the precision of the endstop switches. A stepper motor moves by cycling through a series of phases until in completes four \"full steps\". So, a stepper motor using 16 micro-steps would have 64 phases and when moving in a positive direction it would cycle through phases: 0, 1, 2, ... 61, 62, 63, 0, 1, 2, etc. Crucially, when the stepper motor is at a particular position on a linear rail it should always be at the same stepper phase. Thus, when a carriage triggers the endstop switch the stepper controlling that carriage should always be at the same stepper motor phase. Klipper's endstop phase system combines the stepper phase with the endstop trigger to improve the accuracy of the endstop. In order to use this functionality it is necessary to be able to identify the phase of the stepper motor. If one is using Trinamic TMC2130, TMC2208, TMC2224 or TMC2660 drivers in run-time configuration mode (ie, not stand-alone mode) then Klipper can query the stepper phase from the driver. (It is also possible to use this system on traditional stepper drivers if one can reliably reset the stepper drivers - see below for details.) Calibrating endstop phases \u00b6 If using Trinamic stepper motor drivers with run-time configuration then one can calibrate the endstop phases using the ENDSTOP_PHASE_CALIBRATE command. Start by adding the following to the config file: [endstop_phase] Then RESTART the printer and run a G28 command followed by an ENDSTOP_PHASE_CALIBRATE command. Then move the toolhead to a new location and run G28 again. Try moving the toolhead to several different locations and rerun G28 from each position. Run at least five G28 commands. After performing the above, the ENDSTOP_PHASE_CALIBRATE command will often report the same (or nearly the same) phase for the stepper. This phase can be saved in the config file so that all future G28 commands use that phase. (So, in future homing operations, Klipper will obtain the same position even if the endstop triggers a little earlier or a little later.) To save the endstop phase for a particular stepper motor, run something like the following: ENDSTOP_PHASE_CALIBRATE STEPPER=stepper_z Run the above for all the steppers one wishes to save. Typically, one would use this on stepper_z for cartesian and corexy printers, and for stepper_a, stepper_b, and stepper_c on delta printers. Finally, run the following to update the configuration file with the data: SAVE_CONFIG Additional notes \u00b6 This feature is most useful on delta printers and on the Z endstop of cartesian/corexy printers. It is possible to use this feature on the XY endstops of cartesian printers, but that isn't particularly useful as a minor error in X/Y endstop position is unlikely to impact print quality. It is not valid to use this feature on the XY endstops of corexy printers (as the XY position is not determined by a single stepper on corexy kinematics). It is not valid to use this feature on a printer using a \"probe:z_virtual_endstop\" Z endstop (as the stepper phase is only stable if the endstop is at a static location on a rail). After calibrating the endstop phase, if the endstop is later moved or adjusted then it will be necessary to recalibrate the endstop. Remove the calibration data from the config file and rerun the steps above. In order to use this system the endstop must be accurate enough to identify the stepper position within two \"full steps\". So, for example, if a stepper is using 16 micro-steps with a step distance of 0.005mm then the endstop must have an accuracy of at least 0.160mm. If one gets \"Endstop stepper_z incorrect phase\" type error messages than in may be due to an endstop that is not sufficiently accurate. If recalibration does not help then disable endstop phase adjustments by removing them from the config file. If one is using a traditional stepper controlled Z axis (as on a cartesian or corexy printer) along with traditional bed leveling screws then it is also possible to use this system to arrange for each print layer to be performed on a \"full step\" boundary. To enable this feature be sure the G-Code slicer is configured with a layer height that is a multiple of a \"full step\", manually enable the endstop_align_zero option in the endstop_phase config section (see config reference for further details), and then re-level the bed screws. It is possible to use this system with traditional (non-Trinamic) stepper motor drivers. However, doing this requires making sure that the stepper motor drivers are reset every time the micro-controller is reset. (If the two are always reset together then Klipper can determine the stepper phase by tracking the total number of steps it has commanded the stepper to move.) Currently, the only way to do this reliably is if both the micro-controller and stepper motor drivers are powered solely from USB and that USB power is provided from a host running on a Raspberry Pi. In this situation one can specify an mcu config with \"restart_method: rpi_usb\" - that option will arrange for the micro-controller to always be reset via a USB power reset, which would arrange for both the micro-controller and stepper motor drivers to be reset together. If using this mechanism, one would then need to manually configure the \"trigger_phase\" config sections (see config reference for the details).","title":"Endstop phase"},{"location":"Endstop_Phase.html#endstop-phase","text":"This document describes Klipper's stepper phase adjusted endstop system. This functionality can improve the accuracy of traditional endstop switches. It is most useful when using a Trinamic stepper motor driver that has run-time configuration. A typical endstop switch has an accuracy of around 100 microns. (Each time an axis is homed the switch may trigger slightly earlier or slightly later.) Although this is a relatively small error, it can result in unwanted artifacts. In particular, this positional deviation may be noticeable when printing the first layer of an object. In contrast, typical stepper motors can obtain significantly higher precision. The stepper phase adjusted endstop mechanism can use the precision of the stepper motors to improve the precision of the endstop switches. A stepper motor moves by cycling through a series of phases until in completes four \"full steps\". So, a stepper motor using 16 micro-steps would have 64 phases and when moving in a positive direction it would cycle through phases: 0, 1, 2, ... 61, 62, 63, 0, 1, 2, etc. Crucially, when the stepper motor is at a particular position on a linear rail it should always be at the same stepper phase. Thus, when a carriage triggers the endstop switch the stepper controlling that carriage should always be at the same stepper motor phase. Klipper's endstop phase system combines the stepper phase with the endstop trigger to improve the accuracy of the endstop. In order to use this functionality it is necessary to be able to identify the phase of the stepper motor. If one is using Trinamic TMC2130, TMC2208, TMC2224 or TMC2660 drivers in run-time configuration mode (ie, not stand-alone mode) then Klipper can query the stepper phase from the driver. (It is also possible to use this system on traditional stepper drivers if one can reliably reset the stepper drivers - see below for details.)","title":"Endstop phase"},{"location":"Endstop_Phase.html#calibrating-endstop-phases","text":"If using Trinamic stepper motor drivers with run-time configuration then one can calibrate the endstop phases using the ENDSTOP_PHASE_CALIBRATE command. Start by adding the following to the config file: [endstop_phase] Then RESTART the printer and run a G28 command followed by an ENDSTOP_PHASE_CALIBRATE command. Then move the toolhead to a new location and run G28 again. Try moving the toolhead to several different locations and rerun G28 from each position. Run at least five G28 commands. After performing the above, the ENDSTOP_PHASE_CALIBRATE command will often report the same (or nearly the same) phase for the stepper. This phase can be saved in the config file so that all future G28 commands use that phase. (So, in future homing operations, Klipper will obtain the same position even if the endstop triggers a little earlier or a little later.) To save the endstop phase for a particular stepper motor, run something like the following: ENDSTOP_PHASE_CALIBRATE STEPPER=stepper_z Run the above for all the steppers one wishes to save. Typically, one would use this on stepper_z for cartesian and corexy printers, and for stepper_a, stepper_b, and stepper_c on delta printers. Finally, run the following to update the configuration file with the data: SAVE_CONFIG","title":"Calibrating endstop phases"},{"location":"Endstop_Phase.html#additional-notes","text":"This feature is most useful on delta printers and on the Z endstop of cartesian/corexy printers. It is possible to use this feature on the XY endstops of cartesian printers, but that isn't particularly useful as a minor error in X/Y endstop position is unlikely to impact print quality. It is not valid to use this feature on the XY endstops of corexy printers (as the XY position is not determined by a single stepper on corexy kinematics). It is not valid to use this feature on a printer using a \"probe:z_virtual_endstop\" Z endstop (as the stepper phase is only stable if the endstop is at a static location on a rail). After calibrating the endstop phase, if the endstop is later moved or adjusted then it will be necessary to recalibrate the endstop. Remove the calibration data from the config file and rerun the steps above. In order to use this system the endstop must be accurate enough to identify the stepper position within two \"full steps\". So, for example, if a stepper is using 16 micro-steps with a step distance of 0.005mm then the endstop must have an accuracy of at least 0.160mm. If one gets \"Endstop stepper_z incorrect phase\" type error messages than in may be due to an endstop that is not sufficiently accurate. If recalibration does not help then disable endstop phase adjustments by removing them from the config file. If one is using a traditional stepper controlled Z axis (as on a cartesian or corexy printer) along with traditional bed leveling screws then it is also possible to use this system to arrange for each print layer to be performed on a \"full step\" boundary. To enable this feature be sure the G-Code slicer is configured with a layer height that is a multiple of a \"full step\", manually enable the endstop_align_zero option in the endstop_phase config section (see config reference for further details), and then re-level the bed screws. It is possible to use this system with traditional (non-Trinamic) stepper motor drivers. However, doing this requires making sure that the stepper motor drivers are reset every time the micro-controller is reset. (If the two are always reset together then Klipper can determine the stepper phase by tracking the total number of steps it has commanded the stepper to move.) Currently, the only way to do this reliably is if both the micro-controller and stepper motor drivers are powered solely from USB and that USB power is provided from a host running on a Raspberry Pi. In this situation one can specify an mcu config with \"restart_method: rpi_usb\" - that option will arrange for the micro-controller to always be reset via a USB power reset, which would arrange for both the micro-controller and stepper motor drivers to be reset together. If using this mechanism, one would then need to manually configure the \"trigger_phase\" config sections (see config reference for the details).","title":"Additional notes"},{"location":"Example_Configs.html","text":"Example configurations \u00b6 This document contains guidelines for contributing an example Klipper configuration to the Klipper github repository (located in the config directory ). Note that the Klipper Community Discourse server is also a useful resource for finding and sharing config files. Guidelines \u00b6 Select the appropriate config filename prefix: The printer prefix is used for stock printers sold by a mainstream manufacturer. The generic prefix is used for a 3d printer board that may be used in many different types of printers. The kit prefix is for 3d printers that are assembled according to a widely used specification. These \"kit\" printers are generally distinct from normal \"printers\" in that they are not sold by a manufacturer. The sample prefix is used for config \"snippets\" that one may copy-and-paste into the main config file. The example prefix is used to describe printer kinematics. This type of config is typically only added along with code for a new type of printer kinematics. All configuration files must end in a .cfg suffix. The printer config files must end in a year followed by .cfg (eg, -2019.cfg ). In this case, the year is an approximate year the given printer was sold. Do not use spaces or special characters in the config filename. The filename should contain only characters A-Z , a-z , 0-9 , - , and . . Klipper must be able to start printer , generic , and kit example config file without error. These config files should be added to the test/klippy/printers.test regression test case. Add new config files to that test case in the appropriate section and in alphabetical order within that section. The example configuration should be for the \"stock\" configuration of the printer. (There are too many \"customized\" configurations to track in the main Klipper repository.) Similarly, we only add example config files for printers, kits, and boards that have mainstream popularity (eg, there should be at least a 100 of them in active use). Consider using the Klipper Community Discourse server for other configs. Only specify those devices present on the given printer or board. Do not specify settings specific to your particular setup. For generic config files, only those devices on the mainboard should be described. For example, it would not make sense to add a display config section to a \"generic\" config as there is no way to know if the board will be attached to that type of display. If the board has a specific hardware port to facilitate an optional peripheral (eg, a bltouch port) then one can add a \"commented out\" config section for the given device. Do not specify pressure_advance in an example config, as that value is specific to the filament, not the printer hardware. Similarly, do not specify max_extrude_only_velocity nor max_extrude_only_accel settings. Do not specify a config section containing a host path or host hardware. For example, do not specify [virtual_sdcard] nor [temperature_host] config sections. Only define macros that utilize functionality specific to the given printer or to define g-codes that are commonly emitted by slicers configured for the given printer. Where possible, it is best to use the same wording, phrasing, indentation, and section ordering as the existing config files. The top of each config file should list the type of micro-controller the user should select during \"make menuconfig\". It should also have a reference to \"docs/Config_Reference.md\". Do not copy the field documentation into the example config files. (Doing so creates a maintenance burden as an update to the documentation would then require changing it in many places.) Example config files should not contain a \"SAVE_CONFIG\" section. If necessary, copy the relevant fields from the SAVE_CONFIG section to the appropriate section in the main config area. Use field: value syntax instead of field=value . When adding an extruder rotation_distance it is preferable to specify a gear_ratio if the extruder has a gearing mechanism. We expect the rotation_distance in the example configs to correlate with the circumference of the hobbed gear in the extruder - it is normally in the range of 20 to 35mm. When specifying a gear_ratio it is preferable to specify the actual gears on the mechanism (eg, prefer gear_ratio: 80:20 over gear_ratio: 4:1 ). See the rotation distance document for more information. Avoid defining field values that are set to their default value. For example, one should not specify min_extrude_temp: 170 as that is already the default value. Where possible, lines should not exceed 80 columns. Avoid adding attribution or revision messages to the config files. (For example, avoid adding lines like \"this file was created by ...\".) Place attribution and change history in the git commit message. Do not use any deprecated features in the example config file. Do not disable a default safety system in an example config file. For example, a config should not specify a custom max_extrude_cross_section . Do not enable debugging features. For example there should not be a force_move config section. All known boards that Klipper supports can use the default serial baud rate of 250000. Do not recommend a different baud rate in an example config file. Example config files are submitted by creating a github \"pull request\". Please also follow the directions in the contributing document .","title":"Example configurations"},{"location":"Example_Configs.html#example-configurations","text":"This document contains guidelines for contributing an example Klipper configuration to the Klipper github repository (located in the config directory ). Note that the Klipper Community Discourse server is also a useful resource for finding and sharing config files.","title":"Example configurations"},{"location":"Example_Configs.html#guidelines","text":"Select the appropriate config filename prefix: The printer prefix is used for stock printers sold by a mainstream manufacturer. The generic prefix is used for a 3d printer board that may be used in many different types of printers. The kit prefix is for 3d printers that are assembled according to a widely used specification. These \"kit\" printers are generally distinct from normal \"printers\" in that they are not sold by a manufacturer. The sample prefix is used for config \"snippets\" that one may copy-and-paste into the main config file. The example prefix is used to describe printer kinematics. This type of config is typically only added along with code for a new type of printer kinematics. All configuration files must end in a .cfg suffix. The printer config files must end in a year followed by .cfg (eg, -2019.cfg ). In this case, the year is an approximate year the given printer was sold. Do not use spaces or special characters in the config filename. The filename should contain only characters A-Z , a-z , 0-9 , - , and . . Klipper must be able to start printer , generic , and kit example config file without error. These config files should be added to the test/klippy/printers.test regression test case. Add new config files to that test case in the appropriate section and in alphabetical order within that section. The example configuration should be for the \"stock\" configuration of the printer. (There are too many \"customized\" configurations to track in the main Klipper repository.) Similarly, we only add example config files for printers, kits, and boards that have mainstream popularity (eg, there should be at least a 100 of them in active use). Consider using the Klipper Community Discourse server for other configs. Only specify those devices present on the given printer or board. Do not specify settings specific to your particular setup. For generic config files, only those devices on the mainboard should be described. For example, it would not make sense to add a display config section to a \"generic\" config as there is no way to know if the board will be attached to that type of display. If the board has a specific hardware port to facilitate an optional peripheral (eg, a bltouch port) then one can add a \"commented out\" config section for the given device. Do not specify pressure_advance in an example config, as that value is specific to the filament, not the printer hardware. Similarly, do not specify max_extrude_only_velocity nor max_extrude_only_accel settings. Do not specify a config section containing a host path or host hardware. For example, do not specify [virtual_sdcard] nor [temperature_host] config sections. Only define macros that utilize functionality specific to the given printer or to define g-codes that are commonly emitted by slicers configured for the given printer. Where possible, it is best to use the same wording, phrasing, indentation, and section ordering as the existing config files. The top of each config file should list the type of micro-controller the user should select during \"make menuconfig\". It should also have a reference to \"docs/Config_Reference.md\". Do not copy the field documentation into the example config files. (Doing so creates a maintenance burden as an update to the documentation would then require changing it in many places.) Example config files should not contain a \"SAVE_CONFIG\" section. If necessary, copy the relevant fields from the SAVE_CONFIG section to the appropriate section in the main config area. Use field: value syntax instead of field=value . When adding an extruder rotation_distance it is preferable to specify a gear_ratio if the extruder has a gearing mechanism. We expect the rotation_distance in the example configs to correlate with the circumference of the hobbed gear in the extruder - it is normally in the range of 20 to 35mm. When specifying a gear_ratio it is preferable to specify the actual gears on the mechanism (eg, prefer gear_ratio: 80:20 over gear_ratio: 4:1 ). See the rotation distance document for more information. Avoid defining field values that are set to their default value. For example, one should not specify min_extrude_temp: 170 as that is already the default value. Where possible, lines should not exceed 80 columns. Avoid adding attribution or revision messages to the config files. (For example, avoid adding lines like \"this file was created by ...\".) Place attribution and change history in the git commit message. Do not use any deprecated features in the example config file. Do not disable a default safety system in an example config file. For example, a config should not specify a custom max_extrude_cross_section . Do not enable debugging features. For example there should not be a force_move config section. All known boards that Klipper supports can use the default serial baud rate of 250000. Do not recommend a different baud rate in an example config file. Example config files are submitted by creating a github \"pull request\". Please also follow the directions in the contributing document .","title":"Guidelines"},{"location":"Exclude_Object.html","text":"Exclude Objects \u00b6 The [exclude_object] module allows Klipper to exclude objects while a print is in progress. To enable this feature include an exclude_object config section (also see the command reference and sample-macros.cfg file for a Marlin/RepRapFirmware compatible M486 G-Code macro.) Unlike other 3D printer firmware options, a printer running Klipper utilizes a suite of components and users have many options to choose from. Therefore, in order to provide a a consistent user experience, the [exclude_object] module will establish a contract or API of sorts. The contract covers the contents of the gcode file, how the internal state of the module is controlled, and how that state is provided to clients. Workflow Overview \u00b6 A typical workflow for printing a file might look like this: Slicing is completed and the file is uploaded for printing. During the upload, the file is processed and [exclude_object] markers are added to the file. Alternately, slicers may be configured to prepare object exclusion markers natively, or in it's own pre-processing step. When printing starts, Klipper will reset the [exclude_object] status . When Klipper processes the EXCLUDE_OBJECT_DEFINE block, it will update the status with the known objects and pass it on to clients. The client may use that information to present a UI to the user so that progress can be tracked. Klipper will update the status to include the currently printing object which the client can use for display purposes. If the user requests that an object be cancelled, the client will issue an EXCLUDE_OBJECT NAME=<name> command to Klipper. When Klipper process the command, it will add the object to the list of excluded objects and update the status for the client. The client will receive the updated status from Klipper and can use that information to reflect the object's status in the UI. When printing finishes, the [exclude_object] status will continue to be available until another action resets it. The GCode File \u00b6 The specialized gcode processing needed to support excluding objects does not fit into Klipper's core design goals. Therefore, this module requires that the file is processed before being sent to Klipper for printing. Using a post-process script in the slicer or having middleware process the file on upload are two possibilities for preparing the file for Klipper. A reference post-processing script is available both as an executable and a python library, see cancelobject-preprocessor . Object Definitions \u00b6 The EXCLUDE_OBJECT_DEFINE command is used to provide a summary of each object in the gcode file to be printed. Provides a summary of an object in the file. Objects don't need to be defined in order to be referenced by other commands. The primary purpose of this command is to provide information to the UI without needing to parse the entire gcode file. Object definitions are named, to allow users to easily select an object to be excluded, and additional metadata may be provided to allow for graphical cancellation displays. Currently defined metadata includes a CENTER X,Y coordinate, and a POLYGON list of X,Y points representing a minimal outline of the object. This could be a simple bounding box, or a complicated hull for showing more detailed visualizations of the printed objects. Especially when gcode files include multiple parts with overlapping bounding regions, center points become hard to visually distinguish. POLYGONS must be a json-compatible array of point [X,Y] tuples without whitespace. Additional parameters will be saved as strings in the object definition and provided in status updates. EXCLUDE_OBJECT_DEFINE NAME=calibration_pyramid CENTER=50,50 POLYGON=[[40,40],[50,60],[60,40]] All available G-Code commands are documented in the G-Code Reference Status Information \u00b6 The state of this module is provided to clients by the exclude_object status . The status is reset when: The Klipper firmware is restarted. There is a reset of the [virtual_sdcard] . Notably, this is reset by Klipper at the start of a print. When an EXCLUDE_OBJECT_DEFINE RESET=1 command is issued. The list of defined objects is represented in the exclude_object.objects status field. In a well defined gcode file, this will be done with EXCLUDE_OBJECT_DEFINE commands at the beginning of the file. This will provide clients with object names and coordinates so the UI can provide a graphical representation of the objects if desired. As the print progresses, the exclude_object.current_object status field will be updated as Klipper processes EXCLUDE_OBJECT_START and EXCLUDE_OBJECT_END commands. The current_object field will be set even if the object has been excluded. Undefined objects marked with a EXCLUDE_OBJECT_START will be added to the known objects to assist in UI hinting, without any additional metadata. As EXCLUDE_OBJECT commands are issued, the list of excluded objects is provided in the exclude_object.excluded_objects array. Since Klipper looks ahead to process upcoming gcode, there may be a delay between when the command is issued and when the status is updated.","title":"Exclude Objects"},{"location":"Exclude_Object.html#exclude-objects","text":"The [exclude_object] module allows Klipper to exclude objects while a print is in progress. To enable this feature include an exclude_object config section (also see the command reference and sample-macros.cfg file for a Marlin/RepRapFirmware compatible M486 G-Code macro.) Unlike other 3D printer firmware options, a printer running Klipper utilizes a suite of components and users have many options to choose from. Therefore, in order to provide a a consistent user experience, the [exclude_object] module will establish a contract or API of sorts. The contract covers the contents of the gcode file, how the internal state of the module is controlled, and how that state is provided to clients.","title":"Exclude Objects"},{"location":"Exclude_Object.html#workflow-overview","text":"A typical workflow for printing a file might look like this: Slicing is completed and the file is uploaded for printing. During the upload, the file is processed and [exclude_object] markers are added to the file. Alternately, slicers may be configured to prepare object exclusion markers natively, or in it's own pre-processing step. When printing starts, Klipper will reset the [exclude_object] status . When Klipper processes the EXCLUDE_OBJECT_DEFINE block, it will update the status with the known objects and pass it on to clients. The client may use that information to present a UI to the user so that progress can be tracked. Klipper will update the status to include the currently printing object which the client can use for display purposes. If the user requests that an object be cancelled, the client will issue an EXCLUDE_OBJECT NAME=<name> command to Klipper. When Klipper process the command, it will add the object to the list of excluded objects and update the status for the client. The client will receive the updated status from Klipper and can use that information to reflect the object's status in the UI. When printing finishes, the [exclude_object] status will continue to be available until another action resets it.","title":"Workflow Overview"},{"location":"Exclude_Object.html#the-gcode-file","text":"The specialized gcode processing needed to support excluding objects does not fit into Klipper's core design goals. Therefore, this module requires that the file is processed before being sent to Klipper for printing. Using a post-process script in the slicer or having middleware process the file on upload are two possibilities for preparing the file for Klipper. A reference post-processing script is available both as an executable and a python library, see cancelobject-preprocessor .","title":"The GCode File"},{"location":"Exclude_Object.html#object-definitions","text":"The EXCLUDE_OBJECT_DEFINE command is used to provide a summary of each object in the gcode file to be printed. Provides a summary of an object in the file. Objects don't need to be defined in order to be referenced by other commands. The primary purpose of this command is to provide information to the UI without needing to parse the entire gcode file. Object definitions are named, to allow users to easily select an object to be excluded, and additional metadata may be provided to allow for graphical cancellation displays. Currently defined metadata includes a CENTER X,Y coordinate, and a POLYGON list of X,Y points representing a minimal outline of the object. This could be a simple bounding box, or a complicated hull for showing more detailed visualizations of the printed objects. Especially when gcode files include multiple parts with overlapping bounding regions, center points become hard to visually distinguish. POLYGONS must be a json-compatible array of point [X,Y] tuples without whitespace. Additional parameters will be saved as strings in the object definition and provided in status updates. EXCLUDE_OBJECT_DEFINE NAME=calibration_pyramid CENTER=50,50 POLYGON=[[40,40],[50,60],[60,40]] All available G-Code commands are documented in the G-Code Reference","title":"Object Definitions"},{"location":"Exclude_Object.html#status-information","text":"The state of this module is provided to clients by the exclude_object status . The status is reset when: The Klipper firmware is restarted. There is a reset of the [virtual_sdcard] . Notably, this is reset by Klipper at the start of a print. When an EXCLUDE_OBJECT_DEFINE RESET=1 command is issued. The list of defined objects is represented in the exclude_object.objects status field. In a well defined gcode file, this will be done with EXCLUDE_OBJECT_DEFINE commands at the beginning of the file. This will provide clients with object names and coordinates so the UI can provide a graphical representation of the objects if desired. As the print progresses, the exclude_object.current_object status field will be updated as Klipper processes EXCLUDE_OBJECT_START and EXCLUDE_OBJECT_END commands. The current_object field will be set even if the object has been excluded. Undefined objects marked with a EXCLUDE_OBJECT_START will be added to the known objects to assist in UI hinting, without any additional metadata. As EXCLUDE_OBJECT commands are issued, the list of excluded objects is provided in the exclude_object.excluded_objects array. Since Klipper looks ahead to process upcoming gcode, there may be a delay between when the command is issued and when the status is updated.","title":"Status Information"},{"location":"FAQ.html","text":"Frequently Asked Questions \u00b6 How can I donate to the project? \u00b6 Thank you for your support. See the Sponsors page for information. How do I calculate the rotation_distance config parameter? \u00b6 See the rotation distance document . Where's my serial port? \u00b6 The general way to find a USB serial port is to run ls /dev/serial/by-id/* from an ssh terminal on the host machine. It will likely produce output similar to the following: /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 The name found in the above command is stable and it is possible to use it in the config file and while flashing the micro-controller code. For example, a flash command might look similar to: sudo service klipper stop make flash FLASH_DEVICE=/dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 sudo service klipper start and the updated config might look like: [mcu] serial: /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 Be sure to copy-and-paste the name from the \"ls\" command that you ran above as the name will be different for each printer. If you are using multiple micro-controllers and they do not have unique ids (common on boards with a CH340 USB chip) then follow the directions above using the command ls /dev/serial/by-path/* instead. When the micro-controller restarts the device changes to /dev/ttyUSB1 \u00b6 Follow the directions in the \" Where's my serial port? \" section to prevent this from occurring. The \"make flash\" command doesn't work \u00b6 The code attempts to flash the device using the most common method for each platform. Unfortunately, there is a lot of variance in flashing methods, so the \"make flash\" command may not work on all boards. If you're having an intermittent failure or you do have a standard setup, then double check that Klipper isn't running when flashing (sudo service klipper stop), make sure OctoPrint isn't trying to connect directly to the device (open the Connection tab in the web page and click Disconnect if the Serial Port is set to the device), and make sure FLASH_DEVICE is set correctly for your board (see the question above ). However, if \"make flash\" just doesn't work for your board, then you will need to manually flash. See if there is a config file in the config directory with specific instructions for flashing the device. Also, check the board manufacturer's documentation to see if it describes how to flash the device. Finally, it may be possible to manually flash the device using tools such as \"avrdude\" or \"bossac\" - see the bootloader document for additional information. How do I change the serial baud rate? \u00b6 The recommended baud rate for Klipper is 250000. This baud rate works well on all micro-controller boards that Klipper supports. If you've found an online guide recommending a different baud rate, then ignore that part of the guide and continue with the default value of 250000. If you want to change the baud rate anyway, then the new rate will need to be configured in the micro-controller (during make menuconfig ) and that updated code will need to be compiled and flashed to the micro-controller. The Klipper printer.cfg file will also need to be updated to match that baud rate (see the config reference for details). For example: [mcu] baud: 250000 The baud rate shown on the OctoPrint web page has no impact on the internal Klipper micro-controller baud rate. Always set the OctoPrint baud rate to 250000 when using Klipper. The Klipper micro-controller baud rate is not related to the baud rate of the micro-controller's bootloader. See the bootloader document for additional information on bootloaders. Can I run Klipper on something other than a Raspberry Pi 3? \u00b6 The recommended hardware is a Raspberry Pi Zero2w, Raspberry Pi 3, Raspberry Pi 4 or Raspberry Pi 5. Klipper will also run on other SBC devices as well as x86 hardware, as described below. Klipper will run on a Raspberry Pi 1, 2 and on the Raspberry Pi Zero1, but these boards don't have enough processing power to run Klipper well. It is common for print stalls to occur on these slower machines when printing (The printer may move faster than Klipper can send movement commands.) It is not reccomended to run Kliper on these older machines. For running on the Beaglebone, see the Beaglebone specific installation instructions . Klipper has been run on other machines. The Klipper host software only requires Python running on a Linux (or similar) computer. However, if you wish to run it on a different machine you will need Linux admin knowledge to install the system prerequisites for that particular machine. See the install-octopi.sh script for further information on the necessary Linux admin steps. If you are looking to run the Klipper host software on a low-end chip, then be aware that, at a minimum, a machine with \"double precision floating point\" hardware is required. If you are looking to run the Klipper host software on a shared general-purpose desktop or server class machine, then note that Klipper has some real-time scheduling requirements. If, during a print, the host computer also performs an intensive general-purpose computing task (such as defragmenting a hard drive, 3d rendering, heavy swapping, etc.), then it may cause Klipper to report print errors. Note: If you are not using an OctoPi image, be aware that several Linux distributions enable a \"ModemManager\" (or similar) package that can disrupt serial communication. (Which can cause Klipper to report seemingly random \"Lost communication with MCU\" errors.) If you install Klipper on one of these distributions you may need to disable that package. Can I run multiple instances of Klipper on the same host machine? \u00b6 It is possible to run multiple instances of the Klipper host software, but doing so requires Linux admin knowledge. The Klipper installation scripts ultimately cause the following Unix command to be run: ~/klippy-env/bin/python ~/klipper/klippy/klippy.py ~/printer.cfg -l /tmp/klippy.log One can run multiple instances of the above command as long as each instance has its own printer config file, its own log file, and its own pseudo-tty. For example: ~/klippy-env/bin/python ~/klipper/klippy/klippy.py ~/printer2.cfg -l /tmp/klippy2.log -I /tmp/printer2 If you choose to do this, you will need to implement the necessary start, stop, and installation scripts (if any). The install-octopi.sh script and the klipper-start.sh script may be useful as examples. Do I have to use OctoPrint? \u00b6 The Klipper software is not dependent on OctoPrint. It is possible to use alternative software to send commands to Klipper, but doing so requires Linux admin knowledge. Klipper creates a \"virtual serial port\" via the \"/tmp/printer\" file, and it emulates a classic 3d-printer serial interface via that file. In general, alternative software may work with Klipper as long as it can be configured to use \"/tmp/printer\" for the printer serial port. Why can't I move the stepper before homing the printer? \u00b6 The code does this to reduce the chance of accidentally commanding the head into the bed or a wall. Once the printer is homed the software attempts to verify each move is within the position_min/max defined in the config file. If the motors are disabled (via an M84 or M18 command) then the motors will need to be homed again prior to movement. If you want to move the head after canceling a print via OctoPrint, consider changing the OctoPrint cancel sequence to do that for you. It's configured in OctoPrint via a web browser under: Settings->GCODE Scripts If you want to move the head after a print finishes, consider adding the desired movement to the \"custom g-code\" section of your slicer. If the printer requires some additional movement as part of the homing process itself (or fundamentally does not have a homing process) then consider using a safe_z_home or homing_override section in the config file. If you need to move a stepper for diagnostic or debugging purposes then consider adding a force_move section to the config file. See config reference for further details on these options. Why is the Z position_endstop set to 0.5 in the default configs? \u00b6 For cartesian style printers the Z position_endstop specifies how far the nozzle is from the bed when the endstop triggers. If possible, it is recommended to use a Z-max endstop and home away from the bed (as this reduces the potential for bed collisions). However, if one must home towards the bed then it is recommended to position the endstop so it triggers when the nozzle is still a small distance away from the bed. This way, when homing the axis, it will stop before the nozzle touches the bed. See the bed level document for more information. I converted my config from Marlin and the X/Y axes work fine, but I just get a screeching noise when homing the Z axis \u00b6 Short answer: First, make sure you have verified the stepper configuration as described in the config check document . If the problem persists, try reducing the max_z_velocity setting in the printer config. Long answer: In practice Marlin can typically only step at a rate of around 10000 steps per second. If it is requested to move at a speed that would require a higher step rate then Marlin will generally just step as fast as it can. Klipper is able to achieve much higher step rates, but the stepper motor may not have sufficient torque to move at a higher speed. So, for a Z axis with a high gearing ratio or high microsteps setting the actual obtainable max_z_velocity may be smaller than what is configured in Marlin. My TMC motor driver turns off in the middle of a print \u00b6 If using the TMC2208 (or TMC2224) driver in \"standalone mode\" then make sure to use the latest version of Klipper . A workaround for a TMC2208 \"stealthchop\" driver problem was added to Klipper in mid-March of 2020. I keep getting random \"Lost communication with MCU\" errors \u00b6 This is commonly caused by hardware errors on the USB connection between the host machine and the micro-controller. Things to look for: Use a good quality USB cable between the host machine and micro-controller. Make sure the plugs are secure. If using a Raspberry Pi, use a good quality power supply for the Raspberry Pi and use a good quality USB cable to connect that power supply to the Pi. If you get \"under voltage\" warnings from OctoPrint, this is related to the power supply and it must be fixed. Make sure the printer's power supply is not being overloaded. (Power fluctuations to the micro-controller's USB chip may result in resets of that chip.) Verify stepper, heater, and other printer wires are not crimped or frayed. (Printer movement may place stress on a faulty wire causing it to lose contact, briefly short, or generate excessive noise.) There have been reports of high USB noise when both the printer's power supply and the host's 5V power supply are mixed. (If you find that the micro-controller powers on when either the printer's power supply is on or the USB cable is plugged in, then it indicates the 5V power supplies are being mixed.) It may help to configure the micro-controller to use power from only one source. (Alternatively, if the micro-controller board can not configure its power source, one may modify a USB cable so that it does not carry 5V power between the host and micro-controller.) My Raspberry Pi keeps rebooting during prints \u00b6 This is most likely do to voltage fluctuations. Follow the same troubleshooting steps for a \"Lost communication with MCU\" error. When I set restart_method=command my AVR device just hangs on a restart \u00b6 Some old versions of the AVR bootloader have a known bug in watchdog event handling. This typically manifests when the printer.cfg file has restart_method set to \"command\". When the bug occurs, the AVR device will be unresponsive until power is removed and reapplied to the device (the power or status LEDs may also blink repeatedly until the power is removed). The workaround is to use a restart_method other than \"command\" or to flash an updated bootloader to the AVR device. Flashing a new bootloader is a one time step that typically requires an external programmer - see Bootloaders for further details. Will the heaters be left on if the Raspberry Pi crashes? \u00b6 The software has been designed to prevent that. Once the host enables a heater, the host software needs to confirm that enablement every 5 seconds. If the micro-controller does not receive a confirmation every 5 seconds it goes into a \"shutdown\" state which is designed to turn off all heaters and stepper motors. See the \"config_digital_out\" command in the MCU commands document for further details. In addition, the micro-controller software is configured with a minimum and maximum temperature range for each heater at startup (see the min_temp and max_temp parameters in the config reference for details). If the micro-controller detects that the temperature is outside of that range then it will also enter a \"shutdown\" state. Separately, the host software also implements code to check that heaters and temperature sensors are functioning correctly. See the config reference for further details. How do I convert a Marlin pin number to a Klipper pin name? \u00b6 Short answer: A mapping is available in the sample-aliases.cfg file. Use that file as a guide to finding the actual micro-controller pin names. (It is also possible to copy the relevant board_pins config section into your config file and use the aliases in your config, but it is preferable to translate and use the actual micro-controller pin names.) Note that the sample-aliases.cfg file uses pin names that start with the prefix \"ar\" instead of \"D\" (eg, Arduino pin D23 is Klipper alias ar23 ) and the prefix \"analog\" instead of \"A\" (eg, Arduino pin A14 is Klipper alias analog14 ). Long answer: Klipper uses the standard pin names defined by the micro-controller. On the Atmega chips these hardware pins have names like PA4 , PC7 , or PD2 . Long ago, the Arduino project decided to avoid using the standard hardware names in favor of their own pin names based on incrementing numbers - these Arduino names generally look like D23 or A14 . This was an unfortunate choice that has lead to a great deal of confusion. In particular the Arduino pin numbers frequently don't translate to the same hardware names. For example, D21 is PD0 on one common Arduino board, but is PC7 on another common Arduino board. To avoid this confusion, the core Klipper code uses the standard pin names defined by the micro-controller. Do I have to wire my device to a specific type of micro-controller pin? \u00b6 It depends on the type of device and type of pin: ADC pins (or Analog pins): For thermistors and similar \"analog\" sensors, the device must be wired to an \"analog\" or \"ADC\" capable pin on the micro-controller. If you configure Klipper to use a pin that is not analog capable, Klipper will report a \"Not a valid ADC pin\" error. PWM pins (or Timer pins): Klipper does not use hardware PWM by default for any device. So, in general, one may wire heaters, fans, and similar devices to any general purpose IO pin. However, fans and output_pin devices may be optionally configured to use hardware_pwm: True , in which case the micro-controller must support hardware PWM on the pin (otherwise, Klipper will report a \"Not a valid PWM pin\" error). IRQ pins (or Interrupt pins): Klipper does not use hardware interrupts on IO pins, so it is never necessary to wire a device to one of these micro-controller pins. SPI pins: When using hardware SPI it is necessary to wire the pins to the micro-controller's SPI capable pins. However, most devices can be configured to use \"software SPI\", in which case any general purpose IO pins may be used. I2C pins: When using I2C it is necessary to wire the pins to the micro-controller's I2C capable pins. Other devices may be wired to any general purpose IO pin. For example, steppers, heaters, fans, Z probes, servos, LEDs, common hd44780/st7920 LCD displays, the Trinamic UART control line may be wired to any general purpose IO pin. How do I cancel an M109/M190 \"wait for temperature\" request? \u00b6 Navigate to the OctoPrint terminal tab and issue an M112 command in the terminal box. The M112 command will cause Klipper to enter into a \"shutdown\" state, and it will cause OctoPrint to disconnect from Klipper. Navigate to the OctoPrint connection area and click on \"Connect\" to cause OctoPrint to reconnect. Navigate back to the terminal tab and issue a FIRMWARE_RESTART command to clear the Klipper error state. After completing this sequence, the previous heating request will be canceled and a new print may be started. Can I find out whether the printer has lost steps? \u00b6 In a way, yes. Home the printer, issue a GET_POSITION command, run your print, home again and issue another GET_POSITION . Then compare the values in the mcu: line. This might be helpful to tune settings like stepper motor currents, accelerations and speeds without needing to actually print something and waste filament: just run some high-speed moves in between the GET_POSITION commands. Note that endstop switches themselves tend to trigger at slightly different positions, so a difference of a couple of microsteps is likely the result of endstop inaccuracies. A stepper motor itself can only lose steps in increments of 4 full steps. (So, if one is using 16 microsteps, then a lost step on the stepper would result in the \"mcu:\" step counter being off by a multiple of 64 microsteps.) Why does Klipper report errors? I lost my print! \u00b6 Short answer: We want to know if our printers detect a problem so that the underlying issue can be fixed and we can obtain great quality prints. We definitely do not want our printers to silently produce low quality prints. Long answer: Klipper has been engineered to automatically workaround many transient problems. For example, it automatically detects communication errors and will retransmit; it schedules actions in advance and buffers commands at multiple layers to enable precise timing even with intermittent interference. However, should the software detect an error that it can not recover from, if it is commanded to take an invalid action, or if it detects it is hopelessly unable to perform its commanded task, then Klipper will report an error. In these situations there is a high risk of producing a low-quality print (or worse). It is hoped that alerting the user will empower them to fix the underlying issue and improve the overall quality of their prints. There are some related questions: Why doesn't Klipper pause the print instead? Report a warning instead? Check for errors before the print? Ignore errors in user typed commands? etc? Currently Klipper reads commands using the G-Code protocol, and unfortunately the G-Code command protocol is not flexible enough to make these alternatives practical today. There is developer interest in improving the user experience during abnormal events, but it is expected that will require notable infrastructure work (including a shift away from G-Code). How do I upgrade to the latest software? \u00b6 The first step to upgrading the software is to review the latest config changes document. On occasion, changes are made to the software that require users to update their settings as part of a software upgrade. It is a good idea to review this document prior to upgrading. When ready to upgrade, the general method is to ssh into the Raspberry Pi and run: cd ~/klipper git pull ~/klipper/scripts/install-octopi.sh Then one can recompile and flash the micro-controller code. For example: make menuconfig make clean make sudo service klipper stop make flash FLASH_DEVICE=/dev/ttyACM0 sudo service klipper start However, it's often the case that only the host software changes. In this case, one can update and restart just the host software with: cd ~/klipper git pull sudo service klipper restart If after using this shortcut the software warns about needing to reflash the micro-controller or some other unusual error occurs, then follow the full upgrade steps outlined above. If any errors persist then double check the config changes document, as you may need to modify the printer configuration. Note that the RESTART and FIRMWARE_RESTART g-code commands do not load new software - the above \"sudo service klipper restart\" and \"make flash\" commands are needed for a software change to take effect. How do I uninstall Klipper? \u00b6 On the firmware end, nothing special needs to happen. Just follow the flashing directions for the new firmware. On the raspberry pi end, an uninstall script is available in scripts/klipper-uninstall.sh . For example: sudo ~/klipper/scripts/klipper-uninstall.sh rm -rf ~/klippy-env ~/klipper","title":"Frequently Asked Questions"},{"location":"FAQ.html#frequently-asked-questions","text":"","title":"Frequently Asked Questions"},{"location":"FAQ.html#how-can-i-donate-to-the-project","text":"Thank you for your support. See the Sponsors page for information.","title":"How can I donate to the project?"},{"location":"FAQ.html#how-do-i-calculate-the-rotation_distance-config-parameter","text":"See the rotation distance document .","title":"How do I calculate the rotation_distance config parameter?"},{"location":"FAQ.html#wheres-my-serial-port","text":"The general way to find a USB serial port is to run ls /dev/serial/by-id/* from an ssh terminal on the host machine. It will likely produce output similar to the following: /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 The name found in the above command is stable and it is possible to use it in the config file and while flashing the micro-controller code. For example, a flash command might look similar to: sudo service klipper stop make flash FLASH_DEVICE=/dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 sudo service klipper start and the updated config might look like: [mcu] serial: /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 Be sure to copy-and-paste the name from the \"ls\" command that you ran above as the name will be different for each printer. If you are using multiple micro-controllers and they do not have unique ids (common on boards with a CH340 USB chip) then follow the directions above using the command ls /dev/serial/by-path/* instead.","title":"Where's my serial port?"},{"location":"FAQ.html#when-the-micro-controller-restarts-the-device-changes-to-devttyusb1","text":"Follow the directions in the \" Where's my serial port? \" section to prevent this from occurring.","title":"When the micro-controller restarts the device changes to /dev/ttyUSB1"},{"location":"FAQ.html#the-make-flash-command-doesnt-work","text":"The code attempts to flash the device using the most common method for each platform. Unfortunately, there is a lot of variance in flashing methods, so the \"make flash\" command may not work on all boards. If you're having an intermittent failure or you do have a standard setup, then double check that Klipper isn't running when flashing (sudo service klipper stop), make sure OctoPrint isn't trying to connect directly to the device (open the Connection tab in the web page and click Disconnect if the Serial Port is set to the device), and make sure FLASH_DEVICE is set correctly for your board (see the question above ). However, if \"make flash\" just doesn't work for your board, then you will need to manually flash. See if there is a config file in the config directory with specific instructions for flashing the device. Also, check the board manufacturer's documentation to see if it describes how to flash the device. Finally, it may be possible to manually flash the device using tools such as \"avrdude\" or \"bossac\" - see the bootloader document for additional information.","title":"The \"make flash\" command doesn't work"},{"location":"FAQ.html#how-do-i-change-the-serial-baud-rate","text":"The recommended baud rate for Klipper is 250000. This baud rate works well on all micro-controller boards that Klipper supports. If you've found an online guide recommending a different baud rate, then ignore that part of the guide and continue with the default value of 250000. If you want to change the baud rate anyway, then the new rate will need to be configured in the micro-controller (during make menuconfig ) and that updated code will need to be compiled and flashed to the micro-controller. The Klipper printer.cfg file will also need to be updated to match that baud rate (see the config reference for details). For example: [mcu] baud: 250000 The baud rate shown on the OctoPrint web page has no impact on the internal Klipper micro-controller baud rate. Always set the OctoPrint baud rate to 250000 when using Klipper. The Klipper micro-controller baud rate is not related to the baud rate of the micro-controller's bootloader. See the bootloader document for additional information on bootloaders.","title":"How do I change the serial baud rate?"},{"location":"FAQ.html#can-i-run-klipper-on-something-other-than-a-raspberry-pi-3","text":"The recommended hardware is a Raspberry Pi Zero2w, Raspberry Pi 3, Raspberry Pi 4 or Raspberry Pi 5. Klipper will also run on other SBC devices as well as x86 hardware, as described below. Klipper will run on a Raspberry Pi 1, 2 and on the Raspberry Pi Zero1, but these boards don't have enough processing power to run Klipper well. It is common for print stalls to occur on these slower machines when printing (The printer may move faster than Klipper can send movement commands.) It is not reccomended to run Kliper on these older machines. For running on the Beaglebone, see the Beaglebone specific installation instructions . Klipper has been run on other machines. The Klipper host software only requires Python running on a Linux (or similar) computer. However, if you wish to run it on a different machine you will need Linux admin knowledge to install the system prerequisites for that particular machine. See the install-octopi.sh script for further information on the necessary Linux admin steps. If you are looking to run the Klipper host software on a low-end chip, then be aware that, at a minimum, a machine with \"double precision floating point\" hardware is required. If you are looking to run the Klipper host software on a shared general-purpose desktop or server class machine, then note that Klipper has some real-time scheduling requirements. If, during a print, the host computer also performs an intensive general-purpose computing task (such as defragmenting a hard drive, 3d rendering, heavy swapping, etc.), then it may cause Klipper to report print errors. Note: If you are not using an OctoPi image, be aware that several Linux distributions enable a \"ModemManager\" (or similar) package that can disrupt serial communication. (Which can cause Klipper to report seemingly random \"Lost communication with MCU\" errors.) If you install Klipper on one of these distributions you may need to disable that package.","title":"Can I run Klipper on something other than a Raspberry Pi 3?"},{"location":"FAQ.html#can-i-run-multiple-instances-of-klipper-on-the-same-host-machine","text":"It is possible to run multiple instances of the Klipper host software, but doing so requires Linux admin knowledge. The Klipper installation scripts ultimately cause the following Unix command to be run: ~/klippy-env/bin/python ~/klipper/klippy/klippy.py ~/printer.cfg -l /tmp/klippy.log One can run multiple instances of the above command as long as each instance has its own printer config file, its own log file, and its own pseudo-tty. For example: ~/klippy-env/bin/python ~/klipper/klippy/klippy.py ~/printer2.cfg -l /tmp/klippy2.log -I /tmp/printer2 If you choose to do this, you will need to implement the necessary start, stop, and installation scripts (if any). The install-octopi.sh script and the klipper-start.sh script may be useful as examples.","title":"Can I run multiple instances of Klipper on the same host machine?"},{"location":"FAQ.html#do-i-have-to-use-octoprint","text":"The Klipper software is not dependent on OctoPrint. It is possible to use alternative software to send commands to Klipper, but doing so requires Linux admin knowledge. Klipper creates a \"virtual serial port\" via the \"/tmp/printer\" file, and it emulates a classic 3d-printer serial interface via that file. In general, alternative software may work with Klipper as long as it can be configured to use \"/tmp/printer\" for the printer serial port.","title":"Do I have to use OctoPrint?"},{"location":"FAQ.html#why-cant-i-move-the-stepper-before-homing-the-printer","text":"The code does this to reduce the chance of accidentally commanding the head into the bed or a wall. Once the printer is homed the software attempts to verify each move is within the position_min/max defined in the config file. If the motors are disabled (via an M84 or M18 command) then the motors will need to be homed again prior to movement. If you want to move the head after canceling a print via OctoPrint, consider changing the OctoPrint cancel sequence to do that for you. It's configured in OctoPrint via a web browser under: Settings->GCODE Scripts If you want to move the head after a print finishes, consider adding the desired movement to the \"custom g-code\" section of your slicer. If the printer requires some additional movement as part of the homing process itself (or fundamentally does not have a homing process) then consider using a safe_z_home or homing_override section in the config file. If you need to move a stepper for diagnostic or debugging purposes then consider adding a force_move section to the config file. See config reference for further details on these options.","title":"Why can't I move the stepper before homing the printer?"},{"location":"FAQ.html#why-is-the-z-position_endstop-set-to-05-in-the-default-configs","text":"For cartesian style printers the Z position_endstop specifies how far the nozzle is from the bed when the endstop triggers. If possible, it is recommended to use a Z-max endstop and home away from the bed (as this reduces the potential for bed collisions). However, if one must home towards the bed then it is recommended to position the endstop so it triggers when the nozzle is still a small distance away from the bed. This way, when homing the axis, it will stop before the nozzle touches the bed. See the bed level document for more information.","title":"Why is the Z position_endstop set to 0.5 in the default configs?"},{"location":"FAQ.html#i-converted-my-config-from-marlin-and-the-xy-axes-work-fine-but-i-just-get-a-screeching-noise-when-homing-the-z-axis","text":"Short answer: First, make sure you have verified the stepper configuration as described in the config check document . If the problem persists, try reducing the max_z_velocity setting in the printer config. Long answer: In practice Marlin can typically only step at a rate of around 10000 steps per second. If it is requested to move at a speed that would require a higher step rate then Marlin will generally just step as fast as it can. Klipper is able to achieve much higher step rates, but the stepper motor may not have sufficient torque to move at a higher speed. So, for a Z axis with a high gearing ratio or high microsteps setting the actual obtainable max_z_velocity may be smaller than what is configured in Marlin.","title":"I converted my config from Marlin and the X/Y axes work fine, but I just get a screeching noise when homing the Z axis"},{"location":"FAQ.html#my-tmc-motor-driver-turns-off-in-the-middle-of-a-print","text":"If using the TMC2208 (or TMC2224) driver in \"standalone mode\" then make sure to use the latest version of Klipper . A workaround for a TMC2208 \"stealthchop\" driver problem was added to Klipper in mid-March of 2020.","title":"My TMC motor driver turns off in the middle of a print"},{"location":"FAQ.html#i-keep-getting-random-lost-communication-with-mcu-errors","text":"This is commonly caused by hardware errors on the USB connection between the host machine and the micro-controller. Things to look for: Use a good quality USB cable between the host machine and micro-controller. Make sure the plugs are secure. If using a Raspberry Pi, use a good quality power supply for the Raspberry Pi and use a good quality USB cable to connect that power supply to the Pi. If you get \"under voltage\" warnings from OctoPrint, this is related to the power supply and it must be fixed. Make sure the printer's power supply is not being overloaded. (Power fluctuations to the micro-controller's USB chip may result in resets of that chip.) Verify stepper, heater, and other printer wires are not crimped or frayed. (Printer movement may place stress on a faulty wire causing it to lose contact, briefly short, or generate excessive noise.) There have been reports of high USB noise when both the printer's power supply and the host's 5V power supply are mixed. (If you find that the micro-controller powers on when either the printer's power supply is on or the USB cable is plugged in, then it indicates the 5V power supplies are being mixed.) It may help to configure the micro-controller to use power from only one source. (Alternatively, if the micro-controller board can not configure its power source, one may modify a USB cable so that it does not carry 5V power between the host and micro-controller.)","title":"I keep getting random \"Lost communication with MCU\" errors"},{"location":"FAQ.html#my-raspberry-pi-keeps-rebooting-during-prints","text":"This is most likely do to voltage fluctuations. Follow the same troubleshooting steps for a \"Lost communication with MCU\" error.","title":"My Raspberry Pi keeps rebooting during prints"},{"location":"FAQ.html#when-i-set-restart_methodcommand-my-avr-device-just-hangs-on-a-restart","text":"Some old versions of the AVR bootloader have a known bug in watchdog event handling. This typically manifests when the printer.cfg file has restart_method set to \"command\". When the bug occurs, the AVR device will be unresponsive until power is removed and reapplied to the device (the power or status LEDs may also blink repeatedly until the power is removed). The workaround is to use a restart_method other than \"command\" or to flash an updated bootloader to the AVR device. Flashing a new bootloader is a one time step that typically requires an external programmer - see Bootloaders for further details.","title":"When I set restart_method=command my AVR device just hangs on a restart"},{"location":"FAQ.html#will-the-heaters-be-left-on-if-the-raspberry-pi-crashes","text":"The software has been designed to prevent that. Once the host enables a heater, the host software needs to confirm that enablement every 5 seconds. If the micro-controller does not receive a confirmation every 5 seconds it goes into a \"shutdown\" state which is designed to turn off all heaters and stepper motors. See the \"config_digital_out\" command in the MCU commands document for further details. In addition, the micro-controller software is configured with a minimum and maximum temperature range for each heater at startup (see the min_temp and max_temp parameters in the config reference for details). If the micro-controller detects that the temperature is outside of that range then it will also enter a \"shutdown\" state. Separately, the host software also implements code to check that heaters and temperature sensors are functioning correctly. See the config reference for further details.","title":"Will the heaters be left on if the Raspberry Pi crashes?"},{"location":"FAQ.html#how-do-i-convert-a-marlin-pin-number-to-a-klipper-pin-name","text":"Short answer: A mapping is available in the sample-aliases.cfg file. Use that file as a guide to finding the actual micro-controller pin names. (It is also possible to copy the relevant board_pins config section into your config file and use the aliases in your config, but it is preferable to translate and use the actual micro-controller pin names.) Note that the sample-aliases.cfg file uses pin names that start with the prefix \"ar\" instead of \"D\" (eg, Arduino pin D23 is Klipper alias ar23 ) and the prefix \"analog\" instead of \"A\" (eg, Arduino pin A14 is Klipper alias analog14 ). Long answer: Klipper uses the standard pin names defined by the micro-controller. On the Atmega chips these hardware pins have names like PA4 , PC7 , or PD2 . Long ago, the Arduino project decided to avoid using the standard hardware names in favor of their own pin names based on incrementing numbers - these Arduino names generally look like D23 or A14 . This was an unfortunate choice that has lead to a great deal of confusion. In particular the Arduino pin numbers frequently don't translate to the same hardware names. For example, D21 is PD0 on one common Arduino board, but is PC7 on another common Arduino board. To avoid this confusion, the core Klipper code uses the standard pin names defined by the micro-controller.","title":"How do I convert a Marlin pin number to a Klipper pin name?"},{"location":"FAQ.html#do-i-have-to-wire-my-device-to-a-specific-type-of-micro-controller-pin","text":"It depends on the type of device and type of pin: ADC pins (or Analog pins): For thermistors and similar \"analog\" sensors, the device must be wired to an \"analog\" or \"ADC\" capable pin on the micro-controller. If you configure Klipper to use a pin that is not analog capable, Klipper will report a \"Not a valid ADC pin\" error. PWM pins (or Timer pins): Klipper does not use hardware PWM by default for any device. So, in general, one may wire heaters, fans, and similar devices to any general purpose IO pin. However, fans and output_pin devices may be optionally configured to use hardware_pwm: True , in which case the micro-controller must support hardware PWM on the pin (otherwise, Klipper will report a \"Not a valid PWM pin\" error). IRQ pins (or Interrupt pins): Klipper does not use hardware interrupts on IO pins, so it is never necessary to wire a device to one of these micro-controller pins. SPI pins: When using hardware SPI it is necessary to wire the pins to the micro-controller's SPI capable pins. However, most devices can be configured to use \"software SPI\", in which case any general purpose IO pins may be used. I2C pins: When using I2C it is necessary to wire the pins to the micro-controller's I2C capable pins. Other devices may be wired to any general purpose IO pin. For example, steppers, heaters, fans, Z probes, servos, LEDs, common hd44780/st7920 LCD displays, the Trinamic UART control line may be wired to any general purpose IO pin.","title":"Do I have to wire my device to a specific type of micro-controller pin?"},{"location":"FAQ.html#how-do-i-cancel-an-m109m190-wait-for-temperature-request","text":"Navigate to the OctoPrint terminal tab and issue an M112 command in the terminal box. The M112 command will cause Klipper to enter into a \"shutdown\" state, and it will cause OctoPrint to disconnect from Klipper. Navigate to the OctoPrint connection area and click on \"Connect\" to cause OctoPrint to reconnect. Navigate back to the terminal tab and issue a FIRMWARE_RESTART command to clear the Klipper error state. After completing this sequence, the previous heating request will be canceled and a new print may be started.","title":"How do I cancel an M109/M190 \"wait for temperature\" request?"},{"location":"FAQ.html#can-i-find-out-whether-the-printer-has-lost-steps","text":"In a way, yes. Home the printer, issue a GET_POSITION command, run your print, home again and issue another GET_POSITION . Then compare the values in the mcu: line. This might be helpful to tune settings like stepper motor currents, accelerations and speeds without needing to actually print something and waste filament: just run some high-speed moves in between the GET_POSITION commands. Note that endstop switches themselves tend to trigger at slightly different positions, so a difference of a couple of microsteps is likely the result of endstop inaccuracies. A stepper motor itself can only lose steps in increments of 4 full steps. (So, if one is using 16 microsteps, then a lost step on the stepper would result in the \"mcu:\" step counter being off by a multiple of 64 microsteps.)","title":"Can I find out whether the printer has lost steps?"},{"location":"FAQ.html#why-does-klipper-report-errors-i-lost-my-print","text":"Short answer: We want to know if our printers detect a problem so that the underlying issue can be fixed and we can obtain great quality prints. We definitely do not want our printers to silently produce low quality prints. Long answer: Klipper has been engineered to automatically workaround many transient problems. For example, it automatically detects communication errors and will retransmit; it schedules actions in advance and buffers commands at multiple layers to enable precise timing even with intermittent interference. However, should the software detect an error that it can not recover from, if it is commanded to take an invalid action, or if it detects it is hopelessly unable to perform its commanded task, then Klipper will report an error. In these situations there is a high risk of producing a low-quality print (or worse). It is hoped that alerting the user will empower them to fix the underlying issue and improve the overall quality of their prints. There are some related questions: Why doesn't Klipper pause the print instead? Report a warning instead? Check for errors before the print? Ignore errors in user typed commands? etc? Currently Klipper reads commands using the G-Code protocol, and unfortunately the G-Code command protocol is not flexible enough to make these alternatives practical today. There is developer interest in improving the user experience during abnormal events, but it is expected that will require notable infrastructure work (including a shift away from G-Code).","title":"Why does Klipper report errors? I lost my print!"},{"location":"FAQ.html#how-do-i-upgrade-to-the-latest-software","text":"The first step to upgrading the software is to review the latest config changes document. On occasion, changes are made to the software that require users to update their settings as part of a software upgrade. It is a good idea to review this document prior to upgrading. When ready to upgrade, the general method is to ssh into the Raspberry Pi and run: cd ~/klipper git pull ~/klipper/scripts/install-octopi.sh Then one can recompile and flash the micro-controller code. For example: make menuconfig make clean make sudo service klipper stop make flash FLASH_DEVICE=/dev/ttyACM0 sudo service klipper start However, it's often the case that only the host software changes. In this case, one can update and restart just the host software with: cd ~/klipper git pull sudo service klipper restart If after using this shortcut the software warns about needing to reflash the micro-controller or some other unusual error occurs, then follow the full upgrade steps outlined above. If any errors persist then double check the config changes document, as you may need to modify the printer configuration. Note that the RESTART and FIRMWARE_RESTART g-code commands do not load new software - the above \"sudo service klipper restart\" and \"make flash\" commands are needed for a software change to take effect.","title":"How do I upgrade to the latest software?"},{"location":"FAQ.html#how-do-i-uninstall-klipper","text":"On the firmware end, nothing special needs to happen. Just follow the flashing directions for the new firmware. On the raspberry pi end, an uninstall script is available in scripts/klipper-uninstall.sh . For example: sudo ~/klipper/scripts/klipper-uninstall.sh rm -rf ~/klippy-env ~/klipper","title":"How do I uninstall Klipper?"},{"location":"Features.html","text":"Features \u00b6 Klipper has several compelling features: High precision stepper movement. Klipper utilizes an application processor (such as a low-cost Raspberry Pi) when calculating printer movements. The application processor determines when to step each stepper motor, it compresses those events, transmits them to the micro-controller, and then the micro-controller executes each event at the requested time. Each stepper event is scheduled with a precision of 25 micro-seconds or better. The software does not use kinematic estimations (such as the Bresenham algorithm) - instead it calculates precise step times based on the physics of acceleration and the physics of the machine kinematics. More precise stepper movement provides quieter and more stable printer operation. Best in class performance. Klipper is able to achieve high stepping rates on both new and old micro-controllers. Even old 8-bit micro-controllers can obtain rates over 175K steps per second. On more recent micro-controllers, several million steps per second are possible. Higher stepper rates enable higher print velocities. The stepper event timing remains precise even at high speeds which improves overall stability. Klipper supports printers with multiple micro-controllers. For example, one micro-controller could be used to control an extruder, while another controls the printer's heaters, while a third controls the rest of the printer. The Klipper host software implements clock synchronization to account for clock drift between micro-controllers. No special code is needed to enable multiple micro-controllers - it just requires a few extra lines in the config file. Configuration via simple config file. There's no need to reflash the micro-controller to change a setting. All of Klipper's configuration is stored in a standard config file which can be easily edited. This makes it easier to setup and maintain the hardware. Klipper supports \"Smooth Pressure Advance\" - a mechanism to account for the effects of pressure within an extruder. This reduces extruder \"ooze\" and improves the quality of print corners. Klipper's implementation does not introduce instantaneous extruder speed changes, which improves overall stability and robustness. Klipper supports \"Input Shaping\" to reduce the impact of vibrations on print quality. This can reduce or eliminate \"ringing\" (also known as \"ghosting\", \"echoing\", or \"rippling\") in prints. It may also allow one to obtain faster printing speeds while still maintaining high print quality. Klipper uses an \"iterative solver\" to calculate precise step times from simple kinematic equations. This makes porting Klipper to new types of robots easier and it keeps timing precise even with complex kinematics (no \"line segmentation\" is needed). Klipper is hardware agnostic. One should get the same precise timing independent of the low-level electronics hardware. The Klipper micro-controller code is designed to faithfully follow the schedule provided by the Klipper host software (or prominently alert the user if it is unable to). This makes it easier to use available hardware, to upgrade to new hardware, and to have confidence in the hardware. Portable code. Klipper works on ARM, AVR, PRU, and other micro-controllers. Existing \"reprap\" style printers can run Klipper without hardware modification - just add a Raspberry Pi. Klipper's internal code layout makes it easier to support other micro-controller architectures as well. Simpler code. Klipper uses a very high level language (Python) for most code. The kinematics algorithms, the G-code parsing, the heating and thermistor algorithms, etc. are all written in Python. This makes it easier to develop new functionality. Custom programmable macros. New G-Code commands can be defined in the printer config file (no code changes are necessary). Those commands are programmable - allowing them to produce different actions depending on the state of the printer. Builtin API server. In addition to the standard G-Code interface, Klipper supports a rich JSON based application interface. This enables programmers to build external applications with detailed control of the printer. Additional features \u00b6 Klipper supports many standard 3d printer features: Several web interfaces available. Works with Mainsail, Fluidd, OctoPrint and others. This allows the printer to be controlled using a regular web-browser. The same Raspberry Pi that runs Klipper can also run the web interface. Standard G-Code support. Common g-code commands that are produced by typical \"slicers\" (SuperSlicer, Cura, PrusaSlicer, etc.) are supported. Support for multiple extruders. Extruders with shared heaters and extruders on independent carriages (IDEX) are also supported. Support for cartesian, delta, corexy, corexz, hybrid-corexy, hybrid-corexz, deltesian, rotary delta, polar, and cable winch style printers. Automatic bed leveling support. Klipper can be configured for basic bed tilt detection or full mesh bed leveling. The bed mesh can be customized to the print size (adaptive bed mesh). If the bed uses multiple Z steppers then Klipper can also level by independently manipulating the Z steppers. Most Z height probes are supported, including BL-Touch probes and servo activated probes. Probes may be calibrated for axis twist compensation. If using an \"eddy current probe\" then one can utilize fast bed mesh scanning, Automatic delta calibration support. The calibration tool can perform basic height calibration as well as an enhanced X and Y dimension calibration. The calibration can be done with a Z height probe or via manual probing. Run-time \"exclude object\" support. When configured, this module may facilitate canceling of just one object in a multi-part print. Support for common temperature sensors (eg, common thermistors, AD595, AD597, AD849x, PT100, PT1000, MAX6675, MAX31855, MAX31856, MAX31865, BME280, HTU21D, DS18B20, AHT10, SHT3x, and LM75). Custom thermistors and custom analog temperature sensors can also be configured. One can monitor the internal micro-controller temperature sensor and the internal temperature sensor of a Raspberry Pi. Basic thermal heater protection enabled by default. Support for standard fans, nozzle fans, and temperature controlled fans. No need to keep fans running when the printer is idle. Fan speed can be monitored on fans that have a tachometer. One can assign a \"math formula\" to a fan for automatic fan speed updating. Support for run-time configuration of TMC2130, TMC2208/TMC2224, TMC2209, TMC2240, TMC2660, and TMC5160 stepper motor drivers. There is also support for current control of traditional stepper drivers via AD5206, DAC084S085, MCP4451, MCP4728, MCP4018, and PWM pins. Support for common LCD displays attached directly to the printer. A default menu is also available. The contents of the display and menu can be fully customized via the config file. Constant acceleration and \"look-ahead\" support. All printer moves will gradually accelerate from standstill to cruising speed and then decelerate back to a standstill. The incoming stream of G-Code movement commands are queued and analyzed - the acceleration between movements in a similar direction will be optimized to reduce print stalls and improve overall print time. Klipper implements a \"stepper phase endstop\" algorithm that can improve the accuracy of typical endstop switches. When properly tuned it can improve a print's first layer bed adhesion. Support for filament presence sensors, filament motion sensors, and filament width sensors. Support for measuring and recording acceleration using adxl345, mpu9250, mpu6050, lis2dw12, lis3dh, and icm20948 accelerometers. Support for limiting the top speed of short \"zigzag\" moves to reduce printer vibration and noise. See the kinematics document for more information. Sample configuration files are available for many common printers. Check the config directory for a list. To get started with Klipper, read the installation guide. Step Benchmarks \u00b6 Below are the results of stepper performance tests. The numbers shown represent total number of steps per second on the micro-controller. Micro-controller 1 stepper active 3 steppers active 16Mhz AVR 157K 99K 20Mhz AVR 196K 123K SAMD21 686K 471K STM32F042 814K 578K Beaglebone PRU 866K 708K STM32G0B1 1103K 790K STM32F103 1180K 818K SAM3X8E 1273K 981K SAM4S8C 1690K 1385K LPC1768 1923K 1351K LPC1769 2353K 1622K SAM4E8E 2500K 1674K SAMD51 3077K 1885K AR100 3529K 2507K STM32G431 3617K 2452K STM32F407 3652K 2459K STM32F446 3913K 2634K RP2040 4000K 2571K RP2350 4167K 2663K SAME70 6667K 4737K STM32H723 7429K 8619K If unsure of the micro-controller on a particular board, find the appropriate config file , and look for the micro-controller name in the comments at the top of that file. Further details on the benchmarks are available in the Benchmarks document .","title":"Features"},{"location":"Features.html#features","text":"Klipper has several compelling features: High precision stepper movement. Klipper utilizes an application processor (such as a low-cost Raspberry Pi) when calculating printer movements. The application processor determines when to step each stepper motor, it compresses those events, transmits them to the micro-controller, and then the micro-controller executes each event at the requested time. Each stepper event is scheduled with a precision of 25 micro-seconds or better. The software does not use kinematic estimations (such as the Bresenham algorithm) - instead it calculates precise step times based on the physics of acceleration and the physics of the machine kinematics. More precise stepper movement provides quieter and more stable printer operation. Best in class performance. Klipper is able to achieve high stepping rates on both new and old micro-controllers. Even old 8-bit micro-controllers can obtain rates over 175K steps per second. On more recent micro-controllers, several million steps per second are possible. Higher stepper rates enable higher print velocities. The stepper event timing remains precise even at high speeds which improves overall stability. Klipper supports printers with multiple micro-controllers. For example, one micro-controller could be used to control an extruder, while another controls the printer's heaters, while a third controls the rest of the printer. The Klipper host software implements clock synchronization to account for clock drift between micro-controllers. No special code is needed to enable multiple micro-controllers - it just requires a few extra lines in the config file. Configuration via simple config file. There's no need to reflash the micro-controller to change a setting. All of Klipper's configuration is stored in a standard config file which can be easily edited. This makes it easier to setup and maintain the hardware. Klipper supports \"Smooth Pressure Advance\" - a mechanism to account for the effects of pressure within an extruder. This reduces extruder \"ooze\" and improves the quality of print corners. Klipper's implementation does not introduce instantaneous extruder speed changes, which improves overall stability and robustness. Klipper supports \"Input Shaping\" to reduce the impact of vibrations on print quality. This can reduce or eliminate \"ringing\" (also known as \"ghosting\", \"echoing\", or \"rippling\") in prints. It may also allow one to obtain faster printing speeds while still maintaining high print quality. Klipper uses an \"iterative solver\" to calculate precise step times from simple kinematic equations. This makes porting Klipper to new types of robots easier and it keeps timing precise even with complex kinematics (no \"line segmentation\" is needed). Klipper is hardware agnostic. One should get the same precise timing independent of the low-level electronics hardware. The Klipper micro-controller code is designed to faithfully follow the schedule provided by the Klipper host software (or prominently alert the user if it is unable to). This makes it easier to use available hardware, to upgrade to new hardware, and to have confidence in the hardware. Portable code. Klipper works on ARM, AVR, PRU, and other micro-controllers. Existing \"reprap\" style printers can run Klipper without hardware modification - just add a Raspberry Pi. Klipper's internal code layout makes it easier to support other micro-controller architectures as well. Simpler code. Klipper uses a very high level language (Python) for most code. The kinematics algorithms, the G-code parsing, the heating and thermistor algorithms, etc. are all written in Python. This makes it easier to develop new functionality. Custom programmable macros. New G-Code commands can be defined in the printer config file (no code changes are necessary). Those commands are programmable - allowing them to produce different actions depending on the state of the printer. Builtin API server. In addition to the standard G-Code interface, Klipper supports a rich JSON based application interface. This enables programmers to build external applications with detailed control of the printer.","title":"Features"},{"location":"Features.html#additional-features","text":"Klipper supports many standard 3d printer features: Several web interfaces available. Works with Mainsail, Fluidd, OctoPrint and others. This allows the printer to be controlled using a regular web-browser. The same Raspberry Pi that runs Klipper can also run the web interface. Standard G-Code support. Common g-code commands that are produced by typical \"slicers\" (SuperSlicer, Cura, PrusaSlicer, etc.) are supported. Support for multiple extruders. Extruders with shared heaters and extruders on independent carriages (IDEX) are also supported. Support for cartesian, delta, corexy, corexz, hybrid-corexy, hybrid-corexz, deltesian, rotary delta, polar, and cable winch style printers. Automatic bed leveling support. Klipper can be configured for basic bed tilt detection or full mesh bed leveling. The bed mesh can be customized to the print size (adaptive bed mesh). If the bed uses multiple Z steppers then Klipper can also level by independently manipulating the Z steppers. Most Z height probes are supported, including BL-Touch probes and servo activated probes. Probes may be calibrated for axis twist compensation. If using an \"eddy current probe\" then one can utilize fast bed mesh scanning, Automatic delta calibration support. The calibration tool can perform basic height calibration as well as an enhanced X and Y dimension calibration. The calibration can be done with a Z height probe or via manual probing. Run-time \"exclude object\" support. When configured, this module may facilitate canceling of just one object in a multi-part print. Support for common temperature sensors (eg, common thermistors, AD595, AD597, AD849x, PT100, PT1000, MAX6675, MAX31855, MAX31856, MAX31865, BME280, HTU21D, DS18B20, AHT10, SHT3x, and LM75). Custom thermistors and custom analog temperature sensors can also be configured. One can monitor the internal micro-controller temperature sensor and the internal temperature sensor of a Raspberry Pi. Basic thermal heater protection enabled by default. Support for standard fans, nozzle fans, and temperature controlled fans. No need to keep fans running when the printer is idle. Fan speed can be monitored on fans that have a tachometer. One can assign a \"math formula\" to a fan for automatic fan speed updating. Support for run-time configuration of TMC2130, TMC2208/TMC2224, TMC2209, TMC2240, TMC2660, and TMC5160 stepper motor drivers. There is also support for current control of traditional stepper drivers via AD5206, DAC084S085, MCP4451, MCP4728, MCP4018, and PWM pins. Support for common LCD displays attached directly to the printer. A default menu is also available. The contents of the display and menu can be fully customized via the config file. Constant acceleration and \"look-ahead\" support. All printer moves will gradually accelerate from standstill to cruising speed and then decelerate back to a standstill. The incoming stream of G-Code movement commands are queued and analyzed - the acceleration between movements in a similar direction will be optimized to reduce print stalls and improve overall print time. Klipper implements a \"stepper phase endstop\" algorithm that can improve the accuracy of typical endstop switches. When properly tuned it can improve a print's first layer bed adhesion. Support for filament presence sensors, filament motion sensors, and filament width sensors. Support for measuring and recording acceleration using adxl345, mpu9250, mpu6050, lis2dw12, lis3dh, and icm20948 accelerometers. Support for limiting the top speed of short \"zigzag\" moves to reduce printer vibration and noise. See the kinematics document for more information. Sample configuration files are available for many common printers. Check the config directory for a list. To get started with Klipper, read the installation guide.","title":"Additional features"},{"location":"Features.html#step-benchmarks","text":"Below are the results of stepper performance tests. The numbers shown represent total number of steps per second on the micro-controller. Micro-controller 1 stepper active 3 steppers active 16Mhz AVR 157K 99K 20Mhz AVR 196K 123K SAMD21 686K 471K STM32F042 814K 578K Beaglebone PRU 866K 708K STM32G0B1 1103K 790K STM32F103 1180K 818K SAM3X8E 1273K 981K SAM4S8C 1690K 1385K LPC1768 1923K 1351K LPC1769 2353K 1622K SAM4E8E 2500K 1674K SAMD51 3077K 1885K AR100 3529K 2507K STM32G431 3617K 2452K STM32F407 3652K 2459K STM32F446 3913K 2634K RP2040 4000K 2571K RP2350 4167K 2663K SAME70 6667K 4737K STM32H723 7429K 8619K If unsure of the micro-controller on a particular board, find the appropriate config file , and look for the micro-controller name in the comments at the top of that file. Further details on the benchmarks are available in the Benchmarks document .","title":"Step Benchmarks"},{"location":"G-Codes.html","text":"G-Codes \u00b6 This document describes the commands that Klipper supports. These are commands that one may enter into the OctoPrint terminal tab. G-Code commands \u00b6 Klipper supports the following standard G-Code commands: Move (G0 or G1): G1 [X<pos>] [Y<pos>] [Z<pos>] [E<pos>] [F<speed>] Dwell: G4 P<milliseconds> Move to origin: G28 [X] [Y] [Z] Turn off motors: M18 or M84 Wait for current moves to finish: M400 Use absolute/relative distances for extrusion: M82 , M83 Use absolute/relative coordinates: G90 , G91 Set position: G92 [X<pos>] [Y<pos>] [Z<pos>] [E<pos>] Set speed factor override percentage: M220 S<percent> Set extrude factor override percentage: M221 S<percent> Set acceleration: M204 S<value> OR M204 P<value> T<value> Note: If S is not specified and both P and T are specified, then the acceleration is set to the minimum of P and T. If only one of P or T is specified, the command has no effect. Get extruder temperature: M105 Set extruder temperature: M104 [T<index>] [S<temperature>] Set extruder temperature and wait: M109 [T<index>] S<temperature> Note: M109 always waits for temperature to settle at requested value Set bed temperature: M140 [S<temperature>] Set bed temperature and wait: M190 S<temperature> Note: M190 always waits for temperature to settle at requested value Set fan speed: M106 S<value> Turn fan off: M107 Emergency stop: M112 Get current position: M114 Get firmware version: M115 For further details on the above commands see the RepRap G-Code documentation . Klipper's goal is to support the G-Code commands produced by common 3rd party software (eg, OctoPrint, Printrun, Slic3r, Cura, etc.) in their standard configurations. It is not a goal to support every possible G-Code command. Instead, Klipper prefers human readable \"extended G-Code commands\" . Similarly, the G-Code terminal output is only intended to be human readable - see the API Server document if controlling Klipper from external software. If one requires a less common G-Code command then it may be possible to implement it with a custom gcode_macro config section . For example, one might use this to implement: G12 , G29 , G30 , G31 , M42 , M80 , M81 , T1 , etc. Additional Commands \u00b6 Klipper uses \"extended\" G-Code commands for general configuration and status. These extended commands all follow a similar format - they start with a command name and may be followed by one or more parameters. For example: SET_SERVO SERVO=myservo ANGLE=5.3 . In this document, the commands and parameters are shown in uppercase, however they are not case sensitive. (So, \"SET_SERVO\" and \"set_servo\" both run the same command.) This section is organized by Klipper module name, which generally follows the section names specified in the printer configuration file . Note that some modules are automatically loaded. [adxl345] \u00b6 The following commands are available when an adxl345 config section is enabled. ACCELEROMETER_MEASURE \u00b6 ACCELEROMETER_MEASURE [CHIP=<config_name>] [NAME=<value>] : Starts accelerometer measurements at the requested number of samples per second. If CHIP is not specified it defaults to \"adxl345\". The command works in a start-stop mode: when executed for the first time, it starts the measurements, next execution stops them. The results of measurements are written to a file named /tmp/adxl345-<chip>-<name>.csv where <chip> is the name of the accelerometer chip ( my_chip_name from [adxl345 my_chip_name] ) and <name> is the optional NAME parameter. If NAME is not specified it defaults to the current time in \"YYYYMMDD_HHMMSS\" format. If the accelerometer does not have a name in its config section (simply [adxl345] ) then <chip> part of the name is not generated. ACCELEROMETER_QUERY \u00b6 ACCELEROMETER_QUERY [CHIP=<config_name>] [RATE=<value>] : queries accelerometer for the current value. If CHIP is not specified it defaults to \"adxl345\". If RATE is not specified, the default value is used. This command is useful to test the connection to the ADXL345 accelerometer: one of the returned values should be a free-fall acceleration (+/- some noise of the chip). ACCELEROMETER_DEBUG_READ \u00b6 ACCELEROMETER_DEBUG_READ [CHIP=<config_name>] REG=<register> : queries ADXL345 register \"register\" (e.g. 44 or 0x2C). Can be useful for debugging purposes. ACCELEROMETER_DEBUG_WRITE \u00b6 ACCELEROMETER_DEBUG_WRITE [CHIP=<config_name>] REG=<register> VAL=<value> : Writes raw \"value\" into a register \"register\". Both \"value\" and \"register\" can be a decimal or a hexadecimal integer. Use with care, and refer to ADXL345 data sheet for the reference. [angle] \u00b6 The following commands are available when an angle config section is enabled. ANGLE_CALIBRATE \u00b6 ANGLE_CALIBRATE CHIP=<chip_name> : Perform angle calibration on the given sensor (there must be an [angle chip_name] config section that has specified a stepper parameter). IMPORTANT - this tool will command the stepper motor to move without checking the normal kinematic boundary limits. Ideally the motor should be disconnected from any printer carriage before performing calibration. If the stepper can not be disconnected from the printer, make sure the carriage is near the center of its rail before starting calibration. (The stepper motor may move forwards or backwards two full rotations during this test.) After completing this test use the SAVE_CONFIG command to save the calibration data to the config file. In order to use this tool the Python \"numpy\" package must be installed (see the measuring resonance document for more information). ANGLE_CHIP_CALIBRATE \u00b6 ANGLE_CHIP_CALIBRATE CHIP=<chip_name> : Perform internal sensor calibration, if implemented (MT6826S/MT6835). MT68XX : The motor should be disconnected from any printer carriage before performing calibration. After calibration, the sensor should be reset by disconnecting the power. ANGLE_DEBUG_READ \u00b6 ANGLE_DEBUG_READ CHIP=<config_name> REG=<register> : Queries sensor register \"register\" (e.g. 44 or 0x2C). Can be useful for debugging purposes. This is only available for tle5012b chips. ANGLE_DEBUG_WRITE \u00b6 ANGLE_DEBUG_WRITE CHIP=<config_name> REG=<register> VAL=<value> : Writes raw \"value\" into register \"register\". Both \"value\" and \"register\" can be a decimal or a hexadecimal integer. Use with care, and refer to sensor data sheet for the reference. This is only available for tle5012b chips. [axis_twist_compensation] \u00b6 The following commands are available when the axis_twist_compensation config section is enabled. AXIS_TWIST_COMPENSATION_CALIBRATE \u00b6 AXIS_TWIST_COMPENSATION_CALIBRATE [AXIS=<X|Y>] [SAMPLE_COUNT=<value>] Calibrates axis twist compensation by specifying the target axis or enabling automatic calibration. AXIS: Define the axis ( X or Y ) for which the twist compensation will be calibrated. If not specified, the axis defaults to 'X' . [bed_mesh] \u00b6 The following commands are available when the bed_mesh config section is enabled (also see the bed mesh guide ). BED_MESH_CALIBRATE \u00b6 BED_MESH_CALIBRATE [PROFILE=<name>] [METHOD=manual] [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>] [<mesh_parameter>=<value>] [ADAPTIVE=1] [ADAPTIVE_MARGIN=<value>] : This command probes the bed using generated points specified by the parameters in the config. After probing, a mesh is generated and z-movement is adjusted according to the mesh. The mesh is immediately active after successful completion of BED_MESH_CALIBRATE . The mesh will be saved into a profile specified by the PROFILE parameter, or default if unspecified. If ADAPTIVE=1 is specified then the profile name will begin with adaptive- and should not be saved for reuse. See the PROBE command for details on the optional probe parameters. If METHOD=manual is specified then the manual probing tool is activated - see the MANUAL_PROBE command above for details on the additional commands available while this tool is active. The optional HORIZONTAL_MOVE_Z value overrides the horizontal_move_z option specified in the config file. If ADAPTIVE=1 is specified then the objects defined by the Gcode file being printed will be used to define the probed area. The optional ADAPTIVE_MARGIN value overrides the adaptive_margin option specified in the config file. BED_MESH_OUTPUT \u00b6 BED_MESH_OUTPUT PGP=[<0:1>] : This command outputs the current probed z values and current mesh values to the terminal. If PGP=1 is specified the X, Y coordinates generated by bed_mesh, along with their associated indices, will be output to the terminal. BED_MESH_MAP \u00b6 BED_MESH_MAP : Like to BED_MESH_OUTPUT, this command prints the current state of the mesh to the terminal. Instead of printing the values in a human readable format, the state is serialized in json format. This allows octoprint plugins to easily capture the data and generate height maps approximating the bed's surface. BED_MESH_CLEAR \u00b6 BED_MESH_CLEAR : This command clears the mesh and removes all z adjustment. It is recommended to put this in your end-gcode. BED_MESH_PROFILE \u00b6 BED_MESH_PROFILE LOAD=<name> SAVE=<name> REMOVE=<name> : This command provides profile management for mesh state. LOAD will restore the mesh state from the profile matching the supplied name. SAVE will save the current mesh state to a profile matching the supplied name. Remove will delete the profile matching the supplied name from persistent memory. Note that after SAVE or REMOVE operations have been run the SAVE_CONFIG gcode must be run to make the changes to persistent memory permanent. BED_MESH_OFFSET \u00b6 BED_MESH_OFFSET [X=<value>] [Y=<value>] [ZFADE=<value] : Applies X, Y, and/or ZFADE offsets to the mesh lookup. This is useful for printers with independent extruders, as an offset is necessary to produce correct Z adjustment after a tool change. Note that a ZFADE offset does not apply additional z-adjustment directly, it is used to correct the fade calculation when a gcode offset has been applied to the Z axis. [bed_screws] \u00b6 The following commands are available when the bed_screws config section is enabled (also see the manual level guide ). BED_SCREWS_ADJUST \u00b6 BED_SCREWS_ADJUST : This command will invoke the bed screws adjustment tool. It will command the nozzle to different locations (as defined in the config file) and allow one to make adjustments to the bed screws so that the bed is a constant distance from the nozzle. [bed_tilt] \u00b6 The following commands are available when the bed_tilt config section is enabled. BED_TILT_CALIBRATE \u00b6 BED_TILT_CALIBRATE [METHOD=manual] [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>] : This command will probe the points specified in the config and then recommend updated x and y tilt adjustments. See the PROBE command for details on the optional probe parameters. If METHOD=manual is specified then the manual probing tool is activated - see the MANUAL_PROBE command above for details on the additional commands available while this tool is active. The optional HORIZONTAL_MOVE_Z value overrides the horizontal_move_z option specified in the config file. [bltouch] \u00b6 The following command is available when a bltouch config section is enabled (also see the BL-Touch guide ). BLTOUCH_DEBUG \u00b6 BLTOUCH_DEBUG COMMAND=<command> : This sends a command to the BLTouch. It may be useful for debugging. Available commands are: pin_down , touch_mode , pin_up , self_test , reset . A BL-Touch V3.0 or V3.1 may also support set_5V_output_mode , set_OD_output_mode , output_mode_store commands. BLTOUCH_STORE \u00b6 BLTOUCH_STORE MODE=<output_mode> : This stores an output mode in the EEPROM of a BLTouch V3.1 Available output_modes are: 5V , OD [configfile] \u00b6 The configfile module is automatically loaded. SAVE_CONFIG \u00b6 SAVE_CONFIG : This command will overwrite the main printer config file and restart the host software. This command is used in conjunction with other calibration commands to store the results of calibration tests. [delayed_gcode] \u00b6 The following command is enabled if a delayed_gcode config section has been enabled (also see the template guide ). UPDATE_DELAYED_GCODE \u00b6 UPDATE_DELAYED_GCODE [ID=<name>] [DURATION=<seconds>] : Updates the delay duration for the identified [delayed_gcode] and starts the timer for gcode execution. A value of 0 will cancel a pending delayed gcode from executing. [delta_calibrate] \u00b6 The following commands are available when the delta_calibrate config section is enabled (also see the delta calibrate guide ). DELTA_CALIBRATE \u00b6 DELTA_CALIBRATE [METHOD=manual] [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>] : This command will probe seven points on the bed and recommend updated endstop positions, tower angles, and radius. See the PROBE command for details on the optional probe parameters. If METHOD=manual is specified then the manual probing tool is activated - see the MANUAL_PROBE command above for details on the additional commands available while this tool is active. The optional HORIZONTAL_MOVE_Z value overrides the horizontal_move_z option specified in the config file. DELTA_ANALYZE \u00b6 DELTA_ANALYZE : This command is used during enhanced delta calibration. See Delta Calibrate for details. [display] \u00b6 The following command is available when a display config section is enabled. SET_DISPLAY_GROUP \u00b6 SET_DISPLAY_GROUP [DISPLAY=<display>] GROUP=<group> : Set the active display group of an lcd display. This allows to define multiple display data groups in the config, e.g. [display_data <group> <elementname>] and switch between them using this extended gcode command. If DISPLAY is not specified it defaults to \"display\" (the primary display). [display_status] \u00b6 The display_status module is automatically loaded if a display config section is enabled. It provides the following standard G-Code commands: Display Message: M117 <message> Set build percentage: M73 P<percent> Also provided is the following extended G-Code command: SET_DISPLAY_TEXT MSG=<message> : Performs the equivalent of M117, setting the supplied MSG as the current display message. If MSG is omitted the display will be cleared. [dual_carriage] \u00b6 The following command is available when the dual_carriage config section is enabled. SET_DUAL_CARRIAGE \u00b6 SET_DUAL_CARRIAGE CARRIAGE=<carriage> [MODE=[PRIMARY|COPY|MIRROR]] : This command will change the mode of the specified carriage. If no MODE is provided it defaults to PRIMARY . <carriage> must reference a defined primary or dual carriage for generic_cartesian kinematics or be 0 (for primary carriage) or 1 (for dual carriage) for all other kinematics supporting IDEX. Setting the mode to PRIMARY deactivates the other carriage and makes the specified carriage execute subsequent G-Code commands as-is. COPY and MIRROR modes are supported only for dual carriages. When set to either of these modes, dual carriage will then track the subsequent moves of its primary carriage and either copy relative movements of it (in COPY mode) or execute them in the opposite (mirror) direction (in MIRROR mode). SAVE_DUAL_CARRIAGE_STATE \u00b6 SAVE_DUAL_CARRIAGE_STATE [NAME=<state_name>] : Save the current positions of the dual carriages and their modes. Saving and restoring DUAL_CARRIAGE state can be useful in scripts and macros, as well as in homing routine overrides. If NAME is provided it allows one to name the saved state to the given string. If NAME is not provided it defaults to \"default\". RESTORE_DUAL_CARRIAGE_STATE \u00b6 RESTORE_DUAL_CARRIAGE_STATE [NAME=<state_name>] [MOVE=[0|1] [MOVE_SPEED=<speed>]] : Restore the previously saved positions of the dual carriages and their modes, unless \"MOVE=0\" is specified, in which case only the saved modes will be restored, but not the positions of the carriages. If positions are being restored and \"MOVE_SPEED\" is specified, then the toolhead moves will be performed with the given speed (in mm/s); otherwise the toolhead move will use the rail homing speed. Note that the carriages restore their positions only over their own axis, which may be necessary to correctly restore COPY and MIRROR mode of the dual carriage. [endstop_phase] \u00b6 The following commands are available when an endstop_phase config section is enabled (also see the endstop phase guide ). ENDSTOP_PHASE_CALIBRATE \u00b6 ENDSTOP_PHASE_CALIBRATE [STEPPER=<config_name>] : If no STEPPER parameter is provided then this command will reports statistics on endstop stepper phases during past homing operations. When a STEPPER parameter is provided it arranges for the given endstop phase setting to be written to the config file (in conjunction with the SAVE_CONFIG command). [exclude_object] \u00b6 The following commands are available when an exclude_object config section is enabled (also see the exclude object guide ): EXCLUDE_OBJECT \u00b6 EXCLUDE_OBJECT [NAME=object_name] [CURRENT=1] [RESET=1] : With no parameters, this will return a list of all currently excluded objects. When the NAME parameter is given, the named object will be excluded from printing. When the CURRENT parameter is given, the current object will be excluded from printing. When the RESET parameter is given, the list of excluded objects will be cleared. Additionally including NAME will only reset the named object. This can cause print failures, if layers were already skipped. EXCLUDE_OBJECT_DEFINE \u00b6 EXCLUDE_OBJECT_DEFINE [NAME=object_name [CENTER=X,Y] [POLYGON=[[x,y],...]] [RESET=1] [JSON=1] : Provides a summary of an object in the file. With no parameters provided, this will list the defined objects known to Klipper. Returns a list of strings, unless the JSON parameter is given, when it will return object details in json format. When the NAME parameter is included, this defines an object to be excluded. NAME : This parameter is required. It is the identifier used by other commands in this module. CENTER : An X,Y coordinate for the object. POLYGON : An array of X,Y coordinates that provide an outline for the object. When the RESET parameter is provided, all defined objects will be cleared, and the [exclude_object] module will be reset. EXCLUDE_OBJECT_START \u00b6 EXCLUDE_OBJECT_START NAME=object_name : This command takes a NAME parameter and denotes the start of the gcode for an object on the current layer. EXCLUDE_OBJECT_END \u00b6 EXCLUDE_OBJECT_END [NAME=object_name] : Denotes the end of the object's gcode for the layer. It is paired with EXCLUDE_OBJECT_START . A NAME parameter is optional, and will only warn when the provided name does not match the current object. [extruder] \u00b6 The following commands are available if an extruder config section is enabled: ACTIVATE_EXTRUDER \u00b6 ACTIVATE_EXTRUDER EXTRUDER=<config_name> : In a printer with multiple extruder config sections, this command changes the active hotend. SET_PRESSURE_ADVANCE \u00b6 SET_PRESSURE_ADVANCE [EXTRUDER=<config_name>] [ADVANCE=<pressure_advance>] [SMOOTH_TIME=<pressure_advance_smooth_time>] : Set pressure advance parameters of an extruder stepper (as defined in an extruder or extruder_stepper config section). If EXTRUDER is not specified, it defaults to the stepper defined in the active hotend. SET_EXTRUDER_ROTATION_DISTANCE \u00b6 SET_EXTRUDER_ROTATION_DISTANCE EXTRUDER=<config_name> [DISTANCE=<distance>] : Set a new value for the provided extruder stepper's \"rotation distance\" (as defined in an extruder or extruder_stepper config section). If the rotation distance is a negative number then the stepper motion will be inverted (relative to the stepper direction specified in the config file). Changed settings are not retained on Klipper reset. Use with caution as small changes can result in excessive pressure between extruder and hotend. Do proper calibration with filament before use. If 'DISTANCE' value is not provided then this command will return the current rotation distance. SYNC_EXTRUDER_MOTION \u00b6 SYNC_EXTRUDER_MOTION EXTRUDER=<name> MOTION_QUEUE=<name> : This command will cause the stepper specified by EXTRUDER (as defined in an extruder or extruder_stepper config section) to become synchronized to the movement of an extruder specified by MOTION_QUEUE (as defined in an extruder config section). If MOTION_QUEUE is an empty string then the stepper will be desynchronized from all extruder movement. [fan_generic] \u00b6 The following command is available when a fan_generic config section is enabled. SET_FAN_SPEED \u00b6 SET_FAN_SPEED FAN=config_name SPEED=<speed> This command sets the speed of a fan. \"speed\" must be between 0.0 and 1.0. SET_FAN_SPEED PIN=config_name TEMPLATE=<template_name> [<param_x>=<literal>] : If TEMPLATE is specified then it assigns a display_template to the given fan. For example, if one defined a [display_template my_fan_template] config section then one could assign TEMPLATE=my_fan_template here. The display_template should produce a string containing a floating point number with the desired value. The template will be continuously evaluated and the fan will be automatically set to the resulting speed. One may set display_template parameters to use during template evaluation (parameters will be parsed as Python literals). If TEMPLATE is an empty string then this command will clear any previous template assigned to the pin (one can then use SET_FAN_SPEED commands to manage the values directly). [filament_switch_sensor] \u00b6 The following command is available when a filament_switch_sensor or filament_motion_sensor config section is enabled. QUERY_FILAMENT_SENSOR \u00b6 QUERY_FILAMENT_SENSOR SENSOR=<sensor_name> : Queries the current status of the filament sensor. The data displayed on the terminal will depend on the sensor type defined in the configuration. SET_FILAMENT_SENSOR \u00b6 SET_FILAMENT_SENSOR SENSOR=<sensor_name> ENABLE=[0|1] : Sets the filament sensor on/off. If ENABLE is set to 0, the filament sensor will be disabled, if set to 1 it is enabled. [firmware_retraction] \u00b6 The following standard G-Code commands are available when the firmware_retraction config section is enabled. These commands allow you to utilize the firmware retraction feature available in many slicers, to reduce stringing during non-extrusion moves from one part of the print to another. Appropriately configuring pressure advance reduces the length of retraction required. G10 : Retracts the extruder using the currently configured parameters. G11 : Unretracts the extruder using the currently configured parameters. The following additional commands are also available. SET_RETRACTION \u00b6 SET_RETRACTION [RETRACT_LENGTH=<mm>] [RETRACT_SPEED=<mm/s>] [UNRETRACT_EXTRA_LENGTH=<mm>] [UNRETRACT_SPEED=<mm/s>] : Adjust the parameters used by firmware retraction. RETRACT_LENGTH determines the length of filament to retract and unretract. The speed of retraction is adjusted via RETRACT_SPEED, and is typically set relatively high. The speed of unretraction is adjusted via UNRETRACT_SPEED, and is not particularly critical, although often lower than RETRACT_SPEED. In some cases it is useful to add a small amount of additional length on unretraction, and this is set via UNRETRACT_EXTRA_LENGTH. SET_RETRACTION is commonly set as part of slicer per-filament configuration, as different filaments require different parameter settings. GET_RETRACTION \u00b6 GET_RETRACTION : Queries the current parameters used by firmware retraction and displays them on the terminal. [force_move] \u00b6 The force_move module is automatically loaded, however some commands require setting enable_force_move in the printer config . STEPPER_BUZZ \u00b6 STEPPER_BUZZ STEPPER=<config_name> : Move the given stepper forward one mm and then backward one mm, repeated 10 times. This is a diagnostic tool to help verify stepper connectivity. FORCE_MOVE \u00b6 FORCE_MOVE STEPPER=<config_name> DISTANCE=<value> VELOCITY=<value> [ACCEL=<value>] : This command will forcibly move the given stepper the given distance (in mm) at the given constant velocity (in mm/s). If ACCEL is specified and is greater than zero, then the given acceleration (in mm/s^2) will be used; otherwise no acceleration is performed. No boundary checks are performed; no kinematic updates are made; other parallel steppers on an axis will not be moved. Use caution as an incorrect command could cause damage! Using this command will almost certainly place the low-level kinematics in an incorrect state; issue a G28 afterwards to reset the kinematics. This command is intended for low-level diagnostics and debugging. SET_KINEMATIC_POSITION \u00b6 SET_KINEMATIC_POSITION [X=<value>] [Y=<value>] [Z=<value>] [SET_HOMED=<[X][Y][Z]>] [CLEAR_HOMED=<[X][Y][Z]>] : Force the low-level kinematic code to believe the toolhead is at the given cartesian position and set/clear homed status. This is a diagnostic and debugging command; use SET_GCODE_OFFSET and/or G92 for regular axis transformations. Setting an incorrect or invalid position may lead to internal software errors. The X , Y , and Z parameters are used to alter the low-level kinematic position tracking. If any of these parameters are not set then the position is not changed - for example SET_KINEMATIC_POSITION Z=10 would set all axes as homed, set the internal Z position to 10, and leave the X and Y positions unchanged. Changing the internal position tracking is not dependent on the internal homing state - one may alter the position for both homed and not homed axes, and similarly one may set or clear the homing state of an axis without altering its internal position. The SET_HOMED parameter defaults to XYZ which instructs the kinematics to consider all axes as homed. A bare SET_KINEMATIC_POSITION command will result in all axes being considered homed (and not change its current position). If it is not desired to change the state of homed axes then assign SET_HOMED to an empty string - for example: SET_KINEMATIC_POSITION SET_HOMED= X=10 . It is also possible to request an individual axis be considered homed (eg, SET_HOMED=X ), but note that non-cartesian style kinematics (such as delta kinematics) may not support setting an individual axis as homed. The CLEAR_HOMED parameter instructs the kinematics to consider the given axes as not homed. For example, CLEAR_HOMED=XYZ would request all axes to be considered not homed (and thus require homing prior to movement on those axes). The default is SET_HOMED=XYZ even if CLEAR_HOMED is present, so the command SET_KINEMATIC_POSITION CLEAR_HOMED=Z will set X and Y as homed and clear the homing state for Z. Use SET_KINEMATIC_POSITION SET_HOMED= CLEAR_HOMED=Z if the goal is to clear only the Z homing state. If an axis is specified in neither SET_HOMED nor CLEAR_HOMED then its homing state is not changed and if it is specified in both then CLEAR_HOMED has precedence. It is possible to request clearing of an individual axis, but on non-cartesian style kinematics (such as delta kinematics) doing so may result in clearing the homing state of additional axes. Note the CLEAR parameter is currently an alias for the CLEAR_HOMED parameter, but this alias will be removed in the future. [gcode] \u00b6 The gcode module is automatically loaded. RESTART \u00b6 RESTART : This will cause the host software to reload its config and perform an internal reset. This command will not clear error state from the micro-controller (see FIRMWARE_RESTART) nor will it load new software (see the FAQ ). FIRMWARE_RESTART \u00b6 FIRMWARE_RESTART : This is similar to a RESTART command, but it also clears any error state from the micro-controller. STATUS \u00b6 STATUS : Report the Klipper host software status. HELP \u00b6 HELP : Report the list of available extended G-Code commands. [gcode_arcs] \u00b6 The following standard G-Code commands are available if a gcode_arcs config section is enabled: Arc Move Clockwise (G2), Arc Move Counter-clockwise (G3): G2|G3 [X<pos>] [Y<pos>] [Z<pos>] [E<pos>] [F<speed>] I<value> J<value>|I<value> K<value>|J<value> K<value> Arc Plane Select: G17 (XY plane), G18 (XZ plane), G19 (YZ plane) [gcode_macro] \u00b6 The following command is available when a gcode_macro config section is enabled (also see the command templates guide ). SET_GCODE_VARIABLE \u00b6 SET_GCODE_VARIABLE MACRO=<macro_name> VARIABLE=<name> VALUE=<value> : This command allows one to change the value of a gcode_macro variable at run-time. The provided VALUE is parsed as a Python literal. [gcode_move] \u00b6 The gcode_move module is automatically loaded. GET_POSITION \u00b6 GET_POSITION : Return information on the current location of the toolhead. See the developer documentation of GET_POSITION output for more information. SET_GCODE_OFFSET \u00b6 SET_GCODE_OFFSET [X=<pos>|X_ADJUST=<adjust>] [Y=<pos>|Y_ADJUST=<adjust>] [Z=<pos>|Z_ADJUST=<adjust>] [MOVE=1 [MOVE_SPEED=<speed>]] : Set a positional offset to apply to future G-Code commands. This is commonly used to virtually change the Z bed offset or to set nozzle XY offsets when switching extruders. For example, if \"SET_GCODE_OFFSET Z=0.2\" is sent, then future G-Code moves will have 0.2mm added to their Z height. If the X_ADJUST style parameters are used, then the adjustment will be added to any existing offset (eg, \"SET_GCODE_OFFSET Z=-0.2\" followed by \"SET_GCODE_OFFSET Z_ADJUST=0.3\" would result in a total Z offset of 0.1). If \"MOVE=1\" is specified then a toolhead move will be issued to apply the given offset (otherwise the offset will take effect on the next absolute G-Code move that specifies the given axis). If \"MOVE_SPEED\" is specified then the toolhead move will be performed with the given speed (in mm/s); otherwise the toolhead move will use the last specified G-Code speed. SAVE_GCODE_STATE \u00b6 SAVE_GCODE_STATE [NAME=<state_name>] : Save the current g-code coordinate parsing state. Saving and restoring the g-code state is useful in scripts and macros. This command saves the current g-code absolute coordinate mode (G90/G91), absolute extrude mode (M82/M83), origin (G92), offset (SET_GCODE_OFFSET), speed override (M220), extruder override (M221), move speed, current XYZ position, and relative extruder \"E\" position. If NAME is provided it allows one to name the saved state to the given string. If NAME is not provided it defaults to \"default\". RESTORE_GCODE_STATE \u00b6 RESTORE_GCODE_STATE [NAME=<state_name>] [MOVE=1 [MOVE_SPEED=<speed>]] : Restore a state previously saved via SAVE_GCODE_STATE. If \"MOVE=1\" is specified then a toolhead move will be issued to move back to the previous XYZ position. If \"MOVE_SPEED\" is specified then the toolhead move will be performed with the given speed (in mm/s); otherwise the toolhead move will use the restored g-code speed. [generic_cartesian] \u00b6 The commands in this section become automatically available when kinematics: generic_cartesian is specified as the printer kinematics. SET_STEPPER_CARRIAGES \u00b6 SET_STEPPER_CARRIAGES STEPPER=<stepper_name> CARRIAGES=<carriages> [DISABLE_CHECKS=[0|1]] : Set or update the stepper carriages. <stepper_name> must reference an existing stepper defined in printer.cfg , and <carriages> describes the carriages the stepper moves. See Generic Cartesian Kinematics for a more detailed overview of the carriages parameter in the stepper configuration section. Note that it is only possible to change the coefficients or signs of the carriages with this command, but a user cannot add or remove the carriages that the stepper controls. SET_STEPPER_CARRIAGES is an advanced tool, and the user is advised to exercise an extreme caution using it, since specifying incorrect configuration may physically damage the printer. Note that SET_STEPPER_CARRIAGES performs certain internal validations of the new printer kinematics after the change. Keep in mind that if it detects an issue, it may leave printer kinematics in an invalid state. This means that if SET_STEPPER_CARRIAGES reports an error, it is unsafe to issue other GCode commands, and the user must inspect the error message and either fix the problem, or manually restore the previous stepper(s) configuration. Since SET_STEPPER_CARRIAGES can update a configuration of a single stepper at a time, some sequences of changes can lead to invalid intermediate kinematic configurations, even if the final configuration is valid. In such cases a user can pass DISABLE_CHECKS=1 parameters to all but the last command to disable intermediate checks. For example, if stepper a and stepper b initially have x-y and x+y carriages correspondingly, then the following sequence of commands will let a user effectively swap the carriage controls: SET_STEPPER_CARRIAGES STEPPER=a CARRIAGES=x+y DISABLE_CHECKS=1 and SET_STEPPER_CARRIAGES STEPPER=b CARRIAGES=x-y , while still validating the final kinematics state. [hall_filament_width_sensor] \u00b6 The following commands are available when the tsl1401cl filament width sensor config section or hall filament width sensor config section is enabled (also see TSLl401CL Filament Width Sensor and Hall Filament Width Sensor ): QUERY_FILAMENT_WIDTH \u00b6 QUERY_FILAMENT_WIDTH : Return the current measured filament width. RESET_FILAMENT_WIDTH_SENSOR \u00b6 RESET_FILAMENT_WIDTH_SENSOR : Clear all sensor readings. Helpful after filament change. DISABLE_FILAMENT_WIDTH_SENSOR \u00b6 DISABLE_FILAMENT_WIDTH_SENSOR : Turn off the filament width sensor and stop using it for flow control. ENABLE_FILAMENT_WIDTH_SENSOR \u00b6 ENABLE_FILAMENT_WIDTH_SENSOR : Turn on the filament width sensor and start using it for flow control. QUERY_RAW_FILAMENT_WIDTH \u00b6 QUERY_RAW_FILAMENT_WIDTH : Return the current ADC channel readings and RAW sensor value for calibration points. ENABLE_FILAMENT_WIDTH_LOG \u00b6 ENABLE_FILAMENT_WIDTH_LOG : Turn on diameter logging. DISABLE_FILAMENT_WIDTH_LOG \u00b6 DISABLE_FILAMENT_WIDTH_LOG : Turn off diameter logging. [heaters] \u00b6 The heaters module is automatically loaded if a heater is defined in the config file. TURN_OFF_HEATERS \u00b6 TURN_OFF_HEATERS : Turn off all heaters. TEMPERATURE_WAIT \u00b6 TEMPERATURE_WAIT SENSOR=<config_name> [MINIMUM=<target>] [MAXIMUM=<target>] : Wait until the given temperature sensor is at or above the supplied MINIMUM and/or at or below the supplied MAXIMUM. SET_HEATER_TEMPERATURE \u00b6 SET_HEATER_TEMPERATURE HEATER=<heater_name> [TARGET=<target_temperature>] : Sets the target temperature for a heater. If a target temperature is not supplied, the target is 0. [idle_timeout] \u00b6 The idle_timeout module is automatically loaded. SET_IDLE_TIMEOUT \u00b6 SET_IDLE_TIMEOUT [TIMEOUT=<timeout>] : Allows the user to set the idle timeout (in seconds). [input_shaper] \u00b6 The following command is enabled if an input_shaper config section has been enabled (also see the resonance compensation guide ). SET_INPUT_SHAPER \u00b6 SET_INPUT_SHAPER [SHAPER_FREQ_X=<shaper_freq_x>] [SHAPER_FREQ_Y=<shaper_freq_y>] [DAMPING_RATIO_X=<damping_ratio_x>] [DAMPING_RATIO_Y=<damping_ratio_y>] [SHAPER_TYPE=<shaper>] [SHAPER_TYPE_X=<shaper_type_x>] [SHAPER_TYPE_Y=<shaper_type_y>] : Modify input shaper parameters. Note that SHAPER_TYPE parameter resets input shaper for both X and Y axes even if different shaper types have been configured in [input_shaper] section. SHAPER_TYPE cannot be used together with either of SHAPER_TYPE_X and SHAPER_TYPE_Y parameters. See config reference for more details on each of these parameters. [led] \u00b6 The following command is available when any of the led config sections are enabled. SET_LED \u00b6 SET_LED LED=<config_name> RED=<value> GREEN=<value> BLUE=<value> WHITE=<value> [INDEX=<index>] [TRANSMIT=0] [SYNC=1] : This sets the LED output. Each color <value> must be between 0.0 and 1.0. The WHITE option is only valid on RGBW LEDs. If the LED supports multiple chips in a daisy-chain then one may specify INDEX to alter the color of just the given chip (1 for the first chip, 2 for the second, etc.). If INDEX is not provided then all LEDs in the daisy-chain will be set to the provided color. If TRANSMIT=0 is specified then the color change will only be made on the next SET_LED command that does not specify TRANSMIT=0; this may be useful in combination with the INDEX parameter to batch multiple updates in a daisy-chain. By default, the SET_LED command will sync it's changes with other ongoing gcode commands. This can lead to undesirable behavior if LEDs are being set while the printer is not printing as it will reset the idle timeout. If careful timing is not needed, the optional SYNC=0 parameter can be specified to apply the changes without resetting the idle timeout. SET_LED_TEMPLATE \u00b6 SET_LED_TEMPLATE LED=<led_name> TEMPLATE=<template_name> [<param_x>=<literal>] [INDEX=<index>] : Assign a display_template to a given LED . For example, if one defined a [display_template my_led_template] config section then one could assign TEMPLATE=my_led_template here. The display_template should produce a comma separated string containing four floating point numbers corresponding to red, green, blue, and white color settings. The template will be continuously evaluated and the LED will be automatically set to the resulting colors. One may set display_template parameters to use during template evaluation (parameters will be parsed as Python literals). If INDEX is not specified then all chips in the LED's daisy-chain will be set to the template, otherwise only the chip with the given index will be updated. If TEMPLATE is an empty string then this command will clear any previous template assigned to the LED (one can then use SET_LED commands to manage the LED's color settings). [load_cell] \u00b6 The following commands are enabled if a load_cell config section has been enabled. LOAD_CELL_DIAGNOSTIC \u00b6 LOAD_CELL_DIAGNOSTIC [LOAD_CELL=<config_name>] : This command collects 10 seconds of load cell data and reports statistics that can help you verify proper operation of the load cell. This command can be run on both calibrated and uncalibrated load cells. LOAD_CELL_CALIBRATE \u00b6 LOAD_CELL_CALIBRATE [LOAD_CELL=<config_name>] : Start the guided calibration utility. Calibration is a 3 step process: First you remove all load from the load cell and run the TARE command Next you apply a known load to the load cell and run the CALIBRATE GRAMS=nnn command Finally use the ACCEPT command to save the results You can cancel the calibration process at any time with ABORT . LOAD_CELL_TARE \u00b6 LOAD_CELL_TARE [LOAD_CELL=<config_name>] : This works just like the tare button on digital scale. It sets the current raw reading of the load cell to be the zero point reference value. The response is the percentage of the sensors range that was read and the raw value in counts. If the load cell is calibrated a force in grams is also reported. LOAD_CELL_READ load_cell=\"name\" \u00b6 LOAD_CELL_READ [LOAD_CELL=<config_name>] : This command takes a reading from the load cell. The response is the percentage of the sensors range that was read and the raw value in counts. If the load cell is calibrated a force in grams is also reported. [load_cell_probe] \u00b6 The following commands are enabled if a load_cell config section has been enabled. LOAD_CELL_TEST_TAP \u00b6 LOAD_CELL_TEST_TAP [TAPS=<taps>] [TIMEOUT=<timeout>] : Run a testing routine that reports taps on the load cell. The toolhead will not move but the load cell probe will sense taps just as if it was probing. This can be used as a sanity check to make sure that the probe works. This tool replaces QUERY_ENDSTOPS and QUERY_PROBE for load cell probes. TAPS : the number of taps the tool expects TIMEOOUT : the time, in seconds, that the tool waits for each tab before aborting. Load Cell Command Extensions \u00b6 Commands that perform probes, such as PROBE , PROBE_ACCURACY , BED_MESH_CALIBRATE etc. will accept additional parameters if a [load_cell_probe] is defined. The parameters override the corresponding settings from the [load_cell_probe] configuration: FORCE_SAFETY_LIMIT=<grams> TRIGGER_FORCE=<grams> DRIFT_FILTER_CUTOFF_FREQUENCY=<frequency_hz> DRIFT_FILTER_DELAY=<1|2> BUZZ_FILTER_CUTOFF_FREQUENCY=<frequency_hz> BUZZ_FILTER_DELAY=<1|2> NOTCH_FILTER_FREQUENCIES=<list of frequency_hz> NOTCH_FILTER_QUALITY=<quality> TARE_TIME=<seconds> [manual_probe] \u00b6 The manual_probe module is automatically loaded. MANUAL_PROBE \u00b6 MANUAL_PROBE [SPEED=<speed>] : Run a helper script useful for measuring the height of the nozzle at a given location. If SPEED is specified, it sets the speed of TESTZ commands (the default is 5mm/s). During a manual probe, the following additional commands are available: ACCEPT : This command accepts the current Z position and concludes the manual probing tool. ABORT : This command terminates the manual probing tool. TESTZ Z=<value> : This command moves the nozzle up or down by the amount specified in \"value\". For example, TESTZ Z=-.1 would move the nozzle down .1mm while TESTZ Z=.1 would move the nozzle up .1mm. The value may also be + , - , ++ , or -- to move the nozzle up or down an amount relative to previous attempts. Z_ENDSTOP_CALIBRATE \u00b6 Z_ENDSTOP_CALIBRATE [SPEED=<speed>] : Run a helper script useful for calibrating a Z position_endstop config setting. See the MANUAL_PROBE command for details on the parameters and the additional commands available while the tool is active. Z_OFFSET_APPLY_ENDSTOP \u00b6 Z_OFFSET_APPLY_ENDSTOP : Take the current Z Gcode offset (aka, babystepping), and subtract it from the stepper_z endstop_position. This acts to take a frequently used babystepping value, and \"make it permanent\". Requires a SAVE_CONFIG to take effect. [manual_stepper] \u00b6 The following command is available when a manual_stepper config section is enabled. MANUAL_STEPPER \u00b6 MANUAL_STEPPER STEPPER=config_name [ENABLE=[0|1]] [SET_POSITION=<pos>] [SPEED=<speed>] [ACCEL=<accel>] [MOVE=<pos> [STOP_ON_ENDSTOP=[1|2|-1|-2]] [SYNC=0]] : This command will alter the state of the stepper. Use the ENABLE parameter to enable/disable the stepper. Use the SET_POSITION parameter to force the stepper to think it is at the given position. Use the MOVE parameter to request a movement to the given position. If SPEED and/or ACCEL is specified then the given values will be used instead of the defaults specified in the config file. If an ACCEL of zero is specified then no acceleration will be performed. If STOP_ON_ENDSTOP=1 is specified then the move will end early should the endstop report as triggered (use STOP_ON_ENDSTOP=2 to complete the move without error even if the endstop does not trigger, use -1 or -2 to stop when the endstop reports not triggered). Normally future G-Code commands will be scheduled to run after the stepper move completes, however if a manual stepper move uses SYNC=0 then future G-Code movement commands may run in parallel with the stepper movement. MANUAL_STEPPER STEPPER=config_name GCODE_AXIS=[A-Z] [LIMIT_VELOCITY=<velocity>] [LIMIT_ACCEL=<accel>] [INSTANTANEOUS_CORNER_VELOCITY=<velocity>] : If the GCODE_AXIS parameter is specified then it configures the stepper motor as an extra axis on G1 move commands. For example, if one were to issue a MANUAL_STEPPER ... GCODE_AXIS=R command then one could issue commands like G1 X10 Y20 R30 to move the stepper motor. The resulting moves will occur synchronously with the associated toolhead xyz movements. If the motor is associated with a GCODE_AXIS then one may no longer issue movements using the above MANUAL_STEPPER command - one may unregister the stepper with a MANUAL_STEPPER ... GCODE_AXIS= command to resume manual control of the motor. The LIMIT_VELOCITY and LIMIT_ACCEL parameters allow one to reduce the speed of G1 moves if those moves would result in a velocity or acceleration above the specified limits. The INSTANTANEOUS_CORNER_VELOCITY specifies the maximum instantaneous velocity change (in mm/s) of the motor during the junction of two moves (the default is 1mm/s). [mcp4018] \u00b6 The following command is available when a mcp4018 config section is enabled. SET_DIGIPOT \u00b6 SET_DIGIPOT DIGIPOT=config_name WIPER=<value> : This command will change the current value of the digipot. This value should typically be between 0.0 and 1.0, unless a 'scale' is defined in the config. When 'scale' is defined, then this value should be between 0.0 and 'scale'. [output_pin] \u00b6 The following command is available when an output_pin config section or pwm_tool config section is enabled. SET_PIN \u00b6 SET_PIN PIN=config_name VALUE=<value> : Set the pin to the given output VALUE . VALUE should be 0 or 1 for \"digital\" output pins. For PWM pins, set to a value between 0.0 and 1.0, or between 0.0 and scale if a scale is configured in the output_pin config section. SET_PIN PIN=config_name TEMPLATE=<template_name> [<param_x>=<literal>] : If TEMPLATE is specified then it assigns a display_template to the given pin. For example, if one defined a [display_template my_pin_template] config section then one could assign TEMPLATE=my_pin_template here. The display_template should produce a string containing a floating point number with the desired value. The template will be continuously evaluated and the pin will be automatically set to the resulting value. One may set display_template parameters to use during template evaluation (parameters will be parsed as Python literals). If TEMPLATE is an empty string then this command will clear any previous template assigned to the pin (one can then use SET_PIN commands to manage the values directly). [palette2] \u00b6 The following commands are available when the palette2 config section is enabled. Palette prints work by embedding special OCodes (Omega Codes) in the GCode file: O1 ... O32 : These codes are read from the GCode stream and processed by this module and passed to the Palette 2 device. The following additional commands are also available. PALETTE_CONNECT \u00b6 PALETTE_CONNECT : This command initializes the connection with the Palette 2. PALETTE_DISCONNECT \u00b6 PALETTE_DISCONNECT : This command disconnects from the Palette 2. PALETTE_CLEAR \u00b6 PALETTE_CLEAR : This command instructs the Palette 2 to clear all of the input and output paths of filament. PALETTE_CUT \u00b6 PALETTE_CUT : This command instructs the Palette 2 to cut the filament currently loaded in the splice core. PALETTE_SMART_LOAD \u00b6 PALETTE_SMART_LOAD : This command start the smart load sequence on the Palette 2. Filament is loaded automatically by extruding it the distance calibrated on the device for the printer, and instructs the Palette 2 once the loading has been completed. This command is the same as pressing Smart Load directly on the Palette 2 screen after the filament load is complete. [pause_resume] \u00b6 The following commands are available when the pause_resume config section is enabled: PAUSE \u00b6 PAUSE : Pauses the current print. The current position is captured for restoration upon resume. RESUME \u00b6 RESUME [VELOCITY=<value>] : Resumes the print from a pause, first restoring the previously captured position. The VELOCITY parameter determines the speed at which the tool should return to the original captured position. CLEAR_PAUSE \u00b6 CLEAR_PAUSE : Clears the current paused state without resuming the print. This is useful if one decides to cancel a print after a PAUSE. It is recommended to add this to your start gcode to make sure the paused state is fresh for each print. CANCEL_PRINT \u00b6 CANCEL_PRINT : Cancels the current print. [pid_calibrate] \u00b6 The pid_calibrate module is automatically loaded if a heater is defined in the config file. PID_CALIBRATE \u00b6 PID_CALIBRATE HEATER=<config_name> TARGET=<temperature> [WRITE_FILE=1] : Perform a PID calibration test. The specified heater will be enabled until the specified target temperature is reached, and then the heater will be turned off and on for several cycles. If the WRITE_FILE parameter is enabled, then the file /tmp/heattest.txt will be created with a log of all temperature samples taken during the test. [print_stats] \u00b6 The print_stats module is automatically loaded. SET_PRINT_STATS_INFO \u00b6 SET_PRINT_STATS_INFO [TOTAL_LAYER=<total_layer_count>] [CURRENT_LAYER= <current_layer>] : Pass slicer info like layer act and total to Klipper. Add SET_PRINT_STATS_INFO [TOTAL_LAYER=<total_layer_count>] to your slicer start gcode section and SET_PRINT_STATS_INFO [CURRENT_LAYER= <current_layer>] at the layer change gcode section to pass layer information from your slicer to Klipper. [probe] \u00b6 The following commands are available when a probe config section or bltouch config section is enabled (also see the probe calibrate guide ). PROBE \u00b6 PROBE [PROBE_SPEED=<mm/s>] [LIFT_SPEED=<mm/s>] [SAMPLES=<count>] [SAMPLE_RETRACT_DIST=<mm>] [SAMPLES_TOLERANCE=<mm>] [SAMPLES_TOLERANCE_RETRIES=<count>] [SAMPLES_RESULT=median|average] : Move the nozzle downwards until the probe triggers. If any of the optional parameters are provided they override their equivalent setting in the probe config section . QUERY_PROBE \u00b6 QUERY_PROBE : Report the current status of the probe (\"triggered\" or \"open\"). PROBE_ACCURACY \u00b6 PROBE_ACCURACY [PROBE_SPEED=<mm/s>] [SAMPLES=<count>] [SAMPLE_RETRACT_DIST=<mm>] : Calculate the maximum, minimum, average, median, and standard deviation of multiple probe samples. By default, 10 SAMPLES are taken. Otherwise the optional parameters default to their equivalent setting in the probe config section. PROBE_CALIBRATE \u00b6 PROBE_CALIBRATE [SPEED=<speed>] [<probe_parameter>=<value>] : Run a helper script useful for calibrating the probe's z_offset. See the PROBE command for details on the optional probe parameters. See the MANUAL_PROBE command for details on the SPEED parameter and the additional commands available while the tool is active. Please note, the PROBE_CALIBRATE command uses the speed variable to move in XY direction as well as Z. Z_OFFSET_APPLY_PROBE \u00b6 Z_OFFSET_APPLY_PROBE : Take the current Z Gcode offset (aka, babystepping), and subtract if from the probe's z_offset. This acts to take a frequently used babystepping value, and \"make it permanent\". Requires a SAVE_CONFIG to take effect. [probe_eddy_current] \u00b6 The following commands are available when a probe_eddy_current config section is enabled. PROBE_EDDY_CURRENT_CALIBRATE \u00b6 PROBE_EDDY_CURRENT_CALIBRATE CHIP=<config_name> : This starts a tool that calibrates the sensor resonance frequencies to corresponding Z heights. The tool will take a couple of minutes to complete. After completion, use the SAVE_CONFIG command to store the results in the printer.cfg file. LDC_CALIBRATE_DRIVE_CURRENT \u00b6 LDC_CALIBRATE_DRIVE_CURRENT CHIP=<config_name> This tool will calibrate the ldc1612 DRIVE_CURRENT0 register. Prior to using this tool, move the sensor so that it is near the center of the bed and about 20mm above the bed surface. Run this command to determine an appropriate DRIVE_CURRENT for the sensor. After running this command use the SAVE_CONFIG command to store that new setting in the printer.cfg config file. [pwm_cycle_time] \u00b6 The following command is available when a pwm_cycle_time config section is enabled. SET_PIN \u00b6 SET_PIN PIN=config_name VALUE=<value> [CYCLE_TIME=<cycle_time>] : This command works similarly to output_pin SET_PIN commands. The command here supports setting an explicit cycle time using the CYCLE_TIME parameter (specified in seconds). Note that the CYCLE_TIME parameter is not stored between SET_PIN commands (any SET_PIN command without an explicit CYCLE_TIME parameter will use the cycle_time specified in the pwm_cycle_time config section). [quad_gantry_level] \u00b6 The following commands are available when the quad_gantry_level config section is enabled. QUAD_GANTRY_LEVEL \u00b6 QUAD_GANTRY_LEVEL [RETRIES=<value>] [RETRY_TOLERANCE=<value>] [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>] : This command will probe the points specified in the config and then make independent adjustments to each Z stepper to compensate for tilt. See the PROBE command for details on the optional probe parameters. The optional RETRIES , RETRY_TOLERANCE , and HORIZONTAL_MOVE_Z values override those options specified in the config file. [query_adc] \u00b6 The query_adc module is automatically loaded. QUERY_ADC \u00b6 QUERY_ADC [NAME=<config_name>] [PULLUP=<value>] : Report the last analog value received for a configured analog pin. If NAME is not provided, the list of available adc names are reported. If PULLUP is provided (as a value in Ohms), the raw analog value along with the equivalent resistance given that pullup is reported. [query_endstops] \u00b6 The query_endstops module is automatically loaded. The following standard G-Code commands are currently available, but using them is not recommended: Get Endstop Status: M119 (Use QUERY_ENDSTOPS instead.) QUERY_ENDSTOPS \u00b6 QUERY_ENDSTOPS : Probe the axis endstops and report if they are \"triggered\" or in an \"open\" state. This command is typically used to verify that an endstop is working correctly. [resonance_tester] \u00b6 The following commands are available when a resonance_tester config section is enabled (also see the measuring resonances guide ). MEASURE_AXES_NOISE \u00b6 MEASURE_AXES_NOISE : Measures and outputs the noise for all axes of all enabled accelerometer chips. TEST_RESONANCES \u00b6 TEST_RESONANCES AXIS=<axis> [OUTPUT=<resonances,raw_data>] [NAME=<name>] [FREQ_START=<min_freq>] [FREQ_END=<max_freq>] [ACCEL_PER_HZ=<accel_per_hz>] [HZ_PER_SEC=<hz_per_sec>] [CHIPS=<chip_name>] [POINT=x,y,z] [INPUT_SHAPING=<0:1>] : Runs the resonance test in all configured probe points for the requested \"axis\" and measures the acceleration using the accelerometer chips configured for the respective axis. \"axis\" can either be X or Y, or specify an arbitrary direction as AXIS=dx,dy , where dx and dy are floating point numbers defining a direction vector (e.g. AXIS=X , AXIS=Y , or AXIS=1,-1 to define a diagonal direction). Note that AXIS=dx,dy and AXIS=-dx,-dy is equivalent. chip_name can be one or more configured accel chips, delimited with comma, for example CHIPS=\"adxl345, adxl345 rpi\" . If POINT is specified it will override the point(s) configured in [resonance_tester] . If INPUT_SHAPING=0 or not set(default), disables input shaping for the resonance testing, because it is not valid to run the resonance testing with the input shaper enabled. OUTPUT parameter is a comma-separated list of which outputs will be written. If raw_data is requested, then the raw accelerometer data is written into a file or a series of files /tmp/raw_data_<axis>_[<chip_name>_][<point>_]<name>.csv with ( <point>_ part of the name generated only if more than 1 probe point is configured or POINT is specified). If resonances is specified, the frequency response is calculated (across all probe points) and written into /tmp/resonances_<axis>_<name>.csv file. If unset, OUTPUT defaults to resonances , and NAME defaults to the current time in \"YYYYMMDD_HHMMSS\" format. SHAPER_CALIBRATE \u00b6 SHAPER_CALIBRATE [AXIS=<axis>] [NAME=<name>] [FREQ_START=<min_freq>] [FREQ_END=<max_freq>] [ACCEL_PER_HZ=<accel_per_hz>][HZ_PER_SEC=<hz_per_sec>] [CHIPS=<chip_name>] [MAX_SMOOTHING=<max_smoothing>] [INPUT_SHAPING=<0:1>] : Similarly to TEST_RESONANCES , runs the resonance test as configured, and tries to find the optimal parameters for the input shaper for the requested axis (or both X and Y axes if AXIS parameter is unset). If MAX_SMOOTHING is unset, its value is taken from [resonance_tester] section, with the default being unset. See the Max smoothing of the measuring resonances guide for more information on the use of this feature. The results of the tuning are printed to the console, and the frequency responses and the different input shapers values are written to a CSV file(s) /tmp/calibration_data_<axis>_<name>.csv . Unless specified, NAME defaults to the current time in \"YYYYMMDD_HHMMSS\" format. Note that the suggested input shaper parameters can be persisted in the config by issuing SAVE_CONFIG command, and if [input_shaper] was already enabled previously, these parameters take effect immediately. [respond] \u00b6 The following standard G-Code commands are available when the respond config section is enabled: M118 <message> : echo the message prepended with the configured default prefix (or echo: if no prefix is configured). The following additional commands are also available. RESPOND \u00b6 RESPOND MSG=\"<message>\" : echo the message prepended with the configured default prefix (or echo: if no prefix is configured). RESPOND TYPE=echo MSG=\"<message>\" : echo the message prepended with echo: . RESPOND TYPE=echo_no_space MSG=\"<message>\" : echo the message prepended with echo: without a space between prefix and message, helpful for compatibility with some octoprint plugins that expect very specific formatting. RESPOND TYPE=command MSG=\"<message>\" : echo the message prepended with // . OctoPrint can be configured to respond to these messages (e.g. RESPOND TYPE=command MSG=action:pause ). RESPOND TYPE=error MSG=\"<message>\" : echo the message prepended with !! . RESPOND PREFIX=<prefix> MSG=\"<message>\" : echo the message prepended with <prefix> . (The PREFIX parameter will take priority over the TYPE parameter) [save_variables] \u00b6 The following command is enabled if a save_variables config section has been enabled. SAVE_VARIABLE \u00b6 SAVE_VARIABLE VARIABLE=<name> VALUE=<value> : Saves the variable to disk so that it can be used across restarts. The VARIABLE must be lowercase. All stored variables are loaded into the printer.save_variables.variables dict at startup and can be used in gcode macros. The provided VALUE is parsed as a Python literal. [screws_tilt_adjust] \u00b6 The following commands are available when the screws_tilt_adjust config section is enabled (also see the manual level guide ). SCREWS_TILT_CALCULATE \u00b6 SCREWS_TILT_CALCULATE [DIRECTION=CW|CCW] [MAX_DEVIATION=<value>] [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>] : This command will invoke the bed screws adjustment tool. It will command the nozzle to different locations (as defined in the config file) probing the z height and calculate the number of knob turns to adjust the bed level. If DIRECTION is specified, the knob turns will all be in the same direction, clockwise (CW) or counterclockwise (CCW). See the PROBE command for details on the optional probe parameters. IMPORTANT: You MUST always do a G28 before using this command. If MAX_DEVIATION is specified, the command will raise a gcode error if any difference in the screw height relative to the base screw height is greater than the value provided. The optional HORIZONTAL_MOVE_Z value overrides the horizontal_move_z option specified in the config file. [sdcard_loop] \u00b6 When the sdcard_loop config section is enabled, the following extended commands are available. SDCARD_LOOP_BEGIN \u00b6 SDCARD_LOOP_BEGIN COUNT=<count> : Begin a looped section in the SD print. A count of 0 indicates that the section should be looped indefinitely. SDCARD_LOOP_END \u00b6 SDCARD_LOOP_END : End a looped section in the SD print. SDCARD_LOOP_DESIST \u00b6 SDCARD_LOOP_DESIST : Complete existing loops without further iterations. [servo] \u00b6 The following commands are available when a servo config section is enabled. SET_SERVO \u00b6 SET_SERVO SERVO=config_name [ANGLE=<degrees> | WIDTH=<seconds>] : Set the servo position to the given angle (in degrees) or pulse width (in seconds). Use WIDTH=0 to disable the servo output. [skew_correction] \u00b6 The following commands are available when the skew_correction config section is enabled (also see the Skew Correction guide). SET_SKEW \u00b6 SET_SKEW [XY=<ac_length,bd_length,ad_length>] [XZ=<ac,bd,ad>] [YZ=<ac,bd,ad>] [CLEAR=<0|1>] : Configures the [skew_correction] module with measurements (in mm) taken from a calibration print. One may enter measurements for any combination of planes, planes not entered will retain their current value. If CLEAR=1 is entered then all skew correction will be disabled. GET_CURRENT_SKEW \u00b6 GET_CURRENT_SKEW : Reports the current printer skew for each plane in both radians and degrees. The skew is calculated based on parameters provided via the SET_SKEW gcode. CALC_MEASURED_SKEW \u00b6 CALC_MEASURED_SKEW [AC=<ac_length>] [BD=<bd_length>] [AD=<ad_length>] : Calculates and reports the skew (in radians and degrees) based on a measured print. This can be useful for determining the printer's current skew after correction has been applied. It may also be useful before correction is applied to determine if skew correction is necessary. See Skew Correction for details on skew calibration objects and measurements. SKEW_PROFILE \u00b6 SKEW_PROFILE [LOAD=<name>] [SAVE=<name>] [REMOVE=<name>] : Profile management for skew_correction. LOAD will restore skew state from the profile matching the supplied name. SAVE will save the current skew state to a profile matching the supplied name. Remove will delete the profile matching the supplied name from persistent memory. Note that after SAVE or REMOVE operations have been run the SAVE_CONFIG gcode must be run to make the changes to persistent memory permanent. [smart_effector] \u00b6 Several commands are available when a smart_effector config section is enabled. Be sure to check the official documentation for the Smart Effector on the Duet3D Wiki before changing the Smart Effector parameters. Also check the probe calibration guide . SET_SMART_EFFECTOR \u00b6 SET_SMART_EFFECTOR [SENSITIVITY=<sensitivity>] [ACCEL=<accel>] [RECOVERY_TIME=<time>] : Set the Smart Effector parameters. When SENSITIVITY is specified, the respective value is written to the SmartEffector EEPROM (requires control_pin to be provided). Acceptable <sensitivity> values are 0..255, the default is 50. Lower values require less nozzle contact force to trigger (but there is a higher risk of false triggering due to vibrations during probing), and higher values reduce false triggering (but require larger contact force to trigger). Since the sensitivity is written to EEPROM, it is preserved after the shutdown, and so it does not need to be configured on every printer startup. ACCEL and RECOVERY_TIME allow to override the corresponding parameters at run-time, see the config section of Smart Effector for more info on those parameters. RESET_SMART_EFFECTOR \u00b6 RESET_SMART_EFFECTOR : Resets Smart Effector sensitivity to its factory settings. Requires control_pin to be provided in the config section. [stepper_enable] \u00b6 The stepper_enable module is automatically loaded. SET_STEPPER_ENABLE \u00b6 SET_STEPPER_ENABLE STEPPER=<config_name> ENABLE=[0|1] : Enable or disable only the given stepper. This is a diagnostic and debugging tool and must be used with care. Disabling an axis motor does not reset the homing information. Manually moving a disabled stepper may cause the machine to operate the motor outside of safe limits. This can lead to damage to axis components, hot ends, and print surface. [temperature_fan] \u00b6 The following command is available when a temperature_fan config section is enabled. SET_TEMPERATURE_FAN_TARGET \u00b6 SET_TEMPERATURE_FAN_TARGET temperature_fan=<temperature_fan_name> [target=<target_temperature>] [min_speed=<min_speed>] [max_speed=<max_speed>] : Sets the target temperature for a temperature_fan. If a target is not supplied, it is set to the specified temperature in the config file. If speeds are not supplied, no change is applied. [temperature_probe] \u00b6 The following commands are available when a temperature_probe config section is enabled. TEMPERATURE_PROBE_CALIBRATE \u00b6 TEMPERATURE_PROBE_CALIBRATE [PROBE=<probe name>] [TARGET=<value>] [STEP=<value>] : Initiates probe drift calibration for eddy current based probes. The TARGET is a target temperature for the last sample. When the temperature recorded during a sample exceeds the TARGET calibration will complete. The STEP parameter sets temperature delta (in C) between samples. After a sample has been taken, this delta is used to schedule a call to TEMPERATURE_PROBE_NEXT . The default STEP is 2. TEMPERATURE_PROBE_NEXT \u00b6 TEMPERATURE_PROBE_NEXT : After calibration has started this command is run to take the next sample. It is automatically scheduled to run when the delta specified by STEP has been reached, however its also possible to manually run this command to force a new sample. This command is only available during calibration. TEMPERATURE_PROBE_COMPLETE: \u00b6 TEMPERATURE_PROBE_COMPLETE : Can be used to end calibration and save the current result before the TARGET temperature is reached. This command is only available during calibration. ABORT \u00b6 ABORT : Aborts the calibration process, discarding the current results. This command is only available during drift calibration. TEMPERATURE_PROBE_ENABLE \u00b6 TEMPERATURE_PROBE_ENABLE ENABLE=[0|1] : Sets temperature drift compensation on or off. If ENABLE is set to 0, drift compensation will be disabled, if set to 1 it is enabled. [tmcXXXX] \u00b6 The following commands are available when any of the tmcXXXX config sections are enabled. DUMP_TMC \u00b6 DUMP_TMC STEPPER=<name> [REGISTER=<name>] : This command will read all TMC driver registers and report their values. If a REGISTER is provided, only the specified register will be dumped. INIT_TMC \u00b6 INIT_TMC STEPPER=<name> : This command will initialize the TMC registers. Needed to re-enable the driver if power to the chip is turned off then back on. SET_TMC_CURRENT \u00b6 SET_TMC_CURRENT STEPPER=<name> CURRENT=<amps> HOLDCURRENT=<amps> : This will adjust the run and hold currents of the TMC driver. HOLDCURRENT is not applicable to tmc2660 drivers. When used on a driver which has the globalscaler field (tmc5160 and tmc2240), if StealthChop2 is used, the stepper must be held at standstill for >130ms so that the driver executes the AT#1 calibration. SET_TMC_FIELD \u00b6 SET_TMC_FIELD STEPPER=<name> FIELD=<field> VALUE=<value> VELOCITY=<value> : This will alter the value of the specified register field of the TMC driver. This command is intended for low-level diagnostics and debugging only because changing the fields during run-time can lead to undesired and potentially dangerous behavior of your printer. Permanent changes should be made using the printer configuration file instead. No sanity checks are performed for the given values. A VELOCITY can also be specified instead of a VALUE. This velocity is converted to the 20bit TSTEP based value representation. Only use the VELOCITY argument for fields that represent velocities. [toolhead] \u00b6 The toolhead module is automatically loaded. SET_VELOCITY_LIMIT \u00b6 SET_VELOCITY_LIMIT [VELOCITY=<value>] [ACCEL=<value>] [MINIMUM_CRUISE_RATIO=<value>] [SQUARE_CORNER_VELOCITY=<value>] : This command can alter the velocity limits that were specified in the printer config file. See the printer config section for a description of each parameter. [tuning_tower] \u00b6 The tuning_tower module is automatically loaded. TUNING_TOWER \u00b6 TUNING_TOWER COMMAND=<command> PARAMETER=<name> START=<value> [SKIP=<value>] [FACTOR=<value> [BAND=<value>]] | [STEP_DELTA=<value> STEP_HEIGHT=<value>] : A tool for tuning a parameter on each Z height during a print. The tool will run the given COMMAND with the given PARAMETER assigned to a value that varies with Z according to a formula. Use FACTOR if you will use a ruler or calipers to measure the Z height of the optimum value, or STEP_DELTA and STEP_HEIGHT if the tuning tower model has bands of discrete values as is common with temperature towers. If SKIP=<value> is specified, the tuning process doesn't begin until Z height <value> is reached, and below that the value will be set to START ; in this case, the z_height used in the formulas below is actually max(z - skip, 0) . There are three possible combinations of options: FACTOR : The value changes at a rate of factor per millimeter. The formula used is: value = start + factor * z_height . You can plug the optimum Z height directly into the formula to determine the optimum parameter value. FACTOR and BAND : The value changes at an average rate of factor per millimeter, but in discrete bands where the adjustment will only be made every BAND millimeters of Z height. The formula used is: value = start + factor * ((floor(z_height / band) + .5) * band) . STEP_DELTA and STEP_HEIGHT : The value changes by STEP_DELTA every STEP_HEIGHT millimeters. The formula used is: value = start + step_delta * floor(z_height / step_height) . You can simply count bands or read tuning tower labels to determine the optimum value. [virtual_sdcard] \u00b6 Klipper supports the following standard G-Code commands if the virtual_sdcard config section is enabled: List SD card: M20 Initialize SD card: M21 Select SD file: M23 <filename> Start/resume SD print: M24 Pause SD print: M25 Set SD position: M26 S<offset> Report SD print status: M27 In addition, the following extended commands are available when the \"virtual_sdcard\" config section is enabled. SDCARD_PRINT_FILE \u00b6 SDCARD_PRINT_FILE FILENAME=<filename> : Load a file and start SD print. SDCARD_RESET_FILE \u00b6 SDCARD_RESET_FILE : Unload file and clear SD state. [z_thermal_adjust] \u00b6 The following commands are available when the z_thermal_adjust config section is enabled. SET_Z_THERMAL_ADJUST \u00b6 SET_Z_THERMAL_ADJUST [ENABLE=<0:1>] [TEMP_COEFF=<value>] [REF_TEMP=<value>] : Enable or disable the Z thermal adjustment with ENABLE . Disabling does not remove any adjustment already applied, but will freeze the current adjustment value - this prevents potentially unsafe downward Z movement. Re-enabling can potentially cause upward tool movement as the adjustment is updated and applied. TEMP_COEFF allows run-time tuning of the adjustment temperature coefficient (i.e. the TEMP_COEFF config parameter). TEMP_COEFF values are not saved to the config. REF_TEMP manually overrides the reference temperature typically set during homing (for use in e.g. non-standard homing routines) - will be reset automatically upon homing. [z_tilt] \u00b6 The following commands are available when the z_tilt config section is enabled. Z_TILT_ADJUST \u00b6 Z_TILT_ADJUST [RETRIES=<value>] [RETRY_TOLERANCE=<value>] [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>] : This command will probe the points specified in the config and then make independent adjustments to each Z stepper to compensate for tilt. See the PROBE command for details on the optional probe parameters. The optional RETRIES , RETRY_TOLERANCE , and HORIZONTAL_MOVE_Z values override those options specified in the config file.","title":"G-Codes"},{"location":"G-Codes.html#g-codes","text":"This document describes the commands that Klipper supports. These are commands that one may enter into the OctoPrint terminal tab.","title":"G-Codes"},{"location":"G-Codes.html#g-code-commands","text":"Klipper supports the following standard G-Code commands: Move (G0 or G1): G1 [X<pos>] [Y<pos>] [Z<pos>] [E<pos>] [F<speed>] Dwell: G4 P<milliseconds> Move to origin: G28 [X] [Y] [Z] Turn off motors: M18 or M84 Wait for current moves to finish: M400 Use absolute/relative distances for extrusion: M82 , M83 Use absolute/relative coordinates: G90 , G91 Set position: G92 [X<pos>] [Y<pos>] [Z<pos>] [E<pos>] Set speed factor override percentage: M220 S<percent> Set extrude factor override percentage: M221 S<percent> Set acceleration: M204 S<value> OR M204 P<value> T<value> Note: If S is not specified and both P and T are specified, then the acceleration is set to the minimum of P and T. If only one of P or T is specified, the command has no effect. Get extruder temperature: M105 Set extruder temperature: M104 [T<index>] [S<temperature>] Set extruder temperature and wait: M109 [T<index>] S<temperature> Note: M109 always waits for temperature to settle at requested value Set bed temperature: M140 [S<temperature>] Set bed temperature and wait: M190 S<temperature> Note: M190 always waits for temperature to settle at requested value Set fan speed: M106 S<value> Turn fan off: M107 Emergency stop: M112 Get current position: M114 Get firmware version: M115 For further details on the above commands see the RepRap G-Code documentation . Klipper's goal is to support the G-Code commands produced by common 3rd party software (eg, OctoPrint, Printrun, Slic3r, Cura, etc.) in their standard configurations. It is not a goal to support every possible G-Code command. Instead, Klipper prefers human readable \"extended G-Code commands\" . Similarly, the G-Code terminal output is only intended to be human readable - see the API Server document if controlling Klipper from external software. If one requires a less common G-Code command then it may be possible to implement it with a custom gcode_macro config section . For example, one might use this to implement: G12 , G29 , G30 , G31 , M42 , M80 , M81 , T1 , etc.","title":"G-Code commands"},{"location":"G-Codes.html#additional-commands","text":"Klipper uses \"extended\" G-Code commands for general configuration and status. These extended commands all follow a similar format - they start with a command name and may be followed by one or more parameters. For example: SET_SERVO SERVO=myservo ANGLE=5.3 . In this document, the commands and parameters are shown in uppercase, however they are not case sensitive. (So, \"SET_SERVO\" and \"set_servo\" both run the same command.) This section is organized by Klipper module name, which generally follows the section names specified in the printer configuration file . Note that some modules are automatically loaded.","title":"Additional Commands"},{"location":"G-Codes.html#adxl345","text":"The following commands are available when an adxl345 config section is enabled.","title":"[adxl345]"},{"location":"G-Codes.html#accelerometer_measure","text":"ACCELEROMETER_MEASURE [CHIP=<config_name>] [NAME=<value>] : Starts accelerometer measurements at the requested number of samples per second. If CHIP is not specified it defaults to \"adxl345\". The command works in a start-stop mode: when executed for the first time, it starts the measurements, next execution stops them. The results of measurements are written to a file named /tmp/adxl345-<chip>-<name>.csv where <chip> is the name of the accelerometer chip ( my_chip_name from [adxl345 my_chip_name] ) and <name> is the optional NAME parameter. If NAME is not specified it defaults to the current time in \"YYYYMMDD_HHMMSS\" format. If the accelerometer does not have a name in its config section (simply [adxl345] ) then <chip> part of the name is not generated.","title":"ACCELEROMETER_MEASURE"},{"location":"G-Codes.html#accelerometer_query","text":"ACCELEROMETER_QUERY [CHIP=<config_name>] [RATE=<value>] : queries accelerometer for the current value. If CHIP is not specified it defaults to \"adxl345\". If RATE is not specified, the default value is used. This command is useful to test the connection to the ADXL345 accelerometer: one of the returned values should be a free-fall acceleration (+/- some noise of the chip).","title":"ACCELEROMETER_QUERY"},{"location":"G-Codes.html#accelerometer_debug_read","text":"ACCELEROMETER_DEBUG_READ [CHIP=<config_name>] REG=<register> : queries ADXL345 register \"register\" (e.g. 44 or 0x2C). Can be useful for debugging purposes.","title":"ACCELEROMETER_DEBUG_READ"},{"location":"G-Codes.html#accelerometer_debug_write","text":"ACCELEROMETER_DEBUG_WRITE [CHIP=<config_name>] REG=<register> VAL=<value> : Writes raw \"value\" into a register \"register\". Both \"value\" and \"register\" can be a decimal or a hexadecimal integer. Use with care, and refer to ADXL345 data sheet for the reference.","title":"ACCELEROMETER_DEBUG_WRITE"},{"location":"G-Codes.html#angle","text":"The following commands are available when an angle config section is enabled.","title":"[angle]"},{"location":"G-Codes.html#angle_calibrate","text":"ANGLE_CALIBRATE CHIP=<chip_name> : Perform angle calibration on the given sensor (there must be an [angle chip_name] config section that has specified a stepper parameter). IMPORTANT - this tool will command the stepper motor to move without checking the normal kinematic boundary limits. Ideally the motor should be disconnected from any printer carriage before performing calibration. If the stepper can not be disconnected from the printer, make sure the carriage is near the center of its rail before starting calibration. (The stepper motor may move forwards or backwards two full rotations during this test.) After completing this test use the SAVE_CONFIG command to save the calibration data to the config file. In order to use this tool the Python \"numpy\" package must be installed (see the measuring resonance document for more information).","title":"ANGLE_CALIBRATE"},{"location":"G-Codes.html#angle_chip_calibrate","text":"ANGLE_CHIP_CALIBRATE CHIP=<chip_name> : Perform internal sensor calibration, if implemented (MT6826S/MT6835). MT68XX : The motor should be disconnected from any printer carriage before performing calibration. After calibration, the sensor should be reset by disconnecting the power.","title":"ANGLE_CHIP_CALIBRATE"},{"location":"G-Codes.html#angle_debug_read","text":"ANGLE_DEBUG_READ CHIP=<config_name> REG=<register> : Queries sensor register \"register\" (e.g. 44 or 0x2C). Can be useful for debugging purposes. This is only available for tle5012b chips.","title":"ANGLE_DEBUG_READ"},{"location":"G-Codes.html#angle_debug_write","text":"ANGLE_DEBUG_WRITE CHIP=<config_name> REG=<register> VAL=<value> : Writes raw \"value\" into register \"register\". Both \"value\" and \"register\" can be a decimal or a hexadecimal integer. Use with care, and refer to sensor data sheet for the reference. This is only available for tle5012b chips.","title":"ANGLE_DEBUG_WRITE"},{"location":"G-Codes.html#axis_twist_compensation","text":"The following commands are available when the axis_twist_compensation config section is enabled.","title":"[axis_twist_compensation]"},{"location":"G-Codes.html#axis_twist_compensation_calibrate","text":"AXIS_TWIST_COMPENSATION_CALIBRATE [AXIS=<X|Y>] [SAMPLE_COUNT=<value>] Calibrates axis twist compensation by specifying the target axis or enabling automatic calibration. AXIS: Define the axis ( X or Y ) for which the twist compensation will be calibrated. If not specified, the axis defaults to 'X' .","title":"AXIS_TWIST_COMPENSATION_CALIBRATE"},{"location":"G-Codes.html#bed_mesh","text":"The following commands are available when the bed_mesh config section is enabled (also see the bed mesh guide ).","title":"[bed_mesh]"},{"location":"G-Codes.html#bed_mesh_calibrate","text":"BED_MESH_CALIBRATE [PROFILE=<name>] [METHOD=manual] [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>] [<mesh_parameter>=<value>] [ADAPTIVE=1] [ADAPTIVE_MARGIN=<value>] : This command probes the bed using generated points specified by the parameters in the config. After probing, a mesh is generated and z-movement is adjusted according to the mesh. The mesh is immediately active after successful completion of BED_MESH_CALIBRATE . The mesh will be saved into a profile specified by the PROFILE parameter, or default if unspecified. If ADAPTIVE=1 is specified then the profile name will begin with adaptive- and should not be saved for reuse. See the PROBE command for details on the optional probe parameters. If METHOD=manual is specified then the manual probing tool is activated - see the MANUAL_PROBE command above for details on the additional commands available while this tool is active. The optional HORIZONTAL_MOVE_Z value overrides the horizontal_move_z option specified in the config file. If ADAPTIVE=1 is specified then the objects defined by the Gcode file being printed will be used to define the probed area. The optional ADAPTIVE_MARGIN value overrides the adaptive_margin option specified in the config file.","title":"BED_MESH_CALIBRATE"},{"location":"G-Codes.html#bed_mesh_output","text":"BED_MESH_OUTPUT PGP=[<0:1>] : This command outputs the current probed z values and current mesh values to the terminal. If PGP=1 is specified the X, Y coordinates generated by bed_mesh, along with their associated indices, will be output to the terminal.","title":"BED_MESH_OUTPUT"},{"location":"G-Codes.html#bed_mesh_map","text":"BED_MESH_MAP : Like to BED_MESH_OUTPUT, this command prints the current state of the mesh to the terminal. Instead of printing the values in a human readable format, the state is serialized in json format. This allows octoprint plugins to easily capture the data and generate height maps approximating the bed's surface.","title":"BED_MESH_MAP"},{"location":"G-Codes.html#bed_mesh_clear","text":"BED_MESH_CLEAR : This command clears the mesh and removes all z adjustment. It is recommended to put this in your end-gcode.","title":"BED_MESH_CLEAR"},{"location":"G-Codes.html#bed_mesh_profile","text":"BED_MESH_PROFILE LOAD=<name> SAVE=<name> REMOVE=<name> : This command provides profile management for mesh state. LOAD will restore the mesh state from the profile matching the supplied name. SAVE will save the current mesh state to a profile matching the supplied name. Remove will delete the profile matching the supplied name from persistent memory. Note that after SAVE or REMOVE operations have been run the SAVE_CONFIG gcode must be run to make the changes to persistent memory permanent.","title":"BED_MESH_PROFILE"},{"location":"G-Codes.html#bed_mesh_offset","text":"BED_MESH_OFFSET [X=<value>] [Y=<value>] [ZFADE=<value] : Applies X, Y, and/or ZFADE offsets to the mesh lookup. This is useful for printers with independent extruders, as an offset is necessary to produce correct Z adjustment after a tool change. Note that a ZFADE offset does not apply additional z-adjustment directly, it is used to correct the fade calculation when a gcode offset has been applied to the Z axis.","title":"BED_MESH_OFFSET"},{"location":"G-Codes.html#bed_screws","text":"The following commands are available when the bed_screws config section is enabled (also see the manual level guide ).","title":"[bed_screws]"},{"location":"G-Codes.html#bed_screws_adjust","text":"BED_SCREWS_ADJUST : This command will invoke the bed screws adjustment tool. It will command the nozzle to different locations (as defined in the config file) and allow one to make adjustments to the bed screws so that the bed is a constant distance from the nozzle.","title":"BED_SCREWS_ADJUST"},{"location":"G-Codes.html#bed_tilt","text":"The following commands are available when the bed_tilt config section is enabled.","title":"[bed_tilt]"},{"location":"G-Codes.html#bed_tilt_calibrate","text":"BED_TILT_CALIBRATE [METHOD=manual] [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>] : This command will probe the points specified in the config and then recommend updated x and y tilt adjustments. See the PROBE command for details on the optional probe parameters. If METHOD=manual is specified then the manual probing tool is activated - see the MANUAL_PROBE command above for details on the additional commands available while this tool is active. The optional HORIZONTAL_MOVE_Z value overrides the horizontal_move_z option specified in the config file.","title":"BED_TILT_CALIBRATE"},{"location":"G-Codes.html#bltouch","text":"The following command is available when a bltouch config section is enabled (also see the BL-Touch guide ).","title":"[bltouch]"},{"location":"G-Codes.html#bltouch_debug","text":"BLTOUCH_DEBUG COMMAND=<command> : This sends a command to the BLTouch. It may be useful for debugging. Available commands are: pin_down , touch_mode , pin_up , self_test , reset . A BL-Touch V3.0 or V3.1 may also support set_5V_output_mode , set_OD_output_mode , output_mode_store commands.","title":"BLTOUCH_DEBUG"},{"location":"G-Codes.html#bltouch_store","text":"BLTOUCH_STORE MODE=<output_mode> : This stores an output mode in the EEPROM of a BLTouch V3.1 Available output_modes are: 5V , OD","title":"BLTOUCH_STORE"},{"location":"G-Codes.html#configfile","text":"The configfile module is automatically loaded.","title":"[configfile]"},{"location":"G-Codes.html#save_config","text":"SAVE_CONFIG : This command will overwrite the main printer config file and restart the host software. This command is used in conjunction with other calibration commands to store the results of calibration tests.","title":"SAVE_CONFIG"},{"location":"G-Codes.html#delayed_gcode","text":"The following command is enabled if a delayed_gcode config section has been enabled (also see the template guide ).","title":"[delayed_gcode]"},{"location":"G-Codes.html#update_delayed_gcode","text":"UPDATE_DELAYED_GCODE [ID=<name>] [DURATION=<seconds>] : Updates the delay duration for the identified [delayed_gcode] and starts the timer for gcode execution. A value of 0 will cancel a pending delayed gcode from executing.","title":"UPDATE_DELAYED_GCODE"},{"location":"G-Codes.html#delta_calibrate","text":"The following commands are available when the delta_calibrate config section is enabled (also see the delta calibrate guide ).","title":"[delta_calibrate]"},{"location":"G-Codes.html#delta_calibrate_1","text":"DELTA_CALIBRATE [METHOD=manual] [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>] : This command will probe seven points on the bed and recommend updated endstop positions, tower angles, and radius. See the PROBE command for details on the optional probe parameters. If METHOD=manual is specified then the manual probing tool is activated - see the MANUAL_PROBE command above for details on the additional commands available while this tool is active. The optional HORIZONTAL_MOVE_Z value overrides the horizontal_move_z option specified in the config file.","title":"DELTA_CALIBRATE"},{"location":"G-Codes.html#delta_analyze","text":"DELTA_ANALYZE : This command is used during enhanced delta calibration. See Delta Calibrate for details.","title":"DELTA_ANALYZE"},{"location":"G-Codes.html#display","text":"The following command is available when a display config section is enabled.","title":"[display]"},{"location":"G-Codes.html#set_display_group","text":"SET_DISPLAY_GROUP [DISPLAY=<display>] GROUP=<group> : Set the active display group of an lcd display. This allows to define multiple display data groups in the config, e.g. [display_data <group> <elementname>] and switch between them using this extended gcode command. If DISPLAY is not specified it defaults to \"display\" (the primary display).","title":"SET_DISPLAY_GROUP"},{"location":"G-Codes.html#display_status","text":"The display_status module is automatically loaded if a display config section is enabled. It provides the following standard G-Code commands: Display Message: M117 <message> Set build percentage: M73 P<percent> Also provided is the following extended G-Code command: SET_DISPLAY_TEXT MSG=<message> : Performs the equivalent of M117, setting the supplied MSG as the current display message. If MSG is omitted the display will be cleared.","title":"[display_status]"},{"location":"G-Codes.html#dual_carriage","text":"The following command is available when the dual_carriage config section is enabled.","title":"[dual_carriage]"},{"location":"G-Codes.html#set_dual_carriage","text":"SET_DUAL_CARRIAGE CARRIAGE=<carriage> [MODE=[PRIMARY|COPY|MIRROR]] : This command will change the mode of the specified carriage. If no MODE is provided it defaults to PRIMARY . <carriage> must reference a defined primary or dual carriage for generic_cartesian kinematics or be 0 (for primary carriage) or 1 (for dual carriage) for all other kinematics supporting IDEX. Setting the mode to PRIMARY deactivates the other carriage and makes the specified carriage execute subsequent G-Code commands as-is. COPY and MIRROR modes are supported only for dual carriages. When set to either of these modes, dual carriage will then track the subsequent moves of its primary carriage and either copy relative movements of it (in COPY mode) or execute them in the opposite (mirror) direction (in MIRROR mode).","title":"SET_DUAL_CARRIAGE"},{"location":"G-Codes.html#save_dual_carriage_state","text":"SAVE_DUAL_CARRIAGE_STATE [NAME=<state_name>] : Save the current positions of the dual carriages and their modes. Saving and restoring DUAL_CARRIAGE state can be useful in scripts and macros, as well as in homing routine overrides. If NAME is provided it allows one to name the saved state to the given string. If NAME is not provided it defaults to \"default\".","title":"SAVE_DUAL_CARRIAGE_STATE"},{"location":"G-Codes.html#restore_dual_carriage_state","text":"RESTORE_DUAL_CARRIAGE_STATE [NAME=<state_name>] [MOVE=[0|1] [MOVE_SPEED=<speed>]] : Restore the previously saved positions of the dual carriages and their modes, unless \"MOVE=0\" is specified, in which case only the saved modes will be restored, but not the positions of the carriages. If positions are being restored and \"MOVE_SPEED\" is specified, then the toolhead moves will be performed with the given speed (in mm/s); otherwise the toolhead move will use the rail homing speed. Note that the carriages restore their positions only over their own axis, which may be necessary to correctly restore COPY and MIRROR mode of the dual carriage.","title":"RESTORE_DUAL_CARRIAGE_STATE"},{"location":"G-Codes.html#endstop_phase","text":"The following commands are available when an endstop_phase config section is enabled (also see the endstop phase guide ).","title":"[endstop_phase]"},{"location":"G-Codes.html#endstop_phase_calibrate","text":"ENDSTOP_PHASE_CALIBRATE [STEPPER=<config_name>] : If no STEPPER parameter is provided then this command will reports statistics on endstop stepper phases during past homing operations. When a STEPPER parameter is provided it arranges for the given endstop phase setting to be written to the config file (in conjunction with the SAVE_CONFIG command).","title":"ENDSTOP_PHASE_CALIBRATE"},{"location":"G-Codes.html#exclude_object","text":"The following commands are available when an exclude_object config section is enabled (also see the exclude object guide ):","title":"[exclude_object]"},{"location":"G-Codes.html#exclude_object_1","text":"EXCLUDE_OBJECT [NAME=object_name] [CURRENT=1] [RESET=1] : With no parameters, this will return a list of all currently excluded objects. When the NAME parameter is given, the named object will be excluded from printing. When the CURRENT parameter is given, the current object will be excluded from printing. When the RESET parameter is given, the list of excluded objects will be cleared. Additionally including NAME will only reset the named object. This can cause print failures, if layers were already skipped.","title":"EXCLUDE_OBJECT"},{"location":"G-Codes.html#exclude_object_define","text":"EXCLUDE_OBJECT_DEFINE [NAME=object_name [CENTER=X,Y] [POLYGON=[[x,y],...]] [RESET=1] [JSON=1] : Provides a summary of an object in the file. With no parameters provided, this will list the defined objects known to Klipper. Returns a list of strings, unless the JSON parameter is given, when it will return object details in json format. When the NAME parameter is included, this defines an object to be excluded. NAME : This parameter is required. It is the identifier used by other commands in this module. CENTER : An X,Y coordinate for the object. POLYGON : An array of X,Y coordinates that provide an outline for the object. When the RESET parameter is provided, all defined objects will be cleared, and the [exclude_object] module will be reset.","title":"EXCLUDE_OBJECT_DEFINE"},{"location":"G-Codes.html#exclude_object_start","text":"EXCLUDE_OBJECT_START NAME=object_name : This command takes a NAME parameter and denotes the start of the gcode for an object on the current layer.","title":"EXCLUDE_OBJECT_START"},{"location":"G-Codes.html#exclude_object_end","text":"EXCLUDE_OBJECT_END [NAME=object_name] : Denotes the end of the object's gcode for the layer. It is paired with EXCLUDE_OBJECT_START . A NAME parameter is optional, and will only warn when the provided name does not match the current object.","title":"EXCLUDE_OBJECT_END"},{"location":"G-Codes.html#extruder","text":"The following commands are available if an extruder config section is enabled:","title":"[extruder]"},{"location":"G-Codes.html#activate_extruder","text":"ACTIVATE_EXTRUDER EXTRUDER=<config_name> : In a printer with multiple extruder config sections, this command changes the active hotend.","title":"ACTIVATE_EXTRUDER"},{"location":"G-Codes.html#set_pressure_advance","text":"SET_PRESSURE_ADVANCE [EXTRUDER=<config_name>] [ADVANCE=<pressure_advance>] [SMOOTH_TIME=<pressure_advance_smooth_time>] : Set pressure advance parameters of an extruder stepper (as defined in an extruder or extruder_stepper config section). If EXTRUDER is not specified, it defaults to the stepper defined in the active hotend.","title":"SET_PRESSURE_ADVANCE"},{"location":"G-Codes.html#set_extruder_rotation_distance","text":"SET_EXTRUDER_ROTATION_DISTANCE EXTRUDER=<config_name> [DISTANCE=<distance>] : Set a new value for the provided extruder stepper's \"rotation distance\" (as defined in an extruder or extruder_stepper config section). If the rotation distance is a negative number then the stepper motion will be inverted (relative to the stepper direction specified in the config file). Changed settings are not retained on Klipper reset. Use with caution as small changes can result in excessive pressure between extruder and hotend. Do proper calibration with filament before use. If 'DISTANCE' value is not provided then this command will return the current rotation distance.","title":"SET_EXTRUDER_ROTATION_DISTANCE"},{"location":"G-Codes.html#sync_extruder_motion","text":"SYNC_EXTRUDER_MOTION EXTRUDER=<name> MOTION_QUEUE=<name> : This command will cause the stepper specified by EXTRUDER (as defined in an extruder or extruder_stepper config section) to become synchronized to the movement of an extruder specified by MOTION_QUEUE (as defined in an extruder config section). If MOTION_QUEUE is an empty string then the stepper will be desynchronized from all extruder movement.","title":"SYNC_EXTRUDER_MOTION"},{"location":"G-Codes.html#fan_generic","text":"The following command is available when a fan_generic config section is enabled.","title":"[fan_generic]"},{"location":"G-Codes.html#set_fan_speed","text":"SET_FAN_SPEED FAN=config_name SPEED=<speed> This command sets the speed of a fan. \"speed\" must be between 0.0 and 1.0. SET_FAN_SPEED PIN=config_name TEMPLATE=<template_name> [<param_x>=<literal>] : If TEMPLATE is specified then it assigns a display_template to the given fan. For example, if one defined a [display_template my_fan_template] config section then one could assign TEMPLATE=my_fan_template here. The display_template should produce a string containing a floating point number with the desired value. The template will be continuously evaluated and the fan will be automatically set to the resulting speed. One may set display_template parameters to use during template evaluation (parameters will be parsed as Python literals). If TEMPLATE is an empty string then this command will clear any previous template assigned to the pin (one can then use SET_FAN_SPEED commands to manage the values directly).","title":"SET_FAN_SPEED"},{"location":"G-Codes.html#filament_switch_sensor","text":"The following command is available when a filament_switch_sensor or filament_motion_sensor config section is enabled.","title":"[filament_switch_sensor]"},{"location":"G-Codes.html#query_filament_sensor","text":"QUERY_FILAMENT_SENSOR SENSOR=<sensor_name> : Queries the current status of the filament sensor. The data displayed on the terminal will depend on the sensor type defined in the configuration.","title":"QUERY_FILAMENT_SENSOR"},{"location":"G-Codes.html#set_filament_sensor","text":"SET_FILAMENT_SENSOR SENSOR=<sensor_name> ENABLE=[0|1] : Sets the filament sensor on/off. If ENABLE is set to 0, the filament sensor will be disabled, if set to 1 it is enabled.","title":"SET_FILAMENT_SENSOR"},{"location":"G-Codes.html#firmware_retraction","text":"The following standard G-Code commands are available when the firmware_retraction config section is enabled. These commands allow you to utilize the firmware retraction feature available in many slicers, to reduce stringing during non-extrusion moves from one part of the print to another. Appropriately configuring pressure advance reduces the length of retraction required. G10 : Retracts the extruder using the currently configured parameters. G11 : Unretracts the extruder using the currently configured parameters. The following additional commands are also available.","title":"[firmware_retraction]"},{"location":"G-Codes.html#set_retraction","text":"SET_RETRACTION [RETRACT_LENGTH=<mm>] [RETRACT_SPEED=<mm/s>] [UNRETRACT_EXTRA_LENGTH=<mm>] [UNRETRACT_SPEED=<mm/s>] : Adjust the parameters used by firmware retraction. RETRACT_LENGTH determines the length of filament to retract and unretract. The speed of retraction is adjusted via RETRACT_SPEED, and is typically set relatively high. The speed of unretraction is adjusted via UNRETRACT_SPEED, and is not particularly critical, although often lower than RETRACT_SPEED. In some cases it is useful to add a small amount of additional length on unretraction, and this is set via UNRETRACT_EXTRA_LENGTH. SET_RETRACTION is commonly set as part of slicer per-filament configuration, as different filaments require different parameter settings.","title":"SET_RETRACTION"},{"location":"G-Codes.html#get_retraction","text":"GET_RETRACTION : Queries the current parameters used by firmware retraction and displays them on the terminal.","title":"GET_RETRACTION"},{"location":"G-Codes.html#force_move","text":"The force_move module is automatically loaded, however some commands require setting enable_force_move in the printer config .","title":"[force_move]"},{"location":"G-Codes.html#stepper_buzz","text":"STEPPER_BUZZ STEPPER=<config_name> : Move the given stepper forward one mm and then backward one mm, repeated 10 times. This is a diagnostic tool to help verify stepper connectivity.","title":"STEPPER_BUZZ"},{"location":"G-Codes.html#force_move_1","text":"FORCE_MOVE STEPPER=<config_name> DISTANCE=<value> VELOCITY=<value> [ACCEL=<value>] : This command will forcibly move the given stepper the given distance (in mm) at the given constant velocity (in mm/s). If ACCEL is specified and is greater than zero, then the given acceleration (in mm/s^2) will be used; otherwise no acceleration is performed. No boundary checks are performed; no kinematic updates are made; other parallel steppers on an axis will not be moved. Use caution as an incorrect command could cause damage! Using this command will almost certainly place the low-level kinematics in an incorrect state; issue a G28 afterwards to reset the kinematics. This command is intended for low-level diagnostics and debugging.","title":"FORCE_MOVE"},{"location":"G-Codes.html#set_kinematic_position","text":"SET_KINEMATIC_POSITION [X=<value>] [Y=<value>] [Z=<value>] [SET_HOMED=<[X][Y][Z]>] [CLEAR_HOMED=<[X][Y][Z]>] : Force the low-level kinematic code to believe the toolhead is at the given cartesian position and set/clear homed status. This is a diagnostic and debugging command; use SET_GCODE_OFFSET and/or G92 for regular axis transformations. Setting an incorrect or invalid position may lead to internal software errors. The X , Y , and Z parameters are used to alter the low-level kinematic position tracking. If any of these parameters are not set then the position is not changed - for example SET_KINEMATIC_POSITION Z=10 would set all axes as homed, set the internal Z position to 10, and leave the X and Y positions unchanged. Changing the internal position tracking is not dependent on the internal homing state - one may alter the position for both homed and not homed axes, and similarly one may set or clear the homing state of an axis without altering its internal position. The SET_HOMED parameter defaults to XYZ which instructs the kinematics to consider all axes as homed. A bare SET_KINEMATIC_POSITION command will result in all axes being considered homed (and not change its current position). If it is not desired to change the state of homed axes then assign SET_HOMED to an empty string - for example: SET_KINEMATIC_POSITION SET_HOMED= X=10 . It is also possible to request an individual axis be considered homed (eg, SET_HOMED=X ), but note that non-cartesian style kinematics (such as delta kinematics) may not support setting an individual axis as homed. The CLEAR_HOMED parameter instructs the kinematics to consider the given axes as not homed. For example, CLEAR_HOMED=XYZ would request all axes to be considered not homed (and thus require homing prior to movement on those axes). The default is SET_HOMED=XYZ even if CLEAR_HOMED is present, so the command SET_KINEMATIC_POSITION CLEAR_HOMED=Z will set X and Y as homed and clear the homing state for Z. Use SET_KINEMATIC_POSITION SET_HOMED= CLEAR_HOMED=Z if the goal is to clear only the Z homing state. If an axis is specified in neither SET_HOMED nor CLEAR_HOMED then its homing state is not changed and if it is specified in both then CLEAR_HOMED has precedence. It is possible to request clearing of an individual axis, but on non-cartesian style kinematics (such as delta kinematics) doing so may result in clearing the homing state of additional axes. Note the CLEAR parameter is currently an alias for the CLEAR_HOMED parameter, but this alias will be removed in the future.","title":"SET_KINEMATIC_POSITION"},{"location":"G-Codes.html#gcode","text":"The gcode module is automatically loaded.","title":"[gcode]"},{"location":"G-Codes.html#restart","text":"RESTART : This will cause the host software to reload its config and perform an internal reset. This command will not clear error state from the micro-controller (see FIRMWARE_RESTART) nor will it load new software (see the FAQ ).","title":"RESTART"},{"location":"G-Codes.html#firmware_restart","text":"FIRMWARE_RESTART : This is similar to a RESTART command, but it also clears any error state from the micro-controller.","title":"FIRMWARE_RESTART"},{"location":"G-Codes.html#status","text":"STATUS : Report the Klipper host software status.","title":"STATUS"},{"location":"G-Codes.html#help","text":"HELP : Report the list of available extended G-Code commands.","title":"HELP"},{"location":"G-Codes.html#gcode_arcs","text":"The following standard G-Code commands are available if a gcode_arcs config section is enabled: Arc Move Clockwise (G2), Arc Move Counter-clockwise (G3): G2|G3 [X<pos>] [Y<pos>] [Z<pos>] [E<pos>] [F<speed>] I<value> J<value>|I<value> K<value>|J<value> K<value> Arc Plane Select: G17 (XY plane), G18 (XZ plane), G19 (YZ plane)","title":"[gcode_arcs]"},{"location":"G-Codes.html#gcode_macro","text":"The following command is available when a gcode_macro config section is enabled (also see the command templates guide ).","title":"[gcode_macro]"},{"location":"G-Codes.html#set_gcode_variable","text":"SET_GCODE_VARIABLE MACRO=<macro_name> VARIABLE=<name> VALUE=<value> : This command allows one to change the value of a gcode_macro variable at run-time. The provided VALUE is parsed as a Python literal.","title":"SET_GCODE_VARIABLE"},{"location":"G-Codes.html#gcode_move","text":"The gcode_move module is automatically loaded.","title":"[gcode_move]"},{"location":"G-Codes.html#get_position","text":"GET_POSITION : Return information on the current location of the toolhead. See the developer documentation of GET_POSITION output for more information.","title":"GET_POSITION"},{"location":"G-Codes.html#set_gcode_offset","text":"SET_GCODE_OFFSET [X=<pos>|X_ADJUST=<adjust>] [Y=<pos>|Y_ADJUST=<adjust>] [Z=<pos>|Z_ADJUST=<adjust>] [MOVE=1 [MOVE_SPEED=<speed>]] : Set a positional offset to apply to future G-Code commands. This is commonly used to virtually change the Z bed offset or to set nozzle XY offsets when switching extruders. For example, if \"SET_GCODE_OFFSET Z=0.2\" is sent, then future G-Code moves will have 0.2mm added to their Z height. If the X_ADJUST style parameters are used, then the adjustment will be added to any existing offset (eg, \"SET_GCODE_OFFSET Z=-0.2\" followed by \"SET_GCODE_OFFSET Z_ADJUST=0.3\" would result in a total Z offset of 0.1). If \"MOVE=1\" is specified then a toolhead move will be issued to apply the given offset (otherwise the offset will take effect on the next absolute G-Code move that specifies the given axis). If \"MOVE_SPEED\" is specified then the toolhead move will be performed with the given speed (in mm/s); otherwise the toolhead move will use the last specified G-Code speed.","title":"SET_GCODE_OFFSET"},{"location":"G-Codes.html#save_gcode_state","text":"SAVE_GCODE_STATE [NAME=<state_name>] : Save the current g-code coordinate parsing state. Saving and restoring the g-code state is useful in scripts and macros. This command saves the current g-code absolute coordinate mode (G90/G91), absolute extrude mode (M82/M83), origin (G92), offset (SET_GCODE_OFFSET), speed override (M220), extruder override (M221), move speed, current XYZ position, and relative extruder \"E\" position. If NAME is provided it allows one to name the saved state to the given string. If NAME is not provided it defaults to \"default\".","title":"SAVE_GCODE_STATE"},{"location":"G-Codes.html#restore_gcode_state","text":"RESTORE_GCODE_STATE [NAME=<state_name>] [MOVE=1 [MOVE_SPEED=<speed>]] : Restore a state previously saved via SAVE_GCODE_STATE. If \"MOVE=1\" is specified then a toolhead move will be issued to move back to the previous XYZ position. If \"MOVE_SPEED\" is specified then the toolhead move will be performed with the given speed (in mm/s); otherwise the toolhead move will use the restored g-code speed.","title":"RESTORE_GCODE_STATE"},{"location":"G-Codes.html#generic_cartesian","text":"The commands in this section become automatically available when kinematics: generic_cartesian is specified as the printer kinematics.","title":"[generic_cartesian]"},{"location":"G-Codes.html#set_stepper_carriages","text":"SET_STEPPER_CARRIAGES STEPPER=<stepper_name> CARRIAGES=<carriages> [DISABLE_CHECKS=[0|1]] : Set or update the stepper carriages. <stepper_name> must reference an existing stepper defined in printer.cfg , and <carriages> describes the carriages the stepper moves. See Generic Cartesian Kinematics for a more detailed overview of the carriages parameter in the stepper configuration section. Note that it is only possible to change the coefficients or signs of the carriages with this command, but a user cannot add or remove the carriages that the stepper controls. SET_STEPPER_CARRIAGES is an advanced tool, and the user is advised to exercise an extreme caution using it, since specifying incorrect configuration may physically damage the printer. Note that SET_STEPPER_CARRIAGES performs certain internal validations of the new printer kinematics after the change. Keep in mind that if it detects an issue, it may leave printer kinematics in an invalid state. This means that if SET_STEPPER_CARRIAGES reports an error, it is unsafe to issue other GCode commands, and the user must inspect the error message and either fix the problem, or manually restore the previous stepper(s) configuration. Since SET_STEPPER_CARRIAGES can update a configuration of a single stepper at a time, some sequences of changes can lead to invalid intermediate kinematic configurations, even if the final configuration is valid. In such cases a user can pass DISABLE_CHECKS=1 parameters to all but the last command to disable intermediate checks. For example, if stepper a and stepper b initially have x-y and x+y carriages correspondingly, then the following sequence of commands will let a user effectively swap the carriage controls: SET_STEPPER_CARRIAGES STEPPER=a CARRIAGES=x+y DISABLE_CHECKS=1 and SET_STEPPER_CARRIAGES STEPPER=b CARRIAGES=x-y , while still validating the final kinematics state.","title":"SET_STEPPER_CARRIAGES"},{"location":"G-Codes.html#hall_filament_width_sensor","text":"The following commands are available when the tsl1401cl filament width sensor config section or hall filament width sensor config section is enabled (also see TSLl401CL Filament Width Sensor and Hall Filament Width Sensor ):","title":"[hall_filament_width_sensor]"},{"location":"G-Codes.html#query_filament_width","text":"QUERY_FILAMENT_WIDTH : Return the current measured filament width.","title":"QUERY_FILAMENT_WIDTH"},{"location":"G-Codes.html#reset_filament_width_sensor","text":"RESET_FILAMENT_WIDTH_SENSOR : Clear all sensor readings. Helpful after filament change.","title":"RESET_FILAMENT_WIDTH_SENSOR"},{"location":"G-Codes.html#disable_filament_width_sensor","text":"DISABLE_FILAMENT_WIDTH_SENSOR : Turn off the filament width sensor and stop using it for flow control.","title":"DISABLE_FILAMENT_WIDTH_SENSOR"},{"location":"G-Codes.html#enable_filament_width_sensor","text":"ENABLE_FILAMENT_WIDTH_SENSOR : Turn on the filament width sensor and start using it for flow control.","title":"ENABLE_FILAMENT_WIDTH_SENSOR"},{"location":"G-Codes.html#query_raw_filament_width","text":"QUERY_RAW_FILAMENT_WIDTH : Return the current ADC channel readings and RAW sensor value for calibration points.","title":"QUERY_RAW_FILAMENT_WIDTH"},{"location":"G-Codes.html#enable_filament_width_log","text":"ENABLE_FILAMENT_WIDTH_LOG : Turn on diameter logging.","title":"ENABLE_FILAMENT_WIDTH_LOG"},{"location":"G-Codes.html#disable_filament_width_log","text":"DISABLE_FILAMENT_WIDTH_LOG : Turn off diameter logging.","title":"DISABLE_FILAMENT_WIDTH_LOG"},{"location":"G-Codes.html#heaters","text":"The heaters module is automatically loaded if a heater is defined in the config file.","title":"[heaters]"},{"location":"G-Codes.html#turn_off_heaters","text":"TURN_OFF_HEATERS : Turn off all heaters.","title":"TURN_OFF_HEATERS"},{"location":"G-Codes.html#temperature_wait","text":"TEMPERATURE_WAIT SENSOR=<config_name> [MINIMUM=<target>] [MAXIMUM=<target>] : Wait until the given temperature sensor is at or above the supplied MINIMUM and/or at or below the supplied MAXIMUM.","title":"TEMPERATURE_WAIT"},{"location":"G-Codes.html#set_heater_temperature","text":"SET_HEATER_TEMPERATURE HEATER=<heater_name> [TARGET=<target_temperature>] : Sets the target temperature for a heater. If a target temperature is not supplied, the target is 0.","title":"SET_HEATER_TEMPERATURE"},{"location":"G-Codes.html#idle_timeout","text":"The idle_timeout module is automatically loaded.","title":"[idle_timeout]"},{"location":"G-Codes.html#set_idle_timeout","text":"SET_IDLE_TIMEOUT [TIMEOUT=<timeout>] : Allows the user to set the idle timeout (in seconds).","title":"SET_IDLE_TIMEOUT"},{"location":"G-Codes.html#input_shaper","text":"The following command is enabled if an input_shaper config section has been enabled (also see the resonance compensation guide ).","title":"[input_shaper]"},{"location":"G-Codes.html#set_input_shaper","text":"SET_INPUT_SHAPER [SHAPER_FREQ_X=<shaper_freq_x>] [SHAPER_FREQ_Y=<shaper_freq_y>] [DAMPING_RATIO_X=<damping_ratio_x>] [DAMPING_RATIO_Y=<damping_ratio_y>] [SHAPER_TYPE=<shaper>] [SHAPER_TYPE_X=<shaper_type_x>] [SHAPER_TYPE_Y=<shaper_type_y>] : Modify input shaper parameters. Note that SHAPER_TYPE parameter resets input shaper for both X and Y axes even if different shaper types have been configured in [input_shaper] section. SHAPER_TYPE cannot be used together with either of SHAPER_TYPE_X and SHAPER_TYPE_Y parameters. See config reference for more details on each of these parameters.","title":"SET_INPUT_SHAPER"},{"location":"G-Codes.html#led","text":"The following command is available when any of the led config sections are enabled.","title":"[led]"},{"location":"G-Codes.html#set_led","text":"SET_LED LED=<config_name> RED=<value> GREEN=<value> BLUE=<value> WHITE=<value> [INDEX=<index>] [TRANSMIT=0] [SYNC=1] : This sets the LED output. Each color <value> must be between 0.0 and 1.0. The WHITE option is only valid on RGBW LEDs. If the LED supports multiple chips in a daisy-chain then one may specify INDEX to alter the color of just the given chip (1 for the first chip, 2 for the second, etc.). If INDEX is not provided then all LEDs in the daisy-chain will be set to the provided color. If TRANSMIT=0 is specified then the color change will only be made on the next SET_LED command that does not specify TRANSMIT=0; this may be useful in combination with the INDEX parameter to batch multiple updates in a daisy-chain. By default, the SET_LED command will sync it's changes with other ongoing gcode commands. This can lead to undesirable behavior if LEDs are being set while the printer is not printing as it will reset the idle timeout. If careful timing is not needed, the optional SYNC=0 parameter can be specified to apply the changes without resetting the idle timeout.","title":"SET_LED"},{"location":"G-Codes.html#set_led_template","text":"SET_LED_TEMPLATE LED=<led_name> TEMPLATE=<template_name> [<param_x>=<literal>] [INDEX=<index>] : Assign a display_template to a given LED . For example, if one defined a [display_template my_led_template] config section then one could assign TEMPLATE=my_led_template here. The display_template should produce a comma separated string containing four floating point numbers corresponding to red, green, blue, and white color settings. The template will be continuously evaluated and the LED will be automatically set to the resulting colors. One may set display_template parameters to use during template evaluation (parameters will be parsed as Python literals). If INDEX is not specified then all chips in the LED's daisy-chain will be set to the template, otherwise only the chip with the given index will be updated. If TEMPLATE is an empty string then this command will clear any previous template assigned to the LED (one can then use SET_LED commands to manage the LED's color settings).","title":"SET_LED_TEMPLATE"},{"location":"G-Codes.html#load_cell","text":"The following commands are enabled if a load_cell config section has been enabled.","title":"[load_cell]"},{"location":"G-Codes.html#load_cell_diagnostic","text":"LOAD_CELL_DIAGNOSTIC [LOAD_CELL=<config_name>] : This command collects 10 seconds of load cell data and reports statistics that can help you verify proper operation of the load cell. This command can be run on both calibrated and uncalibrated load cells.","title":"LOAD_CELL_DIAGNOSTIC"},{"location":"G-Codes.html#load_cell_calibrate","text":"LOAD_CELL_CALIBRATE [LOAD_CELL=<config_name>] : Start the guided calibration utility. Calibration is a 3 step process: First you remove all load from the load cell and run the TARE command Next you apply a known load to the load cell and run the CALIBRATE GRAMS=nnn command Finally use the ACCEPT command to save the results You can cancel the calibration process at any time with ABORT .","title":"LOAD_CELL_CALIBRATE"},{"location":"G-Codes.html#load_cell_tare","text":"LOAD_CELL_TARE [LOAD_CELL=<config_name>] : This works just like the tare button on digital scale. It sets the current raw reading of the load cell to be the zero point reference value. The response is the percentage of the sensors range that was read and the raw value in counts. If the load cell is calibrated a force in grams is also reported.","title":"LOAD_CELL_TARE"},{"location":"G-Codes.html#load_cell_read-load_cellname","text":"LOAD_CELL_READ [LOAD_CELL=<config_name>] : This command takes a reading from the load cell. The response is the percentage of the sensors range that was read and the raw value in counts. If the load cell is calibrated a force in grams is also reported.","title":"LOAD_CELL_READ load_cell=\"name\""},{"location":"G-Codes.html#load_cell_probe","text":"The following commands are enabled if a load_cell config section has been enabled.","title":"[load_cell_probe]"},{"location":"G-Codes.html#load_cell_test_tap","text":"LOAD_CELL_TEST_TAP [TAPS=<taps>] [TIMEOUT=<timeout>] : Run a testing routine that reports taps on the load cell. The toolhead will not move but the load cell probe will sense taps just as if it was probing. This can be used as a sanity check to make sure that the probe works. This tool replaces QUERY_ENDSTOPS and QUERY_PROBE for load cell probes. TAPS : the number of taps the tool expects TIMEOOUT : the time, in seconds, that the tool waits for each tab before aborting.","title":"LOAD_CELL_TEST_TAP"},{"location":"G-Codes.html#load-cell-command-extensions","text":"Commands that perform probes, such as PROBE , PROBE_ACCURACY , BED_MESH_CALIBRATE etc. will accept additional parameters if a [load_cell_probe] is defined. The parameters override the corresponding settings from the [load_cell_probe] configuration: FORCE_SAFETY_LIMIT=<grams> TRIGGER_FORCE=<grams> DRIFT_FILTER_CUTOFF_FREQUENCY=<frequency_hz> DRIFT_FILTER_DELAY=<1|2> BUZZ_FILTER_CUTOFF_FREQUENCY=<frequency_hz> BUZZ_FILTER_DELAY=<1|2> NOTCH_FILTER_FREQUENCIES=<list of frequency_hz> NOTCH_FILTER_QUALITY=<quality> TARE_TIME=<seconds>","title":"Load Cell Command Extensions"},{"location":"G-Codes.html#manual_probe","text":"The manual_probe module is automatically loaded.","title":"[manual_probe]"},{"location":"G-Codes.html#manual_probe_1","text":"MANUAL_PROBE [SPEED=<speed>] : Run a helper script useful for measuring the height of the nozzle at a given location. If SPEED is specified, it sets the speed of TESTZ commands (the default is 5mm/s). During a manual probe, the following additional commands are available: ACCEPT : This command accepts the current Z position and concludes the manual probing tool. ABORT : This command terminates the manual probing tool. TESTZ Z=<value> : This command moves the nozzle up or down by the amount specified in \"value\". For example, TESTZ Z=-.1 would move the nozzle down .1mm while TESTZ Z=.1 would move the nozzle up .1mm. The value may also be + , - , ++ , or -- to move the nozzle up or down an amount relative to previous attempts.","title":"MANUAL_PROBE"},{"location":"G-Codes.html#z_endstop_calibrate","text":"Z_ENDSTOP_CALIBRATE [SPEED=<speed>] : Run a helper script useful for calibrating a Z position_endstop config setting. See the MANUAL_PROBE command for details on the parameters and the additional commands available while the tool is active.","title":"Z_ENDSTOP_CALIBRATE"},{"location":"G-Codes.html#z_offset_apply_endstop","text":"Z_OFFSET_APPLY_ENDSTOP : Take the current Z Gcode offset (aka, babystepping), and subtract it from the stepper_z endstop_position. This acts to take a frequently used babystepping value, and \"make it permanent\". Requires a SAVE_CONFIG to take effect.","title":"Z_OFFSET_APPLY_ENDSTOP"},{"location":"G-Codes.html#manual_stepper","text":"The following command is available when a manual_stepper config section is enabled.","title":"[manual_stepper]"},{"location":"G-Codes.html#manual_stepper_1","text":"MANUAL_STEPPER STEPPER=config_name [ENABLE=[0|1]] [SET_POSITION=<pos>] [SPEED=<speed>] [ACCEL=<accel>] [MOVE=<pos> [STOP_ON_ENDSTOP=[1|2|-1|-2]] [SYNC=0]] : This command will alter the state of the stepper. Use the ENABLE parameter to enable/disable the stepper. Use the SET_POSITION parameter to force the stepper to think it is at the given position. Use the MOVE parameter to request a movement to the given position. If SPEED and/or ACCEL is specified then the given values will be used instead of the defaults specified in the config file. If an ACCEL of zero is specified then no acceleration will be performed. If STOP_ON_ENDSTOP=1 is specified then the move will end early should the endstop report as triggered (use STOP_ON_ENDSTOP=2 to complete the move without error even if the endstop does not trigger, use -1 or -2 to stop when the endstop reports not triggered). Normally future G-Code commands will be scheduled to run after the stepper move completes, however if a manual stepper move uses SYNC=0 then future G-Code movement commands may run in parallel with the stepper movement. MANUAL_STEPPER STEPPER=config_name GCODE_AXIS=[A-Z] [LIMIT_VELOCITY=<velocity>] [LIMIT_ACCEL=<accel>] [INSTANTANEOUS_CORNER_VELOCITY=<velocity>] : If the GCODE_AXIS parameter is specified then it configures the stepper motor as an extra axis on G1 move commands. For example, if one were to issue a MANUAL_STEPPER ... GCODE_AXIS=R command then one could issue commands like G1 X10 Y20 R30 to move the stepper motor. The resulting moves will occur synchronously with the associated toolhead xyz movements. If the motor is associated with a GCODE_AXIS then one may no longer issue movements using the above MANUAL_STEPPER command - one may unregister the stepper with a MANUAL_STEPPER ... GCODE_AXIS= command to resume manual control of the motor. The LIMIT_VELOCITY and LIMIT_ACCEL parameters allow one to reduce the speed of G1 moves if those moves would result in a velocity or acceleration above the specified limits. The INSTANTANEOUS_CORNER_VELOCITY specifies the maximum instantaneous velocity change (in mm/s) of the motor during the junction of two moves (the default is 1mm/s).","title":"MANUAL_STEPPER"},{"location":"G-Codes.html#mcp4018","text":"The following command is available when a mcp4018 config section is enabled.","title":"[mcp4018]"},{"location":"G-Codes.html#set_digipot","text":"SET_DIGIPOT DIGIPOT=config_name WIPER=<value> : This command will change the current value of the digipot. This value should typically be between 0.0 and 1.0, unless a 'scale' is defined in the config. When 'scale' is defined, then this value should be between 0.0 and 'scale'.","title":"SET_DIGIPOT"},{"location":"G-Codes.html#output_pin","text":"The following command is available when an output_pin config section or pwm_tool config section is enabled.","title":"[output_pin]"},{"location":"G-Codes.html#set_pin","text":"SET_PIN PIN=config_name VALUE=<value> : Set the pin to the given output VALUE . VALUE should be 0 or 1 for \"digital\" output pins. For PWM pins, set to a value between 0.0 and 1.0, or between 0.0 and scale if a scale is configured in the output_pin config section. SET_PIN PIN=config_name TEMPLATE=<template_name> [<param_x>=<literal>] : If TEMPLATE is specified then it assigns a display_template to the given pin. For example, if one defined a [display_template my_pin_template] config section then one could assign TEMPLATE=my_pin_template here. The display_template should produce a string containing a floating point number with the desired value. The template will be continuously evaluated and the pin will be automatically set to the resulting value. One may set display_template parameters to use during template evaluation (parameters will be parsed as Python literals). If TEMPLATE is an empty string then this command will clear any previous template assigned to the pin (one can then use SET_PIN commands to manage the values directly).","title":"SET_PIN"},{"location":"G-Codes.html#palette2","text":"The following commands are available when the palette2 config section is enabled. Palette prints work by embedding special OCodes (Omega Codes) in the GCode file: O1 ... O32 : These codes are read from the GCode stream and processed by this module and passed to the Palette 2 device. The following additional commands are also available.","title":"[palette2]"},{"location":"G-Codes.html#palette_connect","text":"PALETTE_CONNECT : This command initializes the connection with the Palette 2.","title":"PALETTE_CONNECT"},{"location":"G-Codes.html#palette_disconnect","text":"PALETTE_DISCONNECT : This command disconnects from the Palette 2.","title":"PALETTE_DISCONNECT"},{"location":"G-Codes.html#palette_clear","text":"PALETTE_CLEAR : This command instructs the Palette 2 to clear all of the input and output paths of filament.","title":"PALETTE_CLEAR"},{"location":"G-Codes.html#palette_cut","text":"PALETTE_CUT : This command instructs the Palette 2 to cut the filament currently loaded in the splice core.","title":"PALETTE_CUT"},{"location":"G-Codes.html#palette_smart_load","text":"PALETTE_SMART_LOAD : This command start the smart load sequence on the Palette 2. Filament is loaded automatically by extruding it the distance calibrated on the device for the printer, and instructs the Palette 2 once the loading has been completed. This command is the same as pressing Smart Load directly on the Palette 2 screen after the filament load is complete.","title":"PALETTE_SMART_LOAD"},{"location":"G-Codes.html#pause_resume","text":"The following commands are available when the pause_resume config section is enabled:","title":"[pause_resume]"},{"location":"G-Codes.html#pause","text":"PAUSE : Pauses the current print. The current position is captured for restoration upon resume.","title":"PAUSE"},{"location":"G-Codes.html#resume","text":"RESUME [VELOCITY=<value>] : Resumes the print from a pause, first restoring the previously captured position. The VELOCITY parameter determines the speed at which the tool should return to the original captured position.","title":"RESUME"},{"location":"G-Codes.html#clear_pause","text":"CLEAR_PAUSE : Clears the current paused state without resuming the print. This is useful if one decides to cancel a print after a PAUSE. It is recommended to add this to your start gcode to make sure the paused state is fresh for each print.","title":"CLEAR_PAUSE"},{"location":"G-Codes.html#cancel_print","text":"CANCEL_PRINT : Cancels the current print.","title":"CANCEL_PRINT"},{"location":"G-Codes.html#pid_calibrate","text":"The pid_calibrate module is automatically loaded if a heater is defined in the config file.","title":"[pid_calibrate]"},{"location":"G-Codes.html#pid_calibrate_1","text":"PID_CALIBRATE HEATER=<config_name> TARGET=<temperature> [WRITE_FILE=1] : Perform a PID calibration test. The specified heater will be enabled until the specified target temperature is reached, and then the heater will be turned off and on for several cycles. If the WRITE_FILE parameter is enabled, then the file /tmp/heattest.txt will be created with a log of all temperature samples taken during the test.","title":"PID_CALIBRATE"},{"location":"G-Codes.html#print_stats","text":"The print_stats module is automatically loaded.","title":"[print_stats]"},{"location":"G-Codes.html#set_print_stats_info","text":"SET_PRINT_STATS_INFO [TOTAL_LAYER=<total_layer_count>] [CURRENT_LAYER= <current_layer>] : Pass slicer info like layer act and total to Klipper. Add SET_PRINT_STATS_INFO [TOTAL_LAYER=<total_layer_count>] to your slicer start gcode section and SET_PRINT_STATS_INFO [CURRENT_LAYER= <current_layer>] at the layer change gcode section to pass layer information from your slicer to Klipper.","title":"SET_PRINT_STATS_INFO"},{"location":"G-Codes.html#probe","text":"The following commands are available when a probe config section or bltouch config section is enabled (also see the probe calibrate guide ).","title":"[probe]"},{"location":"G-Codes.html#probe_1","text":"PROBE [PROBE_SPEED=<mm/s>] [LIFT_SPEED=<mm/s>] [SAMPLES=<count>] [SAMPLE_RETRACT_DIST=<mm>] [SAMPLES_TOLERANCE=<mm>] [SAMPLES_TOLERANCE_RETRIES=<count>] [SAMPLES_RESULT=median|average] : Move the nozzle downwards until the probe triggers. If any of the optional parameters are provided they override their equivalent setting in the probe config section .","title":"PROBE"},{"location":"G-Codes.html#query_probe","text":"QUERY_PROBE : Report the current status of the probe (\"triggered\" or \"open\").","title":"QUERY_PROBE"},{"location":"G-Codes.html#probe_accuracy","text":"PROBE_ACCURACY [PROBE_SPEED=<mm/s>] [SAMPLES=<count>] [SAMPLE_RETRACT_DIST=<mm>] : Calculate the maximum, minimum, average, median, and standard deviation of multiple probe samples. By default, 10 SAMPLES are taken. Otherwise the optional parameters default to their equivalent setting in the probe config section.","title":"PROBE_ACCURACY"},{"location":"G-Codes.html#probe_calibrate","text":"PROBE_CALIBRATE [SPEED=<speed>] [<probe_parameter>=<value>] : Run a helper script useful for calibrating the probe's z_offset. See the PROBE command for details on the optional probe parameters. See the MANUAL_PROBE command for details on the SPEED parameter and the additional commands available while the tool is active. Please note, the PROBE_CALIBRATE command uses the speed variable to move in XY direction as well as Z.","title":"PROBE_CALIBRATE"},{"location":"G-Codes.html#z_offset_apply_probe","text":"Z_OFFSET_APPLY_PROBE : Take the current Z Gcode offset (aka, babystepping), and subtract if from the probe's z_offset. This acts to take a frequently used babystepping value, and \"make it permanent\". Requires a SAVE_CONFIG to take effect.","title":"Z_OFFSET_APPLY_PROBE"},{"location":"G-Codes.html#probe_eddy_current","text":"The following commands are available when a probe_eddy_current config section is enabled.","title":"[probe_eddy_current]"},{"location":"G-Codes.html#probe_eddy_current_calibrate","text":"PROBE_EDDY_CURRENT_CALIBRATE CHIP=<config_name> : This starts a tool that calibrates the sensor resonance frequencies to corresponding Z heights. The tool will take a couple of minutes to complete. After completion, use the SAVE_CONFIG command to store the results in the printer.cfg file.","title":"PROBE_EDDY_CURRENT_CALIBRATE"},{"location":"G-Codes.html#ldc_calibrate_drive_current","text":"LDC_CALIBRATE_DRIVE_CURRENT CHIP=<config_name> This tool will calibrate the ldc1612 DRIVE_CURRENT0 register. Prior to using this tool, move the sensor so that it is near the center of the bed and about 20mm above the bed surface. Run this command to determine an appropriate DRIVE_CURRENT for the sensor. After running this command use the SAVE_CONFIG command to store that new setting in the printer.cfg config file.","title":"LDC_CALIBRATE_DRIVE_CURRENT"},{"location":"G-Codes.html#pwm_cycle_time","text":"The following command is available when a pwm_cycle_time config section is enabled.","title":"[pwm_cycle_time]"},{"location":"G-Codes.html#set_pin_1","text":"SET_PIN PIN=config_name VALUE=<value> [CYCLE_TIME=<cycle_time>] : This command works similarly to output_pin SET_PIN commands. The command here supports setting an explicit cycle time using the CYCLE_TIME parameter (specified in seconds). Note that the CYCLE_TIME parameter is not stored between SET_PIN commands (any SET_PIN command without an explicit CYCLE_TIME parameter will use the cycle_time specified in the pwm_cycle_time config section).","title":"SET_PIN"},{"location":"G-Codes.html#quad_gantry_level","text":"The following commands are available when the quad_gantry_level config section is enabled.","title":"[quad_gantry_level]"},{"location":"G-Codes.html#quad_gantry_level_1","text":"QUAD_GANTRY_LEVEL [RETRIES=<value>] [RETRY_TOLERANCE=<value>] [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>] : This command will probe the points specified in the config and then make independent adjustments to each Z stepper to compensate for tilt. See the PROBE command for details on the optional probe parameters. The optional RETRIES , RETRY_TOLERANCE , and HORIZONTAL_MOVE_Z values override those options specified in the config file.","title":"QUAD_GANTRY_LEVEL"},{"location":"G-Codes.html#query_adc","text":"The query_adc module is automatically loaded.","title":"[query_adc]"},{"location":"G-Codes.html#query_adc_1","text":"QUERY_ADC [NAME=<config_name>] [PULLUP=<value>] : Report the last analog value received for a configured analog pin. If NAME is not provided, the list of available adc names are reported. If PULLUP is provided (as a value in Ohms), the raw analog value along with the equivalent resistance given that pullup is reported.","title":"QUERY_ADC"},{"location":"G-Codes.html#query_endstops","text":"The query_endstops module is automatically loaded. The following standard G-Code commands are currently available, but using them is not recommended: Get Endstop Status: M119 (Use QUERY_ENDSTOPS instead.)","title":"[query_endstops]"},{"location":"G-Codes.html#query_endstops_1","text":"QUERY_ENDSTOPS : Probe the axis endstops and report if they are \"triggered\" or in an \"open\" state. This command is typically used to verify that an endstop is working correctly.","title":"QUERY_ENDSTOPS"},{"location":"G-Codes.html#resonance_tester","text":"The following commands are available when a resonance_tester config section is enabled (also see the measuring resonances guide ).","title":"[resonance_tester]"},{"location":"G-Codes.html#measure_axes_noise","text":"MEASURE_AXES_NOISE : Measures and outputs the noise for all axes of all enabled accelerometer chips.","title":"MEASURE_AXES_NOISE"},{"location":"G-Codes.html#test_resonances","text":"TEST_RESONANCES AXIS=<axis> [OUTPUT=<resonances,raw_data>] [NAME=<name>] [FREQ_START=<min_freq>] [FREQ_END=<max_freq>] [ACCEL_PER_HZ=<accel_per_hz>] [HZ_PER_SEC=<hz_per_sec>] [CHIPS=<chip_name>] [POINT=x,y,z] [INPUT_SHAPING=<0:1>] : Runs the resonance test in all configured probe points for the requested \"axis\" and measures the acceleration using the accelerometer chips configured for the respective axis. \"axis\" can either be X or Y, or specify an arbitrary direction as AXIS=dx,dy , where dx and dy are floating point numbers defining a direction vector (e.g. AXIS=X , AXIS=Y , or AXIS=1,-1 to define a diagonal direction). Note that AXIS=dx,dy and AXIS=-dx,-dy is equivalent. chip_name can be one or more configured accel chips, delimited with comma, for example CHIPS=\"adxl345, adxl345 rpi\" . If POINT is specified it will override the point(s) configured in [resonance_tester] . If INPUT_SHAPING=0 or not set(default), disables input shaping for the resonance testing, because it is not valid to run the resonance testing with the input shaper enabled. OUTPUT parameter is a comma-separated list of which outputs will be written. If raw_data is requested, then the raw accelerometer data is written into a file or a series of files /tmp/raw_data_<axis>_[<chip_name>_][<point>_]<name>.csv with ( <point>_ part of the name generated only if more than 1 probe point is configured or POINT is specified). If resonances is specified, the frequency response is calculated (across all probe points) and written into /tmp/resonances_<axis>_<name>.csv file. If unset, OUTPUT defaults to resonances , and NAME defaults to the current time in \"YYYYMMDD_HHMMSS\" format.","title":"TEST_RESONANCES"},{"location":"G-Codes.html#shaper_calibrate","text":"SHAPER_CALIBRATE [AXIS=<axis>] [NAME=<name>] [FREQ_START=<min_freq>] [FREQ_END=<max_freq>] [ACCEL_PER_HZ=<accel_per_hz>][HZ_PER_SEC=<hz_per_sec>] [CHIPS=<chip_name>] [MAX_SMOOTHING=<max_smoothing>] [INPUT_SHAPING=<0:1>] : Similarly to TEST_RESONANCES , runs the resonance test as configured, and tries to find the optimal parameters for the input shaper for the requested axis (or both X and Y axes if AXIS parameter is unset). If MAX_SMOOTHING is unset, its value is taken from [resonance_tester] section, with the default being unset. See the Max smoothing of the measuring resonances guide for more information on the use of this feature. The results of the tuning are printed to the console, and the frequency responses and the different input shapers values are written to a CSV file(s) /tmp/calibration_data_<axis>_<name>.csv . Unless specified, NAME defaults to the current time in \"YYYYMMDD_HHMMSS\" format. Note that the suggested input shaper parameters can be persisted in the config by issuing SAVE_CONFIG command, and if [input_shaper] was already enabled previously, these parameters take effect immediately.","title":"SHAPER_CALIBRATE"},{"location":"G-Codes.html#respond","text":"The following standard G-Code commands are available when the respond config section is enabled: M118 <message> : echo the message prepended with the configured default prefix (or echo: if no prefix is configured). The following additional commands are also available.","title":"[respond]"},{"location":"G-Codes.html#respond_1","text":"RESPOND MSG=\"<message>\" : echo the message prepended with the configured default prefix (or echo: if no prefix is configured). RESPOND TYPE=echo MSG=\"<message>\" : echo the message prepended with echo: . RESPOND TYPE=echo_no_space MSG=\"<message>\" : echo the message prepended with echo: without a space between prefix and message, helpful for compatibility with some octoprint plugins that expect very specific formatting. RESPOND TYPE=command MSG=\"<message>\" : echo the message prepended with // . OctoPrint can be configured to respond to these messages (e.g. RESPOND TYPE=command MSG=action:pause ). RESPOND TYPE=error MSG=\"<message>\" : echo the message prepended with !! . RESPOND PREFIX=<prefix> MSG=\"<message>\" : echo the message prepended with <prefix> . (The PREFIX parameter will take priority over the TYPE parameter)","title":"RESPOND"},{"location":"G-Codes.html#save_variables","text":"The following command is enabled if a save_variables config section has been enabled.","title":"[save_variables]"},{"location":"G-Codes.html#save_variable","text":"SAVE_VARIABLE VARIABLE=<name> VALUE=<value> : Saves the variable to disk so that it can be used across restarts. The VARIABLE must be lowercase. All stored variables are loaded into the printer.save_variables.variables dict at startup and can be used in gcode macros. The provided VALUE is parsed as a Python literal.","title":"SAVE_VARIABLE"},{"location":"G-Codes.html#screws_tilt_adjust","text":"The following commands are available when the screws_tilt_adjust config section is enabled (also see the manual level guide ).","title":"[screws_tilt_adjust]"},{"location":"G-Codes.html#screws_tilt_calculate","text":"SCREWS_TILT_CALCULATE [DIRECTION=CW|CCW] [MAX_DEVIATION=<value>] [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>] : This command will invoke the bed screws adjustment tool. It will command the nozzle to different locations (as defined in the config file) probing the z height and calculate the number of knob turns to adjust the bed level. If DIRECTION is specified, the knob turns will all be in the same direction, clockwise (CW) or counterclockwise (CCW). See the PROBE command for details on the optional probe parameters. IMPORTANT: You MUST always do a G28 before using this command. If MAX_DEVIATION is specified, the command will raise a gcode error if any difference in the screw height relative to the base screw height is greater than the value provided. The optional HORIZONTAL_MOVE_Z value overrides the horizontal_move_z option specified in the config file.","title":"SCREWS_TILT_CALCULATE"},{"location":"G-Codes.html#sdcard_loop","text":"When the sdcard_loop config section is enabled, the following extended commands are available.","title":"[sdcard_loop]"},{"location":"G-Codes.html#sdcard_loop_begin","text":"SDCARD_LOOP_BEGIN COUNT=<count> : Begin a looped section in the SD print. A count of 0 indicates that the section should be looped indefinitely.","title":"SDCARD_LOOP_BEGIN"},{"location":"G-Codes.html#sdcard_loop_end","text":"SDCARD_LOOP_END : End a looped section in the SD print.","title":"SDCARD_LOOP_END"},{"location":"G-Codes.html#sdcard_loop_desist","text":"SDCARD_LOOP_DESIST : Complete existing loops without further iterations.","title":"SDCARD_LOOP_DESIST"},{"location":"G-Codes.html#servo","text":"The following commands are available when a servo config section is enabled.","title":"[servo]"},{"location":"G-Codes.html#set_servo","text":"SET_SERVO SERVO=config_name [ANGLE=<degrees> | WIDTH=<seconds>] : Set the servo position to the given angle (in degrees) or pulse width (in seconds). Use WIDTH=0 to disable the servo output.","title":"SET_SERVO"},{"location":"G-Codes.html#skew_correction","text":"The following commands are available when the skew_correction config section is enabled (also see the Skew Correction guide).","title":"[skew_correction]"},{"location":"G-Codes.html#set_skew","text":"SET_SKEW [XY=<ac_length,bd_length,ad_length>] [XZ=<ac,bd,ad>] [YZ=<ac,bd,ad>] [CLEAR=<0|1>] : Configures the [skew_correction] module with measurements (in mm) taken from a calibration print. One may enter measurements for any combination of planes, planes not entered will retain their current value. If CLEAR=1 is entered then all skew correction will be disabled.","title":"SET_SKEW"},{"location":"G-Codes.html#get_current_skew","text":"GET_CURRENT_SKEW : Reports the current printer skew for each plane in both radians and degrees. The skew is calculated based on parameters provided via the SET_SKEW gcode.","title":"GET_CURRENT_SKEW"},{"location":"G-Codes.html#calc_measured_skew","text":"CALC_MEASURED_SKEW [AC=<ac_length>] [BD=<bd_length>] [AD=<ad_length>] : Calculates and reports the skew (in radians and degrees) based on a measured print. This can be useful for determining the printer's current skew after correction has been applied. It may also be useful before correction is applied to determine if skew correction is necessary. See Skew Correction for details on skew calibration objects and measurements.","title":"CALC_MEASURED_SKEW"},{"location":"G-Codes.html#skew_profile","text":"SKEW_PROFILE [LOAD=<name>] [SAVE=<name>] [REMOVE=<name>] : Profile management for skew_correction. LOAD will restore skew state from the profile matching the supplied name. SAVE will save the current skew state to a profile matching the supplied name. Remove will delete the profile matching the supplied name from persistent memory. Note that after SAVE or REMOVE operations have been run the SAVE_CONFIG gcode must be run to make the changes to persistent memory permanent.","title":"SKEW_PROFILE"},{"location":"G-Codes.html#smart_effector","text":"Several commands are available when a smart_effector config section is enabled. Be sure to check the official documentation for the Smart Effector on the Duet3D Wiki before changing the Smart Effector parameters. Also check the probe calibration guide .","title":"[smart_effector]"},{"location":"G-Codes.html#set_smart_effector","text":"SET_SMART_EFFECTOR [SENSITIVITY=<sensitivity>] [ACCEL=<accel>] [RECOVERY_TIME=<time>] : Set the Smart Effector parameters. When SENSITIVITY is specified, the respective value is written to the SmartEffector EEPROM (requires control_pin to be provided). Acceptable <sensitivity> values are 0..255, the default is 50. Lower values require less nozzle contact force to trigger (but there is a higher risk of false triggering due to vibrations during probing), and higher values reduce false triggering (but require larger contact force to trigger). Since the sensitivity is written to EEPROM, it is preserved after the shutdown, and so it does not need to be configured on every printer startup. ACCEL and RECOVERY_TIME allow to override the corresponding parameters at run-time, see the config section of Smart Effector for more info on those parameters.","title":"SET_SMART_EFFECTOR"},{"location":"G-Codes.html#reset_smart_effector","text":"RESET_SMART_EFFECTOR : Resets Smart Effector sensitivity to its factory settings. Requires control_pin to be provided in the config section.","title":"RESET_SMART_EFFECTOR"},{"location":"G-Codes.html#stepper_enable","text":"The stepper_enable module is automatically loaded.","title":"[stepper_enable]"},{"location":"G-Codes.html#set_stepper_enable","text":"SET_STEPPER_ENABLE STEPPER=<config_name> ENABLE=[0|1] : Enable or disable only the given stepper. This is a diagnostic and debugging tool and must be used with care. Disabling an axis motor does not reset the homing information. Manually moving a disabled stepper may cause the machine to operate the motor outside of safe limits. This can lead to damage to axis components, hot ends, and print surface.","title":"SET_STEPPER_ENABLE"},{"location":"G-Codes.html#temperature_fan","text":"The following command is available when a temperature_fan config section is enabled.","title":"[temperature_fan]"},{"location":"G-Codes.html#set_temperature_fan_target","text":"SET_TEMPERATURE_FAN_TARGET temperature_fan=<temperature_fan_name> [target=<target_temperature>] [min_speed=<min_speed>] [max_speed=<max_speed>] : Sets the target temperature for a temperature_fan. If a target is not supplied, it is set to the specified temperature in the config file. If speeds are not supplied, no change is applied.","title":"SET_TEMPERATURE_FAN_TARGET"},{"location":"G-Codes.html#temperature_probe","text":"The following commands are available when a temperature_probe config section is enabled.","title":"[temperature_probe]"},{"location":"G-Codes.html#temperature_probe_calibrate","text":"TEMPERATURE_PROBE_CALIBRATE [PROBE=<probe name>] [TARGET=<value>] [STEP=<value>] : Initiates probe drift calibration for eddy current based probes. The TARGET is a target temperature for the last sample. When the temperature recorded during a sample exceeds the TARGET calibration will complete. The STEP parameter sets temperature delta (in C) between samples. After a sample has been taken, this delta is used to schedule a call to TEMPERATURE_PROBE_NEXT . The default STEP is 2.","title":"TEMPERATURE_PROBE_CALIBRATE"},{"location":"G-Codes.html#temperature_probe_next","text":"TEMPERATURE_PROBE_NEXT : After calibration has started this command is run to take the next sample. It is automatically scheduled to run when the delta specified by STEP has been reached, however its also possible to manually run this command to force a new sample. This command is only available during calibration.","title":"TEMPERATURE_PROBE_NEXT"},{"location":"G-Codes.html#temperature_probe_complete","text":"TEMPERATURE_PROBE_COMPLETE : Can be used to end calibration and save the current result before the TARGET temperature is reached. This command is only available during calibration.","title":"TEMPERATURE_PROBE_COMPLETE:"},{"location":"G-Codes.html#abort","text":"ABORT : Aborts the calibration process, discarding the current results. This command is only available during drift calibration.","title":"ABORT"},{"location":"G-Codes.html#temperature_probe_enable","text":"TEMPERATURE_PROBE_ENABLE ENABLE=[0|1] : Sets temperature drift compensation on or off. If ENABLE is set to 0, drift compensation will be disabled, if set to 1 it is enabled.","title":"TEMPERATURE_PROBE_ENABLE"},{"location":"G-Codes.html#tmcxxxx","text":"The following commands are available when any of the tmcXXXX config sections are enabled.","title":"[tmcXXXX]"},{"location":"G-Codes.html#dump_tmc","text":"DUMP_TMC STEPPER=<name> [REGISTER=<name>] : This command will read all TMC driver registers and report their values. If a REGISTER is provided, only the specified register will be dumped.","title":"DUMP_TMC"},{"location":"G-Codes.html#init_tmc","text":"INIT_TMC STEPPER=<name> : This command will initialize the TMC registers. Needed to re-enable the driver if power to the chip is turned off then back on.","title":"INIT_TMC"},{"location":"G-Codes.html#set_tmc_current","text":"SET_TMC_CURRENT STEPPER=<name> CURRENT=<amps> HOLDCURRENT=<amps> : This will adjust the run and hold currents of the TMC driver. HOLDCURRENT is not applicable to tmc2660 drivers. When used on a driver which has the globalscaler field (tmc5160 and tmc2240), if StealthChop2 is used, the stepper must be held at standstill for >130ms so that the driver executes the AT#1 calibration.","title":"SET_TMC_CURRENT"},{"location":"G-Codes.html#set_tmc_field","text":"SET_TMC_FIELD STEPPER=<name> FIELD=<field> VALUE=<value> VELOCITY=<value> : This will alter the value of the specified register field of the TMC driver. This command is intended for low-level diagnostics and debugging only because changing the fields during run-time can lead to undesired and potentially dangerous behavior of your printer. Permanent changes should be made using the printer configuration file instead. No sanity checks are performed for the given values. A VELOCITY can also be specified instead of a VALUE. This velocity is converted to the 20bit TSTEP based value representation. Only use the VELOCITY argument for fields that represent velocities.","title":"SET_TMC_FIELD"},{"location":"G-Codes.html#toolhead","text":"The toolhead module is automatically loaded.","title":"[toolhead]"},{"location":"G-Codes.html#set_velocity_limit","text":"SET_VELOCITY_LIMIT [VELOCITY=<value>] [ACCEL=<value>] [MINIMUM_CRUISE_RATIO=<value>] [SQUARE_CORNER_VELOCITY=<value>] : This command can alter the velocity limits that were specified in the printer config file. See the printer config section for a description of each parameter.","title":"SET_VELOCITY_LIMIT"},{"location":"G-Codes.html#tuning_tower","text":"The tuning_tower module is automatically loaded.","title":"[tuning_tower]"},{"location":"G-Codes.html#tuning_tower_1","text":"TUNING_TOWER COMMAND=<command> PARAMETER=<name> START=<value> [SKIP=<value>] [FACTOR=<value> [BAND=<value>]] | [STEP_DELTA=<value> STEP_HEIGHT=<value>] : A tool for tuning a parameter on each Z height during a print. The tool will run the given COMMAND with the given PARAMETER assigned to a value that varies with Z according to a formula. Use FACTOR if you will use a ruler or calipers to measure the Z height of the optimum value, or STEP_DELTA and STEP_HEIGHT if the tuning tower model has bands of discrete values as is common with temperature towers. If SKIP=<value> is specified, the tuning process doesn't begin until Z height <value> is reached, and below that the value will be set to START ; in this case, the z_height used in the formulas below is actually max(z - skip, 0) . There are three possible combinations of options: FACTOR : The value changes at a rate of factor per millimeter. The formula used is: value = start + factor * z_height . You can plug the optimum Z height directly into the formula to determine the optimum parameter value. FACTOR and BAND : The value changes at an average rate of factor per millimeter, but in discrete bands where the adjustment will only be made every BAND millimeters of Z height. The formula used is: value = start + factor * ((floor(z_height / band) + .5) * band) . STEP_DELTA and STEP_HEIGHT : The value changes by STEP_DELTA every STEP_HEIGHT millimeters. The formula used is: value = start + step_delta * floor(z_height / step_height) . You can simply count bands or read tuning tower labels to determine the optimum value.","title":"TUNING_TOWER"},{"location":"G-Codes.html#virtual_sdcard","text":"Klipper supports the following standard G-Code commands if the virtual_sdcard config section is enabled: List SD card: M20 Initialize SD card: M21 Select SD file: M23 <filename> Start/resume SD print: M24 Pause SD print: M25 Set SD position: M26 S<offset> Report SD print status: M27 In addition, the following extended commands are available when the \"virtual_sdcard\" config section is enabled.","title":"[virtual_sdcard]"},{"location":"G-Codes.html#sdcard_print_file","text":"SDCARD_PRINT_FILE FILENAME=<filename> : Load a file and start SD print.","title":"SDCARD_PRINT_FILE"},{"location":"G-Codes.html#sdcard_reset_file","text":"SDCARD_RESET_FILE : Unload file and clear SD state.","title":"SDCARD_RESET_FILE"},{"location":"G-Codes.html#z_thermal_adjust","text":"The following commands are available when the z_thermal_adjust config section is enabled.","title":"[z_thermal_adjust]"},{"location":"G-Codes.html#set_z_thermal_adjust","text":"SET_Z_THERMAL_ADJUST [ENABLE=<0:1>] [TEMP_COEFF=<value>] [REF_TEMP=<value>] : Enable or disable the Z thermal adjustment with ENABLE . Disabling does not remove any adjustment already applied, but will freeze the current adjustment value - this prevents potentially unsafe downward Z movement. Re-enabling can potentially cause upward tool movement as the adjustment is updated and applied. TEMP_COEFF allows run-time tuning of the adjustment temperature coefficient (i.e. the TEMP_COEFF config parameter). TEMP_COEFF values are not saved to the config. REF_TEMP manually overrides the reference temperature typically set during homing (for use in e.g. non-standard homing routines) - will be reset automatically upon homing.","title":"SET_Z_THERMAL_ADJUST"},{"location":"G-Codes.html#z_tilt","text":"The following commands are available when the z_tilt config section is enabled.","title":"[z_tilt]"},{"location":"G-Codes.html#z_tilt_adjust","text":"Z_TILT_ADJUST [RETRIES=<value>] [RETRY_TOLERANCE=<value>] [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>] : This command will probe the points specified in the config and then make independent adjustments to each Z stepper to compensate for tilt. See the PROBE command for details on the optional probe parameters. The optional RETRIES , RETRY_TOLERANCE , and HORIZONTAL_MOVE_Z values override those options specified in the config file.","title":"Z_TILT_ADJUST"},{"location":"Hall_Filament_Width_Sensor.html","text":"Hall filament width sensor \u00b6 This document describes Filament Width Sensor host module. Hardware used for developing this host module is based on two Hall linear sensors (ss49e for example). Sensors in the body are located on opposite sides. Principle of operation: two hall sensors work in differential mode, temperature drift same for sensor. Special temperature compensation not needed. You can find designs at Thingiverse , an assembly video is also available on Youtube To use Hall filament width sensor, read Config Reference and G-Code documentation . How does it work? \u00b6 Sensor generates two analog output based on calculated filament width. Sum of output voltage always equals to detected filament width. Host module monitors voltage changes and adjusts extrusion multiplier. I use the aux2 connector on a ramps-like board with the analog11 and analog12 pins. You can use different pins and different boards. Template for menu variables \u00b6 [menu __main __filament __width_current] type: command enable: {'hall_filament_width_sensor' in printer} name: Dia: {'%.2F' % printer.hall_filament_width_sensor.Diameter} index: 0 [menu __main __filament __raw_width_current] type: command enable: {'hall_filament_width_sensor' in printer} name: Raw: {'%4.0F' % printer.hall_filament_width_sensor.Raw} index: 1 Calibration procedure \u00b6 To get raw sensor value you can use menu item or QUERY_RAW_FILAMENT_WIDTH command in terminal. Insert first calibration rod (1.5 mm size) get first raw sensor value Insert second calibration rod (2.0 mm size) get second raw sensor value Save raw sensor values in config parameter Raw_dia1 and Raw_dia2 How to enable sensor \u00b6 By default, the sensor is disabled at power-on. To enable the sensor, issue ENABLE_FILAMENT_WIDTH_SENSOR command or set the enable parameter to true . Logging \u00b6 By default, diameter logging is disabled at power-on. Issue ENABLE_FILAMENT_WIDTH_LOG command to start logging and issue DISABLE_FILAMENT_WIDTH_LOG command to stop logging. To enable logging at power-on, set the logging parameter to true . Filament diameter is logged on every measurement interval (10 mm by default).","title":"Hall filament width sensor"},{"location":"Hall_Filament_Width_Sensor.html#hall-filament-width-sensor","text":"This document describes Filament Width Sensor host module. Hardware used for developing this host module is based on two Hall linear sensors (ss49e for example). Sensors in the body are located on opposite sides. Principle of operation: two hall sensors work in differential mode, temperature drift same for sensor. Special temperature compensation not needed. You can find designs at Thingiverse , an assembly video is also available on Youtube To use Hall filament width sensor, read Config Reference and G-Code documentation .","title":"Hall filament width sensor"},{"location":"Hall_Filament_Width_Sensor.html#how-does-it-work","text":"Sensor generates two analog output based on calculated filament width. Sum of output voltage always equals to detected filament width. Host module monitors voltage changes and adjusts extrusion multiplier. I use the aux2 connector on a ramps-like board with the analog11 and analog12 pins. You can use different pins and different boards.","title":"How does it work?"},{"location":"Hall_Filament_Width_Sensor.html#template-for-menu-variables","text":"[menu __main __filament __width_current] type: command enable: {'hall_filament_width_sensor' in printer} name: Dia: {'%.2F' % printer.hall_filament_width_sensor.Diameter} index: 0 [menu __main __filament __raw_width_current] type: command enable: {'hall_filament_width_sensor' in printer} name: Raw: {'%4.0F' % printer.hall_filament_width_sensor.Raw} index: 1","title":"Template for menu variables"},{"location":"Hall_Filament_Width_Sensor.html#calibration-procedure","text":"To get raw sensor value you can use menu item or QUERY_RAW_FILAMENT_WIDTH command in terminal. Insert first calibration rod (1.5 mm size) get first raw sensor value Insert second calibration rod (2.0 mm size) get second raw sensor value Save raw sensor values in config parameter Raw_dia1 and Raw_dia2","title":"Calibration procedure"},{"location":"Hall_Filament_Width_Sensor.html#how-to-enable-sensor","text":"By default, the sensor is disabled at power-on. To enable the sensor, issue ENABLE_FILAMENT_WIDTH_SENSOR command or set the enable parameter to true .","title":"How to enable sensor"},{"location":"Hall_Filament_Width_Sensor.html#logging","text":"By default, diameter logging is disabled at power-on. Issue ENABLE_FILAMENT_WIDTH_LOG command to start logging and issue DISABLE_FILAMENT_WIDTH_LOG command to stop logging. To enable logging at power-on, set the logging parameter to true . Filament diameter is logged on every measurement interval (10 mm by default).","title":"Logging"},{"location":"Installation.html","text":"Installation \u00b6 These instructions assume the software will run on a Linux-based host running a Klipper-compatible front end. It is recommended that a SBC(Small Board Computer) such as a Raspberry Pi or Debian-based Linux device be used as the host machine (see the FAQ for other options). For the purposes of these instructions, host relates to the Linux device and mcu relates to the printer board. SBC relates to the term Small Board Computer such as the Raspberry Pi. Obtain a Klipper Configuration File \u00b6 Most Klipper settings are determined by a \"printer configuration file\" printer.cfg, that will be stored on the host. An appropriate configuration file can often be found by looking in the Klipper config directory for a file starting with a \"printer-\" prefix that corresponds to the target printer. The Klipper configuration file contains technical information about the printer that will be needed during the installation. If there isn't an appropriate printer configuration file in the Klipper config directory then try searching the printer manufacturer's website to see if they have an appropriate Klipper configuration file. If no configuration file for the printer can be found, but the type of printer control board is known, then look for an appropriate config file starting with a \"generic-\" prefix. These example printer board files should allow one to successfully complete the initial installation, but will require some customization to obtain full printer functionality. It is also possible to define a new printer configuration from scratch. However, this requires significant technical knowledge about the printer and its electronics. It is recommended that most users start with an appropriate configuration file. If creating a new custom printer configuration file, then start with the closest example config file and use the Klipper config reference for further information. Interacting with Klipper \u00b6 Klipper is a 3d printer firmware, so it needs some way for the user to interact with it. Currently the best choices are front ends that retrieve information through the Moonraker web API and there is also the option to use Octoprint to control Klipper. The choice is up to the user on what to use, but the underlying Klipper is the same in all cases. We encourage users to research the options available and make an informed decision. Obtaining an OS image for SBC's \u00b6 There are many ways to obtain an OS image for Klipper for SBC use, most depend on what front end you wish to use. Some manufacturers of these SBC boards also provide their own Klipper-centric images. The two main Moonraker-based front ends are Fluidd and Mainsail , the latter of which has a premade install image \"MainsailOS\" , this has the option for Raspberry Pi and some OrangePi variants. Fluidd can be installed via KIAUH(Klipper Install And Update Helper), which is explained below and is a 3rd party installer for all things Klipper. OctoPrint can be installed via the popular OctoPi image or via KIAUH, this process is explained in OctoPrint.md Installing via KIAUH \u00b6 Normally you would start with a base image for your SBC, RPiOS Lite for example, or in the case of an x86 Linux device, Ubuntu Server. Please note that Desktop variants are not recommended due to certain helper programs that can stop some Klipper functions from working and even mask access to some printer boards. KIAUH can be used to install Klipper and its associated programs on a variety of Linux-based systems that run a form of Debian. More information can be found at https://github.com/dw-0/kiauh Building and flashing the micro-controller \u00b6 To compile the micro-controller code, start by running these commands on your host device: cd ~/klipper/ make menuconfig The comments at the top of the printer configuration file should describe the settings that need to be set during \"make menuconfig\". Open the file in a web browser or text editor and look for these instructions near the top of the file. Once the appropriate \"menuconfig\" settings have been configured, press \"Q\" to exit, and then \"Y\" to save. Then run: make If the comments at the top of the printer configuration file describe custom steps for \"flashing\" the final image to the printer control board, then follow those steps and then proceed to configuring OctoPrint . Otherwise, the following steps are often used to \"flash\" the printer control board. First, it is necessary to determine the serial port connected to the micro-controller. Run the following: ls /dev/serial/by-id/* It should report something similar to the following: /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 It's common for each printer to have its own unique serial port name. This unique name will be used when flashing the micro-controller. It's possible there may be multiple lines in the above output - if so, choose the line corresponding to the micro-controller. If many items are listed and the choice is ambiguous, unplug the board and run the command again, the missing item will be your print board(see the FAQ for more information). For common micro-controllers with STM32 or clone chips, LPC chips and others, it is usual that these need an initial Klipper flash via SD card. When flashing with this method, it is important to make sure that the print board is not connected with USB to the host, due to some boards being able to feed power back to the board and stopping a flash from occurring. Please note, that most print boards that use SD cards for flash will implement some kind of flash loop protection for when the sd card is left in place. There are two common methods: Filename Change Required (usually \"stock\" print boards): These boards require the firmware file to have a different name each time you flash (for example, firmware1.bin, firmware2.bin, etc.). If you reuse the same filename, the board may ignore it and not update. Automatic File Renaming (usually aftermarket print boards: Other boards allow using the same filename, commonly firmware.bin, but after flashing, the board renames the file to firmware.cur. This helps indicate the firmware was successfully flashed and prevents it from flashing again on the next startup. Before flashing, make sure to check which behavior your board follows. For common micro-controllers using Atmega chips, for example the 2560, the code can be flashed with something similar to: sudo service klipper stop make flash FLASH_DEVICE=/dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 sudo service klipper start Be sure to update the FLASH_DEVICE with the printer's unique serial port name. For common micro-controllers using RP2040 chips, the code can be flashed with something similar to: sudo service klipper stop make flash FLASH_DEVICE=first sudo service klipper start It is important to note that RP2040 chips may need to be put into Boot mode before this operation. Configuring Klipper \u00b6 The next step is to copy the printer configuration file to the host. Arguably the easiest way to set the Klipper configuration file is using the built-in editors in Mainsail or Fluidd. These will allow the user to open the configuration examples and save them to be printer.cfg. Another option is to use a desktop editor that supports editing files over the \"scp\" and/or \"sftp\" protocols. There are freely available tools that support this (eg, Notepad++, WinSCP, and Cyberduck). Load the printer config file in the editor and then save it as a file named \"printer.cfg\" in the home directory of the pi user (ie, /home/pi/printer.cfg). Alternatively, one can also copy and edit the file directly on the host via SSH. That may look something like the following (be sure to update the command to use the appropriate printer config filename): cp ~/klipper/config/example-cartesian.cfg ~/printer.cfg nano ~/printer.cfg It's common for each printer to have its own unique name for the micro-controller. The name may change after flashing Klipper, so rerun these steps again even if they were already done when flashing. Run: ls /dev/serial/by-id/* It should report something similar to the following: /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 Then update the config file with the unique name. For example, update the [mcu] section to look something similar to: [mcu] serial: /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 After creating and editing the file, it will be necessary to issue a \"restart\" command in the command console to load the config. A \"status\" command will report that the printer is ready if the Klipper config file is successfully read and the micro-controller is successfully found and configured. When customizing the printer config file, it is not uncommon for Klipper to report a configuration error. If an error occurs, make any necessary corrections to the printer config file and issue \"restart\" until \"status\" reports the printer is ready. Klipper reports error messages via the command console and pop-ups in Fluidd and Mainsail. The \"status\" command can be used to re-report error messages. A log is available and usually located at ~/printer_data/logs/klippy.log . After Klipper reports that the printer is ready, proceed to the config check document to perform some basic checks on the definitions in the config file. See the main documentation reference for other information.","title":"Installation"},{"location":"Installation.html#installation","text":"These instructions assume the software will run on a Linux-based host running a Klipper-compatible front end. It is recommended that a SBC(Small Board Computer) such as a Raspberry Pi or Debian-based Linux device be used as the host machine (see the FAQ for other options). For the purposes of these instructions, host relates to the Linux device and mcu relates to the printer board. SBC relates to the term Small Board Computer such as the Raspberry Pi.","title":"Installation"},{"location":"Installation.html#obtain-a-klipper-configuration-file","text":"Most Klipper settings are determined by a \"printer configuration file\" printer.cfg, that will be stored on the host. An appropriate configuration file can often be found by looking in the Klipper config directory for a file starting with a \"printer-\" prefix that corresponds to the target printer. The Klipper configuration file contains technical information about the printer that will be needed during the installation. If there isn't an appropriate printer configuration file in the Klipper config directory then try searching the printer manufacturer's website to see if they have an appropriate Klipper configuration file. If no configuration file for the printer can be found, but the type of printer control board is known, then look for an appropriate config file starting with a \"generic-\" prefix. These example printer board files should allow one to successfully complete the initial installation, but will require some customization to obtain full printer functionality. It is also possible to define a new printer configuration from scratch. However, this requires significant technical knowledge about the printer and its electronics. It is recommended that most users start with an appropriate configuration file. If creating a new custom printer configuration file, then start with the closest example config file and use the Klipper config reference for further information.","title":"Obtain a Klipper Configuration File"},{"location":"Installation.html#interacting-with-klipper","text":"Klipper is a 3d printer firmware, so it needs some way for the user to interact with it. Currently the best choices are front ends that retrieve information through the Moonraker web API and there is also the option to use Octoprint to control Klipper. The choice is up to the user on what to use, but the underlying Klipper is the same in all cases. We encourage users to research the options available and make an informed decision.","title":"Interacting with Klipper"},{"location":"Installation.html#obtaining-an-os-image-for-sbcs","text":"There are many ways to obtain an OS image for Klipper for SBC use, most depend on what front end you wish to use. Some manufacturers of these SBC boards also provide their own Klipper-centric images. The two main Moonraker-based front ends are Fluidd and Mainsail , the latter of which has a premade install image \"MainsailOS\" , this has the option for Raspberry Pi and some OrangePi variants. Fluidd can be installed via KIAUH(Klipper Install And Update Helper), which is explained below and is a 3rd party installer for all things Klipper. OctoPrint can be installed via the popular OctoPi image or via KIAUH, this process is explained in OctoPrint.md","title":"Obtaining an OS image for SBC's"},{"location":"Installation.html#installing-via-kiauh","text":"Normally you would start with a base image for your SBC, RPiOS Lite for example, or in the case of an x86 Linux device, Ubuntu Server. Please note that Desktop variants are not recommended due to certain helper programs that can stop some Klipper functions from working and even mask access to some printer boards. KIAUH can be used to install Klipper and its associated programs on a variety of Linux-based systems that run a form of Debian. More information can be found at https://github.com/dw-0/kiauh","title":"Installing via KIAUH"},{"location":"Installation.html#building-and-flashing-the-micro-controller","text":"To compile the micro-controller code, start by running these commands on your host device: cd ~/klipper/ make menuconfig The comments at the top of the printer configuration file should describe the settings that need to be set during \"make menuconfig\". Open the file in a web browser or text editor and look for these instructions near the top of the file. Once the appropriate \"menuconfig\" settings have been configured, press \"Q\" to exit, and then \"Y\" to save. Then run: make If the comments at the top of the printer configuration file describe custom steps for \"flashing\" the final image to the printer control board, then follow those steps and then proceed to configuring OctoPrint . Otherwise, the following steps are often used to \"flash\" the printer control board. First, it is necessary to determine the serial port connected to the micro-controller. Run the following: ls /dev/serial/by-id/* It should report something similar to the following: /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 It's common for each printer to have its own unique serial port name. This unique name will be used when flashing the micro-controller. It's possible there may be multiple lines in the above output - if so, choose the line corresponding to the micro-controller. If many items are listed and the choice is ambiguous, unplug the board and run the command again, the missing item will be your print board(see the FAQ for more information). For common micro-controllers with STM32 or clone chips, LPC chips and others, it is usual that these need an initial Klipper flash via SD card. When flashing with this method, it is important to make sure that the print board is not connected with USB to the host, due to some boards being able to feed power back to the board and stopping a flash from occurring. Please note, that most print boards that use SD cards for flash will implement some kind of flash loop protection for when the sd card is left in place. There are two common methods: Filename Change Required (usually \"stock\" print boards): These boards require the firmware file to have a different name each time you flash (for example, firmware1.bin, firmware2.bin, etc.). If you reuse the same filename, the board may ignore it and not update. Automatic File Renaming (usually aftermarket print boards: Other boards allow using the same filename, commonly firmware.bin, but after flashing, the board renames the file to firmware.cur. This helps indicate the firmware was successfully flashed and prevents it from flashing again on the next startup. Before flashing, make sure to check which behavior your board follows. For common micro-controllers using Atmega chips, for example the 2560, the code can be flashed with something similar to: sudo service klipper stop make flash FLASH_DEVICE=/dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 sudo service klipper start Be sure to update the FLASH_DEVICE with the printer's unique serial port name. For common micro-controllers using RP2040 chips, the code can be flashed with something similar to: sudo service klipper stop make flash FLASH_DEVICE=first sudo service klipper start It is important to note that RP2040 chips may need to be put into Boot mode before this operation.","title":"Building and flashing the micro-controller"},{"location":"Installation.html#configuring-klipper","text":"The next step is to copy the printer configuration file to the host. Arguably the easiest way to set the Klipper configuration file is using the built-in editors in Mainsail or Fluidd. These will allow the user to open the configuration examples and save them to be printer.cfg. Another option is to use a desktop editor that supports editing files over the \"scp\" and/or \"sftp\" protocols. There are freely available tools that support this (eg, Notepad++, WinSCP, and Cyberduck). Load the printer config file in the editor and then save it as a file named \"printer.cfg\" in the home directory of the pi user (ie, /home/pi/printer.cfg). Alternatively, one can also copy and edit the file directly on the host via SSH. That may look something like the following (be sure to update the command to use the appropriate printer config filename): cp ~/klipper/config/example-cartesian.cfg ~/printer.cfg nano ~/printer.cfg It's common for each printer to have its own unique name for the micro-controller. The name may change after flashing Klipper, so rerun these steps again even if they were already done when flashing. Run: ls /dev/serial/by-id/* It should report something similar to the following: /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 Then update the config file with the unique name. For example, update the [mcu] section to look something similar to: [mcu] serial: /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 After creating and editing the file, it will be necessary to issue a \"restart\" command in the command console to load the config. A \"status\" command will report that the printer is ready if the Klipper config file is successfully read and the micro-controller is successfully found and configured. When customizing the printer config file, it is not uncommon for Klipper to report a configuration error. If an error occurs, make any necessary corrections to the printer config file and issue \"restart\" until \"status\" reports the printer is ready. Klipper reports error messages via the command console and pop-ups in Fluidd and Mainsail. The \"status\" command can be used to re-report error messages. A log is available and usually located at ~/printer_data/logs/klippy.log . After Klipper reports that the printer is ready, proceed to the config check document to perform some basic checks on the definitions in the config file. See the main documentation reference for other information.","title":"Configuring Klipper"},{"location":"Kinematics.html","text":"Kinematics \u00b6 This document provides an overview of how Klipper implements robot motion (its kinematics ). The contents may be of interest to both developers interested in working on the Klipper software as well as users interested in better understanding the mechanics of their machines. Acceleration \u00b6 Klipper implements a constant acceleration scheme whenever the print head changes velocity - the velocity is gradually changed to the new speed instead of suddenly jerking to it. Klipper always enforces acceleration between the tool head and the print. The filament leaving the extruder can be quite fragile - rapid jerks and/or extruder flow changes lead to poor quality and poor bed adhesion. Even when not extruding, if the print head is at the same level as the print then rapid jerking of the head can cause disruption of recently deposited filament. Limiting speed changes of the print head (relative to the print) reduces risks of disrupting the print. It is also important to limit acceleration so that the stepper motors do not skip or put excessive stress on the machine. Klipper limits the torque on each stepper by virtue of limiting the acceleration of the print head. Enforcing acceleration at the print head naturally also limits the torque of the steppers that move the print head (the inverse is not always true). Klipper implements constant acceleration. The key formula for constant acceleration is: velocity(time) = start_velocity + accel*time Trapezoid generator \u00b6 Klipper uses a traditional \"trapezoid generator\" to model the motion of each move - each move has a start speed, it accelerates to a cruising speed at constant acceleration, it cruises at a constant speed, and then decelerates to the end speed using constant acceleration. It's called a \"trapezoid generator\" because a velocity diagram of the move looks like a trapezoid. The cruising speed is always greater than or equal to both the start speed and the end speed. The acceleration phase may be of zero duration (if the start speed is equal to the cruising speed), the cruising phase may be of zero duration (if the move immediately starts decelerating after acceleration), and/or the deceleration phase may be of zero duration (if the end speed is equal to the cruising speed). Look-ahead \u00b6 The \"look-ahead\" system is used to determine cornering speeds between moves. Consider the following two moves contained on an XY plane: In the above situation it is possible to fully decelerate after the first move and then fully accelerate at the start of the next move, but that is not ideal as all that acceleration and deceleration would greatly increase the print time and the frequent changes in extruder flow would result in poor print quality. To solve this, the \"look-ahead\" mechanism queues multiple incoming moves and analyzes the angles between moves to determine a reasonable speed that can be obtained during the \"junction\" between two moves. If the next move is nearly in the same direction then the head need only slow down a little (if at all). However, if the next move forms an acute angle (the head is going to travel in nearly a reverse direction on the next move) then only a small junction speed is permitted. The junction speeds are determined using \"approximated centripetal acceleration\". Best described by the author . However, in Klipper, junction speeds are configured by specifying the desired speed that a 90\u00b0 corner should have (the \"square corner velocity\"), and the junction speeds for other angles are derived from that. Key formula for look-ahead: end_velocity^2 = start_velocity^2 + 2*accel*move_distance Minimum cruise ratio \u00b6 Klipper also implements a mechanism for smoothing out the motions of short \"zigzag\" moves. Consider the following moves: In the above, the frequent changes from acceleration to deceleration can cause the machine to vibrate which causes stress on the machine and increases the noise. Klipper implements a mechanism to ensure there is always some movement at a cruising speed between acceleration and deceleration. This is done by reducing the top speed of some moves (or sequence of moves) to ensure there is a minimum distance traveled at cruising speed relative to the distance traveled during acceleration and deceleration. Klipper implements this feature by tracking both a regular move acceleration as well as a virtual \"acceleration to deceleration\" rate: Specifically, the code calculates what the velocity of each move would be if it were limited to this virtual \"acceleration to deceleration\" rate. In the above picture the dashed gray lines represent this virtual acceleration rate for the first move. If a move can not reach its full cruising speed using this virtual acceleration rate then its top speed is reduced to the maximum speed it could obtain at this virtual acceleration rate. For most moves the limit will be at or above the move's existing limits and no change in behavior is induced. For short zigzag moves, however, this limit reduces the top speed. Note that it does not change the actual acceleration within the move - the move continues to use the normal acceleration scheme up to its adjusted top-speed. Generating steps \u00b6 Once the look-ahead process completes, the print head movement for the given move is fully known (time, start position, end position, velocity at each point) and it is possible to generate the step times for the move. This process is done within \"kinematic classes\" in the Klipper code. Outside of these kinematic classes, everything is tracked in millimeters, seconds, and in cartesian coordinate space. It's the task of the kinematic classes to convert from this generic coordinate system to the hardware specifics of the particular printer. Klipper uses an iterative solver to generate the step times for each stepper. The code contains the formulas to calculate the ideal cartesian coordinates of the head at each moment in time, and it has the kinematic formulas to calculate the ideal stepper positions based on those cartesian coordinates. With these formulas, Klipper can determine the ideal time that the stepper should be at each step position. The given steps are then scheduled at these calculated times. The key formula to determine how far a move should travel under constant acceleration is: move_distance = (start_velocity + .5 * accel * move_time) * move_time and the key formula for movement with constant velocity is: move_distance = cruise_velocity * move_time The key formulas for determining the cartesian coordinate of a move given a move distance is: cartesian_x_position = start_x + move_distance * total_x_movement / total_movement cartesian_y_position = start_y + move_distance * total_y_movement / total_movement cartesian_z_position = start_z + move_distance * total_z_movement / total_movement Cartesian Robots \u00b6 Generating steps for cartesian printers is the simplest case. The movement on each axis is directly related to the movement in cartesian space. Key formulas: stepper_x_position = cartesian_x_position stepper_y_position = cartesian_y_position stepper_z_position = cartesian_z_position CoreXY Robots \u00b6 Generating steps on a CoreXY machine is only a little more complex than basic cartesian robots. The key formulas are: stepper_a_position = cartesian_x_position + cartesian_y_position stepper_b_position = cartesian_x_position - cartesian_y_position stepper_z_position = cartesian_z_position Delta Robots \u00b6 Step generation on a delta robot is based on Pythagoras's theorem: stepper_position = (sqrt(arm_length^2 - (cartesian_x_position - tower_x_position)^2 - (cartesian_y_position - tower_y_position)^2) + cartesian_z_position) Stepper motor acceleration limits \u00b6 With delta kinematics it is possible for a move that is accelerating in cartesian space to require an acceleration on a particular stepper motor greater than the move's acceleration. This can occur when a stepper arm is more horizontal than vertical and the line of movement passes near that stepper's tower. Although these moves could require a stepper motor acceleration greater than the printer's maximum configured move acceleration, the effective mass moved by that stepper would be smaller. Thus the higher stepper acceleration does not result in significantly higher stepper torque and it is therefore considered harmless. However, to avoid extreme cases, Klipper enforces a maximum ceiling on stepper acceleration of three times the printer's configured maximum move acceleration. (Similarly, the maximum velocity of the stepper is limited to three times the maximum move velocity.) In order to enforce this limit, moves at the extreme edge of the build envelope (where a stepper arm may be nearly horizontal) will have a lower maximum acceleration and velocity. Extruder kinematics \u00b6 Klipper implements extruder motion in its own kinematic class. Since the timing and speed of each print head movement is fully known for each move, it's possible to calculate the step times for the extruder independently from the step time calculations of the print head movement. Basic extruder movement is simple to calculate. The step time generation uses the same formulas that cartesian robots use: stepper_position = requested_e_position Pressure advance \u00b6 Experimentation has shown that it's possible to improve the modeling of the extruder beyond the basic extruder formula. In the ideal case, as an extrusion move progresses, the same volume of filament should be deposited at each point along the move and there should be no volume extruded after the move. Unfortunately, it's common to find that the basic extrusion formulas cause too little filament to exit the extruder at the start of extrusion moves and for excess filament to extrude after extrusion ends. This is often referred to as \"ooze\". The \"pressure advance\" system attempts to account for this by using a different model for the extruder. Instead of naively believing that each mm^3 of filament fed into the extruder will result in that amount of mm^3 immediately exiting the extruder, it uses a model based on pressure. Pressure increases when filament is pushed into the extruder (as in Hooke's law ) and the pressure necessary to extrude is dominated by the flow rate through the nozzle orifice (as in Poiseuille's law ). The key idea is that the relationship between filament, pressure, and flow rate can be modeled using a linear coefficient: pa_position = nominal_position + pressure_advance_coefficient * nominal_velocity See the pressure advance document for information on how to find this pressure advance coefficient. The basic pressure advance formula can cause the extruder motor to make sudden velocity changes. Klipper implements \"smoothing\" of the extruder movement to avoid this. The above graph shows an example of two extrusion moves with a non-zero cornering velocity between them. Note that the pressure advance system causes additional filament to be pushed into the extruder during acceleration. The higher the desired filament flow rate, the more filament must be pushed in during acceleration to account for pressure. During head deceleration the extra filament is retracted (the extruder will have a negative velocity). The \"smoothing\" is implemented using a weighted average of the extruder position over a small time period (as specified by the pressure_advance_smooth_time config parameter). This averaging can span multiple g-code moves. Note how the extruder motor will start moving prior to the nominal start of the first extrusion move and will continue to move after the nominal end of the last extrusion move. Key formula for \"smoothed pressure advance\": smooth_pa_position(t) = ( definitive_integral(pa_position(x) * (smooth_time/2 - abs(t - x)) * dx, from=t-smooth_time/2, to=t+smooth_time/2) / (smooth_time/2)^2 )","title":"Kinematics"},{"location":"Kinematics.html#kinematics","text":"This document provides an overview of how Klipper implements robot motion (its kinematics ). The contents may be of interest to both developers interested in working on the Klipper software as well as users interested in better understanding the mechanics of their machines.","title":"Kinematics"},{"location":"Kinematics.html#acceleration","text":"Klipper implements a constant acceleration scheme whenever the print head changes velocity - the velocity is gradually changed to the new speed instead of suddenly jerking to it. Klipper always enforces acceleration between the tool head and the print. The filament leaving the extruder can be quite fragile - rapid jerks and/or extruder flow changes lead to poor quality and poor bed adhesion. Even when not extruding, if the print head is at the same level as the print then rapid jerking of the head can cause disruption of recently deposited filament. Limiting speed changes of the print head (relative to the print) reduces risks of disrupting the print. It is also important to limit acceleration so that the stepper motors do not skip or put excessive stress on the machine. Klipper limits the torque on each stepper by virtue of limiting the acceleration of the print head. Enforcing acceleration at the print head naturally also limits the torque of the steppers that move the print head (the inverse is not always true). Klipper implements constant acceleration. The key formula for constant acceleration is: velocity(time) = start_velocity + accel*time","title":"Acceleration"},{"location":"Kinematics.html#trapezoid-generator","text":"Klipper uses a traditional \"trapezoid generator\" to model the motion of each move - each move has a start speed, it accelerates to a cruising speed at constant acceleration, it cruises at a constant speed, and then decelerates to the end speed using constant acceleration. It's called a \"trapezoid generator\" because a velocity diagram of the move looks like a trapezoid. The cruising speed is always greater than or equal to both the start speed and the end speed. The acceleration phase may be of zero duration (if the start speed is equal to the cruising speed), the cruising phase may be of zero duration (if the move immediately starts decelerating after acceleration), and/or the deceleration phase may be of zero duration (if the end speed is equal to the cruising speed).","title":"Trapezoid generator"},{"location":"Kinematics.html#look-ahead","text":"The \"look-ahead\" system is used to determine cornering speeds between moves. Consider the following two moves contained on an XY plane: In the above situation it is possible to fully decelerate after the first move and then fully accelerate at the start of the next move, but that is not ideal as all that acceleration and deceleration would greatly increase the print time and the frequent changes in extruder flow would result in poor print quality. To solve this, the \"look-ahead\" mechanism queues multiple incoming moves and analyzes the angles between moves to determine a reasonable speed that can be obtained during the \"junction\" between two moves. If the next move is nearly in the same direction then the head need only slow down a little (if at all). However, if the next move forms an acute angle (the head is going to travel in nearly a reverse direction on the next move) then only a small junction speed is permitted. The junction speeds are determined using \"approximated centripetal acceleration\". Best described by the author . However, in Klipper, junction speeds are configured by specifying the desired speed that a 90\u00b0 corner should have (the \"square corner velocity\"), and the junction speeds for other angles are derived from that. Key formula for look-ahead: end_velocity^2 = start_velocity^2 + 2*accel*move_distance","title":"Look-ahead"},{"location":"Kinematics.html#minimum-cruise-ratio","text":"Klipper also implements a mechanism for smoothing out the motions of short \"zigzag\" moves. Consider the following moves: In the above, the frequent changes from acceleration to deceleration can cause the machine to vibrate which causes stress on the machine and increases the noise. Klipper implements a mechanism to ensure there is always some movement at a cruising speed between acceleration and deceleration. This is done by reducing the top speed of some moves (or sequence of moves) to ensure there is a minimum distance traveled at cruising speed relative to the distance traveled during acceleration and deceleration. Klipper implements this feature by tracking both a regular move acceleration as well as a virtual \"acceleration to deceleration\" rate: Specifically, the code calculates what the velocity of each move would be if it were limited to this virtual \"acceleration to deceleration\" rate. In the above picture the dashed gray lines represent this virtual acceleration rate for the first move. If a move can not reach its full cruising speed using this virtual acceleration rate then its top speed is reduced to the maximum speed it could obtain at this virtual acceleration rate. For most moves the limit will be at or above the move's existing limits and no change in behavior is induced. For short zigzag moves, however, this limit reduces the top speed. Note that it does not change the actual acceleration within the move - the move continues to use the normal acceleration scheme up to its adjusted top-speed.","title":"Minimum cruise ratio"},{"location":"Kinematics.html#generating-steps","text":"Once the look-ahead process completes, the print head movement for the given move is fully known (time, start position, end position, velocity at each point) and it is possible to generate the step times for the move. This process is done within \"kinematic classes\" in the Klipper code. Outside of these kinematic classes, everything is tracked in millimeters, seconds, and in cartesian coordinate space. It's the task of the kinematic classes to convert from this generic coordinate system to the hardware specifics of the particular printer. Klipper uses an iterative solver to generate the step times for each stepper. The code contains the formulas to calculate the ideal cartesian coordinates of the head at each moment in time, and it has the kinematic formulas to calculate the ideal stepper positions based on those cartesian coordinates. With these formulas, Klipper can determine the ideal time that the stepper should be at each step position. The given steps are then scheduled at these calculated times. The key formula to determine how far a move should travel under constant acceleration is: move_distance = (start_velocity + .5 * accel * move_time) * move_time and the key formula for movement with constant velocity is: move_distance = cruise_velocity * move_time The key formulas for determining the cartesian coordinate of a move given a move distance is: cartesian_x_position = start_x + move_distance * total_x_movement / total_movement cartesian_y_position = start_y + move_distance * total_y_movement / total_movement cartesian_z_position = start_z + move_distance * total_z_movement / total_movement","title":"Generating steps"},{"location":"Kinematics.html#cartesian-robots","text":"Generating steps for cartesian printers is the simplest case. The movement on each axis is directly related to the movement in cartesian space. Key formulas: stepper_x_position = cartesian_x_position stepper_y_position = cartesian_y_position stepper_z_position = cartesian_z_position","title":"Cartesian Robots"},{"location":"Kinematics.html#corexy-robots","text":"Generating steps on a CoreXY machine is only a little more complex than basic cartesian robots. The key formulas are: stepper_a_position = cartesian_x_position + cartesian_y_position stepper_b_position = cartesian_x_position - cartesian_y_position stepper_z_position = cartesian_z_position","title":"CoreXY Robots"},{"location":"Kinematics.html#delta-robots","text":"Step generation on a delta robot is based on Pythagoras's theorem: stepper_position = (sqrt(arm_length^2 - (cartesian_x_position - tower_x_position)^2 - (cartesian_y_position - tower_y_position)^2) + cartesian_z_position)","title":"Delta Robots"},{"location":"Kinematics.html#stepper-motor-acceleration-limits","text":"With delta kinematics it is possible for a move that is accelerating in cartesian space to require an acceleration on a particular stepper motor greater than the move's acceleration. This can occur when a stepper arm is more horizontal than vertical and the line of movement passes near that stepper's tower. Although these moves could require a stepper motor acceleration greater than the printer's maximum configured move acceleration, the effective mass moved by that stepper would be smaller. Thus the higher stepper acceleration does not result in significantly higher stepper torque and it is therefore considered harmless. However, to avoid extreme cases, Klipper enforces a maximum ceiling on stepper acceleration of three times the printer's configured maximum move acceleration. (Similarly, the maximum velocity of the stepper is limited to three times the maximum move velocity.) In order to enforce this limit, moves at the extreme edge of the build envelope (where a stepper arm may be nearly horizontal) will have a lower maximum acceleration and velocity.","title":"Stepper motor acceleration limits"},{"location":"Kinematics.html#extruder-kinematics","text":"Klipper implements extruder motion in its own kinematic class. Since the timing and speed of each print head movement is fully known for each move, it's possible to calculate the step times for the extruder independently from the step time calculations of the print head movement. Basic extruder movement is simple to calculate. The step time generation uses the same formulas that cartesian robots use: stepper_position = requested_e_position","title":"Extruder kinematics"},{"location":"Kinematics.html#pressure-advance","text":"Experimentation has shown that it's possible to improve the modeling of the extruder beyond the basic extruder formula. In the ideal case, as an extrusion move progresses, the same volume of filament should be deposited at each point along the move and there should be no volume extruded after the move. Unfortunately, it's common to find that the basic extrusion formulas cause too little filament to exit the extruder at the start of extrusion moves and for excess filament to extrude after extrusion ends. This is often referred to as \"ooze\". The \"pressure advance\" system attempts to account for this by using a different model for the extruder. Instead of naively believing that each mm^3 of filament fed into the extruder will result in that amount of mm^3 immediately exiting the extruder, it uses a model based on pressure. Pressure increases when filament is pushed into the extruder (as in Hooke's law ) and the pressure necessary to extrude is dominated by the flow rate through the nozzle orifice (as in Poiseuille's law ). The key idea is that the relationship between filament, pressure, and flow rate can be modeled using a linear coefficient: pa_position = nominal_position + pressure_advance_coefficient * nominal_velocity See the pressure advance document for information on how to find this pressure advance coefficient. The basic pressure advance formula can cause the extruder motor to make sudden velocity changes. Klipper implements \"smoothing\" of the extruder movement to avoid this. The above graph shows an example of two extrusion moves with a non-zero cornering velocity between them. Note that the pressure advance system causes additional filament to be pushed into the extruder during acceleration. The higher the desired filament flow rate, the more filament must be pushed in during acceleration to account for pressure. During head deceleration the extra filament is retracted (the extruder will have a negative velocity). The \"smoothing\" is implemented using a weighted average of the extruder position over a small time period (as specified by the pressure_advance_smooth_time config parameter). This averaging can span multiple g-code moves. Note how the extruder motor will start moving prior to the nominal start of the first extrusion move and will continue to move after the nominal end of the last extrusion move. Key formula for \"smoothed pressure advance\": smooth_pa_position(t) = ( definitive_integral(pa_position(x) * (smooth_time/2 - abs(t - x)) * dx, from=t-smooth_time/2, to=t+smooth_time/2) / (smooth_time/2)^2 )","title":"Pressure advance"},{"location":"Load_Cell.html","text":"Load Cells \u00b6 This document describes Klipper's support for load cells. Basic load cell functionality can be used to read force data and to weigh things like filament. A calibrated force sensor is an important part of a load cell based probe. Related Documentation \u00b6 load_cell Config Reference load_cell G-Code Commands load_cell Status Reference Using LOAD_CELL_DIAGNOSTIC \u00b6 When you first connect a load cell its good practice to check for issues by running LOAD_CELL_DIAGNOSTIC . This tool collects 10 seconds of data from the load cell and resport statistics: $ LOAD_CELL_DIAGNOSTIC // Collecting load cell data for 10 seconds... // Samples Collected: 3211 // Measured samples per second: 332.0 // Good samples: 3211, Saturated samples: 0, Unique values: 900 // Sample range: [4.01% to 4.02%] // Sample range / sensor capacity: 0.00524% Things you can check with this data: The configured sample rate of the sensor should be close to the 'Measured samples per second' value. If it is not you may have a configuration or wiring issue. 'Saturated samples' should be 0. If you have saturated samples it means the load sell is seeing more force than it can measure. 'Unique values' should be a large percentage of the 'Samples Collected' value. If 'Unique values' is 1 it is very likely a wiring issue. Tap or push on the sensor while LOAD_CELL_DIAGNOSTIC runs. If things are working correctly this should increase the 'Sample range'. Calibrating a Load Cell \u00b6 Load cells are calibrated using the LOAD_CELL_CALIBRATE command. This is an interactive calibration utility that walks you though a 3 step process: First use the TARE command to establish the zero force value. This is the reference_tare_counts config value. Next you apply a known load or force to the load cell and run the CALIBRATE GRAMS=nnn command. From this the counts_per_gram value is calculated. See the next section for some suggestions on how to do this. Finally, use the ACCEPT command to save the results. You can cancel the calibration process at any time with ABORT . Applying a Known Force or Load \u00b6 The CALIBRATE GRAMS=nnn step can be accomplished in a number of ways. If your load cell is under a platform like a bed or filament holder it might be easiest to put a known mass on the platform. E.g. you could use a couple of 1KG filament spools. If your load cell is in the printer's toolhead a different approach is easier. Put a digital scale on the printers bed and gently lower the toolhead onto the scale (or raise the bed into the toolhead if your bed moves). You may be able to do this using the FORCE_MOVE command. But more likely you will have to manually moving the z axis with the motors off until the toolhead presses on the scale. A good calibration force would ideally be a large percentage of the load cell's rated capacity. E.g. if you have a 5Kg load cell you would ideally calibrate it with a 5kg mass. This might work well with under-bed sensors that have to support a lot of weight. For toolhead probes this may not be a load that your printer bed or toolhead can tolerate without damage. Do try to use at least 1Kg of force, most printers should tolerate this without issue. When calibrating make careful note of the values reported: $ CALIBRATE GRAMS=555 // Calibration value: -2.78% (-59803108), Counts/gram: 73039.78739, Total capacity: +/- 29.14Kg The Total capacity should be close to the theoretical rating of the load cell based on the sensor's capacity. If it is much larger you could have used a higher gain setting in the sensor or a more sensitive load cell. This isn't as critical for 32bit and 24bit sensors but is much more critical for low bit width sensors. Reading Force Data \u00b6 Force data can be read with a GCode command: LOAD_CELL_READ // 10.6g (1.94%) Data is also continuously read and can be consumed from the load_cell printer object in a macro: {% set grams = printer.load_cell.force_g %} This provides an average force over the last 1 second, similar to how temperature sensors work. Taring a Load Cell \u00b6 Taring, sometimes called zeroing, sets the current weight reported by the load_cell to 0. This is useful for measuring relative to a known weight. e.g. when measuring a filament spool, using LOAD_CELL_TARE sets the weight to 0. Then as filament is printed the load_cell will report the weight of the filament used. LOAD_CELL_TARE // Load cell tare value: 5.32% (445903) The current tare value is reported in the printers status and can be read in a macro: {% set tare_counts = printer.load_cell.tare_counts %} Load Cell Probes \u00b6 Related Documentation \u00b6 load_cell_probe Config Reference load_cell_probe G-Code Commands load_cell_probe Statuc Reference Load Cell Probe Safety \u00b6 Because load cells are a direct nozzle contact probe there is a risk of damage to your printer if too much force is used. The load cell probing system includes a number of safety checks that try to keep your machine safe from excessive force to the toolhead. It's important to understand what they are and how they work as you can defeat most of them with poorly chosen config values. Calibration Check \u00b6 Every time a homing move starts, load_cell_probe checks that the load_cell is calibrated. If not it will stop the move with an error: !! Load Cell not calibrated . counts_per_gram \u00b6 This setting is used to convert raw sensor counts into grams. All the safety limits are in gram units for your convenience. If the counts_per_gram setting is not accurate you can easily exceed the safe force on the toolhead. You should never guess this value. Use LOAD_CELL_CALIBRATE to find your load cells actual counts_per_gram . trigger_force \u00b6 This is the force in grams that triggers the endstop to halt the homing move. When a homing move starts the endstop tares itself with the current reading from the load cell. trigger_force is measured from that tare value. There is always some overshoot of this value when the probe collides with the bed, so be conservative. e.g. a setting of 100g could result in 350g of peak force before the toolhead stops. This overshoot will increase with faster probing speed , a low ADC sample rate or multi MCU homing . reference_tare_counts \u00b6 This is the baseline tare value that is set by LOAD_CELL_CALIBRATE . This value works with force_safety_limit to limit the maximum force on the toolhead. force_safety_limit \u00b6 This is the maximum absolute force, relative to reference_tare_counts , that the probe will allow while homing or probing. If the MCU sees this force exceeded it will shut down the printer with the error !! Load cell endstop: too much force! . There are a number of ways this can be triggered: The first risk this protects against is picking too large of a value for drift_filter_cutoff_frequency . This can cause the drift filter to filter out a probe event and continue the homing move. If this happens the force_safety_limit acts as a backup protection. The second problem is probing repeatedly in one place. Klipper does not retract the probe when doing a single PROBE command. This can result in force applied to the toolhead at the end of a probing cycle. Because external forces can vary greatly between probing locations, load_cell_probe performs a tare before beginning each probe. If you repeat the PROBE command, load_cell_probe will tare the endstop at the current force. Multiple cycles of this will result in ever-increasing force on the toolhead. force_safety_limit stops this cycle from running out of control. Another way this run-away can happen is damage to a strain gauge. If the metal part is permanently bent it will change the reference_tare_counts of the device. This puts the starting tare value much closer to the limit making it more likely to be violated. You want to be notified if this is happening because your hardware has been permanently damaged. The final way this can be triggered is due to temperature changes. If your strain gauges are heated their reference_tare_counts may be very different at ambient temperature vs operating temperature. In this case you may need to increase the force_safety_limit to allow for thermal changes. Load Cell Endstop Watchdog Task \u00b6 When homing the load_cell_endstop starts a task on the MCU to trac measurements arriving from the sensor. If the sensor fails to send measurements for 2 sample periods the watchdog will shut down the printer with an error !! LoadCell Endstop timed out waiting on ADC data . If this happens, the most likely cause is a fault from the ADC. Inadequate grounding of your printer can be the root cause. The frame, power supply case and pint bed should all be connected to ground. You may need to ground the frame in multiple places. Anodized aluminum extrusions do not conduct electricity well. You might need to sand the area where the grounding wire is attached to make good electrical contact. Load Cell Probe Setup \u00b6 This section covers the process for commissioning a load cell probe. Verify the Load Cell First \u00b6 A [load_cell_probe] is also a [load_cell] and G-code commands related to [load_cell] work with [load_cell_probe] . Before attempting to use a load cell probe, follow the directions for calibrating the load cell with CALIBRATE_LOAD_CELL and checking its operation with LOAD_CELL_DIAGNOSTIC . Verify Probe Operation With LOAD_CELL_TEST_TAP \u00b6 Use the command LOAD_CELL_TEST_TAP to test the operation of the load cell probe before actually trying to probe with it. This command detects taps, just like the PROBE command, but it does not move the z axis. By default, it listens for 3 taps before ending the test. You have 30 seconds to do each tap, if no taps are detected the command will time out. If this test fails, check your configuration and LOAD_CELL_DIAGNOSTIC carefully to look for issues. Load cell probes don't support the QUERY_ENDSTOPS or QUERY_PROBE commands. Use LOAD_CELL_TEST_TAP for testing functionality before probing. Homing Macros \u00b6 Load cell probe is not an endstop and doesn't support endstop: prove:z_virtual_endstop . For the time being you'll need to configure your z axis with an MCU pin as its endstop. You won't actually be using the pin but for the time being you have to configure something. To home the axis with just the probe you need to set up a custom homing macro. This requires setting up homing_override . Here is a simple macro that can accomplish this. Note that the _HOME_Z_FROM_LAST_PROBE macro has to be separate because of the way macros work. The sub-call is needed so that the _HOME_Z_FROM_LAST_PROBE macro can see the result of the probe in printer.probe.last_z_result . [gcode_macro _HOME_Z_FROM_LAST_PROBE] gcode: {% set z_probed = printer.probe.last_z_result %} {% set z_position = printer.toolhead.position[2] %} {% set z_actual = z_position - z_probed %} SET_KINEMATIC_POSITION Z={z_actual} [gcode_macro _HOME_Z] gcode: SET_GCODE_OFFSET Z=0 # load cell probes dont need a Z offset # position toolhead for homing Z, edit for your printers size #G90 # absolute move #G1 Y50 X50 F{5 * 60} # move to X/Y position for homing # soft home the z axis to its limit so it can be moved: SET_KINEMATIC_POSITION Z={printer.toolhead.axis_maximum[2]} # Fast approach and tap PROBE PROBE_SPEED={5 * 60} # override the speed for faster homing _HOME_Z_FROM_LAST_PROBE # lift z to 2mm G91 # relative move G1 Z2 F{5 * 60} # probe at standard speed PROBE _HOME_Z_FROM_LAST_PROBE # lift z to 10mm for clearance G91 # relative move G1 Z10 F{5 * 60} Suggested Probing Temperature \u00b6 Currently, we suggest keeping the nozzle temperature below the level that causes the filament to ooze while homing and probing. 140C is a good starting point. This temperature is also low enough not to scar PEI build surfaces. Fouling of the nozzle and the print bed due to oozing filament is the #1 source of probing error with the load cell probe. Klipper does not yet have a universal way to detect poor quality taps due to filament ooze. The existing code may decide that a tap is valid when it is of poor quality. Classifying these poor quality taps is an area of active research. Klipper also lacks support for re-locating a probe point if the location has become fouled by filament ooze. Modules like quad_gantry_level will repeatedly probe the same coordinates even if a probe previously failed there. Give the above it is strongly suggested not to probe at printing temperatures. Hot Nozzle Protection \u00b6 The Voron project has a great macro for protecting your print surface from the hot nozzle. See Voron Tap's activate_gcode It is highly suggested to add something like this to your config. Nozzle Cleaning \u00b6 Before probing the nozzle should be clean. You could do this manually before every print. You can also implement a nozzle scrubber and automate the process. Here is a suggested sequence: Wait for the nozzle to heat up to probing temp (e.g. M109 S140 ) Home the machine ( G28 ) Scrub the nozzle on a brush Heat soak the print bed Perform probing tasks: QGL, bed mesh etc. Temperature Compensation for Nozzle Growth \u00b6 If you are probing at a safe temperature, the nozzle will expand after heating to printing temperatures. This will cause the nozzle to get longer and closer to the print surface. You can compensate for this with [z_thermal_adjust] . This adjustment will work across a range of printing temperatures from PLA to PC. Calculating the temp_coeff for [z_thermal_adjust] \u00b6 The easiest way to do this is to measure at 2 different temperatures. Ideally these should be the upper and lower limits of the printing temperature range. E.g. 180C and 290C. You can perform a PROBE_ACCURACY at both temperatures and then calculate the difference of the average z at both. The adjustment value is the change in nozzle length divided by the change in temperature. e.g. temp_coeff = -0.05 / (290 - 180) = -0.00045455 The expected result is a negative number. Positive values for temp_coeff move the nozzle closer to the bed and negative values move it further away. Expect to have to move the nozzle further away as it gets longer when hot. Configure [z_thermal_adjust] \u00b6 Set up z_thermal_adjust to reference the extruder as the source of temperature data. E.g.: [z_thermal_adjust nozzle] temp_coeff=-0.00045455 sensor_type: temperature_combined sensor_list: extruder combination_method: max min_temp: 0 max_temp: 400 max_z_adjustment: 0.1 Continuous Tare Filters for Toolhead Load Cells \u00b6 Klipper implements a configurable IIR filter on the MCU to provide continuous tareing of the load cell while probing. Continuous taring means the 0 value moves with drift caused by external factors like bowden tubes and thermal changes. This is aimed at toolhead sensors and moving beds that experience lots of external forces that change while probing. Installing SciPy \u00b6 The filtering code uses the excellent SciPy library to compute the filter coefficients based on the values your enter into the config. Pre-compiled SciPi builds are available for Python 3 on 32 bit Raspberry Pi systems. 32 bit + Python 3 is strongly recommended because it will streamline your installation experience. It does work with Python 2 but installation can take 30+ minutes and require installing additional tools. ~/klippy-env/bin/pip install scipy Filter Workbench \u00b6 The filter parameters should be selected based on drift seen on the printer during normal operation. A Jupyter notebook is provided in scripts, filter_workbench.ipynb , to perform a detailed investigation with real captured data and FFTs. Filtering Suggestions \u00b6 For those just trying to get a filter working follow these suggestions: The only essential option is drift_filter_cutoff_frequency . A conservative starting value is 0.5 Hz. Prusa shipped the MK4 with a setting of 0.8 Hz and the XL with 11.2 Hz. This is probably a safe range to experiment with. This value should be increased only until normal drift due to bowden tube force is eliminated. Setting this value too high will result in slow triggering and excess force going through the toolhead. Keep trigger_force low. The default is 75 g. The drift filter keeps the internal grams value very close to 0 so a large trigger force is not needed. Keep force_safety_limit to a conservative value. The default value is 2Kg and should keep your toolhead safe while experimenting. If you hit this limit the drift_filter_cutoff_frequency value may be too high. Suggestions for Load Cell Tool Boards \u00b6 This section covers suggestions for those developing toolhead boards that want to support [load_cell_probe] ADC Sensor Selection & Board Development Hints \u00b6 Ideally a sensor would meet these criteria: At least 24 bits wide Use SPI communications Has a pin can be used to indicate sample ready without SPI communications. This is often called the \"data ready\" or \"DRDY\" pin. Checking a pin is much faster than running an SPI query. Has a programmable gain amplifier gain setting of 128. This should eliminate the need for a separate amplifier. Indicates via SPI if the sensor has been reset. Detecting resets avoids timing errors in homing and using noisy data at startup. It can also help users track down wiring and grounding issues. A selectable sample rate between 350Hz and 2Khz. Very high sample rates don't turn out to be beneficial in our 3D printers because they produce so much noise when moving fast. Sample rates below 250Hz will require slower probing speeds. They also increase the force on the toolhead due to longer delays between measurements. E.g. a 500Hz sensor moving at 5mm/s has the same safety factor as a 100Hz sensor moving at only 1mm/s. If designing for under-bed applications, and you want to sense multiple load cells, use a chip that can sample all of its inputs simultaneously. Multiplex ADCs that require switching channels have a settling of several samples after each channel switch making them unsuitable for probing applications. Implementing support for a new sensor chip is not particularly difficult with Klipper's bulk_sensor and load_cell_endstop infrastructure. 5V Power Filtering \u00b6 It is strongly suggested to use larger capacitors than specified by the ADC chip manufacturer. ADC chips are usually targeted at low noise environments, like battery powered devices. Sensor manufacturers suggested application notes generally assume a quiet power supply. Treat their suggested capacitor values as minimums. 3D printers put huge amounts of noise onto the 5V bus and this can ruin the sensor's accuracy. Test the sensor on the board with a typical 3D printer power supply and active stepper drivers before deciding on smoothing capacitor sizes. Grounding & Ground Planes \u00b6 Analog ADC chips contain components that are very vulnerable to noise and ESD. A large ground plane on the first board layer under the chip can help with noise. Keep the chip away from power sections and DC to DC converters. The board should have proper grounding back to the DC supply. HX711 and HX717 Notes \u00b6 This sensor is popular because of its low cost and availability in the supply chain. However, this is a sensor with some drawbacks: The HX71x sensors use bit-bang communication which has a high overhead on the MCU. Using a sensor that communicates via SPI would save resources on the tool board's CPU. The HX71x lacks a way to communicate reset events to the MCU. Klipper detects resets with a timing heuristic but this is not ideal. Resets indicate a problem with wiring or grounding. For probing applications the HX717 version is strongly preferred because of its higher sample rate (320 vs 80). Probing speed on the HX711 should be limited to less than 2mm/s. The sample rate on the HX71x cannot be set from klipper's config. If you have the 10SPS version of the sensor (which is widely distributed) it needs to be physically re-wired to run at 80SPS.","title":"Load Cells"},{"location":"Load_Cell.html#load-cells","text":"This document describes Klipper's support for load cells. Basic load cell functionality can be used to read force data and to weigh things like filament. A calibrated force sensor is an important part of a load cell based probe.","title":"Load Cells"},{"location":"Load_Cell.html#related-documentation","text":"load_cell Config Reference load_cell G-Code Commands load_cell Status Reference","title":"Related Documentation"},{"location":"Load_Cell.html#using-load_cell_diagnostic","text":"When you first connect a load cell its good practice to check for issues by running LOAD_CELL_DIAGNOSTIC . This tool collects 10 seconds of data from the load cell and resport statistics: $ LOAD_CELL_DIAGNOSTIC // Collecting load cell data for 10 seconds... // Samples Collected: 3211 // Measured samples per second: 332.0 // Good samples: 3211, Saturated samples: 0, Unique values: 900 // Sample range: [4.01% to 4.02%] // Sample range / sensor capacity: 0.00524% Things you can check with this data: The configured sample rate of the sensor should be close to the 'Measured samples per second' value. If it is not you may have a configuration or wiring issue. 'Saturated samples' should be 0. If you have saturated samples it means the load sell is seeing more force than it can measure. 'Unique values' should be a large percentage of the 'Samples Collected' value. If 'Unique values' is 1 it is very likely a wiring issue. Tap or push on the sensor while LOAD_CELL_DIAGNOSTIC runs. If things are working correctly this should increase the 'Sample range'.","title":"Using LOAD_CELL_DIAGNOSTIC"},{"location":"Load_Cell.html#calibrating-a-load-cell","text":"Load cells are calibrated using the LOAD_CELL_CALIBRATE command. This is an interactive calibration utility that walks you though a 3 step process: First use the TARE command to establish the zero force value. This is the reference_tare_counts config value. Next you apply a known load or force to the load cell and run the CALIBRATE GRAMS=nnn command. From this the counts_per_gram value is calculated. See the next section for some suggestions on how to do this. Finally, use the ACCEPT command to save the results. You can cancel the calibration process at any time with ABORT .","title":"Calibrating a Load Cell"},{"location":"Load_Cell.html#applying-a-known-force-or-load","text":"The CALIBRATE GRAMS=nnn step can be accomplished in a number of ways. If your load cell is under a platform like a bed or filament holder it might be easiest to put a known mass on the platform. E.g. you could use a couple of 1KG filament spools. If your load cell is in the printer's toolhead a different approach is easier. Put a digital scale on the printers bed and gently lower the toolhead onto the scale (or raise the bed into the toolhead if your bed moves). You may be able to do this using the FORCE_MOVE command. But more likely you will have to manually moving the z axis with the motors off until the toolhead presses on the scale. A good calibration force would ideally be a large percentage of the load cell's rated capacity. E.g. if you have a 5Kg load cell you would ideally calibrate it with a 5kg mass. This might work well with under-bed sensors that have to support a lot of weight. For toolhead probes this may not be a load that your printer bed or toolhead can tolerate without damage. Do try to use at least 1Kg of force, most printers should tolerate this without issue. When calibrating make careful note of the values reported: $ CALIBRATE GRAMS=555 // Calibration value: -2.78% (-59803108), Counts/gram: 73039.78739, Total capacity: +/- 29.14Kg The Total capacity should be close to the theoretical rating of the load cell based on the sensor's capacity. If it is much larger you could have used a higher gain setting in the sensor or a more sensitive load cell. This isn't as critical for 32bit and 24bit sensors but is much more critical for low bit width sensors.","title":"Applying a Known Force or Load"},{"location":"Load_Cell.html#reading-force-data","text":"Force data can be read with a GCode command: LOAD_CELL_READ // 10.6g (1.94%) Data is also continuously read and can be consumed from the load_cell printer object in a macro: {% set grams = printer.load_cell.force_g %} This provides an average force over the last 1 second, similar to how temperature sensors work.","title":"Reading Force Data"},{"location":"Load_Cell.html#taring-a-load-cell","text":"Taring, sometimes called zeroing, sets the current weight reported by the load_cell to 0. This is useful for measuring relative to a known weight. e.g. when measuring a filament spool, using LOAD_CELL_TARE sets the weight to 0. Then as filament is printed the load_cell will report the weight of the filament used. LOAD_CELL_TARE // Load cell tare value: 5.32% (445903) The current tare value is reported in the printers status and can be read in a macro: {% set tare_counts = printer.load_cell.tare_counts %}","title":"Taring a Load Cell"},{"location":"Load_Cell.html#load-cell-probes","text":"","title":"Load Cell Probes"},{"location":"Load_Cell.html#related-documentation_1","text":"load_cell_probe Config Reference load_cell_probe G-Code Commands load_cell_probe Statuc Reference","title":"Related Documentation"},{"location":"Load_Cell.html#load-cell-probe-safety","text":"Because load cells are a direct nozzle contact probe there is a risk of damage to your printer if too much force is used. The load cell probing system includes a number of safety checks that try to keep your machine safe from excessive force to the toolhead. It's important to understand what they are and how they work as you can defeat most of them with poorly chosen config values.","title":"Load Cell Probe Safety"},{"location":"Load_Cell.html#calibration-check","text":"Every time a homing move starts, load_cell_probe checks that the load_cell is calibrated. If not it will stop the move with an error: !! Load Cell not calibrated .","title":"Calibration Check"},{"location":"Load_Cell.html#counts_per_gram","text":"This setting is used to convert raw sensor counts into grams. All the safety limits are in gram units for your convenience. If the counts_per_gram setting is not accurate you can easily exceed the safe force on the toolhead. You should never guess this value. Use LOAD_CELL_CALIBRATE to find your load cells actual counts_per_gram .","title":"counts_per_gram"},{"location":"Load_Cell.html#trigger_force","text":"This is the force in grams that triggers the endstop to halt the homing move. When a homing move starts the endstop tares itself with the current reading from the load cell. trigger_force is measured from that tare value. There is always some overshoot of this value when the probe collides with the bed, so be conservative. e.g. a setting of 100g could result in 350g of peak force before the toolhead stops. This overshoot will increase with faster probing speed , a low ADC sample rate or multi MCU homing .","title":"trigger_force"},{"location":"Load_Cell.html#reference_tare_counts","text":"This is the baseline tare value that is set by LOAD_CELL_CALIBRATE . This value works with force_safety_limit to limit the maximum force on the toolhead.","title":"reference_tare_counts"},{"location":"Load_Cell.html#force_safety_limit","text":"This is the maximum absolute force, relative to reference_tare_counts , that the probe will allow while homing or probing. If the MCU sees this force exceeded it will shut down the printer with the error !! Load cell endstop: too much force! . There are a number of ways this can be triggered: The first risk this protects against is picking too large of a value for drift_filter_cutoff_frequency . This can cause the drift filter to filter out a probe event and continue the homing move. If this happens the force_safety_limit acts as a backup protection. The second problem is probing repeatedly in one place. Klipper does not retract the probe when doing a single PROBE command. This can result in force applied to the toolhead at the end of a probing cycle. Because external forces can vary greatly between probing locations, load_cell_probe performs a tare before beginning each probe. If you repeat the PROBE command, load_cell_probe will tare the endstop at the current force. Multiple cycles of this will result in ever-increasing force on the toolhead. force_safety_limit stops this cycle from running out of control. Another way this run-away can happen is damage to a strain gauge. If the metal part is permanently bent it will change the reference_tare_counts of the device. This puts the starting tare value much closer to the limit making it more likely to be violated. You want to be notified if this is happening because your hardware has been permanently damaged. The final way this can be triggered is due to temperature changes. If your strain gauges are heated their reference_tare_counts may be very different at ambient temperature vs operating temperature. In this case you may need to increase the force_safety_limit to allow for thermal changes.","title":"force_safety_limit"},{"location":"Load_Cell.html#load-cell-endstop-watchdog-task","text":"When homing the load_cell_endstop starts a task on the MCU to trac measurements arriving from the sensor. If the sensor fails to send measurements for 2 sample periods the watchdog will shut down the printer with an error !! LoadCell Endstop timed out waiting on ADC data . If this happens, the most likely cause is a fault from the ADC. Inadequate grounding of your printer can be the root cause. The frame, power supply case and pint bed should all be connected to ground. You may need to ground the frame in multiple places. Anodized aluminum extrusions do not conduct electricity well. You might need to sand the area where the grounding wire is attached to make good electrical contact.","title":"Load Cell Endstop Watchdog Task"},{"location":"Load_Cell.html#load-cell-probe-setup","text":"This section covers the process for commissioning a load cell probe.","title":"Load Cell Probe Setup"},{"location":"Load_Cell.html#verify-the-load-cell-first","text":"A [load_cell_probe] is also a [load_cell] and G-code commands related to [load_cell] work with [load_cell_probe] . Before attempting to use a load cell probe, follow the directions for calibrating the load cell with CALIBRATE_LOAD_CELL and checking its operation with LOAD_CELL_DIAGNOSTIC .","title":"Verify the Load Cell First"},{"location":"Load_Cell.html#verify-probe-operation-with-load_cell_test_tap","text":"Use the command LOAD_CELL_TEST_TAP to test the operation of the load cell probe before actually trying to probe with it. This command detects taps, just like the PROBE command, but it does not move the z axis. By default, it listens for 3 taps before ending the test. You have 30 seconds to do each tap, if no taps are detected the command will time out. If this test fails, check your configuration and LOAD_CELL_DIAGNOSTIC carefully to look for issues. Load cell probes don't support the QUERY_ENDSTOPS or QUERY_PROBE commands. Use LOAD_CELL_TEST_TAP for testing functionality before probing.","title":"Verify Probe Operation With LOAD_CELL_TEST_TAP"},{"location":"Load_Cell.html#homing-macros","text":"Load cell probe is not an endstop and doesn't support endstop: prove:z_virtual_endstop . For the time being you'll need to configure your z axis with an MCU pin as its endstop. You won't actually be using the pin but for the time being you have to configure something. To home the axis with just the probe you need to set up a custom homing macro. This requires setting up homing_override . Here is a simple macro that can accomplish this. Note that the _HOME_Z_FROM_LAST_PROBE macro has to be separate because of the way macros work. The sub-call is needed so that the _HOME_Z_FROM_LAST_PROBE macro can see the result of the probe in printer.probe.last_z_result . [gcode_macro _HOME_Z_FROM_LAST_PROBE] gcode: {% set z_probed = printer.probe.last_z_result %} {% set z_position = printer.toolhead.position[2] %} {% set z_actual = z_position - z_probed %} SET_KINEMATIC_POSITION Z={z_actual} [gcode_macro _HOME_Z] gcode: SET_GCODE_OFFSET Z=0 # load cell probes dont need a Z offset # position toolhead for homing Z, edit for your printers size #G90 # absolute move #G1 Y50 X50 F{5 * 60} # move to X/Y position for homing # soft home the z axis to its limit so it can be moved: SET_KINEMATIC_POSITION Z={printer.toolhead.axis_maximum[2]} # Fast approach and tap PROBE PROBE_SPEED={5 * 60} # override the speed for faster homing _HOME_Z_FROM_LAST_PROBE # lift z to 2mm G91 # relative move G1 Z2 F{5 * 60} # probe at standard speed PROBE _HOME_Z_FROM_LAST_PROBE # lift z to 10mm for clearance G91 # relative move G1 Z10 F{5 * 60}","title":"Homing Macros"},{"location":"Load_Cell.html#suggested-probing-temperature","text":"Currently, we suggest keeping the nozzle temperature below the level that causes the filament to ooze while homing and probing. 140C is a good starting point. This temperature is also low enough not to scar PEI build surfaces. Fouling of the nozzle and the print bed due to oozing filament is the #1 source of probing error with the load cell probe. Klipper does not yet have a universal way to detect poor quality taps due to filament ooze. The existing code may decide that a tap is valid when it is of poor quality. Classifying these poor quality taps is an area of active research. Klipper also lacks support for re-locating a probe point if the location has become fouled by filament ooze. Modules like quad_gantry_level will repeatedly probe the same coordinates even if a probe previously failed there. Give the above it is strongly suggested not to probe at printing temperatures.","title":"Suggested Probing Temperature"},{"location":"Load_Cell.html#hot-nozzle-protection","text":"The Voron project has a great macro for protecting your print surface from the hot nozzle. See Voron Tap's activate_gcode It is highly suggested to add something like this to your config.","title":"Hot Nozzle Protection"},{"location":"Load_Cell.html#nozzle-cleaning","text":"Before probing the nozzle should be clean. You could do this manually before every print. You can also implement a nozzle scrubber and automate the process. Here is a suggested sequence: Wait for the nozzle to heat up to probing temp (e.g. M109 S140 ) Home the machine ( G28 ) Scrub the nozzle on a brush Heat soak the print bed Perform probing tasks: QGL, bed mesh etc.","title":"Nozzle Cleaning"},{"location":"Load_Cell.html#temperature-compensation-for-nozzle-growth","text":"If you are probing at a safe temperature, the nozzle will expand after heating to printing temperatures. This will cause the nozzle to get longer and closer to the print surface. You can compensate for this with [z_thermal_adjust] . This adjustment will work across a range of printing temperatures from PLA to PC.","title":"Temperature Compensation for Nozzle Growth"},{"location":"Load_Cell.html#calculating-the-temp_coeff-for-z_thermal_adjust","text":"The easiest way to do this is to measure at 2 different temperatures. Ideally these should be the upper and lower limits of the printing temperature range. E.g. 180C and 290C. You can perform a PROBE_ACCURACY at both temperatures and then calculate the difference of the average z at both. The adjustment value is the change in nozzle length divided by the change in temperature. e.g. temp_coeff = -0.05 / (290 - 180) = -0.00045455 The expected result is a negative number. Positive values for temp_coeff move the nozzle closer to the bed and negative values move it further away. Expect to have to move the nozzle further away as it gets longer when hot.","title":"Calculating the temp_coeff for [z_thermal_adjust]"},{"location":"Load_Cell.html#configure-z_thermal_adjust","text":"Set up z_thermal_adjust to reference the extruder as the source of temperature data. E.g.: [z_thermal_adjust nozzle] temp_coeff=-0.00045455 sensor_type: temperature_combined sensor_list: extruder combination_method: max min_temp: 0 max_temp: 400 max_z_adjustment: 0.1","title":"Configure [z_thermal_adjust]"},{"location":"Load_Cell.html#continuous-tare-filters-for-toolhead-load-cells","text":"Klipper implements a configurable IIR filter on the MCU to provide continuous tareing of the load cell while probing. Continuous taring means the 0 value moves with drift caused by external factors like bowden tubes and thermal changes. This is aimed at toolhead sensors and moving beds that experience lots of external forces that change while probing.","title":"Continuous Tare Filters for Toolhead Load Cells"},{"location":"Load_Cell.html#installing-scipy","text":"The filtering code uses the excellent SciPy library to compute the filter coefficients based on the values your enter into the config. Pre-compiled SciPi builds are available for Python 3 on 32 bit Raspberry Pi systems. 32 bit + Python 3 is strongly recommended because it will streamline your installation experience. It does work with Python 2 but installation can take 30+ minutes and require installing additional tools. ~/klippy-env/bin/pip install scipy","title":"Installing SciPy"},{"location":"Load_Cell.html#filter-workbench","text":"The filter parameters should be selected based on drift seen on the printer during normal operation. A Jupyter notebook is provided in scripts, filter_workbench.ipynb , to perform a detailed investigation with real captured data and FFTs.","title":"Filter Workbench"},{"location":"Load_Cell.html#filtering-suggestions","text":"For those just trying to get a filter working follow these suggestions: The only essential option is drift_filter_cutoff_frequency . A conservative starting value is 0.5 Hz. Prusa shipped the MK4 with a setting of 0.8 Hz and the XL with 11.2 Hz. This is probably a safe range to experiment with. This value should be increased only until normal drift due to bowden tube force is eliminated. Setting this value too high will result in slow triggering and excess force going through the toolhead. Keep trigger_force low. The default is 75 g. The drift filter keeps the internal grams value very close to 0 so a large trigger force is not needed. Keep force_safety_limit to a conservative value. The default value is 2Kg and should keep your toolhead safe while experimenting. If you hit this limit the drift_filter_cutoff_frequency value may be too high.","title":"Filtering Suggestions"},{"location":"Load_Cell.html#suggestions-for-load-cell-tool-boards","text":"This section covers suggestions for those developing toolhead boards that want to support [load_cell_probe]","title":"Suggestions for Load Cell Tool Boards"},{"location":"Load_Cell.html#adc-sensor-selection-board-development-hints","text":"Ideally a sensor would meet these criteria: At least 24 bits wide Use SPI communications Has a pin can be used to indicate sample ready without SPI communications. This is often called the \"data ready\" or \"DRDY\" pin. Checking a pin is much faster than running an SPI query. Has a programmable gain amplifier gain setting of 128. This should eliminate the need for a separate amplifier. Indicates via SPI if the sensor has been reset. Detecting resets avoids timing errors in homing and using noisy data at startup. It can also help users track down wiring and grounding issues. A selectable sample rate between 350Hz and 2Khz. Very high sample rates don't turn out to be beneficial in our 3D printers because they produce so much noise when moving fast. Sample rates below 250Hz will require slower probing speeds. They also increase the force on the toolhead due to longer delays between measurements. E.g. a 500Hz sensor moving at 5mm/s has the same safety factor as a 100Hz sensor moving at only 1mm/s. If designing for under-bed applications, and you want to sense multiple load cells, use a chip that can sample all of its inputs simultaneously. Multiplex ADCs that require switching channels have a settling of several samples after each channel switch making them unsuitable for probing applications. Implementing support for a new sensor chip is not particularly difficult with Klipper's bulk_sensor and load_cell_endstop infrastructure.","title":"ADC Sensor Selection &amp; Board Development Hints"},{"location":"Load_Cell.html#5v-power-filtering","text":"It is strongly suggested to use larger capacitors than specified by the ADC chip manufacturer. ADC chips are usually targeted at low noise environments, like battery powered devices. Sensor manufacturers suggested application notes generally assume a quiet power supply. Treat their suggested capacitor values as minimums. 3D printers put huge amounts of noise onto the 5V bus and this can ruin the sensor's accuracy. Test the sensor on the board with a typical 3D printer power supply and active stepper drivers before deciding on smoothing capacitor sizes.","title":"5V Power Filtering"},{"location":"Load_Cell.html#grounding-ground-planes","text":"Analog ADC chips contain components that are very vulnerable to noise and ESD. A large ground plane on the first board layer under the chip can help with noise. Keep the chip away from power sections and DC to DC converters. The board should have proper grounding back to the DC supply.","title":"Grounding &amp; Ground Planes"},{"location":"Load_Cell.html#hx711-and-hx717-notes","text":"This sensor is popular because of its low cost and availability in the supply chain. However, this is a sensor with some drawbacks: The HX71x sensors use bit-bang communication which has a high overhead on the MCU. Using a sensor that communicates via SPI would save resources on the tool board's CPU. The HX71x lacks a way to communicate reset events to the MCU. Klipper detects resets with a timing heuristic but this is not ideal. Resets indicate a problem with wiring or grounding. For probing applications the HX717 version is strongly preferred because of its higher sample rate (320 vs 80). Probing speed on the HX711 should be limited to less than 2mm/s. The sample rate on the HX71x cannot be set from klipper's config. If you have the 10SPS version of the sensor (which is widely distributed) it needs to be physically re-wired to run at 80SPS.","title":"HX711 and HX717 Notes"},{"location":"MCU_Commands.html","text":"MCU commands \u00b6 This document provides information on the low-level micro-controller commands that are sent from the Klipper \"host\" software and processed by the Klipper micro-controller software. This document is not an authoritative reference for these commands, nor is it an exclusive list of all available commands. This document may be useful for developers interested in understanding the low-level micro-controller commands. See the protocol document for more information on the format of commands and their transmission. The commands here are described using their \"printf\" style syntax - for those unfamiliar with that format, just note that where a '%...' sequence is seen it should be replaced with an actual integer. For example, a description with \"count=%c\" could be replaced with the text \"count=10\". Note that parameters that are considered \"enumerations\" (see the above protocol document) take a string value which is automatically converted to an integer value for the micro-controller. This is common with parameters named \"pin\" (or that have a suffix of \"_pin\"). Startup Commands \u00b6 It may be necessary to take certain one-time actions to configure the micro-controller and its peripherals. This section lists common commands available for that purpose. Unlike most micro-controller commands, these commands run as soon as they are received and they do not require any particular setup. Common startup commands: set_digital_out pin=%u value=%c : This command immediately configures the given pin as a digital out GPIO and it sets it to either a low level (value=0) or a high level (value=1). This command may be useful for configuring the initial value of LEDs and for configuring the initial value of stepper driver micro-stepping pins. set_pwm_out pin=%u cycle_ticks=%u value=%hu : This command will immediately configure the given pin to use hardware based pulse-width-modulation (PWM) with the given number of cycle_ticks. The \"cycle_ticks\" is the number of MCU clock ticks each power on and power off cycle should last. A cycle_ticks value of 1 can be used to request the fastest possible cycle time. The \"value\" parameter is between 0 and 255 with 0 indicating a full off state and 255 indicating a full on state. This command may be useful for enabling CPU and nozzle cooling fans. Low-level micro-controller configuration \u00b6 Most commands in the micro-controller require an initial setup before they can be successfully invoked. This section provides an overview of the configuration process. This section and the following sections are likely only of interest to developers interested in the internal details of Klipper. When the host first connects to the micro-controller it always starts by obtaining a data dictionary (see protocol for more information). After the data dictionary is obtained the host will check if the micro-controller is in a \"configured\" state and configure it if not. Configuration involves the following phases: get_config : The host starts by checking if the micro-controller is already configured. The micro-controller responds to this command with a \"config\" response message. The micro-controller software always starts in an unconfigured state at power-on. It remains in this state until the host completes the configuration processes (by issuing a finalize_config command). If the micro-controller is already configured from a previous session (and is configured with the desired settings) then no further action is needed by the host and the configuration process ends successfully. allocate_oids count=%c : This command is issued to inform the micro-controller of the maximum number of object-ids (oid) that the host requires. It is only valid to issue this command once. An oid is an integer identifier allocated to each stepper, each endstop, and each schedulable gpio pin. The host determines in advance the number of oids it will require to operate the hardware and passes this to the micro-controller so that it may allocate sufficient memory to store a mapping from oid to internal object. config_XXX oid=%c ... : By convention any command starting with the \"config_\" prefix creates a new micro-controller object and assigns the given oid to it. For example, the config_digital_out command will configure the specified pin as a digital output GPIO and create an internal object that the host can use to schedule changes to the given GPIO. The oid parameter passed into the config command is selected by the host and must be between zero and the maximum count supplied in the allocate_oids command. The config commands may only be run when the micro-controller is not in a configured state (ie, prior to the host sending finalize_config) and after the allocate_oids command has been sent. finalize_config crc=%u : The finalize_config command transitions the micro-controller from an unconfigured state to a configured state. The crc parameter passed to the micro-controller is stored and provided back to the host in \"config\" response messages. By convention, the host takes a 32bit CRC of the configuration it will request and at the start of subsequent communication sessions it checks that the CRC stored in the micro-controller exactly matches its desired CRC. If the CRC does not match then the host knows the micro-controller has not been configured in the state desired by the host. Common micro-controller objects \u00b6 This section lists some commonly used config commands. config_digital_out oid=%c pin=%u value=%c default_value=%c max_duration=%u : This command creates an internal micro-controller object for the given GPIO 'pin'. The pin will be configured in digital output mode and set to an initial value as specified by 'value' (0 for low, 1 for high). Creating a digital_out object allows the host to schedule GPIO updates for the given pin at specified times (see the queue_digital_out command described below). Should the micro-controller software go into shutdown mode then all configured digital_out objects will be set to 'default_value'. The 'max_duration' parameter is used to implement a safety check - if it is non-zero then it is the maximum number of clock ticks that the host may set the given GPIO to a non-default value without further updates. For example, if the default_value is zero and the max_duration is 16000 then if the host sets the gpio to a value of one then it must schedule another update to the gpio pin (to either zero or one) within 16000 clock ticks. This safety feature can be used with heater pins to ensure the host does not enable the heater and then go off-line. config_pwm_out oid=%c pin=%u cycle_ticks=%u value=%hu default_value=%hu max_duration=%u : This command creates an internal object for hardware based PWM pins that the host may schedule updates for. Its usage is analogous to config_digital_out - see the description of the 'set_pwm_out' and 'config_digital_out' commands for parameter description. config_analog_in oid=%c pin=%u : This command is used to configure a pin in analog input sampling mode. Once configured, the pin can be sampled at regular interval using the query_analog_in command (see below). config_stepper oid=%c step_pin=%c dir_pin=%c invert_step=%c step_pulse_ticks=%u : This command creates an internal stepper object. The 'step_pin' and 'dir_pin' parameters specify the step and direction pins respectively; this command will configure them in digital output mode. The 'invert_step' parameter specifies whether a step occurs on a rising edge (invert_step=0) or falling edge (invert_step=1). The 'step_pulse_ticks' parameter specifies the minimum duration of the step pulse. If the mcu exports the constant 'STEPPER_BOTH_EDGE=1' then setting step_pulse_ticks=0 and invert_step=-1 will setup for stepping on both the rising and falling edges of the step pin. config_endstop oid=%c pin=%c pull_up=%c stepper_count=%c : This command creates an internal \"endstop\" object. It is used to specify the endstop pins and to enable \"homing\" operations (see the endstop_home command below). The command will configure the specified pin in digital input mode. The 'pull_up' parameter determines whether hardware provided pullup resistors for the pin (if available) will be enabled. The 'stepper_count' parameter specifies the maximum number of steppers that this endstop may need to halt during a homing operation (see endstop_home below). config_spi oid=%c bus=%u pin=%u mode=%u rate=%u shutdown_msg=%*s : This command creates an internal SPI object. It is used with spi_transfer and spi_send commands (see below). The \"bus\" identifies the SPI bus to use (if the micro-controller has more than one SPI bus available). The \"pin\" specifies the chip select (CS) pin for the device. The \"mode\" is the SPI mode (should be between 0 and 3). The \"rate\" parameter specifies the SPI bus rate (in cycles per second). Finally, the \"shutdown_msg\" is an SPI command to send to the given device should the micro-controller go into a shutdown state. config_spi_without_cs oid=%c bus=%u mode=%u rate=%u shutdown_msg=%*s : This command is similar to config_spi, but without a CS pin definition. It is useful for SPI devices that do not have a chip select line. Common commands \u00b6 This section lists some commonly used run-time commands. It is likely only of interest to developers looking to gain insight into Klipper. set_digital_out_pwm_cycle oid=%c cycle_ticks=%u : This command configures a digital output pin (as created by config_digital_out) to use \"software PWM\". The 'cycle_ticks' is the number of clock ticks for the PWM cycle. Because the output switching is implemented in the micro-controller software, it is recommended that 'cycle_ticks' correspond to a time of 10ms or greater. queue_digital_out oid=%c clock=%u on_ticks=%u : This command will schedule a change to a digital output GPIO pin at the given clock time. To use this command a 'config_digital_out' command with the same 'oid' parameter must have been issued during micro-controller configuration. If 'set_digital_out_pwm_cycle' has been called then 'on_ticks' is the on duration (in clock ticks) for the pwm cycle. Otherwise, 'on_ticks' should be either 0 (for low voltage) or 1 (for high voltage). queue_pwm_out oid=%c clock=%u value=%hu : Schedules a change to a hardware PWM output pin. See the 'queue_digital_out' and 'config_pwm_out' commands for more info. query_analog_in oid=%c clock=%u sample_ticks=%u sample_count=%c rest_ticks=%u min_value=%hu max_value=%hu : This command sets up a recurring schedule of analog input samples. To use this command a 'config_analog_in' command with the same 'oid' parameter must have been issued during micro-controller configuration. The samples will start as of 'clock' time, it will report on the obtained value every 'rest_ticks' clock ticks, it will over-sample 'sample_count' number of times, and it will pause 'sample_ticks' number of clock ticks between over-sample samples. The 'min_value' and 'max_value' parameters implement a safety feature - the micro-controller software will verify the sampled value (after any oversampling) is always between the supplied range. This is intended for use with pins attached to thermistors controlling heaters - it can be used to check that a heater is within a temperature range. get_clock : This command causes the micro-controller to generate a \"clock\" response message. The host sends this command once a second to obtain the value of the micro-controller clock and to estimate the drift between host and micro-controller clocks. It enables the host to accurately estimate the micro-controller clock. Stepper commands \u00b6 queue_step oid=%c interval=%u count=%hu add=%hi : This command schedules 'count' number of steps for the given stepper, with 'interval' number of clock ticks between each step. The first step will be 'interval' number of clock ticks since the last scheduled step for the given stepper. If 'add' is non-zero then the interval will be adjusted by 'add' amount after each step. This command appends the given interval/count/add sequence to a per-stepper queue. There may be hundreds of these sequences queued during normal operation. New sequence are appended to the end of the queue and as each sequence completes its 'count' number of steps it is popped from the front of the queue. This system allows the micro-controller to queue potentially hundreds of thousands of steps - all with reliable and predictable schedule times. set_next_step_dir oid=%c dir=%c : This command specifies the value of the dir_pin that the next queue_step command will use. reset_step_clock oid=%c clock=%u : Normally, step timing is relative to the last step for a given stepper. This command resets the clock so that the next step is relative to the supplied 'clock' time. The host usually only sends this command at the start of a print. stepper_get_position oid=%c : This command causes the micro-controller to generate a \"stepper_position\" response message with the stepper's current position. The position is the total number of steps generated with dir=1 minus the total number of steps generated with dir=0. endstop_home oid=%c clock=%u sample_ticks=%u sample_count=%c rest_ticks=%u pin_value=%c : This command is used during stepper \"homing\" operations. To use this command a 'config_endstop' command with the same 'oid' parameter must have been issued during micro-controller configuration. When this command is invoked, the micro-controller will sample the endstop pin every 'rest_ticks' clock ticks and check if it has a value equal to 'pin_value'. If the value matches (and it continues to match for 'sample_count' additional samples spread 'sample_ticks' apart) then the movement queue for the associated stepper will be cleared and the stepper will come to an immediate halt. The host uses this command to implement homing - the host instructs the endstop to sample for the endstop trigger and then it issues a series of queue_step commands to move a stepper towards the endstop. Once the stepper hits the endstop, the trigger will be detected, the movement halted, and the host notified. Move queue \u00b6 Each queue_step command utilizes an entry in the micro-controller \"move queue\". This queue is allocated when it receives the \"finalize_config\" command, and it reports the number of available queue entries in \"config\" response messages. It is the responsibility of the host to ensure that there is available space in the queue before sending a queue_step command. The host does this by calculating when each queue_step command completes and scheduling new queue_step commands accordingly. SPI Commands \u00b6 spi_transfer oid=%c data=%*s : This command causes the micro-controller to send 'data' to the spi device specified by 'oid' and it generates a \"spi_transfer_response\" response message with the data returned during the transmission. spi_send oid=%c data=%*s : This command is similar to \"spi_transfer\", but it does not generate a \"spi_transfer_response\" message.","title":"MCU commands"},{"location":"MCU_Commands.html#mcu-commands","text":"This document provides information on the low-level micro-controller commands that are sent from the Klipper \"host\" software and processed by the Klipper micro-controller software. This document is not an authoritative reference for these commands, nor is it an exclusive list of all available commands. This document may be useful for developers interested in understanding the low-level micro-controller commands. See the protocol document for more information on the format of commands and their transmission. The commands here are described using their \"printf\" style syntax - for those unfamiliar with that format, just note that where a '%...' sequence is seen it should be replaced with an actual integer. For example, a description with \"count=%c\" could be replaced with the text \"count=10\". Note that parameters that are considered \"enumerations\" (see the above protocol document) take a string value which is automatically converted to an integer value for the micro-controller. This is common with parameters named \"pin\" (or that have a suffix of \"_pin\").","title":"MCU commands"},{"location":"MCU_Commands.html#startup-commands","text":"It may be necessary to take certain one-time actions to configure the micro-controller and its peripherals. This section lists common commands available for that purpose. Unlike most micro-controller commands, these commands run as soon as they are received and they do not require any particular setup. Common startup commands: set_digital_out pin=%u value=%c : This command immediately configures the given pin as a digital out GPIO and it sets it to either a low level (value=0) or a high level (value=1). This command may be useful for configuring the initial value of LEDs and for configuring the initial value of stepper driver micro-stepping pins. set_pwm_out pin=%u cycle_ticks=%u value=%hu : This command will immediately configure the given pin to use hardware based pulse-width-modulation (PWM) with the given number of cycle_ticks. The \"cycle_ticks\" is the number of MCU clock ticks each power on and power off cycle should last. A cycle_ticks value of 1 can be used to request the fastest possible cycle time. The \"value\" parameter is between 0 and 255 with 0 indicating a full off state and 255 indicating a full on state. This command may be useful for enabling CPU and nozzle cooling fans.","title":"Startup Commands"},{"location":"MCU_Commands.html#low-level-micro-controller-configuration","text":"Most commands in the micro-controller require an initial setup before they can be successfully invoked. This section provides an overview of the configuration process. This section and the following sections are likely only of interest to developers interested in the internal details of Klipper. When the host first connects to the micro-controller it always starts by obtaining a data dictionary (see protocol for more information). After the data dictionary is obtained the host will check if the micro-controller is in a \"configured\" state and configure it if not. Configuration involves the following phases: get_config : The host starts by checking if the micro-controller is already configured. The micro-controller responds to this command with a \"config\" response message. The micro-controller software always starts in an unconfigured state at power-on. It remains in this state until the host completes the configuration processes (by issuing a finalize_config command). If the micro-controller is already configured from a previous session (and is configured with the desired settings) then no further action is needed by the host and the configuration process ends successfully. allocate_oids count=%c : This command is issued to inform the micro-controller of the maximum number of object-ids (oid) that the host requires. It is only valid to issue this command once. An oid is an integer identifier allocated to each stepper, each endstop, and each schedulable gpio pin. The host determines in advance the number of oids it will require to operate the hardware and passes this to the micro-controller so that it may allocate sufficient memory to store a mapping from oid to internal object. config_XXX oid=%c ... : By convention any command starting with the \"config_\" prefix creates a new micro-controller object and assigns the given oid to it. For example, the config_digital_out command will configure the specified pin as a digital output GPIO and create an internal object that the host can use to schedule changes to the given GPIO. The oid parameter passed into the config command is selected by the host and must be between zero and the maximum count supplied in the allocate_oids command. The config commands may only be run when the micro-controller is not in a configured state (ie, prior to the host sending finalize_config) and after the allocate_oids command has been sent. finalize_config crc=%u : The finalize_config command transitions the micro-controller from an unconfigured state to a configured state. The crc parameter passed to the micro-controller is stored and provided back to the host in \"config\" response messages. By convention, the host takes a 32bit CRC of the configuration it will request and at the start of subsequent communication sessions it checks that the CRC stored in the micro-controller exactly matches its desired CRC. If the CRC does not match then the host knows the micro-controller has not been configured in the state desired by the host.","title":"Low-level micro-controller configuration"},{"location":"MCU_Commands.html#common-micro-controller-objects","text":"This section lists some commonly used config commands. config_digital_out oid=%c pin=%u value=%c default_value=%c max_duration=%u : This command creates an internal micro-controller object for the given GPIO 'pin'. The pin will be configured in digital output mode and set to an initial value as specified by 'value' (0 for low, 1 for high). Creating a digital_out object allows the host to schedule GPIO updates for the given pin at specified times (see the queue_digital_out command described below). Should the micro-controller software go into shutdown mode then all configured digital_out objects will be set to 'default_value'. The 'max_duration' parameter is used to implement a safety check - if it is non-zero then it is the maximum number of clock ticks that the host may set the given GPIO to a non-default value without further updates. For example, if the default_value is zero and the max_duration is 16000 then if the host sets the gpio to a value of one then it must schedule another update to the gpio pin (to either zero or one) within 16000 clock ticks. This safety feature can be used with heater pins to ensure the host does not enable the heater and then go off-line. config_pwm_out oid=%c pin=%u cycle_ticks=%u value=%hu default_value=%hu max_duration=%u : This command creates an internal object for hardware based PWM pins that the host may schedule updates for. Its usage is analogous to config_digital_out - see the description of the 'set_pwm_out' and 'config_digital_out' commands for parameter description. config_analog_in oid=%c pin=%u : This command is used to configure a pin in analog input sampling mode. Once configured, the pin can be sampled at regular interval using the query_analog_in command (see below). config_stepper oid=%c step_pin=%c dir_pin=%c invert_step=%c step_pulse_ticks=%u : This command creates an internal stepper object. The 'step_pin' and 'dir_pin' parameters specify the step and direction pins respectively; this command will configure them in digital output mode. The 'invert_step' parameter specifies whether a step occurs on a rising edge (invert_step=0) or falling edge (invert_step=1). The 'step_pulse_ticks' parameter specifies the minimum duration of the step pulse. If the mcu exports the constant 'STEPPER_BOTH_EDGE=1' then setting step_pulse_ticks=0 and invert_step=-1 will setup for stepping on both the rising and falling edges of the step pin. config_endstop oid=%c pin=%c pull_up=%c stepper_count=%c : This command creates an internal \"endstop\" object. It is used to specify the endstop pins and to enable \"homing\" operations (see the endstop_home command below). The command will configure the specified pin in digital input mode. The 'pull_up' parameter determines whether hardware provided pullup resistors for the pin (if available) will be enabled. The 'stepper_count' parameter specifies the maximum number of steppers that this endstop may need to halt during a homing operation (see endstop_home below). config_spi oid=%c bus=%u pin=%u mode=%u rate=%u shutdown_msg=%*s : This command creates an internal SPI object. It is used with spi_transfer and spi_send commands (see below). The \"bus\" identifies the SPI bus to use (if the micro-controller has more than one SPI bus available). The \"pin\" specifies the chip select (CS) pin for the device. The \"mode\" is the SPI mode (should be between 0 and 3). The \"rate\" parameter specifies the SPI bus rate (in cycles per second). Finally, the \"shutdown_msg\" is an SPI command to send to the given device should the micro-controller go into a shutdown state. config_spi_without_cs oid=%c bus=%u mode=%u rate=%u shutdown_msg=%*s : This command is similar to config_spi, but without a CS pin definition. It is useful for SPI devices that do not have a chip select line.","title":"Common micro-controller objects"},{"location":"MCU_Commands.html#common-commands","text":"This section lists some commonly used run-time commands. It is likely only of interest to developers looking to gain insight into Klipper. set_digital_out_pwm_cycle oid=%c cycle_ticks=%u : This command configures a digital output pin (as created by config_digital_out) to use \"software PWM\". The 'cycle_ticks' is the number of clock ticks for the PWM cycle. Because the output switching is implemented in the micro-controller software, it is recommended that 'cycle_ticks' correspond to a time of 10ms or greater. queue_digital_out oid=%c clock=%u on_ticks=%u : This command will schedule a change to a digital output GPIO pin at the given clock time. To use this command a 'config_digital_out' command with the same 'oid' parameter must have been issued during micro-controller configuration. If 'set_digital_out_pwm_cycle' has been called then 'on_ticks' is the on duration (in clock ticks) for the pwm cycle. Otherwise, 'on_ticks' should be either 0 (for low voltage) or 1 (for high voltage). queue_pwm_out oid=%c clock=%u value=%hu : Schedules a change to a hardware PWM output pin. See the 'queue_digital_out' and 'config_pwm_out' commands for more info. query_analog_in oid=%c clock=%u sample_ticks=%u sample_count=%c rest_ticks=%u min_value=%hu max_value=%hu : This command sets up a recurring schedule of analog input samples. To use this command a 'config_analog_in' command with the same 'oid' parameter must have been issued during micro-controller configuration. The samples will start as of 'clock' time, it will report on the obtained value every 'rest_ticks' clock ticks, it will over-sample 'sample_count' number of times, and it will pause 'sample_ticks' number of clock ticks between over-sample samples. The 'min_value' and 'max_value' parameters implement a safety feature - the micro-controller software will verify the sampled value (after any oversampling) is always between the supplied range. This is intended for use with pins attached to thermistors controlling heaters - it can be used to check that a heater is within a temperature range. get_clock : This command causes the micro-controller to generate a \"clock\" response message. The host sends this command once a second to obtain the value of the micro-controller clock and to estimate the drift between host and micro-controller clocks. It enables the host to accurately estimate the micro-controller clock.","title":"Common commands"},{"location":"MCU_Commands.html#stepper-commands","text":"queue_step oid=%c interval=%u count=%hu add=%hi : This command schedules 'count' number of steps for the given stepper, with 'interval' number of clock ticks between each step. The first step will be 'interval' number of clock ticks since the last scheduled step for the given stepper. If 'add' is non-zero then the interval will be adjusted by 'add' amount after each step. This command appends the given interval/count/add sequence to a per-stepper queue. There may be hundreds of these sequences queued during normal operation. New sequence are appended to the end of the queue and as each sequence completes its 'count' number of steps it is popped from the front of the queue. This system allows the micro-controller to queue potentially hundreds of thousands of steps - all with reliable and predictable schedule times. set_next_step_dir oid=%c dir=%c : This command specifies the value of the dir_pin that the next queue_step command will use. reset_step_clock oid=%c clock=%u : Normally, step timing is relative to the last step for a given stepper. This command resets the clock so that the next step is relative to the supplied 'clock' time. The host usually only sends this command at the start of a print. stepper_get_position oid=%c : This command causes the micro-controller to generate a \"stepper_position\" response message with the stepper's current position. The position is the total number of steps generated with dir=1 minus the total number of steps generated with dir=0. endstop_home oid=%c clock=%u sample_ticks=%u sample_count=%c rest_ticks=%u pin_value=%c : This command is used during stepper \"homing\" operations. To use this command a 'config_endstop' command with the same 'oid' parameter must have been issued during micro-controller configuration. When this command is invoked, the micro-controller will sample the endstop pin every 'rest_ticks' clock ticks and check if it has a value equal to 'pin_value'. If the value matches (and it continues to match for 'sample_count' additional samples spread 'sample_ticks' apart) then the movement queue for the associated stepper will be cleared and the stepper will come to an immediate halt. The host uses this command to implement homing - the host instructs the endstop to sample for the endstop trigger and then it issues a series of queue_step commands to move a stepper towards the endstop. Once the stepper hits the endstop, the trigger will be detected, the movement halted, and the host notified.","title":"Stepper commands"},{"location":"MCU_Commands.html#move-queue","text":"Each queue_step command utilizes an entry in the micro-controller \"move queue\". This queue is allocated when it receives the \"finalize_config\" command, and it reports the number of available queue entries in \"config\" response messages. It is the responsibility of the host to ensure that there is available space in the queue before sending a queue_step command. The host does this by calculating when each queue_step command completes and scheduling new queue_step commands accordingly.","title":"Move queue"},{"location":"MCU_Commands.html#spi-commands","text":"spi_transfer oid=%c data=%*s : This command causes the micro-controller to send 'data' to the spi device specified by 'oid' and it generates a \"spi_transfer_response\" response message with the data returned during the transmission. spi_send oid=%c data=%*s : This command is similar to \"spi_transfer\", but it does not generate a \"spi_transfer_response\" message.","title":"SPI Commands"},{"location":"Manual_Level.html","text":"Manual leveling \u00b6 This document describes tools for calibrating a Z endstop and for performing adjustments to bed leveling screws. Calibrating a Z endstop \u00b6 An accurate Z endstop position is critical to obtaining high quality prints. Note, though, the accuracy of the Z endstop switch itself can be a limiting factor. If one is using Trinamic stepper motor drivers then consider enabling endstop phase detection to improve the accuracy of the switch. To perform a Z endstop calibration, home the printer, command the head to move to a Z position that is at least five millimeters above the bed (if it is not already), command the head to move to an XY position near the center of the bed, then navigate to the OctoPrint terminal tab and run: Z_ENDSTOP_CALIBRATE Then follow the steps described at \"the paper test\" to determine the actual distance between the nozzle and bed at the given location. Once those steps are complete one can ACCEPT the position and save the results to the config file with: SAVE_CONFIG It's preferable to use a Z endstop switch on the opposite end of the Z axis from the bed. (Homing away from the bed is more robust as then it is generally always safe to home the Z.) However, if one must home towards the bed it is recommended to adjust the endstop so that it triggers a small distance (eg, .5mm) above the bed. Almost all endstop switches can safely be depressed a small distance beyond their trigger point. When this is done, one should find that the Z_ENDSTOP_CALIBRATE command reports a small positive value (eg, .5mm) for the Z position_endstop. Triggering the endstop while it is still some distance from the bed reduces the risk of inadvertent bed crashes. Some printers have the ability to manually adjust the location of the physical endstop switch. However, it's recommended to perform Z endstop positioning in software with Klipper - once the physical location of the endstop is in a convenient location, one can make any further adjustments by running Z_ENDSTOP_CALIBRATE or by manually updating the Z position_endstop in the configuration file. Adjusting bed leveling screws \u00b6 The secret to getting good bed leveling with bed leveling screws is to utilize the printer's high precision motion system during the bed leveling process itself. This is done by commanding the nozzle to a position near each bed screw and then adjusting that screw until the bed is a set distance from the nozzle. Klipper has a tool to assist with this. In order to use the tool it is necessary to specify each screw XY location. This is done by creating a [bed_screws] config section. For example, it might look something similar to: [bed_screws] screw1: 100, 50 screw2: 100, 150 screw3: 150, 100 If a bed screw is under the bed, then specify the XY position directly above the screw. If the screw is outside the bed then specify an XY position closest to the screw that is still within the range of the bed. Once the config file is ready, run RESTART to load that config, and then one can start the tool by running: BED_SCREWS_ADJUST This tool will move the printer's nozzle to each screw XY location and then move the nozzle to a Z=0 height. At this point one can use the \"paper test\" to adjust the bed screw directly under the nozzle. See the information described in \"the paper test\" , but adjust the bed screw instead of commanding the nozzle to different heights. Adjust the bed screw until there is a small amount of friction when pushing the paper back and forth. Once the screw is adjusted so that a small amount of friction is felt, run either the ACCEPT or ADJUSTED command. Use the ADJUSTED command if the bed screw needed an adjustment (typically anything more than about 1/8th of a turn of the screw). Use the ACCEPT command if no significant adjustment is necessary. Both commands will cause the tool to proceed to the next screw. (When an ADJUSTED command is used, the tool will schedule an additional cycle of bed screw adjustments; the tool completes successfully when all bed screws are verified to not require any significant adjustments.) One can use the ABORT command to exit the tool early. This system works best when the printer has a flat printing surface (such as glass) and has straight rails. Upon successful completion of the bed leveling tool the bed should be ready for printing. Fine grained bed screw adjustments \u00b6 If the printer uses three bed screws and all three screws are under the bed, then it may be possible to perform a second \"high precision\" bed leveling step. This is done by commanding the nozzle to locations where the bed moves a larger distance with each bed screw adjustment. For example, consider a bed with screws at locations A, B, and C: For each adjustment made to the bed screw at location C, the bed will swing along a pendulum defined by the remaining two bed screws (shown here as a green line). In this situation, each adjustment to the bed screw at C will move the bed at position D a further amount than directly at C. It is thus possible to make an improved C screw adjustment when the nozzle is at position D. To enable this feature, one would determine the additional nozzle coordinates and add them to the config file. For example, it might look like: [bed_screws] screw1: 100, 50 screw1_fine_adjust: 0, 0 screw2: 100, 150 screw2_fine_adjust: 300, 300 screw3: 150, 100 screw3_fine_adjust: 0, 100 When this feature is enabled, the BED_SCREWS_ADJUST tool will first prompt for coarse adjustments directly above each screw position, and once those are accepted, it will prompt for fine adjustments at the additional locations. Continue to use ACCEPT and ADJUSTED at each position. Adjusting bed leveling screws using the bed probe \u00b6 This is another way to calibrate the bed level using the bed probe. To use it you must have a Z probe (BL Touch, Inductive sensor, etc). To enable this feature, one would determine the nozzle coordinates such that the Z probe is above the screws, and then add them to the config file. For example, it might look like: [screws_tilt_adjust] screw1: -5, 30 screw1_name: front left screw screw2: 155, 30 screw2_name: front right screw screw3: 155, 190 screw3_name: rear right screw screw4: -5, 190 screw4_name: rear left screw horizontal_move_z: 10. speed: 50. screw_thread: CW-M3 The screw1 is always the reference point for the others, so the system assumes that screw1 is at the correct height. Always run G28 first and then run SCREWS_TILT_CALCULATE - it should produce output similar to: Send: G28 Recv: ok Send: SCREWS_TILT_CALCULATE Recv: // 01:20 means 1 full turn and 20 minutes, CW=clockwise, CCW=counter-clockwise Recv: // front left screw (base) : x=-5.0, y=30.0, z=2.48750 Recv: // front right screw : x=155.0, y=30.0, z=2.36000 : adjust CW 01:15 Recv: // rear right screw : y=155.0, y=190.0, z=2.71500 : adjust CCW 00:50 Recv: // read left screw : x=-5.0, y=190.0, z=2.47250 : adjust CW 00:02 Recv: ok This means that: front left screw is the reference point you must not change it. front right screw must be turned clockwise 1 full turn and a quarter turn rear right screw must be turned counter-clockwise 50 minutes rear left screw must be turned clockwise 2 minutes (not need it's ok) Note that \"minutes\" refers to \"minutes of a clock face\". So, for example, 15 minutes is a quarter of a full turn. Repeat the process several times until you get a good level bed - normally when all adjustments are below 6 minutes. If using a probe that is mounted on the side of the hotend (that is, it has an X or Y offset) then note that adjusting the bed tilt will invalidate any previous probe calibration that was performed with a tilted bed. Be sure to run probe calibration after the bed screws have been adjusted. The MAX_DEVIATION parameter is useful when a saved bed mesh is used, to ensure that the bed level has not drifted too far from where it was when the mesh was created. For example, SCREWS_TILT_CALCULATE MAX_DEVIATION=0.01 can be added to the custom start gcode of the slicer before the mesh is loaded. It will abort the print if the configured limit is exceeded (0.01mm in this example), giving the user a chance to adjust the screws and restart the print. The DIRECTION parameter is useful if you can turn your bed adjustment screws in one direction only. For example, you might have screws that start tightened in their lowest (or highest) possible position, which can only be turned in a single direction, to raise (or lower) the bed. If you can only turn the screws clockwise, run SCREWS_TILT_CALCULATE DIRECTION=CW . If you can only turn them counter-clockwise, run SCREWS_TILT_CALCULATE DIRECTION=CCW . A suitable reference point will be chosen such that the bed can be leveled by turning all the screws in the given direction.","title":"Manual leveling"},{"location":"Manual_Level.html#manual-leveling","text":"This document describes tools for calibrating a Z endstop and for performing adjustments to bed leveling screws.","title":"Manual leveling"},{"location":"Manual_Level.html#calibrating-a-z-endstop","text":"An accurate Z endstop position is critical to obtaining high quality prints. Note, though, the accuracy of the Z endstop switch itself can be a limiting factor. If one is using Trinamic stepper motor drivers then consider enabling endstop phase detection to improve the accuracy of the switch. To perform a Z endstop calibration, home the printer, command the head to move to a Z position that is at least five millimeters above the bed (if it is not already), command the head to move to an XY position near the center of the bed, then navigate to the OctoPrint terminal tab and run: Z_ENDSTOP_CALIBRATE Then follow the steps described at \"the paper test\" to determine the actual distance between the nozzle and bed at the given location. Once those steps are complete one can ACCEPT the position and save the results to the config file with: SAVE_CONFIG It's preferable to use a Z endstop switch on the opposite end of the Z axis from the bed. (Homing away from the bed is more robust as then it is generally always safe to home the Z.) However, if one must home towards the bed it is recommended to adjust the endstop so that it triggers a small distance (eg, .5mm) above the bed. Almost all endstop switches can safely be depressed a small distance beyond their trigger point. When this is done, one should find that the Z_ENDSTOP_CALIBRATE command reports a small positive value (eg, .5mm) for the Z position_endstop. Triggering the endstop while it is still some distance from the bed reduces the risk of inadvertent bed crashes. Some printers have the ability to manually adjust the location of the physical endstop switch. However, it's recommended to perform Z endstop positioning in software with Klipper - once the physical location of the endstop is in a convenient location, one can make any further adjustments by running Z_ENDSTOP_CALIBRATE or by manually updating the Z position_endstop in the configuration file.","title":"Calibrating a Z endstop"},{"location":"Manual_Level.html#adjusting-bed-leveling-screws","text":"The secret to getting good bed leveling with bed leveling screws is to utilize the printer's high precision motion system during the bed leveling process itself. This is done by commanding the nozzle to a position near each bed screw and then adjusting that screw until the bed is a set distance from the nozzle. Klipper has a tool to assist with this. In order to use the tool it is necessary to specify each screw XY location. This is done by creating a [bed_screws] config section. For example, it might look something similar to: [bed_screws] screw1: 100, 50 screw2: 100, 150 screw3: 150, 100 If a bed screw is under the bed, then specify the XY position directly above the screw. If the screw is outside the bed then specify an XY position closest to the screw that is still within the range of the bed. Once the config file is ready, run RESTART to load that config, and then one can start the tool by running: BED_SCREWS_ADJUST This tool will move the printer's nozzle to each screw XY location and then move the nozzle to a Z=0 height. At this point one can use the \"paper test\" to adjust the bed screw directly under the nozzle. See the information described in \"the paper test\" , but adjust the bed screw instead of commanding the nozzle to different heights. Adjust the bed screw until there is a small amount of friction when pushing the paper back and forth. Once the screw is adjusted so that a small amount of friction is felt, run either the ACCEPT or ADJUSTED command. Use the ADJUSTED command if the bed screw needed an adjustment (typically anything more than about 1/8th of a turn of the screw). Use the ACCEPT command if no significant adjustment is necessary. Both commands will cause the tool to proceed to the next screw. (When an ADJUSTED command is used, the tool will schedule an additional cycle of bed screw adjustments; the tool completes successfully when all bed screws are verified to not require any significant adjustments.) One can use the ABORT command to exit the tool early. This system works best when the printer has a flat printing surface (such as glass) and has straight rails. Upon successful completion of the bed leveling tool the bed should be ready for printing.","title":"Adjusting bed leveling screws"},{"location":"Manual_Level.html#fine-grained-bed-screw-adjustments","text":"If the printer uses three bed screws and all three screws are under the bed, then it may be possible to perform a second \"high precision\" bed leveling step. This is done by commanding the nozzle to locations where the bed moves a larger distance with each bed screw adjustment. For example, consider a bed with screws at locations A, B, and C: For each adjustment made to the bed screw at location C, the bed will swing along a pendulum defined by the remaining two bed screws (shown here as a green line). In this situation, each adjustment to the bed screw at C will move the bed at position D a further amount than directly at C. It is thus possible to make an improved C screw adjustment when the nozzle is at position D. To enable this feature, one would determine the additional nozzle coordinates and add them to the config file. For example, it might look like: [bed_screws] screw1: 100, 50 screw1_fine_adjust: 0, 0 screw2: 100, 150 screw2_fine_adjust: 300, 300 screw3: 150, 100 screw3_fine_adjust: 0, 100 When this feature is enabled, the BED_SCREWS_ADJUST tool will first prompt for coarse adjustments directly above each screw position, and once those are accepted, it will prompt for fine adjustments at the additional locations. Continue to use ACCEPT and ADJUSTED at each position.","title":"Fine grained bed screw adjustments"},{"location":"Manual_Level.html#adjusting-bed-leveling-screws-using-the-bed-probe","text":"This is another way to calibrate the bed level using the bed probe. To use it you must have a Z probe (BL Touch, Inductive sensor, etc). To enable this feature, one would determine the nozzle coordinates such that the Z probe is above the screws, and then add them to the config file. For example, it might look like: [screws_tilt_adjust] screw1: -5, 30 screw1_name: front left screw screw2: 155, 30 screw2_name: front right screw screw3: 155, 190 screw3_name: rear right screw screw4: -5, 190 screw4_name: rear left screw horizontal_move_z: 10. speed: 50. screw_thread: CW-M3 The screw1 is always the reference point for the others, so the system assumes that screw1 is at the correct height. Always run G28 first and then run SCREWS_TILT_CALCULATE - it should produce output similar to: Send: G28 Recv: ok Send: SCREWS_TILT_CALCULATE Recv: // 01:20 means 1 full turn and 20 minutes, CW=clockwise, CCW=counter-clockwise Recv: // front left screw (base) : x=-5.0, y=30.0, z=2.48750 Recv: // front right screw : x=155.0, y=30.0, z=2.36000 : adjust CW 01:15 Recv: // rear right screw : y=155.0, y=190.0, z=2.71500 : adjust CCW 00:50 Recv: // read left screw : x=-5.0, y=190.0, z=2.47250 : adjust CW 00:02 Recv: ok This means that: front left screw is the reference point you must not change it. front right screw must be turned clockwise 1 full turn and a quarter turn rear right screw must be turned counter-clockwise 50 minutes rear left screw must be turned clockwise 2 minutes (not need it's ok) Note that \"minutes\" refers to \"minutes of a clock face\". So, for example, 15 minutes is a quarter of a full turn. Repeat the process several times until you get a good level bed - normally when all adjustments are below 6 minutes. If using a probe that is mounted on the side of the hotend (that is, it has an X or Y offset) then note that adjusting the bed tilt will invalidate any previous probe calibration that was performed with a tilted bed. Be sure to run probe calibration after the bed screws have been adjusted. The MAX_DEVIATION parameter is useful when a saved bed mesh is used, to ensure that the bed level has not drifted too far from where it was when the mesh was created. For example, SCREWS_TILT_CALCULATE MAX_DEVIATION=0.01 can be added to the custom start gcode of the slicer before the mesh is loaded. It will abort the print if the configured limit is exceeded (0.01mm in this example), giving the user a chance to adjust the screws and restart the print. The DIRECTION parameter is useful if you can turn your bed adjustment screws in one direction only. For example, you might have screws that start tightened in their lowest (or highest) possible position, which can only be turned in a single direction, to raise (or lower) the bed. If you can only turn the screws clockwise, run SCREWS_TILT_CALCULATE DIRECTION=CW . If you can only turn them counter-clockwise, run SCREWS_TILT_CALCULATE DIRECTION=CCW . A suitable reference point will be chosen such that the bed can be leveled by turning all the screws in the given direction.","title":"Adjusting bed leveling screws using the bed probe"},{"location":"Measuring_Resonances.html","text":"Measuring Resonances \u00b6 Klipper has built-in support for the ADXL345, MPU-9250, LIS2DW and LIS3DH compatible accelerometers which can be used to measure resonance frequencies of the printer for different axes, and auto-tune input shapers to compensate for resonances. Note that using accelerometers requires some soldering and crimping. The ADXL345 can be connected to the SPI interface of a Raspberry Pi or MCU board (it needs to be reasonably fast). The MPU family can be connected to the I2C interface of a Raspberry Pi directly, or to an I2C interface of an MCU board that supports 400kbit/s fast mode in Klipper. The LIS2DW and LIS3DH can be connected to either SPI or I2C with the same considerations as above. When sourcing accelerometers, be aware that there are a variety of different PCB board designs and different clones of them. If it is going to be connected to a 5V printer MCU ensure it has a voltage regulator and level shifters. For ADXL345s, make sure that the board supports SPI mode (a small number of boards appear to be hard-configured for I2C by pulling SDO to GND). For MPU-9250/MPU-9255/MPU-6515/MPU-6050/MPU-6500/ICM20948s and LIS2DW/LIS3DH there are also a variety of board designs and clones with different I2C pull-up resistors which will need supplementing. MCUs with Klipper I2C fast-mode Support \u00b6 MCU Family MCU(s) Tested MCU(s) with Support Raspberry Pi 3B+, Pico 3A, 3A+, 3B, 4 AVR ATmega ATmega328p ATmega32u4, ATmega128, ATmega168, ATmega328, ATmega644p, ATmega1280, ATmega1284, ATmega2560 AVR AT90 - AT90usb646, AT90usb1286 SAMD SAMC21G18 SAMC21G18, SAMD21G18, SAMD21E18, SAMD21J18, SAMD21E15, SAMD51G19, SAMD51J19, SAMD51N19, SAMD51P20, SAME51J19, SAME51N19, SAME54P20 Installation instructions \u00b6 Wiring \u00b6 An ethernet cable with shielded twisted pairs (cat5e or better) is recommended for signal integrity over a long distance. If you still experience signal integrity issues (SPI/I2C errors): Double check the wiring with a digital multimeter for: Correct connections when turned off (continuity) Correct power and ground voltages I2C only: Check the SCL and SDA lines' resistances to 3.3V are in the range of 900 ohms to 1.8K For full technical details consult chapter 7 of the I2C-bus specification and user manual UM10204 for fast-mode Shorten the cable Connect ethernet cable shielding only to the MCU board/Pi ground. Double-check your wiring before powering up to prevent damaging your MCU/Raspberry Pi or the accelerometer. SPI Accelerometers \u00b6 Suggested twisted pair order for three twisted pairs: GND+MISO 3.3V+MOSI SCLK+CS Note that unlike a cable shield, GND must be connected at both ends. ADXL345 \u00b6 Direct to Raspberry Pi \u00b6 Note: Many MCUs will work with an ADXL345 in SPI mode (e.g. Pi Pico), wiring and configuration will vary according to your specific board and available pins. You need to connect ADXL345 to your Raspberry Pi via SPI. Note that the I2C connection, which is suggested by ADXL345 documentation, has too low throughput and will not work . The recommended connection scheme: ADXL345 pin RPi pin RPi pin name 3V3 (or VCC) 01 3.3V DC power GND 06 Ground CS 24 GPIO08 (SPI0_CE0_N) SDO 21 GPIO09 (SPI0_MISO) SDA 19 GPIO10 (SPI0_MOSI) SCL 23 GPIO11 (SPI0_SCLK) Fritzing wiring diagrams for some of the ADXL345 boards: Using Raspberry Pi Pico \u00b6 You may connect the ADXL345 to your Raspberry Pi Pico and then connect the Pico to your Raspberry Pi via USB. This makes it easy to reuse the accelerometer on other Klipper devices, as you can connect via USB instead of GPIO. The Pico does not have much processing power, so make sure it is only running the accelerometer and not performing any other duties. In order to avoid damage to your RPi make sure to connect the ADXL345 to 3.3V only. Depending on the board's layout, a level shifter may be present, which makes 5V dangerous for your RPi. ADXL345 pin Pico pin Pico pin name 3V3 (or VCC) 36 3.3V DC power GND 38 Ground CS 2 GP1 (SPI0_CSn) SDO 1 GP0 (SPI0_RX) SDA 5 GP3 (SPI0_TX) SCL 4 GP2 (SPI0_SCK) Wiring diagrams for some of the ADXL345 boards: I2C Accelerometers \u00b6 Suggested twisted pair order for three pairs (preferred): 3.3V+GND SDA+GND SCL+GND or for two pairs: 3.3V+SDA GND+SCL Note that unlike a cable shield, any GND(s) should be connected at both ends. MPU-9250/MPU-9255/MPU-6515/MPU-6050/MPU-6500/ICM20948 \u00b6 These accelerometers have been tested to work over I2C on the RPi, RP2040 (Pico) and AVR at 400kbit/s ( fast mode ). Some MPU accelerometer modules include pull-ups, but some are too large at 10K and must be changed or supplemented by smaller parallel resistors. Recommended connection scheme for I2C on the Raspberry Pi: MPU-9250 pin RPi pin RPi pin name VCC 01 3.3v DC power GND 09 Ground SDA 03 GPIO02 (SDA1) SCL 05 GPIO03 (SCL1) The RPi has built-in 1.8K pull-ups on both SCL and SDA. Recommended connection scheme for I2C (i2c0a) on the RP2040: MPU-9250 pin RP2040 pin RP2040 pin name VCC 36 3v3 GND 38 Ground SDA 01 GP0 (I2C0 SDA) SCL 02 GP1 (I2C0 SCL) The Pico does not include any built-in I2C pull-up resistors. Recommended connection scheme for I2C(TWI) on the AVR ATmega328P Arduino Nano: \u00b6 MPU-9250 pin Atmega328P TQFP32 pin Atmega328P pin name Arduino Nano pin VCC 39 - - GND 38 Ground GND SDA 27 SDA A4 SCL 28 SCL A5 The Arduino Nano does not include any built-in pull-up resistors nor a 3.3V power pin. Mounting the accelerometer \u00b6 The accelerometer must be attached to the toolhead. One needs to design a proper mount that fits their own 3D printer. It is better to align the axes of the accelerometer with the printer's axes (but if it makes it more convenient, axes can be swapped - i.e. no need to align X axis with X and so forth - it should be fine even if Z axis of accelerometer is X axis of the printer, etc.). An example of mounting ADXL345 on the SmartEffector: Note that on a bed slinger printer one must design 2 mounts: one for the toolhead and one for the bed, and run the measurements twice. See the corresponding section for more details. Attention: make sure the accelerometer and any screws that hold it in place do not touch any metal parts of the printer. Basically, the mount must be designed such as to ensure the electrical isolation of the accelerometer from the printer frame. Failing to ensure that can create a ground loop in the system that may damage the electronics. Software installation \u00b6 Note that resonance measurements and shaper auto-calibration require additional software dependencies not installed by default. First, run on your Raspberry Pi the following commands: sudo apt update sudo apt install python3-numpy python3-matplotlib libatlas-base-dev libopenblas-dev Next, in order to install NumPy in the Klipper environment, run the command: ~/klippy-env/bin/pip install -v \"numpy<1.26\" Note that, depending on the performance of the CPU, it may take a lot of time, up to 10-20 minutes. Be patient and wait for the completion of the installation. On some occasions, if the board has too little RAM the installation may fail and you will need to enable swap. Also note the forced version, due to newer versions of NumPY having requirements that may not be satisfied in some klipper python environments. Once installed please check that no errors show from the command: ~/klippy-env/bin/python -c 'import numpy;' The correct output should simply be a new line. Configure ADXL345 With RPi \u00b6 First, check and follow the instructions in the RPi Microcontroller document to setup the \"linux mcu\" on the Raspberry Pi. This will configure a second Klipper instance that runs on your Pi. Make sure the Linux SPI driver is enabled by running sudo raspi-config and enabling SPI under the \"Interfacing options\" menu. Add the following to the printer.cfg file: [mcu rpi] serial: /tmp/klipper_host_mcu [adxl345] cs_pin: rpi:None [resonance_tester] accel_chip: adxl345 probe_points: 100, 100, 20 # an example It is advised to start with 1 probe point, in the middle of the print bed, slightly above it. Configure ADXL345 With Pi Pico \u00b6 Flash the Pico Firmware \u00b6 On your Raspberry Pi, compile the firmware for the Pico. cd ~/klipper make clean make menuconfig Now, while holding down the BOOTSEL button on the Pico, connect the Pico to the Raspberry Pi via USB. Compile and flash the firmware. make flash FLASH_DEVICE=first If that fails, you will be told which FLASH_DEVICE to use. In this example, that's make flash FLASH_DEVICE=2e8a:0003 . Configure the Connection \u00b6 The Pico will now reboot with the new firmware and should show up as a serial device. Find the pico serial device with ls /dev/serial/by-id/* . You can now add an adxl.cfg file with the following settings: [mcu adxl] # Change <mySerial> to whatever you found above. For example, # usb-Klipper_rp2040_E661640843545B2E-if00 serial: /dev/serial/by-id/usb-Klipper_rp2040_<mySerial> [adxl345] cs_pin: adxl:gpio1 spi_bus: spi0a axes_map: x,z,y [resonance_tester] accel_chip: adxl345 probe_points: # Somewhere slightly above the middle of your print bed 147,154, 20 [output_pin power_mode] # Improve power stability pin: adxl:gpio23 If setting up the ADXL345 configuration in a separate file, as shown above, you'll also want to modify your printer.cfg file to include this: [include adxl.cfg] # Comment this out when you disconnect the accelerometer Restart Klipper via the RESTART command. Configure LIS2DW series over SPI \u00b6 [mcu lis] # Change <mySerial> to whatever you found above. For example, # usb-Klipper_rp2040_E661640843545B2E-if00 serial: /dev/serial/by-id/usb-Klipper_rp2040_<mySerial> [lis2dw] cs_pin: lis:gpio1 spi_bus: spi0a axes_map: x,z,y [resonance_tester] accel_chip: lis2dw probe_points: # Somewhere slightly above the middle of your print bed 147,154, 20 Configure MPU-6000/9000 series With RPi \u00b6 Make sure the Linux I2C driver is enabled and the baud rate is set to 400000 (see Enabling I2C section for more details). Then, add the following to the printer.cfg: [mcu rpi] serial: /tmp/klipper_host_mcu [mpu9250] i2c_mcu: rpi i2c_bus: i2c.1 [resonance_tester] accel_chip: mpu9250 probe_points: 100, 100, 20 # an example If you are using the ICM20948, replace instances of \"mpu9250\" with \"icm20948\". Configure MPU-9520 Compatibles With Pico \u00b6 Pico I2C is set to 400000 on default. Simply add the following to the printer.cfg: [mcu pico] serial: /dev/serial/by-id/<your Pico's serial ID> [mpu9250] i2c_mcu: pico i2c_bus: i2c0a [resonance_tester] accel_chip: mpu9250 probe_points: 100, 100, 20 # an example [static_digital_output pico_3V3pwm] # Improve power stability pins: pico:gpio23 If you are using the ICM20948, replace instances of \"mpu9250\" with \"icm20948\". Configure MPU-9520 Compatibles with AVR \u00b6 AVR I2C will be set to 400000 by the mpu9250 option. Simply add the following to the printer.cfg: [mcu nano] serial: /dev/serial/by-id/<your nano's serial ID> [mpu9250] i2c_mcu: nano [resonance_tester] accel_chip: mpu9250 probe_points: 100, 100, 20 # an example If you are using the ICM20948, replace instances of \"mpu9250\" with \"icm20948\". Restart Klipper via the RESTART command. Measuring the resonances \u00b6 Checking the setup \u00b6 Now you can test a connection. For \"non bed-slingers\" (e.g. one accelerometer), in Octoprint, enter ACCELEROMETER_QUERY For \"bed-slingers\" (e.g. more than one accelerometer), enter ACCELEROMETER_QUERY CHIP=<chip> where <chip> is the name of the chip as-entered, e.g. CHIP=bed (see: bed-slinger ) for all installed accelerometer chips. You should see the current measurements from the accelerometer, including the free-fall acceleration, e.g. Recv: // adxl345 values (x, y, z): 470.719200, 941.438400, 9728.196800 If you get an error like Invalid adxl345 id (got xx vs e5) , where xx is some other ID, immediately try again. There's an issue with SPI initialization. If you still get an error, it is indicative of the connection problem with ADXL345, or the faulty sensor. Double-check the power, the wiring (that it matches the schematics, no wire is broken or loose, etc.), and soldering quality. If you are using a MPU-9250 compatible accelerometer and it shows up as mpu-unknown , use with caution! They are probably refurbished chips! Next, try running MEASURE_AXES_NOISE in Octoprint, you should get some baseline numbers for the noise of accelerometer on the axes (should be somewhere in the range of ~1-100). Too high axes noise (e.g. 1000 and more) can be indicative of the sensor issues, problems with its power, or too noisy imbalanced fans on a 3D printer. Measuring the resonances \u00b6 Now you can run some real-life tests. Run the following command: TEST_RESONANCES AXIS=X Note that it will create vibrations on X axis. It will also disable input shaping if it was enabled previously, as it is not valid to run the resonance testing with the input shaper enabled. Attention! Be sure to observe the printer for the first time, to make sure the vibrations do not become too violent ( M112 command can be used to abort the test in case of emergency; hopefully it will not come to this though). If the vibrations do get too strong, you can attempt to specify a lower than the default value for accel_per_hz parameter in [resonance_tester] section, e.g. [resonance_tester] accel_chip: adxl345 accel_per_hz: 50 # default is 75 probe_points: ... If it works for X axis, run for Y axis as well: TEST_RESONANCES AXIS=Y This will generate 2 CSV files ( /tmp/resonances_x_*.csv and /tmp/resonances_y_*.csv ). These files can be processed with the stand-alone script on a Raspberry Pi. This script is intended to be run with a single CSV file for each axis measured, although it can be used with multiple CSV files if you desire to average the results. Averaging results can be useful, for example, if resonance tests were done at multiple test points. Delete the extra CSV files if you do not desire to average them. ~/klipper/scripts/calibrate_shaper.py /tmp/resonances_x_*.csv -o /tmp/shaper_calibrate_x.png ~/klipper/scripts/calibrate_shaper.py /tmp/resonances_y_*.csv -o /tmp/shaper_calibrate_y.png This script will generate the charts /tmp/shaper_calibrate_x.png and /tmp/shaper_calibrate_y.png with frequency responses. You will also get the suggested frequencies for each input shaper, as well as which input shaper is recommended for your setup. For example: Fitted shaper 'zv' frequency = 34.4 Hz (vibrations = 4.0%, smoothing ~= 0.132) To avoid too much smoothing with 'zv', suggested max_accel <= 4500 mm/sec^2 Fitted shaper 'mzv' frequency = 34.6 Hz (vibrations = 0.0%, smoothing ~= 0.170) To avoid too much smoothing with 'mzv', suggested max_accel <= 3500 mm/sec^2 Fitted shaper 'ei' frequency = 41.4 Hz (vibrations = 0.0%, smoothing ~= 0.188) To avoid too much smoothing with 'ei', suggested max_accel <= 3200 mm/sec^2 Fitted shaper '2hump_ei' frequency = 51.8 Hz (vibrations = 0.0%, smoothing ~= 0.201) To avoid too much smoothing with '2hump_ei', suggested max_accel <= 3000 mm/sec^2 Fitted shaper '3hump_ei' frequency = 61.8 Hz (vibrations = 0.0%, smoothing ~= 0.215) To avoid too much smoothing with '3hump_ei', suggested max_accel <= 2800 mm/sec^2 Recommended shaper is mzv @ 34.6 Hz The suggested configuration can be added to [input_shaper] section of printer.cfg , e.g.: [input_shaper] shaper_freq_x: ... shaper_type_x: ... shaper_freq_y: 34.6 shaper_type_y: mzv [printer] max_accel: 3000 # should not exceed the estimated max_accel for X and Y axes or you can choose some other configuration yourself based on the generated charts: peaks in the power spectral density on the charts correspond to the resonance frequencies of the printer. Note that alternatively you can run the input shaper auto-calibration from Klipper directly , which can be convenient, for example, for the input shaper re-calibration . Bed-slinger printers \u00b6 If your printer is a bed slinger printer, you will need to change the location of the accelerometer between the measurements for X and Y axes: measure the resonances of X axis with the accelerometer attached to the toolhead and the resonances of Y axis - to the bed (the usual bed slinger setup). However, you can also connect two accelerometers simultaneously, though the ADXL345 must be connected to different boards (say, to an RPi and printer MCU board), or to two different physical SPI interfaces on the same board (rarely available). Then they can be configured in the following manner: [adxl345 hotend] # Assuming `hotend` chip is connected to an RPi cs_pin: rpi:None [adxl345 bed] # Assuming `bed` chip is connected to a printer MCU board cs_pin: ... # Printer board SPI chip select (CS) pin [resonance_tester] # Assuming the typical setup of the bed slinger printer accel_chip_x: adxl345 hotend accel_chip_y: adxl345 bed probe_points: ... Two MPUs can share one I2C bus, but they cannot measure simultaneously as the 400kbit/s I2C bus is not fast enough. One must have its AD0 pin pulled-down to 0V (address 104) and the other its AD0 pin pulled-up to 3.3V (address 105): [mpu9250 hotend] i2c_mcu: rpi i2c_bus: i2c.1 i2c_address: 104 # This MPU has pin AD0 pulled low [mpu9250 bed] i2c_mcu: rpi i2c_bus: i2c.1 i2c_address: 105 # This MPU has pin AD0 pulled high [resonance_tester] # Assuming the typical setup of the bed slinger printer accel_chip_x: mpu9250 hotend accel_chip_y: mpu9250 bed probe_points: ... [Test with each MPU individually before connecting both to the bus for easy debugging.] Then the commands TEST_RESONANCES AXIS=X and TEST_RESONANCES AXIS=Y will use the correct accelerometer for each axis. Max smoothing \u00b6 Keep in mind that the input shaper can create some smoothing in parts. Automatic tuning of the input shaper performed by calibrate_shaper.py script or SHAPER_CALIBRATE command tries not to exacerbate the smoothing, but at the same time they try to minimize the resulting vibrations. Sometimes they can make a sub-optimal choice of the shaper frequency, or maybe you simply prefer to have less smoothing in parts at the expense of a larger remaining vibrations. In these cases, you can request to limit the maximum smoothing from the input shaper. Let's consider the following results from the automatic tuning: Fitted shaper 'zv' frequency = 57.8 Hz (vibrations = 20.3%, smoothing ~= 0.053) To avoid too much smoothing with 'zv', suggested max_accel <= 13000 mm/sec^2 Fitted shaper 'mzv' frequency = 34.8 Hz (vibrations = 3.6%, smoothing ~= 0.168) To avoid too much smoothing with 'mzv', suggested max_accel <= 3600 mm/sec^2 Fitted shaper 'ei' frequency = 48.8 Hz (vibrations = 4.9%, smoothing ~= 0.135) To avoid too much smoothing with 'ei', suggested max_accel <= 4400 mm/sec^2 Fitted shaper '2hump_ei' frequency = 45.2 Hz (vibrations = 0.1%, smoothing ~= 0.264) To avoid too much smoothing with '2hump_ei', suggested max_accel <= 2200 mm/sec^2 Fitted shaper '3hump_ei' frequency = 48.0 Hz (vibrations = 0.0%, smoothing ~= 0.356) To avoid too much smoothing with '3hump_ei', suggested max_accel <= 1500 mm/sec^2 Recommended shaper is 2hump_ei @ 45.2 Hz Note that the reported smoothing values are some abstract projected values. These values can be used to compare different configurations: the higher the value, the more smoothing a shaper will create. However, these smoothing scores do not represent any real measure of smoothing, because the actual smoothing depends on max_accel and square_corner_velocity parameters. Therefore, you should print some test prints to see how much smoothing exactly a chosen configuration creates. In the example above the suggested shaper parameters are not bad, but what if you want to get less smoothing on the X axis? You can try to limit the maximum shaper smoothing using the following command: ~/klipper/scripts/calibrate_shaper.py /tmp/resonances_x_*.csv -o /tmp/shaper_calibrate_x.png --max_smoothing=0.2 which limits the smoothing to 0.2 score. Now you can get the following result: Fitted shaper 'zv' frequency = 55.4 Hz (vibrations = 19.7%, smoothing ~= 0.057) To avoid too much smoothing with 'zv', suggested max_accel <= 12000 mm/sec^2 Fitted shaper 'mzv' frequency = 34.6 Hz (vibrations = 3.6%, smoothing ~= 0.170) To avoid too much smoothing with 'mzv', suggested max_accel <= 3500 mm/sec^2 Fitted shaper 'ei' frequency = 48.2 Hz (vibrations = 4.8%, smoothing ~= 0.139) To avoid too much smoothing with 'ei', suggested max_accel <= 4300 mm/sec^2 Fitted shaper '2hump_ei' frequency = 52.0 Hz (vibrations = 2.7%, smoothing ~= 0.200) To avoid too much smoothing with '2hump_ei', suggested max_accel <= 3000 mm/sec^2 Fitted shaper '3hump_ei' frequency = 72.6 Hz (vibrations = 1.4%, smoothing ~= 0.155) To avoid too much smoothing with '3hump_ei', suggested max_accel <= 3900 mm/sec^2 Recommended shaper is 3hump_ei @ 72.6 Hz If you compare to the previously suggested parameters, the vibrations are a bit larger, but the smoothing is significantly smaller than previously, allowing larger maximum acceleration. When deciding which max_smoothing parameter to choose, you can use a trial-and-error approach. Try a few different values and see which results you get. Note that the actual smoothing produced by the input shaper depends, primarily, on the lowest resonance frequency of the printer: the higher the frequency of the lowest resonance - the smaller the smoothing. Therefore, if you request the script to find a configuration of the input shaper with the unrealistically small smoothing, it will be at the expense of increased ringing at the lowest resonance frequencies (which are, typically, also more prominently visible in prints). So, always double-check the projected remaining vibrations reported by the script and make sure they are not too high. Note that if you chose a good max_smoothing value for both of your axes, you can store it in the printer.cfg as [resonance_tester] accel_chip: ... probe_points: ... max_smoothing: 0.25 # an example Then, if you rerun the input shaper auto-tuning using SHAPER_CALIBRATE Klipper command in the future, it will use the stored max_smoothing value as a reference. Selecting max_accel \u00b6 Since the input shaper can create some smoothing in parts, especially at high accelerations, you will still need to choose the max_accel value that does not create too much smoothing in the printed parts. A calibration script provides an estimate for max_accel parameter that should not create too much smoothing. Note that the max_accel as displayed by the calibration script is only a theoretical maximum at which the respective shaper is still able to work without producing too much smoothing. It is by no means a recommendation to set this acceleration for printing. The maximum acceleration your printer is able to sustain depends on its mechanical properties and the maximum torque of the used stepper motors. Therefore, it is suggested to set max_accel in [printer] section that does not exceed the estimated values for X and Y axes, likely with some conservative safety margin. Alternatively, follow this part of the input shaper tuning guide and print the test model to choose max_accel parameter experimentally. The same notice applies to the input shaper auto-calibration with SHAPER_CALIBRATE command: it is still necessary to choose the right max_accel value after the auto-calibration, and the suggested acceleration limits will not be applied automatically. Keep in mind that the maximum acceleration without too much smoothing depends on the square_corner_velocity . The general recommendation is not to change it from its default value 5.0, and this is the value used by default by the calibrate_shaper.py script. If you did change it though, you should inform the script about it by passing --square_corner_velocity=... parameter, e.g. ~/klipper/scripts/calibrate_shaper.py /tmp/resonances_x_*.csv -o /tmp/shaper_calibrate_x.png --square_corner_velocity=10.0 so that it can calculate the maximum acceleration recommendations correctly. Note that the SHAPER_CALIBRATE command already takes the configured square_corner_velocity parameter into account, and there is no need to specify it explicitly. If you are doing a shaper re-calibration and the reported smoothing for the suggested shaper configuration is almost the same as what you got during the previous calibration, this step can be skipped. Unreliable measurements of resonance frequencies \u00b6 Sometimes the resonance measurements can produce bogus results, leading to the incorrect suggestions for the input shapers. This can be caused by a variety of reasons, including running fans on the toolhead, incorrect position or non-rigid mounting of the accelerometer, or mechanical problems such as loose belts or binding or bumpy axis. Keep in mind that all fans should be disabled for resonance testing, especially the noisy ones, and that the accelerometer should be rigidly mounted on the corresponding moving part (e.g. on the bed itself for the bed slinger, or on the extruder of the printer itself and not the carriage, and some people get better results by mounting the accelerometer on the nozzle itself). As for mechanical problems, the user should inspect if there is any fault that can be fixed with a moving axis (e.g. linear guide rails cleaned up and lubricated and V-slot wheels tension adjusted correctly). If none of that helps, a user may try the other shapers from the produced list besides the one recommended by default. Testing custom axes \u00b6 TEST_RESONANCES command supports custom axes. While this is not really useful for input shaper calibration, it can be used to study printer resonances in-depth and to check, for example, belt tension. To check the belt tension on CoreXY printers, execute TEST_RESONANCES AXIS=1,1 OUTPUT=raw_data TEST_RESONANCES AXIS=1,-1 OUTPUT=raw_data and use graph_accelerometer.py to process the generated files, e.g. ~/klipper/scripts/graph_accelerometer.py -c /tmp/raw_data_axis*.csv -o /tmp/resonances.png which will generate /tmp/resonances.png comparing the resonances. For Delta printers with the default tower placement (tower A ~= 210 degrees, B ~= 330 degrees, and C ~= 90 degrees), execute TEST_RESONANCES AXIS=0,1 OUTPUT=raw_data TEST_RESONANCES AXIS=-0.866025404,-0.5 OUTPUT=raw_data TEST_RESONANCES AXIS=0.866025404,-0.5 OUTPUT=raw_data and then use the same command ~/klipper/scripts/graph_accelerometer.py -c /tmp/raw_data_axis*.csv -o /tmp/resonances.png to generate /tmp/resonances.png comparing the resonances. Input Shaper auto-calibration \u00b6 Besides manually choosing the appropriate parameters for the input shaper feature, it is also possible to run the auto-tuning for the input shaper directly from Klipper. Run the following command via Octoprint terminal: SHAPER_CALIBRATE This will run the full test for both axes and generate the csv output ( /tmp/calibration_data_*.csv by default) for the frequency response and the suggested input shapers. You will also get the suggested frequencies for each input shaper, as well as which input shaper is recommended for your setup, on Octoprint console. For example: Calculating the best input shaper parameters for y axis Fitted shaper 'zv' frequency = 39.0 Hz (vibrations = 13.2%, smoothing ~= 0.105) To avoid too much smoothing with 'zv', suggested max_accel <= 5900 mm/sec^2 Fitted shaper 'mzv' frequency = 36.8 Hz (vibrations = 1.7%, smoothing ~= 0.150) To avoid too much smoothing with 'mzv', suggested max_accel <= 4000 mm/sec^2 Fitted shaper 'ei' frequency = 36.6 Hz (vibrations = 2.2%, smoothing ~= 0.240) To avoid too much smoothing with 'ei', suggested max_accel <= 2500 mm/sec^2 Fitted shaper '2hump_ei' frequency = 48.0 Hz (vibrations = 0.0%, smoothing ~= 0.234) To avoid too much smoothing with '2hump_ei', suggested max_accel <= 2500 mm/sec^2 Fitted shaper '3hump_ei' frequency = 59.0 Hz (vibrations = 0.0%, smoothing ~= 0.235) To avoid too much smoothing with '3hump_ei', suggested max_accel <= 2500 mm/sec^2 Recommended shaper_type_y = mzv, shaper_freq_y = 36.8 Hz If you agree with the suggested parameters, you can execute SAVE_CONFIG now to save them and restart the Klipper. Note that this will not update max_accel value in [printer] section. You should update it manually following the considerations in Selecting max_accel section. If your printer is a bed slinger printer, you can specify which axis to test, so that you can change the accelerometer mounting point between the tests (by default the test is performed for both axes): SHAPER_CALIBRATE AXIS=Y You can execute SAVE_CONFIG twice - after calibrating each axis. However, if you connected two accelerometers simultaneously, you simply run SHAPER_CALIBRATE without specifying an axis to calibrate the input shaper for both axes in one go. Input Shaper re-calibration \u00b6 SHAPER_CALIBRATE command can be also used to re-calibrate the input shaper in the future, especially if some changes to the printer that can affect its kinematics are made. One can either re-run the full calibration using SHAPER_CALIBRATE command, or restrict the auto-calibration to a single axis by supplying AXIS= parameter, like SHAPER_CALIBRATE AXIS=X Warning! It is not advisable to run the shaper auto-calibration very frequently (e.g. before every print, or every day). In order to determine resonance frequencies, auto-calibration creates intensive vibrations on each of the axes. Generally, 3D printers are not designed to withstand a prolonged exposure to vibrations near the resonance frequencies. Doing so may increase wear of the printer components and reduce their lifespan. There is also an increased risk of some parts unscrewing or becoming loose. Always check that all parts of the printer (including the ones that may normally not move) are securely fixed in place after each auto-tuning. Also, due to some noise in measurements, it is possible that the tuning results will be slightly different from one calibration run to another one. Still, it is not expected that the noise will affect the print quality too much. However, it is still advised to double-check the suggested parameters, and print some test prints before using them to confirm they are good. Offline processing of the accelerometer data \u00b6 It is possible to generate the raw accelerometer data and process it offline (e.g. on a host machine), for example to find resonances. In order to do so, run the following commands via Octoprint terminal: SET_INPUT_SHAPER SHAPER_FREQ_X=0 SHAPER_FREQ_Y=0 TEST_RESONANCES AXIS=X OUTPUT=raw_data ignoring any errors for SET_INPUT_SHAPER command. For TEST_RESONANCES command, specify the desired test axis. The raw data will be written into /tmp directory on the RPi. The raw data can also be obtained by running the command ACCELEROMETER_MEASURE command twice during some normal printer activity - first to start the measurements, and then to stop them and write the output file. Refer to G-Codes for more details. The data can be processed later by the following scripts: scripts/graph_accelerometer.py and scripts/calibrate_shaper.py . Both of them accept one or several raw csv files as the input depending on the mode. The graph_accelerometer.py script supports several modes of operation: plotting raw accelerometer data (use -r parameter), only 1 input is supported; plotting a frequency response (no extra parameters required), if multiple inputs are specified, the average frequency response is computed; comparison of the frequency response between several inputs (use -c parameter); you can additionally specify which accelerometer axis to consider via -a x , -a y or -a z parameter (if none specified, the sum of vibrations for all axes is used); plotting the spectrogram (use -s parameter), only 1 input is supported; you can additionally specify which accelerometer axis to consider via -a x , -a y or -a z parameter (if none specified, the sum of vibrations for all axes is used). Note that graph_accelerometer.py script supports only the raw_data*.csv files and not resonances*.csv or calibration_data*.csv files. For example, ~/klipper/scripts/graph_accelerometer.py /tmp/raw_data_x_*.csv -o /tmp/resonances_x.png -c -a z will plot the comparison of several /tmp/raw_data_x_*.csv files for Z axis to /tmp/resonances_x.png file. The shaper_calibrate.py script accepts 1 or several inputs and can run automatic tuning of the input shaper and suggest the best parameters that work well for all provided inputs. It prints the suggested parameters to the console, and can additionally generate the chart if -o output.png parameter is provided, or the CSV file if -c output.csv parameter is specified. Providing several inputs to shaper_calibrate.py script can be useful if running some advanced tuning of the input shapers, for example: Running TEST_RESONANCES AXIS=X OUTPUT=raw_data (and Y axis) for a single axis twice on a bed slinger printer with the accelerometer attached to the toolhead the first time, and the accelerometer attached to the bed the second time in order to detect axes cross-resonances and attempt to cancel them with input shapers. Running TEST_RESONANCES AXIS=Y OUTPUT=raw_data twice on a bed slinger with a glass bed and a magnetic surfaces (which is lighter) to find the input shaper parameters that work well for any print surface configuration. Combining the resonance data from multiple test points. Combining the resonance data from 2 axis (e.g. on a bed slinger printer to configure X-axis input_shaper from both X and Y axes resonances to cancel vibrations of the bed in case the nozzle 'catches' a print when moving in X axis direction).","title":"Measuring Resonances"},{"location":"Measuring_Resonances.html#measuring-resonances","text":"Klipper has built-in support for the ADXL345, MPU-9250, LIS2DW and LIS3DH compatible accelerometers which can be used to measure resonance frequencies of the printer for different axes, and auto-tune input shapers to compensate for resonances. Note that using accelerometers requires some soldering and crimping. The ADXL345 can be connected to the SPI interface of a Raspberry Pi or MCU board (it needs to be reasonably fast). The MPU family can be connected to the I2C interface of a Raspberry Pi directly, or to an I2C interface of an MCU board that supports 400kbit/s fast mode in Klipper. The LIS2DW and LIS3DH can be connected to either SPI or I2C with the same considerations as above. When sourcing accelerometers, be aware that there are a variety of different PCB board designs and different clones of them. If it is going to be connected to a 5V printer MCU ensure it has a voltage regulator and level shifters. For ADXL345s, make sure that the board supports SPI mode (a small number of boards appear to be hard-configured for I2C by pulling SDO to GND). For MPU-9250/MPU-9255/MPU-6515/MPU-6050/MPU-6500/ICM20948s and LIS2DW/LIS3DH there are also a variety of board designs and clones with different I2C pull-up resistors which will need supplementing.","title":"Measuring Resonances"},{"location":"Measuring_Resonances.html#mcus-with-klipper-i2c-fast-mode-support","text":"MCU Family MCU(s) Tested MCU(s) with Support Raspberry Pi 3B+, Pico 3A, 3A+, 3B, 4 AVR ATmega ATmega328p ATmega32u4, ATmega128, ATmega168, ATmega328, ATmega644p, ATmega1280, ATmega1284, ATmega2560 AVR AT90 - AT90usb646, AT90usb1286 SAMD SAMC21G18 SAMC21G18, SAMD21G18, SAMD21E18, SAMD21J18, SAMD21E15, SAMD51G19, SAMD51J19, SAMD51N19, SAMD51P20, SAME51J19, SAME51N19, SAME54P20","title":"MCUs with Klipper I2C fast-mode Support"},{"location":"Measuring_Resonances.html#installation-instructions","text":"","title":"Installation instructions"},{"location":"Measuring_Resonances.html#wiring","text":"An ethernet cable with shielded twisted pairs (cat5e or better) is recommended for signal integrity over a long distance. If you still experience signal integrity issues (SPI/I2C errors): Double check the wiring with a digital multimeter for: Correct connections when turned off (continuity) Correct power and ground voltages I2C only: Check the SCL and SDA lines' resistances to 3.3V are in the range of 900 ohms to 1.8K For full technical details consult chapter 7 of the I2C-bus specification and user manual UM10204 for fast-mode Shorten the cable Connect ethernet cable shielding only to the MCU board/Pi ground. Double-check your wiring before powering up to prevent damaging your MCU/Raspberry Pi or the accelerometer.","title":"Wiring"},{"location":"Measuring_Resonances.html#spi-accelerometers","text":"Suggested twisted pair order for three twisted pairs: GND+MISO 3.3V+MOSI SCLK+CS Note that unlike a cable shield, GND must be connected at both ends.","title":"SPI Accelerometers"},{"location":"Measuring_Resonances.html#adxl345","text":"","title":"ADXL345"},{"location":"Measuring_Resonances.html#direct-to-raspberry-pi","text":"Note: Many MCUs will work with an ADXL345 in SPI mode (e.g. Pi Pico), wiring and configuration will vary according to your specific board and available pins. You need to connect ADXL345 to your Raspberry Pi via SPI. Note that the I2C connection, which is suggested by ADXL345 documentation, has too low throughput and will not work . The recommended connection scheme: ADXL345 pin RPi pin RPi pin name 3V3 (or VCC) 01 3.3V DC power GND 06 Ground CS 24 GPIO08 (SPI0_CE0_N) SDO 21 GPIO09 (SPI0_MISO) SDA 19 GPIO10 (SPI0_MOSI) SCL 23 GPIO11 (SPI0_SCLK) Fritzing wiring diagrams for some of the ADXL345 boards:","title":"Direct to Raspberry Pi"},{"location":"Measuring_Resonances.html#using-raspberry-pi-pico","text":"You may connect the ADXL345 to your Raspberry Pi Pico and then connect the Pico to your Raspberry Pi via USB. This makes it easy to reuse the accelerometer on other Klipper devices, as you can connect via USB instead of GPIO. The Pico does not have much processing power, so make sure it is only running the accelerometer and not performing any other duties. In order to avoid damage to your RPi make sure to connect the ADXL345 to 3.3V only. Depending on the board's layout, a level shifter may be present, which makes 5V dangerous for your RPi. ADXL345 pin Pico pin Pico pin name 3V3 (or VCC) 36 3.3V DC power GND 38 Ground CS 2 GP1 (SPI0_CSn) SDO 1 GP0 (SPI0_RX) SDA 5 GP3 (SPI0_TX) SCL 4 GP2 (SPI0_SCK) Wiring diagrams for some of the ADXL345 boards:","title":"Using Raspberry Pi Pico"},{"location":"Measuring_Resonances.html#i2c-accelerometers","text":"Suggested twisted pair order for three pairs (preferred): 3.3V+GND SDA+GND SCL+GND or for two pairs: 3.3V+SDA GND+SCL Note that unlike a cable shield, any GND(s) should be connected at both ends.","title":"I2C Accelerometers"},{"location":"Measuring_Resonances.html#mpu-9250mpu-9255mpu-6515mpu-6050mpu-6500icm20948","text":"These accelerometers have been tested to work over I2C on the RPi, RP2040 (Pico) and AVR at 400kbit/s ( fast mode ). Some MPU accelerometer modules include pull-ups, but some are too large at 10K and must be changed or supplemented by smaller parallel resistors. Recommended connection scheme for I2C on the Raspberry Pi: MPU-9250 pin RPi pin RPi pin name VCC 01 3.3v DC power GND 09 Ground SDA 03 GPIO02 (SDA1) SCL 05 GPIO03 (SCL1) The RPi has built-in 1.8K pull-ups on both SCL and SDA. Recommended connection scheme for I2C (i2c0a) on the RP2040: MPU-9250 pin RP2040 pin RP2040 pin name VCC 36 3v3 GND 38 Ground SDA 01 GP0 (I2C0 SDA) SCL 02 GP1 (I2C0 SCL) The Pico does not include any built-in I2C pull-up resistors.","title":"MPU-9250/MPU-9255/MPU-6515/MPU-6050/MPU-6500/ICM20948"},{"location":"Measuring_Resonances.html#recommended-connection-scheme-for-i2ctwi-on-the-avr-atmega328p-arduino-nano","text":"MPU-9250 pin Atmega328P TQFP32 pin Atmega328P pin name Arduino Nano pin VCC 39 - - GND 38 Ground GND SDA 27 SDA A4 SCL 28 SCL A5 The Arduino Nano does not include any built-in pull-up resistors nor a 3.3V power pin.","title":"Recommended connection scheme for I2C(TWI) on the AVR ATmega328P Arduino Nano:"},{"location":"Measuring_Resonances.html#mounting-the-accelerometer","text":"The accelerometer must be attached to the toolhead. One needs to design a proper mount that fits their own 3D printer. It is better to align the axes of the accelerometer with the printer's axes (but if it makes it more convenient, axes can be swapped - i.e. no need to align X axis with X and so forth - it should be fine even if Z axis of accelerometer is X axis of the printer, etc.). An example of mounting ADXL345 on the SmartEffector: Note that on a bed slinger printer one must design 2 mounts: one for the toolhead and one for the bed, and run the measurements twice. See the corresponding section for more details. Attention: make sure the accelerometer and any screws that hold it in place do not touch any metal parts of the printer. Basically, the mount must be designed such as to ensure the electrical isolation of the accelerometer from the printer frame. Failing to ensure that can create a ground loop in the system that may damage the electronics.","title":"Mounting the accelerometer"},{"location":"Measuring_Resonances.html#software-installation","text":"Note that resonance measurements and shaper auto-calibration require additional software dependencies not installed by default. First, run on your Raspberry Pi the following commands: sudo apt update sudo apt install python3-numpy python3-matplotlib libatlas-base-dev libopenblas-dev Next, in order to install NumPy in the Klipper environment, run the command: ~/klippy-env/bin/pip install -v \"numpy<1.26\" Note that, depending on the performance of the CPU, it may take a lot of time, up to 10-20 minutes. Be patient and wait for the completion of the installation. On some occasions, if the board has too little RAM the installation may fail and you will need to enable swap. Also note the forced version, due to newer versions of NumPY having requirements that may not be satisfied in some klipper python environments. Once installed please check that no errors show from the command: ~/klippy-env/bin/python -c 'import numpy;' The correct output should simply be a new line.","title":"Software installation"},{"location":"Measuring_Resonances.html#configure-adxl345-with-rpi","text":"First, check and follow the instructions in the RPi Microcontroller document to setup the \"linux mcu\" on the Raspberry Pi. This will configure a second Klipper instance that runs on your Pi. Make sure the Linux SPI driver is enabled by running sudo raspi-config and enabling SPI under the \"Interfacing options\" menu. Add the following to the printer.cfg file: [mcu rpi] serial: /tmp/klipper_host_mcu [adxl345] cs_pin: rpi:None [resonance_tester] accel_chip: adxl345 probe_points: 100, 100, 20 # an example It is advised to start with 1 probe point, in the middle of the print bed, slightly above it.","title":"Configure ADXL345 With RPi"},{"location":"Measuring_Resonances.html#configure-adxl345-with-pi-pico","text":"","title":"Configure ADXL345 With Pi Pico"},{"location":"Measuring_Resonances.html#flash-the-pico-firmware","text":"On your Raspberry Pi, compile the firmware for the Pico. cd ~/klipper make clean make menuconfig Now, while holding down the BOOTSEL button on the Pico, connect the Pico to the Raspberry Pi via USB. Compile and flash the firmware. make flash FLASH_DEVICE=first If that fails, you will be told which FLASH_DEVICE to use. In this example, that's make flash FLASH_DEVICE=2e8a:0003 .","title":"Flash the Pico Firmware"},{"location":"Measuring_Resonances.html#configure-the-connection","text":"The Pico will now reboot with the new firmware and should show up as a serial device. Find the pico serial device with ls /dev/serial/by-id/* . You can now add an adxl.cfg file with the following settings: [mcu adxl] # Change <mySerial> to whatever you found above. For example, # usb-Klipper_rp2040_E661640843545B2E-if00 serial: /dev/serial/by-id/usb-Klipper_rp2040_<mySerial> [adxl345] cs_pin: adxl:gpio1 spi_bus: spi0a axes_map: x,z,y [resonance_tester] accel_chip: adxl345 probe_points: # Somewhere slightly above the middle of your print bed 147,154, 20 [output_pin power_mode] # Improve power stability pin: adxl:gpio23 If setting up the ADXL345 configuration in a separate file, as shown above, you'll also want to modify your printer.cfg file to include this: [include adxl.cfg] # Comment this out when you disconnect the accelerometer Restart Klipper via the RESTART command.","title":"Configure the Connection"},{"location":"Measuring_Resonances.html#configure-lis2dw-series-over-spi","text":"[mcu lis] # Change <mySerial> to whatever you found above. For example, # usb-Klipper_rp2040_E661640843545B2E-if00 serial: /dev/serial/by-id/usb-Klipper_rp2040_<mySerial> [lis2dw] cs_pin: lis:gpio1 spi_bus: spi0a axes_map: x,z,y [resonance_tester] accel_chip: lis2dw probe_points: # Somewhere slightly above the middle of your print bed 147,154, 20","title":"Configure LIS2DW series over SPI"},{"location":"Measuring_Resonances.html#configure-mpu-60009000-series-with-rpi","text":"Make sure the Linux I2C driver is enabled and the baud rate is set to 400000 (see Enabling I2C section for more details). Then, add the following to the printer.cfg: [mcu rpi] serial: /tmp/klipper_host_mcu [mpu9250] i2c_mcu: rpi i2c_bus: i2c.1 [resonance_tester] accel_chip: mpu9250 probe_points: 100, 100, 20 # an example If you are using the ICM20948, replace instances of \"mpu9250\" with \"icm20948\".","title":"Configure MPU-6000/9000 series With RPi"},{"location":"Measuring_Resonances.html#configure-mpu-9520-compatibles-with-pico","text":"Pico I2C is set to 400000 on default. Simply add the following to the printer.cfg: [mcu pico] serial: /dev/serial/by-id/<your Pico's serial ID> [mpu9250] i2c_mcu: pico i2c_bus: i2c0a [resonance_tester] accel_chip: mpu9250 probe_points: 100, 100, 20 # an example [static_digital_output pico_3V3pwm] # Improve power stability pins: pico:gpio23 If you are using the ICM20948, replace instances of \"mpu9250\" with \"icm20948\".","title":"Configure MPU-9520 Compatibles With Pico"},{"location":"Measuring_Resonances.html#configure-mpu-9520-compatibles-with-avr","text":"AVR I2C will be set to 400000 by the mpu9250 option. Simply add the following to the printer.cfg: [mcu nano] serial: /dev/serial/by-id/<your nano's serial ID> [mpu9250] i2c_mcu: nano [resonance_tester] accel_chip: mpu9250 probe_points: 100, 100, 20 # an example If you are using the ICM20948, replace instances of \"mpu9250\" with \"icm20948\". Restart Klipper via the RESTART command.","title":"Configure MPU-9520 Compatibles with AVR"},{"location":"Measuring_Resonances.html#measuring-the-resonances","text":"","title":"Measuring the resonances"},{"location":"Measuring_Resonances.html#checking-the-setup","text":"Now you can test a connection. For \"non bed-slingers\" (e.g. one accelerometer), in Octoprint, enter ACCELEROMETER_QUERY For \"bed-slingers\" (e.g. more than one accelerometer), enter ACCELEROMETER_QUERY CHIP=<chip> where <chip> is the name of the chip as-entered, e.g. CHIP=bed (see: bed-slinger ) for all installed accelerometer chips. You should see the current measurements from the accelerometer, including the free-fall acceleration, e.g. Recv: // adxl345 values (x, y, z): 470.719200, 941.438400, 9728.196800 If you get an error like Invalid adxl345 id (got xx vs e5) , where xx is some other ID, immediately try again. There's an issue with SPI initialization. If you still get an error, it is indicative of the connection problem with ADXL345, or the faulty sensor. Double-check the power, the wiring (that it matches the schematics, no wire is broken or loose, etc.), and soldering quality. If you are using a MPU-9250 compatible accelerometer and it shows up as mpu-unknown , use with caution! They are probably refurbished chips! Next, try running MEASURE_AXES_NOISE in Octoprint, you should get some baseline numbers for the noise of accelerometer on the axes (should be somewhere in the range of ~1-100). Too high axes noise (e.g. 1000 and more) can be indicative of the sensor issues, problems with its power, or too noisy imbalanced fans on a 3D printer.","title":"Checking the setup"},{"location":"Measuring_Resonances.html#measuring-the-resonances_1","text":"Now you can run some real-life tests. Run the following command: TEST_RESONANCES AXIS=X Note that it will create vibrations on X axis. It will also disable input shaping if it was enabled previously, as it is not valid to run the resonance testing with the input shaper enabled. Attention! Be sure to observe the printer for the first time, to make sure the vibrations do not become too violent ( M112 command can be used to abort the test in case of emergency; hopefully it will not come to this though). If the vibrations do get too strong, you can attempt to specify a lower than the default value for accel_per_hz parameter in [resonance_tester] section, e.g. [resonance_tester] accel_chip: adxl345 accel_per_hz: 50 # default is 75 probe_points: ... If it works for X axis, run for Y axis as well: TEST_RESONANCES AXIS=Y This will generate 2 CSV files ( /tmp/resonances_x_*.csv and /tmp/resonances_y_*.csv ). These files can be processed with the stand-alone script on a Raspberry Pi. This script is intended to be run with a single CSV file for each axis measured, although it can be used with multiple CSV files if you desire to average the results. Averaging results can be useful, for example, if resonance tests were done at multiple test points. Delete the extra CSV files if you do not desire to average them. ~/klipper/scripts/calibrate_shaper.py /tmp/resonances_x_*.csv -o /tmp/shaper_calibrate_x.png ~/klipper/scripts/calibrate_shaper.py /tmp/resonances_y_*.csv -o /tmp/shaper_calibrate_y.png This script will generate the charts /tmp/shaper_calibrate_x.png and /tmp/shaper_calibrate_y.png with frequency responses. You will also get the suggested frequencies for each input shaper, as well as which input shaper is recommended for your setup. For example: Fitted shaper 'zv' frequency = 34.4 Hz (vibrations = 4.0%, smoothing ~= 0.132) To avoid too much smoothing with 'zv', suggested max_accel <= 4500 mm/sec^2 Fitted shaper 'mzv' frequency = 34.6 Hz (vibrations = 0.0%, smoothing ~= 0.170) To avoid too much smoothing with 'mzv', suggested max_accel <= 3500 mm/sec^2 Fitted shaper 'ei' frequency = 41.4 Hz (vibrations = 0.0%, smoothing ~= 0.188) To avoid too much smoothing with 'ei', suggested max_accel <= 3200 mm/sec^2 Fitted shaper '2hump_ei' frequency = 51.8 Hz (vibrations = 0.0%, smoothing ~= 0.201) To avoid too much smoothing with '2hump_ei', suggested max_accel <= 3000 mm/sec^2 Fitted shaper '3hump_ei' frequency = 61.8 Hz (vibrations = 0.0%, smoothing ~= 0.215) To avoid too much smoothing with '3hump_ei', suggested max_accel <= 2800 mm/sec^2 Recommended shaper is mzv @ 34.6 Hz The suggested configuration can be added to [input_shaper] section of printer.cfg , e.g.: [input_shaper] shaper_freq_x: ... shaper_type_x: ... shaper_freq_y: 34.6 shaper_type_y: mzv [printer] max_accel: 3000 # should not exceed the estimated max_accel for X and Y axes or you can choose some other configuration yourself based on the generated charts: peaks in the power spectral density on the charts correspond to the resonance frequencies of the printer. Note that alternatively you can run the input shaper auto-calibration from Klipper directly , which can be convenient, for example, for the input shaper re-calibration .","title":"Measuring the resonances"},{"location":"Measuring_Resonances.html#bed-slinger-printers","text":"If your printer is a bed slinger printer, you will need to change the location of the accelerometer between the measurements for X and Y axes: measure the resonances of X axis with the accelerometer attached to the toolhead and the resonances of Y axis - to the bed (the usual bed slinger setup). However, you can also connect two accelerometers simultaneously, though the ADXL345 must be connected to different boards (say, to an RPi and printer MCU board), or to two different physical SPI interfaces on the same board (rarely available). Then they can be configured in the following manner: [adxl345 hotend] # Assuming `hotend` chip is connected to an RPi cs_pin: rpi:None [adxl345 bed] # Assuming `bed` chip is connected to a printer MCU board cs_pin: ... # Printer board SPI chip select (CS) pin [resonance_tester] # Assuming the typical setup of the bed slinger printer accel_chip_x: adxl345 hotend accel_chip_y: adxl345 bed probe_points: ... Two MPUs can share one I2C bus, but they cannot measure simultaneously as the 400kbit/s I2C bus is not fast enough. One must have its AD0 pin pulled-down to 0V (address 104) and the other its AD0 pin pulled-up to 3.3V (address 105): [mpu9250 hotend] i2c_mcu: rpi i2c_bus: i2c.1 i2c_address: 104 # This MPU has pin AD0 pulled low [mpu9250 bed] i2c_mcu: rpi i2c_bus: i2c.1 i2c_address: 105 # This MPU has pin AD0 pulled high [resonance_tester] # Assuming the typical setup of the bed slinger printer accel_chip_x: mpu9250 hotend accel_chip_y: mpu9250 bed probe_points: ... [Test with each MPU individually before connecting both to the bus for easy debugging.] Then the commands TEST_RESONANCES AXIS=X and TEST_RESONANCES AXIS=Y will use the correct accelerometer for each axis.","title":"Bed-slinger printers"},{"location":"Measuring_Resonances.html#max-smoothing","text":"Keep in mind that the input shaper can create some smoothing in parts. Automatic tuning of the input shaper performed by calibrate_shaper.py script or SHAPER_CALIBRATE command tries not to exacerbate the smoothing, but at the same time they try to minimize the resulting vibrations. Sometimes they can make a sub-optimal choice of the shaper frequency, or maybe you simply prefer to have less smoothing in parts at the expense of a larger remaining vibrations. In these cases, you can request to limit the maximum smoothing from the input shaper. Let's consider the following results from the automatic tuning: Fitted shaper 'zv' frequency = 57.8 Hz (vibrations = 20.3%, smoothing ~= 0.053) To avoid too much smoothing with 'zv', suggested max_accel <= 13000 mm/sec^2 Fitted shaper 'mzv' frequency = 34.8 Hz (vibrations = 3.6%, smoothing ~= 0.168) To avoid too much smoothing with 'mzv', suggested max_accel <= 3600 mm/sec^2 Fitted shaper 'ei' frequency = 48.8 Hz (vibrations = 4.9%, smoothing ~= 0.135) To avoid too much smoothing with 'ei', suggested max_accel <= 4400 mm/sec^2 Fitted shaper '2hump_ei' frequency = 45.2 Hz (vibrations = 0.1%, smoothing ~= 0.264) To avoid too much smoothing with '2hump_ei', suggested max_accel <= 2200 mm/sec^2 Fitted shaper '3hump_ei' frequency = 48.0 Hz (vibrations = 0.0%, smoothing ~= 0.356) To avoid too much smoothing with '3hump_ei', suggested max_accel <= 1500 mm/sec^2 Recommended shaper is 2hump_ei @ 45.2 Hz Note that the reported smoothing values are some abstract projected values. These values can be used to compare different configurations: the higher the value, the more smoothing a shaper will create. However, these smoothing scores do not represent any real measure of smoothing, because the actual smoothing depends on max_accel and square_corner_velocity parameters. Therefore, you should print some test prints to see how much smoothing exactly a chosen configuration creates. In the example above the suggested shaper parameters are not bad, but what if you want to get less smoothing on the X axis? You can try to limit the maximum shaper smoothing using the following command: ~/klipper/scripts/calibrate_shaper.py /tmp/resonances_x_*.csv -o /tmp/shaper_calibrate_x.png --max_smoothing=0.2 which limits the smoothing to 0.2 score. Now you can get the following result: Fitted shaper 'zv' frequency = 55.4 Hz (vibrations = 19.7%, smoothing ~= 0.057) To avoid too much smoothing with 'zv', suggested max_accel <= 12000 mm/sec^2 Fitted shaper 'mzv' frequency = 34.6 Hz (vibrations = 3.6%, smoothing ~= 0.170) To avoid too much smoothing with 'mzv', suggested max_accel <= 3500 mm/sec^2 Fitted shaper 'ei' frequency = 48.2 Hz (vibrations = 4.8%, smoothing ~= 0.139) To avoid too much smoothing with 'ei', suggested max_accel <= 4300 mm/sec^2 Fitted shaper '2hump_ei' frequency = 52.0 Hz (vibrations = 2.7%, smoothing ~= 0.200) To avoid too much smoothing with '2hump_ei', suggested max_accel <= 3000 mm/sec^2 Fitted shaper '3hump_ei' frequency = 72.6 Hz (vibrations = 1.4%, smoothing ~= 0.155) To avoid too much smoothing with '3hump_ei', suggested max_accel <= 3900 mm/sec^2 Recommended shaper is 3hump_ei @ 72.6 Hz If you compare to the previously suggested parameters, the vibrations are a bit larger, but the smoothing is significantly smaller than previously, allowing larger maximum acceleration. When deciding which max_smoothing parameter to choose, you can use a trial-and-error approach. Try a few different values and see which results you get. Note that the actual smoothing produced by the input shaper depends, primarily, on the lowest resonance frequency of the printer: the higher the frequency of the lowest resonance - the smaller the smoothing. Therefore, if you request the script to find a configuration of the input shaper with the unrealistically small smoothing, it will be at the expense of increased ringing at the lowest resonance frequencies (which are, typically, also more prominently visible in prints). So, always double-check the projected remaining vibrations reported by the script and make sure they are not too high. Note that if you chose a good max_smoothing value for both of your axes, you can store it in the printer.cfg as [resonance_tester] accel_chip: ... probe_points: ... max_smoothing: 0.25 # an example Then, if you rerun the input shaper auto-tuning using SHAPER_CALIBRATE Klipper command in the future, it will use the stored max_smoothing value as a reference.","title":"Max smoothing"},{"location":"Measuring_Resonances.html#selecting-max_accel","text":"Since the input shaper can create some smoothing in parts, especially at high accelerations, you will still need to choose the max_accel value that does not create too much smoothing in the printed parts. A calibration script provides an estimate for max_accel parameter that should not create too much smoothing. Note that the max_accel as displayed by the calibration script is only a theoretical maximum at which the respective shaper is still able to work without producing too much smoothing. It is by no means a recommendation to set this acceleration for printing. The maximum acceleration your printer is able to sustain depends on its mechanical properties and the maximum torque of the used stepper motors. Therefore, it is suggested to set max_accel in [printer] section that does not exceed the estimated values for X and Y axes, likely with some conservative safety margin. Alternatively, follow this part of the input shaper tuning guide and print the test model to choose max_accel parameter experimentally. The same notice applies to the input shaper auto-calibration with SHAPER_CALIBRATE command: it is still necessary to choose the right max_accel value after the auto-calibration, and the suggested acceleration limits will not be applied automatically. Keep in mind that the maximum acceleration without too much smoothing depends on the square_corner_velocity . The general recommendation is not to change it from its default value 5.0, and this is the value used by default by the calibrate_shaper.py script. If you did change it though, you should inform the script about it by passing --square_corner_velocity=... parameter, e.g. ~/klipper/scripts/calibrate_shaper.py /tmp/resonances_x_*.csv -o /tmp/shaper_calibrate_x.png --square_corner_velocity=10.0 so that it can calculate the maximum acceleration recommendations correctly. Note that the SHAPER_CALIBRATE command already takes the configured square_corner_velocity parameter into account, and there is no need to specify it explicitly. If you are doing a shaper re-calibration and the reported smoothing for the suggested shaper configuration is almost the same as what you got during the previous calibration, this step can be skipped.","title":"Selecting max_accel"},{"location":"Measuring_Resonances.html#unreliable-measurements-of-resonance-frequencies","text":"Sometimes the resonance measurements can produce bogus results, leading to the incorrect suggestions for the input shapers. This can be caused by a variety of reasons, including running fans on the toolhead, incorrect position or non-rigid mounting of the accelerometer, or mechanical problems such as loose belts or binding or bumpy axis. Keep in mind that all fans should be disabled for resonance testing, especially the noisy ones, and that the accelerometer should be rigidly mounted on the corresponding moving part (e.g. on the bed itself for the bed slinger, or on the extruder of the printer itself and not the carriage, and some people get better results by mounting the accelerometer on the nozzle itself). As for mechanical problems, the user should inspect if there is any fault that can be fixed with a moving axis (e.g. linear guide rails cleaned up and lubricated and V-slot wheels tension adjusted correctly). If none of that helps, a user may try the other shapers from the produced list besides the one recommended by default.","title":"Unreliable measurements of resonance frequencies"},{"location":"Measuring_Resonances.html#testing-custom-axes","text":"TEST_RESONANCES command supports custom axes. While this is not really useful for input shaper calibration, it can be used to study printer resonances in-depth and to check, for example, belt tension. To check the belt tension on CoreXY printers, execute TEST_RESONANCES AXIS=1,1 OUTPUT=raw_data TEST_RESONANCES AXIS=1,-1 OUTPUT=raw_data and use graph_accelerometer.py to process the generated files, e.g. ~/klipper/scripts/graph_accelerometer.py -c /tmp/raw_data_axis*.csv -o /tmp/resonances.png which will generate /tmp/resonances.png comparing the resonances. For Delta printers with the default tower placement (tower A ~= 210 degrees, B ~= 330 degrees, and C ~= 90 degrees), execute TEST_RESONANCES AXIS=0,1 OUTPUT=raw_data TEST_RESONANCES AXIS=-0.866025404,-0.5 OUTPUT=raw_data TEST_RESONANCES AXIS=0.866025404,-0.5 OUTPUT=raw_data and then use the same command ~/klipper/scripts/graph_accelerometer.py -c /tmp/raw_data_axis*.csv -o /tmp/resonances.png to generate /tmp/resonances.png comparing the resonances.","title":"Testing custom axes"},{"location":"Measuring_Resonances.html#input-shaper-auto-calibration","text":"Besides manually choosing the appropriate parameters for the input shaper feature, it is also possible to run the auto-tuning for the input shaper directly from Klipper. Run the following command via Octoprint terminal: SHAPER_CALIBRATE This will run the full test for both axes and generate the csv output ( /tmp/calibration_data_*.csv by default) for the frequency response and the suggested input shapers. You will also get the suggested frequencies for each input shaper, as well as which input shaper is recommended for your setup, on Octoprint console. For example: Calculating the best input shaper parameters for y axis Fitted shaper 'zv' frequency = 39.0 Hz (vibrations = 13.2%, smoothing ~= 0.105) To avoid too much smoothing with 'zv', suggested max_accel <= 5900 mm/sec^2 Fitted shaper 'mzv' frequency = 36.8 Hz (vibrations = 1.7%, smoothing ~= 0.150) To avoid too much smoothing with 'mzv', suggested max_accel <= 4000 mm/sec^2 Fitted shaper 'ei' frequency = 36.6 Hz (vibrations = 2.2%, smoothing ~= 0.240) To avoid too much smoothing with 'ei', suggested max_accel <= 2500 mm/sec^2 Fitted shaper '2hump_ei' frequency = 48.0 Hz (vibrations = 0.0%, smoothing ~= 0.234) To avoid too much smoothing with '2hump_ei', suggested max_accel <= 2500 mm/sec^2 Fitted shaper '3hump_ei' frequency = 59.0 Hz (vibrations = 0.0%, smoothing ~= 0.235) To avoid too much smoothing with '3hump_ei', suggested max_accel <= 2500 mm/sec^2 Recommended shaper_type_y = mzv, shaper_freq_y = 36.8 Hz If you agree with the suggested parameters, you can execute SAVE_CONFIG now to save them and restart the Klipper. Note that this will not update max_accel value in [printer] section. You should update it manually following the considerations in Selecting max_accel section. If your printer is a bed slinger printer, you can specify which axis to test, so that you can change the accelerometer mounting point between the tests (by default the test is performed for both axes): SHAPER_CALIBRATE AXIS=Y You can execute SAVE_CONFIG twice - after calibrating each axis. However, if you connected two accelerometers simultaneously, you simply run SHAPER_CALIBRATE without specifying an axis to calibrate the input shaper for both axes in one go.","title":"Input Shaper auto-calibration"},{"location":"Measuring_Resonances.html#input-shaper-re-calibration","text":"SHAPER_CALIBRATE command can be also used to re-calibrate the input shaper in the future, especially if some changes to the printer that can affect its kinematics are made. One can either re-run the full calibration using SHAPER_CALIBRATE command, or restrict the auto-calibration to a single axis by supplying AXIS= parameter, like SHAPER_CALIBRATE AXIS=X Warning! It is not advisable to run the shaper auto-calibration very frequently (e.g. before every print, or every day). In order to determine resonance frequencies, auto-calibration creates intensive vibrations on each of the axes. Generally, 3D printers are not designed to withstand a prolonged exposure to vibrations near the resonance frequencies. Doing so may increase wear of the printer components and reduce their lifespan. There is also an increased risk of some parts unscrewing or becoming loose. Always check that all parts of the printer (including the ones that may normally not move) are securely fixed in place after each auto-tuning. Also, due to some noise in measurements, it is possible that the tuning results will be slightly different from one calibration run to another one. Still, it is not expected that the noise will affect the print quality too much. However, it is still advised to double-check the suggested parameters, and print some test prints before using them to confirm they are good.","title":"Input Shaper re-calibration"},{"location":"Measuring_Resonances.html#offline-processing-of-the-accelerometer-data","text":"It is possible to generate the raw accelerometer data and process it offline (e.g. on a host machine), for example to find resonances. In order to do so, run the following commands via Octoprint terminal: SET_INPUT_SHAPER SHAPER_FREQ_X=0 SHAPER_FREQ_Y=0 TEST_RESONANCES AXIS=X OUTPUT=raw_data ignoring any errors for SET_INPUT_SHAPER command. For TEST_RESONANCES command, specify the desired test axis. The raw data will be written into /tmp directory on the RPi. The raw data can also be obtained by running the command ACCELEROMETER_MEASURE command twice during some normal printer activity - first to start the measurements, and then to stop them and write the output file. Refer to G-Codes for more details. The data can be processed later by the following scripts: scripts/graph_accelerometer.py and scripts/calibrate_shaper.py . Both of them accept one or several raw csv files as the input depending on the mode. The graph_accelerometer.py script supports several modes of operation: plotting raw accelerometer data (use -r parameter), only 1 input is supported; plotting a frequency response (no extra parameters required), if multiple inputs are specified, the average frequency response is computed; comparison of the frequency response between several inputs (use -c parameter); you can additionally specify which accelerometer axis to consider via -a x , -a y or -a z parameter (if none specified, the sum of vibrations for all axes is used); plotting the spectrogram (use -s parameter), only 1 input is supported; you can additionally specify which accelerometer axis to consider via -a x , -a y or -a z parameter (if none specified, the sum of vibrations for all axes is used). Note that graph_accelerometer.py script supports only the raw_data*.csv files and not resonances*.csv or calibration_data*.csv files. For example, ~/klipper/scripts/graph_accelerometer.py /tmp/raw_data_x_*.csv -o /tmp/resonances_x.png -c -a z will plot the comparison of several /tmp/raw_data_x_*.csv files for Z axis to /tmp/resonances_x.png file. The shaper_calibrate.py script accepts 1 or several inputs and can run automatic tuning of the input shaper and suggest the best parameters that work well for all provided inputs. It prints the suggested parameters to the console, and can additionally generate the chart if -o output.png parameter is provided, or the CSV file if -c output.csv parameter is specified. Providing several inputs to shaper_calibrate.py script can be useful if running some advanced tuning of the input shapers, for example: Running TEST_RESONANCES AXIS=X OUTPUT=raw_data (and Y axis) for a single axis twice on a bed slinger printer with the accelerometer attached to the toolhead the first time, and the accelerometer attached to the bed the second time in order to detect axes cross-resonances and attempt to cancel them with input shapers. Running TEST_RESONANCES AXIS=Y OUTPUT=raw_data twice on a bed slinger with a glass bed and a magnetic surfaces (which is lighter) to find the input shaper parameters that work well for any print surface configuration. Combining the resonance data from multiple test points. Combining the resonance data from 2 axis (e.g. on a bed slinger printer to configure X-axis input_shaper from both X and Y axes resonances to cancel vibrations of the bed in case the nozzle 'catches' a print when moving in X axis direction).","title":"Offline processing of the accelerometer data"},{"location":"Multi_MCU_Homing.html","text":"Multiple Micro-controller Homing and Probing \u00b6 Klipper supports a mechanism for homing with an endstop attached to one micro-controller while its stepper motors are on a different micro-controller. This support is referred to as \"multi-mcu homing\". This feature is also used when a Z probe is on a different micro-controller than the Z stepper motors. This feature can be useful to simplify wiring, as it may be more convenient to attach an endstop or probe to a closer micro-controller. However, using this feature may result in \"overshoot\" of the stepper motors during homing and probing operations. The overshoot occurs due to possible message transmission delays between the micro-controller monitoring the endstop and the micro-controllers moving the stepper motors. The Klipper code is designed to limit this delay to no more than 25ms. (When multi-mcu homing is activated, the micro-controllers send periodic status messages and check that corresponding status messages are received within 25ms.) So, for example, if homing at 10mm/s then it is possible for an overshoot of up to 0.250mm (10mm/s * .025s == 0.250mm). Care should be taken when configuring multi-mcu homing to account for this type of overshoot. Using slower homing or probing speeds can reduce the overshoot. Stepper motor overshoot should not adversely impact the precision of the homing and probing procedure. The Klipper code will detect the overshoot and account for it in its calculations. However, it is important that the hardware design is capable of handling overshoot without causing damage to the machine. In order to use this \"multi-mcu homing\" capability the hardware must have predictably low latency between the host computer and all of the micro-controllers. Typically the round-trip time must be consistently less than 10ms. High latency (even for short periods) is likely to result in homing failures. Should high latency result in a failure (or if some other communication issue is detected) then Klipper will raise a \"Communication timeout during homing\" error. Note that an axis with multiple steppers (eg, stepper_z and stepper_z1 ) need to be on the same micro-controller in order to use multi-mcu homing. For example, if an endstop is on a separate micro-controller from stepper_z then stepper_z1 must be on the same micro-controller as stepper_z .","title":"Multiple Micro-controller Homing and Probing"},{"location":"Multi_MCU_Homing.html#multiple-micro-controller-homing-and-probing","text":"Klipper supports a mechanism for homing with an endstop attached to one micro-controller while its stepper motors are on a different micro-controller. This support is referred to as \"multi-mcu homing\". This feature is also used when a Z probe is on a different micro-controller than the Z stepper motors. This feature can be useful to simplify wiring, as it may be more convenient to attach an endstop or probe to a closer micro-controller. However, using this feature may result in \"overshoot\" of the stepper motors during homing and probing operations. The overshoot occurs due to possible message transmission delays between the micro-controller monitoring the endstop and the micro-controllers moving the stepper motors. The Klipper code is designed to limit this delay to no more than 25ms. (When multi-mcu homing is activated, the micro-controllers send periodic status messages and check that corresponding status messages are received within 25ms.) So, for example, if homing at 10mm/s then it is possible for an overshoot of up to 0.250mm (10mm/s * .025s == 0.250mm). Care should be taken when configuring multi-mcu homing to account for this type of overshoot. Using slower homing or probing speeds can reduce the overshoot. Stepper motor overshoot should not adversely impact the precision of the homing and probing procedure. The Klipper code will detect the overshoot and account for it in its calculations. However, it is important that the hardware design is capable of handling overshoot without causing damage to the machine. In order to use this \"multi-mcu homing\" capability the hardware must have predictably low latency between the host computer and all of the micro-controllers. Typically the round-trip time must be consistently less than 10ms. High latency (even for short periods) is likely to result in homing failures. Should high latency result in a failure (or if some other communication issue is detected) then Klipper will raise a \"Communication timeout during homing\" error. Note that an axis with multiple steppers (eg, stepper_z and stepper_z1 ) need to be on the same micro-controller in order to use multi-mcu homing. For example, if an endstop is on a separate micro-controller from stepper_z then stepper_z1 must be on the same micro-controller as stepper_z .","title":"Multiple Micro-controller Homing and Probing"},{"location":"OctoPrint.html","text":"OctoPrint for Klipper \u00b6 Klipper has a few options for its front ends, Octoprint was the first and original front end for Klipper. This document will give a brief overview of installing with this option. Install with OctoPi \u00b6 Start by installing OctoPi on the Raspberry Pi computer. Use OctoPi v0.17.0 or later - see the OctoPi releases for release information. One should verify that OctoPi boots and that the OctoPrint web server works. After connecting to the OctoPrint web page, follow the prompt to upgrade OctoPrint if needed. After installing OctoPi and upgrading OctoPrint, it will be necessary to ssh into the target machine to run a handful of system commands. Start by running these commands on your host device: If you do not have git installed, please do so with: sudo apt install git then proceed: cd ~ git clone https://github.com/Klipper3d/klipper ./klipper/scripts/install-octopi.sh The above will download Klipper, install the needed system dependencies, setup Klipper to run at system startup, and start the Klipper host software. It will require an internet connection and it may take a few minutes to complete. Installing with KIAUH \u00b6 KIAUH can be used to install OctoPrint on a variety of Linux based systems that run a form of Debian. More information can be found at https://github.com/dw-0/kiauh Configuring OctoPrint to use Klipper \u00b6 The OctoPrint web server needs to be configured to communicate with the Klipper host software. Using a web browser, login to the OctoPrint web page and then configure the following items: Navigate to the Settings tab (the wrench icon at the top of the page). Under \"Serial Connection\" in \"Additional serial ports\" add: ~/printer_data/comms/klippy.serial Then click \"Save\". In some older setups this address may be /tmp/printer Enter the Settings tab again and under \"Serial Connection\" change the \"Serial Port\" setting to the one added above. In the Settings tab, navigate to the \"Behavior\" sub-tab and select the \"Cancel any ongoing prints but stay connected to the printer\" option. Click \"Save\". From the main page, under the \"Connection\" section (at the top left of the page) make sure the \"Serial Port\" is set to the new additional one added and click \"Connect\". (If it is not in the available selection then try reloading the page.) Once connected, navigate to the \"Terminal\" tab and type \"status\" (without the quotes) into the command entry box and click \"Send\". The terminal window will likely report there is an error opening the config file - that means OctoPrint is successfully communicating with Klipper. Please proceed to Installation.md and the Building and flashing the micro-controller section","title":"OctoPrint for Klipper"},{"location":"OctoPrint.html#octoprint-for-klipper","text":"Klipper has a few options for its front ends, Octoprint was the first and original front end for Klipper. This document will give a brief overview of installing with this option.","title":"OctoPrint for Klipper"},{"location":"OctoPrint.html#install-with-octopi","text":"Start by installing OctoPi on the Raspberry Pi computer. Use OctoPi v0.17.0 or later - see the OctoPi releases for release information. One should verify that OctoPi boots and that the OctoPrint web server works. After connecting to the OctoPrint web page, follow the prompt to upgrade OctoPrint if needed. After installing OctoPi and upgrading OctoPrint, it will be necessary to ssh into the target machine to run a handful of system commands. Start by running these commands on your host device: If you do not have git installed, please do so with: sudo apt install git then proceed: cd ~ git clone https://github.com/Klipper3d/klipper ./klipper/scripts/install-octopi.sh The above will download Klipper, install the needed system dependencies, setup Klipper to run at system startup, and start the Klipper host software. It will require an internet connection and it may take a few minutes to complete.","title":"Install with OctoPi"},{"location":"OctoPrint.html#installing-with-kiauh","text":"KIAUH can be used to install OctoPrint on a variety of Linux based systems that run a form of Debian. More information can be found at https://github.com/dw-0/kiauh","title":"Installing with KIAUH"},{"location":"OctoPrint.html#configuring-octoprint-to-use-klipper","text":"The OctoPrint web server needs to be configured to communicate with the Klipper host software. Using a web browser, login to the OctoPrint web page and then configure the following items: Navigate to the Settings tab (the wrench icon at the top of the page). Under \"Serial Connection\" in \"Additional serial ports\" add: ~/printer_data/comms/klippy.serial Then click \"Save\". In some older setups this address may be /tmp/printer Enter the Settings tab again and under \"Serial Connection\" change the \"Serial Port\" setting to the one added above. In the Settings tab, navigate to the \"Behavior\" sub-tab and select the \"Cancel any ongoing prints but stay connected to the printer\" option. Click \"Save\". From the main page, under the \"Connection\" section (at the top left of the page) make sure the \"Serial Port\" is set to the new additional one added and click \"Connect\". (If it is not in the available selection then try reloading the page.) Once connected, navigate to the \"Terminal\" tab and type \"status\" (without the quotes) into the command entry box and click \"Send\". The terminal window will likely report there is an error opening the config file - that means OctoPrint is successfully communicating with Klipper. Please proceed to Installation.md and the Building and flashing the micro-controller section","title":"Configuring OctoPrint to use Klipper"},{"location":"Overview.html","text":"Overview \u00b6 Welcome to the Klipper documentation. If new to Klipper, start with the features and installation documents. Overview information \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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","title":"Overview"},{"location":"Overview.html#overview","text":"Welcome to the Klipper documentation. If new to Klipper, start with the features and installation documents.","title":"Overview"},{"location":"Overview.html#overview-information","text":"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.","title":"Overview information"},{"location":"Overview.html#installation-and-configuration","text":"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.","title":"Installation and Configuration"},{"location":"Overview.html#developer-documentation","text":"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.","title":"Developer Documentation"},{"location":"Overview.html#device-specific-documents","text":"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","title":"Device Specific Documents"},{"location":"Packaging.html","text":"Packaging Klipper \u00b6 Klipper is somewhat of a packaging anomaly among python programs, as it doesn't use setuptools to build and install. Some notes regarding how best to package it are as follows: C modules \u00b6 Klipper uses a C module to handle some kinematics calculations more quickly. This module needs to be compiled at packaging time to avoid introducing a runtime dependency on a compiler. To compile the C module, run python2 klippy/chelper/__init__.py . Compiling python code \u00b6 Many distributions have a policy of compiling all python code before packaging to improve startup time. You can do this by running python2 -m compileall klippy . Versioning \u00b6 If you are building a package of Klipper from git, it is usual practice not to ship a .git directory, so the versioning must be handled without git. To do this, use the script shipped in scripts/make_version.py which should be run as follows: python2 scripts/make_version.py YOURDISTRONAME > klippy/.version . Sample packaging script \u00b6 klipper-git is packaged for Arch Linux, and has a PKGBUILD (package build script) available at Arch User Repository .","title":"Packaging Klipper"},{"location":"Packaging.html#packaging-klipper","text":"Klipper is somewhat of a packaging anomaly among python programs, as it doesn't use setuptools to build and install. Some notes regarding how best to package it are as follows:","title":"Packaging Klipper"},{"location":"Packaging.html#c-modules","text":"Klipper uses a C module to handle some kinematics calculations more quickly. This module needs to be compiled at packaging time to avoid introducing a runtime dependency on a compiler. To compile the C module, run python2 klippy/chelper/__init__.py .","title":"C modules"},{"location":"Packaging.html#compiling-python-code","text":"Many distributions have a policy of compiling all python code before packaging to improve startup time. You can do this by running python2 -m compileall klippy .","title":"Compiling python code"},{"location":"Packaging.html#versioning","text":"If you are building a package of Klipper from git, it is usual practice not to ship a .git directory, so the versioning must be handled without git. To do this, use the script shipped in scripts/make_version.py which should be run as follows: python2 scripts/make_version.py YOURDISTRONAME > klippy/.version .","title":"Versioning"},{"location":"Packaging.html#sample-packaging-script","text":"klipper-git is packaged for Arch Linux, and has a PKGBUILD (package build script) available at Arch User Repository .","title":"Sample packaging script"},{"location":"Pressure_Advance.html","text":"Pressure advance \u00b6 This document provides information on tuning the \"pressure advance\" configuration variable for a particular nozzle and filament. The pressure advance feature can be helpful in reducing ooze. For more information on how pressure advance is implemented see the kinematics document. Tuning pressure advance \u00b6 Pressure advance does two useful things - it reduces ooze during non-extrude moves and it reduces blobbing during cornering. This guide uses the second feature (reducing blobbing during cornering) as a mechanism for tuning. In order to calibrate pressure advance the printer must be configured and operational as the tuning test involves printing and inspecting a test object. It is a good idea to read this document in full prior to running the test. Use a slicer to generate g-code for the large hollow square found in docs/prints/square_tower.stl . Use a high speed (eg, 100mm/s), zero infill, and a coarse layer height (the layer height should be around 75% of the nozzle diameter). Make sure any \"dynamic acceleration control\" and \"scarf joint\" seams are disabled in the slicer. Prepare for the test by issuing the following G-Code command: SET_VELOCITY_LIMIT SQUARE_CORNER_VELOCITY=1 ACCEL=500 This command makes the nozzle travel slower through corners to emphasize the effects of extruder pressure. Then for printers with a direct drive extruder run the command: TUNING_TOWER COMMAND=SET_PRESSURE_ADVANCE PARAMETER=ADVANCE START=0 FACTOR=.005 For long bowden extruders use: TUNING_TOWER COMMAND=SET_PRESSURE_ADVANCE PARAMETER=ADVANCE START=0 FACTOR=.020 Then print the object. When fully printed the test print looks like: The above TUNING_TOWER command instructs Klipper to alter the pressure_advance setting on each layer of the print. Higher layers in the print will have a larger pressure advance value set. Layers below the ideal pressure_advance setting will have blobbing at the corners, and layers above the ideal setting can lead to rounded corners and poor extrusion leading up to the corner. One can cancel the print early if one observes that the corners are no longer printing well (and thus one can avoid printing layers that are known to be above the ideal pressure_advance value). Inspect the print and then use a digital calipers to find the height that has the best quality corners. When in doubt, prefer a lower height. The pressure_advance value can then be calculated as pressure_advance = <start> + <measured_height> * <factor> . (For example, 0 + 12.90 * .020 would be .258 .) It is possible to choose custom settings for START and FACTOR if that helps identify the best pressure advance setting. When doing this, be sure to issue the TUNING_TOWER command at the start of each test print. Typical pressure advance values are between 0.050 and 1.000 (the high end usually only with bowden extruders). If there is no significant improvement with a pressure advance up to 1.000, then pressure advance is unlikely to improve the quality of prints. Return to a default configuration with pressure advance disabled. Although this tuning exercise directly improves the quality of corners, it's worth remembering that a good pressure advance configuration also reduces ooze throughout the print. At the completion of this test, set pressure_advance = <calculated_value> in the [extruder] section of the configuration file and issue a RESTART command. The RESTART command will clear the test state and return the acceleration and cornering speeds to their normal values. Important Notes \u00b6 The pressure advance value is dependent on the extruder, the nozzle, and the filament. It is common for filament from different manufactures or with different pigments to require significantly different pressure advance values. Therefore, one should calibrate pressure advance on each printer and with each spool of filament. Printing temperature and extrusion rates can impact pressure advance. Be sure to tune the extruder rotation_distance and nozzle temperature prior to tuning pressure advance. The test print is designed to run with a high extruder flow rate, but otherwise \"normal\" slicer settings. A high flow rate is obtained by using a high printing speed (eg, 100mm/s) and a coarse layer height (typically around 75% of the nozzle diameter). Other slicer settings should be similar to their defaults (eg, perimeters of 2 or 3 lines, normal retraction amount). It can be useful to set the external perimeter speed to be the same speed as the rest of the print, but it is not a requirement. It is common for the test print to show different behavior on each corner. Often the slicer will arrange to change layers at one corner which can result in that corner being significantly different from the remaining three corners. If this occurs, then ignore that corner and tune pressure advance using the other three corners. It is also common for the remaining corners to vary slightly. (This can occur due to small differences in how the printer's frame reacts to cornering in certain directions.) Try to choose a value that works well for all the remaining corners. If in doubt, prefer a lower pressure advance value. If a high pressure advance value (eg, over 0.200) is used then one may find that the extruder skips when returning to the printer's normal acceleration. The pressure advance system accounts for pressure by pushing in extra filament during acceleration and retracting that filament during deceleration. With a high acceleration and high pressure advance the extruder may not have enough torque to push the required filament. If this occurs, either use a lower acceleration value or disable pressure advance. Once pressure advance is tuned in Klipper, it may still be useful to configure a small retract value in the slicer (eg, 0.75mm) and to utilize the slicer's \"wipe on retract option\" if available. These slicer settings may help counteract ooze caused by filament cohesion (filament pulled out of the nozzle due to the stickiness of the plastic). It is recommended to disable the slicer's \"z-lift on retract\" option. The pressure advance system does not change the timing or path of the toolhead. A print with pressure advance enabled will take the same amount of time as a print without pressure advance. Pressure advance also does not change the total amount of filament extruded during a print. Pressure advance results in extra extruder movement during move acceleration and deceleration. A very high pressure advance setting will result in a very large amount of extruder movement during acceleration and deceleration, and no configuration setting places a limit on the amount of that movement.","title":"Pressure advance"},{"location":"Pressure_Advance.html#pressure-advance","text":"This document provides information on tuning the \"pressure advance\" configuration variable for a particular nozzle and filament. The pressure advance feature can be helpful in reducing ooze. For more information on how pressure advance is implemented see the kinematics document.","title":"Pressure advance"},{"location":"Pressure_Advance.html#tuning-pressure-advance","text":"Pressure advance does two useful things - it reduces ooze during non-extrude moves and it reduces blobbing during cornering. This guide uses the second feature (reducing blobbing during cornering) as a mechanism for tuning. In order to calibrate pressure advance the printer must be configured and operational as the tuning test involves printing and inspecting a test object. It is a good idea to read this document in full prior to running the test. Use a slicer to generate g-code for the large hollow square found in docs/prints/square_tower.stl . Use a high speed (eg, 100mm/s), zero infill, and a coarse layer height (the layer height should be around 75% of the nozzle diameter). Make sure any \"dynamic acceleration control\" and \"scarf joint\" seams are disabled in the slicer. Prepare for the test by issuing the following G-Code command: SET_VELOCITY_LIMIT SQUARE_CORNER_VELOCITY=1 ACCEL=500 This command makes the nozzle travel slower through corners to emphasize the effects of extruder pressure. Then for printers with a direct drive extruder run the command: TUNING_TOWER COMMAND=SET_PRESSURE_ADVANCE PARAMETER=ADVANCE START=0 FACTOR=.005 For long bowden extruders use: TUNING_TOWER COMMAND=SET_PRESSURE_ADVANCE PARAMETER=ADVANCE START=0 FACTOR=.020 Then print the object. When fully printed the test print looks like: The above TUNING_TOWER command instructs Klipper to alter the pressure_advance setting on each layer of the print. Higher layers in the print will have a larger pressure advance value set. Layers below the ideal pressure_advance setting will have blobbing at the corners, and layers above the ideal setting can lead to rounded corners and poor extrusion leading up to the corner. One can cancel the print early if one observes that the corners are no longer printing well (and thus one can avoid printing layers that are known to be above the ideal pressure_advance value). Inspect the print and then use a digital calipers to find the height that has the best quality corners. When in doubt, prefer a lower height. The pressure_advance value can then be calculated as pressure_advance = <start> + <measured_height> * <factor> . (For example, 0 + 12.90 * .020 would be .258 .) It is possible to choose custom settings for START and FACTOR if that helps identify the best pressure advance setting. When doing this, be sure to issue the TUNING_TOWER command at the start of each test print. Typical pressure advance values are between 0.050 and 1.000 (the high end usually only with bowden extruders). If there is no significant improvement with a pressure advance up to 1.000, then pressure advance is unlikely to improve the quality of prints. Return to a default configuration with pressure advance disabled. Although this tuning exercise directly improves the quality of corners, it's worth remembering that a good pressure advance configuration also reduces ooze throughout the print. At the completion of this test, set pressure_advance = <calculated_value> in the [extruder] section of the configuration file and issue a RESTART command. The RESTART command will clear the test state and return the acceleration and cornering speeds to their normal values.","title":"Tuning pressure advance"},{"location":"Pressure_Advance.html#important-notes","text":"The pressure advance value is dependent on the extruder, the nozzle, and the filament. It is common for filament from different manufactures or with different pigments to require significantly different pressure advance values. Therefore, one should calibrate pressure advance on each printer and with each spool of filament. Printing temperature and extrusion rates can impact pressure advance. Be sure to tune the extruder rotation_distance and nozzle temperature prior to tuning pressure advance. The test print is designed to run with a high extruder flow rate, but otherwise \"normal\" slicer settings. A high flow rate is obtained by using a high printing speed (eg, 100mm/s) and a coarse layer height (typically around 75% of the nozzle diameter). Other slicer settings should be similar to their defaults (eg, perimeters of 2 or 3 lines, normal retraction amount). It can be useful to set the external perimeter speed to be the same speed as the rest of the print, but it is not a requirement. It is common for the test print to show different behavior on each corner. Often the slicer will arrange to change layers at one corner which can result in that corner being significantly different from the remaining three corners. If this occurs, then ignore that corner and tune pressure advance using the other three corners. It is also common for the remaining corners to vary slightly. (This can occur due to small differences in how the printer's frame reacts to cornering in certain directions.) Try to choose a value that works well for all the remaining corners. If in doubt, prefer a lower pressure advance value. If a high pressure advance value (eg, over 0.200) is used then one may find that the extruder skips when returning to the printer's normal acceleration. The pressure advance system accounts for pressure by pushing in extra filament during acceleration and retracting that filament during deceleration. With a high acceleration and high pressure advance the extruder may not have enough torque to push the required filament. If this occurs, either use a lower acceleration value or disable pressure advance. Once pressure advance is tuned in Klipper, it may still be useful to configure a small retract value in the slicer (eg, 0.75mm) and to utilize the slicer's \"wipe on retract option\" if available. These slicer settings may help counteract ooze caused by filament cohesion (filament pulled out of the nozzle due to the stickiness of the plastic). It is recommended to disable the slicer's \"z-lift on retract\" option. The pressure advance system does not change the timing or path of the toolhead. A print with pressure advance enabled will take the same amount of time as a print without pressure advance. Pressure advance also does not change the total amount of filament extruded during a print. Pressure advance results in extra extruder movement during move acceleration and deceleration. A very high pressure advance setting will result in a very large amount of extruder movement during acceleration and deceleration, and no configuration setting places a limit on the amount of that movement.","title":"Important Notes"},{"location":"Probe_Calibrate.html","text":"Probe calibration \u00b6 This document describes the method for calibrating the X, Y, and Z offsets of an \"automatic z probe\" in Klipper. This is useful for users that have a [probe] or [bltouch] section in their config file. Calibrating probe X and Y offsets \u00b6 To calibrate the X and Y offset, navigate to the OctoPrint \"Control\" tab, home the printer, and then use the OctoPrint jogging buttons to move the head to a position near the center of the bed. Place a piece of blue painters tape (or similar) on the bed underneath the probe. Navigate to the OctoPrint \"Terminal\" tab and issue a PROBE command: PROBE Place a mark on the tape directly under where the probe is (or use a similar method to note the location on the bed). Issue a GET_POSITION command and record the toolhead XY location reported by that command. For example if one sees: Recv: // toolhead: X:46.500000 Y:27.000000 Z:15.000000 E:0.000000 then one would record a probe X position of 46.5 and probe Y position of 27. After recording the probe position, issue a series of G1 commands until the nozzle is directly above the mark on the bed. For example, one might issue: G1 F300 X57 Y30 Z15 to move the nozzle to an X position of 57 and Y of 30. Once one finds the position directly above the mark, use the GET_POSITION command to report that position. This is the nozzle position. The x_offset is then the nozzle_x_position - probe_x_position and y_offset is similarly the nozzle_y_position - probe_y_position . Update the printer.cfg file with the given values, remove the tape/marks from the bed, and then issue a RESTART command so that the new values take effect. Calibrating probe Z offset \u00b6 Providing an accurate probe z_offset is critical to obtaining high quality prints. The z_offset is the distance between the nozzle and bed when the probe triggers. The Klipper PROBE_CALIBRATE tool can be used to obtain this value - it will run an automatic probe to measure the probe's Z trigger position and then start a manual probe to obtain the nozzle Z height. The probe z_offset will then be calculated from these measurements. Start by homing the printer and then move the head to a position near the center of the bed. Navigate to the OctoPrint terminal tab and run the PROBE_CALIBRATE command to start the tool. This tool will perform an automatic probe, then lift the head, move the nozzle over the location of the probe point, and start the manual probe tool. If the nozzle does not move to a position above the automatic probe point, then ABORT the manual probe tool and perform the XY probe offset calibration described above. Once the manual probe tool starts, follow the steps described at \"the paper test\" to determine the actual distance between the nozzle and bed at the given location. Once those steps are complete one can ACCEPT the position and save the results to the config file with: SAVE_CONFIG Note that if a change is made to the printer's motion system, hotend position, or probe location then it will invalidate the results of PROBE_CALIBRATE. If the probe has an X or Y offset and the bed tilt is changed (eg, by adjusting bed screws, running DELTA_CALIBRATE, running Z_TILT_ADJUST, running QUAD_GANTRY_LEVEL, or similar) then it will invalidate the results of PROBE_CALIBRATE. After making any of the above adjustments it will be necessary to run PROBE_CALIBRATE again. If the results of PROBE_CALIBRATE are invalidated, then any previous bed mesh results that were obtained using the probe are also invalidated - it will be necessary to rerun BED_MESH_CALIBRATE after recalibrating the probe. Repeatability check \u00b6 After calibrating the probe X, Y, and Z offsets it is a good idea to verify that the probe provides repeatable results. Start by homing the printer and then move the head to a position near the center of the bed. Navigate to the OctoPrint terminal tab and run the PROBE_ACCURACY command. This command will run the probe ten times and produce output similar to the following: Recv: // probe accuracy: at X:0.000 Y:0.000 Z:10.000 Recv: // and read 10 times with speed of 5 mm/s Recv: // probe at -0.003,0.005 is z=2.506948 Recv: // probe at -0.003,0.005 is z=2.519448 Recv: // probe at -0.003,0.005 is z=2.519448 Recv: // probe at -0.003,0.005 is z=2.506948 Recv: // probe at -0.003,0.005 is z=2.519448 Recv: // probe at -0.003,0.005 is z=2.519448 Recv: // probe at -0.003,0.005 is z=2.506948 Recv: // probe at -0.003,0.005 is z=2.506948 Recv: // probe at -0.003,0.005 is z=2.519448 Recv: // probe at -0.003,0.005 is z=2.506948 Recv: // probe accuracy results: maximum 2.519448, minimum 2.506948, range 0.012500, average 2.513198, median 2.513198, standard deviation 0.006250 Ideally the tool will report an identical maximum and minimum value. (That is, ideally the probe obtains an identical result on all ten probes.) However, it's normal for the minimum and maximum values to differ by one Z \"step distance\" or up to 5 microns (.005mm). A \"step distance\" is rotation_distance/(full_steps_per_rotation*microsteps) . The distance between the minimum and the maximum value is called the range. So, in the above example, since the printer uses a Z step distance of .0125, a range of 0.012500 would be considered normal. If the results of the test show a range value that is greater than 25 microns (.025mm) then the probe does not have sufficient accuracy for typical bed leveling procedures. It may be possible to tune the probe speed and/or probe start height to improve the repeatability of the probe. The PROBE_ACCURACY command allows one to run tests with different parameters to see their impact - see the G-Codes document for further details. If the probe generally obtains repeatable results but has an occasional outlier, then it may be possible to account for that by using multiple samples on each probe - read the description of the probe samples config parameters in the config reference for more details. If new probe speed, samples count, or other settings are needed, then update the printer.cfg file and issue a RESTART command. If so, it is a good idea to calibrate the z_offset again. If repeatable results can not be obtained then don't use the probe for bed leveling. Klipper has several manual probing tools that can be used instead - see the Bed Level document for further details. Location Bias Check \u00b6 Some probes can have a systemic bias that corrupts the results of the probe at certain toolhead locations. For example, if the probe mount tilts slightly when moving along the Y axis then it could result in the probe reporting biased results at different Y positions. This is a common issue with probes on delta printers, however it can occur on all printers. One can check for a location bias by using the PROBE_CALIBRATE command to measuring the probe z_offset at various X and Y locations. Ideally, the probe z_offset would be a constant value at every printer location. For delta printers, try measuring the z_offset at a position near the A tower, at a position near the B tower, and at a position near the C tower. For cartesian, corexy, and similar printers, try measuring the z_offset at positions near the four corners of the bed. Before starting this test, first calibrate the probe X, Y, and Z offsets as described at the beginning of this document. Then home the printer and navigate to the first XY position. Follow the steps at calibrating probe Z offset to run the PROBE_CALIBRATE command, TESTZ commands, and ACCEPT command, but do not run SAVE_CONFIG . Note the reported z_offset found. Then navigate to the other XY positions, repeat these PROBE_CALIBRATE steps, and note the reported z_offset. If the difference between the minimum reported z_offset and the maximum reported z_offset is greater than 25 microns (.025mm) then the probe is not suitable for typical bed leveling procedures. See the Bed Level document for manual probe alternatives. Temperature Bias \u00b6 Many probes have a systemic bias when probing at different temperatures. For example, the probe may consistently trigger at a lower height when the probe is at a higher temperature. It is recommended to run the bed leveling tools at a consistent temperature to account for this bias. For example, either always run the tools when the printer is at room temperature, or always run the tools after the printer has obtained a consistent print temperature. In either case, it is a good idea to wait several minutes after the desired temperature is reached, so that the printer apparatus is consistently at the desired temperature. To check for a temperature bias, start with the printer at room temperature and then home the printer, move the head to a position near the center of the bed, and run the PROBE_ACCURACY command. Note the results. Then, without homing or disabling the stepper motors, heat the printer nozzle and bed to printing temperature, and run the PROBE_ACCURACY command again. Ideally, the command will report identical results. As above, if the probe does have a temperature bias then be careful to always use the probe at a consistent temperature.","title":"Probe calibration"},{"location":"Probe_Calibrate.html#probe-calibration","text":"This document describes the method for calibrating the X, Y, and Z offsets of an \"automatic z probe\" in Klipper. This is useful for users that have a [probe] or [bltouch] section in their config file.","title":"Probe calibration"},{"location":"Probe_Calibrate.html#calibrating-probe-x-and-y-offsets","text":"To calibrate the X and Y offset, navigate to the OctoPrint \"Control\" tab, home the printer, and then use the OctoPrint jogging buttons to move the head to a position near the center of the bed. Place a piece of blue painters tape (or similar) on the bed underneath the probe. Navigate to the OctoPrint \"Terminal\" tab and issue a PROBE command: PROBE Place a mark on the tape directly under where the probe is (or use a similar method to note the location on the bed). Issue a GET_POSITION command and record the toolhead XY location reported by that command. For example if one sees: Recv: // toolhead: X:46.500000 Y:27.000000 Z:15.000000 E:0.000000 then one would record a probe X position of 46.5 and probe Y position of 27. After recording the probe position, issue a series of G1 commands until the nozzle is directly above the mark on the bed. For example, one might issue: G1 F300 X57 Y30 Z15 to move the nozzle to an X position of 57 and Y of 30. Once one finds the position directly above the mark, use the GET_POSITION command to report that position. This is the nozzle position. The x_offset is then the nozzle_x_position - probe_x_position and y_offset is similarly the nozzle_y_position - probe_y_position . Update the printer.cfg file with the given values, remove the tape/marks from the bed, and then issue a RESTART command so that the new values take effect.","title":"Calibrating probe X and Y offsets"},{"location":"Probe_Calibrate.html#calibrating-probe-z-offset","text":"Providing an accurate probe z_offset is critical to obtaining high quality prints. The z_offset is the distance between the nozzle and bed when the probe triggers. The Klipper PROBE_CALIBRATE tool can be used to obtain this value - it will run an automatic probe to measure the probe's Z trigger position and then start a manual probe to obtain the nozzle Z height. The probe z_offset will then be calculated from these measurements. Start by homing the printer and then move the head to a position near the center of the bed. Navigate to the OctoPrint terminal tab and run the PROBE_CALIBRATE command to start the tool. This tool will perform an automatic probe, then lift the head, move the nozzle over the location of the probe point, and start the manual probe tool. If the nozzle does not move to a position above the automatic probe point, then ABORT the manual probe tool and perform the XY probe offset calibration described above. Once the manual probe tool starts, follow the steps described at \"the paper test\" to determine the actual distance between the nozzle and bed at the given location. Once those steps are complete one can ACCEPT the position and save the results to the config file with: SAVE_CONFIG Note that if a change is made to the printer's motion system, hotend position, or probe location then it will invalidate the results of PROBE_CALIBRATE. If the probe has an X or Y offset and the bed tilt is changed (eg, by adjusting bed screws, running DELTA_CALIBRATE, running Z_TILT_ADJUST, running QUAD_GANTRY_LEVEL, or similar) then it will invalidate the results of PROBE_CALIBRATE. After making any of the above adjustments it will be necessary to run PROBE_CALIBRATE again. If the results of PROBE_CALIBRATE are invalidated, then any previous bed mesh results that were obtained using the probe are also invalidated - it will be necessary to rerun BED_MESH_CALIBRATE after recalibrating the probe.","title":"Calibrating probe Z offset"},{"location":"Probe_Calibrate.html#repeatability-check","text":"After calibrating the probe X, Y, and Z offsets it is a good idea to verify that the probe provides repeatable results. Start by homing the printer and then move the head to a position near the center of the bed. Navigate to the OctoPrint terminal tab and run the PROBE_ACCURACY command. This command will run the probe ten times and produce output similar to the following: Recv: // probe accuracy: at X:0.000 Y:0.000 Z:10.000 Recv: // and read 10 times with speed of 5 mm/s Recv: // probe at -0.003,0.005 is z=2.506948 Recv: // probe at -0.003,0.005 is z=2.519448 Recv: // probe at -0.003,0.005 is z=2.519448 Recv: // probe at -0.003,0.005 is z=2.506948 Recv: // probe at -0.003,0.005 is z=2.519448 Recv: // probe at -0.003,0.005 is z=2.519448 Recv: // probe at -0.003,0.005 is z=2.506948 Recv: // probe at -0.003,0.005 is z=2.506948 Recv: // probe at -0.003,0.005 is z=2.519448 Recv: // probe at -0.003,0.005 is z=2.506948 Recv: // probe accuracy results: maximum 2.519448, minimum 2.506948, range 0.012500, average 2.513198, median 2.513198, standard deviation 0.006250 Ideally the tool will report an identical maximum and minimum value. (That is, ideally the probe obtains an identical result on all ten probes.) However, it's normal for the minimum and maximum values to differ by one Z \"step distance\" or up to 5 microns (.005mm). A \"step distance\" is rotation_distance/(full_steps_per_rotation*microsteps) . The distance between the minimum and the maximum value is called the range. So, in the above example, since the printer uses a Z step distance of .0125, a range of 0.012500 would be considered normal. If the results of the test show a range value that is greater than 25 microns (.025mm) then the probe does not have sufficient accuracy for typical bed leveling procedures. It may be possible to tune the probe speed and/or probe start height to improve the repeatability of the probe. The PROBE_ACCURACY command allows one to run tests with different parameters to see their impact - see the G-Codes document for further details. If the probe generally obtains repeatable results but has an occasional outlier, then it may be possible to account for that by using multiple samples on each probe - read the description of the probe samples config parameters in the config reference for more details. If new probe speed, samples count, or other settings are needed, then update the printer.cfg file and issue a RESTART command. If so, it is a good idea to calibrate the z_offset again. If repeatable results can not be obtained then don't use the probe for bed leveling. Klipper has several manual probing tools that can be used instead - see the Bed Level document for further details.","title":"Repeatability check"},{"location":"Probe_Calibrate.html#location-bias-check","text":"Some probes can have a systemic bias that corrupts the results of the probe at certain toolhead locations. For example, if the probe mount tilts slightly when moving along the Y axis then it could result in the probe reporting biased results at different Y positions. This is a common issue with probes on delta printers, however it can occur on all printers. One can check for a location bias by using the PROBE_CALIBRATE command to measuring the probe z_offset at various X and Y locations. Ideally, the probe z_offset would be a constant value at every printer location. For delta printers, try measuring the z_offset at a position near the A tower, at a position near the B tower, and at a position near the C tower. For cartesian, corexy, and similar printers, try measuring the z_offset at positions near the four corners of the bed. Before starting this test, first calibrate the probe X, Y, and Z offsets as described at the beginning of this document. Then home the printer and navigate to the first XY position. Follow the steps at calibrating probe Z offset to run the PROBE_CALIBRATE command, TESTZ commands, and ACCEPT command, but do not run SAVE_CONFIG . Note the reported z_offset found. Then navigate to the other XY positions, repeat these PROBE_CALIBRATE steps, and note the reported z_offset. If the difference between the minimum reported z_offset and the maximum reported z_offset is greater than 25 microns (.025mm) then the probe is not suitable for typical bed leveling procedures. See the Bed Level document for manual probe alternatives.","title":"Location Bias Check"},{"location":"Probe_Calibrate.html#temperature-bias","text":"Many probes have a systemic bias when probing at different temperatures. For example, the probe may consistently trigger at a lower height when the probe is at a higher temperature. It is recommended to run the bed leveling tools at a consistent temperature to account for this bias. For example, either always run the tools when the printer is at room temperature, or always run the tools after the printer has obtained a consistent print temperature. In either case, it is a good idea to wait several minutes after the desired temperature is reached, so that the printer apparatus is consistently at the desired temperature. To check for a temperature bias, start with the printer at room temperature and then home the printer, move the head to a position near the center of the bed, and run the PROBE_ACCURACY command. Note the results. Then, without homing or disabling the stepper motors, heat the printer nozzle and bed to printing temperature, and run the PROBE_ACCURACY command again. Ideally, the command will report identical results. As above, if the probe does have a temperature bias then be careful to always use the probe at a consistent temperature.","title":"Temperature Bias"},{"location":"Protocol.html","text":"Protocol \u00b6 The Klipper messaging protocol is used for low-level communication between the Klipper host software and the Klipper micro-controller software. At a high level the protocol can be thought of as a series of command and response strings that are compressed, transmitted, and then processed at the receiving side. An example series of commands in uncompressed human-readable format might look like: set_digital_out pin=PA3 value=1 set_digital_out pin=PA7 value=1 schedule_digital_out oid=8 clock=4000000 value=0 queue_step oid=7 interval=7458 count=10 add=331 queue_step oid=7 interval=11717 count=4 add=1281 See the mcu commands document for information on available commands. See the debugging document for information on how to translate a G-Code file into its corresponding human-readable micro-controller commands. This page provides a high-level description of the Klipper messaging protocol itself. It describes how messages are declared, encoded in binary format (the \"compression\" scheme), and transmitted. The goal of the protocol is to enable an error-free communication channel between the host and micro-controller that is low-latency, low-bandwidth, and low-complexity for the micro-controller. Micro-controller Interface \u00b6 The Klipper transmission protocol can be thought of as a RPC mechanism between micro-controller and host. The micro-controller software declares the commands that the host may invoke along with the response messages that it can generate. The host uses that information to command the micro-controller to perform actions and to interpret the results. Declaring commands \u00b6 The micro-controller software declares a \"command\" by using the DECL_COMMAND() macro in the C code. For example: DECL_COMMAND(command_update_digital_out, \"update_digital_out oid=%c value=%c\"); The above declares a command named \"update_digital_out\". This allows the host to \"invoke\" this command which would cause the command_update_digital_out() C function to be executed in the micro-controller. The above also indicates that the command takes two integer parameters. When the command_update_digital_out() C code is executed, it will be passed an array containing these two integers - the first corresponding to the 'oid' and the second corresponding to the 'value'. In general, the parameters are described with printf() style syntax (eg, \"%u\"). The formatting directly corresponds to the human-readable view of commands (eg, \"update_digital_out oid=7 value=1\"). In the above example, \"value=\" is a parameter name and \"%c\" indicates the parameter is an integer. Internally, the parameter name is only used as documentation. In this example, the \"%c\" is also used as documentation to indicate the expected integer is 1 byte in size (the declared integer size does not impact the parsing or encoding). The micro-controller build will collect all commands declared with DECL_COMMAND(), determine their parameters, and arrange for them to be callable. Declaring responses \u00b6 To send information from the micro-controller to the host a \"response\" is generated. These are both declared and transmitted using the sendf() C macro. For example: sendf(\"status clock=%u status=%c\", sched_read_time(), sched_is_shutdown()); The above transmits a \"status\" response message that contains two integer parameters (\"clock\" and \"status\"). The micro-controller build automatically finds all sendf() calls and generates encoders for them. The first parameter of the sendf() function describes the response and it is in the same format as command declarations. The host can arrange to register a callback function for each response. So, in effect, commands allow the host to invoke C functions in the micro-controller and responses allow the micro-controller software to invoke code in the host. The sendf() macro should only be invoked from command or task handlers, and it should not be invoked from interrupts or timers. The code does not need to issue a sendf() in response to a received command, it is not limited in the number of times sendf() may be invoked, and it may invoke sendf() at any time from a task handler. Output responses \u00b6 To simplify debugging, there is also an output() C function. For example: output(\"The value of %u is %s with size %u.\", x, buf, buf_len); The output() function is similar in usage to printf() - it is intended to generate and format arbitrary messages for human consumption. Declaring enumerations \u00b6 Enumerations allow the host code to use string identifiers for parameters that the micro-controller handles as integers. They are declared in the micro-controller code - for example: DECL_ENUMERATION(\"spi_bus\", \"spi\", 0); DECL_ENUMERATION_RANGE(\"pin\", \"PC0\", 16, 8); If the first example, the DECL_ENUMERATION() macro defines an enumeration for any command/response message with a parameter name of \"spi_bus\" or parameter name with a suffix of \"_spi_bus\". For those parameters the string \"spi\" is a valid value and it will be transmitted with an integer value of zero. It's also possible to declare an enumeration range. In the second example, a \"pin\" parameter (or any parameter with a suffix of \"_pin\") would accept PC0, PC1, PC2, ..., PC7 as valid values. The strings will be transmitted with integers 16, 17, 18, ..., 23. Declaring constants \u00b6 Constants can also be exported. For example, the following: DECL_CONSTANT(\"SERIAL_BAUD\", 250000); would export a constant named \"SERIAL_BAUD\" with a value of 250000 from the micro-controller to the host. It is also possible to declare a constant that is a string - for example: DECL_CONSTANT_STR(\"MCU\", \"pru\"); Low-level message encoding \u00b6 To accomplish the above RPC mechanism, each command and response is encoded into a binary format for transmission. This section describes the transmission system. Message Blocks \u00b6 All data sent from host to micro-controller and vice-versa are contained in \"message blocks\". A message block has a two byte header and a three byte trailer. The format of a message block is: <1 byte length><1 byte sequence><n-byte content><2 byte crc><1 byte sync> The length byte contains the number of bytes in the message block including the header and trailer bytes (thus the minimum message length is 5 bytes). The maximum message block length is currently 64 bytes. The sequence byte contains a 4 bit sequence number in the low-order bits and the high-order bits always contain 0x10 (the high-order bits are reserved for future use). The content bytes contain arbitrary data and its format is described in the following section. The crc bytes contain a 16bit CCITT CRC of the message block including the header bytes but excluding the trailer bytes. The sync byte is 0x7e. The format of the message block is inspired by HDLC message frames. Like in HDLC, the message block may optionally contain an additional sync character at the start of the block. Unlike in HDLC, a sync character is not exclusive to the framing and may be present in the message block content. Message Block Contents \u00b6 Each message block sent from host to micro-controller contains a series of zero or more message commands in its contents. Each command starts with a Variable Length Quantity (VLQ) encoded integer command-id followed by zero or more VLQ parameters for the given command. As an example, the following four commands might be placed in a single message block: update_digital_out oid=6 value=1 update_digital_out oid=5 value=0 get_config get_clock and encoded into the following eight VLQ integers: <id_update_digital_out><6><1><id_update_digital_out><5><0><id_get_config><id_get_clock> In order to encode and parse the message contents, both the host and micro-controller must agree on the command ids and the number of parameters each command has. So, in the above example, both the host and micro-controller would know that \"id_update_digital_out\" is always followed by two parameters, and \"id_get_config\" and \"id_get_clock\" have zero parameters. The host and micro-controller share a \"data dictionary\" that maps the command descriptions (eg, \"update_digital_out oid=%c value=%c\") to their integer command-ids. When processing the data, the parser will know to expect a specific number of VLQ encoded parameters following a given command id. The message contents for blocks sent from micro-controller to host follow the same format. The identifiers in these messages are \"response ids\", but they serve the same purpose and follow the same encoding rules. In practice, message blocks sent from the micro-controller to the host never contain more than one response in the message block contents. Variable Length Quantities \u00b6 See the wikipedia article for more information on the general format of VLQ encoded integers. Klipper uses an encoding scheme that supports both positive and negative integers. Integers close to zero use less bytes to encode and positive integers typically encode using less bytes than negative integers. The following table shows the number of bytes each integer takes to encode: Integer Encoded size -32 .. 95 1 -4096 .. 12287 2 -524288 .. 1572863 3 -67108864 .. 201326591 4 -2147483648 .. 4294967295 5 Variable length strings \u00b6 As an exception to the above encoding rules, if a parameter to a command or response is a dynamic string then the parameter is not encoded as a simple VLQ integer. Instead it is encoded by transmitting the length as a VLQ encoded integer followed by the contents itself: <VLQ encoded length><n-byte contents> The command descriptions found in the data dictionary allow both the host and micro-controller to know which command parameters use simple VLQ encoding and which parameters use string encoding. Data Dictionary \u00b6 In order for meaningful communications to be established between micro-controller and host, both sides must agree on a \"data dictionary\". This data dictionary contains the integer identifiers for commands and responses along with their descriptions. The micro-controller build uses the contents of DECL_COMMAND() and sendf() macros to generate the data dictionary. The build automatically assigns unique identifiers to each command and response. This system allows both the host and micro-controller code to seamlessly use descriptive human-readable names while still using minimal bandwidth. The host queries the data dictionary when it first connects to the micro-controller. Once the host downloads the data dictionary from the micro-controller, it uses that data dictionary to encode all commands and to parse all responses from the micro-controller. The host must therefore handle a dynamic data dictionary. However, to keep the micro-controller software simple, the micro-controller always uses its static (compiled in) data dictionary. The data dictionary is queried by sending \"identify\" commands to the micro-controller. The micro-controller will respond to each identify command with an \"identify_response\" message. Since these two commands are needed prior to obtaining the data dictionary, their integer ids and parameter types are hard-coded in both the micro-controller and the host. The \"identify_response\" response id is 0, the \"identify\" command id is 1. Other than having hard-coded ids the identify command and its response are declared and transmitted the same way as other commands and responses. No other command or response is hard-coded. The format of the transmitted data dictionary itself is a zlib compressed JSON string. The micro-controller build process generates the string, compresses it, and stores it in the text section of the micro-controller flash. The data dictionary can be much larger than the maximum message block size - the host downloads it by sending multiple identify commands requesting progressive chunks of the data dictionary. Once all chunks are obtained the host will assemble the chunks, uncompress the data, and parse the contents. In addition to information on the communication protocol, the data dictionary also contains the software version, enumerations (as defined by DECL_ENUMERATION), and constants (as defined by DECL_CONSTANT). Message flow \u00b6 Message commands sent from host to micro-controller are intended to be error-free. The micro-controller will check the CRC and sequence numbers in each message block to ensure the commands are accurate and in-order. The micro-controller always processes message blocks in-order - should it receive a block out-of-order it will discard it and any other out-of-order blocks until it receives blocks with the correct sequencing. The low-level host code implements an automatic retransmission system for lost and corrupt message blocks sent to the micro-controller. To facilitate this, the micro-controller transmits an \"ack message block\" after each successfully received message block. The host schedules a timeout after sending each block and it will retransmit should the timeout expire without receiving a corresponding \"ack\". In addition, if the micro-controller detects a corrupt or out-of-order block it may transmit a \"nak message block\" to facilitate fast retransmission. An \"ack\" is a message block with empty content (ie, a 5 byte message block) and a sequence number greater than the last received host sequence number. A \"nak\" is a message block with empty content and a sequence number less than the last received host sequence number. The protocol facilitates a \"window\" transmission system so that the host can have many outstanding message blocks in-flight at a time. (This is in addition to the many commands that may be present in a given message block.) This allows maximum bandwidth utilization even in the event of transmission latency. The timeout, retransmit, windowing, and ack mechanism are inspired by similar mechanisms in TCP . In the other direction, message blocks sent from micro-controller to host are designed to be error-free, but they do not have assured transmission. (Responses should not be corrupt, but they may go missing.) This is done to keep the implementation in the micro-controller simple. There is no automatic retransmission system for responses - the high-level code is expected to be capable of handling an occasional missing response (usually by re-requesting the content or setting up a recurring schedule of response transmission). The sequence number field in message blocks sent to the host is always one greater than the last received sequence number of message blocks received from the host. It is not used to track sequences of response message blocks.","title":"Protocol"},{"location":"Protocol.html#protocol","text":"The Klipper messaging protocol is used for low-level communication between the Klipper host software and the Klipper micro-controller software. At a high level the protocol can be thought of as a series of command and response strings that are compressed, transmitted, and then processed at the receiving side. An example series of commands in uncompressed human-readable format might look like: set_digital_out pin=PA3 value=1 set_digital_out pin=PA7 value=1 schedule_digital_out oid=8 clock=4000000 value=0 queue_step oid=7 interval=7458 count=10 add=331 queue_step oid=7 interval=11717 count=4 add=1281 See the mcu commands document for information on available commands. See the debugging document for information on how to translate a G-Code file into its corresponding human-readable micro-controller commands. This page provides a high-level description of the Klipper messaging protocol itself. It describes how messages are declared, encoded in binary format (the \"compression\" scheme), and transmitted. The goal of the protocol is to enable an error-free communication channel between the host and micro-controller that is low-latency, low-bandwidth, and low-complexity for the micro-controller.","title":"Protocol"},{"location":"Protocol.html#micro-controller-interface","text":"The Klipper transmission protocol can be thought of as a RPC mechanism between micro-controller and host. The micro-controller software declares the commands that the host may invoke along with the response messages that it can generate. The host uses that information to command the micro-controller to perform actions and to interpret the results.","title":"Micro-controller Interface"},{"location":"Protocol.html#declaring-commands","text":"The micro-controller software declares a \"command\" by using the DECL_COMMAND() macro in the C code. For example: DECL_COMMAND(command_update_digital_out, \"update_digital_out oid=%c value=%c\"); The above declares a command named \"update_digital_out\". This allows the host to \"invoke\" this command which would cause the command_update_digital_out() C function to be executed in the micro-controller. The above also indicates that the command takes two integer parameters. When the command_update_digital_out() C code is executed, it will be passed an array containing these two integers - the first corresponding to the 'oid' and the second corresponding to the 'value'. In general, the parameters are described with printf() style syntax (eg, \"%u\"). The formatting directly corresponds to the human-readable view of commands (eg, \"update_digital_out oid=7 value=1\"). In the above example, \"value=\" is a parameter name and \"%c\" indicates the parameter is an integer. Internally, the parameter name is only used as documentation. In this example, the \"%c\" is also used as documentation to indicate the expected integer is 1 byte in size (the declared integer size does not impact the parsing or encoding). The micro-controller build will collect all commands declared with DECL_COMMAND(), determine their parameters, and arrange for them to be callable.","title":"Declaring commands"},{"location":"Protocol.html#declaring-responses","text":"To send information from the micro-controller to the host a \"response\" is generated. These are both declared and transmitted using the sendf() C macro. For example: sendf(\"status clock=%u status=%c\", sched_read_time(), sched_is_shutdown()); The above transmits a \"status\" response message that contains two integer parameters (\"clock\" and \"status\"). The micro-controller build automatically finds all sendf() calls and generates encoders for them. The first parameter of the sendf() function describes the response and it is in the same format as command declarations. The host can arrange to register a callback function for each response. So, in effect, commands allow the host to invoke C functions in the micro-controller and responses allow the micro-controller software to invoke code in the host. The sendf() macro should only be invoked from command or task handlers, and it should not be invoked from interrupts or timers. The code does not need to issue a sendf() in response to a received command, it is not limited in the number of times sendf() may be invoked, and it may invoke sendf() at any time from a task handler.","title":"Declaring responses"},{"location":"Protocol.html#output-responses","text":"To simplify debugging, there is also an output() C function. For example: output(\"The value of %u is %s with size %u.\", x, buf, buf_len); The output() function is similar in usage to printf() - it is intended to generate and format arbitrary messages for human consumption.","title":"Output responses"},{"location":"Protocol.html#declaring-enumerations","text":"Enumerations allow the host code to use string identifiers for parameters that the micro-controller handles as integers. They are declared in the micro-controller code - for example: DECL_ENUMERATION(\"spi_bus\", \"spi\", 0); DECL_ENUMERATION_RANGE(\"pin\", \"PC0\", 16, 8); If the first example, the DECL_ENUMERATION() macro defines an enumeration for any command/response message with a parameter name of \"spi_bus\" or parameter name with a suffix of \"_spi_bus\". For those parameters the string \"spi\" is a valid value and it will be transmitted with an integer value of zero. It's also possible to declare an enumeration range. In the second example, a \"pin\" parameter (or any parameter with a suffix of \"_pin\") would accept PC0, PC1, PC2, ..., PC7 as valid values. The strings will be transmitted with integers 16, 17, 18, ..., 23.","title":"Declaring enumerations"},{"location":"Protocol.html#declaring-constants","text":"Constants can also be exported. For example, the following: DECL_CONSTANT(\"SERIAL_BAUD\", 250000); would export a constant named \"SERIAL_BAUD\" with a value of 250000 from the micro-controller to the host. It is also possible to declare a constant that is a string - for example: DECL_CONSTANT_STR(\"MCU\", \"pru\");","title":"Declaring constants"},{"location":"Protocol.html#low-level-message-encoding","text":"To accomplish the above RPC mechanism, each command and response is encoded into a binary format for transmission. This section describes the transmission system.","title":"Low-level message encoding"},{"location":"Protocol.html#message-blocks","text":"All data sent from host to micro-controller and vice-versa are contained in \"message blocks\". A message block has a two byte header and a three byte trailer. The format of a message block is: <1 byte length><1 byte sequence><n-byte content><2 byte crc><1 byte sync> The length byte contains the number of bytes in the message block including the header and trailer bytes (thus the minimum message length is 5 bytes). The maximum message block length is currently 64 bytes. The sequence byte contains a 4 bit sequence number in the low-order bits and the high-order bits always contain 0x10 (the high-order bits are reserved for future use). The content bytes contain arbitrary data and its format is described in the following section. The crc bytes contain a 16bit CCITT CRC of the message block including the header bytes but excluding the trailer bytes. The sync byte is 0x7e. The format of the message block is inspired by HDLC message frames. Like in HDLC, the message block may optionally contain an additional sync character at the start of the block. Unlike in HDLC, a sync character is not exclusive to the framing and may be present in the message block content.","title":"Message Blocks"},{"location":"Protocol.html#message-block-contents","text":"Each message block sent from host to micro-controller contains a series of zero or more message commands in its contents. Each command starts with a Variable Length Quantity (VLQ) encoded integer command-id followed by zero or more VLQ parameters for the given command. As an example, the following four commands might be placed in a single message block: update_digital_out oid=6 value=1 update_digital_out oid=5 value=0 get_config get_clock and encoded into the following eight VLQ integers: <id_update_digital_out><6><1><id_update_digital_out><5><0><id_get_config><id_get_clock> In order to encode and parse the message contents, both the host and micro-controller must agree on the command ids and the number of parameters each command has. So, in the above example, both the host and micro-controller would know that \"id_update_digital_out\" is always followed by two parameters, and \"id_get_config\" and \"id_get_clock\" have zero parameters. The host and micro-controller share a \"data dictionary\" that maps the command descriptions (eg, \"update_digital_out oid=%c value=%c\") to their integer command-ids. When processing the data, the parser will know to expect a specific number of VLQ encoded parameters following a given command id. The message contents for blocks sent from micro-controller to host follow the same format. The identifiers in these messages are \"response ids\", but they serve the same purpose and follow the same encoding rules. In practice, message blocks sent from the micro-controller to the host never contain more than one response in the message block contents.","title":"Message Block Contents"},{"location":"Protocol.html#variable-length-quantities","text":"See the wikipedia article for more information on the general format of VLQ encoded integers. Klipper uses an encoding scheme that supports both positive and negative integers. Integers close to zero use less bytes to encode and positive integers typically encode using less bytes than negative integers. The following table shows the number of bytes each integer takes to encode: Integer Encoded size -32 .. 95 1 -4096 .. 12287 2 -524288 .. 1572863 3 -67108864 .. 201326591 4 -2147483648 .. 4294967295 5","title":"Variable Length Quantities"},{"location":"Protocol.html#variable-length-strings","text":"As an exception to the above encoding rules, if a parameter to a command or response is a dynamic string then the parameter is not encoded as a simple VLQ integer. Instead it is encoded by transmitting the length as a VLQ encoded integer followed by the contents itself: <VLQ encoded length><n-byte contents> The command descriptions found in the data dictionary allow both the host and micro-controller to know which command parameters use simple VLQ encoding and which parameters use string encoding.","title":"Variable length strings"},{"location":"Protocol.html#data-dictionary","text":"In order for meaningful communications to be established between micro-controller and host, both sides must agree on a \"data dictionary\". This data dictionary contains the integer identifiers for commands and responses along with their descriptions. The micro-controller build uses the contents of DECL_COMMAND() and sendf() macros to generate the data dictionary. The build automatically assigns unique identifiers to each command and response. This system allows both the host and micro-controller code to seamlessly use descriptive human-readable names while still using minimal bandwidth. The host queries the data dictionary when it first connects to the micro-controller. Once the host downloads the data dictionary from the micro-controller, it uses that data dictionary to encode all commands and to parse all responses from the micro-controller. The host must therefore handle a dynamic data dictionary. However, to keep the micro-controller software simple, the micro-controller always uses its static (compiled in) data dictionary. The data dictionary is queried by sending \"identify\" commands to the micro-controller. The micro-controller will respond to each identify command with an \"identify_response\" message. Since these two commands are needed prior to obtaining the data dictionary, their integer ids and parameter types are hard-coded in both the micro-controller and the host. The \"identify_response\" response id is 0, the \"identify\" command id is 1. Other than having hard-coded ids the identify command and its response are declared and transmitted the same way as other commands and responses. No other command or response is hard-coded. The format of the transmitted data dictionary itself is a zlib compressed JSON string. The micro-controller build process generates the string, compresses it, and stores it in the text section of the micro-controller flash. The data dictionary can be much larger than the maximum message block size - the host downloads it by sending multiple identify commands requesting progressive chunks of the data dictionary. Once all chunks are obtained the host will assemble the chunks, uncompress the data, and parse the contents. In addition to information on the communication protocol, the data dictionary also contains the software version, enumerations (as defined by DECL_ENUMERATION), and constants (as defined by DECL_CONSTANT).","title":"Data Dictionary"},{"location":"Protocol.html#message-flow","text":"Message commands sent from host to micro-controller are intended to be error-free. The micro-controller will check the CRC and sequence numbers in each message block to ensure the commands are accurate and in-order. The micro-controller always processes message blocks in-order - should it receive a block out-of-order it will discard it and any other out-of-order blocks until it receives blocks with the correct sequencing. The low-level host code implements an automatic retransmission system for lost and corrupt message blocks sent to the micro-controller. To facilitate this, the micro-controller transmits an \"ack message block\" after each successfully received message block. The host schedules a timeout after sending each block and it will retransmit should the timeout expire without receiving a corresponding \"ack\". In addition, if the micro-controller detects a corrupt or out-of-order block it may transmit a \"nak message block\" to facilitate fast retransmission. An \"ack\" is a message block with empty content (ie, a 5 byte message block) and a sequence number greater than the last received host sequence number. A \"nak\" is a message block with empty content and a sequence number less than the last received host sequence number. The protocol facilitates a \"window\" transmission system so that the host can have many outstanding message blocks in-flight at a time. (This is in addition to the many commands that may be present in a given message block.) This allows maximum bandwidth utilization even in the event of transmission latency. The timeout, retransmit, windowing, and ack mechanism are inspired by similar mechanisms in TCP . In the other direction, message blocks sent from micro-controller to host are designed to be error-free, but they do not have assured transmission. (Responses should not be corrupt, but they may go missing.) This is done to keep the implementation in the micro-controller simple. There is no automatic retransmission system for responses - the high-level code is expected to be capable of handling an occasional missing response (usually by re-requesting the content or setting up a recurring schedule of response transmission). The sequence number field in message blocks sent to the host is always one greater than the last received sequence number of message blocks received from the host. It is not used to track sequences of response message blocks.","title":"Message flow"},{"location":"RPi_microcontroller.html","text":"RPi microcontroller \u00b6 This document describes the process of running Klipper on a RPi and use the same RPi as secondary mcu. Why use RPi as a secondary MCU? \u00b6 Often the MCUs dedicated to controlling 3D printers have a limited and pre-configured number of exposed pins to manage the main printing functions (thermal resistors, extruders, steppers ...). Using the RPi where Klipper is installed as a secondary MCU gives the possibility to directly use the GPIOs and the buses (i2c, spi) of the RPi inside klipper without using Octoprint plugins (if used) or external programs giving the ability to control everything within the print GCODE. Warning : If your platform is a Beaglebone and you have correctly followed the installation steps, the linux mcu is already installed and configured for your system. Install the rc script \u00b6 If you want to use the host as a secondary MCU the klipper_mcu process must run before the klippy process. After installing Klipper, install the script. run: cd ~/klipper/ sudo cp ./scripts/klipper-mcu.service /etc/systemd/system/ sudo systemctl enable klipper-mcu.service Building the micro-controller code \u00b6 To compile the Klipper micro-controller code, start by configuring it for the \"Linux process\": cd ~/klipper/ make menuconfig In the menu, set \"Microcontroller Architecture\" to \"Linux process,\" then save and exit. To build and install the new micro-controller code, run: sudo service klipper stop make flash sudo service klipper start If klippy.log reports a \"Permission denied\" error when attempting to connect to /tmp/klipper_host_mcu then you need to add your user to the tty group. The following command will add the \"pi\" user to the tty group: sudo usermod -a -G tty pi Remaining configuration \u00b6 Complete the installation by configuring Klipper secondary MCU following the instructions in RaspberryPi sample config and Multi MCU sample config . Optional: Enabling SPI \u00b6 Make sure the Linux SPI driver is enabled by running sudo raspi-config and enabling SPI under the \"Interfacing options\" menu. Optional: Enabling I2C \u00b6 Make sure the Linux I2C driver is enabled by running sudo raspi-config and enabling I2C under the \"Interfacing options\" menu. If planning to use I2C for the MPU accelerometer, it is also required to set the baud rate to 400000 by: adding/uncommenting dtparam=i2c_arm=on,i2c_arm_baudrate=400000 in /boot/config.txt (or /boot/firmware/config.txt in some distros). Optional: Identify the correct gpiochip \u00b6 On Raspberry Pi and on many clones the pins exposed on the GPIO belong to the first gpiochip. They can therefore be used on klipper simply by referring them with the name gpio0..n . However, there are cases in which the exposed pins belong to gpiochips other than the first. For example in the case of some OrangePi models or if a Port Expander is used. In these cases it is useful to use the commands to access the Linux GPIO character device to verify the configuration. To install the Linux GPIO character device - binary on a debian based distro like octopi run: sudo apt-get install gpiod To check available gpiochip run: gpiodetect To check the pin number and the pin availability tun: gpioinfo The chosen pin can thus be used within the configuration as gpiochip<n>/gpio<o> where n is the chip number as seen by the gpiodetect command and o is the line number seen by the gpioinfo command. Warning: only gpio marked as unused can be used. It is not possible for a line to be used by multiple processes simultaneously. For example on a RPi 3B+ where klipper use the GPIO20 for a switch: $ gpiodetect gpiochip0 [pinctrl-bcm2835] (54 lines) gpiochip1 [raspberrypi-exp-gpio] (8 lines) $ gpioinfo gpiochip0 - 54 lines: line 0: unnamed unused input active-high line 1: unnamed unused input active-high line 2: unnamed unused input active-high line 3: unnamed unused input active-high line 4: unnamed unused input active-high line 5: unnamed unused input active-high line 6: unnamed unused input active-high line 7: unnamed unused input active-high line 8: unnamed unused input active-high line 9: unnamed unused input active-high line 10: unnamed unused input active-high line 11: unnamed unused input active-high line 12: unnamed unused input active-high line 13: unnamed unused input active-high line 14: unnamed unused input active-high line 15: unnamed unused input active-high line 16: unnamed unused input active-high line 17: unnamed unused input active-high line 18: unnamed unused input active-high line 19: unnamed unused input active-high line 20: unnamed \"klipper\" output active-high [used] line 21: unnamed unused input active-high line 22: unnamed unused input active-high line 23: unnamed unused input active-high line 24: unnamed unused input active-high line 25: unnamed unused input active-high line 26: unnamed unused input active-high line 27: unnamed unused input active-high line 28: unnamed unused input active-high line 29: unnamed \"led0\" output active-high [used] line 30: unnamed unused input active-high line 31: unnamed unused input active-high line 32: unnamed unused input active-high line 33: unnamed unused input active-high line 34: unnamed unused input active-high line 35: unnamed unused input active-high line 36: unnamed unused input active-high line 37: unnamed unused input active-high line 38: unnamed unused input active-high line 39: unnamed unused input active-high line 40: unnamed unused input active-high line 41: unnamed unused input active-high line 42: unnamed unused input active-high line 43: unnamed unused input active-high line 44: unnamed unused input active-high line 45: unnamed unused input active-high line 46: unnamed unused input active-high line 47: unnamed unused input active-high line 48: unnamed unused input active-high line 49: unnamed unused input active-high line 50: unnamed unused input active-high line 51: unnamed unused input active-high line 52: unnamed unused input active-high line 53: unnamed unused input active-high gpiochip1 - 8 lines: line 0: unnamed unused input active-high line 1: unnamed unused input active-high line 2: unnamed \"led1\" output active-low [used] line 3: unnamed unused input active-high line 4: unnamed unused input active-high line 5: unnamed unused input active-high line 6: unnamed unused input active-high line 7: unnamed unused input active-high Optional: Hardware PWM \u00b6 Raspberry Pi's have two PWM channels (PWM0 and PWM1) which are exposed on the header or if not, can be routed to existing gpio pins. The Linux mcu daemon uses the pwmchip sysfs interface to control hardware pwm devices on Linux hosts. The pwm sysfs interface is not exposed by default on a Raspberry and can be activated by adding a line to /boot/config.txt : # Enable pwmchip sysfs interface dtoverlay=pwm,pin=12,func=4 This example enables only PWM0 and routes it to gpio12. If both PWM channels need to be enabled you can use pwm-2chan : # Enable pwmchip sysfs interface dtoverlay=pwm-2chan,pin=12,func=4,pin2=13,func2=4 This example additionally enables PWM1 and routes it to gpio13. The overlay does not expose the pwm line on sysfs on boot and needs to be exported by echo'ing the number of the pwm channel to /sys/class/pwm/pwmchip0/export . This will create device /sys/class/pwm/pwmchip0/pwm0 in the filesystem. The easiest way to do this is by adding this to /etc/rc.local before the exit 0 line: # Enable pwmchip sysfs interface echo 0 > /sys/class/pwm/pwmchip0/export When using both PWM channels, the number of the second channel needs to be echo'd as well: # Enable pwmchip sysfs interface echo 0 > /sys/class/pwm/pwmchip0/export echo 1 > /sys/class/pwm/pwmchip0/export With the sysfs in place, you can now use either the pwm channel(s) by adding the following piece of configuration to your printer.cfg : [output_pin caselight] pin: host:pwmchip0/pwm0 pwm: True hardware_pwm: True cycle_time: 0.000001 [output_pin beeper] pin: host:pwmchip0/pwm1 pwm: True hardware_pwm: True value: 0 shutdown_value: 0 cycle_time: 0.0005 This will add hardware pwm control to gpio12 and gpio13 on the Pi (because the overlay was configured to route pwm0 to pin=12 and pwm1 to pin=13). PWM0 can be routed to gpio12 and gpio18, PWM1 can be routed to gpio13 and gpio19: PWM gpio PIN Func 0 12 4 0 18 2 1 13 4 1 19 2","title":"RPi microcontroller"},{"location":"RPi_microcontroller.html#rpi-microcontroller","text":"This document describes the process of running Klipper on a RPi and use the same RPi as secondary mcu.","title":"RPi microcontroller"},{"location":"RPi_microcontroller.html#why-use-rpi-as-a-secondary-mcu","text":"Often the MCUs dedicated to controlling 3D printers have a limited and pre-configured number of exposed pins to manage the main printing functions (thermal resistors, extruders, steppers ...). Using the RPi where Klipper is installed as a secondary MCU gives the possibility to directly use the GPIOs and the buses (i2c, spi) of the RPi inside klipper without using Octoprint plugins (if used) or external programs giving the ability to control everything within the print GCODE. Warning : If your platform is a Beaglebone and you have correctly followed the installation steps, the linux mcu is already installed and configured for your system.","title":"Why use RPi as a secondary MCU?"},{"location":"RPi_microcontroller.html#install-the-rc-script","text":"If you want to use the host as a secondary MCU the klipper_mcu process must run before the klippy process. After installing Klipper, install the script. run: cd ~/klipper/ sudo cp ./scripts/klipper-mcu.service /etc/systemd/system/ sudo systemctl enable klipper-mcu.service","title":"Install the rc script"},{"location":"RPi_microcontroller.html#building-the-micro-controller-code","text":"To compile the Klipper micro-controller code, start by configuring it for the \"Linux process\": cd ~/klipper/ make menuconfig In the menu, set \"Microcontroller Architecture\" to \"Linux process,\" then save and exit. To build and install the new micro-controller code, run: sudo service klipper stop make flash sudo service klipper start If klippy.log reports a \"Permission denied\" error when attempting to connect to /tmp/klipper_host_mcu then you need to add your user to the tty group. The following command will add the \"pi\" user to the tty group: sudo usermod -a -G tty pi","title":"Building the micro-controller code"},{"location":"RPi_microcontroller.html#remaining-configuration","text":"Complete the installation by configuring Klipper secondary MCU following the instructions in RaspberryPi sample config and Multi MCU sample config .","title":"Remaining configuration"},{"location":"RPi_microcontroller.html#optional-enabling-spi","text":"Make sure the Linux SPI driver is enabled by running sudo raspi-config and enabling SPI under the \"Interfacing options\" menu.","title":"Optional: Enabling SPI"},{"location":"RPi_microcontroller.html#optional-enabling-i2c","text":"Make sure the Linux I2C driver is enabled by running sudo raspi-config and enabling I2C under the \"Interfacing options\" menu. If planning to use I2C for the MPU accelerometer, it is also required to set the baud rate to 400000 by: adding/uncommenting dtparam=i2c_arm=on,i2c_arm_baudrate=400000 in /boot/config.txt (or /boot/firmware/config.txt in some distros).","title":"Optional: Enabling I2C"},{"location":"RPi_microcontroller.html#optional-identify-the-correct-gpiochip","text":"On Raspberry Pi and on many clones the pins exposed on the GPIO belong to the first gpiochip. They can therefore be used on klipper simply by referring them with the name gpio0..n . However, there are cases in which the exposed pins belong to gpiochips other than the first. For example in the case of some OrangePi models or if a Port Expander is used. In these cases it is useful to use the commands to access the Linux GPIO character device to verify the configuration. To install the Linux GPIO character device - binary on a debian based distro like octopi run: sudo apt-get install gpiod To check available gpiochip run: gpiodetect To check the pin number and the pin availability tun: gpioinfo The chosen pin can thus be used within the configuration as gpiochip<n>/gpio<o> where n is the chip number as seen by the gpiodetect command and o is the line number seen by the gpioinfo command. Warning: only gpio marked as unused can be used. It is not possible for a line to be used by multiple processes simultaneously. For example on a RPi 3B+ where klipper use the GPIO20 for a switch: $ gpiodetect gpiochip0 [pinctrl-bcm2835] (54 lines) gpiochip1 [raspberrypi-exp-gpio] (8 lines) $ gpioinfo gpiochip0 - 54 lines: line 0: unnamed unused input active-high line 1: unnamed unused input active-high line 2: unnamed unused input active-high line 3: unnamed unused input active-high line 4: unnamed unused input active-high line 5: unnamed unused input active-high line 6: unnamed unused input active-high line 7: unnamed unused input active-high line 8: unnamed unused input active-high line 9: unnamed unused input active-high line 10: unnamed unused input active-high line 11: unnamed unused input active-high line 12: unnamed unused input active-high line 13: unnamed unused input active-high line 14: unnamed unused input active-high line 15: unnamed unused input active-high line 16: unnamed unused input active-high line 17: unnamed unused input active-high line 18: unnamed unused input active-high line 19: unnamed unused input active-high line 20: unnamed \"klipper\" output active-high [used] line 21: unnamed unused input active-high line 22: unnamed unused input active-high line 23: unnamed unused input active-high line 24: unnamed unused input active-high line 25: unnamed unused input active-high line 26: unnamed unused input active-high line 27: unnamed unused input active-high line 28: unnamed unused input active-high line 29: unnamed \"led0\" output active-high [used] line 30: unnamed unused input active-high line 31: unnamed unused input active-high line 32: unnamed unused input active-high line 33: unnamed unused input active-high line 34: unnamed unused input active-high line 35: unnamed unused input active-high line 36: unnamed unused input active-high line 37: unnamed unused input active-high line 38: unnamed unused input active-high line 39: unnamed unused input active-high line 40: unnamed unused input active-high line 41: unnamed unused input active-high line 42: unnamed unused input active-high line 43: unnamed unused input active-high line 44: unnamed unused input active-high line 45: unnamed unused input active-high line 46: unnamed unused input active-high line 47: unnamed unused input active-high line 48: unnamed unused input active-high line 49: unnamed unused input active-high line 50: unnamed unused input active-high line 51: unnamed unused input active-high line 52: unnamed unused input active-high line 53: unnamed unused input active-high gpiochip1 - 8 lines: line 0: unnamed unused input active-high line 1: unnamed unused input active-high line 2: unnamed \"led1\" output active-low [used] line 3: unnamed unused input active-high line 4: unnamed unused input active-high line 5: unnamed unused input active-high line 6: unnamed unused input active-high line 7: unnamed unused input active-high","title":"Optional: Identify the correct gpiochip"},{"location":"RPi_microcontroller.html#optional-hardware-pwm","text":"Raspberry Pi's have two PWM channels (PWM0 and PWM1) which are exposed on the header or if not, can be routed to existing gpio pins. The Linux mcu daemon uses the pwmchip sysfs interface to control hardware pwm devices on Linux hosts. The pwm sysfs interface is not exposed by default on a Raspberry and can be activated by adding a line to /boot/config.txt : # Enable pwmchip sysfs interface dtoverlay=pwm,pin=12,func=4 This example enables only PWM0 and routes it to gpio12. If both PWM channels need to be enabled you can use pwm-2chan : # Enable pwmchip sysfs interface dtoverlay=pwm-2chan,pin=12,func=4,pin2=13,func2=4 This example additionally enables PWM1 and routes it to gpio13. The overlay does not expose the pwm line on sysfs on boot and needs to be exported by echo'ing the number of the pwm channel to /sys/class/pwm/pwmchip0/export . This will create device /sys/class/pwm/pwmchip0/pwm0 in the filesystem. The easiest way to do this is by adding this to /etc/rc.local before the exit 0 line: # Enable pwmchip sysfs interface echo 0 > /sys/class/pwm/pwmchip0/export When using both PWM channels, the number of the second channel needs to be echo'd as well: # Enable pwmchip sysfs interface echo 0 > /sys/class/pwm/pwmchip0/export echo 1 > /sys/class/pwm/pwmchip0/export With the sysfs in place, you can now use either the pwm channel(s) by adding the following piece of configuration to your printer.cfg : [output_pin caselight] pin: host:pwmchip0/pwm0 pwm: True hardware_pwm: True cycle_time: 0.000001 [output_pin beeper] pin: host:pwmchip0/pwm1 pwm: True hardware_pwm: True value: 0 shutdown_value: 0 cycle_time: 0.0005 This will add hardware pwm control to gpio12 and gpio13 on the Pi (because the overlay was configured to route pwm0 to pin=12 and pwm1 to pin=13). PWM0 can be routed to gpio12 and gpio18, PWM1 can be routed to gpio13 and gpio19: PWM gpio PIN Func 0 12 4 0 18 2 1 13 4 1 19 2","title":"Optional: Hardware PWM"},{"location":"Releases.html","text":"Releases \u00b6 History of Klipper releases. Please see installation for information on installing Klipper. Klipper 0.13.0 \u00b6 Available on 20250411. Major changes in this release: New \"sweeping vibrations\" resonance testing mechanism for input shaper. Fans and GPIO pins can now be assigned a formula (via Jinja2 \"templates\"). The bed_mesh code now supports \"adaptive bed mesh\". The area probed can be adjusted for the size of the print. A new minimum_cruise_ratio kinematic parameter has been added (it replaces the previous max_accel_to_decel parameter). Several new sensors added: Support for ldc1612 \"eddy\" current sensors. This includes probing support, fast \"scan\" probing, and temperature calibration. New support for \"load cell\" measurements. Support for connecting these load cells to hx71x and ads1220 ADC sensors. Support for BMP180, BMP388, and SHT3x temperature sensors. Support for measuring temperature with ADS1x1x ADC chips. New lis3dh and icm20948 accelerometer support. Support for mt6816 and mt6826s \"hall angle\" sensors. New micro-controller improvements: New support for rp2350 micro-controllers. Existing rp2040 chips now run at 200MHz (up from 125Mhz). The micro-controller code can now define many more commands (up to 16384 from 128). Other modules added: aip31068_spi, canbus_stats, error_mcu, garbage_collection, pwm_cycle_time, pwm_tool, garbage_collection. Several bug fixes and code cleanups. Klipper 0.12.0 \u00b6 Available on 20231110. Major changes in this release: Support for COPY and MIRROR modes on IDEX printers. Several micro-controller improvements: Support for new ar100 and hc32f460 architectures. Support for stm32f7, stm32g0b0, stm32g07x, stm32g4, stm32h723, n32g45x, samc21, and samd21j18 chip variants. Improved DFU and Katapult reboot handling. Improved performance on USB to CANbus bridge mode. Improved performance on \"linux mcu\". New support for software based i2c. New hardware support for tmc2240 stepper motor drivers, lis2dw12 accelerometers, and aht10 temperature sensors. New axis_twist_compensation and temperature_combined modules added. New support for gcode arcs in XY, XZ, and YZ planes. Several bug fixes and code cleanups. Klipper 0.11.0 \u00b6 Available on 20221128. Major changes in this release: Trinamic stepper motor driver \"step on both edges\" optimization. Support for Python3. The Klipper host code will run with either Python2 or Python3. Enhanced CAN bus support. Support for CAN bus on rp2040, stm32g0, stm32h7, same51, and same54 chips. Support for \"USB to CAN bus bridge\" mode. Support for CanBoot bootloader. Support for mpu9250 and mpu6050 accelerometers. Improved error handling for max31856, max31855, max31865, and max6675 temperature sensors. It is now possible to configure LEDs to update during long running G-Code commands using LED \"template\" support. Several micro-controller improvements. New support for stm32h743, stm32h750, stm32l412, stm32g0b1, same70, same51, and same54 chips. Support for i2c reads on atsamd and stm32f0. Hardware pwm support on stm32. Linux mcu signal based event dispatch. New rp2040 support for \"make flash\", i2c, and rp2040-e5 USB errata. New modules added: angle, dac084S085, exclude_object, led, mpu9250, pca9632, smart_effector, z_thermal_adjust. New deltesian kinematics added. New dump_mcu tool added. Several bug fixes and code cleanups. Klipper 0.10.0 \u00b6 Available on 20210929. Major changes in this release: Support for \"Multi-MCU Homing\". It is now possible for a stepper motor and its endstop to be wired to separate micro-controllers. This simplifies wiring of Z probes on \"toolhead boards\". Klipper now has a Community Discord Server and a Community Discourse Server . The Klipper website now uses the \"mkdocs\" infrastructure. There is also a Klipper Translations project. Automated support for flashing firmware via sdcard on many boards. New kinematic support for \"Hybrid CoreXY\" and \"Hybrid CoreXZ\" printers. Klipper now uses rotation_distance to configure stepper motor travel distances. The main Klipper host code can now directly communicate with micro-controllers using CAN bus. New \"motion analysis\" system. Klipper's internal motion updates and sensor results can be tracked and logged for analysis. Trinamic stepper motor drivers are now continuously monitored for error conditions. Support for the rp2040 micro-controller (Raspberry Pi Pico boards). The \"make menuconfig\" system now utilizes kconfiglib. Many additional modules added: ds18b20, duplicate_pin_override, filament_motion_sensor, palette2, motion_report, pca9533, pulse_counter, save_variables, sdcard_loop, temperature_host, temperature_mcu Several bug fixes and code cleanups. Klipper 0.9.0 \u00b6 Available on 20201020. Major changes in this release: Support for \"Input Shaping\" - a mechanism to counteract printer resonance. It can reduce or eliminate \"ringing\" in prints. New \"Smooth Pressure Advance\" system. This implements \"Pressure Advance\" without introducing instantaneous velocity changes. It is also now possible to tune pressure advance using a \"Tuning Tower\" method. New \"webhooks\" API server. This provides a programmable JSON interface to Klipper. The LCD display and menu are now configurable using the Jinja2 template language. The TMC2208 stepper motor drivers can now be used in \"standalone\" mode with Klipper. Improved BL-Touch v3 support. Improved USB identification. Klipper now has its own USB identification code and micro-controllers can now report their unique serial numbers during USB identification. New kinematic support for \"Rotary Delta\" and \"CoreXZ\" printers. Micro-controller improvements: support for stm32f070, support for stm32f207, support for GPIO pins on \"Linux MCU\", stm32 \"HID bootloader\" support, Chitu bootloader support, MKS Robin bootloader support. Improved handling of Python \"garbage collection\" events. Many additional modules added: adc_scaled, adxl345, bme280, display_status, extruder_stepper, fan_generic, hall_filament_width_sensor, htu21d, homing_heaters, input_shaper, lm75, print_stats, resonance_tester, shaper_calibrate, query_adc, graph_accelerometer, graph_extruder, graph_motion, graph_shaper, graph_temp_sensor, whconsole Several bug fixes and code cleanups. Klipper 0.9.1 \u00b6 Available on 20201028. Release containing only bug fixes. Klipper 0.8.0 \u00b6 Available on 20191021. Major changes in this release: New G-Code command template support. G-Code in the config file is now evaluated with the Jinja2 template language. Improvements to Trinamic stepper drivers: New support for TMC2209 and TMC5160 drivers. Improved DUMP_TMC, SET_TMC_CURRENT, and INIT_TMC G-Code commands. Improved support for TMC UART handling with an analog mux. Improved homing, probing, and bed leveling support: New manual_probe, bed_screws, screws_tilt_adjust, skew_correction, safe_z_home modules added. Enhanced multi-sample probing with median, average, and retry logic. Improved documentation for BL-Touch, probe calibration, endstop calibration, delta calibration, sensorless homing, and endstop phase calibration. Improved homing support on a large Z axis. Many Klipper micro-controller improvements: Klipper ported to: SAM3X8C, SAM4S8C, SAMD51, STM32F042, STM32F4 New USB CDC driver implementations on SAM3X, SAM4, STM32F4. Enhanced support for flashing Klipper over USB. Software SPI support. Greatly improved temperature filtering on the LPC176x. Early output pin settings can be configured in the micro-controller. New website with the Klipper documentation: http://klipper3d.org/ Klipper now has a logo. Experimental support for polar and \"cable winch\" kinematics. The config file can now include other config files. Many additional modules added: board_pins, controller_fan, delayed_gcode, dotstar, filament_switch_sensor, firmware_retraction, gcode_arcs, gcode_button, heater_generic, manual_stepper, mcp4018, mcp4728, neopixel, pause_resume, respond, temperature_sensor tsl1401cl_filament_width_sensor, tuning_tower Many additional commands added: RESTORE_GCODE_STATE, SAVE_GCODE_STATE, SET_GCODE_VARIABLE, SET_HEATER_TEMPERATURE, SET_IDLE_TIMEOUT, SET_TEMPERATURE_FAN_TARGET Several bug fixes and code cleanups. Klipper 0.7.0 \u00b6 Available on 20181220. Major changes in this release: Klipper now supports \"mesh\" bed leveling New support for \"enhanced\" delta calibration (calibrates print x/y dimensions on delta printers) Support for run-time configuration of Trinamic stepper motor drivers (tmc2130, tmc2208, tmc2660) Improved temperature sensor support: MAX6675, MAX31855, MAX31856, MAX31865, custom thermistors, common pt100 style sensors Several new modules: temperature_fan, sx1509, force_move, mcp4451, z_tilt, quad_gantry_level, endstop_phase, bltouch Several new commands added: SAVE_CONFIG, SET_PRESSURE_ADVANCE, SET_GCODE_OFFSET, SET_VELOCITY_LIMIT, STEPPER_BUZZ, TURN_OFF_HEATERS, M204, custom g-code macros Expanded LCD display support: Support for run-time menus New display icons Support for \"uc1701\" and \"ssd1306\" displays Additional micro-controller support: Klipper ported to: LPC176x (Smoothieboards), SAM4E8E (Duet2), SAMD21 (Arduino Zero), STM32F103 (\"Blue pill\" devices), atmega32u4 New Generic USB CDC driver implemented on AVR, LPC176x, SAMD21, and STM32F103 Performance improvements on ARM processors The kinematics code was rewritten to use an \"iterative solver\" New automatic test cases for the Klipper host software Many new example config files for common off-the-shelf printers Documentation updates for bootloaders, benchmarking, micro-controller porting, config checks, pin mapping, slicer settings, packaging, and more Several bug fixes and code cleanups Klipper 0.6.0 \u00b6 Available on 20180331. Major changes in this release: Enhanced heater and thermistor hardware failure checks Support for Z probes Initial support for automatic parameter calibration on deltas (via a new delta_calibrate command) Initial support for bed tilt compensation (via bed_tilt_calibrate command) Initial support for \"safe homing\" and homing overrides Initial support for displaying status on RepRapDiscount style 2004 and 12864 displays New multi-extruder improvements: Support for shared heaters Initial support for dual carriages Support for configuring multiple steppers per axis (eg, dual Z) Support for custom digital and pwm output pins (with a new SET_PIN command) Initial support for a \"virtual sdcard\" that allows printing directly from Klipper (helps on machines too slow to run OctoPrint well) Support for setting different arm lengths on each tower of a delta Support for G-Code M220/M221 commands (speed factor override / extrude factor override) Several documentation updates: Many new example config files for common off-the-shelf printers New multiple MCU config example New bltouch sensor config example New FAQ, config check, and G-Code documents Initial support for continuous integration testing on all github commits Several bug fixes and code cleanups Klipper 0.5.0 \u00b6 Available on 20171025. Major changes in this release: Support for printers with multiple extruders. Initial support for running on the Beaglebone PRU. Initial support for the Replicape board. Initial support for running the micro-controller code in a real-time Linux process. Support for multiple micro-controllers. (For example, one could control an extruder with one micro-controller and the rest of the printer with another.) Software clock synchronization is implemented to coordinate actions between micro-controllers. Stepper performance improvements (20Mhz AVRs up to 189K steps per second). Support for controlling servos and support for defining nozzle cooling fans. Several bug fixes and code cleanups Klipper 0.4.0 \u00b6 Available on 20170503. Major changes in this release: Improved installation on Raspberry Pi machines. Most of the install is now scripted. Support for corexy kinematics Documentation updates: New Kinematics document, new Pressure Advance tuning guide, new example config files, and more Stepper performance improvements (20Mhz AVRs over 175K steps per second, Arduino Due over 460K) Support for automatic micro-controller resets. Support for resets via toggling USB power on Raspberry Pi. The pressure advance algorithm now works with look-ahead to reduce pressure changes during cornering. Support for limiting the top speed of short zigzag moves Support for AD595 sensors Several bug fixes and code cleanups Klipper 0.3.0 \u00b6 Available on 20161223. Major changes in this release: Improved documentation Support for robots with delta kinematics Support for Arduino Due micro-controller (ARM cortex-M3) Support for USB based AVR micro-controllers Support for \"pressure advance\" algorithm - it reduces ooze during prints. New \"stepper phased based endstop\" feature - enables higher precision on endstop homing. Support for \"extended g-code\" commands such as \"help\", \"restart\", and \"status\". Support for reloading the Klipper config and restarting the host software by issuing a \"restart\" command from the terminal. Stepper performance improvements (20Mhz AVRs up to 158K steps per second). Improved error reporting. Most errors now shown via the terminal along with help on how to resolve. Several bug fixes and code cleanups Klipper 0.2.0 \u00b6 Initial release of Klipper. Available on 20160525. Major features available in the initial release include: Basic support for cartesian printers (steppers, extruder, heated bed, cooling fan). Support for common g-code commands. Support for interfacing with OctoPrint. Acceleration and lookahead handling Support for AVR micro-controllers via standard serial ports","title":"Releases"},{"location":"Releases.html#releases","text":"History of Klipper releases. Please see installation for information on installing Klipper.","title":"Releases"},{"location":"Releases.html#klipper-0130","text":"Available on 20250411. Major changes in this release: New \"sweeping vibrations\" resonance testing mechanism for input shaper. Fans and GPIO pins can now be assigned a formula (via Jinja2 \"templates\"). The bed_mesh code now supports \"adaptive bed mesh\". The area probed can be adjusted for the size of the print. A new minimum_cruise_ratio kinematic parameter has been added (it replaces the previous max_accel_to_decel parameter). Several new sensors added: Support for ldc1612 \"eddy\" current sensors. This includes probing support, fast \"scan\" probing, and temperature calibration. New support for \"load cell\" measurements. Support for connecting these load cells to hx71x and ads1220 ADC sensors. Support for BMP180, BMP388, and SHT3x temperature sensors. Support for measuring temperature with ADS1x1x ADC chips. New lis3dh and icm20948 accelerometer support. Support for mt6816 and mt6826s \"hall angle\" sensors. New micro-controller improvements: New support for rp2350 micro-controllers. Existing rp2040 chips now run at 200MHz (up from 125Mhz). The micro-controller code can now define many more commands (up to 16384 from 128). Other modules added: aip31068_spi, canbus_stats, error_mcu, garbage_collection, pwm_cycle_time, pwm_tool, garbage_collection. Several bug fixes and code cleanups.","title":"Klipper 0.13.0"},{"location":"Releases.html#klipper-0120","text":"Available on 20231110. Major changes in this release: Support for COPY and MIRROR modes on IDEX printers. Several micro-controller improvements: Support for new ar100 and hc32f460 architectures. Support for stm32f7, stm32g0b0, stm32g07x, stm32g4, stm32h723, n32g45x, samc21, and samd21j18 chip variants. Improved DFU and Katapult reboot handling. Improved performance on USB to CANbus bridge mode. Improved performance on \"linux mcu\". New support for software based i2c. New hardware support for tmc2240 stepper motor drivers, lis2dw12 accelerometers, and aht10 temperature sensors. New axis_twist_compensation and temperature_combined modules added. New support for gcode arcs in XY, XZ, and YZ planes. Several bug fixes and code cleanups.","title":"Klipper 0.12.0"},{"location":"Releases.html#klipper-0110","text":"Available on 20221128. Major changes in this release: Trinamic stepper motor driver \"step on both edges\" optimization. Support for Python3. The Klipper host code will run with either Python2 or Python3. Enhanced CAN bus support. Support for CAN bus on rp2040, stm32g0, stm32h7, same51, and same54 chips. Support for \"USB to CAN bus bridge\" mode. Support for CanBoot bootloader. Support for mpu9250 and mpu6050 accelerometers. Improved error handling for max31856, max31855, max31865, and max6675 temperature sensors. It is now possible to configure LEDs to update during long running G-Code commands using LED \"template\" support. Several micro-controller improvements. New support for stm32h743, stm32h750, stm32l412, stm32g0b1, same70, same51, and same54 chips. Support for i2c reads on atsamd and stm32f0. Hardware pwm support on stm32. Linux mcu signal based event dispatch. New rp2040 support for \"make flash\", i2c, and rp2040-e5 USB errata. New modules added: angle, dac084S085, exclude_object, led, mpu9250, pca9632, smart_effector, z_thermal_adjust. New deltesian kinematics added. New dump_mcu tool added. Several bug fixes and code cleanups.","title":"Klipper 0.11.0"},{"location":"Releases.html#klipper-0100","text":"Available on 20210929. Major changes in this release: Support for \"Multi-MCU Homing\". It is now possible for a stepper motor and its endstop to be wired to separate micro-controllers. This simplifies wiring of Z probes on \"toolhead boards\". Klipper now has a Community Discord Server and a Community Discourse Server . The Klipper website now uses the \"mkdocs\" infrastructure. There is also a Klipper Translations project. Automated support for flashing firmware via sdcard on many boards. New kinematic support for \"Hybrid CoreXY\" and \"Hybrid CoreXZ\" printers. Klipper now uses rotation_distance to configure stepper motor travel distances. The main Klipper host code can now directly communicate with micro-controllers using CAN bus. New \"motion analysis\" system. Klipper's internal motion updates and sensor results can be tracked and logged for analysis. Trinamic stepper motor drivers are now continuously monitored for error conditions. Support for the rp2040 micro-controller (Raspberry Pi Pico boards). The \"make menuconfig\" system now utilizes kconfiglib. Many additional modules added: ds18b20, duplicate_pin_override, filament_motion_sensor, palette2, motion_report, pca9533, pulse_counter, save_variables, sdcard_loop, temperature_host, temperature_mcu Several bug fixes and code cleanups.","title":"Klipper 0.10.0"},{"location":"Releases.html#klipper-090","text":"Available on 20201020. Major changes in this release: Support for \"Input Shaping\" - a mechanism to counteract printer resonance. It can reduce or eliminate \"ringing\" in prints. New \"Smooth Pressure Advance\" system. This implements \"Pressure Advance\" without introducing instantaneous velocity changes. It is also now possible to tune pressure advance using a \"Tuning Tower\" method. New \"webhooks\" API server. This provides a programmable JSON interface to Klipper. The LCD display and menu are now configurable using the Jinja2 template language. The TMC2208 stepper motor drivers can now be used in \"standalone\" mode with Klipper. Improved BL-Touch v3 support. Improved USB identification. Klipper now has its own USB identification code and micro-controllers can now report their unique serial numbers during USB identification. New kinematic support for \"Rotary Delta\" and \"CoreXZ\" printers. Micro-controller improvements: support for stm32f070, support for stm32f207, support for GPIO pins on \"Linux MCU\", stm32 \"HID bootloader\" support, Chitu bootloader support, MKS Robin bootloader support. Improved handling of Python \"garbage collection\" events. Many additional modules added: adc_scaled, adxl345, bme280, display_status, extruder_stepper, fan_generic, hall_filament_width_sensor, htu21d, homing_heaters, input_shaper, lm75, print_stats, resonance_tester, shaper_calibrate, query_adc, graph_accelerometer, graph_extruder, graph_motion, graph_shaper, graph_temp_sensor, whconsole Several bug fixes and code cleanups.","title":"Klipper 0.9.0"},{"location":"Releases.html#klipper-091","text":"Available on 20201028. Release containing only bug fixes.","title":"Klipper 0.9.1"},{"location":"Releases.html#klipper-080","text":"Available on 20191021. Major changes in this release: New G-Code command template support. G-Code in the config file is now evaluated with the Jinja2 template language. Improvements to Trinamic stepper drivers: New support for TMC2209 and TMC5160 drivers. Improved DUMP_TMC, SET_TMC_CURRENT, and INIT_TMC G-Code commands. Improved support for TMC UART handling with an analog mux. Improved homing, probing, and bed leveling support: New manual_probe, bed_screws, screws_tilt_adjust, skew_correction, safe_z_home modules added. Enhanced multi-sample probing with median, average, and retry logic. Improved documentation for BL-Touch, probe calibration, endstop calibration, delta calibration, sensorless homing, and endstop phase calibration. Improved homing support on a large Z axis. Many Klipper micro-controller improvements: Klipper ported to: SAM3X8C, SAM4S8C, SAMD51, STM32F042, STM32F4 New USB CDC driver implementations on SAM3X, SAM4, STM32F4. Enhanced support for flashing Klipper over USB. Software SPI support. Greatly improved temperature filtering on the LPC176x. Early output pin settings can be configured in the micro-controller. New website with the Klipper documentation: http://klipper3d.org/ Klipper now has a logo. Experimental support for polar and \"cable winch\" kinematics. The config file can now include other config files. Many additional modules added: board_pins, controller_fan, delayed_gcode, dotstar, filament_switch_sensor, firmware_retraction, gcode_arcs, gcode_button, heater_generic, manual_stepper, mcp4018, mcp4728, neopixel, pause_resume, respond, temperature_sensor tsl1401cl_filament_width_sensor, tuning_tower Many additional commands added: RESTORE_GCODE_STATE, SAVE_GCODE_STATE, SET_GCODE_VARIABLE, SET_HEATER_TEMPERATURE, SET_IDLE_TIMEOUT, SET_TEMPERATURE_FAN_TARGET Several bug fixes and code cleanups.","title":"Klipper 0.8.0"},{"location":"Releases.html#klipper-070","text":"Available on 20181220. Major changes in this release: Klipper now supports \"mesh\" bed leveling New support for \"enhanced\" delta calibration (calibrates print x/y dimensions on delta printers) Support for run-time configuration of Trinamic stepper motor drivers (tmc2130, tmc2208, tmc2660) Improved temperature sensor support: MAX6675, MAX31855, MAX31856, MAX31865, custom thermistors, common pt100 style sensors Several new modules: temperature_fan, sx1509, force_move, mcp4451, z_tilt, quad_gantry_level, endstop_phase, bltouch Several new commands added: SAVE_CONFIG, SET_PRESSURE_ADVANCE, SET_GCODE_OFFSET, SET_VELOCITY_LIMIT, STEPPER_BUZZ, TURN_OFF_HEATERS, M204, custom g-code macros Expanded LCD display support: Support for run-time menus New display icons Support for \"uc1701\" and \"ssd1306\" displays Additional micro-controller support: Klipper ported to: LPC176x (Smoothieboards), SAM4E8E (Duet2), SAMD21 (Arduino Zero), STM32F103 (\"Blue pill\" devices), atmega32u4 New Generic USB CDC driver implemented on AVR, LPC176x, SAMD21, and STM32F103 Performance improvements on ARM processors The kinematics code was rewritten to use an \"iterative solver\" New automatic test cases for the Klipper host software Many new example config files for common off-the-shelf printers Documentation updates for bootloaders, benchmarking, micro-controller porting, config checks, pin mapping, slicer settings, packaging, and more Several bug fixes and code cleanups","title":"Klipper 0.7.0"},{"location":"Releases.html#klipper-060","text":"Available on 20180331. Major changes in this release: Enhanced heater and thermistor hardware failure checks Support for Z probes Initial support for automatic parameter calibration on deltas (via a new delta_calibrate command) Initial support for bed tilt compensation (via bed_tilt_calibrate command) Initial support for \"safe homing\" and homing overrides Initial support for displaying status on RepRapDiscount style 2004 and 12864 displays New multi-extruder improvements: Support for shared heaters Initial support for dual carriages Support for configuring multiple steppers per axis (eg, dual Z) Support for custom digital and pwm output pins (with a new SET_PIN command) Initial support for a \"virtual sdcard\" that allows printing directly from Klipper (helps on machines too slow to run OctoPrint well) Support for setting different arm lengths on each tower of a delta Support for G-Code M220/M221 commands (speed factor override / extrude factor override) Several documentation updates: Many new example config files for common off-the-shelf printers New multiple MCU config example New bltouch sensor config example New FAQ, config check, and G-Code documents Initial support for continuous integration testing on all github commits Several bug fixes and code cleanups","title":"Klipper 0.6.0"},{"location":"Releases.html#klipper-050","text":"Available on 20171025. Major changes in this release: Support for printers with multiple extruders. Initial support for running on the Beaglebone PRU. Initial support for the Replicape board. Initial support for running the micro-controller code in a real-time Linux process. Support for multiple micro-controllers. (For example, one could control an extruder with one micro-controller and the rest of the printer with another.) Software clock synchronization is implemented to coordinate actions between micro-controllers. Stepper performance improvements (20Mhz AVRs up to 189K steps per second). Support for controlling servos and support for defining nozzle cooling fans. Several bug fixes and code cleanups","title":"Klipper 0.5.0"},{"location":"Releases.html#klipper-040","text":"Available on 20170503. Major changes in this release: Improved installation on Raspberry Pi machines. Most of the install is now scripted. Support for corexy kinematics Documentation updates: New Kinematics document, new Pressure Advance tuning guide, new example config files, and more Stepper performance improvements (20Mhz AVRs over 175K steps per second, Arduino Due over 460K) Support for automatic micro-controller resets. Support for resets via toggling USB power on Raspberry Pi. The pressure advance algorithm now works with look-ahead to reduce pressure changes during cornering. Support for limiting the top speed of short zigzag moves Support for AD595 sensors Several bug fixes and code cleanups","title":"Klipper 0.4.0"},{"location":"Releases.html#klipper-030","text":"Available on 20161223. Major changes in this release: Improved documentation Support for robots with delta kinematics Support for Arduino Due micro-controller (ARM cortex-M3) Support for USB based AVR micro-controllers Support for \"pressure advance\" algorithm - it reduces ooze during prints. New \"stepper phased based endstop\" feature - enables higher precision on endstop homing. Support for \"extended g-code\" commands such as \"help\", \"restart\", and \"status\". Support for reloading the Klipper config and restarting the host software by issuing a \"restart\" command from the terminal. Stepper performance improvements (20Mhz AVRs up to 158K steps per second). Improved error reporting. Most errors now shown via the terminal along with help on how to resolve. Several bug fixes and code cleanups","title":"Klipper 0.3.0"},{"location":"Releases.html#klipper-020","text":"Initial release of Klipper. Available on 20160525. Major features available in the initial release include: Basic support for cartesian printers (steppers, extruder, heated bed, cooling fan). Support for common g-code commands. Support for interfacing with OctoPrint. Acceleration and lookahead handling Support for AVR micro-controllers via standard serial ports","title":"Klipper 0.2.0"},{"location":"Resonance_Compensation.html","text":"Resonance Compensation \u00b6 Klipper supports Input Shaping - a technique that can be used to reduce ringing (also known as echoing, ghosting or rippling) in prints. Ringing is a surface printing defect when, typically, elements like edges repeat themselves on a printed surface as a subtle 'echo': | | | Ringing is caused by mechanical vibrations in the printer due to quick changes of the printing direction. Note that ringing usually has mechanical origins: insufficiently rigid printer frame, non-tight or too springy belts, alignment issues of mechanical parts, heavy moving mass, etc. Those should be checked and fixed first, if possible. Input shaping is an open-loop control technique which creates a commanding signal that cancels its own vibrations. Input shaping requires some tuning and measurements before it can be enabled. Besides ringing, Input Shaping typically reduces the vibrations and shaking of the printer in general, and may also improve the reliability of the stealthChop mode of Trinamic stepper drivers. Tuning \u00b6 Basic tuning requires measuring the ringing frequencies of the printer by printing a test model. Slice the ringing test model, which can be found in docs/prints/ringing_tower.stl , in the slicer: Suggested layer height is 0.2 or 0.25 mm. Infill and top layers can be set to 0. Use 1-2 perimeters, or even better the smooth vase mode with 1-2 mm base. Use sufficiently high speed, around 80-100 mm/sec, for external perimeters. Make sure that the minimum layer time is at most 3 seconds. Make sure any \"dynamic acceleration control\" is disabled in the slicer. Do not turn the model. The model has X and Y marks at the back of the model. Note the unusual location of the marks vs. the axes of the printer - it is not a mistake. The marks can be used later in the tuning process as a reference, because they show which axis the measurements correspond to. Ringing frequency \u00b6 First, measure the ringing frequency . If square_corner_velocity parameter was changed, revert it back to 5.0. It is not advised to increase it when using input shaper because it can cause more smoothing in parts - it is better to use higher acceleration value instead. Disable the minimum_cruise_ratio feature by issuing the following command: SET_VELOCITY_LIMIT MINIMUM_CRUISE_RATIO=0 Disable Pressure Advance: SET_PRESSURE_ADVANCE ADVANCE=0 If you have already added [input_shaper] section to the printer.cfg, execute SET_INPUT_SHAPER SHAPER_FREQ_X=0 SHAPER_FREQ_Y=0 command. If you get \"Unknown command\" error, you can safely ignore it at this point and continue with the measurements. Execute the command: TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5 Basically, we try to make ringing more pronounced by setting different large values for acceleration. This command will increase the acceleration every 5 mm starting from 1500 mm/sec^2: 1500 mm/sec^2, 2000 mm/sec^2, 2500 mm/sec^2 and so forth up until 7000 mm/sec^2 at the last band. Print the test model sliced with the suggested parameters. You can stop the print earlier if the ringing is clearly visible and you see that acceleration gets too high for your printer (e.g. printer shakes too much or starts skipping steps). Use X and Y marks at the back of the model for reference. The measurements from the side with X mark should be used for X axis configuration , and Y mark - for Y axis configuration. Measure the distance D (in mm) between several oscillations on the part with X mark, near the notches, preferably skipping the first oscillation or two. To measure the distance between oscillations more easily, mark the oscillations first, then measure the distance between the marks with a ruler or calipers: | | | Count how many oscillations N the measured distance D corresponds to. If you are unsure how to count the oscillations, refer to the picture above, which shows N = 6 oscillations. Compute the ringing frequency of X axis as V \u00b7 N / D (Hz), where V is the velocity for outer perimeters (mm/sec). For the example above, we marked 6 oscillations, and the test was printed at 100 mm/sec velocity, so the frequency is 100 * 6 / 12.14 \u2248 49.4 Hz. Do (8) - (10) for Y mark as well. Note that ringing on the test print should follow the pattern of the curved notches, as in the picture above. If it doesn't, then this defect is not really a ringing and has a different origin - either mechanical, or an extruder issue. It should be fixed first before enabling and tuning input shapers. If the measurements are not reliable because, say, the distance between the oscillations is not stable, it might mean that the printer has several resonance frequencies on the same axis. One may try to follow the tuning process described in Unreliable measurements of ringing frequencies section instead and still get something out of the input shaping technique. Ringing frequency can depend on the position of the model within the buildplate and Z height, especially on delta printers ; you can check if you see the differences in frequencies at different positions along the sides of the test model and at different heights. You can calculate the average ringing frequencies over X and Y axes if that is the case. If the measured ringing frequency is very low (below approx 20-25 Hz), it might be a good idea to invest into stiffening the printer or decreasing the moving mass - depending on what is applicable in your case - before proceeding with further input shaping tuning, and re-measuring the frequencies afterwards. For many popular printer models there are often some solutions available already. Note that the ringing frequencies can change if the changes are made to the printer that affect the moving mass or change the stiffness of the system, for example: Some tools are installed, removed or replaced on the toolhead that change its mass, e.g. a new (heavier or lighter) stepper motor for direct extruder or a new hotend is installed, heavy fan with a duct is added, etc. Belts are tightened. Some addons to increase frame rigidity are installed. Different bed is installed on a bed-slinger printer, or glass added, etc. If such changes are made, it is a good idea to at least measure the ringing frequencies to see if they have changed. Input shaper configuration \u00b6 After the ringing frequencies for X and Y axes are measured, you can add the following section to your printer.cfg : [input_shaper] shaper_freq_x: ... # frequency for the X mark of the test model shaper_freq_y: ... # frequency for the Y mark of the test model For the example above, we get shaper_freq_x/y = 49.4. Choosing input shaper \u00b6 Klipper supports several input shapers. They differ in their sensitivity to errors determining the resonance frequency and how much smoothing they cause in the printed parts. Also, some of the shapers like 2HUMP_EI and 3HUMP_EI should usually not be used with shaper_freq = resonance frequency - they are configured from different considerations to reduce several resonances at once. For most of the printers, either MZV or EI shapers can be recommended. This section describes a testing process to choose between them, and figure out a few other related parameters. Print the ringing test model as follows: Restart the firmware: RESTART Prepare for test: SET_VELOCITY_LIMIT MINIMUM_CRUISE_RATIO=0 Disable Pressure Advance: SET_PRESSURE_ADVANCE ADVANCE=0 Execute: SET_INPUT_SHAPER SHAPER_TYPE=MZV Execute the command: TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5 Print the test model sliced with the suggested parameters. If you see no ringing at this point, then MZV shaper can be recommended for use. If you do see some ringing, re-measure the frequencies using steps (8)-(10) described in Ringing frequency section. If the frequencies differ significantly from the values you obtained earlier, a more complex input shaper configuration is needed. You can refer to Technical details of Input shapers section. Otherwise, proceed to the next step. Now try EI input shaper. To try it, repeat steps (1)-(6) from above, but executing at step 4 the following command instead: SET_INPUT_SHAPER SHAPER_TYPE=EI . Compare two prints with MZV and EI input shaper. If EI shows noticeably better results than MZV, use EI shaper, otherwise prefer MZV. Note that EI shaper will cause more smoothing in printed parts (see the next section for further details). Add shaper_type: mzv (or ei) parameter to [input_shaper] section, e.g.: [input_shaper] shaper_freq_x: ... shaper_freq_y: ... shaper_type: mzv A few notes on shaper selection: EI shaper may be more suited for bed slinger printers (if the resonance frequency and resulting smoothing allows): as more filament is deposited on the moving bed, the mass of the bed increases and the resonance frequency will decrease. Since EI shaper is more robust to resonance frequency changes, it may work better when printing large parts. Due to the nature of delta kinematics, resonance frequencies can differ a lot in different parts of the build volume. Therefore, EI shaper can be a better fit for delta printers rather than MZV or ZV, and should be considered for the use. If the resonance frequency is sufficiently large (more than 50-60 Hz), then one can even attempt to test 2HUMP_EI shaper (by running the suggested test above with SET_INPUT_SHAPER SHAPER_TYPE=2HUMP_EI ), but check the considerations in the section below before enabling it. Selecting max_accel \u00b6 You should have a printed test for the shaper you chose from the previous step (if you don't, print the test model sliced with the suggested parameters with the pressure advance disabled SET_PRESSURE_ADVANCE ADVANCE=0 and with the tuning tower enabled as TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5 ). Note that at very high accelerations, depending on the resonance frequency and the input shaper you chose (e.g. EI shaper creates more smoothing than MZV), input shaping may cause too much smoothing and rounding of the parts. So, max_accel should be chosen such as to prevent that. Another parameter that can impact smoothing is square_corner_velocity , so it is not advisable to increase it above the default 5 mm/sec to prevent increased smoothing. In order to select a suitable max_accel value, inspect the model for the chosen input shaper. First, take a note at which acceleration ringing is still small - that you are comfortable with it. Next, check the smoothing. To help with that, the test model has a small gap in the wall (0.15 mm): As the acceleration increases, so does the smoothing, and the actual gap in the print widens: In this picture, the acceleration increases left to right, and the gap starts to grow starting from 3500 mm/sec^2 (5-th band from the left). So the good value for max_accel = 3000 (mm/sec^2) in this case to avoid the excessive smoothing. Note the acceleration when the gap is still very small in your test print. If you see bulges, but no gap in the wall at all, even at high accelerations, it may be due to disabled Pressure Advance, especially on Bowden extruders. If that is the case, you may need to repeat the print with the PA enabled. It may also be a result of a miscalibrated (too high) filament flow, so it is a good idea to check that too. Choose the minimum out of the two acceleration values (from ringing and smoothing), and put it as max_accel into printer.cfg. As a note, it may happen - especially at low ringing frequencies - that EI shaper will cause too much smoothing even at lower accelerations. In this case, MZV may be a better choice, because it may allow higher acceleration values. At very low ringing frequencies (~25 Hz and below) even MZV shaper may create too much smoothing. If that is the case, you can also try to repeat the steps in Choosing input shaper section with ZV shaper, by using SET_INPUT_SHAPER SHAPER_TYPE=ZV command instead. ZV shaper should show even less smoothing than MZV, but is more sensitive to errors in measuring the ringing frequencies. Another consideration is that if a resonance frequency is too low (below 20-25 Hz), it might be a good idea to increase the printer stiffness or reduce the moving mass. Otherwise, acceleration and printing speed may be limited due too much smoothing now instead of ringing. Fine-tuning resonance frequencies \u00b6 Note that the precision of the resonance frequencies measurements using the ringing test model is sufficient for most purposes, so further tuning is not advised. If you still want to try to double-check your results (e.g. if you still see some ringing after printing a test model with an input shaper of your choice with the same frequencies as you have measured earlier), you can follow the steps in this section. Note that if you see ringing at different frequencies after enabling [input_shaper], this section will not help with that. Assuming that you have sliced the ringing model with suggested parameters, complete the following steps for each of the axes X and Y: Prepare for test: SET_VELOCITY_LIMIT MINIMUM_CRUISE_RATIO=0 Make sure Pressure Advance is disabled: SET_PRESSURE_ADVANCE ADVANCE=0 Execute: SET_INPUT_SHAPER SHAPER_TYPE=ZV From the existing ringing test model with your chosen input shaper select the acceleration that shows ringing sufficiently well, and set it with: SET_VELOCITY_LIMIT ACCEL=... Calculate the necessary parameters for the TUNING_TOWER command to tune shaper_freq_x parameter as follows: start = shaper_freq_x * 83 / 132 and factor = shaper_freq_x / 66, where shaper_freq_x here is the current value in printer.cfg . Execute the command: TUNING_TOWER COMMAND=SET_INPUT_SHAPER PARAMETER=SHAPER_FREQ_X START=start FACTOR=factor BAND=5 using start and factor values calculated at step (5). Print the test model. Reset the original frequency value: SET_INPUT_SHAPER SHAPER_FREQ_X=... . Find the band which shows ringing the least and count its number from the bottom starting at 1. Calculate the new shaper_freq_x value via old shaper_freq_x * (39 + 5 * #band-number) / 66. Repeat these steps for the Y axis in the same manner, replacing references to X axis with the axis Y (e.g. replace shaper_freq_x with shaper_freq_y in the formulae and in the TUNING_TOWER command). As an example, let's assume you have had measured the ringing frequency for one of the axis equal to 45 Hz. This gives start = 45 * 83 / 132 = 28.30 and factor = 45 / 66 = 0.6818 values for TUNING_TOWER command. Now let's assume that after printing the test model, the fourth band from the bottom gives the least ringing. This gives the updated shaper_freq_? value equal to 45 * (39 + 5 * 4) / 66 \u2248 40.23. After both new shaper_freq_x and shaper_freq_y parameters have been calculated, you can update [input_shaper] section in printer.cfg with the new shaper_freq_x and shaper_freq_y values. Pressure Advance \u00b6 If you use Pressure Advance, it may need to be re-tuned. Follow the instructions to find the new value, if it differs from the previous one. Make sure to restart Klipper before tuning Pressure Advance. Unreliable measurements of ringing frequencies \u00b6 If you are unable to measure the ringing frequencies, e.g. if the distance between the oscillations is not stable, you may still be able to take advantage of input shaping techniques, but the results may not be as good as with proper measurements of the frequencies, and will require a bit more tuning and printing the test model. Note that another possibility is to purchase and install an accelerometer and measure the resonances with it (refer to the docs describing the required hardware and the setup process) - but this option requires some crimping and soldering. For tuning, add empty [input_shaper] section to your printer.cfg . Then, assuming that you have sliced the ringing model with suggested parameters, print the test model 3 times as follows. First time, prior to printing, run RESTART SET_VELOCITY_LIMIT MINIMUM_CRUISE_RATIO=0 SET_PRESSURE_ADVANCE ADVANCE=0 SET_INPUT_SHAPER SHAPER_TYPE=2HUMP_EI SHAPER_FREQ_X=60 SHAPER_FREQ_Y=60 TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5 and print the model. Then print the model again, but before printing run instead SET_INPUT_SHAPER SHAPER_TYPE=2HUMP_EI SHAPER_FREQ_X=50 SHAPER_FREQ_Y=50 TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5 Then print the model for the 3rd time, but now run SET_INPUT_SHAPER SHAPER_TYPE=2HUMP_EI SHAPER_FREQ_X=40 SHAPER_FREQ_Y=40 TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5 Essentially, we are printing the ringing test model with TUNING_TOWER using 2HUMP_EI shaper with shaper_freq = 60 Hz, 50 Hz, and 40 Hz. If none of the models demonstrate improvements in ringing, then, unfortunately, it does not look like the input shaping techniques can help with your case. Otherwise, it may be that all models show no ringing, or some show the ringing and some - not so much. Choose the test model with the highest frequency that still shows good improvements in ringing. For example, if 40 Hz and 50 Hz models show almost no ringing, and 60 Hz model already shows some more ringing, stick with 50 Hz. Now check if EI shaper would be good enough in your case. Choose EI shaper frequency based on the frequency of 2HUMP_EI shaper you chose: For 2HUMP_EI 60 Hz shaper, use EI shaper with shaper_freq = 50 Hz. For 2HUMP_EI 50 Hz shaper, use EI shaper with shaper_freq = 40 Hz. For 2HUMP_EI 40 Hz shaper, use EI shaper with shaper_freq = 33 Hz. Now print the test model one more time, running SET_INPUT_SHAPER SHAPER_TYPE=EI SHAPER_FREQ_X=... SHAPER_FREQ_Y=... TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5 providing the shaper_freq_x=... and shaper_freq_y=... as determined previously. If EI shaper shows very comparable good results as 2HUMP_EI shaper, stick with EI shaper and the frequency determined earlier, otherwise use 2HUMP_EI shaper with the corresponding frequency. Add the results to printer.cfg as, e.g. [input_shaper] shaper_freq_x: 50 shaper_freq_y: 50 shaper_type: 2hump_ei Continue the tuning with Selecting max_accel section. Troubleshooting and FAQ \u00b6 I cannot get reliable measurements of resonance frequencies \u00b6 First, make sure it is not some other problem with the printer instead of ringing. If the measurements are not reliable because, say, the distance between the oscillations is not stable, it might mean that the printer has several resonance frequencies on the same axis. One may try to follow the tuning process described in Unreliable measurements of ringing frequencies section and still get something out of the input shaping technique. Another possibility is to install an accelerometer, measure the resonances with it, and auto-tune the input shaper using the results of those measurements. After enabling [input_shaper], I get too smoothed printed parts and fine details are lost \u00b6 Check the considerations in Selecting max_accel section. If the resonance frequency is low, one should not set too high max_accel or increase square_corner_velocity parameters. It might also be better to choose MZV or even ZV input shapers over EI (or 2HUMP_EI and 3HUMP_EI shapers). After successfully printing for some time without ringing, it appears to come back \u00b6 It is possible that after some time the resonance frequencies have changed. E.g. maybe the belts tension has changed (belts got more loose), etc. It is a good idea to check and re-measure the ringing frequencies as described in Ringing frequency section and update your config file if necessary. Is dual carriage setup supported with input shapers? \u00b6 Yes. In this case, one should measure the resonances twice for each carriage. For example, if the second (dual) carriage is installed on X axis, it is possible to set different input shapers for X axis for the primary and dual carriages. However, the input shaper for Y axis should be the same for both carriages (as ultimately this axis is driven by one or more stepper motors each commanded to perform exactly the same steps). One possibility to configure the input shaper for such setups is to keep [input_shaper] section empty and additionally define a [delayed_gcode] section in the printer.cfg as follows: [input_shaper] # Intentionally empty [delayed_gcode init_shaper] initial_duration: 0.1 gcode: SET_DUAL_CARRIAGE CARRIAGE=1 SET_INPUT_SHAPER SHAPER_TYPE_X=<dual_carriage_shaper> SHAPER_FREQ_X=<dual_carriage_freq> SHAPER_TYPE_Y=<y_shaper> SHAPER_FREQ_Y=<y_freq> SET_DUAL_CARRIAGE CARRIAGE=0 SET_INPUT_SHAPER SHAPER_TYPE_X=<primary_carriage_shaper> SHAPER_FREQ_X=<primary_carriage_freq> SHAPER_TYPE_Y=<y_shaper> SHAPER_FREQ_Y=<y_freq> Note that SHAPER_TYPE_Y and SHAPER_FREQ_Y should be the same in both commands. It is also possible to put a similar snippet into the start g-code in the slicer, however then the shaper will not be enabled until any print is started. Note that the input shaper only needs to be configured once. Subsequent changes of the carriages or their modes via SET_DUAL_CARRIAGE command will preserve the configured input shaper parameters. Does input_shaper affect print time? \u00b6 No, input_shaper feature has pretty much no impact on the print times by itself. However, the value of max_accel certainly does (tuning of this parameter described in this section ). Technical details \u00b6 Input shapers \u00b6 Input shapers used in Klipper are rather standard, and one can find more in-depth overview in the articles describing the corresponding shapers. This section contains a brief overview of some technical aspects of the supported input shapers. The table below shows some (usually approximate) parameters of each shaper. Input shaper Shaper duration Vibration reduction 20x (5% vibration tolerance) Vibration reduction 10x (10% vibration tolerance) ZV 0.5 / shaper_freq N/A \u00b1 5% shaper_freq MZV 0.75 / shaper_freq \u00b1 4% shaper_freq -10%...+15% shaper_freq ZVD 1 / shaper_freq \u00b1 15% shaper_freq \u00b1 22% shaper_freq EI 1 / shaper_freq \u00b1 20% shaper_freq \u00b1 25% shaper_freq 2HUMP_EI 1.5 / shaper_freq \u00b1 35% shaper_freq \u00b1 40 shaper_freq 3HUMP_EI 2 / shaper_freq -45...+50% shaper_freq -50%...+55% shaper_freq A note on vibration reduction: the values in the table above are approximate. If the damping ratio of the printer is known for each axis, the shaper can be configured more precisely and it will then reduce the resonances in a bit wider range of frequencies. However, the damping ratio is usually unknown and is hard to estimate without a special equipment, so Klipper uses 0.1 value by default, which is a good all-round value. The frequency ranges in the table cover a number of different possible damping ratios around that value (approx. from 0.05 to 0.2). Also note that EI, 2HUMP_EI, and 3HUMP_EI are tuned to reduce vibrations to 5%, so the values for 10% vibration tolerance are provided only for the reference. How to use this table: Shaper duration affects the smoothing in parts - the larger it is, the more smooth the parts are. This dependency is not linear, but can give a sense of which shapers 'smooth' more for the same frequency. The ordering by smoothing is like this: ZV < MZV < ZVD \u2248 EI < 2HUMP_EI < 3HUMP_EI. Also, it is rarely practical to set shaper_freq = resonance freq for shapers 2HUMP_EI and 3HUMP_EI (they should be used to reduce vibrations for several frequencies). One can estimate a range of frequencies in which the shaper reduces vibrations. For example, MZV with shaper_freq = 35 Hz reduces vibrations to 5% for frequencies [33.6, 36.4] Hz. 3HUMP_EI with shaper_freq = 50 Hz reduces vibrations to 5% in range [27.5, 75] Hz. One can use this table to check which shaper they should be using if they need to reduce vibrations at several frequencies. For example, if one has resonances at 35 Hz and 60 Hz on the same axis: a) EI shaper needs to have shaper_freq = 35 / (1 - 0.2) = 43.75 Hz, and it will reduce resonances until 43.75 * (1 + 0.2) = 52.5 Hz, so it is not sufficient; b) 2HUMP_EI shaper needs to have shaper_freq = 35 / (1 - 0.35) = 53.85 Hz and will reduce vibrations until 53.85 * (1 + 0.35) = 72.7 Hz - so this is an acceptable configuration. Always try to use as high shaper_freq as possible for a given shaper (perhaps with some safety margin, so in this example shaper_freq \u2248 50-52 Hz would work best), and try to use a shaper with as small shaper duration as possible. If one needs to reduce vibrations at several very different frequencies (say, 30 Hz and 100 Hz), they may see that the table above does not provide enough information. In this case one may have more luck with scripts/graph_shaper.py script, which is more flexible.","title":"Resonance Compensation"},{"location":"Resonance_Compensation.html#resonance-compensation","text":"Klipper supports Input Shaping - a technique that can be used to reduce ringing (also known as echoing, ghosting or rippling) in prints. Ringing is a surface printing defect when, typically, elements like edges repeat themselves on a printed surface as a subtle 'echo': | | | Ringing is caused by mechanical vibrations in the printer due to quick changes of the printing direction. Note that ringing usually has mechanical origins: insufficiently rigid printer frame, non-tight or too springy belts, alignment issues of mechanical parts, heavy moving mass, etc. Those should be checked and fixed first, if possible. Input shaping is an open-loop control technique which creates a commanding signal that cancels its own vibrations. Input shaping requires some tuning and measurements before it can be enabled. Besides ringing, Input Shaping typically reduces the vibrations and shaking of the printer in general, and may also improve the reliability of the stealthChop mode of Trinamic stepper drivers.","title":"Resonance Compensation"},{"location":"Resonance_Compensation.html#tuning","text":"Basic tuning requires measuring the ringing frequencies of the printer by printing a test model. Slice the ringing test model, which can be found in docs/prints/ringing_tower.stl , in the slicer: Suggested layer height is 0.2 or 0.25 mm. Infill and top layers can be set to 0. Use 1-2 perimeters, or even better the smooth vase mode with 1-2 mm base. Use sufficiently high speed, around 80-100 mm/sec, for external perimeters. Make sure that the minimum layer time is at most 3 seconds. Make sure any \"dynamic acceleration control\" is disabled in the slicer. Do not turn the model. The model has X and Y marks at the back of the model. Note the unusual location of the marks vs. the axes of the printer - it is not a mistake. The marks can be used later in the tuning process as a reference, because they show which axis the measurements correspond to.","title":"Tuning"},{"location":"Resonance_Compensation.html#ringing-frequency","text":"First, measure the ringing frequency . If square_corner_velocity parameter was changed, revert it back to 5.0. It is not advised to increase it when using input shaper because it can cause more smoothing in parts - it is better to use higher acceleration value instead. Disable the minimum_cruise_ratio feature by issuing the following command: SET_VELOCITY_LIMIT MINIMUM_CRUISE_RATIO=0 Disable Pressure Advance: SET_PRESSURE_ADVANCE ADVANCE=0 If you have already added [input_shaper] section to the printer.cfg, execute SET_INPUT_SHAPER SHAPER_FREQ_X=0 SHAPER_FREQ_Y=0 command. If you get \"Unknown command\" error, you can safely ignore it at this point and continue with the measurements. Execute the command: TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5 Basically, we try to make ringing more pronounced by setting different large values for acceleration. This command will increase the acceleration every 5 mm starting from 1500 mm/sec^2: 1500 mm/sec^2, 2000 mm/sec^2, 2500 mm/sec^2 and so forth up until 7000 mm/sec^2 at the last band. Print the test model sliced with the suggested parameters. You can stop the print earlier if the ringing is clearly visible and you see that acceleration gets too high for your printer (e.g. printer shakes too much or starts skipping steps). Use X and Y marks at the back of the model for reference. The measurements from the side with X mark should be used for X axis configuration , and Y mark - for Y axis configuration. Measure the distance D (in mm) between several oscillations on the part with X mark, near the notches, preferably skipping the first oscillation or two. To measure the distance between oscillations more easily, mark the oscillations first, then measure the distance between the marks with a ruler or calipers: | | | Count how many oscillations N the measured distance D corresponds to. If you are unsure how to count the oscillations, refer to the picture above, which shows N = 6 oscillations. Compute the ringing frequency of X axis as V \u00b7 N / D (Hz), where V is the velocity for outer perimeters (mm/sec). For the example above, we marked 6 oscillations, and the test was printed at 100 mm/sec velocity, so the frequency is 100 * 6 / 12.14 \u2248 49.4 Hz. Do (8) - (10) for Y mark as well. Note that ringing on the test print should follow the pattern of the curved notches, as in the picture above. If it doesn't, then this defect is not really a ringing and has a different origin - either mechanical, or an extruder issue. It should be fixed first before enabling and tuning input shapers. If the measurements are not reliable because, say, the distance between the oscillations is not stable, it might mean that the printer has several resonance frequencies on the same axis. One may try to follow the tuning process described in Unreliable measurements of ringing frequencies section instead and still get something out of the input shaping technique. Ringing frequency can depend on the position of the model within the buildplate and Z height, especially on delta printers ; you can check if you see the differences in frequencies at different positions along the sides of the test model and at different heights. You can calculate the average ringing frequencies over X and Y axes if that is the case. If the measured ringing frequency is very low (below approx 20-25 Hz), it might be a good idea to invest into stiffening the printer or decreasing the moving mass - depending on what is applicable in your case - before proceeding with further input shaping tuning, and re-measuring the frequencies afterwards. For many popular printer models there are often some solutions available already. Note that the ringing frequencies can change if the changes are made to the printer that affect the moving mass or change the stiffness of the system, for example: Some tools are installed, removed or replaced on the toolhead that change its mass, e.g. a new (heavier or lighter) stepper motor for direct extruder or a new hotend is installed, heavy fan with a duct is added, etc. Belts are tightened. Some addons to increase frame rigidity are installed. Different bed is installed on a bed-slinger printer, or glass added, etc. If such changes are made, it is a good idea to at least measure the ringing frequencies to see if they have changed.","title":"Ringing frequency"},{"location":"Resonance_Compensation.html#input-shaper-configuration","text":"After the ringing frequencies for X and Y axes are measured, you can add the following section to your printer.cfg : [input_shaper] shaper_freq_x: ... # frequency for the X mark of the test model shaper_freq_y: ... # frequency for the Y mark of the test model For the example above, we get shaper_freq_x/y = 49.4.","title":"Input shaper configuration"},{"location":"Resonance_Compensation.html#choosing-input-shaper","text":"Klipper supports several input shapers. They differ in their sensitivity to errors determining the resonance frequency and how much smoothing they cause in the printed parts. Also, some of the shapers like 2HUMP_EI and 3HUMP_EI should usually not be used with shaper_freq = resonance frequency - they are configured from different considerations to reduce several resonances at once. For most of the printers, either MZV or EI shapers can be recommended. This section describes a testing process to choose between them, and figure out a few other related parameters. Print the ringing test model as follows: Restart the firmware: RESTART Prepare for test: SET_VELOCITY_LIMIT MINIMUM_CRUISE_RATIO=0 Disable Pressure Advance: SET_PRESSURE_ADVANCE ADVANCE=0 Execute: SET_INPUT_SHAPER SHAPER_TYPE=MZV Execute the command: TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5 Print the test model sliced with the suggested parameters. If you see no ringing at this point, then MZV shaper can be recommended for use. If you do see some ringing, re-measure the frequencies using steps (8)-(10) described in Ringing frequency section. If the frequencies differ significantly from the values you obtained earlier, a more complex input shaper configuration is needed. You can refer to Technical details of Input shapers section. Otherwise, proceed to the next step. Now try EI input shaper. To try it, repeat steps (1)-(6) from above, but executing at step 4 the following command instead: SET_INPUT_SHAPER SHAPER_TYPE=EI . Compare two prints with MZV and EI input shaper. If EI shows noticeably better results than MZV, use EI shaper, otherwise prefer MZV. Note that EI shaper will cause more smoothing in printed parts (see the next section for further details). Add shaper_type: mzv (or ei) parameter to [input_shaper] section, e.g.: [input_shaper] shaper_freq_x: ... shaper_freq_y: ... shaper_type: mzv A few notes on shaper selection: EI shaper may be more suited for bed slinger printers (if the resonance frequency and resulting smoothing allows): as more filament is deposited on the moving bed, the mass of the bed increases and the resonance frequency will decrease. Since EI shaper is more robust to resonance frequency changes, it may work better when printing large parts. Due to the nature of delta kinematics, resonance frequencies can differ a lot in different parts of the build volume. Therefore, EI shaper can be a better fit for delta printers rather than MZV or ZV, and should be considered for the use. If the resonance frequency is sufficiently large (more than 50-60 Hz), then one can even attempt to test 2HUMP_EI shaper (by running the suggested test above with SET_INPUT_SHAPER SHAPER_TYPE=2HUMP_EI ), but check the considerations in the section below before enabling it.","title":"Choosing input shaper"},{"location":"Resonance_Compensation.html#selecting-max_accel","text":"You should have a printed test for the shaper you chose from the previous step (if you don't, print the test model sliced with the suggested parameters with the pressure advance disabled SET_PRESSURE_ADVANCE ADVANCE=0 and with the tuning tower enabled as TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5 ). Note that at very high accelerations, depending on the resonance frequency and the input shaper you chose (e.g. EI shaper creates more smoothing than MZV), input shaping may cause too much smoothing and rounding of the parts. So, max_accel should be chosen such as to prevent that. Another parameter that can impact smoothing is square_corner_velocity , so it is not advisable to increase it above the default 5 mm/sec to prevent increased smoothing. In order to select a suitable max_accel value, inspect the model for the chosen input shaper. First, take a note at which acceleration ringing is still small - that you are comfortable with it. Next, check the smoothing. To help with that, the test model has a small gap in the wall (0.15 mm): As the acceleration increases, so does the smoothing, and the actual gap in the print widens: In this picture, the acceleration increases left to right, and the gap starts to grow starting from 3500 mm/sec^2 (5-th band from the left). So the good value for max_accel = 3000 (mm/sec^2) in this case to avoid the excessive smoothing. Note the acceleration when the gap is still very small in your test print. If you see bulges, but no gap in the wall at all, even at high accelerations, it may be due to disabled Pressure Advance, especially on Bowden extruders. If that is the case, you may need to repeat the print with the PA enabled. It may also be a result of a miscalibrated (too high) filament flow, so it is a good idea to check that too. Choose the minimum out of the two acceleration values (from ringing and smoothing), and put it as max_accel into printer.cfg. As a note, it may happen - especially at low ringing frequencies - that EI shaper will cause too much smoothing even at lower accelerations. In this case, MZV may be a better choice, because it may allow higher acceleration values. At very low ringing frequencies (~25 Hz and below) even MZV shaper may create too much smoothing. If that is the case, you can also try to repeat the steps in Choosing input shaper section with ZV shaper, by using SET_INPUT_SHAPER SHAPER_TYPE=ZV command instead. ZV shaper should show even less smoothing than MZV, but is more sensitive to errors in measuring the ringing frequencies. Another consideration is that if a resonance frequency is too low (below 20-25 Hz), it might be a good idea to increase the printer stiffness or reduce the moving mass. Otherwise, acceleration and printing speed may be limited due too much smoothing now instead of ringing.","title":"Selecting max_accel"},{"location":"Resonance_Compensation.html#fine-tuning-resonance-frequencies","text":"Note that the precision of the resonance frequencies measurements using the ringing test model is sufficient for most purposes, so further tuning is not advised. If you still want to try to double-check your results (e.g. if you still see some ringing after printing a test model with an input shaper of your choice with the same frequencies as you have measured earlier), you can follow the steps in this section. Note that if you see ringing at different frequencies after enabling [input_shaper], this section will not help with that. Assuming that you have sliced the ringing model with suggested parameters, complete the following steps for each of the axes X and Y: Prepare for test: SET_VELOCITY_LIMIT MINIMUM_CRUISE_RATIO=0 Make sure Pressure Advance is disabled: SET_PRESSURE_ADVANCE ADVANCE=0 Execute: SET_INPUT_SHAPER SHAPER_TYPE=ZV From the existing ringing test model with your chosen input shaper select the acceleration that shows ringing sufficiently well, and set it with: SET_VELOCITY_LIMIT ACCEL=... Calculate the necessary parameters for the TUNING_TOWER command to tune shaper_freq_x parameter as follows: start = shaper_freq_x * 83 / 132 and factor = shaper_freq_x / 66, where shaper_freq_x here is the current value in printer.cfg . Execute the command: TUNING_TOWER COMMAND=SET_INPUT_SHAPER PARAMETER=SHAPER_FREQ_X START=start FACTOR=factor BAND=5 using start and factor values calculated at step (5). Print the test model. Reset the original frequency value: SET_INPUT_SHAPER SHAPER_FREQ_X=... . Find the band which shows ringing the least and count its number from the bottom starting at 1. Calculate the new shaper_freq_x value via old shaper_freq_x * (39 + 5 * #band-number) / 66. Repeat these steps for the Y axis in the same manner, replacing references to X axis with the axis Y (e.g. replace shaper_freq_x with shaper_freq_y in the formulae and in the TUNING_TOWER command). As an example, let's assume you have had measured the ringing frequency for one of the axis equal to 45 Hz. This gives start = 45 * 83 / 132 = 28.30 and factor = 45 / 66 = 0.6818 values for TUNING_TOWER command. Now let's assume that after printing the test model, the fourth band from the bottom gives the least ringing. This gives the updated shaper_freq_? value equal to 45 * (39 + 5 * 4) / 66 \u2248 40.23. After both new shaper_freq_x and shaper_freq_y parameters have been calculated, you can update [input_shaper] section in printer.cfg with the new shaper_freq_x and shaper_freq_y values.","title":"Fine-tuning resonance frequencies"},{"location":"Resonance_Compensation.html#pressure-advance","text":"If you use Pressure Advance, it may need to be re-tuned. Follow the instructions to find the new value, if it differs from the previous one. Make sure to restart Klipper before tuning Pressure Advance.","title":"Pressure Advance"},{"location":"Resonance_Compensation.html#unreliable-measurements-of-ringing-frequencies","text":"If you are unable to measure the ringing frequencies, e.g. if the distance between the oscillations is not stable, you may still be able to take advantage of input shaping techniques, but the results may not be as good as with proper measurements of the frequencies, and will require a bit more tuning and printing the test model. Note that another possibility is to purchase and install an accelerometer and measure the resonances with it (refer to the docs describing the required hardware and the setup process) - but this option requires some crimping and soldering. For tuning, add empty [input_shaper] section to your printer.cfg . Then, assuming that you have sliced the ringing model with suggested parameters, print the test model 3 times as follows. First time, prior to printing, run RESTART SET_VELOCITY_LIMIT MINIMUM_CRUISE_RATIO=0 SET_PRESSURE_ADVANCE ADVANCE=0 SET_INPUT_SHAPER SHAPER_TYPE=2HUMP_EI SHAPER_FREQ_X=60 SHAPER_FREQ_Y=60 TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5 and print the model. Then print the model again, but before printing run instead SET_INPUT_SHAPER SHAPER_TYPE=2HUMP_EI SHAPER_FREQ_X=50 SHAPER_FREQ_Y=50 TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5 Then print the model for the 3rd time, but now run SET_INPUT_SHAPER SHAPER_TYPE=2HUMP_EI SHAPER_FREQ_X=40 SHAPER_FREQ_Y=40 TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5 Essentially, we are printing the ringing test model with TUNING_TOWER using 2HUMP_EI shaper with shaper_freq = 60 Hz, 50 Hz, and 40 Hz. If none of the models demonstrate improvements in ringing, then, unfortunately, it does not look like the input shaping techniques can help with your case. Otherwise, it may be that all models show no ringing, or some show the ringing and some - not so much. Choose the test model with the highest frequency that still shows good improvements in ringing. For example, if 40 Hz and 50 Hz models show almost no ringing, and 60 Hz model already shows some more ringing, stick with 50 Hz. Now check if EI shaper would be good enough in your case. Choose EI shaper frequency based on the frequency of 2HUMP_EI shaper you chose: For 2HUMP_EI 60 Hz shaper, use EI shaper with shaper_freq = 50 Hz. For 2HUMP_EI 50 Hz shaper, use EI shaper with shaper_freq = 40 Hz. For 2HUMP_EI 40 Hz shaper, use EI shaper with shaper_freq = 33 Hz. Now print the test model one more time, running SET_INPUT_SHAPER SHAPER_TYPE=EI SHAPER_FREQ_X=... SHAPER_FREQ_Y=... TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5 providing the shaper_freq_x=... and shaper_freq_y=... as determined previously. If EI shaper shows very comparable good results as 2HUMP_EI shaper, stick with EI shaper and the frequency determined earlier, otherwise use 2HUMP_EI shaper with the corresponding frequency. Add the results to printer.cfg as, e.g. [input_shaper] shaper_freq_x: 50 shaper_freq_y: 50 shaper_type: 2hump_ei Continue the tuning with Selecting max_accel section.","title":"Unreliable measurements of ringing frequencies"},{"location":"Resonance_Compensation.html#troubleshooting-and-faq","text":"","title":"Troubleshooting and FAQ"},{"location":"Resonance_Compensation.html#i-cannot-get-reliable-measurements-of-resonance-frequencies","text":"First, make sure it is not some other problem with the printer instead of ringing. If the measurements are not reliable because, say, the distance between the oscillations is not stable, it might mean that the printer has several resonance frequencies on the same axis. One may try to follow the tuning process described in Unreliable measurements of ringing frequencies section and still get something out of the input shaping technique. Another possibility is to install an accelerometer, measure the resonances with it, and auto-tune the input shaper using the results of those measurements.","title":"I cannot get reliable measurements of resonance frequencies"},{"location":"Resonance_Compensation.html#after-enabling-input_shaper-i-get-too-smoothed-printed-parts-and-fine-details-are-lost","text":"Check the considerations in Selecting max_accel section. If the resonance frequency is low, one should not set too high max_accel or increase square_corner_velocity parameters. It might also be better to choose MZV or even ZV input shapers over EI (or 2HUMP_EI and 3HUMP_EI shapers).","title":"After enabling [input_shaper], I get too smoothed printed parts and fine details are lost"},{"location":"Resonance_Compensation.html#after-successfully-printing-for-some-time-without-ringing-it-appears-to-come-back","text":"It is possible that after some time the resonance frequencies have changed. E.g. maybe the belts tension has changed (belts got more loose), etc. It is a good idea to check and re-measure the ringing frequencies as described in Ringing frequency section and update your config file if necessary.","title":"After successfully printing for some time without ringing, it appears to come back"},{"location":"Resonance_Compensation.html#is-dual-carriage-setup-supported-with-input-shapers","text":"Yes. In this case, one should measure the resonances twice for each carriage. For example, if the second (dual) carriage is installed on X axis, it is possible to set different input shapers for X axis for the primary and dual carriages. However, the input shaper for Y axis should be the same for both carriages (as ultimately this axis is driven by one or more stepper motors each commanded to perform exactly the same steps). One possibility to configure the input shaper for such setups is to keep [input_shaper] section empty and additionally define a [delayed_gcode] section in the printer.cfg as follows: [input_shaper] # Intentionally empty [delayed_gcode init_shaper] initial_duration: 0.1 gcode: SET_DUAL_CARRIAGE CARRIAGE=1 SET_INPUT_SHAPER SHAPER_TYPE_X=<dual_carriage_shaper> SHAPER_FREQ_X=<dual_carriage_freq> SHAPER_TYPE_Y=<y_shaper> SHAPER_FREQ_Y=<y_freq> SET_DUAL_CARRIAGE CARRIAGE=0 SET_INPUT_SHAPER SHAPER_TYPE_X=<primary_carriage_shaper> SHAPER_FREQ_X=<primary_carriage_freq> SHAPER_TYPE_Y=<y_shaper> SHAPER_FREQ_Y=<y_freq> Note that SHAPER_TYPE_Y and SHAPER_FREQ_Y should be the same in both commands. It is also possible to put a similar snippet into the start g-code in the slicer, however then the shaper will not be enabled until any print is started. Note that the input shaper only needs to be configured once. Subsequent changes of the carriages or their modes via SET_DUAL_CARRIAGE command will preserve the configured input shaper parameters.","title":"Is dual carriage setup supported with input shapers?"},{"location":"Resonance_Compensation.html#does-input_shaper-affect-print-time","text":"No, input_shaper feature has pretty much no impact on the print times by itself. However, the value of max_accel certainly does (tuning of this parameter described in this section ).","title":"Does input_shaper affect print time?"},{"location":"Resonance_Compensation.html#technical-details","text":"","title":"Technical details"},{"location":"Resonance_Compensation.html#input-shapers","text":"Input shapers used in Klipper are rather standard, and one can find more in-depth overview in the articles describing the corresponding shapers. This section contains a brief overview of some technical aspects of the supported input shapers. The table below shows some (usually approximate) parameters of each shaper. Input shaper Shaper duration Vibration reduction 20x (5% vibration tolerance) Vibration reduction 10x (10% vibration tolerance) ZV 0.5 / shaper_freq N/A \u00b1 5% shaper_freq MZV 0.75 / shaper_freq \u00b1 4% shaper_freq -10%...+15% shaper_freq ZVD 1 / shaper_freq \u00b1 15% shaper_freq \u00b1 22% shaper_freq EI 1 / shaper_freq \u00b1 20% shaper_freq \u00b1 25% shaper_freq 2HUMP_EI 1.5 / shaper_freq \u00b1 35% shaper_freq \u00b1 40 shaper_freq 3HUMP_EI 2 / shaper_freq -45...+50% shaper_freq -50%...+55% shaper_freq A note on vibration reduction: the values in the table above are approximate. If the damping ratio of the printer is known for each axis, the shaper can be configured more precisely and it will then reduce the resonances in a bit wider range of frequencies. However, the damping ratio is usually unknown and is hard to estimate without a special equipment, so Klipper uses 0.1 value by default, which is a good all-round value. The frequency ranges in the table cover a number of different possible damping ratios around that value (approx. from 0.05 to 0.2). Also note that EI, 2HUMP_EI, and 3HUMP_EI are tuned to reduce vibrations to 5%, so the values for 10% vibration tolerance are provided only for the reference. How to use this table: Shaper duration affects the smoothing in parts - the larger it is, the more smooth the parts are. This dependency is not linear, but can give a sense of which shapers 'smooth' more for the same frequency. The ordering by smoothing is like this: ZV < MZV < ZVD \u2248 EI < 2HUMP_EI < 3HUMP_EI. Also, it is rarely practical to set shaper_freq = resonance freq for shapers 2HUMP_EI and 3HUMP_EI (they should be used to reduce vibrations for several frequencies). One can estimate a range of frequencies in which the shaper reduces vibrations. For example, MZV with shaper_freq = 35 Hz reduces vibrations to 5% for frequencies [33.6, 36.4] Hz. 3HUMP_EI with shaper_freq = 50 Hz reduces vibrations to 5% in range [27.5, 75] Hz. One can use this table to check which shaper they should be using if they need to reduce vibrations at several frequencies. For example, if one has resonances at 35 Hz and 60 Hz on the same axis: a) EI shaper needs to have shaper_freq = 35 / (1 - 0.2) = 43.75 Hz, and it will reduce resonances until 43.75 * (1 + 0.2) = 52.5 Hz, so it is not sufficient; b) 2HUMP_EI shaper needs to have shaper_freq = 35 / (1 - 0.35) = 53.85 Hz and will reduce vibrations until 53.85 * (1 + 0.35) = 72.7 Hz - so this is an acceptable configuration. Always try to use as high shaper_freq as possible for a given shaper (perhaps with some safety margin, so in this example shaper_freq \u2248 50-52 Hz would work best), and try to use a shaper with as small shaper duration as possible. If one needs to reduce vibrations at several very different frequencies (say, 30 Hz and 100 Hz), they may see that the table above does not provide enough information. In this case one may have more luck with scripts/graph_shaper.py script, which is more flexible.","title":"Input shapers"},{"location":"Rotation_Distance.html","text":"Rotation distance \u00b6 Stepper motor drivers on Klipper require a rotation_distance parameter in each stepper config section . The rotation_distance is the amount of distance that the axis moves with one full revolution of the stepper motor. This document describes how one can configure this value. Obtaining rotation_distance from steps_per_mm (or step_distance) \u00b6 The designers of your 3d printer originally calculated steps_per_mm from a rotation distance. If you know the steps_per_mm then it is possible to use this general formula to obtain that original rotation distance: rotation_distance = <full_steps_per_rotation> * <microsteps> / <steps_per_mm> Or, if you have an older Klipper configuration and know the step_distance parameter you can use this formula: rotation_distance = <full_steps_per_rotation> * <microsteps> * <step_distance> The <full_steps_per_rotation> setting is determined from the type of stepper motor. Most stepper motors are \"1.8 degree steppers\" and therefore have 200 full steps per rotation (360 divided by 1.8 is 200). Some stepper motors are \"0.9 degree steppers\" and thus have 400 full steps per rotation. Other stepper motors are rare. If unsure, do not set full_steps_per_rotation in the config file and use 200 in the formula above. The <microsteps> setting is determined by the stepper motor driver. Most drivers use 16 microsteps. If unsure, set microsteps: 16 in the config and use 16 in the formula above. Almost all printers should have a whole number for rotation_distance on X, Y, and Z type axes. If the above formula results in a rotation_distance that is within .01 of a whole number then round the final value to that whole_number. Calibrating rotation_distance on extruders \u00b6 On an extruder, the rotation_distance is the amount of distance the filament travels for one full rotation of the stepper motor. The best way to get an accurate value for this setting is to use a \"measure and trim\" procedure. First start with an initial guess for the rotation distance. This may be obtained from steps_per_mm or by inspecting the hardware . Then use the following procedure to \"measure and trim\": Make sure the extruder has filament in it, the hotend is heated to an appropriate temperature, and the printer is ready to extrude. Use a marker to place a mark on the filament around 70mm from the intake of the extruder body. Then use a digital calipers to measure the actual distance of that mark as precisely as one can. Note this as <initial_mark_distance> . Extrude 50mm of filament with the following command sequence: G91 followed by G1 E50 F60 . Note 50mm as <requested_extrude_distance> . Wait for the extruder to finish the move (it will take about 50 seconds). It is important to use the slow extrusion rate for this test as a faster rate can cause high pressure in the extruder which will skew the results. (Do not use the \"extrude button\" on graphical front-ends for this test as they extrude at a fast rate.) Use the digital calipers to measure the new distance between the extruder body and the mark on the filament. Note this as <subsequent_mark_distance> . Then calculate: actual_extrude_distance = <initial_mark_distance> - <subsequent_mark_distance> Calculate rotation_distance as: rotation_distance = <previous_rotation_distance> * <actual_extrude_distance> / <requested_extrude_distance> Round the new rotation_distance to three decimal places. If the actual_extrude_distance differs from requested_extrude_distance by more than about 2mm then it is a good idea to perform the steps above a second time. Note: Do not use a \"measure and trim\" type of method to calibrate x, y, or z type axes. The \"measure and trim\" method is not accurate enough for those axes and will likely lead to a worse configuration. Instead, if needed, those axes can be determined by measuring the belts, pulleys, and lead screw hardware . Obtaining rotation_distance by inspecting the hardware \u00b6 It's possible to calculate rotation_distance with knowledge of the stepper motors and printer kinematics. This may be useful if the steps_per_mm is not known or if designing a new printer. Belt driven axes \u00b6 It is easy to calculate rotation_distance for a linear axis that uses a belt and pulley. First determine the type of belt. Most printers use a 2mm belt pitch (that is, each tooth on the belt is 2mm apart). Then count the number of teeth on the stepper motor pulley. The rotation_distance is then calculated as: rotation_distance = <belt_pitch> * <number_of_teeth_on_pulley> For example, if a printer has a 2mm belt and uses a pulley with 20 teeth, then the rotation distance is 40. Axes with a lead screw \u00b6 It is easy to calculate the rotation_distance for common lead screws using the following formula: rotation_distance = <screw_pitch> * <number_of_separate_threads> For example, the common \"T8 leadscrew\" has a rotation distance of 8 (it has a pitch of 2mm and has 4 separate threads). Older printers with \"threaded rods\" have only one \"thread\" on the lead screw and thus the rotation distance is the pitch of the screw. (The screw pitch is the distance between each groove on the screw.) So, for example, an M6 metric rod has a rotation distance of 1 and an M8 rod has a rotation distance of 1.25. Extruder \u00b6 It's possible to obtain an initial rotation distance for extruders by measuring the diameter of the \"hobbed bolt\" that pushes the filament and using the following formula: rotation_distance = <diameter> * 3.14 If the extruder uses gears then it will also be necessary to determine and set the gear_ratio for the extruder. The actual rotation distance on an extruder will vary from printer to printer, because the grip of the \"hobbed bolt\" that engages the filament can vary. It can even vary between filament spools. After obtaining an initial rotation_distance, use the measure and trim procedure to obtain a more accurate setting. Using a gear_ratio \u00b6 Setting a gear_ratio can make it easier to configure the rotation_distance on steppers that have a gear box (or similar) attached to it. Most steppers do not have a gear box - if unsure then do not set gear_ratio in the config. When gear_ratio is set, the rotation_distance represents the distance the axis moves with one full rotation of the final gear on the gear box. If, for example, one is using a gearbox with a \"5:1\" ratio, then one could calculate the rotation_distance with knowledge of the hardware and then add gear_ratio: 5:1 to the config. For gearing implemented with belts and pulleys, it is possible to determine the gear_ratio by counting the teeth on the pulleys. For example, if a stepper with a 16 toothed pulley drives the next pulley with 80 teeth then one would use gear_ratio: 80:16 . Indeed, one could open a common off the shelf \"gear box\" and count the teeth in it to confirm its gear ratio. Note that sometimes a gearbox will have a slightly different gear ratio than what it is advertised as. The common BMG extruder motor gears are an example of this - they are advertised as \"3:1\" but actually use \"50:17\" gearing. (Using teeth numbers without a common denominator may improve overall gear wear as the teeth don't always mesh the same way with each revolution.) The common \"5.18:1 planetary gearbox\", is more accurately configured with gear_ratio: 57:11 . If several gears are used on an axis then it is possible to provide a comma separated list to gear_ratio. For example, a \"5:1\" gear box driving a 16 toothed to 80 toothed pulley could use gear_ratio: 5:1, 80:16 . In most cases, gear_ratio should be defined with whole numbers as common gears and pulleys have a whole number of teeth on them. However, in cases where a belt drives a pulley using friction instead of teeth, it may make sense to use a floating point number in the gear ratio (eg, gear_ratio: 107.237:16 ).","title":"Rotation distance"},{"location":"Rotation_Distance.html#rotation-distance","text":"Stepper motor drivers on Klipper require a rotation_distance parameter in each stepper config section . The rotation_distance is the amount of distance that the axis moves with one full revolution of the stepper motor. This document describes how one can configure this value.","title":"Rotation distance"},{"location":"Rotation_Distance.html#obtaining-rotation_distance-from-steps_per_mm-or-step_distance","text":"The designers of your 3d printer originally calculated steps_per_mm from a rotation distance. If you know the steps_per_mm then it is possible to use this general formula to obtain that original rotation distance: rotation_distance = <full_steps_per_rotation> * <microsteps> / <steps_per_mm> Or, if you have an older Klipper configuration and know the step_distance parameter you can use this formula: rotation_distance = <full_steps_per_rotation> * <microsteps> * <step_distance> The <full_steps_per_rotation> setting is determined from the type of stepper motor. Most stepper motors are \"1.8 degree steppers\" and therefore have 200 full steps per rotation (360 divided by 1.8 is 200). Some stepper motors are \"0.9 degree steppers\" and thus have 400 full steps per rotation. Other stepper motors are rare. If unsure, do not set full_steps_per_rotation in the config file and use 200 in the formula above. The <microsteps> setting is determined by the stepper motor driver. Most drivers use 16 microsteps. If unsure, set microsteps: 16 in the config and use 16 in the formula above. Almost all printers should have a whole number for rotation_distance on X, Y, and Z type axes. If the above formula results in a rotation_distance that is within .01 of a whole number then round the final value to that whole_number.","title":"Obtaining rotation_distance from steps_per_mm (or step_distance)"},{"location":"Rotation_Distance.html#calibrating-rotation_distance-on-extruders","text":"On an extruder, the rotation_distance is the amount of distance the filament travels for one full rotation of the stepper motor. The best way to get an accurate value for this setting is to use a \"measure and trim\" procedure. First start with an initial guess for the rotation distance. This may be obtained from steps_per_mm or by inspecting the hardware . Then use the following procedure to \"measure and trim\": Make sure the extruder has filament in it, the hotend is heated to an appropriate temperature, and the printer is ready to extrude. Use a marker to place a mark on the filament around 70mm from the intake of the extruder body. Then use a digital calipers to measure the actual distance of that mark as precisely as one can. Note this as <initial_mark_distance> . Extrude 50mm of filament with the following command sequence: G91 followed by G1 E50 F60 . Note 50mm as <requested_extrude_distance> . Wait for the extruder to finish the move (it will take about 50 seconds). It is important to use the slow extrusion rate for this test as a faster rate can cause high pressure in the extruder which will skew the results. (Do not use the \"extrude button\" on graphical front-ends for this test as they extrude at a fast rate.) Use the digital calipers to measure the new distance between the extruder body and the mark on the filament. Note this as <subsequent_mark_distance> . Then calculate: actual_extrude_distance = <initial_mark_distance> - <subsequent_mark_distance> Calculate rotation_distance as: rotation_distance = <previous_rotation_distance> * <actual_extrude_distance> / <requested_extrude_distance> Round the new rotation_distance to three decimal places. If the actual_extrude_distance differs from requested_extrude_distance by more than about 2mm then it is a good idea to perform the steps above a second time. Note: Do not use a \"measure and trim\" type of method to calibrate x, y, or z type axes. The \"measure and trim\" method is not accurate enough for those axes and will likely lead to a worse configuration. Instead, if needed, those axes can be determined by measuring the belts, pulleys, and lead screw hardware .","title":"Calibrating rotation_distance on extruders"},{"location":"Rotation_Distance.html#obtaining-rotation_distance-by-inspecting-the-hardware","text":"It's possible to calculate rotation_distance with knowledge of the stepper motors and printer kinematics. This may be useful if the steps_per_mm is not known or if designing a new printer.","title":"Obtaining rotation_distance by inspecting the hardware"},{"location":"Rotation_Distance.html#belt-driven-axes","text":"It is easy to calculate rotation_distance for a linear axis that uses a belt and pulley. First determine the type of belt. Most printers use a 2mm belt pitch (that is, each tooth on the belt is 2mm apart). Then count the number of teeth on the stepper motor pulley. The rotation_distance is then calculated as: rotation_distance = <belt_pitch> * <number_of_teeth_on_pulley> For example, if a printer has a 2mm belt and uses a pulley with 20 teeth, then the rotation distance is 40.","title":"Belt driven axes"},{"location":"Rotation_Distance.html#axes-with-a-lead-screw","text":"It is easy to calculate the rotation_distance for common lead screws using the following formula: rotation_distance = <screw_pitch> * <number_of_separate_threads> For example, the common \"T8 leadscrew\" has a rotation distance of 8 (it has a pitch of 2mm and has 4 separate threads). Older printers with \"threaded rods\" have only one \"thread\" on the lead screw and thus the rotation distance is the pitch of the screw. (The screw pitch is the distance between each groove on the screw.) So, for example, an M6 metric rod has a rotation distance of 1 and an M8 rod has a rotation distance of 1.25.","title":"Axes with a lead screw"},{"location":"Rotation_Distance.html#extruder","text":"It's possible to obtain an initial rotation distance for extruders by measuring the diameter of the \"hobbed bolt\" that pushes the filament and using the following formula: rotation_distance = <diameter> * 3.14 If the extruder uses gears then it will also be necessary to determine and set the gear_ratio for the extruder. The actual rotation distance on an extruder will vary from printer to printer, because the grip of the \"hobbed bolt\" that engages the filament can vary. It can even vary between filament spools. After obtaining an initial rotation_distance, use the measure and trim procedure to obtain a more accurate setting.","title":"Extruder"},{"location":"Rotation_Distance.html#using-a-gear_ratio","text":"Setting a gear_ratio can make it easier to configure the rotation_distance on steppers that have a gear box (or similar) attached to it. Most steppers do not have a gear box - if unsure then do not set gear_ratio in the config. When gear_ratio is set, the rotation_distance represents the distance the axis moves with one full rotation of the final gear on the gear box. If, for example, one is using a gearbox with a \"5:1\" ratio, then one could calculate the rotation_distance with knowledge of the hardware and then add gear_ratio: 5:1 to the config. For gearing implemented with belts and pulleys, it is possible to determine the gear_ratio by counting the teeth on the pulleys. For example, if a stepper with a 16 toothed pulley drives the next pulley with 80 teeth then one would use gear_ratio: 80:16 . Indeed, one could open a common off the shelf \"gear box\" and count the teeth in it to confirm its gear ratio. Note that sometimes a gearbox will have a slightly different gear ratio than what it is advertised as. The common BMG extruder motor gears are an example of this - they are advertised as \"3:1\" but actually use \"50:17\" gearing. (Using teeth numbers without a common denominator may improve overall gear wear as the teeth don't always mesh the same way with each revolution.) The common \"5.18:1 planetary gearbox\", is more accurately configured with gear_ratio: 57:11 . If several gears are used on an axis then it is possible to provide a comma separated list to gear_ratio. For example, a \"5:1\" gear box driving a 16 toothed to 80 toothed pulley could use gear_ratio: 5:1, 80:16 . In most cases, gear_ratio should be defined with whole numbers as common gears and pulleys have a whole number of teeth on them. However, in cases where a belt drives a pulley using friction instead of teeth, it may make sense to use a floating point number in the gear ratio (eg, gear_ratio: 107.237:16 ).","title":"Using a gear_ratio"},{"location":"SDCard_Updates.html","text":"SDCard updates \u00b6 Many of today's popular controller boards ship with a bootloader capable of updating firmware via SD Card. While this is convenient in many circumstances, these bootloaders typically provide no other way to update firmware. This can be a nuisance if your board is mounted in a location that is difficult to access or if you need to update firmware often. After Klipper has been initially flashed to a controller it is possible to transfer new firmware to the SD Card and initiate the flashing procedure via ssh. Typical Upgrade Procedure \u00b6 The procedure for updating MCU firmware using the SD Card is similar to that of other methods. Instead of using make flash it is necessary to run a helper script, flash-sdcard.sh . Updating a BigTreeTech SKR 1.3 might look like the following: sudo service klipper stop cd ~/klipper git pull make clean make menuconfig make ./scripts/flash-sdcard.sh /dev/ttyACM0 btt-skr-v1.3 sudo service klipper start It is up to the user to determine the device location and board name. If a user needs to flash multiple boards, flash-sdcard.sh (or make flash if appropriate) should be run for each board prior to restarting the Klipper service. Supported boards can be listed with the following command: ./scripts/flash-sdcard.sh -l If you do not see your board listed it may be necessary to add a new board definition as described below . Advanced Usage \u00b6 The above commands assume that your MCU connects at the default baud rate of 250000 and the firmware is located at ~/klipper/out/klipper.bin . The flash-sdcard.sh script provides options for changing these defaults. All options can be viewed by the help screen: ./scripts/flash-sdcard.sh -h SD Card upload utility for Klipper usage: flash_sdcard.sh [-h] [-l] [-c] [-b <baud>] [-f <firmware>] <device> <board> positional arguments: <device> device serial port <board> board type optional arguments: -h show this message -l list available boards -c run flash check/verify only (skip upload) -b <baud> serial baud rate (default is 250000) -f <firmware> path to klipper.bin If your board is flashed with firmware that connects at a custom baud rate it is possible to upgrade by specifying the -b option: ./scripts/flash-sdcard.sh -b 115200 /dev/ttyAMA0 btt-skr-v1.3 If you wish to flash a build of Klipper located somewhere other than the default location it can be done by specifying the -f option: ./scripts/flash-sdcard.sh -f ~/downloads/klipper.bin /dev/ttyAMA0 btt-skr-v1.3 Note that when upgrading a MKS Robin E3 it is not necessary to manually run update_mks_robin.py and supply the resulting binary to flash-sdcard.sh . This procedure is automated during the upload process. The -c option is used to perform a check or verify-only operation to test if the board is running the specified firmware correctly. This option is primarily intended for cases where a manual power-cycle is necessary to complete the flashing procedure, such as with bootloaders that use SDIO mode instead of SPI to access their SD Cards. (See Caveats below) But, it can also be used anytime to verify if the code flashed into the board matches the version in your build folder on any supported board. Caveats \u00b6 As mentioned in the introduction, this method only works for upgrading firmware. The initial flashing procedure must be done manually per the instructions that apply to your controller board. While it is possible to flash a build that changes the Serial Baud or connection interface (ie: from USB to UART), verification will always fail as the script will be unable to reconnect to the MCU to verify the current version. Only boards that use SPI for SD Card communication are supported. Boards that use SDIO, such as the Flymaker Flyboard and MKS Robin Nano V1/V2, will not work in SDIO mode. However, it's usually possible to flash such boards using Software SPI mode instead. But if the board's bootloader only uses SDIO mode to access the SD Card, a power-cycle of the board and SD Card will be necessary so that the mode can switch from SPI back to SDIO to complete reflashing. Such boards should be defined with skip_verify enabled to skip the verify step immediately after flashing. Then after the manual power-cycle, you can rerun the exact same ./scripts/flash-sdcard.sh command, but add the -c option to complete the check/verify operation. See Flashing Boards that use SDIO for examples. Board Definitions \u00b6 Most common boards should be available, however it is possible to add a new board definition if necessary. Board definitions are located in ~/klipper/scripts/spi_flash/board_defs.py . The definitions are stored in dictionary, for example: BOARD_DEFS = { 'generic-lpc1768' : { 'mcu' : \"lpc1768\" , 'spi_bus' : \"ssp1\" , \"cs_pin\" : \"P0.6\" }, ...< further definitions > } The following fields may be specified: mcu : The mcu type. This can be retrieved after configuring the build via make menuconfig by running cat .config | grep CONFIG_MCU . This field is required. spi_bus : The SPI bus connected to the SD Card. This should be retrieved from the board's schematic. This field is required. cs_pin : The Chip Select Pin connected to the SD Card. This should be retrieved from the board schematic. This field is required. firmware_path : The path on the SD Card where firmware should be transferred. The default is firmware.bin . current_firmware_path : The path on the SD Card where the renamed firmware file is located after a successful flash. The default is firmware.cur . skip_verify : This defines a boolean value which tells the scripts to skip the firmware verification step during the flashing process. The default is False . It can be set to True for boards that require a manual power-cycle to complete flashing. To verify the firmware afterward, run the script again with the -c option to perform the verification step. See caveats with SDIO cards If software SPI is required, the spi_bus field should be set to swspi and the following additional field should be specified: spi_pins : This should be 3 comma separated pins that are connected to the SD Card in the format of miso,mosi,sclk . It should be exceedingly rare that Software SPI is necessary, typically only boards with design errors or boards that normally only support SDIO mode for their SD Card will require it. The btt-skr-pro board definition provides an example of the former, and the btt-octopus-f446-v1 board definition provides an example of the latter. Prior to creating a new board definition one should check to see if an existing board definition meets the criteria necessary for the new board. If this is the case, a BOARD_ALIAS may be specified. For example, the following alias may be added to specify my-new-board as an alias for generic-lpc1768 : BOARD_ALIASES = { ...< previous aliases > , 'my-new-board' : BOARD_DEFS [ 'generic-lpc1768' ], } If you need a new board definition and you are uncomfortable with the procedure outlined above it is recommended that you request one in the Klipper Discord . Flashing Boards that use SDIO \u00b6 As mentioned in the Caveats , boards whose bootloader uses SDIO mode to access their SD Card require a power-cycle of the board, and specifically the SD Card itself, in order to switch from the SPI Mode used while writing the file to the SD Card back to SDIO mode for the bootloader to flash it into the board. These board definitions will use the skip_verify flag, which tells the flashing tool to stop after writing the firmware to the SD Card so that the board can be manually power-cycled and the verification step deferred until that's complete. There are two scenarios -- one with the RPi Host running on a separate power supply and the other when the RPi Host is running on the same power supply as the main board being flashed. The difference is whether or not it's necessary to also shutdown the RPi and then ssh again after the flashing is complete in order to do the verification step, or if the verification can be done immediately. Here's examples of the two scenarios: SDIO Programming with RPi on Separate Power Supply \u00b6 A typical session with the RPi on a Separate Power Supply looks like the following. You will, of course, need to use your proper device path and board name: sudo service klipper stop cd ~/klipper git pull make clean make menuconfig make ./scripts/flash-sdcard.sh /dev/ttyACM0 btt-octopus-f446-v1 [[[manually power-cycle the printer board here when instructed]]] ./scripts/flash-sdcard.sh -c /dev/ttyACM0 btt-octopus-f446-v1 sudo service klipper start SDIO Programming with RPi on the Same Power Supply \u00b6 A typical session with the RPi on the Same Power Supply looks like the following. You will, of course, need to use your proper device path and board name: sudo service klipper stop cd ~/klipper git pull make clean make menuconfig make ./scripts/flash-sdcard.sh /dev/ttyACM0 btt-octopus-f446-v1 sudo shutdown -h now [[[wait for the RPi to shutdown, then power-cycle and ssh again to the RPi when it restarts]]] sudo service klipper stop cd ~/klipper ./scripts/flash-sdcard.sh -c /dev/ttyACM0 btt-octopus-f446-v1 sudo service klipper start In this case, since the RPi Host is being restarted, which will restart the klipper service, it's necessary to stop klipper again before doing the verification step and restart it after verification is complete. SDIO to SPI Pin Mapping \u00b6 If your board's schematic uses SDIO for its SD Card, you can map the pins as described in the chart below to determine the compatible Software SPI pins to assign in the board_defs.py file: SD Card Pin Micro SD Card Pin SDIO Pin Name SPI Pin Name 9 1 DATA2 None (PU)* 1 2 CD/DATA3 CS 2 3 CMD MOSI 4 4 +3.3V (VDD) +3.3V (VDD) 5 5 CLK SCLK 3 6 GND (VSS) GND (VSS) 7 7 DATA0 MISO 8 8 DATA1 None (PU)* N/A 9 Card Detect (CD) Card Detect (CD) 6 10 GND GND * None (PU) indicates an unused pin with a pull-up resistor","title":"SDCard updates"},{"location":"SDCard_Updates.html#sdcard-updates","text":"Many of today's popular controller boards ship with a bootloader capable of updating firmware via SD Card. While this is convenient in many circumstances, these bootloaders typically provide no other way to update firmware. This can be a nuisance if your board is mounted in a location that is difficult to access or if you need to update firmware often. After Klipper has been initially flashed to a controller it is possible to transfer new firmware to the SD Card and initiate the flashing procedure via ssh.","title":"SDCard updates"},{"location":"SDCard_Updates.html#typical-upgrade-procedure","text":"The procedure for updating MCU firmware using the SD Card is similar to that of other methods. Instead of using make flash it is necessary to run a helper script, flash-sdcard.sh . Updating a BigTreeTech SKR 1.3 might look like the following: sudo service klipper stop cd ~/klipper git pull make clean make menuconfig make ./scripts/flash-sdcard.sh /dev/ttyACM0 btt-skr-v1.3 sudo service klipper start It is up to the user to determine the device location and board name. If a user needs to flash multiple boards, flash-sdcard.sh (or make flash if appropriate) should be run for each board prior to restarting the Klipper service. Supported boards can be listed with the following command: ./scripts/flash-sdcard.sh -l If you do not see your board listed it may be necessary to add a new board definition as described below .","title":"Typical Upgrade Procedure"},{"location":"SDCard_Updates.html#advanced-usage","text":"The above commands assume that your MCU connects at the default baud rate of 250000 and the firmware is located at ~/klipper/out/klipper.bin . The flash-sdcard.sh script provides options for changing these defaults. All options can be viewed by the help screen: ./scripts/flash-sdcard.sh -h SD Card upload utility for Klipper usage: flash_sdcard.sh [-h] [-l] [-c] [-b <baud>] [-f <firmware>] <device> <board> positional arguments: <device> device serial port <board> board type optional arguments: -h show this message -l list available boards -c run flash check/verify only (skip upload) -b <baud> serial baud rate (default is 250000) -f <firmware> path to klipper.bin If your board is flashed with firmware that connects at a custom baud rate it is possible to upgrade by specifying the -b option: ./scripts/flash-sdcard.sh -b 115200 /dev/ttyAMA0 btt-skr-v1.3 If you wish to flash a build of Klipper located somewhere other than the default location it can be done by specifying the -f option: ./scripts/flash-sdcard.sh -f ~/downloads/klipper.bin /dev/ttyAMA0 btt-skr-v1.3 Note that when upgrading a MKS Robin E3 it is not necessary to manually run update_mks_robin.py and supply the resulting binary to flash-sdcard.sh . This procedure is automated during the upload process. The -c option is used to perform a check or verify-only operation to test if the board is running the specified firmware correctly. This option is primarily intended for cases where a manual power-cycle is necessary to complete the flashing procedure, such as with bootloaders that use SDIO mode instead of SPI to access their SD Cards. (See Caveats below) But, it can also be used anytime to verify if the code flashed into the board matches the version in your build folder on any supported board.","title":"Advanced Usage"},{"location":"SDCard_Updates.html#caveats","text":"As mentioned in the introduction, this method only works for upgrading firmware. The initial flashing procedure must be done manually per the instructions that apply to your controller board. While it is possible to flash a build that changes the Serial Baud or connection interface (ie: from USB to UART), verification will always fail as the script will be unable to reconnect to the MCU to verify the current version. Only boards that use SPI for SD Card communication are supported. Boards that use SDIO, such as the Flymaker Flyboard and MKS Robin Nano V1/V2, will not work in SDIO mode. However, it's usually possible to flash such boards using Software SPI mode instead. But if the board's bootloader only uses SDIO mode to access the SD Card, a power-cycle of the board and SD Card will be necessary so that the mode can switch from SPI back to SDIO to complete reflashing. Such boards should be defined with skip_verify enabled to skip the verify step immediately after flashing. Then after the manual power-cycle, you can rerun the exact same ./scripts/flash-sdcard.sh command, but add the -c option to complete the check/verify operation. See Flashing Boards that use SDIO for examples.","title":"Caveats"},{"location":"SDCard_Updates.html#board-definitions","text":"Most common boards should be available, however it is possible to add a new board definition if necessary. Board definitions are located in ~/klipper/scripts/spi_flash/board_defs.py . The definitions are stored in dictionary, for example: BOARD_DEFS = { 'generic-lpc1768' : { 'mcu' : \"lpc1768\" , 'spi_bus' : \"ssp1\" , \"cs_pin\" : \"P0.6\" }, ...< further definitions > } The following fields may be specified: mcu : The mcu type. This can be retrieved after configuring the build via make menuconfig by running cat .config | grep CONFIG_MCU . This field is required. spi_bus : The SPI bus connected to the SD Card. This should be retrieved from the board's schematic. This field is required. cs_pin : The Chip Select Pin connected to the SD Card. This should be retrieved from the board schematic. This field is required. firmware_path : The path on the SD Card where firmware should be transferred. The default is firmware.bin . current_firmware_path : The path on the SD Card where the renamed firmware file is located after a successful flash. The default is firmware.cur . skip_verify : This defines a boolean value which tells the scripts to skip the firmware verification step during the flashing process. The default is False . It can be set to True for boards that require a manual power-cycle to complete flashing. To verify the firmware afterward, run the script again with the -c option to perform the verification step. See caveats with SDIO cards If software SPI is required, the spi_bus field should be set to swspi and the following additional field should be specified: spi_pins : This should be 3 comma separated pins that are connected to the SD Card in the format of miso,mosi,sclk . It should be exceedingly rare that Software SPI is necessary, typically only boards with design errors or boards that normally only support SDIO mode for their SD Card will require it. The btt-skr-pro board definition provides an example of the former, and the btt-octopus-f446-v1 board definition provides an example of the latter. Prior to creating a new board definition one should check to see if an existing board definition meets the criteria necessary for the new board. If this is the case, a BOARD_ALIAS may be specified. For example, the following alias may be added to specify my-new-board as an alias for generic-lpc1768 : BOARD_ALIASES = { ...< previous aliases > , 'my-new-board' : BOARD_DEFS [ 'generic-lpc1768' ], } If you need a new board definition and you are uncomfortable with the procedure outlined above it is recommended that you request one in the Klipper Discord .","title":"Board Definitions"},{"location":"SDCard_Updates.html#flashing-boards-that-use-sdio","text":"As mentioned in the Caveats , boards whose bootloader uses SDIO mode to access their SD Card require a power-cycle of the board, and specifically the SD Card itself, in order to switch from the SPI Mode used while writing the file to the SD Card back to SDIO mode for the bootloader to flash it into the board. These board definitions will use the skip_verify flag, which tells the flashing tool to stop after writing the firmware to the SD Card so that the board can be manually power-cycled and the verification step deferred until that's complete. There are two scenarios -- one with the RPi Host running on a separate power supply and the other when the RPi Host is running on the same power supply as the main board being flashed. The difference is whether or not it's necessary to also shutdown the RPi and then ssh again after the flashing is complete in order to do the verification step, or if the verification can be done immediately. Here's examples of the two scenarios:","title":"Flashing Boards that use SDIO"},{"location":"SDCard_Updates.html#sdio-programming-with-rpi-on-separate-power-supply","text":"A typical session with the RPi on a Separate Power Supply looks like the following. You will, of course, need to use your proper device path and board name: sudo service klipper stop cd ~/klipper git pull make clean make menuconfig make ./scripts/flash-sdcard.sh /dev/ttyACM0 btt-octopus-f446-v1 [[[manually power-cycle the printer board here when instructed]]] ./scripts/flash-sdcard.sh -c /dev/ttyACM0 btt-octopus-f446-v1 sudo service klipper start","title":"SDIO Programming with RPi on Separate Power Supply"},{"location":"SDCard_Updates.html#sdio-programming-with-rpi-on-the-same-power-supply","text":"A typical session with the RPi on the Same Power Supply looks like the following. You will, of course, need to use your proper device path and board name: sudo service klipper stop cd ~/klipper git pull make clean make menuconfig make ./scripts/flash-sdcard.sh /dev/ttyACM0 btt-octopus-f446-v1 sudo shutdown -h now [[[wait for the RPi to shutdown, then power-cycle and ssh again to the RPi when it restarts]]] sudo service klipper stop cd ~/klipper ./scripts/flash-sdcard.sh -c /dev/ttyACM0 btt-octopus-f446-v1 sudo service klipper start In this case, since the RPi Host is being restarted, which will restart the klipper service, it's necessary to stop klipper again before doing the verification step and restart it after verification is complete.","title":"SDIO Programming with RPi on the Same Power Supply"},{"location":"SDCard_Updates.html#sdio-to-spi-pin-mapping","text":"If your board's schematic uses SDIO for its SD Card, you can map the pins as described in the chart below to determine the compatible Software SPI pins to assign in the board_defs.py file: SD Card Pin Micro SD Card Pin SDIO Pin Name SPI Pin Name 9 1 DATA2 None (PU)* 1 2 CD/DATA3 CS 2 3 CMD MOSI 4 4 +3.3V (VDD) +3.3V (VDD) 5 5 CLK SCLK 3 6 GND (VSS) GND (VSS) 7 7 DATA0 MISO 8 8 DATA1 None (PU)* N/A 9 Card Detect (CD) Card Detect (CD) 6 10 GND GND * None (PU) indicates an unused pin with a pull-up resistor","title":"SDIO to SPI Pin Mapping"},{"location":"Skew_Correction.html","text":"Skew correction \u00b6 Software based skew correction can help resolve dimensional inaccuracies resulting from a printer assembly that is not perfectly square. Note that if your printer is significantly skewed it is strongly recommended to first use mechanical means to get your printer as square as possible prior to applying software based correction. Print a Calibration Object \u00b6 The first step in correcting skew is to print a calibration object along the plane you want to correct. There is also a calibration object that includes all planes in one model. You want the object oriented so that corner A is toward the origin of the plane. Make sure that no skew correction is applied during this print. You may do this by either removing the [skew_correction] module from printer.cfg or by issuing a SET_SKEW CLEAR=1 gcode. Take your measurements \u00b6 The [skew_correction] module requires 3 measurements for each plane you want to correct; the length from Corner A to Corner C, the length from Corner B to Corner D, and the length from Corner A to Corner D. When measuring length AD do not include the flats on the corners that some test objects provide. Configure your skew \u00b6 Make sure [skew_correction] is in printer.cfg. You may now use the SET_SKEW gcode to configure skew_correction. For example, if your measured lengths along XY are as follows: Length AC = 140.4 Length BD = 142.8 Length AD = 99.8 SET_SKEW can be used to configure skew correction for the XY plane. SET_SKEW XY=140.4,142.8,99.8 You may also add measurements for XZ and YZ to the gcode: SET_SKEW XY=140.4,142.8,99.8 XZ=141.6,141.4,99.8 YZ=142.4,140.5,99.5 The [skew_correction] module also supports profile management in a manner similar to [bed_mesh] . After setting skew using the SET_SKEW gcode, you may use the SKEW_PROFILE gcode to save it: SKEW_PROFILE SAVE=my_skew_profile After this command you will be prompted to issue a SAVE_CONFIG gcode to save the profile to persistent storage. If no profile is named my_skew_profile then a new profile will be created. If the named profile exists it will be overwritten. Once you have a saved profile, you may load it: SKEW_PROFILE LOAD=my_skew_profile It is also possible to remove an old or out of date profile: SKEW_PROFILE REMOVE=my_skew_profile After removing a profile you will be prompted to issue a SAVE_CONFIG to make this change persist. Verifying your correction \u00b6 After skew_correction has been configured you may reprint the calibration part with correction enabled. Use the following gcode to check your skew on each plane. The results should be lower than those reported via GET_CURRENT_SKEW . CALC_MEASURED_SKEW AC=<ac_length> BD=<bd_length> AD=<ad_length> Caveats \u00b6 Due to the nature of skew correction it is recommended to configure skew in your start gcode, after homing and any kind of movement that travels near the edge of the print area such as a purge or nozzle wipe. You may use use the SET_SKEW or SKEW_PROFILE gcodes to accomplish this. It is also recommended to issue a SET_SKEW CLEAR=1 in your end gcode. Keep in mind that it is possible for [skew_correction] to generate a correction that moves the tool beyond the printer's boundaries on the X and/or Y axes. It is recommended to arrange parts away from the edges when using [skew_correction] .","title":"Skew correction"},{"location":"Skew_Correction.html#skew-correction","text":"Software based skew correction can help resolve dimensional inaccuracies resulting from a printer assembly that is not perfectly square. Note that if your printer is significantly skewed it is strongly recommended to first use mechanical means to get your printer as square as possible prior to applying software based correction.","title":"Skew correction"},{"location":"Skew_Correction.html#print-a-calibration-object","text":"The first step in correcting skew is to print a calibration object along the plane you want to correct. There is also a calibration object that includes all planes in one model. You want the object oriented so that corner A is toward the origin of the plane. Make sure that no skew correction is applied during this print. You may do this by either removing the [skew_correction] module from printer.cfg or by issuing a SET_SKEW CLEAR=1 gcode.","title":"Print a Calibration Object"},{"location":"Skew_Correction.html#take-your-measurements","text":"The [skew_correction] module requires 3 measurements for each plane you want to correct; the length from Corner A to Corner C, the length from Corner B to Corner D, and the length from Corner A to Corner D. When measuring length AD do not include the flats on the corners that some test objects provide.","title":"Take your measurements"},{"location":"Skew_Correction.html#configure-your-skew","text":"Make sure [skew_correction] is in printer.cfg. You may now use the SET_SKEW gcode to configure skew_correction. For example, if your measured lengths along XY are as follows: Length AC = 140.4 Length BD = 142.8 Length AD = 99.8 SET_SKEW can be used to configure skew correction for the XY plane. SET_SKEW XY=140.4,142.8,99.8 You may also add measurements for XZ and YZ to the gcode: SET_SKEW XY=140.4,142.8,99.8 XZ=141.6,141.4,99.8 YZ=142.4,140.5,99.5 The [skew_correction] module also supports profile management in a manner similar to [bed_mesh] . After setting skew using the SET_SKEW gcode, you may use the SKEW_PROFILE gcode to save it: SKEW_PROFILE SAVE=my_skew_profile After this command you will be prompted to issue a SAVE_CONFIG gcode to save the profile to persistent storage. If no profile is named my_skew_profile then a new profile will be created. If the named profile exists it will be overwritten. Once you have a saved profile, you may load it: SKEW_PROFILE LOAD=my_skew_profile It is also possible to remove an old or out of date profile: SKEW_PROFILE REMOVE=my_skew_profile After removing a profile you will be prompted to issue a SAVE_CONFIG to make this change persist.","title":"Configure your skew"},{"location":"Skew_Correction.html#verifying-your-correction","text":"After skew_correction has been configured you may reprint the calibration part with correction enabled. Use the following gcode to check your skew on each plane. The results should be lower than those reported via GET_CURRENT_SKEW . CALC_MEASURED_SKEW AC=<ac_length> BD=<bd_length> AD=<ad_length>","title":"Verifying your correction"},{"location":"Skew_Correction.html#caveats","text":"Due to the nature of skew correction it is recommended to configure skew in your start gcode, after homing and any kind of movement that travels near the edge of the print area such as a purge or nozzle wipe. You may use use the SET_SKEW or SKEW_PROFILE gcodes to accomplish this. It is also recommended to issue a SET_SKEW CLEAR=1 in your end gcode. Keep in mind that it is possible for [skew_correction] to generate a correction that moves the tool beyond the printer's boundaries on the X and/or Y axes. It is recommended to arrange parts away from the edges when using [skew_correction] .","title":"Caveats"},{"location":"Slicers.html","text":"Slicers \u00b6 This document provides some tips for configuring a \"slicer\" application for use with Klipper. Common slicers used with Klipper are Slic3r, Cura, Simplify3D, etc. Set the G-Code flavor to Marlin \u00b6 Many slicers have an option to configure the \"G-Code flavor\". The default is frequently \"Marlin\" and that works well with Klipper. The \"Smoothieware\" setting also works well with Klipper. Klipper gcode_macro \u00b6 Slicers will often allow one to configure \"Start G-Code\" and \"End G-Code\" sequences. It is often convenient to define custom macros in the Klipper config file instead - such as: [gcode_macro START_PRINT] and [gcode_macro END_PRINT] . Then one can just run START_PRINT and END_PRINT in the slicer's configuration. Defining these actions in the Klipper configuration may make it easier to tweak the printer's start and end steps as changes do not require re-slicing. See sample-macros.cfg for example START_PRINT and END_PRINT macros. See the config reference for details on defining a gcode_macro. Large retraction settings may require tuning Klipper \u00b6 The maximum speed and acceleration of retraction moves are controlled in Klipper by the max_extrude_only_velocity and max_extrude_only_accel config settings. These settings have a default value that should work well on many printers. However, if one has configured a large retraction in the slicer (eg, 5mm or greater) then one may find they limit the desired speed of retractions. If using a large retraction, consider tuning Klipper's pressure advance instead. Otherwise, if one finds the toolhead seems to \"pause\" during retraction and priming, then consider explicitly defining max_extrude_only_velocity and max_extrude_only_accel in the Klipper config file. Do not enable \"coasting\" \u00b6 The \"coasting\" feature is likely to result in poor quality prints with Klipper. Consider using Klipper's pressure advance instead. Specifically, if the slicer dramatically changes the extrusion rate between moves then Klipper will perform deceleration and acceleration between moves. This is likely to make blobbing worse, not better. In contrast, it is okay (and often helpful) to use a slicer's \"retract\" setting, \"wipe\" setting, and/or \"wipe on retract\" setting. Do not use \"extra restart distance\" on Simplify3d \u00b6 This setting can cause dramatic changes to extrusion rates which can trigger Klipper's maximum extrusion cross-section check. Consider using Klipper's pressure advance or the regular Simplify3d retract setting instead. Disable \"PreloadVE\" on KISSlicer \u00b6 If using KISSlicer slicing software then set \"PreloadVE\" to zero. Consider using Klipper's pressure advance instead. Disable any \"advanced extruder pressure\" settings \u00b6 Some slicers advertise an \"advanced extruder pressure\" capability. It is recommended to keep these options disabled when using Klipper as they are likely to result in poor quality prints. Consider using Klipper's pressure advance instead. Specifically, these slicer settings can instruct the firmware to make wild changes to the extrusion rate in the hope that the firmware will approximate those requests and the printer will roughly obtain a desirable extruder pressure. Klipper, however, utilizes precise kinematic calculations and timing. When Klipper is commanded to make significant changes to the extrusion rate it will plan out the corresponding changes to velocity, acceleration, and extruder movement - which is not the slicer's intent. The slicer may even command excessive extrusion rates to the point that it triggers Klipper's maximum extrusion cross-section check. In contrast, it is okay (and often helpful) to use a slicer's \"retract\" setting, \"wipe\" setting, and/or \"wipe on retract\" setting. START_PRINT macros \u00b6 When using a START_PRINT macro or similar, it is useful to sometimes pass through parameters from the slicer variables to the macro. In Cura, to pass through temperatures, the following start gcode would be used: START_PRINT BED_TEMP={material_bed_temperature_layer_0} EXTRUDER_TEMP={material_print_temperature_layer_0} In slic3r derivatives such as PrusaSlicer and SuperSlicer, the following would be used: START_PRINT EXTRUDER_TEMP=[first_layer_temperature] BED_TEMP=[first_layer_bed_temperature] Also note that these slicers will insert their own heating codes when certain conditions are not met. In Cura, the existence of the {material_bed_temperature_layer_0} and {material_print_temperature_layer_0} variables is enough to mitigate this. In slic3r derivatives, you would use: M140 S0 M104 S0 before the macro call. Also note that SuperSlicer has a \"custom gcode only\" button option, which achieves the same outcome. An example of a START_PRINT macro using these parameters can be found in config/sample-macros.cfg","title":"Slicers"},{"location":"Slicers.html#slicers","text":"This document provides some tips for configuring a \"slicer\" application for use with Klipper. Common slicers used with Klipper are Slic3r, Cura, Simplify3D, etc.","title":"Slicers"},{"location":"Slicers.html#set-the-g-code-flavor-to-marlin","text":"Many slicers have an option to configure the \"G-Code flavor\". The default is frequently \"Marlin\" and that works well with Klipper. The \"Smoothieware\" setting also works well with Klipper.","title":"Set the G-Code flavor to Marlin"},{"location":"Slicers.html#klipper-gcode_macro","text":"Slicers will often allow one to configure \"Start G-Code\" and \"End G-Code\" sequences. It is often convenient to define custom macros in the Klipper config file instead - such as: [gcode_macro START_PRINT] and [gcode_macro END_PRINT] . Then one can just run START_PRINT and END_PRINT in the slicer's configuration. Defining these actions in the Klipper configuration may make it easier to tweak the printer's start and end steps as changes do not require re-slicing. See sample-macros.cfg for example START_PRINT and END_PRINT macros. See the config reference for details on defining a gcode_macro.","title":"Klipper gcode_macro"},{"location":"Slicers.html#large-retraction-settings-may-require-tuning-klipper","text":"The maximum speed and acceleration of retraction moves are controlled in Klipper by the max_extrude_only_velocity and max_extrude_only_accel config settings. These settings have a default value that should work well on many printers. However, if one has configured a large retraction in the slicer (eg, 5mm or greater) then one may find they limit the desired speed of retractions. If using a large retraction, consider tuning Klipper's pressure advance instead. Otherwise, if one finds the toolhead seems to \"pause\" during retraction and priming, then consider explicitly defining max_extrude_only_velocity and max_extrude_only_accel in the Klipper config file.","title":"Large retraction settings may require tuning Klipper"},{"location":"Slicers.html#do-not-enable-coasting","text":"The \"coasting\" feature is likely to result in poor quality prints with Klipper. Consider using Klipper's pressure advance instead. Specifically, if the slicer dramatically changes the extrusion rate between moves then Klipper will perform deceleration and acceleration between moves. This is likely to make blobbing worse, not better. In contrast, it is okay (and often helpful) to use a slicer's \"retract\" setting, \"wipe\" setting, and/or \"wipe on retract\" setting.","title":"Do not enable \"coasting\""},{"location":"Slicers.html#do-not-use-extra-restart-distance-on-simplify3d","text":"This setting can cause dramatic changes to extrusion rates which can trigger Klipper's maximum extrusion cross-section check. Consider using Klipper's pressure advance or the regular Simplify3d retract setting instead.","title":"Do not use \"extra restart distance\" on Simplify3d"},{"location":"Slicers.html#disable-preloadve-on-kisslicer","text":"If using KISSlicer slicing software then set \"PreloadVE\" to zero. Consider using Klipper's pressure advance instead.","title":"Disable \"PreloadVE\" on KISSlicer"},{"location":"Slicers.html#disable-any-advanced-extruder-pressure-settings","text":"Some slicers advertise an \"advanced extruder pressure\" capability. It is recommended to keep these options disabled when using Klipper as they are likely to result in poor quality prints. Consider using Klipper's pressure advance instead. Specifically, these slicer settings can instruct the firmware to make wild changes to the extrusion rate in the hope that the firmware will approximate those requests and the printer will roughly obtain a desirable extruder pressure. Klipper, however, utilizes precise kinematic calculations and timing. When Klipper is commanded to make significant changes to the extrusion rate it will plan out the corresponding changes to velocity, acceleration, and extruder movement - which is not the slicer's intent. The slicer may even command excessive extrusion rates to the point that it triggers Klipper's maximum extrusion cross-section check. In contrast, it is okay (and often helpful) to use a slicer's \"retract\" setting, \"wipe\" setting, and/or \"wipe on retract\" setting.","title":"Disable any \"advanced extruder pressure\" settings"},{"location":"Slicers.html#start_print-macros","text":"When using a START_PRINT macro or similar, it is useful to sometimes pass through parameters from the slicer variables to the macro. In Cura, to pass through temperatures, the following start gcode would be used: START_PRINT BED_TEMP={material_bed_temperature_layer_0} EXTRUDER_TEMP={material_print_temperature_layer_0} In slic3r derivatives such as PrusaSlicer and SuperSlicer, the following would be used: START_PRINT EXTRUDER_TEMP=[first_layer_temperature] BED_TEMP=[first_layer_bed_temperature] Also note that these slicers will insert their own heating codes when certain conditions are not met. In Cura, the existence of the {material_bed_temperature_layer_0} and {material_print_temperature_layer_0} variables is enough to mitigate this. In slic3r derivatives, you would use: M140 S0 M104 S0 before the macro call. Also note that SuperSlicer has a \"custom gcode only\" button option, which achieves the same outcome. An example of a START_PRINT macro using these parameters can be found in config/sample-macros.cfg","title":"START_PRINT macros"},{"location":"Sponsors.html","text":"Sponsors \u00b6 Klipper is Free Software. We depend on the generous support from sponsors. Please consider sponsoring Klipper or supporting our sponsors. BIGTREETECH \u00b6 BIGTREETECH is the official mainboard sponsor of Klipper. BIGTREETECH is committed to developing innovative and competitive products to serve the 3D printing community better. Follow them on Facebook or Twitter . Sponsors \u00b6 Klipper Developers \u00b6 Kevin O'Connor \u00b6 Kevin is the original author and current maintainer of Klipper. Donate at: https://ko-fi.com/koconnor or https://www.patreon.com/koconnor Eric Callahan \u00b6 Eric is the author of bed_mesh, spi_flash, and several other Klipper modules. Eric has a donations page at: https://ko-fi.com/arksine Related Klipper Projects \u00b6 Klipper is frequently used with other Free Software. Consider using or supporting these projects. Moonraker Mainsail Fluidd OctoPrint KlipperScreen","title":"Sponsors"},{"location":"Sponsors.html#sponsors","text":"Klipper is Free Software. We depend on the generous support from sponsors. Please consider sponsoring Klipper or supporting our sponsors.","title":"Sponsors"},{"location":"Sponsors.html#bigtreetech","text":"BIGTREETECH is the official mainboard sponsor of Klipper. BIGTREETECH is committed to developing innovative and competitive products to serve the 3D printing community better. Follow them on Facebook or Twitter .","title":"BIGTREETECH"},{"location":"Sponsors.html#sponsors_1","text":"","title":"Sponsors"},{"location":"Sponsors.html#klipper-developers","text":"","title":"Klipper Developers"},{"location":"Sponsors.html#kevin-oconnor","text":"Kevin is the original author and current maintainer of Klipper. Donate at: https://ko-fi.com/koconnor or https://www.patreon.com/koconnor","title":"Kevin O'Connor"},{"location":"Sponsors.html#eric-callahan","text":"Eric is the author of bed_mesh, spi_flash, and several other Klipper modules. Eric has a donations page at: https://ko-fi.com/arksine","title":"Eric Callahan"},{"location":"Sponsors.html#related-klipper-projects","text":"Klipper is frequently used with other Free Software. Consider using or supporting these projects. Moonraker Mainsail Fluidd OctoPrint KlipperScreen","title":"Related Klipper Projects"},{"location":"Status_Reference.html","text":"Status reference \u00b6 This document is a reference of printer status information available in Klipper macros , display fields , and via the API Server . The fields in this document are subject to change - if using an attribute be sure to review the Config Changes document when upgrading the Klipper software. angle \u00b6 The following information is available in angle some_name objects: temperature : The last temperature reading (in Celsius) from a tle5012b magnetic hall sensor. This value is only available if the angle sensor is a tle5012b chip and if measurements are in progress (otherwise it reports None ). bed_mesh \u00b6 The following information is available in the bed_mesh object: profile_name , mesh_min , mesh_max , probed_matrix , mesh_matrix : Information on the currently active bed_mesh. profiles : The set of currently defined profiles as setup using BED_MESH_PROFILE. bed_screws \u00b6 The following information is available in the bed_screws object: is_active : Returns True if the bed screws adjustment tool is currently active. state : The bed screws adjustment tool state. It is one of the following strings: \"adjust\", \"fine\". current_screw : The index for the current screw being adjusted. accepted_screws : The number of accepted screws. canbus_stats \u00b6 The following information is available in the canbus_stats some_mcu_name object (this object is automatically available if an mcu is configured to use canbus): rx_error : The number of receive errors detected by the micro-controller canbus hardware. tx_error : The number of transmit errors detected by the micro-controller canbus hardware. tx_retries : The number of transmit attempts that were retried due to bus contention or errors. bus_state : The status of the interface (typically \"active\" for a bus in normal operation, \"warn\" for a bus with recent errors, \"passive\" for a bus that will no longer transmit canbus error frames, or \"off\" for a bus that will no longer transmit or receive messages). Note that only the rp2XXX micro-controllers report a non-zero tx_retries field and the rp2XXX micro-controllers always report tx_error as zero and bus_state as \"active\". configfile \u00b6 The following information is available in the configfile object (this object is always available): settings.<section>.<option> : Returns the given config file setting (or default value) during the last software start or restart. (Any settings changed at run-time will not be reflected here.) config.<section>.<option> : Returns the given raw config file setting as read by Klipper during the last software start or restart. (Any settings changed at run-time will not be reflected here.) All values are returned as strings. save_config_pending : Returns true if there are updates that a SAVE_CONFIG command may persist to disk. save_config_pending_items : Contains the sections and options that were changed and would be persisted by a SAVE_CONFIG . warnings : A list of warnings about config options. Each entry in the list will be a dictionary containing a type and message field (both strings). Additional fields may be available depending on the type of warning. display_status \u00b6 The following information is available in the display_status object (this object is automatically available if a display config section is defined): progress : The progress value of the last M73 G-Code command (or virtual_sdcard.progress if no recent M73 received). message : The message contained in the last M117 G-Code command. endstop_phase \u00b6 The following information is available in the endstop_phase object: last_home.<stepper name>.phase : The phase of the stepper motor at the end of the last home attempt. last_home.<stepper name>.phases : The total number of phases available on the stepper motor. last_home.<stepper name>.mcu_position : The position (as tracked by the micro-controller) of the stepper motor at the end of the last home attempt. The position is the total number of steps taken in a forward direction minus the total number of steps taken in the reverse direction since the micro-controller was last restarted. exclude_object \u00b6 The following information is available in the exclude_object object: objects : An array of the known objects as provided by the EXCLUDE_OBJECT_DEFINE command. This is the same information provided by the EXCLUDE_OBJECT VERBOSE=1 command. The center and polygon fields will only be present if provided in the original EXCLUDE_OBJECT_DEFINE Here is a JSON sample: [ { \"polygon\": [ [ 156.25, 146.2511675 ], [ 156.25, 153.7488325 ], [ 163.75, 153.7488325 ], [ 163.75, 146.2511675 ] ], \"name\": \"CYLINDER_2_STL_ID_2_COPY_0\", \"center\": [ 160, 150 ] }, { \"polygon\": [ [ 146.25, 146.2511675 ], [ 146.25, 153.7488325 ], [ 153.75, 153.7488325 ], [ 153.75, 146.2511675 ] ], \"name\": \"CYLINDER_2_STL_ID_1_COPY_0\", \"center\": [ 150, 150 ] } ] excluded_objects : An array of strings listing the names of excluded objects. current_object : The name of the object currently being printed. extruder_stepper \u00b6 The following information is available for extruder_stepper objects (as well as extruder objects): pressure_advance : The current pressure advance value. smooth_time : The current pressure advance smooth time. motion_queue : The name of the extruder that this extruder stepper is currently synchronized to. This is reported as None if the extruder stepper is not currently associated with an extruder. fan \u00b6 The following information is available in fan , heater_fan some_name and controller_fan some_name objects: speed : The fan speed as a float between 0.0 and 1.0. rpm : The measured fan speed in rotations per minute if the fan has a tachometer_pin defined. filament_switch_sensor \u00b6 The following information is available in filament_switch_sensor some_name objects: enabled : Returns True if the switch sensor is currently enabled. filament_detected : Returns True if the sensor is in a triggered state. filament_motion_sensor \u00b6 The following information is available in filament_motion_sensor some_name objects: enabled : Returns True if the motion sensor is currently enabled. filament_detected : Returns True if the sensor is in a triggered state. firmware_retraction \u00b6 The following information is available in the firmware_retraction object: retract_length , retract_speed , unretract_extra_length , unretract_speed : The current settings for the firmware_retraction module. These settings may differ from the config file if a SET_RETRACTION command alters them. gcode \u00b6 The following information is available in the gcode object: commands : Returns a list of all currently available commands. For each command, if a help string is defined it will also be provided. gcode_button \u00b6 The following information is available in gcode_button some_name objects: state : The current button state returned as \"PRESSED\" or \"RELEASED\" gcode_macro \u00b6 The following information is available in gcode_macro some_name objects: <variable> : The current value of a gcode_macro variable . gcode_move \u00b6 The following information is available in the gcode_move object (this object is always available): gcode_position : The current position of the toolhead relative to the current G-Code origin. That is, positions that one might directly send to a G1 command. It is possible to access the x, y, z, and e components of this position (eg, gcode_position.x ). position : The last commanded position of the toolhead using the coordinate system specified in the config file. It is possible to access the x, y, z, and e components of this position (eg, position.x ). homing_origin : The origin of the gcode coordinate system (relative to the coordinate system specified in the config file) to use after a G28 command. The SET_GCODE_OFFSET command can alter this position. It is possible to access the x, y, and z components of this position (eg, homing_origin.x ). speed : The last speed set in a G1 command (in mm/s). speed_factor : The \"speed factor override\" as set by an M220 command. This is a floating point value such that 1.0 means no override and, for example, 2.0 would double requested speed. extrude_factor : The \"extrude factor override\" as set by an M221 command. This is a floating point value such that 1.0 means no override and, for example, 2.0 would double requested extrusions. absolute_coordinates : This returns True if in G90 absolute coordinate mode or False if in G91 relative mode. absolute_extrude : This returns True if in M82 absolute extrude mode or False if in M83 relative mode. hall_filament_width_sensor \u00b6 The following information is available in the hall_filament_width_sensor object: all items from filament_switch_sensor is_active : Returns True if the sensor is currently active. Diameter : The last reading from the sensor in mm. Raw : The last raw ADC reading from the sensor. heater \u00b6 The following information is available for heater objects such as extruder , heater_bed , and heater_generic : temperature : The last reported temperature (in Celsius as a float) for the given heater. target : The current target temperature (in Celsius as a float) for the given heater. power : The last setting of the PWM pin (a value between 0.0 and 1.0) associated with the heater. can_extrude : If extruder can extrude (defined by min_extrude_temp ), available only for extruder heaters \u00b6 The following information is available in the heaters object (this object is available if any heater is defined): available_heaters : Returns a list of all currently available heaters by their full config section names, e.g. [\"extruder\", \"heater_bed\", \"heater_generic my_custom_heater\"] . available_sensors : Returns a list of all currently available temperature sensors by their full config section names, e.g. [\"extruder\", \"heater_bed\", \"heater_generic my_custom_heater\", \"temperature_sensor electronics_temp\"] . available_monitors : Returns a list of all currently available temperature monitors by their full config section names, e.g. [\"tmc2240 stepper_x\"] . While a temperature sensor is always available to read, a temperature monitor may not be available and will return null in such case. idle_timeout \u00b6 The following information is available in the idle_timeout object (this object is always available): state : The current state of the printer as tracked by the idle_timeout module. It is one of the following strings: \"Idle\", \"Printing\", \"Ready\". printing_time : The amount of time (in seconds) the printer has been in the \"Printing\" state (as tracked by the idle_timeout module). idle_timeout : The current 'timeout' (in seconds) to wait for the gcode to be triggered. (as set by SET_IDLE_TIMEOUT ) led \u00b6 The following information is available for each [led led_name] , [neopixel led_name] , [dotstar led_name] , [pca9533 led_name] , and [pca9632 led_name] config section defined in printer.cfg: color_data : A list of color lists containing the RGBW values for a led in the chain. Each value is represented as a float from 0.0 to 1.0. Each color list contains 4 items (red, green, blue, white) even if the underlying LED supports fewer color channels. For example, the blue value (3rd item in color list) of the second neopixel in a chain could be accessed at printer[\"neopixel <config_name>\"].color_data[1][2] . load_cell \u00b6 The following information is available for each [load_cell name] : 'is_calibrated': True/False is the load cell calibrated 'counts_per_gram': The number of raw sensor counts that equals 1 gram of force 'reference_tare_counts': The reference number of raw sensor counts for 0 force 'tare_counts': The current number of raw sensor counts for 0 force 'force_g': The force in grams, averaged over the last polling period. 'min_force_g': The minimum force in grams, over the last polling period. 'max_force_g': The maximum force in grams, over the last polling period. load_cell_probe \u00b6 The following information is available for [load_cell_probe] : all items from load_cell all items from probe 'endstop_tare_counts': the load cell probe keeps a tare value independent of the load cell. This re-set at the start of each probe. 'last_trigger_time': timestamp of the last homing trigger manual_probe \u00b6 The following information is available in the manual_probe object: is_active : Returns True if a manual probing helper script is currently active. z_position : The current height of the nozzle (as the printer currently understands it). z_position_lower : Last probe attempt just lower than the current height. z_position_upper : Last probe attempt just greater than the current height. mcu \u00b6 The following information is available in mcu and mcu some_name objects: mcu_version : The Klipper code version reported by the micro-controller. mcu_build_versions : Information on the build tools used to generate the micro-controller code (as reported by the micro-controller). mcu_constants.<constant_name> : Compile time constants reported by the micro-controller. The available constants may differ between micro-controller architectures and with each code revision. last_stats.<statistics_name> : Statistics information on the micro-controller connection. motion_report \u00b6 The following information is available in the motion_report object (this object is automatically available if any stepper config section is defined): live_position : The requested toolhead position interpolated to the current time. live_velocity : The requested toolhead velocity (in mm/s) at the current time. live_extruder_velocity : The requested extruder velocity (in mm/s) at the current time. output_pin \u00b6 The following information is available in output_pin some_name and pwm_tool some_name objects: value : The \"value\" of the pin, as set by a SET_PIN command. palette2 \u00b6 The following information is available in the palette2 object: ping : Amount of the last reported Palette 2 ping in percent. remaining_load_length : When starting a Palette 2 print, this will be the amount of filament to load into the extruder. is_splicing : True when the Palette 2 is splicing filament. pause_resume \u00b6 The following information is available in the pause_resume object: is_paused : Returns true if a PAUSE command has been executed without a corresponding RESUME. print_stats \u00b6 The following information is available in the print_stats object (this object is automatically available if a virtual_sdcard config section is defined): filename , total_duration , print_duration , filament_used , state , message : Estimated information about the current print when a virtual_sdcard print is active. info.total_layer : The total layer value of the last SET_PRINT_STATS_INFO TOTAL_LAYER=<value> G-Code command. info.current_layer : The current layer value of the last SET_PRINT_STATS_INFO CURRENT_LAYER=<value> G-Code command. probe \u00b6 The following information is available in the probe object (this object is also available if a bltouch config section is defined): name : Returns the name of the probe in use. last_query : Returns True if the probe was reported as \"triggered\" during the last QUERY_PROBE command. Note, if this is used in a macro, due to the order of template expansion, the QUERY_PROBE command must be run prior to the macro containing this reference. last_z_result : Returns the Z result value of the last PROBE command. Note, if this is used in a macro, due to the order of template expansion, the PROBE (or similar) command must be run prior to the macro containing this reference. pwm_cycle_time \u00b6 The following information is available in pwm_cycle_time some_name objects: value : The \"value\" of the pin, as set by a SET_PIN command. quad_gantry_level \u00b6 The following information is available in the quad_gantry_level object (this object is available if quad_gantry_level is defined): applied : True if the gantry leveling process has been run and completed successfully. query_endstops \u00b6 The following information is available in the query_endstops object (this object is available if any endstop is defined): last_query[\"<endstop>\"] : Returns True if the given endstop was reported as \"triggered\" during the last QUERY_ENDSTOP command. Note, if this is used in a macro, due to the order of template expansion, the QUERY_ENDSTOP command must be run prior to the macro containing this reference. screws_tilt_adjust \u00b6 The following information is available in the screws_tilt_adjust object: error : Returns True if the most recent SCREWS_TILT_CALCULATE command included the MAX_DEVIATION parameter and any of the probed screw points exceeded the specified MAX_DEVIATION . max_deviation : Return the last MAX_DEVIATION value of the most recent SCREWS_TILT_CALCULATE command. results[\"<screw>\"] : A dictionary containing the following keys: z : The measured Z height of the screw location. sign : A string specifying the direction to turn to screw for the necessary adjustment. Either \"CW\" for clockwise or \"CCW\" for counterclockwise. adjust : The number of screw turns to adjust the screw, given in the format \"HH:MM,\" where \"HH\" is the number of full screw turns and \"MM\" is the number of \"minutes of a clock face\" representing a partial screw turn. (E.g. \"01:15\" would mean to turn the screw one and a quarter revolutions.) is_base : Returns True if this is the base screw. servo \u00b6 The following information is available in servo some_name objects: printer[\"servo <config_name>\"].value : The last setting of the PWM pin (a value between 0.0 and 1.0) associated with the servo. skew_correction.py \u00b6 The following information is available in the skew_correction object (this object is available if any skew_correction is defined): current_profile_name : Returns the name of the currently loaded SKEW_PROFILE. stepper_enable \u00b6 The following information is available in the stepper_enable object (this object is available if any stepper is defined): steppers[\"<stepper>\"] : Returns True if the given stepper is enabled. system_stats \u00b6 The following information is available in the system_stats object (this object is always available): sysload , cputime , memavail : Information on the host operating system and process load. temperature sensors \u00b6 The following information is available in bme280 config_section_name , htu21d config_section_name , sht3x config_section_name , lm75 config_section_name , temperature_host config_section_name and temperature_combined config_section_name objects: temperature : The last read temperature from the sensor. humidity , pressure , gas : The last read values from the sensor (only on bme280, htu21d, sht3x and lm75 sensors). temperature_fan \u00b6 The following information is available in temperature_fan some_name objects: temperature : The last read temperature from the sensor. target : The target temperature for the fan. temperature_sensor \u00b6 The following information is available in temperature_sensor some_name objects: temperature : The last read temperature from the sensor. measured_min_temp , measured_max_temp : The lowest and highest temperature seen by the sensor since the Klipper host software was last restarted. tmc drivers \u00b6 The following information is available in TMC stepper driver objects (eg, [tmc2208 stepper_x] ): mcu_phase_offset : The micro-controller stepper position corresponding with the driver's \"zero\" phase. This field may be null if the phase offset is not known. phase_offset_position : The \"commanded position\" corresponding to the driver's \"zero\" phase. This field may be null if the phase offset is not known. drv_status : The results of the last driver status query. (Only non-zero fields are reported.) This field will be null if the driver is not enabled (and thus is not periodically queried). temperature : The internal temperature reported by the driver. This field will be null if the driver is not enabled or if the driver does not support temperature reporting. run_current : The currently set run current. hold_current : The currently set hold current. toolhead \u00b6 The following information is available in the toolhead object (this object is always available): position : The last commanded position of the toolhead relative to the coordinate system specified in the config file. It is possible to access the x, y, z, and e components of this position (eg, position.x ). extruder : The name of the currently active extruder. For example, in a macro one could use printer[printer.toolhead.extruder].target to get the target temperature of the current extruder. homed_axes : The current cartesian axes considered to be in a \"homed\" state. This is a string containing one or more of \"x\", \"y\", \"z\". axis_minimum , axis_maximum : The axis travel limits (mm) after homing. It is possible to access the x, y, z components of this limit value (eg, axis_minimum.x , axis_maximum.z ). For Delta printers the cone_start_z is the max z height at maximum radius ( printer.toolhead.cone_start_z ). max_velocity , max_accel , minimum_cruise_ratio , square_corner_velocity : The current printing limits that are in effect. This may differ from the config file settings if a SET_VELOCITY_LIMIT (or M204 ) command alters them at run-time. stalls : The total number of times (since the last restart) that the printer had to be paused because the toolhead moved faster than moves could be read from the G-Code input. dual_carriage \u00b6 The following information is available in dual_carriage on a cartesian, hybrid_corexy or hybrid_corexz robot carriage_0 : The mode of the carriage 0. Possible values are: \"INACTIVE\" and \"PRIMARY\". carriage_1 : The mode of the carriage 1. Possible values are: \"INACTIVE\", \"PRIMARY\", \"COPY\", and \"MIRROR\". On a generic_cartesian kinematic, the following information is available in dual_carriage : carriages[\"<carriage>\"] : The mode of the carriage <carriage> . Possible values are \"INACTIVE\" and \"PRIMARY\" for the primary carriage and \"INACTIVE\", \"PRIMARY\", \"COPY\", and \"MIRROR\" for the dual carriage. virtual_sdcard \u00b6 The following information is available in the virtual_sdcard object: is_active : Returns True if a print from file is currently active. progress : An estimate of the current print progress (based of file size and file position). file_path : A full path to the file of currently loaded file. file_position : The current position (in bytes) of an active print. file_size : The file size (in bytes) of currently loaded file. webhooks \u00b6 The following information is available in the webhooks object (this object is always available): state : Returns a string indicating the current Klipper state. Possible values are: \"ready\", \"startup\", \"shutdown\", \"error\". state_message : A human readable string giving additional context on the current Klipper state. z_thermal_adjust \u00b6 The following information is available in the z_thermal_adjust object (this object is available if z_thermal_adjust is defined). enabled : Returns True if adjustment is enabled. temperature : Current (smoothed) temperature of the defined sensor. [degC] measured_min_temp : Minimum measured temperature. [degC] measured_max_temp : Maximum measured temperature. [degC] current_z_adjust : Last computed Z adjustment [mm]. z_adjust_ref_temperature : Current reference temperature used for calculation of Z current_z_adjust [degC]. z_tilt \u00b6 The following information is available in the z_tilt object (this object is available if z_tilt is defined): applied : True if the z-tilt leveling process has been run and completed successfully.","title":"Status reference"},{"location":"Status_Reference.html#status-reference","text":"This document is a reference of printer status information available in Klipper macros , display fields , and via the API Server . The fields in this document are subject to change - if using an attribute be sure to review the Config Changes document when upgrading the Klipper software.","title":"Status reference"},{"location":"Status_Reference.html#angle","text":"The following information is available in angle some_name objects: temperature : The last temperature reading (in Celsius) from a tle5012b magnetic hall sensor. This value is only available if the angle sensor is a tle5012b chip and if measurements are in progress (otherwise it reports None ).","title":"angle"},{"location":"Status_Reference.html#bed_mesh","text":"The following information is available in the bed_mesh object: profile_name , mesh_min , mesh_max , probed_matrix , mesh_matrix : Information on the currently active bed_mesh. profiles : The set of currently defined profiles as setup using BED_MESH_PROFILE.","title":"bed_mesh"},{"location":"Status_Reference.html#bed_screws","text":"The following information is available in the bed_screws object: is_active : Returns True if the bed screws adjustment tool is currently active. state : The bed screws adjustment tool state. It is one of the following strings: \"adjust\", \"fine\". current_screw : The index for the current screw being adjusted. accepted_screws : The number of accepted screws.","title":"bed_screws"},{"location":"Status_Reference.html#canbus_stats","text":"The following information is available in the canbus_stats some_mcu_name object (this object is automatically available if an mcu is configured to use canbus): rx_error : The number of receive errors detected by the micro-controller canbus hardware. tx_error : The number of transmit errors detected by the micro-controller canbus hardware. tx_retries : The number of transmit attempts that were retried due to bus contention or errors. bus_state : The status of the interface (typically \"active\" for a bus in normal operation, \"warn\" for a bus with recent errors, \"passive\" for a bus that will no longer transmit canbus error frames, or \"off\" for a bus that will no longer transmit or receive messages). Note that only the rp2XXX micro-controllers report a non-zero tx_retries field and the rp2XXX micro-controllers always report tx_error as zero and bus_state as \"active\".","title":"canbus_stats"},{"location":"Status_Reference.html#configfile","text":"The following information is available in the configfile object (this object is always available): settings.<section>.<option> : Returns the given config file setting (or default value) during the last software start or restart. (Any settings changed at run-time will not be reflected here.) config.<section>.<option> : Returns the given raw config file setting as read by Klipper during the last software start or restart. (Any settings changed at run-time will not be reflected here.) All values are returned as strings. save_config_pending : Returns true if there are updates that a SAVE_CONFIG command may persist to disk. save_config_pending_items : Contains the sections and options that were changed and would be persisted by a SAVE_CONFIG . warnings : A list of warnings about config options. Each entry in the list will be a dictionary containing a type and message field (both strings). Additional fields may be available depending on the type of warning.","title":"configfile"},{"location":"Status_Reference.html#display_status","text":"The following information is available in the display_status object (this object is automatically available if a display config section is defined): progress : The progress value of the last M73 G-Code command (or virtual_sdcard.progress if no recent M73 received). message : The message contained in the last M117 G-Code command.","title":"display_status"},{"location":"Status_Reference.html#endstop_phase","text":"The following information is available in the endstop_phase object: last_home.<stepper name>.phase : The phase of the stepper motor at the end of the last home attempt. last_home.<stepper name>.phases : The total number of phases available on the stepper motor. last_home.<stepper name>.mcu_position : The position (as tracked by the micro-controller) of the stepper motor at the end of the last home attempt. The position is the total number of steps taken in a forward direction minus the total number of steps taken in the reverse direction since the micro-controller was last restarted.","title":"endstop_phase"},{"location":"Status_Reference.html#exclude_object","text":"The following information is available in the exclude_object object: objects : An array of the known objects as provided by the EXCLUDE_OBJECT_DEFINE command. This is the same information provided by the EXCLUDE_OBJECT VERBOSE=1 command. The center and polygon fields will only be present if provided in the original EXCLUDE_OBJECT_DEFINE Here is a JSON sample: [ { \"polygon\": [ [ 156.25, 146.2511675 ], [ 156.25, 153.7488325 ], [ 163.75, 153.7488325 ], [ 163.75, 146.2511675 ] ], \"name\": \"CYLINDER_2_STL_ID_2_COPY_0\", \"center\": [ 160, 150 ] }, { \"polygon\": [ [ 146.25, 146.2511675 ], [ 146.25, 153.7488325 ], [ 153.75, 153.7488325 ], [ 153.75, 146.2511675 ] ], \"name\": \"CYLINDER_2_STL_ID_1_COPY_0\", \"center\": [ 150, 150 ] } ] excluded_objects : An array of strings listing the names of excluded objects. current_object : The name of the object currently being printed.","title":"exclude_object"},{"location":"Status_Reference.html#extruder_stepper","text":"The following information is available for extruder_stepper objects (as well as extruder objects): pressure_advance : The current pressure advance value. smooth_time : The current pressure advance smooth time. motion_queue : The name of the extruder that this extruder stepper is currently synchronized to. This is reported as None if the extruder stepper is not currently associated with an extruder.","title":"extruder_stepper"},{"location":"Status_Reference.html#fan","text":"The following information is available in fan , heater_fan some_name and controller_fan some_name objects: speed : The fan speed as a float between 0.0 and 1.0. rpm : The measured fan speed in rotations per minute if the fan has a tachometer_pin defined.","title":"fan"},{"location":"Status_Reference.html#filament_switch_sensor","text":"The following information is available in filament_switch_sensor some_name objects: enabled : Returns True if the switch sensor is currently enabled. filament_detected : Returns True if the sensor is in a triggered state.","title":"filament_switch_sensor"},{"location":"Status_Reference.html#filament_motion_sensor","text":"The following information is available in filament_motion_sensor some_name objects: enabled : Returns True if the motion sensor is currently enabled. filament_detected : Returns True if the sensor is in a triggered state.","title":"filament_motion_sensor"},{"location":"Status_Reference.html#firmware_retraction","text":"The following information is available in the firmware_retraction object: retract_length , retract_speed , unretract_extra_length , unretract_speed : The current settings for the firmware_retraction module. These settings may differ from the config file if a SET_RETRACTION command alters them.","title":"firmware_retraction"},{"location":"Status_Reference.html#gcode","text":"The following information is available in the gcode object: commands : Returns a list of all currently available commands. For each command, if a help string is defined it will also be provided.","title":"gcode"},{"location":"Status_Reference.html#gcode_button","text":"The following information is available in gcode_button some_name objects: state : The current button state returned as \"PRESSED\" or \"RELEASED\"","title":"gcode_button"},{"location":"Status_Reference.html#gcode_macro","text":"The following information is available in gcode_macro some_name objects: <variable> : The current value of a gcode_macro variable .","title":"gcode_macro"},{"location":"Status_Reference.html#gcode_move","text":"The following information is available in the gcode_move object (this object is always available): gcode_position : The current position of the toolhead relative to the current G-Code origin. That is, positions that one might directly send to a G1 command. It is possible to access the x, y, z, and e components of this position (eg, gcode_position.x ). position : The last commanded position of the toolhead using the coordinate system specified in the config file. It is possible to access the x, y, z, and e components of this position (eg, position.x ). homing_origin : The origin of the gcode coordinate system (relative to the coordinate system specified in the config file) to use after a G28 command. The SET_GCODE_OFFSET command can alter this position. It is possible to access the x, y, and z components of this position (eg, homing_origin.x ). speed : The last speed set in a G1 command (in mm/s). speed_factor : The \"speed factor override\" as set by an M220 command. This is a floating point value such that 1.0 means no override and, for example, 2.0 would double requested speed. extrude_factor : The \"extrude factor override\" as set by an M221 command. This is a floating point value such that 1.0 means no override and, for example, 2.0 would double requested extrusions. absolute_coordinates : This returns True if in G90 absolute coordinate mode or False if in G91 relative mode. absolute_extrude : This returns True if in M82 absolute extrude mode or False if in M83 relative mode.","title":"gcode_move"},{"location":"Status_Reference.html#hall_filament_width_sensor","text":"The following information is available in the hall_filament_width_sensor object: all items from filament_switch_sensor is_active : Returns True if the sensor is currently active. Diameter : The last reading from the sensor in mm. Raw : The last raw ADC reading from the sensor.","title":"hall_filament_width_sensor"},{"location":"Status_Reference.html#heater","text":"The following information is available for heater objects such as extruder , heater_bed , and heater_generic : temperature : The last reported temperature (in Celsius as a float) for the given heater. target : The current target temperature (in Celsius as a float) for the given heater. power : The last setting of the PWM pin (a value between 0.0 and 1.0) associated with the heater. can_extrude : If extruder can extrude (defined by min_extrude_temp ), available only for extruder","title":"heater"},{"location":"Status_Reference.html#heaters","text":"The following information is available in the heaters object (this object is available if any heater is defined): available_heaters : Returns a list of all currently available heaters by their full config section names, e.g. [\"extruder\", \"heater_bed\", \"heater_generic my_custom_heater\"] . available_sensors : Returns a list of all currently available temperature sensors by their full config section names, e.g. [\"extruder\", \"heater_bed\", \"heater_generic my_custom_heater\", \"temperature_sensor electronics_temp\"] . available_monitors : Returns a list of all currently available temperature monitors by their full config section names, e.g. [\"tmc2240 stepper_x\"] . While a temperature sensor is always available to read, a temperature monitor may not be available and will return null in such case.","title":"heaters"},{"location":"Status_Reference.html#idle_timeout","text":"The following information is available in the idle_timeout object (this object is always available): state : The current state of the printer as tracked by the idle_timeout module. It is one of the following strings: \"Idle\", \"Printing\", \"Ready\". printing_time : The amount of time (in seconds) the printer has been in the \"Printing\" state (as tracked by the idle_timeout module). idle_timeout : The current 'timeout' (in seconds) to wait for the gcode to be triggered. (as set by SET_IDLE_TIMEOUT )","title":"idle_timeout"},{"location":"Status_Reference.html#led","text":"The following information is available for each [led led_name] , [neopixel led_name] , [dotstar led_name] , [pca9533 led_name] , and [pca9632 led_name] config section defined in printer.cfg: color_data : A list of color lists containing the RGBW values for a led in the chain. Each value is represented as a float from 0.0 to 1.0. Each color list contains 4 items (red, green, blue, white) even if the underlying LED supports fewer color channels. For example, the blue value (3rd item in color list) of the second neopixel in a chain could be accessed at printer[\"neopixel <config_name>\"].color_data[1][2] .","title":"led"},{"location":"Status_Reference.html#load_cell","text":"The following information is available for each [load_cell name] : 'is_calibrated': True/False is the load cell calibrated 'counts_per_gram': The number of raw sensor counts that equals 1 gram of force 'reference_tare_counts': The reference number of raw sensor counts for 0 force 'tare_counts': The current number of raw sensor counts for 0 force 'force_g': The force in grams, averaged over the last polling period. 'min_force_g': The minimum force in grams, over the last polling period. 'max_force_g': The maximum force in grams, over the last polling period.","title":"load_cell"},{"location":"Status_Reference.html#load_cell_probe","text":"The following information is available for [load_cell_probe] : all items from load_cell all items from probe 'endstop_tare_counts': the load cell probe keeps a tare value independent of the load cell. This re-set at the start of each probe. 'last_trigger_time': timestamp of the last homing trigger","title":"load_cell_probe"},{"location":"Status_Reference.html#manual_probe","text":"The following information is available in the manual_probe object: is_active : Returns True if a manual probing helper script is currently active. z_position : The current height of the nozzle (as the printer currently understands it). z_position_lower : Last probe attempt just lower than the current height. z_position_upper : Last probe attempt just greater than the current height.","title":"manual_probe"},{"location":"Status_Reference.html#mcu","text":"The following information is available in mcu and mcu some_name objects: mcu_version : The Klipper code version reported by the micro-controller. mcu_build_versions : Information on the build tools used to generate the micro-controller code (as reported by the micro-controller). mcu_constants.<constant_name> : Compile time constants reported by the micro-controller. The available constants may differ between micro-controller architectures and with each code revision. last_stats.<statistics_name> : Statistics information on the micro-controller connection.","title":"mcu"},{"location":"Status_Reference.html#motion_report","text":"The following information is available in the motion_report object (this object is automatically available if any stepper config section is defined): live_position : The requested toolhead position interpolated to the current time. live_velocity : The requested toolhead velocity (in mm/s) at the current time. live_extruder_velocity : The requested extruder velocity (in mm/s) at the current time.","title":"motion_report"},{"location":"Status_Reference.html#output_pin","text":"The following information is available in output_pin some_name and pwm_tool some_name objects: value : The \"value\" of the pin, as set by a SET_PIN command.","title":"output_pin"},{"location":"Status_Reference.html#palette2","text":"The following information is available in the palette2 object: ping : Amount of the last reported Palette 2 ping in percent. remaining_load_length : When starting a Palette 2 print, this will be the amount of filament to load into the extruder. is_splicing : True when the Palette 2 is splicing filament.","title":"palette2"},{"location":"Status_Reference.html#pause_resume","text":"The following information is available in the pause_resume object: is_paused : Returns true if a PAUSE command has been executed without a corresponding RESUME.","title":"pause_resume"},{"location":"Status_Reference.html#print_stats","text":"The following information is available in the print_stats object (this object is automatically available if a virtual_sdcard config section is defined): filename , total_duration , print_duration , filament_used , state , message : Estimated information about the current print when a virtual_sdcard print is active. info.total_layer : The total layer value of the last SET_PRINT_STATS_INFO TOTAL_LAYER=<value> G-Code command. info.current_layer : The current layer value of the last SET_PRINT_STATS_INFO CURRENT_LAYER=<value> G-Code command.","title":"print_stats"},{"location":"Status_Reference.html#probe","text":"The following information is available in the probe object (this object is also available if a bltouch config section is defined): name : Returns the name of the probe in use. last_query : Returns True if the probe was reported as \"triggered\" during the last QUERY_PROBE command. Note, if this is used in a macro, due to the order of template expansion, the QUERY_PROBE command must be run prior to the macro containing this reference. last_z_result : Returns the Z result value of the last PROBE command. Note, if this is used in a macro, due to the order of template expansion, the PROBE (or similar) command must be run prior to the macro containing this reference.","title":"probe"},{"location":"Status_Reference.html#pwm_cycle_time","text":"The following information is available in pwm_cycle_time some_name objects: value : The \"value\" of the pin, as set by a SET_PIN command.","title":"pwm_cycle_time"},{"location":"Status_Reference.html#quad_gantry_level","text":"The following information is available in the quad_gantry_level object (this object is available if quad_gantry_level is defined): applied : True if the gantry leveling process has been run and completed successfully.","title":"quad_gantry_level"},{"location":"Status_Reference.html#query_endstops","text":"The following information is available in the query_endstops object (this object is available if any endstop is defined): last_query[\"<endstop>\"] : Returns True if the given endstop was reported as \"triggered\" during the last QUERY_ENDSTOP command. Note, if this is used in a macro, due to the order of template expansion, the QUERY_ENDSTOP command must be run prior to the macro containing this reference.","title":"query_endstops"},{"location":"Status_Reference.html#screws_tilt_adjust","text":"The following information is available in the screws_tilt_adjust object: error : Returns True if the most recent SCREWS_TILT_CALCULATE command included the MAX_DEVIATION parameter and any of the probed screw points exceeded the specified MAX_DEVIATION . max_deviation : Return the last MAX_DEVIATION value of the most recent SCREWS_TILT_CALCULATE command. results[\"<screw>\"] : A dictionary containing the following keys: z : The measured Z height of the screw location. sign : A string specifying the direction to turn to screw for the necessary adjustment. Either \"CW\" for clockwise or \"CCW\" for counterclockwise. adjust : The number of screw turns to adjust the screw, given in the format \"HH:MM,\" where \"HH\" is the number of full screw turns and \"MM\" is the number of \"minutes of a clock face\" representing a partial screw turn. (E.g. \"01:15\" would mean to turn the screw one and a quarter revolutions.) is_base : Returns True if this is the base screw.","title":"screws_tilt_adjust"},{"location":"Status_Reference.html#servo","text":"The following information is available in servo some_name objects: printer[\"servo <config_name>\"].value : The last setting of the PWM pin (a value between 0.0 and 1.0) associated with the servo.","title":"servo"},{"location":"Status_Reference.html#skew_correctionpy","text":"The following information is available in the skew_correction object (this object is available if any skew_correction is defined): current_profile_name : Returns the name of the currently loaded SKEW_PROFILE.","title":"skew_correction.py"},{"location":"Status_Reference.html#stepper_enable","text":"The following information is available in the stepper_enable object (this object is available if any stepper is defined): steppers[\"<stepper>\"] : Returns True if the given stepper is enabled.","title":"stepper_enable"},{"location":"Status_Reference.html#system_stats","text":"The following information is available in the system_stats object (this object is always available): sysload , cputime , memavail : Information on the host operating system and process load.","title":"system_stats"},{"location":"Status_Reference.html#temperature-sensors","text":"The following information is available in bme280 config_section_name , htu21d config_section_name , sht3x config_section_name , lm75 config_section_name , temperature_host config_section_name and temperature_combined config_section_name objects: temperature : The last read temperature from the sensor. humidity , pressure , gas : The last read values from the sensor (only on bme280, htu21d, sht3x and lm75 sensors).","title":"temperature sensors"},{"location":"Status_Reference.html#temperature_fan","text":"The following information is available in temperature_fan some_name objects: temperature : The last read temperature from the sensor. target : The target temperature for the fan.","title":"temperature_fan"},{"location":"Status_Reference.html#temperature_sensor","text":"The following information is available in temperature_sensor some_name objects: temperature : The last read temperature from the sensor. measured_min_temp , measured_max_temp : The lowest and highest temperature seen by the sensor since the Klipper host software was last restarted.","title":"temperature_sensor"},{"location":"Status_Reference.html#tmc-drivers","text":"The following information is available in TMC stepper driver objects (eg, [tmc2208 stepper_x] ): mcu_phase_offset : The micro-controller stepper position corresponding with the driver's \"zero\" phase. This field may be null if the phase offset is not known. phase_offset_position : The \"commanded position\" corresponding to the driver's \"zero\" phase. This field may be null if the phase offset is not known. drv_status : The results of the last driver status query. (Only non-zero fields are reported.) This field will be null if the driver is not enabled (and thus is not periodically queried). temperature : The internal temperature reported by the driver. This field will be null if the driver is not enabled or if the driver does not support temperature reporting. run_current : The currently set run current. hold_current : The currently set hold current.","title":"tmc drivers"},{"location":"Status_Reference.html#toolhead","text":"The following information is available in the toolhead object (this object is always available): position : The last commanded position of the toolhead relative to the coordinate system specified in the config file. It is possible to access the x, y, z, and e components of this position (eg, position.x ). extruder : The name of the currently active extruder. For example, in a macro one could use printer[printer.toolhead.extruder].target to get the target temperature of the current extruder. homed_axes : The current cartesian axes considered to be in a \"homed\" state. This is a string containing one or more of \"x\", \"y\", \"z\". axis_minimum , axis_maximum : The axis travel limits (mm) after homing. It is possible to access the x, y, z components of this limit value (eg, axis_minimum.x , axis_maximum.z ). For Delta printers the cone_start_z is the max z height at maximum radius ( printer.toolhead.cone_start_z ). max_velocity , max_accel , minimum_cruise_ratio , square_corner_velocity : The current printing limits that are in effect. This may differ from the config file settings if a SET_VELOCITY_LIMIT (or M204 ) command alters them at run-time. stalls : The total number of times (since the last restart) that the printer had to be paused because the toolhead moved faster than moves could be read from the G-Code input.","title":"toolhead"},{"location":"Status_Reference.html#dual_carriage","text":"The following information is available in dual_carriage on a cartesian, hybrid_corexy or hybrid_corexz robot carriage_0 : The mode of the carriage 0. Possible values are: \"INACTIVE\" and \"PRIMARY\". carriage_1 : The mode of the carriage 1. Possible values are: \"INACTIVE\", \"PRIMARY\", \"COPY\", and \"MIRROR\". On a generic_cartesian kinematic, the following information is available in dual_carriage : carriages[\"<carriage>\"] : The mode of the carriage <carriage> . Possible values are \"INACTIVE\" and \"PRIMARY\" for the primary carriage and \"INACTIVE\", \"PRIMARY\", \"COPY\", and \"MIRROR\" for the dual carriage.","title":"dual_carriage"},{"location":"Status_Reference.html#virtual_sdcard","text":"The following information is available in the virtual_sdcard object: is_active : Returns True if a print from file is currently active. progress : An estimate of the current print progress (based of file size and file position). file_path : A full path to the file of currently loaded file. file_position : The current position (in bytes) of an active print. file_size : The file size (in bytes) of currently loaded file.","title":"virtual_sdcard"},{"location":"Status_Reference.html#webhooks","text":"The following information is available in the webhooks object (this object is always available): state : Returns a string indicating the current Klipper state. Possible values are: \"ready\", \"startup\", \"shutdown\", \"error\". state_message : A human readable string giving additional context on the current Klipper state.","title":"webhooks"},{"location":"Status_Reference.html#z_thermal_adjust","text":"The following information is available in the z_thermal_adjust object (this object is available if z_thermal_adjust is defined). enabled : Returns True if adjustment is enabled. temperature : Current (smoothed) temperature of the defined sensor. [degC] measured_min_temp : Minimum measured temperature. [degC] measured_max_temp : Maximum measured temperature. [degC] current_z_adjust : Last computed Z adjustment [mm]. z_adjust_ref_temperature : Current reference temperature used for calculation of Z current_z_adjust [degC].","title":"z_thermal_adjust"},{"location":"Status_Reference.html#z_tilt","text":"The following information is available in the z_tilt object (this object is available if z_tilt is defined): applied : True if the z-tilt leveling process has been run and completed successfully.","title":"z_tilt"},{"location":"TMC_Drivers.html","text":"TMC drivers \u00b6 This document provides information on using Trinamic stepper motor drivers in SPI/UART mode on Klipper. Klipper can also use Trinamic drivers in their \"standalone mode\". However, when the drivers are in this mode, no special Klipper configuration is needed and the advanced Klipper features discussed in this document are not available. In addition to this document, be sure to review the TMC driver config reference . Tuning motor current \u00b6 A higher driver current increases positional accuracy and torque. However, a higher current also increases the heat produced by the stepper motor and the stepper motor driver. If the stepper motor driver gets too hot it will disable itself and Klipper will report an error. If the stepper motor gets too hot, it loses torque and positional accuracy. (If it gets very hot it may also melt plastic parts attached to it or near it.) As a general tuning tip, prefer higher current values as long as the stepper motor does not get too hot and the stepper motor driver does not report warnings or errors. In general, it is okay for the stepper motor to feel warm, but it should not become so hot that it is painful to touch. Prefer to not specify a hold_current \u00b6 If one configures a hold_current then the TMC driver can reduce current to the stepper motor when it detects that the stepper is not moving. However, changing motor current may itself introduce motor movement. This may occur due to \"detent forces\" within the stepper motor (the permanent magnet in the rotor pulls towards the iron teeth in the stator) or due to external forces on the axis carriage. Most stepper motors will not obtain a significant benefit to reducing current during normal prints, because few printing moves will leave a stepper motor idle for sufficiently long to activate the hold_current feature. And, it is unlikely that one would want to introduce subtle print artifacts to the few printing moves that do leave a stepper idle sufficiently long. If one wishes to reduce current to motors during print start routines, then consider issuing SET_TMC_CURRENT commands in a START_PRINT macro to adjust the current before and after normal printing moves. Some printers with dedicated Z motors that are idle during normal printing moves (no bed_mesh, no bed_tilt, no Z skew_correction, no \"vase mode\" prints, etc.) may find that Z motors do run cooler with a hold_current . If implementing this then be sure to take into account this type of uncommanded Z axis movement during bed leveling, bed probing, probe calibration, and similar. The driver_TPOWERDOWN and driver_IHOLDDELAY should also be calibrated accordingly. If unsure, prefer to not specify a hold_current . Setting \"spreadCycle\" vs \"stealthChop\" Mode \u00b6 By default, Klipper places the TMC drivers in \"spreadCycle\" mode. If the driver supports \"stealthChop\" then it can be enabled by adding stealthchop_threshold: 999999 to the TMC config section. In general, spreadCycle mode provides greater torque and greater positional accuracy than stealthChop mode. However, stealthChop mode may produce significantly lower audible noise on some printers. Tests comparing modes have shown an increased \"positional lag\" of around 75% of a full-step during constant velocity moves when using stealthChop mode (for example, on a printer with 40mm rotation_distance and 200 steps_per_rotation, position deviation of constant speed moves increased by ~0.150mm). However, this \"delay in obtaining the requested position\" may not manifest as a significant print defect and one may prefer the quieter behavior of stealthChop mode. It is recommended to always use \"spreadCycle\" mode (by not specifying stealthchop_threshold ) or to always use \"stealthChop\" mode (by setting stealthchop_threshold to 999999). Unfortunately, the drivers often produce poor and confusing results if the mode changes while the motor is at a non-zero velocity. Note that the stealthchop_threshold config option does not impact sensorless homing as Klipper automatically switches the TMC driver to an appropriate mode during sensorless homing operations. TMC interpolate setting introduces small position deviation \u00b6 The TMC driver interpolate setting may reduce the audible noise of printer movement at the cost of introducing a small systemic positional error. This systemic positional error results from the driver's delay in executing \"steps\" that Klipper sends it. During constant velocity moves, this delay results in a positional error of nearly half a configured microstep (more precisely, the error is half a microstep distance minus a 512th of a full step distance). For example, on an axis with a 40mm rotation_distance, 200 steps_per_rotation, and 16 microsteps, the systemic error introduced during constant velocity moves is ~0.006mm. For best positional accuracy consider using spreadCycle mode and disable interpolation (set interpolate: False in the TMC driver config). When configured this way, one may increase the microstep setting to reduce audible noise during stepper movement. Typically, a microstep setting of 64 or 128 will have similar audible noise as interpolation, and do so without introducing a systemic positional error. If using stealthChop mode then the positional inaccuracy from interpolation is small relative to the positional inaccuracy introduced from stealthChop mode. Therefore tuning interpolation is not considered useful when in stealthChop mode, and one can leave interpolation in its default state. Sensorless Homing \u00b6 Sensorless homing allows to home an axis without the need for a physical limit switch. Instead, the carriage on the axis is moved into the mechanical limit making the stepper motor lose steps. The stepper driver senses the lost steps and indicates this to the controlling MCU (Klipper) by toggling a pin. This information can be used by Klipper as end stop for the axis. This guide covers the setup of sensorless homing for the X axis of your (cartesian) printer. However, it works the same with all other axes (that require an end stop). You should configure and tune it for one axis at a time. Limitations \u00b6 Be sure that your mechanical components are able to handle the load of the carriage bumping into the limit of the axis repeatedly. Especially leadscrews might generate a lot of force. Homing a Z axis by bumping the nozzle into the printing surface might not be a good idea. For best results, verify that the axis carriage will make a firm contact with the axis limit. Further, sensorless homing might not be accurate enough for your printer. While homing X and Y axes on a cartesian machine can work well, homing the Z axis is generally not accurate enough and may result in an inconsistent first layer height. Homing a delta printer sensorless is not advisable due to missing accuracy. Further, the stall detection of the stepper driver is dependent on the mechanical load on the motor, the motor current and the motor temperature (coil resistance). Sensorless homing works best at medium motor speeds. For very slow speeds (less than 10 RPM) the motor does not generate significant back EMF and the TMC cannot reliably detect motor stalls. Further, at very high speeds, the back EMF of the motor approaches the supply voltage of the motor, so the TMC cannot detect stalls anymore. It is advised to have a look in the datasheet of your specific TMCs. There you can also find more details on limitations of this setup. Prerequisites \u00b6 A few prerequisites are needed to use sensorless homing: A stallGuard capable TMC stepper driver (tmc2130, tmc2209, tmc2660, or tmc5160). SPI / UART interface of the TMC driver wired to micro-controller (stand-alone mode does not work). The appropriate \"DIAG\" or \"SG_TST\" pin of TMC driver connected to the micro-controller. The steps in the config checks document must be run to confirm the stepper motors are configured and working properly. Tuning \u00b6 The procedure described here has six major steps: Choose a homing speed. Configure the printer.cfg file to enable sensorless homing. Find the stallguard setting with highest sensitivity that successfully homes. Find the stallguard setting with lowest sensitivity that successfully homes with a single touch. Update the printer.cfg with the desired stallguard setting. Create or update printer.cfg macros to home consistently. Choose homing speed \u00b6 The homing speed is an important choice when performing sensorless homing. It's desirable to use a slow homing speed so that the carriage does not exert excessive force on the frame when making contact with the end of the rail. However, the TMC drivers can't reliably detect a stall at very slow speeds. A good starting point for the homing speed is for the stepper motor to make a full rotation every two seconds. For many axes this will be the rotation_distance divided by two. For example: [stepper_x] rotation_distance: 40 homing_speed: 20 ... Configure printer.cfg for sensorless homing \u00b6 The homing_retract_dist setting must be set to zero in the stepper_x config section to disable the second homing move. The second homing attempt does not add value when using sensorless homing, it will not work reliably, and it will confuse the tuning process. Be sure that a hold_current setting is not specified in the TMC driver section of the config. (If a hold_current is set then after contact is made, the motor stops while the carriage is pressed against the end of the rail, and reducing the current while in that position may cause the carriage to move - that results in poor performance and will confuse the tuning process.) It is necessary to configure the sensorless homing pins and to configure initial \"stallguard\" settings. A tmc2209 example configuration for an X axis might look like: [tmc2209 stepper_x] diag_pin: ^PA1 # Set to MCU pin connected to TMC DIAG pin driver_SGTHRS: 255 # 255 is most sensitive value, 0 is least sensitive ... [stepper_x] endstop_pin: tmc2209_stepper_x:virtual_endstop homing_retract_dist: 0 ... An example tmc2130 or tmc5160 config might look like: [tmc2130 stepper_x] diag1_pin: ^!PA1 # Pin connected to TMC DIAG1 pin (or use diag0_pin / DIAG0 pin) driver_SGT: -64 # -64 is most sensitive value, 63 is least sensitive ... [stepper_x] endstop_pin: tmc2130_stepper_x:virtual_endstop homing_retract_dist: 0 ... An example tmc2660 config might look like: [tmc2660 stepper_x] driver_SGT: -64 # -64 is most sensitive value, 63 is least sensitive ... [stepper_x] endstop_pin: ^PA1 # Pin connected to TMC SG_TST pin homing_retract_dist: 0 ... The examples above only show settings specific to sensorless homing. See the config reference for all the available options. Find highest sensitivity that successfully homes \u00b6 Place the carriage near the center of the rail. Use the SET_TMC_FIELD command to set the highest sensitivity. For tmc2209: SET_TMC_FIELD STEPPER=stepper_x FIELD=SGTHRS VALUE=255 For tmc2130, tmc5160, and tmc2660: SET_TMC_FIELD STEPPER=stepper_x FIELD=sgt VALUE=-64 Then issue a G28 X0 command and verify the axis does not move at all or quickly stops moving. If the axis does not stop, then issue an M112 to halt the printer - something is not correct with the diag/sg_tst pin wiring or configuration and it must be corrected before continuing. Next, continually decrease the sensitivity of the VALUE setting and run the SET_TMC_FIELD G28 X0 commands again to find the highest sensitivity that results in the carriage successfully moving all the way to the endstop and halting. (For tmc2209 drivers this will be decreasing SGTHRS, for other drivers it will be increasing sgt.) Be sure to start each attempt with the carriage near the center of the rail (if needed issue M84 and then manually move the carriage to the center). It should be possible to find the highest sensitivity that homes reliably (settings with higher sensitivity result in small or no movement). Note the found value as maximum_sensitivity . (If the minimum possible sensitivity (SGTHRS=0 or sgt=63) is obtained without any carriage movement then something is not correct with the diag/sg_tst pin wiring or configuration and it must be corrected before continuing.) When searching for maximum_sensitivity, it may be convenient to jump to different VALUE settings (so as to bisect the VALUE parameter). If doing this then be prepared to issue an M112 command to halt the printer, as a setting with a very low sensitivity may cause the axis to repeatedly \"bang\" into the end of the rail. Be sure to wait a couple of seconds between each homing attempt. After the TMC driver detects a stall it may take a little time for it to clear its internal indicator and be capable of detecting another stall. During these tuning tests, if a G28 X0 command does not move all the way to the axis limit, then be careful with issuing any regular movement commands (eg, G1 ). Klipper will not have a correct understanding of the carriage position and a move command may cause undesirable and confusing results. Find lowest sensitivity that homes with one touch \u00b6 When homing with the found maximum_sensitivity value, the axis should move to the end of the rail and stop with a \"single touch\" - that is, there should not be a \"clicking\" or \"banging\" sound. (If there is a banging or clicking sound at maximum_sensitivity then the homing_speed may be too low, the driver current may be too low, or sensorless homing may not be a good choice for the axis.) The next step is to again continually move the carriage to a position near the center of the rail, decrease the sensitivity, and run the SET_TMC_FIELD G28 X0 commands - the goal is now to find the lowest sensitivity that still results in the carriage successfully homing with a \"single touch\". That is, it does not \"bang\" or \"click\" when contacting the end of the rail. Note the found value as minimum_sensitivity . Update printer.cfg with sensitivity value \u00b6 After finding maximum_sensitivity and minimum_sensitivity , use a calculator to obtain the recommend sensitivity as minimum_sensitivity + (maximum_sensitivity - minimum_sensitivity)/3 . The recommended sensitivity should be in the range between the minimum and maximum, but slightly closer to the minimum. Round the final value to the nearest integer value. For tmc2209 set this in the config as driver_SGTHRS , for other TMC drivers set this in the config as driver_SGT . If the range between maximum_sensitivity and minimum_sensitivity is small (eg, less than 5) then it may result in unstable homing. A faster homing speed may increase the range and make the operation more stable. Note that if any change is made to driver current, homing speed, or a notable change is made to the printer hardware, then it will be necessary to run the tuning process again. Using Macros when Homing \u00b6 After sensorless homing completes the carriage will be pressed against the end of the rail and the stepper will exert a force on the frame until the carriage is moved away. It is a good idea to create a macro to home the axis and immediately move the carriage away from the end of the rail. It is a good idea for the macro to pause at least 2 seconds prior to starting sensorless homing (or otherwise ensure that there has been no movement on the stepper for 2 seconds). Without a delay it is possible for the driver's internal stall flag to still be set from a previous move. It can also be useful to have that macro set the driver current before homing and set a new current after the carriage has moved away. An example macro might look something like: [gcode_macro SENSORLESS_HOME_X] gcode: {% set HOME_CUR = 0.700 %} {% set driver_config = printer.configfile.settings['tmc2209 stepper_x'] %} {% set RUN_CUR = driver_config.run_current %} # Set current for sensorless homing SET_TMC_CURRENT STEPPER=stepper_x CURRENT={HOME_CUR} # Pause to ensure driver stall flag is clear G4 P2000 # Home G28 X0 # Move away G90 G1 X5 F1200 # Set current during print SET_TMC_CURRENT STEPPER=stepper_x CURRENT={RUN_CUR} The resulting macro can be called from a homing_override config section or from a START_PRINT macro . Note that if the driver current during homing is changed, then the tuning process should be run again. Tips for sensorless homing on CoreXY \u00b6 It is possible to use sensorless homing on the X and Y carriages of a CoreXY printer. Klipper uses the [stepper_x] stepper to detect stalls when homing the X carriage and uses the [stepper_y] stepper to detect stalls when homing the Y carriage. Use the tuning guide described above to find the appropriate \"stall sensitivity\" for each carriage, but be aware of the following restrictions: When using sensorless homing on CoreXY, make sure there is no hold_current configured for either stepper. While tuning, make sure both the X and Y carriages are near the center of their rails before each home attempt. After tuning is complete, when homing both X and Y, use macros to ensure that one axis is homed first, then move that carriage away from the axis limit, pause for at least 2 seconds, and then start the homing of the other carriage. The move away from the axis avoids homing one axis while the other is pressed against the axis limit (which may skew the stall detection). The pause is necessary to ensure the driver's stall flag is cleared prior to homing again. An example CoreXY homing macro might look like: [gcode_macro HOME] gcode: G90 # Home Z G28 Z0 G1 Z10 F1200 # Home Y G28 Y0 G1 Y5 F1200 # Home X G4 P2000 G28 X0 G1 X5 F1200 Querying and diagnosing driver settings \u00b6 The ` DUMP_TMC command is a useful tool when configuring and diagnosing the drivers. It will report all fields configured by Klipper as well as all fields that can be queried from the driver. All of the reported fields are defined in the Trinamic datasheet for each driver. These datasheets can be found on the Trinamic website . Obtain and review the Trinamic datasheet for the driver to interpret the results of DUMP_TMC. Configuring driver_XXX settings \u00b6 Klipper supports configuring many low-level driver fields using driver_XXX settings. The TMC driver config reference has the full list of fields available for each type of driver. In addition, almost all fields can be modified at run-time using the SET_TMC_FIELD command . Each of these fields is defined in the Trinamic datasheet for each driver. These datasheets can be found on the Trinamic website . Note that the Trinamic datasheets sometime use wording that can confuse a high-level setting (such as \"hysteresis end\") with a low-level field value (eg, \"HEND\"). In Klipper, driver_XXX and SET_TMC_FIELD always set the low-level field value that is actually written to the driver. So, for example, if the Trinamic datasheet states that a value of 3 must be written to the HEND field to obtain a \"hysteresis end\" of 0, then set driver_HEND=3 to obtain the high-level value of 0. Common Questions \u00b6 Can I use stealthChop mode on an extruder with pressure advance? \u00b6 Many people successfully use \"stealthChop\" mode with Klipper's pressure advance. Klipper implements smooth pressure advance which does not introduce any instantaneous velocity changes. However, \"stealthChop\" mode may produce lower motor torque and/or produce higher motor heat. It may or may not be an adequate mode for your particular printer. I keep getting \"Unable to read tmc uart 'stepper_x' register IFCNT\" errors? \u00b6 This occurs when Klipper is unable to communicate with a tmc2208 or tmc2209 driver. Make sure that the motor power is enabled, as the stepper motor driver generally needs motor power before it can communicate with the micro-controller. If this error occurs after flashing Klipper for the first time, then the stepper driver may have been previously programmed in a state that is not compatible with Klipper. To reset the state, remove all power from the printer for several seconds (physically unplug both USB and power plugs). Otherwise, this error is typically the result of incorrect UART pin wiring or an incorrect Klipper configuration of the UART pin settings. I keep getting \"Unable to write tmc spi 'stepper_x' register ...\" errors? \u00b6 This occurs when Klipper is unable to communicate with a tmc2130 or tmc5160 driver. Make sure that the motor power is enabled, as the stepper motor driver generally needs motor power before it can communicate with the micro-controller. Otherwise, this error is typically the result of incorrect SPI wiring, an incorrect Klipper configuration of the SPI settings, or an incomplete configuration of devices on an SPI bus. Note that if the driver is on a shared SPI bus with multiple devices then be sure to fully configure every device on that shared SPI bus in Klipper. If a device on a shared SPI bus is not configured, then it may incorrectly respond to commands not intended for it and corrupt the communication to the intended device. If there is a device on a shared SPI bus that can not be configured in Klipper, then use a static_digital_output config section to set the CS pin of the unused device high (so that it will not attempt to use the SPI bus). The board's schematic is often a useful reference for finding which devices are on an SPI bus and their associated pins. Why did I get a \"TMC reports error: ...\" error? \u00b6 This type of error indicates the TMC driver detected a problem and has disabled itself. That is, the driver stopped holding its position and ignored movement commands. If Klipper detects that an active driver has disabled itself, it will transition the printer into a \"shutdown\" state. It's also possible that a TMC reports error shutdown occurs due to SPI errors that prevent communication with the driver (on tmc2130, tmc5160, or tmc2660). If this occurs, it's common for the reported driver status to show 00000000 or ffffffff - for example: TMC reports error: DRV_STATUS: ffffffff ... OR TMC reports error: READRSP@RDSEL2: 00000000 ... . Such a failure may be due to an SPI wiring problem or may be due to a self-reset or failure of the TMC driver. Some common errors and tips for diagnosing them: TMC reports error: ... ot=1(OvertempError!) \u00b6 This indicates the motor driver disabled itself because it became too hot. Typical solutions are to decrease the stepper motor current, increase cooling on the stepper motor driver, and/or increase cooling on the stepper motor. TMC reports error: ... ShortToGND OR ShortToSupply \u00b6 This indicates the driver has disabled itself because it detected very high current passing through the driver. This may indicate a loose or shorted wire to the stepper motor or within the stepper motor itself. This error may also occur if using stealthChop mode and the TMC driver is not able to accurately predict the mechanical load of the motor. (If the driver makes a poor prediction then it may send too much current through the motor and trigger its own over-current detection.) To test this, disable stealthChop mode and check if the errors continue to occur. TMC reports error: ... reset=1(Reset) OR CS_ACTUAL=0(Reset?) OR SE=0(Reset?) \u00b6 This indicates that the driver has reset itself mid-print. This may be due to voltage or wiring issues. TMC reports error: ... uv_cp=1(Undervoltage!) \u00b6 This indicates the driver has detected a low-voltage event and has disabled itself. This may be due to wiring or power supply issues. How do I tune spreadCycle/coolStep/etc. mode on my drivers? \u00b6 The Trinamic website has guides on configuring the drivers. These guides are often technical, low-level, and may require specialized hardware. Regardless, they are the best source of information.","title":"TMC drivers"},{"location":"TMC_Drivers.html#tmc-drivers","text":"This document provides information on using Trinamic stepper motor drivers in SPI/UART mode on Klipper. Klipper can also use Trinamic drivers in their \"standalone mode\". However, when the drivers are in this mode, no special Klipper configuration is needed and the advanced Klipper features discussed in this document are not available. In addition to this document, be sure to review the TMC driver config reference .","title":"TMC drivers"},{"location":"TMC_Drivers.html#tuning-motor-current","text":"A higher driver current increases positional accuracy and torque. However, a higher current also increases the heat produced by the stepper motor and the stepper motor driver. If the stepper motor driver gets too hot it will disable itself and Klipper will report an error. If the stepper motor gets too hot, it loses torque and positional accuracy. (If it gets very hot it may also melt plastic parts attached to it or near it.) As a general tuning tip, prefer higher current values as long as the stepper motor does not get too hot and the stepper motor driver does not report warnings or errors. In general, it is okay for the stepper motor to feel warm, but it should not become so hot that it is painful to touch.","title":"Tuning motor current"},{"location":"TMC_Drivers.html#prefer-to-not-specify-a-hold_current","text":"If one configures a hold_current then the TMC driver can reduce current to the stepper motor when it detects that the stepper is not moving. However, changing motor current may itself introduce motor movement. This may occur due to \"detent forces\" within the stepper motor (the permanent magnet in the rotor pulls towards the iron teeth in the stator) or due to external forces on the axis carriage. Most stepper motors will not obtain a significant benefit to reducing current during normal prints, because few printing moves will leave a stepper motor idle for sufficiently long to activate the hold_current feature. And, it is unlikely that one would want to introduce subtle print artifacts to the few printing moves that do leave a stepper idle sufficiently long. If one wishes to reduce current to motors during print start routines, then consider issuing SET_TMC_CURRENT commands in a START_PRINT macro to adjust the current before and after normal printing moves. Some printers with dedicated Z motors that are idle during normal printing moves (no bed_mesh, no bed_tilt, no Z skew_correction, no \"vase mode\" prints, etc.) may find that Z motors do run cooler with a hold_current . If implementing this then be sure to take into account this type of uncommanded Z axis movement during bed leveling, bed probing, probe calibration, and similar. The driver_TPOWERDOWN and driver_IHOLDDELAY should also be calibrated accordingly. If unsure, prefer to not specify a hold_current .","title":"Prefer to not specify a hold_current"},{"location":"TMC_Drivers.html#setting-spreadcycle-vs-stealthchop-mode","text":"By default, Klipper places the TMC drivers in \"spreadCycle\" mode. If the driver supports \"stealthChop\" then it can be enabled by adding stealthchop_threshold: 999999 to the TMC config section. In general, spreadCycle mode provides greater torque and greater positional accuracy than stealthChop mode. However, stealthChop mode may produce significantly lower audible noise on some printers. Tests comparing modes have shown an increased \"positional lag\" of around 75% of a full-step during constant velocity moves when using stealthChop mode (for example, on a printer with 40mm rotation_distance and 200 steps_per_rotation, position deviation of constant speed moves increased by ~0.150mm). However, this \"delay in obtaining the requested position\" may not manifest as a significant print defect and one may prefer the quieter behavior of stealthChop mode. It is recommended to always use \"spreadCycle\" mode (by not specifying stealthchop_threshold ) or to always use \"stealthChop\" mode (by setting stealthchop_threshold to 999999). Unfortunately, the drivers often produce poor and confusing results if the mode changes while the motor is at a non-zero velocity. Note that the stealthchop_threshold config option does not impact sensorless homing as Klipper automatically switches the TMC driver to an appropriate mode during sensorless homing operations.","title":"Setting \"spreadCycle\" vs \"stealthChop\" Mode"},{"location":"TMC_Drivers.html#tmc-interpolate-setting-introduces-small-position-deviation","text":"The TMC driver interpolate setting may reduce the audible noise of printer movement at the cost of introducing a small systemic positional error. This systemic positional error results from the driver's delay in executing \"steps\" that Klipper sends it. During constant velocity moves, this delay results in a positional error of nearly half a configured microstep (more precisely, the error is half a microstep distance minus a 512th of a full step distance). For example, on an axis with a 40mm rotation_distance, 200 steps_per_rotation, and 16 microsteps, the systemic error introduced during constant velocity moves is ~0.006mm. For best positional accuracy consider using spreadCycle mode and disable interpolation (set interpolate: False in the TMC driver config). When configured this way, one may increase the microstep setting to reduce audible noise during stepper movement. Typically, a microstep setting of 64 or 128 will have similar audible noise as interpolation, and do so without introducing a systemic positional error. If using stealthChop mode then the positional inaccuracy from interpolation is small relative to the positional inaccuracy introduced from stealthChop mode. Therefore tuning interpolation is not considered useful when in stealthChop mode, and one can leave interpolation in its default state.","title":"TMC interpolate setting introduces small position deviation"},{"location":"TMC_Drivers.html#sensorless-homing","text":"Sensorless homing allows to home an axis without the need for a physical limit switch. Instead, the carriage on the axis is moved into the mechanical limit making the stepper motor lose steps. The stepper driver senses the lost steps and indicates this to the controlling MCU (Klipper) by toggling a pin. This information can be used by Klipper as end stop for the axis. This guide covers the setup of sensorless homing for the X axis of your (cartesian) printer. However, it works the same with all other axes (that require an end stop). You should configure and tune it for one axis at a time.","title":"Sensorless Homing"},{"location":"TMC_Drivers.html#limitations","text":"Be sure that your mechanical components are able to handle the load of the carriage bumping into the limit of the axis repeatedly. Especially leadscrews might generate a lot of force. Homing a Z axis by bumping the nozzle into the printing surface might not be a good idea. For best results, verify that the axis carriage will make a firm contact with the axis limit. Further, sensorless homing might not be accurate enough for your printer. While homing X and Y axes on a cartesian machine can work well, homing the Z axis is generally not accurate enough and may result in an inconsistent first layer height. Homing a delta printer sensorless is not advisable due to missing accuracy. Further, the stall detection of the stepper driver is dependent on the mechanical load on the motor, the motor current and the motor temperature (coil resistance). Sensorless homing works best at medium motor speeds. For very slow speeds (less than 10 RPM) the motor does not generate significant back EMF and the TMC cannot reliably detect motor stalls. Further, at very high speeds, the back EMF of the motor approaches the supply voltage of the motor, so the TMC cannot detect stalls anymore. It is advised to have a look in the datasheet of your specific TMCs. There you can also find more details on limitations of this setup.","title":"Limitations"},{"location":"TMC_Drivers.html#prerequisites","text":"A few prerequisites are needed to use sensorless homing: A stallGuard capable TMC stepper driver (tmc2130, tmc2209, tmc2660, or tmc5160). SPI / UART interface of the TMC driver wired to micro-controller (stand-alone mode does not work). The appropriate \"DIAG\" or \"SG_TST\" pin of TMC driver connected to the micro-controller. The steps in the config checks document must be run to confirm the stepper motors are configured and working properly.","title":"Prerequisites"},{"location":"TMC_Drivers.html#tuning","text":"The procedure described here has six major steps: Choose a homing speed. Configure the printer.cfg file to enable sensorless homing. Find the stallguard setting with highest sensitivity that successfully homes. Find the stallguard setting with lowest sensitivity that successfully homes with a single touch. Update the printer.cfg with the desired stallguard setting. Create or update printer.cfg macros to home consistently.","title":"Tuning"},{"location":"TMC_Drivers.html#choose-homing-speed","text":"The homing speed is an important choice when performing sensorless homing. It's desirable to use a slow homing speed so that the carriage does not exert excessive force on the frame when making contact with the end of the rail. However, the TMC drivers can't reliably detect a stall at very slow speeds. A good starting point for the homing speed is for the stepper motor to make a full rotation every two seconds. For many axes this will be the rotation_distance divided by two. For example: [stepper_x] rotation_distance: 40 homing_speed: 20 ...","title":"Choose homing speed"},{"location":"TMC_Drivers.html#configure-printercfg-for-sensorless-homing","text":"The homing_retract_dist setting must be set to zero in the stepper_x config section to disable the second homing move. The second homing attempt does not add value when using sensorless homing, it will not work reliably, and it will confuse the tuning process. Be sure that a hold_current setting is not specified in the TMC driver section of the config. (If a hold_current is set then after contact is made, the motor stops while the carriage is pressed against the end of the rail, and reducing the current while in that position may cause the carriage to move - that results in poor performance and will confuse the tuning process.) It is necessary to configure the sensorless homing pins and to configure initial \"stallguard\" settings. A tmc2209 example configuration for an X axis might look like: [tmc2209 stepper_x] diag_pin: ^PA1 # Set to MCU pin connected to TMC DIAG pin driver_SGTHRS: 255 # 255 is most sensitive value, 0 is least sensitive ... [stepper_x] endstop_pin: tmc2209_stepper_x:virtual_endstop homing_retract_dist: 0 ... An example tmc2130 or tmc5160 config might look like: [tmc2130 stepper_x] diag1_pin: ^!PA1 # Pin connected to TMC DIAG1 pin (or use diag0_pin / DIAG0 pin) driver_SGT: -64 # -64 is most sensitive value, 63 is least sensitive ... [stepper_x] endstop_pin: tmc2130_stepper_x:virtual_endstop homing_retract_dist: 0 ... An example tmc2660 config might look like: [tmc2660 stepper_x] driver_SGT: -64 # -64 is most sensitive value, 63 is least sensitive ... [stepper_x] endstop_pin: ^PA1 # Pin connected to TMC SG_TST pin homing_retract_dist: 0 ... The examples above only show settings specific to sensorless homing. See the config reference for all the available options.","title":"Configure printer.cfg for sensorless homing"},{"location":"TMC_Drivers.html#find-highest-sensitivity-that-successfully-homes","text":"Place the carriage near the center of the rail. Use the SET_TMC_FIELD command to set the highest sensitivity. For tmc2209: SET_TMC_FIELD STEPPER=stepper_x FIELD=SGTHRS VALUE=255 For tmc2130, tmc5160, and tmc2660: SET_TMC_FIELD STEPPER=stepper_x FIELD=sgt VALUE=-64 Then issue a G28 X0 command and verify the axis does not move at all or quickly stops moving. If the axis does not stop, then issue an M112 to halt the printer - something is not correct with the diag/sg_tst pin wiring or configuration and it must be corrected before continuing. Next, continually decrease the sensitivity of the VALUE setting and run the SET_TMC_FIELD G28 X0 commands again to find the highest sensitivity that results in the carriage successfully moving all the way to the endstop and halting. (For tmc2209 drivers this will be decreasing SGTHRS, for other drivers it will be increasing sgt.) Be sure to start each attempt with the carriage near the center of the rail (if needed issue M84 and then manually move the carriage to the center). It should be possible to find the highest sensitivity that homes reliably (settings with higher sensitivity result in small or no movement). Note the found value as maximum_sensitivity . (If the minimum possible sensitivity (SGTHRS=0 or sgt=63) is obtained without any carriage movement then something is not correct with the diag/sg_tst pin wiring or configuration and it must be corrected before continuing.) When searching for maximum_sensitivity, it may be convenient to jump to different VALUE settings (so as to bisect the VALUE parameter). If doing this then be prepared to issue an M112 command to halt the printer, as a setting with a very low sensitivity may cause the axis to repeatedly \"bang\" into the end of the rail. Be sure to wait a couple of seconds between each homing attempt. After the TMC driver detects a stall it may take a little time for it to clear its internal indicator and be capable of detecting another stall. During these tuning tests, if a G28 X0 command does not move all the way to the axis limit, then be careful with issuing any regular movement commands (eg, G1 ). Klipper will not have a correct understanding of the carriage position and a move command may cause undesirable and confusing results.","title":"Find highest sensitivity that successfully homes"},{"location":"TMC_Drivers.html#find-lowest-sensitivity-that-homes-with-one-touch","text":"When homing with the found maximum_sensitivity value, the axis should move to the end of the rail and stop with a \"single touch\" - that is, there should not be a \"clicking\" or \"banging\" sound. (If there is a banging or clicking sound at maximum_sensitivity then the homing_speed may be too low, the driver current may be too low, or sensorless homing may not be a good choice for the axis.) The next step is to again continually move the carriage to a position near the center of the rail, decrease the sensitivity, and run the SET_TMC_FIELD G28 X0 commands - the goal is now to find the lowest sensitivity that still results in the carriage successfully homing with a \"single touch\". That is, it does not \"bang\" or \"click\" when contacting the end of the rail. Note the found value as minimum_sensitivity .","title":"Find lowest sensitivity that homes with one touch"},{"location":"TMC_Drivers.html#update-printercfg-with-sensitivity-value","text":"After finding maximum_sensitivity and minimum_sensitivity , use a calculator to obtain the recommend sensitivity as minimum_sensitivity + (maximum_sensitivity - minimum_sensitivity)/3 . The recommended sensitivity should be in the range between the minimum and maximum, but slightly closer to the minimum. Round the final value to the nearest integer value. For tmc2209 set this in the config as driver_SGTHRS , for other TMC drivers set this in the config as driver_SGT . If the range between maximum_sensitivity and minimum_sensitivity is small (eg, less than 5) then it may result in unstable homing. A faster homing speed may increase the range and make the operation more stable. Note that if any change is made to driver current, homing speed, or a notable change is made to the printer hardware, then it will be necessary to run the tuning process again.","title":"Update printer.cfg with sensitivity value"},{"location":"TMC_Drivers.html#using-macros-when-homing","text":"After sensorless homing completes the carriage will be pressed against the end of the rail and the stepper will exert a force on the frame until the carriage is moved away. It is a good idea to create a macro to home the axis and immediately move the carriage away from the end of the rail. It is a good idea for the macro to pause at least 2 seconds prior to starting sensorless homing (or otherwise ensure that there has been no movement on the stepper for 2 seconds). Without a delay it is possible for the driver's internal stall flag to still be set from a previous move. It can also be useful to have that macro set the driver current before homing and set a new current after the carriage has moved away. An example macro might look something like: [gcode_macro SENSORLESS_HOME_X] gcode: {% set HOME_CUR = 0.700 %} {% set driver_config = printer.configfile.settings['tmc2209 stepper_x'] %} {% set RUN_CUR = driver_config.run_current %} # Set current for sensorless homing SET_TMC_CURRENT STEPPER=stepper_x CURRENT={HOME_CUR} # Pause to ensure driver stall flag is clear G4 P2000 # Home G28 X0 # Move away G90 G1 X5 F1200 # Set current during print SET_TMC_CURRENT STEPPER=stepper_x CURRENT={RUN_CUR} The resulting macro can be called from a homing_override config section or from a START_PRINT macro . Note that if the driver current during homing is changed, then the tuning process should be run again.","title":"Using Macros when Homing"},{"location":"TMC_Drivers.html#tips-for-sensorless-homing-on-corexy","text":"It is possible to use sensorless homing on the X and Y carriages of a CoreXY printer. Klipper uses the [stepper_x] stepper to detect stalls when homing the X carriage and uses the [stepper_y] stepper to detect stalls when homing the Y carriage. Use the tuning guide described above to find the appropriate \"stall sensitivity\" for each carriage, but be aware of the following restrictions: When using sensorless homing on CoreXY, make sure there is no hold_current configured for either stepper. While tuning, make sure both the X and Y carriages are near the center of their rails before each home attempt. After tuning is complete, when homing both X and Y, use macros to ensure that one axis is homed first, then move that carriage away from the axis limit, pause for at least 2 seconds, and then start the homing of the other carriage. The move away from the axis avoids homing one axis while the other is pressed against the axis limit (which may skew the stall detection). The pause is necessary to ensure the driver's stall flag is cleared prior to homing again. An example CoreXY homing macro might look like: [gcode_macro HOME] gcode: G90 # Home Z G28 Z0 G1 Z10 F1200 # Home Y G28 Y0 G1 Y5 F1200 # Home X G4 P2000 G28 X0 G1 X5 F1200","title":"Tips for sensorless homing on CoreXY"},{"location":"TMC_Drivers.html#querying-and-diagnosing-driver-settings","text":"The ` DUMP_TMC command is a useful tool when configuring and diagnosing the drivers. It will report all fields configured by Klipper as well as all fields that can be queried from the driver. All of the reported fields are defined in the Trinamic datasheet for each driver. These datasheets can be found on the Trinamic website . Obtain and review the Trinamic datasheet for the driver to interpret the results of DUMP_TMC.","title":"Querying and diagnosing driver settings"},{"location":"TMC_Drivers.html#configuring-driver_xxx-settings","text":"Klipper supports configuring many low-level driver fields using driver_XXX settings. The TMC driver config reference has the full list of fields available for each type of driver. In addition, almost all fields can be modified at run-time using the SET_TMC_FIELD command . Each of these fields is defined in the Trinamic datasheet for each driver. These datasheets can be found on the Trinamic website . Note that the Trinamic datasheets sometime use wording that can confuse a high-level setting (such as \"hysteresis end\") with a low-level field value (eg, \"HEND\"). In Klipper, driver_XXX and SET_TMC_FIELD always set the low-level field value that is actually written to the driver. So, for example, if the Trinamic datasheet states that a value of 3 must be written to the HEND field to obtain a \"hysteresis end\" of 0, then set driver_HEND=3 to obtain the high-level value of 0.","title":"Configuring driver_XXX settings"},{"location":"TMC_Drivers.html#common-questions","text":"","title":"Common Questions"},{"location":"TMC_Drivers.html#can-i-use-stealthchop-mode-on-an-extruder-with-pressure-advance","text":"Many people successfully use \"stealthChop\" mode with Klipper's pressure advance. Klipper implements smooth pressure advance which does not introduce any instantaneous velocity changes. However, \"stealthChop\" mode may produce lower motor torque and/or produce higher motor heat. It may or may not be an adequate mode for your particular printer.","title":"Can I use stealthChop mode on an extruder with pressure advance?"},{"location":"TMC_Drivers.html#i-keep-getting-unable-to-read-tmc-uart-stepper_x-register-ifcnt-errors","text":"This occurs when Klipper is unable to communicate with a tmc2208 or tmc2209 driver. Make sure that the motor power is enabled, as the stepper motor driver generally needs motor power before it can communicate with the micro-controller. If this error occurs after flashing Klipper for the first time, then the stepper driver may have been previously programmed in a state that is not compatible with Klipper. To reset the state, remove all power from the printer for several seconds (physically unplug both USB and power plugs). Otherwise, this error is typically the result of incorrect UART pin wiring or an incorrect Klipper configuration of the UART pin settings.","title":"I keep getting \"Unable to read tmc uart 'stepper_x' register IFCNT\" errors?"},{"location":"TMC_Drivers.html#i-keep-getting-unable-to-write-tmc-spi-stepper_x-register-errors","text":"This occurs when Klipper is unable to communicate with a tmc2130 or tmc5160 driver. Make sure that the motor power is enabled, as the stepper motor driver generally needs motor power before it can communicate with the micro-controller. Otherwise, this error is typically the result of incorrect SPI wiring, an incorrect Klipper configuration of the SPI settings, or an incomplete configuration of devices on an SPI bus. Note that if the driver is on a shared SPI bus with multiple devices then be sure to fully configure every device on that shared SPI bus in Klipper. If a device on a shared SPI bus is not configured, then it may incorrectly respond to commands not intended for it and corrupt the communication to the intended device. If there is a device on a shared SPI bus that can not be configured in Klipper, then use a static_digital_output config section to set the CS pin of the unused device high (so that it will not attempt to use the SPI bus). The board's schematic is often a useful reference for finding which devices are on an SPI bus and their associated pins.","title":"I keep getting \"Unable to write tmc spi 'stepper_x' register ...\" errors?"},{"location":"TMC_Drivers.html#why-did-i-get-a-tmc-reports-error-error","text":"This type of error indicates the TMC driver detected a problem and has disabled itself. That is, the driver stopped holding its position and ignored movement commands. If Klipper detects that an active driver has disabled itself, it will transition the printer into a \"shutdown\" state. It's also possible that a TMC reports error shutdown occurs due to SPI errors that prevent communication with the driver (on tmc2130, tmc5160, or tmc2660). If this occurs, it's common for the reported driver status to show 00000000 or ffffffff - for example: TMC reports error: DRV_STATUS: ffffffff ... OR TMC reports error: READRSP@RDSEL2: 00000000 ... . Such a failure may be due to an SPI wiring problem or may be due to a self-reset or failure of the TMC driver. Some common errors and tips for diagnosing them:","title":"Why did I get a \"TMC reports error: ...\" error?"},{"location":"TMC_Drivers.html#tmc-reports-error-ot1overtemperror","text":"This indicates the motor driver disabled itself because it became too hot. Typical solutions are to decrease the stepper motor current, increase cooling on the stepper motor driver, and/or increase cooling on the stepper motor.","title":"TMC reports error: ... ot=1(OvertempError!)"},{"location":"TMC_Drivers.html#tmc-reports-error-shorttognd-or-shorttosupply","text":"This indicates the driver has disabled itself because it detected very high current passing through the driver. This may indicate a loose or shorted wire to the stepper motor or within the stepper motor itself. This error may also occur if using stealthChop mode and the TMC driver is not able to accurately predict the mechanical load of the motor. (If the driver makes a poor prediction then it may send too much current through the motor and trigger its own over-current detection.) To test this, disable stealthChop mode and check if the errors continue to occur.","title":"TMC reports error: ... ShortToGND OR ShortToSupply"},{"location":"TMC_Drivers.html#tmc-reports-error-reset1reset-or-cs_actual0reset-or-se0reset","text":"This indicates that the driver has reset itself mid-print. This may be due to voltage or wiring issues.","title":"TMC reports error: ... reset=1(Reset) OR CS_ACTUAL=0(Reset?) OR SE=0(Reset?)"},{"location":"TMC_Drivers.html#tmc-reports-error-uv_cp1undervoltage","text":"This indicates the driver has detected a low-voltage event and has disabled itself. This may be due to wiring or power supply issues.","title":"TMC reports error: ... uv_cp=1(Undervoltage!)"},{"location":"TMC_Drivers.html#how-do-i-tune-spreadcyclecoolstepetc-mode-on-my-drivers","text":"The Trinamic website has guides on configuring the drivers. These guides are often technical, low-level, and may require specialized hardware. Regardless, they are the best source of information.","title":"How do I tune spreadCycle/coolStep/etc. mode on my drivers?"},{"location":"TSL1401CL_Filament_Width_Sensor.html","text":"TSL1401CL filament width sensor \u00b6 This document describes Filament Width Sensor host module. Hardware used for developing this host module is based on TSL1401CL linear sensor array but it can work with any sensor array that has analog output. You can find designs at Thingiverse . To use a sensor array as a filament width sensor, read Config Reference and G-Code documentation . How does it work? \u00b6 Sensor generates analog output based on calculated filament width. Output voltage always equals to detected filament width (Ex. 1.65v, 1.70v, 3.0v). Host module monitors voltage changes and adjusts extrusion multiplier. Note: \u00b6 Sensor readings done with 10 mm intervals by default. If necessary you are free to change this setting by editing MEASUREMENT_INTERVAL_MM parameter in filament_width_sensor.py file.","title":"TSL1401CL filament width sensor"},{"location":"TSL1401CL_Filament_Width_Sensor.html#tsl1401cl-filament-width-sensor","text":"This document describes Filament Width Sensor host module. Hardware used for developing this host module is based on TSL1401CL linear sensor array but it can work with any sensor array that has analog output. You can find designs at Thingiverse . To use a sensor array as a filament width sensor, read Config Reference and G-Code documentation .","title":"TSL1401CL filament width sensor"},{"location":"TSL1401CL_Filament_Width_Sensor.html#how-does-it-work","text":"Sensor generates analog output based on calculated filament width. Output voltage always equals to detected filament width (Ex. 1.65v, 1.70v, 3.0v). Host module monitors voltage changes and adjusts extrusion multiplier.","title":"How does it work?"},{"location":"TSL1401CL_Filament_Width_Sensor.html#note","text":"Sensor readings done with 10 mm intervals by default. If necessary you are free to change this setting by editing MEASUREMENT_INTERVAL_MM parameter in filament_width_sensor.py file.","title":"Note:"},{"location":"Using_PWM_Tools.html","text":"Using PWM tools \u00b6 This document describes how to setup a PWM-controlled laser or spindle using pwm_tool and some macros. How does it work? \u00b6 With re-purposing the printhead's fan pwm output, you can control lasers or spindles. This is useful if you use switchable print heads, for example the E3D toolchanger or a DIY solution. Usually, cam-tools such as LaserWeb can be configured to use M3-M5 commands, which stand for spindle speed CW ( M3 S[0-255] ), spindle speed CCW ( M4 S[0-255] ) and spindle stop ( M5 ). Warning: When driving a laser, keep all security precautions that you can think of! Diode lasers are usually inverted. This means, that when the MCU restarts, the laser will be fully on for the time it takes the MCU to start up again. For good measure, it is recommended to always wear appropriate laser-goggles of the right wavelength if the laser is powered; and to disconnect the laser when it is not needed. Also, you should configure a safety timeout, so that when your host or MCU encounters an error, the tool will stop. For an example configuration, see config/sample-pwm-tool.cfg . Commands \u00b6 M3/M4 S<value> : Set PWM duty-cycle. Values between 0 and 255. M5 : Stop PWM output to shutdown value. Laserweb Configuration \u00b6 If you use Laserweb, a working configuration would be: GCODE START: M5 ; Disable Laser G21 ; Set units to mm G90 ; Absolute positioning G0 Z0 F7000 ; Set Non-Cutting speed GCODE END: M5 ; Disable Laser G91 ; relative G0 Z+20 F4000 ; G90 ; absolute GCODE HOMING: M5 ; Disable Laser G28 ; Home all axis TOOL ON: M3 $INTENSITY TOOL OFF: M5 ; Disable Laser LASER INTENSITY: S","title":"Using PWM tools"},{"location":"Using_PWM_Tools.html#using-pwm-tools","text":"This document describes how to setup a PWM-controlled laser or spindle using pwm_tool and some macros.","title":"Using PWM tools"},{"location":"Using_PWM_Tools.html#how-does-it-work","text":"With re-purposing the printhead's fan pwm output, you can control lasers or spindles. This is useful if you use switchable print heads, for example the E3D toolchanger or a DIY solution. Usually, cam-tools such as LaserWeb can be configured to use M3-M5 commands, which stand for spindle speed CW ( M3 S[0-255] ), spindle speed CCW ( M4 S[0-255] ) and spindle stop ( M5 ). Warning: When driving a laser, keep all security precautions that you can think of! Diode lasers are usually inverted. This means, that when the MCU restarts, the laser will be fully on for the time it takes the MCU to start up again. For good measure, it is recommended to always wear appropriate laser-goggles of the right wavelength if the laser is powered; and to disconnect the laser when it is not needed. Also, you should configure a safety timeout, so that when your host or MCU encounters an error, the tool will stop. For an example configuration, see config/sample-pwm-tool.cfg .","title":"How does it work?"},{"location":"Using_PWM_Tools.html#commands","text":"M3/M4 S<value> : Set PWM duty-cycle. Values between 0 and 255. M5 : Stop PWM output to shutdown value.","title":"Commands"},{"location":"Using_PWM_Tools.html#laserweb-configuration","text":"If you use Laserweb, a working configuration would be: GCODE START: M5 ; Disable Laser G21 ; Set units to mm G90 ; Absolute positioning G0 Z0 F7000 ; Set Non-Cutting speed GCODE END: M5 ; Disable Laser G91 ; relative G0 Z+20 F4000 ; G90 ; absolute GCODE HOMING: M5 ; Disable Laser G28 ; Home all axis TOOL ON: M3 $INTENSITY TOOL OFF: M5 ; Disable Laser LASER INTENSITY: S","title":"Laserweb Configuration"}]}
\ No newline at end of file
+{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"index.html","text":"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 .","title":"Welcome"},{"location":"API_Server.html","text":"API server \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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\" \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 Dumps the configuration and state for the current mesh and all saved profiles. For example: {\"id\": 123, \"method\": \"bed_mesh/dump_mesh\"} might return: { \"current_mesh\": { \"name\": \"eddy-scan-test\", \"probed_matrix\": [...], \"mesh_matrix\": [...], \"mesh_params\": { \"x_count\": 9, \"y_count\": 9, \"mesh_x_pps\": 2, \"mesh_y_pps\": 2, \"algo\": \"bicubic\", \"tension\": 0.5, \"min_x\": 20, \"max_x\": 330, \"min_y\": 30, \"max_y\": 320 } }, \"profiles\": { \"default\": { \"points\": [...], \"mesh_params\": { \"min_x\": 20, \"max_x\": 330, \"min_y\": 30, \"max_y\": 320, \"x_count\": 9, \"y_count\": 9, \"mesh_x_pps\": 2, \"mesh_y_pps\": 2, \"algo\": \"bicubic\", \"tension\": 0.5 } }, \"eddy-scan-test\": { \"points\": [...], \"mesh_params\": { \"x_count\": 9, \"y_count\": 9, \"mesh_x_pps\": 2, \"mesh_y_pps\": 2, \"algo\": \"bicubic\", \"tension\": 0.5, \"min_x\": 20, \"max_x\": 330, \"min_y\": 30, \"max_y\": 320 } }, \"eddy-rapid-test\": { \"points\": [...], \"mesh_params\": { \"x_count\": 9, \"y_count\": 9, \"mesh_x_pps\": 2, \"mesh_y_pps\": 2, \"algo\": \"bicubic\", \"tension\": 0.5, \"min_x\": 20, \"max_x\": 330, \"min_y\": 30, \"max_y\": 320 } } }, \"calibration\": { \"points\": [...], \"config\": { \"x_count\": 9, \"y_count\": 9, \"mesh_x_pps\": 2, \"mesh_y_pps\": 2, \"algo\": \"bicubic\", \"tension\": 0.5, \"mesh_min\": [ 20, 30 ], \"mesh_max\": [ 330, 320 ], \"origin\": null, \"radius\": null }, \"probe_path\": [...], \"rapid_path\": [...] }, \"probe_offsets\": [ 0, 25, 0.5 ], \"axis_minimum\": [ 0, 0, -5, 0 ], \"axis_maximum\": [ 351, 358, 330, 0 ] } 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 .","title":"API server"},{"location":"API_Server.html#api-server","text":"This document describes Klipper's Application Programmer Interface (API). This interface enables external applications to query and control the Klipper host software.","title":"API server"},{"location":"API_Server.html#enabling-the-api-socket","text":"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.","title":"Enabling the API socket"},{"location":"API_Server.html#request-format","text":"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.)","title":"Request format"},{"location":"API_Server.html#api-protocol","text":"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.","title":"API Protocol"},{"location":"API_Server.html#subscriptions","text":"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 ( {} ).","title":"Subscriptions"},{"location":"API_Server.html#available-endpoints","text":"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\"} ).","title":"Available \"endpoints\""},{"location":"API_Server.html#info","text":"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.","title":"info"},{"location":"API_Server.html#emergency_stop","text":"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\"}","title":"emergency_stop"},{"location":"API_Server.html#register_remote_method","text":"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}}","title":"register_remote_method"},{"location":"API_Server.html#objectslist","text":"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\"]}}","title":"objects/list"},{"location":"API_Server.html#objectsquery","text":"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.","title":"objects/query"},{"location":"API_Server.html#objectssubscribe","text":"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}}","title":"objects/subscribe"},{"location":"API_Server.html#gcodehelp","text":"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\", ...}}","title":"gcode/help"},{"location":"API_Server.html#gcodescript","text":"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.","title":"gcode/script"},{"location":"API_Server.html#gcoderestart","text":"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.","title":"gcode/restart"},{"location":"API_Server.html#gcodefirmware_restart","text":"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.","title":"gcode/firmware_restart"},{"location":"API_Server.html#gcodesubscribe_output","text":"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.","title":"gcode/subscribe_output"},{"location":"API_Server.html#motion_reportdump_stepper","text":"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.","title":"motion_report/dump_stepper"},{"location":"API_Server.html#motion_reportdump_trapq","text":"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.","title":"motion_report/dump_trapq"},{"location":"API_Server.html#adxl345dump_adxl345","text":"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.","title":"adxl345/dump_adxl345"},{"location":"API_Server.html#angledump_angle","text":"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.","title":"angle/dump_angle"},{"location":"API_Server.html#load_celldump_force","text":"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.","title":"load_cell/dump_force"},{"location":"API_Server.html#load_cell_probedump_taps","text":"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","title":"load_cell_probe/dump_taps"},{"location":"API_Server.html#pause_resumecancel","text":"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.","title":"pause_resume/cancel"},{"location":"API_Server.html#pause_resumepause","text":"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.","title":"pause_resume/pause"},{"location":"API_Server.html#pause_resumeresume","text":"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.","title":"pause_resume/resume"},{"location":"API_Server.html#query_endstopsstatus","text":"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.","title":"query_endstops/status"},{"location":"API_Server.html#bed_meshdump_mesh","text":"Dumps the configuration and state for the current mesh and all saved profiles. For example: {\"id\": 123, \"method\": \"bed_mesh/dump_mesh\"} might return: { \"current_mesh\": { \"name\": \"eddy-scan-test\", \"probed_matrix\": [...], \"mesh_matrix\": [...], \"mesh_params\": { \"x_count\": 9, \"y_count\": 9, \"mesh_x_pps\": 2, \"mesh_y_pps\": 2, \"algo\": \"bicubic\", \"tension\": 0.5, \"min_x\": 20, \"max_x\": 330, \"min_y\": 30, \"max_y\": 320 } }, \"profiles\": { \"default\": { \"points\": [...], \"mesh_params\": { \"min_x\": 20, \"max_x\": 330, \"min_y\": 30, \"max_y\": 320, \"x_count\": 9, \"y_count\": 9, \"mesh_x_pps\": 2, \"mesh_y_pps\": 2, \"algo\": \"bicubic\", \"tension\": 0.5 } }, \"eddy-scan-test\": { \"points\": [...], \"mesh_params\": { \"x_count\": 9, \"y_count\": 9, \"mesh_x_pps\": 2, \"mesh_y_pps\": 2, \"algo\": \"bicubic\", \"tension\": 0.5, \"min_x\": 20, \"max_x\": 330, \"min_y\": 30, \"max_y\": 320 } }, \"eddy-rapid-test\": { \"points\": [...], \"mesh_params\": { \"x_count\": 9, \"y_count\": 9, \"mesh_x_pps\": 2, \"mesh_y_pps\": 2, \"algo\": \"bicubic\", \"tension\": 0.5, \"min_x\": 20, \"max_x\": 330, \"min_y\": 30, \"max_y\": 320 } } }, \"calibration\": { \"points\": [...], \"config\": { \"x_count\": 9, \"y_count\": 9, \"mesh_x_pps\": 2, \"mesh_y_pps\": 2, \"algo\": \"bicubic\", \"tension\": 0.5, \"mesh_min\": [ 20, 30 ], \"mesh_max\": [ 330, 320 ], \"origin\": null, \"radius\": null }, \"probe_path\": [...], \"rapid_path\": [...] }, \"probe_offsets\": [ 0, 25, 0.5 ], \"axis_minimum\": [ 0, 0, -5, 0 ], \"axis_maximum\": [ 351, 358, 330, 0 ] } 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 .","title":"bed_mesh/dump_mesh"},{"location":"Axis_Twist_Compensation.html","text":"Axis Twist Compensation \u00b6 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 \u00b6 Tip: Make sure the probe X and Y offsets are correctly set as they greatly influence calibration. Basic Usage: X-Axis Calibration \u00b6 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> Adjust Your Z Offset: After completing the calibration, be sure to adjust your Z offset . Perform Bed Leveling Operations: Use probe-based operations as needed, such as: - Screws Tilt Adjust - Z Tilt Adjust 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 \u00b6 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 \u00b6 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","title":"Axis Twist Compensation"},{"location":"Axis_Twist_Compensation.html#axis-twist-compensation","text":"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.","title":"Axis Twist Compensation"},{"location":"Axis_Twist_Compensation.html#overview-of-compensation-usage","text":"Tip: Make sure the probe X and Y offsets are correctly set as they greatly influence calibration.","title":"Overview of compensation usage"},{"location":"Axis_Twist_Compensation.html#basic-usage-x-axis-calibration","text":"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> Adjust Your Z Offset: After completing the calibration, be sure to adjust your Z offset . Perform Bed Leveling Operations: Use probe-based operations as needed, such as: - Screws Tilt Adjust - Z Tilt Adjust Finalize the Setup: Home all axes, and perform a Bed Mesh if necessary. Run a test print, followed by any fine-tuning if needed.","title":"Basic Usage: X-Axis Calibration"},{"location":"Axis_Twist_Compensation.html#for-y-axis-calibration","text":"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.","title":"For Y-Axis Calibration"},{"location":"Axis_Twist_Compensation.html#axis_twist_compensation-setup-and-commands","text":"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","title":"[axis_twist_compensation] setup and commands"},{"location":"BLTouch.html","text":"BL-Touch \u00b6 Connecting BL-Touch \u00b6 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 \u00b6 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 \u00b6 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\" \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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.","title":"BL-Touch"},{"location":"BLTouch.html#bl-touch","text":"","title":"BL-Touch"},{"location":"BLTouch.html#connecting-bl-touch","text":"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.","title":"Connecting BL-Touch"},{"location":"BLTouch.html#initial-tests","text":"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.","title":"Initial tests"},{"location":"BLTouch.html#bl-touch-gone-bad","text":"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.","title":"BL-Touch gone bad"},{"location":"BLTouch.html#bl-touch-clones","text":"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.","title":"BL-Touch \"clones\""},{"location":"BLTouch.html#bl-touch-v3","text":"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).","title":"BL-Touch v3"},{"location":"BLTouch.html#multi-probing-without-stowing","text":"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).","title":"Multi-probing without stowing"},{"location":"BLTouch.html#calibrating-the-bl-touch-offsets","text":"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.","title":"Calibrating the BL-Touch offsets"},{"location":"BLTouch.html#bl-touch-output-mode","text":"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.","title":"BL-Touch output mode"},{"location":"Beaglebone.html","text":"Beaglebone \u00b6 This document describes the process of running Klipper on a Beaglebone PRU. Building an OS image \u00b6 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: remove some BeagleBone \"Demo\" resources if you did boot from SD-Card, and it's bigger than 4Gb - you can expand current filesystem to take whole card space 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 \u00b6 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) \u00b6 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 \u00b6 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 \u00b6 Complete the installation by configuring Klipper following the instructions in the main Installation document. Printing on the Beaglebone \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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","title":"Beaglebone"},{"location":"Beaglebone.html#beaglebone","text":"This document describes the process of running Klipper on a Beaglebone PRU.","title":"Beaglebone"},{"location":"Beaglebone.html#building-an-os-image","text":"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: remove some BeagleBone \"Demo\" resources if you did boot from SD-Card, and it's bigger than 4Gb - you can expand current filesystem to take whole card space 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.","title":"Building an OS image"},{"location":"Beaglebone.html#installing-octoprint","text":"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/","title":"Installing Octoprint"},{"location":"Beaglebone.html#building-the-beaglebone-pru-micro-controller-code-pru-firmware","text":"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.","title":"Building the BeagleBone PRU micro-controller code (PRU firmware)"},{"location":"Beaglebone.html#building-and-installing-linux-host-micro-controller-code","text":"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.","title":"Building and installing Linux host micro-controller code"},{"location":"Beaglebone.html#remaining-configuration","text":"Complete the installation by configuring Klipper following the instructions in the main Installation document.","title":"Remaining configuration"},{"location":"Beaglebone.html#printing-on-the-beaglebone","text":"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.","title":"Printing on the Beaglebone"},{"location":"Beaglebone.html#avr-micro-controller-code-build","text":"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","title":"AVR micro-controller code build"},{"location":"Beaglebone.html#hardware-pin-designation","text":"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.","title":"Hardware Pin designation"},{"location":"Beaglebone.html#enabling-hardware-spi","text":"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.","title":"Enabling hardware SPI"},{"location":"Beaglebone.html#enabling-hardware-i2c","text":"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","title":"Enabling hardware I2C"},{"location":"Beaglebone.html#enabling-hardware-uartserialcan","text":"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","title":"Enabling hardware UART(Serial)/CAN"},{"location":"Bed_Level.html","text":"Bed leveling \u00b6 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 \u00b6 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\" \u00b6 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 \u00b6 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.","title":"Bed leveling"},{"location":"Bed_Level.html#bed-leveling","text":"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.","title":"Bed leveling"},{"location":"Bed_Level.html#choose-the-appropriate-calibration-mechanism","text":"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.","title":"Choose the appropriate calibration mechanism"},{"location":"Bed_Level.html#the-paper-test","text":"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.","title":"The \"paper test\""},{"location":"Bed_Level.html#determining-thermal-expansion","text":"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.","title":"Determining Thermal Expansion"},{"location":"Bed_Mesh.html","text":"Bed Mesh \u00b6 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 \u00b6 Rectangular Beds \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 Calibration \u00b6 BED_MESH_CALIBRATE PROFILE=<name> METHOD=[manual | automatic | scan | rapid_scan] <br> [<probe_parameter>=<value>] [<mesh_parameter>=<value>] [ADAPTIVE=[0|1] <br> [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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 BED_MESH_CLEAR This gcode may be used to clear the internal mesh state. Apply X/Y offsets \u00b6 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 \u00b6 Dumping mesh data \u00b6 {\"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 \u00b6 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 \u00b6 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 \u00b6 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 <input> -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 \u00b6 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 <input> 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 \u00b6 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 <input> 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","title":"Bed Mesh"},{"location":"Bed_Mesh.html#bed-mesh","text":"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.","title":"Bed Mesh"},{"location":"Bed_Mesh.html#basic-configuration","text":"","title":"Basic Configuration"},{"location":"Bed_Mesh.html#rectangular-beds","text":"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).","title":"Rectangular Beds"},{"location":"Bed_Mesh.html#round-beds","text":"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.","title":"Round beds"},{"location":"Bed_Mesh.html#advanced-configuration","text":"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.","title":"Advanced Configuration"},{"location":"Bed_Mesh.html#mesh-interpolation","text":"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.","title":"Mesh Interpolation"},{"location":"Bed_Mesh.html#move-splitting","text":"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.","title":"Move Splitting"},{"location":"Bed_Mesh.html#mesh-fade","text":"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.","title":"Mesh Fade"},{"location":"Bed_Mesh.html#configuring-the-zero-reference-position","text":"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.","title":"Configuring the zero reference position"},{"location":"Bed_Mesh.html#faulty-regions","text":"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.","title":"Faulty Regions"},{"location":"Bed_Mesh.html#adaptive-meshes","text":"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.","title":"Adaptive Meshes"},{"location":"Bed_Mesh.html#surface-scans","text":"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.","title":"Surface Scans"},{"location":"Bed_Mesh.html#scan-height","text":"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.","title":"Scan Height"},{"location":"Bed_Mesh.html#rapid-continuous-scanning","text":"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.","title":"Rapid (Continuous) Scanning"},{"location":"Bed_Mesh.html#bed-mesh-gcodes","text":"","title":"Bed Mesh Gcodes"},{"location":"Bed_Mesh.html#calibration","text":"BED_MESH_CALIBRATE PROFILE=<name> METHOD=[manual | automatic | scan | rapid_scan] <br> [<probe_parameter>=<value>] [<mesh_parameter>=<value>] [ADAPTIVE=[0|1] <br> [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.","title":"Calibration"},{"location":"Bed_Mesh.html#profiles","text":"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.","title":"Profiles"},{"location":"Bed_Mesh.html#loading-the-default-profile","text":"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","title":"Loading the default profile"},{"location":"Bed_Mesh.html#output","text":"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.","title":"Output"},{"location":"Bed_Mesh.html#clear-mesh-state","text":"BED_MESH_CLEAR This gcode may be used to clear the internal mesh state.","title":"Clear Mesh State"},{"location":"Bed_Mesh.html#apply-xy-offsets","text":"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 .","title":"Apply X/Y offsets"},{"location":"Bed_Mesh.html#bed-mesh-webhooks-apis","text":"","title":"Bed Mesh Webhooks APIs"},{"location":"Bed_Mesh.html#dumping-mesh-data","text":"{\"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 .","title":"Dumping mesh data"},{"location":"Bed_Mesh.html#visualization-and-analysis","text":"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","title":"Visualization and analysis"},{"location":"Bed_Mesh.html#pre-requisites","text":"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.","title":"Pre-requisites"},{"location":"Bed_Mesh.html#plotting-mesh-data","text":"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 <input> -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","title":"Plotting Mesh data"},{"location":"Bed_Mesh.html#bed-mesh-analysis","text":"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 <input> 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","title":"Bed Mesh Analysis"},{"location":"Bed_Mesh.html#save-mesh-data-to-a-file","text":"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 <input> 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","title":"Save mesh data to a file"},{"location":"Benchmarks.html","text":"Benchmarks \u00b6 This document describes Klipper benchmarks. Micro-controller Benchmarks \u00b6 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 \u00b6 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 \u00b6 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). avr ticks 1 stepper 102 3 stepper 486 Arduino Due step rate benchmark \u00b6 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 . sam3x8e ticks 1 stepper 66 3 stepper 257 Duet Maestro step rate benchmark \u00b6 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 . sam4s8c ticks 1 stepper 71 3 stepper 260 Duet Wifi step rate benchmark \u00b6 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) . sam4e8e ticks 1 stepper 48 3 stepper 215 Beaglebone PRU step rate benchmark \u00b6 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) . pru ticks 1 stepper 231 3 stepper 847 STM32F042 step rate benchmark \u00b6 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 . stm32f042 ticks 1 stepper 59 3 stepper 249 STM32F103 step rate benchmark \u00b6 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 . stm32f103 ticks 1 stepper 61 3 stepper 264 STM32F4 step rate benchmark \u00b6 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). stm32f446 ticks 1 stepper 46 3 stepper 205 stm32f407 ticks 1 stepper 46 3 stepper 205 STM32H7 step rate benchmark \u00b6 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 . stm32h723 ticks 1 stepper 70 3 stepper 181 STM32G0B1 step rate benchmark \u00b6 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 . stm32g0b1 ticks 1 stepper 58 3 stepper 243 STM32G4 step rate benchmark \u00b6 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 . stm32g431 ticks 1 stepper 47 3 stepper 208 LPC176x step rate benchmark \u00b6 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. lpc1768 ticks 1 stepper 52 3 stepper 222 lpc1769 ticks 1 stepper 51 3 stepper 222 SAMD21 step rate benchmark \u00b6 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. samd21 ticks 1 stepper 70 3 stepper 306 SAMD51 step rate benchmark \u00b6 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. samd51 ticks 1 stepper 39 3 stepper 191 1 stepper (200Mhz) 39 3 stepper (200Mhz) 181 SAME70 step rate benchmark \u00b6 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. same70 ticks 1 stepper 45 3 stepper 190 AR100 step rate benchmark \u00b6 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. AR100 R_PIO ticks 1 stepper 85 3 stepper 359 RPxxxx step rate benchmark \u00b6 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. rp2040 (*) ticks 1 stepper 3 3 stepper 14 rp2350 ticks 1 stepper 36 3 stepper 169 (*) 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 \u00b6 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. Linux (RPi3) ticks 1 stepper 160 3 stepper 380 Command dispatch benchmark \u00b6 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. MCU Rate Build Build compiler atmega2560 (serial) 23K b161a69e avr-gcc (GCC) 4.8.1 sam3x8e (serial) 23K b161a69e arm-none-eabi-gcc (Fedora 7.1.0-5.fc27) 7.1.0 rp2350 (CAN) 59K 17b8ce4c arm-none-eabi-gcc (Fedora 14.1.0-1.fc40) 14.1.0 at90usb1286 (USB) 75K 01d2183f avr-gcc (GCC) 5.4.0 ar100 (serial) 138K 08d037c6 or1k-linux-musl-gcc 9.3.0 samd21 (USB) 223K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 pru (shared memory) 260K c5968a08 pru-gcc (GCC) 8.0.0 20170530 (experimental) stm32f103 (USB) 355K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 sam3x8e (USB) 418K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 lpc1768 (USB) 534K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 lpc1769 (USB) 628K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 sam4s8c (USB) 650K 8d4a5c16 arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 samd51 (USB) 864K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 stm32f446 (USB) 870K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 rp2040 (USB) 885K f6718291 arm-none-eabi-gcc (Fedora 14.1.0-1.fc40) 14.1.0 rp2350 (USB) 885K f6718291 arm-none-eabi-gcc (Fedora 14.1.0-1.fc40) 14.1.0 Host Benchmarks \u00b6 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","title":"Benchmarks"},{"location":"Benchmarks.html#benchmarks","text":"This document describes Klipper benchmarks.","title":"Benchmarks"},{"location":"Benchmarks.html#micro-controller-benchmarks","text":"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.","title":"Micro-controller Benchmarks"},{"location":"Benchmarks.html#step-rate-benchmark-test","text":"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.","title":"Step rate benchmark test"},{"location":"Benchmarks.html#avr-step-rate-benchmark","text":"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). avr ticks 1 stepper 102 3 stepper 486","title":"AVR step rate benchmark"},{"location":"Benchmarks.html#arduino-due-step-rate-benchmark","text":"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 . sam3x8e ticks 1 stepper 66 3 stepper 257","title":"Arduino Due step rate benchmark"},{"location":"Benchmarks.html#duet-maestro-step-rate-benchmark","text":"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 . sam4s8c ticks 1 stepper 71 3 stepper 260","title":"Duet Maestro step rate benchmark"},{"location":"Benchmarks.html#duet-wifi-step-rate-benchmark","text":"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) . sam4e8e ticks 1 stepper 48 3 stepper 215","title":"Duet Wifi step rate benchmark"},{"location":"Benchmarks.html#beaglebone-pru-step-rate-benchmark","text":"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) . pru ticks 1 stepper 231 3 stepper 847","title":"Beaglebone PRU step rate benchmark"},{"location":"Benchmarks.html#stm32f042-step-rate-benchmark","text":"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 . stm32f042 ticks 1 stepper 59 3 stepper 249","title":"STM32F042 step rate benchmark"},{"location":"Benchmarks.html#stm32f103-step-rate-benchmark","text":"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 . stm32f103 ticks 1 stepper 61 3 stepper 264","title":"STM32F103 step rate benchmark"},{"location":"Benchmarks.html#stm32f4-step-rate-benchmark","text":"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). stm32f446 ticks 1 stepper 46 3 stepper 205 stm32f407 ticks 1 stepper 46 3 stepper 205","title":"STM32F4 step rate benchmark"},{"location":"Benchmarks.html#stm32h7-step-rate-benchmark","text":"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 . stm32h723 ticks 1 stepper 70 3 stepper 181","title":"STM32H7 step rate benchmark"},{"location":"Benchmarks.html#stm32g0b1-step-rate-benchmark","text":"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 . stm32g0b1 ticks 1 stepper 58 3 stepper 243","title":"STM32G0B1 step rate benchmark"},{"location":"Benchmarks.html#stm32g4-step-rate-benchmark","text":"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 . stm32g431 ticks 1 stepper 47 3 stepper 208","title":"STM32G4 step rate benchmark"},{"location":"Benchmarks.html#lpc176x-step-rate-benchmark","text":"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. lpc1768 ticks 1 stepper 52 3 stepper 222 lpc1769 ticks 1 stepper 51 3 stepper 222","title":"LPC176x step rate benchmark"},{"location":"Benchmarks.html#samd21-step-rate-benchmark","text":"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. samd21 ticks 1 stepper 70 3 stepper 306","title":"SAMD21 step rate benchmark"},{"location":"Benchmarks.html#samd51-step-rate-benchmark","text":"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. samd51 ticks 1 stepper 39 3 stepper 191 1 stepper (200Mhz) 39 3 stepper (200Mhz) 181","title":"SAMD51 step rate benchmark"},{"location":"Benchmarks.html#same70-step-rate-benchmark","text":"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. same70 ticks 1 stepper 45 3 stepper 190","title":"SAME70 step rate benchmark"},{"location":"Benchmarks.html#ar100-step-rate-benchmark","text":"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. AR100 R_PIO ticks 1 stepper 85 3 stepper 359","title":"AR100 step rate benchmark"},{"location":"Benchmarks.html#rpxxxx-step-rate-benchmark","text":"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. rp2040 (*) ticks 1 stepper 3 3 stepper 14 rp2350 ticks 1 stepper 36 3 stepper 169 (*) 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.","title":"RPxxxx step rate benchmark"},{"location":"Benchmarks.html#linux-mcu-step-rate-benchmark","text":"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. Linux (RPi3) ticks 1 stepper 160 3 stepper 380","title":"Linux MCU step rate benchmark"},{"location":"Benchmarks.html#command-dispatch-benchmark","text":"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. MCU Rate Build Build compiler atmega2560 (serial) 23K b161a69e avr-gcc (GCC) 4.8.1 sam3x8e (serial) 23K b161a69e arm-none-eabi-gcc (Fedora 7.1.0-5.fc27) 7.1.0 rp2350 (CAN) 59K 17b8ce4c arm-none-eabi-gcc (Fedora 14.1.0-1.fc40) 14.1.0 at90usb1286 (USB) 75K 01d2183f avr-gcc (GCC) 5.4.0 ar100 (serial) 138K 08d037c6 or1k-linux-musl-gcc 9.3.0 samd21 (USB) 223K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 pru (shared memory) 260K c5968a08 pru-gcc (GCC) 8.0.0 20170530 (experimental) stm32f103 (USB) 355K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 sam3x8e (USB) 418K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 lpc1768 (USB) 534K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 lpc1769 (USB) 628K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 sam4s8c (USB) 650K 8d4a5c16 arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 samd51 (USB) 864K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 stm32f446 (USB) 870K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 rp2040 (USB) 885K f6718291 arm-none-eabi-gcc (Fedora 14.1.0-1.fc40) 14.1.0 rp2350 (USB) 885K f6718291 arm-none-eabi-gcc (Fedora 14.1.0-1.fc40) 14.1.0","title":"Command dispatch benchmark"},{"location":"Benchmarks.html#host-benchmarks","text":"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","title":"Host Benchmarks"},{"location":"Bootloader_Entry.html","text":"Bootloader Entry \u00b6 Klipper can be instructed to reboot into a Bootloader in one of the following ways: Requesting the bootloader \u00b6 Virtual Serial \u00b6 If a virtual (USB-ACM) serial port is in use, pulsing DTR while at 1200 baud will request the bootloader. Python (with flash_usb ) \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 <BAUD> is the baud rate of the serial port, such as 115200 . CANBUS \u00b6 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 \u00b6 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. <UUID> is the UUID of your CAN device. See the CANBUS Documentation for information on finding the CAN UUID of your devices. Entering the bootloader \u00b6 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 \u00b6 STM32 DFU Warning \u00b6 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.","title":"Bootloader Entry"},{"location":"Bootloader_Entry.html#bootloader-entry","text":"Klipper can be instructed to reboot into a Bootloader in one of the following ways:","title":"Bootloader Entry"},{"location":"Bootloader_Entry.html#requesting-the-bootloader","text":"","title":"Requesting the bootloader"},{"location":"Bootloader_Entry.html#virtual-serial","text":"If a virtual (USB-ACM) serial port is in use, pulsing DTR while at 1200 baud will request the bootloader.","title":"Virtual Serial"},{"location":"Bootloader_Entry.html#python-with-flash_usb","text":"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> .","title":"Python (with flash_usb)"},{"location":"Bootloader_Entry.html#picocom","text":"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","title":"Picocom"},{"location":"Bootloader_Entry.html#physical-serial","text":"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.","title":"Physical serial"},{"location":"Bootloader_Entry.html#shell","text":"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 <BAUD> is the baud rate of the serial port, such as 115200 .","title":"Shell"},{"location":"Bootloader_Entry.html#canbus","text":"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.","title":"CANBUS"},{"location":"Bootloader_Entry.html#katapults-flashtoolpy","text":"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. <UUID> is the UUID of your CAN device. See the CANBUS Documentation for information on finding the CAN UUID of your devices.","title":"Katapult's flashtool.py"},{"location":"Bootloader_Entry.html#entering-the-bootloader","text":"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","title":"Entering the bootloader"},{"location":"Bootloader_Entry.html#notes","text":"","title":"Notes"},{"location":"Bootloader_Entry.html#stm32-dfu-warning","text":"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.","title":"STM32 DFU Warning"},{"location":"Bootloaders.html","text":"Bootloaders \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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) \u00b6 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) \u00b6 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) \u00b6 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) \u00b6 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) \u00b6 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) \u00b6 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 \u00b6 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 \u00b6 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: 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 \u00b6 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 \u00b6 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 flash_can.py utility supplied in the lib/canboot 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) \u00b6 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) \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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.","title":"Bootloaders"},{"location":"Bootloaders.html#bootloaders","text":"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.","title":"Bootloaders"},{"location":"Bootloaders.html#avr-micro-controllers","text":"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).","title":"AVR micro-controllers"},{"location":"Bootloaders.html#atmega2560","text":"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","title":"Atmega2560"},{"location":"Bootloaders.html#atmega1280","text":"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","title":"Atmega1280"},{"location":"Bootloaders.html#atmega1284p","text":"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","title":"Atmega1284p"},{"location":"Bootloaders.html#at90usb1286","text":"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","title":"At90usb1286"},{"location":"Bootloaders.html#atmega168","text":"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","title":"Atmega168"},{"location":"Bootloaders.html#sam3-micro-controllers-arduino-due","text":"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","title":"SAM3 micro-controllers (Arduino Due)"},{"location":"Bootloaders.html#sam4-micro-controllers-duet-wifi","text":"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","title":"SAM4 micro-controllers (Duet Wifi)"},{"location":"Bootloaders.html#samdc21-micro-controllers-duet3d-toolboard-1lc","text":"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","title":"SAMDC21 micro-controllers (Duet3D Toolboard 1LC)"},{"location":"Bootloaders.html#samd21-micro-controllers-arduino-zero","text":"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","title":"SAMD21 micro-controllers (Arduino Zero)"},{"location":"Bootloaders.html#samd51-micro-controllers-adafruit-metro-m4-and-similar","text":"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","title":"SAMD51 micro-controllers (Adafruit Metro-M4 and similar)"},{"location":"Bootloaders.html#stm32f103-micro-controllers-blue-pill-devices","text":"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.","title":"STM32F103 micro-controllers (Blue Pill devices)"},{"location":"Bootloaders.html#stm32f103-with-stm32duino-bootloader","text":"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.","title":"STM32F103 with stm32duino bootloader"},{"location":"Bootloaders.html#stm32f103-with-hid-bootloader","text":"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: 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.","title":"STM32F103 with HID bootloader"},{"location":"Bootloaders.html#stm32f103stm32f072-with-msc-bootloader","text":"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.","title":"STM32F103/STM32F072 with MSC bootloader"},{"location":"Bootloaders.html#stm32f103stm32f0x2-with-canboot-bootloader","text":"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 flash_can.py utility supplied in the lib/canboot 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.","title":"STM32F103/STM32F0x2 with CanBoot bootloader"},{"location":"Bootloaders.html#stm32f4-micro-controllers-skr-pro-11","text":"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.","title":"STM32F4 micro-controllers (SKR Pro 1.1)"},{"location":"Bootloaders.html#lpc176x-micro-controllers-smoothieboards","text":"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.","title":"LPC176x micro-controllers (Smoothieboards)"},{"location":"Bootloaders.html#running-openocd-on-the-raspberry-pi","text":"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","title":"Running OpenOCD on the Raspberry PI"},{"location":"Bootloaders.html#configure-openocd","text":"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","title":"Configure OpenOCD"},{"location":"Bootloaders.html#wire-the-raspberry-pi-to-the-target-chip","text":"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.","title":"Wire the Raspberry Pi to the target chip"},{"location":"Bootloaders.html#run-openocd","text":"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.)","title":"Run OpenOCD"},{"location":"Bootloaders.html#openocd-and-gdb","text":"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.","title":"OpenOCD and gdb"},{"location":"CANBUS.html","text":"CANBUS \u00b6 This document describes Klipper's CAN bus support. Device Hardware \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 See the CAN bus troubleshooting document.","title":"CANBUS"},{"location":"CANBUS.html#canbus","text":"This document describes Klipper's CAN bus support.","title":"CANBUS"},{"location":"CANBUS.html#device-hardware","text":"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.","title":"Device Hardware"},{"location":"CANBUS.html#host-hardware","text":"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","title":"Host Hardware"},{"location":"CANBUS.html#terminating-resistors","text":"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.","title":"Terminating Resistors"},{"location":"CANBUS.html#finding-the-canbus_uuid-for-new-micro-controllers","text":"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.","title":"Finding the canbus_uuid for new micro-controllers"},{"location":"CANBUS.html#configuring-klipper","text":"Update the Klipper mcu configuration to use the CAN bus to communicate with the device - for example: [mcu my_can_mcu] canbus_uuid: 11aa22bb33cc","title":"Configuring Klipper"},{"location":"CANBUS.html#usb-to-can-bus-bridge-mode","text":"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 .","title":"USB to CAN bus bridge mode"},{"location":"CANBUS.html#tips-for-troubleshooting","text":"See the CAN bus troubleshooting document.","title":"Tips for troubleshooting"},{"location":"CANBUS_Troubleshooting.html","text":"CANBUS Troubleshooting \u00b6 This document provides information on troubleshooting communication issues when using Klipper with CAN bus . Verify CAN bus wiring \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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.","title":"CANBUS Troubleshooting"},{"location":"CANBUS_Troubleshooting.html#canbus-troubleshooting","text":"This document provides information on troubleshooting communication issues when using Klipper with CAN bus .","title":"CANBUS Troubleshooting"},{"location":"CANBUS_Troubleshooting.html#verify-can-bus-wiring","text":"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.","title":"Verify CAN bus wiring"},{"location":"CANBUS_Troubleshooting.html#check-for-incrementing-bytes_invalid-counter","text":"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 .","title":"Check for incrementing bytes_invalid counter"},{"location":"CANBUS_Troubleshooting.html#use-an-appropriate-txqueuelen-setting","text":"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.","title":"Use an appropriate txqueuelen setting"},{"location":"CANBUS_Troubleshooting.html#use-canbus_querypy-only-to-identify-nodes-never-previously-seen","text":"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.","title":"Use canbus_query.py only to identify nodes never previously seen"},{"location":"CANBUS_Troubleshooting.html#obtaining-candump-logs","text":"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 .","title":"Obtaining candump logs"},{"location":"CANBUS_Troubleshooting.html#parsing-klipper-messages-in-a-candump-log","text":"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.","title":"Parsing Klipper messages in a candump log"},{"location":"CANBUS_Troubleshooting.html#using-a-logic-analyzer-on-the-canbus-wiring","text":"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.","title":"Using a logic analyzer on the canbus wiring"},{"location":"CANBUS_protocol.html","text":"CANBUS protocol \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 The RESP_NEED_NODEID message format is: <1-byte message_id = 0x20><6-byte canbus_uuid><1-byte set_klipper_nodeid = 0x01> Data Packets \u00b6 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 ).","title":"CANBUS protocol"},{"location":"CANBUS_protocol.html#canbus-protocol","text":"This document describes the protocol Klipper uses to communicate over CAN bus . See CANBUS.md for information on configuring Klipper with CAN bus.","title":"CANBUS protocol"},{"location":"CANBUS_protocol.html#micro-controller-id-assignment","text":"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.","title":"Micro-controller id assignment"},{"location":"CANBUS_protocol.html#admin-messages","text":"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\".","title":"Admin messages"},{"location":"CANBUS_protocol.html#cmd_query_unassigned-message","text":"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>","title":"CMD_QUERY_UNASSIGNED message"},{"location":"CANBUS_protocol.html#cmd_set_klipper_nodeid-message","text":"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>","title":"CMD_SET_KLIPPER_NODEID message"},{"location":"CANBUS_protocol.html#resp_need_nodeid-message","text":"The RESP_NEED_NODEID message format is: <1-byte message_id = 0x20><6-byte canbus_uuid><1-byte set_klipper_nodeid = 0x01>","title":"RESP_NEED_NODEID message"},{"location":"CANBUS_protocol.html#data-packets","text":"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 ).","title":"Data Packets"},{"location":"CONTRIBUTING.html","text":"Contributing to Klipper \u00b6 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 \u00b6 Contributions to Klipper generally follow a high-level process: A submitter starts by creating a GitHub Pull Request when a submission is ready for widespread deployment. 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. 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 \u00b6 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: 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\". 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. 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 . 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 . 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 . 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 \u00b6 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 \u00b6 The Klipper \"reviewers\" are: Name GitHub Id Areas of interest Dmitry Butyugin @dmbutyugin Input shaping, resonance testing, kinematics Eric Callahan @Arksine Bed leveling, MCU flashing James Hartley @JamesH1978 Configuration files Kevin O'Connor @KevinOConnor Core motion system, Micro-controller code 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: Name GitHub name Kevin O'Connor @KevinOConnor Format of commit messages \u00b6 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 <myemail@example.org> 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 \u00b6 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: update klipper-translations repository active_translations 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: Currently, there isn't a method for correctly translating pictures in the documentation It is impossible to translate titles in mkdocs.yml.","title":"Contributing to Klipper"},{"location":"CONTRIBUTING.html#contributing-to-klipper","text":"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.","title":"Contributing to Klipper"},{"location":"CONTRIBUTING.html#overview-of-contribution-process","text":"Contributions to Klipper generally follow a high-level process: A submitter starts by creating a GitHub Pull Request when a submission is ready for widespread deployment. 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. 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.","title":"Overview of Contribution Process"},{"location":"CONTRIBUTING.html#what-to-expect-in-a-review","text":"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: 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\". 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. 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 . 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 . 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 . 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.","title":"What to expect in a review"},{"location":"CONTRIBUTING.html#helping-with-reviews","text":"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\".","title":"Helping with reviews"},{"location":"CONTRIBUTING.html#reviewers","text":"The Klipper \"reviewers\" are: Name GitHub Id Areas of interest Dmitry Butyugin @dmbutyugin Input shaping, resonance testing, kinematics Eric Callahan @Arksine Bed leveling, MCU flashing James Hartley @JamesH1978 Configuration files Kevin O'Connor @KevinOConnor Core motion system, Micro-controller code 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: Name GitHub name Kevin O'Connor @KevinOConnor","title":"Reviewers"},{"location":"CONTRIBUTING.html#format-of-commit-messages","text":"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 <myemail@example.org> 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.","title":"Format of commit messages"},{"location":"CONTRIBUTING.html#contributing-to-klipper-translations","text":"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: update klipper-translations repository active_translations 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: Currently, there isn't a method for correctly translating pictures in the documentation It is impossible to translate titles in mkdocs.yml.","title":"Contributing to Klipper Translations"},{"location":"Code_Overview.html","text":"Code overview \u00b6 This document describes the overall code layout and major code flow of Klipper. Directory Layout \u00b6 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 \u00b6 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 \u00b6 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 entirely in the klippy/queuelogger.py code and its operation is generally 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 operation is generally 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/stepcompress.c C code and its operation is generally not exposed to the Python code. Code flow of a move command \u00b6 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() -> LookAheadQueue.flush() -> Move.set_junction() -> ToolHead._process_moves() -> 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_moves() is called, 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_moves() -> 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. Klipper uses an iterative solver to generate the step times for each stepper. For efficiency reasons, the stepper pulse times are generated in C code in a thread per stepper motor. The threads are notified of new activity by the motion_queuing module (klippy/extras/motion_queuing.py): PrinterMotionQueuing._flush_handler() -> PrinterMotionQueuing._advance_move_time() -> steppersync_start_gen_steps() -> stepcompress_start_gen_steps() . The step times are then generated from that thread (klippy/chelper/stepcompress.c): sc_background_thread() -> stepcompress_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 stepcompress.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 \u00b6 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 \u00b6 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: Start by studying the \" code flow of a move \" section and the Kinematics document . 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. 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. 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. 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. 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 \u00b6 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: 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. 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. 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. 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. Add support for timer dispatch from hardware interrupts. See Klipper commit 970831ee as an example of steps 1-5 done for the LPC176x architecture. Bring up basic GPIO input and output support. See Klipper commit c78b9076 as an example of this. Bring up additional peripherals - for example see Klipper commit 65613aed , c812a40a , and c381d03a . Create a sample Klipper config file in the config/ directory. Test the micro-controller with the main klippy.py program. Consider adding build test cases in the test/ directory. Additional coding tips: 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. 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 \u00b6 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 \u00b6 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.","title":"Code overview"},{"location":"Code_Overview.html#code-overview","text":"This document describes the overall code layout and major code flow of Klipper.","title":"Code overview"},{"location":"Code_Overview.html#directory-layout","text":"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.","title":"Directory Layout"},{"location":"Code_Overview.html#micro-controller-code-flow","text":"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.","title":"Micro-controller code flow"},{"location":"Code_Overview.html#klippy-code-overview","text":"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 entirely in the klippy/queuelogger.py code and its operation is generally 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 operation is generally 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/stepcompress.c C code and its operation is generally not exposed to the Python code.","title":"Klippy code overview"},{"location":"Code_Overview.html#code-flow-of-a-move-command","text":"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() -> LookAheadQueue.flush() -> Move.set_junction() -> ToolHead._process_moves() -> 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_moves() is called, 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_moves() -> 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. Klipper uses an iterative solver to generate the step times for each stepper. For efficiency reasons, the stepper pulse times are generated in C code in a thread per stepper motor. The threads are notified of new activity by the motion_queuing module (klippy/extras/motion_queuing.py): PrinterMotionQueuing._flush_handler() -> PrinterMotionQueuing._advance_move_time() -> steppersync_start_gen_steps() -> stepcompress_start_gen_steps() . The step times are then generated from that thread (klippy/chelper/stepcompress.c): sc_background_thread() -> stepcompress_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 stepcompress.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.","title":"Code flow of a move command"},{"location":"Code_Overview.html#adding-a-host-module","text":"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.","title":"Adding a host module"},{"location":"Code_Overview.html#adding-new-kinematics","text":"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: Start by studying the \" code flow of a move \" section and the Kinematics document . 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. 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. 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. 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. 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.","title":"Adding new kinematics"},{"location":"Code_Overview.html#porting-to-a-new-micro-controller","text":"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: 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. 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. 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. 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. Add support for timer dispatch from hardware interrupts. See Klipper commit 970831ee as an example of steps 1-5 done for the LPC176x architecture. Bring up basic GPIO input and output support. See Klipper commit c78b9076 as an example of this. Bring up additional peripherals - for example see Klipper commit 65613aed , c812a40a , and c381d03a . Create a sample Klipper config file in the config/ directory. Test the micro-controller with the main klippy.py program. Consider adding build test cases in the test/ directory. Additional coding tips: 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. 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.","title":"Porting to a new micro-controller"},{"location":"Code_Overview.html#coordinate-systems","text":"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.","title":"Coordinate Systems"},{"location":"Code_Overview.html#time","text":"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.","title":"Time"},{"location":"Command_Templates.html","text":"Commands templates \u00b6 This document provides information on implementing G-Code command sequences in gcode_macro (and similar) config sections. G-Code Macro Naming \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 <update> . When <force> is set True then it will also stop editing. Default value is False. When <update> 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 \u00b6 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}","title":"Commands templates"},{"location":"Command_Templates.html#commands-templates","text":"This document provides information on implementing G-Code command sequences in gcode_macro (and similar) config sections.","title":"Commands templates"},{"location":"Command_Templates.html#g-code-macro-naming","text":"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).","title":"G-Code Macro Naming"},{"location":"Command_Templates.html#formatting-of-g-code-in-the-config","text":"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.","title":"Formatting of G-Code in the config"},{"location":"Command_Templates.html#add-a-description-to-your-macro","text":"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.","title":"Add a description to your macro"},{"location":"Command_Templates.html#saverestore-state-for-g-code-moves","text":"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.","title":"Save/Restore state for G-Code moves"},{"location":"Command_Templates.html#template-expansion","text":"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","title":"Template expansion"},{"location":"Command_Templates.html#macro-parameters","text":"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}","title":"Macro parameters"},{"location":"Command_Templates.html#the-rawparams-variable","text":"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 .","title":"The \"rawparams\" variable"},{"location":"Command_Templates.html#the-printer-variable","text":"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}","title":"The \"printer\" Variable"},{"location":"Command_Templates.html#actions","text":"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\")","title":"Actions"},{"location":"Command_Templates.html#variables","text":"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.","title":"Variables"},{"location":"Command_Templates.html#delayed-gcodes","text":"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","title":"Delayed Gcodes"},{"location":"Command_Templates.html#menu-templates","text":"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 <update> . When <force> is set True then it will also stop editing. Default value is False. When <update> 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.","title":"Menu templates"},{"location":"Command_Templates.html#save-variables-to-disk","text":"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}","title":"Save Variables to disk"},{"location":"Config_Changes.html","text":"Configuration Changes \u00b6 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 \u00b6 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","title":"Configuration Changes"},{"location":"Config_Changes.html#configuration-changes","text":"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.","title":"Configuration Changes"},{"location":"Config_Changes.html#changes","text":"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","title":"Changes"},{"location":"Config_Reference.html","text":"Configuration reference \u00b6 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 \u00b6 Format of micro-controller pin names \u00b6 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] \u00b6 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] \u00b6 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 \u00b6 [printer] \u00b6 The printer section controls high level printer settings. [printer] kinematics: # The type of printer in use. This option may be one of: cartesian, # corexy, corexz, hybrid_corexy, hybrid_corexz, generic_cartesian, # rotary_delta, delta, deltesian, polar, winch, or none. # This parameter must be specified. max_velocity: # Maximum velocity (in mm/s) of the toolhead (relative to the # print). This value may be changed at runtime using the # SET_VELOCITY_LIMIT command. This parameter must be specified. max_accel: # Maximum acceleration (in mm/s^2) of the toolhead (relative to the # print). Although this parameter is described as a \"maximum\" # acceleration, in practice most moves that accelerate or decelerate # will do so at the rate specified here. The value specified here # may be changed at runtime using the SET_VELOCITY_LIMIT command. # This parameter must be specified. #minimum_cruise_ratio: 0.5 # Most moves will accelerate to a cruising speed, travel at that # cruising speed, and then decelerate. However, some moves that # travel a short distance could nominally accelerate and then # immediately decelerate. This option reduces the top speed of these # moves to ensure there is always a minimum distance traveled at a # cruising speed. That is, it enforces a minimum distance traveled # at cruising speed relative to the total distance traveled. It is # intended to reduce the top speed of short zigzag moves (and thus # reduce printer vibration from these moves). For example, a # minimum_cruise_ratio of 0.5 would ensure that a standalone 1.5mm # move would have a minimum cruising distance of 0.75mm. Specify a # ratio of 0.0 to disable this feature (there would be no minimum # cruising distance enforced between acceleration and deceleration). # The value specified here may be changed at runtime using the # SET_VELOCITY_LIMIT command. The default is 0.5. #square_corner_velocity: 5.0 # The maximum velocity (in mm/s) that the toolhead may travel a 90 # degree corner at. A non-zero value can reduce changes in extruder # flow rates by enabling instantaneous velocity changes of the # toolhead during cornering. This value configures the internal # centripetal velocity cornering algorithm; corners with angles # larger than 90 degrees will have a higher cornering velocity while # corners with angles less than 90 degrees will have a lower # cornering velocity. If this is set to zero then the toolhead will # decelerate to zero at each corner. The value specified here may be # changed at runtime using the SET_VELOCITY_LIMIT command. The # default is 5mm/s. [stepper] \u00b6 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. [stepper_x] step_pin: # Step GPIO pin (triggered high). This parameter must be provided. dir_pin: # Direction GPIO pin (high indicates positive direction). This # parameter must be provided. enable_pin: # Enable pin (default is enable high; use ! to indicate enable # low). If this parameter is not provided then the stepper motor # driver must always be enabled. rotation_distance: # Distance (in mm) that the axis travels with one full rotation of # the stepper motor (or final gear if gear_ratio is specified). # This parameter must be provided. microsteps: # The number of microsteps the stepper motor driver uses. This # parameter must be provided. #full_steps_per_rotation: 200 # The number of full steps for one rotation of the stepper motor. # Set this to 200 for a 1.8 degree stepper motor or set to 400 for a # 0.9 degree motor. The default is 200. #gear_ratio: # The gear ratio if the stepper motor is connected to the axis via a # gearbox. For example, one may specify \"5:1\" if a 5 to 1 gearbox is # in use. If the axis has multiple gearboxes one may specify a comma # separated list of gear ratios (for example, \"57:11, 2:1\"). If a # gear_ratio is specified then rotation_distance specifies the # distance the axis travels for one full rotation of the final gear. # The default is to not use a gear ratio. #step_pulse_duration: # The minimum time between the step pulse signal edge and the # following \"unstep\" signal edge. This is also used to set the # minimum time between a step pulse and a direction change signal. # The default is 0.000000100 (100ns) for TMC steppers that are # configured in UART or SPI mode, and the default is 0.000002 (which # is 2us) for all other steppers. endstop_pin: # Endstop switch detection pin. If this endstop pin is on a # different mcu than the stepper motor then it enables \"multi-mcu # homing\". This parameter must be provided for the X, Y, and Z # steppers on cartesian style printers. #position_min: 0 # Minimum valid distance (in mm) the user may command the stepper to # move to. The default is 0mm. position_endstop: # Location of the endstop (in mm). This parameter must be provided # for the X, Y, and Z steppers on cartesian style printers. position_max: # Maximum valid distance (in mm) the user may command the stepper to # move to. This parameter must be provided for the X, Y, and Z # steppers on cartesian style printers. #homing_speed: 5.0 # Maximum velocity (in mm/s) of the stepper when homing. The default # is 5mm/s. #homing_retract_dist: 5.0 # Distance to backoff (in mm) before homing a second time during # homing. Set this to zero to disable the second home. The default # is 5mm. #homing_retract_speed: # Speed to use on the retract move after homing in case this should # be different from the homing speed, which is the default for this # parameter #second_homing_speed: # Velocity (in mm/s) of the stepper when performing the second home. # The default is homing_speed/2. #homing_positive_dir: # If true, homing will cause the stepper to move in a positive # direction (away from zero); if false, home towards zero. It is # better to use the default than to specify this parameter. The # default is true if position_endstop is near position_max and false # if near position_min. Cartesian Kinematics \u00b6 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 \u00b6 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. [printer] kinematics: delta max_z_velocity: # For delta printers this limits the maximum velocity (in mm/s) of # moves with z axis movement. This setting can be used to reduce the # maximum speed of up/down moves (which require a higher step rate # than other moves on a delta printer). 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. Setting this may be useful if the printer can reach higher # acceleration on XY moves than Z moves (eg, when using input shaper). # The default is to use max_accel for max_z_accel. #minimum_z_position: 0 # The minimum Z position that the user may command the head to move # to. The default is 0. delta_radius: # Radius (in mm) of the horizontal circle formed by the three linear # axis towers. This parameter may also be calculated as: # delta_radius = smooth_rod_offset - effector_offset - carriage_offset # This parameter must be provided. #print_radius: # The radius (in mm) of valid toolhead XY coordinates. One may use # this setting to customize the range checking of toolhead moves. If # a large value is specified here then it may be possible to command # the toolhead into a collision with a tower. The default is to use # delta_radius for print_radius (which would normally prevent a # tower collision). # The stepper_a section describes the stepper controlling the front # left tower (at 210 degrees). This section also controls the homing # parameters (homing_speed, homing_retract_dist) for all towers. [stepper_a] position_endstop: # Distance (in mm) between the nozzle and the bed when the nozzle is # in the center of the build area and the endstop triggers. This # parameter must be provided for stepper_a; for stepper_b and # stepper_c this parameter defaults to the value specified for # stepper_a. arm_length: # Length (in mm) of the diagonal rod that connects this tower to the # print head. This parameter must be provided for stepper_a; for # stepper_b and stepper_c this parameter defaults to the value # specified for stepper_a. #angle: # This option specifies the angle (in degrees) that the tower is # at. The default is 210 for stepper_a, 330 for stepper_b, and 90 # for stepper_c. # The stepper_b section describes the stepper controlling the front # right tower (at 330 degrees). [stepper_b] # The stepper_c section describes the stepper controlling the rear # tower (at 90 degrees). [stepper_c] # The delta_calibrate section enables a DELTA_CALIBRATE extended # g-code command that can calibrate the tower endstop positions and # angles. [delta_calibrate] radius: # Radius (in mm) of the area that may be probed. This is the radius # of nozzle coordinates to be probed; if using an automatic probe # with an XY offset then choose a radius small enough so that the # probe always fits over the bed. This parameter must be provided. #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. Deltesian Kinematics \u00b6 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. [printer] kinematics: deltesian max_z_velocity: # For deltesian printers, this limits the maximum velocity (in mm/s) of # moves with z axis movement. This setting can be used to reduce the # maximum speed of up/down moves (which require a higher step rate # than other moves on a deltesian printer). 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. Setting this may be useful if the printer can reach higher # acceleration on XY moves than Z moves (eg, when using input shaper). # The default is to use max_accel for max_z_accel. #minimum_z_position: 0 # The minimum Z position that the user may command the head to move # to. The default is 0. #min_angle: 5 # This represents the minimum angle (in degrees) relative to horizontal # that the deltesian arms are allowed to achieve. This parameter is # intended to restrict the arms from becoming completely horizontal, # which would risk accidental inversion of the XZ axis. The default is 5. #print_width: # The distance (in mm) of valid toolhead X coordinates. One may use # this setting to customize the range checking of toolhead moves. If # a large value is specified here then it may be possible to command # the toolhead into a collision with a tower. This setting usually # corresponds to bed width (in mm). #slow_ratio: 3 # The ratio used to limit velocity and acceleration on moves near the # extremes of the X axis. If vertical distance divided by horizontal # distance exceeds the value of slow_ratio, then velocity and # acceleration are limited to half their nominal values. If vertical # distance divided by horizontal distance exceeds twice the value of # the slow_ratio, then velocity and acceleration are limited to one # quarter of their nominal values. The default is 3. # The stepper_left section is used to describe the stepper controlling # the left tower. This section also controls the homing parameters # (homing_speed, homing_retract_dist) for all towers. [stepper_left] position_endstop: # Distance (in mm) between the nozzle and the bed when the nozzle is # in the center of the build area and the endstops are triggered. This # parameter must be provided for stepper_left; for stepper_right this # parameter defaults to the value specified for stepper_left. arm_length: # Length (in mm) of the diagonal rod that connects the tower carriage to # the print head. This parameter must be provided for stepper_left; for # stepper_right, this parameter defaults to the value specified for # stepper_left. arm_x_length: # Horizontal distance between the print head and the tower when the # printers is homed. This parameter must be provided for stepper_left; # for stepper_right, this parameter defaults to the value specified for # stepper_left. # The stepper_right section is used to describe the stepper controlling the # right tower. [stepper_right] # The stepper_y section is used to describe the stepper controlling # the Y axis in a deltesian robot. [stepper_y] CoreXY Kinematics \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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. # 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 \u00b6 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. [printer] kinematics: rotary_delta max_z_velocity: # For delta printers this limits the maximum velocity (in mm/s) of # moves with z axis movement. This setting can be used to reduce the # maximum speed of up/down moves (which require a higher step rate # than other moves on a delta printer). The default is to use # max_velocity for max_z_velocity. #minimum_z_position: 0 # The minimum Z position that the user may command the head to move # to. The default is 0. shoulder_radius: # Radius (in mm) of the horizontal circle formed by the three # shoulder joints, minus the radius of the circle formed by the # effector joints. This parameter may also be calculated as: # shoulder_radius = (delta_f - delta_e) / sqrt(12) # This parameter must be provided. shoulder_height: # Distance (in mm) of the shoulder joints from the bed, minus the # effector toolhead height. This parameter must be provided. # The stepper_a section describes the stepper controlling the rear # right arm (at 30 degrees). This section also controls the homing # parameters (homing_speed, homing_retract_dist) for all arms. [stepper_a] gear_ratio: # A gear_ratio must be specified and rotation_distance may not be # specified. For example, if the arm has an 80 toothed pulley driven # by a pulley with 16 teeth, which is in turn connected to a 60 # toothed pulley driven by a stepper with a 16 toothed pulley, then # one would specify a gear ratio of \"80:16, 60:16\". This parameter # must be provided. position_endstop: # Distance (in mm) between the nozzle and the bed when the nozzle is # in the center of the build area and the endstop triggers. This # parameter must be provided for stepper_a; for stepper_b and # stepper_c this parameter defaults to the value specified for # stepper_a. upper_arm_length: # Length (in mm) of the arm connecting the \"shoulder joint\" to the # \"elbow joint\". This parameter must be provided for stepper_a; for # stepper_b and stepper_c this parameter defaults to the value # specified for stepper_a. lower_arm_length: # Length (in mm) of the arm connecting the \"elbow joint\" to the # \"effector joint\". This parameter must be provided for stepper_a; # for stepper_b and stepper_c this parameter defaults to the value # specified for stepper_a. #angle: # This option specifies the angle (in degrees) that the arm is at. # The default is 30 for stepper_a, 150 for stepper_b, and 270 for # stepper_c. # The stepper_b section describes the stepper controlling the rear # left arm (at 150 degrees). [stepper_b] # The stepper_c section describes the stepper controlling the front # arm (at 270 degrees). [stepper_c] # The delta_calibrate section enables a DELTA_CALIBRATE extended # g-code command that can calibrate the shoulder endstop positions. [delta_calibrate] radius: # Radius (in mm) of the area that may be probed. This is the radius # of nozzle coordinates to be probed; if using an automatic probe # with an XY offset then choose a radius small enough so that the # probe always fits over the bed. This parameter must be provided. #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. Cable winch Kinematics \u00b6 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 \u00b6 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 the following three carriages: [carriage x] , [carriage y] , and [carriage z] , e.g. [carriage x] endstop_pin: # Endstop switch detection pin. If this endstop pin is on a # different mcu than the stepper motor(s) moving this carriage, # then it enables \"multi-mcu homing\". This parameter must be provided. #position_min: 0 # Minimum valid distance (in mm) the user may command the carriage to # move to. The default is 0mm. position_endstop: # Location of the endstop (in mm). This parameter must be provided. position_max: # Maximum valid distance (in mm) the user may command the stepper to # move to. This parameter must be provided. #homing_speed: 5.0 # Maximum velocity (in mm/s) of the carriage when homing. The default # is 5mm/s. #homing_retract_dist: 5.0 # Distance to backoff (in mm) before homing a second time during # homing. Set this to zero to disable the second home. The default # is 5mm. #homing_retract_speed: # Speed to use on the retract move after homing in case this should # be different from the homing speed, which is the default for this # parameter #second_homing_speed: # Velocity (in mm/s) of the carriage when performing the second home. # The default is homing_speed/2. #homing_positive_dir: # If true, homing will cause the carriage to move in a positive # direction (away from zero); if false, home towards zero. It is # better to use the default than to specify this parameter. The # default is true if position_endstop is near position_max and false # if near position_min. 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. x, x+y, y-0.5*z, x-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, x+y indicates that the motion of the stepper in the positive direction by the distance d moves the carriages x and y by the same distance d in the positive direction, while x-0.5*y means the motion of the stepper in the positive direction by the distance d moves the carriage x by the distance d in the positive direction, but the 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 x] endstop_pin: ... ... [carriage y] endstop_pin: ... ... [stepper a0] carriages: x-y step_pin: ... dir_pin: ... enable_pin: ... rotation_distance: ... ... [stepper a1] carriages: x-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 beam, 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 y1] primary_carriage: y endstop_pin: ... [stepper sy1] carriages: 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 \u00b6 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 \u00b6 [extruder] \u00b6 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. [extruder] step_pin: dir_pin: enable_pin: microsteps: rotation_distance: #full_steps_per_rotation: #gear_ratio: # See the \"stepper\" section for a description of the above # parameters. If none of the above parameters are specified then no # stepper will be associated with the nozzle hotend (though a # SYNC_EXTRUDER_MOTION command may associate one at run-time). nozzle_diameter: # Diameter of the nozzle orifice (in mm). This parameter must be # provided. filament_diameter: # The nominal diameter of the raw filament (in mm) as it enters the # extruder. This parameter must be provided. #max_extrude_cross_section: # Maximum area (in mm^2) of an extrusion cross section (eg, # extrusion width multiplied by layer height). This setting prevents # excessive amounts of extrusion during relatively small XY moves. # If a move requests an extrusion rate that would exceed this value # it will cause an error to be returned. The default is: 4.0 * # nozzle_diameter^2 #instantaneous_corner_velocity: 1.000 # The maximum instantaneous velocity change (in mm/s) of the # extruder during the junction of two moves. The default is 1mm/s. #max_extrude_only_distance: 50.0 # Maximum length (in mm of raw filament) that a retraction or # extrude-only move may have. If a retraction or extrude-only move # requests a distance greater than this value it will cause an error # to be returned. The default is 50mm. #max_extrude_only_velocity: #max_extrude_only_accel: # Maximum velocity (in mm/s) and acceleration (in mm/s^2) of the # extruder motor for retractions and extrude-only moves. These # settings do not have any impact on normal printing moves. If not # specified then they are calculated to match the limit an XY # printing move with a cross section of 4.0*nozzle_diameter^2 would # have. #pressure_advance: 0.0 # The amount of raw filament to push into the extruder during # extruder acceleration. An equal amount of filament is retracted # during deceleration. It is measured in millimeters per # millimeter/second. The default is 0, which disables pressure # advance. #pressure_advance_smooth_time: 0.040 # A time range (in seconds) to use when calculating the average # extruder velocity for pressure advance. A larger value results in # smoother extruder movements. This parameter may not exceed 200ms. # This setting only applies if pressure_advance is non-zero. The # default is 0.040 (40 milliseconds). # # The remaining variables describe the extruder heater. heater_pin: # PWM output pin controlling the heater. This parameter must be # provided. #max_power: 1.0 # The maximum power (expressed as a value from 0.0 to 1.0) that the # heater_pin may be set to. The value 1.0 allows the pin to be set # fully enabled for extended periods, while a value of 0.5 would # allow the pin to be enabled for no more than half the time. This # setting may be used to limit the total power output (over extended # periods) to the heater. The default is 1.0. sensor_type: # Type of sensor - common thermistors are \"EPCOS 100K B57560G104F\", # \"ATC Semitec 104GT-2\", \"ATC Semitec 104NT-4-R025H42G\", \"Generic # 3950\",\"Honeywell 100K 135-104LAG-J01\", \"NTC 100K MGB18-104F39050L32\", # \"SliceEngineering 450\", and \"TDK NTCG104LH104JT1\". See the # \"Temperature sensors\" section for other sensors. This parameter # must be provided. sensor_pin: # Analog input pin connected to the sensor. This parameter must be # provided. #pullup_resistor: 4700 # The resistance (in ohms) of the pullup attached to the thermistor. # This parameter is only valid when the sensor is a thermistor. The # default is 4700 ohms. #smooth_time: 1.0 # A time value (in seconds) over which temperature measurements will # be smoothed to reduce the impact of measurement noise. The default # is 1 seconds. control: # Control algorithm (either pid or watermark). This parameter must # be provided. pid_Kp: pid_Ki: pid_Kd: # The proportional (pid_Kp), integral (pid_Ki), and derivative # (pid_Kd) settings for the PID feedback control system. Klipper # evaluates the PID settings with the following general formula: # heater_pwm = (Kp*error + Ki*integral(error) - Kd*derivative(error)) / 255 # Where \"error\" is \"requested_temperature - measured_temperature\" # and \"heater_pwm\" is the requested heating rate with 0.0 being full # off and 1.0 being full on. Consider using the PID_CALIBRATE # command to obtain these parameters. The pid_Kp, pid_Ki, and pid_Kd # parameters must be provided for PID heaters. #max_delta: 2.0 # On 'watermark' controlled heaters this is the number of degrees in # Celsius above the target temperature before disabling the heater # as well as the number of degrees below the target before # re-enabling the heater. The default is 2 degrees Celsius. #pwm_cycle_time: 0.100 # Time in seconds for each software PWM cycle of the heater. It is # not recommended to set this unless there is an electrical # requirement to switch the heater faster than 10 times a second. # The default is 0.100 seconds. #min_extrude_temp: 170 # The minimum temperature (in Celsius) at which extruder move # commands may be issued. The default is 170 Celsius. min_temp: max_temp: # The maximum range of valid temperatures (in Celsius) that the # heater must remain within. This controls a safety feature # implemented in the micro-controller code - should the measured # temperature ever fall outside this range then the micro-controller # will go into a shutdown state. This check can help detect some # heater and sensor hardware failures. Set this range just wide # enough so that reasonable temperatures do not result in an error. # These parameters must be provided. [heater_bed] \u00b6 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 \u00b6 [bed_mesh] \u00b6 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 [bed_mesh] #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. #mesh_radius: # Defines the radius of the mesh to probe for round beds. Note that # the radius is relative to the coordinate specified by the # mesh_origin option. This parameter must be provided for round beds # and omitted for rectangular beds. #mesh_origin: # Defines the center X, Y coordinate of the mesh for round beds. This # coordinate is relative to the probe's location. It may be useful # to adjust the mesh_origin in an effort to maximize the size of the # mesh radius. Default is 0, 0. This parameter must be omitted for # rectangular beds. #mesh_min: # Defines the minimum X, Y coordinate of the mesh for rectangular # beds. This coordinate is relative to the probe's location. This # will be the first point probed, nearest to the origin. This # parameter must be provided for rectangular beds. #mesh_max: # Defines the maximum X, Y coordinate of the mesh for rectangular # beds. Adheres to the same principle as mesh_min, however this will # be the furthest point probed from the bed's origin. This parameter # must be provided for rectangular beds. #probe_count: 3, 3 # For rectangular beds, this is a comma separate pair of integer # values X, Y defining the number of points to probe along each # axis. A single value is also valid, in which case that value will # be applied to both axes. Default is 3, 3. #round_probe_count: 5 # For round beds, this integer value defines the maximum number of # points to probe along each axis. This value must be an odd number. # Default is 5. #fade_start: 1.0 # The gcode z position in which to start phasing out z-adjustment # when fade is enabled. Default is 1.0. #fade_end: 0.0 # The gcode z position in which phasing out completes. When set to a # value below fade_start, fade is disabled. It should be noted that # fade may add unwanted scaling along the z-axis of a print. If a # user wishes to enable fade, a value of 10.0 is recommended. # Default is 0.0, which disables fade. #fade_target: # The z position in which fade should converge. When this value is # set to a non-zero value it must be within the range of z-values in # the mesh. Users that wish to converge to the z homing position # should set this to 0. Default is the average z value of the mesh. #split_delta_z: .025 # The amount of Z difference (in mm) along a move that will trigger # a split. Default is .025. #move_check_distance: 5.0 # The distance (in mm) along a move to check for split_delta_z. # This is also the minimum length that a move can be split. Default # is 5.0. #mesh_pps: 2, 2 # A comma separated pair of integers X, Y defining the number of # points per segment to interpolate in the mesh along each axis. A # \"segment\" can be defined as the space between each probed point. # The user may enter a single value which will be applied to both # axes. Default is 2, 2. #algorithm: lagrange # The interpolation algorithm to use. May be either \"lagrange\" or # \"bicubic\". This option will not affect 3x3 grids, which are forced # to use lagrange sampling. Default is lagrange. #bicubic_tension: .2 # When using the bicubic algorithm the tension parameter above may # be applied to change the amount of slope interpolated. Larger # numbers will increase the amount of slope, which results in more # curvature in the mesh. Default is .2. #zero_reference_position: # An optional X,Y coordinate that specifies the location on the bed # where Z = 0. When this option is specified the mesh will be offset # so that zero Z adjustment occurs at this location. The default is # no zero reference. #faulty_region_1_min: #faulty_region_1_max: # Optional points that define a faulty region. See docs/Bed_Mesh.md # for details on faulty regions. Up to 99 faulty regions may be added. # By default no faulty regions are set. #adaptive_margin: # An optional margin (in mm) to be added around the bed area used by # the defined print objects when generating an adaptive mesh. #scan_overshoot: # 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. [bed_tilt] \u00b6 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] \u00b6 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] \u00b6 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] \u00b6 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. [z_tilt] #z_positions: # A list of X, Y coordinates (one per line; subsequent lines # indented) describing the location of each bed \"pivot point\". The # \"pivot point\" is the point where the bed attaches to the given Z # stepper. It is described using nozzle coordinates (the X, Y position # of the nozzle if it could move directly above the point). The # first entry corresponds to stepper_z, the second to stepper_z1, # the third to stepper_z2, etc. This parameter must be provided. #points: # A list of X, Y coordinates (one per line; subsequent lines # indented) that should be probed during a Z_TILT_ADJUST command. # Specify coordinates of the nozzle and be sure the probe is above # the bed at the given nozzle coordinates. This parameter must be # provided. #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. #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. Note the smallest unit of # change here would be a single step. However if you are probing # more points than steppers then you will likely have a fixed # minimum value for the range of probed points which you can learn # by observing command output. [quad_gantry_level] \u00b6 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] \u00b6 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] \u00b6 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 \u00b6 [safe_z_home] \u00b6 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] \u00b6 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] \u00b6 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 \u00b6 [gcode_macro] \u00b6 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] \u00b6 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] \u00b6 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] \u00b6 Idle timeout. An idle timeout is automatically enabled - add an explicit idle_timeout config section to change the default settings. [idle_timeout] #gcode: # A list of G-Code commands to execute on an idle timeout. See # docs/Command_Templates.md for G-Code format. The default is to run # \"TURN_OFF_HEATERS\" and \"M84\". #timeout: 600 # Idle time (in seconds) to wait before running the above G-Code # commands. The default is 600 seconds. Optional G-Code features \u00b6 [virtual_sdcard] \u00b6 A virtual sdcard may be useful if the host machine is not fast enough to run OctoPrint well. It allows the Klipper host software to directly print gcode files stored in a directory on the host using standard sdcard G-Code commands (eg, M24). [virtual_sdcard] path: # The path of the local directory on the host machine to look for # g-code files. This is a read-only directory (sdcard file writes # are not supported). One may point this to OctoPrint's upload # directory (generally ~/.octoprint/uploads/ ). This parameter must # be provided. #on_error_gcode: # A list of G-Code commands to execute when an error is reported. # See docs/Command_Templates.md for G-Code format. The default is to # run TURN_OFF_HEATERS. [sdcard_loop] \u00b6 Some printers with stage-clearing features, such as a part ejector or a belt printer, can find use in looping sections of the sdcard file. (For example, to print the same part over and over, or repeat the a section of a part for a chain or other repeated pattern). See the command reference for supported commands. See the sample-macros.cfg file for a Marlin compatible M808 G-Code macro. [sdcard_loop] [force_move] \u00b6 Support manually moving stepper motors for diagnostic purposes. Note, using this feature may place the printer in an invalid state - see the command reference for important details. [force_move] #enable_force_move: False # Set to true to enable FORCE_MOVE and SET_KINEMATIC_POSITION # extended G-Code commands. The default is false. [pause_resume] \u00b6 Pause/Resume functionality with support of position capture and restore. See the command reference for more information. [pause_resume] #recover_velocity: 50. # When capture/restore is enabled, the speed at which to return to # the captured position (in mm/s). Default is 50.0 mm/s. [firmware_retraction] \u00b6 Firmware filament retraction. This enables G10 (retract) and G11 (unretract) GCODE commands issued by many slicers. The parameters below provide startup defaults, although the values can be adjusted via the SET_RETRACTION command ), allowing per-filament settings and runtime tuning. [firmware_retraction] #retract_length: 0 # The length of filament (in mm) to retract when G10 is activated, # and to unretract when G11 is activated (but see # unretract_extra_length below). The default is 0 mm. #retract_speed: 20 # The speed of retraction, in mm/s. The default is 20 mm/s. #unretract_extra_length: 0 # The length (in mm) of *additional* filament to add when # unretracting. #unretract_speed: 10 # The speed of unretraction, in mm/s. The default is 10 mm/s. [gcode_arcs] \u00b6 Support for gcode arc (G2/G3) commands. [gcode_arcs] #resolution: 1.0 # An arc will be split into segments. Each segment's length will # equal the resolution in mm set above. Lower values will produce a # finer arc, but also more work for your machine. Arcs smaller than # the configured value will become straight lines. The default is # 1mm. [respond] \u00b6 Enable the \"M118\" and \"RESPOND\" extended commands . [respond] #default_type: echo # Sets the default prefix of the \"M118\" and \"RESPOND\" output to one # of the following: # echo: \"echo: \" (This is the default) # command: \"// \" # error: \"!! \" #default_prefix: echo: # Directly sets the default prefix. If present, this value will # override the \"default_type\". [exclude_object] \u00b6 Enables support to exclude or cancel individual objects during the printing process. See the exclude objects guide and command reference for additional information. See the sample-macros.cfg file for a Marlin/RepRapFirmware compatible M486 G-Code macro. [exclude_object] Resonance compensation \u00b6 [input_shaper] \u00b6 Enables resonance compensation . Also see the command reference . [input_shaper] #shaper_freq_x: 0 # A frequency (in Hz) of the input shaper for X axis. This is # usually a resonance frequency of X axis that the input shaper # should suppress. For more complex shapers, like 2- and 3-hump EI # input shapers, this parameter can be set from different # considerations. The default value is 0, which disables input # shaping for X axis. #shaper_freq_y: 0 # A frequency (in Hz) of the input shaper for Y axis. This is # usually a resonance frequency of Y axis that the input shaper # should suppress. For more complex shapers, like 2- and 3-hump EI # input shapers, this parameter can be set from different # considerations. The default value is 0, which disables input # shaping for Y axis. #shaper_type: mzv # A type of the input shaper to use for both X and Y axes. Supported # shapers are zv, mzv, zvd, ei, 2hump_ei, and 3hump_ei. The default # is mzv input shaper. #shaper_type_x: #shaper_type_y: # If shaper_type is not set, these two parameters can be used to # configure different input shapers for X and Y axes. The same # values are supported as for shaper_type parameter. #damping_ratio_x: 0.1 #damping_ratio_y: 0.1 # Damping ratios of vibrations of X and Y axes used by input shapers # to improve vibration suppression. Default value is 0.1 which is a # good all-round value for most printers. In most circumstances this # parameter requires no tuning and should not be changed. [adxl345] \u00b6 Support for ADXL345 accelerometers. This support allows one to query accelerometer measurements from the sensor. This enables an ACCELEROMETER_MEASURE command (see G-Codes for more information). The default chip name is \"default\", but one may specify an explicit name (eg, [adxl345 my_chip_name]). [adxl345] cs_pin: # The SPI enable pin for the sensor. This parameter must be provided. #spi_speed: 5000000 # The SPI speed (in hz) to use when communicating with the chip. # The default is 5000000. #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #axes_map: x, y, z # The accelerometer axis for each of the printer's X, Y, and Z axes. # This may be useful if the accelerometer is mounted in an # orientation that does not match the printer orientation. For # example, one could set this to \"y, x, z\" to swap the X and Y axes. # It is also possible to negate an axis if the accelerometer # direction is reversed (eg, \"x, z, -y\"). The default is \"x, y, z\". #rate: 3200 # Output data rate for ADXL345. ADXL345 supports the following data # rates: 3200, 1600, 800, 400, 200, 100, 50, and 25. Note that it is # not recommended to change this rate from the default 3200, and # rates below 800 will considerably affect the quality of resonance # measurements. [icm20948] \u00b6 Support for icm20948 accelerometers. [icm20948] #i2c_address: # Default is 104 (0x68). If AD0 is high, it would be 0x69 instead. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: 400000 # See the \"common I2C settings\" section for a description of the # above parameters. The default \"i2c_speed\" is 400000. #axes_map: x, y, z # See the \"adxl345\" section for information on this parameter. [lis2dw] \u00b6 Support for LIS2DW accelerometers. [lis2dw] #cs_pin: # The SPI enable pin for the sensor. This parameter must be provided # if using SPI. #spi_speed: 5000000 # The SPI speed (in hz) to use when communicating with the chip. # The default is 5000000. #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #i2c_address: # Default is 25 (0x19). If SA0 is high, it would be 24 (0x18) instead. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: 400000 # See the \"common I2C settings\" section for a description of the # above parameters. The default \"i2c_speed\" is 400000. #axes_map: x, y, z # See the \"adxl345\" section for information on this parameter. [lis3dh] \u00b6 Support for LIS3DH accelerometers. [lis3dh] #cs_pin: # The SPI enable pin for the sensor. This parameter must be provided # if using SPI. #spi_speed: 5000000 # The SPI speed (in hz) to use when communicating with the chip. # The default is 5000000. #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #i2c_address: # Default is 25 (0x19). If SA0 is high, it would be 24 (0x18) instead. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: 400000 # See the \"common I2C settings\" section for a description of the # above parameters. The default \"i2c_speed\" is 400000. #axes_map: x, y, z # See the \"adxl345\" section for information on this parameter. [mpu9250] \u00b6 Support for MPU-9250, MPU-9255, MPU-6515, MPU-6050, and MPU-6500 accelerometers (one may define any number of sections with an \"mpu9250\" prefix). [mpu9250 my_accelerometer] #i2c_address: # Default is 104 (0x68). If AD0 is high, it would be 0x69 instead. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: 400000 # See the \"common I2C settings\" section for a description of the # above parameters. The default \"i2c_speed\" is 400000. #axes_map: x, y, z # See the \"adxl345\" section for information on this parameter. [resonance_tester] \u00b6 Support for resonance testing and automatic input shaper calibration. In order to use most of the functionality of this module, additional software dependencies must be installed; refer to Measuring Resonances and the command reference for more information. See the Max smoothing section of the measuring resonances guide for more information on max_smoothing parameter and its use. [resonance_tester] #probe_points: # A list of X, Y, Z coordinates of points (one point per line) to test # resonances at. At least one point is required. Make sure that all # points with some safety margin in XY plane (~a few centimeters) # are reachable by the toolhead. #accel_chip: # A name of the accelerometer chip to use for measurements. If # adxl345 chip was defined without an explicit name, this parameter # can simply reference it as \"accel_chip: adxl345\", otherwise an # explicit name must be supplied as well, e.g. \"accel_chip: adxl345 # my_chip_name\". Either this, or the next two parameters must be # set. #accel_chip_x: #accel_chip_y: # Names of the accelerometer chips to use for measurements for each # of the axis. Can be useful, for instance, on bed slinger printer, # if two separate accelerometers are mounted on the bed (for Y axis) # and on the toolhead (for X axis). These parameters have the same # format as 'accel_chip' parameter. Only 'accel_chip' or these two # parameters must be provided. #max_smoothing: # Maximum input shaper smoothing to allow for each axis during shaper # auto-calibration (with 'SHAPER_CALIBRATE' command). By default no # maximum smoothing is specified. Refer to Measuring_Resonances guide # for more details on using this feature. #move_speed: 50 # The speed (in mm/s) to move the toolhead to and between test points # during the calibration. The default is 50. #min_freq: 5 # Minimum frequency to test for resonances. The default is 5 Hz. #max_freq: 133.33 # Maximum frequency to test for resonances. The default is 133.33 Hz. #accel_per_hz: 60 # This parameter is used to determine which acceleration to use to # test a specific frequency: accel = accel_per_hz * freq. Higher the # value, the higher is the energy of the oscillations. Can be set to # a lower than the default value if the resonances get too strong on # the printer. However, lower values make measurements of # high-frequency resonances less precise. The default value is 75 # (mm/sec). #hz_per_sec: 1 # Determines the speed of the test. When testing all frequencies in # range [min_freq, max_freq], each second the frequency increases by # hz_per_sec. Small values make the test slow, and the large values # will decrease the precision of the test. The default value is 1.0 # (Hz/sec == sec^-2). #sweeping_accel: 400 # An acceleration of slow sweeping moves. The default is 400 mm/sec^2. #sweeping_period: 1.2 # A period of slow sweeping moves. Setting this parameter to 0 # disables slow sweeping moves. Avoid setting it to a too small # non-zero value in order to not poison the measurements. # The default is 1.2 sec which is a good all-round choice. Config file helpers \u00b6 [board_pins] \u00b6 Board pin aliases (one may define any number of sections with a \"board_pins\" prefix). Use this to define aliases for the pins on a micro-controller. [board_pins my_aliases] mcu: mcu # A comma separated list of micro-controllers that may use the # aliases. The default is to apply the aliases to the main \"mcu\". aliases: aliases_<name>: # A comma separated list of \"name=value\" aliases to create for the # given micro-controller. For example, \"EXP1_1=PE6\" would create an # \"EXP1_1\" alias for the \"PE6\" pin. However, if \"value\" is enclosed # in \"<>\" then \"name\" is created as a reserved pin (for example, # \"EXP1_9=<GND>\" would reserve \"EXP1_9\"). Any number of options # starting with \"aliases_\" may be specified. [include] \u00b6 Include file support. One may include additional config file from the main printer config file. Wildcards may also be used (eg, \"configs/*.cfg\"). [include my_other_config.cfg] [duplicate_pin_override] \u00b6 This tool allows a single micro-controller pin to be defined multiple times in a config file without normal error checking. This is intended for diagnostic and debugging purposes. This section is not needed where Klipper supports using the same pin multiple times, and using this override may cause confusing and unexpected results. [duplicate_pin_override] pins: # A comma separated list of pins that may be used multiple times in # a config file without normal error checks. This parameter must be # provided. Bed probing hardware \u00b6 [probe] \u00b6 Z height probe. One may define this section to enable Z height probing hardware. When this section is enabled, PROBE and QUERY_PROBE extended g-code commands become available. Also, see the probe calibrate guide . The probe section also creates a virtual \"probe:z_virtual_endstop\" pin. One may set the stepper_z endstop_pin to this virtual pin on cartesian style printers that use the probe in place of a z endstop. If using \"probe:z_virtual_endstop\" then do not define a position_endstop in the stepper_z config section. [probe] pin: # Probe detection pin. If the pin is on a different microcontroller # than the Z steppers then it enables \"multi-mcu homing\". This # parameter must be provided. #deactivate_on_each_sample: True # This determines if Klipper should execute deactivation gcode # between each probe attempt when performing a multiple probe # sequence. The default is True. #x_offset: 0.0 # The distance (in mm) between the probe and the nozzle along the # x-axis. The default is 0. #y_offset: 0.0 # The distance (in mm) between the probe and the nozzle along the # y-axis. The default is 0. z_offset: # The distance (in mm) between the bed and the nozzle when the probe # triggers. This parameter must be provided. #speed: 5.0 # Speed (in mm/s) of the Z axis when probing. The default is 5mm/s. #samples: 1 # The number of times to probe each point. The probed z-values will # be averaged. The default is to probe 1 time. #sample_retract_dist: 2.0 # The distance (in mm) to lift the toolhead between each sample (if # sampling more than once). The default is 2mm. #lift_speed: # Speed (in mm/s) of the Z axis when lifting the probe between # samples. The default is to use the same value as the 'speed' # parameter. #samples_result: average # The calculation method when sampling more than once - either # \"median\" or \"average\". The default is average. #samples_tolerance: 0.100 # The maximum Z distance (in mm) that a sample may differ from other # samples. If this tolerance is exceeded then either an error is # reported or the attempt is restarted (see # samples_tolerance_retries). The default is 0.100mm. #samples_tolerance_retries: 0 # The number of times to retry if a sample is found that exceeds # samples_tolerance. On a retry, all current samples are discarded # and the probe attempt is restarted. If a valid set of samples are # not obtained in the given number of retries then an error is # reported. The default is zero which causes an error to be reported # on the first sample that exceeds samples_tolerance. #activate_gcode: # A list of G-Code commands to execute prior to each probe attempt. # See docs/Command_Templates.md for G-Code format. This may be # useful if the probe needs to be activated in some way. Do not # issue any commands here that move the toolhead (eg, G1). The # default is to not run any special G-Code commands on activation. #deactivate_gcode: # A list of G-Code commands to execute after each probe attempt # completes. See docs/Command_Templates.md for G-Code format. Do not # issue any commands here that move the toolhead. The default is to # not run any special G-Code commands on deactivation. [bltouch] \u00b6 BLTouch probe. One may define this section (instead of a probe section) to enable a BLTouch probe. See BL-Touch guide and command reference for further information. A virtual \"probe:z_virtual_endstop\" pin is also created (see the \"probe\" section for the details). [bltouch] sensor_pin: # Pin connected to the BLTouch sensor pin. Most BLTouch devices # require a pullup on the sensor pin (prefix the pin name with \"^\"). # This parameter must be provided. control_pin: # Pin connected to the BLTouch control pin. This parameter must be # provided. #pin_move_time: 0.680 # The amount of time (in seconds) to wait for the BLTouch pin to # move up or down. The default is 0.680 seconds. #stow_on_each_sample: True # This determines if Klipper should command the pin to move up # between each probe attempt when performing a multiple probe # sequence. Read the directions in docs/BLTouch.md before setting # this to False. The default is True. #probe_with_touch_mode: False # If this is set to True then Klipper will probe with the device in # \"touch_mode\". The default is False (probing in \"pin_down\" mode). #pin_up_reports_not_triggered: True # Set if the BLTouch consistently reports the probe in a \"not # triggered\" state after a successful \"pin_up\" command. This should # be True for all genuine BLTouch devices. Read the directions in # docs/BLTouch.md before setting this to False. The default is True. #pin_up_touch_mode_reports_triggered: True # Set if the BLTouch consistently reports a \"triggered\" state after # the commands \"pin_up\" followed by \"touch_mode\". This should be # True for all genuine BLTouch devices. Read the directions in # docs/BLTouch.md before setting this to False. The default is True. #set_output_mode: # Request a specific sensor pin output mode on the BLTouch V3.0 (and # later). This setting should not be used on other types of probes. # Set to \"5V\" to request a sensor pin output of 5 Volts (only use if # the controller board needs 5V mode and is 5V tolerant on its input # signal line). Set to \"OD\" to request the sensor pin output use # open drain mode. The default is to not request an output mode. #x_offset: #y_offset: #z_offset: #speed: #lift_speed: #samples: #sample_retract_dist: #samples_result: #samples_tolerance: #samples_tolerance_retries: # See the \"probe\" section for information on these parameters. [smart_effector] \u00b6 The \"Smart Effector\" from Duet3d implements a Z probe using a force sensor. One may define this section instead of [probe] to enable the Smart Effector specific features. This also enables runtime commands to adjust the parameters of the Smart Effector at run time. [smart_effector] pin: # Pin connected to the Smart Effector Z Probe output pin (pin 5). Note that # pullup resistor on the board is generally not required. However, if the # output pin is connected to the board pin with a pullup resistor, that # resistor must be high value (e.g. 10K Ohm or more). Some boards have a low # value pullup resistor on the Z probe input, which will likely result in an # always-triggered probe state. In this case, connect the Smart Effector to # a different pin on the board. This parameter is required. #control_pin: # Pin connected to the Smart Effector control input pin (pin 7). If provided, # Smart Effector sensitivity programming commands become available. #probe_accel: # If set, limits the acceleration of the probing moves (in mm/sec^2). # A sudden large acceleration at the beginning of the probing move may # cause spurious probe triggering, especially if the hotend is heavy. # To prevent that, it may be necessary to reduce the acceleration of # the probing moves via this parameter. #recovery_time: 0.4 # A delay between the travel moves and the probing moves in seconds. A fast # travel move prior to probing may result in a spurious probe triggering. # This may cause 'Probe triggered prior to movement' errors if no delay # is set. Value 0 disables the recovery delay. # Default value is 0.4. #x_offset: #y_offset: # Should be left unset (or set to 0). z_offset: # Trigger height of the probe. Start with -0.1 (mm), and adjust later using # `PROBE_CALIBRATE` command. This parameter must be provided. #speed: # Speed (in mm/s) of the Z axis when probing. It is recommended to start # with the probing speed of 20 mm/s and adjust it as necessary to improve # the accuracy and repeatability of the probe triggering. #samples: #sample_retract_dist: #samples_result: #samples_tolerance: #samples_tolerance_retries: #activate_gcode: #deactivate_gcode: #deactivate_on_each_sample: # See the \"probe\" section for more information on the parameters above. [probe_eddy_current] \u00b6 Support for eddy current inductive probes. One may define this section (instead of a probe section) to enable this probe. See the command reference for further information. [probe_eddy_current my_eddy_probe] sensor_type: ldc1612 # The sensor chip used to perform eddy current measurements. This # parameter must be provided and must be set to ldc1612. #frequency: # The external crystal frequency (in Hz) of the LDC1612 chip. # The default is 12000000. #intb_pin: # MCU gpio pin connected to the ldc1612 sensor's INTB pin (if # available). The default is to not use the INTB pin. #z_offset: # The nominal distance (in mm) between the nozzle and bed that a # probing attempt should stop at. This parameter must be provided. #i2c_address: #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # The i2c settings for the sensor chip. See the \"common I2C # settings\" section for a description of the above parameters. #x_offset: #y_offset: #speed: #lift_speed: #samples: #sample_retract_dist: #samples_result: #samples_tolerance: #samples_tolerance_retries: # See the \"probe\" section for information on these parameters. [axis_twist_compensation] \u00b6 A tool to compensate for inaccurate probe readings due to twist in X or Y gantry. See the Axis Twist Compensation Guide for more detailed information regarding symptoms, configuration and setup. [axis_twist_compensation] #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. calibrate_start_x: 20 # Defines the minimum X coordinate of the calibration # This should be the X coordinate that positions the nozzle at the starting # calibration position. calibrate_end_x: 200 # Defines the maximum X coordinate of the calibration # This should be the X coordinate that positions the nozzle at the ending # calibration position. calibrate_y: 112.5 # Defines the Y coordinate of the calibration # This should be the Y coordinate that positions the nozzle during the # calibration process. This parameter is recommended to # be near the center of the bed # For Y-axis twist compensation, specify the following parameters: calibrate_start_y: ... # Defines the minimum Y coordinate of the calibration # This should be the Y coordinate that positions the nozzle at the starting # calibration position for the Y axis. This parameter must be provided if # compensating for Y axis twist. calibrate_end_y: ... # Defines the maximum Y coordinate of the calibration # This should be the Y coordinate that positions the nozzle at the ending # calibration position for the Y axis. This parameter must be provided if # compensating for Y axis twist. calibrate_x: ... # Defines the X coordinate of the calibration for Y axis twist compensation # This should be the X coordinate that positions the nozzle during the # calibration process for Y axis twist compensation. This parameter must be # provided and is recommended to be near the center of the bed. Additional stepper motors and extruders \u00b6 [stepper_z1] \u00b6 Multi-stepper axes. On a cartesian style printer, the stepper controlling a given axis may have additional config blocks defining steppers that should be stepped in concert with the primary stepper. One may define any number of sections with a numeric suffix starting at 1 (for example, \"stepper_z1\", \"stepper_z2\", etc.). [stepper_z1] #step_pin: #dir_pin: #enable_pin: #microsteps: #rotation_distance: # See the \"stepper\" section for the definition of the above parameters. #endstop_pin: # If an endstop_pin is defined for the additional stepper then the # stepper will home until the endstop is triggered. Otherwise, the # stepper will home until the endstop on the primary stepper for the # axis is triggered. [extruder1] \u00b6 In a multi-extruder printer add an additional extruder section for each additional extruder. The additional extruder sections should be named \"extruder1\", \"extruder2\", \"extruder3\", and so on. See the \"extruder\" section for a description of available parameters. See sample-multi-extruder.cfg for an example configuration. [extruder1] #step_pin: #dir_pin: #... # See the \"extruder\" section for available stepper and heater # parameters. #shared_heater: # This option is deprecated and should no longer be specified. [dual_carriage] \u00b6 Support for cartesian, generic_cartesian and hybrid_corexy/z printers with dual carriages on a single axis. The carriage mode can be set via the SET_DUAL_CARRIAGE extended g-code command. For example, \"SET_DUAL_CARRIAGE CARRIAGE=1\" command will activate the carriage defined in this section (CARRIAGE=0 will return activation to the primary carriage). Dual carriage support is typically combined with extra extruders - the SET_DUAL_CARRIAGE command is often called at the same time as the ACTIVATE_EXTRUDER command. Be sure to park the carriages during deactivation. Note that during G28 homing, typically the primary carriage is homed first followed by the carriage defined in the [dual_carriage] config section. However, the [dual_carriage] carriage will be homed first if both carriages home in a positive direction and the [dual_carriage] carriage has a position_endstop greater than the primary carriage, or if both carriages home in a negative direction and the [dual_carriage] carriage has a position_endstop less than the primary carriage. Additionally, one could use \"SET_DUAL_CARRIAGE CARRIAGE=1 MODE=COPY\" or \"SET_DUAL_CARRIAGE CARRIAGE=1 MODE=MIRROR\" commands to activate either copying or mirroring mode of the dual carriage, in which case it will follow the motion of the carriage 0 accordingly. These commands can be used to print two parts simultaneously - either two identical parts (in COPY mode) or mirrored parts (in MIRROR mode). Note that COPY and MIRROR modes also require appropriate configuration of the extruder on the dual carriage, which can typically be achieved with \"SYNC_EXTRUDER_MOTION MOTION_QUEUE=extruder EXTRUDER= \" or a similar command. See sample-idex.cfg for an example configuration with a regular Cartesian kinematic. [dual_carriage] axis: # The axis this extra carriage is on (either x or y). This parameter # must be provided. #safe_distance: # The minimum distance (in mm) to enforce between the dual and the primary # carriages. If a G-Code command is executed that will bring the carriages # closer than the specified limit, such a command will be rejected with an # error. If safe_distance is not provided, it will be inferred from # position_min and position_max for the dual and primary carriages. If set # to 0 (or safe_distance is unset and position_min and position_max are # identical for the primary and dual carriages), the carriages proximity # checks will be disabled. #step_pin: #dir_pin: #enable_pin: #microsteps: #rotation_distance: #endstop_pin: #position_endstop: #position_min: #position_max: # See the \"stepper\" section for the definition of the above parameters. For an example of dual carriage configuration with generic_cartesian kinematic, see the following configuration sample . Please note that in this case the [dual_carriage] configuration deviates from the configuration described above: [dual_carriage my_dc_carriage] primary_carriage: # Defines the matching primary carriage of this dual carriage and # the corresponding IDEX axis. Valid choices are x, y, z. # This parameter must be provided. #safe_distance: # The minimum distance (in mm) to enforce between the dual and the primary # carriages. If a G-Code command is executed that will bring the carriages # closer than the specified limit, such a command will be rejected with an # error. If safe_distance is not provided, it will be inferred from # position_min and position_max for the dual and primary carriages. If set # to 0 (or safe_distance is unset and position_min and position_max are # identical for the primary and dual carriages), the carriages proximity # checks will be disabled. endstop_pin: #position_min: position_endstop: position_max: #homing_speed: #homing_retract_dist: #homing_retract_speed: #second_homing_speed: #homing_positive_dir: ... Refer to generic cartesian section for more information on the regular carriage parameters. Then a user must define one or more stepper motors moving the dual carriage (and other carriages as appropriate), for instance [carriage x] ... [carriage y] ... [dual_carriage u] primary_carriage: x ... [stepper dc_stepper] carriages: u-y ... [dual_carriage] requires special configuration for the input shaper. In general, it is necessary to run input shaper calibration twice - for the dual_carriage and its primary_carriage for the axis they share. Then the input shaper can be configured as follows, assuming the example above: [input_shaper] # Intentionally empty [delayed_gcode init_shaper] initial_duration: 0.1 gcode: SET_DUAL_CARRIAGE CARRIAGE=u SET_INPUT_SHAPER SHAPER_TYPE_X=<dual_carriage_x_shaper> SHAPER_FREQ_X=<dual_carriage_x_freq> SHAPER_TYPE_Y=<y_shaper> SHAPER_FREQ_Y=<y_freq> SET_DUAL_CARRIAGE CARRIAGE=x SET_INPUT_SHAPER SHAPER_TYPE_X=<primary_carriage_x_shaper> SHAPER_FREQ_X=<primary_carriage_x_freq> SHAPER_TYPE_Y=<y_shaper> SHAPER_FREQ_Y=<y_freq> Note that SHAPER_TYPE_Y and SHAPER_FREQ_Y must be the same in both commands in this case, since the same motors drive Y axis when either of the x and u carriages are active. It is worth noting that generic_cartesian kinematic can support two dual carriages for X and Y axes. For reference, see for instance a sample of CoreXYUV configuration. [extruder_stepper] \u00b6 Support for additional steppers synchronized to the movement of an extruder (one may define any number of sections with an \"extruder_stepper\" prefix). See the command reference for more information. [extruder_stepper my_extra_stepper] extruder: # The extruder this stepper is synchronized to. If this is set to an # empty string then the stepper will not be synchronized to an # extruder. This parameter must be provided. #step_pin: #dir_pin: #enable_pin: #microsteps: #rotation_distance: # See the \"stepper\" section for the definition of the above # parameters. [manual_stepper] \u00b6 Manual steppers (one may define any number of sections with a \"manual_stepper\" prefix). These are steppers that are controlled by the MANUAL_STEPPER g-code command. For example: \"MANUAL_STEPPER STEPPER=my_stepper MOVE=10 SPEED=5\". See G-Codes file for a description of the MANUAL_STEPPER command. The steppers are not connected to the normal printer kinematics. [manual_stepper my_stepper] #step_pin: #dir_pin: #enable_pin: #microsteps: #rotation_distance: # See the \"stepper\" section for a description of these parameters. #velocity: # Set the default velocity (in mm/s) for the stepper. This value # will be used if a MANUAL_STEPPER command does not specify a SPEED # parameter. The default is 5mm/s. #accel: # Set the default acceleration (in mm/s^2) for the stepper. An # acceleration of zero will result in no acceleration. This value # will be used if a MANUAL_STEPPER command does not specify an ACCEL # parameter. The default is zero. #endstop_pin: # Endstop switch detection pin. If specified, then one may perform # \"homing moves\" by adding a STOP_ON_ENDSTOP parameter to # MANUAL_STEPPER movement commands. #position_min: #position_max: # The minimum and maximum position the stepper can be commanded to # move to. If specified then one may not command the stepper to move # past the given position. Note that these limits do not prevent # setting an arbitrary position with the `MANUAL_STEPPER # SET_POSITION=x` command. The default is to not enforce a limit. Custom heaters and sensors \u00b6 [verify_heater] \u00b6 Heater and temperature sensor verification. Heater verification is automatically enabled for each heater that is configured on the printer. Use verify_heater sections to change the default settings. [verify_heater heater_config_name] #max_error: 120 # The maximum \"cumulative temperature error\" before raising an # error. Smaller values result in stricter checking and larger # values allow for more time before an error is reported. # Specifically, the temperature is inspected once a second and if it # is close to the target temperature then an internal \"error # counter\" is reset; otherwise, if the temperature is below the # target range then the counter is increased by the amount the # reported temperature differs from that range. Should the counter # exceed this \"max_error\" then an error is raised. The default is # 120. #check_gain_time: # This controls heater verification during initial heating. Smaller # values result in stricter checking and larger values allow for # more time before an error is reported. Specifically, during # initial heating, as long as the heater increases in temperature # within this time frame (specified in seconds) then the internal # \"error counter\" is reset. The default is 20 seconds for extruders # and 60 seconds for heater_bed. #hysteresis: 5 # The maximum temperature difference (in Celsius) to a target # temperature that is considered in range of the target. This # controls the max_error range check. It is rare to customize this # value. The default is 5. #heating_gain: 2 # The minimum temperature (in Celsius) that the heater must increase # by during the check_gain_time check. It is rare to customize this # value. The default is 2. [homing_heaters] \u00b6 Tool to disable heaters when homing or probing an axis. [homing_heaters] #steppers: # A comma separated list of steppers that should cause heaters to be # disabled. The default is to disable heaters for any homing/probing # move. # Typical example: stepper_z #heaters: # A comma separated list of heaters to disable during homing/probing # moves. The default is to disable all heaters. # Typical example: extruder, heater_bed [thermistor] \u00b6 Custom thermistors (one may define any number of sections with a \"thermistor\" prefix). A custom thermistor may be used in the sensor_type field of a heater config section. (For example, if one defines a \"[thermistor my_thermistor]\" section then one may use a \"sensor_type: my_thermistor\" when defining a heater.) Be sure to place the thermistor section in the config file above its first use in a heater section. [thermistor my_thermistor] #temperature1: #resistance1: #temperature2: #resistance2: #temperature3: #resistance3: # Three resistance measurements (in Ohms) at the given temperatures # (in Celsius). The three measurements will be used to calculate the # Steinhart-Hart coefficients for the thermistor. These parameters # must be provided when using Steinhart-Hart to define the # thermistor. #beta: # Alternatively, one may define temperature1, resistance1, and beta # to define the thermistor parameters. This parameter must be # provided when using \"beta\" to define the thermistor. [adc_temperature] \u00b6 Custom ADC temperature sensors (one may define any number of sections with an \"adc_temperature\" prefix). This allows one to define a custom temperature sensor that measures a voltage on an Analog to Digital Converter (ADC) pin and uses linear interpolation between a set of configured temperature/voltage (or temperature/resistance) measurements to determine the temperature. The resulting sensor can be used as a sensor_type in a heater section. (For example, if one defines a \"[adc_temperature my_sensor]\" section then one may use a \"sensor_type: my_sensor\" when defining a heater.) Be sure to place the sensor section in the config file above its first use in a heater section. [adc_temperature my_sensor] #temperature1: #voltage1: #temperature2: #voltage2: #... # A set of temperatures (in Celsius) and voltages (in Volts) to use # as reference when converting a temperature. A heater section using # this sensor may also specify adc_voltage and voltage_offset # parameters to define the ADC voltage (see \"Common temperature # amplifiers\" section for details). At least two measurements must # be provided. #temperature1: #resistance1: #temperature2: #resistance2: #... # Alternatively one may specify a set of temperatures (in Celsius) # and resistance (in Ohms) to use as reference when converting a # temperature. A heater section using this sensor may also specify a # pullup_resistor parameter (see \"extruder\" section for details). At # least two measurements must be provided. [heater_generic] \u00b6 Generic heaters (one may define any number of sections with a \"heater_generic\" prefix). These heaters behave similarly to standard heaters (extruders, heated beds). Use the SET_HEATER_TEMPERATURE command (see G-Codes for details) to set the target temperature. [heater_generic my_generic_heater] #gcode_id: # The id to use when reporting the temperature in the M105 command. # This parameter must be provided. #heater_pin: #max_power: #sensor_type: #sensor_pin: #smooth_time: #control: #pid_Kp: #pid_Ki: #pid_Kd: #pwm_cycle_time: #min_temp: #max_temp: # See the \"extruder\" section for the definition of the above # parameters. [temperature_sensor] \u00b6 Generic temperature sensors. One can define any number of additional temperature sensors that are reported via the M105 command. [temperature_sensor my_sensor] #sensor_type: #sensor_pin: #min_temp: #max_temp: # See the \"extruder\" section for the definition of the above # parameters. #gcode_id: # See the \"heater_generic\" section for the definition of this # parameter. [temperature_probe] \u00b6 Reports probe coil temperature. Includes optional thermal drift calibration for eddy current based probes. A [temperature_probe] section may be linked to a [probe_eddy_current] by using the same postfix for both sections. [temperature_probe my_probe] #sensor_type: #sensor_pin: #min_temp: #max_temp: # Temperature sensor configuration. # See the \"extruder\" section for the definition of the above # parameters. #smooth_time: # A time value (in seconds) over which temperature measurements will # be smoothed to reduce the impact of measurement noise. The default # is 2.0 seconds. #gcode_id: # See the \"heater_generic\" section for the definition of this # parameter. #speed: # The travel speed [mm/s] for xy moves during calibration. Default # is the speed defined by the probe. #horizontal_move_z: # The z distance [mm] from the bed at which xy moves will occur # during calibration. Default is 2mm. #resting_z: # The z distance [mm] from the bed at which the tool will rest # to heat the probe coil during calibration. Default is .4mm #calibration_position: # The X, Y, Z position where the tool should be moved when # probe drift calibration initializes. This is the location # where the first manual probe will occur. If omitted, the # default behavior is not to move the tool prior to the first # manual probe. #calibration_bed_temp: # The maximum safe bed temperature (in C) used to heat the probe # during probe drift calibration. When set, the calibration # procedure will turn on the bed after the first sample is # taken. When the calibration procedure is complete the bed # temperature will be set to zero. When omitted the default # behavior is not to set the bed temperature. #calibration_extruder_temp: # The extruder temperature (in C) set probe during drift calibration. # When this option is supplied the procedure will wait for until the # specified temperature is reached before requesting the first manual # probe. When the calibration procedure is complete the extruder # temperature will be set to 0. When omitted the default behavior is # not to set the extruder temperature. #extruder_heating_z: 50. # The Z location where extruder heating will occur if the # \"calibration_extruder_temp\" option is set. Its recommended to heat # the extruder some distance from the bed to minimize its impact on # the probe coil temperature. The default is 50. #max_validation_temp: 60. # The maximum temperature used to validate the calibration. It is # recommended to set this to a value between 100 and 120 for enclosed # printers. The default is 60. Temperature sensors \u00b6 Klipper includes definitions for many types of temperature sensors. These sensors may be used in any config section that requires a temperature sensor (such as an [extruder] or [heater_bed] section). Common thermistors \u00b6 Common thermistors. The following parameters are available in heater sections that use one of these sensors. sensor_type: # One of \"EPCOS 100K B57560G104F\", \"ATC Semitec 104GT-2\", # \"ATC Semitec 104NT-4-R025H42G\", \"Generic 3950\", # \"Honeywell 100K 135-104LAG-J01\", \"NTC 100K MGB18-104F39050L32\", # \"SliceEngineering 450\", or \"TDK NTCG104LH104JT1\" sensor_pin: # Analog input pin connected to the thermistor. This parameter must # be provided. #pullup_resistor: 4700 # The resistance (in ohms) of the pullup attached to the thermistor. # The default is 4700 ohms. #inline_resistor: 0 # The resistance (in ohms) of an extra (not heat varying) resistor # that is placed inline with the thermistor. It is rare to set this. # The default is 0 ohms. Common temperature amplifiers \u00b6 Common temperature amplifiers. The following parameters are available in heater sections that use one of these sensors. sensor_type: # One of \"PT100 INA826\", \"AD595\", \"AD597\", \"AD8494\", \"AD8495\", # \"AD8496\", or \"AD8497\". sensor_pin: # Analog input pin connected to the sensor. This parameter must be # provided. #adc_voltage: 5.0 # The ADC comparison voltage (in Volts). The default is 5 volts. #voltage_offset: 0 # The ADC voltage offset (in Volts). The default is 0. Directly connected PT1000 sensor \u00b6 Directly connected PT1000 sensor. The following parameters are available in heater sections that use one of these sensors. sensor_type: PT1000 sensor_pin: # Analog input pin connected to the sensor. This parameter must be # provided. #pullup_resistor: 4700 # The resistance (in ohms) of the pullup attached to the sensor. The # default is 4700 ohms. MAXxxxxx temperature sensors \u00b6 MAXxxxxx serial peripheral interface (SPI) temperature based sensors. The following parameters are available in heater sections that use one of these sensor types. sensor_type: # One of \"MAX6675\", \"MAX31855\", \"MAX31856\", or \"MAX31865\". sensor_pin: # The chip select line for the sensor chip. This parameter must be # provided. #spi_speed: 4000000 # The SPI speed (in hz) to use when communicating with the chip. # The default is 4000000. #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #tc_type: K #tc_use_50Hz_filter: False #tc_averaging_count: 1 # The above parameters control the sensor parameters of MAX31856 # chips. The defaults for each parameter are next to the parameter # name in the above list. #rtd_nominal_r: 100 #rtd_reference_r: 430 #rtd_num_of_wires: 2 #rtd_use_50Hz_filter: False # The above parameters control the sensor parameters of MAX31865 # chips. The defaults for each parameter are next to the parameter # name in the above list. BMP180/BMP280/BME280/BMP388/BME680 temperature sensor \u00b6 BMP180/BMP280/BME280/BMP388/BME680 two wire interface (I2C) environmental sensors. Note that these sensors are not intended for use with extruders and heater beds, but rather for monitoring ambient temperature (C), pressure (hPa), relative humidity and in case of the BME680 gas level. See sample-macros.cfg for a gcode_macro that may be used to report pressure and humidity in addition to temperature. sensor_type: BME280 #i2c_address: # Default is 118 (0x76). The BMP180, BMP388 and some BME280 sensors # have an address of 119 (0x77). #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. AHT10/AHT20/AHT21 temperature sensor \u00b6 AHT10/AHT20/AHT21 two wire interface (I2C) environmental sensors. Note that these sensors are not intended for use with extruders and heater beds, but rather for monitoring ambient temperature (C) and relative humidity. See sample-macros.cfg for a gcode_macro that may be used to report humidity in addition to temperature. sensor_type: AHT10 # Also use AHT10 for AHT20 and AHT21 sensors. #i2c_address: # Default is 56 (0x38). Some AHT10 sensors give the option to use # 57 (0x39) by moving a resistor. #i2c_mcu: #i2c_bus: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #aht10_report_time: # Interval in seconds between readings. Default is 30, minimum is 5 HTU21D sensor \u00b6 HTU21D family two wire interface (I2C) environmental sensor. Note that this sensor is not intended for use with extruders and heater beds, but rather for monitoring ambient temperature (C) and relative humidity. See sample-macros.cfg for a gcode_macro that may be used to report humidity in addition to temperature. sensor_type: # Must be \"HTU21D\" , \"SI7013\", \"SI7020\", \"SI7021\" or \"SHT21\" #i2c_address: # Default is 64 (0x40). #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #htu21d_hold_master: # If the sensor can hold the I2C buf while reading. If True no other # bus communication can be performed while reading is in progress. # Default is False. #htu21d_resolution: # The resolution of temperature and humidity reading. # Valid values are: # 'TEMP14_HUM12' -> 14bit for Temp and 12bit for humidity # 'TEMP13_HUM10' -> 13bit for Temp and 10bit for humidity # 'TEMP12_HUM08' -> 12bit for Temp and 08bit for humidity # 'TEMP11_HUM11' -> 11bit for Temp and 11bit for humidity # Default is: \"TEMP11_HUM11\" #htu21d_report_time: # Interval in seconds between readings. Default is 30 SHT3X sensor \u00b6 SHT3X family two wire interface (I2C) environmental sensor. These sensors have a range of -55~125 C, so are usable for e.g. chamber temperature monitoring. They can also function as simple fan/heater controllers. sensor_type: SHT3X #i2c_address: # Default is 68 (0x44). #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. LM75 temperature sensor \u00b6 LM75/LM75A two wire (I2C) connected temperature sensors. These sensors have a range of -55~125 C, so are usable for e.g. chamber temperature monitoring. They can also function as simple fan/heater controllers. sensor_type: LM75 #i2c_address: # Default is 72 (0x48). Normal range is 72-79 (0x48-0x4F) and the 3 # low bits of the address are configured via pins on the chip # (usually with jumpers or hard wired). #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #lm75_report_time: # Interval in seconds between readings. Default is 0.8, with minimum # 0.5. Builtin micro-controller temperature sensor \u00b6 The atsam, atsamd, stm32 and rp2040 micro-controllers contain an internal temperature sensor. One can use the \"temperature_mcu\" sensor to monitor these temperatures. sensor_type: temperature_mcu #sensor_mcu: mcu # The micro-controller to read from. The default is \"mcu\". #sensor_temperature1: #sensor_adc1: # Specify the above two parameters (a temperature in Celsius and an # ADC value as a float between 0.0 and 1.0) to calibrate the # micro-controller temperature. This may improve the reported # temperature accuracy on some chips. A typical way to obtain this # calibration information is to completely remove power from the # printer for a few hours (to ensure it is at the ambient # temperature), then power it up and use the QUERY_ADC command to # obtain an ADC measurement. Use some other temperature sensor on # the printer to find the corresponding ambient temperature. The # default is to use the factory calibration data on the # micro-controller (if applicable) or the nominal values from the # micro-controller specification. #sensor_temperature2: #sensor_adc2: # If sensor_temperature1/sensor_adc1 is specified then one may also # specify sensor_temperature2/sensor_adc2 calibration data. Doing so # may provide calibrated \"temperature slope\" information. The # default is to use the factory calibration data on the # micro-controller (if applicable) or the nominal values from the # micro-controller specification. Host temperature sensor \u00b6 Temperature from the machine (eg Raspberry Pi) running the host software. sensor_type: temperature_host #sensor_path: # The path to temperature system file. The default is # \"/sys/class/thermal/thermal_zone0/temp\" which is the temperature # system file on a Raspberry Pi computer. DS18B20 temperature sensor \u00b6 DS18B20 is a 1-wire (w1) digital temperature sensor. Note that this sensor is not intended for use with extruders and heater beds, but rather for monitoring ambient temperature (C). These sensors have range up to 125 C, so are usable for e.g. chamber temperature monitoring. They can also function as simple fan/heater controllers. DS18B20 sensors are only supported on the \"host mcu\", e.g. the Raspberry Pi. The w1-gpio Linux kernel module must be installed. sensor_type: DS18B20 serial_no: # Each 1-wire device has a unique serial number used to identify the device, # usually in the format 28-031674b175ff. This parameter must be provided. # Attached 1-wire devices can be listed using the following Linux command: # ls /sys/bus/w1/devices/ #ds18_report_time: # Interval in seconds between readings. Default is 3.0, with a minimum of 1.0 #sensor_mcu: # The micro-controller to read from. Must be the host_mcu Combined temperature sensor \u00b6 Combined temperature sensor is a virtual temperature sensor based on several other sensors. This sensor can be used with extruders, heater_generic and heater beds. sensor_type: temperature_combined #sensor_list: # Must be provided. List of sensors to combine to new \"virtual\" # sensor. # E.g. 'temperature_sensor sensor1,extruder,heater_bed' #combination_method: # Must be provided. Combination method used for the sensor. # Available options are 'max', 'min', 'mean'. #maximum_deviation: # Must be provided. Maximum permissible deviation between the sensors # to combine (e.g. 5 degrees). To disable it, use a large value (e.g. 999.9) Fans \u00b6 [fan] \u00b6 Print cooling fan. [fan] pin: # Output pin controlling the fan. This parameter must be provided. #max_power: 1.0 # The maximum power (expressed as a value from 0.0 to 1.0) that the # pin may be set to. The value 1.0 allows the pin to be set fully # enabled for extended periods, while a value of 0.5 would allow the # pin to be enabled for no more than half the time. This setting may # be used to limit the total power output (over extended periods) to # the fan. If this value is less than 1.0 then fan speed requests # will be scaled between zero and max_power (for example, if # max_power is .9 and a fan speed of 80% is requested then the fan # power will be set to 72%). The default is 1.0. #shutdown_speed: 0 # The desired fan speed (expressed as a value from 0.0 to 1.0) if # the micro-controller software enters an error state. The default # is 0. #cycle_time: 0.010 # The amount of time (in seconds) for each PWM power cycle to the # fan. It is recommended this be 10 milliseconds or greater when # using software based PWM. The default is 0.010 seconds. #hardware_pwm: False # Enable this to use hardware PWM instead of software PWM. Most fans # do not work well with hardware PWM, so it is not recommended to # enable this unless there is an electrical requirement to switch at # very high speeds. When using hardware PWM the actual cycle time is # constrained by the implementation and may be significantly # different than the requested cycle_time. The default is False. #kick_start_time: 0.100 # Time (in seconds) to run the fan at full speed when either first # enabling or increasing it by more than 50% (helps get the fan # spinning). The default is 0.100 seconds. #off_below: 0.0 # The minimum input speed which will power the fan (expressed as a # value from 0.0 to 1.0). When a speed lower than off_below is # requested the fan will instead be turned off. This setting may be # used to prevent fan stalls and to ensure kick starts are # effective. The default is 0.0. # # This setting should be recalibrated whenever max_power is adjusted. # To calibrate this setting, start with off_below set to 0.0 and the # fan spinning. Gradually lower the fan speed to determine the lowest # input speed which reliably drives the fan without stalls. Set # off_below to the duty cycle corresponding to this value (for # example, 12% -> 0.12) or slightly higher. #tachometer_pin: # Tachometer input pin for monitoring fan speed. A pullup is generally # required. This parameter is optional. #tachometer_ppr: 2 # When tachometer_pin is specified, this is the number of pulses per # revolution of the tachometer signal. For a BLDC fan this is # normally half the number of poles. The default is 2. #tachometer_poll_interval: 0.0015 # When tachometer_pin is specified, this is the polling period of the # tachometer pin, in seconds. The default is 0.0015, which is fast # enough for fans below 10000 RPM at 2 PPR. This must be smaller than # 30/(tachometer_ppr*rpm), with some margin, where rpm is the # maximum speed (in RPM) of the fan. #enable_pin: # Optional pin to enable power to the fan. This can be useful for fans # with dedicated PWM inputs. Some of these fans stay on even at 0% PWM # input. In such a case, the PWM pin can be used normally, and e.g. a # ground-switched FET(standard fan pin) can be used to control power to # the fan. [heater_fan] \u00b6 Heater cooling fans (one may define any number of sections with a \"heater_fan\" prefix). A \"heater fan\" is a fan that will be enabled whenever its associated heater is active. By default, a heater_fan has a shutdown_speed equal to max_power. [heater_fan heatbreak_cooling_fan] #pin: #max_power: #shutdown_speed: #cycle_time: #hardware_pwm: #kick_start_time: #off_below: #tachometer_pin: #tachometer_ppr: #tachometer_poll_interval: #enable_pin: # See the \"fan\" section for a description of the above parameters. #heater: extruder # Name of the config section defining the heater that this fan is # associated with. If a comma separated list of heater names is # provided here, then the fan will be enabled when any of the given # heaters are enabled. The default is \"extruder\". #heater_temp: 50.0 # A temperature (in Celsius) that the heater must drop below before # the fan is disabled. The default is 50 Celsius. #fan_speed: 1.0 # The fan speed (expressed as a value from 0.0 to 1.0) that the fan # will be set to when its associated heater is enabled. The default # is 1.0 [controller_fan] \u00b6 Controller cooling fan (one may define any number of sections with a \"controller_fan\" prefix). A \"controller fan\" is a fan that will be enabled whenever its associated heater or its associated stepper driver is active. The fan will stop whenever an idle_timeout is reached to ensure no overheating will occur after deactivating a watched component. [controller_fan my_controller_fan] #pin: #max_power: #shutdown_speed: #cycle_time: #hardware_pwm: #kick_start_time: #off_below: #tachometer_pin: #tachometer_ppr: #tachometer_poll_interval: #enable_pin: # See the \"fan\" section for a description of the above parameters. #fan_speed: 1.0 # The fan speed (expressed as a value from 0.0 to 1.0) that the fan # will be set to when a heater or stepper driver is active. # The default is 1.0 #idle_timeout: # The amount of time (in seconds) after a stepper driver or heater # was active and the fan should be kept running. The default # is 30 seconds. #idle_speed: # The fan speed (expressed as a value from 0.0 to 1.0) that the fan # will be set to when a heater or stepper driver was active and # before the idle_timeout is reached. The default is fan_speed. #heater: #stepper: # Name of the config section defining the heater/stepper that this fan # is associated with. If a comma separated list of heater/stepper names # is provided here, then the fan will be enabled when any of the given # heaters/steppers are enabled. The default heater is \"extruder\", the # default stepper is all of them. [temperature_fan] \u00b6 Temperature-triggered cooling fans (one may define any number of sections with a \"temperature_fan\" prefix). A \"temperature fan\" is a fan that will be enabled whenever its associated sensor is above a set temperature. By default, a temperature_fan has a shutdown_speed equal to max_power. See the command reference for additional information. [temperature_fan my_temp_fan] #pin: #max_power: #shutdown_speed: #cycle_time: #hardware_pwm: #kick_start_time: #off_below: #tachometer_pin: #tachometer_ppr: #tachometer_poll_interval: #enable_pin: # See the \"fan\" section for a description of the above parameters. #sensor_type: #sensor_pin: #control: #max_delta: #min_temp: #max_temp: # See the \"extruder\" section for a description of the above parameters. #pid_Kp: #pid_Ki: #pid_Kd: # The proportional (pid_Kp), integral (pid_Ki), and derivative # (pid_Kd) settings for the PID feedback control system. Klipper # evaluates the PID settings with the following general formula: # fan_pwm = max_power - (Kp*e + Ki*integral(e) - Kd*derivative(e)) / 255 # Where \"e\" is \"target_temperature - measured_temperature\" and # \"fan_pwm\" is the requested fan rate with 0.0 being full off and # 1.0 being full on. The pid_Kp, pid_Ki, and pid_Kd parameters must # be provided when the PID control algorithm is enabled. #pid_deriv_time: 2.0 # A time value (in seconds) over which temperature measurements will # be smoothed when using the PID control algorithm. This may reduce # the impact of measurement noise. The default is 2 seconds. #target_temp: 40.0 # A temperature (in Celsius) that will be the target temperature. # The default is 40 degrees. #max_speed: 1.0 # The fan speed (expressed as a value from 0.0 to 1.0) that the fan # will be set to when the sensor temperature exceeds the set value. # The default is 1.0. #min_speed: 0.3 # The minimum fan speed (expressed as a value from 0.0 to 1.0) that # the fan will be set to for PID temperature fans. # The default is 0.3. #gcode_id: # If set, the temperature will be reported in M105 queries using the # given id. The default is to not report the temperature via M105. [fan_generic] \u00b6 Manually controlled fan (one may define any number of sections with a \"fan_generic\" prefix). The speed of a manually controlled fan is set with the SET_FAN_SPEED gcode command . [fan_generic extruder_partfan] #pin: #max_power: #shutdown_speed: #cycle_time: #hardware_pwm: #kick_start_time: #off_below: #tachometer_pin: #tachometer_ppr: #tachometer_poll_interval: #enable_pin: # See the \"fan\" section for a description of the above parameters. LEDs \u00b6 [led] \u00b6 Support for LEDs (and LED strips) controlled via micro-controller PWM pins (one may define any number of sections with an \"led\" prefix). See the command reference for more information. [led my_led] #red_pin: #green_pin: #blue_pin: #white_pin: # The pin controlling the given LED color. At least one of the above # parameters must be provided. #cycle_time: 0.010 # The amount of time (in seconds) per PWM cycle. It is recommended # this be 10 milliseconds or greater when using software based PWM. # The default is 0.010 seconds. #hardware_pwm: False # Enable this to use hardware PWM instead of software PWM. When # using hardware PWM the actual cycle time is constrained by the # implementation and may be significantly different than the # requested cycle_time. The default is False. #initial_RED: 0.0 #initial_GREEN: 0.0 #initial_BLUE: 0.0 #initial_WHITE: 0.0 # Sets the initial LED color. Each value should be between 0.0 and # 1.0. The default for each color is 0. [neopixel] \u00b6 Neopixel (aka WS2812) LED support (one may define any number of sections with a \"neopixel\" prefix). See the command reference for more information. Note that the linux mcu implementation does not currently support directly connected neopixels. The current design using the Linux kernel interface does not allow this scenario because the kernel GPIO interface is not fast enough to provide the required pulse rates. [neopixel my_neopixel] pin: # The pin connected to the neopixel. This parameter must be # provided. #chain_count: # The number of Neopixel chips that are \"daisy chained\" to the # provided pin. The default is 1 (which indicates only a single # Neopixel is connected to the pin). #color_order: GRB # Set the pixel order required by the LED hardware (using a string # containing the letters R, G, B, W with W optional). Alternatively, # this may be a comma separated list of pixel orders - one for each # LED in the chain. The default is GRB. #initial_RED: 0.0 #initial_GREEN: 0.0 #initial_BLUE: 0.0 #initial_WHITE: 0.0 # See the \"led\" section for information on these parameters. [dotstar] \u00b6 Dotstar (aka APA102) LED support (one may define any number of sections with a \"dotstar\" prefix). See the command reference for more information. [dotstar my_dotstar] data_pin: # The pin connected to the data line of the dotstar. This parameter # must be provided. clock_pin: # The pin connected to the clock line of the dotstar. This parameter # must be provided. #chain_count: # See the \"neopixel\" section for information on this parameter. #initial_RED: 0.0 #initial_GREEN: 0.0 #initial_BLUE: 0.0 # See the \"led\" section for information on these parameters. [pca9533] \u00b6 PCA9533 LED support. The PCA9533 is used on the mightyboard. [pca9533 my_pca9533] #i2c_address: 98 # The i2c address that the chip is using on the i2c bus. Use 98 for # the PCA9533/1, 99 for the PCA9533/2. The default is 98. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #initial_RED: 0.0 #initial_GREEN: 0.0 #initial_BLUE: 0.0 #initial_WHITE: 0.0 # See the \"led\" section for information on these parameters. [pca9632] \u00b6 PCA9632 LED support. The PCA9632 is used on the FlashForge Dreamer. [pca9632 my_pca9632] #i2c_address: 98 # The i2c address that the chip is using on the i2c bus. This may be # 96, 97, 98, or 99. The default is 98. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #color_order: RGBW # Set the pixel order of the LED (using a string containing the # letters R, G, B, W). The default is RGBW. #initial_RED: 0.0 #initial_GREEN: 0.0 #initial_BLUE: 0.0 #initial_WHITE: 0.0 # See the \"led\" section for information on these parameters. Additional servos, buttons, and other pins \u00b6 [servo] \u00b6 Servos (one may define any number of sections with a \"servo\" prefix). The servos may be controlled using the SET_SERVO g-code command . For example: SET_SERVO SERVO=my_servo ANGLE=180 [servo my_servo] pin: # PWM output pin controlling the servo. This parameter must be # provided. #maximum_servo_angle: 180 # The maximum angle (in degrees) that this servo can be set to. The # default is 180 degrees. #minimum_pulse_width: 0.001 # The minimum pulse width time (in seconds). This should correspond # with an angle of 0 degrees. The default is 0.001 seconds. #maximum_pulse_width: 0.002 # The maximum pulse width time (in seconds). This should correspond # with an angle of maximum_servo_angle. The default is 0.002 # seconds. #initial_angle: # Initial angle (in degrees) to set the servo to. The default is to # not send any signal at startup. #initial_pulse_width: # Initial pulse width time (in seconds) to set the servo to. (This # is only valid if initial_angle is not set.) The default is to not # send any signal at startup. [gcode_button] \u00b6 Execute gcode when a button is pressed or released (or when a pin changes state). You can check the state of the button by using QUERY_BUTTON button=my_gcode_button . [gcode_button my_gcode_button] pin: # The pin on which the button is connected. This parameter must be # provided. #analog_range: # Two comma separated resistances (in Ohms) specifying the minimum # and maximum resistance range for the button. If analog_range is # provided then the pin must be an analog capable pin. The default # is to use digital gpio for the button. #analog_pullup_resistor: # The pullup resistance (in Ohms) when analog_range is specified. # The default is 4700 ohms. #press_gcode: # A list of G-Code commands to execute when the button is pressed. # G-Code templates are supported. This parameter must be provided. #release_gcode: # A list of G-Code commands to execute when the button is released. # G-Code templates are supported. The default is to not run any # commands on a button release. #debounce_delay: # A period of time in seconds to debounce events prior to running the # button gcode. If the button is pressed and released during this # delay, the entire button press is ignored. Default is 0. [output_pin] \u00b6 Run-time configurable output pins (one may define any number of sections with an \"output_pin\" prefix). Pins configured here will be setup as output pins and one may modify them at run-time using \"SET_PIN PIN=my_pin VALUE=.1\" type extended g-code commands . [output_pin my_pin] pin: # The pin to configure as an output. This parameter must be # provided. #pwm: False # Set if the output pin should be capable of pulse-width-modulation. # If this is true, the value fields should be between 0 and 1; if it # is false the value fields should be either 0 or 1. The default is # False. #value: # The value to initially set the pin to during MCU configuration. # The default is 0 (for low voltage). #shutdown_value: # The value to set the pin to on an MCU shutdown event. The default # is 0 (for low voltage). #cycle_time: 0.100 # The amount of time (in seconds) per PWM cycle. It is recommended # this be 10 milliseconds or greater when using software based PWM. # The default is 0.100 seconds for pwm pins. #hardware_pwm: False # Enable this to use hardware PWM instead of software PWM. When # using hardware PWM the actual cycle time is constrained by the # implementation and may be significantly different than the # requested cycle_time. The default is False. #scale: # This parameter can be used to alter how the 'value' and # 'shutdown_value' parameters are interpreted for pwm pins. If # provided, then the 'value' parameter should be between 0.0 and # 'scale'. This may be useful when configuring a PWM pin that # controls a stepper voltage reference. The 'scale' can be set to # the equivalent stepper amperage if the PWM were fully enabled, and # then the 'value' parameter can be specified using the desired # amperage for the stepper. The default is to not scale the 'value' # parameter. #maximum_mcu_duration: #static_value: # These options are deprecated and should no longer be specified. [pwm_tool] \u00b6 Pulse width modulation digital output pins capable of high speed updates (one may define any number of sections with an \"output_pin\" prefix). Pins configured here will be setup as output pins and one may modify them at run-time using \"SET_PIN PIN=my_pin VALUE=.1\" type extended g-code commands . [pwm_tool my_tool] pin: # The pin to configure as an output. This parameter must be provided. #maximum_mcu_duration: # The maximum duration a non-shutdown value may be driven by the MCU # without an acknowledge from the host. # If host can not keep up with an update, the MCU will shutdown # and set all pins to their respective shutdown values. # Default: 0 (disabled) # Usual values are around 5 seconds. #value: #shutdown_value: #cycle_time: 0.100 #hardware_pwm: False #scale: # See the \"output_pin\" section for the definition of these parameters. [pwm_cycle_time] \u00b6 Run-time configurable output pins with dynamic pwm cycle timing (one may define any number of sections with an \"pwm_cycle_time\" prefix). Pins configured here will be setup as output pins and one may modify them at run-time using \"SET_PIN PIN=my_pin VALUE=.1 CYCLE_TIME=0.100\" type extended g-code commands . [pwm_cycle_time my_pin] pin: #value: #shutdown_value: #cycle_time: 0.100 #scale: # See the \"output_pin\" section for information on these parameters. [static_digital_output] \u00b6 Statically configured digital output pins (one may define any number of sections with a \"static_digital_output\" prefix). Pins configured here will be setup as a GPIO output during MCU configuration. They can not be changed at run-time. [static_digital_output my_output_pins] pins: # A comma separated list of pins to be set as GPIO output pins. The # pin will be set to a high level unless the pin name is prefaced # with \"!\". This parameter must be provided. [multi_pin] \u00b6 Multiple pin outputs (one may define any number of sections with a \"multi_pin\" prefix). A multi_pin output creates an internal pin alias that can modify multiple output pins each time the alias pin is set. For example, one could define a \"[multi_pin my_fan]\" object containing two pins and then set \"pin=multi_pin:my_fan\" in the \"[fan]\" section - on each fan change both output pins would be updated. These aliases may not be used with stepper motor pins. [multi_pin my_multi_pin] pins: # A comma separated list of pins associated with this alias. This # parameter must be provided. TMC stepper driver configuration \u00b6 Configuration of Trinamic stepper motor drivers in UART/SPI mode. Additional information is in the TMC Drivers guide and in the command reference . [tmc2130] \u00b6 Configure a TMC2130 stepper motor driver via SPI bus. To use this feature, define a config section with a \"tmc2130\" prefix followed by the name of the corresponding stepper config section (for example, \"[tmc2130 stepper_x]\"). [tmc2130 stepper_x] cs_pin: # The pin corresponding to the TMC2130 chip select line. This pin # will be set to low at the start of SPI messages and raised to high # after the message completes. This parameter must be provided. #spi_speed: #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #chain_position: #chain_length: # These parameters configure an SPI daisy chain. The two parameters # define the stepper position in the chain and the total chain length. # Position 1 corresponds to the stepper that connects to the MOSI signal. # The default is to not use an SPI daisy chain. #interpolate: True # If true, enable step interpolation (the driver will internally # step at a rate of 256 micro-steps). This interpolation does # introduce a small systemic positional deviation - see # TMC_Drivers.md for details. The default is True. run_current: # The amount of current (in amps RMS) to configure the driver to use # during stepper movement. This parameter must be provided. #hold_current: # The amount of current (in amps RMS) to configure the driver to use # when the stepper is not moving. Setting a hold_current is not # recommended (see TMC_Drivers.md for details). The default is to # not reduce the current. #sense_resistor: 0.110 # The resistance (in ohms) of the motor sense resistor. The default # is 0.110 ohms. #stealthchop_threshold: 0 # The velocity (in mm/s) to set the \"stealthChop\" threshold to. When # set, \"stealthChop\" mode will be enabled if the stepper motor # velocity is below this value. Note that the \"sensorless homing\" # code may temporarily override this setting during homing # operations. The default is 0, which disables \"stealthChop\" mode. #coolstep_threshold: # The velocity (in mm/s) to set the TMC driver internal \"CoolStep\" # threshold to. If set, the coolstep feature will be enabled when # the stepper motor velocity is near or above this value. Important # - if coolstep_threshold is set and \"sensorless homing\" is used, # then one must ensure that the homing speed is above the coolstep # threshold! The default is to not enable the coolstep feature. #high_velocity_threshold: # The velocity (in mm/s) to set the TMC driver internal \"high # velocity\" threshold (THIGH) to. This is typically used to disable # the \"CoolStep\" feature at high speeds. The default is to not set a # TMC \"high velocity\" threshold. #driver_MSLUT0: 2863314260 #driver_MSLUT1: 1251300522 #driver_MSLUT2: 608774441 #driver_MSLUT3: 269500962 #driver_MSLUT4: 4227858431 #driver_MSLUT5: 3048961917 #driver_MSLUT6: 1227445590 #driver_MSLUT7: 4211234 #driver_W0: 2 #driver_W1: 1 #driver_W2: 1 #driver_W3: 1 #driver_X1: 128 #driver_X2: 255 #driver_X3: 255 #driver_START_SIN: 0 #driver_START_SIN90: 247 # These fields control the Microstep Table registers directly. The optimal # wave table is specific to each motor and might vary with current. An # optimal configuration will have minimal print artifacts caused by # non-linear stepper movement. The values specified above are the default # values used by the driver. The value must be specified as a decimal integer # (hex form is not supported). In order to compute the wave table fields, # see the tmc2130 \"Calculation Sheet\" from the Trinamic website. #driver_IHOLDDELAY: 8 #driver_TPOWERDOWN: 0 #driver_TBL: 1 #driver_TOFF: 4 #driver_HEND: 7 #driver_HSTRT: 0 #driver_VHIGHFS: 0 #driver_VHIGHCHM: 0 #driver_PWM_AUTOSCALE: True #driver_PWM_FREQ: 1 #driver_PWM_GRAD: 4 #driver_PWM_AMPL: 128 #driver_FREEWHEEL: 0 #driver_SGT: 0 #driver_SEMIN: 0 #driver_SEUP: 0 #driver_SEMAX: 0 #driver_SEDN: 0 #driver_SEIMIN: 0 #driver_SFILT: 0 # Set the given register during the configuration of the TMC2130 # chip. This may be used to set custom motor parameters. The # defaults for each parameter are next to the parameter name in the # above list. #diag0_pin: #diag1_pin: # The micro-controller pin attached to one of the DIAG lines of the # TMC2130 chip. Only a single diag pin should be specified. The pin # is \"active low\" and is thus normally prefaced with \"^!\". Setting # this creates a \"tmc2130_stepper_x:virtual_endstop\" virtual pin # which may be used as the stepper's endstop_pin. Doing this enables # \"sensorless homing\". (Be sure to also set driver_SGT to an # appropriate sensitivity value.) The default is to not enable # sensorless homing. [tmc2208] \u00b6 Configure a TMC2208 (or TMC2224) stepper motor driver via single wire UART. To use this feature, define a config section with a \"tmc2208\" prefix followed by the name of the corresponding stepper config section (for example, \"[tmc2208 stepper_x]\"). [tmc2208 stepper_x] uart_pin: # The pin connected to the TMC2208 PDN_UART line. This parameter # must be provided. #tx_pin: # If using separate receive and transmit lines to communicate with # the driver then set uart_pin to the receive pin and tx_pin to the # transmit pin. The default is to use uart_pin for both reading and # writing. #select_pins: # A comma separated list of pins to set prior to accessing the # tmc2208 UART. This may be useful for configuring an analog mux for # UART communication. The default is to not configure any pins. #interpolate: True # If true, enable step interpolation (the driver will internally # step at a rate of 256 micro-steps). This interpolation does # introduce a small systemic positional deviation - see # TMC_Drivers.md for details. The default is True. run_current: # The amount of current (in amps RMS) to configure the driver to use # during stepper movement. This parameter must be provided. #hold_current: # The amount of current (in amps RMS) to configure the driver to use # when the stepper is not moving. Setting a hold_current is not # recommended (see TMC_Drivers.md for details). The default is to # not reduce the current. #sense_resistor: 0.110 # The resistance (in ohms) of the motor sense resistor. The default # is 0.110 ohms. #stealthchop_threshold: 0 # The velocity (in mm/s) to set the \"stealthChop\" threshold to. When # set, \"stealthChop\" mode will be enabled if the stepper motor # velocity is below this value. Note that the \"sensorless homing\" # code may temporarily override this setting during homing # operations. The default is 0, which disables \"stealthChop\" mode. #driver_MULTISTEP_FILT: True #driver_IHOLDDELAY: 8 #driver_TPOWERDOWN: 20 #driver_TBL: 2 #driver_TOFF: 3 #driver_HEND: 0 #driver_HSTRT: 5 #driver_PWM_AUTOGRAD: True #driver_PWM_AUTOSCALE: True #driver_PWM_LIM: 12 #driver_PWM_REG: 8 #driver_PWM_FREQ: 1 #driver_PWM_GRAD: 14 #driver_PWM_OFS: 36 #driver_FREEWHEEL: 0 # Set the given register during the configuration of the TMC2208 # chip. This may be used to set custom motor parameters. The # defaults for each parameter are next to the parameter name in the # above list. [tmc2209] \u00b6 Configure a TMC2209 stepper motor driver via single wire UART. To use this feature, define a config section with a \"tmc2209\" prefix followed by the name of the corresponding stepper config section (for example, \"[tmc2209 stepper_x]\"). [tmc2209 stepper_x] uart_pin: #tx_pin: #select_pins: #interpolate: True run_current: #hold_current: #sense_resistor: 0.110 #stealthchop_threshold: 0 # See the \"tmc2208\" section for the definition of these parameters. #coolstep_threshold: # The velocity (in mm/s) to set the TMC driver internal \"CoolStep\" # threshold to. If set, the coolstep feature will be enabled when # the stepper motor velocity is near or above this value. Important # - if coolstep_threshold is set and \"sensorless homing\" is used, # then one must ensure that the homing speed is above the coolstep # threshold! The default is to not enable the coolstep feature. #uart_address: # The address of the TMC2209 chip for UART messages (an integer # between 0 and 3). This is typically used when multiple TMC2209 # chips are connected to the same UART pin. The default is zero. #driver_MULTISTEP_FILT: True #driver_IHOLDDELAY: 8 #driver_TPOWERDOWN: 20 #driver_TBL: 2 #driver_TOFF: 3 #driver_HEND: 0 #driver_HSTRT: 5 #driver_PWM_AUTOGRAD: True #driver_PWM_AUTOSCALE: True #driver_PWM_LIM: 12 #driver_PWM_REG: 8 #driver_PWM_FREQ: 1 #driver_PWM_GRAD: 14 #driver_PWM_OFS: 36 #driver_FREEWHEEL: 0 #driver_SGTHRS: 0 #driver_SEMIN: 0 #driver_SEUP: 0 #driver_SEMAX: 0 #driver_SEDN: 0 #driver_SEIMIN: 0 # Set the given register during the configuration of the TMC2209 # chip. This may be used to set custom motor parameters. The # defaults for each parameter are next to the parameter name in the # above list. #diag_pin: # The micro-controller pin attached to the DIAG line of the TMC2209 # chip. The pin is normally prefaced with \"^\" to enable a pullup. # Setting this creates a \"tmc2209_stepper_x:virtual_endstop\" virtual # pin which may be used as the stepper's endstop_pin. Doing this # enables \"sensorless homing\". (Be sure to also set driver_SGTHRS to # an appropriate sensitivity value.) The default is to not enable # sensorless homing. [tmc2660] \u00b6 Configure a TMC2660 stepper motor driver via SPI bus. To use this feature, define a config section with a tmc2660 prefix followed by the name of the corresponding stepper config section (for example, \"[tmc2660 stepper_x]\"). [tmc2660 stepper_x] cs_pin: # The pin corresponding to the TMC2660 chip select line. This pin # will be set to low at the start of SPI messages and set to high # after the message transfer completes. This parameter must be # provided. #spi_speed: 4000000 # SPI bus frequency used to communicate with the TMC2660 stepper # driver. The default is 4000000. #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #interpolate: True # If true, enable step interpolation (the driver will internally # step at a rate of 256 micro-steps). This only works if microsteps # is set to 16. Interpolation does introduce a small systemic # positional deviation - see TMC_Drivers.md for details. The default # is True. run_current: # The amount of current (in amps RMS) used by the driver during # stepper movement. This parameter must be provided. #sense_resistor: # The resistance (in ohms) of the motor sense resistor. This # parameter must be provided. #idle_current_percent: 100 # The percentage of the run_current the stepper driver will be # lowered to when the idle timeout expires (you need to set up the # timeout using a [idle_timeout] config section). The current will # be raised again once the stepper has to move again. Make sure to # set this to a high enough value such that the steppers do not lose # their position. There is also small delay until the current is # raised again, so take this into account when commanding fast moves # while the stepper is idling. The default is 100 (no reduction). #driver_TBL: 2 #driver_RNDTF: 0 #driver_HDEC: 0 #driver_CHM: 0 #driver_HEND: 3 #driver_HSTRT: 3 #driver_TOFF: 4 #driver_SEIMIN: 0 #driver_SEDN: 0 #driver_SEMAX: 0 #driver_SEUP: 0 #driver_SEMIN: 0 #driver_SFILT: 0 #driver_SGT: 0 #driver_SLPH: 0 #driver_SLPL: 0 #driver_DISS2G: 0 #driver_TS2G: 3 # Set the given parameter during the configuration of the TMC2660 # chip. This may be used to set custom driver parameters. The # defaults for each parameter are next to the parameter name in the # list above. See the TMC2660 datasheet about what each parameter # does and what the restrictions on parameter combinations are. Be # especially aware of the CHOPCONF register, where setting CHM to # either zero or one will lead to layout changes (the first bit of # HDEC) is interpreted as the MSB of HSTRT in this case). [tmc2240] \u00b6 Configure a TMC2240 stepper motor driver via SPI bus or UART. To use this feature, define a config section with a \"tmc2240\" prefix followed by the name of the corresponding stepper config section (for example, \"[tmc2240 stepper_x]\"). [tmc2240 stepper_x] cs_pin: # The pin corresponding to the TMC2240 chip select line. This pin # will be set to low at the start of SPI messages and raised to high # after the message completes. This parameter must be provided. #spi_speed: #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #uart_pin: # The pin connected to the TMC2240 DIAG1/SW line. If this parameter # is provided UART communication is used rather then SPI. #chain_position: #chain_length: # These parameters configure an SPI daisy chain. The two parameters # define the stepper position in the chain and the total chain length. # Position 1 corresponds to the stepper that connects to the MOSI signal. # The default is to not use an SPI daisy chain. #interpolate: True # If true, enable step interpolation (the driver will internally # step at a rate of 256 micro-steps). The default is True. run_current: # The amount of current (in amps RMS) to configure the driver to use # during stepper movement. This parameter must be provided. #hold_current: # The amount of current (in amps RMS) to configure the driver to use # when the stepper is not moving. Setting a hold_current is not # recommended (see TMC_Drivers.md for details). The default is to # not reduce the current. #rref: 12000 # The resistance (in ohms) of the resistor between IREF and GND. The # default is 12000. #stealthchop_threshold: 0 # The velocity (in mm/s) to set the \"stealthChop\" threshold to. When # set, \"stealthChop\" mode will be enabled if the stepper motor # velocity is below this value. Note that the \"sensorless homing\" # code may temporarily override this setting during homing # operations. The default is 0, which disables \"stealthChop\" mode. #coolstep_threshold: # The velocity (in mm/s) to set the TMC driver internal \"CoolStep\" # threshold to. If set, the coolstep feature will be enabled when # the stepper motor velocity is near or above this value. Important # - if coolstep_threshold is set and \"sensorless homing\" is used, # then one must ensure that the homing speed is above the coolstep # threshold! The default is to not enable the coolstep feature. #high_velocity_threshold: # The velocity (in mm/s) to set the TMC driver internal \"high # velocity\" threshold (THIGH) to. This is typically used to disable # the \"CoolStep\" feature at high speeds. The default is to not set a # TMC \"high velocity\" threshold. #driver_MSLUT0: 2863314260 #driver_MSLUT1: 1251300522 #driver_MSLUT2: 608774441 #driver_MSLUT3: 269500962 #driver_MSLUT4: 4227858431 #driver_MSLUT5: 3048961917 #driver_MSLUT6: 1227445590 #driver_MSLUT7: 4211234 #driver_W0: 2 #driver_W1: 1 #driver_W2: 1 #driver_W3: 1 #driver_X1: 128 #driver_X2: 255 #driver_X3: 255 #driver_START_SIN: 0 #driver_START_SIN90: 247 #driver_OFFSET_SIN90: 0 # These fields control the Microstep Table registers directly. The optimal # wave table is specific to each motor and might vary with current. An # optimal configuration will have minimal print artifacts caused by # non-linear stepper movement. The values specified above are the default # values used by the driver. The value must be specified as a decimal integer # (hex form is not supported). In order to compute the wave table fields, # see the tmc2130 \"Calculation Sheet\" from the Trinamic website. # Additionally, this driver also has the OFFSET_SIN90 field which can be used # to tune a motor with unbalanced coils. See the `Sine Wave Lookup Table` # section in the datasheet for information about this field and how to tune # it. #driver_MULTISTEP_FILT: True #driver_IHOLDDELAY: 6 #driver_IRUNDELAY: 4 #driver_TPOWERDOWN: 10 #driver_TBL: 2 #driver_TOFF: 3 #driver_HEND: 2 #driver_HSTRT: 5 #driver_FD3: 0 #driver_TPFD: 4 #driver_CHM: 0 #driver_VHIGHFS: 0 #driver_VHIGHCHM: 0 #driver_DISS2G: 0 #driver_DISS2VS: 0 #driver_PWM_AUTOSCALE: True #driver_PWM_AUTOGRAD: True #driver_PWM_FREQ: 0 #driver_FREEWHEEL: 0 #driver_PWM_GRAD: 0 #driver_PWM_OFS: 29 #driver_PWM_REG: 4 #driver_PWM_LIM: 12 #driver_SGT: 0 #driver_SEMIN: 0 #driver_SEUP: 0 #driver_SEMAX: 0 #driver_SEDN: 0 #driver_SEIMIN: 0 #driver_SFILT: 0 #driver_SG4_ANGLE_OFFSET: 1 #driver_SLOPE_CONTROL: 0 # Set the given register during the configuration of the TMC2240 # chip. This may be used to set custom motor parameters. The # defaults for each parameter are next to the parameter name in the # above list. #diag0_pin: #diag1_pin: # The micro-controller pin attached to one of the DIAG lines of the # TMC2240 chip. Only a single diag pin should be specified. The pin # is \"active low\" and is thus normally prefaced with \"^!\". Setting # this creates a \"tmc2240_stepper_x:virtual_endstop\" virtual pin # which may be used as the stepper's endstop_pin. Doing this enables # \"sensorless homing\". (Be sure to also set driver_SGT to an # appropriate sensitivity value.) The default is to not enable # sensorless homing. [tmc5160] \u00b6 Configure a TMC5160 stepper motor driver via SPI bus. To use this feature, define a config section with a \"tmc5160\" prefix followed by the name of the corresponding stepper config section (for example, \"[tmc5160 stepper_x]\"). [tmc5160 stepper_x] cs_pin: # The pin corresponding to the TMC5160 chip select line. This pin # will be set to low at the start of SPI messages and raised to high # after the message completes. This parameter must be provided. #spi_speed: #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #chain_position: #chain_length: # These parameters configure an SPI daisy chain. The two parameters # define the stepper position in the chain and the total chain length. # Position 1 corresponds to the stepper that connects to the MOSI signal. # The default is to not use an SPI daisy chain. #interpolate: True # If true, enable step interpolation (the driver will internally # step at a rate of 256 micro-steps). The default is True. run_current: # The amount of current (in amps RMS) to configure the driver to use # during stepper movement. This parameter must be provided. #hold_current: # The amount of current (in amps RMS) to configure the driver to use # when the stepper is not moving. Setting a hold_current is not # recommended (see TMC_Drivers.md for details). The default is to # not reduce the current. #sense_resistor: 0.075 # The resistance (in ohms) of the motor sense resistor. The default # is 0.075 ohms. #stealthchop_threshold: 0 # The velocity (in mm/s) to set the \"stealthChop\" threshold to. When # set, \"stealthChop\" mode will be enabled if the stepper motor # velocity is below this value. Note that the \"sensorless homing\" # code may temporarily override this setting during homing # operations. The default is 0, which disables \"stealthChop\" mode. #coolstep_threshold: # The velocity (in mm/s) to set the TMC driver internal \"CoolStep\" # threshold to. If set, the coolstep feature will be enabled when # the stepper motor velocity is near or above this value. Important # - if coolstep_threshold is set and \"sensorless homing\" is used, # then one must ensure that the homing speed is above the coolstep # threshold! The default is to not enable the coolstep feature. #high_velocity_threshold: # The velocity (in mm/s) to set the TMC driver internal \"high # velocity\" threshold (THIGH) to. This is typically used to disable # the \"CoolStep\" feature at high speeds. The default is to not set a # TMC \"high velocity\" threshold. #driver_MSLUT0: 2863314260 #driver_MSLUT1: 1251300522 #driver_MSLUT2: 608774441 #driver_MSLUT3: 269500962 #driver_MSLUT4: 4227858431 #driver_MSLUT5: 3048961917 #driver_MSLUT6: 1227445590 #driver_MSLUT7: 4211234 #driver_W0: 2 #driver_W1: 1 #driver_W2: 1 #driver_W3: 1 #driver_X1: 128 #driver_X2: 255 #driver_X3: 255 #driver_START_SIN: 0 #driver_START_SIN90: 247 # These fields control the Microstep Table registers directly. The optimal # wave table is specific to each motor and might vary with current. An # optimal configuration will have minimal print artifacts caused by # non-linear stepper movement. The values specified above are the default # values used by the driver. The value must be specified as a decimal integer # (hex form is not supported). In order to compute the wave table fields, # see the tmc2130 \"Calculation Sheet\" from the Trinamic website. #driver_MULTISTEP_FILT: True #driver_IHOLDDELAY: 6 #driver_TPOWERDOWN: 10 #driver_TBL: 2 #driver_TOFF: 3 #driver_HEND: 2 #driver_HSTRT: 5 #driver_FD3: 0 #driver_TPFD: 4 #driver_CHM: 0 #driver_VHIGHFS: 0 #driver_VHIGHCHM: 0 #driver_DISS2G: 0 #driver_DISS2VS: 0 #driver_PWM_AUTOSCALE: True #driver_PWM_AUTOGRAD: True #driver_PWM_FREQ: 0 #driver_FREEWHEEL: 0 #driver_PWM_GRAD: 0 #driver_PWM_OFS: 30 #driver_PWM_REG: 4 #driver_PWM_LIM: 12 #driver_SGT: 0 #driver_SEMIN: 0 #driver_SEUP: 0 #driver_SEMAX: 0 #driver_SEDN: 0 #driver_SEIMIN: 0 #driver_SFILT: 0 #driver_DRVSTRENGTH: 0 #driver_BBMCLKS: 4 #driver_BBMTIME: 0 #driver_FILT_ISENSE: 0 # Set the given register during the configuration of the TMC5160 # chip. This may be used to set custom motor parameters. The # defaults for each parameter are next to the parameter name in the # above list. #diag0_pin: #diag1_pin: # The micro-controller pin attached to one of the DIAG lines of the # TMC5160 chip. Only a single diag pin should be specified. The pin # is \"active low\" and is thus normally prefaced with \"^!\". Setting # this creates a \"tmc5160_stepper_x:virtual_endstop\" virtual pin # which may be used as the stepper's endstop_pin. Doing this enables # \"sensorless homing\". (Be sure to also set driver_SGT to an # appropriate sensitivity value.) The default is to not enable # sensorless homing. Run-time stepper motor current configuration \u00b6 [ad5206] \u00b6 Statically configured AD5206 digipots connected via SPI bus (one may define any number of sections with an \"ad5206\" prefix). [ad5206 my_digipot] enable_pin: # The pin corresponding to the AD5206 chip select line. This pin # will be set to low at the start of SPI messages and raised to high # after the message completes. This parameter must be provided. #spi_speed: #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #channel_1: #channel_2: #channel_3: #channel_4: #channel_5: #channel_6: # The value to statically set the given AD5206 channel to. This is # typically set to a number between 0.0 and 1.0 with 1.0 being the # highest resistance and 0.0 being the lowest resistance. However, # the range may be changed with the 'scale' parameter (see below). # If a channel is not specified then it is left unconfigured. #scale: # This parameter can be used to alter how the 'channel_x' parameters # are interpreted. If provided, then the 'channel_x' parameters # should be between 0.0 and 'scale'. This may be useful when the # AD5206 is used to set stepper voltage references. The 'scale' can # be set to the equivalent stepper amperage if the AD5206 were at # its highest resistance, and then the 'channel_x' parameters can be # specified using the desired amperage value for the stepper. The # default is to not scale the 'channel_x' parameters. [mcp4451] \u00b6 Statically configured MCP4451 digipot connected via I2C bus (one may define any number of sections with an \"mcp4451\" prefix). [mcp4451 my_digipot] i2c_address: # The i2c address that the chip is using on the i2c bus. This # parameter must be provided. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #wiper_0: #wiper_1: #wiper_2: #wiper_3: # The value to statically set the given MCP4451 \"wiper\" to. This is # typically set to a number between 0.0 and 1.0 with 1.0 being the # highest resistance and 0.0 being the lowest resistance. However, # the range may be changed with the 'scale' parameter (see below). # If a wiper is not specified then it is left unconfigured. #scale: # This parameter can be used to alter how the 'wiper_x' parameters # are interpreted. If provided, then the 'wiper_x' parameters should # be between 0.0 and 'scale'. This may be useful when the MCP4451 is # used to set stepper voltage references. The 'scale' can be set to # the equivalent stepper amperage if the MCP4451 were at its highest # resistance, and then the 'wiper_x' parameters can be specified # using the desired amperage value for the stepper. The default is # to not scale the 'wiper_x' parameters. [mcp4728] \u00b6 Statically configured MCP4728 digital-to-analog converter connected via I2C bus (one may define any number of sections with an \"mcp4728\" prefix). [mcp4728 my_dac] #i2c_address: 96 # The i2c address that the chip is using on the i2c bus. The default # is 96. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #channel_a: #channel_b: #channel_c: #channel_d: # The value to statically set the given MCP4728 channel to. This is # typically set to a number between 0.0 and 1.0 with 1.0 being the # highest voltage (2.048V) and 0.0 being the lowest voltage. # However, the range may be changed with the 'scale' parameter (see # below). If a channel is not specified then it is left # unconfigured. #scale: # This parameter can be used to alter how the 'channel_x' parameters # are interpreted. If provided, then the 'channel_x' parameters # should be between 0.0 and 'scale'. This may be useful when the # MCP4728 is used to set stepper voltage references. The 'scale' can # be set to the equivalent stepper amperage if the MCP4728 were at # its highest voltage (2.048V), and then the 'channel_x' parameters # can be specified using the desired amperage value for the # stepper. The default is to not scale the 'channel_x' parameters. [mcp4018] \u00b6 Statically configured MCP4018 digipot connected via i2c (one may define any number of sections with an \"mcp4018\" prefix). [mcp4018 my_digipot] #i2c_address: 47 # The i2c address that the chip is using on the i2c bus. The default # is 47. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. wiper: # The value to statically set the given MCP4018 \"wiper\" to. This is # typically set to a number between 0.0 and 1.0 with 1.0 being the # highest resistance and 0.0 being the lowest resistance. However, # the range may be changed with the 'scale' parameter (see below). # This parameter must be provided. #scale: # This parameter can be used to alter how the 'wiper' parameter is # interpreted. If provided, then the 'wiper' parameter should be # between 0.0 and 'scale'. This may be useful when the MCP4018 is # used to set stepper voltage references. The 'scale' can be set to # the equivalent stepper amperage if the MCP4018 is at its highest # resistance, and then the 'wiper' parameter can be specified using # the desired amperage value for the stepper. The default is to not # scale the 'wiper' parameter. Display support \u00b6 [display] \u00b6 Support for a display attached to the micro-controller. [display] lcd_type: # The type of LCD chip in use. This may be \"hd44780\", \"hd44780_spi\", # \"aip31068_spi\", \"st7920\", \"emulated_st7920\", \"uc1701\", \"ssd1306\", or # \"sh1106\". # See the display sections below for information on each type and # additional parameters they provide. This parameter must be # provided. #display_group: # The name of the display_data group to show on the display. This # controls the content of the screen (see the \"display_data\" section # for more information). The default is _default_20x4 for hd44780 or # aip31068_spi displays and _default_16x4 for other displays. #menu_timeout: # Timeout for menu. Being inactive this amount of seconds will # trigger menu exit or return to root menu when having autorun # enabled. The default is 0 seconds (disabled) #menu_root: # Name of the main menu section to show when clicking the encoder # on the home screen. The defaults is __main, and this shows the # the default menus as defined in klippy/extras/display/menu.cfg #menu_reverse_navigation: # When enabled it will reverse up and down directions for list # navigation. The default is False. This parameter is optional. #encoder_pins: # The pins connected to encoder. 2 pins must be provided when using # encoder. This parameter must be provided when using menu. #encoder_steps_per_detent: # How many steps the encoder emits per detent (\"click\"). If the # encoder takes two detents to move between entries or moves two # entries from one detent, try changing this. Allowed values are 2 # (half-stepping) or 4 (full-stepping). The default is 4. #click_pin: # The pin connected to 'enter' button or encoder 'click'. This # parameter must be provided when using menu. The presence of an # 'analog_range_click_pin' config parameter turns this parameter # from digital to analog. #back_pin: # The pin connected to 'back' button. This parameter is optional, # menu can be used without it. The presence of an # 'analog_range_back_pin' config parameter turns this parameter from # digital to analog. #up_pin: # The pin connected to 'up' button. This parameter must be provided # when using menu without encoder. The presence of an # 'analog_range_up_pin' config parameter turns this parameter from # digital to analog. #down_pin: # The pin connected to 'down' button. This parameter must be # provided when using menu without encoder. The presence of an # 'analog_range_down_pin' config parameter turns this parameter from # digital to analog. #kill_pin: # The pin connected to 'kill' button. This button will call # emergency stop. The presence of an 'analog_range_kill_pin' config # parameter turns this parameter from digital to analog. #analog_pullup_resistor: 4700 # The resistance (in ohms) of the pullup attached to the analog # button. The default is 4700 ohms. #analog_range_click_pin: # The resistance range for a 'enter' button. Range minimum and # maximum comma-separated values must be provided when using analog # button. #analog_range_back_pin: # The resistance range for a 'back' button. Range minimum and # maximum comma-separated values must be provided when using analog # button. #analog_range_up_pin: # The resistance range for a 'up' button. Range minimum and maximum # comma-separated values must be provided when using analog button. #analog_range_down_pin: # The resistance range for a 'down' button. Range minimum and # maximum comma-separated values must be provided when using analog # button. #analog_range_kill_pin: # The resistance range for a 'kill' button. Range minimum and # maximum comma-separated values must be provided when using analog # button. hd44780 display \u00b6 Information on configuring hd44780 displays (which is used in \"RepRapDiscount 2004 Smart Controller\" type displays). [display] lcd_type: hd44780 # Set to \"hd44780\" for hd44780 displays. rs_pin: e_pin: d4_pin: d5_pin: d6_pin: d7_pin: # The pins connected to an hd44780 type lcd. These parameters must # be provided. #hd44780_protocol_init: True # Perform 8-bit/4-bit protocol initialization on an hd44780 display. # This is necessary on real hd44780 devices. However, one may need # to disable this on some \"clone\" devices. The default is True. #line_length: # Set the number of characters per line for an hd44780 type lcd. # Possible values are 20 (default) and 16. The number of lines is # fixed to 4. ... hd44780_spi display \u00b6 Information on configuring an hd44780_spi display - a 20x04 display controlled via a hardware \"shift register\" (which is used in mightyboard based printers). [display] lcd_type: hd44780_spi # Set to \"hd44780_spi\" for hd44780_spi displays. latch_pin: spi_software_sclk_pin: spi_software_mosi_pin: spi_software_miso_pin: # The pins connected to the shift register controlling the display. # The spi_software_miso_pin needs to be set to an unused pin of the # printer mainboard as the shift register does not have a MISO pin, # but the software spi implementation requires this pin to be # configured. #hd44780_protocol_init: True # Perform 8-bit/4-bit protocol initialization on an hd44780 display. # This is necessary on real hd44780 devices. However, one may need # to disable this on some \"clone\" devices. The default is True. #line_length: # Set the number of characters per line for an hd44780 type lcd. # Possible values are 20 (default) and 16. The number of lines is # fixed to 4. ... aip31068_spi display \u00b6 Information on configuring an aip31068_spi display - a very similar to hd44780_spi a 20x04 (20 symbols by 4 lines) display with slightly different internal protocol. [display] lcd_type: aip31068_spi latch_pin: spi_software_sclk_pin: spi_software_mosi_pin: spi_software_miso_pin: # The pins connected to the shift register controlling the display. # The spi_software_miso_pin needs to be set to an unused pin of the # printer mainboard as the shift register does not have a MISO pin, # but the software spi implementation requires this pin to be # configured. #line_length: # Set the number of characters per line for an hd44780 type lcd. # Possible values are 20 (default) and 16. The number of lines is # fixed to 4. ... st7920 display \u00b6 Information on configuring st7920 displays (which is used in \"RepRapDiscount 12864 Full Graphic Smart Controller\" type displays). [display] lcd_type: st7920 # Set to \"st7920\" for st7920 displays. cs_pin: sclk_pin: sid_pin: # The pins connected to an st7920 type lcd. These parameters must be # provided. ... emulated_st7920 display \u00b6 Information on configuring an emulated st7920 display - found in some \"2.4 inch touchscreen devices\" and similar. [display] lcd_type: emulated_st7920 # Set to \"emulated_st7920\" for emulated_st7920 displays. en_pin: spi_software_sclk_pin: spi_software_mosi_pin: spi_software_miso_pin: # The pins connected to an emulated_st7920 type lcd. The en_pin # corresponds to the cs_pin of the st7920 type lcd, # spi_software_sclk_pin corresponds to sclk_pin and # spi_software_mosi_pin corresponds to sid_pin. The # spi_software_miso_pin needs to be set to an unused pin of the # printer mainboard as the st7920 as no MISO pin but the software # spi implementation requires this pin to be configured. ... uc1701 display \u00b6 Information on configuring uc1701 displays (which is used in \"MKS Mini 12864\" type displays). [display] lcd_type: uc1701 # Set to \"uc1701\" for uc1701 displays. cs_pin: a0_pin: # The pins connected to a uc1701 type lcd. These parameters must be # provided. #rst_pin: # The pin connected to the \"rst\" pin on the lcd. If it is not # specified then the hardware must have a pull-up on the # corresponding lcd line. #contrast: # The contrast to set. The value may range from 0 to 63 and the # default is 40. ... ssd1306 and sh1106 displays \u00b6 Information on configuring ssd1306 and sh1106 displays. [display] lcd_type: # Set to either \"ssd1306\" or \"sh1106\" for the given display type. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # Optional parameters available for displays connected via an i2c # bus. See the \"common I2C settings\" section for a description of # the above parameters. #cs_pin: #dc_pin: #spi_speed: #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # The pins connected to the lcd when in \"4-wire\" spi mode. See the # \"common SPI settings\" section for a description of the parameters # that start with \"spi_\". The default is to use i2c mode for the # display. #reset_pin: # A reset pin may be specified on the display. If it is not # specified then the hardware must have a pull-up on the # corresponding lcd line. #contrast: # The contrast to set. The value may range from 0 to 256 and the # default is 239. #vcomh: 0 # Set the Vcomh value on the display. This value is associated with # a \"smearing\" effect on some OLED displays. The value may range # from 0 to 63. Default is 0. #invert: False # TRUE inverts the pixels on certain OLED displays. The default is # False. #x_offset: 0 # Set the horizontal offset value on SH1106 displays. The default is # 0. ... [display_data] \u00b6 Support for displaying custom data on an lcd screen. One may create any number of display groups and any number of data items under those groups. The display will show all the data items for a given group if the display_group option in the [display] section is set to the given group name. A default set of display groups are automatically created. One can replace or extend these display_data items by overriding the defaults in the main printer.cfg config file. [display_data my_group_name my_data_name] position: # Comma separated row and column of the display position that should # be used to display the information. This parameter must be # provided. text: # The text to show at the given position. This field is evaluated # using command templates (see docs/Command_Templates.md). This # parameter must be provided. [display_template] \u00b6 Display data text \"macros\" (one may define any number of sections with a display_template prefix). See the command templates document for information on template evaluation. This feature allows one to reduce repetitive definitions in display_data sections. One may use the builtin render() function in display_data sections to evaluate a template. For example, if one were to define [display_template my_template] then one could use { render('my_template') } in a display_data section. This feature can also be used for continuous LED updates using the SET_LED_TEMPLATE command. [display_template my_template_name] #param_<name>: # One may specify any number of options with a \"param_\" prefix. The # given name will be assigned the given value (parsed as a Python # literal) and will be available during macro expansion. If the # parameter is passed in the call to render() then that value will # be used during macro expansion. For example, a config with # \"param_speed = 75\" might have a caller with # \"render('my_template_name', param_speed=80)\". Parameter names may # not use upper case characters. text: # The text to return when the this template is rendered. This field # is evaluated using command templates (see # docs/Command_Templates.md). This parameter must be provided. [display_glyph] \u00b6 Display a custom glyph on displays that support it. The given name will be assigned the given display data which can then be referenced in the display templates by their name surrounded by two \"tilde\" symbols i.e. ~my_display_glyph~ See sample-glyphs.cfg for some examples. [display_glyph my_display_glyph] #data: # The display data, stored as 16 lines consisting of 16 bits (1 per # pixel) where '.' is a blank pixel and '*' is an on pixel (e.g., # \"****************\" to display a solid horizontal line). # Alternatively, one can use '0' for a blank pixel and '1' for an on # pixel. Put each display line into a separate config line. The # glyph must consist of exactly 16 lines with 16 bits each. This # parameter is optional. #hd44780_data: # Glyph to use on 20x4 hd44780 displays. The glyph must consist of # exactly 8 lines with 5 bits each. This parameter is optional. #hd44780_slot: # The hd44780 hardware index (0..7) to store the glyph at. If # multiple distinct images use the same slot then make sure to only # use one of those images in any given screen. This parameter is # required if hd44780_data is specified. [display my_extra_display] \u00b6 If a primary [display] section has been defined in printer.cfg as shown above it is possible to define multiple auxiliary displays. Note that auxiliary displays do not currently support menu functionality, thus they do not support the \"menu\" options or button configuration. [display my_extra_display] # See the \"display\" section for available parameters. [menu] \u00b6 Customizable lcd display menus. A default set of menus are automatically created. One can replace or extend the menu by overriding the defaults in the main printer.cfg config file. See the command template document for information on menu attributes available during template rendering. # Common parameters available for all menu config sections. #[menu __some_list __some_name] #type: disabled # Permanently disabled menu element, only required attribute is 'type'. # Allows you to easily disable/hide existing menu items. #[menu some_name] #type: # One of command, input, list, text: # command - basic menu element with various script triggers # input - same like 'command' but has value changing capabilities. # Press will start/stop edit mode. # list - it allows for menu items to be grouped together in a # scrollable list. Add to the list by creating menu # configurations using \"some_list\" as a prefix - for # example: [menu some_list some_item_in_the_list] # vsdlist - same as 'list' but will append files from virtual sdcard # (will be removed in the future) #name: # Name of menu item - evaluated as a template. #enable: # Template that evaluates to True or False. #index: # Position where an item needs to be inserted in list. By default # the item is added at the end. #[menu some_list] #type: list #name: #enable: # See above for a description of these parameters. #[menu some_list some_command] #type: command #name: #enable: # See above for a description of these parameters. #gcode: # Script to run on button click or long click. Evaluated as a # template. #[menu some_list some_input] #type: input #name: #enable: # See above for a description of these parameters. #input: # Initial value to use when editing - evaluated as a template. # Result must be float. #input_min: # Minimum value of range - evaluated as a template. Default -99999. #input_max: # Maximum value of range - evaluated as a template. Default 99999. #input_step: # Editing step - Must be a positive integer or float value. It has # internal fast rate step. When \"(input_max - input_min) / # input_step > 100\" then fast rate step is 10 * input_step else fast # rate step is same input_step. #realtime: # This attribute accepts static boolean value. When enabled then # gcode script is run after each value change. The default is False. #gcode: # Script to run on button click, long click or value change. # Evaluated as a template. The button click will trigger the edit # mode start or end. Filament sensors \u00b6 [filament_switch_sensor] \u00b6 Filament Switch Sensor. Support for filament insert and runout detection using a switch sensor, such as an endstop switch. See the command reference for more information. [filament_switch_sensor my_sensor] #pause_on_runout: True # When set to True, a PAUSE will execute immediately after a runout # is detected. Note that if pause_on_runout is False and the # runout_gcode is omitted then runout detection is disabled. Default # is True. #runout_gcode: # A list of G-Code commands to execute after a filament runout is # detected. See docs/Command_Templates.md for G-Code format. If # pause_on_runout is set to True this G-Code will run after the # PAUSE is complete. The default is not to run any G-Code commands. #insert_gcode: # A list of G-Code commands to execute after a filament insert is # detected. See docs/Command_Templates.md for G-Code format. The # default is not to run any G-Code commands, which disables insert # detection. #event_delay: 3.0 # The minimum amount of time in seconds to delay between events. # Events triggered during this time period will be silently # ignored. The default is 3 seconds. #pause_delay: 0.5 # The amount of time to delay, in seconds, between the pause command # dispatch and execution of the runout_gcode. It may be useful to # increase this delay if OctoPrint exhibits strange pause behavior. # Default is 0.5 seconds. #debounce_delay: # A period of time in seconds to debounce events prior to running the # switch gcode. The switch must he held in a single state for at least # this long to activate. If the switch is toggled on/off during this delay, # the event is ignored. Default is 0. #switch_pin: # The pin on which the switch is connected. This parameter must be # provided. [filament_motion_sensor] \u00b6 Filament Motion Sensor. Support for filament insert and runout detection using an encoder that toggles the output pin during filament movement through the sensor. See the command reference for more information. [filament_motion_sensor my_sensor] detection_length: 7.0 # The minimum length of filament pulled through the sensor to trigger # a state change on the switch_pin # Default is 7 mm. extruder: # The name of the extruder or extruder_stepper section this sensor # is associated with. This parameter must be provided. switch_pin: #pause_on_runout: #runout_gcode: #insert_gcode: #event_delay: #pause_delay: # See the \"filament_switch_sensor\" section for a description of the # above parameters. [tsl1401cl_filament_width_sensor] \u00b6 TSLl401CL Based Filament Width Sensor. See the guide for more information. [tsl1401cl_filament_width_sensor] #pin: #default_nominal_filament_diameter: 1.75 # (mm) # Maximum allowed filament diameter difference as mm. #max_difference: 0.2 # The distance from sensor to the melting chamber as mm. #measurement_delay: 100 [hall_filament_width_sensor] \u00b6 Hall filament width sensor (see Hall Filament Width Sensor ). [hall_filament_width_sensor] adc1: adc2: # Analog input pins connected to the sensor. These parameters must # be provided. #cal_dia1: 1.50 #cal_dia2: 2.00 # The calibration values (in mm) for the sensors. The default is # 1.50 for cal_dia1 and 2.00 for cal_dia2. #raw_dia1: 9500 #raw_dia2: 10500 # The raw calibration values for the sensors. The default is 9500 # for raw_dia1 and 10500 for raw_dia2. #default_nominal_filament_diameter: 1.75 # The nominal filament diameter. This parameter must be provided. #max_difference: 0.200 # Maximum allowed filament diameter difference in millimeters (mm). # If difference between nominal filament diameter and sensor output # is more than +- max_difference, extrusion multiplier is set back # to %100. The default is 0.200. #measurement_delay: 70 # The distance from sensor to the melting chamber/hot-end in # millimeters (mm). The filament between the sensor and the hot-end # will be treated as the default_nominal_filament_diameter. Host # module works with FIFO logic. It keeps each sensor value and # position in an array and POP them back in correct position. This # parameter must be provided. #enable: False # Sensor enabled or disabled after power on. The default is to # disable. #measurement_interval: 10 # The approximate distance (in mm) between sensor readings. The # default is 10mm. #logging: False # Out diameter to terminal and klipper.log can be turn on|of by # command. #min_diameter: 1.0 # Minimal diameter for trigger virtual filament_switch_sensor. #max_diameter: # Maximum diameter for triggering virtual filament_switch_sensor. # The default is default_nominal_filament_diameter + max_difference. #use_current_dia_while_delay: False # Use the current diameter instead of the nominal diameter while # the measurement delay has not run through. #pause_on_runout: #runout_gcode: #insert_gcode: #event_delay: #pause_delay: # See the \"filament_switch_sensor\" section for a description of the # above parameters. Load Cells \u00b6 [load_cell] \u00b6 Load Cell. Uses an ADC sensor attached to a load cell to create a digital scale. [load_cell] sensor_type: # This must be one of the supported sensor types, see below. #counts_per_gram: # The floating point number of sensor counts that indicates 1 gram of force. # This value is calculated by the LOAD_CELL_CALIBRATE command. #reference_tare_counts: # The integer tare value, in raw sensor counts, taken when LOAD_CELL_CALIBRATE # is run. This is the default tare value when klipper starts up. #sensor_orientation: # Change the sensor's orientation. Can be either 'normal' or 'inverted'. # The default is 'normal'. Use 'inverted' if the sensor reports a # decreasing force value when placed under load. HX711 \u00b6 This is a 24 bit low sample rate chip using \"bit-bang\" communications. It is suitable for filament scales. [load_cell] sensor_type: hx711 sclk_pin: # The pin connected to the HX711 clock line. This parameter must be provided. dout_pin: # The pin connected to the HX711 data output line. This parameter must be # provided. #gain: A-128 # Valid values for gain are: A-128, A-64, B-32. The default is A-128. # 'A' denotes the input channel and the number denotes the gain. Only the 3 # listed combinations are supported by the chip. Note that changing the gain # setting also selects the channel being read. #sample_rate: 80 # Valid values for sample_rate are 80 or 10. The default value is 80. # This must match the wiring of the chip. The sample rate cannot be changed # in software. HX717 \u00b6 This is the 4x higher sample rate version of the HX711, suitable for probing. [load_cell] sensor_type: hx717 sclk_pin: # The pin connected to the HX717 clock line. This parameter must be provided. dout_pin: # The pin connected to the HX717 data output line. This parameter must be # provided. #gain: A-128 # Valid values for gain are A-128, B-64, A-64, B-8. # 'A' denotes the input channel and the number denotes the gain setting. # Only the 4 listed combinations are supported by the chip. Note that # changing the gain setting also selects the channel being read. #sample_rate: 320 # Valid values for sample_rate are: 10, 20, 80, 320. The default is 320. # This must match the wiring of the chip. The sample rate cannot be changed # in software. ADS1220 \u00b6 The ADS1220 is a 24 bit ADC supporting up to a 2Khz sample rate configurable in software. [load_cell] sensor_type: ads1220 cs_pin: # The pin connected to the ADS1220 chip select line. This parameter must # be provided. #spi_speed: 512000 # This chip supports 2 speeds: 256000 or 512000. The faster speed is only # enabled when one of the Turbo sample rates is used. The correct spi_speed # is selected based on the sample rate. #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. data_ready_pin: # Pin connected to the ADS1220 data ready line. This parameter must be # provided. #gain: 128 # Valid gain values are 128, 64, 32, 16, 8, 4, 2, 1 # The default is 128 #pga_bypass: False # Disable the internal Programmable Gain Amplifier. If # True the PGA will be disabled for gains 1, 2, and 4. The PGA is always # enabled for gain settings 8 to 128, regardless of the pga_bypass setting. # If AVSS is used as an input pga_bypass is forced to True. # The default is False. #sample_rate: 660 # This chip supports two ranges of sample rates, Normal and Turbo. In turbo # mode the chip's internal clock runs twice as fast and the SPI communication # speed is also doubled. # Normal sample rates: 20, 45, 90, 175, 330, 600, 1000 # Turbo sample rates: 40, 90, 180, 350, 660, 1200, 2000 # The default is 660 #input_mux: # Input multiplexer configuration, select a pair of pins to use. The first pin # is the positive, AINP, and the second pin is the negative, AINN. Valid # values are: 'AIN0_AIN1', 'AIN0_AIN2', 'AIN0_AIN3', 'AIN1_AIN2', 'AIN1_AIN3', # 'AIN2_AIN3', 'AIN1_AIN0', 'AIN3_AIN2', 'AIN0_AVSS', 'AIN1_AVSS', 'AIN2_AVSS' # and 'AIN3_AVSS'. If AVSS is used the PGA is bypassed and the pga_bypass # setting will be forced to True. # The default is AIN0_AIN1. #vref: # The selected voltage reference. Valid values are: 'internal', 'REF0', 'REF1' # and 'analog_supply'. Default is 'internal'. [load_cell_probe] \u00b6 Load Cell Probe. This combines the functionality of a [probe] and a [load_cell]. [load_cell_probe] sensor_type: # This must be one of the supported bulk ADC sensor types and support # load cell endstops on the mcu. #counts_per_gram: #reference_tare_counts: #sensor_orientation: # These parameters must be configured before the probe will operate. # See the [load_cell] section for further details. #force_safety_limit: 2000 # The safe limit for probing force relative to the reference_tare_counts on # the load_cell. The default is +/-2Kg. #trigger_force: 75.0 # The force that the probe will trigger at. 75g is the default. #drift_filter_cutoff_frequency: 0.8 # Enable optional continuous taring while homing & probing to reject drift. # The value is a frequency, in Hz, below which drift will be ignored. This # option requires the SciPy library. Default: None #drift_filter_delay: 2 # The delay, or 'order', of the drift filter. This controls the number of # samples required to make a trigger detection. Can be 1 or 2, the default # is 2. #buzz_filter_cutoff_frequency: 100.0 # The value is a frequency, in Hz, above which high frequency noise in the # load cell will be igfiltered outnored. This option requires the SciPy # library. Default: None #buzz_filter_delay: 2 # The delay, or 'order', of the buzz filter. This controls the number of # samples required to make a trigger detection. Can be 1 or 2, the default # is 2. #notch_filter_frequencies: 50, 60 # 1 or 2 frequencies, in Hz, to filter out of the load cell data. This is # intended to reject power line noise. This option requires the SciPy # library. Default: None #notch_filter_quality: 2.0 # Controls how narrow the range of frequencies are that the notch filter # removes. Larger numbers produce a narrower filter. Minimum value is 0.5 and # maximum is 3.0. Default: 2.0 #tare_time: # The rime in seconds used for taring the load_cell before each probe. The # default value is: 4 / 60 = 0.066. This collects samples from 4 cycles of # 60Hz mains power to cancel power line noise. #z_offset: #speed: #samples: #sample_retract_dist: #lift_speed: #samples_result: #samples_tolerance: #samples_tolerance_retries: #activate_gcode: #deactivate_gcode: # See the \"[probe]\" section for a description of the above parameters. Board specific hardware support \u00b6 [sx1509] \u00b6 Configure an SX1509 I2C to GPIO expander. Due to the delay incurred by I2C communication you should NOT use SX1509 pins as stepper enable, step or dir pins or any other pin that requires fast bit-banging. They are best used as static or gcode controlled digital outputs or hardware-pwm pins for e.g. fans. One may define any number of sections with an \"sx1509\" prefix. Each expander provides a set of 16 pins (sx1509_my_sx1509:PIN_0 to sx1509_my_sx1509:PIN_15) which can be used in the printer configuration. See the generic-duet2-duex.cfg file for an example. [sx1509 my_sx1509] i2c_address: # I2C address used by this expander. Depending on the hardware # jumpers this is one out of the following addresses: 62 63 112 # 113. This parameter must be provided. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. [samd_sercom] \u00b6 SAMD SERCOM configuration to specify which pins to use on a given SERCOM. One may define any number of sections with a \"samd_sercom\" prefix. Each SERCOM must be configured prior to using it as SPI or I2C peripheral. Place this config section above any other section that makes use of SPI or I2C buses. [samd_sercom my_sercom] sercom: # The name of the sercom bus to configure in the micro-controller. # Available names are \"sercom0\", \"sercom1\", etc.. This parameter # must be provided. tx_pin: # MOSI pin for SPI communication, or SDA (data) pin for I2C # communication. The pin must have a valid pinmux configuration # for the given SERCOM peripheral. This parameter must be provided. #rx_pin: # MISO pin for SPI communication. This pin is not used for I2C # communication (I2C uses tx_pin for both sending and receiving). # The pin must have a valid pinmux configuration for the given # SERCOM peripheral. This parameter is optional. clk_pin: # CLK pin for SPI communication, or SCL (clock) pin for I2C # communication. The pin must have a valid pinmux configuration # for the given SERCOM peripheral. This parameter must be provided. [adc_scaled] \u00b6 Duet2 Maestro analog scaling by vref and vssa readings. Defining an adc_scaled section enables virtual adc pins (such as \"my_name:PB0\") that are automatically adjusted by the board's vref and vssa monitoring pins. Be sure to define this config section above any config sections that use one these virtual pins. See the generic-duet2-maestro.cfg file for an example. [adc_scaled my_name] vref_pin: # The ADC pin to use for VREF monitoring. This parameter must be # provided. vssa_pin: # The ADC pin to use for VSSA monitoring. This parameter must be # provided. #smooth_time: 2.0 # A time value (in seconds) over which the vref and vssa # measurements will be smoothed to reduce the impact of measurement # noise. The default is 2 seconds. [ads1x1x] \u00b6 ADS1013, ADS1014, ADS1015, ADS1113, ADS1114 and ADS1115 are I2C based Analog to Digital Converters that can be used for temperature sensors. They provide 4 analog input pins either as single line or as differential input. Note: Use caution if using this sensor to control heaters. The heater min_temp and max_temp are only verified in the host and only if the host is running and operating normally. (ADC inputs directly connected to the micro-controller verify min_temp and max_temp within the micro-controller and do not require a working connection to the host.) [ads1x1x my_ads1x1x] chip: ADS1115 #pga: 4.096V # Default value is 4.096V. The maximum voltage range used for the input. This # scales all values read from the ADC. Options are: 6.144V, 4.096V, 2.048V, # 1.024V, 0.512V, 0.256V #adc_voltage: 3.3 # The supply voltage for the device. This allows additional software scaling # for all values read from the ADC. i2c_mcu: host i2c_bus: i2c.1 #address_pin: GND # Default value is GND. There can be up to four addressed devices depending # upon wiring of the device. Check the datasheet for details. The i2c_address # can be specified directly instead of using the address_pin. The chip provides pins that can be used on other sensors. sensor_type: ... # Can be any thermistor or adc_temperature. sensor_pin: my_ads1x1x:AIN0 # A combination of the name of the ads1x1x chip and the pin. Possible # pin values are AIN0, AIN1, AIN2 and AIN3 for single ended lines and # DIFF01, DIFF03, DIFF13 and DIFF23 for differential between their # corresponding lines. For example # DIFF03 measures the differential between line 0 and 3. Only specific # combinations for the differentials are allowed. [replicape] \u00b6 Replicape support - see the beaglebone guide and the generic-replicape.cfg file for an example. # The \"replicape\" config section adds \"replicape:stepper_x_enable\" # virtual stepper enable pins (for steppers X, Y, Z, E, and H) and # \"replicape:power_x\" PWM output pins (for hotbed, e, h, fan0, fan1, # fan2, and fan3) that may then be used elsewhere in the config file. [replicape] revision: # The replicape hardware revision. Currently only revision \"B3\" is # supported. This parameter must be provided. #enable_pin: !gpio0_20 # The replicape global enable pin. The default is !gpio0_20 (aka # P9_41). host_mcu: # The name of the mcu config section that communicates with the # Klipper \"linux process\" mcu instance. This parameter must be # provided. #standstill_power_down: False # This parameter controls the CFG6_ENN line on all stepper # motors. True sets the enable lines to \"open\". The default is # False. #stepper_x_microstep_mode: #stepper_y_microstep_mode: #stepper_z_microstep_mode: #stepper_e_microstep_mode: #stepper_h_microstep_mode: # This parameter controls the CFG1 and CFG2 pins of the given # stepper motor driver. Available options are: disable, 1, 2, # spread2, 4, 16, spread4, spread16, stealth4, and stealth16. The # default is disable. #stepper_x_current: #stepper_y_current: #stepper_z_current: #stepper_e_current: #stepper_h_current: # The configured maximum current (in Amps) of the stepper motor # driver. This parameter must be provided if the stepper is not in a # disable mode. #stepper_x_chopper_off_time_high: #stepper_y_chopper_off_time_high: #stepper_z_chopper_off_time_high: #stepper_e_chopper_off_time_high: #stepper_h_chopper_off_time_high: # This parameter controls the CFG0 pin of the stepper motor driver # (True sets CFG0 high, False sets it low). The default is False. #stepper_x_chopper_hysteresis_high: #stepper_y_chopper_hysteresis_high: #stepper_z_chopper_hysteresis_high: #stepper_e_chopper_hysteresis_high: #stepper_h_chopper_hysteresis_high: # This parameter controls the CFG4 pin of the stepper motor driver # (True sets CFG4 high, False sets it low). The default is False. #stepper_x_chopper_blank_time_high: #stepper_y_chopper_blank_time_high: #stepper_z_chopper_blank_time_high: #stepper_e_chopper_blank_time_high: #stepper_h_chopper_blank_time_high: # This parameter controls the CFG5 pin of the stepper motor driver # (True sets CFG5 high, False sets it low). The default is True. Other Custom Modules \u00b6 [palette2] \u00b6 Palette 2 multimaterial support - provides a tighter integration supporting Palette 2 devices in connected mode. This modules also requires [virtual_sdcard] and [pause_resume] for full functionality. If you use this module, do not use the Palette 2 plugin for Octoprint as they will conflict, and 1 will fail to initialize properly likely aborting your print. If you use Octoprint and stream gcode over the serial port instead of printing from virtual_sd, then remove M1 and M0 from Pausing commands in Settings > Serial Connection > Firmware & protocol will prevent the need to start print on the Palette 2 and unpausing in Octoprint for your print to begin. [palette2] serial: # The serial port to connect to the Palette 2. #baud: 115200 # The baud rate to use. The default is 115200. #feedrate_splice: 0.8 # The feedrate to use when splicing, default is 0.8 #feedrate_normal: 1.0 # The feedrate to use after splicing, default is 1.0 #auto_load_speed: 2 # Extrude feedrate when autoloading, default is 2 (mm/s) #auto_cancel_variation: 0.1 # Auto cancel print when ping variation is above this threshold [angle] \u00b6 Magnetic hall angle sensor support for reading stepper motor angle shaft measurements using a1333, as5047d, mt6816, mt6826s, or tle5012b SPI chips. The measurements are available via the API Server and motion analysis tool . See the G-Code reference for available commands. [angle my_angle_sensor] sensor_type: # The type of the magnetic hall sensor chip. Available choices are # \"a1333\", \"as5047d\", \"mt6816\", \"mt6826s\", and \"tle5012b\". This parameter must be # specified. #sample_period: 0.000400 # The query period (in seconds) to use during measurements. The # default is 0.000400 (which is 2500 samples per second). #stepper: # The name of the stepper that the angle sensor is attached to (eg, # \"stepper_x\"). Setting this value enables an angle calibration # tool. To use this feature, the Python \"numpy\" package must be # installed. The default is to not enable angle calibration for the # angle sensor. cs_pin: # The SPI enable pin for the sensor. This parameter must be provided. #spi_speed: #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. Common bus parameters \u00b6 Common SPI settings \u00b6 The following parameters are generally available for devices using an SPI bus. #spi_speed: # The SPI speed (in hz) to use when communicating with the device. # The default depends on the type of device. #spi_bus: # If the micro-controller supports multiple SPI busses then one may # specify the micro-controller bus name here. The default depends on # the type of micro-controller. #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # Specify the above parameters to use \"software based SPI\". This # mode does not require micro-controller hardware support (typically # any general purpose pins may be used). The default is to not use # \"software spi\". Common I2C settings \u00b6 The following parameters are generally available for devices using an I2C bus. Note that Klipper's current micro-controller support for I2C is generally not tolerant to line noise. Unexpected errors on the I2C wires may result in Klipper raising a run-time error. Klipper's support for error recovery varies between each micro-controller type. It is generally recommended to only use I2C devices that are on the same printed circuit board as the micro-controller. Most Klipper micro-controller implementations only support an i2c_speed of 100000 ( standard mode , 100kbit/s). The Klipper \"Linux\" micro-controller supports a 400000 speed ( fast mode , 400kbit/s), but it must be set in the operating system and the i2c_speed parameter is otherwise ignored. The Klipper \"RP2040\" micro-controller and ATmega AVR family and some STM32 (F0, G0, G4, L4, F7, H7) support a rate of 400000 via the i2c_speed parameter. All other Klipper micro-controllers use a 100000 rate and ignore the i2c_speed parameter. #i2c_address: # The i2c address of the device. This must specified as a decimal # number (not in hex). The default depends on the type of device. #i2c_mcu: # The name of the micro-controller that the chip is connected to. # The default is \"mcu\". #i2c_bus: # If the micro-controller supports multiple I2C busses then one may # specify the micro-controller bus name here. The default depends on # the type of micro-controller. #i2c_software_scl_pin: #i2c_software_sda_pin: # Specify these parameters to use micro-controller software based # I2C \"bit-banging\" support. The two parameters should the two pins # on the micro-controller to use for the scl and sda wires. The # default is to use hardware based I2C support as specified by the # i2c_bus parameter. #i2c_speed: # The I2C speed (in Hz) to use when communicating with the device. # The Klipper implementation on most micro-controllers is hard-coded # to 100000 and changing this value has no effect. The default is # 100000. Linux, RP2040 and ATmega support 400000.","title":"Configuration reference"},{"location":"Config_Reference.html#configuration-reference","text":"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.","title":"Configuration reference"},{"location":"Config_Reference.html#micro-controller-configuration","text":"","title":"Micro-controller configuration"},{"location":"Config_Reference.html#format-of-micro-controller-pin-names","text":"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.","title":"Format of micro-controller pin names"},{"location":"Config_Reference.html#mcu","text":"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.","title":"[mcu]"},{"location":"Config_Reference.html#mcu-my_extra_mcu","text":"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.","title":"[mcu my_extra_mcu]"},{"location":"Config_Reference.html#common-kinematic-settings","text":"","title":"Common kinematic settings"},{"location":"Config_Reference.html#printer","text":"The printer section controls high level printer settings. [printer] kinematics: # The type of printer in use. This option may be one of: cartesian, # corexy, corexz, hybrid_corexy, hybrid_corexz, generic_cartesian, # rotary_delta, delta, deltesian, polar, winch, or none. # This parameter must be specified. max_velocity: # Maximum velocity (in mm/s) of the toolhead (relative to the # print). This value may be changed at runtime using the # SET_VELOCITY_LIMIT command. This parameter must be specified. max_accel: # Maximum acceleration (in mm/s^2) of the toolhead (relative to the # print). Although this parameter is described as a \"maximum\" # acceleration, in practice most moves that accelerate or decelerate # will do so at the rate specified here. The value specified here # may be changed at runtime using the SET_VELOCITY_LIMIT command. # This parameter must be specified. #minimum_cruise_ratio: 0.5 # Most moves will accelerate to a cruising speed, travel at that # cruising speed, and then decelerate. However, some moves that # travel a short distance could nominally accelerate and then # immediately decelerate. This option reduces the top speed of these # moves to ensure there is always a minimum distance traveled at a # cruising speed. That is, it enforces a minimum distance traveled # at cruising speed relative to the total distance traveled. It is # intended to reduce the top speed of short zigzag moves (and thus # reduce printer vibration from these moves). For example, a # minimum_cruise_ratio of 0.5 would ensure that a standalone 1.5mm # move would have a minimum cruising distance of 0.75mm. Specify a # ratio of 0.0 to disable this feature (there would be no minimum # cruising distance enforced between acceleration and deceleration). # The value specified here may be changed at runtime using the # SET_VELOCITY_LIMIT command. The default is 0.5. #square_corner_velocity: 5.0 # The maximum velocity (in mm/s) that the toolhead may travel a 90 # degree corner at. A non-zero value can reduce changes in extruder # flow rates by enabling instantaneous velocity changes of the # toolhead during cornering. This value configures the internal # centripetal velocity cornering algorithm; corners with angles # larger than 90 degrees will have a higher cornering velocity while # corners with angles less than 90 degrees will have a lower # cornering velocity. If this is set to zero then the toolhead will # decelerate to zero at each corner. The value specified here may be # changed at runtime using the SET_VELOCITY_LIMIT command. The # default is 5mm/s.","title":"[printer]"},{"location":"Config_Reference.html#stepper","text":"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. [stepper_x] step_pin: # Step GPIO pin (triggered high). This parameter must be provided. dir_pin: # Direction GPIO pin (high indicates positive direction). This # parameter must be provided. enable_pin: # Enable pin (default is enable high; use ! to indicate enable # low). If this parameter is not provided then the stepper motor # driver must always be enabled. rotation_distance: # Distance (in mm) that the axis travels with one full rotation of # the stepper motor (or final gear if gear_ratio is specified). # This parameter must be provided. microsteps: # The number of microsteps the stepper motor driver uses. This # parameter must be provided. #full_steps_per_rotation: 200 # The number of full steps for one rotation of the stepper motor. # Set this to 200 for a 1.8 degree stepper motor or set to 400 for a # 0.9 degree motor. The default is 200. #gear_ratio: # The gear ratio if the stepper motor is connected to the axis via a # gearbox. For example, one may specify \"5:1\" if a 5 to 1 gearbox is # in use. If the axis has multiple gearboxes one may specify a comma # separated list of gear ratios (for example, \"57:11, 2:1\"). If a # gear_ratio is specified then rotation_distance specifies the # distance the axis travels for one full rotation of the final gear. # The default is to not use a gear ratio. #step_pulse_duration: # The minimum time between the step pulse signal edge and the # following \"unstep\" signal edge. This is also used to set the # minimum time between a step pulse and a direction change signal. # The default is 0.000000100 (100ns) for TMC steppers that are # configured in UART or SPI mode, and the default is 0.000002 (which # is 2us) for all other steppers. endstop_pin: # Endstop switch detection pin. If this endstop pin is on a # different mcu than the stepper motor then it enables \"multi-mcu # homing\". This parameter must be provided for the X, Y, and Z # steppers on cartesian style printers. #position_min: 0 # Minimum valid distance (in mm) the user may command the stepper to # move to. The default is 0mm. position_endstop: # Location of the endstop (in mm). This parameter must be provided # for the X, Y, and Z steppers on cartesian style printers. position_max: # Maximum valid distance (in mm) the user may command the stepper to # move to. This parameter must be provided for the X, Y, and Z # steppers on cartesian style printers. #homing_speed: 5.0 # Maximum velocity (in mm/s) of the stepper when homing. The default # is 5mm/s. #homing_retract_dist: 5.0 # Distance to backoff (in mm) before homing a second time during # homing. Set this to zero to disable the second home. The default # is 5mm. #homing_retract_speed: # Speed to use on the retract move after homing in case this should # be different from the homing speed, which is the default for this # parameter #second_homing_speed: # Velocity (in mm/s) of the stepper when performing the second home. # The default is homing_speed/2. #homing_positive_dir: # If true, homing will cause the stepper to move in a positive # direction (away from zero); if false, home towards zero. It is # better to use the default than to specify this parameter. The # default is true if position_endstop is near position_max and false # if near position_min.","title":"[stepper]"},{"location":"Config_Reference.html#cartesian-kinematics","text":"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]","title":"Cartesian Kinematics"},{"location":"Config_Reference.html#linear-delta-kinematics","text":"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. [printer] kinematics: delta max_z_velocity: # For delta printers this limits the maximum velocity (in mm/s) of # moves with z axis movement. This setting can be used to reduce the # maximum speed of up/down moves (which require a higher step rate # than other moves on a delta printer). 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. Setting this may be useful if the printer can reach higher # acceleration on XY moves than Z moves (eg, when using input shaper). # The default is to use max_accel for max_z_accel. #minimum_z_position: 0 # The minimum Z position that the user may command the head to move # to. The default is 0. delta_radius: # Radius (in mm) of the horizontal circle formed by the three linear # axis towers. This parameter may also be calculated as: # delta_radius = smooth_rod_offset - effector_offset - carriage_offset # This parameter must be provided. #print_radius: # The radius (in mm) of valid toolhead XY coordinates. One may use # this setting to customize the range checking of toolhead moves. If # a large value is specified here then it may be possible to command # the toolhead into a collision with a tower. The default is to use # delta_radius for print_radius (which would normally prevent a # tower collision). # The stepper_a section describes the stepper controlling the front # left tower (at 210 degrees). This section also controls the homing # parameters (homing_speed, homing_retract_dist) for all towers. [stepper_a] position_endstop: # Distance (in mm) between the nozzle and the bed when the nozzle is # in the center of the build area and the endstop triggers. This # parameter must be provided for stepper_a; for stepper_b and # stepper_c this parameter defaults to the value specified for # stepper_a. arm_length: # Length (in mm) of the diagonal rod that connects this tower to the # print head. This parameter must be provided for stepper_a; for # stepper_b and stepper_c this parameter defaults to the value # specified for stepper_a. #angle: # This option specifies the angle (in degrees) that the tower is # at. The default is 210 for stepper_a, 330 for stepper_b, and 90 # for stepper_c. # The stepper_b section describes the stepper controlling the front # right tower (at 330 degrees). [stepper_b] # The stepper_c section describes the stepper controlling the rear # tower (at 90 degrees). [stepper_c] # The delta_calibrate section enables a DELTA_CALIBRATE extended # g-code command that can calibrate the tower endstop positions and # angles. [delta_calibrate] radius: # Radius (in mm) of the area that may be probed. This is the radius # of nozzle coordinates to be probed; if using an automatic probe # with an XY offset then choose a radius small enough so that the # probe always fits over the bed. This parameter must be provided. #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.","title":"Linear Delta Kinematics"},{"location":"Config_Reference.html#deltesian-kinematics","text":"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. [printer] kinematics: deltesian max_z_velocity: # For deltesian printers, this limits the maximum velocity (in mm/s) of # moves with z axis movement. This setting can be used to reduce the # maximum speed of up/down moves (which require a higher step rate # than other moves on a deltesian printer). 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. Setting this may be useful if the printer can reach higher # acceleration on XY moves than Z moves (eg, when using input shaper). # The default is to use max_accel for max_z_accel. #minimum_z_position: 0 # The minimum Z position that the user may command the head to move # to. The default is 0. #min_angle: 5 # This represents the minimum angle (in degrees) relative to horizontal # that the deltesian arms are allowed to achieve. This parameter is # intended to restrict the arms from becoming completely horizontal, # which would risk accidental inversion of the XZ axis. The default is 5. #print_width: # The distance (in mm) of valid toolhead X coordinates. One may use # this setting to customize the range checking of toolhead moves. If # a large value is specified here then it may be possible to command # the toolhead into a collision with a tower. This setting usually # corresponds to bed width (in mm). #slow_ratio: 3 # The ratio used to limit velocity and acceleration on moves near the # extremes of the X axis. If vertical distance divided by horizontal # distance exceeds the value of slow_ratio, then velocity and # acceleration are limited to half their nominal values. If vertical # distance divided by horizontal distance exceeds twice the value of # the slow_ratio, then velocity and acceleration are limited to one # quarter of their nominal values. The default is 3. # The stepper_left section is used to describe the stepper controlling # the left tower. This section also controls the homing parameters # (homing_speed, homing_retract_dist) for all towers. [stepper_left] position_endstop: # Distance (in mm) between the nozzle and the bed when the nozzle is # in the center of the build area and the endstops are triggered. This # parameter must be provided for stepper_left; for stepper_right this # parameter defaults to the value specified for stepper_left. arm_length: # Length (in mm) of the diagonal rod that connects the tower carriage to # the print head. This parameter must be provided for stepper_left; for # stepper_right, this parameter defaults to the value specified for # stepper_left. arm_x_length: # Horizontal distance between the print head and the tower when the # printers is homed. This parameter must be provided for stepper_left; # for stepper_right, this parameter defaults to the value specified for # stepper_left. # The stepper_right section is used to describe the stepper controlling the # right tower. [stepper_right] # The stepper_y section is used to describe the stepper controlling # the Y axis in a deltesian robot. [stepper_y]","title":"Deltesian Kinematics"},{"location":"Config_Reference.html#corexy-kinematics","text":"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]","title":"CoreXY Kinematics"},{"location":"Config_Reference.html#corexz-kinematics","text":"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]","title":"CoreXZ Kinematics"},{"location":"Config_Reference.html#hybrid-corexy-kinematics","text":"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]","title":"Hybrid-CoreXY Kinematics"},{"location":"Config_Reference.html#hybrid-corexz-kinematics","text":"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]","title":"Hybrid-CoreXZ Kinematics"},{"location":"Config_Reference.html#polar-kinematics","text":"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. # 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]","title":"Polar Kinematics"},{"location":"Config_Reference.html#rotary-delta-kinematics","text":"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. [printer] kinematics: rotary_delta max_z_velocity: # For delta printers this limits the maximum velocity (in mm/s) of # moves with z axis movement. This setting can be used to reduce the # maximum speed of up/down moves (which require a higher step rate # than other moves on a delta printer). The default is to use # max_velocity for max_z_velocity. #minimum_z_position: 0 # The minimum Z position that the user may command the head to move # to. The default is 0. shoulder_radius: # Radius (in mm) of the horizontal circle formed by the three # shoulder joints, minus the radius of the circle formed by the # effector joints. This parameter may also be calculated as: # shoulder_radius = (delta_f - delta_e) / sqrt(12) # This parameter must be provided. shoulder_height: # Distance (in mm) of the shoulder joints from the bed, minus the # effector toolhead height. This parameter must be provided. # The stepper_a section describes the stepper controlling the rear # right arm (at 30 degrees). This section also controls the homing # parameters (homing_speed, homing_retract_dist) for all arms. [stepper_a] gear_ratio: # A gear_ratio must be specified and rotation_distance may not be # specified. For example, if the arm has an 80 toothed pulley driven # by a pulley with 16 teeth, which is in turn connected to a 60 # toothed pulley driven by a stepper with a 16 toothed pulley, then # one would specify a gear ratio of \"80:16, 60:16\". This parameter # must be provided. position_endstop: # Distance (in mm) between the nozzle and the bed when the nozzle is # in the center of the build area and the endstop triggers. This # parameter must be provided for stepper_a; for stepper_b and # stepper_c this parameter defaults to the value specified for # stepper_a. upper_arm_length: # Length (in mm) of the arm connecting the \"shoulder joint\" to the # \"elbow joint\". This parameter must be provided for stepper_a; for # stepper_b and stepper_c this parameter defaults to the value # specified for stepper_a. lower_arm_length: # Length (in mm) of the arm connecting the \"elbow joint\" to the # \"effector joint\". This parameter must be provided for stepper_a; # for stepper_b and stepper_c this parameter defaults to the value # specified for stepper_a. #angle: # This option specifies the angle (in degrees) that the arm is at. # The default is 30 for stepper_a, 150 for stepper_b, and 270 for # stepper_c. # The stepper_b section describes the stepper controlling the rear # left arm (at 150 degrees). [stepper_b] # The stepper_c section describes the stepper controlling the front # arm (at 270 degrees). [stepper_c] # The delta_calibrate section enables a DELTA_CALIBRATE extended # g-code command that can calibrate the shoulder endstop positions. [delta_calibrate] radius: # Radius (in mm) of the area that may be probed. This is the radius # of nozzle coordinates to be probed; if using an automatic probe # with an XY offset then choose a radius small enough so that the # probe always fits over the bed. This parameter must be provided. #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.","title":"Rotary delta Kinematics"},{"location":"Config_Reference.html#cable-winch-kinematics","text":"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.","title":"Cable winch Kinematics"},{"location":"Config_Reference.html#generic-cartesian-kinematics","text":"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 the following three carriages: [carriage x] , [carriage y] , and [carriage z] , e.g. [carriage x] endstop_pin: # Endstop switch detection pin. If this endstop pin is on a # different mcu than the stepper motor(s) moving this carriage, # then it enables \"multi-mcu homing\". This parameter must be provided. #position_min: 0 # Minimum valid distance (in mm) the user may command the carriage to # move to. The default is 0mm. position_endstop: # Location of the endstop (in mm). This parameter must be provided. position_max: # Maximum valid distance (in mm) the user may command the stepper to # move to. This parameter must be provided. #homing_speed: 5.0 # Maximum velocity (in mm/s) of the carriage when homing. The default # is 5mm/s. #homing_retract_dist: 5.0 # Distance to backoff (in mm) before homing a second time during # homing. Set this to zero to disable the second home. The default # is 5mm. #homing_retract_speed: # Speed to use on the retract move after homing in case this should # be different from the homing speed, which is the default for this # parameter #second_homing_speed: # Velocity (in mm/s) of the carriage when performing the second home. # The default is homing_speed/2. #homing_positive_dir: # If true, homing will cause the carriage to move in a positive # direction (away from zero); if false, home towards zero. It is # better to use the default than to specify this parameter. The # default is true if position_endstop is near position_max and false # if near position_min. 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. x, x+y, y-0.5*z, x-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, x+y indicates that the motion of the stepper in the positive direction by the distance d moves the carriages x and y by the same distance d in the positive direction, while x-0.5*y means the motion of the stepper in the positive direction by the distance d moves the carriage x by the distance d in the positive direction, but the 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 x] endstop_pin: ... ... [carriage y] endstop_pin: ... ... [stepper a0] carriages: x-y step_pin: ... dir_pin: ... enable_pin: ... rotation_distance: ... ... [stepper a1] carriages: x-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 beam, 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 y1] primary_carriage: y endstop_pin: ... [stepper sy1] carriages: 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.","title":"Generic Cartesian Kinematics"},{"location":"Config_Reference.html#none-kinematics","text":"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.","title":"None Kinematics"},{"location":"Config_Reference.html#common-extruder-and-heated-bed-support","text":"","title":"Common extruder and heated bed support"},{"location":"Config_Reference.html#extruder","text":"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. [extruder] step_pin: dir_pin: enable_pin: microsteps: rotation_distance: #full_steps_per_rotation: #gear_ratio: # See the \"stepper\" section for a description of the above # parameters. If none of the above parameters are specified then no # stepper will be associated with the nozzle hotend (though a # SYNC_EXTRUDER_MOTION command may associate one at run-time). nozzle_diameter: # Diameter of the nozzle orifice (in mm). This parameter must be # provided. filament_diameter: # The nominal diameter of the raw filament (in mm) as it enters the # extruder. This parameter must be provided. #max_extrude_cross_section: # Maximum area (in mm^2) of an extrusion cross section (eg, # extrusion width multiplied by layer height). This setting prevents # excessive amounts of extrusion during relatively small XY moves. # If a move requests an extrusion rate that would exceed this value # it will cause an error to be returned. The default is: 4.0 * # nozzle_diameter^2 #instantaneous_corner_velocity: 1.000 # The maximum instantaneous velocity change (in mm/s) of the # extruder during the junction of two moves. The default is 1mm/s. #max_extrude_only_distance: 50.0 # Maximum length (in mm of raw filament) that a retraction or # extrude-only move may have. If a retraction or extrude-only move # requests a distance greater than this value it will cause an error # to be returned. The default is 50mm. #max_extrude_only_velocity: #max_extrude_only_accel: # Maximum velocity (in mm/s) and acceleration (in mm/s^2) of the # extruder motor for retractions and extrude-only moves. These # settings do not have any impact on normal printing moves. If not # specified then they are calculated to match the limit an XY # printing move with a cross section of 4.0*nozzle_diameter^2 would # have. #pressure_advance: 0.0 # The amount of raw filament to push into the extruder during # extruder acceleration. An equal amount of filament is retracted # during deceleration. It is measured in millimeters per # millimeter/second. The default is 0, which disables pressure # advance. #pressure_advance_smooth_time: 0.040 # A time range (in seconds) to use when calculating the average # extruder velocity for pressure advance. A larger value results in # smoother extruder movements. This parameter may not exceed 200ms. # This setting only applies if pressure_advance is non-zero. The # default is 0.040 (40 milliseconds). # # The remaining variables describe the extruder heater. heater_pin: # PWM output pin controlling the heater. This parameter must be # provided. #max_power: 1.0 # The maximum power (expressed as a value from 0.0 to 1.0) that the # heater_pin may be set to. The value 1.0 allows the pin to be set # fully enabled for extended periods, while a value of 0.5 would # allow the pin to be enabled for no more than half the time. This # setting may be used to limit the total power output (over extended # periods) to the heater. The default is 1.0. sensor_type: # Type of sensor - common thermistors are \"EPCOS 100K B57560G104F\", # \"ATC Semitec 104GT-2\", \"ATC Semitec 104NT-4-R025H42G\", \"Generic # 3950\",\"Honeywell 100K 135-104LAG-J01\", \"NTC 100K MGB18-104F39050L32\", # \"SliceEngineering 450\", and \"TDK NTCG104LH104JT1\". See the # \"Temperature sensors\" section for other sensors. This parameter # must be provided. sensor_pin: # Analog input pin connected to the sensor. This parameter must be # provided. #pullup_resistor: 4700 # The resistance (in ohms) of the pullup attached to the thermistor. # This parameter is only valid when the sensor is a thermistor. The # default is 4700 ohms. #smooth_time: 1.0 # A time value (in seconds) over which temperature measurements will # be smoothed to reduce the impact of measurement noise. The default # is 1 seconds. control: # Control algorithm (either pid or watermark). This parameter must # be provided. pid_Kp: pid_Ki: pid_Kd: # The proportional (pid_Kp), integral (pid_Ki), and derivative # (pid_Kd) settings for the PID feedback control system. Klipper # evaluates the PID settings with the following general formula: # heater_pwm = (Kp*error + Ki*integral(error) - Kd*derivative(error)) / 255 # Where \"error\" is \"requested_temperature - measured_temperature\" # and \"heater_pwm\" is the requested heating rate with 0.0 being full # off and 1.0 being full on. Consider using the PID_CALIBRATE # command to obtain these parameters. The pid_Kp, pid_Ki, and pid_Kd # parameters must be provided for PID heaters. #max_delta: 2.0 # On 'watermark' controlled heaters this is the number of degrees in # Celsius above the target temperature before disabling the heater # as well as the number of degrees below the target before # re-enabling the heater. The default is 2 degrees Celsius. #pwm_cycle_time: 0.100 # Time in seconds for each software PWM cycle of the heater. It is # not recommended to set this unless there is an electrical # requirement to switch the heater faster than 10 times a second. # The default is 0.100 seconds. #min_extrude_temp: 170 # The minimum temperature (in Celsius) at which extruder move # commands may be issued. The default is 170 Celsius. min_temp: max_temp: # The maximum range of valid temperatures (in Celsius) that the # heater must remain within. This controls a safety feature # implemented in the micro-controller code - should the measured # temperature ever fall outside this range then the micro-controller # will go into a shutdown state. This check can help detect some # heater and sensor hardware failures. Set this range just wide # enough so that reasonable temperatures do not result in an error. # These parameters must be provided.","title":"[extruder]"},{"location":"Config_Reference.html#heater_bed","text":"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.","title":"[heater_bed]"},{"location":"Config_Reference.html#bed-level-support","text":"","title":"Bed level support"},{"location":"Config_Reference.html#bed_mesh","text":"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 [bed_mesh] #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. #mesh_radius: # Defines the radius of the mesh to probe for round beds. Note that # the radius is relative to the coordinate specified by the # mesh_origin option. This parameter must be provided for round beds # and omitted for rectangular beds. #mesh_origin: # Defines the center X, Y coordinate of the mesh for round beds. This # coordinate is relative to the probe's location. It may be useful # to adjust the mesh_origin in an effort to maximize the size of the # mesh radius. Default is 0, 0. This parameter must be omitted for # rectangular beds. #mesh_min: # Defines the minimum X, Y coordinate of the mesh for rectangular # beds. This coordinate is relative to the probe's location. This # will be the first point probed, nearest to the origin. This # parameter must be provided for rectangular beds. #mesh_max: # Defines the maximum X, Y coordinate of the mesh for rectangular # beds. Adheres to the same principle as mesh_min, however this will # be the furthest point probed from the bed's origin. This parameter # must be provided for rectangular beds. #probe_count: 3, 3 # For rectangular beds, this is a comma separate pair of integer # values X, Y defining the number of points to probe along each # axis. A single value is also valid, in which case that value will # be applied to both axes. Default is 3, 3. #round_probe_count: 5 # For round beds, this integer value defines the maximum number of # points to probe along each axis. This value must be an odd number. # Default is 5. #fade_start: 1.0 # The gcode z position in which to start phasing out z-adjustment # when fade is enabled. Default is 1.0. #fade_end: 0.0 # The gcode z position in which phasing out completes. When set to a # value below fade_start, fade is disabled. It should be noted that # fade may add unwanted scaling along the z-axis of a print. If a # user wishes to enable fade, a value of 10.0 is recommended. # Default is 0.0, which disables fade. #fade_target: # The z position in which fade should converge. When this value is # set to a non-zero value it must be within the range of z-values in # the mesh. Users that wish to converge to the z homing position # should set this to 0. Default is the average z value of the mesh. #split_delta_z: .025 # The amount of Z difference (in mm) along a move that will trigger # a split. Default is .025. #move_check_distance: 5.0 # The distance (in mm) along a move to check for split_delta_z. # This is also the minimum length that a move can be split. Default # is 5.0. #mesh_pps: 2, 2 # A comma separated pair of integers X, Y defining the number of # points per segment to interpolate in the mesh along each axis. A # \"segment\" can be defined as the space between each probed point. # The user may enter a single value which will be applied to both # axes. Default is 2, 2. #algorithm: lagrange # The interpolation algorithm to use. May be either \"lagrange\" or # \"bicubic\". This option will not affect 3x3 grids, which are forced # to use lagrange sampling. Default is lagrange. #bicubic_tension: .2 # When using the bicubic algorithm the tension parameter above may # be applied to change the amount of slope interpolated. Larger # numbers will increase the amount of slope, which results in more # curvature in the mesh. Default is .2. #zero_reference_position: # An optional X,Y coordinate that specifies the location on the bed # where Z = 0. When this option is specified the mesh will be offset # so that zero Z adjustment occurs at this location. The default is # no zero reference. #faulty_region_1_min: #faulty_region_1_max: # Optional points that define a faulty region. See docs/Bed_Mesh.md # for details on faulty regions. Up to 99 faulty regions may be added. # By default no faulty regions are set. #adaptive_margin: # An optional margin (in mm) to be added around the bed area used by # the defined print objects when generating an adaptive mesh. #scan_overshoot: # 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.","title":"[bed_mesh]"},{"location":"Config_Reference.html#bed_tilt","text":"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.","title":"[bed_tilt]"},{"location":"Config_Reference.html#bed_screws","text":"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.","title":"[bed_screws]"},{"location":"Config_Reference.html#screws_tilt_adjust","text":"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.","title":"[screws_tilt_adjust]"},{"location":"Config_Reference.html#z_tilt","text":"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. [z_tilt] #z_positions: # A list of X, Y coordinates (one per line; subsequent lines # indented) describing the location of each bed \"pivot point\". The # \"pivot point\" is the point where the bed attaches to the given Z # stepper. It is described using nozzle coordinates (the X, Y position # of the nozzle if it could move directly above the point). The # first entry corresponds to stepper_z, the second to stepper_z1, # the third to stepper_z2, etc. This parameter must be provided. #points: # A list of X, Y coordinates (one per line; subsequent lines # indented) that should be probed during a Z_TILT_ADJUST command. # Specify coordinates of the nozzle and be sure the probe is above # the bed at the given nozzle coordinates. This parameter must be # provided. #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. #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. Note the smallest unit of # change here would be a single step. However if you are probing # more points than steppers then you will likely have a fixed # minimum value for the range of probed points which you can learn # by observing command output.","title":"[z_tilt]"},{"location":"Config_Reference.html#quad_gantry_level","text":"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.","title":"[quad_gantry_level]"},{"location":"Config_Reference.html#skew_correction","text":"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]","title":"[skew_correction]"},{"location":"Config_Reference.html#z_thermal_adjust","text":"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.","title":"[z_thermal_adjust]"},{"location":"Config_Reference.html#customized-homing","text":"","title":"Customized homing"},{"location":"Config_Reference.html#safe_z_home","text":"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.","title":"[safe_z_home]"},{"location":"Config_Reference.html#homing_override","text":"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.","title":"[homing_override]"},{"location":"Config_Reference.html#endstop_phase","text":"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.","title":"[endstop_phase]"},{"location":"Config_Reference.html#g-code-macros-and-events","text":"","title":"G-Code macros and events"},{"location":"Config_Reference.html#gcode_macro","text":"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\"","title":"[gcode_macro]"},{"location":"Config_Reference.html#delayed_gcode","text":"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.","title":"[delayed_gcode]"},{"location":"Config_Reference.html#save_variables","text":"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","title":"[save_variables]"},{"location":"Config_Reference.html#idle_timeout","text":"Idle timeout. An idle timeout is automatically enabled - add an explicit idle_timeout config section to change the default settings. [idle_timeout] #gcode: # A list of G-Code commands to execute on an idle timeout. See # docs/Command_Templates.md for G-Code format. The default is to run # \"TURN_OFF_HEATERS\" and \"M84\". #timeout: 600 # Idle time (in seconds) to wait before running the above G-Code # commands. The default is 600 seconds.","title":"[idle_timeout]"},{"location":"Config_Reference.html#optional-g-code-features","text":"","title":"Optional G-Code features"},{"location":"Config_Reference.html#virtual_sdcard","text":"A virtual sdcard may be useful if the host machine is not fast enough to run OctoPrint well. It allows the Klipper host software to directly print gcode files stored in a directory on the host using standard sdcard G-Code commands (eg, M24). [virtual_sdcard] path: # The path of the local directory on the host machine to look for # g-code files. This is a read-only directory (sdcard file writes # are not supported). One may point this to OctoPrint's upload # directory (generally ~/.octoprint/uploads/ ). This parameter must # be provided. #on_error_gcode: # A list of G-Code commands to execute when an error is reported. # See docs/Command_Templates.md for G-Code format. The default is to # run TURN_OFF_HEATERS.","title":"[virtual_sdcard]"},{"location":"Config_Reference.html#sdcard_loop","text":"Some printers with stage-clearing features, such as a part ejector or a belt printer, can find use in looping sections of the sdcard file. (For example, to print the same part over and over, or repeat the a section of a part for a chain or other repeated pattern). See the command reference for supported commands. See the sample-macros.cfg file for a Marlin compatible M808 G-Code macro. [sdcard_loop]","title":"[sdcard_loop]"},{"location":"Config_Reference.html#force_move","text":"Support manually moving stepper motors for diagnostic purposes. Note, using this feature may place the printer in an invalid state - see the command reference for important details. [force_move] #enable_force_move: False # Set to true to enable FORCE_MOVE and SET_KINEMATIC_POSITION # extended G-Code commands. The default is false.","title":"[force_move]"},{"location":"Config_Reference.html#pause_resume","text":"Pause/Resume functionality with support of position capture and restore. See the command reference for more information. [pause_resume] #recover_velocity: 50. # When capture/restore is enabled, the speed at which to return to # the captured position (in mm/s). Default is 50.0 mm/s.","title":"[pause_resume]"},{"location":"Config_Reference.html#firmware_retraction","text":"Firmware filament retraction. This enables G10 (retract) and G11 (unretract) GCODE commands issued by many slicers. The parameters below provide startup defaults, although the values can be adjusted via the SET_RETRACTION command ), allowing per-filament settings and runtime tuning. [firmware_retraction] #retract_length: 0 # The length of filament (in mm) to retract when G10 is activated, # and to unretract when G11 is activated (but see # unretract_extra_length below). The default is 0 mm. #retract_speed: 20 # The speed of retraction, in mm/s. The default is 20 mm/s. #unretract_extra_length: 0 # The length (in mm) of *additional* filament to add when # unretracting. #unretract_speed: 10 # The speed of unretraction, in mm/s. The default is 10 mm/s.","title":"[firmware_retraction]"},{"location":"Config_Reference.html#gcode_arcs","text":"Support for gcode arc (G2/G3) commands. [gcode_arcs] #resolution: 1.0 # An arc will be split into segments. Each segment's length will # equal the resolution in mm set above. Lower values will produce a # finer arc, but also more work for your machine. Arcs smaller than # the configured value will become straight lines. The default is # 1mm.","title":"[gcode_arcs]"},{"location":"Config_Reference.html#respond","text":"Enable the \"M118\" and \"RESPOND\" extended commands . [respond] #default_type: echo # Sets the default prefix of the \"M118\" and \"RESPOND\" output to one # of the following: # echo: \"echo: \" (This is the default) # command: \"// \" # error: \"!! \" #default_prefix: echo: # Directly sets the default prefix. If present, this value will # override the \"default_type\".","title":"[respond]"},{"location":"Config_Reference.html#exclude_object","text":"Enables support to exclude or cancel individual objects during the printing process. See the exclude objects guide and command reference for additional information. See the sample-macros.cfg file for a Marlin/RepRapFirmware compatible M486 G-Code macro. [exclude_object]","title":"[exclude_object]"},{"location":"Config_Reference.html#resonance-compensation","text":"","title":"Resonance compensation"},{"location":"Config_Reference.html#input_shaper","text":"Enables resonance compensation . Also see the command reference . [input_shaper] #shaper_freq_x: 0 # A frequency (in Hz) of the input shaper for X axis. This is # usually a resonance frequency of X axis that the input shaper # should suppress. For more complex shapers, like 2- and 3-hump EI # input shapers, this parameter can be set from different # considerations. The default value is 0, which disables input # shaping for X axis. #shaper_freq_y: 0 # A frequency (in Hz) of the input shaper for Y axis. This is # usually a resonance frequency of Y axis that the input shaper # should suppress. For more complex shapers, like 2- and 3-hump EI # input shapers, this parameter can be set from different # considerations. The default value is 0, which disables input # shaping for Y axis. #shaper_type: mzv # A type of the input shaper to use for both X and Y axes. Supported # shapers are zv, mzv, zvd, ei, 2hump_ei, and 3hump_ei. The default # is mzv input shaper. #shaper_type_x: #shaper_type_y: # If shaper_type is not set, these two parameters can be used to # configure different input shapers for X and Y axes. The same # values are supported as for shaper_type parameter. #damping_ratio_x: 0.1 #damping_ratio_y: 0.1 # Damping ratios of vibrations of X and Y axes used by input shapers # to improve vibration suppression. Default value is 0.1 which is a # good all-round value for most printers. In most circumstances this # parameter requires no tuning and should not be changed.","title":"[input_shaper]"},{"location":"Config_Reference.html#adxl345","text":"Support for ADXL345 accelerometers. This support allows one to query accelerometer measurements from the sensor. This enables an ACCELEROMETER_MEASURE command (see G-Codes for more information). The default chip name is \"default\", but one may specify an explicit name (eg, [adxl345 my_chip_name]). [adxl345] cs_pin: # The SPI enable pin for the sensor. This parameter must be provided. #spi_speed: 5000000 # The SPI speed (in hz) to use when communicating with the chip. # The default is 5000000. #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #axes_map: x, y, z # The accelerometer axis for each of the printer's X, Y, and Z axes. # This may be useful if the accelerometer is mounted in an # orientation that does not match the printer orientation. For # example, one could set this to \"y, x, z\" to swap the X and Y axes. # It is also possible to negate an axis if the accelerometer # direction is reversed (eg, \"x, z, -y\"). The default is \"x, y, z\". #rate: 3200 # Output data rate for ADXL345. ADXL345 supports the following data # rates: 3200, 1600, 800, 400, 200, 100, 50, and 25. Note that it is # not recommended to change this rate from the default 3200, and # rates below 800 will considerably affect the quality of resonance # measurements.","title":"[adxl345]"},{"location":"Config_Reference.html#icm20948","text":"Support for icm20948 accelerometers. [icm20948] #i2c_address: # Default is 104 (0x68). If AD0 is high, it would be 0x69 instead. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: 400000 # See the \"common I2C settings\" section for a description of the # above parameters. The default \"i2c_speed\" is 400000. #axes_map: x, y, z # See the \"adxl345\" section for information on this parameter.","title":"[icm20948]"},{"location":"Config_Reference.html#lis2dw","text":"Support for LIS2DW accelerometers. [lis2dw] #cs_pin: # The SPI enable pin for the sensor. This parameter must be provided # if using SPI. #spi_speed: 5000000 # The SPI speed (in hz) to use when communicating with the chip. # The default is 5000000. #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #i2c_address: # Default is 25 (0x19). If SA0 is high, it would be 24 (0x18) instead. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: 400000 # See the \"common I2C settings\" section for a description of the # above parameters. The default \"i2c_speed\" is 400000. #axes_map: x, y, z # See the \"adxl345\" section for information on this parameter.","title":"[lis2dw]"},{"location":"Config_Reference.html#lis3dh","text":"Support for LIS3DH accelerometers. [lis3dh] #cs_pin: # The SPI enable pin for the sensor. This parameter must be provided # if using SPI. #spi_speed: 5000000 # The SPI speed (in hz) to use when communicating with the chip. # The default is 5000000. #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #i2c_address: # Default is 25 (0x19). If SA0 is high, it would be 24 (0x18) instead. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: 400000 # See the \"common I2C settings\" section for a description of the # above parameters. The default \"i2c_speed\" is 400000. #axes_map: x, y, z # See the \"adxl345\" section for information on this parameter.","title":"[lis3dh]"},{"location":"Config_Reference.html#mpu9250","text":"Support for MPU-9250, MPU-9255, MPU-6515, MPU-6050, and MPU-6500 accelerometers (one may define any number of sections with an \"mpu9250\" prefix). [mpu9250 my_accelerometer] #i2c_address: # Default is 104 (0x68). If AD0 is high, it would be 0x69 instead. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: 400000 # See the \"common I2C settings\" section for a description of the # above parameters. The default \"i2c_speed\" is 400000. #axes_map: x, y, z # See the \"adxl345\" section for information on this parameter.","title":"[mpu9250]"},{"location":"Config_Reference.html#resonance_tester","text":"Support for resonance testing and automatic input shaper calibration. In order to use most of the functionality of this module, additional software dependencies must be installed; refer to Measuring Resonances and the command reference for more information. See the Max smoothing section of the measuring resonances guide for more information on max_smoothing parameter and its use. [resonance_tester] #probe_points: # A list of X, Y, Z coordinates of points (one point per line) to test # resonances at. At least one point is required. Make sure that all # points with some safety margin in XY plane (~a few centimeters) # are reachable by the toolhead. #accel_chip: # A name of the accelerometer chip to use for measurements. If # adxl345 chip was defined without an explicit name, this parameter # can simply reference it as \"accel_chip: adxl345\", otherwise an # explicit name must be supplied as well, e.g. \"accel_chip: adxl345 # my_chip_name\". Either this, or the next two parameters must be # set. #accel_chip_x: #accel_chip_y: # Names of the accelerometer chips to use for measurements for each # of the axis. Can be useful, for instance, on bed slinger printer, # if two separate accelerometers are mounted on the bed (for Y axis) # and on the toolhead (for X axis). These parameters have the same # format as 'accel_chip' parameter. Only 'accel_chip' or these two # parameters must be provided. #max_smoothing: # Maximum input shaper smoothing to allow for each axis during shaper # auto-calibration (with 'SHAPER_CALIBRATE' command). By default no # maximum smoothing is specified. Refer to Measuring_Resonances guide # for more details on using this feature. #move_speed: 50 # The speed (in mm/s) to move the toolhead to and between test points # during the calibration. The default is 50. #min_freq: 5 # Minimum frequency to test for resonances. The default is 5 Hz. #max_freq: 133.33 # Maximum frequency to test for resonances. The default is 133.33 Hz. #accel_per_hz: 60 # This parameter is used to determine which acceleration to use to # test a specific frequency: accel = accel_per_hz * freq. Higher the # value, the higher is the energy of the oscillations. Can be set to # a lower than the default value if the resonances get too strong on # the printer. However, lower values make measurements of # high-frequency resonances less precise. The default value is 75 # (mm/sec). #hz_per_sec: 1 # Determines the speed of the test. When testing all frequencies in # range [min_freq, max_freq], each second the frequency increases by # hz_per_sec. Small values make the test slow, and the large values # will decrease the precision of the test. The default value is 1.0 # (Hz/sec == sec^-2). #sweeping_accel: 400 # An acceleration of slow sweeping moves. The default is 400 mm/sec^2. #sweeping_period: 1.2 # A period of slow sweeping moves. Setting this parameter to 0 # disables slow sweeping moves. Avoid setting it to a too small # non-zero value in order to not poison the measurements. # The default is 1.2 sec which is a good all-round choice.","title":"[resonance_tester]"},{"location":"Config_Reference.html#config-file-helpers","text":"","title":"Config file helpers"},{"location":"Config_Reference.html#board_pins","text":"Board pin aliases (one may define any number of sections with a \"board_pins\" prefix). Use this to define aliases for the pins on a micro-controller. [board_pins my_aliases] mcu: mcu # A comma separated list of micro-controllers that may use the # aliases. The default is to apply the aliases to the main \"mcu\". aliases: aliases_<name>: # A comma separated list of \"name=value\" aliases to create for the # given micro-controller. For example, \"EXP1_1=PE6\" would create an # \"EXP1_1\" alias for the \"PE6\" pin. However, if \"value\" is enclosed # in \"<>\" then \"name\" is created as a reserved pin (for example, # \"EXP1_9=<GND>\" would reserve \"EXP1_9\"). Any number of options # starting with \"aliases_\" may be specified.","title":"[board_pins]"},{"location":"Config_Reference.html#include","text":"Include file support. One may include additional config file from the main printer config file. Wildcards may also be used (eg, \"configs/*.cfg\"). [include my_other_config.cfg]","title":"[include]"},{"location":"Config_Reference.html#duplicate_pin_override","text":"This tool allows a single micro-controller pin to be defined multiple times in a config file without normal error checking. This is intended for diagnostic and debugging purposes. This section is not needed where Klipper supports using the same pin multiple times, and using this override may cause confusing and unexpected results. [duplicate_pin_override] pins: # A comma separated list of pins that may be used multiple times in # a config file without normal error checks. This parameter must be # provided.","title":"[duplicate_pin_override]"},{"location":"Config_Reference.html#bed-probing-hardware","text":"","title":"Bed probing hardware"},{"location":"Config_Reference.html#probe","text":"Z height probe. One may define this section to enable Z height probing hardware. When this section is enabled, PROBE and QUERY_PROBE extended g-code commands become available. Also, see the probe calibrate guide . The probe section also creates a virtual \"probe:z_virtual_endstop\" pin. One may set the stepper_z endstop_pin to this virtual pin on cartesian style printers that use the probe in place of a z endstop. If using \"probe:z_virtual_endstop\" then do not define a position_endstop in the stepper_z config section. [probe] pin: # Probe detection pin. If the pin is on a different microcontroller # than the Z steppers then it enables \"multi-mcu homing\". This # parameter must be provided. #deactivate_on_each_sample: True # This determines if Klipper should execute deactivation gcode # between each probe attempt when performing a multiple probe # sequence. The default is True. #x_offset: 0.0 # The distance (in mm) between the probe and the nozzle along the # x-axis. The default is 0. #y_offset: 0.0 # The distance (in mm) between the probe and the nozzle along the # y-axis. The default is 0. z_offset: # The distance (in mm) between the bed and the nozzle when the probe # triggers. This parameter must be provided. #speed: 5.0 # Speed (in mm/s) of the Z axis when probing. The default is 5mm/s. #samples: 1 # The number of times to probe each point. The probed z-values will # be averaged. The default is to probe 1 time. #sample_retract_dist: 2.0 # The distance (in mm) to lift the toolhead between each sample (if # sampling more than once). The default is 2mm. #lift_speed: # Speed (in mm/s) of the Z axis when lifting the probe between # samples. The default is to use the same value as the 'speed' # parameter. #samples_result: average # The calculation method when sampling more than once - either # \"median\" or \"average\". The default is average. #samples_tolerance: 0.100 # The maximum Z distance (in mm) that a sample may differ from other # samples. If this tolerance is exceeded then either an error is # reported or the attempt is restarted (see # samples_tolerance_retries). The default is 0.100mm. #samples_tolerance_retries: 0 # The number of times to retry if a sample is found that exceeds # samples_tolerance. On a retry, all current samples are discarded # and the probe attempt is restarted. If a valid set of samples are # not obtained in the given number of retries then an error is # reported. The default is zero which causes an error to be reported # on the first sample that exceeds samples_tolerance. #activate_gcode: # A list of G-Code commands to execute prior to each probe attempt. # See docs/Command_Templates.md for G-Code format. This may be # useful if the probe needs to be activated in some way. Do not # issue any commands here that move the toolhead (eg, G1). The # default is to not run any special G-Code commands on activation. #deactivate_gcode: # A list of G-Code commands to execute after each probe attempt # completes. See docs/Command_Templates.md for G-Code format. Do not # issue any commands here that move the toolhead. The default is to # not run any special G-Code commands on deactivation.","title":"[probe]"},{"location":"Config_Reference.html#bltouch","text":"BLTouch probe. One may define this section (instead of a probe section) to enable a BLTouch probe. See BL-Touch guide and command reference for further information. A virtual \"probe:z_virtual_endstop\" pin is also created (see the \"probe\" section for the details). [bltouch] sensor_pin: # Pin connected to the BLTouch sensor pin. Most BLTouch devices # require a pullup on the sensor pin (prefix the pin name with \"^\"). # This parameter must be provided. control_pin: # Pin connected to the BLTouch control pin. This parameter must be # provided. #pin_move_time: 0.680 # The amount of time (in seconds) to wait for the BLTouch pin to # move up or down. The default is 0.680 seconds. #stow_on_each_sample: True # This determines if Klipper should command the pin to move up # between each probe attempt when performing a multiple probe # sequence. Read the directions in docs/BLTouch.md before setting # this to False. The default is True. #probe_with_touch_mode: False # If this is set to True then Klipper will probe with the device in # \"touch_mode\". The default is False (probing in \"pin_down\" mode). #pin_up_reports_not_triggered: True # Set if the BLTouch consistently reports the probe in a \"not # triggered\" state after a successful \"pin_up\" command. This should # be True for all genuine BLTouch devices. Read the directions in # docs/BLTouch.md before setting this to False. The default is True. #pin_up_touch_mode_reports_triggered: True # Set if the BLTouch consistently reports a \"triggered\" state after # the commands \"pin_up\" followed by \"touch_mode\". This should be # True for all genuine BLTouch devices. Read the directions in # docs/BLTouch.md before setting this to False. The default is True. #set_output_mode: # Request a specific sensor pin output mode on the BLTouch V3.0 (and # later). This setting should not be used on other types of probes. # Set to \"5V\" to request a sensor pin output of 5 Volts (only use if # the controller board needs 5V mode and is 5V tolerant on its input # signal line). Set to \"OD\" to request the sensor pin output use # open drain mode. The default is to not request an output mode. #x_offset: #y_offset: #z_offset: #speed: #lift_speed: #samples: #sample_retract_dist: #samples_result: #samples_tolerance: #samples_tolerance_retries: # See the \"probe\" section for information on these parameters.","title":"[bltouch]"},{"location":"Config_Reference.html#smart_effector","text":"The \"Smart Effector\" from Duet3d implements a Z probe using a force sensor. One may define this section instead of [probe] to enable the Smart Effector specific features. This also enables runtime commands to adjust the parameters of the Smart Effector at run time. [smart_effector] pin: # Pin connected to the Smart Effector Z Probe output pin (pin 5). Note that # pullup resistor on the board is generally not required. However, if the # output pin is connected to the board pin with a pullup resistor, that # resistor must be high value (e.g. 10K Ohm or more). Some boards have a low # value pullup resistor on the Z probe input, which will likely result in an # always-triggered probe state. In this case, connect the Smart Effector to # a different pin on the board. This parameter is required. #control_pin: # Pin connected to the Smart Effector control input pin (pin 7). If provided, # Smart Effector sensitivity programming commands become available. #probe_accel: # If set, limits the acceleration of the probing moves (in mm/sec^2). # A sudden large acceleration at the beginning of the probing move may # cause spurious probe triggering, especially if the hotend is heavy. # To prevent that, it may be necessary to reduce the acceleration of # the probing moves via this parameter. #recovery_time: 0.4 # A delay between the travel moves and the probing moves in seconds. A fast # travel move prior to probing may result in a spurious probe triggering. # This may cause 'Probe triggered prior to movement' errors if no delay # is set. Value 0 disables the recovery delay. # Default value is 0.4. #x_offset: #y_offset: # Should be left unset (or set to 0). z_offset: # Trigger height of the probe. Start with -0.1 (mm), and adjust later using # `PROBE_CALIBRATE` command. This parameter must be provided. #speed: # Speed (in mm/s) of the Z axis when probing. It is recommended to start # with the probing speed of 20 mm/s and adjust it as necessary to improve # the accuracy and repeatability of the probe triggering. #samples: #sample_retract_dist: #samples_result: #samples_tolerance: #samples_tolerance_retries: #activate_gcode: #deactivate_gcode: #deactivate_on_each_sample: # See the \"probe\" section for more information on the parameters above.","title":"[smart_effector]"},{"location":"Config_Reference.html#probe_eddy_current","text":"Support for eddy current inductive probes. One may define this section (instead of a probe section) to enable this probe. See the command reference for further information. [probe_eddy_current my_eddy_probe] sensor_type: ldc1612 # The sensor chip used to perform eddy current measurements. This # parameter must be provided and must be set to ldc1612. #frequency: # The external crystal frequency (in Hz) of the LDC1612 chip. # The default is 12000000. #intb_pin: # MCU gpio pin connected to the ldc1612 sensor's INTB pin (if # available). The default is to not use the INTB pin. #z_offset: # The nominal distance (in mm) between the nozzle and bed that a # probing attempt should stop at. This parameter must be provided. #i2c_address: #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # The i2c settings for the sensor chip. See the \"common I2C # settings\" section for a description of the above parameters. #x_offset: #y_offset: #speed: #lift_speed: #samples: #sample_retract_dist: #samples_result: #samples_tolerance: #samples_tolerance_retries: # See the \"probe\" section for information on these parameters.","title":"[probe_eddy_current]"},{"location":"Config_Reference.html#axis_twist_compensation","text":"A tool to compensate for inaccurate probe readings due to twist in X or Y gantry. See the Axis Twist Compensation Guide for more detailed information regarding symptoms, configuration and setup. [axis_twist_compensation] #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. calibrate_start_x: 20 # Defines the minimum X coordinate of the calibration # This should be the X coordinate that positions the nozzle at the starting # calibration position. calibrate_end_x: 200 # Defines the maximum X coordinate of the calibration # This should be the X coordinate that positions the nozzle at the ending # calibration position. calibrate_y: 112.5 # Defines the Y coordinate of the calibration # This should be the Y coordinate that positions the nozzle during the # calibration process. This parameter is recommended to # be near the center of the bed # For Y-axis twist compensation, specify the following parameters: calibrate_start_y: ... # Defines the minimum Y coordinate of the calibration # This should be the Y coordinate that positions the nozzle at the starting # calibration position for the Y axis. This parameter must be provided if # compensating for Y axis twist. calibrate_end_y: ... # Defines the maximum Y coordinate of the calibration # This should be the Y coordinate that positions the nozzle at the ending # calibration position for the Y axis. This parameter must be provided if # compensating for Y axis twist. calibrate_x: ... # Defines the X coordinate of the calibration for Y axis twist compensation # This should be the X coordinate that positions the nozzle during the # calibration process for Y axis twist compensation. This parameter must be # provided and is recommended to be near the center of the bed.","title":"[axis_twist_compensation]"},{"location":"Config_Reference.html#additional-stepper-motors-and-extruders","text":"","title":"Additional stepper motors and extruders"},{"location":"Config_Reference.html#stepper_z1","text":"Multi-stepper axes. On a cartesian style printer, the stepper controlling a given axis may have additional config blocks defining steppers that should be stepped in concert with the primary stepper. One may define any number of sections with a numeric suffix starting at 1 (for example, \"stepper_z1\", \"stepper_z2\", etc.). [stepper_z1] #step_pin: #dir_pin: #enable_pin: #microsteps: #rotation_distance: # See the \"stepper\" section for the definition of the above parameters. #endstop_pin: # If an endstop_pin is defined for the additional stepper then the # stepper will home until the endstop is triggered. Otherwise, the # stepper will home until the endstop on the primary stepper for the # axis is triggered.","title":"[stepper_z1]"},{"location":"Config_Reference.html#extruder1","text":"In a multi-extruder printer add an additional extruder section for each additional extruder. The additional extruder sections should be named \"extruder1\", \"extruder2\", \"extruder3\", and so on. See the \"extruder\" section for a description of available parameters. See sample-multi-extruder.cfg for an example configuration. [extruder1] #step_pin: #dir_pin: #... # See the \"extruder\" section for available stepper and heater # parameters. #shared_heater: # This option is deprecated and should no longer be specified.","title":"[extruder1]"},{"location":"Config_Reference.html#dual_carriage","text":"Support for cartesian, generic_cartesian and hybrid_corexy/z printers with dual carriages on a single axis. The carriage mode can be set via the SET_DUAL_CARRIAGE extended g-code command. For example, \"SET_DUAL_CARRIAGE CARRIAGE=1\" command will activate the carriage defined in this section (CARRIAGE=0 will return activation to the primary carriage). Dual carriage support is typically combined with extra extruders - the SET_DUAL_CARRIAGE command is often called at the same time as the ACTIVATE_EXTRUDER command. Be sure to park the carriages during deactivation. Note that during G28 homing, typically the primary carriage is homed first followed by the carriage defined in the [dual_carriage] config section. However, the [dual_carriage] carriage will be homed first if both carriages home in a positive direction and the [dual_carriage] carriage has a position_endstop greater than the primary carriage, or if both carriages home in a negative direction and the [dual_carriage] carriage has a position_endstop less than the primary carriage. Additionally, one could use \"SET_DUAL_CARRIAGE CARRIAGE=1 MODE=COPY\" or \"SET_DUAL_CARRIAGE CARRIAGE=1 MODE=MIRROR\" commands to activate either copying or mirroring mode of the dual carriage, in which case it will follow the motion of the carriage 0 accordingly. These commands can be used to print two parts simultaneously - either two identical parts (in COPY mode) or mirrored parts (in MIRROR mode). Note that COPY and MIRROR modes also require appropriate configuration of the extruder on the dual carriage, which can typically be achieved with \"SYNC_EXTRUDER_MOTION MOTION_QUEUE=extruder EXTRUDER= \" or a similar command. See sample-idex.cfg for an example configuration with a regular Cartesian kinematic. [dual_carriage] axis: # The axis this extra carriage is on (either x or y). This parameter # must be provided. #safe_distance: # The minimum distance (in mm) to enforce between the dual and the primary # carriages. If a G-Code command is executed that will bring the carriages # closer than the specified limit, such a command will be rejected with an # error. If safe_distance is not provided, it will be inferred from # position_min and position_max for the dual and primary carriages. If set # to 0 (or safe_distance is unset and position_min and position_max are # identical for the primary and dual carriages), the carriages proximity # checks will be disabled. #step_pin: #dir_pin: #enable_pin: #microsteps: #rotation_distance: #endstop_pin: #position_endstop: #position_min: #position_max: # See the \"stepper\" section for the definition of the above parameters. For an example of dual carriage configuration with generic_cartesian kinematic, see the following configuration sample . Please note that in this case the [dual_carriage] configuration deviates from the configuration described above: [dual_carriage my_dc_carriage] primary_carriage: # Defines the matching primary carriage of this dual carriage and # the corresponding IDEX axis. Valid choices are x, y, z. # This parameter must be provided. #safe_distance: # The minimum distance (in mm) to enforce between the dual and the primary # carriages. If a G-Code command is executed that will bring the carriages # closer than the specified limit, such a command will be rejected with an # error. If safe_distance is not provided, it will be inferred from # position_min and position_max for the dual and primary carriages. If set # to 0 (or safe_distance is unset and position_min and position_max are # identical for the primary and dual carriages), the carriages proximity # checks will be disabled. endstop_pin: #position_min: position_endstop: position_max: #homing_speed: #homing_retract_dist: #homing_retract_speed: #second_homing_speed: #homing_positive_dir: ... Refer to generic cartesian section for more information on the regular carriage parameters. Then a user must define one or more stepper motors moving the dual carriage (and other carriages as appropriate), for instance [carriage x] ... [carriage y] ... [dual_carriage u] primary_carriage: x ... [stepper dc_stepper] carriages: u-y ... [dual_carriage] requires special configuration for the input shaper. In general, it is necessary to run input shaper calibration twice - for the dual_carriage and its primary_carriage for the axis they share. Then the input shaper can be configured as follows, assuming the example above: [input_shaper] # Intentionally empty [delayed_gcode init_shaper] initial_duration: 0.1 gcode: SET_DUAL_CARRIAGE CARRIAGE=u SET_INPUT_SHAPER SHAPER_TYPE_X=<dual_carriage_x_shaper> SHAPER_FREQ_X=<dual_carriage_x_freq> SHAPER_TYPE_Y=<y_shaper> SHAPER_FREQ_Y=<y_freq> SET_DUAL_CARRIAGE CARRIAGE=x SET_INPUT_SHAPER SHAPER_TYPE_X=<primary_carriage_x_shaper> SHAPER_FREQ_X=<primary_carriage_x_freq> SHAPER_TYPE_Y=<y_shaper> SHAPER_FREQ_Y=<y_freq> Note that SHAPER_TYPE_Y and SHAPER_FREQ_Y must be the same in both commands in this case, since the same motors drive Y axis when either of the x and u carriages are active. It is worth noting that generic_cartesian kinematic can support two dual carriages for X and Y axes. For reference, see for instance a sample of CoreXYUV configuration.","title":"[dual_carriage]"},{"location":"Config_Reference.html#extruder_stepper","text":"Support for additional steppers synchronized to the movement of an extruder (one may define any number of sections with an \"extruder_stepper\" prefix). See the command reference for more information. [extruder_stepper my_extra_stepper] extruder: # The extruder this stepper is synchronized to. If this is set to an # empty string then the stepper will not be synchronized to an # extruder. This parameter must be provided. #step_pin: #dir_pin: #enable_pin: #microsteps: #rotation_distance: # See the \"stepper\" section for the definition of the above # parameters.","title":"[extruder_stepper]"},{"location":"Config_Reference.html#manual_stepper","text":"Manual steppers (one may define any number of sections with a \"manual_stepper\" prefix). These are steppers that are controlled by the MANUAL_STEPPER g-code command. For example: \"MANUAL_STEPPER STEPPER=my_stepper MOVE=10 SPEED=5\". See G-Codes file for a description of the MANUAL_STEPPER command. The steppers are not connected to the normal printer kinematics. [manual_stepper my_stepper] #step_pin: #dir_pin: #enable_pin: #microsteps: #rotation_distance: # See the \"stepper\" section for a description of these parameters. #velocity: # Set the default velocity (in mm/s) for the stepper. This value # will be used if a MANUAL_STEPPER command does not specify a SPEED # parameter. The default is 5mm/s. #accel: # Set the default acceleration (in mm/s^2) for the stepper. An # acceleration of zero will result in no acceleration. This value # will be used if a MANUAL_STEPPER command does not specify an ACCEL # parameter. The default is zero. #endstop_pin: # Endstop switch detection pin. If specified, then one may perform # \"homing moves\" by adding a STOP_ON_ENDSTOP parameter to # MANUAL_STEPPER movement commands. #position_min: #position_max: # The minimum and maximum position the stepper can be commanded to # move to. If specified then one may not command the stepper to move # past the given position. Note that these limits do not prevent # setting an arbitrary position with the `MANUAL_STEPPER # SET_POSITION=x` command. The default is to not enforce a limit.","title":"[manual_stepper]"},{"location":"Config_Reference.html#custom-heaters-and-sensors","text":"","title":"Custom heaters and sensors"},{"location":"Config_Reference.html#verify_heater","text":"Heater and temperature sensor verification. Heater verification is automatically enabled for each heater that is configured on the printer. Use verify_heater sections to change the default settings. [verify_heater heater_config_name] #max_error: 120 # The maximum \"cumulative temperature error\" before raising an # error. Smaller values result in stricter checking and larger # values allow for more time before an error is reported. # Specifically, the temperature is inspected once a second and if it # is close to the target temperature then an internal \"error # counter\" is reset; otherwise, if the temperature is below the # target range then the counter is increased by the amount the # reported temperature differs from that range. Should the counter # exceed this \"max_error\" then an error is raised. The default is # 120. #check_gain_time: # This controls heater verification during initial heating. Smaller # values result in stricter checking and larger values allow for # more time before an error is reported. Specifically, during # initial heating, as long as the heater increases in temperature # within this time frame (specified in seconds) then the internal # \"error counter\" is reset. The default is 20 seconds for extruders # and 60 seconds for heater_bed. #hysteresis: 5 # The maximum temperature difference (in Celsius) to a target # temperature that is considered in range of the target. This # controls the max_error range check. It is rare to customize this # value. The default is 5. #heating_gain: 2 # The minimum temperature (in Celsius) that the heater must increase # by during the check_gain_time check. It is rare to customize this # value. The default is 2.","title":"[verify_heater]"},{"location":"Config_Reference.html#homing_heaters","text":"Tool to disable heaters when homing or probing an axis. [homing_heaters] #steppers: # A comma separated list of steppers that should cause heaters to be # disabled. The default is to disable heaters for any homing/probing # move. # Typical example: stepper_z #heaters: # A comma separated list of heaters to disable during homing/probing # moves. The default is to disable all heaters. # Typical example: extruder, heater_bed","title":"[homing_heaters]"},{"location":"Config_Reference.html#thermistor","text":"Custom thermistors (one may define any number of sections with a \"thermistor\" prefix). A custom thermistor may be used in the sensor_type field of a heater config section. (For example, if one defines a \"[thermistor my_thermistor]\" section then one may use a \"sensor_type: my_thermistor\" when defining a heater.) Be sure to place the thermistor section in the config file above its first use in a heater section. [thermistor my_thermistor] #temperature1: #resistance1: #temperature2: #resistance2: #temperature3: #resistance3: # Three resistance measurements (in Ohms) at the given temperatures # (in Celsius). The three measurements will be used to calculate the # Steinhart-Hart coefficients for the thermistor. These parameters # must be provided when using Steinhart-Hart to define the # thermistor. #beta: # Alternatively, one may define temperature1, resistance1, and beta # to define the thermistor parameters. This parameter must be # provided when using \"beta\" to define the thermistor.","title":"[thermistor]"},{"location":"Config_Reference.html#adc_temperature","text":"Custom ADC temperature sensors (one may define any number of sections with an \"adc_temperature\" prefix). This allows one to define a custom temperature sensor that measures a voltage on an Analog to Digital Converter (ADC) pin and uses linear interpolation between a set of configured temperature/voltage (or temperature/resistance) measurements to determine the temperature. The resulting sensor can be used as a sensor_type in a heater section. (For example, if one defines a \"[adc_temperature my_sensor]\" section then one may use a \"sensor_type: my_sensor\" when defining a heater.) Be sure to place the sensor section in the config file above its first use in a heater section. [adc_temperature my_sensor] #temperature1: #voltage1: #temperature2: #voltage2: #... # A set of temperatures (in Celsius) and voltages (in Volts) to use # as reference when converting a temperature. A heater section using # this sensor may also specify adc_voltage and voltage_offset # parameters to define the ADC voltage (see \"Common temperature # amplifiers\" section for details). At least two measurements must # be provided. #temperature1: #resistance1: #temperature2: #resistance2: #... # Alternatively one may specify a set of temperatures (in Celsius) # and resistance (in Ohms) to use as reference when converting a # temperature. A heater section using this sensor may also specify a # pullup_resistor parameter (see \"extruder\" section for details). At # least two measurements must be provided.","title":"[adc_temperature]"},{"location":"Config_Reference.html#heater_generic","text":"Generic heaters (one may define any number of sections with a \"heater_generic\" prefix). These heaters behave similarly to standard heaters (extruders, heated beds). Use the SET_HEATER_TEMPERATURE command (see G-Codes for details) to set the target temperature. [heater_generic my_generic_heater] #gcode_id: # The id to use when reporting the temperature in the M105 command. # This parameter must be provided. #heater_pin: #max_power: #sensor_type: #sensor_pin: #smooth_time: #control: #pid_Kp: #pid_Ki: #pid_Kd: #pwm_cycle_time: #min_temp: #max_temp: # See the \"extruder\" section for the definition of the above # parameters.","title":"[heater_generic]"},{"location":"Config_Reference.html#temperature_sensor","text":"Generic temperature sensors. One can define any number of additional temperature sensors that are reported via the M105 command. [temperature_sensor my_sensor] #sensor_type: #sensor_pin: #min_temp: #max_temp: # See the \"extruder\" section for the definition of the above # parameters. #gcode_id: # See the \"heater_generic\" section for the definition of this # parameter.","title":"[temperature_sensor]"},{"location":"Config_Reference.html#temperature_probe","text":"Reports probe coil temperature. Includes optional thermal drift calibration for eddy current based probes. A [temperature_probe] section may be linked to a [probe_eddy_current] by using the same postfix for both sections. [temperature_probe my_probe] #sensor_type: #sensor_pin: #min_temp: #max_temp: # Temperature sensor configuration. # See the \"extruder\" section for the definition of the above # parameters. #smooth_time: # A time value (in seconds) over which temperature measurements will # be smoothed to reduce the impact of measurement noise. The default # is 2.0 seconds. #gcode_id: # See the \"heater_generic\" section for the definition of this # parameter. #speed: # The travel speed [mm/s] for xy moves during calibration. Default # is the speed defined by the probe. #horizontal_move_z: # The z distance [mm] from the bed at which xy moves will occur # during calibration. Default is 2mm. #resting_z: # The z distance [mm] from the bed at which the tool will rest # to heat the probe coil during calibration. Default is .4mm #calibration_position: # The X, Y, Z position where the tool should be moved when # probe drift calibration initializes. This is the location # where the first manual probe will occur. If omitted, the # default behavior is not to move the tool prior to the first # manual probe. #calibration_bed_temp: # The maximum safe bed temperature (in C) used to heat the probe # during probe drift calibration. When set, the calibration # procedure will turn on the bed after the first sample is # taken. When the calibration procedure is complete the bed # temperature will be set to zero. When omitted the default # behavior is not to set the bed temperature. #calibration_extruder_temp: # The extruder temperature (in C) set probe during drift calibration. # When this option is supplied the procedure will wait for until the # specified temperature is reached before requesting the first manual # probe. When the calibration procedure is complete the extruder # temperature will be set to 0. When omitted the default behavior is # not to set the extruder temperature. #extruder_heating_z: 50. # The Z location where extruder heating will occur if the # \"calibration_extruder_temp\" option is set. Its recommended to heat # the extruder some distance from the bed to minimize its impact on # the probe coil temperature. The default is 50. #max_validation_temp: 60. # The maximum temperature used to validate the calibration. It is # recommended to set this to a value between 100 and 120 for enclosed # printers. The default is 60.","title":"[temperature_probe]"},{"location":"Config_Reference.html#temperature-sensors","text":"Klipper includes definitions for many types of temperature sensors. These sensors may be used in any config section that requires a temperature sensor (such as an [extruder] or [heater_bed] section).","title":"Temperature sensors"},{"location":"Config_Reference.html#common-thermistors","text":"Common thermistors. The following parameters are available in heater sections that use one of these sensors. sensor_type: # One of \"EPCOS 100K B57560G104F\", \"ATC Semitec 104GT-2\", # \"ATC Semitec 104NT-4-R025H42G\", \"Generic 3950\", # \"Honeywell 100K 135-104LAG-J01\", \"NTC 100K MGB18-104F39050L32\", # \"SliceEngineering 450\", or \"TDK NTCG104LH104JT1\" sensor_pin: # Analog input pin connected to the thermistor. This parameter must # be provided. #pullup_resistor: 4700 # The resistance (in ohms) of the pullup attached to the thermistor. # The default is 4700 ohms. #inline_resistor: 0 # The resistance (in ohms) of an extra (not heat varying) resistor # that is placed inline with the thermistor. It is rare to set this. # The default is 0 ohms.","title":"Common thermistors"},{"location":"Config_Reference.html#common-temperature-amplifiers","text":"Common temperature amplifiers. The following parameters are available in heater sections that use one of these sensors. sensor_type: # One of \"PT100 INA826\", \"AD595\", \"AD597\", \"AD8494\", \"AD8495\", # \"AD8496\", or \"AD8497\". sensor_pin: # Analog input pin connected to the sensor. This parameter must be # provided. #adc_voltage: 5.0 # The ADC comparison voltage (in Volts). The default is 5 volts. #voltage_offset: 0 # The ADC voltage offset (in Volts). The default is 0.","title":"Common temperature amplifiers"},{"location":"Config_Reference.html#directly-connected-pt1000-sensor","text":"Directly connected PT1000 sensor. The following parameters are available in heater sections that use one of these sensors. sensor_type: PT1000 sensor_pin: # Analog input pin connected to the sensor. This parameter must be # provided. #pullup_resistor: 4700 # The resistance (in ohms) of the pullup attached to the sensor. The # default is 4700 ohms.","title":"Directly connected PT1000 sensor"},{"location":"Config_Reference.html#maxxxxxx-temperature-sensors","text":"MAXxxxxx serial peripheral interface (SPI) temperature based sensors. The following parameters are available in heater sections that use one of these sensor types. sensor_type: # One of \"MAX6675\", \"MAX31855\", \"MAX31856\", or \"MAX31865\". sensor_pin: # The chip select line for the sensor chip. This parameter must be # provided. #spi_speed: 4000000 # The SPI speed (in hz) to use when communicating with the chip. # The default is 4000000. #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #tc_type: K #tc_use_50Hz_filter: False #tc_averaging_count: 1 # The above parameters control the sensor parameters of MAX31856 # chips. The defaults for each parameter are next to the parameter # name in the above list. #rtd_nominal_r: 100 #rtd_reference_r: 430 #rtd_num_of_wires: 2 #rtd_use_50Hz_filter: False # The above parameters control the sensor parameters of MAX31865 # chips. The defaults for each parameter are next to the parameter # name in the above list.","title":"MAXxxxxx temperature sensors"},{"location":"Config_Reference.html#bmp180bmp280bme280bmp388bme680-temperature-sensor","text":"BMP180/BMP280/BME280/BMP388/BME680 two wire interface (I2C) environmental sensors. Note that these sensors are not intended for use with extruders and heater beds, but rather for monitoring ambient temperature (C), pressure (hPa), relative humidity and in case of the BME680 gas level. See sample-macros.cfg for a gcode_macro that may be used to report pressure and humidity in addition to temperature. sensor_type: BME280 #i2c_address: # Default is 118 (0x76). The BMP180, BMP388 and some BME280 sensors # have an address of 119 (0x77). #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters.","title":"BMP180/BMP280/BME280/BMP388/BME680 temperature sensor"},{"location":"Config_Reference.html#aht10aht20aht21-temperature-sensor","text":"AHT10/AHT20/AHT21 two wire interface (I2C) environmental sensors. Note that these sensors are not intended for use with extruders and heater beds, but rather for monitoring ambient temperature (C) and relative humidity. See sample-macros.cfg for a gcode_macro that may be used to report humidity in addition to temperature. sensor_type: AHT10 # Also use AHT10 for AHT20 and AHT21 sensors. #i2c_address: # Default is 56 (0x38). Some AHT10 sensors give the option to use # 57 (0x39) by moving a resistor. #i2c_mcu: #i2c_bus: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #aht10_report_time: # Interval in seconds between readings. Default is 30, minimum is 5","title":"AHT10/AHT20/AHT21 temperature sensor"},{"location":"Config_Reference.html#htu21d-sensor","text":"HTU21D family two wire interface (I2C) environmental sensor. Note that this sensor is not intended for use with extruders and heater beds, but rather for monitoring ambient temperature (C) and relative humidity. See sample-macros.cfg for a gcode_macro that may be used to report humidity in addition to temperature. sensor_type: # Must be \"HTU21D\" , \"SI7013\", \"SI7020\", \"SI7021\" or \"SHT21\" #i2c_address: # Default is 64 (0x40). #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #htu21d_hold_master: # If the sensor can hold the I2C buf while reading. If True no other # bus communication can be performed while reading is in progress. # Default is False. #htu21d_resolution: # The resolution of temperature and humidity reading. # Valid values are: # 'TEMP14_HUM12' -> 14bit for Temp and 12bit for humidity # 'TEMP13_HUM10' -> 13bit for Temp and 10bit for humidity # 'TEMP12_HUM08' -> 12bit for Temp and 08bit for humidity # 'TEMP11_HUM11' -> 11bit for Temp and 11bit for humidity # Default is: \"TEMP11_HUM11\" #htu21d_report_time: # Interval in seconds between readings. Default is 30","title":"HTU21D sensor"},{"location":"Config_Reference.html#sht3x-sensor","text":"SHT3X family two wire interface (I2C) environmental sensor. These sensors have a range of -55~125 C, so are usable for e.g. chamber temperature monitoring. They can also function as simple fan/heater controllers. sensor_type: SHT3X #i2c_address: # Default is 68 (0x44). #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters.","title":"SHT3X sensor"},{"location":"Config_Reference.html#lm75-temperature-sensor","text":"LM75/LM75A two wire (I2C) connected temperature sensors. These sensors have a range of -55~125 C, so are usable for e.g. chamber temperature monitoring. They can also function as simple fan/heater controllers. sensor_type: LM75 #i2c_address: # Default is 72 (0x48). Normal range is 72-79 (0x48-0x4F) and the 3 # low bits of the address are configured via pins on the chip # (usually with jumpers or hard wired). #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #lm75_report_time: # Interval in seconds between readings. Default is 0.8, with minimum # 0.5.","title":"LM75 temperature sensor"},{"location":"Config_Reference.html#builtin-micro-controller-temperature-sensor","text":"The atsam, atsamd, stm32 and rp2040 micro-controllers contain an internal temperature sensor. One can use the \"temperature_mcu\" sensor to monitor these temperatures. sensor_type: temperature_mcu #sensor_mcu: mcu # The micro-controller to read from. The default is \"mcu\". #sensor_temperature1: #sensor_adc1: # Specify the above two parameters (a temperature in Celsius and an # ADC value as a float between 0.0 and 1.0) to calibrate the # micro-controller temperature. This may improve the reported # temperature accuracy on some chips. A typical way to obtain this # calibration information is to completely remove power from the # printer for a few hours (to ensure it is at the ambient # temperature), then power it up and use the QUERY_ADC command to # obtain an ADC measurement. Use some other temperature sensor on # the printer to find the corresponding ambient temperature. The # default is to use the factory calibration data on the # micro-controller (if applicable) or the nominal values from the # micro-controller specification. #sensor_temperature2: #sensor_adc2: # If sensor_temperature1/sensor_adc1 is specified then one may also # specify sensor_temperature2/sensor_adc2 calibration data. Doing so # may provide calibrated \"temperature slope\" information. The # default is to use the factory calibration data on the # micro-controller (if applicable) or the nominal values from the # micro-controller specification.","title":"Builtin micro-controller temperature sensor"},{"location":"Config_Reference.html#host-temperature-sensor","text":"Temperature from the machine (eg Raspberry Pi) running the host software. sensor_type: temperature_host #sensor_path: # The path to temperature system file. The default is # \"/sys/class/thermal/thermal_zone0/temp\" which is the temperature # system file on a Raspberry Pi computer.","title":"Host temperature sensor"},{"location":"Config_Reference.html#ds18b20-temperature-sensor","text":"DS18B20 is a 1-wire (w1) digital temperature sensor. Note that this sensor is not intended for use with extruders and heater beds, but rather for monitoring ambient temperature (C). These sensors have range up to 125 C, so are usable for e.g. chamber temperature monitoring. They can also function as simple fan/heater controllers. DS18B20 sensors are only supported on the \"host mcu\", e.g. the Raspberry Pi. The w1-gpio Linux kernel module must be installed. sensor_type: DS18B20 serial_no: # Each 1-wire device has a unique serial number used to identify the device, # usually in the format 28-031674b175ff. This parameter must be provided. # Attached 1-wire devices can be listed using the following Linux command: # ls /sys/bus/w1/devices/ #ds18_report_time: # Interval in seconds between readings. Default is 3.0, with a minimum of 1.0 #sensor_mcu: # The micro-controller to read from. Must be the host_mcu","title":"DS18B20 temperature sensor"},{"location":"Config_Reference.html#combined-temperature-sensor","text":"Combined temperature sensor is a virtual temperature sensor based on several other sensors. This sensor can be used with extruders, heater_generic and heater beds. sensor_type: temperature_combined #sensor_list: # Must be provided. List of sensors to combine to new \"virtual\" # sensor. # E.g. 'temperature_sensor sensor1,extruder,heater_bed' #combination_method: # Must be provided. Combination method used for the sensor. # Available options are 'max', 'min', 'mean'. #maximum_deviation: # Must be provided. Maximum permissible deviation between the sensors # to combine (e.g. 5 degrees). To disable it, use a large value (e.g. 999.9)","title":"Combined temperature sensor"},{"location":"Config_Reference.html#fans","text":"","title":"Fans"},{"location":"Config_Reference.html#fan","text":"Print cooling fan. [fan] pin: # Output pin controlling the fan. This parameter must be provided. #max_power: 1.0 # The maximum power (expressed as a value from 0.0 to 1.0) that the # pin may be set to. The value 1.0 allows the pin to be set fully # enabled for extended periods, while a value of 0.5 would allow the # pin to be enabled for no more than half the time. This setting may # be used to limit the total power output (over extended periods) to # the fan. If this value is less than 1.0 then fan speed requests # will be scaled between zero and max_power (for example, if # max_power is .9 and a fan speed of 80% is requested then the fan # power will be set to 72%). The default is 1.0. #shutdown_speed: 0 # The desired fan speed (expressed as a value from 0.0 to 1.0) if # the micro-controller software enters an error state. The default # is 0. #cycle_time: 0.010 # The amount of time (in seconds) for each PWM power cycle to the # fan. It is recommended this be 10 milliseconds or greater when # using software based PWM. The default is 0.010 seconds. #hardware_pwm: False # Enable this to use hardware PWM instead of software PWM. Most fans # do not work well with hardware PWM, so it is not recommended to # enable this unless there is an electrical requirement to switch at # very high speeds. When using hardware PWM the actual cycle time is # constrained by the implementation and may be significantly # different than the requested cycle_time. The default is False. #kick_start_time: 0.100 # Time (in seconds) to run the fan at full speed when either first # enabling or increasing it by more than 50% (helps get the fan # spinning). The default is 0.100 seconds. #off_below: 0.0 # The minimum input speed which will power the fan (expressed as a # value from 0.0 to 1.0). When a speed lower than off_below is # requested the fan will instead be turned off. This setting may be # used to prevent fan stalls and to ensure kick starts are # effective. The default is 0.0. # # This setting should be recalibrated whenever max_power is adjusted. # To calibrate this setting, start with off_below set to 0.0 and the # fan spinning. Gradually lower the fan speed to determine the lowest # input speed which reliably drives the fan without stalls. Set # off_below to the duty cycle corresponding to this value (for # example, 12% -> 0.12) or slightly higher. #tachometer_pin: # Tachometer input pin for monitoring fan speed. A pullup is generally # required. This parameter is optional. #tachometer_ppr: 2 # When tachometer_pin is specified, this is the number of pulses per # revolution of the tachometer signal. For a BLDC fan this is # normally half the number of poles. The default is 2. #tachometer_poll_interval: 0.0015 # When tachometer_pin is specified, this is the polling period of the # tachometer pin, in seconds. The default is 0.0015, which is fast # enough for fans below 10000 RPM at 2 PPR. This must be smaller than # 30/(tachometer_ppr*rpm), with some margin, where rpm is the # maximum speed (in RPM) of the fan. #enable_pin: # Optional pin to enable power to the fan. This can be useful for fans # with dedicated PWM inputs. Some of these fans stay on even at 0% PWM # input. In such a case, the PWM pin can be used normally, and e.g. a # ground-switched FET(standard fan pin) can be used to control power to # the fan.","title":"[fan]"},{"location":"Config_Reference.html#heater_fan","text":"Heater cooling fans (one may define any number of sections with a \"heater_fan\" prefix). A \"heater fan\" is a fan that will be enabled whenever its associated heater is active. By default, a heater_fan has a shutdown_speed equal to max_power. [heater_fan heatbreak_cooling_fan] #pin: #max_power: #shutdown_speed: #cycle_time: #hardware_pwm: #kick_start_time: #off_below: #tachometer_pin: #tachometer_ppr: #tachometer_poll_interval: #enable_pin: # See the \"fan\" section for a description of the above parameters. #heater: extruder # Name of the config section defining the heater that this fan is # associated with. If a comma separated list of heater names is # provided here, then the fan will be enabled when any of the given # heaters are enabled. The default is \"extruder\". #heater_temp: 50.0 # A temperature (in Celsius) that the heater must drop below before # the fan is disabled. The default is 50 Celsius. #fan_speed: 1.0 # The fan speed (expressed as a value from 0.0 to 1.0) that the fan # will be set to when its associated heater is enabled. The default # is 1.0","title":"[heater_fan]"},{"location":"Config_Reference.html#controller_fan","text":"Controller cooling fan (one may define any number of sections with a \"controller_fan\" prefix). A \"controller fan\" is a fan that will be enabled whenever its associated heater or its associated stepper driver is active. The fan will stop whenever an idle_timeout is reached to ensure no overheating will occur after deactivating a watched component. [controller_fan my_controller_fan] #pin: #max_power: #shutdown_speed: #cycle_time: #hardware_pwm: #kick_start_time: #off_below: #tachometer_pin: #tachometer_ppr: #tachometer_poll_interval: #enable_pin: # See the \"fan\" section for a description of the above parameters. #fan_speed: 1.0 # The fan speed (expressed as a value from 0.0 to 1.0) that the fan # will be set to when a heater or stepper driver is active. # The default is 1.0 #idle_timeout: # The amount of time (in seconds) after a stepper driver or heater # was active and the fan should be kept running. The default # is 30 seconds. #idle_speed: # The fan speed (expressed as a value from 0.0 to 1.0) that the fan # will be set to when a heater or stepper driver was active and # before the idle_timeout is reached. The default is fan_speed. #heater: #stepper: # Name of the config section defining the heater/stepper that this fan # is associated with. If a comma separated list of heater/stepper names # is provided here, then the fan will be enabled when any of the given # heaters/steppers are enabled. The default heater is \"extruder\", the # default stepper is all of them.","title":"[controller_fan]"},{"location":"Config_Reference.html#temperature_fan","text":"Temperature-triggered cooling fans (one may define any number of sections with a \"temperature_fan\" prefix). A \"temperature fan\" is a fan that will be enabled whenever its associated sensor is above a set temperature. By default, a temperature_fan has a shutdown_speed equal to max_power. See the command reference for additional information. [temperature_fan my_temp_fan] #pin: #max_power: #shutdown_speed: #cycle_time: #hardware_pwm: #kick_start_time: #off_below: #tachometer_pin: #tachometer_ppr: #tachometer_poll_interval: #enable_pin: # See the \"fan\" section for a description of the above parameters. #sensor_type: #sensor_pin: #control: #max_delta: #min_temp: #max_temp: # See the \"extruder\" section for a description of the above parameters. #pid_Kp: #pid_Ki: #pid_Kd: # The proportional (pid_Kp), integral (pid_Ki), and derivative # (pid_Kd) settings for the PID feedback control system. Klipper # evaluates the PID settings with the following general formula: # fan_pwm = max_power - (Kp*e + Ki*integral(e) - Kd*derivative(e)) / 255 # Where \"e\" is \"target_temperature - measured_temperature\" and # \"fan_pwm\" is the requested fan rate with 0.0 being full off and # 1.0 being full on. The pid_Kp, pid_Ki, and pid_Kd parameters must # be provided when the PID control algorithm is enabled. #pid_deriv_time: 2.0 # A time value (in seconds) over which temperature measurements will # be smoothed when using the PID control algorithm. This may reduce # the impact of measurement noise. The default is 2 seconds. #target_temp: 40.0 # A temperature (in Celsius) that will be the target temperature. # The default is 40 degrees. #max_speed: 1.0 # The fan speed (expressed as a value from 0.0 to 1.0) that the fan # will be set to when the sensor temperature exceeds the set value. # The default is 1.0. #min_speed: 0.3 # The minimum fan speed (expressed as a value from 0.0 to 1.0) that # the fan will be set to for PID temperature fans. # The default is 0.3. #gcode_id: # If set, the temperature will be reported in M105 queries using the # given id. The default is to not report the temperature via M105.","title":"[temperature_fan]"},{"location":"Config_Reference.html#fan_generic","text":"Manually controlled fan (one may define any number of sections with a \"fan_generic\" prefix). The speed of a manually controlled fan is set with the SET_FAN_SPEED gcode command . [fan_generic extruder_partfan] #pin: #max_power: #shutdown_speed: #cycle_time: #hardware_pwm: #kick_start_time: #off_below: #tachometer_pin: #tachometer_ppr: #tachometer_poll_interval: #enable_pin: # See the \"fan\" section for a description of the above parameters.","title":"[fan_generic]"},{"location":"Config_Reference.html#leds","text":"","title":"LEDs"},{"location":"Config_Reference.html#led","text":"Support for LEDs (and LED strips) controlled via micro-controller PWM pins (one may define any number of sections with an \"led\" prefix). See the command reference for more information. [led my_led] #red_pin: #green_pin: #blue_pin: #white_pin: # The pin controlling the given LED color. At least one of the above # parameters must be provided. #cycle_time: 0.010 # The amount of time (in seconds) per PWM cycle. It is recommended # this be 10 milliseconds or greater when using software based PWM. # The default is 0.010 seconds. #hardware_pwm: False # Enable this to use hardware PWM instead of software PWM. When # using hardware PWM the actual cycle time is constrained by the # implementation and may be significantly different than the # requested cycle_time. The default is False. #initial_RED: 0.0 #initial_GREEN: 0.0 #initial_BLUE: 0.0 #initial_WHITE: 0.0 # Sets the initial LED color. Each value should be between 0.0 and # 1.0. The default for each color is 0.","title":"[led]"},{"location":"Config_Reference.html#neopixel","text":"Neopixel (aka WS2812) LED support (one may define any number of sections with a \"neopixel\" prefix). See the command reference for more information. Note that the linux mcu implementation does not currently support directly connected neopixels. The current design using the Linux kernel interface does not allow this scenario because the kernel GPIO interface is not fast enough to provide the required pulse rates. [neopixel my_neopixel] pin: # The pin connected to the neopixel. This parameter must be # provided. #chain_count: # The number of Neopixel chips that are \"daisy chained\" to the # provided pin. The default is 1 (which indicates only a single # Neopixel is connected to the pin). #color_order: GRB # Set the pixel order required by the LED hardware (using a string # containing the letters R, G, B, W with W optional). Alternatively, # this may be a comma separated list of pixel orders - one for each # LED in the chain. The default is GRB. #initial_RED: 0.0 #initial_GREEN: 0.0 #initial_BLUE: 0.0 #initial_WHITE: 0.0 # See the \"led\" section for information on these parameters.","title":"[neopixel]"},{"location":"Config_Reference.html#dotstar","text":"Dotstar (aka APA102) LED support (one may define any number of sections with a \"dotstar\" prefix). See the command reference for more information. [dotstar my_dotstar] data_pin: # The pin connected to the data line of the dotstar. This parameter # must be provided. clock_pin: # The pin connected to the clock line of the dotstar. This parameter # must be provided. #chain_count: # See the \"neopixel\" section for information on this parameter. #initial_RED: 0.0 #initial_GREEN: 0.0 #initial_BLUE: 0.0 # See the \"led\" section for information on these parameters.","title":"[dotstar]"},{"location":"Config_Reference.html#pca9533","text":"PCA9533 LED support. The PCA9533 is used on the mightyboard. [pca9533 my_pca9533] #i2c_address: 98 # The i2c address that the chip is using on the i2c bus. Use 98 for # the PCA9533/1, 99 for the PCA9533/2. The default is 98. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #initial_RED: 0.0 #initial_GREEN: 0.0 #initial_BLUE: 0.0 #initial_WHITE: 0.0 # See the \"led\" section for information on these parameters.","title":"[pca9533]"},{"location":"Config_Reference.html#pca9632","text":"PCA9632 LED support. The PCA9632 is used on the FlashForge Dreamer. [pca9632 my_pca9632] #i2c_address: 98 # The i2c address that the chip is using on the i2c bus. This may be # 96, 97, 98, or 99. The default is 98. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #color_order: RGBW # Set the pixel order of the LED (using a string containing the # letters R, G, B, W). The default is RGBW. #initial_RED: 0.0 #initial_GREEN: 0.0 #initial_BLUE: 0.0 #initial_WHITE: 0.0 # See the \"led\" section for information on these parameters.","title":"[pca9632]"},{"location":"Config_Reference.html#additional-servos-buttons-and-other-pins","text":"","title":"Additional servos, buttons, and other pins"},{"location":"Config_Reference.html#servo","text":"Servos (one may define any number of sections with a \"servo\" prefix). The servos may be controlled using the SET_SERVO g-code command . For example: SET_SERVO SERVO=my_servo ANGLE=180 [servo my_servo] pin: # PWM output pin controlling the servo. This parameter must be # provided. #maximum_servo_angle: 180 # The maximum angle (in degrees) that this servo can be set to. The # default is 180 degrees. #minimum_pulse_width: 0.001 # The minimum pulse width time (in seconds). This should correspond # with an angle of 0 degrees. The default is 0.001 seconds. #maximum_pulse_width: 0.002 # The maximum pulse width time (in seconds). This should correspond # with an angle of maximum_servo_angle. The default is 0.002 # seconds. #initial_angle: # Initial angle (in degrees) to set the servo to. The default is to # not send any signal at startup. #initial_pulse_width: # Initial pulse width time (in seconds) to set the servo to. (This # is only valid if initial_angle is not set.) The default is to not # send any signal at startup.","title":"[servo]"},{"location":"Config_Reference.html#gcode_button","text":"Execute gcode when a button is pressed or released (or when a pin changes state). You can check the state of the button by using QUERY_BUTTON button=my_gcode_button . [gcode_button my_gcode_button] pin: # The pin on which the button is connected. This parameter must be # provided. #analog_range: # Two comma separated resistances (in Ohms) specifying the minimum # and maximum resistance range for the button. If analog_range is # provided then the pin must be an analog capable pin. The default # is to use digital gpio for the button. #analog_pullup_resistor: # The pullup resistance (in Ohms) when analog_range is specified. # The default is 4700 ohms. #press_gcode: # A list of G-Code commands to execute when the button is pressed. # G-Code templates are supported. This parameter must be provided. #release_gcode: # A list of G-Code commands to execute when the button is released. # G-Code templates are supported. The default is to not run any # commands on a button release. #debounce_delay: # A period of time in seconds to debounce events prior to running the # button gcode. If the button is pressed and released during this # delay, the entire button press is ignored. Default is 0.","title":"[gcode_button]"},{"location":"Config_Reference.html#output_pin","text":"Run-time configurable output pins (one may define any number of sections with an \"output_pin\" prefix). Pins configured here will be setup as output pins and one may modify them at run-time using \"SET_PIN PIN=my_pin VALUE=.1\" type extended g-code commands . [output_pin my_pin] pin: # The pin to configure as an output. This parameter must be # provided. #pwm: False # Set if the output pin should be capable of pulse-width-modulation. # If this is true, the value fields should be between 0 and 1; if it # is false the value fields should be either 0 or 1. The default is # False. #value: # The value to initially set the pin to during MCU configuration. # The default is 0 (for low voltage). #shutdown_value: # The value to set the pin to on an MCU shutdown event. The default # is 0 (for low voltage). #cycle_time: 0.100 # The amount of time (in seconds) per PWM cycle. It is recommended # this be 10 milliseconds or greater when using software based PWM. # The default is 0.100 seconds for pwm pins. #hardware_pwm: False # Enable this to use hardware PWM instead of software PWM. When # using hardware PWM the actual cycle time is constrained by the # implementation and may be significantly different than the # requested cycle_time. The default is False. #scale: # This parameter can be used to alter how the 'value' and # 'shutdown_value' parameters are interpreted for pwm pins. If # provided, then the 'value' parameter should be between 0.0 and # 'scale'. This may be useful when configuring a PWM pin that # controls a stepper voltage reference. The 'scale' can be set to # the equivalent stepper amperage if the PWM were fully enabled, and # then the 'value' parameter can be specified using the desired # amperage for the stepper. The default is to not scale the 'value' # parameter. #maximum_mcu_duration: #static_value: # These options are deprecated and should no longer be specified.","title":"[output_pin]"},{"location":"Config_Reference.html#pwm_tool","text":"Pulse width modulation digital output pins capable of high speed updates (one may define any number of sections with an \"output_pin\" prefix). Pins configured here will be setup as output pins and one may modify them at run-time using \"SET_PIN PIN=my_pin VALUE=.1\" type extended g-code commands . [pwm_tool my_tool] pin: # The pin to configure as an output. This parameter must be provided. #maximum_mcu_duration: # The maximum duration a non-shutdown value may be driven by the MCU # without an acknowledge from the host. # If host can not keep up with an update, the MCU will shutdown # and set all pins to their respective shutdown values. # Default: 0 (disabled) # Usual values are around 5 seconds. #value: #shutdown_value: #cycle_time: 0.100 #hardware_pwm: False #scale: # See the \"output_pin\" section for the definition of these parameters.","title":"[pwm_tool]"},{"location":"Config_Reference.html#pwm_cycle_time","text":"Run-time configurable output pins with dynamic pwm cycle timing (one may define any number of sections with an \"pwm_cycle_time\" prefix). Pins configured here will be setup as output pins and one may modify them at run-time using \"SET_PIN PIN=my_pin VALUE=.1 CYCLE_TIME=0.100\" type extended g-code commands . [pwm_cycle_time my_pin] pin: #value: #shutdown_value: #cycle_time: 0.100 #scale: # See the \"output_pin\" section for information on these parameters.","title":"[pwm_cycle_time]"},{"location":"Config_Reference.html#static_digital_output","text":"Statically configured digital output pins (one may define any number of sections with a \"static_digital_output\" prefix). Pins configured here will be setup as a GPIO output during MCU configuration. They can not be changed at run-time. [static_digital_output my_output_pins] pins: # A comma separated list of pins to be set as GPIO output pins. The # pin will be set to a high level unless the pin name is prefaced # with \"!\". This parameter must be provided.","title":"[static_digital_output]"},{"location":"Config_Reference.html#multi_pin","text":"Multiple pin outputs (one may define any number of sections with a \"multi_pin\" prefix). A multi_pin output creates an internal pin alias that can modify multiple output pins each time the alias pin is set. For example, one could define a \"[multi_pin my_fan]\" object containing two pins and then set \"pin=multi_pin:my_fan\" in the \"[fan]\" section - on each fan change both output pins would be updated. These aliases may not be used with stepper motor pins. [multi_pin my_multi_pin] pins: # A comma separated list of pins associated with this alias. This # parameter must be provided.","title":"[multi_pin]"},{"location":"Config_Reference.html#tmc-stepper-driver-configuration","text":"Configuration of Trinamic stepper motor drivers in UART/SPI mode. Additional information is in the TMC Drivers guide and in the command reference .","title":"TMC stepper driver configuration"},{"location":"Config_Reference.html#tmc2130","text":"Configure a TMC2130 stepper motor driver via SPI bus. To use this feature, define a config section with a \"tmc2130\" prefix followed by the name of the corresponding stepper config section (for example, \"[tmc2130 stepper_x]\"). [tmc2130 stepper_x] cs_pin: # The pin corresponding to the TMC2130 chip select line. This pin # will be set to low at the start of SPI messages and raised to high # after the message completes. This parameter must be provided. #spi_speed: #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #chain_position: #chain_length: # These parameters configure an SPI daisy chain. The two parameters # define the stepper position in the chain and the total chain length. # Position 1 corresponds to the stepper that connects to the MOSI signal. # The default is to not use an SPI daisy chain. #interpolate: True # If true, enable step interpolation (the driver will internally # step at a rate of 256 micro-steps). This interpolation does # introduce a small systemic positional deviation - see # TMC_Drivers.md for details. The default is True. run_current: # The amount of current (in amps RMS) to configure the driver to use # during stepper movement. This parameter must be provided. #hold_current: # The amount of current (in amps RMS) to configure the driver to use # when the stepper is not moving. Setting a hold_current is not # recommended (see TMC_Drivers.md for details). The default is to # not reduce the current. #sense_resistor: 0.110 # The resistance (in ohms) of the motor sense resistor. The default # is 0.110 ohms. #stealthchop_threshold: 0 # The velocity (in mm/s) to set the \"stealthChop\" threshold to. When # set, \"stealthChop\" mode will be enabled if the stepper motor # velocity is below this value. Note that the \"sensorless homing\" # code may temporarily override this setting during homing # operations. The default is 0, which disables \"stealthChop\" mode. #coolstep_threshold: # The velocity (in mm/s) to set the TMC driver internal \"CoolStep\" # threshold to. If set, the coolstep feature will be enabled when # the stepper motor velocity is near or above this value. Important # - if coolstep_threshold is set and \"sensorless homing\" is used, # then one must ensure that the homing speed is above the coolstep # threshold! The default is to not enable the coolstep feature. #high_velocity_threshold: # The velocity (in mm/s) to set the TMC driver internal \"high # velocity\" threshold (THIGH) to. This is typically used to disable # the \"CoolStep\" feature at high speeds. The default is to not set a # TMC \"high velocity\" threshold. #driver_MSLUT0: 2863314260 #driver_MSLUT1: 1251300522 #driver_MSLUT2: 608774441 #driver_MSLUT3: 269500962 #driver_MSLUT4: 4227858431 #driver_MSLUT5: 3048961917 #driver_MSLUT6: 1227445590 #driver_MSLUT7: 4211234 #driver_W0: 2 #driver_W1: 1 #driver_W2: 1 #driver_W3: 1 #driver_X1: 128 #driver_X2: 255 #driver_X3: 255 #driver_START_SIN: 0 #driver_START_SIN90: 247 # These fields control the Microstep Table registers directly. The optimal # wave table is specific to each motor and might vary with current. An # optimal configuration will have minimal print artifacts caused by # non-linear stepper movement. The values specified above are the default # values used by the driver. The value must be specified as a decimal integer # (hex form is not supported). In order to compute the wave table fields, # see the tmc2130 \"Calculation Sheet\" from the Trinamic website. #driver_IHOLDDELAY: 8 #driver_TPOWERDOWN: 0 #driver_TBL: 1 #driver_TOFF: 4 #driver_HEND: 7 #driver_HSTRT: 0 #driver_VHIGHFS: 0 #driver_VHIGHCHM: 0 #driver_PWM_AUTOSCALE: True #driver_PWM_FREQ: 1 #driver_PWM_GRAD: 4 #driver_PWM_AMPL: 128 #driver_FREEWHEEL: 0 #driver_SGT: 0 #driver_SEMIN: 0 #driver_SEUP: 0 #driver_SEMAX: 0 #driver_SEDN: 0 #driver_SEIMIN: 0 #driver_SFILT: 0 # Set the given register during the configuration of the TMC2130 # chip. This may be used to set custom motor parameters. The # defaults for each parameter are next to the parameter name in the # above list. #diag0_pin: #diag1_pin: # The micro-controller pin attached to one of the DIAG lines of the # TMC2130 chip. Only a single diag pin should be specified. The pin # is \"active low\" and is thus normally prefaced with \"^!\". Setting # this creates a \"tmc2130_stepper_x:virtual_endstop\" virtual pin # which may be used as the stepper's endstop_pin. Doing this enables # \"sensorless homing\". (Be sure to also set driver_SGT to an # appropriate sensitivity value.) The default is to not enable # sensorless homing.","title":"[tmc2130]"},{"location":"Config_Reference.html#tmc2208","text":"Configure a TMC2208 (or TMC2224) stepper motor driver via single wire UART. To use this feature, define a config section with a \"tmc2208\" prefix followed by the name of the corresponding stepper config section (for example, \"[tmc2208 stepper_x]\"). [tmc2208 stepper_x] uart_pin: # The pin connected to the TMC2208 PDN_UART line. This parameter # must be provided. #tx_pin: # If using separate receive and transmit lines to communicate with # the driver then set uart_pin to the receive pin and tx_pin to the # transmit pin. The default is to use uart_pin for both reading and # writing. #select_pins: # A comma separated list of pins to set prior to accessing the # tmc2208 UART. This may be useful for configuring an analog mux for # UART communication. The default is to not configure any pins. #interpolate: True # If true, enable step interpolation (the driver will internally # step at a rate of 256 micro-steps). This interpolation does # introduce a small systemic positional deviation - see # TMC_Drivers.md for details. The default is True. run_current: # The amount of current (in amps RMS) to configure the driver to use # during stepper movement. This parameter must be provided. #hold_current: # The amount of current (in amps RMS) to configure the driver to use # when the stepper is not moving. Setting a hold_current is not # recommended (see TMC_Drivers.md for details). The default is to # not reduce the current. #sense_resistor: 0.110 # The resistance (in ohms) of the motor sense resistor. The default # is 0.110 ohms. #stealthchop_threshold: 0 # The velocity (in mm/s) to set the \"stealthChop\" threshold to. When # set, \"stealthChop\" mode will be enabled if the stepper motor # velocity is below this value. Note that the \"sensorless homing\" # code may temporarily override this setting during homing # operations. The default is 0, which disables \"stealthChop\" mode. #driver_MULTISTEP_FILT: True #driver_IHOLDDELAY: 8 #driver_TPOWERDOWN: 20 #driver_TBL: 2 #driver_TOFF: 3 #driver_HEND: 0 #driver_HSTRT: 5 #driver_PWM_AUTOGRAD: True #driver_PWM_AUTOSCALE: True #driver_PWM_LIM: 12 #driver_PWM_REG: 8 #driver_PWM_FREQ: 1 #driver_PWM_GRAD: 14 #driver_PWM_OFS: 36 #driver_FREEWHEEL: 0 # Set the given register during the configuration of the TMC2208 # chip. This may be used to set custom motor parameters. The # defaults for each parameter are next to the parameter name in the # above list.","title":"[tmc2208]"},{"location":"Config_Reference.html#tmc2209","text":"Configure a TMC2209 stepper motor driver via single wire UART. To use this feature, define a config section with a \"tmc2209\" prefix followed by the name of the corresponding stepper config section (for example, \"[tmc2209 stepper_x]\"). [tmc2209 stepper_x] uart_pin: #tx_pin: #select_pins: #interpolate: True run_current: #hold_current: #sense_resistor: 0.110 #stealthchop_threshold: 0 # See the \"tmc2208\" section for the definition of these parameters. #coolstep_threshold: # The velocity (in mm/s) to set the TMC driver internal \"CoolStep\" # threshold to. If set, the coolstep feature will be enabled when # the stepper motor velocity is near or above this value. Important # - if coolstep_threshold is set and \"sensorless homing\" is used, # then one must ensure that the homing speed is above the coolstep # threshold! The default is to not enable the coolstep feature. #uart_address: # The address of the TMC2209 chip for UART messages (an integer # between 0 and 3). This is typically used when multiple TMC2209 # chips are connected to the same UART pin. The default is zero. #driver_MULTISTEP_FILT: True #driver_IHOLDDELAY: 8 #driver_TPOWERDOWN: 20 #driver_TBL: 2 #driver_TOFF: 3 #driver_HEND: 0 #driver_HSTRT: 5 #driver_PWM_AUTOGRAD: True #driver_PWM_AUTOSCALE: True #driver_PWM_LIM: 12 #driver_PWM_REG: 8 #driver_PWM_FREQ: 1 #driver_PWM_GRAD: 14 #driver_PWM_OFS: 36 #driver_FREEWHEEL: 0 #driver_SGTHRS: 0 #driver_SEMIN: 0 #driver_SEUP: 0 #driver_SEMAX: 0 #driver_SEDN: 0 #driver_SEIMIN: 0 # Set the given register during the configuration of the TMC2209 # chip. This may be used to set custom motor parameters. The # defaults for each parameter are next to the parameter name in the # above list. #diag_pin: # The micro-controller pin attached to the DIAG line of the TMC2209 # chip. The pin is normally prefaced with \"^\" to enable a pullup. # Setting this creates a \"tmc2209_stepper_x:virtual_endstop\" virtual # pin which may be used as the stepper's endstop_pin. Doing this # enables \"sensorless homing\". (Be sure to also set driver_SGTHRS to # an appropriate sensitivity value.) The default is to not enable # sensorless homing.","title":"[tmc2209]"},{"location":"Config_Reference.html#tmc2660","text":"Configure a TMC2660 stepper motor driver via SPI bus. To use this feature, define a config section with a tmc2660 prefix followed by the name of the corresponding stepper config section (for example, \"[tmc2660 stepper_x]\"). [tmc2660 stepper_x] cs_pin: # The pin corresponding to the TMC2660 chip select line. This pin # will be set to low at the start of SPI messages and set to high # after the message transfer completes. This parameter must be # provided. #spi_speed: 4000000 # SPI bus frequency used to communicate with the TMC2660 stepper # driver. The default is 4000000. #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #interpolate: True # If true, enable step interpolation (the driver will internally # step at a rate of 256 micro-steps). This only works if microsteps # is set to 16. Interpolation does introduce a small systemic # positional deviation - see TMC_Drivers.md for details. The default # is True. run_current: # The amount of current (in amps RMS) used by the driver during # stepper movement. This parameter must be provided. #sense_resistor: # The resistance (in ohms) of the motor sense resistor. This # parameter must be provided. #idle_current_percent: 100 # The percentage of the run_current the stepper driver will be # lowered to when the idle timeout expires (you need to set up the # timeout using a [idle_timeout] config section). The current will # be raised again once the stepper has to move again. Make sure to # set this to a high enough value such that the steppers do not lose # their position. There is also small delay until the current is # raised again, so take this into account when commanding fast moves # while the stepper is idling. The default is 100 (no reduction). #driver_TBL: 2 #driver_RNDTF: 0 #driver_HDEC: 0 #driver_CHM: 0 #driver_HEND: 3 #driver_HSTRT: 3 #driver_TOFF: 4 #driver_SEIMIN: 0 #driver_SEDN: 0 #driver_SEMAX: 0 #driver_SEUP: 0 #driver_SEMIN: 0 #driver_SFILT: 0 #driver_SGT: 0 #driver_SLPH: 0 #driver_SLPL: 0 #driver_DISS2G: 0 #driver_TS2G: 3 # Set the given parameter during the configuration of the TMC2660 # chip. This may be used to set custom driver parameters. The # defaults for each parameter are next to the parameter name in the # list above. See the TMC2660 datasheet about what each parameter # does and what the restrictions on parameter combinations are. Be # especially aware of the CHOPCONF register, where setting CHM to # either zero or one will lead to layout changes (the first bit of # HDEC) is interpreted as the MSB of HSTRT in this case).","title":"[tmc2660]"},{"location":"Config_Reference.html#tmc2240","text":"Configure a TMC2240 stepper motor driver via SPI bus or UART. To use this feature, define a config section with a \"tmc2240\" prefix followed by the name of the corresponding stepper config section (for example, \"[tmc2240 stepper_x]\"). [tmc2240 stepper_x] cs_pin: # The pin corresponding to the TMC2240 chip select line. This pin # will be set to low at the start of SPI messages and raised to high # after the message completes. This parameter must be provided. #spi_speed: #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #uart_pin: # The pin connected to the TMC2240 DIAG1/SW line. If this parameter # is provided UART communication is used rather then SPI. #chain_position: #chain_length: # These parameters configure an SPI daisy chain. The two parameters # define the stepper position in the chain and the total chain length. # Position 1 corresponds to the stepper that connects to the MOSI signal. # The default is to not use an SPI daisy chain. #interpolate: True # If true, enable step interpolation (the driver will internally # step at a rate of 256 micro-steps). The default is True. run_current: # The amount of current (in amps RMS) to configure the driver to use # during stepper movement. This parameter must be provided. #hold_current: # The amount of current (in amps RMS) to configure the driver to use # when the stepper is not moving. Setting a hold_current is not # recommended (see TMC_Drivers.md for details). The default is to # not reduce the current. #rref: 12000 # The resistance (in ohms) of the resistor between IREF and GND. The # default is 12000. #stealthchop_threshold: 0 # The velocity (in mm/s) to set the \"stealthChop\" threshold to. When # set, \"stealthChop\" mode will be enabled if the stepper motor # velocity is below this value. Note that the \"sensorless homing\" # code may temporarily override this setting during homing # operations. The default is 0, which disables \"stealthChop\" mode. #coolstep_threshold: # The velocity (in mm/s) to set the TMC driver internal \"CoolStep\" # threshold to. If set, the coolstep feature will be enabled when # the stepper motor velocity is near or above this value. Important # - if coolstep_threshold is set and \"sensorless homing\" is used, # then one must ensure that the homing speed is above the coolstep # threshold! The default is to not enable the coolstep feature. #high_velocity_threshold: # The velocity (in mm/s) to set the TMC driver internal \"high # velocity\" threshold (THIGH) to. This is typically used to disable # the \"CoolStep\" feature at high speeds. The default is to not set a # TMC \"high velocity\" threshold. #driver_MSLUT0: 2863314260 #driver_MSLUT1: 1251300522 #driver_MSLUT2: 608774441 #driver_MSLUT3: 269500962 #driver_MSLUT4: 4227858431 #driver_MSLUT5: 3048961917 #driver_MSLUT6: 1227445590 #driver_MSLUT7: 4211234 #driver_W0: 2 #driver_W1: 1 #driver_W2: 1 #driver_W3: 1 #driver_X1: 128 #driver_X2: 255 #driver_X3: 255 #driver_START_SIN: 0 #driver_START_SIN90: 247 #driver_OFFSET_SIN90: 0 # These fields control the Microstep Table registers directly. The optimal # wave table is specific to each motor and might vary with current. An # optimal configuration will have minimal print artifacts caused by # non-linear stepper movement. The values specified above are the default # values used by the driver. The value must be specified as a decimal integer # (hex form is not supported). In order to compute the wave table fields, # see the tmc2130 \"Calculation Sheet\" from the Trinamic website. # Additionally, this driver also has the OFFSET_SIN90 field which can be used # to tune a motor with unbalanced coils. See the `Sine Wave Lookup Table` # section in the datasheet for information about this field and how to tune # it. #driver_MULTISTEP_FILT: True #driver_IHOLDDELAY: 6 #driver_IRUNDELAY: 4 #driver_TPOWERDOWN: 10 #driver_TBL: 2 #driver_TOFF: 3 #driver_HEND: 2 #driver_HSTRT: 5 #driver_FD3: 0 #driver_TPFD: 4 #driver_CHM: 0 #driver_VHIGHFS: 0 #driver_VHIGHCHM: 0 #driver_DISS2G: 0 #driver_DISS2VS: 0 #driver_PWM_AUTOSCALE: True #driver_PWM_AUTOGRAD: True #driver_PWM_FREQ: 0 #driver_FREEWHEEL: 0 #driver_PWM_GRAD: 0 #driver_PWM_OFS: 29 #driver_PWM_REG: 4 #driver_PWM_LIM: 12 #driver_SGT: 0 #driver_SEMIN: 0 #driver_SEUP: 0 #driver_SEMAX: 0 #driver_SEDN: 0 #driver_SEIMIN: 0 #driver_SFILT: 0 #driver_SG4_ANGLE_OFFSET: 1 #driver_SLOPE_CONTROL: 0 # Set the given register during the configuration of the TMC2240 # chip. This may be used to set custom motor parameters. The # defaults for each parameter are next to the parameter name in the # above list. #diag0_pin: #diag1_pin: # The micro-controller pin attached to one of the DIAG lines of the # TMC2240 chip. Only a single diag pin should be specified. The pin # is \"active low\" and is thus normally prefaced with \"^!\". Setting # this creates a \"tmc2240_stepper_x:virtual_endstop\" virtual pin # which may be used as the stepper's endstop_pin. Doing this enables # \"sensorless homing\". (Be sure to also set driver_SGT to an # appropriate sensitivity value.) The default is to not enable # sensorless homing.","title":"[tmc2240]"},{"location":"Config_Reference.html#tmc5160","text":"Configure a TMC5160 stepper motor driver via SPI bus. To use this feature, define a config section with a \"tmc5160\" prefix followed by the name of the corresponding stepper config section (for example, \"[tmc5160 stepper_x]\"). [tmc5160 stepper_x] cs_pin: # The pin corresponding to the TMC5160 chip select line. This pin # will be set to low at the start of SPI messages and raised to high # after the message completes. This parameter must be provided. #spi_speed: #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #chain_position: #chain_length: # These parameters configure an SPI daisy chain. The two parameters # define the stepper position in the chain and the total chain length. # Position 1 corresponds to the stepper that connects to the MOSI signal. # The default is to not use an SPI daisy chain. #interpolate: True # If true, enable step interpolation (the driver will internally # step at a rate of 256 micro-steps). The default is True. run_current: # The amount of current (in amps RMS) to configure the driver to use # during stepper movement. This parameter must be provided. #hold_current: # The amount of current (in amps RMS) to configure the driver to use # when the stepper is not moving. Setting a hold_current is not # recommended (see TMC_Drivers.md for details). The default is to # not reduce the current. #sense_resistor: 0.075 # The resistance (in ohms) of the motor sense resistor. The default # is 0.075 ohms. #stealthchop_threshold: 0 # The velocity (in mm/s) to set the \"stealthChop\" threshold to. When # set, \"stealthChop\" mode will be enabled if the stepper motor # velocity is below this value. Note that the \"sensorless homing\" # code may temporarily override this setting during homing # operations. The default is 0, which disables \"stealthChop\" mode. #coolstep_threshold: # The velocity (in mm/s) to set the TMC driver internal \"CoolStep\" # threshold to. If set, the coolstep feature will be enabled when # the stepper motor velocity is near or above this value. Important # - if coolstep_threshold is set and \"sensorless homing\" is used, # then one must ensure that the homing speed is above the coolstep # threshold! The default is to not enable the coolstep feature. #high_velocity_threshold: # The velocity (in mm/s) to set the TMC driver internal \"high # velocity\" threshold (THIGH) to. This is typically used to disable # the \"CoolStep\" feature at high speeds. The default is to not set a # TMC \"high velocity\" threshold. #driver_MSLUT0: 2863314260 #driver_MSLUT1: 1251300522 #driver_MSLUT2: 608774441 #driver_MSLUT3: 269500962 #driver_MSLUT4: 4227858431 #driver_MSLUT5: 3048961917 #driver_MSLUT6: 1227445590 #driver_MSLUT7: 4211234 #driver_W0: 2 #driver_W1: 1 #driver_W2: 1 #driver_W3: 1 #driver_X1: 128 #driver_X2: 255 #driver_X3: 255 #driver_START_SIN: 0 #driver_START_SIN90: 247 # These fields control the Microstep Table registers directly. The optimal # wave table is specific to each motor and might vary with current. An # optimal configuration will have minimal print artifacts caused by # non-linear stepper movement. The values specified above are the default # values used by the driver. The value must be specified as a decimal integer # (hex form is not supported). In order to compute the wave table fields, # see the tmc2130 \"Calculation Sheet\" from the Trinamic website. #driver_MULTISTEP_FILT: True #driver_IHOLDDELAY: 6 #driver_TPOWERDOWN: 10 #driver_TBL: 2 #driver_TOFF: 3 #driver_HEND: 2 #driver_HSTRT: 5 #driver_FD3: 0 #driver_TPFD: 4 #driver_CHM: 0 #driver_VHIGHFS: 0 #driver_VHIGHCHM: 0 #driver_DISS2G: 0 #driver_DISS2VS: 0 #driver_PWM_AUTOSCALE: True #driver_PWM_AUTOGRAD: True #driver_PWM_FREQ: 0 #driver_FREEWHEEL: 0 #driver_PWM_GRAD: 0 #driver_PWM_OFS: 30 #driver_PWM_REG: 4 #driver_PWM_LIM: 12 #driver_SGT: 0 #driver_SEMIN: 0 #driver_SEUP: 0 #driver_SEMAX: 0 #driver_SEDN: 0 #driver_SEIMIN: 0 #driver_SFILT: 0 #driver_DRVSTRENGTH: 0 #driver_BBMCLKS: 4 #driver_BBMTIME: 0 #driver_FILT_ISENSE: 0 # Set the given register during the configuration of the TMC5160 # chip. This may be used to set custom motor parameters. The # defaults for each parameter are next to the parameter name in the # above list. #diag0_pin: #diag1_pin: # The micro-controller pin attached to one of the DIAG lines of the # TMC5160 chip. Only a single diag pin should be specified. The pin # is \"active low\" and is thus normally prefaced with \"^!\". Setting # this creates a \"tmc5160_stepper_x:virtual_endstop\" virtual pin # which may be used as the stepper's endstop_pin. Doing this enables # \"sensorless homing\". (Be sure to also set driver_SGT to an # appropriate sensitivity value.) The default is to not enable # sensorless homing.","title":"[tmc5160]"},{"location":"Config_Reference.html#run-time-stepper-motor-current-configuration","text":"","title":"Run-time stepper motor current configuration"},{"location":"Config_Reference.html#ad5206","text":"Statically configured AD5206 digipots connected via SPI bus (one may define any number of sections with an \"ad5206\" prefix). [ad5206 my_digipot] enable_pin: # The pin corresponding to the AD5206 chip select line. This pin # will be set to low at the start of SPI messages and raised to high # after the message completes. This parameter must be provided. #spi_speed: #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #channel_1: #channel_2: #channel_3: #channel_4: #channel_5: #channel_6: # The value to statically set the given AD5206 channel to. This is # typically set to a number between 0.0 and 1.0 with 1.0 being the # highest resistance and 0.0 being the lowest resistance. However, # the range may be changed with the 'scale' parameter (see below). # If a channel is not specified then it is left unconfigured. #scale: # This parameter can be used to alter how the 'channel_x' parameters # are interpreted. If provided, then the 'channel_x' parameters # should be between 0.0 and 'scale'. This may be useful when the # AD5206 is used to set stepper voltage references. The 'scale' can # be set to the equivalent stepper amperage if the AD5206 were at # its highest resistance, and then the 'channel_x' parameters can be # specified using the desired amperage value for the stepper. The # default is to not scale the 'channel_x' parameters.","title":"[ad5206]"},{"location":"Config_Reference.html#mcp4451","text":"Statically configured MCP4451 digipot connected via I2C bus (one may define any number of sections with an \"mcp4451\" prefix). [mcp4451 my_digipot] i2c_address: # The i2c address that the chip is using on the i2c bus. This # parameter must be provided. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #wiper_0: #wiper_1: #wiper_2: #wiper_3: # The value to statically set the given MCP4451 \"wiper\" to. This is # typically set to a number between 0.0 and 1.0 with 1.0 being the # highest resistance and 0.0 being the lowest resistance. However, # the range may be changed with the 'scale' parameter (see below). # If a wiper is not specified then it is left unconfigured. #scale: # This parameter can be used to alter how the 'wiper_x' parameters # are interpreted. If provided, then the 'wiper_x' parameters should # be between 0.0 and 'scale'. This may be useful when the MCP4451 is # used to set stepper voltage references. The 'scale' can be set to # the equivalent stepper amperage if the MCP4451 were at its highest # resistance, and then the 'wiper_x' parameters can be specified # using the desired amperage value for the stepper. The default is # to not scale the 'wiper_x' parameters.","title":"[mcp4451]"},{"location":"Config_Reference.html#mcp4728","text":"Statically configured MCP4728 digital-to-analog converter connected via I2C bus (one may define any number of sections with an \"mcp4728\" prefix). [mcp4728 my_dac] #i2c_address: 96 # The i2c address that the chip is using on the i2c bus. The default # is 96. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #channel_a: #channel_b: #channel_c: #channel_d: # The value to statically set the given MCP4728 channel to. This is # typically set to a number between 0.0 and 1.0 with 1.0 being the # highest voltage (2.048V) and 0.0 being the lowest voltage. # However, the range may be changed with the 'scale' parameter (see # below). If a channel is not specified then it is left # unconfigured. #scale: # This parameter can be used to alter how the 'channel_x' parameters # are interpreted. If provided, then the 'channel_x' parameters # should be between 0.0 and 'scale'. This may be useful when the # MCP4728 is used to set stepper voltage references. The 'scale' can # be set to the equivalent stepper amperage if the MCP4728 were at # its highest voltage (2.048V), and then the 'channel_x' parameters # can be specified using the desired amperage value for the # stepper. The default is to not scale the 'channel_x' parameters.","title":"[mcp4728]"},{"location":"Config_Reference.html#mcp4018","text":"Statically configured MCP4018 digipot connected via i2c (one may define any number of sections with an \"mcp4018\" prefix). [mcp4018 my_digipot] #i2c_address: 47 # The i2c address that the chip is using on the i2c bus. The default # is 47. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. wiper: # The value to statically set the given MCP4018 \"wiper\" to. This is # typically set to a number between 0.0 and 1.0 with 1.0 being the # highest resistance and 0.0 being the lowest resistance. However, # the range may be changed with the 'scale' parameter (see below). # This parameter must be provided. #scale: # This parameter can be used to alter how the 'wiper' parameter is # interpreted. If provided, then the 'wiper' parameter should be # between 0.0 and 'scale'. This may be useful when the MCP4018 is # used to set stepper voltage references. The 'scale' can be set to # the equivalent stepper amperage if the MCP4018 is at its highest # resistance, and then the 'wiper' parameter can be specified using # the desired amperage value for the stepper. The default is to not # scale the 'wiper' parameter.","title":"[mcp4018]"},{"location":"Config_Reference.html#display-support","text":"","title":"Display support"},{"location":"Config_Reference.html#display","text":"Support for a display attached to the micro-controller. [display] lcd_type: # The type of LCD chip in use. This may be \"hd44780\", \"hd44780_spi\", # \"aip31068_spi\", \"st7920\", \"emulated_st7920\", \"uc1701\", \"ssd1306\", or # \"sh1106\". # See the display sections below for information on each type and # additional parameters they provide. This parameter must be # provided. #display_group: # The name of the display_data group to show on the display. This # controls the content of the screen (see the \"display_data\" section # for more information). The default is _default_20x4 for hd44780 or # aip31068_spi displays and _default_16x4 for other displays. #menu_timeout: # Timeout for menu. Being inactive this amount of seconds will # trigger menu exit or return to root menu when having autorun # enabled. The default is 0 seconds (disabled) #menu_root: # Name of the main menu section to show when clicking the encoder # on the home screen. The defaults is __main, and this shows the # the default menus as defined in klippy/extras/display/menu.cfg #menu_reverse_navigation: # When enabled it will reverse up and down directions for list # navigation. The default is False. This parameter is optional. #encoder_pins: # The pins connected to encoder. 2 pins must be provided when using # encoder. This parameter must be provided when using menu. #encoder_steps_per_detent: # How many steps the encoder emits per detent (\"click\"). If the # encoder takes two detents to move between entries or moves two # entries from one detent, try changing this. Allowed values are 2 # (half-stepping) or 4 (full-stepping). The default is 4. #click_pin: # The pin connected to 'enter' button or encoder 'click'. This # parameter must be provided when using menu. The presence of an # 'analog_range_click_pin' config parameter turns this parameter # from digital to analog. #back_pin: # The pin connected to 'back' button. This parameter is optional, # menu can be used without it. The presence of an # 'analog_range_back_pin' config parameter turns this parameter from # digital to analog. #up_pin: # The pin connected to 'up' button. This parameter must be provided # when using menu without encoder. The presence of an # 'analog_range_up_pin' config parameter turns this parameter from # digital to analog. #down_pin: # The pin connected to 'down' button. This parameter must be # provided when using menu without encoder. The presence of an # 'analog_range_down_pin' config parameter turns this parameter from # digital to analog. #kill_pin: # The pin connected to 'kill' button. This button will call # emergency stop. The presence of an 'analog_range_kill_pin' config # parameter turns this parameter from digital to analog. #analog_pullup_resistor: 4700 # The resistance (in ohms) of the pullup attached to the analog # button. The default is 4700 ohms. #analog_range_click_pin: # The resistance range for a 'enter' button. Range minimum and # maximum comma-separated values must be provided when using analog # button. #analog_range_back_pin: # The resistance range for a 'back' button. Range minimum and # maximum comma-separated values must be provided when using analog # button. #analog_range_up_pin: # The resistance range for a 'up' button. Range minimum and maximum # comma-separated values must be provided when using analog button. #analog_range_down_pin: # The resistance range for a 'down' button. Range minimum and # maximum comma-separated values must be provided when using analog # button. #analog_range_kill_pin: # The resistance range for a 'kill' button. Range minimum and # maximum comma-separated values must be provided when using analog # button.","title":"[display]"},{"location":"Config_Reference.html#hd44780-display","text":"Information on configuring hd44780 displays (which is used in \"RepRapDiscount 2004 Smart Controller\" type displays). [display] lcd_type: hd44780 # Set to \"hd44780\" for hd44780 displays. rs_pin: e_pin: d4_pin: d5_pin: d6_pin: d7_pin: # The pins connected to an hd44780 type lcd. These parameters must # be provided. #hd44780_protocol_init: True # Perform 8-bit/4-bit protocol initialization on an hd44780 display. # This is necessary on real hd44780 devices. However, one may need # to disable this on some \"clone\" devices. The default is True. #line_length: # Set the number of characters per line for an hd44780 type lcd. # Possible values are 20 (default) and 16. The number of lines is # fixed to 4. ...","title":"hd44780 display"},{"location":"Config_Reference.html#hd44780_spi-display","text":"Information on configuring an hd44780_spi display - a 20x04 display controlled via a hardware \"shift register\" (which is used in mightyboard based printers). [display] lcd_type: hd44780_spi # Set to \"hd44780_spi\" for hd44780_spi displays. latch_pin: spi_software_sclk_pin: spi_software_mosi_pin: spi_software_miso_pin: # The pins connected to the shift register controlling the display. # The spi_software_miso_pin needs to be set to an unused pin of the # printer mainboard as the shift register does not have a MISO pin, # but the software spi implementation requires this pin to be # configured. #hd44780_protocol_init: True # Perform 8-bit/4-bit protocol initialization on an hd44780 display. # This is necessary on real hd44780 devices. However, one may need # to disable this on some \"clone\" devices. The default is True. #line_length: # Set the number of characters per line for an hd44780 type lcd. # Possible values are 20 (default) and 16. The number of lines is # fixed to 4. ...","title":"hd44780_spi display"},{"location":"Config_Reference.html#aip31068_spi-display","text":"Information on configuring an aip31068_spi display - a very similar to hd44780_spi a 20x04 (20 symbols by 4 lines) display with slightly different internal protocol. [display] lcd_type: aip31068_spi latch_pin: spi_software_sclk_pin: spi_software_mosi_pin: spi_software_miso_pin: # The pins connected to the shift register controlling the display. # The spi_software_miso_pin needs to be set to an unused pin of the # printer mainboard as the shift register does not have a MISO pin, # but the software spi implementation requires this pin to be # configured. #line_length: # Set the number of characters per line for an hd44780 type lcd. # Possible values are 20 (default) and 16. The number of lines is # fixed to 4. ...","title":"aip31068_spi display"},{"location":"Config_Reference.html#st7920-display","text":"Information on configuring st7920 displays (which is used in \"RepRapDiscount 12864 Full Graphic Smart Controller\" type displays). [display] lcd_type: st7920 # Set to \"st7920\" for st7920 displays. cs_pin: sclk_pin: sid_pin: # The pins connected to an st7920 type lcd. These parameters must be # provided. ...","title":"st7920 display"},{"location":"Config_Reference.html#emulated_st7920-display","text":"Information on configuring an emulated st7920 display - found in some \"2.4 inch touchscreen devices\" and similar. [display] lcd_type: emulated_st7920 # Set to \"emulated_st7920\" for emulated_st7920 displays. en_pin: spi_software_sclk_pin: spi_software_mosi_pin: spi_software_miso_pin: # The pins connected to an emulated_st7920 type lcd. The en_pin # corresponds to the cs_pin of the st7920 type lcd, # spi_software_sclk_pin corresponds to sclk_pin and # spi_software_mosi_pin corresponds to sid_pin. The # spi_software_miso_pin needs to be set to an unused pin of the # printer mainboard as the st7920 as no MISO pin but the software # spi implementation requires this pin to be configured. ...","title":"emulated_st7920 display"},{"location":"Config_Reference.html#uc1701-display","text":"Information on configuring uc1701 displays (which is used in \"MKS Mini 12864\" type displays). [display] lcd_type: uc1701 # Set to \"uc1701\" for uc1701 displays. cs_pin: a0_pin: # The pins connected to a uc1701 type lcd. These parameters must be # provided. #rst_pin: # The pin connected to the \"rst\" pin on the lcd. If it is not # specified then the hardware must have a pull-up on the # corresponding lcd line. #contrast: # The contrast to set. The value may range from 0 to 63 and the # default is 40. ...","title":"uc1701 display"},{"location":"Config_Reference.html#ssd1306-and-sh1106-displays","text":"Information on configuring ssd1306 and sh1106 displays. [display] lcd_type: # Set to either \"ssd1306\" or \"sh1106\" for the given display type. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # Optional parameters available for displays connected via an i2c # bus. See the \"common I2C settings\" section for a description of # the above parameters. #cs_pin: #dc_pin: #spi_speed: #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # The pins connected to the lcd when in \"4-wire\" spi mode. See the # \"common SPI settings\" section for a description of the parameters # that start with \"spi_\". The default is to use i2c mode for the # display. #reset_pin: # A reset pin may be specified on the display. If it is not # specified then the hardware must have a pull-up on the # corresponding lcd line. #contrast: # The contrast to set. The value may range from 0 to 256 and the # default is 239. #vcomh: 0 # Set the Vcomh value on the display. This value is associated with # a \"smearing\" effect on some OLED displays. The value may range # from 0 to 63. Default is 0. #invert: False # TRUE inverts the pixels on certain OLED displays. The default is # False. #x_offset: 0 # Set the horizontal offset value on SH1106 displays. The default is # 0. ...","title":"ssd1306 and sh1106 displays"},{"location":"Config_Reference.html#display_data","text":"Support for displaying custom data on an lcd screen. One may create any number of display groups and any number of data items under those groups. The display will show all the data items for a given group if the display_group option in the [display] section is set to the given group name. A default set of display groups are automatically created. One can replace or extend these display_data items by overriding the defaults in the main printer.cfg config file. [display_data my_group_name my_data_name] position: # Comma separated row and column of the display position that should # be used to display the information. This parameter must be # provided. text: # The text to show at the given position. This field is evaluated # using command templates (see docs/Command_Templates.md). This # parameter must be provided.","title":"[display_data]"},{"location":"Config_Reference.html#display_template","text":"Display data text \"macros\" (one may define any number of sections with a display_template prefix). See the command templates document for information on template evaluation. This feature allows one to reduce repetitive definitions in display_data sections. One may use the builtin render() function in display_data sections to evaluate a template. For example, if one were to define [display_template my_template] then one could use { render('my_template') } in a display_data section. This feature can also be used for continuous LED updates using the SET_LED_TEMPLATE command. [display_template my_template_name] #param_<name>: # One may specify any number of options with a \"param_\" prefix. The # given name will be assigned the given value (parsed as a Python # literal) and will be available during macro expansion. If the # parameter is passed in the call to render() then that value will # be used during macro expansion. For example, a config with # \"param_speed = 75\" might have a caller with # \"render('my_template_name', param_speed=80)\". Parameter names may # not use upper case characters. text: # The text to return when the this template is rendered. This field # is evaluated using command templates (see # docs/Command_Templates.md). This parameter must be provided.","title":"[display_template]"},{"location":"Config_Reference.html#display_glyph","text":"Display a custom glyph on displays that support it. The given name will be assigned the given display data which can then be referenced in the display templates by their name surrounded by two \"tilde\" symbols i.e. ~my_display_glyph~ See sample-glyphs.cfg for some examples. [display_glyph my_display_glyph] #data: # The display data, stored as 16 lines consisting of 16 bits (1 per # pixel) where '.' is a blank pixel and '*' is an on pixel (e.g., # \"****************\" to display a solid horizontal line). # Alternatively, one can use '0' for a blank pixel and '1' for an on # pixel. Put each display line into a separate config line. The # glyph must consist of exactly 16 lines with 16 bits each. This # parameter is optional. #hd44780_data: # Glyph to use on 20x4 hd44780 displays. The glyph must consist of # exactly 8 lines with 5 bits each. This parameter is optional. #hd44780_slot: # The hd44780 hardware index (0..7) to store the glyph at. If # multiple distinct images use the same slot then make sure to only # use one of those images in any given screen. This parameter is # required if hd44780_data is specified.","title":"[display_glyph]"},{"location":"Config_Reference.html#display-my_extra_display","text":"If a primary [display] section has been defined in printer.cfg as shown above it is possible to define multiple auxiliary displays. Note that auxiliary displays do not currently support menu functionality, thus they do not support the \"menu\" options or button configuration. [display my_extra_display] # See the \"display\" section for available parameters.","title":"[display my_extra_display]"},{"location":"Config_Reference.html#menu","text":"Customizable lcd display menus. A default set of menus are automatically created. One can replace or extend the menu by overriding the defaults in the main printer.cfg config file. See the command template document for information on menu attributes available during template rendering. # Common parameters available for all menu config sections. #[menu __some_list __some_name] #type: disabled # Permanently disabled menu element, only required attribute is 'type'. # Allows you to easily disable/hide existing menu items. #[menu some_name] #type: # One of command, input, list, text: # command - basic menu element with various script triggers # input - same like 'command' but has value changing capabilities. # Press will start/stop edit mode. # list - it allows for menu items to be grouped together in a # scrollable list. Add to the list by creating menu # configurations using \"some_list\" as a prefix - for # example: [menu some_list some_item_in_the_list] # vsdlist - same as 'list' but will append files from virtual sdcard # (will be removed in the future) #name: # Name of menu item - evaluated as a template. #enable: # Template that evaluates to True or False. #index: # Position where an item needs to be inserted in list. By default # the item is added at the end. #[menu some_list] #type: list #name: #enable: # See above for a description of these parameters. #[menu some_list some_command] #type: command #name: #enable: # See above for a description of these parameters. #gcode: # Script to run on button click or long click. Evaluated as a # template. #[menu some_list some_input] #type: input #name: #enable: # See above for a description of these parameters. #input: # Initial value to use when editing - evaluated as a template. # Result must be float. #input_min: # Minimum value of range - evaluated as a template. Default -99999. #input_max: # Maximum value of range - evaluated as a template. Default 99999. #input_step: # Editing step - Must be a positive integer or float value. It has # internal fast rate step. When \"(input_max - input_min) / # input_step > 100\" then fast rate step is 10 * input_step else fast # rate step is same input_step. #realtime: # This attribute accepts static boolean value. When enabled then # gcode script is run after each value change. The default is False. #gcode: # Script to run on button click, long click or value change. # Evaluated as a template. The button click will trigger the edit # mode start or end.","title":"[menu]"},{"location":"Config_Reference.html#filament-sensors","text":"","title":"Filament sensors"},{"location":"Config_Reference.html#filament_switch_sensor","text":"Filament Switch Sensor. Support for filament insert and runout detection using a switch sensor, such as an endstop switch. See the command reference for more information. [filament_switch_sensor my_sensor] #pause_on_runout: True # When set to True, a PAUSE will execute immediately after a runout # is detected. Note that if pause_on_runout is False and the # runout_gcode is omitted then runout detection is disabled. Default # is True. #runout_gcode: # A list of G-Code commands to execute after a filament runout is # detected. See docs/Command_Templates.md for G-Code format. If # pause_on_runout is set to True this G-Code will run after the # PAUSE is complete. The default is not to run any G-Code commands. #insert_gcode: # A list of G-Code commands to execute after a filament insert is # detected. See docs/Command_Templates.md for G-Code format. The # default is not to run any G-Code commands, which disables insert # detection. #event_delay: 3.0 # The minimum amount of time in seconds to delay between events. # Events triggered during this time period will be silently # ignored. The default is 3 seconds. #pause_delay: 0.5 # The amount of time to delay, in seconds, between the pause command # dispatch and execution of the runout_gcode. It may be useful to # increase this delay if OctoPrint exhibits strange pause behavior. # Default is 0.5 seconds. #debounce_delay: # A period of time in seconds to debounce events prior to running the # switch gcode. The switch must he held in a single state for at least # this long to activate. If the switch is toggled on/off during this delay, # the event is ignored. Default is 0. #switch_pin: # The pin on which the switch is connected. This parameter must be # provided.","title":"[filament_switch_sensor]"},{"location":"Config_Reference.html#filament_motion_sensor","text":"Filament Motion Sensor. Support for filament insert and runout detection using an encoder that toggles the output pin during filament movement through the sensor. See the command reference for more information. [filament_motion_sensor my_sensor] detection_length: 7.0 # The minimum length of filament pulled through the sensor to trigger # a state change on the switch_pin # Default is 7 mm. extruder: # The name of the extruder or extruder_stepper section this sensor # is associated with. This parameter must be provided. switch_pin: #pause_on_runout: #runout_gcode: #insert_gcode: #event_delay: #pause_delay: # See the \"filament_switch_sensor\" section for a description of the # above parameters.","title":"[filament_motion_sensor]"},{"location":"Config_Reference.html#tsl1401cl_filament_width_sensor","text":"TSLl401CL Based Filament Width Sensor. See the guide for more information. [tsl1401cl_filament_width_sensor] #pin: #default_nominal_filament_diameter: 1.75 # (mm) # Maximum allowed filament diameter difference as mm. #max_difference: 0.2 # The distance from sensor to the melting chamber as mm. #measurement_delay: 100","title":"[tsl1401cl_filament_width_sensor]"},{"location":"Config_Reference.html#hall_filament_width_sensor","text":"Hall filament width sensor (see Hall Filament Width Sensor ). [hall_filament_width_sensor] adc1: adc2: # Analog input pins connected to the sensor. These parameters must # be provided. #cal_dia1: 1.50 #cal_dia2: 2.00 # The calibration values (in mm) for the sensors. The default is # 1.50 for cal_dia1 and 2.00 for cal_dia2. #raw_dia1: 9500 #raw_dia2: 10500 # The raw calibration values for the sensors. The default is 9500 # for raw_dia1 and 10500 for raw_dia2. #default_nominal_filament_diameter: 1.75 # The nominal filament diameter. This parameter must be provided. #max_difference: 0.200 # Maximum allowed filament diameter difference in millimeters (mm). # If difference between nominal filament diameter and sensor output # is more than +- max_difference, extrusion multiplier is set back # to %100. The default is 0.200. #measurement_delay: 70 # The distance from sensor to the melting chamber/hot-end in # millimeters (mm). The filament between the sensor and the hot-end # will be treated as the default_nominal_filament_diameter. Host # module works with FIFO logic. It keeps each sensor value and # position in an array and POP them back in correct position. This # parameter must be provided. #enable: False # Sensor enabled or disabled after power on. The default is to # disable. #measurement_interval: 10 # The approximate distance (in mm) between sensor readings. The # default is 10mm. #logging: False # Out diameter to terminal and klipper.log can be turn on|of by # command. #min_diameter: 1.0 # Minimal diameter for trigger virtual filament_switch_sensor. #max_diameter: # Maximum diameter for triggering virtual filament_switch_sensor. # The default is default_nominal_filament_diameter + max_difference. #use_current_dia_while_delay: False # Use the current diameter instead of the nominal diameter while # the measurement delay has not run through. #pause_on_runout: #runout_gcode: #insert_gcode: #event_delay: #pause_delay: # See the \"filament_switch_sensor\" section for a description of the # above parameters.","title":"[hall_filament_width_sensor]"},{"location":"Config_Reference.html#load-cells","text":"","title":"Load Cells"},{"location":"Config_Reference.html#load_cell","text":"Load Cell. Uses an ADC sensor attached to a load cell to create a digital scale. [load_cell] sensor_type: # This must be one of the supported sensor types, see below. #counts_per_gram: # The floating point number of sensor counts that indicates 1 gram of force. # This value is calculated by the LOAD_CELL_CALIBRATE command. #reference_tare_counts: # The integer tare value, in raw sensor counts, taken when LOAD_CELL_CALIBRATE # is run. This is the default tare value when klipper starts up. #sensor_orientation: # Change the sensor's orientation. Can be either 'normal' or 'inverted'. # The default is 'normal'. Use 'inverted' if the sensor reports a # decreasing force value when placed under load.","title":"[load_cell]"},{"location":"Config_Reference.html#hx711","text":"This is a 24 bit low sample rate chip using \"bit-bang\" communications. It is suitable for filament scales. [load_cell] sensor_type: hx711 sclk_pin: # The pin connected to the HX711 clock line. This parameter must be provided. dout_pin: # The pin connected to the HX711 data output line. This parameter must be # provided. #gain: A-128 # Valid values for gain are: A-128, A-64, B-32. The default is A-128. # 'A' denotes the input channel and the number denotes the gain. Only the 3 # listed combinations are supported by the chip. Note that changing the gain # setting also selects the channel being read. #sample_rate: 80 # Valid values for sample_rate are 80 or 10. The default value is 80. # This must match the wiring of the chip. The sample rate cannot be changed # in software.","title":"HX711"},{"location":"Config_Reference.html#hx717","text":"This is the 4x higher sample rate version of the HX711, suitable for probing. [load_cell] sensor_type: hx717 sclk_pin: # The pin connected to the HX717 clock line. This parameter must be provided. dout_pin: # The pin connected to the HX717 data output line. This parameter must be # provided. #gain: A-128 # Valid values for gain are A-128, B-64, A-64, B-8. # 'A' denotes the input channel and the number denotes the gain setting. # Only the 4 listed combinations are supported by the chip. Note that # changing the gain setting also selects the channel being read. #sample_rate: 320 # Valid values for sample_rate are: 10, 20, 80, 320. The default is 320. # This must match the wiring of the chip. The sample rate cannot be changed # in software.","title":"HX717"},{"location":"Config_Reference.html#ads1220","text":"The ADS1220 is a 24 bit ADC supporting up to a 2Khz sample rate configurable in software. [load_cell] sensor_type: ads1220 cs_pin: # The pin connected to the ADS1220 chip select line. This parameter must # be provided. #spi_speed: 512000 # This chip supports 2 speeds: 256000 or 512000. The faster speed is only # enabled when one of the Turbo sample rates is used. The correct spi_speed # is selected based on the sample rate. #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. data_ready_pin: # Pin connected to the ADS1220 data ready line. This parameter must be # provided. #gain: 128 # Valid gain values are 128, 64, 32, 16, 8, 4, 2, 1 # The default is 128 #pga_bypass: False # Disable the internal Programmable Gain Amplifier. If # True the PGA will be disabled for gains 1, 2, and 4. The PGA is always # enabled for gain settings 8 to 128, regardless of the pga_bypass setting. # If AVSS is used as an input pga_bypass is forced to True. # The default is False. #sample_rate: 660 # This chip supports two ranges of sample rates, Normal and Turbo. In turbo # mode the chip's internal clock runs twice as fast and the SPI communication # speed is also doubled. # Normal sample rates: 20, 45, 90, 175, 330, 600, 1000 # Turbo sample rates: 40, 90, 180, 350, 660, 1200, 2000 # The default is 660 #input_mux: # Input multiplexer configuration, select a pair of pins to use. The first pin # is the positive, AINP, and the second pin is the negative, AINN. Valid # values are: 'AIN0_AIN1', 'AIN0_AIN2', 'AIN0_AIN3', 'AIN1_AIN2', 'AIN1_AIN3', # 'AIN2_AIN3', 'AIN1_AIN0', 'AIN3_AIN2', 'AIN0_AVSS', 'AIN1_AVSS', 'AIN2_AVSS' # and 'AIN3_AVSS'. If AVSS is used the PGA is bypassed and the pga_bypass # setting will be forced to True. # The default is AIN0_AIN1. #vref: # The selected voltage reference. Valid values are: 'internal', 'REF0', 'REF1' # and 'analog_supply'. Default is 'internal'.","title":"ADS1220"},{"location":"Config_Reference.html#load_cell_probe","text":"Load Cell Probe. This combines the functionality of a [probe] and a [load_cell]. [load_cell_probe] sensor_type: # This must be one of the supported bulk ADC sensor types and support # load cell endstops on the mcu. #counts_per_gram: #reference_tare_counts: #sensor_orientation: # These parameters must be configured before the probe will operate. # See the [load_cell] section for further details. #force_safety_limit: 2000 # The safe limit for probing force relative to the reference_tare_counts on # the load_cell. The default is +/-2Kg. #trigger_force: 75.0 # The force that the probe will trigger at. 75g is the default. #drift_filter_cutoff_frequency: 0.8 # Enable optional continuous taring while homing & probing to reject drift. # The value is a frequency, in Hz, below which drift will be ignored. This # option requires the SciPy library. Default: None #drift_filter_delay: 2 # The delay, or 'order', of the drift filter. This controls the number of # samples required to make a trigger detection. Can be 1 or 2, the default # is 2. #buzz_filter_cutoff_frequency: 100.0 # The value is a frequency, in Hz, above which high frequency noise in the # load cell will be igfiltered outnored. This option requires the SciPy # library. Default: None #buzz_filter_delay: 2 # The delay, or 'order', of the buzz filter. This controls the number of # samples required to make a trigger detection. Can be 1 or 2, the default # is 2. #notch_filter_frequencies: 50, 60 # 1 or 2 frequencies, in Hz, to filter out of the load cell data. This is # intended to reject power line noise. This option requires the SciPy # library. Default: None #notch_filter_quality: 2.0 # Controls how narrow the range of frequencies are that the notch filter # removes. Larger numbers produce a narrower filter. Minimum value is 0.5 and # maximum is 3.0. Default: 2.0 #tare_time: # The rime in seconds used for taring the load_cell before each probe. The # default value is: 4 / 60 = 0.066. This collects samples from 4 cycles of # 60Hz mains power to cancel power line noise. #z_offset: #speed: #samples: #sample_retract_dist: #lift_speed: #samples_result: #samples_tolerance: #samples_tolerance_retries: #activate_gcode: #deactivate_gcode: # See the \"[probe]\" section for a description of the above parameters.","title":"[load_cell_probe]"},{"location":"Config_Reference.html#board-specific-hardware-support","text":"","title":"Board specific hardware support"},{"location":"Config_Reference.html#sx1509","text":"Configure an SX1509 I2C to GPIO expander. Due to the delay incurred by I2C communication you should NOT use SX1509 pins as stepper enable, step or dir pins or any other pin that requires fast bit-banging. They are best used as static or gcode controlled digital outputs or hardware-pwm pins for e.g. fans. One may define any number of sections with an \"sx1509\" prefix. Each expander provides a set of 16 pins (sx1509_my_sx1509:PIN_0 to sx1509_my_sx1509:PIN_15) which can be used in the printer configuration. See the generic-duet2-duex.cfg file for an example. [sx1509 my_sx1509] i2c_address: # I2C address used by this expander. Depending on the hardware # jumpers this is one out of the following addresses: 62 63 112 # 113. This parameter must be provided. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters.","title":"[sx1509]"},{"location":"Config_Reference.html#samd_sercom","text":"SAMD SERCOM configuration to specify which pins to use on a given SERCOM. One may define any number of sections with a \"samd_sercom\" prefix. Each SERCOM must be configured prior to using it as SPI or I2C peripheral. Place this config section above any other section that makes use of SPI or I2C buses. [samd_sercom my_sercom] sercom: # The name of the sercom bus to configure in the micro-controller. # Available names are \"sercom0\", \"sercom1\", etc.. This parameter # must be provided. tx_pin: # MOSI pin for SPI communication, or SDA (data) pin for I2C # communication. The pin must have a valid pinmux configuration # for the given SERCOM peripheral. This parameter must be provided. #rx_pin: # MISO pin for SPI communication. This pin is not used for I2C # communication (I2C uses tx_pin for both sending and receiving). # The pin must have a valid pinmux configuration for the given # SERCOM peripheral. This parameter is optional. clk_pin: # CLK pin for SPI communication, or SCL (clock) pin for I2C # communication. The pin must have a valid pinmux configuration # for the given SERCOM peripheral. This parameter must be provided.","title":"[samd_sercom]"},{"location":"Config_Reference.html#adc_scaled","text":"Duet2 Maestro analog scaling by vref and vssa readings. Defining an adc_scaled section enables virtual adc pins (such as \"my_name:PB0\") that are automatically adjusted by the board's vref and vssa monitoring pins. Be sure to define this config section above any config sections that use one these virtual pins. See the generic-duet2-maestro.cfg file for an example. [adc_scaled my_name] vref_pin: # The ADC pin to use for VREF monitoring. This parameter must be # provided. vssa_pin: # The ADC pin to use for VSSA monitoring. This parameter must be # provided. #smooth_time: 2.0 # A time value (in seconds) over which the vref and vssa # measurements will be smoothed to reduce the impact of measurement # noise. The default is 2 seconds.","title":"[adc_scaled]"},{"location":"Config_Reference.html#ads1x1x","text":"ADS1013, ADS1014, ADS1015, ADS1113, ADS1114 and ADS1115 are I2C based Analog to Digital Converters that can be used for temperature sensors. They provide 4 analog input pins either as single line or as differential input. Note: Use caution if using this sensor to control heaters. The heater min_temp and max_temp are only verified in the host and only if the host is running and operating normally. (ADC inputs directly connected to the micro-controller verify min_temp and max_temp within the micro-controller and do not require a working connection to the host.) [ads1x1x my_ads1x1x] chip: ADS1115 #pga: 4.096V # Default value is 4.096V. The maximum voltage range used for the input. This # scales all values read from the ADC. Options are: 6.144V, 4.096V, 2.048V, # 1.024V, 0.512V, 0.256V #adc_voltage: 3.3 # The supply voltage for the device. This allows additional software scaling # for all values read from the ADC. i2c_mcu: host i2c_bus: i2c.1 #address_pin: GND # Default value is GND. There can be up to four addressed devices depending # upon wiring of the device. Check the datasheet for details. The i2c_address # can be specified directly instead of using the address_pin. The chip provides pins that can be used on other sensors. sensor_type: ... # Can be any thermistor or adc_temperature. sensor_pin: my_ads1x1x:AIN0 # A combination of the name of the ads1x1x chip and the pin. Possible # pin values are AIN0, AIN1, AIN2 and AIN3 for single ended lines and # DIFF01, DIFF03, DIFF13 and DIFF23 for differential between their # corresponding lines. For example # DIFF03 measures the differential between line 0 and 3. Only specific # combinations for the differentials are allowed.","title":"[ads1x1x]"},{"location":"Config_Reference.html#replicape","text":"Replicape support - see the beaglebone guide and the generic-replicape.cfg file for an example. # The \"replicape\" config section adds \"replicape:stepper_x_enable\" # virtual stepper enable pins (for steppers X, Y, Z, E, and H) and # \"replicape:power_x\" PWM output pins (for hotbed, e, h, fan0, fan1, # fan2, and fan3) that may then be used elsewhere in the config file. [replicape] revision: # The replicape hardware revision. Currently only revision \"B3\" is # supported. This parameter must be provided. #enable_pin: !gpio0_20 # The replicape global enable pin. The default is !gpio0_20 (aka # P9_41). host_mcu: # The name of the mcu config section that communicates with the # Klipper \"linux process\" mcu instance. This parameter must be # provided. #standstill_power_down: False # This parameter controls the CFG6_ENN line on all stepper # motors. True sets the enable lines to \"open\". The default is # False. #stepper_x_microstep_mode: #stepper_y_microstep_mode: #stepper_z_microstep_mode: #stepper_e_microstep_mode: #stepper_h_microstep_mode: # This parameter controls the CFG1 and CFG2 pins of the given # stepper motor driver. Available options are: disable, 1, 2, # spread2, 4, 16, spread4, spread16, stealth4, and stealth16. The # default is disable. #stepper_x_current: #stepper_y_current: #stepper_z_current: #stepper_e_current: #stepper_h_current: # The configured maximum current (in Amps) of the stepper motor # driver. This parameter must be provided if the stepper is not in a # disable mode. #stepper_x_chopper_off_time_high: #stepper_y_chopper_off_time_high: #stepper_z_chopper_off_time_high: #stepper_e_chopper_off_time_high: #stepper_h_chopper_off_time_high: # This parameter controls the CFG0 pin of the stepper motor driver # (True sets CFG0 high, False sets it low). The default is False. #stepper_x_chopper_hysteresis_high: #stepper_y_chopper_hysteresis_high: #stepper_z_chopper_hysteresis_high: #stepper_e_chopper_hysteresis_high: #stepper_h_chopper_hysteresis_high: # This parameter controls the CFG4 pin of the stepper motor driver # (True sets CFG4 high, False sets it low). The default is False. #stepper_x_chopper_blank_time_high: #stepper_y_chopper_blank_time_high: #stepper_z_chopper_blank_time_high: #stepper_e_chopper_blank_time_high: #stepper_h_chopper_blank_time_high: # This parameter controls the CFG5 pin of the stepper motor driver # (True sets CFG5 high, False sets it low). The default is True.","title":"[replicape]"},{"location":"Config_Reference.html#other-custom-modules","text":"","title":"Other Custom Modules"},{"location":"Config_Reference.html#palette2","text":"Palette 2 multimaterial support - provides a tighter integration supporting Palette 2 devices in connected mode. This modules also requires [virtual_sdcard] and [pause_resume] for full functionality. If you use this module, do not use the Palette 2 plugin for Octoprint as they will conflict, and 1 will fail to initialize properly likely aborting your print. If you use Octoprint and stream gcode over the serial port instead of printing from virtual_sd, then remove M1 and M0 from Pausing commands in Settings > Serial Connection > Firmware & protocol will prevent the need to start print on the Palette 2 and unpausing in Octoprint for your print to begin. [palette2] serial: # The serial port to connect to the Palette 2. #baud: 115200 # The baud rate to use. The default is 115200. #feedrate_splice: 0.8 # The feedrate to use when splicing, default is 0.8 #feedrate_normal: 1.0 # The feedrate to use after splicing, default is 1.0 #auto_load_speed: 2 # Extrude feedrate when autoloading, default is 2 (mm/s) #auto_cancel_variation: 0.1 # Auto cancel print when ping variation is above this threshold","title":"[palette2]"},{"location":"Config_Reference.html#angle","text":"Magnetic hall angle sensor support for reading stepper motor angle shaft measurements using a1333, as5047d, mt6816, mt6826s, or tle5012b SPI chips. The measurements are available via the API Server and motion analysis tool . See the G-Code reference for available commands. [angle my_angle_sensor] sensor_type: # The type of the magnetic hall sensor chip. Available choices are # \"a1333\", \"as5047d\", \"mt6816\", \"mt6826s\", and \"tle5012b\". This parameter must be # specified. #sample_period: 0.000400 # The query period (in seconds) to use during measurements. The # default is 0.000400 (which is 2500 samples per second). #stepper: # The name of the stepper that the angle sensor is attached to (eg, # \"stepper_x\"). Setting this value enables an angle calibration # tool. To use this feature, the Python \"numpy\" package must be # installed. The default is to not enable angle calibration for the # angle sensor. cs_pin: # The SPI enable pin for the sensor. This parameter must be provided. #spi_speed: #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters.","title":"[angle]"},{"location":"Config_Reference.html#common-bus-parameters","text":"","title":"Common bus parameters"},{"location":"Config_Reference.html#common-spi-settings","text":"The following parameters are generally available for devices using an SPI bus. #spi_speed: # The SPI speed (in hz) to use when communicating with the device. # The default depends on the type of device. #spi_bus: # If the micro-controller supports multiple SPI busses then one may # specify the micro-controller bus name here. The default depends on # the type of micro-controller. #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # Specify the above parameters to use \"software based SPI\". This # mode does not require micro-controller hardware support (typically # any general purpose pins may be used). The default is to not use # \"software spi\".","title":"Common SPI settings"},{"location":"Config_Reference.html#common-i2c-settings","text":"The following parameters are generally available for devices using an I2C bus. Note that Klipper's current micro-controller support for I2C is generally not tolerant to line noise. Unexpected errors on the I2C wires may result in Klipper raising a run-time error. Klipper's support for error recovery varies between each micro-controller type. It is generally recommended to only use I2C devices that are on the same printed circuit board as the micro-controller. Most Klipper micro-controller implementations only support an i2c_speed of 100000 ( standard mode , 100kbit/s). The Klipper \"Linux\" micro-controller supports a 400000 speed ( fast mode , 400kbit/s), but it must be set in the operating system and the i2c_speed parameter is otherwise ignored. The Klipper \"RP2040\" micro-controller and ATmega AVR family and some STM32 (F0, G0, G4, L4, F7, H7) support a rate of 400000 via the i2c_speed parameter. All other Klipper micro-controllers use a 100000 rate and ignore the i2c_speed parameter. #i2c_address: # The i2c address of the device. This must specified as a decimal # number (not in hex). The default depends on the type of device. #i2c_mcu: # The name of the micro-controller that the chip is connected to. # The default is \"mcu\". #i2c_bus: # If the micro-controller supports multiple I2C busses then one may # specify the micro-controller bus name here. The default depends on # the type of micro-controller. #i2c_software_scl_pin: #i2c_software_sda_pin: # Specify these parameters to use micro-controller software based # I2C \"bit-banging\" support. The two parameters should the two pins # on the micro-controller to use for the scl and sda wires. The # default is to use hardware based I2C support as specified by the # i2c_bus parameter. #i2c_speed: # The I2C speed (in Hz) to use when communicating with the device. # The Klipper implementation on most micro-controllers is hard-coded # to 100000 and changing this value has no effect. The default is # 100000. Linux, RP2040 and ATmega support 400000.","title":"Common I2C settings"},{"location":"Config_checks.html","text":"Configuration checks \u00b6 This document provides a list of steps to help confirm the pin settings in the Klipper printer.cfg file. It is a good idea to run through these steps after following the steps in the installation document . During this guide, it may be necessary to make changes to the Klipper config file. Be sure to issue a RESTART command after every change to the config file to ensure that the change takes effect (type \"restart\" in the Octoprint terminal tab and then click \"Send\"). It's also a good idea to issue a STATUS command after every RESTART to verify that the config file is successfully loaded. Verify temperature \u00b6 Start by verifying that temperatures are being properly reported. Navigate to the temperature graph section in the user interface. Verify that the temperature of the nozzle and bed (if applicable) are present and not increasing. If it is increasing, remove power from the printer. If the temperatures are not accurate, review the \"sensor_type\" and \"sensor_pin\" settings for the nozzle and/or bed. Verify M112 \u00b6 Navigate to the command console and issue an M112 command in the terminal box. This command requests Klipper to go into a \"shutdown\" state. It will cause an error to show, which can be cleared with a FIRMWARE_RESTART command in the command console. Octoprint will also require a reconnect. Then navigate to the temperature graph section and verify that temperatures continue to update and the temperatures are not increasing. If temperatures are increasing, remove power from the printer. Verify heaters \u00b6 Navigate to the temperature graph section and type in 50 followed by enter in the extruder/tool temperature box. The extruder temperature in the graph should start to increase (within about 30 seconds or so). Then go to the extruder temperature drop-down box and select \"Off\". After several minutes the temperature should start to return to its initial room temperature value. If the temperature does not increase then verify the \"heater_pin\" setting in the config. If the printer has a heated bed then perform the above test again with the bed. Verify stepper motor enable pin \u00b6 Verify that all of the printer axes can manually move freely (the stepper motors are disabled). If not, issue an M84 command to disable the motors. If any of the axes still can not move freely, then verify the stepper \"enable_pin\" configuration for the given axis. On most commodity stepper motor drivers, the motor enable pin is \"active low\" and therefore the enable pin should have a \"!\" before the pin (for example, \"enable_pin: !PA1\"). Verify endstops \u00b6 Manually move all the printer axes so that none of them are in contact with an endstop. Send a QUERY_ENDSTOPS command via the command console. It should respond with the current state of all of the configured endstops and they should all report a state of \"open\". For each of the endstops, rerun the QUERY_ENDSTOPS command while manually triggering the endstop. The QUERY_ENDSTOPS command should report the endstop as \"TRIGGERED\". If the endstop appears inverted (it reports \"open\" when triggered and vice-versa) then add a \"!\" to the pin definition (for example, \"endstop_pin: ^!PA2\"), or remove the \"!\" if there is already one present. If the endstop does not change at all then it generally indicates that the endstop is connected to a different pin. However, it may also require a change to the pullup setting of the pin (the '^' at the start of the endstop_pin name - most printers will use a pullup resistor and the '^' should be present). Verify stepper motors \u00b6 Use the STEPPER_BUZZ command to verify the connectivity of each stepper motor. Start by manually positioning the given axis to a midway point and then run STEPPER_BUZZ STEPPER=stepper_x in the command console. The STEPPER_BUZZ command will cause the given stepper to move one millimeter in a positive direction and then it will return to its starting position. (If the endstop is defined at position_endstop=0 then at the start of each movement the stepper will move away from the endstop.) It will perform this oscillation ten times. If the stepper does not move at all, then verify the \"enable_pin\" and \"step_pin\" settings for the stepper. If the stepper motor moves but does not return to its original position then verify the \"dir_pin\" setting. If the stepper motor oscillates in an incorrect direction, then it generally indicates that the \"dir_pin\" for the axis needs to be inverted. This is done by adding a '!' to the \"dir_pin\" in the printer config file (or removing it if one is already there). If the motor moves significantly more or significantly less than one millimeter then verify the \"rotation_distance\" setting. Run the above test for each stepper motor defined in the config file. (Set the STEPPER parameter of the STEPPER_BUZZ command to the name of the config section that is to be tested.) If there is no filament in the extruder then one can use STEPPER_BUZZ to verify the extruder motor connectivity (use STEPPER=extruder). Otherwise, it's best to test the extruder motor separately (see the next section). After verifying all endstops and verifying all stepper motors the homing mechanism should be tested. Issue a G28 command to home all axes. Remove power from the printer if it does not home properly. Rerun the endstop and stepper motor verification steps if necessary. Verify extruder motor \u00b6 To test the extruder motor it will be necessary to heat the extruder to a printing temperature. Navigate to the temperature graph section and select a target temperature from the temperature drop-down box (or manually enter an appropriate temperature). Wait for the printer to reach the desired temperature. Then navigate to the command console and click the \"Extrude\" button. Verify that the extruder motor turns in the correct direction. If it does not, see the troubleshooting tips in the previous section to confirm the \"enable_pin\", \"step_pin\", and \"dir_pin\" settings for the extruder. Calibrate PID settings \u00b6 Klipper supports PID control for the extruder and bed heaters. In order to use this control mechanism, it is necessary to calibrate the PID settings on each printer (PID settings found in other firmwares or in the example configuration files often work poorly). To calibrate the extruder, navigate to the command console and run the PID_CALIBRATE command. For example: PID_CALIBRATE HEATER=extruder TARGET=170 At the completion of the tuning test run SAVE_CONFIG to update the printer.cfg file the new PID settings. If the printer has a heated bed and it supports being driven by PWM (Pulse Width Modulation) then it is recommended to use PID control for the bed. (When the bed heater is controlled using the PID algorithm it may turn on and off ten times a second, which may not be suitable for heaters using a mechanical switch.) A typical bed PID calibration command is: PID_CALIBRATE HEATER=heater_bed TARGET=60 Next steps \u00b6 This guide is intended to help with basic verification of pin settings in the Klipper configuration file. Be sure to read the bed leveling guide. Also see the Slicers document for information on configuring a slicer with Klipper. After one has verified that basic printing works, it is a good idea to consider calibrating pressure advance . It may be necessary to perform other types of detailed printer calibration - a number of guides are available online to help with this (for example, do a web search for \"3d printer calibration\"). As an example, if you experience the effect called ringing, you may try following resonance compensation tuning guide.","title":"Configuration checks"},{"location":"Config_checks.html#configuration-checks","text":"This document provides a list of steps to help confirm the pin settings in the Klipper printer.cfg file. It is a good idea to run through these steps after following the steps in the installation document . During this guide, it may be necessary to make changes to the Klipper config file. Be sure to issue a RESTART command after every change to the config file to ensure that the change takes effect (type \"restart\" in the Octoprint terminal tab and then click \"Send\"). It's also a good idea to issue a STATUS command after every RESTART to verify that the config file is successfully loaded.","title":"Configuration checks"},{"location":"Config_checks.html#verify-temperature","text":"Start by verifying that temperatures are being properly reported. Navigate to the temperature graph section in the user interface. Verify that the temperature of the nozzle and bed (if applicable) are present and not increasing. If it is increasing, remove power from the printer. If the temperatures are not accurate, review the \"sensor_type\" and \"sensor_pin\" settings for the nozzle and/or bed.","title":"Verify temperature"},{"location":"Config_checks.html#verify-m112","text":"Navigate to the command console and issue an M112 command in the terminal box. This command requests Klipper to go into a \"shutdown\" state. It will cause an error to show, which can be cleared with a FIRMWARE_RESTART command in the command console. Octoprint will also require a reconnect. Then navigate to the temperature graph section and verify that temperatures continue to update and the temperatures are not increasing. If temperatures are increasing, remove power from the printer.","title":"Verify M112"},{"location":"Config_checks.html#verify-heaters","text":"Navigate to the temperature graph section and type in 50 followed by enter in the extruder/tool temperature box. The extruder temperature in the graph should start to increase (within about 30 seconds or so). Then go to the extruder temperature drop-down box and select \"Off\". After several minutes the temperature should start to return to its initial room temperature value. If the temperature does not increase then verify the \"heater_pin\" setting in the config. If the printer has a heated bed then perform the above test again with the bed.","title":"Verify heaters"},{"location":"Config_checks.html#verify-stepper-motor-enable-pin","text":"Verify that all of the printer axes can manually move freely (the stepper motors are disabled). If not, issue an M84 command to disable the motors. If any of the axes still can not move freely, then verify the stepper \"enable_pin\" configuration for the given axis. On most commodity stepper motor drivers, the motor enable pin is \"active low\" and therefore the enable pin should have a \"!\" before the pin (for example, \"enable_pin: !PA1\").","title":"Verify stepper motor enable pin"},{"location":"Config_checks.html#verify-endstops","text":"Manually move all the printer axes so that none of them are in contact with an endstop. Send a QUERY_ENDSTOPS command via the command console. It should respond with the current state of all of the configured endstops and they should all report a state of \"open\". For each of the endstops, rerun the QUERY_ENDSTOPS command while manually triggering the endstop. The QUERY_ENDSTOPS command should report the endstop as \"TRIGGERED\". If the endstop appears inverted (it reports \"open\" when triggered and vice-versa) then add a \"!\" to the pin definition (for example, \"endstop_pin: ^!PA2\"), or remove the \"!\" if there is already one present. If the endstop does not change at all then it generally indicates that the endstop is connected to a different pin. However, it may also require a change to the pullup setting of the pin (the '^' at the start of the endstop_pin name - most printers will use a pullup resistor and the '^' should be present).","title":"Verify endstops"},{"location":"Config_checks.html#verify-stepper-motors","text":"Use the STEPPER_BUZZ command to verify the connectivity of each stepper motor. Start by manually positioning the given axis to a midway point and then run STEPPER_BUZZ STEPPER=stepper_x in the command console. The STEPPER_BUZZ command will cause the given stepper to move one millimeter in a positive direction and then it will return to its starting position. (If the endstop is defined at position_endstop=0 then at the start of each movement the stepper will move away from the endstop.) It will perform this oscillation ten times. If the stepper does not move at all, then verify the \"enable_pin\" and \"step_pin\" settings for the stepper. If the stepper motor moves but does not return to its original position then verify the \"dir_pin\" setting. If the stepper motor oscillates in an incorrect direction, then it generally indicates that the \"dir_pin\" for the axis needs to be inverted. This is done by adding a '!' to the \"dir_pin\" in the printer config file (or removing it if one is already there). If the motor moves significantly more or significantly less than one millimeter then verify the \"rotation_distance\" setting. Run the above test for each stepper motor defined in the config file. (Set the STEPPER parameter of the STEPPER_BUZZ command to the name of the config section that is to be tested.) If there is no filament in the extruder then one can use STEPPER_BUZZ to verify the extruder motor connectivity (use STEPPER=extruder). Otherwise, it's best to test the extruder motor separately (see the next section). After verifying all endstops and verifying all stepper motors the homing mechanism should be tested. Issue a G28 command to home all axes. Remove power from the printer if it does not home properly. Rerun the endstop and stepper motor verification steps if necessary.","title":"Verify stepper motors"},{"location":"Config_checks.html#verify-extruder-motor","text":"To test the extruder motor it will be necessary to heat the extruder to a printing temperature. Navigate to the temperature graph section and select a target temperature from the temperature drop-down box (or manually enter an appropriate temperature). Wait for the printer to reach the desired temperature. Then navigate to the command console and click the \"Extrude\" button. Verify that the extruder motor turns in the correct direction. If it does not, see the troubleshooting tips in the previous section to confirm the \"enable_pin\", \"step_pin\", and \"dir_pin\" settings for the extruder.","title":"Verify extruder motor"},{"location":"Config_checks.html#calibrate-pid-settings","text":"Klipper supports PID control for the extruder and bed heaters. In order to use this control mechanism, it is necessary to calibrate the PID settings on each printer (PID settings found in other firmwares or in the example configuration files often work poorly). To calibrate the extruder, navigate to the command console and run the PID_CALIBRATE command. For example: PID_CALIBRATE HEATER=extruder TARGET=170 At the completion of the tuning test run SAVE_CONFIG to update the printer.cfg file the new PID settings. If the printer has a heated bed and it supports being driven by PWM (Pulse Width Modulation) then it is recommended to use PID control for the bed. (When the bed heater is controlled using the PID algorithm it may turn on and off ten times a second, which may not be suitable for heaters using a mechanical switch.) A typical bed PID calibration command is: PID_CALIBRATE HEATER=heater_bed TARGET=60","title":"Calibrate PID settings"},{"location":"Config_checks.html#next-steps","text":"This guide is intended to help with basic verification of pin settings in the Klipper configuration file. Be sure to read the bed leveling guide. Also see the Slicers document for information on configuring a slicer with Klipper. After one has verified that basic printing works, it is a good idea to consider calibrating pressure advance . It may be necessary to perform other types of detailed printer calibration - a number of guides are available online to help with this (for example, do a web search for \"3d printer calibration\"). As an example, if you experience the effect called ringing, you may try following resonance compensation tuning guide.","title":"Next steps"},{"location":"Contact.html","text":"Contact \u00b6 This document provides contact information for Klipper. Discourse Forum \u00b6 There is a Klipper Community Discourse server for \"forum\" style discussions on Klipper. Note that Discourse is not Discord. Discord Chat \u00b6 There is a Discord server dedicated to Klipper at: https://discord.klipper3d.org . Note that Discord is not Discourse. This server is run by a community of Klipper enthusiasts dedicated to discussions on Klipper. It allows users to chat with other users in real-time. I have a question about Klipper \u00b6 Many questions we receive are already answered in the Klipper documentation . Please be sure to to read the documentation and follow the directions provided there. It is also possible to search for similar questions in the Klipper Discourse Forum . If you are interested in sharing your knowledge and experience with other Klipper users then you can join the Klipper Discourse Forum or Klipper Discord Chat . Both are communities where Klipper users can discuss Klipper with other users. If you have a general question or are experiencing general printing problems, then also consider a general 3d-printing forum or a forum dedicated to the printer hardware. I have a feature request \u00b6 All new features require someone interested and able to implement that feature. If you are interested in helping to implement or test a new feature, you can search for ongoing developments in the Klipper Discourse Forum . There is also Klipper Discord Chat for discussions between collaborators. Help! It doesn't work! \u00b6 If you are experiencing problems we recommend you carefully read the Klipper documentation and double check that all steps were followed. If you are experiencing a printing problem, then we recommend carefully inspecting the printer hardware (all joints, wires, screws, etc.) and verify nothing is abnormal. We find most printing problems are not related to the Klipper software. If you do find a problem with the printer hardware then consider searching general 3d-printing forums or forums dedicated to the printer hardware. It is also possible to search for similar issues in the Klipper Discourse Forum . If you are interested in sharing your knowledge and experience with other Klipper users then you can join the Klipper Discourse Forum or Klipper Discord Chat . Both are communities where Klipper users can discuss Klipper with other users. I found a bug in the Klipper software \u00b6 Klipper is an open-source project and we appreciate when collaborators diagnose errors in the software. Problems should be reported in the Klipper Discourse Forum . There is important information that will be needed in order to fix a bug. Please follow these steps: Make sure you are running unmodified code from https://github.com/Klipper3d/klipper . If the code has been modified or is obtained from another source, then you should reproduce the problem on the unmodified code from https://github.com/Klipper3d/klipper prior to reporting. If possible, run an M112 command immediately after the undesirable event occurs. This causes Klipper to go into a \"shutdown state\" and it will cause additional debugging information to be written to the log file. Obtain the Klipper log file from the event. The log file has been engineered to answer common questions the Klipper developers have about the software and its environment (software version, hardware type, configuration, event timing, and hundreds of other questions). Dedicated Klipper web interfaces have the ability to directly obtain the Klipper log file. It's the easiest way to obtain the log when using one of these interfaces. Otherwise, an \"scp\" or \"sftp\" utility is needed to copy the log file to your desktop computer. The \"scp\" utility comes standard with Linux and MacOS desktops. There are freely available scp utilities for other desktops (eg, WinSCP). The log file may be located in the ~/printer_data/logs/klippy.log file (if using a graphical scp utility, look for the \"printer_data\" folder, then the \"logs\" folder under that, then the klippy.log file). The log file may alternatively be located in the /tmp/klippy.log file (if using a graphical scp utility that can not directly copy /tmp/klippy.log then repeatedly click on .. or \"parent folder\" until reaching the root directory, click on the tmp folder, and then select the klippy.log file). Copy the log file to your desktop so that it can be attached to an issue report. Do not modify the log file in any way; do not provide a snippet of the log. Only the full unmodified log file provides the necessary information. It is a good idea to compress the log file with zip or gzip. Open a new topic on the Klipper Discourse Forum and provide a clear description of the problem. Other Klipper contributors will need to understand what steps were taken, what the desired outcome was, and what outcome actually occurred. The compressed Klipper log file should be attached to that topic. I am making changes that I'd like to include in Klipper \u00b6 Klipper is open-source software and we appreciate new contributions. See the CONTRIBUTING document for information. There are several documents for developers . If you have questions on the code then you can also ask in the Klipper Discourse Forum or on the Klipper Discord Chat . Professional Services \u00b6 Custom software development, software support, and solutions: https://ko-fi.com/koconnor","title":"Contact"},{"location":"Contact.html#contact","text":"This document provides contact information for Klipper.","title":"Contact"},{"location":"Contact.html#discourse-forum","text":"There is a Klipper Community Discourse server for \"forum\" style discussions on Klipper. Note that Discourse is not Discord.","title":"Discourse Forum"},{"location":"Contact.html#discord-chat","text":"There is a Discord server dedicated to Klipper at: https://discord.klipper3d.org . Note that Discord is not Discourse. This server is run by a community of Klipper enthusiasts dedicated to discussions on Klipper. It allows users to chat with other users in real-time.","title":"Discord Chat"},{"location":"Contact.html#i-have-a-question-about-klipper","text":"Many questions we receive are already answered in the Klipper documentation . Please be sure to to read the documentation and follow the directions provided there. It is also possible to search for similar questions in the Klipper Discourse Forum . If you are interested in sharing your knowledge and experience with other Klipper users then you can join the Klipper Discourse Forum or Klipper Discord Chat . Both are communities where Klipper users can discuss Klipper with other users. If you have a general question or are experiencing general printing problems, then also consider a general 3d-printing forum or a forum dedicated to the printer hardware.","title":"I have a question about Klipper"},{"location":"Contact.html#i-have-a-feature-request","text":"All new features require someone interested and able to implement that feature. If you are interested in helping to implement or test a new feature, you can search for ongoing developments in the Klipper Discourse Forum . There is also Klipper Discord Chat for discussions between collaborators.","title":"I have a feature request"},{"location":"Contact.html#help-it-doesnt-work","text":"If you are experiencing problems we recommend you carefully read the Klipper documentation and double check that all steps were followed. If you are experiencing a printing problem, then we recommend carefully inspecting the printer hardware (all joints, wires, screws, etc.) and verify nothing is abnormal. We find most printing problems are not related to the Klipper software. If you do find a problem with the printer hardware then consider searching general 3d-printing forums or forums dedicated to the printer hardware. It is also possible to search for similar issues in the Klipper Discourse Forum . If you are interested in sharing your knowledge and experience with other Klipper users then you can join the Klipper Discourse Forum or Klipper Discord Chat . Both are communities where Klipper users can discuss Klipper with other users.","title":"Help! It doesn't work!"},{"location":"Contact.html#i-found-a-bug-in-the-klipper-software","text":"Klipper is an open-source project and we appreciate when collaborators diagnose errors in the software. Problems should be reported in the Klipper Discourse Forum . There is important information that will be needed in order to fix a bug. Please follow these steps: Make sure you are running unmodified code from https://github.com/Klipper3d/klipper . If the code has been modified or is obtained from another source, then you should reproduce the problem on the unmodified code from https://github.com/Klipper3d/klipper prior to reporting. If possible, run an M112 command immediately after the undesirable event occurs. This causes Klipper to go into a \"shutdown state\" and it will cause additional debugging information to be written to the log file. Obtain the Klipper log file from the event. The log file has been engineered to answer common questions the Klipper developers have about the software and its environment (software version, hardware type, configuration, event timing, and hundreds of other questions). Dedicated Klipper web interfaces have the ability to directly obtain the Klipper log file. It's the easiest way to obtain the log when using one of these interfaces. Otherwise, an \"scp\" or \"sftp\" utility is needed to copy the log file to your desktop computer. The \"scp\" utility comes standard with Linux and MacOS desktops. There are freely available scp utilities for other desktops (eg, WinSCP). The log file may be located in the ~/printer_data/logs/klippy.log file (if using a graphical scp utility, look for the \"printer_data\" folder, then the \"logs\" folder under that, then the klippy.log file). The log file may alternatively be located in the /tmp/klippy.log file (if using a graphical scp utility that can not directly copy /tmp/klippy.log then repeatedly click on .. or \"parent folder\" until reaching the root directory, click on the tmp folder, and then select the klippy.log file). Copy the log file to your desktop so that it can be attached to an issue report. Do not modify the log file in any way; do not provide a snippet of the log. Only the full unmodified log file provides the necessary information. It is a good idea to compress the log file with zip or gzip. Open a new topic on the Klipper Discourse Forum and provide a clear description of the problem. Other Klipper contributors will need to understand what steps were taken, what the desired outcome was, and what outcome actually occurred. The compressed Klipper log file should be attached to that topic.","title":"I found a bug in the Klipper software"},{"location":"Contact.html#i-am-making-changes-that-id-like-to-include-in-klipper","text":"Klipper is open-source software and we appreciate new contributions. See the CONTRIBUTING document for information. There are several documents for developers . If you have questions on the code then you can also ask in the Klipper Discourse Forum or on the Klipper Discord Chat .","title":"I am making changes that I'd like to include in Klipper"},{"location":"Contact.html#professional-services","text":"Custom software development, software support, and solutions: https://ko-fi.com/koconnor","title":"Professional Services"},{"location":"Debugging.html","text":"Debugging \u00b6 This document describes some of the Klipper debugging tools. Running the regression tests \u00b6 The main Klipper GitHub repository uses \"github actions\" to run a series of regression tests. It can be useful to run some of these tests locally. The source code \"whitespace check\" can be run with: ./scripts/check_whitespace.sh The Klippy regression test suite requires \"data dictionaries\" from many platforms. The easiest way to obtain them is to download them from github . Once the data dictionaries are downloaded, use the following to run the regression suite: tar xfz klipper-dict-20??????.tar.gz ~/klippy-env/bin/python ~/klipper/scripts/test_klippy.py -d dict/ ~/klipper/test/klippy/*.test Manually sending commands to the micro-controller \u00b6 Normally, the host klippy.py process would be used to translate gcode commands to Klipper micro-controller commands. However, it's also possible to manually send these MCU commands (functions marked with the DECL_COMMAND() macro in the Klipper source code). To do so, run: ~/klippy-env/bin/python ./klippy/console.py /tmp/pseudoserial See the \"HELP\" command within the tool for more information on its functionality. Some command-line options are available. For more information run: ~/klippy-env/bin/python ./klippy/console.py --help Translating gcode files to micro-controller commands \u00b6 The Klippy host code can run in a batch mode to produce the low-level micro-controller commands associated with a gcode file. Inspecting these low-level commands is useful when trying to understand the actions of the low-level hardware. It can also be useful to compare the difference in micro-controller commands after a code change. To run Klippy in this batch mode, there is a one time step necessary to generate the micro-controller \"data dictionary\". This is done by compiling the micro-controller code to obtain the out/klipper.dict file: make menuconfig make Once the above is done it is possible to run Klipper in batch mode (see installation for the steps necessary to build the python virtual environment and a printer.cfg file): ~/klippy-env/bin/python ./klippy/klippy.py ~/printer.cfg -i test.gcode -o test.serial -v -d out/klipper.dict The above will produce a file test.serial with the binary serial output. This output can be translated to readable text with: ~/klippy-env/bin/python ./klippy/parsedump.py out/klipper.dict test.serial > test.txt The resulting file test.txt contains a human readable list of micro-controller commands. The batch mode disables certain response / request commands in order to function. As a result, there will be some differences between actual commands and the above output. The generated data is useful for testing and inspection; it is not useful for sending to a real micro-controller. Motion analysis and data logging \u00b6 Klipper supports logging its internal motion history, which can be later analyzed. To use this feature, Klipper must be started with the API Server enabled. Data logging is enabled with the data_logger.py tool. For example: ~/klipper/scripts/motan/data_logger.py /tmp/klippy_uds mylog This command will connect to the Klipper API Server, subscribe to status and motion information, and log the results. Two files are generated - a compressed data file and an index file (eg, mylog.json.gz and mylog.index.gz ). After starting the logging, it is possible to complete prints and other actions - the logging will continue in the background. When done logging, hit ctrl-c to exit from the data_logger.py tool. The resulting files can be read and graphed using the motan_graph.py tool. To generate graphs on a Raspberry Pi, a one time step is necessary to install the \"matplotlib\" package: sudo apt-get update sudo apt-get install python-matplotlib However, it may be more convenient to copy the data files to a desktop class machine along with the Python code in the scripts/motan/ directory. The motion analysis scripts should run on any machine with a recent version of Python and Matplotlib installed. Graphs can be generated with a command like the following: ~/klipper/scripts/motan/motan_graph.py mylog -o mygraph.png One can use the -g option to specify the datasets to graph (it takes a Python literal containing a list of lists). For example: ~/klipper/scripts/motan/motan_graph.py mylog -g '[[\"trapq(toolhead,velocity)\"], [\"trapq(toolhead,accel)\"]]' The list of available datasets can be found using the -l option - for example: ~/klipper/scripts/motan/motan_graph.py -l It is also possible to specify matplotlib plot options for each dataset: ~/klipper/scripts/motan/motan_graph.py mylog -g '[[\"trapq(toolhead,velocity)?color=red&alpha=0.4\"]]' Many matplotlib options are available; some examples are \"color\", \"label\", \"alpha\", and \"linestyle\". The motan_graph.py tool supports several other command-line options - use the --help option to see a list. It may also be convenient to view/modify the motan_graph.py script itself. The raw data logs produced by the data_logger.py tool follow the format described in the API Server . It may be useful to inspect the data with a Unix command like the following: gunzip < mylog.json.gz | tr '\\03' '\\n' | less Generating load graphs \u00b6 The Klippy log file (/tmp/klippy.log) stores statistics on bandwidth, micro-controller load, and host buffer load. It can be useful to graph these statistics after a print. To generate a graph, a one time step is necessary to install the \"matplotlib\" package: sudo apt-get update sudo apt-get install python-matplotlib Then graphs can be produced with: ~/klipper/scripts/graphstats.py /tmp/klippy.log -o loadgraph.png One can then view the resulting loadgraph.png file. Different graphs can be produced. For more information run: ~/klipper/scripts/graphstats.py --help Extracting information from the klippy.log file \u00b6 The Klippy log file (/tmp/klippy.log) also contains debugging information. There is a logextract.py script that may be useful when analyzing a micro-controller shutdown or similar problem. It is typically run with something like: mkdir work_directory cd work_directory cp /tmp/klippy.log . ~/klipper/scripts/logextract.py ./klippy.log The script will extract the printer config file and will extract MCU shutdown information. The information dumps from an MCU shutdown (if present) will be reordered by timestamp to assist in diagnosing cause and effect scenarios. Testing with simulavr \u00b6 The simulavr tool enables one to simulate an Atmel ATmega micro-controller. This section describes how one can run test gcode files through simulavr. It is recommended to run this on a desktop class machine (not a Raspberry Pi) as it does require significant cpu to run efficiently. To use simulavr, download the simulavr package and compile with python support. Note that the build system may need to have some packages (such as swig) installed in order to build the python module. git clone git://git.savannah.nongnu.org/simulavr.git cd simulavr make python make build Make sure a file like ./build/pysimulavr/_pysimulavr.*.so is present after the above compilation: ls ./build/pysimulavr/_pysimulavr.*.so This command should report a specific file (e.g. ./build/pysimulavr/_pysimulavr.cpython-39-x86_64-linux-gnu.so ) and not an error. If you are on a Debian-based system (Debian, Ubuntu, etc.) you can install the following packages and generate *.deb files for system-wide installation of simulavr: sudo apt update sudo apt install g++ make cmake swig rst2pdf help2man texinfo make cfgclean python debian sudo dpkg -i build/debian/python3-simulavr*.deb To compile Klipper for use in simulavr, run: cd /path/to/klipper make menuconfig and compile the micro-controller software for an AVR atmega644p and select SIMULAVR software emulation support. Then one can compile Klipper (run make ) and then start the simulation with: PYTHONPATH=/path/to/simulavr/build/pysimulavr/ ./scripts/avrsim.py out/klipper.elf Note that if you have installed python3-simulavr system-wide, you do not need to set PYTHONPATH , and can simply run the simulator as ./scripts/avrsim.py out/klipper.elf Then, with simulavr running in another window, one can run the following to read gcode from a file (eg, \"test.gcode\"), process it with Klippy, and send it to Klipper running in simulavr (see installation for the steps necessary to build the python virtual environment): ~/klippy-env/bin/python ./klippy/klippy.py config/generic-simulavr.cfg -i test.gcode -v Using simulavr with gtkwave \u00b6 One useful feature of simulavr is its ability to create signal wave generation files with the exact timing of events. To do this, follow the directions above, but run avrsim.py with a command-line like the following: PYTHONPATH=/path/to/simulavr/src/python/ ./scripts/avrsim.py out/klipper.elf -t PORTA.PORT,PORTC.PORT The above would create a file avrsim.vcd with information on each change to the GPIOs on PORTA and PORTB. This could then be viewed using gtkwave with: gtkwave avrsim.vcd","title":"Debugging"},{"location":"Debugging.html#debugging","text":"This document describes some of the Klipper debugging tools.","title":"Debugging"},{"location":"Debugging.html#running-the-regression-tests","text":"The main Klipper GitHub repository uses \"github actions\" to run a series of regression tests. It can be useful to run some of these tests locally. The source code \"whitespace check\" can be run with: ./scripts/check_whitespace.sh The Klippy regression test suite requires \"data dictionaries\" from many platforms. The easiest way to obtain them is to download them from github . Once the data dictionaries are downloaded, use the following to run the regression suite: tar xfz klipper-dict-20??????.tar.gz ~/klippy-env/bin/python ~/klipper/scripts/test_klippy.py -d dict/ ~/klipper/test/klippy/*.test","title":"Running the regression tests"},{"location":"Debugging.html#manually-sending-commands-to-the-micro-controller","text":"Normally, the host klippy.py process would be used to translate gcode commands to Klipper micro-controller commands. However, it's also possible to manually send these MCU commands (functions marked with the DECL_COMMAND() macro in the Klipper source code). To do so, run: ~/klippy-env/bin/python ./klippy/console.py /tmp/pseudoserial See the \"HELP\" command within the tool for more information on its functionality. Some command-line options are available. For more information run: ~/klippy-env/bin/python ./klippy/console.py --help","title":"Manually sending commands to the micro-controller"},{"location":"Debugging.html#translating-gcode-files-to-micro-controller-commands","text":"The Klippy host code can run in a batch mode to produce the low-level micro-controller commands associated with a gcode file. Inspecting these low-level commands is useful when trying to understand the actions of the low-level hardware. It can also be useful to compare the difference in micro-controller commands after a code change. To run Klippy in this batch mode, there is a one time step necessary to generate the micro-controller \"data dictionary\". This is done by compiling the micro-controller code to obtain the out/klipper.dict file: make menuconfig make Once the above is done it is possible to run Klipper in batch mode (see installation for the steps necessary to build the python virtual environment and a printer.cfg file): ~/klippy-env/bin/python ./klippy/klippy.py ~/printer.cfg -i test.gcode -o test.serial -v -d out/klipper.dict The above will produce a file test.serial with the binary serial output. This output can be translated to readable text with: ~/klippy-env/bin/python ./klippy/parsedump.py out/klipper.dict test.serial > test.txt The resulting file test.txt contains a human readable list of micro-controller commands. The batch mode disables certain response / request commands in order to function. As a result, there will be some differences between actual commands and the above output. The generated data is useful for testing and inspection; it is not useful for sending to a real micro-controller.","title":"Translating gcode files to micro-controller commands"},{"location":"Debugging.html#motion-analysis-and-data-logging","text":"Klipper supports logging its internal motion history, which can be later analyzed. To use this feature, Klipper must be started with the API Server enabled. Data logging is enabled with the data_logger.py tool. For example: ~/klipper/scripts/motan/data_logger.py /tmp/klippy_uds mylog This command will connect to the Klipper API Server, subscribe to status and motion information, and log the results. Two files are generated - a compressed data file and an index file (eg, mylog.json.gz and mylog.index.gz ). After starting the logging, it is possible to complete prints and other actions - the logging will continue in the background. When done logging, hit ctrl-c to exit from the data_logger.py tool. The resulting files can be read and graphed using the motan_graph.py tool. To generate graphs on a Raspberry Pi, a one time step is necessary to install the \"matplotlib\" package: sudo apt-get update sudo apt-get install python-matplotlib However, it may be more convenient to copy the data files to a desktop class machine along with the Python code in the scripts/motan/ directory. The motion analysis scripts should run on any machine with a recent version of Python and Matplotlib installed. Graphs can be generated with a command like the following: ~/klipper/scripts/motan/motan_graph.py mylog -o mygraph.png One can use the -g option to specify the datasets to graph (it takes a Python literal containing a list of lists). For example: ~/klipper/scripts/motan/motan_graph.py mylog -g '[[\"trapq(toolhead,velocity)\"], [\"trapq(toolhead,accel)\"]]' The list of available datasets can be found using the -l option - for example: ~/klipper/scripts/motan/motan_graph.py -l It is also possible to specify matplotlib plot options for each dataset: ~/klipper/scripts/motan/motan_graph.py mylog -g '[[\"trapq(toolhead,velocity)?color=red&alpha=0.4\"]]' Many matplotlib options are available; some examples are \"color\", \"label\", \"alpha\", and \"linestyle\". The motan_graph.py tool supports several other command-line options - use the --help option to see a list. It may also be convenient to view/modify the motan_graph.py script itself. The raw data logs produced by the data_logger.py tool follow the format described in the API Server . It may be useful to inspect the data with a Unix command like the following: gunzip < mylog.json.gz | tr '\\03' '\\n' | less","title":"Motion analysis and data logging"},{"location":"Debugging.html#generating-load-graphs","text":"The Klippy log file (/tmp/klippy.log) stores statistics on bandwidth, micro-controller load, and host buffer load. It can be useful to graph these statistics after a print. To generate a graph, a one time step is necessary to install the \"matplotlib\" package: sudo apt-get update sudo apt-get install python-matplotlib Then graphs can be produced with: ~/klipper/scripts/graphstats.py /tmp/klippy.log -o loadgraph.png One can then view the resulting loadgraph.png file. Different graphs can be produced. For more information run: ~/klipper/scripts/graphstats.py --help","title":"Generating load graphs"},{"location":"Debugging.html#extracting-information-from-the-klippylog-file","text":"The Klippy log file (/tmp/klippy.log) also contains debugging information. There is a logextract.py script that may be useful when analyzing a micro-controller shutdown or similar problem. It is typically run with something like: mkdir work_directory cd work_directory cp /tmp/klippy.log . ~/klipper/scripts/logextract.py ./klippy.log The script will extract the printer config file and will extract MCU shutdown information. The information dumps from an MCU shutdown (if present) will be reordered by timestamp to assist in diagnosing cause and effect scenarios.","title":"Extracting information from the klippy.log file"},{"location":"Debugging.html#testing-with-simulavr","text":"The simulavr tool enables one to simulate an Atmel ATmega micro-controller. This section describes how one can run test gcode files through simulavr. It is recommended to run this on a desktop class machine (not a Raspberry Pi) as it does require significant cpu to run efficiently. To use simulavr, download the simulavr package and compile with python support. Note that the build system may need to have some packages (such as swig) installed in order to build the python module. git clone git://git.savannah.nongnu.org/simulavr.git cd simulavr make python make build Make sure a file like ./build/pysimulavr/_pysimulavr.*.so is present after the above compilation: ls ./build/pysimulavr/_pysimulavr.*.so This command should report a specific file (e.g. ./build/pysimulavr/_pysimulavr.cpython-39-x86_64-linux-gnu.so ) and not an error. If you are on a Debian-based system (Debian, Ubuntu, etc.) you can install the following packages and generate *.deb files for system-wide installation of simulavr: sudo apt update sudo apt install g++ make cmake swig rst2pdf help2man texinfo make cfgclean python debian sudo dpkg -i build/debian/python3-simulavr*.deb To compile Klipper for use in simulavr, run: cd /path/to/klipper make menuconfig and compile the micro-controller software for an AVR atmega644p and select SIMULAVR software emulation support. Then one can compile Klipper (run make ) and then start the simulation with: PYTHONPATH=/path/to/simulavr/build/pysimulavr/ ./scripts/avrsim.py out/klipper.elf Note that if you have installed python3-simulavr system-wide, you do not need to set PYTHONPATH , and can simply run the simulator as ./scripts/avrsim.py out/klipper.elf Then, with simulavr running in another window, one can run the following to read gcode from a file (eg, \"test.gcode\"), process it with Klippy, and send it to Klipper running in simulavr (see installation for the steps necessary to build the python virtual environment): ~/klippy-env/bin/python ./klippy/klippy.py config/generic-simulavr.cfg -i test.gcode -v","title":"Testing with simulavr"},{"location":"Debugging.html#using-simulavr-with-gtkwave","text":"One useful feature of simulavr is its ability to create signal wave generation files with the exact timing of events. To do this, follow the directions above, but run avrsim.py with a command-line like the following: PYTHONPATH=/path/to/simulavr/src/python/ ./scripts/avrsim.py out/klipper.elf -t PORTA.PORT,PORTC.PORT The above would create a file avrsim.vcd with information on each change to the GPIOs on PORTA and PORTB. This could then be viewed using gtkwave with: gtkwave avrsim.vcd","title":"Using simulavr with gtkwave"},{"location":"Delta_Calibrate.html","text":"Delta calibration \u00b6 This document describes Klipper's automatic calibration system for \"delta\" style printers. Delta calibration involves finding the tower endstop positions, tower angles, delta radius, and delta arm lengths. These settings control printer motion on a delta printer. Each one of these parameters has a non-obvious and non-linear impact and it is difficult to calibrate them manually. In contrast, the software calibration code can provide excellent results with just a few minutes of time. No special probing hardware is necessary. Ultimately, the delta calibration is dependent on the precision of the tower endstop switches. If one is using Trinamic stepper motor drivers then consider enabling endstop phase detection to improve the accuracy of those switches. Automatic vs manual probing \u00b6 Klipper supports calibrating the delta parameters via a manual probing method or via an automatic Z probe. A number of delta printer kits come with automatic Z probes that are not sufficiently accurate (specifically, small differences in arm length can cause effector tilt which can skew an automatic probe). If using an automatic probe then first calibrate the probe and then check for a probe location bias . If the automatic probe has a bias of more than 25 microns (.025mm) then use manual probing instead. Manual probing only takes a few minutes and it eliminates error introduced by the probe. If using a probe that is mounted on the side of the hotend (that is, it has an X or Y offset) then note that performing delta calibration will invalidate the results of probe calibration. These types of probes are rarely suitable for use on a delta (because minor effector tilt will result in a probe location bias). If using the probe anyway, then be sure to rerun probe calibration after any delta calibration. Basic delta calibration \u00b6 Klipper has a DELTA_CALIBRATE command that can perform basic delta calibration. This command probes seven different points on the bed and calculates new values for the tower angles, tower endstops, and delta radius. In order to perform this calibration the initial delta parameters (arm lengths, radius, and endstop positions) must be provided and they should have an accuracy to within a few millimeters. Most delta printer kits will provide these parameters - configure the printer with these initial defaults and then go on to run the DELTA_CALIBRATE command as described below. If no defaults are available then search online for a delta calibration guide that can provide a basic starting point. During the delta calibration process it may be necessary for the printer to probe below what would otherwise be considered the plane of the bed. It is typical to permit this during calibration by updating the config so that the printer's minimum_z_position=-5 . (Once calibration completes, one can remove this setting from the config.) There are two ways to perform the probing - manual probing ( DELTA_CALIBRATE METHOD=manual ) and automatic probing ( DELTA_CALIBRATE ). The manual probing method will move the head near the bed and then wait for the user to follow the steps described at \"the paper test\" to determine the actual distance between the nozzle and bed at the given location. To perform the basic probe, make sure the config has a [delta_calibrate] section defined and then run the tool: G28 DELTA_CALIBRATE METHOD=manual After probing the seven points new delta parameters will be calculated. Save and apply these parameters by running: SAVE_CONFIG The basic calibration should provide delta parameters that are accurate enough for basic printing. If this is a new printer, this is a good time to print some basic objects and verify general functionality. Enhanced delta calibration \u00b6 The basic delta calibration generally does a good job of calculating delta parameters such that the nozzle is the correct distance from the bed. However, it does not attempt to calibrate X and Y dimensional accuracy. It's a good idea to perform an enhanced delta calibration to verify dimensional accuracy. This calibration procedure requires printing a test object and measuring parts of that test object with digital calipers. Prior to running an enhanced delta calibration one must run the basic delta calibration (via the DELTA_CALIBRATE command) and save the results (via the SAVE_CONFIG command). Make sure there hasn't been any notable change to the printer configuration nor hardware since last performing a basic delta calibration (if unsure, rerun the basic delta calibration , including SAVE_CONFIG, just prior to printing the test object described below.) Use a slicer to generate G-Code from the docs/prints/calibrate_size.stl file. Slice the object using a slow speed (eg, 40mm/s). If possible, use a stiff plastic (such as PLA) for the object. The object has a diameter of 140mm. If this is too large for the printer then one can scale it down (but be sure to uniformly scale both the X and Y axes). If the printer supports significantly larger prints then this object can also be increased in size. A larger size can improve the measurement accuracy, but good print adhesion is more important than a larger print size. Print the test object and wait for it to fully cool. The commands described below must be run with the same printer settings used to print the calibration object (don't run DELTA_CALIBRATE between printing and measuring, or do something that would otherwise change the printer configuration). If possible, perform the measurements described below while the object is still attached to the print bed, but don't worry if the part detaches from the bed - just try to avoid bending the object when performing the measurements. Start by measuring the distance between the center pillar and the pillar next to the \"A\" label (which should also be pointing towards the \"A\" tower). Then go counterclockwise and measure the distances between the center pillar and the other pillars (distance from center to pillar across from C label, distance from center to pillar with B label, etc.). Enter these parameters into Klipper with a comma separated list of floating point numbers: DELTA_ANALYZE CENTER_DISTS=<a_dist>,<far_c_dist>,<b_dist>,<far_a_dist>,<c_dist>,<far_b_dist> Provide the values without spaces between them. Then measure the distance between the A pillar and the pillar across from the C label. Then go counterclockwise and measure the distance between the pillar across from C to the B pillar, the distance between the B pillar and the pillar across from A, and so on. Enter these parameters into Klipper: DELTA_ANALYZE OUTER_DISTS=<a_to_far_c>,<far_c_to_b>,<b_to_far_a>,<far_a_to_c>,<c_to_far_b>,<far_b_to_a> At this point it is okay to remove the object from the bed. The final measurements are of the pillars themselves. Measure the size of the center pillar along the A spoke, then the B spoke, and then the C spoke. Enter them into Klipper: DELTA_ANALYZE CENTER_PILLAR_WIDTHS=<a>,<b>,<c> The final measurements are of the outer pillars. Start by measuring the distance of the A pillar along the line from A to the pillar across from C. Then go counterclockwise and measure the remaining outer pillars (pillar across from C along the line to B, B pillar along the line to pillar across from A, etc.). And enter them into Klipper: DELTA_ANALYZE OUTER_PILLAR_WIDTHS=<a>,<far_c>,<b>,<far_a>,<c>,<far_b> If the object was scaled to a smaller or larger size then provide the scale factor that was used when slicing the object: DELTA_ANALYZE SCALE=1.0 (A scale value of 2.0 would mean the object is twice its original size, 0.5 would be half its original size.) Finally, perform the enhanced delta calibration by running: DELTA_ANALYZE CALIBRATE=extended This command can take several minutes to complete. After completion it will calculate updated delta parameters (delta radius, tower angles, endstop positions, and arm lengths). Use the SAVE_CONFIG command to save and apply the settings: SAVE_CONFIG The SAVE_CONFIG command will save both the updated delta parameters and information from the distance measurements. Future DELTA_CALIBRATE commands will also utilize this distance information. Do not attempt to reenter the raw distance measurements after running SAVE_CONFIG, as this command changes the printer configuration and the raw measurements no longer apply. Additional notes \u00b6 If the delta printer has good dimensional accuracy then the distance between any two pillars should be around 74mm and the width of every pillar should be around 9mm. (Specifically, the goal is for the distance between any two pillars minus the width of one of the pillars to be exactly 65mm.) Should there be a dimensional inaccuracy in the part then the DELTA_ANALYZE routine will calculate new delta parameters using both the distance measurements and the previous height measurements from the last DELTA_CALIBRATE command. DELTA_ANALYZE may produce delta parameters that are surprising. For example, it may suggest arm lengths that do not match the printer's actual arm lengths. Despite this, testing has shown that DELTA_ANALYZE often produces superior results. It is believed that the calculated delta parameters are able to account for slight errors elsewhere in the hardware. For example, small differences in arm length may result in a tilt to the effector and some of that tilt may be accounted for by adjusting the arm length parameters. Using Bed Mesh on a Delta \u00b6 It is possible to use bed mesh on a delta. However, it is important to obtain good delta calibration prior to enabling a bed mesh. Running bed mesh with poor delta calibration will result in confusing and poor results. Note that performing delta calibration will invalidate any previously obtained bed mesh. After performing a new delta calibration be sure to rerun BED_MESH_CALIBRATE.","title":"Delta calibration"},{"location":"Delta_Calibrate.html#delta-calibration","text":"This document describes Klipper's automatic calibration system for \"delta\" style printers. Delta calibration involves finding the tower endstop positions, tower angles, delta radius, and delta arm lengths. These settings control printer motion on a delta printer. Each one of these parameters has a non-obvious and non-linear impact and it is difficult to calibrate them manually. In contrast, the software calibration code can provide excellent results with just a few minutes of time. No special probing hardware is necessary. Ultimately, the delta calibration is dependent on the precision of the tower endstop switches. If one is using Trinamic stepper motor drivers then consider enabling endstop phase detection to improve the accuracy of those switches.","title":"Delta calibration"},{"location":"Delta_Calibrate.html#automatic-vs-manual-probing","text":"Klipper supports calibrating the delta parameters via a manual probing method or via an automatic Z probe. A number of delta printer kits come with automatic Z probes that are not sufficiently accurate (specifically, small differences in arm length can cause effector tilt which can skew an automatic probe). If using an automatic probe then first calibrate the probe and then check for a probe location bias . If the automatic probe has a bias of more than 25 microns (.025mm) then use manual probing instead. Manual probing only takes a few minutes and it eliminates error introduced by the probe. If using a probe that is mounted on the side of the hotend (that is, it has an X or Y offset) then note that performing delta calibration will invalidate the results of probe calibration. These types of probes are rarely suitable for use on a delta (because minor effector tilt will result in a probe location bias). If using the probe anyway, then be sure to rerun probe calibration after any delta calibration.","title":"Automatic vs manual probing"},{"location":"Delta_Calibrate.html#basic-delta-calibration","text":"Klipper has a DELTA_CALIBRATE command that can perform basic delta calibration. This command probes seven different points on the bed and calculates new values for the tower angles, tower endstops, and delta radius. In order to perform this calibration the initial delta parameters (arm lengths, radius, and endstop positions) must be provided and they should have an accuracy to within a few millimeters. Most delta printer kits will provide these parameters - configure the printer with these initial defaults and then go on to run the DELTA_CALIBRATE command as described below. If no defaults are available then search online for a delta calibration guide that can provide a basic starting point. During the delta calibration process it may be necessary for the printer to probe below what would otherwise be considered the plane of the bed. It is typical to permit this during calibration by updating the config so that the printer's minimum_z_position=-5 . (Once calibration completes, one can remove this setting from the config.) There are two ways to perform the probing - manual probing ( DELTA_CALIBRATE METHOD=manual ) and automatic probing ( DELTA_CALIBRATE ). The manual probing method will move the head near the bed and then wait for the user to follow the steps described at \"the paper test\" to determine the actual distance between the nozzle and bed at the given location. To perform the basic probe, make sure the config has a [delta_calibrate] section defined and then run the tool: G28 DELTA_CALIBRATE METHOD=manual After probing the seven points new delta parameters will be calculated. Save and apply these parameters by running: SAVE_CONFIG The basic calibration should provide delta parameters that are accurate enough for basic printing. If this is a new printer, this is a good time to print some basic objects and verify general functionality.","title":"Basic delta calibration"},{"location":"Delta_Calibrate.html#enhanced-delta-calibration","text":"The basic delta calibration generally does a good job of calculating delta parameters such that the nozzle is the correct distance from the bed. However, it does not attempt to calibrate X and Y dimensional accuracy. It's a good idea to perform an enhanced delta calibration to verify dimensional accuracy. This calibration procedure requires printing a test object and measuring parts of that test object with digital calipers. Prior to running an enhanced delta calibration one must run the basic delta calibration (via the DELTA_CALIBRATE command) and save the results (via the SAVE_CONFIG command). Make sure there hasn't been any notable change to the printer configuration nor hardware since last performing a basic delta calibration (if unsure, rerun the basic delta calibration , including SAVE_CONFIG, just prior to printing the test object described below.) Use a slicer to generate G-Code from the docs/prints/calibrate_size.stl file. Slice the object using a slow speed (eg, 40mm/s). If possible, use a stiff plastic (such as PLA) for the object. The object has a diameter of 140mm. If this is too large for the printer then one can scale it down (but be sure to uniformly scale both the X and Y axes). If the printer supports significantly larger prints then this object can also be increased in size. A larger size can improve the measurement accuracy, but good print adhesion is more important than a larger print size. Print the test object and wait for it to fully cool. The commands described below must be run with the same printer settings used to print the calibration object (don't run DELTA_CALIBRATE between printing and measuring, or do something that would otherwise change the printer configuration). If possible, perform the measurements described below while the object is still attached to the print bed, but don't worry if the part detaches from the bed - just try to avoid bending the object when performing the measurements. Start by measuring the distance between the center pillar and the pillar next to the \"A\" label (which should also be pointing towards the \"A\" tower). Then go counterclockwise and measure the distances between the center pillar and the other pillars (distance from center to pillar across from C label, distance from center to pillar with B label, etc.). Enter these parameters into Klipper with a comma separated list of floating point numbers: DELTA_ANALYZE CENTER_DISTS=<a_dist>,<far_c_dist>,<b_dist>,<far_a_dist>,<c_dist>,<far_b_dist> Provide the values without spaces between them. Then measure the distance between the A pillar and the pillar across from the C label. Then go counterclockwise and measure the distance between the pillar across from C to the B pillar, the distance between the B pillar and the pillar across from A, and so on. Enter these parameters into Klipper: DELTA_ANALYZE OUTER_DISTS=<a_to_far_c>,<far_c_to_b>,<b_to_far_a>,<far_a_to_c>,<c_to_far_b>,<far_b_to_a> At this point it is okay to remove the object from the bed. The final measurements are of the pillars themselves. Measure the size of the center pillar along the A spoke, then the B spoke, and then the C spoke. Enter them into Klipper: DELTA_ANALYZE CENTER_PILLAR_WIDTHS=<a>,<b>,<c> The final measurements are of the outer pillars. Start by measuring the distance of the A pillar along the line from A to the pillar across from C. Then go counterclockwise and measure the remaining outer pillars (pillar across from C along the line to B, B pillar along the line to pillar across from A, etc.). And enter them into Klipper: DELTA_ANALYZE OUTER_PILLAR_WIDTHS=<a>,<far_c>,<b>,<far_a>,<c>,<far_b> If the object was scaled to a smaller or larger size then provide the scale factor that was used when slicing the object: DELTA_ANALYZE SCALE=1.0 (A scale value of 2.0 would mean the object is twice its original size, 0.5 would be half its original size.) Finally, perform the enhanced delta calibration by running: DELTA_ANALYZE CALIBRATE=extended This command can take several minutes to complete. After completion it will calculate updated delta parameters (delta radius, tower angles, endstop positions, and arm lengths). Use the SAVE_CONFIG command to save and apply the settings: SAVE_CONFIG The SAVE_CONFIG command will save both the updated delta parameters and information from the distance measurements. Future DELTA_CALIBRATE commands will also utilize this distance information. Do not attempt to reenter the raw distance measurements after running SAVE_CONFIG, as this command changes the printer configuration and the raw measurements no longer apply.","title":"Enhanced delta calibration"},{"location":"Delta_Calibrate.html#additional-notes","text":"If the delta printer has good dimensional accuracy then the distance between any two pillars should be around 74mm and the width of every pillar should be around 9mm. (Specifically, the goal is for the distance between any two pillars minus the width of one of the pillars to be exactly 65mm.) Should there be a dimensional inaccuracy in the part then the DELTA_ANALYZE routine will calculate new delta parameters using both the distance measurements and the previous height measurements from the last DELTA_CALIBRATE command. DELTA_ANALYZE may produce delta parameters that are surprising. For example, it may suggest arm lengths that do not match the printer's actual arm lengths. Despite this, testing has shown that DELTA_ANALYZE often produces superior results. It is believed that the calculated delta parameters are able to account for slight errors elsewhere in the hardware. For example, small differences in arm length may result in a tilt to the effector and some of that tilt may be accounted for by adjusting the arm length parameters.","title":"Additional notes"},{"location":"Delta_Calibrate.html#using-bed-mesh-on-a-delta","text":"It is possible to use bed mesh on a delta. However, it is important to obtain good delta calibration prior to enabling a bed mesh. Running bed mesh with poor delta calibration will result in confusing and poor results. Note that performing delta calibration will invalidate any previously obtained bed mesh. After performing a new delta calibration be sure to rerun BED_MESH_CALIBRATE.","title":"Using Bed Mesh on a Delta"},{"location":"Eddy_Probe.html","text":"Eddy Current Inductive probe \u00b6 This document describes how to use an eddy current inductive probe in Klipper. Currently, an eddy current probe can not be used for Z homing. The sensor can only be used for Z probing. Start by declaring a probe_eddy_current config section in the printer.cfg file. It is recommended to set the z_offset to 0.5mm. It is typical for the sensor to require an x_offset and y_offset . If these values are not known, one should estimate the values during initial calibration. The first step in calibration is to determine the appropriate DRIVE_CURRENT for the sensor. Home the printer and navigate the toolhead so that the sensor is near the center of the bed and is about 20mm above the bed. Then issue an LDC_CALIBRATE_DRIVE_CURRENT CHIP=<config_name> command. For example, if the config section was named [probe_eddy_current my_eddy_probe] then one would run LDC_CALIBRATE_DRIVE_CURRENT CHIP=my_eddy_probe . This command should complete in a few seconds. After it completes, issue a SAVE_CONFIG command to save the results to the printer.cfg and restart. The second step in calibration is to correlate the sensor readings to the corresponding Z heights. Home the printer and navigate the toolhead so that the nozzle is near the center of the bed. Then run an PROBE_EDDY_CURRENT_CALIBRATE CHIP=my_eddy_probe command. Once the tool starts, follow the steps described at \"the paper test\" to determine the actual distance between the nozzle and bed at the given location. Once those steps are complete one can ACCEPT the position. The tool will then move the the toolhead so that the sensor is above the point where the nozzle used to be and run a series of movements to correlate the sensor to Z positions. This will take a couple of minutes. After the tool completes, issue a SAVE_CONFIG command to save the results to the printer.cfg and restart. After initial calibration it is a good idea to verify that the x_offset and y_offset are accurate. Follow the steps to calibrate probe x and y offsets . If either the x_offset or y_offset is modified then be sure to run the PROBE_EDDY_CURRENT_CALIBRATE command (as described above) after making the change. Once calibration is complete, one may use all the standard Klipper tools that use a Z probe. Note that eddy current sensors (and inductive probes in general) are susceptible to \"thermal drift\". That is, changes in temperature can result in changes in reported Z height. Changes in either the bed surface temperature or sensor hardware temperature can skew the results. It is important that calibration and probing is only done when the printer is at a stable temperature. Thermal Drift Calibration \u00b6 As with all inductive probes, eddy current probes are subject to significant thermal drift. If the eddy probe has a temperature sensor on the coil it is possible to configure a [temperature_probe] to report coil temperature and enable software drift compensation. To link a temperature probe to an eddy current probe the [temperature_probe] section must share a name with the [probe_eddy_current] section. For example: [probe_eddy_current my_probe] # eddy probe configuration... [temperature_probe my_probe] # temperature probe configuration... See the configuration reference for further details on how to configure a temperature_probe . It is advised to configure the calibration_position , calibration_extruder_temp , extruder_heating_z , and calibration_bed_temp options, as doing so will automate some of the steps outlined below. If the printer to be calibrated is enclosed, it is strongly recommended to set the max_validation_temp option to a value between 100 and 120. Eddy probe manufacturers may offer a stock drift calibration that can be manually added to drift_calibration option of the [probe_eddy_current] section. If they do not, or if the stock calibration does not perform well on your system, the temperature_probe module offers a manual calibration procedure via the TEMPERATURE_PROBE_CALIBRATE gcode command. Prior to performing calibration the user should have an idea of what the maximum attainable temperature probe coil temperature is. This temperature should be used to set the TARGET parameter of the TEMPERATURE_PROBE_CALIBRATE command. The goal is to calibrate across the widest temperature range possible, thus its desirable to start with the printer cold and finish with the coil at the maximum temperature it can reach. Once a [temperature_probe] is configured, the following steps may be taken to perform thermal drift calibration: The probe must be calibrated using PROBE_EDDY_CURRENT_CALIBRATE when a [temperature_probe] is configured and linked. This captures the temperature during calibration which is necessary to perform thermal drift compensation. Make sure the nozzle is free of debris and filament. The bed, nozzle, and probe coil should be cold prior to calibration. The following steps are required if the calibration_position , calibration_extruder_temp , and extruder_heating_z options in [temperature_probe] are NOT configured: Move the tool to the center of the bed. Z should be 30mm+ above the bed. Heat the extruder to a temperature above the maximum safe bed temperature. 150-170C should be sufficient for most configurations. The purpose of heating the extruder is to avoid nozzle expansion during calibration. When the extruder temperature has settled, move the Z axis down to about 1mm above the bed. Start drift calibration. If the probe's name is my_probe and the maximum probe temperature we can achieve is 80C, the appropriate gcode command is TEMPERATURE_PROBE_CALIBRATE PROBE=my_probe TARGET=80 . If configured, the tool will move to the X,Y coordinate specified by the calibration_position and the Z value specified by extruder_heating_z . After heating the extruder to the specified temperature the tool will move to the Z value specified by the calibration_position . The procedure will request a manual probe. Perform the manual probe with the paper test and ACCEPT . The calibration procedure will take the first set of samples with the probe then park the probe in the heating position. If the calibration_bed_temp is NOT configured turn on the bed heat to the maximum safe temperature. Otherwise this step will be performed automatically. By default the calibration procedure will request a manual probe every 2C between samples until the TARGET is reached. The temperature delta between samples can be customized by setting the STEP parameter in TEMPERATURE_PROBE_CALIBRATE . Care should be taken when setting a custom STEP value, a value too high may request too few samples resulting in a poor calibration. The following additional gcode commands are available during drift calibration: TEMPERATURE_PROBE_NEXT may be used to force a new sample before the step delta has been reached. TEMPERATURE_PROBE_COMPLETE may be used to complete calibration before the TARGET has been reached. ABORT may be used to end calibration and discard results. When calibration is finished use SAVE_CONFIG to store the drift calibration. As one may conclude, the calibration process outlined above is more challenging and time consuming than most other procedures. It may require practice and several attempts to achieve an optimal calibration.","title":"Eddy Current Inductive probe"},{"location":"Eddy_Probe.html#eddy-current-inductive-probe","text":"This document describes how to use an eddy current inductive probe in Klipper. Currently, an eddy current probe can not be used for Z homing. The sensor can only be used for Z probing. Start by declaring a probe_eddy_current config section in the printer.cfg file. It is recommended to set the z_offset to 0.5mm. It is typical for the sensor to require an x_offset and y_offset . If these values are not known, one should estimate the values during initial calibration. The first step in calibration is to determine the appropriate DRIVE_CURRENT for the sensor. Home the printer and navigate the toolhead so that the sensor is near the center of the bed and is about 20mm above the bed. Then issue an LDC_CALIBRATE_DRIVE_CURRENT CHIP=<config_name> command. For example, if the config section was named [probe_eddy_current my_eddy_probe] then one would run LDC_CALIBRATE_DRIVE_CURRENT CHIP=my_eddy_probe . This command should complete in a few seconds. After it completes, issue a SAVE_CONFIG command to save the results to the printer.cfg and restart. The second step in calibration is to correlate the sensor readings to the corresponding Z heights. Home the printer and navigate the toolhead so that the nozzle is near the center of the bed. Then run an PROBE_EDDY_CURRENT_CALIBRATE CHIP=my_eddy_probe command. Once the tool starts, follow the steps described at \"the paper test\" to determine the actual distance between the nozzle and bed at the given location. Once those steps are complete one can ACCEPT the position. The tool will then move the the toolhead so that the sensor is above the point where the nozzle used to be and run a series of movements to correlate the sensor to Z positions. This will take a couple of minutes. After the tool completes, issue a SAVE_CONFIG command to save the results to the printer.cfg and restart. After initial calibration it is a good idea to verify that the x_offset and y_offset are accurate. Follow the steps to calibrate probe x and y offsets . If either the x_offset or y_offset is modified then be sure to run the PROBE_EDDY_CURRENT_CALIBRATE command (as described above) after making the change. Once calibration is complete, one may use all the standard Klipper tools that use a Z probe. Note that eddy current sensors (and inductive probes in general) are susceptible to \"thermal drift\". That is, changes in temperature can result in changes in reported Z height. Changes in either the bed surface temperature or sensor hardware temperature can skew the results. It is important that calibration and probing is only done when the printer is at a stable temperature.","title":"Eddy Current Inductive probe"},{"location":"Eddy_Probe.html#thermal-drift-calibration","text":"As with all inductive probes, eddy current probes are subject to significant thermal drift. If the eddy probe has a temperature sensor on the coil it is possible to configure a [temperature_probe] to report coil temperature and enable software drift compensation. To link a temperature probe to an eddy current probe the [temperature_probe] section must share a name with the [probe_eddy_current] section. For example: [probe_eddy_current my_probe] # eddy probe configuration... [temperature_probe my_probe] # temperature probe configuration... See the configuration reference for further details on how to configure a temperature_probe . It is advised to configure the calibration_position , calibration_extruder_temp , extruder_heating_z , and calibration_bed_temp options, as doing so will automate some of the steps outlined below. If the printer to be calibrated is enclosed, it is strongly recommended to set the max_validation_temp option to a value between 100 and 120. Eddy probe manufacturers may offer a stock drift calibration that can be manually added to drift_calibration option of the [probe_eddy_current] section. If they do not, or if the stock calibration does not perform well on your system, the temperature_probe module offers a manual calibration procedure via the TEMPERATURE_PROBE_CALIBRATE gcode command. Prior to performing calibration the user should have an idea of what the maximum attainable temperature probe coil temperature is. This temperature should be used to set the TARGET parameter of the TEMPERATURE_PROBE_CALIBRATE command. The goal is to calibrate across the widest temperature range possible, thus its desirable to start with the printer cold and finish with the coil at the maximum temperature it can reach. Once a [temperature_probe] is configured, the following steps may be taken to perform thermal drift calibration: The probe must be calibrated using PROBE_EDDY_CURRENT_CALIBRATE when a [temperature_probe] is configured and linked. This captures the temperature during calibration which is necessary to perform thermal drift compensation. Make sure the nozzle is free of debris and filament. The bed, nozzle, and probe coil should be cold prior to calibration. The following steps are required if the calibration_position , calibration_extruder_temp , and extruder_heating_z options in [temperature_probe] are NOT configured: Move the tool to the center of the bed. Z should be 30mm+ above the bed. Heat the extruder to a temperature above the maximum safe bed temperature. 150-170C should be sufficient for most configurations. The purpose of heating the extruder is to avoid nozzle expansion during calibration. When the extruder temperature has settled, move the Z axis down to about 1mm above the bed. Start drift calibration. If the probe's name is my_probe and the maximum probe temperature we can achieve is 80C, the appropriate gcode command is TEMPERATURE_PROBE_CALIBRATE PROBE=my_probe TARGET=80 . If configured, the tool will move to the X,Y coordinate specified by the calibration_position and the Z value specified by extruder_heating_z . After heating the extruder to the specified temperature the tool will move to the Z value specified by the calibration_position . The procedure will request a manual probe. Perform the manual probe with the paper test and ACCEPT . The calibration procedure will take the first set of samples with the probe then park the probe in the heating position. If the calibration_bed_temp is NOT configured turn on the bed heat to the maximum safe temperature. Otherwise this step will be performed automatically. By default the calibration procedure will request a manual probe every 2C between samples until the TARGET is reached. The temperature delta between samples can be customized by setting the STEP parameter in TEMPERATURE_PROBE_CALIBRATE . Care should be taken when setting a custom STEP value, a value too high may request too few samples resulting in a poor calibration. The following additional gcode commands are available during drift calibration: TEMPERATURE_PROBE_NEXT may be used to force a new sample before the step delta has been reached. TEMPERATURE_PROBE_COMPLETE may be used to complete calibration before the TARGET has been reached. ABORT may be used to end calibration and discard results. When calibration is finished use SAVE_CONFIG to store the drift calibration. As one may conclude, the calibration process outlined above is more challenging and time consuming than most other procedures. It may require practice and several attempts to achieve an optimal calibration.","title":"Thermal Drift Calibration"},{"location":"Endstop_Phase.html","text":"Endstop phase \u00b6 This document describes Klipper's stepper phase adjusted endstop system. This functionality can improve the accuracy of traditional endstop switches. It is most useful when using a Trinamic stepper motor driver that has run-time configuration. A typical endstop switch has an accuracy of around 100 microns. (Each time an axis is homed the switch may trigger slightly earlier or slightly later.) Although this is a relatively small error, it can result in unwanted artifacts. In particular, this positional deviation may be noticeable when printing the first layer of an object. In contrast, typical stepper motors can obtain significantly higher precision. The stepper phase adjusted endstop mechanism can use the precision of the stepper motors to improve the precision of the endstop switches. A stepper motor moves by cycling through a series of phases until in completes four \"full steps\". So, a stepper motor using 16 micro-steps would have 64 phases and when moving in a positive direction it would cycle through phases: 0, 1, 2, ... 61, 62, 63, 0, 1, 2, etc. Crucially, when the stepper motor is at a particular position on a linear rail it should always be at the same stepper phase. Thus, when a carriage triggers the endstop switch the stepper controlling that carriage should always be at the same stepper motor phase. Klipper's endstop phase system combines the stepper phase with the endstop trigger to improve the accuracy of the endstop. In order to use this functionality it is necessary to be able to identify the phase of the stepper motor. If one is using Trinamic TMC2130, TMC2208, TMC2224 or TMC2660 drivers in run-time configuration mode (ie, not stand-alone mode) then Klipper can query the stepper phase from the driver. (It is also possible to use this system on traditional stepper drivers if one can reliably reset the stepper drivers - see below for details.) Calibrating endstop phases \u00b6 If using Trinamic stepper motor drivers with run-time configuration then one can calibrate the endstop phases using the ENDSTOP_PHASE_CALIBRATE command. Start by adding the following to the config file: [endstop_phase] Then RESTART the printer and run a G28 command followed by an ENDSTOP_PHASE_CALIBRATE command. Then move the toolhead to a new location and run G28 again. Try moving the toolhead to several different locations and rerun G28 from each position. Run at least five G28 commands. After performing the above, the ENDSTOP_PHASE_CALIBRATE command will often report the same (or nearly the same) phase for the stepper. This phase can be saved in the config file so that all future G28 commands use that phase. (So, in future homing operations, Klipper will obtain the same position even if the endstop triggers a little earlier or a little later.) To save the endstop phase for a particular stepper motor, run something like the following: ENDSTOP_PHASE_CALIBRATE STEPPER=stepper_z Run the above for all the steppers one wishes to save. Typically, one would use this on stepper_z for cartesian and corexy printers, and for stepper_a, stepper_b, and stepper_c on delta printers. Finally, run the following to update the configuration file with the data: SAVE_CONFIG Additional notes \u00b6 This feature is most useful on delta printers and on the Z endstop of cartesian/corexy printers. It is possible to use this feature on the XY endstops of cartesian printers, but that isn't particularly useful as a minor error in X/Y endstop position is unlikely to impact print quality. It is not valid to use this feature on the XY endstops of corexy printers (as the XY position is not determined by a single stepper on corexy kinematics). It is not valid to use this feature on a printer using a \"probe:z_virtual_endstop\" Z endstop (as the stepper phase is only stable if the endstop is at a static location on a rail). After calibrating the endstop phase, if the endstop is later moved or adjusted then it will be necessary to recalibrate the endstop. Remove the calibration data from the config file and rerun the steps above. In order to use this system the endstop must be accurate enough to identify the stepper position within two \"full steps\". So, for example, if a stepper is using 16 micro-steps with a step distance of 0.005mm then the endstop must have an accuracy of at least 0.160mm. If one gets \"Endstop stepper_z incorrect phase\" type error messages than in may be due to an endstop that is not sufficiently accurate. If recalibration does not help then disable endstop phase adjustments by removing them from the config file. If one is using a traditional stepper controlled Z axis (as on a cartesian or corexy printer) along with traditional bed leveling screws then it is also possible to use this system to arrange for each print layer to be performed on a \"full step\" boundary. To enable this feature be sure the G-Code slicer is configured with a layer height that is a multiple of a \"full step\", manually enable the endstop_align_zero option in the endstop_phase config section (see config reference for further details), and then re-level the bed screws. It is possible to use this system with traditional (non-Trinamic) stepper motor drivers. However, doing this requires making sure that the stepper motor drivers are reset every time the micro-controller is reset. (If the two are always reset together then Klipper can determine the stepper phase by tracking the total number of steps it has commanded the stepper to move.) Currently, the only way to do this reliably is if both the micro-controller and stepper motor drivers are powered solely from USB and that USB power is provided from a host running on a Raspberry Pi. In this situation one can specify an mcu config with \"restart_method: rpi_usb\" - that option will arrange for the micro-controller to always be reset via a USB power reset, which would arrange for both the micro-controller and stepper motor drivers to be reset together. If using this mechanism, one would then need to manually configure the \"trigger_phase\" config sections (see config reference for the details).","title":"Endstop phase"},{"location":"Endstop_Phase.html#endstop-phase","text":"This document describes Klipper's stepper phase adjusted endstop system. This functionality can improve the accuracy of traditional endstop switches. It is most useful when using a Trinamic stepper motor driver that has run-time configuration. A typical endstop switch has an accuracy of around 100 microns. (Each time an axis is homed the switch may trigger slightly earlier or slightly later.) Although this is a relatively small error, it can result in unwanted artifacts. In particular, this positional deviation may be noticeable when printing the first layer of an object. In contrast, typical stepper motors can obtain significantly higher precision. The stepper phase adjusted endstop mechanism can use the precision of the stepper motors to improve the precision of the endstop switches. A stepper motor moves by cycling through a series of phases until in completes four \"full steps\". So, a stepper motor using 16 micro-steps would have 64 phases and when moving in a positive direction it would cycle through phases: 0, 1, 2, ... 61, 62, 63, 0, 1, 2, etc. Crucially, when the stepper motor is at a particular position on a linear rail it should always be at the same stepper phase. Thus, when a carriage triggers the endstop switch the stepper controlling that carriage should always be at the same stepper motor phase. Klipper's endstop phase system combines the stepper phase with the endstop trigger to improve the accuracy of the endstop. In order to use this functionality it is necessary to be able to identify the phase of the stepper motor. If one is using Trinamic TMC2130, TMC2208, TMC2224 or TMC2660 drivers in run-time configuration mode (ie, not stand-alone mode) then Klipper can query the stepper phase from the driver. (It is also possible to use this system on traditional stepper drivers if one can reliably reset the stepper drivers - see below for details.)","title":"Endstop phase"},{"location":"Endstop_Phase.html#calibrating-endstop-phases","text":"If using Trinamic stepper motor drivers with run-time configuration then one can calibrate the endstop phases using the ENDSTOP_PHASE_CALIBRATE command. Start by adding the following to the config file: [endstop_phase] Then RESTART the printer and run a G28 command followed by an ENDSTOP_PHASE_CALIBRATE command. Then move the toolhead to a new location and run G28 again. Try moving the toolhead to several different locations and rerun G28 from each position. Run at least five G28 commands. After performing the above, the ENDSTOP_PHASE_CALIBRATE command will often report the same (or nearly the same) phase for the stepper. This phase can be saved in the config file so that all future G28 commands use that phase. (So, in future homing operations, Klipper will obtain the same position even if the endstop triggers a little earlier or a little later.) To save the endstop phase for a particular stepper motor, run something like the following: ENDSTOP_PHASE_CALIBRATE STEPPER=stepper_z Run the above for all the steppers one wishes to save. Typically, one would use this on stepper_z for cartesian and corexy printers, and for stepper_a, stepper_b, and stepper_c on delta printers. Finally, run the following to update the configuration file with the data: SAVE_CONFIG","title":"Calibrating endstop phases"},{"location":"Endstop_Phase.html#additional-notes","text":"This feature is most useful on delta printers and on the Z endstop of cartesian/corexy printers. It is possible to use this feature on the XY endstops of cartesian printers, but that isn't particularly useful as a minor error in X/Y endstop position is unlikely to impact print quality. It is not valid to use this feature on the XY endstops of corexy printers (as the XY position is not determined by a single stepper on corexy kinematics). It is not valid to use this feature on a printer using a \"probe:z_virtual_endstop\" Z endstop (as the stepper phase is only stable if the endstop is at a static location on a rail). After calibrating the endstop phase, if the endstop is later moved or adjusted then it will be necessary to recalibrate the endstop. Remove the calibration data from the config file and rerun the steps above. In order to use this system the endstop must be accurate enough to identify the stepper position within two \"full steps\". So, for example, if a stepper is using 16 micro-steps with a step distance of 0.005mm then the endstop must have an accuracy of at least 0.160mm. If one gets \"Endstop stepper_z incorrect phase\" type error messages than in may be due to an endstop that is not sufficiently accurate. If recalibration does not help then disable endstop phase adjustments by removing them from the config file. If one is using a traditional stepper controlled Z axis (as on a cartesian or corexy printer) along with traditional bed leveling screws then it is also possible to use this system to arrange for each print layer to be performed on a \"full step\" boundary. To enable this feature be sure the G-Code slicer is configured with a layer height that is a multiple of a \"full step\", manually enable the endstop_align_zero option in the endstop_phase config section (see config reference for further details), and then re-level the bed screws. It is possible to use this system with traditional (non-Trinamic) stepper motor drivers. However, doing this requires making sure that the stepper motor drivers are reset every time the micro-controller is reset. (If the two are always reset together then Klipper can determine the stepper phase by tracking the total number of steps it has commanded the stepper to move.) Currently, the only way to do this reliably is if both the micro-controller and stepper motor drivers are powered solely from USB and that USB power is provided from a host running on a Raspberry Pi. In this situation one can specify an mcu config with \"restart_method: rpi_usb\" - that option will arrange for the micro-controller to always be reset via a USB power reset, which would arrange for both the micro-controller and stepper motor drivers to be reset together. If using this mechanism, one would then need to manually configure the \"trigger_phase\" config sections (see config reference for the details).","title":"Additional notes"},{"location":"Example_Configs.html","text":"Example configurations \u00b6 This document contains guidelines for contributing an example Klipper configuration to the Klipper github repository (located in the config directory ). Note that the Klipper Community Discourse server is also a useful resource for finding and sharing config files. Guidelines \u00b6 Select the appropriate config filename prefix: The printer prefix is used for stock printers sold by a mainstream manufacturer. The generic prefix is used for a 3d printer board that may be used in many different types of printers. The kit prefix is for 3d printers that are assembled according to a widely used specification. These \"kit\" printers are generally distinct from normal \"printers\" in that they are not sold by a manufacturer. The sample prefix is used for config \"snippets\" that one may copy-and-paste into the main config file. The example prefix is used to describe printer kinematics. This type of config is typically only added along with code for a new type of printer kinematics. All configuration files must end in a .cfg suffix. The printer config files must end in a year followed by .cfg (eg, -2019.cfg ). In this case, the year is an approximate year the given printer was sold. Do not use spaces or special characters in the config filename. The filename should contain only characters A-Z , a-z , 0-9 , - , and . . Klipper must be able to start printer , generic , and kit example config file without error. These config files should be added to the test/klippy/printers.test regression test case. Add new config files to that test case in the appropriate section and in alphabetical order within that section. The example configuration should be for the \"stock\" configuration of the printer. (There are too many \"customized\" configurations to track in the main Klipper repository.) Similarly, we only add example config files for printers, kits, and boards that have mainstream popularity (eg, there should be at least a 100 of them in active use). Consider using the Klipper Community Discourse server for other configs. Only specify those devices present on the given printer or board. Do not specify settings specific to your particular setup. For generic config files, only those devices on the mainboard should be described. For example, it would not make sense to add a display config section to a \"generic\" config as there is no way to know if the board will be attached to that type of display. If the board has a specific hardware port to facilitate an optional peripheral (eg, a bltouch port) then one can add a \"commented out\" config section for the given device. Do not specify pressure_advance in an example config, as that value is specific to the filament, not the printer hardware. Similarly, do not specify max_extrude_only_velocity nor max_extrude_only_accel settings. Do not specify a config section containing a host path or host hardware. For example, do not specify [virtual_sdcard] nor [temperature_host] config sections. Only define macros that utilize functionality specific to the given printer or to define g-codes that are commonly emitted by slicers configured for the given printer. Where possible, it is best to use the same wording, phrasing, indentation, and section ordering as the existing config files. The top of each config file should list the type of micro-controller the user should select during \"make menuconfig\". It should also have a reference to \"docs/Config_Reference.md\". Do not copy the field documentation into the example config files. (Doing so creates a maintenance burden as an update to the documentation would then require changing it in many places.) Example config files should not contain a \"SAVE_CONFIG\" section. If necessary, copy the relevant fields from the SAVE_CONFIG section to the appropriate section in the main config area. Use field: value syntax instead of field=value . When adding an extruder rotation_distance it is preferable to specify a gear_ratio if the extruder has a gearing mechanism. We expect the rotation_distance in the example configs to correlate with the circumference of the hobbed gear in the extruder - it is normally in the range of 20 to 35mm. When specifying a gear_ratio it is preferable to specify the actual gears on the mechanism (eg, prefer gear_ratio: 80:20 over gear_ratio: 4:1 ). See the rotation distance document for more information. Avoid defining field values that are set to their default value. For example, one should not specify min_extrude_temp: 170 as that is already the default value. Where possible, lines should not exceed 80 columns. Avoid adding attribution or revision messages to the config files. (For example, avoid adding lines like \"this file was created by ...\".) Place attribution and change history in the git commit message. Do not use any deprecated features in the example config file. Do not disable a default safety system in an example config file. For example, a config should not specify a custom max_extrude_cross_section . Do not enable debugging features. For example there should not be a force_move config section. All known boards that Klipper supports can use the default serial baud rate of 250000. Do not recommend a different baud rate in an example config file. Example config files are submitted by creating a github \"pull request\". Please also follow the directions in the contributing document .","title":"Example configurations"},{"location":"Example_Configs.html#example-configurations","text":"This document contains guidelines for contributing an example Klipper configuration to the Klipper github repository (located in the config directory ). Note that the Klipper Community Discourse server is also a useful resource for finding and sharing config files.","title":"Example configurations"},{"location":"Example_Configs.html#guidelines","text":"Select the appropriate config filename prefix: The printer prefix is used for stock printers sold by a mainstream manufacturer. The generic prefix is used for a 3d printer board that may be used in many different types of printers. The kit prefix is for 3d printers that are assembled according to a widely used specification. These \"kit\" printers are generally distinct from normal \"printers\" in that they are not sold by a manufacturer. The sample prefix is used for config \"snippets\" that one may copy-and-paste into the main config file. The example prefix is used to describe printer kinematics. This type of config is typically only added along with code for a new type of printer kinematics. All configuration files must end in a .cfg suffix. The printer config files must end in a year followed by .cfg (eg, -2019.cfg ). In this case, the year is an approximate year the given printer was sold. Do not use spaces or special characters in the config filename. The filename should contain only characters A-Z , a-z , 0-9 , - , and . . Klipper must be able to start printer , generic , and kit example config file without error. These config files should be added to the test/klippy/printers.test regression test case. Add new config files to that test case in the appropriate section and in alphabetical order within that section. The example configuration should be for the \"stock\" configuration of the printer. (There are too many \"customized\" configurations to track in the main Klipper repository.) Similarly, we only add example config files for printers, kits, and boards that have mainstream popularity (eg, there should be at least a 100 of them in active use). Consider using the Klipper Community Discourse server for other configs. Only specify those devices present on the given printer or board. Do not specify settings specific to your particular setup. For generic config files, only those devices on the mainboard should be described. For example, it would not make sense to add a display config section to a \"generic\" config as there is no way to know if the board will be attached to that type of display. If the board has a specific hardware port to facilitate an optional peripheral (eg, a bltouch port) then one can add a \"commented out\" config section for the given device. Do not specify pressure_advance in an example config, as that value is specific to the filament, not the printer hardware. Similarly, do not specify max_extrude_only_velocity nor max_extrude_only_accel settings. Do not specify a config section containing a host path or host hardware. For example, do not specify [virtual_sdcard] nor [temperature_host] config sections. Only define macros that utilize functionality specific to the given printer or to define g-codes that are commonly emitted by slicers configured for the given printer. Where possible, it is best to use the same wording, phrasing, indentation, and section ordering as the existing config files. The top of each config file should list the type of micro-controller the user should select during \"make menuconfig\". It should also have a reference to \"docs/Config_Reference.md\". Do not copy the field documentation into the example config files. (Doing so creates a maintenance burden as an update to the documentation would then require changing it in many places.) Example config files should not contain a \"SAVE_CONFIG\" section. If necessary, copy the relevant fields from the SAVE_CONFIG section to the appropriate section in the main config area. Use field: value syntax instead of field=value . When adding an extruder rotation_distance it is preferable to specify a gear_ratio if the extruder has a gearing mechanism. We expect the rotation_distance in the example configs to correlate with the circumference of the hobbed gear in the extruder - it is normally in the range of 20 to 35mm. When specifying a gear_ratio it is preferable to specify the actual gears on the mechanism (eg, prefer gear_ratio: 80:20 over gear_ratio: 4:1 ). See the rotation distance document for more information. Avoid defining field values that are set to their default value. For example, one should not specify min_extrude_temp: 170 as that is already the default value. Where possible, lines should not exceed 80 columns. Avoid adding attribution or revision messages to the config files. (For example, avoid adding lines like \"this file was created by ...\".) Place attribution and change history in the git commit message. Do not use any deprecated features in the example config file. Do not disable a default safety system in an example config file. For example, a config should not specify a custom max_extrude_cross_section . Do not enable debugging features. For example there should not be a force_move config section. All known boards that Klipper supports can use the default serial baud rate of 250000. Do not recommend a different baud rate in an example config file. Example config files are submitted by creating a github \"pull request\". Please also follow the directions in the contributing document .","title":"Guidelines"},{"location":"Exclude_Object.html","text":"Exclude Objects \u00b6 The [exclude_object] module allows Klipper to exclude objects while a print is in progress. To enable this feature include an exclude_object config section (also see the command reference and sample-macros.cfg file for a Marlin/RepRapFirmware compatible M486 G-Code macro.) Unlike other 3D printer firmware options, a printer running Klipper utilizes a suite of components and users have many options to choose from. Therefore, in order to provide a a consistent user experience, the [exclude_object] module will establish a contract or API of sorts. The contract covers the contents of the gcode file, how the internal state of the module is controlled, and how that state is provided to clients. Workflow Overview \u00b6 A typical workflow for printing a file might look like this: Slicing is completed and the file is uploaded for printing. During the upload, the file is processed and [exclude_object] markers are added to the file. Alternately, slicers may be configured to prepare object exclusion markers natively, or in it's own pre-processing step. When printing starts, Klipper will reset the [exclude_object] status . When Klipper processes the EXCLUDE_OBJECT_DEFINE block, it will update the status with the known objects and pass it on to clients. The client may use that information to present a UI to the user so that progress can be tracked. Klipper will update the status to include the currently printing object which the client can use for display purposes. If the user requests that an object be cancelled, the client will issue an EXCLUDE_OBJECT NAME=<name> command to Klipper. When Klipper process the command, it will add the object to the list of excluded objects and update the status for the client. The client will receive the updated status from Klipper and can use that information to reflect the object's status in the UI. When printing finishes, the [exclude_object] status will continue to be available until another action resets it. The GCode File \u00b6 The specialized gcode processing needed to support excluding objects does not fit into Klipper's core design goals. Therefore, this module requires that the file is processed before being sent to Klipper for printing. Using a post-process script in the slicer or having middleware process the file on upload are two possibilities for preparing the file for Klipper. A reference post-processing script is available both as an executable and a python library, see cancelobject-preprocessor . Object Definitions \u00b6 The EXCLUDE_OBJECT_DEFINE command is used to provide a summary of each object in the gcode file to be printed. Provides a summary of an object in the file. Objects don't need to be defined in order to be referenced by other commands. The primary purpose of this command is to provide information to the UI without needing to parse the entire gcode file. Object definitions are named, to allow users to easily select an object to be excluded, and additional metadata may be provided to allow for graphical cancellation displays. Currently defined metadata includes a CENTER X,Y coordinate, and a POLYGON list of X,Y points representing a minimal outline of the object. This could be a simple bounding box, or a complicated hull for showing more detailed visualizations of the printed objects. Especially when gcode files include multiple parts with overlapping bounding regions, center points become hard to visually distinguish. POLYGONS must be a json-compatible array of point [X,Y] tuples without whitespace. Additional parameters will be saved as strings in the object definition and provided in status updates. EXCLUDE_OBJECT_DEFINE NAME=calibration_pyramid CENTER=50,50 POLYGON=[[40,40],[50,60],[60,40]] All available G-Code commands are documented in the G-Code Reference Status Information \u00b6 The state of this module is provided to clients by the exclude_object status . The status is reset when: The Klipper firmware is restarted. There is a reset of the [virtual_sdcard] . Notably, this is reset by Klipper at the start of a print. When an EXCLUDE_OBJECT_DEFINE RESET=1 command is issued. The list of defined objects is represented in the exclude_object.objects status field. In a well defined gcode file, this will be done with EXCLUDE_OBJECT_DEFINE commands at the beginning of the file. This will provide clients with object names and coordinates so the UI can provide a graphical representation of the objects if desired. As the print progresses, the exclude_object.current_object status field will be updated as Klipper processes EXCLUDE_OBJECT_START and EXCLUDE_OBJECT_END commands. The current_object field will be set even if the object has been excluded. Undefined objects marked with a EXCLUDE_OBJECT_START will be added to the known objects to assist in UI hinting, without any additional metadata. As EXCLUDE_OBJECT commands are issued, the list of excluded objects is provided in the exclude_object.excluded_objects array. Since Klipper looks ahead to process upcoming gcode, there may be a delay between when the command is issued and when the status is updated.","title":"Exclude Objects"},{"location":"Exclude_Object.html#exclude-objects","text":"The [exclude_object] module allows Klipper to exclude objects while a print is in progress. To enable this feature include an exclude_object config section (also see the command reference and sample-macros.cfg file for a Marlin/RepRapFirmware compatible M486 G-Code macro.) Unlike other 3D printer firmware options, a printer running Klipper utilizes a suite of components and users have many options to choose from. Therefore, in order to provide a a consistent user experience, the [exclude_object] module will establish a contract or API of sorts. The contract covers the contents of the gcode file, how the internal state of the module is controlled, and how that state is provided to clients.","title":"Exclude Objects"},{"location":"Exclude_Object.html#workflow-overview","text":"A typical workflow for printing a file might look like this: Slicing is completed and the file is uploaded for printing. During the upload, the file is processed and [exclude_object] markers are added to the file. Alternately, slicers may be configured to prepare object exclusion markers natively, or in it's own pre-processing step. When printing starts, Klipper will reset the [exclude_object] status . When Klipper processes the EXCLUDE_OBJECT_DEFINE block, it will update the status with the known objects and pass it on to clients. The client may use that information to present a UI to the user so that progress can be tracked. Klipper will update the status to include the currently printing object which the client can use for display purposes. If the user requests that an object be cancelled, the client will issue an EXCLUDE_OBJECT NAME=<name> command to Klipper. When Klipper process the command, it will add the object to the list of excluded objects and update the status for the client. The client will receive the updated status from Klipper and can use that information to reflect the object's status in the UI. When printing finishes, the [exclude_object] status will continue to be available until another action resets it.","title":"Workflow Overview"},{"location":"Exclude_Object.html#the-gcode-file","text":"The specialized gcode processing needed to support excluding objects does not fit into Klipper's core design goals. Therefore, this module requires that the file is processed before being sent to Klipper for printing. Using a post-process script in the slicer or having middleware process the file on upload are two possibilities for preparing the file for Klipper. A reference post-processing script is available both as an executable and a python library, see cancelobject-preprocessor .","title":"The GCode File"},{"location":"Exclude_Object.html#object-definitions","text":"The EXCLUDE_OBJECT_DEFINE command is used to provide a summary of each object in the gcode file to be printed. Provides a summary of an object in the file. Objects don't need to be defined in order to be referenced by other commands. The primary purpose of this command is to provide information to the UI without needing to parse the entire gcode file. Object definitions are named, to allow users to easily select an object to be excluded, and additional metadata may be provided to allow for graphical cancellation displays. Currently defined metadata includes a CENTER X,Y coordinate, and a POLYGON list of X,Y points representing a minimal outline of the object. This could be a simple bounding box, or a complicated hull for showing more detailed visualizations of the printed objects. Especially when gcode files include multiple parts with overlapping bounding regions, center points become hard to visually distinguish. POLYGONS must be a json-compatible array of point [X,Y] tuples without whitespace. Additional parameters will be saved as strings in the object definition and provided in status updates. EXCLUDE_OBJECT_DEFINE NAME=calibration_pyramid CENTER=50,50 POLYGON=[[40,40],[50,60],[60,40]] All available G-Code commands are documented in the G-Code Reference","title":"Object Definitions"},{"location":"Exclude_Object.html#status-information","text":"The state of this module is provided to clients by the exclude_object status . The status is reset when: The Klipper firmware is restarted. There is a reset of the [virtual_sdcard] . Notably, this is reset by Klipper at the start of a print. When an EXCLUDE_OBJECT_DEFINE RESET=1 command is issued. The list of defined objects is represented in the exclude_object.objects status field. In a well defined gcode file, this will be done with EXCLUDE_OBJECT_DEFINE commands at the beginning of the file. This will provide clients with object names and coordinates so the UI can provide a graphical representation of the objects if desired. As the print progresses, the exclude_object.current_object status field will be updated as Klipper processes EXCLUDE_OBJECT_START and EXCLUDE_OBJECT_END commands. The current_object field will be set even if the object has been excluded. Undefined objects marked with a EXCLUDE_OBJECT_START will be added to the known objects to assist in UI hinting, without any additional metadata. As EXCLUDE_OBJECT commands are issued, the list of excluded objects is provided in the exclude_object.excluded_objects array. Since Klipper looks ahead to process upcoming gcode, there may be a delay between when the command is issued and when the status is updated.","title":"Status Information"},{"location":"FAQ.html","text":"Frequently Asked Questions \u00b6 How can I donate to the project? \u00b6 Thank you for your support. See the Sponsors page for information. How do I calculate the rotation_distance config parameter? \u00b6 See the rotation distance document . Where's my serial port? \u00b6 The general way to find a USB serial port is to run ls /dev/serial/by-id/* from an ssh terminal on the host machine. It will likely produce output similar to the following: /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 The name found in the above command is stable and it is possible to use it in the config file and while flashing the micro-controller code. For example, a flash command might look similar to: sudo service klipper stop make flash FLASH_DEVICE=/dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 sudo service klipper start and the updated config might look like: [mcu] serial: /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 Be sure to copy-and-paste the name from the \"ls\" command that you ran above as the name will be different for each printer. If you are using multiple micro-controllers and they do not have unique ids (common on boards with a CH340 USB chip) then follow the directions above using the command ls /dev/serial/by-path/* instead. When the micro-controller restarts the device changes to /dev/ttyUSB1 \u00b6 Follow the directions in the \" Where's my serial port? \" section to prevent this from occurring. The \"make flash\" command doesn't work \u00b6 The code attempts to flash the device using the most common method for each platform. Unfortunately, there is a lot of variance in flashing methods, so the \"make flash\" command may not work on all boards. If you're having an intermittent failure or you do have a standard setup, then double check that Klipper isn't running when flashing (sudo service klipper stop), make sure OctoPrint isn't trying to connect directly to the device (open the Connection tab in the web page and click Disconnect if the Serial Port is set to the device), and make sure FLASH_DEVICE is set correctly for your board (see the question above ). However, if \"make flash\" just doesn't work for your board, then you will need to manually flash. See if there is a config file in the config directory with specific instructions for flashing the device. Also, check the board manufacturer's documentation to see if it describes how to flash the device. Finally, it may be possible to manually flash the device using tools such as \"avrdude\" or \"bossac\" - see the bootloader document for additional information. How do I change the serial baud rate? \u00b6 The recommended baud rate for Klipper is 250000. This baud rate works well on all micro-controller boards that Klipper supports. If you've found an online guide recommending a different baud rate, then ignore that part of the guide and continue with the default value of 250000. If you want to change the baud rate anyway, then the new rate will need to be configured in the micro-controller (during make menuconfig ) and that updated code will need to be compiled and flashed to the micro-controller. The Klipper printer.cfg file will also need to be updated to match that baud rate (see the config reference for details). For example: [mcu] baud: 250000 The baud rate shown on the OctoPrint web page has no impact on the internal Klipper micro-controller baud rate. Always set the OctoPrint baud rate to 250000 when using Klipper. The Klipper micro-controller baud rate is not related to the baud rate of the micro-controller's bootloader. See the bootloader document for additional information on bootloaders. Can I run Klipper on something other than a Raspberry Pi 3? \u00b6 The recommended hardware is a Raspberry Pi Zero2w, Raspberry Pi 3, Raspberry Pi 4 or Raspberry Pi 5. Klipper will also run on other SBC devices as well as x86 hardware, as described below. Klipper will run on a Raspberry Pi 1, 2 and on the Raspberry Pi Zero1, but these boards don't have enough processing power to run Klipper well. It is common for print stalls to occur on these slower machines when printing (The printer may move faster than Klipper can send movement commands.) It is not reccomended to run Kliper on these older machines. For running on the Beaglebone, see the Beaglebone specific installation instructions . Klipper has been run on other machines. The Klipper host software only requires Python running on a Linux (or similar) computer. However, if you wish to run it on a different machine you will need Linux admin knowledge to install the system prerequisites for that particular machine. See the install-octopi.sh script for further information on the necessary Linux admin steps. If you are looking to run the Klipper host software on a low-end chip, then be aware that, at a minimum, a machine with \"double precision floating point\" hardware is required. If you are looking to run the Klipper host software on a shared general-purpose desktop or server class machine, then note that Klipper has some real-time scheduling requirements. If, during a print, the host computer also performs an intensive general-purpose computing task (such as defragmenting a hard drive, 3d rendering, heavy swapping, etc.), then it may cause Klipper to report print errors. Note: If you are not using an OctoPi image, be aware that several Linux distributions enable a \"ModemManager\" (or similar) package that can disrupt serial communication. (Which can cause Klipper to report seemingly random \"Lost communication with MCU\" errors.) If you install Klipper on one of these distributions you may need to disable that package. Can I run multiple instances of Klipper on the same host machine? \u00b6 It is possible to run multiple instances of the Klipper host software, but doing so requires Linux admin knowledge. The Klipper installation scripts ultimately cause the following Unix command to be run: ~/klippy-env/bin/python ~/klipper/klippy/klippy.py ~/printer.cfg -l /tmp/klippy.log One can run multiple instances of the above command as long as each instance has its own printer config file, its own log file, and its own pseudo-tty. For example: ~/klippy-env/bin/python ~/klipper/klippy/klippy.py ~/printer2.cfg -l /tmp/klippy2.log -I /tmp/printer2 If you choose to do this, you will need to implement the necessary start, stop, and installation scripts (if any). The install-octopi.sh script and the klipper-start.sh script may be useful as examples. Do I have to use OctoPrint? \u00b6 The Klipper software is not dependent on OctoPrint. It is possible to use alternative software to send commands to Klipper, but doing so requires Linux admin knowledge. Klipper creates a \"virtual serial port\" via the \"/tmp/printer\" file, and it emulates a classic 3d-printer serial interface via that file. In general, alternative software may work with Klipper as long as it can be configured to use \"/tmp/printer\" for the printer serial port. Why can't I move the stepper before homing the printer? \u00b6 The code does this to reduce the chance of accidentally commanding the head into the bed or a wall. Once the printer is homed the software attempts to verify each move is within the position_min/max defined in the config file. If the motors are disabled (via an M84 or M18 command) then the motors will need to be homed again prior to movement. If you want to move the head after canceling a print via OctoPrint, consider changing the OctoPrint cancel sequence to do that for you. It's configured in OctoPrint via a web browser under: Settings->GCODE Scripts If you want to move the head after a print finishes, consider adding the desired movement to the \"custom g-code\" section of your slicer. If the printer requires some additional movement as part of the homing process itself (or fundamentally does not have a homing process) then consider using a safe_z_home or homing_override section in the config file. If you need to move a stepper for diagnostic or debugging purposes then consider adding a force_move section to the config file. See config reference for further details on these options. Why is the Z position_endstop set to 0.5 in the default configs? \u00b6 For cartesian style printers the Z position_endstop specifies how far the nozzle is from the bed when the endstop triggers. If possible, it is recommended to use a Z-max endstop and home away from the bed (as this reduces the potential for bed collisions). However, if one must home towards the bed then it is recommended to position the endstop so it triggers when the nozzle is still a small distance away from the bed. This way, when homing the axis, it will stop before the nozzle touches the bed. See the bed level document for more information. I converted my config from Marlin and the X/Y axes work fine, but I just get a screeching noise when homing the Z axis \u00b6 Short answer: First, make sure you have verified the stepper configuration as described in the config check document . If the problem persists, try reducing the max_z_velocity setting in the printer config. Long answer: In practice Marlin can typically only step at a rate of around 10000 steps per second. If it is requested to move at a speed that would require a higher step rate then Marlin will generally just step as fast as it can. Klipper is able to achieve much higher step rates, but the stepper motor may not have sufficient torque to move at a higher speed. So, for a Z axis with a high gearing ratio or high microsteps setting the actual obtainable max_z_velocity may be smaller than what is configured in Marlin. My TMC motor driver turns off in the middle of a print \u00b6 If using the TMC2208 (or TMC2224) driver in \"standalone mode\" then make sure to use the latest version of Klipper . A workaround for a TMC2208 \"stealthchop\" driver problem was added to Klipper in mid-March of 2020. I keep getting random \"Lost communication with MCU\" errors \u00b6 This is commonly caused by hardware errors on the USB connection between the host machine and the micro-controller. Things to look for: Use a good quality USB cable between the host machine and micro-controller. Make sure the plugs are secure. If using a Raspberry Pi, use a good quality power supply for the Raspberry Pi and use a good quality USB cable to connect that power supply to the Pi. If you get \"under voltage\" warnings from OctoPrint, this is related to the power supply and it must be fixed. Make sure the printer's power supply is not being overloaded. (Power fluctuations to the micro-controller's USB chip may result in resets of that chip.) Verify stepper, heater, and other printer wires are not crimped or frayed. (Printer movement may place stress on a faulty wire causing it to lose contact, briefly short, or generate excessive noise.) There have been reports of high USB noise when both the printer's power supply and the host's 5V power supply are mixed. (If you find that the micro-controller powers on when either the printer's power supply is on or the USB cable is plugged in, then it indicates the 5V power supplies are being mixed.) It may help to configure the micro-controller to use power from only one source. (Alternatively, if the micro-controller board can not configure its power source, one may modify a USB cable so that it does not carry 5V power between the host and micro-controller.) My Raspberry Pi keeps rebooting during prints \u00b6 This is most likely do to voltage fluctuations. Follow the same troubleshooting steps for a \"Lost communication with MCU\" error. When I set restart_method=command my AVR device just hangs on a restart \u00b6 Some old versions of the AVR bootloader have a known bug in watchdog event handling. This typically manifests when the printer.cfg file has restart_method set to \"command\". When the bug occurs, the AVR device will be unresponsive until power is removed and reapplied to the device (the power or status LEDs may also blink repeatedly until the power is removed). The workaround is to use a restart_method other than \"command\" or to flash an updated bootloader to the AVR device. Flashing a new bootloader is a one time step that typically requires an external programmer - see Bootloaders for further details. Will the heaters be left on if the Raspberry Pi crashes? \u00b6 The software has been designed to prevent that. Once the host enables a heater, the host software needs to confirm that enablement every 5 seconds. If the micro-controller does not receive a confirmation every 5 seconds it goes into a \"shutdown\" state which is designed to turn off all heaters and stepper motors. See the \"config_digital_out\" command in the MCU commands document for further details. In addition, the micro-controller software is configured with a minimum and maximum temperature range for each heater at startup (see the min_temp and max_temp parameters in the config reference for details). If the micro-controller detects that the temperature is outside of that range then it will also enter a \"shutdown\" state. Separately, the host software also implements code to check that heaters and temperature sensors are functioning correctly. See the config reference for further details. How do I convert a Marlin pin number to a Klipper pin name? \u00b6 Short answer: A mapping is available in the sample-aliases.cfg file. Use that file as a guide to finding the actual micro-controller pin names. (It is also possible to copy the relevant board_pins config section into your config file and use the aliases in your config, but it is preferable to translate and use the actual micro-controller pin names.) Note that the sample-aliases.cfg file uses pin names that start with the prefix \"ar\" instead of \"D\" (eg, Arduino pin D23 is Klipper alias ar23 ) and the prefix \"analog\" instead of \"A\" (eg, Arduino pin A14 is Klipper alias analog14 ). Long answer: Klipper uses the standard pin names defined by the micro-controller. On the Atmega chips these hardware pins have names like PA4 , PC7 , or PD2 . Long ago, the Arduino project decided to avoid using the standard hardware names in favor of their own pin names based on incrementing numbers - these Arduino names generally look like D23 or A14 . This was an unfortunate choice that has lead to a great deal of confusion. In particular the Arduino pin numbers frequently don't translate to the same hardware names. For example, D21 is PD0 on one common Arduino board, but is PC7 on another common Arduino board. To avoid this confusion, the core Klipper code uses the standard pin names defined by the micro-controller. Do I have to wire my device to a specific type of micro-controller pin? \u00b6 It depends on the type of device and type of pin: ADC pins (or Analog pins): For thermistors and similar \"analog\" sensors, the device must be wired to an \"analog\" or \"ADC\" capable pin on the micro-controller. If you configure Klipper to use a pin that is not analog capable, Klipper will report a \"Not a valid ADC pin\" error. PWM pins (or Timer pins): Klipper does not use hardware PWM by default for any device. So, in general, one may wire heaters, fans, and similar devices to any general purpose IO pin. However, fans and output_pin devices may be optionally configured to use hardware_pwm: True , in which case the micro-controller must support hardware PWM on the pin (otherwise, Klipper will report a \"Not a valid PWM pin\" error). IRQ pins (or Interrupt pins): Klipper does not use hardware interrupts on IO pins, so it is never necessary to wire a device to one of these micro-controller pins. SPI pins: When using hardware SPI it is necessary to wire the pins to the micro-controller's SPI capable pins. However, most devices can be configured to use \"software SPI\", in which case any general purpose IO pins may be used. I2C pins: When using I2C it is necessary to wire the pins to the micro-controller's I2C capable pins. Other devices may be wired to any general purpose IO pin. For example, steppers, heaters, fans, Z probes, servos, LEDs, common hd44780/st7920 LCD displays, the Trinamic UART control line may be wired to any general purpose IO pin. How do I cancel an M109/M190 \"wait for temperature\" request? \u00b6 Navigate to the OctoPrint terminal tab and issue an M112 command in the terminal box. The M112 command will cause Klipper to enter into a \"shutdown\" state, and it will cause OctoPrint to disconnect from Klipper. Navigate to the OctoPrint connection area and click on \"Connect\" to cause OctoPrint to reconnect. Navigate back to the terminal tab and issue a FIRMWARE_RESTART command to clear the Klipper error state. After completing this sequence, the previous heating request will be canceled and a new print may be started. Can I find out whether the printer has lost steps? \u00b6 In a way, yes. Home the printer, issue a GET_POSITION command, run your print, home again and issue another GET_POSITION . Then compare the values in the mcu: line. This might be helpful to tune settings like stepper motor currents, accelerations and speeds without needing to actually print something and waste filament: just run some high-speed moves in between the GET_POSITION commands. Note that endstop switches themselves tend to trigger at slightly different positions, so a difference of a couple of microsteps is likely the result of endstop inaccuracies. A stepper motor itself can only lose steps in increments of 4 full steps. (So, if one is using 16 microsteps, then a lost step on the stepper would result in the \"mcu:\" step counter being off by a multiple of 64 microsteps.) Why does Klipper report errors? I lost my print! \u00b6 Short answer: We want to know if our printers detect a problem so that the underlying issue can be fixed and we can obtain great quality prints. We definitely do not want our printers to silently produce low quality prints. Long answer: Klipper has been engineered to automatically workaround many transient problems. For example, it automatically detects communication errors and will retransmit; it schedules actions in advance and buffers commands at multiple layers to enable precise timing even with intermittent interference. However, should the software detect an error that it can not recover from, if it is commanded to take an invalid action, or if it detects it is hopelessly unable to perform its commanded task, then Klipper will report an error. In these situations there is a high risk of producing a low-quality print (or worse). It is hoped that alerting the user will empower them to fix the underlying issue and improve the overall quality of their prints. There are some related questions: Why doesn't Klipper pause the print instead? Report a warning instead? Check for errors before the print? Ignore errors in user typed commands? etc? Currently Klipper reads commands using the G-Code protocol, and unfortunately the G-Code command protocol is not flexible enough to make these alternatives practical today. There is developer interest in improving the user experience during abnormal events, but it is expected that will require notable infrastructure work (including a shift away from G-Code). How do I upgrade to the latest software? \u00b6 The first step to upgrading the software is to review the latest config changes document. On occasion, changes are made to the software that require users to update their settings as part of a software upgrade. It is a good idea to review this document prior to upgrading. When ready to upgrade, the general method is to ssh into the Raspberry Pi and run: cd ~/klipper git pull ~/klipper/scripts/install-octopi.sh Then one can recompile and flash the micro-controller code. For example: make menuconfig make clean make sudo service klipper stop make flash FLASH_DEVICE=/dev/ttyACM0 sudo service klipper start However, it's often the case that only the host software changes. In this case, one can update and restart just the host software with: cd ~/klipper git pull sudo service klipper restart If after using this shortcut the software warns about needing to reflash the micro-controller or some other unusual error occurs, then follow the full upgrade steps outlined above. If any errors persist then double check the config changes document, as you may need to modify the printer configuration. Note that the RESTART and FIRMWARE_RESTART g-code commands do not load new software - the above \"sudo service klipper restart\" and \"make flash\" commands are needed for a software change to take effect. How do I uninstall Klipper? \u00b6 On the firmware end, nothing special needs to happen. Just follow the flashing directions for the new firmware. On the raspberry pi end, an uninstall script is available in scripts/klipper-uninstall.sh . For example: sudo ~/klipper/scripts/klipper-uninstall.sh rm -rf ~/klippy-env ~/klipper","title":"Frequently Asked Questions"},{"location":"FAQ.html#frequently-asked-questions","text":"","title":"Frequently Asked Questions"},{"location":"FAQ.html#how-can-i-donate-to-the-project","text":"Thank you for your support. See the Sponsors page for information.","title":"How can I donate to the project?"},{"location":"FAQ.html#how-do-i-calculate-the-rotation_distance-config-parameter","text":"See the rotation distance document .","title":"How do I calculate the rotation_distance config parameter?"},{"location":"FAQ.html#wheres-my-serial-port","text":"The general way to find a USB serial port is to run ls /dev/serial/by-id/* from an ssh terminal on the host machine. It will likely produce output similar to the following: /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 The name found in the above command is stable and it is possible to use it in the config file and while flashing the micro-controller code. For example, a flash command might look similar to: sudo service klipper stop make flash FLASH_DEVICE=/dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 sudo service klipper start and the updated config might look like: [mcu] serial: /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 Be sure to copy-and-paste the name from the \"ls\" command that you ran above as the name will be different for each printer. If you are using multiple micro-controllers and they do not have unique ids (common on boards with a CH340 USB chip) then follow the directions above using the command ls /dev/serial/by-path/* instead.","title":"Where's my serial port?"},{"location":"FAQ.html#when-the-micro-controller-restarts-the-device-changes-to-devttyusb1","text":"Follow the directions in the \" Where's my serial port? \" section to prevent this from occurring.","title":"When the micro-controller restarts the device changes to /dev/ttyUSB1"},{"location":"FAQ.html#the-make-flash-command-doesnt-work","text":"The code attempts to flash the device using the most common method for each platform. Unfortunately, there is a lot of variance in flashing methods, so the \"make flash\" command may not work on all boards. If you're having an intermittent failure or you do have a standard setup, then double check that Klipper isn't running when flashing (sudo service klipper stop), make sure OctoPrint isn't trying to connect directly to the device (open the Connection tab in the web page and click Disconnect if the Serial Port is set to the device), and make sure FLASH_DEVICE is set correctly for your board (see the question above ). However, if \"make flash\" just doesn't work for your board, then you will need to manually flash. See if there is a config file in the config directory with specific instructions for flashing the device. Also, check the board manufacturer's documentation to see if it describes how to flash the device. Finally, it may be possible to manually flash the device using tools such as \"avrdude\" or \"bossac\" - see the bootloader document for additional information.","title":"The \"make flash\" command doesn't work"},{"location":"FAQ.html#how-do-i-change-the-serial-baud-rate","text":"The recommended baud rate for Klipper is 250000. This baud rate works well on all micro-controller boards that Klipper supports. If you've found an online guide recommending a different baud rate, then ignore that part of the guide and continue with the default value of 250000. If you want to change the baud rate anyway, then the new rate will need to be configured in the micro-controller (during make menuconfig ) and that updated code will need to be compiled and flashed to the micro-controller. The Klipper printer.cfg file will also need to be updated to match that baud rate (see the config reference for details). For example: [mcu] baud: 250000 The baud rate shown on the OctoPrint web page has no impact on the internal Klipper micro-controller baud rate. Always set the OctoPrint baud rate to 250000 when using Klipper. The Klipper micro-controller baud rate is not related to the baud rate of the micro-controller's bootloader. See the bootloader document for additional information on bootloaders.","title":"How do I change the serial baud rate?"},{"location":"FAQ.html#can-i-run-klipper-on-something-other-than-a-raspberry-pi-3","text":"The recommended hardware is a Raspberry Pi Zero2w, Raspberry Pi 3, Raspberry Pi 4 or Raspberry Pi 5. Klipper will also run on other SBC devices as well as x86 hardware, as described below. Klipper will run on a Raspberry Pi 1, 2 and on the Raspberry Pi Zero1, but these boards don't have enough processing power to run Klipper well. It is common for print stalls to occur on these slower machines when printing (The printer may move faster than Klipper can send movement commands.) It is not reccomended to run Kliper on these older machines. For running on the Beaglebone, see the Beaglebone specific installation instructions . Klipper has been run on other machines. The Klipper host software only requires Python running on a Linux (or similar) computer. However, if you wish to run it on a different machine you will need Linux admin knowledge to install the system prerequisites for that particular machine. See the install-octopi.sh script for further information on the necessary Linux admin steps. If you are looking to run the Klipper host software on a low-end chip, then be aware that, at a minimum, a machine with \"double precision floating point\" hardware is required. If you are looking to run the Klipper host software on a shared general-purpose desktop or server class machine, then note that Klipper has some real-time scheduling requirements. If, during a print, the host computer also performs an intensive general-purpose computing task (such as defragmenting a hard drive, 3d rendering, heavy swapping, etc.), then it may cause Klipper to report print errors. Note: If you are not using an OctoPi image, be aware that several Linux distributions enable a \"ModemManager\" (or similar) package that can disrupt serial communication. (Which can cause Klipper to report seemingly random \"Lost communication with MCU\" errors.) If you install Klipper on one of these distributions you may need to disable that package.","title":"Can I run Klipper on something other than a Raspberry Pi 3?"},{"location":"FAQ.html#can-i-run-multiple-instances-of-klipper-on-the-same-host-machine","text":"It is possible to run multiple instances of the Klipper host software, but doing so requires Linux admin knowledge. The Klipper installation scripts ultimately cause the following Unix command to be run: ~/klippy-env/bin/python ~/klipper/klippy/klippy.py ~/printer.cfg -l /tmp/klippy.log One can run multiple instances of the above command as long as each instance has its own printer config file, its own log file, and its own pseudo-tty. For example: ~/klippy-env/bin/python ~/klipper/klippy/klippy.py ~/printer2.cfg -l /tmp/klippy2.log -I /tmp/printer2 If you choose to do this, you will need to implement the necessary start, stop, and installation scripts (if any). The install-octopi.sh script and the klipper-start.sh script may be useful as examples.","title":"Can I run multiple instances of Klipper on the same host machine?"},{"location":"FAQ.html#do-i-have-to-use-octoprint","text":"The Klipper software is not dependent on OctoPrint. It is possible to use alternative software to send commands to Klipper, but doing so requires Linux admin knowledge. Klipper creates a \"virtual serial port\" via the \"/tmp/printer\" file, and it emulates a classic 3d-printer serial interface via that file. In general, alternative software may work with Klipper as long as it can be configured to use \"/tmp/printer\" for the printer serial port.","title":"Do I have to use OctoPrint?"},{"location":"FAQ.html#why-cant-i-move-the-stepper-before-homing-the-printer","text":"The code does this to reduce the chance of accidentally commanding the head into the bed or a wall. Once the printer is homed the software attempts to verify each move is within the position_min/max defined in the config file. If the motors are disabled (via an M84 or M18 command) then the motors will need to be homed again prior to movement. If you want to move the head after canceling a print via OctoPrint, consider changing the OctoPrint cancel sequence to do that for you. It's configured in OctoPrint via a web browser under: Settings->GCODE Scripts If you want to move the head after a print finishes, consider adding the desired movement to the \"custom g-code\" section of your slicer. If the printer requires some additional movement as part of the homing process itself (or fundamentally does not have a homing process) then consider using a safe_z_home or homing_override section in the config file. If you need to move a stepper for diagnostic or debugging purposes then consider adding a force_move section to the config file. See config reference for further details on these options.","title":"Why can't I move the stepper before homing the printer?"},{"location":"FAQ.html#why-is-the-z-position_endstop-set-to-05-in-the-default-configs","text":"For cartesian style printers the Z position_endstop specifies how far the nozzle is from the bed when the endstop triggers. If possible, it is recommended to use a Z-max endstop and home away from the bed (as this reduces the potential for bed collisions). However, if one must home towards the bed then it is recommended to position the endstop so it triggers when the nozzle is still a small distance away from the bed. This way, when homing the axis, it will stop before the nozzle touches the bed. See the bed level document for more information.","title":"Why is the Z position_endstop set to 0.5 in the default configs?"},{"location":"FAQ.html#i-converted-my-config-from-marlin-and-the-xy-axes-work-fine-but-i-just-get-a-screeching-noise-when-homing-the-z-axis","text":"Short answer: First, make sure you have verified the stepper configuration as described in the config check document . If the problem persists, try reducing the max_z_velocity setting in the printer config. Long answer: In practice Marlin can typically only step at a rate of around 10000 steps per second. If it is requested to move at a speed that would require a higher step rate then Marlin will generally just step as fast as it can. Klipper is able to achieve much higher step rates, but the stepper motor may not have sufficient torque to move at a higher speed. So, for a Z axis with a high gearing ratio or high microsteps setting the actual obtainable max_z_velocity may be smaller than what is configured in Marlin.","title":"I converted my config from Marlin and the X/Y axes work fine, but I just get a screeching noise when homing the Z axis"},{"location":"FAQ.html#my-tmc-motor-driver-turns-off-in-the-middle-of-a-print","text":"If using the TMC2208 (or TMC2224) driver in \"standalone mode\" then make sure to use the latest version of Klipper . A workaround for a TMC2208 \"stealthchop\" driver problem was added to Klipper in mid-March of 2020.","title":"My TMC motor driver turns off in the middle of a print"},{"location":"FAQ.html#i-keep-getting-random-lost-communication-with-mcu-errors","text":"This is commonly caused by hardware errors on the USB connection between the host machine and the micro-controller. Things to look for: Use a good quality USB cable between the host machine and micro-controller. Make sure the plugs are secure. If using a Raspberry Pi, use a good quality power supply for the Raspberry Pi and use a good quality USB cable to connect that power supply to the Pi. If you get \"under voltage\" warnings from OctoPrint, this is related to the power supply and it must be fixed. Make sure the printer's power supply is not being overloaded. (Power fluctuations to the micro-controller's USB chip may result in resets of that chip.) Verify stepper, heater, and other printer wires are not crimped or frayed. (Printer movement may place stress on a faulty wire causing it to lose contact, briefly short, or generate excessive noise.) There have been reports of high USB noise when both the printer's power supply and the host's 5V power supply are mixed. (If you find that the micro-controller powers on when either the printer's power supply is on or the USB cable is plugged in, then it indicates the 5V power supplies are being mixed.) It may help to configure the micro-controller to use power from only one source. (Alternatively, if the micro-controller board can not configure its power source, one may modify a USB cable so that it does not carry 5V power between the host and micro-controller.)","title":"I keep getting random \"Lost communication with MCU\" errors"},{"location":"FAQ.html#my-raspberry-pi-keeps-rebooting-during-prints","text":"This is most likely do to voltage fluctuations. Follow the same troubleshooting steps for a \"Lost communication with MCU\" error.","title":"My Raspberry Pi keeps rebooting during prints"},{"location":"FAQ.html#when-i-set-restart_methodcommand-my-avr-device-just-hangs-on-a-restart","text":"Some old versions of the AVR bootloader have a known bug in watchdog event handling. This typically manifests when the printer.cfg file has restart_method set to \"command\". When the bug occurs, the AVR device will be unresponsive until power is removed and reapplied to the device (the power or status LEDs may also blink repeatedly until the power is removed). The workaround is to use a restart_method other than \"command\" or to flash an updated bootloader to the AVR device. Flashing a new bootloader is a one time step that typically requires an external programmer - see Bootloaders for further details.","title":"When I set restart_method=command my AVR device just hangs on a restart"},{"location":"FAQ.html#will-the-heaters-be-left-on-if-the-raspberry-pi-crashes","text":"The software has been designed to prevent that. Once the host enables a heater, the host software needs to confirm that enablement every 5 seconds. If the micro-controller does not receive a confirmation every 5 seconds it goes into a \"shutdown\" state which is designed to turn off all heaters and stepper motors. See the \"config_digital_out\" command in the MCU commands document for further details. In addition, the micro-controller software is configured with a minimum and maximum temperature range for each heater at startup (see the min_temp and max_temp parameters in the config reference for details). If the micro-controller detects that the temperature is outside of that range then it will also enter a \"shutdown\" state. Separately, the host software also implements code to check that heaters and temperature sensors are functioning correctly. See the config reference for further details.","title":"Will the heaters be left on if the Raspberry Pi crashes?"},{"location":"FAQ.html#how-do-i-convert-a-marlin-pin-number-to-a-klipper-pin-name","text":"Short answer: A mapping is available in the sample-aliases.cfg file. Use that file as a guide to finding the actual micro-controller pin names. (It is also possible to copy the relevant board_pins config section into your config file and use the aliases in your config, but it is preferable to translate and use the actual micro-controller pin names.) Note that the sample-aliases.cfg file uses pin names that start with the prefix \"ar\" instead of \"D\" (eg, Arduino pin D23 is Klipper alias ar23 ) and the prefix \"analog\" instead of \"A\" (eg, Arduino pin A14 is Klipper alias analog14 ). Long answer: Klipper uses the standard pin names defined by the micro-controller. On the Atmega chips these hardware pins have names like PA4 , PC7 , or PD2 . Long ago, the Arduino project decided to avoid using the standard hardware names in favor of their own pin names based on incrementing numbers - these Arduino names generally look like D23 or A14 . This was an unfortunate choice that has lead to a great deal of confusion. In particular the Arduino pin numbers frequently don't translate to the same hardware names. For example, D21 is PD0 on one common Arduino board, but is PC7 on another common Arduino board. To avoid this confusion, the core Klipper code uses the standard pin names defined by the micro-controller.","title":"How do I convert a Marlin pin number to a Klipper pin name?"},{"location":"FAQ.html#do-i-have-to-wire-my-device-to-a-specific-type-of-micro-controller-pin","text":"It depends on the type of device and type of pin: ADC pins (or Analog pins): For thermistors and similar \"analog\" sensors, the device must be wired to an \"analog\" or \"ADC\" capable pin on the micro-controller. If you configure Klipper to use a pin that is not analog capable, Klipper will report a \"Not a valid ADC pin\" error. PWM pins (or Timer pins): Klipper does not use hardware PWM by default for any device. So, in general, one may wire heaters, fans, and similar devices to any general purpose IO pin. However, fans and output_pin devices may be optionally configured to use hardware_pwm: True , in which case the micro-controller must support hardware PWM on the pin (otherwise, Klipper will report a \"Not a valid PWM pin\" error). IRQ pins (or Interrupt pins): Klipper does not use hardware interrupts on IO pins, so it is never necessary to wire a device to one of these micro-controller pins. SPI pins: When using hardware SPI it is necessary to wire the pins to the micro-controller's SPI capable pins. However, most devices can be configured to use \"software SPI\", in which case any general purpose IO pins may be used. I2C pins: When using I2C it is necessary to wire the pins to the micro-controller's I2C capable pins. Other devices may be wired to any general purpose IO pin. For example, steppers, heaters, fans, Z probes, servos, LEDs, common hd44780/st7920 LCD displays, the Trinamic UART control line may be wired to any general purpose IO pin.","title":"Do I have to wire my device to a specific type of micro-controller pin?"},{"location":"FAQ.html#how-do-i-cancel-an-m109m190-wait-for-temperature-request","text":"Navigate to the OctoPrint terminal tab and issue an M112 command in the terminal box. The M112 command will cause Klipper to enter into a \"shutdown\" state, and it will cause OctoPrint to disconnect from Klipper. Navigate to the OctoPrint connection area and click on \"Connect\" to cause OctoPrint to reconnect. Navigate back to the terminal tab and issue a FIRMWARE_RESTART command to clear the Klipper error state. After completing this sequence, the previous heating request will be canceled and a new print may be started.","title":"How do I cancel an M109/M190 \"wait for temperature\" request?"},{"location":"FAQ.html#can-i-find-out-whether-the-printer-has-lost-steps","text":"In a way, yes. Home the printer, issue a GET_POSITION command, run your print, home again and issue another GET_POSITION . Then compare the values in the mcu: line. This might be helpful to tune settings like stepper motor currents, accelerations and speeds without needing to actually print something and waste filament: just run some high-speed moves in between the GET_POSITION commands. Note that endstop switches themselves tend to trigger at slightly different positions, so a difference of a couple of microsteps is likely the result of endstop inaccuracies. A stepper motor itself can only lose steps in increments of 4 full steps. (So, if one is using 16 microsteps, then a lost step on the stepper would result in the \"mcu:\" step counter being off by a multiple of 64 microsteps.)","title":"Can I find out whether the printer has lost steps?"},{"location":"FAQ.html#why-does-klipper-report-errors-i-lost-my-print","text":"Short answer: We want to know if our printers detect a problem so that the underlying issue can be fixed and we can obtain great quality prints. We definitely do not want our printers to silently produce low quality prints. Long answer: Klipper has been engineered to automatically workaround many transient problems. For example, it automatically detects communication errors and will retransmit; it schedules actions in advance and buffers commands at multiple layers to enable precise timing even with intermittent interference. However, should the software detect an error that it can not recover from, if it is commanded to take an invalid action, or if it detects it is hopelessly unable to perform its commanded task, then Klipper will report an error. In these situations there is a high risk of producing a low-quality print (or worse). It is hoped that alerting the user will empower them to fix the underlying issue and improve the overall quality of their prints. There are some related questions: Why doesn't Klipper pause the print instead? Report a warning instead? Check for errors before the print? Ignore errors in user typed commands? etc? Currently Klipper reads commands using the G-Code protocol, and unfortunately the G-Code command protocol is not flexible enough to make these alternatives practical today. There is developer interest in improving the user experience during abnormal events, but it is expected that will require notable infrastructure work (including a shift away from G-Code).","title":"Why does Klipper report errors? I lost my print!"},{"location":"FAQ.html#how-do-i-upgrade-to-the-latest-software","text":"The first step to upgrading the software is to review the latest config changes document. On occasion, changes are made to the software that require users to update their settings as part of a software upgrade. It is a good idea to review this document prior to upgrading. When ready to upgrade, the general method is to ssh into the Raspberry Pi and run: cd ~/klipper git pull ~/klipper/scripts/install-octopi.sh Then one can recompile and flash the micro-controller code. For example: make menuconfig make clean make sudo service klipper stop make flash FLASH_DEVICE=/dev/ttyACM0 sudo service klipper start However, it's often the case that only the host software changes. In this case, one can update and restart just the host software with: cd ~/klipper git pull sudo service klipper restart If after using this shortcut the software warns about needing to reflash the micro-controller or some other unusual error occurs, then follow the full upgrade steps outlined above. If any errors persist then double check the config changes document, as you may need to modify the printer configuration. Note that the RESTART and FIRMWARE_RESTART g-code commands do not load new software - the above \"sudo service klipper restart\" and \"make flash\" commands are needed for a software change to take effect.","title":"How do I upgrade to the latest software?"},{"location":"FAQ.html#how-do-i-uninstall-klipper","text":"On the firmware end, nothing special needs to happen. Just follow the flashing directions for the new firmware. On the raspberry pi end, an uninstall script is available in scripts/klipper-uninstall.sh . For example: sudo ~/klipper/scripts/klipper-uninstall.sh rm -rf ~/klippy-env ~/klipper","title":"How do I uninstall Klipper?"},{"location":"Features.html","text":"Features \u00b6 Klipper has several compelling features: High precision stepper movement. Klipper utilizes an application processor (such as a low-cost Raspberry Pi) when calculating printer movements. The application processor determines when to step each stepper motor, it compresses those events, transmits them to the micro-controller, and then the micro-controller executes each event at the requested time. Each stepper event is scheduled with a precision of 25 micro-seconds or better. The software does not use kinematic estimations (such as the Bresenham algorithm) - instead it calculates precise step times based on the physics of acceleration and the physics of the machine kinematics. More precise stepper movement provides quieter and more stable printer operation. Best in class performance. Klipper is able to achieve high stepping rates on both new and old micro-controllers. Even old 8-bit micro-controllers can obtain rates over 175K steps per second. On more recent micro-controllers, several million steps per second are possible. Higher stepper rates enable higher print velocities. The stepper event timing remains precise even at high speeds which improves overall stability. Klipper supports printers with multiple micro-controllers. For example, one micro-controller could be used to control an extruder, while another controls the printer's heaters, while a third controls the rest of the printer. The Klipper host software implements clock synchronization to account for clock drift between micro-controllers. No special code is needed to enable multiple micro-controllers - it just requires a few extra lines in the config file. Configuration via simple config file. There's no need to reflash the micro-controller to change a setting. All of Klipper's configuration is stored in a standard config file which can be easily edited. This makes it easier to setup and maintain the hardware. Klipper supports \"Smooth Pressure Advance\" - a mechanism to account for the effects of pressure within an extruder. This reduces extruder \"ooze\" and improves the quality of print corners. Klipper's implementation does not introduce instantaneous extruder speed changes, which improves overall stability and robustness. Klipper supports \"Input Shaping\" to reduce the impact of vibrations on print quality. This can reduce or eliminate \"ringing\" (also known as \"ghosting\", \"echoing\", or \"rippling\") in prints. It may also allow one to obtain faster printing speeds while still maintaining high print quality. Klipper uses an \"iterative solver\" to calculate precise step times from simple kinematic equations. This makes porting Klipper to new types of robots easier and it keeps timing precise even with complex kinematics (no \"line segmentation\" is needed). Klipper is hardware agnostic. One should get the same precise timing independent of the low-level electronics hardware. The Klipper micro-controller code is designed to faithfully follow the schedule provided by the Klipper host software (or prominently alert the user if it is unable to). This makes it easier to use available hardware, to upgrade to new hardware, and to have confidence in the hardware. Portable code. Klipper works on ARM, AVR, PRU, and other micro-controllers. Existing \"reprap\" style printers can run Klipper without hardware modification - just add a Raspberry Pi. Klipper's internal code layout makes it easier to support other micro-controller architectures as well. Simpler code. Klipper uses a very high level language (Python) for most code. The kinematics algorithms, the G-code parsing, the heating and thermistor algorithms, etc. are all written in Python. This makes it easier to develop new functionality. Custom programmable macros. New G-Code commands can be defined in the printer config file (no code changes are necessary). Those commands are programmable - allowing them to produce different actions depending on the state of the printer. Builtin API server. In addition to the standard G-Code interface, Klipper supports a rich JSON based application interface. This enables programmers to build external applications with detailed control of the printer. Additional features \u00b6 Klipper supports many standard 3d printer features: Several web interfaces available. Works with Mainsail, Fluidd, OctoPrint and others. This allows the printer to be controlled using a regular web-browser. The same Raspberry Pi that runs Klipper can also run the web interface. Standard G-Code support. Common g-code commands that are produced by typical \"slicers\" (SuperSlicer, Cura, PrusaSlicer, etc.) are supported. Support for multiple extruders. Extruders with shared heaters and extruders on independent carriages (IDEX) are also supported. Support for cartesian, delta, corexy, corexz, hybrid-corexy, hybrid-corexz, deltesian, rotary delta, polar, and cable winch style printers. Automatic bed leveling support. Klipper can be configured for basic bed tilt detection or full mesh bed leveling. The bed mesh can be customized to the print size (adaptive bed mesh). If the bed uses multiple Z steppers then Klipper can also level by independently manipulating the Z steppers. Most Z height probes are supported, including BL-Touch probes and servo activated probes. Probes may be calibrated for axis twist compensation. If using an \"eddy current probe\" then one can utilize fast bed mesh scanning, Automatic delta calibration support. The calibration tool can perform basic height calibration as well as an enhanced X and Y dimension calibration. The calibration can be done with a Z height probe or via manual probing. Run-time \"exclude object\" support. When configured, this module may facilitate canceling of just one object in a multi-part print. Support for common temperature sensors (eg, common thermistors, AD595, AD597, AD849x, PT100, PT1000, MAX6675, MAX31855, MAX31856, MAX31865, BME280, HTU21D, DS18B20, AHT10, SHT3x, and LM75). Custom thermistors and custom analog temperature sensors can also be configured. One can monitor the internal micro-controller temperature sensor and the internal temperature sensor of a Raspberry Pi. Basic thermal heater protection enabled by default. Support for standard fans, nozzle fans, and temperature controlled fans. No need to keep fans running when the printer is idle. Fan speed can be monitored on fans that have a tachometer. One can assign a \"math formula\" to a fan for automatic fan speed updating. Support for run-time configuration of TMC2130, TMC2208/TMC2224, TMC2209, TMC2240, TMC2660, and TMC5160 stepper motor drivers. There is also support for current control of traditional stepper drivers via AD5206, DAC084S085, MCP4451, MCP4728, MCP4018, and PWM pins. Support for common LCD displays attached directly to the printer. A default menu is also available. The contents of the display and menu can be fully customized via the config file. Constant acceleration and \"look-ahead\" support. All printer moves will gradually accelerate from standstill to cruising speed and then decelerate back to a standstill. The incoming stream of G-Code movement commands are queued and analyzed - the acceleration between movements in a similar direction will be optimized to reduce print stalls and improve overall print time. Klipper implements a \"stepper phase endstop\" algorithm that can improve the accuracy of typical endstop switches. When properly tuned it can improve a print's first layer bed adhesion. Support for filament presence sensors, filament motion sensors, and filament width sensors. Support for measuring and recording acceleration using adxl345, mpu9250, mpu6050, lis2dw12, lis3dh, and icm20948 accelerometers. Support for limiting the top speed of short \"zigzag\" moves to reduce printer vibration and noise. See the kinematics document for more information. Sample configuration files are available for many common printers. Check the config directory for a list. To get started with Klipper, read the installation guide. Step Benchmarks \u00b6 Below are the results of stepper performance tests. The numbers shown represent total number of steps per second on the micro-controller. Micro-controller 1 stepper active 3 steppers active 16Mhz AVR 157K 99K 20Mhz AVR 196K 123K SAMD21 686K 471K STM32F042 814K 578K Beaglebone PRU 866K 708K STM32G0B1 1103K 790K STM32F103 1180K 818K SAM3X8E 1273K 981K SAM4S8C 1690K 1385K LPC1768 1923K 1351K LPC1769 2353K 1622K SAM4E8E 2500K 1674K SAMD51 3077K 1885K AR100 3529K 2507K STM32G431 3617K 2452K STM32F407 3652K 2459K STM32F446 3913K 2634K RP2040 4000K 2571K RP2350 4167K 2663K SAME70 6667K 4737K STM32H723 7429K 8619K If unsure of the micro-controller on a particular board, find the appropriate config file , and look for the micro-controller name in the comments at the top of that file. Further details on the benchmarks are available in the Benchmarks document .","title":"Features"},{"location":"Features.html#features","text":"Klipper has several compelling features: High precision stepper movement. Klipper utilizes an application processor (such as a low-cost Raspberry Pi) when calculating printer movements. The application processor determines when to step each stepper motor, it compresses those events, transmits them to the micro-controller, and then the micro-controller executes each event at the requested time. Each stepper event is scheduled with a precision of 25 micro-seconds or better. The software does not use kinematic estimations (such as the Bresenham algorithm) - instead it calculates precise step times based on the physics of acceleration and the physics of the machine kinematics. More precise stepper movement provides quieter and more stable printer operation. Best in class performance. Klipper is able to achieve high stepping rates on both new and old micro-controllers. Even old 8-bit micro-controllers can obtain rates over 175K steps per second. On more recent micro-controllers, several million steps per second are possible. Higher stepper rates enable higher print velocities. The stepper event timing remains precise even at high speeds which improves overall stability. Klipper supports printers with multiple micro-controllers. For example, one micro-controller could be used to control an extruder, while another controls the printer's heaters, while a third controls the rest of the printer. The Klipper host software implements clock synchronization to account for clock drift between micro-controllers. No special code is needed to enable multiple micro-controllers - it just requires a few extra lines in the config file. Configuration via simple config file. There's no need to reflash the micro-controller to change a setting. All of Klipper's configuration is stored in a standard config file which can be easily edited. This makes it easier to setup and maintain the hardware. Klipper supports \"Smooth Pressure Advance\" - a mechanism to account for the effects of pressure within an extruder. This reduces extruder \"ooze\" and improves the quality of print corners. Klipper's implementation does not introduce instantaneous extruder speed changes, which improves overall stability and robustness. Klipper supports \"Input Shaping\" to reduce the impact of vibrations on print quality. This can reduce or eliminate \"ringing\" (also known as \"ghosting\", \"echoing\", or \"rippling\") in prints. It may also allow one to obtain faster printing speeds while still maintaining high print quality. Klipper uses an \"iterative solver\" to calculate precise step times from simple kinematic equations. This makes porting Klipper to new types of robots easier and it keeps timing precise even with complex kinematics (no \"line segmentation\" is needed). Klipper is hardware agnostic. One should get the same precise timing independent of the low-level electronics hardware. The Klipper micro-controller code is designed to faithfully follow the schedule provided by the Klipper host software (or prominently alert the user if it is unable to). This makes it easier to use available hardware, to upgrade to new hardware, and to have confidence in the hardware. Portable code. Klipper works on ARM, AVR, PRU, and other micro-controllers. Existing \"reprap\" style printers can run Klipper without hardware modification - just add a Raspberry Pi. Klipper's internal code layout makes it easier to support other micro-controller architectures as well. Simpler code. Klipper uses a very high level language (Python) for most code. The kinematics algorithms, the G-code parsing, the heating and thermistor algorithms, etc. are all written in Python. This makes it easier to develop new functionality. Custom programmable macros. New G-Code commands can be defined in the printer config file (no code changes are necessary). Those commands are programmable - allowing them to produce different actions depending on the state of the printer. Builtin API server. In addition to the standard G-Code interface, Klipper supports a rich JSON based application interface. This enables programmers to build external applications with detailed control of the printer.","title":"Features"},{"location":"Features.html#additional-features","text":"Klipper supports many standard 3d printer features: Several web interfaces available. Works with Mainsail, Fluidd, OctoPrint and others. This allows the printer to be controlled using a regular web-browser. The same Raspberry Pi that runs Klipper can also run the web interface. Standard G-Code support. Common g-code commands that are produced by typical \"slicers\" (SuperSlicer, Cura, PrusaSlicer, etc.) are supported. Support for multiple extruders. Extruders with shared heaters and extruders on independent carriages (IDEX) are also supported. Support for cartesian, delta, corexy, corexz, hybrid-corexy, hybrid-corexz, deltesian, rotary delta, polar, and cable winch style printers. Automatic bed leveling support. Klipper can be configured for basic bed tilt detection or full mesh bed leveling. The bed mesh can be customized to the print size (adaptive bed mesh). If the bed uses multiple Z steppers then Klipper can also level by independently manipulating the Z steppers. Most Z height probes are supported, including BL-Touch probes and servo activated probes. Probes may be calibrated for axis twist compensation. If using an \"eddy current probe\" then one can utilize fast bed mesh scanning, Automatic delta calibration support. The calibration tool can perform basic height calibration as well as an enhanced X and Y dimension calibration. The calibration can be done with a Z height probe or via manual probing. Run-time \"exclude object\" support. When configured, this module may facilitate canceling of just one object in a multi-part print. Support for common temperature sensors (eg, common thermistors, AD595, AD597, AD849x, PT100, PT1000, MAX6675, MAX31855, MAX31856, MAX31865, BME280, HTU21D, DS18B20, AHT10, SHT3x, and LM75). Custom thermistors and custom analog temperature sensors can also be configured. One can monitor the internal micro-controller temperature sensor and the internal temperature sensor of a Raspberry Pi. Basic thermal heater protection enabled by default. Support for standard fans, nozzle fans, and temperature controlled fans. No need to keep fans running when the printer is idle. Fan speed can be monitored on fans that have a tachometer. One can assign a \"math formula\" to a fan for automatic fan speed updating. Support for run-time configuration of TMC2130, TMC2208/TMC2224, TMC2209, TMC2240, TMC2660, and TMC5160 stepper motor drivers. There is also support for current control of traditional stepper drivers via AD5206, DAC084S085, MCP4451, MCP4728, MCP4018, and PWM pins. Support for common LCD displays attached directly to the printer. A default menu is also available. The contents of the display and menu can be fully customized via the config file. Constant acceleration and \"look-ahead\" support. All printer moves will gradually accelerate from standstill to cruising speed and then decelerate back to a standstill. The incoming stream of G-Code movement commands are queued and analyzed - the acceleration between movements in a similar direction will be optimized to reduce print stalls and improve overall print time. Klipper implements a \"stepper phase endstop\" algorithm that can improve the accuracy of typical endstop switches. When properly tuned it can improve a print's first layer bed adhesion. Support for filament presence sensors, filament motion sensors, and filament width sensors. Support for measuring and recording acceleration using adxl345, mpu9250, mpu6050, lis2dw12, lis3dh, and icm20948 accelerometers. Support for limiting the top speed of short \"zigzag\" moves to reduce printer vibration and noise. See the kinematics document for more information. Sample configuration files are available for many common printers. Check the config directory for a list. To get started with Klipper, read the installation guide.","title":"Additional features"},{"location":"Features.html#step-benchmarks","text":"Below are the results of stepper performance tests. The numbers shown represent total number of steps per second on the micro-controller. Micro-controller 1 stepper active 3 steppers active 16Mhz AVR 157K 99K 20Mhz AVR 196K 123K SAMD21 686K 471K STM32F042 814K 578K Beaglebone PRU 866K 708K STM32G0B1 1103K 790K STM32F103 1180K 818K SAM3X8E 1273K 981K SAM4S8C 1690K 1385K LPC1768 1923K 1351K LPC1769 2353K 1622K SAM4E8E 2500K 1674K SAMD51 3077K 1885K AR100 3529K 2507K STM32G431 3617K 2452K STM32F407 3652K 2459K STM32F446 3913K 2634K RP2040 4000K 2571K RP2350 4167K 2663K SAME70 6667K 4737K STM32H723 7429K 8619K If unsure of the micro-controller on a particular board, find the appropriate config file , and look for the micro-controller name in the comments at the top of that file. Further details on the benchmarks are available in the Benchmarks document .","title":"Step Benchmarks"},{"location":"G-Codes.html","text":"G-Codes \u00b6 This document describes the commands that Klipper supports. These are commands that one may enter into the OctoPrint terminal tab. G-Code commands \u00b6 Klipper supports the following standard G-Code commands: Move (G0 or G1): G1 [X<pos>] [Y<pos>] [Z<pos>] [E<pos>] [F<speed>] Dwell: G4 P<milliseconds> Move to origin: G28 [X] [Y] [Z] Turn off motors: M18 or M84 Wait for current moves to finish: M400 Use absolute/relative distances for extrusion: M82 , M83 Use absolute/relative coordinates: G90 , G91 Set position: G92 [X<pos>] [Y<pos>] [Z<pos>] [E<pos>] Set speed factor override percentage: M220 S<percent> Set extrude factor override percentage: M221 S<percent> Set acceleration: M204 S<value> OR M204 P<value> T<value> Note: If S is not specified and both P and T are specified, then the acceleration is set to the minimum of P and T. If only one of P or T is specified, the command has no effect. Get extruder temperature: M105 Set extruder temperature: M104 [T<index>] [S<temperature>] Set extruder temperature and wait: M109 [T<index>] S<temperature> Note: M109 always waits for temperature to settle at requested value Set bed temperature: M140 [S<temperature>] Set bed temperature and wait: M190 S<temperature> Note: M190 always waits for temperature to settle at requested value Set fan speed: M106 S<value> Turn fan off: M107 Emergency stop: M112 Get current position: M114 Get firmware version: M115 For further details on the above commands see the RepRap G-Code documentation . Klipper's goal is to support the G-Code commands produced by common 3rd party software (eg, OctoPrint, Printrun, Slic3r, Cura, etc.) in their standard configurations. It is not a goal to support every possible G-Code command. Instead, Klipper prefers human readable \"extended G-Code commands\" . Similarly, the G-Code terminal output is only intended to be human readable - see the API Server document if controlling Klipper from external software. If one requires a less common G-Code command then it may be possible to implement it with a custom gcode_macro config section . For example, one might use this to implement: G12 , G29 , G30 , G31 , M42 , M80 , M81 , T1 , etc. Additional Commands \u00b6 Klipper uses \"extended\" G-Code commands for general configuration and status. These extended commands all follow a similar format - they start with a command name and may be followed by one or more parameters. For example: SET_SERVO SERVO=myservo ANGLE=5.3 . In this document, the commands and parameters are shown in uppercase, however they are not case sensitive. (So, \"SET_SERVO\" and \"set_servo\" both run the same command.) This section is organized by Klipper module name, which generally follows the section names specified in the printer configuration file . Note that some modules are automatically loaded. [adxl345] \u00b6 The following commands are available when an adxl345 config section is enabled. ACCELEROMETER_MEASURE \u00b6 ACCELEROMETER_MEASURE [CHIP=<config_name>] [NAME=<value>] : Starts accelerometer measurements at the requested number of samples per second. If CHIP is not specified it defaults to \"adxl345\". The command works in a start-stop mode: when executed for the first time, it starts the measurements, next execution stops them. The results of measurements are written to a file named /tmp/adxl345-<chip>-<name>.csv where <chip> is the name of the accelerometer chip ( my_chip_name from [adxl345 my_chip_name] ) and <name> is the optional NAME parameter. If NAME is not specified it defaults to the current time in \"YYYYMMDD_HHMMSS\" format. If the accelerometer does not have a name in its config section (simply [adxl345] ) then <chip> part of the name is not generated. ACCELEROMETER_QUERY \u00b6 ACCELEROMETER_QUERY [CHIP=<config_name>] [RATE=<value>] : queries accelerometer for the current value. If CHIP is not specified it defaults to \"adxl345\". If RATE is not specified, the default value is used. This command is useful to test the connection to the ADXL345 accelerometer: one of the returned values should be a free-fall acceleration (+/- some noise of the chip). ACCELEROMETER_DEBUG_READ \u00b6 ACCELEROMETER_DEBUG_READ [CHIP=<config_name>] REG=<register> : queries ADXL345 register \"register\" (e.g. 44 or 0x2C). Can be useful for debugging purposes. ACCELEROMETER_DEBUG_WRITE \u00b6 ACCELEROMETER_DEBUG_WRITE [CHIP=<config_name>] REG=<register> VAL=<value> : Writes raw \"value\" into a register \"register\". Both \"value\" and \"register\" can be a decimal or a hexadecimal integer. Use with care, and refer to ADXL345 data sheet for the reference. [angle] \u00b6 The following commands are available when an angle config section is enabled. ANGLE_CALIBRATE \u00b6 ANGLE_CALIBRATE CHIP=<chip_name> : Perform angle calibration on the given sensor (there must be an [angle chip_name] config section that has specified a stepper parameter). IMPORTANT - this tool will command the stepper motor to move without checking the normal kinematic boundary limits. Ideally the motor should be disconnected from any printer carriage before performing calibration. If the stepper can not be disconnected from the printer, make sure the carriage is near the center of its rail before starting calibration. (The stepper motor may move forwards or backwards two full rotations during this test.) After completing this test use the SAVE_CONFIG command to save the calibration data to the config file. In order to use this tool the Python \"numpy\" package must be installed (see the measuring resonance document for more information). ANGLE_CHIP_CALIBRATE \u00b6 ANGLE_CHIP_CALIBRATE CHIP=<chip_name> : Perform internal sensor calibration, if implemented (MT6826S/MT6835). MT68XX : The motor should be disconnected from any printer carriage before performing calibration. After calibration, the sensor should be reset by disconnecting the power. ANGLE_DEBUG_READ \u00b6 ANGLE_DEBUG_READ CHIP=<config_name> REG=<register> : Queries sensor register \"register\" (e.g. 44 or 0x2C). Can be useful for debugging purposes. This is only available for tle5012b chips. ANGLE_DEBUG_WRITE \u00b6 ANGLE_DEBUG_WRITE CHIP=<config_name> REG=<register> VAL=<value> : Writes raw \"value\" into register \"register\". Both \"value\" and \"register\" can be a decimal or a hexadecimal integer. Use with care, and refer to sensor data sheet for the reference. This is only available for tle5012b chips. [axis_twist_compensation] \u00b6 The following commands are available when the axis_twist_compensation config section is enabled. AXIS_TWIST_COMPENSATION_CALIBRATE \u00b6 AXIS_TWIST_COMPENSATION_CALIBRATE [AXIS=<X|Y>] [SAMPLE_COUNT=<value>] Calibrates axis twist compensation by specifying the target axis or enabling automatic calibration. AXIS: Define the axis ( X or Y ) for which the twist compensation will be calibrated. If not specified, the axis defaults to 'X' . [bed_mesh] \u00b6 The following commands are available when the bed_mesh config section is enabled (also see the bed mesh guide ). BED_MESH_CALIBRATE \u00b6 BED_MESH_CALIBRATE [PROFILE=<name>] [METHOD=manual] [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>] [<mesh_parameter>=<value>] [ADAPTIVE=1] [ADAPTIVE_MARGIN=<value>] : This command probes the bed using generated points specified by the parameters in the config. After probing, a mesh is generated and z-movement is adjusted according to the mesh. The mesh is immediately active after successful completion of BED_MESH_CALIBRATE . The mesh will be saved into a profile specified by the PROFILE parameter, or default if unspecified. If ADAPTIVE=1 is specified then the profile name will begin with adaptive- and should not be saved for reuse. See the PROBE command for details on the optional probe parameters. If METHOD=manual is specified then the manual probing tool is activated - see the MANUAL_PROBE command above for details on the additional commands available while this tool is active. The optional HORIZONTAL_MOVE_Z value overrides the horizontal_move_z option specified in the config file. If ADAPTIVE=1 is specified then the objects defined by the Gcode file being printed will be used to define the probed area. The optional ADAPTIVE_MARGIN value overrides the adaptive_margin option specified in the config file. BED_MESH_OUTPUT \u00b6 BED_MESH_OUTPUT PGP=[<0:1>] : This command outputs the current probed z values and current mesh values to the terminal. If PGP=1 is specified the X, Y coordinates generated by bed_mesh, along with their associated indices, will be output to the terminal. BED_MESH_MAP \u00b6 BED_MESH_MAP : Like to BED_MESH_OUTPUT, this command prints the current state of the mesh to the terminal. Instead of printing the values in a human readable format, the state is serialized in json format. This allows octoprint plugins to easily capture the data and generate height maps approximating the bed's surface. BED_MESH_CLEAR \u00b6 BED_MESH_CLEAR : This command clears the mesh and removes all z adjustment. It is recommended to put this in your end-gcode. BED_MESH_PROFILE \u00b6 BED_MESH_PROFILE LOAD=<name> SAVE=<name> REMOVE=<name> : This command provides profile management for mesh state. LOAD will restore the mesh state from the profile matching the supplied name. SAVE will save the current mesh state to a profile matching the supplied name. Remove will delete the profile matching the supplied name from persistent memory. Note that after SAVE or REMOVE operations have been run the SAVE_CONFIG gcode must be run to make the changes to persistent memory permanent. BED_MESH_OFFSET \u00b6 BED_MESH_OFFSET [X=<value>] [Y=<value>] [ZFADE=<value] : Applies X, Y, and/or ZFADE offsets to the mesh lookup. This is useful for printers with independent extruders, as an offset is necessary to produce correct Z adjustment after a tool change. Note that a ZFADE offset does not apply additional z-adjustment directly, it is used to correct the fade calculation when a gcode offset has been applied to the Z axis. [bed_screws] \u00b6 The following commands are available when the bed_screws config section is enabled (also see the manual level guide ). BED_SCREWS_ADJUST \u00b6 BED_SCREWS_ADJUST : This command will invoke the bed screws adjustment tool. It will command the nozzle to different locations (as defined in the config file) and allow one to make adjustments to the bed screws so that the bed is a constant distance from the nozzle. [bed_tilt] \u00b6 The following commands are available when the bed_tilt config section is enabled. BED_TILT_CALIBRATE \u00b6 BED_TILT_CALIBRATE [METHOD=manual] [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>] : This command will probe the points specified in the config and then recommend updated x and y tilt adjustments. See the PROBE command for details on the optional probe parameters. If METHOD=manual is specified then the manual probing tool is activated - see the MANUAL_PROBE command above for details on the additional commands available while this tool is active. The optional HORIZONTAL_MOVE_Z value overrides the horizontal_move_z option specified in the config file. [bltouch] \u00b6 The following command is available when a bltouch config section is enabled (also see the BL-Touch guide ). BLTOUCH_DEBUG \u00b6 BLTOUCH_DEBUG COMMAND=<command> : This sends a command to the BLTouch. It may be useful for debugging. Available commands are: pin_down , touch_mode , pin_up , self_test , reset . A BL-Touch V3.0 or V3.1 may also support set_5V_output_mode , set_OD_output_mode , output_mode_store commands. BLTOUCH_STORE \u00b6 BLTOUCH_STORE MODE=<output_mode> : This stores an output mode in the EEPROM of a BLTouch V3.1 Available output_modes are: 5V , OD [configfile] \u00b6 The configfile module is automatically loaded. SAVE_CONFIG \u00b6 SAVE_CONFIG : This command will overwrite the main printer config file and restart the host software. This command is used in conjunction with other calibration commands to store the results of calibration tests. [delayed_gcode] \u00b6 The following command is enabled if a delayed_gcode config section has been enabled (also see the template guide ). UPDATE_DELAYED_GCODE \u00b6 UPDATE_DELAYED_GCODE [ID=<name>] [DURATION=<seconds>] : Updates the delay duration for the identified [delayed_gcode] and starts the timer for gcode execution. A value of 0 will cancel a pending delayed gcode from executing. [delta_calibrate] \u00b6 The following commands are available when the delta_calibrate config section is enabled (also see the delta calibrate guide ). DELTA_CALIBRATE \u00b6 DELTA_CALIBRATE [METHOD=manual] [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>] : This command will probe seven points on the bed and recommend updated endstop positions, tower angles, and radius. See the PROBE command for details on the optional probe parameters. If METHOD=manual is specified then the manual probing tool is activated - see the MANUAL_PROBE command above for details on the additional commands available while this tool is active. The optional HORIZONTAL_MOVE_Z value overrides the horizontal_move_z option specified in the config file. DELTA_ANALYZE \u00b6 DELTA_ANALYZE : This command is used during enhanced delta calibration. See Delta Calibrate for details. [display] \u00b6 The following command is available when a display config section is enabled. SET_DISPLAY_GROUP \u00b6 SET_DISPLAY_GROUP [DISPLAY=<display>] GROUP=<group> : Set the active display group of an lcd display. This allows to define multiple display data groups in the config, e.g. [display_data <group> <elementname>] and switch between them using this extended gcode command. If DISPLAY is not specified it defaults to \"display\" (the primary display). [display_status] \u00b6 The display_status module is automatically loaded if a display config section is enabled. It provides the following standard G-Code commands: Display Message: M117 <message> Set build percentage: M73 P<percent> Also provided is the following extended G-Code command: SET_DISPLAY_TEXT MSG=<message> : Performs the equivalent of M117, setting the supplied MSG as the current display message. If MSG is omitted the display will be cleared. [dual_carriage] \u00b6 The following command is available when the dual_carriage config section is enabled. SET_DUAL_CARRIAGE \u00b6 SET_DUAL_CARRIAGE CARRIAGE=<carriage> [MODE=[PRIMARY|COPY|MIRROR]] : This command will change the mode of the specified carriage. If no MODE is provided it defaults to PRIMARY . <carriage> must reference a defined primary or dual carriage for generic_cartesian kinematics or be 0 (for primary carriage) or 1 (for dual carriage) for all other kinematics supporting IDEX. Setting the mode to PRIMARY deactivates the other carriage and makes the specified carriage execute subsequent G-Code commands as-is. COPY and MIRROR modes are supported only for dual carriages. When set to either of these modes, dual carriage will then track the subsequent moves of its primary carriage and either copy relative movements of it (in COPY mode) or execute them in the opposite (mirror) direction (in MIRROR mode). SAVE_DUAL_CARRIAGE_STATE \u00b6 SAVE_DUAL_CARRIAGE_STATE [NAME=<state_name>] : Save the current positions of the dual carriages and their modes. Saving and restoring DUAL_CARRIAGE state can be useful in scripts and macros, as well as in homing routine overrides. If NAME is provided it allows one to name the saved state to the given string. If NAME is not provided it defaults to \"default\". RESTORE_DUAL_CARRIAGE_STATE \u00b6 RESTORE_DUAL_CARRIAGE_STATE [NAME=<state_name>] [MOVE=[0|1] [MOVE_SPEED=<speed>]] : Restore the previously saved positions of the dual carriages and their modes, unless \"MOVE=0\" is specified, in which case only the saved modes will be restored, but not the positions of the carriages. If positions are being restored and \"MOVE_SPEED\" is specified, then the toolhead moves will be performed with the given speed (in mm/s); otherwise the toolhead move will use the rail homing speed. Note that the carriages restore their positions only over their own axis, which may be necessary to correctly restore COPY and MIRROR mode of the dual carriage. [endstop_phase] \u00b6 The following commands are available when an endstop_phase config section is enabled (also see the endstop phase guide ). ENDSTOP_PHASE_CALIBRATE \u00b6 ENDSTOP_PHASE_CALIBRATE [STEPPER=<config_name>] : If no STEPPER parameter is provided then this command will reports statistics on endstop stepper phases during past homing operations. When a STEPPER parameter is provided it arranges for the given endstop phase setting to be written to the config file (in conjunction with the SAVE_CONFIG command). [exclude_object] \u00b6 The following commands are available when an exclude_object config section is enabled (also see the exclude object guide ): EXCLUDE_OBJECT \u00b6 EXCLUDE_OBJECT [NAME=object_name] [CURRENT=1] [RESET=1] : With no parameters, this will return a list of all currently excluded objects. When the NAME parameter is given, the named object will be excluded from printing. When the CURRENT parameter is given, the current object will be excluded from printing. When the RESET parameter is given, the list of excluded objects will be cleared. Additionally including NAME will only reset the named object. This can cause print failures, if layers were already skipped. EXCLUDE_OBJECT_DEFINE \u00b6 EXCLUDE_OBJECT_DEFINE [NAME=object_name [CENTER=X,Y] [POLYGON=[[x,y],...]] [RESET=1] [JSON=1] : Provides a summary of an object in the file. With no parameters provided, this will list the defined objects known to Klipper. Returns a list of strings, unless the JSON parameter is given, when it will return object details in json format. When the NAME parameter is included, this defines an object to be excluded. NAME : This parameter is required. It is the identifier used by other commands in this module. CENTER : An X,Y coordinate for the object. POLYGON : An array of X,Y coordinates that provide an outline for the object. When the RESET parameter is provided, all defined objects will be cleared, and the [exclude_object] module will be reset. EXCLUDE_OBJECT_START \u00b6 EXCLUDE_OBJECT_START NAME=object_name : This command takes a NAME parameter and denotes the start of the gcode for an object on the current layer. EXCLUDE_OBJECT_END \u00b6 EXCLUDE_OBJECT_END [NAME=object_name] : Denotes the end of the object's gcode for the layer. It is paired with EXCLUDE_OBJECT_START . A NAME parameter is optional, and will only warn when the provided name does not match the current object. [extruder] \u00b6 The following commands are available if an extruder config section is enabled: ACTIVATE_EXTRUDER \u00b6 ACTIVATE_EXTRUDER EXTRUDER=<config_name> : In a printer with multiple extruder config sections, this command changes the active hotend. SET_PRESSURE_ADVANCE \u00b6 SET_PRESSURE_ADVANCE [EXTRUDER=<config_name>] [ADVANCE=<pressure_advance>] [SMOOTH_TIME=<pressure_advance_smooth_time>] : Set pressure advance parameters of an extruder stepper (as defined in an extruder or extruder_stepper config section). If EXTRUDER is not specified, it defaults to the stepper defined in the active hotend. SET_EXTRUDER_ROTATION_DISTANCE \u00b6 SET_EXTRUDER_ROTATION_DISTANCE EXTRUDER=<config_name> [DISTANCE=<distance>] : Set a new value for the provided extruder stepper's \"rotation distance\" (as defined in an extruder or extruder_stepper config section). If the rotation distance is a negative number then the stepper motion will be inverted (relative to the stepper direction specified in the config file). Changed settings are not retained on Klipper reset. Use with caution as small changes can result in excessive pressure between extruder and hotend. Do proper calibration with filament before use. If 'DISTANCE' value is not provided then this command will return the current rotation distance. SYNC_EXTRUDER_MOTION \u00b6 SYNC_EXTRUDER_MOTION EXTRUDER=<name> MOTION_QUEUE=<name> : This command will cause the stepper specified by EXTRUDER (as defined in an extruder or extruder_stepper config section) to become synchronized to the movement of an extruder specified by MOTION_QUEUE (as defined in an extruder config section). If MOTION_QUEUE is an empty string then the stepper will be desynchronized from all extruder movement. [fan_generic] \u00b6 The following command is available when a fan_generic config section is enabled. SET_FAN_SPEED \u00b6 SET_FAN_SPEED FAN=config_name SPEED=<speed> This command sets the speed of a fan. \"speed\" must be between 0.0 and 1.0. SET_FAN_SPEED PIN=config_name TEMPLATE=<template_name> [<param_x>=<literal>] : If TEMPLATE is specified then it assigns a display_template to the given fan. For example, if one defined a [display_template my_fan_template] config section then one could assign TEMPLATE=my_fan_template here. The display_template should produce a string containing a floating point number with the desired value. The template will be continuously evaluated and the fan will be automatically set to the resulting speed. One may set display_template parameters to use during template evaluation (parameters will be parsed as Python literals). If TEMPLATE is an empty string then this command will clear any previous template assigned to the pin (one can then use SET_FAN_SPEED commands to manage the values directly). [filament_switch_sensor] \u00b6 The following command is available when a filament_switch_sensor or filament_motion_sensor config section is enabled. QUERY_FILAMENT_SENSOR \u00b6 QUERY_FILAMENT_SENSOR SENSOR=<sensor_name> : Queries the current status of the filament sensor. The data displayed on the terminal will depend on the sensor type defined in the configuration. SET_FILAMENT_SENSOR \u00b6 SET_FILAMENT_SENSOR SENSOR=<sensor_name> ENABLE=[0|1] : Sets the filament sensor on/off. If ENABLE is set to 0, the filament sensor will be disabled, if set to 1 it is enabled. [firmware_retraction] \u00b6 The following standard G-Code commands are available when the firmware_retraction config section is enabled. These commands allow you to utilize the firmware retraction feature available in many slicers, to reduce stringing during non-extrusion moves from one part of the print to another. Appropriately configuring pressure advance reduces the length of retraction required. G10 : Retracts the extruder using the currently configured parameters. G11 : Unretracts the extruder using the currently configured parameters. The following additional commands are also available. SET_RETRACTION \u00b6 SET_RETRACTION [RETRACT_LENGTH=<mm>] [RETRACT_SPEED=<mm/s>] [UNRETRACT_EXTRA_LENGTH=<mm>] [UNRETRACT_SPEED=<mm/s>] : Adjust the parameters used by firmware retraction. RETRACT_LENGTH determines the length of filament to retract and unretract. The speed of retraction is adjusted via RETRACT_SPEED, and is typically set relatively high. The speed of unretraction is adjusted via UNRETRACT_SPEED, and is not particularly critical, although often lower than RETRACT_SPEED. In some cases it is useful to add a small amount of additional length on unretraction, and this is set via UNRETRACT_EXTRA_LENGTH. SET_RETRACTION is commonly set as part of slicer per-filament configuration, as different filaments require different parameter settings. GET_RETRACTION \u00b6 GET_RETRACTION : Queries the current parameters used by firmware retraction and displays them on the terminal. [force_move] \u00b6 The force_move module is automatically loaded, however some commands require setting enable_force_move in the printer config . STEPPER_BUZZ \u00b6 STEPPER_BUZZ STEPPER=<config_name> : Move the given stepper forward one mm and then backward one mm, repeated 10 times. This is a diagnostic tool to help verify stepper connectivity. FORCE_MOVE \u00b6 FORCE_MOVE STEPPER=<config_name> DISTANCE=<value> VELOCITY=<value> [ACCEL=<value>] : This command will forcibly move the given stepper the given distance (in mm) at the given constant velocity (in mm/s). If ACCEL is specified and is greater than zero, then the given acceleration (in mm/s^2) will be used; otherwise no acceleration is performed. No boundary checks are performed; no kinematic updates are made; other parallel steppers on an axis will not be moved. Use caution as an incorrect command could cause damage! Using this command will almost certainly place the low-level kinematics in an incorrect state; issue a G28 afterwards to reset the kinematics. This command is intended for low-level diagnostics and debugging. SET_KINEMATIC_POSITION \u00b6 SET_KINEMATIC_POSITION [X=<value>] [Y=<value>] [Z=<value>] [SET_HOMED=<[X][Y][Z]>] [CLEAR_HOMED=<[X][Y][Z]>] : Force the low-level kinematic code to believe the toolhead is at the given cartesian position and set/clear homed status. This is a diagnostic and debugging command; use SET_GCODE_OFFSET and/or G92 for regular axis transformations. Setting an incorrect or invalid position may lead to internal software errors. The X , Y , and Z parameters are used to alter the low-level kinematic position tracking. If any of these parameters are not set then the position is not changed - for example SET_KINEMATIC_POSITION Z=10 would set all axes as homed, set the internal Z position to 10, and leave the X and Y positions unchanged. Changing the internal position tracking is not dependent on the internal homing state - one may alter the position for both homed and not homed axes, and similarly one may set or clear the homing state of an axis without altering its internal position. The SET_HOMED parameter defaults to XYZ which instructs the kinematics to consider all axes as homed. A bare SET_KINEMATIC_POSITION command will result in all axes being considered homed (and not change its current position). If it is not desired to change the state of homed axes then assign SET_HOMED to an empty string - for example: SET_KINEMATIC_POSITION SET_HOMED= X=10 . It is also possible to request an individual axis be considered homed (eg, SET_HOMED=X ), but note that non-cartesian style kinematics (such as delta kinematics) may not support setting an individual axis as homed. The CLEAR_HOMED parameter instructs the kinematics to consider the given axes as not homed. For example, CLEAR_HOMED=XYZ would request all axes to be considered not homed (and thus require homing prior to movement on those axes). The default is SET_HOMED=XYZ even if CLEAR_HOMED is present, so the command SET_KINEMATIC_POSITION CLEAR_HOMED=Z will set X and Y as homed and clear the homing state for Z. Use SET_KINEMATIC_POSITION SET_HOMED= CLEAR_HOMED=Z if the goal is to clear only the Z homing state. If an axis is specified in neither SET_HOMED nor CLEAR_HOMED then its homing state is not changed and if it is specified in both then CLEAR_HOMED has precedence. It is possible to request clearing of an individual axis, but on non-cartesian style kinematics (such as delta kinematics) doing so may result in clearing the homing state of additional axes. Note the CLEAR parameter is currently an alias for the CLEAR_HOMED parameter, but this alias will be removed in the future. [gcode] \u00b6 The gcode module is automatically loaded. RESTART \u00b6 RESTART : This will cause the host software to reload its config and perform an internal reset. This command will not clear error state from the micro-controller (see FIRMWARE_RESTART) nor will it load new software (see the FAQ ). FIRMWARE_RESTART \u00b6 FIRMWARE_RESTART : This is similar to a RESTART command, but it also clears any error state from the micro-controller. STATUS \u00b6 STATUS : Report the Klipper host software status. HELP \u00b6 HELP : Report the list of available extended G-Code commands. [gcode_arcs] \u00b6 The following standard G-Code commands are available if a gcode_arcs config section is enabled: Arc Move Clockwise (G2), Arc Move Counter-clockwise (G3): G2|G3 [X<pos>] [Y<pos>] [Z<pos>] [E<pos>] [F<speed>] I<value> J<value>|I<value> K<value>|J<value> K<value> Arc Plane Select: G17 (XY plane), G18 (XZ plane), G19 (YZ plane) [gcode_macro] \u00b6 The following command is available when a gcode_macro config section is enabled (also see the command templates guide ). SET_GCODE_VARIABLE \u00b6 SET_GCODE_VARIABLE MACRO=<macro_name> VARIABLE=<name> VALUE=<value> : This command allows one to change the value of a gcode_macro variable at run-time. The provided VALUE is parsed as a Python literal. [gcode_move] \u00b6 The gcode_move module is automatically loaded. GET_POSITION \u00b6 GET_POSITION : Return information on the current location of the toolhead. See the developer documentation of GET_POSITION output for more information. SET_GCODE_OFFSET \u00b6 SET_GCODE_OFFSET [X=<pos>|X_ADJUST=<adjust>] [Y=<pos>|Y_ADJUST=<adjust>] [Z=<pos>|Z_ADJUST=<adjust>] [MOVE=1 [MOVE_SPEED=<speed>]] : Set a positional offset to apply to future G-Code commands. This is commonly used to virtually change the Z bed offset or to set nozzle XY offsets when switching extruders. For example, if \"SET_GCODE_OFFSET Z=0.2\" is sent, then future G-Code moves will have 0.2mm added to their Z height. If the X_ADJUST style parameters are used, then the adjustment will be added to any existing offset (eg, \"SET_GCODE_OFFSET Z=-0.2\" followed by \"SET_GCODE_OFFSET Z_ADJUST=0.3\" would result in a total Z offset of 0.1). If \"MOVE=1\" is specified then a toolhead move will be issued to apply the given offset (otherwise the offset will take effect on the next absolute G-Code move that specifies the given axis). If \"MOVE_SPEED\" is specified then the toolhead move will be performed with the given speed (in mm/s); otherwise the toolhead move will use the last specified G-Code speed. SAVE_GCODE_STATE \u00b6 SAVE_GCODE_STATE [NAME=<state_name>] : Save the current g-code coordinate parsing state. Saving and restoring the g-code state is useful in scripts and macros. This command saves the current g-code absolute coordinate mode (G90/G91), absolute extrude mode (M82/M83), origin (G92), offset (SET_GCODE_OFFSET), speed override (M220), extruder override (M221), move speed, current XYZ position, and relative extruder \"E\" position. If NAME is provided it allows one to name the saved state to the given string. If NAME is not provided it defaults to \"default\". RESTORE_GCODE_STATE \u00b6 RESTORE_GCODE_STATE [NAME=<state_name>] [MOVE=1 [MOVE_SPEED=<speed>]] : Restore a state previously saved via SAVE_GCODE_STATE. If \"MOVE=1\" is specified then a toolhead move will be issued to move back to the previous XYZ position. If \"MOVE_SPEED\" is specified then the toolhead move will be performed with the given speed (in mm/s); otherwise the toolhead move will use the restored g-code speed. [generic_cartesian] \u00b6 The commands in this section become automatically available when kinematics: generic_cartesian is specified as the printer kinematics. SET_STEPPER_CARRIAGES \u00b6 SET_STEPPER_CARRIAGES STEPPER=<stepper_name> CARRIAGES=<carriages> [DISABLE_CHECKS=[0|1]] : Set or update the stepper carriages. <stepper_name> must reference an existing stepper defined in printer.cfg , and <carriages> describes the carriages the stepper moves. See Generic Cartesian Kinematics for a more detailed overview of the carriages parameter in the stepper configuration section. Note that it is only possible to change the coefficients or signs of the carriages with this command, but a user cannot add or remove the carriages that the stepper controls. SET_STEPPER_CARRIAGES is an advanced tool, and the user is advised to exercise an extreme caution using it, since specifying incorrect configuration may physically damage the printer. Note that SET_STEPPER_CARRIAGES performs certain internal validations of the new printer kinematics after the change. Keep in mind that if it detects an issue, it may leave printer kinematics in an invalid state. This means that if SET_STEPPER_CARRIAGES reports an error, it is unsafe to issue other GCode commands, and the user must inspect the error message and either fix the problem, or manually restore the previous stepper(s) configuration. Since SET_STEPPER_CARRIAGES can update a configuration of a single stepper at a time, some sequences of changes can lead to invalid intermediate kinematic configurations, even if the final configuration is valid. In such cases a user can pass DISABLE_CHECKS=1 parameters to all but the last command to disable intermediate checks. For example, if stepper a and stepper b initially have x-y and x+y carriages correspondingly, then the following sequence of commands will let a user effectively swap the carriage controls: SET_STEPPER_CARRIAGES STEPPER=a CARRIAGES=x+y DISABLE_CHECKS=1 and SET_STEPPER_CARRIAGES STEPPER=b CARRIAGES=x-y , while still validating the final kinematics state. [hall_filament_width_sensor] \u00b6 The following commands are available when the tsl1401cl filament width sensor config section or hall filament width sensor config section is enabled (also see TSLl401CL Filament Width Sensor and Hall Filament Width Sensor ): QUERY_FILAMENT_WIDTH \u00b6 QUERY_FILAMENT_WIDTH : Return the current measured filament width. RESET_FILAMENT_WIDTH_SENSOR \u00b6 RESET_FILAMENT_WIDTH_SENSOR : Clear all sensor readings. Helpful after filament change. DISABLE_FILAMENT_WIDTH_SENSOR \u00b6 DISABLE_FILAMENT_WIDTH_SENSOR : Turn off the filament width sensor and stop using it for flow control. ENABLE_FILAMENT_WIDTH_SENSOR \u00b6 ENABLE_FILAMENT_WIDTH_SENSOR : Turn on the filament width sensor and start using it for flow control. QUERY_RAW_FILAMENT_WIDTH \u00b6 QUERY_RAW_FILAMENT_WIDTH : Return the current ADC channel readings and RAW sensor value for calibration points. ENABLE_FILAMENT_WIDTH_LOG \u00b6 ENABLE_FILAMENT_WIDTH_LOG : Turn on diameter logging. DISABLE_FILAMENT_WIDTH_LOG \u00b6 DISABLE_FILAMENT_WIDTH_LOG : Turn off diameter logging. [heaters] \u00b6 The heaters module is automatically loaded if a heater is defined in the config file. TURN_OFF_HEATERS \u00b6 TURN_OFF_HEATERS : Turn off all heaters. TEMPERATURE_WAIT \u00b6 TEMPERATURE_WAIT SENSOR=<config_name> [MINIMUM=<target>] [MAXIMUM=<target>] : Wait until the given temperature sensor is at or above the supplied MINIMUM and/or at or below the supplied MAXIMUM. SET_HEATER_TEMPERATURE \u00b6 SET_HEATER_TEMPERATURE HEATER=<heater_name> [TARGET=<target_temperature>] : Sets the target temperature for a heater. If a target temperature is not supplied, the target is 0. [idle_timeout] \u00b6 The idle_timeout module is automatically loaded. SET_IDLE_TIMEOUT \u00b6 SET_IDLE_TIMEOUT [TIMEOUT=<timeout>] : Allows the user to set the idle timeout (in seconds). [input_shaper] \u00b6 The following command is enabled if an input_shaper config section has been enabled (also see the resonance compensation guide ). SET_INPUT_SHAPER \u00b6 SET_INPUT_SHAPER [SHAPER_FREQ_X=<shaper_freq_x>] [SHAPER_FREQ_Y=<shaper_freq_y>] [DAMPING_RATIO_X=<damping_ratio_x>] [DAMPING_RATIO_Y=<damping_ratio_y>] [SHAPER_TYPE=<shaper>] [SHAPER_TYPE_X=<shaper_type_x>] [SHAPER_TYPE_Y=<shaper_type_y>] : Modify input shaper parameters. Note that SHAPER_TYPE parameter resets input shaper for both X and Y axes even if different shaper types have been configured in [input_shaper] section. SHAPER_TYPE cannot be used together with either of SHAPER_TYPE_X and SHAPER_TYPE_Y parameters. See config reference for more details on each of these parameters. [led] \u00b6 The following command is available when any of the led config sections are enabled. SET_LED \u00b6 SET_LED LED=<config_name> RED=<value> GREEN=<value> BLUE=<value> WHITE=<value> [INDEX=<index>] [TRANSMIT=0] [SYNC=1] : This sets the LED output. Each color <value> must be between 0.0 and 1.0. The WHITE option is only valid on RGBW LEDs. If the LED supports multiple chips in a daisy-chain then one may specify INDEX to alter the color of just the given chip (1 for the first chip, 2 for the second, etc.). If INDEX is not provided then all LEDs in the daisy-chain will be set to the provided color. If TRANSMIT=0 is specified then the color change will only be made on the next SET_LED command that does not specify TRANSMIT=0; this may be useful in combination with the INDEX parameter to batch multiple updates in a daisy-chain. By default, the SET_LED command will sync it's changes with other ongoing gcode commands. This can lead to undesirable behavior if LEDs are being set while the printer is not printing as it will reset the idle timeout. If careful timing is not needed, the optional SYNC=0 parameter can be specified to apply the changes without resetting the idle timeout. SET_LED_TEMPLATE \u00b6 SET_LED_TEMPLATE LED=<led_name> TEMPLATE=<template_name> [<param_x>=<literal>] [INDEX=<index>] : Assign a display_template to a given LED . For example, if one defined a [display_template my_led_template] config section then one could assign TEMPLATE=my_led_template here. The display_template should produce a comma separated string containing four floating point numbers corresponding to red, green, blue, and white color settings. The template will be continuously evaluated and the LED will be automatically set to the resulting colors. One may set display_template parameters to use during template evaluation (parameters will be parsed as Python literals). If INDEX is not specified then all chips in the LED's daisy-chain will be set to the template, otherwise only the chip with the given index will be updated. If TEMPLATE is an empty string then this command will clear any previous template assigned to the LED (one can then use SET_LED commands to manage the LED's color settings). [load_cell] \u00b6 The following commands are enabled if a load_cell config section has been enabled. LOAD_CELL_DIAGNOSTIC \u00b6 LOAD_CELL_DIAGNOSTIC [LOAD_CELL=<config_name>] : This command collects 10 seconds of load cell data and reports statistics that can help you verify proper operation of the load cell. This command can be run on both calibrated and uncalibrated load cells. LOAD_CELL_CALIBRATE \u00b6 LOAD_CELL_CALIBRATE [LOAD_CELL=<config_name>] : Start the guided calibration utility. Calibration is a 3 step process: First you remove all load from the load cell and run the TARE command Next you apply a known load to the load cell and run the CALIBRATE GRAMS=nnn command Finally use the ACCEPT command to save the results You can cancel the calibration process at any time with ABORT . LOAD_CELL_TARE \u00b6 LOAD_CELL_TARE [LOAD_CELL=<config_name>] : This works just like the tare button on digital scale. It sets the current raw reading of the load cell to be the zero point reference value. The response is the percentage of the sensors range that was read and the raw value in counts. If the load cell is calibrated a force in grams is also reported. LOAD_CELL_READ load_cell=\"name\" \u00b6 LOAD_CELL_READ [LOAD_CELL=<config_name>] : This command takes a reading from the load cell. The response is the percentage of the sensors range that was read and the raw value in counts. If the load cell is calibrated a force in grams is also reported. [load_cell_probe] \u00b6 The following commands are enabled if a load_cell config section has been enabled. LOAD_CELL_TEST_TAP \u00b6 LOAD_CELL_TEST_TAP [TAPS=<taps>] [TIMEOUT=<timeout>] : Run a testing routine that reports taps on the load cell. The toolhead will not move but the load cell probe will sense taps just as if it was probing. This can be used as a sanity check to make sure that the probe works. This tool replaces QUERY_ENDSTOPS and QUERY_PROBE for load cell probes. TAPS : the number of taps the tool expects TIMEOOUT : the time, in seconds, that the tool waits for each tab before aborting. Load Cell Command Extensions \u00b6 Commands that perform probes, such as PROBE , PROBE_ACCURACY , BED_MESH_CALIBRATE etc. will accept additional parameters if a [load_cell_probe] is defined. The parameters override the corresponding settings from the [load_cell_probe] configuration: FORCE_SAFETY_LIMIT=<grams> TRIGGER_FORCE=<grams> DRIFT_FILTER_CUTOFF_FREQUENCY=<frequency_hz> DRIFT_FILTER_DELAY=<1|2> BUZZ_FILTER_CUTOFF_FREQUENCY=<frequency_hz> BUZZ_FILTER_DELAY=<1|2> NOTCH_FILTER_FREQUENCIES=<list of frequency_hz> NOTCH_FILTER_QUALITY=<quality> TARE_TIME=<seconds> [manual_probe] \u00b6 The manual_probe module is automatically loaded. MANUAL_PROBE \u00b6 MANUAL_PROBE [SPEED=<speed>] : Run a helper script useful for measuring the height of the nozzle at a given location. If SPEED is specified, it sets the speed of TESTZ commands (the default is 5mm/s). During a manual probe, the following additional commands are available: ACCEPT : This command accepts the current Z position and concludes the manual probing tool. ABORT : This command terminates the manual probing tool. TESTZ Z=<value> : This command moves the nozzle up or down by the amount specified in \"value\". For example, TESTZ Z=-.1 would move the nozzle down .1mm while TESTZ Z=.1 would move the nozzle up .1mm. The value may also be + , - , ++ , or -- to move the nozzle up or down an amount relative to previous attempts. Z_ENDSTOP_CALIBRATE \u00b6 Z_ENDSTOP_CALIBRATE [SPEED=<speed>] : Run a helper script useful for calibrating a Z position_endstop config setting. See the MANUAL_PROBE command for details on the parameters and the additional commands available while the tool is active. Z_OFFSET_APPLY_ENDSTOP \u00b6 Z_OFFSET_APPLY_ENDSTOP : Take the current Z Gcode offset (aka, babystepping), and subtract it from the stepper_z endstop_position. This acts to take a frequently used babystepping value, and \"make it permanent\". Requires a SAVE_CONFIG to take effect. [manual_stepper] \u00b6 The following command is available when a manual_stepper config section is enabled. MANUAL_STEPPER \u00b6 MANUAL_STEPPER STEPPER=config_name [ENABLE=[0|1]] [SET_POSITION=<pos>] [SPEED=<speed>] [ACCEL=<accel>] [MOVE=<pos> [STOP_ON_ENDSTOP=[1|2|-1|-2]] [SYNC=0]] : This command will alter the state of the stepper. Use the ENABLE parameter to enable/disable the stepper. Use the SET_POSITION parameter to force the stepper to think it is at the given position. Use the MOVE parameter to request a movement to the given position. If SPEED and/or ACCEL is specified then the given values will be used instead of the defaults specified in the config file. If an ACCEL of zero is specified then no acceleration will be performed. If STOP_ON_ENDSTOP=1 is specified then the move will end early should the endstop report as triggered (use STOP_ON_ENDSTOP=2 to complete the move without error even if the endstop does not trigger, use -1 or -2 to stop when the endstop reports not triggered). Normally future G-Code commands will be scheduled to run after the stepper move completes, however if a manual stepper move uses SYNC=0 then future G-Code movement commands may run in parallel with the stepper movement. MANUAL_STEPPER STEPPER=config_name GCODE_AXIS=[A-Z] [LIMIT_VELOCITY=<velocity>] [LIMIT_ACCEL=<accel>] [INSTANTANEOUS_CORNER_VELOCITY=<velocity>] : If the GCODE_AXIS parameter is specified then it configures the stepper motor as an extra axis on G1 move commands. For example, if one were to issue a MANUAL_STEPPER ... GCODE_AXIS=R command then one could issue commands like G1 X10 Y20 R30 to move the stepper motor. The resulting moves will occur synchronously with the associated toolhead xyz movements. If the motor is associated with a GCODE_AXIS then one may no longer issue movements using the above MANUAL_STEPPER command - one may unregister the stepper with a MANUAL_STEPPER ... GCODE_AXIS= command to resume manual control of the motor. The LIMIT_VELOCITY and LIMIT_ACCEL parameters allow one to reduce the speed of G1 moves if those moves would result in a velocity or acceleration above the specified limits. The INSTANTANEOUS_CORNER_VELOCITY specifies the maximum instantaneous velocity change (in mm/s) of the motor during the junction of two moves (the default is 1mm/s). [mcp4018] \u00b6 The following command is available when a mcp4018 config section is enabled. SET_DIGIPOT \u00b6 SET_DIGIPOT DIGIPOT=config_name WIPER=<value> : This command will change the current value of the digipot. This value should typically be between 0.0 and 1.0, unless a 'scale' is defined in the config. When 'scale' is defined, then this value should be between 0.0 and 'scale'. [output_pin] \u00b6 The following command is available when an output_pin config section or pwm_tool config section is enabled. SET_PIN \u00b6 SET_PIN PIN=config_name VALUE=<value> : Set the pin to the given output VALUE . VALUE should be 0 or 1 for \"digital\" output pins. For PWM pins, set to a value between 0.0 and 1.0, or between 0.0 and scale if a scale is configured in the output_pin config section. SET_PIN PIN=config_name TEMPLATE=<template_name> [<param_x>=<literal>] : If TEMPLATE is specified then it assigns a display_template to the given pin. For example, if one defined a [display_template my_pin_template] config section then one could assign TEMPLATE=my_pin_template here. The display_template should produce a string containing a floating point number with the desired value. The template will be continuously evaluated and the pin will be automatically set to the resulting value. One may set display_template parameters to use during template evaluation (parameters will be parsed as Python literals). If TEMPLATE is an empty string then this command will clear any previous template assigned to the pin (one can then use SET_PIN commands to manage the values directly). [palette2] \u00b6 The following commands are available when the palette2 config section is enabled. Palette prints work by embedding special OCodes (Omega Codes) in the GCode file: O1 ... O32 : These codes are read from the GCode stream and processed by this module and passed to the Palette 2 device. The following additional commands are also available. PALETTE_CONNECT \u00b6 PALETTE_CONNECT : This command initializes the connection with the Palette 2. PALETTE_DISCONNECT \u00b6 PALETTE_DISCONNECT : This command disconnects from the Palette 2. PALETTE_CLEAR \u00b6 PALETTE_CLEAR : This command instructs the Palette 2 to clear all of the input and output paths of filament. PALETTE_CUT \u00b6 PALETTE_CUT : This command instructs the Palette 2 to cut the filament currently loaded in the splice core. PALETTE_SMART_LOAD \u00b6 PALETTE_SMART_LOAD : This command start the smart load sequence on the Palette 2. Filament is loaded automatically by extruding it the distance calibrated on the device for the printer, and instructs the Palette 2 once the loading has been completed. This command is the same as pressing Smart Load directly on the Palette 2 screen after the filament load is complete. [pause_resume] \u00b6 The following commands are available when the pause_resume config section is enabled: PAUSE \u00b6 PAUSE : Pauses the current print. The current position is captured for restoration upon resume. RESUME \u00b6 RESUME [VELOCITY=<value>] : Resumes the print from a pause, first restoring the previously captured position. The VELOCITY parameter determines the speed at which the tool should return to the original captured position. CLEAR_PAUSE \u00b6 CLEAR_PAUSE : Clears the current paused state without resuming the print. This is useful if one decides to cancel a print after a PAUSE. It is recommended to add this to your start gcode to make sure the paused state is fresh for each print. CANCEL_PRINT \u00b6 CANCEL_PRINT : Cancels the current print. [pid_calibrate] \u00b6 The pid_calibrate module is automatically loaded if a heater is defined in the config file. PID_CALIBRATE \u00b6 PID_CALIBRATE HEATER=<config_name> TARGET=<temperature> [WRITE_FILE=1] : Perform a PID calibration test. The specified heater will be enabled until the specified target temperature is reached, and then the heater will be turned off and on for several cycles. If the WRITE_FILE parameter is enabled, then the file /tmp/heattest.txt will be created with a log of all temperature samples taken during the test. [print_stats] \u00b6 The print_stats module is automatically loaded. SET_PRINT_STATS_INFO \u00b6 SET_PRINT_STATS_INFO [TOTAL_LAYER=<total_layer_count>] [CURRENT_LAYER= <current_layer>] : Pass slicer info like layer act and total to Klipper. Add SET_PRINT_STATS_INFO [TOTAL_LAYER=<total_layer_count>] to your slicer start gcode section and SET_PRINT_STATS_INFO [CURRENT_LAYER= <current_layer>] at the layer change gcode section to pass layer information from your slicer to Klipper. [probe] \u00b6 The following commands are available when a probe config section or bltouch config section is enabled (also see the probe calibrate guide ). PROBE \u00b6 PROBE [PROBE_SPEED=<mm/s>] [LIFT_SPEED=<mm/s>] [SAMPLES=<count>] [SAMPLE_RETRACT_DIST=<mm>] [SAMPLES_TOLERANCE=<mm>] [SAMPLES_TOLERANCE_RETRIES=<count>] [SAMPLES_RESULT=median|average] : Move the nozzle downwards until the probe triggers. If any of the optional parameters are provided they override their equivalent setting in the probe config section . QUERY_PROBE \u00b6 QUERY_PROBE : Report the current status of the probe (\"triggered\" or \"open\"). PROBE_ACCURACY \u00b6 PROBE_ACCURACY [PROBE_SPEED=<mm/s>] [SAMPLES=<count>] [SAMPLE_RETRACT_DIST=<mm>] : Calculate the maximum, minimum, average, median, and standard deviation of multiple probe samples. By default, 10 SAMPLES are taken. Otherwise the optional parameters default to their equivalent setting in the probe config section. PROBE_CALIBRATE \u00b6 PROBE_CALIBRATE [SPEED=<speed>] [<probe_parameter>=<value>] : Run a helper script useful for calibrating the probe's z_offset. See the PROBE command for details on the optional probe parameters. See the MANUAL_PROBE command for details on the SPEED parameter and the additional commands available while the tool is active. Please note, the PROBE_CALIBRATE command uses the speed variable to move in XY direction as well as Z. Z_OFFSET_APPLY_PROBE \u00b6 Z_OFFSET_APPLY_PROBE : Take the current Z Gcode offset (aka, babystepping), and subtract if from the probe's z_offset. This acts to take a frequently used babystepping value, and \"make it permanent\". Requires a SAVE_CONFIG to take effect. [probe_eddy_current] \u00b6 The following commands are available when a probe_eddy_current config section is enabled. PROBE_EDDY_CURRENT_CALIBRATE \u00b6 PROBE_EDDY_CURRENT_CALIBRATE CHIP=<config_name> : This starts a tool that calibrates the sensor resonance frequencies to corresponding Z heights. The tool will take a couple of minutes to complete. After completion, use the SAVE_CONFIG command to store the results in the printer.cfg file. LDC_CALIBRATE_DRIVE_CURRENT \u00b6 LDC_CALIBRATE_DRIVE_CURRENT CHIP=<config_name> This tool will calibrate the ldc1612 DRIVE_CURRENT0 register. Prior to using this tool, move the sensor so that it is near the center of the bed and about 20mm above the bed surface. Run this command to determine an appropriate DRIVE_CURRENT for the sensor. After running this command use the SAVE_CONFIG command to store that new setting in the printer.cfg config file. [pwm_cycle_time] \u00b6 The following command is available when a pwm_cycle_time config section is enabled. SET_PIN \u00b6 SET_PIN PIN=config_name VALUE=<value> [CYCLE_TIME=<cycle_time>] : This command works similarly to output_pin SET_PIN commands. The command here supports setting an explicit cycle time using the CYCLE_TIME parameter (specified in seconds). Note that the CYCLE_TIME parameter is not stored between SET_PIN commands (any SET_PIN command without an explicit CYCLE_TIME parameter will use the cycle_time specified in the pwm_cycle_time config section). [quad_gantry_level] \u00b6 The following commands are available when the quad_gantry_level config section is enabled. QUAD_GANTRY_LEVEL \u00b6 QUAD_GANTRY_LEVEL [RETRIES=<value>] [RETRY_TOLERANCE=<value>] [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>] : This command will probe the points specified in the config and then make independent adjustments to each Z stepper to compensate for tilt. See the PROBE command for details on the optional probe parameters. The optional RETRIES , RETRY_TOLERANCE , and HORIZONTAL_MOVE_Z values override those options specified in the config file. [query_adc] \u00b6 The query_adc module is automatically loaded. QUERY_ADC \u00b6 QUERY_ADC [NAME=<config_name>] [PULLUP=<value>] : Report the last analog value received for a configured analog pin. If NAME is not provided, the list of available adc names are reported. If PULLUP is provided (as a value in Ohms), the raw analog value along with the equivalent resistance given that pullup is reported. [query_endstops] \u00b6 The query_endstops module is automatically loaded. The following standard G-Code commands are currently available, but using them is not recommended: Get Endstop Status: M119 (Use QUERY_ENDSTOPS instead.) QUERY_ENDSTOPS \u00b6 QUERY_ENDSTOPS : Probe the axis endstops and report if they are \"triggered\" or in an \"open\" state. This command is typically used to verify that an endstop is working correctly. [resonance_tester] \u00b6 The following commands are available when a resonance_tester config section is enabled (also see the measuring resonances guide ). MEASURE_AXES_NOISE \u00b6 MEASURE_AXES_NOISE : Measures and outputs the noise for all axes of all enabled accelerometer chips. TEST_RESONANCES \u00b6 TEST_RESONANCES AXIS=<axis> [OUTPUT=<resonances,raw_data>] [NAME=<name>] [FREQ_START=<min_freq>] [FREQ_END=<max_freq>] [ACCEL_PER_HZ=<accel_per_hz>] [HZ_PER_SEC=<hz_per_sec>] [CHIPS=<chip_name>] [POINT=x,y,z] [INPUT_SHAPING=<0:1>] : Runs the resonance test in all configured probe points for the requested \"axis\" and measures the acceleration using the accelerometer chips configured for the respective axis. \"axis\" can either be X or Y, or specify an arbitrary direction as AXIS=dx,dy , where dx and dy are floating point numbers defining a direction vector (e.g. AXIS=X , AXIS=Y , or AXIS=1,-1 to define a diagonal direction). Note that AXIS=dx,dy and AXIS=-dx,-dy is equivalent. chip_name can be one or more configured accel chips, delimited with comma, for example CHIPS=\"adxl345, adxl345 rpi\" . If POINT is specified it will override the point(s) configured in [resonance_tester] . If INPUT_SHAPING=0 or not set(default), disables input shaping for the resonance testing, because it is not valid to run the resonance testing with the input shaper enabled. OUTPUT parameter is a comma-separated list of which outputs will be written. If raw_data is requested, then the raw accelerometer data is written into a file or a series of files /tmp/raw_data_<axis>_[<chip_name>_][<point>_]<name>.csv with ( <point>_ part of the name generated only if more than 1 probe point is configured or POINT is specified). If resonances is specified, the frequency response is calculated (across all probe points) and written into /tmp/resonances_<axis>_<name>.csv file. If unset, OUTPUT defaults to resonances , and NAME defaults to the current time in \"YYYYMMDD_HHMMSS\" format. SHAPER_CALIBRATE \u00b6 SHAPER_CALIBRATE [AXIS=<axis>] [NAME=<name>] [FREQ_START=<min_freq>] [FREQ_END=<max_freq>] [ACCEL_PER_HZ=<accel_per_hz>][HZ_PER_SEC=<hz_per_sec>] [CHIPS=<chip_name>] [MAX_SMOOTHING=<max_smoothing>] [INPUT_SHAPING=<0:1>] : Similarly to TEST_RESONANCES , runs the resonance test as configured, and tries to find the optimal parameters for the input shaper for the requested axis (or both X and Y axes if AXIS parameter is unset). If MAX_SMOOTHING is unset, its value is taken from [resonance_tester] section, with the default being unset. See the Max smoothing of the measuring resonances guide for more information on the use of this feature. The results of the tuning are printed to the console, and the frequency responses and the different input shapers values are written to a CSV file(s) /tmp/calibration_data_<axis>_<name>.csv . Unless specified, NAME defaults to the current time in \"YYYYMMDD_HHMMSS\" format. Note that the suggested input shaper parameters can be persisted in the config by issuing SAVE_CONFIG command, and if [input_shaper] was already enabled previously, these parameters take effect immediately. [respond] \u00b6 The following standard G-Code commands are available when the respond config section is enabled: M118 <message> : echo the message prepended with the configured default prefix (or echo: if no prefix is configured). The following additional commands are also available. RESPOND \u00b6 RESPOND MSG=\"<message>\" : echo the message prepended with the configured default prefix (or echo: if no prefix is configured). RESPOND TYPE=echo MSG=\"<message>\" : echo the message prepended with echo: . RESPOND TYPE=echo_no_space MSG=\"<message>\" : echo the message prepended with echo: without a space between prefix and message, helpful for compatibility with some octoprint plugins that expect very specific formatting. RESPOND TYPE=command MSG=\"<message>\" : echo the message prepended with // . OctoPrint can be configured to respond to these messages (e.g. RESPOND TYPE=command MSG=action:pause ). RESPOND TYPE=error MSG=\"<message>\" : echo the message prepended with !! . RESPOND PREFIX=<prefix> MSG=\"<message>\" : echo the message prepended with <prefix> . (The PREFIX parameter will take priority over the TYPE parameter) [save_variables] \u00b6 The following command is enabled if a save_variables config section has been enabled. SAVE_VARIABLE \u00b6 SAVE_VARIABLE VARIABLE=<name> VALUE=<value> : Saves the variable to disk so that it can be used across restarts. The VARIABLE must be lowercase. All stored variables are loaded into the printer.save_variables.variables dict at startup and can be used in gcode macros. The provided VALUE is parsed as a Python literal. [screws_tilt_adjust] \u00b6 The following commands are available when the screws_tilt_adjust config section is enabled (also see the manual level guide ). SCREWS_TILT_CALCULATE \u00b6 SCREWS_TILT_CALCULATE [DIRECTION=CW|CCW] [MAX_DEVIATION=<value>] [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>] : This command will invoke the bed screws adjustment tool. It will command the nozzle to different locations (as defined in the config file) probing the z height and calculate the number of knob turns to adjust the bed level. If DIRECTION is specified, the knob turns will all be in the same direction, clockwise (CW) or counterclockwise (CCW). See the PROBE command for details on the optional probe parameters. IMPORTANT: You MUST always do a G28 before using this command. If MAX_DEVIATION is specified, the command will raise a gcode error if any difference in the screw height relative to the base screw height is greater than the value provided. The optional HORIZONTAL_MOVE_Z value overrides the horizontal_move_z option specified in the config file. [sdcard_loop] \u00b6 When the sdcard_loop config section is enabled, the following extended commands are available. SDCARD_LOOP_BEGIN \u00b6 SDCARD_LOOP_BEGIN COUNT=<count> : Begin a looped section in the SD print. A count of 0 indicates that the section should be looped indefinitely. SDCARD_LOOP_END \u00b6 SDCARD_LOOP_END : End a looped section in the SD print. SDCARD_LOOP_DESIST \u00b6 SDCARD_LOOP_DESIST : Complete existing loops without further iterations. [servo] \u00b6 The following commands are available when a servo config section is enabled. SET_SERVO \u00b6 SET_SERVO SERVO=config_name [ANGLE=<degrees> | WIDTH=<seconds>] : Set the servo position to the given angle (in degrees) or pulse width (in seconds). Use WIDTH=0 to disable the servo output. [skew_correction] \u00b6 The following commands are available when the skew_correction config section is enabled (also see the Skew Correction guide). SET_SKEW \u00b6 SET_SKEW [XY=<ac_length,bd_length,ad_length>] [XZ=<ac,bd,ad>] [YZ=<ac,bd,ad>] [CLEAR=<0|1>] : Configures the [skew_correction] module with measurements (in mm) taken from a calibration print. One may enter measurements for any combination of planes, planes not entered will retain their current value. If CLEAR=1 is entered then all skew correction will be disabled. GET_CURRENT_SKEW \u00b6 GET_CURRENT_SKEW : Reports the current printer skew for each plane in both radians and degrees. The skew is calculated based on parameters provided via the SET_SKEW gcode. CALC_MEASURED_SKEW \u00b6 CALC_MEASURED_SKEW [AC=<ac_length>] [BD=<bd_length>] [AD=<ad_length>] : Calculates and reports the skew (in radians and degrees) based on a measured print. This can be useful for determining the printer's current skew after correction has been applied. It may also be useful before correction is applied to determine if skew correction is necessary. See Skew Correction for details on skew calibration objects and measurements. SKEW_PROFILE \u00b6 SKEW_PROFILE [LOAD=<name>] [SAVE=<name>] [REMOVE=<name>] : Profile management for skew_correction. LOAD will restore skew state from the profile matching the supplied name. SAVE will save the current skew state to a profile matching the supplied name. Remove will delete the profile matching the supplied name from persistent memory. Note that after SAVE or REMOVE operations have been run the SAVE_CONFIG gcode must be run to make the changes to persistent memory permanent. [smart_effector] \u00b6 Several commands are available when a smart_effector config section is enabled. Be sure to check the official documentation for the Smart Effector on the Duet3D Wiki before changing the Smart Effector parameters. Also check the probe calibration guide . SET_SMART_EFFECTOR \u00b6 SET_SMART_EFFECTOR [SENSITIVITY=<sensitivity>] [ACCEL=<accel>] [RECOVERY_TIME=<time>] : Set the Smart Effector parameters. When SENSITIVITY is specified, the respective value is written to the SmartEffector EEPROM (requires control_pin to be provided). Acceptable <sensitivity> values are 0..255, the default is 50. Lower values require less nozzle contact force to trigger (but there is a higher risk of false triggering due to vibrations during probing), and higher values reduce false triggering (but require larger contact force to trigger). Since the sensitivity is written to EEPROM, it is preserved after the shutdown, and so it does not need to be configured on every printer startup. ACCEL and RECOVERY_TIME allow to override the corresponding parameters at run-time, see the config section of Smart Effector for more info on those parameters. RESET_SMART_EFFECTOR \u00b6 RESET_SMART_EFFECTOR : Resets Smart Effector sensitivity to its factory settings. Requires control_pin to be provided in the config section. [stepper_enable] \u00b6 The stepper_enable module is automatically loaded. SET_STEPPER_ENABLE \u00b6 SET_STEPPER_ENABLE STEPPER=<config_name> ENABLE=[0|1] : Enable or disable only the given stepper. This is a diagnostic and debugging tool and must be used with care. Disabling an axis motor does not reset the homing information. Manually moving a disabled stepper may cause the machine to operate the motor outside of safe limits. This can lead to damage to axis components, hot ends, and print surface. [temperature_fan] \u00b6 The following command is available when a temperature_fan config section is enabled. SET_TEMPERATURE_FAN_TARGET \u00b6 SET_TEMPERATURE_FAN_TARGET temperature_fan=<temperature_fan_name> [target=<target_temperature>] [min_speed=<min_speed>] [max_speed=<max_speed>] : Sets the target temperature for a temperature_fan. If a target is not supplied, it is set to the specified temperature in the config file. If speeds are not supplied, no change is applied. [temperature_probe] \u00b6 The following commands are available when a temperature_probe config section is enabled. TEMPERATURE_PROBE_CALIBRATE \u00b6 TEMPERATURE_PROBE_CALIBRATE [PROBE=<probe name>] [TARGET=<value>] [STEP=<value>] : Initiates probe drift calibration for eddy current based probes. The TARGET is a target temperature for the last sample. When the temperature recorded during a sample exceeds the TARGET calibration will complete. The STEP parameter sets temperature delta (in C) between samples. After a sample has been taken, this delta is used to schedule a call to TEMPERATURE_PROBE_NEXT . The default STEP is 2. TEMPERATURE_PROBE_NEXT \u00b6 TEMPERATURE_PROBE_NEXT : After calibration has started this command is run to take the next sample. It is automatically scheduled to run when the delta specified by STEP has been reached, however its also possible to manually run this command to force a new sample. This command is only available during calibration. TEMPERATURE_PROBE_COMPLETE: \u00b6 TEMPERATURE_PROBE_COMPLETE : Can be used to end calibration and save the current result before the TARGET temperature is reached. This command is only available during calibration. ABORT \u00b6 ABORT : Aborts the calibration process, discarding the current results. This command is only available during drift calibration. TEMPERATURE_PROBE_ENABLE \u00b6 TEMPERATURE_PROBE_ENABLE ENABLE=[0|1] : Sets temperature drift compensation on or off. If ENABLE is set to 0, drift compensation will be disabled, if set to 1 it is enabled. [tmcXXXX] \u00b6 The following commands are available when any of the tmcXXXX config sections are enabled. DUMP_TMC \u00b6 DUMP_TMC STEPPER=<name> [REGISTER=<name>] : This command will read all TMC driver registers and report their values. If a REGISTER is provided, only the specified register will be dumped. INIT_TMC \u00b6 INIT_TMC STEPPER=<name> : This command will initialize the TMC registers. Needed to re-enable the driver if power to the chip is turned off then back on. SET_TMC_CURRENT \u00b6 SET_TMC_CURRENT STEPPER=<name> CURRENT=<amps> HOLDCURRENT=<amps> : This will adjust the run and hold currents of the TMC driver. HOLDCURRENT is not applicable to tmc2660 drivers. When used on a driver which has the globalscaler field (tmc5160 and tmc2240), if StealthChop2 is used, the stepper must be held at standstill for >130ms so that the driver executes the AT#1 calibration. SET_TMC_FIELD \u00b6 SET_TMC_FIELD STEPPER=<name> FIELD=<field> VALUE=<value> VELOCITY=<value> : This will alter the value of the specified register field of the TMC driver. This command is intended for low-level diagnostics and debugging only because changing the fields during run-time can lead to undesired and potentially dangerous behavior of your printer. Permanent changes should be made using the printer configuration file instead. No sanity checks are performed for the given values. A VELOCITY can also be specified instead of a VALUE. This velocity is converted to the 20bit TSTEP based value representation. Only use the VELOCITY argument for fields that represent velocities. [toolhead] \u00b6 The toolhead module is automatically loaded. SET_VELOCITY_LIMIT \u00b6 SET_VELOCITY_LIMIT [VELOCITY=<value>] [ACCEL=<value>] [MINIMUM_CRUISE_RATIO=<value>] [SQUARE_CORNER_VELOCITY=<value>] : This command can alter the velocity limits that were specified in the printer config file. See the printer config section for a description of each parameter. [tuning_tower] \u00b6 The tuning_tower module is automatically loaded. TUNING_TOWER \u00b6 TUNING_TOWER COMMAND=<command> PARAMETER=<name> START=<value> [SKIP=<value>] [FACTOR=<value> [BAND=<value>]] | [STEP_DELTA=<value> STEP_HEIGHT=<value>] : A tool for tuning a parameter on each Z height during a print. The tool will run the given COMMAND with the given PARAMETER assigned to a value that varies with Z according to a formula. Use FACTOR if you will use a ruler or calipers to measure the Z height of the optimum value, or STEP_DELTA and STEP_HEIGHT if the tuning tower model has bands of discrete values as is common with temperature towers. If SKIP=<value> is specified, the tuning process doesn't begin until Z height <value> is reached, and below that the value will be set to START ; in this case, the z_height used in the formulas below is actually max(z - skip, 0) . There are three possible combinations of options: FACTOR : The value changes at a rate of factor per millimeter. The formula used is: value = start + factor * z_height . You can plug the optimum Z height directly into the formula to determine the optimum parameter value. FACTOR and BAND : The value changes at an average rate of factor per millimeter, but in discrete bands where the adjustment will only be made every BAND millimeters of Z height. The formula used is: value = start + factor * ((floor(z_height / band) + .5) * band) . STEP_DELTA and STEP_HEIGHT : The value changes by STEP_DELTA every STEP_HEIGHT millimeters. The formula used is: value = start + step_delta * floor(z_height / step_height) . You can simply count bands or read tuning tower labels to determine the optimum value. [virtual_sdcard] \u00b6 Klipper supports the following standard G-Code commands if the virtual_sdcard config section is enabled: List SD card: M20 Initialize SD card: M21 Select SD file: M23 <filename> Start/resume SD print: M24 Pause SD print: M25 Set SD position: M26 S<offset> Report SD print status: M27 In addition, the following extended commands are available when the \"virtual_sdcard\" config section is enabled. SDCARD_PRINT_FILE \u00b6 SDCARD_PRINT_FILE FILENAME=<filename> : Load a file and start SD print. SDCARD_RESET_FILE \u00b6 SDCARD_RESET_FILE : Unload file and clear SD state. [z_thermal_adjust] \u00b6 The following commands are available when the z_thermal_adjust config section is enabled. SET_Z_THERMAL_ADJUST \u00b6 SET_Z_THERMAL_ADJUST [ENABLE=<0:1>] [TEMP_COEFF=<value>] [REF_TEMP=<value>] : Enable or disable the Z thermal adjustment with ENABLE . Disabling does not remove any adjustment already applied, but will freeze the current adjustment value - this prevents potentially unsafe downward Z movement. Re-enabling can potentially cause upward tool movement as the adjustment is updated and applied. TEMP_COEFF allows run-time tuning of the adjustment temperature coefficient (i.e. the TEMP_COEFF config parameter). TEMP_COEFF values are not saved to the config. REF_TEMP manually overrides the reference temperature typically set during homing (for use in e.g. non-standard homing routines) - will be reset automatically upon homing. [z_tilt] \u00b6 The following commands are available when the z_tilt config section is enabled. Z_TILT_ADJUST \u00b6 Z_TILT_ADJUST [RETRIES=<value>] [RETRY_TOLERANCE=<value>] [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>] : This command will probe the points specified in the config and then make independent adjustments to each Z stepper to compensate for tilt. See the PROBE command for details on the optional probe parameters. The optional RETRIES , RETRY_TOLERANCE , and HORIZONTAL_MOVE_Z values override those options specified in the config file.","title":"G-Codes"},{"location":"G-Codes.html#g-codes","text":"This document describes the commands that Klipper supports. These are commands that one may enter into the OctoPrint terminal tab.","title":"G-Codes"},{"location":"G-Codes.html#g-code-commands","text":"Klipper supports the following standard G-Code commands: Move (G0 or G1): G1 [X<pos>] [Y<pos>] [Z<pos>] [E<pos>] [F<speed>] Dwell: G4 P<milliseconds> Move to origin: G28 [X] [Y] [Z] Turn off motors: M18 or M84 Wait for current moves to finish: M400 Use absolute/relative distances for extrusion: M82 , M83 Use absolute/relative coordinates: G90 , G91 Set position: G92 [X<pos>] [Y<pos>] [Z<pos>] [E<pos>] Set speed factor override percentage: M220 S<percent> Set extrude factor override percentage: M221 S<percent> Set acceleration: M204 S<value> OR M204 P<value> T<value> Note: If S is not specified and both P and T are specified, then the acceleration is set to the minimum of P and T. If only one of P or T is specified, the command has no effect. Get extruder temperature: M105 Set extruder temperature: M104 [T<index>] [S<temperature>] Set extruder temperature and wait: M109 [T<index>] S<temperature> Note: M109 always waits for temperature to settle at requested value Set bed temperature: M140 [S<temperature>] Set bed temperature and wait: M190 S<temperature> Note: M190 always waits for temperature to settle at requested value Set fan speed: M106 S<value> Turn fan off: M107 Emergency stop: M112 Get current position: M114 Get firmware version: M115 For further details on the above commands see the RepRap G-Code documentation . Klipper's goal is to support the G-Code commands produced by common 3rd party software (eg, OctoPrint, Printrun, Slic3r, Cura, etc.) in their standard configurations. It is not a goal to support every possible G-Code command. Instead, Klipper prefers human readable \"extended G-Code commands\" . Similarly, the G-Code terminal output is only intended to be human readable - see the API Server document if controlling Klipper from external software. If one requires a less common G-Code command then it may be possible to implement it with a custom gcode_macro config section . For example, one might use this to implement: G12 , G29 , G30 , G31 , M42 , M80 , M81 , T1 , etc.","title":"G-Code commands"},{"location":"G-Codes.html#additional-commands","text":"Klipper uses \"extended\" G-Code commands for general configuration and status. These extended commands all follow a similar format - they start with a command name and may be followed by one or more parameters. For example: SET_SERVO SERVO=myservo ANGLE=5.3 . In this document, the commands and parameters are shown in uppercase, however they are not case sensitive. (So, \"SET_SERVO\" and \"set_servo\" both run the same command.) This section is organized by Klipper module name, which generally follows the section names specified in the printer configuration file . Note that some modules are automatically loaded.","title":"Additional Commands"},{"location":"G-Codes.html#adxl345","text":"The following commands are available when an adxl345 config section is enabled.","title":"[adxl345]"},{"location":"G-Codes.html#accelerometer_measure","text":"ACCELEROMETER_MEASURE [CHIP=<config_name>] [NAME=<value>] : Starts accelerometer measurements at the requested number of samples per second. If CHIP is not specified it defaults to \"adxl345\". The command works in a start-stop mode: when executed for the first time, it starts the measurements, next execution stops them. The results of measurements are written to a file named /tmp/adxl345-<chip>-<name>.csv where <chip> is the name of the accelerometer chip ( my_chip_name from [adxl345 my_chip_name] ) and <name> is the optional NAME parameter. If NAME is not specified it defaults to the current time in \"YYYYMMDD_HHMMSS\" format. If the accelerometer does not have a name in its config section (simply [adxl345] ) then <chip> part of the name is not generated.","title":"ACCELEROMETER_MEASURE"},{"location":"G-Codes.html#accelerometer_query","text":"ACCELEROMETER_QUERY [CHIP=<config_name>] [RATE=<value>] : queries accelerometer for the current value. If CHIP is not specified it defaults to \"adxl345\". If RATE is not specified, the default value is used. This command is useful to test the connection to the ADXL345 accelerometer: one of the returned values should be a free-fall acceleration (+/- some noise of the chip).","title":"ACCELEROMETER_QUERY"},{"location":"G-Codes.html#accelerometer_debug_read","text":"ACCELEROMETER_DEBUG_READ [CHIP=<config_name>] REG=<register> : queries ADXL345 register \"register\" (e.g. 44 or 0x2C). Can be useful for debugging purposes.","title":"ACCELEROMETER_DEBUG_READ"},{"location":"G-Codes.html#accelerometer_debug_write","text":"ACCELEROMETER_DEBUG_WRITE [CHIP=<config_name>] REG=<register> VAL=<value> : Writes raw \"value\" into a register \"register\". Both \"value\" and \"register\" can be a decimal or a hexadecimal integer. Use with care, and refer to ADXL345 data sheet for the reference.","title":"ACCELEROMETER_DEBUG_WRITE"},{"location":"G-Codes.html#angle","text":"The following commands are available when an angle config section is enabled.","title":"[angle]"},{"location":"G-Codes.html#angle_calibrate","text":"ANGLE_CALIBRATE CHIP=<chip_name> : Perform angle calibration on the given sensor (there must be an [angle chip_name] config section that has specified a stepper parameter). IMPORTANT - this tool will command the stepper motor to move without checking the normal kinematic boundary limits. Ideally the motor should be disconnected from any printer carriage before performing calibration. If the stepper can not be disconnected from the printer, make sure the carriage is near the center of its rail before starting calibration. (The stepper motor may move forwards or backwards two full rotations during this test.) After completing this test use the SAVE_CONFIG command to save the calibration data to the config file. In order to use this tool the Python \"numpy\" package must be installed (see the measuring resonance document for more information).","title":"ANGLE_CALIBRATE"},{"location":"G-Codes.html#angle_chip_calibrate","text":"ANGLE_CHIP_CALIBRATE CHIP=<chip_name> : Perform internal sensor calibration, if implemented (MT6826S/MT6835). MT68XX : The motor should be disconnected from any printer carriage before performing calibration. After calibration, the sensor should be reset by disconnecting the power.","title":"ANGLE_CHIP_CALIBRATE"},{"location":"G-Codes.html#angle_debug_read","text":"ANGLE_DEBUG_READ CHIP=<config_name> REG=<register> : Queries sensor register \"register\" (e.g. 44 or 0x2C). Can be useful for debugging purposes. This is only available for tle5012b chips.","title":"ANGLE_DEBUG_READ"},{"location":"G-Codes.html#angle_debug_write","text":"ANGLE_DEBUG_WRITE CHIP=<config_name> REG=<register> VAL=<value> : Writes raw \"value\" into register \"register\". Both \"value\" and \"register\" can be a decimal or a hexadecimal integer. Use with care, and refer to sensor data sheet for the reference. This is only available for tle5012b chips.","title":"ANGLE_DEBUG_WRITE"},{"location":"G-Codes.html#axis_twist_compensation","text":"The following commands are available when the axis_twist_compensation config section is enabled.","title":"[axis_twist_compensation]"},{"location":"G-Codes.html#axis_twist_compensation_calibrate","text":"AXIS_TWIST_COMPENSATION_CALIBRATE [AXIS=<X|Y>] [SAMPLE_COUNT=<value>] Calibrates axis twist compensation by specifying the target axis or enabling automatic calibration. AXIS: Define the axis ( X or Y ) for which the twist compensation will be calibrated. If not specified, the axis defaults to 'X' .","title":"AXIS_TWIST_COMPENSATION_CALIBRATE"},{"location":"G-Codes.html#bed_mesh","text":"The following commands are available when the bed_mesh config section is enabled (also see the bed mesh guide ).","title":"[bed_mesh]"},{"location":"G-Codes.html#bed_mesh_calibrate","text":"BED_MESH_CALIBRATE [PROFILE=<name>] [METHOD=manual] [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>] [<mesh_parameter>=<value>] [ADAPTIVE=1] [ADAPTIVE_MARGIN=<value>] : This command probes the bed using generated points specified by the parameters in the config. After probing, a mesh is generated and z-movement is adjusted according to the mesh. The mesh is immediately active after successful completion of BED_MESH_CALIBRATE . The mesh will be saved into a profile specified by the PROFILE parameter, or default if unspecified. If ADAPTIVE=1 is specified then the profile name will begin with adaptive- and should not be saved for reuse. See the PROBE command for details on the optional probe parameters. If METHOD=manual is specified then the manual probing tool is activated - see the MANUAL_PROBE command above for details on the additional commands available while this tool is active. The optional HORIZONTAL_MOVE_Z value overrides the horizontal_move_z option specified in the config file. If ADAPTIVE=1 is specified then the objects defined by the Gcode file being printed will be used to define the probed area. The optional ADAPTIVE_MARGIN value overrides the adaptive_margin option specified in the config file.","title":"BED_MESH_CALIBRATE"},{"location":"G-Codes.html#bed_mesh_output","text":"BED_MESH_OUTPUT PGP=[<0:1>] : This command outputs the current probed z values and current mesh values to the terminal. If PGP=1 is specified the X, Y coordinates generated by bed_mesh, along with their associated indices, will be output to the terminal.","title":"BED_MESH_OUTPUT"},{"location":"G-Codes.html#bed_mesh_map","text":"BED_MESH_MAP : Like to BED_MESH_OUTPUT, this command prints the current state of the mesh to the terminal. Instead of printing the values in a human readable format, the state is serialized in json format. This allows octoprint plugins to easily capture the data and generate height maps approximating the bed's surface.","title":"BED_MESH_MAP"},{"location":"G-Codes.html#bed_mesh_clear","text":"BED_MESH_CLEAR : This command clears the mesh and removes all z adjustment. It is recommended to put this in your end-gcode.","title":"BED_MESH_CLEAR"},{"location":"G-Codes.html#bed_mesh_profile","text":"BED_MESH_PROFILE LOAD=<name> SAVE=<name> REMOVE=<name> : This command provides profile management for mesh state. LOAD will restore the mesh state from the profile matching the supplied name. SAVE will save the current mesh state to a profile matching the supplied name. Remove will delete the profile matching the supplied name from persistent memory. Note that after SAVE or REMOVE operations have been run the SAVE_CONFIG gcode must be run to make the changes to persistent memory permanent.","title":"BED_MESH_PROFILE"},{"location":"G-Codes.html#bed_mesh_offset","text":"BED_MESH_OFFSET [X=<value>] [Y=<value>] [ZFADE=<value] : Applies X, Y, and/or ZFADE offsets to the mesh lookup. This is useful for printers with independent extruders, as an offset is necessary to produce correct Z adjustment after a tool change. Note that a ZFADE offset does not apply additional z-adjustment directly, it is used to correct the fade calculation when a gcode offset has been applied to the Z axis.","title":"BED_MESH_OFFSET"},{"location":"G-Codes.html#bed_screws","text":"The following commands are available when the bed_screws config section is enabled (also see the manual level guide ).","title":"[bed_screws]"},{"location":"G-Codes.html#bed_screws_adjust","text":"BED_SCREWS_ADJUST : This command will invoke the bed screws adjustment tool. It will command the nozzle to different locations (as defined in the config file) and allow one to make adjustments to the bed screws so that the bed is a constant distance from the nozzle.","title":"BED_SCREWS_ADJUST"},{"location":"G-Codes.html#bed_tilt","text":"The following commands are available when the bed_tilt config section is enabled.","title":"[bed_tilt]"},{"location":"G-Codes.html#bed_tilt_calibrate","text":"BED_TILT_CALIBRATE [METHOD=manual] [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>] : This command will probe the points specified in the config and then recommend updated x and y tilt adjustments. See the PROBE command for details on the optional probe parameters. If METHOD=manual is specified then the manual probing tool is activated - see the MANUAL_PROBE command above for details on the additional commands available while this tool is active. The optional HORIZONTAL_MOVE_Z value overrides the horizontal_move_z option specified in the config file.","title":"BED_TILT_CALIBRATE"},{"location":"G-Codes.html#bltouch","text":"The following command is available when a bltouch config section is enabled (also see the BL-Touch guide ).","title":"[bltouch]"},{"location":"G-Codes.html#bltouch_debug","text":"BLTOUCH_DEBUG COMMAND=<command> : This sends a command to the BLTouch. It may be useful for debugging. Available commands are: pin_down , touch_mode , pin_up , self_test , reset . A BL-Touch V3.0 or V3.1 may also support set_5V_output_mode , set_OD_output_mode , output_mode_store commands.","title":"BLTOUCH_DEBUG"},{"location":"G-Codes.html#bltouch_store","text":"BLTOUCH_STORE MODE=<output_mode> : This stores an output mode in the EEPROM of a BLTouch V3.1 Available output_modes are: 5V , OD","title":"BLTOUCH_STORE"},{"location":"G-Codes.html#configfile","text":"The configfile module is automatically loaded.","title":"[configfile]"},{"location":"G-Codes.html#save_config","text":"SAVE_CONFIG : This command will overwrite the main printer config file and restart the host software. This command is used in conjunction with other calibration commands to store the results of calibration tests.","title":"SAVE_CONFIG"},{"location":"G-Codes.html#delayed_gcode","text":"The following command is enabled if a delayed_gcode config section has been enabled (also see the template guide ).","title":"[delayed_gcode]"},{"location":"G-Codes.html#update_delayed_gcode","text":"UPDATE_DELAYED_GCODE [ID=<name>] [DURATION=<seconds>] : Updates the delay duration for the identified [delayed_gcode] and starts the timer for gcode execution. A value of 0 will cancel a pending delayed gcode from executing.","title":"UPDATE_DELAYED_GCODE"},{"location":"G-Codes.html#delta_calibrate","text":"The following commands are available when the delta_calibrate config section is enabled (also see the delta calibrate guide ).","title":"[delta_calibrate]"},{"location":"G-Codes.html#delta_calibrate_1","text":"DELTA_CALIBRATE [METHOD=manual] [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>] : This command will probe seven points on the bed and recommend updated endstop positions, tower angles, and radius. See the PROBE command for details on the optional probe parameters. If METHOD=manual is specified then the manual probing tool is activated - see the MANUAL_PROBE command above for details on the additional commands available while this tool is active. The optional HORIZONTAL_MOVE_Z value overrides the horizontal_move_z option specified in the config file.","title":"DELTA_CALIBRATE"},{"location":"G-Codes.html#delta_analyze","text":"DELTA_ANALYZE : This command is used during enhanced delta calibration. See Delta Calibrate for details.","title":"DELTA_ANALYZE"},{"location":"G-Codes.html#display","text":"The following command is available when a display config section is enabled.","title":"[display]"},{"location":"G-Codes.html#set_display_group","text":"SET_DISPLAY_GROUP [DISPLAY=<display>] GROUP=<group> : Set the active display group of an lcd display. This allows to define multiple display data groups in the config, e.g. [display_data <group> <elementname>] and switch between them using this extended gcode command. If DISPLAY is not specified it defaults to \"display\" (the primary display).","title":"SET_DISPLAY_GROUP"},{"location":"G-Codes.html#display_status","text":"The display_status module is automatically loaded if a display config section is enabled. It provides the following standard G-Code commands: Display Message: M117 <message> Set build percentage: M73 P<percent> Also provided is the following extended G-Code command: SET_DISPLAY_TEXT MSG=<message> : Performs the equivalent of M117, setting the supplied MSG as the current display message. If MSG is omitted the display will be cleared.","title":"[display_status]"},{"location":"G-Codes.html#dual_carriage","text":"The following command is available when the dual_carriage config section is enabled.","title":"[dual_carriage]"},{"location":"G-Codes.html#set_dual_carriage","text":"SET_DUAL_CARRIAGE CARRIAGE=<carriage> [MODE=[PRIMARY|COPY|MIRROR]] : This command will change the mode of the specified carriage. If no MODE is provided it defaults to PRIMARY . <carriage> must reference a defined primary or dual carriage for generic_cartesian kinematics or be 0 (for primary carriage) or 1 (for dual carriage) for all other kinematics supporting IDEX. Setting the mode to PRIMARY deactivates the other carriage and makes the specified carriage execute subsequent G-Code commands as-is. COPY and MIRROR modes are supported only for dual carriages. When set to either of these modes, dual carriage will then track the subsequent moves of its primary carriage and either copy relative movements of it (in COPY mode) or execute them in the opposite (mirror) direction (in MIRROR mode).","title":"SET_DUAL_CARRIAGE"},{"location":"G-Codes.html#save_dual_carriage_state","text":"SAVE_DUAL_CARRIAGE_STATE [NAME=<state_name>] : Save the current positions of the dual carriages and their modes. Saving and restoring DUAL_CARRIAGE state can be useful in scripts and macros, as well as in homing routine overrides. If NAME is provided it allows one to name the saved state to the given string. If NAME is not provided it defaults to \"default\".","title":"SAVE_DUAL_CARRIAGE_STATE"},{"location":"G-Codes.html#restore_dual_carriage_state","text":"RESTORE_DUAL_CARRIAGE_STATE [NAME=<state_name>] [MOVE=[0|1] [MOVE_SPEED=<speed>]] : Restore the previously saved positions of the dual carriages and their modes, unless \"MOVE=0\" is specified, in which case only the saved modes will be restored, but not the positions of the carriages. If positions are being restored and \"MOVE_SPEED\" is specified, then the toolhead moves will be performed with the given speed (in mm/s); otherwise the toolhead move will use the rail homing speed. Note that the carriages restore their positions only over their own axis, which may be necessary to correctly restore COPY and MIRROR mode of the dual carriage.","title":"RESTORE_DUAL_CARRIAGE_STATE"},{"location":"G-Codes.html#endstop_phase","text":"The following commands are available when an endstop_phase config section is enabled (also see the endstop phase guide ).","title":"[endstop_phase]"},{"location":"G-Codes.html#endstop_phase_calibrate","text":"ENDSTOP_PHASE_CALIBRATE [STEPPER=<config_name>] : If no STEPPER parameter is provided then this command will reports statistics on endstop stepper phases during past homing operations. When a STEPPER parameter is provided it arranges for the given endstop phase setting to be written to the config file (in conjunction with the SAVE_CONFIG command).","title":"ENDSTOP_PHASE_CALIBRATE"},{"location":"G-Codes.html#exclude_object","text":"The following commands are available when an exclude_object config section is enabled (also see the exclude object guide ):","title":"[exclude_object]"},{"location":"G-Codes.html#exclude_object_1","text":"EXCLUDE_OBJECT [NAME=object_name] [CURRENT=1] [RESET=1] : With no parameters, this will return a list of all currently excluded objects. When the NAME parameter is given, the named object will be excluded from printing. When the CURRENT parameter is given, the current object will be excluded from printing. When the RESET parameter is given, the list of excluded objects will be cleared. Additionally including NAME will only reset the named object. This can cause print failures, if layers were already skipped.","title":"EXCLUDE_OBJECT"},{"location":"G-Codes.html#exclude_object_define","text":"EXCLUDE_OBJECT_DEFINE [NAME=object_name [CENTER=X,Y] [POLYGON=[[x,y],...]] [RESET=1] [JSON=1] : Provides a summary of an object in the file. With no parameters provided, this will list the defined objects known to Klipper. Returns a list of strings, unless the JSON parameter is given, when it will return object details in json format. When the NAME parameter is included, this defines an object to be excluded. NAME : This parameter is required. It is the identifier used by other commands in this module. CENTER : An X,Y coordinate for the object. POLYGON : An array of X,Y coordinates that provide an outline for the object. When the RESET parameter is provided, all defined objects will be cleared, and the [exclude_object] module will be reset.","title":"EXCLUDE_OBJECT_DEFINE"},{"location":"G-Codes.html#exclude_object_start","text":"EXCLUDE_OBJECT_START NAME=object_name : This command takes a NAME parameter and denotes the start of the gcode for an object on the current layer.","title":"EXCLUDE_OBJECT_START"},{"location":"G-Codes.html#exclude_object_end","text":"EXCLUDE_OBJECT_END [NAME=object_name] : Denotes the end of the object's gcode for the layer. It is paired with EXCLUDE_OBJECT_START . A NAME parameter is optional, and will only warn when the provided name does not match the current object.","title":"EXCLUDE_OBJECT_END"},{"location":"G-Codes.html#extruder","text":"The following commands are available if an extruder config section is enabled:","title":"[extruder]"},{"location":"G-Codes.html#activate_extruder","text":"ACTIVATE_EXTRUDER EXTRUDER=<config_name> : In a printer with multiple extruder config sections, this command changes the active hotend.","title":"ACTIVATE_EXTRUDER"},{"location":"G-Codes.html#set_pressure_advance","text":"SET_PRESSURE_ADVANCE [EXTRUDER=<config_name>] [ADVANCE=<pressure_advance>] [SMOOTH_TIME=<pressure_advance_smooth_time>] : Set pressure advance parameters of an extruder stepper (as defined in an extruder or extruder_stepper config section). If EXTRUDER is not specified, it defaults to the stepper defined in the active hotend.","title":"SET_PRESSURE_ADVANCE"},{"location":"G-Codes.html#set_extruder_rotation_distance","text":"SET_EXTRUDER_ROTATION_DISTANCE EXTRUDER=<config_name> [DISTANCE=<distance>] : Set a new value for the provided extruder stepper's \"rotation distance\" (as defined in an extruder or extruder_stepper config section). If the rotation distance is a negative number then the stepper motion will be inverted (relative to the stepper direction specified in the config file). Changed settings are not retained on Klipper reset. Use with caution as small changes can result in excessive pressure between extruder and hotend. Do proper calibration with filament before use. If 'DISTANCE' value is not provided then this command will return the current rotation distance.","title":"SET_EXTRUDER_ROTATION_DISTANCE"},{"location":"G-Codes.html#sync_extruder_motion","text":"SYNC_EXTRUDER_MOTION EXTRUDER=<name> MOTION_QUEUE=<name> : This command will cause the stepper specified by EXTRUDER (as defined in an extruder or extruder_stepper config section) to become synchronized to the movement of an extruder specified by MOTION_QUEUE (as defined in an extruder config section). If MOTION_QUEUE is an empty string then the stepper will be desynchronized from all extruder movement.","title":"SYNC_EXTRUDER_MOTION"},{"location":"G-Codes.html#fan_generic","text":"The following command is available when a fan_generic config section is enabled.","title":"[fan_generic]"},{"location":"G-Codes.html#set_fan_speed","text":"SET_FAN_SPEED FAN=config_name SPEED=<speed> This command sets the speed of a fan. \"speed\" must be between 0.0 and 1.0. SET_FAN_SPEED PIN=config_name TEMPLATE=<template_name> [<param_x>=<literal>] : If TEMPLATE is specified then it assigns a display_template to the given fan. For example, if one defined a [display_template my_fan_template] config section then one could assign TEMPLATE=my_fan_template here. The display_template should produce a string containing a floating point number with the desired value. The template will be continuously evaluated and the fan will be automatically set to the resulting speed. One may set display_template parameters to use during template evaluation (parameters will be parsed as Python literals). If TEMPLATE is an empty string then this command will clear any previous template assigned to the pin (one can then use SET_FAN_SPEED commands to manage the values directly).","title":"SET_FAN_SPEED"},{"location":"G-Codes.html#filament_switch_sensor","text":"The following command is available when a filament_switch_sensor or filament_motion_sensor config section is enabled.","title":"[filament_switch_sensor]"},{"location":"G-Codes.html#query_filament_sensor","text":"QUERY_FILAMENT_SENSOR SENSOR=<sensor_name> : Queries the current status of the filament sensor. The data displayed on the terminal will depend on the sensor type defined in the configuration.","title":"QUERY_FILAMENT_SENSOR"},{"location":"G-Codes.html#set_filament_sensor","text":"SET_FILAMENT_SENSOR SENSOR=<sensor_name> ENABLE=[0|1] : Sets the filament sensor on/off. If ENABLE is set to 0, the filament sensor will be disabled, if set to 1 it is enabled.","title":"SET_FILAMENT_SENSOR"},{"location":"G-Codes.html#firmware_retraction","text":"The following standard G-Code commands are available when the firmware_retraction config section is enabled. These commands allow you to utilize the firmware retraction feature available in many slicers, to reduce stringing during non-extrusion moves from one part of the print to another. Appropriately configuring pressure advance reduces the length of retraction required. G10 : Retracts the extruder using the currently configured parameters. G11 : Unretracts the extruder using the currently configured parameters. The following additional commands are also available.","title":"[firmware_retraction]"},{"location":"G-Codes.html#set_retraction","text":"SET_RETRACTION [RETRACT_LENGTH=<mm>] [RETRACT_SPEED=<mm/s>] [UNRETRACT_EXTRA_LENGTH=<mm>] [UNRETRACT_SPEED=<mm/s>] : Adjust the parameters used by firmware retraction. RETRACT_LENGTH determines the length of filament to retract and unretract. The speed of retraction is adjusted via RETRACT_SPEED, and is typically set relatively high. The speed of unretraction is adjusted via UNRETRACT_SPEED, and is not particularly critical, although often lower than RETRACT_SPEED. In some cases it is useful to add a small amount of additional length on unretraction, and this is set via UNRETRACT_EXTRA_LENGTH. SET_RETRACTION is commonly set as part of slicer per-filament configuration, as different filaments require different parameter settings.","title":"SET_RETRACTION"},{"location":"G-Codes.html#get_retraction","text":"GET_RETRACTION : Queries the current parameters used by firmware retraction and displays them on the terminal.","title":"GET_RETRACTION"},{"location":"G-Codes.html#force_move","text":"The force_move module is automatically loaded, however some commands require setting enable_force_move in the printer config .","title":"[force_move]"},{"location":"G-Codes.html#stepper_buzz","text":"STEPPER_BUZZ STEPPER=<config_name> : Move the given stepper forward one mm and then backward one mm, repeated 10 times. This is a diagnostic tool to help verify stepper connectivity.","title":"STEPPER_BUZZ"},{"location":"G-Codes.html#force_move_1","text":"FORCE_MOVE STEPPER=<config_name> DISTANCE=<value> VELOCITY=<value> [ACCEL=<value>] : This command will forcibly move the given stepper the given distance (in mm) at the given constant velocity (in mm/s). If ACCEL is specified and is greater than zero, then the given acceleration (in mm/s^2) will be used; otherwise no acceleration is performed. No boundary checks are performed; no kinematic updates are made; other parallel steppers on an axis will not be moved. Use caution as an incorrect command could cause damage! Using this command will almost certainly place the low-level kinematics in an incorrect state; issue a G28 afterwards to reset the kinematics. This command is intended for low-level diagnostics and debugging.","title":"FORCE_MOVE"},{"location":"G-Codes.html#set_kinematic_position","text":"SET_KINEMATIC_POSITION [X=<value>] [Y=<value>] [Z=<value>] [SET_HOMED=<[X][Y][Z]>] [CLEAR_HOMED=<[X][Y][Z]>] : Force the low-level kinematic code to believe the toolhead is at the given cartesian position and set/clear homed status. This is a diagnostic and debugging command; use SET_GCODE_OFFSET and/or G92 for regular axis transformations. Setting an incorrect or invalid position may lead to internal software errors. The X , Y , and Z parameters are used to alter the low-level kinematic position tracking. If any of these parameters are not set then the position is not changed - for example SET_KINEMATIC_POSITION Z=10 would set all axes as homed, set the internal Z position to 10, and leave the X and Y positions unchanged. Changing the internal position tracking is not dependent on the internal homing state - one may alter the position for both homed and not homed axes, and similarly one may set or clear the homing state of an axis without altering its internal position. The SET_HOMED parameter defaults to XYZ which instructs the kinematics to consider all axes as homed. A bare SET_KINEMATIC_POSITION command will result in all axes being considered homed (and not change its current position). If it is not desired to change the state of homed axes then assign SET_HOMED to an empty string - for example: SET_KINEMATIC_POSITION SET_HOMED= X=10 . It is also possible to request an individual axis be considered homed (eg, SET_HOMED=X ), but note that non-cartesian style kinematics (such as delta kinematics) may not support setting an individual axis as homed. The CLEAR_HOMED parameter instructs the kinematics to consider the given axes as not homed. For example, CLEAR_HOMED=XYZ would request all axes to be considered not homed (and thus require homing prior to movement on those axes). The default is SET_HOMED=XYZ even if CLEAR_HOMED is present, so the command SET_KINEMATIC_POSITION CLEAR_HOMED=Z will set X and Y as homed and clear the homing state for Z. Use SET_KINEMATIC_POSITION SET_HOMED= CLEAR_HOMED=Z if the goal is to clear only the Z homing state. If an axis is specified in neither SET_HOMED nor CLEAR_HOMED then its homing state is not changed and if it is specified in both then CLEAR_HOMED has precedence. It is possible to request clearing of an individual axis, but on non-cartesian style kinematics (such as delta kinematics) doing so may result in clearing the homing state of additional axes. Note the CLEAR parameter is currently an alias for the CLEAR_HOMED parameter, but this alias will be removed in the future.","title":"SET_KINEMATIC_POSITION"},{"location":"G-Codes.html#gcode","text":"The gcode module is automatically loaded.","title":"[gcode]"},{"location":"G-Codes.html#restart","text":"RESTART : This will cause the host software to reload its config and perform an internal reset. This command will not clear error state from the micro-controller (see FIRMWARE_RESTART) nor will it load new software (see the FAQ ).","title":"RESTART"},{"location":"G-Codes.html#firmware_restart","text":"FIRMWARE_RESTART : This is similar to a RESTART command, but it also clears any error state from the micro-controller.","title":"FIRMWARE_RESTART"},{"location":"G-Codes.html#status","text":"STATUS : Report the Klipper host software status.","title":"STATUS"},{"location":"G-Codes.html#help","text":"HELP : Report the list of available extended G-Code commands.","title":"HELP"},{"location":"G-Codes.html#gcode_arcs","text":"The following standard G-Code commands are available if a gcode_arcs config section is enabled: Arc Move Clockwise (G2), Arc Move Counter-clockwise (G3): G2|G3 [X<pos>] [Y<pos>] [Z<pos>] [E<pos>] [F<speed>] I<value> J<value>|I<value> K<value>|J<value> K<value> Arc Plane Select: G17 (XY plane), G18 (XZ plane), G19 (YZ plane)","title":"[gcode_arcs]"},{"location":"G-Codes.html#gcode_macro","text":"The following command is available when a gcode_macro config section is enabled (also see the command templates guide ).","title":"[gcode_macro]"},{"location":"G-Codes.html#set_gcode_variable","text":"SET_GCODE_VARIABLE MACRO=<macro_name> VARIABLE=<name> VALUE=<value> : This command allows one to change the value of a gcode_macro variable at run-time. The provided VALUE is parsed as a Python literal.","title":"SET_GCODE_VARIABLE"},{"location":"G-Codes.html#gcode_move","text":"The gcode_move module is automatically loaded.","title":"[gcode_move]"},{"location":"G-Codes.html#get_position","text":"GET_POSITION : Return information on the current location of the toolhead. See the developer documentation of GET_POSITION output for more information.","title":"GET_POSITION"},{"location":"G-Codes.html#set_gcode_offset","text":"SET_GCODE_OFFSET [X=<pos>|X_ADJUST=<adjust>] [Y=<pos>|Y_ADJUST=<adjust>] [Z=<pos>|Z_ADJUST=<adjust>] [MOVE=1 [MOVE_SPEED=<speed>]] : Set a positional offset to apply to future G-Code commands. This is commonly used to virtually change the Z bed offset or to set nozzle XY offsets when switching extruders. For example, if \"SET_GCODE_OFFSET Z=0.2\" is sent, then future G-Code moves will have 0.2mm added to their Z height. If the X_ADJUST style parameters are used, then the adjustment will be added to any existing offset (eg, \"SET_GCODE_OFFSET Z=-0.2\" followed by \"SET_GCODE_OFFSET Z_ADJUST=0.3\" would result in a total Z offset of 0.1). If \"MOVE=1\" is specified then a toolhead move will be issued to apply the given offset (otherwise the offset will take effect on the next absolute G-Code move that specifies the given axis). If \"MOVE_SPEED\" is specified then the toolhead move will be performed with the given speed (in mm/s); otherwise the toolhead move will use the last specified G-Code speed.","title":"SET_GCODE_OFFSET"},{"location":"G-Codes.html#save_gcode_state","text":"SAVE_GCODE_STATE [NAME=<state_name>] : Save the current g-code coordinate parsing state. Saving and restoring the g-code state is useful in scripts and macros. This command saves the current g-code absolute coordinate mode (G90/G91), absolute extrude mode (M82/M83), origin (G92), offset (SET_GCODE_OFFSET), speed override (M220), extruder override (M221), move speed, current XYZ position, and relative extruder \"E\" position. If NAME is provided it allows one to name the saved state to the given string. If NAME is not provided it defaults to \"default\".","title":"SAVE_GCODE_STATE"},{"location":"G-Codes.html#restore_gcode_state","text":"RESTORE_GCODE_STATE [NAME=<state_name>] [MOVE=1 [MOVE_SPEED=<speed>]] : Restore a state previously saved via SAVE_GCODE_STATE. If \"MOVE=1\" is specified then a toolhead move will be issued to move back to the previous XYZ position. If \"MOVE_SPEED\" is specified then the toolhead move will be performed with the given speed (in mm/s); otherwise the toolhead move will use the restored g-code speed.","title":"RESTORE_GCODE_STATE"},{"location":"G-Codes.html#generic_cartesian","text":"The commands in this section become automatically available when kinematics: generic_cartesian is specified as the printer kinematics.","title":"[generic_cartesian]"},{"location":"G-Codes.html#set_stepper_carriages","text":"SET_STEPPER_CARRIAGES STEPPER=<stepper_name> CARRIAGES=<carriages> [DISABLE_CHECKS=[0|1]] : Set or update the stepper carriages. <stepper_name> must reference an existing stepper defined in printer.cfg , and <carriages> describes the carriages the stepper moves. See Generic Cartesian Kinematics for a more detailed overview of the carriages parameter in the stepper configuration section. Note that it is only possible to change the coefficients or signs of the carriages with this command, but a user cannot add or remove the carriages that the stepper controls. SET_STEPPER_CARRIAGES is an advanced tool, and the user is advised to exercise an extreme caution using it, since specifying incorrect configuration may physically damage the printer. Note that SET_STEPPER_CARRIAGES performs certain internal validations of the new printer kinematics after the change. Keep in mind that if it detects an issue, it may leave printer kinematics in an invalid state. This means that if SET_STEPPER_CARRIAGES reports an error, it is unsafe to issue other GCode commands, and the user must inspect the error message and either fix the problem, or manually restore the previous stepper(s) configuration. Since SET_STEPPER_CARRIAGES can update a configuration of a single stepper at a time, some sequences of changes can lead to invalid intermediate kinematic configurations, even if the final configuration is valid. In such cases a user can pass DISABLE_CHECKS=1 parameters to all but the last command to disable intermediate checks. For example, if stepper a and stepper b initially have x-y and x+y carriages correspondingly, then the following sequence of commands will let a user effectively swap the carriage controls: SET_STEPPER_CARRIAGES STEPPER=a CARRIAGES=x+y DISABLE_CHECKS=1 and SET_STEPPER_CARRIAGES STEPPER=b CARRIAGES=x-y , while still validating the final kinematics state.","title":"SET_STEPPER_CARRIAGES"},{"location":"G-Codes.html#hall_filament_width_sensor","text":"The following commands are available when the tsl1401cl filament width sensor config section or hall filament width sensor config section is enabled (also see TSLl401CL Filament Width Sensor and Hall Filament Width Sensor ):","title":"[hall_filament_width_sensor]"},{"location":"G-Codes.html#query_filament_width","text":"QUERY_FILAMENT_WIDTH : Return the current measured filament width.","title":"QUERY_FILAMENT_WIDTH"},{"location":"G-Codes.html#reset_filament_width_sensor","text":"RESET_FILAMENT_WIDTH_SENSOR : Clear all sensor readings. Helpful after filament change.","title":"RESET_FILAMENT_WIDTH_SENSOR"},{"location":"G-Codes.html#disable_filament_width_sensor","text":"DISABLE_FILAMENT_WIDTH_SENSOR : Turn off the filament width sensor and stop using it for flow control.","title":"DISABLE_FILAMENT_WIDTH_SENSOR"},{"location":"G-Codes.html#enable_filament_width_sensor","text":"ENABLE_FILAMENT_WIDTH_SENSOR : Turn on the filament width sensor and start using it for flow control.","title":"ENABLE_FILAMENT_WIDTH_SENSOR"},{"location":"G-Codes.html#query_raw_filament_width","text":"QUERY_RAW_FILAMENT_WIDTH : Return the current ADC channel readings and RAW sensor value for calibration points.","title":"QUERY_RAW_FILAMENT_WIDTH"},{"location":"G-Codes.html#enable_filament_width_log","text":"ENABLE_FILAMENT_WIDTH_LOG : Turn on diameter logging.","title":"ENABLE_FILAMENT_WIDTH_LOG"},{"location":"G-Codes.html#disable_filament_width_log","text":"DISABLE_FILAMENT_WIDTH_LOG : Turn off diameter logging.","title":"DISABLE_FILAMENT_WIDTH_LOG"},{"location":"G-Codes.html#heaters","text":"The heaters module is automatically loaded if a heater is defined in the config file.","title":"[heaters]"},{"location":"G-Codes.html#turn_off_heaters","text":"TURN_OFF_HEATERS : Turn off all heaters.","title":"TURN_OFF_HEATERS"},{"location":"G-Codes.html#temperature_wait","text":"TEMPERATURE_WAIT SENSOR=<config_name> [MINIMUM=<target>] [MAXIMUM=<target>] : Wait until the given temperature sensor is at or above the supplied MINIMUM and/or at or below the supplied MAXIMUM.","title":"TEMPERATURE_WAIT"},{"location":"G-Codes.html#set_heater_temperature","text":"SET_HEATER_TEMPERATURE HEATER=<heater_name> [TARGET=<target_temperature>] : Sets the target temperature for a heater. If a target temperature is not supplied, the target is 0.","title":"SET_HEATER_TEMPERATURE"},{"location":"G-Codes.html#idle_timeout","text":"The idle_timeout module is automatically loaded.","title":"[idle_timeout]"},{"location":"G-Codes.html#set_idle_timeout","text":"SET_IDLE_TIMEOUT [TIMEOUT=<timeout>] : Allows the user to set the idle timeout (in seconds).","title":"SET_IDLE_TIMEOUT"},{"location":"G-Codes.html#input_shaper","text":"The following command is enabled if an input_shaper config section has been enabled (also see the resonance compensation guide ).","title":"[input_shaper]"},{"location":"G-Codes.html#set_input_shaper","text":"SET_INPUT_SHAPER [SHAPER_FREQ_X=<shaper_freq_x>] [SHAPER_FREQ_Y=<shaper_freq_y>] [DAMPING_RATIO_X=<damping_ratio_x>] [DAMPING_RATIO_Y=<damping_ratio_y>] [SHAPER_TYPE=<shaper>] [SHAPER_TYPE_X=<shaper_type_x>] [SHAPER_TYPE_Y=<shaper_type_y>] : Modify input shaper parameters. Note that SHAPER_TYPE parameter resets input shaper for both X and Y axes even if different shaper types have been configured in [input_shaper] section. SHAPER_TYPE cannot be used together with either of SHAPER_TYPE_X and SHAPER_TYPE_Y parameters. See config reference for more details on each of these parameters.","title":"SET_INPUT_SHAPER"},{"location":"G-Codes.html#led","text":"The following command is available when any of the led config sections are enabled.","title":"[led]"},{"location":"G-Codes.html#set_led","text":"SET_LED LED=<config_name> RED=<value> GREEN=<value> BLUE=<value> WHITE=<value> [INDEX=<index>] [TRANSMIT=0] [SYNC=1] : This sets the LED output. Each color <value> must be between 0.0 and 1.0. The WHITE option is only valid on RGBW LEDs. If the LED supports multiple chips in a daisy-chain then one may specify INDEX to alter the color of just the given chip (1 for the first chip, 2 for the second, etc.). If INDEX is not provided then all LEDs in the daisy-chain will be set to the provided color. If TRANSMIT=0 is specified then the color change will only be made on the next SET_LED command that does not specify TRANSMIT=0; this may be useful in combination with the INDEX parameter to batch multiple updates in a daisy-chain. By default, the SET_LED command will sync it's changes with other ongoing gcode commands. This can lead to undesirable behavior if LEDs are being set while the printer is not printing as it will reset the idle timeout. If careful timing is not needed, the optional SYNC=0 parameter can be specified to apply the changes without resetting the idle timeout.","title":"SET_LED"},{"location":"G-Codes.html#set_led_template","text":"SET_LED_TEMPLATE LED=<led_name> TEMPLATE=<template_name> [<param_x>=<literal>] [INDEX=<index>] : Assign a display_template to a given LED . For example, if one defined a [display_template my_led_template] config section then one could assign TEMPLATE=my_led_template here. The display_template should produce a comma separated string containing four floating point numbers corresponding to red, green, blue, and white color settings. The template will be continuously evaluated and the LED will be automatically set to the resulting colors. One may set display_template parameters to use during template evaluation (parameters will be parsed as Python literals). If INDEX is not specified then all chips in the LED's daisy-chain will be set to the template, otherwise only the chip with the given index will be updated. If TEMPLATE is an empty string then this command will clear any previous template assigned to the LED (one can then use SET_LED commands to manage the LED's color settings).","title":"SET_LED_TEMPLATE"},{"location":"G-Codes.html#load_cell","text":"The following commands are enabled if a load_cell config section has been enabled.","title":"[load_cell]"},{"location":"G-Codes.html#load_cell_diagnostic","text":"LOAD_CELL_DIAGNOSTIC [LOAD_CELL=<config_name>] : This command collects 10 seconds of load cell data and reports statistics that can help you verify proper operation of the load cell. This command can be run on both calibrated and uncalibrated load cells.","title":"LOAD_CELL_DIAGNOSTIC"},{"location":"G-Codes.html#load_cell_calibrate","text":"LOAD_CELL_CALIBRATE [LOAD_CELL=<config_name>] : Start the guided calibration utility. Calibration is a 3 step process: First you remove all load from the load cell and run the TARE command Next you apply a known load to the load cell and run the CALIBRATE GRAMS=nnn command Finally use the ACCEPT command to save the results You can cancel the calibration process at any time with ABORT .","title":"LOAD_CELL_CALIBRATE"},{"location":"G-Codes.html#load_cell_tare","text":"LOAD_CELL_TARE [LOAD_CELL=<config_name>] : This works just like the tare button on digital scale. It sets the current raw reading of the load cell to be the zero point reference value. The response is the percentage of the sensors range that was read and the raw value in counts. If the load cell is calibrated a force in grams is also reported.","title":"LOAD_CELL_TARE"},{"location":"G-Codes.html#load_cell_read-load_cellname","text":"LOAD_CELL_READ [LOAD_CELL=<config_name>] : This command takes a reading from the load cell. The response is the percentage of the sensors range that was read and the raw value in counts. If the load cell is calibrated a force in grams is also reported.","title":"LOAD_CELL_READ load_cell=\"name\""},{"location":"G-Codes.html#load_cell_probe","text":"The following commands are enabled if a load_cell config section has been enabled.","title":"[load_cell_probe]"},{"location":"G-Codes.html#load_cell_test_tap","text":"LOAD_CELL_TEST_TAP [TAPS=<taps>] [TIMEOUT=<timeout>] : Run a testing routine that reports taps on the load cell. The toolhead will not move but the load cell probe will sense taps just as if it was probing. This can be used as a sanity check to make sure that the probe works. This tool replaces QUERY_ENDSTOPS and QUERY_PROBE for load cell probes. TAPS : the number of taps the tool expects TIMEOOUT : the time, in seconds, that the tool waits for each tab before aborting.","title":"LOAD_CELL_TEST_TAP"},{"location":"G-Codes.html#load-cell-command-extensions","text":"Commands that perform probes, such as PROBE , PROBE_ACCURACY , BED_MESH_CALIBRATE etc. will accept additional parameters if a [load_cell_probe] is defined. The parameters override the corresponding settings from the [load_cell_probe] configuration: FORCE_SAFETY_LIMIT=<grams> TRIGGER_FORCE=<grams> DRIFT_FILTER_CUTOFF_FREQUENCY=<frequency_hz> DRIFT_FILTER_DELAY=<1|2> BUZZ_FILTER_CUTOFF_FREQUENCY=<frequency_hz> BUZZ_FILTER_DELAY=<1|2> NOTCH_FILTER_FREQUENCIES=<list of frequency_hz> NOTCH_FILTER_QUALITY=<quality> TARE_TIME=<seconds>","title":"Load Cell Command Extensions"},{"location":"G-Codes.html#manual_probe","text":"The manual_probe module is automatically loaded.","title":"[manual_probe]"},{"location":"G-Codes.html#manual_probe_1","text":"MANUAL_PROBE [SPEED=<speed>] : Run a helper script useful for measuring the height of the nozzle at a given location. If SPEED is specified, it sets the speed of TESTZ commands (the default is 5mm/s). During a manual probe, the following additional commands are available: ACCEPT : This command accepts the current Z position and concludes the manual probing tool. ABORT : This command terminates the manual probing tool. TESTZ Z=<value> : This command moves the nozzle up or down by the amount specified in \"value\". For example, TESTZ Z=-.1 would move the nozzle down .1mm while TESTZ Z=.1 would move the nozzle up .1mm. The value may also be + , - , ++ , or -- to move the nozzle up or down an amount relative to previous attempts.","title":"MANUAL_PROBE"},{"location":"G-Codes.html#z_endstop_calibrate","text":"Z_ENDSTOP_CALIBRATE [SPEED=<speed>] : Run a helper script useful for calibrating a Z position_endstop config setting. See the MANUAL_PROBE command for details on the parameters and the additional commands available while the tool is active.","title":"Z_ENDSTOP_CALIBRATE"},{"location":"G-Codes.html#z_offset_apply_endstop","text":"Z_OFFSET_APPLY_ENDSTOP : Take the current Z Gcode offset (aka, babystepping), and subtract it from the stepper_z endstop_position. This acts to take a frequently used babystepping value, and \"make it permanent\". Requires a SAVE_CONFIG to take effect.","title":"Z_OFFSET_APPLY_ENDSTOP"},{"location":"G-Codes.html#manual_stepper","text":"The following command is available when a manual_stepper config section is enabled.","title":"[manual_stepper]"},{"location":"G-Codes.html#manual_stepper_1","text":"MANUAL_STEPPER STEPPER=config_name [ENABLE=[0|1]] [SET_POSITION=<pos>] [SPEED=<speed>] [ACCEL=<accel>] [MOVE=<pos> [STOP_ON_ENDSTOP=[1|2|-1|-2]] [SYNC=0]] : This command will alter the state of the stepper. Use the ENABLE parameter to enable/disable the stepper. Use the SET_POSITION parameter to force the stepper to think it is at the given position. Use the MOVE parameter to request a movement to the given position. If SPEED and/or ACCEL is specified then the given values will be used instead of the defaults specified in the config file. If an ACCEL of zero is specified then no acceleration will be performed. If STOP_ON_ENDSTOP=1 is specified then the move will end early should the endstop report as triggered (use STOP_ON_ENDSTOP=2 to complete the move without error even if the endstop does not trigger, use -1 or -2 to stop when the endstop reports not triggered). Normally future G-Code commands will be scheduled to run after the stepper move completes, however if a manual stepper move uses SYNC=0 then future G-Code movement commands may run in parallel with the stepper movement. MANUAL_STEPPER STEPPER=config_name GCODE_AXIS=[A-Z] [LIMIT_VELOCITY=<velocity>] [LIMIT_ACCEL=<accel>] [INSTANTANEOUS_CORNER_VELOCITY=<velocity>] : If the GCODE_AXIS parameter is specified then it configures the stepper motor as an extra axis on G1 move commands. For example, if one were to issue a MANUAL_STEPPER ... GCODE_AXIS=R command then one could issue commands like G1 X10 Y20 R30 to move the stepper motor. The resulting moves will occur synchronously with the associated toolhead xyz movements. If the motor is associated with a GCODE_AXIS then one may no longer issue movements using the above MANUAL_STEPPER command - one may unregister the stepper with a MANUAL_STEPPER ... GCODE_AXIS= command to resume manual control of the motor. The LIMIT_VELOCITY and LIMIT_ACCEL parameters allow one to reduce the speed of G1 moves if those moves would result in a velocity or acceleration above the specified limits. The INSTANTANEOUS_CORNER_VELOCITY specifies the maximum instantaneous velocity change (in mm/s) of the motor during the junction of two moves (the default is 1mm/s).","title":"MANUAL_STEPPER"},{"location":"G-Codes.html#mcp4018","text":"The following command is available when a mcp4018 config section is enabled.","title":"[mcp4018]"},{"location":"G-Codes.html#set_digipot","text":"SET_DIGIPOT DIGIPOT=config_name WIPER=<value> : This command will change the current value of the digipot. This value should typically be between 0.0 and 1.0, unless a 'scale' is defined in the config. When 'scale' is defined, then this value should be between 0.0 and 'scale'.","title":"SET_DIGIPOT"},{"location":"G-Codes.html#output_pin","text":"The following command is available when an output_pin config section or pwm_tool config section is enabled.","title":"[output_pin]"},{"location":"G-Codes.html#set_pin","text":"SET_PIN PIN=config_name VALUE=<value> : Set the pin to the given output VALUE . VALUE should be 0 or 1 for \"digital\" output pins. For PWM pins, set to a value between 0.0 and 1.0, or between 0.0 and scale if a scale is configured in the output_pin config section. SET_PIN PIN=config_name TEMPLATE=<template_name> [<param_x>=<literal>] : If TEMPLATE is specified then it assigns a display_template to the given pin. For example, if one defined a [display_template my_pin_template] config section then one could assign TEMPLATE=my_pin_template here. The display_template should produce a string containing a floating point number with the desired value. The template will be continuously evaluated and the pin will be automatically set to the resulting value. One may set display_template parameters to use during template evaluation (parameters will be parsed as Python literals). If TEMPLATE is an empty string then this command will clear any previous template assigned to the pin (one can then use SET_PIN commands to manage the values directly).","title":"SET_PIN"},{"location":"G-Codes.html#palette2","text":"The following commands are available when the palette2 config section is enabled. Palette prints work by embedding special OCodes (Omega Codes) in the GCode file: O1 ... O32 : These codes are read from the GCode stream and processed by this module and passed to the Palette 2 device. The following additional commands are also available.","title":"[palette2]"},{"location":"G-Codes.html#palette_connect","text":"PALETTE_CONNECT : This command initializes the connection with the Palette 2.","title":"PALETTE_CONNECT"},{"location":"G-Codes.html#palette_disconnect","text":"PALETTE_DISCONNECT : This command disconnects from the Palette 2.","title":"PALETTE_DISCONNECT"},{"location":"G-Codes.html#palette_clear","text":"PALETTE_CLEAR : This command instructs the Palette 2 to clear all of the input and output paths of filament.","title":"PALETTE_CLEAR"},{"location":"G-Codes.html#palette_cut","text":"PALETTE_CUT : This command instructs the Palette 2 to cut the filament currently loaded in the splice core.","title":"PALETTE_CUT"},{"location":"G-Codes.html#palette_smart_load","text":"PALETTE_SMART_LOAD : This command start the smart load sequence on the Palette 2. Filament is loaded automatically by extruding it the distance calibrated on the device for the printer, and instructs the Palette 2 once the loading has been completed. This command is the same as pressing Smart Load directly on the Palette 2 screen after the filament load is complete.","title":"PALETTE_SMART_LOAD"},{"location":"G-Codes.html#pause_resume","text":"The following commands are available when the pause_resume config section is enabled:","title":"[pause_resume]"},{"location":"G-Codes.html#pause","text":"PAUSE : Pauses the current print. The current position is captured for restoration upon resume.","title":"PAUSE"},{"location":"G-Codes.html#resume","text":"RESUME [VELOCITY=<value>] : Resumes the print from a pause, first restoring the previously captured position. The VELOCITY parameter determines the speed at which the tool should return to the original captured position.","title":"RESUME"},{"location":"G-Codes.html#clear_pause","text":"CLEAR_PAUSE : Clears the current paused state without resuming the print. This is useful if one decides to cancel a print after a PAUSE. It is recommended to add this to your start gcode to make sure the paused state is fresh for each print.","title":"CLEAR_PAUSE"},{"location":"G-Codes.html#cancel_print","text":"CANCEL_PRINT : Cancels the current print.","title":"CANCEL_PRINT"},{"location":"G-Codes.html#pid_calibrate","text":"The pid_calibrate module is automatically loaded if a heater is defined in the config file.","title":"[pid_calibrate]"},{"location":"G-Codes.html#pid_calibrate_1","text":"PID_CALIBRATE HEATER=<config_name> TARGET=<temperature> [WRITE_FILE=1] : Perform a PID calibration test. The specified heater will be enabled until the specified target temperature is reached, and then the heater will be turned off and on for several cycles. If the WRITE_FILE parameter is enabled, then the file /tmp/heattest.txt will be created with a log of all temperature samples taken during the test.","title":"PID_CALIBRATE"},{"location":"G-Codes.html#print_stats","text":"The print_stats module is automatically loaded.","title":"[print_stats]"},{"location":"G-Codes.html#set_print_stats_info","text":"SET_PRINT_STATS_INFO [TOTAL_LAYER=<total_layer_count>] [CURRENT_LAYER= <current_layer>] : Pass slicer info like layer act and total to Klipper. Add SET_PRINT_STATS_INFO [TOTAL_LAYER=<total_layer_count>] to your slicer start gcode section and SET_PRINT_STATS_INFO [CURRENT_LAYER= <current_layer>] at the layer change gcode section to pass layer information from your slicer to Klipper.","title":"SET_PRINT_STATS_INFO"},{"location":"G-Codes.html#probe","text":"The following commands are available when a probe config section or bltouch config section is enabled (also see the probe calibrate guide ).","title":"[probe]"},{"location":"G-Codes.html#probe_1","text":"PROBE [PROBE_SPEED=<mm/s>] [LIFT_SPEED=<mm/s>] [SAMPLES=<count>] [SAMPLE_RETRACT_DIST=<mm>] [SAMPLES_TOLERANCE=<mm>] [SAMPLES_TOLERANCE_RETRIES=<count>] [SAMPLES_RESULT=median|average] : Move the nozzle downwards until the probe triggers. If any of the optional parameters are provided they override their equivalent setting in the probe config section .","title":"PROBE"},{"location":"G-Codes.html#query_probe","text":"QUERY_PROBE : Report the current status of the probe (\"triggered\" or \"open\").","title":"QUERY_PROBE"},{"location":"G-Codes.html#probe_accuracy","text":"PROBE_ACCURACY [PROBE_SPEED=<mm/s>] [SAMPLES=<count>] [SAMPLE_RETRACT_DIST=<mm>] : Calculate the maximum, minimum, average, median, and standard deviation of multiple probe samples. By default, 10 SAMPLES are taken. Otherwise the optional parameters default to their equivalent setting in the probe config section.","title":"PROBE_ACCURACY"},{"location":"G-Codes.html#probe_calibrate","text":"PROBE_CALIBRATE [SPEED=<speed>] [<probe_parameter>=<value>] : Run a helper script useful for calibrating the probe's z_offset. See the PROBE command for details on the optional probe parameters. See the MANUAL_PROBE command for details on the SPEED parameter and the additional commands available while the tool is active. Please note, the PROBE_CALIBRATE command uses the speed variable to move in XY direction as well as Z.","title":"PROBE_CALIBRATE"},{"location":"G-Codes.html#z_offset_apply_probe","text":"Z_OFFSET_APPLY_PROBE : Take the current Z Gcode offset (aka, babystepping), and subtract if from the probe's z_offset. This acts to take a frequently used babystepping value, and \"make it permanent\". Requires a SAVE_CONFIG to take effect.","title":"Z_OFFSET_APPLY_PROBE"},{"location":"G-Codes.html#probe_eddy_current","text":"The following commands are available when a probe_eddy_current config section is enabled.","title":"[probe_eddy_current]"},{"location":"G-Codes.html#probe_eddy_current_calibrate","text":"PROBE_EDDY_CURRENT_CALIBRATE CHIP=<config_name> : This starts a tool that calibrates the sensor resonance frequencies to corresponding Z heights. The tool will take a couple of minutes to complete. After completion, use the SAVE_CONFIG command to store the results in the printer.cfg file.","title":"PROBE_EDDY_CURRENT_CALIBRATE"},{"location":"G-Codes.html#ldc_calibrate_drive_current","text":"LDC_CALIBRATE_DRIVE_CURRENT CHIP=<config_name> This tool will calibrate the ldc1612 DRIVE_CURRENT0 register. Prior to using this tool, move the sensor so that it is near the center of the bed and about 20mm above the bed surface. Run this command to determine an appropriate DRIVE_CURRENT for the sensor. After running this command use the SAVE_CONFIG command to store that new setting in the printer.cfg config file.","title":"LDC_CALIBRATE_DRIVE_CURRENT"},{"location":"G-Codes.html#pwm_cycle_time","text":"The following command is available when a pwm_cycle_time config section is enabled.","title":"[pwm_cycle_time]"},{"location":"G-Codes.html#set_pin_1","text":"SET_PIN PIN=config_name VALUE=<value> [CYCLE_TIME=<cycle_time>] : This command works similarly to output_pin SET_PIN commands. The command here supports setting an explicit cycle time using the CYCLE_TIME parameter (specified in seconds). Note that the CYCLE_TIME parameter is not stored between SET_PIN commands (any SET_PIN command without an explicit CYCLE_TIME parameter will use the cycle_time specified in the pwm_cycle_time config section).","title":"SET_PIN"},{"location":"G-Codes.html#quad_gantry_level","text":"The following commands are available when the quad_gantry_level config section is enabled.","title":"[quad_gantry_level]"},{"location":"G-Codes.html#quad_gantry_level_1","text":"QUAD_GANTRY_LEVEL [RETRIES=<value>] [RETRY_TOLERANCE=<value>] [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>] : This command will probe the points specified in the config and then make independent adjustments to each Z stepper to compensate for tilt. See the PROBE command for details on the optional probe parameters. The optional RETRIES , RETRY_TOLERANCE , and HORIZONTAL_MOVE_Z values override those options specified in the config file.","title":"QUAD_GANTRY_LEVEL"},{"location":"G-Codes.html#query_adc","text":"The query_adc module is automatically loaded.","title":"[query_adc]"},{"location":"G-Codes.html#query_adc_1","text":"QUERY_ADC [NAME=<config_name>] [PULLUP=<value>] : Report the last analog value received for a configured analog pin. If NAME is not provided, the list of available adc names are reported. If PULLUP is provided (as a value in Ohms), the raw analog value along with the equivalent resistance given that pullup is reported.","title":"QUERY_ADC"},{"location":"G-Codes.html#query_endstops","text":"The query_endstops module is automatically loaded. The following standard G-Code commands are currently available, but using them is not recommended: Get Endstop Status: M119 (Use QUERY_ENDSTOPS instead.)","title":"[query_endstops]"},{"location":"G-Codes.html#query_endstops_1","text":"QUERY_ENDSTOPS : Probe the axis endstops and report if they are \"triggered\" or in an \"open\" state. This command is typically used to verify that an endstop is working correctly.","title":"QUERY_ENDSTOPS"},{"location":"G-Codes.html#resonance_tester","text":"The following commands are available when a resonance_tester config section is enabled (also see the measuring resonances guide ).","title":"[resonance_tester]"},{"location":"G-Codes.html#measure_axes_noise","text":"MEASURE_AXES_NOISE : Measures and outputs the noise for all axes of all enabled accelerometer chips.","title":"MEASURE_AXES_NOISE"},{"location":"G-Codes.html#test_resonances","text":"TEST_RESONANCES AXIS=<axis> [OUTPUT=<resonances,raw_data>] [NAME=<name>] [FREQ_START=<min_freq>] [FREQ_END=<max_freq>] [ACCEL_PER_HZ=<accel_per_hz>] [HZ_PER_SEC=<hz_per_sec>] [CHIPS=<chip_name>] [POINT=x,y,z] [INPUT_SHAPING=<0:1>] : Runs the resonance test in all configured probe points for the requested \"axis\" and measures the acceleration using the accelerometer chips configured for the respective axis. \"axis\" can either be X or Y, or specify an arbitrary direction as AXIS=dx,dy , where dx and dy are floating point numbers defining a direction vector (e.g. AXIS=X , AXIS=Y , or AXIS=1,-1 to define a diagonal direction). Note that AXIS=dx,dy and AXIS=-dx,-dy is equivalent. chip_name can be one or more configured accel chips, delimited with comma, for example CHIPS=\"adxl345, adxl345 rpi\" . If POINT is specified it will override the point(s) configured in [resonance_tester] . If INPUT_SHAPING=0 or not set(default), disables input shaping for the resonance testing, because it is not valid to run the resonance testing with the input shaper enabled. OUTPUT parameter is a comma-separated list of which outputs will be written. If raw_data is requested, then the raw accelerometer data is written into a file or a series of files /tmp/raw_data_<axis>_[<chip_name>_][<point>_]<name>.csv with ( <point>_ part of the name generated only if more than 1 probe point is configured or POINT is specified). If resonances is specified, the frequency response is calculated (across all probe points) and written into /tmp/resonances_<axis>_<name>.csv file. If unset, OUTPUT defaults to resonances , and NAME defaults to the current time in \"YYYYMMDD_HHMMSS\" format.","title":"TEST_RESONANCES"},{"location":"G-Codes.html#shaper_calibrate","text":"SHAPER_CALIBRATE [AXIS=<axis>] [NAME=<name>] [FREQ_START=<min_freq>] [FREQ_END=<max_freq>] [ACCEL_PER_HZ=<accel_per_hz>][HZ_PER_SEC=<hz_per_sec>] [CHIPS=<chip_name>] [MAX_SMOOTHING=<max_smoothing>] [INPUT_SHAPING=<0:1>] : Similarly to TEST_RESONANCES , runs the resonance test as configured, and tries to find the optimal parameters for the input shaper for the requested axis (or both X and Y axes if AXIS parameter is unset). If MAX_SMOOTHING is unset, its value is taken from [resonance_tester] section, with the default being unset. See the Max smoothing of the measuring resonances guide for more information on the use of this feature. The results of the tuning are printed to the console, and the frequency responses and the different input shapers values are written to a CSV file(s) /tmp/calibration_data_<axis>_<name>.csv . Unless specified, NAME defaults to the current time in \"YYYYMMDD_HHMMSS\" format. Note that the suggested input shaper parameters can be persisted in the config by issuing SAVE_CONFIG command, and if [input_shaper] was already enabled previously, these parameters take effect immediately.","title":"SHAPER_CALIBRATE"},{"location":"G-Codes.html#respond","text":"The following standard G-Code commands are available when the respond config section is enabled: M118 <message> : echo the message prepended with the configured default prefix (or echo: if no prefix is configured). The following additional commands are also available.","title":"[respond]"},{"location":"G-Codes.html#respond_1","text":"RESPOND MSG=\"<message>\" : echo the message prepended with the configured default prefix (or echo: if no prefix is configured). RESPOND TYPE=echo MSG=\"<message>\" : echo the message prepended with echo: . RESPOND TYPE=echo_no_space MSG=\"<message>\" : echo the message prepended with echo: without a space between prefix and message, helpful for compatibility with some octoprint plugins that expect very specific formatting. RESPOND TYPE=command MSG=\"<message>\" : echo the message prepended with // . OctoPrint can be configured to respond to these messages (e.g. RESPOND TYPE=command MSG=action:pause ). RESPOND TYPE=error MSG=\"<message>\" : echo the message prepended with !! . RESPOND PREFIX=<prefix> MSG=\"<message>\" : echo the message prepended with <prefix> . (The PREFIX parameter will take priority over the TYPE parameter)","title":"RESPOND"},{"location":"G-Codes.html#save_variables","text":"The following command is enabled if a save_variables config section has been enabled.","title":"[save_variables]"},{"location":"G-Codes.html#save_variable","text":"SAVE_VARIABLE VARIABLE=<name> VALUE=<value> : Saves the variable to disk so that it can be used across restarts. The VARIABLE must be lowercase. All stored variables are loaded into the printer.save_variables.variables dict at startup and can be used in gcode macros. The provided VALUE is parsed as a Python literal.","title":"SAVE_VARIABLE"},{"location":"G-Codes.html#screws_tilt_adjust","text":"The following commands are available when the screws_tilt_adjust config section is enabled (also see the manual level guide ).","title":"[screws_tilt_adjust]"},{"location":"G-Codes.html#screws_tilt_calculate","text":"SCREWS_TILT_CALCULATE [DIRECTION=CW|CCW] [MAX_DEVIATION=<value>] [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>] : This command will invoke the bed screws adjustment tool. It will command the nozzle to different locations (as defined in the config file) probing the z height and calculate the number of knob turns to adjust the bed level. If DIRECTION is specified, the knob turns will all be in the same direction, clockwise (CW) or counterclockwise (CCW). See the PROBE command for details on the optional probe parameters. IMPORTANT: You MUST always do a G28 before using this command. If MAX_DEVIATION is specified, the command will raise a gcode error if any difference in the screw height relative to the base screw height is greater than the value provided. The optional HORIZONTAL_MOVE_Z value overrides the horizontal_move_z option specified in the config file.","title":"SCREWS_TILT_CALCULATE"},{"location":"G-Codes.html#sdcard_loop","text":"When the sdcard_loop config section is enabled, the following extended commands are available.","title":"[sdcard_loop]"},{"location":"G-Codes.html#sdcard_loop_begin","text":"SDCARD_LOOP_BEGIN COUNT=<count> : Begin a looped section in the SD print. A count of 0 indicates that the section should be looped indefinitely.","title":"SDCARD_LOOP_BEGIN"},{"location":"G-Codes.html#sdcard_loop_end","text":"SDCARD_LOOP_END : End a looped section in the SD print.","title":"SDCARD_LOOP_END"},{"location":"G-Codes.html#sdcard_loop_desist","text":"SDCARD_LOOP_DESIST : Complete existing loops without further iterations.","title":"SDCARD_LOOP_DESIST"},{"location":"G-Codes.html#servo","text":"The following commands are available when a servo config section is enabled.","title":"[servo]"},{"location":"G-Codes.html#set_servo","text":"SET_SERVO SERVO=config_name [ANGLE=<degrees> | WIDTH=<seconds>] : Set the servo position to the given angle (in degrees) or pulse width (in seconds). Use WIDTH=0 to disable the servo output.","title":"SET_SERVO"},{"location":"G-Codes.html#skew_correction","text":"The following commands are available when the skew_correction config section is enabled (also see the Skew Correction guide).","title":"[skew_correction]"},{"location":"G-Codes.html#set_skew","text":"SET_SKEW [XY=<ac_length,bd_length,ad_length>] [XZ=<ac,bd,ad>] [YZ=<ac,bd,ad>] [CLEAR=<0|1>] : Configures the [skew_correction] module with measurements (in mm) taken from a calibration print. One may enter measurements for any combination of planes, planes not entered will retain their current value. If CLEAR=1 is entered then all skew correction will be disabled.","title":"SET_SKEW"},{"location":"G-Codes.html#get_current_skew","text":"GET_CURRENT_SKEW : Reports the current printer skew for each plane in both radians and degrees. The skew is calculated based on parameters provided via the SET_SKEW gcode.","title":"GET_CURRENT_SKEW"},{"location":"G-Codes.html#calc_measured_skew","text":"CALC_MEASURED_SKEW [AC=<ac_length>] [BD=<bd_length>] [AD=<ad_length>] : Calculates and reports the skew (in radians and degrees) based on a measured print. This can be useful for determining the printer's current skew after correction has been applied. It may also be useful before correction is applied to determine if skew correction is necessary. See Skew Correction for details on skew calibration objects and measurements.","title":"CALC_MEASURED_SKEW"},{"location":"G-Codes.html#skew_profile","text":"SKEW_PROFILE [LOAD=<name>] [SAVE=<name>] [REMOVE=<name>] : Profile management for skew_correction. LOAD will restore skew state from the profile matching the supplied name. SAVE will save the current skew state to a profile matching the supplied name. Remove will delete the profile matching the supplied name from persistent memory. Note that after SAVE or REMOVE operations have been run the SAVE_CONFIG gcode must be run to make the changes to persistent memory permanent.","title":"SKEW_PROFILE"},{"location":"G-Codes.html#smart_effector","text":"Several commands are available when a smart_effector config section is enabled. Be sure to check the official documentation for the Smart Effector on the Duet3D Wiki before changing the Smart Effector parameters. Also check the probe calibration guide .","title":"[smart_effector]"},{"location":"G-Codes.html#set_smart_effector","text":"SET_SMART_EFFECTOR [SENSITIVITY=<sensitivity>] [ACCEL=<accel>] [RECOVERY_TIME=<time>] : Set the Smart Effector parameters. When SENSITIVITY is specified, the respective value is written to the SmartEffector EEPROM (requires control_pin to be provided). Acceptable <sensitivity> values are 0..255, the default is 50. Lower values require less nozzle contact force to trigger (but there is a higher risk of false triggering due to vibrations during probing), and higher values reduce false triggering (but require larger contact force to trigger). Since the sensitivity is written to EEPROM, it is preserved after the shutdown, and so it does not need to be configured on every printer startup. ACCEL and RECOVERY_TIME allow to override the corresponding parameters at run-time, see the config section of Smart Effector for more info on those parameters.","title":"SET_SMART_EFFECTOR"},{"location":"G-Codes.html#reset_smart_effector","text":"RESET_SMART_EFFECTOR : Resets Smart Effector sensitivity to its factory settings. Requires control_pin to be provided in the config section.","title":"RESET_SMART_EFFECTOR"},{"location":"G-Codes.html#stepper_enable","text":"The stepper_enable module is automatically loaded.","title":"[stepper_enable]"},{"location":"G-Codes.html#set_stepper_enable","text":"SET_STEPPER_ENABLE STEPPER=<config_name> ENABLE=[0|1] : Enable or disable only the given stepper. This is a diagnostic and debugging tool and must be used with care. Disabling an axis motor does not reset the homing information. Manually moving a disabled stepper may cause the machine to operate the motor outside of safe limits. This can lead to damage to axis components, hot ends, and print surface.","title":"SET_STEPPER_ENABLE"},{"location":"G-Codes.html#temperature_fan","text":"The following command is available when a temperature_fan config section is enabled.","title":"[temperature_fan]"},{"location":"G-Codes.html#set_temperature_fan_target","text":"SET_TEMPERATURE_FAN_TARGET temperature_fan=<temperature_fan_name> [target=<target_temperature>] [min_speed=<min_speed>] [max_speed=<max_speed>] : Sets the target temperature for a temperature_fan. If a target is not supplied, it is set to the specified temperature in the config file. If speeds are not supplied, no change is applied.","title":"SET_TEMPERATURE_FAN_TARGET"},{"location":"G-Codes.html#temperature_probe","text":"The following commands are available when a temperature_probe config section is enabled.","title":"[temperature_probe]"},{"location":"G-Codes.html#temperature_probe_calibrate","text":"TEMPERATURE_PROBE_CALIBRATE [PROBE=<probe name>] [TARGET=<value>] [STEP=<value>] : Initiates probe drift calibration for eddy current based probes. The TARGET is a target temperature for the last sample. When the temperature recorded during a sample exceeds the TARGET calibration will complete. The STEP parameter sets temperature delta (in C) between samples. After a sample has been taken, this delta is used to schedule a call to TEMPERATURE_PROBE_NEXT . The default STEP is 2.","title":"TEMPERATURE_PROBE_CALIBRATE"},{"location":"G-Codes.html#temperature_probe_next","text":"TEMPERATURE_PROBE_NEXT : After calibration has started this command is run to take the next sample. It is automatically scheduled to run when the delta specified by STEP has been reached, however its also possible to manually run this command to force a new sample. This command is only available during calibration.","title":"TEMPERATURE_PROBE_NEXT"},{"location":"G-Codes.html#temperature_probe_complete","text":"TEMPERATURE_PROBE_COMPLETE : Can be used to end calibration and save the current result before the TARGET temperature is reached. This command is only available during calibration.","title":"TEMPERATURE_PROBE_COMPLETE:"},{"location":"G-Codes.html#abort","text":"ABORT : Aborts the calibration process, discarding the current results. This command is only available during drift calibration.","title":"ABORT"},{"location":"G-Codes.html#temperature_probe_enable","text":"TEMPERATURE_PROBE_ENABLE ENABLE=[0|1] : Sets temperature drift compensation on or off. If ENABLE is set to 0, drift compensation will be disabled, if set to 1 it is enabled.","title":"TEMPERATURE_PROBE_ENABLE"},{"location":"G-Codes.html#tmcxxxx","text":"The following commands are available when any of the tmcXXXX config sections are enabled.","title":"[tmcXXXX]"},{"location":"G-Codes.html#dump_tmc","text":"DUMP_TMC STEPPER=<name> [REGISTER=<name>] : This command will read all TMC driver registers and report their values. If a REGISTER is provided, only the specified register will be dumped.","title":"DUMP_TMC"},{"location":"G-Codes.html#init_tmc","text":"INIT_TMC STEPPER=<name> : This command will initialize the TMC registers. Needed to re-enable the driver if power to the chip is turned off then back on.","title":"INIT_TMC"},{"location":"G-Codes.html#set_tmc_current","text":"SET_TMC_CURRENT STEPPER=<name> CURRENT=<amps> HOLDCURRENT=<amps> : This will adjust the run and hold currents of the TMC driver. HOLDCURRENT is not applicable to tmc2660 drivers. When used on a driver which has the globalscaler field (tmc5160 and tmc2240), if StealthChop2 is used, the stepper must be held at standstill for >130ms so that the driver executes the AT#1 calibration.","title":"SET_TMC_CURRENT"},{"location":"G-Codes.html#set_tmc_field","text":"SET_TMC_FIELD STEPPER=<name> FIELD=<field> VALUE=<value> VELOCITY=<value> : This will alter the value of the specified register field of the TMC driver. This command is intended for low-level diagnostics and debugging only because changing the fields during run-time can lead to undesired and potentially dangerous behavior of your printer. Permanent changes should be made using the printer configuration file instead. No sanity checks are performed for the given values. A VELOCITY can also be specified instead of a VALUE. This velocity is converted to the 20bit TSTEP based value representation. Only use the VELOCITY argument for fields that represent velocities.","title":"SET_TMC_FIELD"},{"location":"G-Codes.html#toolhead","text":"The toolhead module is automatically loaded.","title":"[toolhead]"},{"location":"G-Codes.html#set_velocity_limit","text":"SET_VELOCITY_LIMIT [VELOCITY=<value>] [ACCEL=<value>] [MINIMUM_CRUISE_RATIO=<value>] [SQUARE_CORNER_VELOCITY=<value>] : This command can alter the velocity limits that were specified in the printer config file. See the printer config section for a description of each parameter.","title":"SET_VELOCITY_LIMIT"},{"location":"G-Codes.html#tuning_tower","text":"The tuning_tower module is automatically loaded.","title":"[tuning_tower]"},{"location":"G-Codes.html#tuning_tower_1","text":"TUNING_TOWER COMMAND=<command> PARAMETER=<name> START=<value> [SKIP=<value>] [FACTOR=<value> [BAND=<value>]] | [STEP_DELTA=<value> STEP_HEIGHT=<value>] : A tool for tuning a parameter on each Z height during a print. The tool will run the given COMMAND with the given PARAMETER assigned to a value that varies with Z according to a formula. Use FACTOR if you will use a ruler or calipers to measure the Z height of the optimum value, or STEP_DELTA and STEP_HEIGHT if the tuning tower model has bands of discrete values as is common with temperature towers. If SKIP=<value> is specified, the tuning process doesn't begin until Z height <value> is reached, and below that the value will be set to START ; in this case, the z_height used in the formulas below is actually max(z - skip, 0) . There are three possible combinations of options: FACTOR : The value changes at a rate of factor per millimeter. The formula used is: value = start + factor * z_height . You can plug the optimum Z height directly into the formula to determine the optimum parameter value. FACTOR and BAND : The value changes at an average rate of factor per millimeter, but in discrete bands where the adjustment will only be made every BAND millimeters of Z height. The formula used is: value = start + factor * ((floor(z_height / band) + .5) * band) . STEP_DELTA and STEP_HEIGHT : The value changes by STEP_DELTA every STEP_HEIGHT millimeters. The formula used is: value = start + step_delta * floor(z_height / step_height) . You can simply count bands or read tuning tower labels to determine the optimum value.","title":"TUNING_TOWER"},{"location":"G-Codes.html#virtual_sdcard","text":"Klipper supports the following standard G-Code commands if the virtual_sdcard config section is enabled: List SD card: M20 Initialize SD card: M21 Select SD file: M23 <filename> Start/resume SD print: M24 Pause SD print: M25 Set SD position: M26 S<offset> Report SD print status: M27 In addition, the following extended commands are available when the \"virtual_sdcard\" config section is enabled.","title":"[virtual_sdcard]"},{"location":"G-Codes.html#sdcard_print_file","text":"SDCARD_PRINT_FILE FILENAME=<filename> : Load a file and start SD print.","title":"SDCARD_PRINT_FILE"},{"location":"G-Codes.html#sdcard_reset_file","text":"SDCARD_RESET_FILE : Unload file and clear SD state.","title":"SDCARD_RESET_FILE"},{"location":"G-Codes.html#z_thermal_adjust","text":"The following commands are available when the z_thermal_adjust config section is enabled.","title":"[z_thermal_adjust]"},{"location":"G-Codes.html#set_z_thermal_adjust","text":"SET_Z_THERMAL_ADJUST [ENABLE=<0:1>] [TEMP_COEFF=<value>] [REF_TEMP=<value>] : Enable or disable the Z thermal adjustment with ENABLE . Disabling does not remove any adjustment already applied, but will freeze the current adjustment value - this prevents potentially unsafe downward Z movement. Re-enabling can potentially cause upward tool movement as the adjustment is updated and applied. TEMP_COEFF allows run-time tuning of the adjustment temperature coefficient (i.e. the TEMP_COEFF config parameter). TEMP_COEFF values are not saved to the config. REF_TEMP manually overrides the reference temperature typically set during homing (for use in e.g. non-standard homing routines) - will be reset automatically upon homing.","title":"SET_Z_THERMAL_ADJUST"},{"location":"G-Codes.html#z_tilt","text":"The following commands are available when the z_tilt config section is enabled.","title":"[z_tilt]"},{"location":"G-Codes.html#z_tilt_adjust","text":"Z_TILT_ADJUST [RETRIES=<value>] [RETRY_TOLERANCE=<value>] [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>] : This command will probe the points specified in the config and then make independent adjustments to each Z stepper to compensate for tilt. See the PROBE command for details on the optional probe parameters. The optional RETRIES , RETRY_TOLERANCE , and HORIZONTAL_MOVE_Z values override those options specified in the config file.","title":"Z_TILT_ADJUST"},{"location":"Hall_Filament_Width_Sensor.html","text":"Hall filament width sensor \u00b6 This document describes Filament Width Sensor host module. Hardware used for developing this host module is based on two Hall linear sensors (ss49e for example). Sensors in the body are located on opposite sides. Principle of operation: two hall sensors work in differential mode, temperature drift same for sensor. Special temperature compensation not needed. You can find designs at Thingiverse , an assembly video is also available on Youtube To use Hall filament width sensor, read Config Reference and G-Code documentation . How does it work? \u00b6 Sensor generates two analog output based on calculated filament width. Sum of output voltage always equals to detected filament width. Host module monitors voltage changes and adjusts extrusion multiplier. I use the aux2 connector on a ramps-like board with the analog11 and analog12 pins. You can use different pins and different boards. Template for menu variables \u00b6 [menu __main __filament __width_current] type: command enable: {'hall_filament_width_sensor' in printer} name: Dia: {'%.2F' % printer.hall_filament_width_sensor.Diameter} index: 0 [menu __main __filament __raw_width_current] type: command enable: {'hall_filament_width_sensor' in printer} name: Raw: {'%4.0F' % printer.hall_filament_width_sensor.Raw} index: 1 Calibration procedure \u00b6 To get raw sensor value you can use menu item or QUERY_RAW_FILAMENT_WIDTH command in terminal. Insert first calibration rod (1.5 mm size) get first raw sensor value Insert second calibration rod (2.0 mm size) get second raw sensor value Save raw sensor values in config parameter Raw_dia1 and Raw_dia2 How to enable sensor \u00b6 By default, the sensor is disabled at power-on. To enable the sensor, issue ENABLE_FILAMENT_WIDTH_SENSOR command or set the enable parameter to true . Logging \u00b6 By default, diameter logging is disabled at power-on. Issue ENABLE_FILAMENT_WIDTH_LOG command to start logging and issue DISABLE_FILAMENT_WIDTH_LOG command to stop logging. To enable logging at power-on, set the logging parameter to true . Filament diameter is logged on every measurement interval (10 mm by default).","title":"Hall filament width sensor"},{"location":"Hall_Filament_Width_Sensor.html#hall-filament-width-sensor","text":"This document describes Filament Width Sensor host module. Hardware used for developing this host module is based on two Hall linear sensors (ss49e for example). Sensors in the body are located on opposite sides. Principle of operation: two hall sensors work in differential mode, temperature drift same for sensor. Special temperature compensation not needed. You can find designs at Thingiverse , an assembly video is also available on Youtube To use Hall filament width sensor, read Config Reference and G-Code documentation .","title":"Hall filament width sensor"},{"location":"Hall_Filament_Width_Sensor.html#how-does-it-work","text":"Sensor generates two analog output based on calculated filament width. Sum of output voltage always equals to detected filament width. Host module monitors voltage changes and adjusts extrusion multiplier. I use the aux2 connector on a ramps-like board with the analog11 and analog12 pins. You can use different pins and different boards.","title":"How does it work?"},{"location":"Hall_Filament_Width_Sensor.html#template-for-menu-variables","text":"[menu __main __filament __width_current] type: command enable: {'hall_filament_width_sensor' in printer} name: Dia: {'%.2F' % printer.hall_filament_width_sensor.Diameter} index: 0 [menu __main __filament __raw_width_current] type: command enable: {'hall_filament_width_sensor' in printer} name: Raw: {'%4.0F' % printer.hall_filament_width_sensor.Raw} index: 1","title":"Template for menu variables"},{"location":"Hall_Filament_Width_Sensor.html#calibration-procedure","text":"To get raw sensor value you can use menu item or QUERY_RAW_FILAMENT_WIDTH command in terminal. Insert first calibration rod (1.5 mm size) get first raw sensor value Insert second calibration rod (2.0 mm size) get second raw sensor value Save raw sensor values in config parameter Raw_dia1 and Raw_dia2","title":"Calibration procedure"},{"location":"Hall_Filament_Width_Sensor.html#how-to-enable-sensor","text":"By default, the sensor is disabled at power-on. To enable the sensor, issue ENABLE_FILAMENT_WIDTH_SENSOR command or set the enable parameter to true .","title":"How to enable sensor"},{"location":"Hall_Filament_Width_Sensor.html#logging","text":"By default, diameter logging is disabled at power-on. Issue ENABLE_FILAMENT_WIDTH_LOG command to start logging and issue DISABLE_FILAMENT_WIDTH_LOG command to stop logging. To enable logging at power-on, set the logging parameter to true . Filament diameter is logged on every measurement interval (10 mm by default).","title":"Logging"},{"location":"Installation.html","text":"Installation \u00b6 These instructions assume the software will run on a Linux-based host running a Klipper-compatible front end. It is recommended that a SBC(Small Board Computer) such as a Raspberry Pi or Debian-based Linux device be used as the host machine (see the FAQ for other options). For the purposes of these instructions, host relates to the Linux device and mcu relates to the printer board. SBC relates to the term Small Board Computer such as the Raspberry Pi. Obtain a Klipper Configuration File \u00b6 Most Klipper settings are determined by a \"printer configuration file\" printer.cfg, that will be stored on the host. An appropriate configuration file can often be found by looking in the Klipper config directory for a file starting with a \"printer-\" prefix that corresponds to the target printer. The Klipper configuration file contains technical information about the printer that will be needed during the installation. If there isn't an appropriate printer configuration file in the Klipper config directory then try searching the printer manufacturer's website to see if they have an appropriate Klipper configuration file. If no configuration file for the printer can be found, but the type of printer control board is known, then look for an appropriate config file starting with a \"generic-\" prefix. These example printer board files should allow one to successfully complete the initial installation, but will require some customization to obtain full printer functionality. It is also possible to define a new printer configuration from scratch. However, this requires significant technical knowledge about the printer and its electronics. It is recommended that most users start with an appropriate configuration file. If creating a new custom printer configuration file, then start with the closest example config file and use the Klipper config reference for further information. Interacting with Klipper \u00b6 Klipper is a 3d printer firmware, so it needs some way for the user to interact with it. Currently the best choices are front ends that retrieve information through the Moonraker web API and there is also the option to use Octoprint to control Klipper. The choice is up to the user on what to use, but the underlying Klipper is the same in all cases. We encourage users to research the options available and make an informed decision. Obtaining an OS image for SBC's \u00b6 There are many ways to obtain an OS image for Klipper for SBC use, most depend on what front end you wish to use. Some manufacturers of these SBC boards also provide their own Klipper-centric images. The two main Moonraker-based front ends are Fluidd and Mainsail , the latter of which has a premade install image \"MainsailOS\" , this has the option for Raspberry Pi and some OrangePi variants. Fluidd can be installed via KIAUH(Klipper Install And Update Helper), which is explained below and is a 3rd party installer for all things Klipper. OctoPrint can be installed via the popular OctoPi image or via KIAUH, this process is explained in OctoPrint.md Installing via KIAUH \u00b6 Normally you would start with a base image for your SBC, RPiOS Lite for example, or in the case of an x86 Linux device, Ubuntu Server. Please note that Desktop variants are not recommended due to certain helper programs that can stop some Klipper functions from working and even mask access to some printer boards. KIAUH can be used to install Klipper and its associated programs on a variety of Linux-based systems that run a form of Debian. More information can be found at https://github.com/dw-0/kiauh Building and flashing the micro-controller \u00b6 To compile the micro-controller code, start by running these commands on your host device: cd ~/klipper/ make menuconfig The comments at the top of the printer configuration file should describe the settings that need to be set during \"make menuconfig\". Open the file in a web browser or text editor and look for these instructions near the top of the file. Once the appropriate \"menuconfig\" settings have been configured, press \"Q\" to exit, and then \"Y\" to save. Then run: make If the comments at the top of the printer configuration file describe custom steps for \"flashing\" the final image to the printer control board, then follow those steps and then proceed to configuring OctoPrint . Otherwise, the following steps are often used to \"flash\" the printer control board. First, it is necessary to determine the serial port connected to the micro-controller. Run the following: ls /dev/serial/by-id/* It should report something similar to the following: /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 It's common for each printer to have its own unique serial port name. This unique name will be used when flashing the micro-controller. It's possible there may be multiple lines in the above output - if so, choose the line corresponding to the micro-controller. If many items are listed and the choice is ambiguous, unplug the board and run the command again, the missing item will be your print board(see the FAQ for more information). For common micro-controllers with STM32 or clone chips, LPC chips and others, it is usual that these need an initial Klipper flash via SD card. When flashing with this method, it is important to make sure that the print board is not connected with USB to the host, due to some boards being able to feed power back to the board and stopping a flash from occurring. Please note, that most print boards that use SD cards for flash will implement some kind of flash loop protection for when the sd card is left in place. There are two common methods: Filename Change Required (usually \"stock\" print boards): These boards require the firmware file to have a different name each time you flash (for example, firmware1.bin, firmware2.bin, etc.). If you reuse the same filename, the board may ignore it and not update. Automatic File Renaming (usually aftermarket print boards: Other boards allow using the same filename, commonly firmware.bin, but after flashing, the board renames the file to firmware.cur. This helps indicate the firmware was successfully flashed and prevents it from flashing again on the next startup. Before flashing, make sure to check which behavior your board follows. For common micro-controllers using Atmega chips, for example the 2560, the code can be flashed with something similar to: sudo service klipper stop make flash FLASH_DEVICE=/dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 sudo service klipper start Be sure to update the FLASH_DEVICE with the printer's unique serial port name. For common micro-controllers using RP2040 chips, the code can be flashed with something similar to: sudo service klipper stop make flash FLASH_DEVICE=first sudo service klipper start It is important to note that RP2040 chips may need to be put into Boot mode before this operation. Configuring Klipper \u00b6 The next step is to copy the printer configuration file to the host. Arguably the easiest way to set the Klipper configuration file is using the built-in editors in Mainsail or Fluidd. These will allow the user to open the configuration examples and save them to be printer.cfg. Another option is to use a desktop editor that supports editing files over the \"scp\" and/or \"sftp\" protocols. There are freely available tools that support this (eg, Notepad++, WinSCP, and Cyberduck). Load the printer config file in the editor and then save it as a file named \"printer.cfg\" in the home directory of the pi user (ie, /home/pi/printer.cfg). Alternatively, one can also copy and edit the file directly on the host via SSH. That may look something like the following (be sure to update the command to use the appropriate printer config filename): cp ~/klipper/config/example-cartesian.cfg ~/printer.cfg nano ~/printer.cfg It's common for each printer to have its own unique name for the micro-controller. The name may change after flashing Klipper, so rerun these steps again even if they were already done when flashing. Run: ls /dev/serial/by-id/* It should report something similar to the following: /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 Then update the config file with the unique name. For example, update the [mcu] section to look something similar to: [mcu] serial: /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 After creating and editing the file, it will be necessary to issue a \"restart\" command in the command console to load the config. A \"status\" command will report that the printer is ready if the Klipper config file is successfully read and the micro-controller is successfully found and configured. When customizing the printer config file, it is not uncommon for Klipper to report a configuration error. If an error occurs, make any necessary corrections to the printer config file and issue \"restart\" until \"status\" reports the printer is ready. Klipper reports error messages via the command console and pop-ups in Fluidd and Mainsail. The \"status\" command can be used to re-report error messages. A log is available and usually located at ~/printer_data/logs/klippy.log . After Klipper reports that the printer is ready, proceed to the config check document to perform some basic checks on the definitions in the config file. See the main documentation reference for other information.","title":"Installation"},{"location":"Installation.html#installation","text":"These instructions assume the software will run on a Linux-based host running a Klipper-compatible front end. It is recommended that a SBC(Small Board Computer) such as a Raspberry Pi or Debian-based Linux device be used as the host machine (see the FAQ for other options). For the purposes of these instructions, host relates to the Linux device and mcu relates to the printer board. SBC relates to the term Small Board Computer such as the Raspberry Pi.","title":"Installation"},{"location":"Installation.html#obtain-a-klipper-configuration-file","text":"Most Klipper settings are determined by a \"printer configuration file\" printer.cfg, that will be stored on the host. An appropriate configuration file can often be found by looking in the Klipper config directory for a file starting with a \"printer-\" prefix that corresponds to the target printer. The Klipper configuration file contains technical information about the printer that will be needed during the installation. If there isn't an appropriate printer configuration file in the Klipper config directory then try searching the printer manufacturer's website to see if they have an appropriate Klipper configuration file. If no configuration file for the printer can be found, but the type of printer control board is known, then look for an appropriate config file starting with a \"generic-\" prefix. These example printer board files should allow one to successfully complete the initial installation, but will require some customization to obtain full printer functionality. It is also possible to define a new printer configuration from scratch. However, this requires significant technical knowledge about the printer and its electronics. It is recommended that most users start with an appropriate configuration file. If creating a new custom printer configuration file, then start with the closest example config file and use the Klipper config reference for further information.","title":"Obtain a Klipper Configuration File"},{"location":"Installation.html#interacting-with-klipper","text":"Klipper is a 3d printer firmware, so it needs some way for the user to interact with it. Currently the best choices are front ends that retrieve information through the Moonraker web API and there is also the option to use Octoprint to control Klipper. The choice is up to the user on what to use, but the underlying Klipper is the same in all cases. We encourage users to research the options available and make an informed decision.","title":"Interacting with Klipper"},{"location":"Installation.html#obtaining-an-os-image-for-sbcs","text":"There are many ways to obtain an OS image for Klipper for SBC use, most depend on what front end you wish to use. Some manufacturers of these SBC boards also provide their own Klipper-centric images. The two main Moonraker-based front ends are Fluidd and Mainsail , the latter of which has a premade install image \"MainsailOS\" , this has the option for Raspberry Pi and some OrangePi variants. Fluidd can be installed via KIAUH(Klipper Install And Update Helper), which is explained below and is a 3rd party installer for all things Klipper. OctoPrint can be installed via the popular OctoPi image or via KIAUH, this process is explained in OctoPrint.md","title":"Obtaining an OS image for SBC's"},{"location":"Installation.html#installing-via-kiauh","text":"Normally you would start with a base image for your SBC, RPiOS Lite for example, or in the case of an x86 Linux device, Ubuntu Server. Please note that Desktop variants are not recommended due to certain helper programs that can stop some Klipper functions from working and even mask access to some printer boards. KIAUH can be used to install Klipper and its associated programs on a variety of Linux-based systems that run a form of Debian. More information can be found at https://github.com/dw-0/kiauh","title":"Installing via KIAUH"},{"location":"Installation.html#building-and-flashing-the-micro-controller","text":"To compile the micro-controller code, start by running these commands on your host device: cd ~/klipper/ make menuconfig The comments at the top of the printer configuration file should describe the settings that need to be set during \"make menuconfig\". Open the file in a web browser or text editor and look for these instructions near the top of the file. Once the appropriate \"menuconfig\" settings have been configured, press \"Q\" to exit, and then \"Y\" to save. Then run: make If the comments at the top of the printer configuration file describe custom steps for \"flashing\" the final image to the printer control board, then follow those steps and then proceed to configuring OctoPrint . Otherwise, the following steps are often used to \"flash\" the printer control board. First, it is necessary to determine the serial port connected to the micro-controller. Run the following: ls /dev/serial/by-id/* It should report something similar to the following: /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 It's common for each printer to have its own unique serial port name. This unique name will be used when flashing the micro-controller. It's possible there may be multiple lines in the above output - if so, choose the line corresponding to the micro-controller. If many items are listed and the choice is ambiguous, unplug the board and run the command again, the missing item will be your print board(see the FAQ for more information). For common micro-controllers with STM32 or clone chips, LPC chips and others, it is usual that these need an initial Klipper flash via SD card. When flashing with this method, it is important to make sure that the print board is not connected with USB to the host, due to some boards being able to feed power back to the board and stopping a flash from occurring. Please note, that most print boards that use SD cards for flash will implement some kind of flash loop protection for when the sd card is left in place. There are two common methods: Filename Change Required (usually \"stock\" print boards): These boards require the firmware file to have a different name each time you flash (for example, firmware1.bin, firmware2.bin, etc.). If you reuse the same filename, the board may ignore it and not update. Automatic File Renaming (usually aftermarket print boards: Other boards allow using the same filename, commonly firmware.bin, but after flashing, the board renames the file to firmware.cur. This helps indicate the firmware was successfully flashed and prevents it from flashing again on the next startup. Before flashing, make sure to check which behavior your board follows. For common micro-controllers using Atmega chips, for example the 2560, the code can be flashed with something similar to: sudo service klipper stop make flash FLASH_DEVICE=/dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 sudo service klipper start Be sure to update the FLASH_DEVICE with the printer's unique serial port name. For common micro-controllers using RP2040 chips, the code can be flashed with something similar to: sudo service klipper stop make flash FLASH_DEVICE=first sudo service klipper start It is important to note that RP2040 chips may need to be put into Boot mode before this operation.","title":"Building and flashing the micro-controller"},{"location":"Installation.html#configuring-klipper","text":"The next step is to copy the printer configuration file to the host. Arguably the easiest way to set the Klipper configuration file is using the built-in editors in Mainsail or Fluidd. These will allow the user to open the configuration examples and save them to be printer.cfg. Another option is to use a desktop editor that supports editing files over the \"scp\" and/or \"sftp\" protocols. There are freely available tools that support this (eg, Notepad++, WinSCP, and Cyberduck). Load the printer config file in the editor and then save it as a file named \"printer.cfg\" in the home directory of the pi user (ie, /home/pi/printer.cfg). Alternatively, one can also copy and edit the file directly on the host via SSH. That may look something like the following (be sure to update the command to use the appropriate printer config filename): cp ~/klipper/config/example-cartesian.cfg ~/printer.cfg nano ~/printer.cfg It's common for each printer to have its own unique name for the micro-controller. The name may change after flashing Klipper, so rerun these steps again even if they were already done when flashing. Run: ls /dev/serial/by-id/* It should report something similar to the following: /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 Then update the config file with the unique name. For example, update the [mcu] section to look something similar to: [mcu] serial: /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 After creating and editing the file, it will be necessary to issue a \"restart\" command in the command console to load the config. A \"status\" command will report that the printer is ready if the Klipper config file is successfully read and the micro-controller is successfully found and configured. When customizing the printer config file, it is not uncommon for Klipper to report a configuration error. If an error occurs, make any necessary corrections to the printer config file and issue \"restart\" until \"status\" reports the printer is ready. Klipper reports error messages via the command console and pop-ups in Fluidd and Mainsail. The \"status\" command can be used to re-report error messages. A log is available and usually located at ~/printer_data/logs/klippy.log . After Klipper reports that the printer is ready, proceed to the config check document to perform some basic checks on the definitions in the config file. See the main documentation reference for other information.","title":"Configuring Klipper"},{"location":"Kinematics.html","text":"Kinematics \u00b6 This document provides an overview of how Klipper implements robot motion (its kinematics ). The contents may be of interest to both developers interested in working on the Klipper software as well as users interested in better understanding the mechanics of their machines. Acceleration \u00b6 Klipper implements a constant acceleration scheme whenever the print head changes velocity - the velocity is gradually changed to the new speed instead of suddenly jerking to it. Klipper always enforces acceleration between the tool head and the print. The filament leaving the extruder can be quite fragile - rapid jerks and/or extruder flow changes lead to poor quality and poor bed adhesion. Even when not extruding, if the print head is at the same level as the print then rapid jerking of the head can cause disruption of recently deposited filament. Limiting speed changes of the print head (relative to the print) reduces risks of disrupting the print. It is also important to limit acceleration so that the stepper motors do not skip or put excessive stress on the machine. Klipper limits the torque on each stepper by virtue of limiting the acceleration of the print head. Enforcing acceleration at the print head naturally also limits the torque of the steppers that move the print head (the inverse is not always true). Klipper implements constant acceleration. The key formula for constant acceleration is: velocity(time) = start_velocity + accel*time Trapezoid generator \u00b6 Klipper uses a traditional \"trapezoid generator\" to model the motion of each move - each move has a start speed, it accelerates to a cruising speed at constant acceleration, it cruises at a constant speed, and then decelerates to the end speed using constant acceleration. It's called a \"trapezoid generator\" because a velocity diagram of the move looks like a trapezoid. The cruising speed is always greater than or equal to both the start speed and the end speed. The acceleration phase may be of zero duration (if the start speed is equal to the cruising speed), the cruising phase may be of zero duration (if the move immediately starts decelerating after acceleration), and/or the deceleration phase may be of zero duration (if the end speed is equal to the cruising speed). Look-ahead \u00b6 The \"look-ahead\" system is used to determine cornering speeds between moves. Consider the following two moves contained on an XY plane: In the above situation it is possible to fully decelerate after the first move and then fully accelerate at the start of the next move, but that is not ideal as all that acceleration and deceleration would greatly increase the print time and the frequent changes in extruder flow would result in poor print quality. To solve this, the \"look-ahead\" mechanism queues multiple incoming moves and analyzes the angles between moves to determine a reasonable speed that can be obtained during the \"junction\" between two moves. If the next move is nearly in the same direction then the head need only slow down a little (if at all). However, if the next move forms an acute angle (the head is going to travel in nearly a reverse direction on the next move) then only a small junction speed is permitted. The junction speeds are determined using \"approximated centripetal acceleration\". Best described by the author . However, in Klipper, junction speeds are configured by specifying the desired speed that a 90\u00b0 corner should have (the \"square corner velocity\"), and the junction speeds for other angles are derived from that. Key formula for look-ahead: end_velocity^2 = start_velocity^2 + 2*accel*move_distance Minimum cruise ratio \u00b6 Klipper also implements a mechanism for smoothing out the motions of short \"zigzag\" moves. Consider the following moves: In the above, the frequent changes from acceleration to deceleration can cause the machine to vibrate which causes stress on the machine and increases the noise. Klipper implements a mechanism to ensure there is always some movement at a cruising speed between acceleration and deceleration. This is done by reducing the top speed of some moves (or sequence of moves) to ensure there is a minimum distance traveled at cruising speed relative to the distance traveled during acceleration and deceleration. Klipper implements this feature by tracking both a regular move acceleration as well as a virtual \"acceleration to deceleration\" rate: Specifically, the code calculates what the velocity of each move would be if it were limited to this virtual \"acceleration to deceleration\" rate. In the above picture the dashed gray lines represent this virtual acceleration rate for the first move. If a move can not reach its full cruising speed using this virtual acceleration rate then its top speed is reduced to the maximum speed it could obtain at this virtual acceleration rate. For most moves the limit will be at or above the move's existing limits and no change in behavior is induced. For short zigzag moves, however, this limit reduces the top speed. Note that it does not change the actual acceleration within the move - the move continues to use the normal acceleration scheme up to its adjusted top-speed. Generating steps \u00b6 Once the look-ahead process completes, the print head movement for the given move is fully known (time, start position, end position, velocity at each point) and it is possible to generate the step times for the move. This process is done within \"kinematic classes\" in the Klipper code. Outside of these kinematic classes, everything is tracked in millimeters, seconds, and in cartesian coordinate space. It's the task of the kinematic classes to convert from this generic coordinate system to the hardware specifics of the particular printer. Klipper uses an iterative solver to generate the step times for each stepper. The code contains the formulas to calculate the ideal cartesian coordinates of the head at each moment in time, and it has the kinematic formulas to calculate the ideal stepper positions based on those cartesian coordinates. With these formulas, Klipper can determine the ideal time that the stepper should be at each step position. The given steps are then scheduled at these calculated times. The key formula to determine how far a move should travel under constant acceleration is: move_distance = (start_velocity + .5 * accel * move_time) * move_time and the key formula for movement with constant velocity is: move_distance = cruise_velocity * move_time The key formulas for determining the cartesian coordinate of a move given a move distance is: cartesian_x_position = start_x + move_distance * total_x_movement / total_movement cartesian_y_position = start_y + move_distance * total_y_movement / total_movement cartesian_z_position = start_z + move_distance * total_z_movement / total_movement Cartesian Robots \u00b6 Generating steps for cartesian printers is the simplest case. The movement on each axis is directly related to the movement in cartesian space. Key formulas: stepper_x_position = cartesian_x_position stepper_y_position = cartesian_y_position stepper_z_position = cartesian_z_position CoreXY Robots \u00b6 Generating steps on a CoreXY machine is only a little more complex than basic cartesian robots. The key formulas are: stepper_a_position = cartesian_x_position + cartesian_y_position stepper_b_position = cartesian_x_position - cartesian_y_position stepper_z_position = cartesian_z_position Delta Robots \u00b6 Step generation on a delta robot is based on Pythagoras's theorem: stepper_position = (sqrt(arm_length^2 - (cartesian_x_position - tower_x_position)^2 - (cartesian_y_position - tower_y_position)^2) + cartesian_z_position) Stepper motor acceleration limits \u00b6 With delta kinematics it is possible for a move that is accelerating in cartesian space to require an acceleration on a particular stepper motor greater than the move's acceleration. This can occur when a stepper arm is more horizontal than vertical and the line of movement passes near that stepper's tower. Although these moves could require a stepper motor acceleration greater than the printer's maximum configured move acceleration, the effective mass moved by that stepper would be smaller. Thus the higher stepper acceleration does not result in significantly higher stepper torque and it is therefore considered harmless. However, to avoid extreme cases, Klipper enforces a maximum ceiling on stepper acceleration of three times the printer's configured maximum move acceleration. (Similarly, the maximum velocity of the stepper is limited to three times the maximum move velocity.) In order to enforce this limit, moves at the extreme edge of the build envelope (where a stepper arm may be nearly horizontal) will have a lower maximum acceleration and velocity. Extruder kinematics \u00b6 Klipper implements extruder motion in its own kinematic class. Since the timing and speed of each print head movement is fully known for each move, it's possible to calculate the step times for the extruder independently from the step time calculations of the print head movement. Basic extruder movement is simple to calculate. The step time generation uses the same formulas that cartesian robots use: stepper_position = requested_e_position Pressure advance \u00b6 Experimentation has shown that it's possible to improve the modeling of the extruder beyond the basic extruder formula. In the ideal case, as an extrusion move progresses, the same volume of filament should be deposited at each point along the move and there should be no volume extruded after the move. Unfortunately, it's common to find that the basic extrusion formulas cause too little filament to exit the extruder at the start of extrusion moves and for excess filament to extrude after extrusion ends. This is often referred to as \"ooze\". The \"pressure advance\" system attempts to account for this by using a different model for the extruder. Instead of naively believing that each mm^3 of filament fed into the extruder will result in that amount of mm^3 immediately exiting the extruder, it uses a model based on pressure. Pressure increases when filament is pushed into the extruder (as in Hooke's law ) and the pressure necessary to extrude is dominated by the flow rate through the nozzle orifice (as in Poiseuille's law ). The key idea is that the relationship between filament, pressure, and flow rate can be modeled using a linear coefficient: pa_position = nominal_position + pressure_advance_coefficient * nominal_velocity See the pressure advance document for information on how to find this pressure advance coefficient. The basic pressure advance formula can cause the extruder motor to make sudden velocity changes. Klipper implements \"smoothing\" of the extruder movement to avoid this. The above graph shows an example of two extrusion moves with a non-zero cornering velocity between them. Note that the pressure advance system causes additional filament to be pushed into the extruder during acceleration. The higher the desired filament flow rate, the more filament must be pushed in during acceleration to account for pressure. During head deceleration the extra filament is retracted (the extruder will have a negative velocity). The \"smoothing\" is implemented using a weighted average of the extruder position over a small time period (as specified by the pressure_advance_smooth_time config parameter). This averaging can span multiple g-code moves. Note how the extruder motor will start moving prior to the nominal start of the first extrusion move and will continue to move after the nominal end of the last extrusion move. Key formula for \"smoothed pressure advance\": smooth_pa_position(t) = ( definitive_integral(pa_position(x) * (smooth_time/2 - abs(t - x)) * dx, from=t-smooth_time/2, to=t+smooth_time/2) / (smooth_time/2)^2 )","title":"Kinematics"},{"location":"Kinematics.html#kinematics","text":"This document provides an overview of how Klipper implements robot motion (its kinematics ). The contents may be of interest to both developers interested in working on the Klipper software as well as users interested in better understanding the mechanics of their machines.","title":"Kinematics"},{"location":"Kinematics.html#acceleration","text":"Klipper implements a constant acceleration scheme whenever the print head changes velocity - the velocity is gradually changed to the new speed instead of suddenly jerking to it. Klipper always enforces acceleration between the tool head and the print. The filament leaving the extruder can be quite fragile - rapid jerks and/or extruder flow changes lead to poor quality and poor bed adhesion. Even when not extruding, if the print head is at the same level as the print then rapid jerking of the head can cause disruption of recently deposited filament. Limiting speed changes of the print head (relative to the print) reduces risks of disrupting the print. It is also important to limit acceleration so that the stepper motors do not skip or put excessive stress on the machine. Klipper limits the torque on each stepper by virtue of limiting the acceleration of the print head. Enforcing acceleration at the print head naturally also limits the torque of the steppers that move the print head (the inverse is not always true). Klipper implements constant acceleration. The key formula for constant acceleration is: velocity(time) = start_velocity + accel*time","title":"Acceleration"},{"location":"Kinematics.html#trapezoid-generator","text":"Klipper uses a traditional \"trapezoid generator\" to model the motion of each move - each move has a start speed, it accelerates to a cruising speed at constant acceleration, it cruises at a constant speed, and then decelerates to the end speed using constant acceleration. It's called a \"trapezoid generator\" because a velocity diagram of the move looks like a trapezoid. The cruising speed is always greater than or equal to both the start speed and the end speed. The acceleration phase may be of zero duration (if the start speed is equal to the cruising speed), the cruising phase may be of zero duration (if the move immediately starts decelerating after acceleration), and/or the deceleration phase may be of zero duration (if the end speed is equal to the cruising speed).","title":"Trapezoid generator"},{"location":"Kinematics.html#look-ahead","text":"The \"look-ahead\" system is used to determine cornering speeds between moves. Consider the following two moves contained on an XY plane: In the above situation it is possible to fully decelerate after the first move and then fully accelerate at the start of the next move, but that is not ideal as all that acceleration and deceleration would greatly increase the print time and the frequent changes in extruder flow would result in poor print quality. To solve this, the \"look-ahead\" mechanism queues multiple incoming moves and analyzes the angles between moves to determine a reasonable speed that can be obtained during the \"junction\" between two moves. If the next move is nearly in the same direction then the head need only slow down a little (if at all). However, if the next move forms an acute angle (the head is going to travel in nearly a reverse direction on the next move) then only a small junction speed is permitted. The junction speeds are determined using \"approximated centripetal acceleration\". Best described by the author . However, in Klipper, junction speeds are configured by specifying the desired speed that a 90\u00b0 corner should have (the \"square corner velocity\"), and the junction speeds for other angles are derived from that. Key formula for look-ahead: end_velocity^2 = start_velocity^2 + 2*accel*move_distance","title":"Look-ahead"},{"location":"Kinematics.html#minimum-cruise-ratio","text":"Klipper also implements a mechanism for smoothing out the motions of short \"zigzag\" moves. Consider the following moves: In the above, the frequent changes from acceleration to deceleration can cause the machine to vibrate which causes stress on the machine and increases the noise. Klipper implements a mechanism to ensure there is always some movement at a cruising speed between acceleration and deceleration. This is done by reducing the top speed of some moves (or sequence of moves) to ensure there is a minimum distance traveled at cruising speed relative to the distance traveled during acceleration and deceleration. Klipper implements this feature by tracking both a regular move acceleration as well as a virtual \"acceleration to deceleration\" rate: Specifically, the code calculates what the velocity of each move would be if it were limited to this virtual \"acceleration to deceleration\" rate. In the above picture the dashed gray lines represent this virtual acceleration rate for the first move. If a move can not reach its full cruising speed using this virtual acceleration rate then its top speed is reduced to the maximum speed it could obtain at this virtual acceleration rate. For most moves the limit will be at or above the move's existing limits and no change in behavior is induced. For short zigzag moves, however, this limit reduces the top speed. Note that it does not change the actual acceleration within the move - the move continues to use the normal acceleration scheme up to its adjusted top-speed.","title":"Minimum cruise ratio"},{"location":"Kinematics.html#generating-steps","text":"Once the look-ahead process completes, the print head movement for the given move is fully known (time, start position, end position, velocity at each point) and it is possible to generate the step times for the move. This process is done within \"kinematic classes\" in the Klipper code. Outside of these kinematic classes, everything is tracked in millimeters, seconds, and in cartesian coordinate space. It's the task of the kinematic classes to convert from this generic coordinate system to the hardware specifics of the particular printer. Klipper uses an iterative solver to generate the step times for each stepper. The code contains the formulas to calculate the ideal cartesian coordinates of the head at each moment in time, and it has the kinematic formulas to calculate the ideal stepper positions based on those cartesian coordinates. With these formulas, Klipper can determine the ideal time that the stepper should be at each step position. The given steps are then scheduled at these calculated times. The key formula to determine how far a move should travel under constant acceleration is: move_distance = (start_velocity + .5 * accel * move_time) * move_time and the key formula for movement with constant velocity is: move_distance = cruise_velocity * move_time The key formulas for determining the cartesian coordinate of a move given a move distance is: cartesian_x_position = start_x + move_distance * total_x_movement / total_movement cartesian_y_position = start_y + move_distance * total_y_movement / total_movement cartesian_z_position = start_z + move_distance * total_z_movement / total_movement","title":"Generating steps"},{"location":"Kinematics.html#cartesian-robots","text":"Generating steps for cartesian printers is the simplest case. The movement on each axis is directly related to the movement in cartesian space. Key formulas: stepper_x_position = cartesian_x_position stepper_y_position = cartesian_y_position stepper_z_position = cartesian_z_position","title":"Cartesian Robots"},{"location":"Kinematics.html#corexy-robots","text":"Generating steps on a CoreXY machine is only a little more complex than basic cartesian robots. The key formulas are: stepper_a_position = cartesian_x_position + cartesian_y_position stepper_b_position = cartesian_x_position - cartesian_y_position stepper_z_position = cartesian_z_position","title":"CoreXY Robots"},{"location":"Kinematics.html#delta-robots","text":"Step generation on a delta robot is based on Pythagoras's theorem: stepper_position = (sqrt(arm_length^2 - (cartesian_x_position - tower_x_position)^2 - (cartesian_y_position - tower_y_position)^2) + cartesian_z_position)","title":"Delta Robots"},{"location":"Kinematics.html#stepper-motor-acceleration-limits","text":"With delta kinematics it is possible for a move that is accelerating in cartesian space to require an acceleration on a particular stepper motor greater than the move's acceleration. This can occur when a stepper arm is more horizontal than vertical and the line of movement passes near that stepper's tower. Although these moves could require a stepper motor acceleration greater than the printer's maximum configured move acceleration, the effective mass moved by that stepper would be smaller. Thus the higher stepper acceleration does not result in significantly higher stepper torque and it is therefore considered harmless. However, to avoid extreme cases, Klipper enforces a maximum ceiling on stepper acceleration of three times the printer's configured maximum move acceleration. (Similarly, the maximum velocity of the stepper is limited to three times the maximum move velocity.) In order to enforce this limit, moves at the extreme edge of the build envelope (where a stepper arm may be nearly horizontal) will have a lower maximum acceleration and velocity.","title":"Stepper motor acceleration limits"},{"location":"Kinematics.html#extruder-kinematics","text":"Klipper implements extruder motion in its own kinematic class. Since the timing and speed of each print head movement is fully known for each move, it's possible to calculate the step times for the extruder independently from the step time calculations of the print head movement. Basic extruder movement is simple to calculate. The step time generation uses the same formulas that cartesian robots use: stepper_position = requested_e_position","title":"Extruder kinematics"},{"location":"Kinematics.html#pressure-advance","text":"Experimentation has shown that it's possible to improve the modeling of the extruder beyond the basic extruder formula. In the ideal case, as an extrusion move progresses, the same volume of filament should be deposited at each point along the move and there should be no volume extruded after the move. Unfortunately, it's common to find that the basic extrusion formulas cause too little filament to exit the extruder at the start of extrusion moves and for excess filament to extrude after extrusion ends. This is often referred to as \"ooze\". The \"pressure advance\" system attempts to account for this by using a different model for the extruder. Instead of naively believing that each mm^3 of filament fed into the extruder will result in that amount of mm^3 immediately exiting the extruder, it uses a model based on pressure. Pressure increases when filament is pushed into the extruder (as in Hooke's law ) and the pressure necessary to extrude is dominated by the flow rate through the nozzle orifice (as in Poiseuille's law ). The key idea is that the relationship between filament, pressure, and flow rate can be modeled using a linear coefficient: pa_position = nominal_position + pressure_advance_coefficient * nominal_velocity See the pressure advance document for information on how to find this pressure advance coefficient. The basic pressure advance formula can cause the extruder motor to make sudden velocity changes. Klipper implements \"smoothing\" of the extruder movement to avoid this. The above graph shows an example of two extrusion moves with a non-zero cornering velocity between them. Note that the pressure advance system causes additional filament to be pushed into the extruder during acceleration. The higher the desired filament flow rate, the more filament must be pushed in during acceleration to account for pressure. During head deceleration the extra filament is retracted (the extruder will have a negative velocity). The \"smoothing\" is implemented using a weighted average of the extruder position over a small time period (as specified by the pressure_advance_smooth_time config parameter). This averaging can span multiple g-code moves. Note how the extruder motor will start moving prior to the nominal start of the first extrusion move and will continue to move after the nominal end of the last extrusion move. Key formula for \"smoothed pressure advance\": smooth_pa_position(t) = ( definitive_integral(pa_position(x) * (smooth_time/2 - abs(t - x)) * dx, from=t-smooth_time/2, to=t+smooth_time/2) / (smooth_time/2)^2 )","title":"Pressure advance"},{"location":"Load_Cell.html","text":"Load Cells \u00b6 This document describes Klipper's support for load cells. Basic load cell functionality can be used to read force data and to weigh things like filament. A calibrated force sensor is an important part of a load cell based probe. Related Documentation \u00b6 load_cell Config Reference load_cell G-Code Commands load_cell Status Reference Using LOAD_CELL_DIAGNOSTIC \u00b6 When you first connect a load cell its good practice to check for issues by running LOAD_CELL_DIAGNOSTIC . This tool collects 10 seconds of data from the load cell and resport statistics: $ LOAD_CELL_DIAGNOSTIC // Collecting load cell data for 10 seconds... // Samples Collected: 3211 // Measured samples per second: 332.0 // Good samples: 3211, Saturated samples: 0, Unique values: 900 // Sample range: [4.01% to 4.02%] // Sample range / sensor capacity: 0.00524% Things you can check with this data: The configured sample rate of the sensor should be close to the 'Measured samples per second' value. If it is not you may have a configuration or wiring issue. 'Saturated samples' should be 0. If you have saturated samples it means the load sell is seeing more force than it can measure. 'Unique values' should be a large percentage of the 'Samples Collected' value. If 'Unique values' is 1 it is very likely a wiring issue. Tap or push on the sensor while LOAD_CELL_DIAGNOSTIC runs. If things are working correctly this should increase the 'Sample range'. Calibrating a Load Cell \u00b6 Load cells are calibrated using the LOAD_CELL_CALIBRATE command. This is an interactive calibration utility that walks you though a 3 step process: First use the TARE command to establish the zero force value. This is the reference_tare_counts config value. Next you apply a known load or force to the load cell and run the CALIBRATE GRAMS=nnn command. From this the counts_per_gram value is calculated. See the next section for some suggestions on how to do this. Finally, use the ACCEPT command to save the results. You can cancel the calibration process at any time with ABORT . Applying a Known Force or Load \u00b6 The CALIBRATE GRAMS=nnn step can be accomplished in a number of ways. If your load cell is under a platform like a bed or filament holder it might be easiest to put a known mass on the platform. E.g. you could use a couple of 1KG filament spools. If your load cell is in the printer's toolhead a different approach is easier. Put a digital scale on the printers bed and gently lower the toolhead onto the scale (or raise the bed into the toolhead if your bed moves). You may be able to do this using the FORCE_MOVE command. But more likely you will have to manually moving the z axis with the motors off until the toolhead presses on the scale. A good calibration force would ideally be a large percentage of the load cell's rated capacity. E.g. if you have a 5Kg load cell you would ideally calibrate it with a 5kg mass. This might work well with under-bed sensors that have to support a lot of weight. For toolhead probes this may not be a load that your printer bed or toolhead can tolerate without damage. Do try to use at least 1Kg of force, most printers should tolerate this without issue. When calibrating make careful note of the values reported: $ CALIBRATE GRAMS=555 // Calibration value: -2.78% (-59803108), Counts/gram: 73039.78739, Total capacity: +/- 29.14Kg The Total capacity should be close to the theoretical rating of the load cell based on the sensor's capacity. If it is much larger you could have used a higher gain setting in the sensor or a more sensitive load cell. This isn't as critical for 32bit and 24bit sensors but is much more critical for low bit width sensors. Reading Force Data \u00b6 Force data can be read with a GCode command: LOAD_CELL_READ // 10.6g (1.94%) Data is also continuously read and can be consumed from the load_cell printer object in a macro: {% set grams = printer.load_cell.force_g %} This provides an average force over the last 1 second, similar to how temperature sensors work. Taring a Load Cell \u00b6 Taring, sometimes called zeroing, sets the current weight reported by the load_cell to 0. This is useful for measuring relative to a known weight. e.g. when measuring a filament spool, using LOAD_CELL_TARE sets the weight to 0. Then as filament is printed the load_cell will report the weight of the filament used. LOAD_CELL_TARE // Load cell tare value: 5.32% (445903) The current tare value is reported in the printers status and can be read in a macro: {% set tare_counts = printer.load_cell.tare_counts %} Load Cell Probes \u00b6 Related Documentation \u00b6 load_cell_probe Config Reference load_cell_probe G-Code Commands load_cell_probe Statuc Reference Load Cell Probe Safety \u00b6 Because load cells are a direct nozzle contact probe there is a risk of damage to your printer if too much force is used. The load cell probing system includes a number of safety checks that try to keep your machine safe from excessive force to the toolhead. It's important to understand what they are and how they work as you can defeat most of them with poorly chosen config values. Calibration Check \u00b6 Every time a homing move starts, load_cell_probe checks that the load_cell is calibrated. If not it will stop the move with an error: !! Load Cell not calibrated . counts_per_gram \u00b6 This setting is used to convert raw sensor counts into grams. All the safety limits are in gram units for your convenience. If the counts_per_gram setting is not accurate you can easily exceed the safe force on the toolhead. You should never guess this value. Use LOAD_CELL_CALIBRATE to find your load cells actual counts_per_gram . trigger_force \u00b6 This is the force in grams that triggers the endstop to halt the homing move. When a homing move starts the endstop tares itself with the current reading from the load cell. trigger_force is measured from that tare value. There is always some overshoot of this value when the probe collides with the bed, so be conservative. e.g. a setting of 100g could result in 350g of peak force before the toolhead stops. This overshoot will increase with faster probing speed , a low ADC sample rate or multi MCU homing . reference_tare_counts \u00b6 This is the baseline tare value that is set by LOAD_CELL_CALIBRATE . This value works with force_safety_limit to limit the maximum force on the toolhead. force_safety_limit \u00b6 This is the maximum absolute force, relative to reference_tare_counts , that the probe will allow while homing or probing. If the MCU sees this force exceeded it will shut down the printer with the error !! Load cell endstop: too much force! . There are a number of ways this can be triggered: The first risk this protects against is picking too large of a value for drift_filter_cutoff_frequency . This can cause the drift filter to filter out a probe event and continue the homing move. If this happens the force_safety_limit acts as a backup protection. The second problem is probing repeatedly in one place. Klipper does not retract the probe when doing a single PROBE command. This can result in force applied to the toolhead at the end of a probing cycle. Because external forces can vary greatly between probing locations, load_cell_probe performs a tare before beginning each probe. If you repeat the PROBE command, load_cell_probe will tare the endstop at the current force. Multiple cycles of this will result in ever-increasing force on the toolhead. force_safety_limit stops this cycle from running out of control. Another way this run-away can happen is damage to a strain gauge. If the metal part is permanently bent it will change the reference_tare_counts of the device. This puts the starting tare value much closer to the limit making it more likely to be violated. You want to be notified if this is happening because your hardware has been permanently damaged. The final way this can be triggered is due to temperature changes. If your strain gauges are heated their reference_tare_counts may be very different at ambient temperature vs operating temperature. In this case you may need to increase the force_safety_limit to allow for thermal changes. Load Cell Endstop Watchdog Task \u00b6 When homing the load_cell_endstop starts a task on the MCU to trac measurements arriving from the sensor. If the sensor fails to send measurements for 2 sample periods the watchdog will shut down the printer with an error !! LoadCell Endstop timed out waiting on ADC data . If this happens, the most likely cause is a fault from the ADC. Inadequate grounding of your printer can be the root cause. The frame, power supply case and pint bed should all be connected to ground. You may need to ground the frame in multiple places. Anodized aluminum extrusions do not conduct electricity well. You might need to sand the area where the grounding wire is attached to make good electrical contact. Load Cell Probe Setup \u00b6 This section covers the process for commissioning a load cell probe. Verify the Load Cell First \u00b6 A [load_cell_probe] is also a [load_cell] and G-code commands related to [load_cell] work with [load_cell_probe] . Before attempting to use a load cell probe, follow the directions for calibrating the load cell with CALIBRATE_LOAD_CELL and checking its operation with LOAD_CELL_DIAGNOSTIC . Verify Probe Operation With LOAD_CELL_TEST_TAP \u00b6 Use the command LOAD_CELL_TEST_TAP to test the operation of the load cell probe before actually trying to probe with it. This command detects taps, just like the PROBE command, but it does not move the z axis. By default, it listens for 3 taps before ending the test. You have 30 seconds to do each tap, if no taps are detected the command will time out. If this test fails, check your configuration and LOAD_CELL_DIAGNOSTIC carefully to look for issues. Load cell probes don't support the QUERY_ENDSTOPS or QUERY_PROBE commands. Use LOAD_CELL_TEST_TAP for testing functionality before probing. Homing Macros \u00b6 Load cell probe is not an endstop and doesn't support endstop: prove:z_virtual_endstop . For the time being you'll need to configure your z axis with an MCU pin as its endstop. You won't actually be using the pin but for the time being you have to configure something. To home the axis with just the probe you need to set up a custom homing macro. This requires setting up homing_override . Here is a simple macro that can accomplish this. Note that the _HOME_Z_FROM_LAST_PROBE macro has to be separate because of the way macros work. The sub-call is needed so that the _HOME_Z_FROM_LAST_PROBE macro can see the result of the probe in printer.probe.last_z_result . [gcode_macro _HOME_Z_FROM_LAST_PROBE] gcode: {% set z_probed = printer.probe.last_z_result %} {% set z_position = printer.toolhead.position[2] %} {% set z_actual = z_position - z_probed %} SET_KINEMATIC_POSITION Z={z_actual} [gcode_macro _HOME_Z] gcode: SET_GCODE_OFFSET Z=0 # load cell probes dont need a Z offset # position toolhead for homing Z, edit for your printers size #G90 # absolute move #G1 Y50 X50 F{5 * 60} # move to X/Y position for homing # soft home the z axis to its limit so it can be moved: SET_KINEMATIC_POSITION Z={printer.toolhead.axis_maximum[2]} # Fast approach and tap PROBE PROBE_SPEED={5 * 60} # override the speed for faster homing _HOME_Z_FROM_LAST_PROBE # lift z to 2mm G91 # relative move G1 Z2 F{5 * 60} # probe at standard speed PROBE _HOME_Z_FROM_LAST_PROBE # lift z to 10mm for clearance G91 # relative move G1 Z10 F{5 * 60} Suggested Probing Temperature \u00b6 Currently, we suggest keeping the nozzle temperature below the level that causes the filament to ooze while homing and probing. 140C is a good starting point. This temperature is also low enough not to scar PEI build surfaces. Fouling of the nozzle and the print bed due to oozing filament is the #1 source of probing error with the load cell probe. Klipper does not yet have a universal way to detect poor quality taps due to filament ooze. The existing code may decide that a tap is valid when it is of poor quality. Classifying these poor quality taps is an area of active research. Klipper also lacks support for re-locating a probe point if the location has become fouled by filament ooze. Modules like quad_gantry_level will repeatedly probe the same coordinates even if a probe previously failed there. Give the above it is strongly suggested not to probe at printing temperatures. Hot Nozzle Protection \u00b6 The Voron project has a great macro for protecting your print surface from the hot nozzle. See Voron Tap's activate_gcode It is highly suggested to add something like this to your config. Nozzle Cleaning \u00b6 Before probing the nozzle should be clean. You could do this manually before every print. You can also implement a nozzle scrubber and automate the process. Here is a suggested sequence: Wait for the nozzle to heat up to probing temp (e.g. M109 S140 ) Home the machine ( G28 ) Scrub the nozzle on a brush Heat soak the print bed Perform probing tasks: QGL, bed mesh etc. Temperature Compensation for Nozzle Growth \u00b6 If you are probing at a safe temperature, the nozzle will expand after heating to printing temperatures. This will cause the nozzle to get longer and closer to the print surface. You can compensate for this with [z_thermal_adjust] . This adjustment will work across a range of printing temperatures from PLA to PC. Calculating the temp_coeff for [z_thermal_adjust] \u00b6 The easiest way to do this is to measure at 2 different temperatures. Ideally these should be the upper and lower limits of the printing temperature range. E.g. 180C and 290C. You can perform a PROBE_ACCURACY at both temperatures and then calculate the difference of the average z at both. The adjustment value is the change in nozzle length divided by the change in temperature. e.g. temp_coeff = -0.05 / (290 - 180) = -0.00045455 The expected result is a negative number. Positive values for temp_coeff move the nozzle closer to the bed and negative values move it further away. Expect to have to move the nozzle further away as it gets longer when hot. Configure [z_thermal_adjust] \u00b6 Set up z_thermal_adjust to reference the extruder as the source of temperature data. E.g.: [z_thermal_adjust nozzle] temp_coeff=-0.00045455 sensor_type: temperature_combined sensor_list: extruder combination_method: max min_temp: 0 max_temp: 400 max_z_adjustment: 0.1 Continuous Tare Filters for Toolhead Load Cells \u00b6 Klipper implements a configurable IIR filter on the MCU to provide continuous tareing of the load cell while probing. Continuous taring means the 0 value moves with drift caused by external factors like bowden tubes and thermal changes. This is aimed at toolhead sensors and moving beds that experience lots of external forces that change while probing. Installing SciPy \u00b6 The filtering code uses the excellent SciPy library to compute the filter coefficients based on the values your enter into the config. Pre-compiled SciPi builds are available for Python 3 on 32 bit Raspberry Pi systems. 32 bit + Python 3 is strongly recommended because it will streamline your installation experience. It does work with Python 2 but installation can take 30+ minutes and require installing additional tools. ~/klippy-env/bin/pip install scipy Filter Workbench \u00b6 The filter parameters should be selected based on drift seen on the printer during normal operation. A Jupyter notebook is provided in scripts, filter_workbench.ipynb , to perform a detailed investigation with real captured data and FFTs. Filtering Suggestions \u00b6 For those just trying to get a filter working follow these suggestions: The only essential option is drift_filter_cutoff_frequency . A conservative starting value is 0.5 Hz. Prusa shipped the MK4 with a setting of 0.8 Hz and the XL with 11.2 Hz. This is probably a safe range to experiment with. This value should be increased only until normal drift due to bowden tube force is eliminated. Setting this value too high will result in slow triggering and excess force going through the toolhead. Keep trigger_force low. The default is 75 g. The drift filter keeps the internal grams value very close to 0 so a large trigger force is not needed. Keep force_safety_limit to a conservative value. The default value is 2Kg and should keep your toolhead safe while experimenting. If you hit this limit the drift_filter_cutoff_frequency value may be too high. Suggestions for Load Cell Tool Boards \u00b6 This section covers suggestions for those developing toolhead boards that want to support [load_cell_probe] ADC Sensor Selection & Board Development Hints \u00b6 Ideally a sensor would meet these criteria: At least 24 bits wide Use SPI communications Has a pin can be used to indicate sample ready without SPI communications. This is often called the \"data ready\" or \"DRDY\" pin. Checking a pin is much faster than running an SPI query. Has a programmable gain amplifier gain setting of 128. This should eliminate the need for a separate amplifier. Indicates via SPI if the sensor has been reset. Detecting resets avoids timing errors in homing and using noisy data at startup. It can also help users track down wiring and grounding issues. A selectable sample rate between 350Hz and 2Khz. Very high sample rates don't turn out to be beneficial in our 3D printers because they produce so much noise when moving fast. Sample rates below 250Hz will require slower probing speeds. They also increase the force on the toolhead due to longer delays between measurements. E.g. a 500Hz sensor moving at 5mm/s has the same safety factor as a 100Hz sensor moving at only 1mm/s. If designing for under-bed applications, and you want to sense multiple load cells, use a chip that can sample all of its inputs simultaneously. Multiplex ADCs that require switching channels have a settling of several samples after each channel switch making them unsuitable for probing applications. Implementing support for a new sensor chip is not particularly difficult with Klipper's bulk_sensor and load_cell_endstop infrastructure. 5V Power Filtering \u00b6 It is strongly suggested to use larger capacitors than specified by the ADC chip manufacturer. ADC chips are usually targeted at low noise environments, like battery powered devices. Sensor manufacturers suggested application notes generally assume a quiet power supply. Treat their suggested capacitor values as minimums. 3D printers put huge amounts of noise onto the 5V bus and this can ruin the sensor's accuracy. Test the sensor on the board with a typical 3D printer power supply and active stepper drivers before deciding on smoothing capacitor sizes. Grounding & Ground Planes \u00b6 Analog ADC chips contain components that are very vulnerable to noise and ESD. A large ground plane on the first board layer under the chip can help with noise. Keep the chip away from power sections and DC to DC converters. The board should have proper grounding back to the DC supply. HX711 and HX717 Notes \u00b6 This sensor is popular because of its low cost and availability in the supply chain. However, this is a sensor with some drawbacks: The HX71x sensors use bit-bang communication which has a high overhead on the MCU. Using a sensor that communicates via SPI would save resources on the tool board's CPU. The HX71x lacks a way to communicate reset events to the MCU. Klipper detects resets with a timing heuristic but this is not ideal. Resets indicate a problem with wiring or grounding. For probing applications the HX717 version is strongly preferred because of its higher sample rate (320 vs 80). Probing speed on the HX711 should be limited to less than 2mm/s. The sample rate on the HX71x cannot be set from klipper's config. If you have the 10SPS version of the sensor (which is widely distributed) it needs to be physically re-wired to run at 80SPS.","title":"Load Cells"},{"location":"Load_Cell.html#load-cells","text":"This document describes Klipper's support for load cells. Basic load cell functionality can be used to read force data and to weigh things like filament. A calibrated force sensor is an important part of a load cell based probe.","title":"Load Cells"},{"location":"Load_Cell.html#related-documentation","text":"load_cell Config Reference load_cell G-Code Commands load_cell Status Reference","title":"Related Documentation"},{"location":"Load_Cell.html#using-load_cell_diagnostic","text":"When you first connect a load cell its good practice to check for issues by running LOAD_CELL_DIAGNOSTIC . This tool collects 10 seconds of data from the load cell and resport statistics: $ LOAD_CELL_DIAGNOSTIC // Collecting load cell data for 10 seconds... // Samples Collected: 3211 // Measured samples per second: 332.0 // Good samples: 3211, Saturated samples: 0, Unique values: 900 // Sample range: [4.01% to 4.02%] // Sample range / sensor capacity: 0.00524% Things you can check with this data: The configured sample rate of the sensor should be close to the 'Measured samples per second' value. If it is not you may have a configuration or wiring issue. 'Saturated samples' should be 0. If you have saturated samples it means the load sell is seeing more force than it can measure. 'Unique values' should be a large percentage of the 'Samples Collected' value. If 'Unique values' is 1 it is very likely a wiring issue. Tap or push on the sensor while LOAD_CELL_DIAGNOSTIC runs. If things are working correctly this should increase the 'Sample range'.","title":"Using LOAD_CELL_DIAGNOSTIC"},{"location":"Load_Cell.html#calibrating-a-load-cell","text":"Load cells are calibrated using the LOAD_CELL_CALIBRATE command. This is an interactive calibration utility that walks you though a 3 step process: First use the TARE command to establish the zero force value. This is the reference_tare_counts config value. Next you apply a known load or force to the load cell and run the CALIBRATE GRAMS=nnn command. From this the counts_per_gram value is calculated. See the next section for some suggestions on how to do this. Finally, use the ACCEPT command to save the results. You can cancel the calibration process at any time with ABORT .","title":"Calibrating a Load Cell"},{"location":"Load_Cell.html#applying-a-known-force-or-load","text":"The CALIBRATE GRAMS=nnn step can be accomplished in a number of ways. If your load cell is under a platform like a bed or filament holder it might be easiest to put a known mass on the platform. E.g. you could use a couple of 1KG filament spools. If your load cell is in the printer's toolhead a different approach is easier. Put a digital scale on the printers bed and gently lower the toolhead onto the scale (or raise the bed into the toolhead if your bed moves). You may be able to do this using the FORCE_MOVE command. But more likely you will have to manually moving the z axis with the motors off until the toolhead presses on the scale. A good calibration force would ideally be a large percentage of the load cell's rated capacity. E.g. if you have a 5Kg load cell you would ideally calibrate it with a 5kg mass. This might work well with under-bed sensors that have to support a lot of weight. For toolhead probes this may not be a load that your printer bed or toolhead can tolerate without damage. Do try to use at least 1Kg of force, most printers should tolerate this without issue. When calibrating make careful note of the values reported: $ CALIBRATE GRAMS=555 // Calibration value: -2.78% (-59803108), Counts/gram: 73039.78739, Total capacity: +/- 29.14Kg The Total capacity should be close to the theoretical rating of the load cell based on the sensor's capacity. If it is much larger you could have used a higher gain setting in the sensor or a more sensitive load cell. This isn't as critical for 32bit and 24bit sensors but is much more critical for low bit width sensors.","title":"Applying a Known Force or Load"},{"location":"Load_Cell.html#reading-force-data","text":"Force data can be read with a GCode command: LOAD_CELL_READ // 10.6g (1.94%) Data is also continuously read and can be consumed from the load_cell printer object in a macro: {% set grams = printer.load_cell.force_g %} This provides an average force over the last 1 second, similar to how temperature sensors work.","title":"Reading Force Data"},{"location":"Load_Cell.html#taring-a-load-cell","text":"Taring, sometimes called zeroing, sets the current weight reported by the load_cell to 0. This is useful for measuring relative to a known weight. e.g. when measuring a filament spool, using LOAD_CELL_TARE sets the weight to 0. Then as filament is printed the load_cell will report the weight of the filament used. LOAD_CELL_TARE // Load cell tare value: 5.32% (445903) The current tare value is reported in the printers status and can be read in a macro: {% set tare_counts = printer.load_cell.tare_counts %}","title":"Taring a Load Cell"},{"location":"Load_Cell.html#load-cell-probes","text":"","title":"Load Cell Probes"},{"location":"Load_Cell.html#related-documentation_1","text":"load_cell_probe Config Reference load_cell_probe G-Code Commands load_cell_probe Statuc Reference","title":"Related Documentation"},{"location":"Load_Cell.html#load-cell-probe-safety","text":"Because load cells are a direct nozzle contact probe there is a risk of damage to your printer if too much force is used. The load cell probing system includes a number of safety checks that try to keep your machine safe from excessive force to the toolhead. It's important to understand what they are and how they work as you can defeat most of them with poorly chosen config values.","title":"Load Cell Probe Safety"},{"location":"Load_Cell.html#calibration-check","text":"Every time a homing move starts, load_cell_probe checks that the load_cell is calibrated. If not it will stop the move with an error: !! Load Cell not calibrated .","title":"Calibration Check"},{"location":"Load_Cell.html#counts_per_gram","text":"This setting is used to convert raw sensor counts into grams. All the safety limits are in gram units for your convenience. If the counts_per_gram setting is not accurate you can easily exceed the safe force on the toolhead. You should never guess this value. Use LOAD_CELL_CALIBRATE to find your load cells actual counts_per_gram .","title":"counts_per_gram"},{"location":"Load_Cell.html#trigger_force","text":"This is the force in grams that triggers the endstop to halt the homing move. When a homing move starts the endstop tares itself with the current reading from the load cell. trigger_force is measured from that tare value. There is always some overshoot of this value when the probe collides with the bed, so be conservative. e.g. a setting of 100g could result in 350g of peak force before the toolhead stops. This overshoot will increase with faster probing speed , a low ADC sample rate or multi MCU homing .","title":"trigger_force"},{"location":"Load_Cell.html#reference_tare_counts","text":"This is the baseline tare value that is set by LOAD_CELL_CALIBRATE . This value works with force_safety_limit to limit the maximum force on the toolhead.","title":"reference_tare_counts"},{"location":"Load_Cell.html#force_safety_limit","text":"This is the maximum absolute force, relative to reference_tare_counts , that the probe will allow while homing or probing. If the MCU sees this force exceeded it will shut down the printer with the error !! Load cell endstop: too much force! . There are a number of ways this can be triggered: The first risk this protects against is picking too large of a value for drift_filter_cutoff_frequency . This can cause the drift filter to filter out a probe event and continue the homing move. If this happens the force_safety_limit acts as a backup protection. The second problem is probing repeatedly in one place. Klipper does not retract the probe when doing a single PROBE command. This can result in force applied to the toolhead at the end of a probing cycle. Because external forces can vary greatly between probing locations, load_cell_probe performs a tare before beginning each probe. If you repeat the PROBE command, load_cell_probe will tare the endstop at the current force. Multiple cycles of this will result in ever-increasing force on the toolhead. force_safety_limit stops this cycle from running out of control. Another way this run-away can happen is damage to a strain gauge. If the metal part is permanently bent it will change the reference_tare_counts of the device. This puts the starting tare value much closer to the limit making it more likely to be violated. You want to be notified if this is happening because your hardware has been permanently damaged. The final way this can be triggered is due to temperature changes. If your strain gauges are heated their reference_tare_counts may be very different at ambient temperature vs operating temperature. In this case you may need to increase the force_safety_limit to allow for thermal changes.","title":"force_safety_limit"},{"location":"Load_Cell.html#load-cell-endstop-watchdog-task","text":"When homing the load_cell_endstop starts a task on the MCU to trac measurements arriving from the sensor. If the sensor fails to send measurements for 2 sample periods the watchdog will shut down the printer with an error !! LoadCell Endstop timed out waiting on ADC data . If this happens, the most likely cause is a fault from the ADC. Inadequate grounding of your printer can be the root cause. The frame, power supply case and pint bed should all be connected to ground. You may need to ground the frame in multiple places. Anodized aluminum extrusions do not conduct electricity well. You might need to sand the area where the grounding wire is attached to make good electrical contact.","title":"Load Cell Endstop Watchdog Task"},{"location":"Load_Cell.html#load-cell-probe-setup","text":"This section covers the process for commissioning a load cell probe.","title":"Load Cell Probe Setup"},{"location":"Load_Cell.html#verify-the-load-cell-first","text":"A [load_cell_probe] is also a [load_cell] and G-code commands related to [load_cell] work with [load_cell_probe] . Before attempting to use a load cell probe, follow the directions for calibrating the load cell with CALIBRATE_LOAD_CELL and checking its operation with LOAD_CELL_DIAGNOSTIC .","title":"Verify the Load Cell First"},{"location":"Load_Cell.html#verify-probe-operation-with-load_cell_test_tap","text":"Use the command LOAD_CELL_TEST_TAP to test the operation of the load cell probe before actually trying to probe with it. This command detects taps, just like the PROBE command, but it does not move the z axis. By default, it listens for 3 taps before ending the test. You have 30 seconds to do each tap, if no taps are detected the command will time out. If this test fails, check your configuration and LOAD_CELL_DIAGNOSTIC carefully to look for issues. Load cell probes don't support the QUERY_ENDSTOPS or QUERY_PROBE commands. Use LOAD_CELL_TEST_TAP for testing functionality before probing.","title":"Verify Probe Operation With LOAD_CELL_TEST_TAP"},{"location":"Load_Cell.html#homing-macros","text":"Load cell probe is not an endstop and doesn't support endstop: prove:z_virtual_endstop . For the time being you'll need to configure your z axis with an MCU pin as its endstop. You won't actually be using the pin but for the time being you have to configure something. To home the axis with just the probe you need to set up a custom homing macro. This requires setting up homing_override . Here is a simple macro that can accomplish this. Note that the _HOME_Z_FROM_LAST_PROBE macro has to be separate because of the way macros work. The sub-call is needed so that the _HOME_Z_FROM_LAST_PROBE macro can see the result of the probe in printer.probe.last_z_result . [gcode_macro _HOME_Z_FROM_LAST_PROBE] gcode: {% set z_probed = printer.probe.last_z_result %} {% set z_position = printer.toolhead.position[2] %} {% set z_actual = z_position - z_probed %} SET_KINEMATIC_POSITION Z={z_actual} [gcode_macro _HOME_Z] gcode: SET_GCODE_OFFSET Z=0 # load cell probes dont need a Z offset # position toolhead for homing Z, edit for your printers size #G90 # absolute move #G1 Y50 X50 F{5 * 60} # move to X/Y position for homing # soft home the z axis to its limit so it can be moved: SET_KINEMATIC_POSITION Z={printer.toolhead.axis_maximum[2]} # Fast approach and tap PROBE PROBE_SPEED={5 * 60} # override the speed for faster homing _HOME_Z_FROM_LAST_PROBE # lift z to 2mm G91 # relative move G1 Z2 F{5 * 60} # probe at standard speed PROBE _HOME_Z_FROM_LAST_PROBE # lift z to 10mm for clearance G91 # relative move G1 Z10 F{5 * 60}","title":"Homing Macros"},{"location":"Load_Cell.html#suggested-probing-temperature","text":"Currently, we suggest keeping the nozzle temperature below the level that causes the filament to ooze while homing and probing. 140C is a good starting point. This temperature is also low enough not to scar PEI build surfaces. Fouling of the nozzle and the print bed due to oozing filament is the #1 source of probing error with the load cell probe. Klipper does not yet have a universal way to detect poor quality taps due to filament ooze. The existing code may decide that a tap is valid when it is of poor quality. Classifying these poor quality taps is an area of active research. Klipper also lacks support for re-locating a probe point if the location has become fouled by filament ooze. Modules like quad_gantry_level will repeatedly probe the same coordinates even if a probe previously failed there. Give the above it is strongly suggested not to probe at printing temperatures.","title":"Suggested Probing Temperature"},{"location":"Load_Cell.html#hot-nozzle-protection","text":"The Voron project has a great macro for protecting your print surface from the hot nozzle. See Voron Tap's activate_gcode It is highly suggested to add something like this to your config.","title":"Hot Nozzle Protection"},{"location":"Load_Cell.html#nozzle-cleaning","text":"Before probing the nozzle should be clean. You could do this manually before every print. You can also implement a nozzle scrubber and automate the process. Here is a suggested sequence: Wait for the nozzle to heat up to probing temp (e.g. M109 S140 ) Home the machine ( G28 ) Scrub the nozzle on a brush Heat soak the print bed Perform probing tasks: QGL, bed mesh etc.","title":"Nozzle Cleaning"},{"location":"Load_Cell.html#temperature-compensation-for-nozzle-growth","text":"If you are probing at a safe temperature, the nozzle will expand after heating to printing temperatures. This will cause the nozzle to get longer and closer to the print surface. You can compensate for this with [z_thermal_adjust] . This adjustment will work across a range of printing temperatures from PLA to PC.","title":"Temperature Compensation for Nozzle Growth"},{"location":"Load_Cell.html#calculating-the-temp_coeff-for-z_thermal_adjust","text":"The easiest way to do this is to measure at 2 different temperatures. Ideally these should be the upper and lower limits of the printing temperature range. E.g. 180C and 290C. You can perform a PROBE_ACCURACY at both temperatures and then calculate the difference of the average z at both. The adjustment value is the change in nozzle length divided by the change in temperature. e.g. temp_coeff = -0.05 / (290 - 180) = -0.00045455 The expected result is a negative number. Positive values for temp_coeff move the nozzle closer to the bed and negative values move it further away. Expect to have to move the nozzle further away as it gets longer when hot.","title":"Calculating the temp_coeff for [z_thermal_adjust]"},{"location":"Load_Cell.html#configure-z_thermal_adjust","text":"Set up z_thermal_adjust to reference the extruder as the source of temperature data. E.g.: [z_thermal_adjust nozzle] temp_coeff=-0.00045455 sensor_type: temperature_combined sensor_list: extruder combination_method: max min_temp: 0 max_temp: 400 max_z_adjustment: 0.1","title":"Configure [z_thermal_adjust]"},{"location":"Load_Cell.html#continuous-tare-filters-for-toolhead-load-cells","text":"Klipper implements a configurable IIR filter on the MCU to provide continuous tareing of the load cell while probing. Continuous taring means the 0 value moves with drift caused by external factors like bowden tubes and thermal changes. This is aimed at toolhead sensors and moving beds that experience lots of external forces that change while probing.","title":"Continuous Tare Filters for Toolhead Load Cells"},{"location":"Load_Cell.html#installing-scipy","text":"The filtering code uses the excellent SciPy library to compute the filter coefficients based on the values your enter into the config. Pre-compiled SciPi builds are available for Python 3 on 32 bit Raspberry Pi systems. 32 bit + Python 3 is strongly recommended because it will streamline your installation experience. It does work with Python 2 but installation can take 30+ minutes and require installing additional tools. ~/klippy-env/bin/pip install scipy","title":"Installing SciPy"},{"location":"Load_Cell.html#filter-workbench","text":"The filter parameters should be selected based on drift seen on the printer during normal operation. A Jupyter notebook is provided in scripts, filter_workbench.ipynb , to perform a detailed investigation with real captured data and FFTs.","title":"Filter Workbench"},{"location":"Load_Cell.html#filtering-suggestions","text":"For those just trying to get a filter working follow these suggestions: The only essential option is drift_filter_cutoff_frequency . A conservative starting value is 0.5 Hz. Prusa shipped the MK4 with a setting of 0.8 Hz and the XL with 11.2 Hz. This is probably a safe range to experiment with. This value should be increased only until normal drift due to bowden tube force is eliminated. Setting this value too high will result in slow triggering and excess force going through the toolhead. Keep trigger_force low. The default is 75 g. The drift filter keeps the internal grams value very close to 0 so a large trigger force is not needed. Keep force_safety_limit to a conservative value. The default value is 2Kg and should keep your toolhead safe while experimenting. If you hit this limit the drift_filter_cutoff_frequency value may be too high.","title":"Filtering Suggestions"},{"location":"Load_Cell.html#suggestions-for-load-cell-tool-boards","text":"This section covers suggestions for those developing toolhead boards that want to support [load_cell_probe]","title":"Suggestions for Load Cell Tool Boards"},{"location":"Load_Cell.html#adc-sensor-selection-board-development-hints","text":"Ideally a sensor would meet these criteria: At least 24 bits wide Use SPI communications Has a pin can be used to indicate sample ready without SPI communications. This is often called the \"data ready\" or \"DRDY\" pin. Checking a pin is much faster than running an SPI query. Has a programmable gain amplifier gain setting of 128. This should eliminate the need for a separate amplifier. Indicates via SPI if the sensor has been reset. Detecting resets avoids timing errors in homing and using noisy data at startup. It can also help users track down wiring and grounding issues. A selectable sample rate between 350Hz and 2Khz. Very high sample rates don't turn out to be beneficial in our 3D printers because they produce so much noise when moving fast. Sample rates below 250Hz will require slower probing speeds. They also increase the force on the toolhead due to longer delays between measurements. E.g. a 500Hz sensor moving at 5mm/s has the same safety factor as a 100Hz sensor moving at only 1mm/s. If designing for under-bed applications, and you want to sense multiple load cells, use a chip that can sample all of its inputs simultaneously. Multiplex ADCs that require switching channels have a settling of several samples after each channel switch making them unsuitable for probing applications. Implementing support for a new sensor chip is not particularly difficult with Klipper's bulk_sensor and load_cell_endstop infrastructure.","title":"ADC Sensor Selection &amp; Board Development Hints"},{"location":"Load_Cell.html#5v-power-filtering","text":"It is strongly suggested to use larger capacitors than specified by the ADC chip manufacturer. ADC chips are usually targeted at low noise environments, like battery powered devices. Sensor manufacturers suggested application notes generally assume a quiet power supply. Treat their suggested capacitor values as minimums. 3D printers put huge amounts of noise onto the 5V bus and this can ruin the sensor's accuracy. Test the sensor on the board with a typical 3D printer power supply and active stepper drivers before deciding on smoothing capacitor sizes.","title":"5V Power Filtering"},{"location":"Load_Cell.html#grounding-ground-planes","text":"Analog ADC chips contain components that are very vulnerable to noise and ESD. A large ground plane on the first board layer under the chip can help with noise. Keep the chip away from power sections and DC to DC converters. The board should have proper grounding back to the DC supply.","title":"Grounding &amp; Ground Planes"},{"location":"Load_Cell.html#hx711-and-hx717-notes","text":"This sensor is popular because of its low cost and availability in the supply chain. However, this is a sensor with some drawbacks: The HX71x sensors use bit-bang communication which has a high overhead on the MCU. Using a sensor that communicates via SPI would save resources on the tool board's CPU. The HX71x lacks a way to communicate reset events to the MCU. Klipper detects resets with a timing heuristic but this is not ideal. Resets indicate a problem with wiring or grounding. For probing applications the HX717 version is strongly preferred because of its higher sample rate (320 vs 80). Probing speed on the HX711 should be limited to less than 2mm/s. The sample rate on the HX71x cannot be set from klipper's config. If you have the 10SPS version of the sensor (which is widely distributed) it needs to be physically re-wired to run at 80SPS.","title":"HX711 and HX717 Notes"},{"location":"MCU_Commands.html","text":"MCU commands \u00b6 This document provides information on the low-level micro-controller commands that are sent from the Klipper \"host\" software and processed by the Klipper micro-controller software. This document is not an authoritative reference for these commands, nor is it an exclusive list of all available commands. This document may be useful for developers interested in understanding the low-level micro-controller commands. See the protocol document for more information on the format of commands and their transmission. The commands here are described using their \"printf\" style syntax - for those unfamiliar with that format, just note that where a '%...' sequence is seen it should be replaced with an actual integer. For example, a description with \"count=%c\" could be replaced with the text \"count=10\". Note that parameters that are considered \"enumerations\" (see the above protocol document) take a string value which is automatically converted to an integer value for the micro-controller. This is common with parameters named \"pin\" (or that have a suffix of \"_pin\"). Startup Commands \u00b6 It may be necessary to take certain one-time actions to configure the micro-controller and its peripherals. This section lists common commands available for that purpose. Unlike most micro-controller commands, these commands run as soon as they are received and they do not require any particular setup. Common startup commands: set_digital_out pin=%u value=%c : This command immediately configures the given pin as a digital out GPIO and it sets it to either a low level (value=0) or a high level (value=1). This command may be useful for configuring the initial value of LEDs and for configuring the initial value of stepper driver micro-stepping pins. set_pwm_out pin=%u cycle_ticks=%u value=%hu : This command will immediately configure the given pin to use hardware based pulse-width-modulation (PWM) with the given number of cycle_ticks. The \"cycle_ticks\" is the number of MCU clock ticks each power on and power off cycle should last. A cycle_ticks value of 1 can be used to request the fastest possible cycle time. The \"value\" parameter is between 0 and 255 with 0 indicating a full off state and 255 indicating a full on state. This command may be useful for enabling CPU and nozzle cooling fans. Low-level micro-controller configuration \u00b6 Most commands in the micro-controller require an initial setup before they can be successfully invoked. This section provides an overview of the configuration process. This section and the following sections are likely only of interest to developers interested in the internal details of Klipper. When the host first connects to the micro-controller it always starts by obtaining a data dictionary (see protocol for more information). After the data dictionary is obtained the host will check if the micro-controller is in a \"configured\" state and configure it if not. Configuration involves the following phases: get_config : The host starts by checking if the micro-controller is already configured. The micro-controller responds to this command with a \"config\" response message. The micro-controller software always starts in an unconfigured state at power-on. It remains in this state until the host completes the configuration processes (by issuing a finalize_config command). If the micro-controller is already configured from a previous session (and is configured with the desired settings) then no further action is needed by the host and the configuration process ends successfully. allocate_oids count=%c : This command is issued to inform the micro-controller of the maximum number of object-ids (oid) that the host requires. It is only valid to issue this command once. An oid is an integer identifier allocated to each stepper, each endstop, and each schedulable gpio pin. The host determines in advance the number of oids it will require to operate the hardware and passes this to the micro-controller so that it may allocate sufficient memory to store a mapping from oid to internal object. config_XXX oid=%c ... : By convention any command starting with the \"config_\" prefix creates a new micro-controller object and assigns the given oid to it. For example, the config_digital_out command will configure the specified pin as a digital output GPIO and create an internal object that the host can use to schedule changes to the given GPIO. The oid parameter passed into the config command is selected by the host and must be between zero and the maximum count supplied in the allocate_oids command. The config commands may only be run when the micro-controller is not in a configured state (ie, prior to the host sending finalize_config) and after the allocate_oids command has been sent. finalize_config crc=%u : The finalize_config command transitions the micro-controller from an unconfigured state to a configured state. The crc parameter passed to the micro-controller is stored and provided back to the host in \"config\" response messages. By convention, the host takes a 32bit CRC of the configuration it will request and at the start of subsequent communication sessions it checks that the CRC stored in the micro-controller exactly matches its desired CRC. If the CRC does not match then the host knows the micro-controller has not been configured in the state desired by the host. Common micro-controller objects \u00b6 This section lists some commonly used config commands. config_digital_out oid=%c pin=%u value=%c default_value=%c max_duration=%u : This command creates an internal micro-controller object for the given GPIO 'pin'. The pin will be configured in digital output mode and set to an initial value as specified by 'value' (0 for low, 1 for high). Creating a digital_out object allows the host to schedule GPIO updates for the given pin at specified times (see the queue_digital_out command described below). Should the micro-controller software go into shutdown mode then all configured digital_out objects will be set to 'default_value'. The 'max_duration' parameter is used to implement a safety check - if it is non-zero then it is the maximum number of clock ticks that the host may set the given GPIO to a non-default value without further updates. For example, if the default_value is zero and the max_duration is 16000 then if the host sets the gpio to a value of one then it must schedule another update to the gpio pin (to either zero or one) within 16000 clock ticks. This safety feature can be used with heater pins to ensure the host does not enable the heater and then go off-line. config_pwm_out oid=%c pin=%u cycle_ticks=%u value=%hu default_value=%hu max_duration=%u : This command creates an internal object for hardware based PWM pins that the host may schedule updates for. Its usage is analogous to config_digital_out - see the description of the 'set_pwm_out' and 'config_digital_out' commands for parameter description. config_analog_in oid=%c pin=%u : This command is used to configure a pin in analog input sampling mode. Once configured, the pin can be sampled at regular interval using the query_analog_in command (see below). config_stepper oid=%c step_pin=%c dir_pin=%c invert_step=%c step_pulse_ticks=%u : This command creates an internal stepper object. The 'step_pin' and 'dir_pin' parameters specify the step and direction pins respectively; this command will configure them in digital output mode. The 'invert_step' parameter specifies whether a step occurs on a rising edge (invert_step=0) or falling edge (invert_step=1). The 'step_pulse_ticks' parameter specifies the minimum duration of the step pulse. If the mcu exports the constant 'STEPPER_BOTH_EDGE=1' then setting step_pulse_ticks=0 and invert_step=-1 will setup for stepping on both the rising and falling edges of the step pin. config_endstop oid=%c pin=%c pull_up=%c stepper_count=%c : This command creates an internal \"endstop\" object. It is used to specify the endstop pins and to enable \"homing\" operations (see the endstop_home command below). The command will configure the specified pin in digital input mode. The 'pull_up' parameter determines whether hardware provided pullup resistors for the pin (if available) will be enabled. The 'stepper_count' parameter specifies the maximum number of steppers that this endstop may need to halt during a homing operation (see endstop_home below). config_spi oid=%c bus=%u pin=%u mode=%u rate=%u shutdown_msg=%*s : This command creates an internal SPI object. It is used with spi_transfer and spi_send commands (see below). The \"bus\" identifies the SPI bus to use (if the micro-controller has more than one SPI bus available). The \"pin\" specifies the chip select (CS) pin for the device. The \"mode\" is the SPI mode (should be between 0 and 3). The \"rate\" parameter specifies the SPI bus rate (in cycles per second). Finally, the \"shutdown_msg\" is an SPI command to send to the given device should the micro-controller go into a shutdown state. config_spi_without_cs oid=%c bus=%u mode=%u rate=%u shutdown_msg=%*s : This command is similar to config_spi, but without a CS pin definition. It is useful for SPI devices that do not have a chip select line. Common commands \u00b6 This section lists some commonly used run-time commands. It is likely only of interest to developers looking to gain insight into Klipper. set_digital_out_pwm_cycle oid=%c cycle_ticks=%u : This command configures a digital output pin (as created by config_digital_out) to use \"software PWM\". The 'cycle_ticks' is the number of clock ticks for the PWM cycle. Because the output switching is implemented in the micro-controller software, it is recommended that 'cycle_ticks' correspond to a time of 10ms or greater. queue_digital_out oid=%c clock=%u on_ticks=%u : This command will schedule a change to a digital output GPIO pin at the given clock time. To use this command a 'config_digital_out' command with the same 'oid' parameter must have been issued during micro-controller configuration. If 'set_digital_out_pwm_cycle' has been called then 'on_ticks' is the on duration (in clock ticks) for the pwm cycle. Otherwise, 'on_ticks' should be either 0 (for low voltage) or 1 (for high voltage). queue_pwm_out oid=%c clock=%u value=%hu : Schedules a change to a hardware PWM output pin. See the 'queue_digital_out' and 'config_pwm_out' commands for more info. query_analog_in oid=%c clock=%u sample_ticks=%u sample_count=%c rest_ticks=%u min_value=%hu max_value=%hu : This command sets up a recurring schedule of analog input samples. To use this command a 'config_analog_in' command with the same 'oid' parameter must have been issued during micro-controller configuration. The samples will start as of 'clock' time, it will report on the obtained value every 'rest_ticks' clock ticks, it will over-sample 'sample_count' number of times, and it will pause 'sample_ticks' number of clock ticks between over-sample samples. The 'min_value' and 'max_value' parameters implement a safety feature - the micro-controller software will verify the sampled value (after any oversampling) is always between the supplied range. This is intended for use with pins attached to thermistors controlling heaters - it can be used to check that a heater is within a temperature range. get_clock : This command causes the micro-controller to generate a \"clock\" response message. The host sends this command once a second to obtain the value of the micro-controller clock and to estimate the drift between host and micro-controller clocks. It enables the host to accurately estimate the micro-controller clock. Stepper commands \u00b6 queue_step oid=%c interval=%u count=%hu add=%hi : This command schedules 'count' number of steps for the given stepper, with 'interval' number of clock ticks between each step. The first step will be 'interval' number of clock ticks since the last scheduled step for the given stepper. If 'add' is non-zero then the interval will be adjusted by 'add' amount after each step. This command appends the given interval/count/add sequence to a per-stepper queue. There may be hundreds of these sequences queued during normal operation. New sequence are appended to the end of the queue and as each sequence completes its 'count' number of steps it is popped from the front of the queue. This system allows the micro-controller to queue potentially hundreds of thousands of steps - all with reliable and predictable schedule times. set_next_step_dir oid=%c dir=%c : This command specifies the value of the dir_pin that the next queue_step command will use. reset_step_clock oid=%c clock=%u : Normally, step timing is relative to the last step for a given stepper. This command resets the clock so that the next step is relative to the supplied 'clock' time. The host usually only sends this command at the start of a print. stepper_get_position oid=%c : This command causes the micro-controller to generate a \"stepper_position\" response message with the stepper's current position. The position is the total number of steps generated with dir=1 minus the total number of steps generated with dir=0. endstop_home oid=%c clock=%u sample_ticks=%u sample_count=%c rest_ticks=%u pin_value=%c : This command is used during stepper \"homing\" operations. To use this command a 'config_endstop' command with the same 'oid' parameter must have been issued during micro-controller configuration. When this command is invoked, the micro-controller will sample the endstop pin every 'rest_ticks' clock ticks and check if it has a value equal to 'pin_value'. If the value matches (and it continues to match for 'sample_count' additional samples spread 'sample_ticks' apart) then the movement queue for the associated stepper will be cleared and the stepper will come to an immediate halt. The host uses this command to implement homing - the host instructs the endstop to sample for the endstop trigger and then it issues a series of queue_step commands to move a stepper towards the endstop. Once the stepper hits the endstop, the trigger will be detected, the movement halted, and the host notified. Move queue \u00b6 Each queue_step command utilizes an entry in the micro-controller \"move queue\". This queue is allocated when it receives the \"finalize_config\" command, and it reports the number of available queue entries in \"config\" response messages. It is the responsibility of the host to ensure that there is available space in the queue before sending a queue_step command. The host does this by calculating when each queue_step command completes and scheduling new queue_step commands accordingly. SPI Commands \u00b6 spi_transfer oid=%c data=%*s : This command causes the micro-controller to send 'data' to the spi device specified by 'oid' and it generates a \"spi_transfer_response\" response message with the data returned during the transmission. spi_send oid=%c data=%*s : This command is similar to \"spi_transfer\", but it does not generate a \"spi_transfer_response\" message.","title":"MCU commands"},{"location":"MCU_Commands.html#mcu-commands","text":"This document provides information on the low-level micro-controller commands that are sent from the Klipper \"host\" software and processed by the Klipper micro-controller software. This document is not an authoritative reference for these commands, nor is it an exclusive list of all available commands. This document may be useful for developers interested in understanding the low-level micro-controller commands. See the protocol document for more information on the format of commands and their transmission. The commands here are described using their \"printf\" style syntax - for those unfamiliar with that format, just note that where a '%...' sequence is seen it should be replaced with an actual integer. For example, a description with \"count=%c\" could be replaced with the text \"count=10\". Note that parameters that are considered \"enumerations\" (see the above protocol document) take a string value which is automatically converted to an integer value for the micro-controller. This is common with parameters named \"pin\" (or that have a suffix of \"_pin\").","title":"MCU commands"},{"location":"MCU_Commands.html#startup-commands","text":"It may be necessary to take certain one-time actions to configure the micro-controller and its peripherals. This section lists common commands available for that purpose. Unlike most micro-controller commands, these commands run as soon as they are received and they do not require any particular setup. Common startup commands: set_digital_out pin=%u value=%c : This command immediately configures the given pin as a digital out GPIO and it sets it to either a low level (value=0) or a high level (value=1). This command may be useful for configuring the initial value of LEDs and for configuring the initial value of stepper driver micro-stepping pins. set_pwm_out pin=%u cycle_ticks=%u value=%hu : This command will immediately configure the given pin to use hardware based pulse-width-modulation (PWM) with the given number of cycle_ticks. The \"cycle_ticks\" is the number of MCU clock ticks each power on and power off cycle should last. A cycle_ticks value of 1 can be used to request the fastest possible cycle time. The \"value\" parameter is between 0 and 255 with 0 indicating a full off state and 255 indicating a full on state. This command may be useful for enabling CPU and nozzle cooling fans.","title":"Startup Commands"},{"location":"MCU_Commands.html#low-level-micro-controller-configuration","text":"Most commands in the micro-controller require an initial setup before they can be successfully invoked. This section provides an overview of the configuration process. This section and the following sections are likely only of interest to developers interested in the internal details of Klipper. When the host first connects to the micro-controller it always starts by obtaining a data dictionary (see protocol for more information). After the data dictionary is obtained the host will check if the micro-controller is in a \"configured\" state and configure it if not. Configuration involves the following phases: get_config : The host starts by checking if the micro-controller is already configured. The micro-controller responds to this command with a \"config\" response message. The micro-controller software always starts in an unconfigured state at power-on. It remains in this state until the host completes the configuration processes (by issuing a finalize_config command). If the micro-controller is already configured from a previous session (and is configured with the desired settings) then no further action is needed by the host and the configuration process ends successfully. allocate_oids count=%c : This command is issued to inform the micro-controller of the maximum number of object-ids (oid) that the host requires. It is only valid to issue this command once. An oid is an integer identifier allocated to each stepper, each endstop, and each schedulable gpio pin. The host determines in advance the number of oids it will require to operate the hardware and passes this to the micro-controller so that it may allocate sufficient memory to store a mapping from oid to internal object. config_XXX oid=%c ... : By convention any command starting with the \"config_\" prefix creates a new micro-controller object and assigns the given oid to it. For example, the config_digital_out command will configure the specified pin as a digital output GPIO and create an internal object that the host can use to schedule changes to the given GPIO. The oid parameter passed into the config command is selected by the host and must be between zero and the maximum count supplied in the allocate_oids command. The config commands may only be run when the micro-controller is not in a configured state (ie, prior to the host sending finalize_config) and after the allocate_oids command has been sent. finalize_config crc=%u : The finalize_config command transitions the micro-controller from an unconfigured state to a configured state. The crc parameter passed to the micro-controller is stored and provided back to the host in \"config\" response messages. By convention, the host takes a 32bit CRC of the configuration it will request and at the start of subsequent communication sessions it checks that the CRC stored in the micro-controller exactly matches its desired CRC. If the CRC does not match then the host knows the micro-controller has not been configured in the state desired by the host.","title":"Low-level micro-controller configuration"},{"location":"MCU_Commands.html#common-micro-controller-objects","text":"This section lists some commonly used config commands. config_digital_out oid=%c pin=%u value=%c default_value=%c max_duration=%u : This command creates an internal micro-controller object for the given GPIO 'pin'. The pin will be configured in digital output mode and set to an initial value as specified by 'value' (0 for low, 1 for high). Creating a digital_out object allows the host to schedule GPIO updates for the given pin at specified times (see the queue_digital_out command described below). Should the micro-controller software go into shutdown mode then all configured digital_out objects will be set to 'default_value'. The 'max_duration' parameter is used to implement a safety check - if it is non-zero then it is the maximum number of clock ticks that the host may set the given GPIO to a non-default value without further updates. For example, if the default_value is zero and the max_duration is 16000 then if the host sets the gpio to a value of one then it must schedule another update to the gpio pin (to either zero or one) within 16000 clock ticks. This safety feature can be used with heater pins to ensure the host does not enable the heater and then go off-line. config_pwm_out oid=%c pin=%u cycle_ticks=%u value=%hu default_value=%hu max_duration=%u : This command creates an internal object for hardware based PWM pins that the host may schedule updates for. Its usage is analogous to config_digital_out - see the description of the 'set_pwm_out' and 'config_digital_out' commands for parameter description. config_analog_in oid=%c pin=%u : This command is used to configure a pin in analog input sampling mode. Once configured, the pin can be sampled at regular interval using the query_analog_in command (see below). config_stepper oid=%c step_pin=%c dir_pin=%c invert_step=%c step_pulse_ticks=%u : This command creates an internal stepper object. The 'step_pin' and 'dir_pin' parameters specify the step and direction pins respectively; this command will configure them in digital output mode. The 'invert_step' parameter specifies whether a step occurs on a rising edge (invert_step=0) or falling edge (invert_step=1). The 'step_pulse_ticks' parameter specifies the minimum duration of the step pulse. If the mcu exports the constant 'STEPPER_BOTH_EDGE=1' then setting step_pulse_ticks=0 and invert_step=-1 will setup for stepping on both the rising and falling edges of the step pin. config_endstop oid=%c pin=%c pull_up=%c stepper_count=%c : This command creates an internal \"endstop\" object. It is used to specify the endstop pins and to enable \"homing\" operations (see the endstop_home command below). The command will configure the specified pin in digital input mode. The 'pull_up' parameter determines whether hardware provided pullup resistors for the pin (if available) will be enabled. The 'stepper_count' parameter specifies the maximum number of steppers that this endstop may need to halt during a homing operation (see endstop_home below). config_spi oid=%c bus=%u pin=%u mode=%u rate=%u shutdown_msg=%*s : This command creates an internal SPI object. It is used with spi_transfer and spi_send commands (see below). The \"bus\" identifies the SPI bus to use (if the micro-controller has more than one SPI bus available). The \"pin\" specifies the chip select (CS) pin for the device. The \"mode\" is the SPI mode (should be between 0 and 3). The \"rate\" parameter specifies the SPI bus rate (in cycles per second). Finally, the \"shutdown_msg\" is an SPI command to send to the given device should the micro-controller go into a shutdown state. config_spi_without_cs oid=%c bus=%u mode=%u rate=%u shutdown_msg=%*s : This command is similar to config_spi, but without a CS pin definition. It is useful for SPI devices that do not have a chip select line.","title":"Common micro-controller objects"},{"location":"MCU_Commands.html#common-commands","text":"This section lists some commonly used run-time commands. It is likely only of interest to developers looking to gain insight into Klipper. set_digital_out_pwm_cycle oid=%c cycle_ticks=%u : This command configures a digital output pin (as created by config_digital_out) to use \"software PWM\". The 'cycle_ticks' is the number of clock ticks for the PWM cycle. Because the output switching is implemented in the micro-controller software, it is recommended that 'cycle_ticks' correspond to a time of 10ms or greater. queue_digital_out oid=%c clock=%u on_ticks=%u : This command will schedule a change to a digital output GPIO pin at the given clock time. To use this command a 'config_digital_out' command with the same 'oid' parameter must have been issued during micro-controller configuration. If 'set_digital_out_pwm_cycle' has been called then 'on_ticks' is the on duration (in clock ticks) for the pwm cycle. Otherwise, 'on_ticks' should be either 0 (for low voltage) or 1 (for high voltage). queue_pwm_out oid=%c clock=%u value=%hu : Schedules a change to a hardware PWM output pin. See the 'queue_digital_out' and 'config_pwm_out' commands for more info. query_analog_in oid=%c clock=%u sample_ticks=%u sample_count=%c rest_ticks=%u min_value=%hu max_value=%hu : This command sets up a recurring schedule of analog input samples. To use this command a 'config_analog_in' command with the same 'oid' parameter must have been issued during micro-controller configuration. The samples will start as of 'clock' time, it will report on the obtained value every 'rest_ticks' clock ticks, it will over-sample 'sample_count' number of times, and it will pause 'sample_ticks' number of clock ticks between over-sample samples. The 'min_value' and 'max_value' parameters implement a safety feature - the micro-controller software will verify the sampled value (after any oversampling) is always between the supplied range. This is intended for use with pins attached to thermistors controlling heaters - it can be used to check that a heater is within a temperature range. get_clock : This command causes the micro-controller to generate a \"clock\" response message. The host sends this command once a second to obtain the value of the micro-controller clock and to estimate the drift between host and micro-controller clocks. It enables the host to accurately estimate the micro-controller clock.","title":"Common commands"},{"location":"MCU_Commands.html#stepper-commands","text":"queue_step oid=%c interval=%u count=%hu add=%hi : This command schedules 'count' number of steps for the given stepper, with 'interval' number of clock ticks between each step. The first step will be 'interval' number of clock ticks since the last scheduled step for the given stepper. If 'add' is non-zero then the interval will be adjusted by 'add' amount after each step. This command appends the given interval/count/add sequence to a per-stepper queue. There may be hundreds of these sequences queued during normal operation. New sequence are appended to the end of the queue and as each sequence completes its 'count' number of steps it is popped from the front of the queue. This system allows the micro-controller to queue potentially hundreds of thousands of steps - all with reliable and predictable schedule times. set_next_step_dir oid=%c dir=%c : This command specifies the value of the dir_pin that the next queue_step command will use. reset_step_clock oid=%c clock=%u : Normally, step timing is relative to the last step for a given stepper. This command resets the clock so that the next step is relative to the supplied 'clock' time. The host usually only sends this command at the start of a print. stepper_get_position oid=%c : This command causes the micro-controller to generate a \"stepper_position\" response message with the stepper's current position. The position is the total number of steps generated with dir=1 minus the total number of steps generated with dir=0. endstop_home oid=%c clock=%u sample_ticks=%u sample_count=%c rest_ticks=%u pin_value=%c : This command is used during stepper \"homing\" operations. To use this command a 'config_endstop' command with the same 'oid' parameter must have been issued during micro-controller configuration. When this command is invoked, the micro-controller will sample the endstop pin every 'rest_ticks' clock ticks and check if it has a value equal to 'pin_value'. If the value matches (and it continues to match for 'sample_count' additional samples spread 'sample_ticks' apart) then the movement queue for the associated stepper will be cleared and the stepper will come to an immediate halt. The host uses this command to implement homing - the host instructs the endstop to sample for the endstop trigger and then it issues a series of queue_step commands to move a stepper towards the endstop. Once the stepper hits the endstop, the trigger will be detected, the movement halted, and the host notified.","title":"Stepper commands"},{"location":"MCU_Commands.html#move-queue","text":"Each queue_step command utilizes an entry in the micro-controller \"move queue\". This queue is allocated when it receives the \"finalize_config\" command, and it reports the number of available queue entries in \"config\" response messages. It is the responsibility of the host to ensure that there is available space in the queue before sending a queue_step command. The host does this by calculating when each queue_step command completes and scheduling new queue_step commands accordingly.","title":"Move queue"},{"location":"MCU_Commands.html#spi-commands","text":"spi_transfer oid=%c data=%*s : This command causes the micro-controller to send 'data' to the spi device specified by 'oid' and it generates a \"spi_transfer_response\" response message with the data returned during the transmission. spi_send oid=%c data=%*s : This command is similar to \"spi_transfer\", but it does not generate a \"spi_transfer_response\" message.","title":"SPI Commands"},{"location":"Manual_Level.html","text":"Manual leveling \u00b6 This document describes tools for calibrating a Z endstop and for performing adjustments to bed leveling screws. Calibrating a Z endstop \u00b6 An accurate Z endstop position is critical to obtaining high quality prints. Note, though, the accuracy of the Z endstop switch itself can be a limiting factor. If one is using Trinamic stepper motor drivers then consider enabling endstop phase detection to improve the accuracy of the switch. To perform a Z endstop calibration, home the printer, command the head to move to a Z position that is at least five millimeters above the bed (if it is not already), command the head to move to an XY position near the center of the bed, then navigate to the OctoPrint terminal tab and run: Z_ENDSTOP_CALIBRATE Then follow the steps described at \"the paper test\" to determine the actual distance between the nozzle and bed at the given location. Once those steps are complete one can ACCEPT the position and save the results to the config file with: SAVE_CONFIG It's preferable to use a Z endstop switch on the opposite end of the Z axis from the bed. (Homing away from the bed is more robust as then it is generally always safe to home the Z.) However, if one must home towards the bed it is recommended to adjust the endstop so that it triggers a small distance (eg, .5mm) above the bed. Almost all endstop switches can safely be depressed a small distance beyond their trigger point. When this is done, one should find that the Z_ENDSTOP_CALIBRATE command reports a small positive value (eg, .5mm) for the Z position_endstop. Triggering the endstop while it is still some distance from the bed reduces the risk of inadvertent bed crashes. Some printers have the ability to manually adjust the location of the physical endstop switch. However, it's recommended to perform Z endstop positioning in software with Klipper - once the physical location of the endstop is in a convenient location, one can make any further adjustments by running Z_ENDSTOP_CALIBRATE or by manually updating the Z position_endstop in the configuration file. Adjusting bed leveling screws \u00b6 The secret to getting good bed leveling with bed leveling screws is to utilize the printer's high precision motion system during the bed leveling process itself. This is done by commanding the nozzle to a position near each bed screw and then adjusting that screw until the bed is a set distance from the nozzle. Klipper has a tool to assist with this. In order to use the tool it is necessary to specify each screw XY location. This is done by creating a [bed_screws] config section. For example, it might look something similar to: [bed_screws] screw1: 100, 50 screw2: 100, 150 screw3: 150, 100 If a bed screw is under the bed, then specify the XY position directly above the screw. If the screw is outside the bed then specify an XY position closest to the screw that is still within the range of the bed. Once the config file is ready, run RESTART to load that config, and then one can start the tool by running: BED_SCREWS_ADJUST This tool will move the printer's nozzle to each screw XY location and then move the nozzle to a Z=0 height. At this point one can use the \"paper test\" to adjust the bed screw directly under the nozzle. See the information described in \"the paper test\" , but adjust the bed screw instead of commanding the nozzle to different heights. Adjust the bed screw until there is a small amount of friction when pushing the paper back and forth. Once the screw is adjusted so that a small amount of friction is felt, run either the ACCEPT or ADJUSTED command. Use the ADJUSTED command if the bed screw needed an adjustment (typically anything more than about 1/8th of a turn of the screw). Use the ACCEPT command if no significant adjustment is necessary. Both commands will cause the tool to proceed to the next screw. (When an ADJUSTED command is used, the tool will schedule an additional cycle of bed screw adjustments; the tool completes successfully when all bed screws are verified to not require any significant adjustments.) One can use the ABORT command to exit the tool early. This system works best when the printer has a flat printing surface (such as glass) and has straight rails. Upon successful completion of the bed leveling tool the bed should be ready for printing. Fine grained bed screw adjustments \u00b6 If the printer uses three bed screws and all three screws are under the bed, then it may be possible to perform a second \"high precision\" bed leveling step. This is done by commanding the nozzle to locations where the bed moves a larger distance with each bed screw adjustment. For example, consider a bed with screws at locations A, B, and C: For each adjustment made to the bed screw at location C, the bed will swing along a pendulum defined by the remaining two bed screws (shown here as a green line). In this situation, each adjustment to the bed screw at C will move the bed at position D a further amount than directly at C. It is thus possible to make an improved C screw adjustment when the nozzle is at position D. To enable this feature, one would determine the additional nozzle coordinates and add them to the config file. For example, it might look like: [bed_screws] screw1: 100, 50 screw1_fine_adjust: 0, 0 screw2: 100, 150 screw2_fine_adjust: 300, 300 screw3: 150, 100 screw3_fine_adjust: 0, 100 When this feature is enabled, the BED_SCREWS_ADJUST tool will first prompt for coarse adjustments directly above each screw position, and once those are accepted, it will prompt for fine adjustments at the additional locations. Continue to use ACCEPT and ADJUSTED at each position. Adjusting bed leveling screws using the bed probe \u00b6 This is another way to calibrate the bed level using the bed probe. To use it you must have a Z probe (BL Touch, Inductive sensor, etc). To enable this feature, one would determine the nozzle coordinates such that the Z probe is above the screws, and then add them to the config file. For example, it might look like: [screws_tilt_adjust] screw1: -5, 30 screw1_name: front left screw screw2: 155, 30 screw2_name: front right screw screw3: 155, 190 screw3_name: rear right screw screw4: -5, 190 screw4_name: rear left screw horizontal_move_z: 10. speed: 50. screw_thread: CW-M3 The screw1 is always the reference point for the others, so the system assumes that screw1 is at the correct height. Always run G28 first and then run SCREWS_TILT_CALCULATE - it should produce output similar to: Send: G28 Recv: ok Send: SCREWS_TILT_CALCULATE Recv: // 01:20 means 1 full turn and 20 minutes, CW=clockwise, CCW=counter-clockwise Recv: // front left screw (base) : x=-5.0, y=30.0, z=2.48750 Recv: // front right screw : x=155.0, y=30.0, z=2.36000 : adjust CW 01:15 Recv: // rear right screw : y=155.0, y=190.0, z=2.71500 : adjust CCW 00:50 Recv: // read left screw : x=-5.0, y=190.0, z=2.47250 : adjust CW 00:02 Recv: ok This means that: front left screw is the reference point you must not change it. front right screw must be turned clockwise 1 full turn and a quarter turn rear right screw must be turned counter-clockwise 50 minutes rear left screw must be turned clockwise 2 minutes (not need it's ok) Note that \"minutes\" refers to \"minutes of a clock face\". So, for example, 15 minutes is a quarter of a full turn. Repeat the process several times until you get a good level bed - normally when all adjustments are below 6 minutes. If using a probe that is mounted on the side of the hotend (that is, it has an X or Y offset) then note that adjusting the bed tilt will invalidate any previous probe calibration that was performed with a tilted bed. Be sure to run probe calibration after the bed screws have been adjusted. The MAX_DEVIATION parameter is useful when a saved bed mesh is used, to ensure that the bed level has not drifted too far from where it was when the mesh was created. For example, SCREWS_TILT_CALCULATE MAX_DEVIATION=0.01 can be added to the custom start gcode of the slicer before the mesh is loaded. It will abort the print if the configured limit is exceeded (0.01mm in this example), giving the user a chance to adjust the screws and restart the print. The DIRECTION parameter is useful if you can turn your bed adjustment screws in one direction only. For example, you might have screws that start tightened in their lowest (or highest) possible position, which can only be turned in a single direction, to raise (or lower) the bed. If you can only turn the screws clockwise, run SCREWS_TILT_CALCULATE DIRECTION=CW . If you can only turn them counter-clockwise, run SCREWS_TILT_CALCULATE DIRECTION=CCW . A suitable reference point will be chosen such that the bed can be leveled by turning all the screws in the given direction.","title":"Manual leveling"},{"location":"Manual_Level.html#manual-leveling","text":"This document describes tools for calibrating a Z endstop and for performing adjustments to bed leveling screws.","title":"Manual leveling"},{"location":"Manual_Level.html#calibrating-a-z-endstop","text":"An accurate Z endstop position is critical to obtaining high quality prints. Note, though, the accuracy of the Z endstop switch itself can be a limiting factor. If one is using Trinamic stepper motor drivers then consider enabling endstop phase detection to improve the accuracy of the switch. To perform a Z endstop calibration, home the printer, command the head to move to a Z position that is at least five millimeters above the bed (if it is not already), command the head to move to an XY position near the center of the bed, then navigate to the OctoPrint terminal tab and run: Z_ENDSTOP_CALIBRATE Then follow the steps described at \"the paper test\" to determine the actual distance between the nozzle and bed at the given location. Once those steps are complete one can ACCEPT the position and save the results to the config file with: SAVE_CONFIG It's preferable to use a Z endstop switch on the opposite end of the Z axis from the bed. (Homing away from the bed is more robust as then it is generally always safe to home the Z.) However, if one must home towards the bed it is recommended to adjust the endstop so that it triggers a small distance (eg, .5mm) above the bed. Almost all endstop switches can safely be depressed a small distance beyond their trigger point. When this is done, one should find that the Z_ENDSTOP_CALIBRATE command reports a small positive value (eg, .5mm) for the Z position_endstop. Triggering the endstop while it is still some distance from the bed reduces the risk of inadvertent bed crashes. Some printers have the ability to manually adjust the location of the physical endstop switch. However, it's recommended to perform Z endstop positioning in software with Klipper - once the physical location of the endstop is in a convenient location, one can make any further adjustments by running Z_ENDSTOP_CALIBRATE or by manually updating the Z position_endstop in the configuration file.","title":"Calibrating a Z endstop"},{"location":"Manual_Level.html#adjusting-bed-leveling-screws","text":"The secret to getting good bed leveling with bed leveling screws is to utilize the printer's high precision motion system during the bed leveling process itself. This is done by commanding the nozzle to a position near each bed screw and then adjusting that screw until the bed is a set distance from the nozzle. Klipper has a tool to assist with this. In order to use the tool it is necessary to specify each screw XY location. This is done by creating a [bed_screws] config section. For example, it might look something similar to: [bed_screws] screw1: 100, 50 screw2: 100, 150 screw3: 150, 100 If a bed screw is under the bed, then specify the XY position directly above the screw. If the screw is outside the bed then specify an XY position closest to the screw that is still within the range of the bed. Once the config file is ready, run RESTART to load that config, and then one can start the tool by running: BED_SCREWS_ADJUST This tool will move the printer's nozzle to each screw XY location and then move the nozzle to a Z=0 height. At this point one can use the \"paper test\" to adjust the bed screw directly under the nozzle. See the information described in \"the paper test\" , but adjust the bed screw instead of commanding the nozzle to different heights. Adjust the bed screw until there is a small amount of friction when pushing the paper back and forth. Once the screw is adjusted so that a small amount of friction is felt, run either the ACCEPT or ADJUSTED command. Use the ADJUSTED command if the bed screw needed an adjustment (typically anything more than about 1/8th of a turn of the screw). Use the ACCEPT command if no significant adjustment is necessary. Both commands will cause the tool to proceed to the next screw. (When an ADJUSTED command is used, the tool will schedule an additional cycle of bed screw adjustments; the tool completes successfully when all bed screws are verified to not require any significant adjustments.) One can use the ABORT command to exit the tool early. This system works best when the printer has a flat printing surface (such as glass) and has straight rails. Upon successful completion of the bed leveling tool the bed should be ready for printing.","title":"Adjusting bed leveling screws"},{"location":"Manual_Level.html#fine-grained-bed-screw-adjustments","text":"If the printer uses three bed screws and all three screws are under the bed, then it may be possible to perform a second \"high precision\" bed leveling step. This is done by commanding the nozzle to locations where the bed moves a larger distance with each bed screw adjustment. For example, consider a bed with screws at locations A, B, and C: For each adjustment made to the bed screw at location C, the bed will swing along a pendulum defined by the remaining two bed screws (shown here as a green line). In this situation, each adjustment to the bed screw at C will move the bed at position D a further amount than directly at C. It is thus possible to make an improved C screw adjustment when the nozzle is at position D. To enable this feature, one would determine the additional nozzle coordinates and add them to the config file. For example, it might look like: [bed_screws] screw1: 100, 50 screw1_fine_adjust: 0, 0 screw2: 100, 150 screw2_fine_adjust: 300, 300 screw3: 150, 100 screw3_fine_adjust: 0, 100 When this feature is enabled, the BED_SCREWS_ADJUST tool will first prompt for coarse adjustments directly above each screw position, and once those are accepted, it will prompt for fine adjustments at the additional locations. Continue to use ACCEPT and ADJUSTED at each position.","title":"Fine grained bed screw adjustments"},{"location":"Manual_Level.html#adjusting-bed-leveling-screws-using-the-bed-probe","text":"This is another way to calibrate the bed level using the bed probe. To use it you must have a Z probe (BL Touch, Inductive sensor, etc). To enable this feature, one would determine the nozzle coordinates such that the Z probe is above the screws, and then add them to the config file. For example, it might look like: [screws_tilt_adjust] screw1: -5, 30 screw1_name: front left screw screw2: 155, 30 screw2_name: front right screw screw3: 155, 190 screw3_name: rear right screw screw4: -5, 190 screw4_name: rear left screw horizontal_move_z: 10. speed: 50. screw_thread: CW-M3 The screw1 is always the reference point for the others, so the system assumes that screw1 is at the correct height. Always run G28 first and then run SCREWS_TILT_CALCULATE - it should produce output similar to: Send: G28 Recv: ok Send: SCREWS_TILT_CALCULATE Recv: // 01:20 means 1 full turn and 20 minutes, CW=clockwise, CCW=counter-clockwise Recv: // front left screw (base) : x=-5.0, y=30.0, z=2.48750 Recv: // front right screw : x=155.0, y=30.0, z=2.36000 : adjust CW 01:15 Recv: // rear right screw : y=155.0, y=190.0, z=2.71500 : adjust CCW 00:50 Recv: // read left screw : x=-5.0, y=190.0, z=2.47250 : adjust CW 00:02 Recv: ok This means that: front left screw is the reference point you must not change it. front right screw must be turned clockwise 1 full turn and a quarter turn rear right screw must be turned counter-clockwise 50 minutes rear left screw must be turned clockwise 2 minutes (not need it's ok) Note that \"minutes\" refers to \"minutes of a clock face\". So, for example, 15 minutes is a quarter of a full turn. Repeat the process several times until you get a good level bed - normally when all adjustments are below 6 minutes. If using a probe that is mounted on the side of the hotend (that is, it has an X or Y offset) then note that adjusting the bed tilt will invalidate any previous probe calibration that was performed with a tilted bed. Be sure to run probe calibration after the bed screws have been adjusted. The MAX_DEVIATION parameter is useful when a saved bed mesh is used, to ensure that the bed level has not drifted too far from where it was when the mesh was created. For example, SCREWS_TILT_CALCULATE MAX_DEVIATION=0.01 can be added to the custom start gcode of the slicer before the mesh is loaded. It will abort the print if the configured limit is exceeded (0.01mm in this example), giving the user a chance to adjust the screws and restart the print. The DIRECTION parameter is useful if you can turn your bed adjustment screws in one direction only. For example, you might have screws that start tightened in their lowest (or highest) possible position, which can only be turned in a single direction, to raise (or lower) the bed. If you can only turn the screws clockwise, run SCREWS_TILT_CALCULATE DIRECTION=CW . If you can only turn them counter-clockwise, run SCREWS_TILT_CALCULATE DIRECTION=CCW . A suitable reference point will be chosen such that the bed can be leveled by turning all the screws in the given direction.","title":"Adjusting bed leveling screws using the bed probe"},{"location":"Measuring_Resonances.html","text":"Measuring Resonances \u00b6 Klipper has built-in support for the ADXL345, MPU-9250, LIS2DW and LIS3DH compatible accelerometers which can be used to measure resonance frequencies of the printer for different axes, and auto-tune input shapers to compensate for resonances. Note that using accelerometers requires some soldering and crimping. The ADXL345 can be connected to the SPI interface of a Raspberry Pi or MCU board (it needs to be reasonably fast). The MPU family can be connected to the I2C interface of a Raspberry Pi directly, or to an I2C interface of an MCU board that supports 400kbit/s fast mode in Klipper. The LIS2DW and LIS3DH can be connected to either SPI or I2C with the same considerations as above. When sourcing accelerometers, be aware that there are a variety of different PCB board designs and different clones of them. If it is going to be connected to a 5V printer MCU ensure it has a voltage regulator and level shifters. For ADXL345s, make sure that the board supports SPI mode (a small number of boards appear to be hard-configured for I2C by pulling SDO to GND). For MPU-9250/MPU-9255/MPU-6515/MPU-6050/MPU-6500/ICM20948s and LIS2DW/LIS3DH there are also a variety of board designs and clones with different I2C pull-up resistors which will need supplementing. MCUs with Klipper I2C fast-mode Support \u00b6 MCU Family MCU(s) Tested MCU(s) with Support Raspberry Pi 3B+, Pico 3A, 3A+, 3B, 4 AVR ATmega ATmega328p ATmega32u4, ATmega128, ATmega168, ATmega328, ATmega644p, ATmega1280, ATmega1284, ATmega2560 AVR AT90 - AT90usb646, AT90usb1286 SAMD SAMC21G18 SAMC21G18, SAMD21G18, SAMD21E18, SAMD21J18, SAMD21E15, SAMD51G19, SAMD51J19, SAMD51N19, SAMD51P20, SAME51J19, SAME51N19, SAME54P20 Installation instructions \u00b6 Wiring \u00b6 An ethernet cable with shielded twisted pairs (cat5e or better) is recommended for signal integrity over a long distance. If you still experience signal integrity issues (SPI/I2C errors): Double check the wiring with a digital multimeter for: Correct connections when turned off (continuity) Correct power and ground voltages I2C only: Check the SCL and SDA lines' resistances to 3.3V are in the range of 900 ohms to 1.8K For full technical details consult chapter 7 of the I2C-bus specification and user manual UM10204 for fast-mode Shorten the cable Connect ethernet cable shielding only to the MCU board/Pi ground. Double-check your wiring before powering up to prevent damaging your MCU/Raspberry Pi or the accelerometer. SPI Accelerometers \u00b6 Suggested twisted pair order for three twisted pairs: GND+MISO 3.3V+MOSI SCLK+CS Note that unlike a cable shield, GND must be connected at both ends. ADXL345 \u00b6 Direct to Raspberry Pi \u00b6 Note: Many MCUs will work with an ADXL345 in SPI mode (e.g. Pi Pico), wiring and configuration will vary according to your specific board and available pins. You need to connect ADXL345 to your Raspberry Pi via SPI. Note that the I2C connection, which is suggested by ADXL345 documentation, has too low throughput and will not work . The recommended connection scheme: ADXL345 pin RPi pin RPi pin name 3V3 (or VCC) 01 3.3V DC power GND 06 Ground CS 24 GPIO08 (SPI0_CE0_N) SDO 21 GPIO09 (SPI0_MISO) SDA 19 GPIO10 (SPI0_MOSI) SCL 23 GPIO11 (SPI0_SCLK) Fritzing wiring diagrams for some of the ADXL345 boards: Using Raspberry Pi Pico \u00b6 You may connect the ADXL345 to your Raspberry Pi Pico and then connect the Pico to your Raspberry Pi via USB. This makes it easy to reuse the accelerometer on other Klipper devices, as you can connect via USB instead of GPIO. The Pico does not have much processing power, so make sure it is only running the accelerometer and not performing any other duties. In order to avoid damage to your RPi make sure to connect the ADXL345 to 3.3V only. Depending on the board's layout, a level shifter may be present, which makes 5V dangerous for your RPi. ADXL345 pin Pico pin Pico pin name 3V3 (or VCC) 36 3.3V DC power GND 38 Ground CS 2 GP1 (SPI0_CSn) SDO 1 GP0 (SPI0_RX) SDA 5 GP3 (SPI0_TX) SCL 4 GP2 (SPI0_SCK) Wiring diagrams for some of the ADXL345 boards: I2C Accelerometers \u00b6 Suggested twisted pair order for three pairs (preferred): 3.3V+GND SDA+GND SCL+GND or for two pairs: 3.3V+SDA GND+SCL Note that unlike a cable shield, any GND(s) should be connected at both ends. MPU-9250/MPU-9255/MPU-6515/MPU-6050/MPU-6500/ICM20948 \u00b6 These accelerometers have been tested to work over I2C on the RPi, RP2040 (Pico) and AVR at 400kbit/s ( fast mode ). Some MPU accelerometer modules include pull-ups, but some are too large at 10K and must be changed or supplemented by smaller parallel resistors. Recommended connection scheme for I2C on the Raspberry Pi: MPU-9250 pin RPi pin RPi pin name VCC 01 3.3v DC power GND 09 Ground SDA 03 GPIO02 (SDA1) SCL 05 GPIO03 (SCL1) The RPi has built-in 1.8K pull-ups on both SCL and SDA. Recommended connection scheme for I2C (i2c0a) on the RP2040: MPU-9250 pin RP2040 pin RP2040 pin name VCC 36 3v3 GND 38 Ground SDA 01 GP0 (I2C0 SDA) SCL 02 GP1 (I2C0 SCL) The Pico does not include any built-in I2C pull-up resistors. Recommended connection scheme for I2C(TWI) on the AVR ATmega328P Arduino Nano: \u00b6 MPU-9250 pin Atmega328P TQFP32 pin Atmega328P pin name Arduino Nano pin VCC 39 - - GND 38 Ground GND SDA 27 SDA A4 SCL 28 SCL A5 The Arduino Nano does not include any built-in pull-up resistors nor a 3.3V power pin. Mounting the accelerometer \u00b6 The accelerometer must be attached to the toolhead. One needs to design a proper mount that fits their own 3D printer. It is better to align the axes of the accelerometer with the printer's axes (but if it makes it more convenient, axes can be swapped - i.e. no need to align X axis with X and so forth - it should be fine even if Z axis of accelerometer is X axis of the printer, etc.). An example of mounting ADXL345 on the SmartEffector: Note that on a bed slinger printer one must design 2 mounts: one for the toolhead and one for the bed, and run the measurements twice. See the corresponding section for more details. Attention: make sure the accelerometer and any screws that hold it in place do not touch any metal parts of the printer. Basically, the mount must be designed such as to ensure the electrical isolation of the accelerometer from the printer frame. Failing to ensure that can create a ground loop in the system that may damage the electronics. Software installation \u00b6 Note that resonance measurements and shaper auto-calibration require additional software dependencies not installed by default. First, run on your Raspberry Pi the following commands: sudo apt update sudo apt install python3-numpy python3-matplotlib libatlas-base-dev libopenblas-dev Next, in order to install NumPy in the Klipper environment, run the command: ~/klippy-env/bin/pip install -v \"numpy<1.26\" Note that, depending on the performance of the CPU, it may take a lot of time, up to 10-20 minutes. Be patient and wait for the completion of the installation. On some occasions, if the board has too little RAM the installation may fail and you will need to enable swap. Also note the forced version, due to newer versions of NumPY having requirements that may not be satisfied in some klipper python environments. Once installed please check that no errors show from the command: ~/klippy-env/bin/python -c 'import numpy;' The correct output should simply be a new line. Configure ADXL345 With RPi \u00b6 First, check and follow the instructions in the RPi Microcontroller document to setup the \"linux mcu\" on the Raspberry Pi. This will configure a second Klipper instance that runs on your Pi. Make sure the Linux SPI driver is enabled by running sudo raspi-config and enabling SPI under the \"Interfacing options\" menu. Add the following to the printer.cfg file: [mcu rpi] serial: /tmp/klipper_host_mcu [adxl345] cs_pin: rpi:None [resonance_tester] accel_chip: adxl345 probe_points: 100, 100, 20 # an example It is advised to start with 1 probe point, in the middle of the print bed, slightly above it. Configure ADXL345 With Pi Pico \u00b6 Flash the Pico Firmware \u00b6 On your Raspberry Pi, compile the firmware for the Pico. cd ~/klipper make clean make menuconfig Now, while holding down the BOOTSEL button on the Pico, connect the Pico to the Raspberry Pi via USB. Compile and flash the firmware. make flash FLASH_DEVICE=first If that fails, you will be told which FLASH_DEVICE to use. In this example, that's make flash FLASH_DEVICE=2e8a:0003 . Configure the Connection \u00b6 The Pico will now reboot with the new firmware and should show up as a serial device. Find the pico serial device with ls /dev/serial/by-id/* . You can now add an adxl.cfg file with the following settings: [mcu adxl] # Change <mySerial> to whatever you found above. For example, # usb-Klipper_rp2040_E661640843545B2E-if00 serial: /dev/serial/by-id/usb-Klipper_rp2040_<mySerial> [adxl345] cs_pin: adxl:gpio1 spi_bus: spi0a axes_map: x,z,y [resonance_tester] accel_chip: adxl345 probe_points: # Somewhere slightly above the middle of your print bed 147,154, 20 [output_pin power_mode] # Improve power stability pin: adxl:gpio23 If setting up the ADXL345 configuration in a separate file, as shown above, you'll also want to modify your printer.cfg file to include this: [include adxl.cfg] # Comment this out when you disconnect the accelerometer Restart Klipper via the RESTART command. Configure LIS2DW series over SPI \u00b6 [mcu lis] # Change <mySerial> to whatever you found above. For example, # usb-Klipper_rp2040_E661640843545B2E-if00 serial: /dev/serial/by-id/usb-Klipper_rp2040_<mySerial> [lis2dw] cs_pin: lis:gpio1 spi_bus: spi0a axes_map: x,z,y [resonance_tester] accel_chip: lis2dw probe_points: # Somewhere slightly above the middle of your print bed 147,154, 20 Configure MPU-6000/9000 series With RPi \u00b6 Make sure the Linux I2C driver is enabled and the baud rate is set to 400000 (see Enabling I2C section for more details). Then, add the following to the printer.cfg: [mcu rpi] serial: /tmp/klipper_host_mcu [mpu9250] i2c_mcu: rpi i2c_bus: i2c.1 [resonance_tester] accel_chip: mpu9250 probe_points: 100, 100, 20 # an example If you are using the ICM20948, replace instances of \"mpu9250\" with \"icm20948\". Configure MPU-9520 Compatibles With Pico \u00b6 Pico I2C is set to 400000 on default. Simply add the following to the printer.cfg: [mcu pico] serial: /dev/serial/by-id/<your Pico's serial ID> [mpu9250] i2c_mcu: pico i2c_bus: i2c0a [resonance_tester] accel_chip: mpu9250 probe_points: 100, 100, 20 # an example [static_digital_output pico_3V3pwm] # Improve power stability pins: pico:gpio23 If you are using the ICM20948, replace instances of \"mpu9250\" with \"icm20948\". Configure MPU-9520 Compatibles with AVR \u00b6 AVR I2C will be set to 400000 by the mpu9250 option. Simply add the following to the printer.cfg: [mcu nano] serial: /dev/serial/by-id/<your nano's serial ID> [mpu9250] i2c_mcu: nano [resonance_tester] accel_chip: mpu9250 probe_points: 100, 100, 20 # an example If you are using the ICM20948, replace instances of \"mpu9250\" with \"icm20948\". Restart Klipper via the RESTART command. Measuring the resonances \u00b6 Checking the setup \u00b6 Now you can test a connection. For \"non bed-slingers\" (e.g. one accelerometer), in Octoprint, enter ACCELEROMETER_QUERY For \"bed-slingers\" (e.g. more than one accelerometer), enter ACCELEROMETER_QUERY CHIP=<chip> where <chip> is the name of the chip as-entered, e.g. CHIP=bed (see: bed-slinger ) for all installed accelerometer chips. You should see the current measurements from the accelerometer, including the free-fall acceleration, e.g. Recv: // adxl345 values (x, y, z): 470.719200, 941.438400, 9728.196800 If you get an error like Invalid adxl345 id (got xx vs e5) , where xx is some other ID, immediately try again. There's an issue with SPI initialization. If you still get an error, it is indicative of the connection problem with ADXL345, or the faulty sensor. Double-check the power, the wiring (that it matches the schematics, no wire is broken or loose, etc.), and soldering quality. If you are using a MPU-9250 compatible accelerometer and it shows up as mpu-unknown , use with caution! They are probably refurbished chips! Next, try running MEASURE_AXES_NOISE in Octoprint, you should get some baseline numbers for the noise of accelerometer on the axes (should be somewhere in the range of ~1-100). Too high axes noise (e.g. 1000 and more) can be indicative of the sensor issues, problems with its power, or too noisy imbalanced fans on a 3D printer. Measuring the resonances \u00b6 Now you can run some real-life tests. Run the following command: TEST_RESONANCES AXIS=X Note that it will create vibrations on X axis. It will also disable input shaping if it was enabled previously, as it is not valid to run the resonance testing with the input shaper enabled. Attention! Be sure to observe the printer for the first time, to make sure the vibrations do not become too violent ( M112 command can be used to abort the test in case of emergency; hopefully it will not come to this though). If the vibrations do get too strong, you can attempt to specify a lower than the default value for accel_per_hz parameter in [resonance_tester] section, e.g. [resonance_tester] accel_chip: adxl345 accel_per_hz: 50 # default is 75 probe_points: ... If it works for X axis, run for Y axis as well: TEST_RESONANCES AXIS=Y This will generate 2 CSV files ( /tmp/resonances_x_*.csv and /tmp/resonances_y_*.csv ). These files can be processed with the stand-alone script on a Raspberry Pi. This script is intended to be run with a single CSV file for each axis measured, although it can be used with multiple CSV files if you desire to average the results. Averaging results can be useful, for example, if resonance tests were done at multiple test points. Delete the extra CSV files if you do not desire to average them. ~/klipper/scripts/calibrate_shaper.py /tmp/resonances_x_*.csv -o /tmp/shaper_calibrate_x.png ~/klipper/scripts/calibrate_shaper.py /tmp/resonances_y_*.csv -o /tmp/shaper_calibrate_y.png This script will generate the charts /tmp/shaper_calibrate_x.png and /tmp/shaper_calibrate_y.png with frequency responses. You will also get the suggested frequencies for each input shaper, as well as which input shaper is recommended for your setup. For example: Fitted shaper 'zv' frequency = 34.4 Hz (vibrations = 4.0%, smoothing ~= 0.132) To avoid too much smoothing with 'zv', suggested max_accel <= 4500 mm/sec^2 Fitted shaper 'mzv' frequency = 34.6 Hz (vibrations = 0.0%, smoothing ~= 0.170) To avoid too much smoothing with 'mzv', suggested max_accel <= 3500 mm/sec^2 Fitted shaper 'ei' frequency = 41.4 Hz (vibrations = 0.0%, smoothing ~= 0.188) To avoid too much smoothing with 'ei', suggested max_accel <= 3200 mm/sec^2 Fitted shaper '2hump_ei' frequency = 51.8 Hz (vibrations = 0.0%, smoothing ~= 0.201) To avoid too much smoothing with '2hump_ei', suggested max_accel <= 3000 mm/sec^2 Fitted shaper '3hump_ei' frequency = 61.8 Hz (vibrations = 0.0%, smoothing ~= 0.215) To avoid too much smoothing with '3hump_ei', suggested max_accel <= 2800 mm/sec^2 Recommended shaper is mzv @ 34.6 Hz The suggested configuration can be added to [input_shaper] section of printer.cfg , e.g.: [input_shaper] shaper_freq_x: ... shaper_type_x: ... shaper_freq_y: 34.6 shaper_type_y: mzv [printer] max_accel: 3000 # should not exceed the estimated max_accel for X and Y axes or you can choose some other configuration yourself based on the generated charts: peaks in the power spectral density on the charts correspond to the resonance frequencies of the printer. Note that alternatively you can run the input shaper auto-calibration from Klipper directly , which can be convenient, for example, for the input shaper re-calibration . Bed-slinger printers \u00b6 If your printer is a bed slinger printer, you will need to change the location of the accelerometer between the measurements for X and Y axes: measure the resonances of X axis with the accelerometer attached to the toolhead and the resonances of Y axis - to the bed (the usual bed slinger setup). However, you can also connect two accelerometers simultaneously, though the ADXL345 must be connected to different boards (say, to an RPi and printer MCU board), or to two different physical SPI interfaces on the same board (rarely available). Then they can be configured in the following manner: [adxl345 hotend] # Assuming `hotend` chip is connected to an RPi cs_pin: rpi:None [adxl345 bed] # Assuming `bed` chip is connected to a printer MCU board cs_pin: ... # Printer board SPI chip select (CS) pin [resonance_tester] # Assuming the typical setup of the bed slinger printer accel_chip_x: adxl345 hotend accel_chip_y: adxl345 bed probe_points: ... Two MPUs can share one I2C bus, but they cannot measure simultaneously as the 400kbit/s I2C bus is not fast enough. One must have its AD0 pin pulled-down to 0V (address 104) and the other its AD0 pin pulled-up to 3.3V (address 105): [mpu9250 hotend] i2c_mcu: rpi i2c_bus: i2c.1 i2c_address: 104 # This MPU has pin AD0 pulled low [mpu9250 bed] i2c_mcu: rpi i2c_bus: i2c.1 i2c_address: 105 # This MPU has pin AD0 pulled high [resonance_tester] # Assuming the typical setup of the bed slinger printer accel_chip_x: mpu9250 hotend accel_chip_y: mpu9250 bed probe_points: ... [Test with each MPU individually before connecting both to the bus for easy debugging.] Then the commands TEST_RESONANCES AXIS=X and TEST_RESONANCES AXIS=Y will use the correct accelerometer for each axis. Max smoothing \u00b6 Keep in mind that the input shaper can create some smoothing in parts. Automatic tuning of the input shaper performed by calibrate_shaper.py script or SHAPER_CALIBRATE command tries not to exacerbate the smoothing, but at the same time they try to minimize the resulting vibrations. Sometimes they can make a sub-optimal choice of the shaper frequency, or maybe you simply prefer to have less smoothing in parts at the expense of a larger remaining vibrations. In these cases, you can request to limit the maximum smoothing from the input shaper. Let's consider the following results from the automatic tuning: Fitted shaper 'zv' frequency = 57.8 Hz (vibrations = 20.3%, smoothing ~= 0.053) To avoid too much smoothing with 'zv', suggested max_accel <= 13000 mm/sec^2 Fitted shaper 'mzv' frequency = 34.8 Hz (vibrations = 3.6%, smoothing ~= 0.168) To avoid too much smoothing with 'mzv', suggested max_accel <= 3600 mm/sec^2 Fitted shaper 'ei' frequency = 48.8 Hz (vibrations = 4.9%, smoothing ~= 0.135) To avoid too much smoothing with 'ei', suggested max_accel <= 4400 mm/sec^2 Fitted shaper '2hump_ei' frequency = 45.2 Hz (vibrations = 0.1%, smoothing ~= 0.264) To avoid too much smoothing with '2hump_ei', suggested max_accel <= 2200 mm/sec^2 Fitted shaper '3hump_ei' frequency = 48.0 Hz (vibrations = 0.0%, smoothing ~= 0.356) To avoid too much smoothing with '3hump_ei', suggested max_accel <= 1500 mm/sec^2 Recommended shaper is 2hump_ei @ 45.2 Hz Note that the reported smoothing values are some abstract projected values. These values can be used to compare different configurations: the higher the value, the more smoothing a shaper will create. However, these smoothing scores do not represent any real measure of smoothing, because the actual smoothing depends on max_accel and square_corner_velocity parameters. Therefore, you should print some test prints to see how much smoothing exactly a chosen configuration creates. In the example above the suggested shaper parameters are not bad, but what if you want to get less smoothing on the X axis? You can try to limit the maximum shaper smoothing using the following command: ~/klipper/scripts/calibrate_shaper.py /tmp/resonances_x_*.csv -o /tmp/shaper_calibrate_x.png --max_smoothing=0.2 which limits the smoothing to 0.2 score. Now you can get the following result: Fitted shaper 'zv' frequency = 55.4 Hz (vibrations = 19.7%, smoothing ~= 0.057) To avoid too much smoothing with 'zv', suggested max_accel <= 12000 mm/sec^2 Fitted shaper 'mzv' frequency = 34.6 Hz (vibrations = 3.6%, smoothing ~= 0.170) To avoid too much smoothing with 'mzv', suggested max_accel <= 3500 mm/sec^2 Fitted shaper 'ei' frequency = 48.2 Hz (vibrations = 4.8%, smoothing ~= 0.139) To avoid too much smoothing with 'ei', suggested max_accel <= 4300 mm/sec^2 Fitted shaper '2hump_ei' frequency = 52.0 Hz (vibrations = 2.7%, smoothing ~= 0.200) To avoid too much smoothing with '2hump_ei', suggested max_accel <= 3000 mm/sec^2 Fitted shaper '3hump_ei' frequency = 72.6 Hz (vibrations = 1.4%, smoothing ~= 0.155) To avoid too much smoothing with '3hump_ei', suggested max_accel <= 3900 mm/sec^2 Recommended shaper is 3hump_ei @ 72.6 Hz If you compare to the previously suggested parameters, the vibrations are a bit larger, but the smoothing is significantly smaller than previously, allowing larger maximum acceleration. When deciding which max_smoothing parameter to choose, you can use a trial-and-error approach. Try a few different values and see which results you get. Note that the actual smoothing produced by the input shaper depends, primarily, on the lowest resonance frequency of the printer: the higher the frequency of the lowest resonance - the smaller the smoothing. Therefore, if you request the script to find a configuration of the input shaper with the unrealistically small smoothing, it will be at the expense of increased ringing at the lowest resonance frequencies (which are, typically, also more prominently visible in prints). So, always double-check the projected remaining vibrations reported by the script and make sure they are not too high. Note that if you chose a good max_smoothing value for both of your axes, you can store it in the printer.cfg as [resonance_tester] accel_chip: ... probe_points: ... max_smoothing: 0.25 # an example Then, if you rerun the input shaper auto-tuning using SHAPER_CALIBRATE Klipper command in the future, it will use the stored max_smoothing value as a reference. Selecting max_accel \u00b6 Since the input shaper can create some smoothing in parts, especially at high accelerations, you will still need to choose the max_accel value that does not create too much smoothing in the printed parts. A calibration script provides an estimate for max_accel parameter that should not create too much smoothing. Note that the max_accel as displayed by the calibration script is only a theoretical maximum at which the respective shaper is still able to work without producing too much smoothing. It is by no means a recommendation to set this acceleration for printing. The maximum acceleration your printer is able to sustain depends on its mechanical properties and the maximum torque of the used stepper motors. Therefore, it is suggested to set max_accel in [printer] section that does not exceed the estimated values for X and Y axes, likely with some conservative safety margin. Alternatively, follow this part of the input shaper tuning guide and print the test model to choose max_accel parameter experimentally. The same notice applies to the input shaper auto-calibration with SHAPER_CALIBRATE command: it is still necessary to choose the right max_accel value after the auto-calibration, and the suggested acceleration limits will not be applied automatically. Keep in mind that the maximum acceleration without too much smoothing depends on the square_corner_velocity . The general recommendation is not to change it from its default value 5.0, and this is the value used by default by the calibrate_shaper.py script. If you did change it though, you should inform the script about it by passing --square_corner_velocity=... parameter, e.g. ~/klipper/scripts/calibrate_shaper.py /tmp/resonances_x_*.csv -o /tmp/shaper_calibrate_x.png --square_corner_velocity=10.0 so that it can calculate the maximum acceleration recommendations correctly. Note that the SHAPER_CALIBRATE command already takes the configured square_corner_velocity parameter into account, and there is no need to specify it explicitly. If you are doing a shaper re-calibration and the reported smoothing for the suggested shaper configuration is almost the same as what you got during the previous calibration, this step can be skipped. Unreliable measurements of resonance frequencies \u00b6 Sometimes the resonance measurements can produce bogus results, leading to the incorrect suggestions for the input shapers. This can be caused by a variety of reasons, including running fans on the toolhead, incorrect position or non-rigid mounting of the accelerometer, or mechanical problems such as loose belts or binding or bumpy axis. Keep in mind that all fans should be disabled for resonance testing, especially the noisy ones, and that the accelerometer should be rigidly mounted on the corresponding moving part (e.g. on the bed itself for the bed slinger, or on the extruder of the printer itself and not the carriage, and some people get better results by mounting the accelerometer on the nozzle itself). As for mechanical problems, the user should inspect if there is any fault that can be fixed with a moving axis (e.g. linear guide rails cleaned up and lubricated and V-slot wheels tension adjusted correctly). If none of that helps, a user may try the other shapers from the produced list besides the one recommended by default. Testing custom axes \u00b6 TEST_RESONANCES command supports custom axes. While this is not really useful for input shaper calibration, it can be used to study printer resonances in-depth and to check, for example, belt tension. To check the belt tension on CoreXY printers, execute TEST_RESONANCES AXIS=1,1 OUTPUT=raw_data TEST_RESONANCES AXIS=1,-1 OUTPUT=raw_data and use graph_accelerometer.py to process the generated files, e.g. ~/klipper/scripts/graph_accelerometer.py -c /tmp/raw_data_axis*.csv -o /tmp/resonances.png which will generate /tmp/resonances.png comparing the resonances. For Delta printers with the default tower placement (tower A ~= 210 degrees, B ~= 330 degrees, and C ~= 90 degrees), execute TEST_RESONANCES AXIS=0,1 OUTPUT=raw_data TEST_RESONANCES AXIS=-0.866025404,-0.5 OUTPUT=raw_data TEST_RESONANCES AXIS=0.866025404,-0.5 OUTPUT=raw_data and then use the same command ~/klipper/scripts/graph_accelerometer.py -c /tmp/raw_data_axis*.csv -o /tmp/resonances.png to generate /tmp/resonances.png comparing the resonances. Input Shaper auto-calibration \u00b6 Besides manually choosing the appropriate parameters for the input shaper feature, it is also possible to run the auto-tuning for the input shaper directly from Klipper. Run the following command via Octoprint terminal: SHAPER_CALIBRATE This will run the full test for both axes and generate the csv output ( /tmp/calibration_data_*.csv by default) for the frequency response and the suggested input shapers. You will also get the suggested frequencies for each input shaper, as well as which input shaper is recommended for your setup, on Octoprint console. For example: Calculating the best input shaper parameters for y axis Fitted shaper 'zv' frequency = 39.0 Hz (vibrations = 13.2%, smoothing ~= 0.105) To avoid too much smoothing with 'zv', suggested max_accel <= 5900 mm/sec^2 Fitted shaper 'mzv' frequency = 36.8 Hz (vibrations = 1.7%, smoothing ~= 0.150) To avoid too much smoothing with 'mzv', suggested max_accel <= 4000 mm/sec^2 Fitted shaper 'ei' frequency = 36.6 Hz (vibrations = 2.2%, smoothing ~= 0.240) To avoid too much smoothing with 'ei', suggested max_accel <= 2500 mm/sec^2 Fitted shaper '2hump_ei' frequency = 48.0 Hz (vibrations = 0.0%, smoothing ~= 0.234) To avoid too much smoothing with '2hump_ei', suggested max_accel <= 2500 mm/sec^2 Fitted shaper '3hump_ei' frequency = 59.0 Hz (vibrations = 0.0%, smoothing ~= 0.235) To avoid too much smoothing with '3hump_ei', suggested max_accel <= 2500 mm/sec^2 Recommended shaper_type_y = mzv, shaper_freq_y = 36.8 Hz If you agree with the suggested parameters, you can execute SAVE_CONFIG now to save them and restart the Klipper. Note that this will not update max_accel value in [printer] section. You should update it manually following the considerations in Selecting max_accel section. If your printer is a bed slinger printer, you can specify which axis to test, so that you can change the accelerometer mounting point between the tests (by default the test is performed for both axes): SHAPER_CALIBRATE AXIS=Y You can execute SAVE_CONFIG twice - after calibrating each axis. However, if you connected two accelerometers simultaneously, you simply run SHAPER_CALIBRATE without specifying an axis to calibrate the input shaper for both axes in one go. Input Shaper re-calibration \u00b6 SHAPER_CALIBRATE command can be also used to re-calibrate the input shaper in the future, especially if some changes to the printer that can affect its kinematics are made. One can either re-run the full calibration using SHAPER_CALIBRATE command, or restrict the auto-calibration to a single axis by supplying AXIS= parameter, like SHAPER_CALIBRATE AXIS=X Warning! It is not advisable to run the shaper auto-calibration very frequently (e.g. before every print, or every day). In order to determine resonance frequencies, auto-calibration creates intensive vibrations on each of the axes. Generally, 3D printers are not designed to withstand a prolonged exposure to vibrations near the resonance frequencies. Doing so may increase wear of the printer components and reduce their lifespan. There is also an increased risk of some parts unscrewing or becoming loose. Always check that all parts of the printer (including the ones that may normally not move) are securely fixed in place after each auto-tuning. Also, due to some noise in measurements, it is possible that the tuning results will be slightly different from one calibration run to another one. Still, it is not expected that the noise will affect the print quality too much. However, it is still advised to double-check the suggested parameters, and print some test prints before using them to confirm they are good. Offline processing of the accelerometer data \u00b6 It is possible to generate the raw accelerometer data and process it offline (e.g. on a host machine), for example to find resonances. In order to do so, run the following commands via Octoprint terminal: SET_INPUT_SHAPER SHAPER_FREQ_X=0 SHAPER_FREQ_Y=0 TEST_RESONANCES AXIS=X OUTPUT=raw_data ignoring any errors for SET_INPUT_SHAPER command. For TEST_RESONANCES command, specify the desired test axis. The raw data will be written into /tmp directory on the RPi. The raw data can also be obtained by running the command ACCELEROMETER_MEASURE command twice during some normal printer activity - first to start the measurements, and then to stop them and write the output file. Refer to G-Codes for more details. The data can be processed later by the following scripts: scripts/graph_accelerometer.py and scripts/calibrate_shaper.py . Both of them accept one or several raw csv files as the input depending on the mode. The graph_accelerometer.py script supports several modes of operation: plotting raw accelerometer data (use -r parameter), only 1 input is supported; plotting a frequency response (no extra parameters required), if multiple inputs are specified, the average frequency response is computed; comparison of the frequency response between several inputs (use -c parameter); you can additionally specify which accelerometer axis to consider via -a x , -a y or -a z parameter (if none specified, the sum of vibrations for all axes is used); plotting the spectrogram (use -s parameter), only 1 input is supported; you can additionally specify which accelerometer axis to consider via -a x , -a y or -a z parameter (if none specified, the sum of vibrations for all axes is used). Note that graph_accelerometer.py script supports only the raw_data*.csv files and not resonances*.csv or calibration_data*.csv files. For example, ~/klipper/scripts/graph_accelerometer.py /tmp/raw_data_x_*.csv -o /tmp/resonances_x.png -c -a z will plot the comparison of several /tmp/raw_data_x_*.csv files for Z axis to /tmp/resonances_x.png file. The shaper_calibrate.py script accepts 1 or several inputs and can run automatic tuning of the input shaper and suggest the best parameters that work well for all provided inputs. It prints the suggested parameters to the console, and can additionally generate the chart if -o output.png parameter is provided, or the CSV file if -c output.csv parameter is specified. Providing several inputs to shaper_calibrate.py script can be useful if running some advanced tuning of the input shapers, for example: Running TEST_RESONANCES AXIS=X OUTPUT=raw_data (and Y axis) for a single axis twice on a bed slinger printer with the accelerometer attached to the toolhead the first time, and the accelerometer attached to the bed the second time in order to detect axes cross-resonances and attempt to cancel them with input shapers. Running TEST_RESONANCES AXIS=Y OUTPUT=raw_data twice on a bed slinger with a glass bed and a magnetic surfaces (which is lighter) to find the input shaper parameters that work well for any print surface configuration. Combining the resonance data from multiple test points. Combining the resonance data from 2 axis (e.g. on a bed slinger printer to configure X-axis input_shaper from both X and Y axes resonances to cancel vibrations of the bed in case the nozzle 'catches' a print when moving in X axis direction).","title":"Measuring Resonances"},{"location":"Measuring_Resonances.html#measuring-resonances","text":"Klipper has built-in support for the ADXL345, MPU-9250, LIS2DW and LIS3DH compatible accelerometers which can be used to measure resonance frequencies of the printer for different axes, and auto-tune input shapers to compensate for resonances. Note that using accelerometers requires some soldering and crimping. The ADXL345 can be connected to the SPI interface of a Raspberry Pi or MCU board (it needs to be reasonably fast). The MPU family can be connected to the I2C interface of a Raspberry Pi directly, or to an I2C interface of an MCU board that supports 400kbit/s fast mode in Klipper. The LIS2DW and LIS3DH can be connected to either SPI or I2C with the same considerations as above. When sourcing accelerometers, be aware that there are a variety of different PCB board designs and different clones of them. If it is going to be connected to a 5V printer MCU ensure it has a voltage regulator and level shifters. For ADXL345s, make sure that the board supports SPI mode (a small number of boards appear to be hard-configured for I2C by pulling SDO to GND). For MPU-9250/MPU-9255/MPU-6515/MPU-6050/MPU-6500/ICM20948s and LIS2DW/LIS3DH there are also a variety of board designs and clones with different I2C pull-up resistors which will need supplementing.","title":"Measuring Resonances"},{"location":"Measuring_Resonances.html#mcus-with-klipper-i2c-fast-mode-support","text":"MCU Family MCU(s) Tested MCU(s) with Support Raspberry Pi 3B+, Pico 3A, 3A+, 3B, 4 AVR ATmega ATmega328p ATmega32u4, ATmega128, ATmega168, ATmega328, ATmega644p, ATmega1280, ATmega1284, ATmega2560 AVR AT90 - AT90usb646, AT90usb1286 SAMD SAMC21G18 SAMC21G18, SAMD21G18, SAMD21E18, SAMD21J18, SAMD21E15, SAMD51G19, SAMD51J19, SAMD51N19, SAMD51P20, SAME51J19, SAME51N19, SAME54P20","title":"MCUs with Klipper I2C fast-mode Support"},{"location":"Measuring_Resonances.html#installation-instructions","text":"","title":"Installation instructions"},{"location":"Measuring_Resonances.html#wiring","text":"An ethernet cable with shielded twisted pairs (cat5e or better) is recommended for signal integrity over a long distance. If you still experience signal integrity issues (SPI/I2C errors): Double check the wiring with a digital multimeter for: Correct connections when turned off (continuity) Correct power and ground voltages I2C only: Check the SCL and SDA lines' resistances to 3.3V are in the range of 900 ohms to 1.8K For full technical details consult chapter 7 of the I2C-bus specification and user manual UM10204 for fast-mode Shorten the cable Connect ethernet cable shielding only to the MCU board/Pi ground. Double-check your wiring before powering up to prevent damaging your MCU/Raspberry Pi or the accelerometer.","title":"Wiring"},{"location":"Measuring_Resonances.html#spi-accelerometers","text":"Suggested twisted pair order for three twisted pairs: GND+MISO 3.3V+MOSI SCLK+CS Note that unlike a cable shield, GND must be connected at both ends.","title":"SPI Accelerometers"},{"location":"Measuring_Resonances.html#adxl345","text":"","title":"ADXL345"},{"location":"Measuring_Resonances.html#direct-to-raspberry-pi","text":"Note: Many MCUs will work with an ADXL345 in SPI mode (e.g. Pi Pico), wiring and configuration will vary according to your specific board and available pins. You need to connect ADXL345 to your Raspberry Pi via SPI. Note that the I2C connection, which is suggested by ADXL345 documentation, has too low throughput and will not work . The recommended connection scheme: ADXL345 pin RPi pin RPi pin name 3V3 (or VCC) 01 3.3V DC power GND 06 Ground CS 24 GPIO08 (SPI0_CE0_N) SDO 21 GPIO09 (SPI0_MISO) SDA 19 GPIO10 (SPI0_MOSI) SCL 23 GPIO11 (SPI0_SCLK) Fritzing wiring diagrams for some of the ADXL345 boards:","title":"Direct to Raspberry Pi"},{"location":"Measuring_Resonances.html#using-raspberry-pi-pico","text":"You may connect the ADXL345 to your Raspberry Pi Pico and then connect the Pico to your Raspberry Pi via USB. This makes it easy to reuse the accelerometer on other Klipper devices, as you can connect via USB instead of GPIO. The Pico does not have much processing power, so make sure it is only running the accelerometer and not performing any other duties. In order to avoid damage to your RPi make sure to connect the ADXL345 to 3.3V only. Depending on the board's layout, a level shifter may be present, which makes 5V dangerous for your RPi. ADXL345 pin Pico pin Pico pin name 3V3 (or VCC) 36 3.3V DC power GND 38 Ground CS 2 GP1 (SPI0_CSn) SDO 1 GP0 (SPI0_RX) SDA 5 GP3 (SPI0_TX) SCL 4 GP2 (SPI0_SCK) Wiring diagrams for some of the ADXL345 boards:","title":"Using Raspberry Pi Pico"},{"location":"Measuring_Resonances.html#i2c-accelerometers","text":"Suggested twisted pair order for three pairs (preferred): 3.3V+GND SDA+GND SCL+GND or for two pairs: 3.3V+SDA GND+SCL Note that unlike a cable shield, any GND(s) should be connected at both ends.","title":"I2C Accelerometers"},{"location":"Measuring_Resonances.html#mpu-9250mpu-9255mpu-6515mpu-6050mpu-6500icm20948","text":"These accelerometers have been tested to work over I2C on the RPi, RP2040 (Pico) and AVR at 400kbit/s ( fast mode ). Some MPU accelerometer modules include pull-ups, but some are too large at 10K and must be changed or supplemented by smaller parallel resistors. Recommended connection scheme for I2C on the Raspberry Pi: MPU-9250 pin RPi pin RPi pin name VCC 01 3.3v DC power GND 09 Ground SDA 03 GPIO02 (SDA1) SCL 05 GPIO03 (SCL1) The RPi has built-in 1.8K pull-ups on both SCL and SDA. Recommended connection scheme for I2C (i2c0a) on the RP2040: MPU-9250 pin RP2040 pin RP2040 pin name VCC 36 3v3 GND 38 Ground SDA 01 GP0 (I2C0 SDA) SCL 02 GP1 (I2C0 SCL) The Pico does not include any built-in I2C pull-up resistors.","title":"MPU-9250/MPU-9255/MPU-6515/MPU-6050/MPU-6500/ICM20948"},{"location":"Measuring_Resonances.html#recommended-connection-scheme-for-i2ctwi-on-the-avr-atmega328p-arduino-nano","text":"MPU-9250 pin Atmega328P TQFP32 pin Atmega328P pin name Arduino Nano pin VCC 39 - - GND 38 Ground GND SDA 27 SDA A4 SCL 28 SCL A5 The Arduino Nano does not include any built-in pull-up resistors nor a 3.3V power pin.","title":"Recommended connection scheme for I2C(TWI) on the AVR ATmega328P Arduino Nano:"},{"location":"Measuring_Resonances.html#mounting-the-accelerometer","text":"The accelerometer must be attached to the toolhead. One needs to design a proper mount that fits their own 3D printer. It is better to align the axes of the accelerometer with the printer's axes (but if it makes it more convenient, axes can be swapped - i.e. no need to align X axis with X and so forth - it should be fine even if Z axis of accelerometer is X axis of the printer, etc.). An example of mounting ADXL345 on the SmartEffector: Note that on a bed slinger printer one must design 2 mounts: one for the toolhead and one for the bed, and run the measurements twice. See the corresponding section for more details. Attention: make sure the accelerometer and any screws that hold it in place do not touch any metal parts of the printer. Basically, the mount must be designed such as to ensure the electrical isolation of the accelerometer from the printer frame. Failing to ensure that can create a ground loop in the system that may damage the electronics.","title":"Mounting the accelerometer"},{"location":"Measuring_Resonances.html#software-installation","text":"Note that resonance measurements and shaper auto-calibration require additional software dependencies not installed by default. First, run on your Raspberry Pi the following commands: sudo apt update sudo apt install python3-numpy python3-matplotlib libatlas-base-dev libopenblas-dev Next, in order to install NumPy in the Klipper environment, run the command: ~/klippy-env/bin/pip install -v \"numpy<1.26\" Note that, depending on the performance of the CPU, it may take a lot of time, up to 10-20 minutes. Be patient and wait for the completion of the installation. On some occasions, if the board has too little RAM the installation may fail and you will need to enable swap. Also note the forced version, due to newer versions of NumPY having requirements that may not be satisfied in some klipper python environments. Once installed please check that no errors show from the command: ~/klippy-env/bin/python -c 'import numpy;' The correct output should simply be a new line.","title":"Software installation"},{"location":"Measuring_Resonances.html#configure-adxl345-with-rpi","text":"First, check and follow the instructions in the RPi Microcontroller document to setup the \"linux mcu\" on the Raspberry Pi. This will configure a second Klipper instance that runs on your Pi. Make sure the Linux SPI driver is enabled by running sudo raspi-config and enabling SPI under the \"Interfacing options\" menu. Add the following to the printer.cfg file: [mcu rpi] serial: /tmp/klipper_host_mcu [adxl345] cs_pin: rpi:None [resonance_tester] accel_chip: adxl345 probe_points: 100, 100, 20 # an example It is advised to start with 1 probe point, in the middle of the print bed, slightly above it.","title":"Configure ADXL345 With RPi"},{"location":"Measuring_Resonances.html#configure-adxl345-with-pi-pico","text":"","title":"Configure ADXL345 With Pi Pico"},{"location":"Measuring_Resonances.html#flash-the-pico-firmware","text":"On your Raspberry Pi, compile the firmware for the Pico. cd ~/klipper make clean make menuconfig Now, while holding down the BOOTSEL button on the Pico, connect the Pico to the Raspberry Pi via USB. Compile and flash the firmware. make flash FLASH_DEVICE=first If that fails, you will be told which FLASH_DEVICE to use. In this example, that's make flash FLASH_DEVICE=2e8a:0003 .","title":"Flash the Pico Firmware"},{"location":"Measuring_Resonances.html#configure-the-connection","text":"The Pico will now reboot with the new firmware and should show up as a serial device. Find the pico serial device with ls /dev/serial/by-id/* . You can now add an adxl.cfg file with the following settings: [mcu adxl] # Change <mySerial> to whatever you found above. For example, # usb-Klipper_rp2040_E661640843545B2E-if00 serial: /dev/serial/by-id/usb-Klipper_rp2040_<mySerial> [adxl345] cs_pin: adxl:gpio1 spi_bus: spi0a axes_map: x,z,y [resonance_tester] accel_chip: adxl345 probe_points: # Somewhere slightly above the middle of your print bed 147,154, 20 [output_pin power_mode] # Improve power stability pin: adxl:gpio23 If setting up the ADXL345 configuration in a separate file, as shown above, you'll also want to modify your printer.cfg file to include this: [include adxl.cfg] # Comment this out when you disconnect the accelerometer Restart Klipper via the RESTART command.","title":"Configure the Connection"},{"location":"Measuring_Resonances.html#configure-lis2dw-series-over-spi","text":"[mcu lis] # Change <mySerial> to whatever you found above. For example, # usb-Klipper_rp2040_E661640843545B2E-if00 serial: /dev/serial/by-id/usb-Klipper_rp2040_<mySerial> [lis2dw] cs_pin: lis:gpio1 spi_bus: spi0a axes_map: x,z,y [resonance_tester] accel_chip: lis2dw probe_points: # Somewhere slightly above the middle of your print bed 147,154, 20","title":"Configure LIS2DW series over SPI"},{"location":"Measuring_Resonances.html#configure-mpu-60009000-series-with-rpi","text":"Make sure the Linux I2C driver is enabled and the baud rate is set to 400000 (see Enabling I2C section for more details). Then, add the following to the printer.cfg: [mcu rpi] serial: /tmp/klipper_host_mcu [mpu9250] i2c_mcu: rpi i2c_bus: i2c.1 [resonance_tester] accel_chip: mpu9250 probe_points: 100, 100, 20 # an example If you are using the ICM20948, replace instances of \"mpu9250\" with \"icm20948\".","title":"Configure MPU-6000/9000 series With RPi"},{"location":"Measuring_Resonances.html#configure-mpu-9520-compatibles-with-pico","text":"Pico I2C is set to 400000 on default. Simply add the following to the printer.cfg: [mcu pico] serial: /dev/serial/by-id/<your Pico's serial ID> [mpu9250] i2c_mcu: pico i2c_bus: i2c0a [resonance_tester] accel_chip: mpu9250 probe_points: 100, 100, 20 # an example [static_digital_output pico_3V3pwm] # Improve power stability pins: pico:gpio23 If you are using the ICM20948, replace instances of \"mpu9250\" with \"icm20948\".","title":"Configure MPU-9520 Compatibles With Pico"},{"location":"Measuring_Resonances.html#configure-mpu-9520-compatibles-with-avr","text":"AVR I2C will be set to 400000 by the mpu9250 option. Simply add the following to the printer.cfg: [mcu nano] serial: /dev/serial/by-id/<your nano's serial ID> [mpu9250] i2c_mcu: nano [resonance_tester] accel_chip: mpu9250 probe_points: 100, 100, 20 # an example If you are using the ICM20948, replace instances of \"mpu9250\" with \"icm20948\". Restart Klipper via the RESTART command.","title":"Configure MPU-9520 Compatibles with AVR"},{"location":"Measuring_Resonances.html#measuring-the-resonances","text":"","title":"Measuring the resonances"},{"location":"Measuring_Resonances.html#checking-the-setup","text":"Now you can test a connection. For \"non bed-slingers\" (e.g. one accelerometer), in Octoprint, enter ACCELEROMETER_QUERY For \"bed-slingers\" (e.g. more than one accelerometer), enter ACCELEROMETER_QUERY CHIP=<chip> where <chip> is the name of the chip as-entered, e.g. CHIP=bed (see: bed-slinger ) for all installed accelerometer chips. You should see the current measurements from the accelerometer, including the free-fall acceleration, e.g. Recv: // adxl345 values (x, y, z): 470.719200, 941.438400, 9728.196800 If you get an error like Invalid adxl345 id (got xx vs e5) , where xx is some other ID, immediately try again. There's an issue with SPI initialization. If you still get an error, it is indicative of the connection problem with ADXL345, or the faulty sensor. Double-check the power, the wiring (that it matches the schematics, no wire is broken or loose, etc.), and soldering quality. If you are using a MPU-9250 compatible accelerometer and it shows up as mpu-unknown , use with caution! They are probably refurbished chips! Next, try running MEASURE_AXES_NOISE in Octoprint, you should get some baseline numbers for the noise of accelerometer on the axes (should be somewhere in the range of ~1-100). Too high axes noise (e.g. 1000 and more) can be indicative of the sensor issues, problems with its power, or too noisy imbalanced fans on a 3D printer.","title":"Checking the setup"},{"location":"Measuring_Resonances.html#measuring-the-resonances_1","text":"Now you can run some real-life tests. Run the following command: TEST_RESONANCES AXIS=X Note that it will create vibrations on X axis. It will also disable input shaping if it was enabled previously, as it is not valid to run the resonance testing with the input shaper enabled. Attention! Be sure to observe the printer for the first time, to make sure the vibrations do not become too violent ( M112 command can be used to abort the test in case of emergency; hopefully it will not come to this though). If the vibrations do get too strong, you can attempt to specify a lower than the default value for accel_per_hz parameter in [resonance_tester] section, e.g. [resonance_tester] accel_chip: adxl345 accel_per_hz: 50 # default is 75 probe_points: ... If it works for X axis, run for Y axis as well: TEST_RESONANCES AXIS=Y This will generate 2 CSV files ( /tmp/resonances_x_*.csv and /tmp/resonances_y_*.csv ). These files can be processed with the stand-alone script on a Raspberry Pi. This script is intended to be run with a single CSV file for each axis measured, although it can be used with multiple CSV files if you desire to average the results. Averaging results can be useful, for example, if resonance tests were done at multiple test points. Delete the extra CSV files if you do not desire to average them. ~/klipper/scripts/calibrate_shaper.py /tmp/resonances_x_*.csv -o /tmp/shaper_calibrate_x.png ~/klipper/scripts/calibrate_shaper.py /tmp/resonances_y_*.csv -o /tmp/shaper_calibrate_y.png This script will generate the charts /tmp/shaper_calibrate_x.png and /tmp/shaper_calibrate_y.png with frequency responses. You will also get the suggested frequencies for each input shaper, as well as which input shaper is recommended for your setup. For example: Fitted shaper 'zv' frequency = 34.4 Hz (vibrations = 4.0%, smoothing ~= 0.132) To avoid too much smoothing with 'zv', suggested max_accel <= 4500 mm/sec^2 Fitted shaper 'mzv' frequency = 34.6 Hz (vibrations = 0.0%, smoothing ~= 0.170) To avoid too much smoothing with 'mzv', suggested max_accel <= 3500 mm/sec^2 Fitted shaper 'ei' frequency = 41.4 Hz (vibrations = 0.0%, smoothing ~= 0.188) To avoid too much smoothing with 'ei', suggested max_accel <= 3200 mm/sec^2 Fitted shaper '2hump_ei' frequency = 51.8 Hz (vibrations = 0.0%, smoothing ~= 0.201) To avoid too much smoothing with '2hump_ei', suggested max_accel <= 3000 mm/sec^2 Fitted shaper '3hump_ei' frequency = 61.8 Hz (vibrations = 0.0%, smoothing ~= 0.215) To avoid too much smoothing with '3hump_ei', suggested max_accel <= 2800 mm/sec^2 Recommended shaper is mzv @ 34.6 Hz The suggested configuration can be added to [input_shaper] section of printer.cfg , e.g.: [input_shaper] shaper_freq_x: ... shaper_type_x: ... shaper_freq_y: 34.6 shaper_type_y: mzv [printer] max_accel: 3000 # should not exceed the estimated max_accel for X and Y axes or you can choose some other configuration yourself based on the generated charts: peaks in the power spectral density on the charts correspond to the resonance frequencies of the printer. Note that alternatively you can run the input shaper auto-calibration from Klipper directly , which can be convenient, for example, for the input shaper re-calibration .","title":"Measuring the resonances"},{"location":"Measuring_Resonances.html#bed-slinger-printers","text":"If your printer is a bed slinger printer, you will need to change the location of the accelerometer between the measurements for X and Y axes: measure the resonances of X axis with the accelerometer attached to the toolhead and the resonances of Y axis - to the bed (the usual bed slinger setup). However, you can also connect two accelerometers simultaneously, though the ADXL345 must be connected to different boards (say, to an RPi and printer MCU board), or to two different physical SPI interfaces on the same board (rarely available). Then they can be configured in the following manner: [adxl345 hotend] # Assuming `hotend` chip is connected to an RPi cs_pin: rpi:None [adxl345 bed] # Assuming `bed` chip is connected to a printer MCU board cs_pin: ... # Printer board SPI chip select (CS) pin [resonance_tester] # Assuming the typical setup of the bed slinger printer accel_chip_x: adxl345 hotend accel_chip_y: adxl345 bed probe_points: ... Two MPUs can share one I2C bus, but they cannot measure simultaneously as the 400kbit/s I2C bus is not fast enough. One must have its AD0 pin pulled-down to 0V (address 104) and the other its AD0 pin pulled-up to 3.3V (address 105): [mpu9250 hotend] i2c_mcu: rpi i2c_bus: i2c.1 i2c_address: 104 # This MPU has pin AD0 pulled low [mpu9250 bed] i2c_mcu: rpi i2c_bus: i2c.1 i2c_address: 105 # This MPU has pin AD0 pulled high [resonance_tester] # Assuming the typical setup of the bed slinger printer accel_chip_x: mpu9250 hotend accel_chip_y: mpu9250 bed probe_points: ... [Test with each MPU individually before connecting both to the bus for easy debugging.] Then the commands TEST_RESONANCES AXIS=X and TEST_RESONANCES AXIS=Y will use the correct accelerometer for each axis.","title":"Bed-slinger printers"},{"location":"Measuring_Resonances.html#max-smoothing","text":"Keep in mind that the input shaper can create some smoothing in parts. Automatic tuning of the input shaper performed by calibrate_shaper.py script or SHAPER_CALIBRATE command tries not to exacerbate the smoothing, but at the same time they try to minimize the resulting vibrations. Sometimes they can make a sub-optimal choice of the shaper frequency, or maybe you simply prefer to have less smoothing in parts at the expense of a larger remaining vibrations. In these cases, you can request to limit the maximum smoothing from the input shaper. Let's consider the following results from the automatic tuning: Fitted shaper 'zv' frequency = 57.8 Hz (vibrations = 20.3%, smoothing ~= 0.053) To avoid too much smoothing with 'zv', suggested max_accel <= 13000 mm/sec^2 Fitted shaper 'mzv' frequency = 34.8 Hz (vibrations = 3.6%, smoothing ~= 0.168) To avoid too much smoothing with 'mzv', suggested max_accel <= 3600 mm/sec^2 Fitted shaper 'ei' frequency = 48.8 Hz (vibrations = 4.9%, smoothing ~= 0.135) To avoid too much smoothing with 'ei', suggested max_accel <= 4400 mm/sec^2 Fitted shaper '2hump_ei' frequency = 45.2 Hz (vibrations = 0.1%, smoothing ~= 0.264) To avoid too much smoothing with '2hump_ei', suggested max_accel <= 2200 mm/sec^2 Fitted shaper '3hump_ei' frequency = 48.0 Hz (vibrations = 0.0%, smoothing ~= 0.356) To avoid too much smoothing with '3hump_ei', suggested max_accel <= 1500 mm/sec^2 Recommended shaper is 2hump_ei @ 45.2 Hz Note that the reported smoothing values are some abstract projected values. These values can be used to compare different configurations: the higher the value, the more smoothing a shaper will create. However, these smoothing scores do not represent any real measure of smoothing, because the actual smoothing depends on max_accel and square_corner_velocity parameters. Therefore, you should print some test prints to see how much smoothing exactly a chosen configuration creates. In the example above the suggested shaper parameters are not bad, but what if you want to get less smoothing on the X axis? You can try to limit the maximum shaper smoothing using the following command: ~/klipper/scripts/calibrate_shaper.py /tmp/resonances_x_*.csv -o /tmp/shaper_calibrate_x.png --max_smoothing=0.2 which limits the smoothing to 0.2 score. Now you can get the following result: Fitted shaper 'zv' frequency = 55.4 Hz (vibrations = 19.7%, smoothing ~= 0.057) To avoid too much smoothing with 'zv', suggested max_accel <= 12000 mm/sec^2 Fitted shaper 'mzv' frequency = 34.6 Hz (vibrations = 3.6%, smoothing ~= 0.170) To avoid too much smoothing with 'mzv', suggested max_accel <= 3500 mm/sec^2 Fitted shaper 'ei' frequency = 48.2 Hz (vibrations = 4.8%, smoothing ~= 0.139) To avoid too much smoothing with 'ei', suggested max_accel <= 4300 mm/sec^2 Fitted shaper '2hump_ei' frequency = 52.0 Hz (vibrations = 2.7%, smoothing ~= 0.200) To avoid too much smoothing with '2hump_ei', suggested max_accel <= 3000 mm/sec^2 Fitted shaper '3hump_ei' frequency = 72.6 Hz (vibrations = 1.4%, smoothing ~= 0.155) To avoid too much smoothing with '3hump_ei', suggested max_accel <= 3900 mm/sec^2 Recommended shaper is 3hump_ei @ 72.6 Hz If you compare to the previously suggested parameters, the vibrations are a bit larger, but the smoothing is significantly smaller than previously, allowing larger maximum acceleration. When deciding which max_smoothing parameter to choose, you can use a trial-and-error approach. Try a few different values and see which results you get. Note that the actual smoothing produced by the input shaper depends, primarily, on the lowest resonance frequency of the printer: the higher the frequency of the lowest resonance - the smaller the smoothing. Therefore, if you request the script to find a configuration of the input shaper with the unrealistically small smoothing, it will be at the expense of increased ringing at the lowest resonance frequencies (which are, typically, also more prominently visible in prints). So, always double-check the projected remaining vibrations reported by the script and make sure they are not too high. Note that if you chose a good max_smoothing value for both of your axes, you can store it in the printer.cfg as [resonance_tester] accel_chip: ... probe_points: ... max_smoothing: 0.25 # an example Then, if you rerun the input shaper auto-tuning using SHAPER_CALIBRATE Klipper command in the future, it will use the stored max_smoothing value as a reference.","title":"Max smoothing"},{"location":"Measuring_Resonances.html#selecting-max_accel","text":"Since the input shaper can create some smoothing in parts, especially at high accelerations, you will still need to choose the max_accel value that does not create too much smoothing in the printed parts. A calibration script provides an estimate for max_accel parameter that should not create too much smoothing. Note that the max_accel as displayed by the calibration script is only a theoretical maximum at which the respective shaper is still able to work without producing too much smoothing. It is by no means a recommendation to set this acceleration for printing. The maximum acceleration your printer is able to sustain depends on its mechanical properties and the maximum torque of the used stepper motors. Therefore, it is suggested to set max_accel in [printer] section that does not exceed the estimated values for X and Y axes, likely with some conservative safety margin. Alternatively, follow this part of the input shaper tuning guide and print the test model to choose max_accel parameter experimentally. The same notice applies to the input shaper auto-calibration with SHAPER_CALIBRATE command: it is still necessary to choose the right max_accel value after the auto-calibration, and the suggested acceleration limits will not be applied automatically. Keep in mind that the maximum acceleration without too much smoothing depends on the square_corner_velocity . The general recommendation is not to change it from its default value 5.0, and this is the value used by default by the calibrate_shaper.py script. If you did change it though, you should inform the script about it by passing --square_corner_velocity=... parameter, e.g. ~/klipper/scripts/calibrate_shaper.py /tmp/resonances_x_*.csv -o /tmp/shaper_calibrate_x.png --square_corner_velocity=10.0 so that it can calculate the maximum acceleration recommendations correctly. Note that the SHAPER_CALIBRATE command already takes the configured square_corner_velocity parameter into account, and there is no need to specify it explicitly. If you are doing a shaper re-calibration and the reported smoothing for the suggested shaper configuration is almost the same as what you got during the previous calibration, this step can be skipped.","title":"Selecting max_accel"},{"location":"Measuring_Resonances.html#unreliable-measurements-of-resonance-frequencies","text":"Sometimes the resonance measurements can produce bogus results, leading to the incorrect suggestions for the input shapers. This can be caused by a variety of reasons, including running fans on the toolhead, incorrect position or non-rigid mounting of the accelerometer, or mechanical problems such as loose belts or binding or bumpy axis. Keep in mind that all fans should be disabled for resonance testing, especially the noisy ones, and that the accelerometer should be rigidly mounted on the corresponding moving part (e.g. on the bed itself for the bed slinger, or on the extruder of the printer itself and not the carriage, and some people get better results by mounting the accelerometer on the nozzle itself). As for mechanical problems, the user should inspect if there is any fault that can be fixed with a moving axis (e.g. linear guide rails cleaned up and lubricated and V-slot wheels tension adjusted correctly). If none of that helps, a user may try the other shapers from the produced list besides the one recommended by default.","title":"Unreliable measurements of resonance frequencies"},{"location":"Measuring_Resonances.html#testing-custom-axes","text":"TEST_RESONANCES command supports custom axes. While this is not really useful for input shaper calibration, it can be used to study printer resonances in-depth and to check, for example, belt tension. To check the belt tension on CoreXY printers, execute TEST_RESONANCES AXIS=1,1 OUTPUT=raw_data TEST_RESONANCES AXIS=1,-1 OUTPUT=raw_data and use graph_accelerometer.py to process the generated files, e.g. ~/klipper/scripts/graph_accelerometer.py -c /tmp/raw_data_axis*.csv -o /tmp/resonances.png which will generate /tmp/resonances.png comparing the resonances. For Delta printers with the default tower placement (tower A ~= 210 degrees, B ~= 330 degrees, and C ~= 90 degrees), execute TEST_RESONANCES AXIS=0,1 OUTPUT=raw_data TEST_RESONANCES AXIS=-0.866025404,-0.5 OUTPUT=raw_data TEST_RESONANCES AXIS=0.866025404,-0.5 OUTPUT=raw_data and then use the same command ~/klipper/scripts/graph_accelerometer.py -c /tmp/raw_data_axis*.csv -o /tmp/resonances.png to generate /tmp/resonances.png comparing the resonances.","title":"Testing custom axes"},{"location":"Measuring_Resonances.html#input-shaper-auto-calibration","text":"Besides manually choosing the appropriate parameters for the input shaper feature, it is also possible to run the auto-tuning for the input shaper directly from Klipper. Run the following command via Octoprint terminal: SHAPER_CALIBRATE This will run the full test for both axes and generate the csv output ( /tmp/calibration_data_*.csv by default) for the frequency response and the suggested input shapers. You will also get the suggested frequencies for each input shaper, as well as which input shaper is recommended for your setup, on Octoprint console. For example: Calculating the best input shaper parameters for y axis Fitted shaper 'zv' frequency = 39.0 Hz (vibrations = 13.2%, smoothing ~= 0.105) To avoid too much smoothing with 'zv', suggested max_accel <= 5900 mm/sec^2 Fitted shaper 'mzv' frequency = 36.8 Hz (vibrations = 1.7%, smoothing ~= 0.150) To avoid too much smoothing with 'mzv', suggested max_accel <= 4000 mm/sec^2 Fitted shaper 'ei' frequency = 36.6 Hz (vibrations = 2.2%, smoothing ~= 0.240) To avoid too much smoothing with 'ei', suggested max_accel <= 2500 mm/sec^2 Fitted shaper '2hump_ei' frequency = 48.0 Hz (vibrations = 0.0%, smoothing ~= 0.234) To avoid too much smoothing with '2hump_ei', suggested max_accel <= 2500 mm/sec^2 Fitted shaper '3hump_ei' frequency = 59.0 Hz (vibrations = 0.0%, smoothing ~= 0.235) To avoid too much smoothing with '3hump_ei', suggested max_accel <= 2500 mm/sec^2 Recommended shaper_type_y = mzv, shaper_freq_y = 36.8 Hz If you agree with the suggested parameters, you can execute SAVE_CONFIG now to save them and restart the Klipper. Note that this will not update max_accel value in [printer] section. You should update it manually following the considerations in Selecting max_accel section. If your printer is a bed slinger printer, you can specify which axis to test, so that you can change the accelerometer mounting point between the tests (by default the test is performed for both axes): SHAPER_CALIBRATE AXIS=Y You can execute SAVE_CONFIG twice - after calibrating each axis. However, if you connected two accelerometers simultaneously, you simply run SHAPER_CALIBRATE without specifying an axis to calibrate the input shaper for both axes in one go.","title":"Input Shaper auto-calibration"},{"location":"Measuring_Resonances.html#input-shaper-re-calibration","text":"SHAPER_CALIBRATE command can be also used to re-calibrate the input shaper in the future, especially if some changes to the printer that can affect its kinematics are made. One can either re-run the full calibration using SHAPER_CALIBRATE command, or restrict the auto-calibration to a single axis by supplying AXIS= parameter, like SHAPER_CALIBRATE AXIS=X Warning! It is not advisable to run the shaper auto-calibration very frequently (e.g. before every print, or every day). In order to determine resonance frequencies, auto-calibration creates intensive vibrations on each of the axes. Generally, 3D printers are not designed to withstand a prolonged exposure to vibrations near the resonance frequencies. Doing so may increase wear of the printer components and reduce their lifespan. There is also an increased risk of some parts unscrewing or becoming loose. Always check that all parts of the printer (including the ones that may normally not move) are securely fixed in place after each auto-tuning. Also, due to some noise in measurements, it is possible that the tuning results will be slightly different from one calibration run to another one. Still, it is not expected that the noise will affect the print quality too much. However, it is still advised to double-check the suggested parameters, and print some test prints before using them to confirm they are good.","title":"Input Shaper re-calibration"},{"location":"Measuring_Resonances.html#offline-processing-of-the-accelerometer-data","text":"It is possible to generate the raw accelerometer data and process it offline (e.g. on a host machine), for example to find resonances. In order to do so, run the following commands via Octoprint terminal: SET_INPUT_SHAPER SHAPER_FREQ_X=0 SHAPER_FREQ_Y=0 TEST_RESONANCES AXIS=X OUTPUT=raw_data ignoring any errors for SET_INPUT_SHAPER command. For TEST_RESONANCES command, specify the desired test axis. The raw data will be written into /tmp directory on the RPi. The raw data can also be obtained by running the command ACCELEROMETER_MEASURE command twice during some normal printer activity - first to start the measurements, and then to stop them and write the output file. Refer to G-Codes for more details. The data can be processed later by the following scripts: scripts/graph_accelerometer.py and scripts/calibrate_shaper.py . Both of them accept one or several raw csv files as the input depending on the mode. The graph_accelerometer.py script supports several modes of operation: plotting raw accelerometer data (use -r parameter), only 1 input is supported; plotting a frequency response (no extra parameters required), if multiple inputs are specified, the average frequency response is computed; comparison of the frequency response between several inputs (use -c parameter); you can additionally specify which accelerometer axis to consider via -a x , -a y or -a z parameter (if none specified, the sum of vibrations for all axes is used); plotting the spectrogram (use -s parameter), only 1 input is supported; you can additionally specify which accelerometer axis to consider via -a x , -a y or -a z parameter (if none specified, the sum of vibrations for all axes is used). Note that graph_accelerometer.py script supports only the raw_data*.csv files and not resonances*.csv or calibration_data*.csv files. For example, ~/klipper/scripts/graph_accelerometer.py /tmp/raw_data_x_*.csv -o /tmp/resonances_x.png -c -a z will plot the comparison of several /tmp/raw_data_x_*.csv files for Z axis to /tmp/resonances_x.png file. The shaper_calibrate.py script accepts 1 or several inputs and can run automatic tuning of the input shaper and suggest the best parameters that work well for all provided inputs. It prints the suggested parameters to the console, and can additionally generate the chart if -o output.png parameter is provided, or the CSV file if -c output.csv parameter is specified. Providing several inputs to shaper_calibrate.py script can be useful if running some advanced tuning of the input shapers, for example: Running TEST_RESONANCES AXIS=X OUTPUT=raw_data (and Y axis) for a single axis twice on a bed slinger printer with the accelerometer attached to the toolhead the first time, and the accelerometer attached to the bed the second time in order to detect axes cross-resonances and attempt to cancel them with input shapers. Running TEST_RESONANCES AXIS=Y OUTPUT=raw_data twice on a bed slinger with a glass bed and a magnetic surfaces (which is lighter) to find the input shaper parameters that work well for any print surface configuration. Combining the resonance data from multiple test points. Combining the resonance data from 2 axis (e.g. on a bed slinger printer to configure X-axis input_shaper from both X and Y axes resonances to cancel vibrations of the bed in case the nozzle 'catches' a print when moving in X axis direction).","title":"Offline processing of the accelerometer data"},{"location":"Multi_MCU_Homing.html","text":"Multiple Micro-controller Homing and Probing \u00b6 Klipper supports a mechanism for homing with an endstop attached to one micro-controller while its stepper motors are on a different micro-controller. This support is referred to as \"multi-mcu homing\". This feature is also used when a Z probe is on a different micro-controller than the Z stepper motors. This feature can be useful to simplify wiring, as it may be more convenient to attach an endstop or probe to a closer micro-controller. However, using this feature may result in \"overshoot\" of the stepper motors during homing and probing operations. The overshoot occurs due to possible message transmission delays between the micro-controller monitoring the endstop and the micro-controllers moving the stepper motors. The Klipper code is designed to limit this delay to no more than 25ms. (When multi-mcu homing is activated, the micro-controllers send periodic status messages and check that corresponding status messages are received within 25ms.) So, for example, if homing at 10mm/s then it is possible for an overshoot of up to 0.250mm (10mm/s * .025s == 0.250mm). Care should be taken when configuring multi-mcu homing to account for this type of overshoot. Using slower homing or probing speeds can reduce the overshoot. Stepper motor overshoot should not adversely impact the precision of the homing and probing procedure. The Klipper code will detect the overshoot and account for it in its calculations. However, it is important that the hardware design is capable of handling overshoot without causing damage to the machine. In order to use this \"multi-mcu homing\" capability the hardware must have predictably low latency between the host computer and all of the micro-controllers. Typically the round-trip time must be consistently less than 10ms. High latency (even for short periods) is likely to result in homing failures. Should high latency result in a failure (or if some other communication issue is detected) then Klipper will raise a \"Communication timeout during homing\" error. Note that an axis with multiple steppers (eg, stepper_z and stepper_z1 ) need to be on the same micro-controller in order to use multi-mcu homing. For example, if an endstop is on a separate micro-controller from stepper_z then stepper_z1 must be on the same micro-controller as stepper_z .","title":"Multiple Micro-controller Homing and Probing"},{"location":"Multi_MCU_Homing.html#multiple-micro-controller-homing-and-probing","text":"Klipper supports a mechanism for homing with an endstop attached to one micro-controller while its stepper motors are on a different micro-controller. This support is referred to as \"multi-mcu homing\". This feature is also used when a Z probe is on a different micro-controller than the Z stepper motors. This feature can be useful to simplify wiring, as it may be more convenient to attach an endstop or probe to a closer micro-controller. However, using this feature may result in \"overshoot\" of the stepper motors during homing and probing operations. The overshoot occurs due to possible message transmission delays between the micro-controller monitoring the endstop and the micro-controllers moving the stepper motors. The Klipper code is designed to limit this delay to no more than 25ms. (When multi-mcu homing is activated, the micro-controllers send periodic status messages and check that corresponding status messages are received within 25ms.) So, for example, if homing at 10mm/s then it is possible for an overshoot of up to 0.250mm (10mm/s * .025s == 0.250mm). Care should be taken when configuring multi-mcu homing to account for this type of overshoot. Using slower homing or probing speeds can reduce the overshoot. Stepper motor overshoot should not adversely impact the precision of the homing and probing procedure. The Klipper code will detect the overshoot and account for it in its calculations. However, it is important that the hardware design is capable of handling overshoot without causing damage to the machine. In order to use this \"multi-mcu homing\" capability the hardware must have predictably low latency between the host computer and all of the micro-controllers. Typically the round-trip time must be consistently less than 10ms. High latency (even for short periods) is likely to result in homing failures. Should high latency result in a failure (or if some other communication issue is detected) then Klipper will raise a \"Communication timeout during homing\" error. Note that an axis with multiple steppers (eg, stepper_z and stepper_z1 ) need to be on the same micro-controller in order to use multi-mcu homing. For example, if an endstop is on a separate micro-controller from stepper_z then stepper_z1 must be on the same micro-controller as stepper_z .","title":"Multiple Micro-controller Homing and Probing"},{"location":"OctoPrint.html","text":"OctoPrint for Klipper \u00b6 Klipper has a few options for its front ends, Octoprint was the first and original front end for Klipper. This document will give a brief overview of installing with this option. Install with OctoPi \u00b6 Start by installing OctoPi on the Raspberry Pi computer. Use OctoPi v0.17.0 or later - see the OctoPi releases for release information. One should verify that OctoPi boots and that the OctoPrint web server works. After connecting to the OctoPrint web page, follow the prompt to upgrade OctoPrint if needed. After installing OctoPi and upgrading OctoPrint, it will be necessary to ssh into the target machine to run a handful of system commands. Start by running these commands on your host device: If you do not have git installed, please do so with: sudo apt install git then proceed: cd ~ git clone https://github.com/Klipper3d/klipper ./klipper/scripts/install-octopi.sh The above will download Klipper, install the needed system dependencies, setup Klipper to run at system startup, and start the Klipper host software. It will require an internet connection and it may take a few minutes to complete. Installing with KIAUH \u00b6 KIAUH can be used to install OctoPrint on a variety of Linux based systems that run a form of Debian. More information can be found at https://github.com/dw-0/kiauh Configuring OctoPrint to use Klipper \u00b6 The OctoPrint web server needs to be configured to communicate with the Klipper host software. Using a web browser, login to the OctoPrint web page and then configure the following items: Navigate to the Settings tab (the wrench icon at the top of the page). Under \"Serial Connection\" in \"Additional serial ports\" add: ~/printer_data/comms/klippy.serial Then click \"Save\". In some older setups this address may be /tmp/printer Enter the Settings tab again and under \"Serial Connection\" change the \"Serial Port\" setting to the one added above. In the Settings tab, navigate to the \"Behavior\" sub-tab and select the \"Cancel any ongoing prints but stay connected to the printer\" option. Click \"Save\". From the main page, under the \"Connection\" section (at the top left of the page) make sure the \"Serial Port\" is set to the new additional one added and click \"Connect\". (If it is not in the available selection then try reloading the page.) Once connected, navigate to the \"Terminal\" tab and type \"status\" (without the quotes) into the command entry box and click \"Send\". The terminal window will likely report there is an error opening the config file - that means OctoPrint is successfully communicating with Klipper. Please proceed to Installation.md and the Building and flashing the micro-controller section","title":"OctoPrint for Klipper"},{"location":"OctoPrint.html#octoprint-for-klipper","text":"Klipper has a few options for its front ends, Octoprint was the first and original front end for Klipper. This document will give a brief overview of installing with this option.","title":"OctoPrint for Klipper"},{"location":"OctoPrint.html#install-with-octopi","text":"Start by installing OctoPi on the Raspberry Pi computer. Use OctoPi v0.17.0 or later - see the OctoPi releases for release information. One should verify that OctoPi boots and that the OctoPrint web server works. After connecting to the OctoPrint web page, follow the prompt to upgrade OctoPrint if needed. After installing OctoPi and upgrading OctoPrint, it will be necessary to ssh into the target machine to run a handful of system commands. Start by running these commands on your host device: If you do not have git installed, please do so with: sudo apt install git then proceed: cd ~ git clone https://github.com/Klipper3d/klipper ./klipper/scripts/install-octopi.sh The above will download Klipper, install the needed system dependencies, setup Klipper to run at system startup, and start the Klipper host software. It will require an internet connection and it may take a few minutes to complete.","title":"Install with OctoPi"},{"location":"OctoPrint.html#installing-with-kiauh","text":"KIAUH can be used to install OctoPrint on a variety of Linux based systems that run a form of Debian. More information can be found at https://github.com/dw-0/kiauh","title":"Installing with KIAUH"},{"location":"OctoPrint.html#configuring-octoprint-to-use-klipper","text":"The OctoPrint web server needs to be configured to communicate with the Klipper host software. Using a web browser, login to the OctoPrint web page and then configure the following items: Navigate to the Settings tab (the wrench icon at the top of the page). Under \"Serial Connection\" in \"Additional serial ports\" add: ~/printer_data/comms/klippy.serial Then click \"Save\". In some older setups this address may be /tmp/printer Enter the Settings tab again and under \"Serial Connection\" change the \"Serial Port\" setting to the one added above. In the Settings tab, navigate to the \"Behavior\" sub-tab and select the \"Cancel any ongoing prints but stay connected to the printer\" option. Click \"Save\". From the main page, under the \"Connection\" section (at the top left of the page) make sure the \"Serial Port\" is set to the new additional one added and click \"Connect\". (If it is not in the available selection then try reloading the page.) Once connected, navigate to the \"Terminal\" tab and type \"status\" (without the quotes) into the command entry box and click \"Send\". The terminal window will likely report there is an error opening the config file - that means OctoPrint is successfully communicating with Klipper. Please proceed to Installation.md and the Building and flashing the micro-controller section","title":"Configuring OctoPrint to use Klipper"},{"location":"Overview.html","text":"Overview \u00b6 Welcome to the Klipper documentation. If new to Klipper, start with the features and installation documents. Overview information \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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","title":"Overview"},{"location":"Overview.html#overview","text":"Welcome to the Klipper documentation. If new to Klipper, start with the features and installation documents.","title":"Overview"},{"location":"Overview.html#overview-information","text":"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.","title":"Overview information"},{"location":"Overview.html#installation-and-configuration","text":"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.","title":"Installation and Configuration"},{"location":"Overview.html#developer-documentation","text":"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.","title":"Developer Documentation"},{"location":"Overview.html#device-specific-documents","text":"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","title":"Device Specific Documents"},{"location":"Packaging.html","text":"Packaging Klipper \u00b6 Klipper is somewhat of a packaging anomaly among python programs, as it doesn't use setuptools to build and install. Some notes regarding how best to package it are as follows: C modules \u00b6 Klipper uses a C module to handle some kinematics calculations more quickly. This module needs to be compiled at packaging time to avoid introducing a runtime dependency on a compiler. To compile the C module, run python2 klippy/chelper/__init__.py . Compiling python code \u00b6 Many distributions have a policy of compiling all python code before packaging to improve startup time. You can do this by running python2 -m compileall klippy . Versioning \u00b6 If you are building a package of Klipper from git, it is usual practice not to ship a .git directory, so the versioning must be handled without git. To do this, use the script shipped in scripts/make_version.py which should be run as follows: python2 scripts/make_version.py YOURDISTRONAME > klippy/.version . Sample packaging script \u00b6 klipper-git is packaged for Arch Linux, and has a PKGBUILD (package build script) available at Arch User Repository .","title":"Packaging Klipper"},{"location":"Packaging.html#packaging-klipper","text":"Klipper is somewhat of a packaging anomaly among python programs, as it doesn't use setuptools to build and install. Some notes regarding how best to package it are as follows:","title":"Packaging Klipper"},{"location":"Packaging.html#c-modules","text":"Klipper uses a C module to handle some kinematics calculations more quickly. This module needs to be compiled at packaging time to avoid introducing a runtime dependency on a compiler. To compile the C module, run python2 klippy/chelper/__init__.py .","title":"C modules"},{"location":"Packaging.html#compiling-python-code","text":"Many distributions have a policy of compiling all python code before packaging to improve startup time. You can do this by running python2 -m compileall klippy .","title":"Compiling python code"},{"location":"Packaging.html#versioning","text":"If you are building a package of Klipper from git, it is usual practice not to ship a .git directory, so the versioning must be handled without git. To do this, use the script shipped in scripts/make_version.py which should be run as follows: python2 scripts/make_version.py YOURDISTRONAME > klippy/.version .","title":"Versioning"},{"location":"Packaging.html#sample-packaging-script","text":"klipper-git is packaged for Arch Linux, and has a PKGBUILD (package build script) available at Arch User Repository .","title":"Sample packaging script"},{"location":"Pressure_Advance.html","text":"Pressure advance \u00b6 This document provides information on tuning the \"pressure advance\" configuration variable for a particular nozzle and filament. The pressure advance feature can be helpful in reducing ooze. For more information on how pressure advance is implemented see the kinematics document. Tuning pressure advance \u00b6 Pressure advance does two useful things - it reduces ooze during non-extrude moves and it reduces blobbing during cornering. This guide uses the second feature (reducing blobbing during cornering) as a mechanism for tuning. In order to calibrate pressure advance the printer must be configured and operational as the tuning test involves printing and inspecting a test object. It is a good idea to read this document in full prior to running the test. Use a slicer to generate g-code for the large hollow square found in docs/prints/square_tower.stl . Use a high speed (eg, 100mm/s), zero infill, and a coarse layer height (the layer height should be around 75% of the nozzle diameter). Make sure any \"dynamic acceleration control\" and \"scarf joint\" seams are disabled in the slicer. Prepare for the test by issuing the following G-Code command: SET_VELOCITY_LIMIT SQUARE_CORNER_VELOCITY=1 ACCEL=500 This command makes the nozzle travel slower through corners to emphasize the effects of extruder pressure. Then for printers with a direct drive extruder run the command: TUNING_TOWER COMMAND=SET_PRESSURE_ADVANCE PARAMETER=ADVANCE START=0 FACTOR=.005 For long bowden extruders use: TUNING_TOWER COMMAND=SET_PRESSURE_ADVANCE PARAMETER=ADVANCE START=0 FACTOR=.020 Then print the object. When fully printed the test print looks like: The above TUNING_TOWER command instructs Klipper to alter the pressure_advance setting on each layer of the print. Higher layers in the print will have a larger pressure advance value set. Layers below the ideal pressure_advance setting will have blobbing at the corners, and layers above the ideal setting can lead to rounded corners and poor extrusion leading up to the corner. One can cancel the print early if one observes that the corners are no longer printing well (and thus one can avoid printing layers that are known to be above the ideal pressure_advance value). Inspect the print and then use a digital calipers to find the height that has the best quality corners. When in doubt, prefer a lower height. The pressure_advance value can then be calculated as pressure_advance = <start> + <measured_height> * <factor> . (For example, 0 + 12.90 * .020 would be .258 .) It is possible to choose custom settings for START and FACTOR if that helps identify the best pressure advance setting. When doing this, be sure to issue the TUNING_TOWER command at the start of each test print. Typical pressure advance values are between 0.050 and 1.000 (the high end usually only with bowden extruders). If there is no significant improvement with a pressure advance up to 1.000, then pressure advance is unlikely to improve the quality of prints. Return to a default configuration with pressure advance disabled. Although this tuning exercise directly improves the quality of corners, it's worth remembering that a good pressure advance configuration also reduces ooze throughout the print. At the completion of this test, set pressure_advance = <calculated_value> in the [extruder] section of the configuration file and issue a RESTART command. The RESTART command will clear the test state and return the acceleration and cornering speeds to their normal values. Important Notes \u00b6 The pressure advance value is dependent on the extruder, the nozzle, and the filament. It is common for filament from different manufactures or with different pigments to require significantly different pressure advance values. Therefore, one should calibrate pressure advance on each printer and with each spool of filament. Printing temperature and extrusion rates can impact pressure advance. Be sure to tune the extruder rotation_distance and nozzle temperature prior to tuning pressure advance. The test print is designed to run with a high extruder flow rate, but otherwise \"normal\" slicer settings. A high flow rate is obtained by using a high printing speed (eg, 100mm/s) and a coarse layer height (typically around 75% of the nozzle diameter). Other slicer settings should be similar to their defaults (eg, perimeters of 2 or 3 lines, normal retraction amount). It can be useful to set the external perimeter speed to be the same speed as the rest of the print, but it is not a requirement. It is common for the test print to show different behavior on each corner. Often the slicer will arrange to change layers at one corner which can result in that corner being significantly different from the remaining three corners. If this occurs, then ignore that corner and tune pressure advance using the other three corners. It is also common for the remaining corners to vary slightly. (This can occur due to small differences in how the printer's frame reacts to cornering in certain directions.) Try to choose a value that works well for all the remaining corners. If in doubt, prefer a lower pressure advance value. If a high pressure advance value (eg, over 0.200) is used then one may find that the extruder skips when returning to the printer's normal acceleration. The pressure advance system accounts for pressure by pushing in extra filament during acceleration and retracting that filament during deceleration. With a high acceleration and high pressure advance the extruder may not have enough torque to push the required filament. If this occurs, either use a lower acceleration value or disable pressure advance. Once pressure advance is tuned in Klipper, it may still be useful to configure a small retract value in the slicer (eg, 0.75mm) and to utilize the slicer's \"wipe on retract option\" if available. These slicer settings may help counteract ooze caused by filament cohesion (filament pulled out of the nozzle due to the stickiness of the plastic). It is recommended to disable the slicer's \"z-lift on retract\" option. The pressure advance system does not change the timing or path of the toolhead. A print with pressure advance enabled will take the same amount of time as a print without pressure advance. Pressure advance also does not change the total amount of filament extruded during a print. Pressure advance results in extra extruder movement during move acceleration and deceleration. A very high pressure advance setting will result in a very large amount of extruder movement during acceleration and deceleration, and no configuration setting places a limit on the amount of that movement.","title":"Pressure advance"},{"location":"Pressure_Advance.html#pressure-advance","text":"This document provides information on tuning the \"pressure advance\" configuration variable for a particular nozzle and filament. The pressure advance feature can be helpful in reducing ooze. For more information on how pressure advance is implemented see the kinematics document.","title":"Pressure advance"},{"location":"Pressure_Advance.html#tuning-pressure-advance","text":"Pressure advance does two useful things - it reduces ooze during non-extrude moves and it reduces blobbing during cornering. This guide uses the second feature (reducing blobbing during cornering) as a mechanism for tuning. In order to calibrate pressure advance the printer must be configured and operational as the tuning test involves printing and inspecting a test object. It is a good idea to read this document in full prior to running the test. Use a slicer to generate g-code for the large hollow square found in docs/prints/square_tower.stl . Use a high speed (eg, 100mm/s), zero infill, and a coarse layer height (the layer height should be around 75% of the nozzle diameter). Make sure any \"dynamic acceleration control\" and \"scarf joint\" seams are disabled in the slicer. Prepare for the test by issuing the following G-Code command: SET_VELOCITY_LIMIT SQUARE_CORNER_VELOCITY=1 ACCEL=500 This command makes the nozzle travel slower through corners to emphasize the effects of extruder pressure. Then for printers with a direct drive extruder run the command: TUNING_TOWER COMMAND=SET_PRESSURE_ADVANCE PARAMETER=ADVANCE START=0 FACTOR=.005 For long bowden extruders use: TUNING_TOWER COMMAND=SET_PRESSURE_ADVANCE PARAMETER=ADVANCE START=0 FACTOR=.020 Then print the object. When fully printed the test print looks like: The above TUNING_TOWER command instructs Klipper to alter the pressure_advance setting on each layer of the print. Higher layers in the print will have a larger pressure advance value set. Layers below the ideal pressure_advance setting will have blobbing at the corners, and layers above the ideal setting can lead to rounded corners and poor extrusion leading up to the corner. One can cancel the print early if one observes that the corners are no longer printing well (and thus one can avoid printing layers that are known to be above the ideal pressure_advance value). Inspect the print and then use a digital calipers to find the height that has the best quality corners. When in doubt, prefer a lower height. The pressure_advance value can then be calculated as pressure_advance = <start> + <measured_height> * <factor> . (For example, 0 + 12.90 * .020 would be .258 .) It is possible to choose custom settings for START and FACTOR if that helps identify the best pressure advance setting. When doing this, be sure to issue the TUNING_TOWER command at the start of each test print. Typical pressure advance values are between 0.050 and 1.000 (the high end usually only with bowden extruders). If there is no significant improvement with a pressure advance up to 1.000, then pressure advance is unlikely to improve the quality of prints. Return to a default configuration with pressure advance disabled. Although this tuning exercise directly improves the quality of corners, it's worth remembering that a good pressure advance configuration also reduces ooze throughout the print. At the completion of this test, set pressure_advance = <calculated_value> in the [extruder] section of the configuration file and issue a RESTART command. The RESTART command will clear the test state and return the acceleration and cornering speeds to their normal values.","title":"Tuning pressure advance"},{"location":"Pressure_Advance.html#important-notes","text":"The pressure advance value is dependent on the extruder, the nozzle, and the filament. It is common for filament from different manufactures or with different pigments to require significantly different pressure advance values. Therefore, one should calibrate pressure advance on each printer and with each spool of filament. Printing temperature and extrusion rates can impact pressure advance. Be sure to tune the extruder rotation_distance and nozzle temperature prior to tuning pressure advance. The test print is designed to run with a high extruder flow rate, but otherwise \"normal\" slicer settings. A high flow rate is obtained by using a high printing speed (eg, 100mm/s) and a coarse layer height (typically around 75% of the nozzle diameter). Other slicer settings should be similar to their defaults (eg, perimeters of 2 or 3 lines, normal retraction amount). It can be useful to set the external perimeter speed to be the same speed as the rest of the print, but it is not a requirement. It is common for the test print to show different behavior on each corner. Often the slicer will arrange to change layers at one corner which can result in that corner being significantly different from the remaining three corners. If this occurs, then ignore that corner and tune pressure advance using the other three corners. It is also common for the remaining corners to vary slightly. (This can occur due to small differences in how the printer's frame reacts to cornering in certain directions.) Try to choose a value that works well for all the remaining corners. If in doubt, prefer a lower pressure advance value. If a high pressure advance value (eg, over 0.200) is used then one may find that the extruder skips when returning to the printer's normal acceleration. The pressure advance system accounts for pressure by pushing in extra filament during acceleration and retracting that filament during deceleration. With a high acceleration and high pressure advance the extruder may not have enough torque to push the required filament. If this occurs, either use a lower acceleration value or disable pressure advance. Once pressure advance is tuned in Klipper, it may still be useful to configure a small retract value in the slicer (eg, 0.75mm) and to utilize the slicer's \"wipe on retract option\" if available. These slicer settings may help counteract ooze caused by filament cohesion (filament pulled out of the nozzle due to the stickiness of the plastic). It is recommended to disable the slicer's \"z-lift on retract\" option. The pressure advance system does not change the timing or path of the toolhead. A print with pressure advance enabled will take the same amount of time as a print without pressure advance. Pressure advance also does not change the total amount of filament extruded during a print. Pressure advance results in extra extruder movement during move acceleration and deceleration. A very high pressure advance setting will result in a very large amount of extruder movement during acceleration and deceleration, and no configuration setting places a limit on the amount of that movement.","title":"Important Notes"},{"location":"Probe_Calibrate.html","text":"Probe calibration \u00b6 This document describes the method for calibrating the X, Y, and Z offsets of an \"automatic z probe\" in Klipper. This is useful for users that have a [probe] or [bltouch] section in their config file. Calibrating probe X and Y offsets \u00b6 To calibrate the X and Y offset, navigate to the OctoPrint \"Control\" tab, home the printer, and then use the OctoPrint jogging buttons to move the head to a position near the center of the bed. Place a piece of blue painters tape (or similar) on the bed underneath the probe. Navigate to the OctoPrint \"Terminal\" tab and issue a PROBE command: PROBE Place a mark on the tape directly under where the probe is (or use a similar method to note the location on the bed). Issue a GET_POSITION command and record the toolhead XY location reported by that command. For example if one sees: Recv: // toolhead: X:46.500000 Y:27.000000 Z:15.000000 E:0.000000 then one would record a probe X position of 46.5 and probe Y position of 27. After recording the probe position, issue a series of G1 commands until the nozzle is directly above the mark on the bed. For example, one might issue: G1 F300 X57 Y30 Z15 to move the nozzle to an X position of 57 and Y of 30. Once one finds the position directly above the mark, use the GET_POSITION command to report that position. This is the nozzle position. The x_offset is then the nozzle_x_position - probe_x_position and y_offset is similarly the nozzle_y_position - probe_y_position . Update the printer.cfg file with the given values, remove the tape/marks from the bed, and then issue a RESTART command so that the new values take effect. Calibrating probe Z offset \u00b6 Providing an accurate probe z_offset is critical to obtaining high quality prints. The z_offset is the distance between the nozzle and bed when the probe triggers. The Klipper PROBE_CALIBRATE tool can be used to obtain this value - it will run an automatic probe to measure the probe's Z trigger position and then start a manual probe to obtain the nozzle Z height. The probe z_offset will then be calculated from these measurements. Start by homing the printer and then move the head to a position near the center of the bed. Navigate to the OctoPrint terminal tab and run the PROBE_CALIBRATE command to start the tool. This tool will perform an automatic probe, then lift the head, move the nozzle over the location of the probe point, and start the manual probe tool. If the nozzle does not move to a position above the automatic probe point, then ABORT the manual probe tool and perform the XY probe offset calibration described above. Once the manual probe tool starts, follow the steps described at \"the paper test\" to determine the actual distance between the nozzle and bed at the given location. Once those steps are complete one can ACCEPT the position and save the results to the config file with: SAVE_CONFIG Note that if a change is made to the printer's motion system, hotend position, or probe location then it will invalidate the results of PROBE_CALIBRATE. If the probe has an X or Y offset and the bed tilt is changed (eg, by adjusting bed screws, running DELTA_CALIBRATE, running Z_TILT_ADJUST, running QUAD_GANTRY_LEVEL, or similar) then it will invalidate the results of PROBE_CALIBRATE. After making any of the above adjustments it will be necessary to run PROBE_CALIBRATE again. If the results of PROBE_CALIBRATE are invalidated, then any previous bed mesh results that were obtained using the probe are also invalidated - it will be necessary to rerun BED_MESH_CALIBRATE after recalibrating the probe. Repeatability check \u00b6 After calibrating the probe X, Y, and Z offsets it is a good idea to verify that the probe provides repeatable results. Start by homing the printer and then move the head to a position near the center of the bed. Navigate to the OctoPrint terminal tab and run the PROBE_ACCURACY command. This command will run the probe ten times and produce output similar to the following: Recv: // probe accuracy: at X:0.000 Y:0.000 Z:10.000 Recv: // and read 10 times with speed of 5 mm/s Recv: // probe at -0.003,0.005 is z=2.506948 Recv: // probe at -0.003,0.005 is z=2.519448 Recv: // probe at -0.003,0.005 is z=2.519448 Recv: // probe at -0.003,0.005 is z=2.506948 Recv: // probe at -0.003,0.005 is z=2.519448 Recv: // probe at -0.003,0.005 is z=2.519448 Recv: // probe at -0.003,0.005 is z=2.506948 Recv: // probe at -0.003,0.005 is z=2.506948 Recv: // probe at -0.003,0.005 is z=2.519448 Recv: // probe at -0.003,0.005 is z=2.506948 Recv: // probe accuracy results: maximum 2.519448, minimum 2.506948, range 0.012500, average 2.513198, median 2.513198, standard deviation 0.006250 Ideally the tool will report an identical maximum and minimum value. (That is, ideally the probe obtains an identical result on all ten probes.) However, it's normal for the minimum and maximum values to differ by one Z \"step distance\" or up to 5 microns (.005mm). A \"step distance\" is rotation_distance/(full_steps_per_rotation*microsteps) . The distance between the minimum and the maximum value is called the range. So, in the above example, since the printer uses a Z step distance of .0125, a range of 0.012500 would be considered normal. If the results of the test show a range value that is greater than 25 microns (.025mm) then the probe does not have sufficient accuracy for typical bed leveling procedures. It may be possible to tune the probe speed and/or probe start height to improve the repeatability of the probe. The PROBE_ACCURACY command allows one to run tests with different parameters to see their impact - see the G-Codes document for further details. If the probe generally obtains repeatable results but has an occasional outlier, then it may be possible to account for that by using multiple samples on each probe - read the description of the probe samples config parameters in the config reference for more details. If new probe speed, samples count, or other settings are needed, then update the printer.cfg file and issue a RESTART command. If so, it is a good idea to calibrate the z_offset again. If repeatable results can not be obtained then don't use the probe for bed leveling. Klipper has several manual probing tools that can be used instead - see the Bed Level document for further details. Location Bias Check \u00b6 Some probes can have a systemic bias that corrupts the results of the probe at certain toolhead locations. For example, if the probe mount tilts slightly when moving along the Y axis then it could result in the probe reporting biased results at different Y positions. This is a common issue with probes on delta printers, however it can occur on all printers. One can check for a location bias by using the PROBE_CALIBRATE command to measuring the probe z_offset at various X and Y locations. Ideally, the probe z_offset would be a constant value at every printer location. For delta printers, try measuring the z_offset at a position near the A tower, at a position near the B tower, and at a position near the C tower. For cartesian, corexy, and similar printers, try measuring the z_offset at positions near the four corners of the bed. Before starting this test, first calibrate the probe X, Y, and Z offsets as described at the beginning of this document. Then home the printer and navigate to the first XY position. Follow the steps at calibrating probe Z offset to run the PROBE_CALIBRATE command, TESTZ commands, and ACCEPT command, but do not run SAVE_CONFIG . Note the reported z_offset found. Then navigate to the other XY positions, repeat these PROBE_CALIBRATE steps, and note the reported z_offset. If the difference between the minimum reported z_offset and the maximum reported z_offset is greater than 25 microns (.025mm) then the probe is not suitable for typical bed leveling procedures. See the Bed Level document for manual probe alternatives. Temperature Bias \u00b6 Many probes have a systemic bias when probing at different temperatures. For example, the probe may consistently trigger at a lower height when the probe is at a higher temperature. It is recommended to run the bed leveling tools at a consistent temperature to account for this bias. For example, either always run the tools when the printer is at room temperature, or always run the tools after the printer has obtained a consistent print temperature. In either case, it is a good idea to wait several minutes after the desired temperature is reached, so that the printer apparatus is consistently at the desired temperature. To check for a temperature bias, start with the printer at room temperature and then home the printer, move the head to a position near the center of the bed, and run the PROBE_ACCURACY command. Note the results. Then, without homing or disabling the stepper motors, heat the printer nozzle and bed to printing temperature, and run the PROBE_ACCURACY command again. Ideally, the command will report identical results. As above, if the probe does have a temperature bias then be careful to always use the probe at a consistent temperature.","title":"Probe calibration"},{"location":"Probe_Calibrate.html#probe-calibration","text":"This document describes the method for calibrating the X, Y, and Z offsets of an \"automatic z probe\" in Klipper. This is useful for users that have a [probe] or [bltouch] section in their config file.","title":"Probe calibration"},{"location":"Probe_Calibrate.html#calibrating-probe-x-and-y-offsets","text":"To calibrate the X and Y offset, navigate to the OctoPrint \"Control\" tab, home the printer, and then use the OctoPrint jogging buttons to move the head to a position near the center of the bed. Place a piece of blue painters tape (or similar) on the bed underneath the probe. Navigate to the OctoPrint \"Terminal\" tab and issue a PROBE command: PROBE Place a mark on the tape directly under where the probe is (or use a similar method to note the location on the bed). Issue a GET_POSITION command and record the toolhead XY location reported by that command. For example if one sees: Recv: // toolhead: X:46.500000 Y:27.000000 Z:15.000000 E:0.000000 then one would record a probe X position of 46.5 and probe Y position of 27. After recording the probe position, issue a series of G1 commands until the nozzle is directly above the mark on the bed. For example, one might issue: G1 F300 X57 Y30 Z15 to move the nozzle to an X position of 57 and Y of 30. Once one finds the position directly above the mark, use the GET_POSITION command to report that position. This is the nozzle position. The x_offset is then the nozzle_x_position - probe_x_position and y_offset is similarly the nozzle_y_position - probe_y_position . Update the printer.cfg file with the given values, remove the tape/marks from the bed, and then issue a RESTART command so that the new values take effect.","title":"Calibrating probe X and Y offsets"},{"location":"Probe_Calibrate.html#calibrating-probe-z-offset","text":"Providing an accurate probe z_offset is critical to obtaining high quality prints. The z_offset is the distance between the nozzle and bed when the probe triggers. The Klipper PROBE_CALIBRATE tool can be used to obtain this value - it will run an automatic probe to measure the probe's Z trigger position and then start a manual probe to obtain the nozzle Z height. The probe z_offset will then be calculated from these measurements. Start by homing the printer and then move the head to a position near the center of the bed. Navigate to the OctoPrint terminal tab and run the PROBE_CALIBRATE command to start the tool. This tool will perform an automatic probe, then lift the head, move the nozzle over the location of the probe point, and start the manual probe tool. If the nozzle does not move to a position above the automatic probe point, then ABORT the manual probe tool and perform the XY probe offset calibration described above. Once the manual probe tool starts, follow the steps described at \"the paper test\" to determine the actual distance between the nozzle and bed at the given location. Once those steps are complete one can ACCEPT the position and save the results to the config file with: SAVE_CONFIG Note that if a change is made to the printer's motion system, hotend position, or probe location then it will invalidate the results of PROBE_CALIBRATE. If the probe has an X or Y offset and the bed tilt is changed (eg, by adjusting bed screws, running DELTA_CALIBRATE, running Z_TILT_ADJUST, running QUAD_GANTRY_LEVEL, or similar) then it will invalidate the results of PROBE_CALIBRATE. After making any of the above adjustments it will be necessary to run PROBE_CALIBRATE again. If the results of PROBE_CALIBRATE are invalidated, then any previous bed mesh results that were obtained using the probe are also invalidated - it will be necessary to rerun BED_MESH_CALIBRATE after recalibrating the probe.","title":"Calibrating probe Z offset"},{"location":"Probe_Calibrate.html#repeatability-check","text":"After calibrating the probe X, Y, and Z offsets it is a good idea to verify that the probe provides repeatable results. Start by homing the printer and then move the head to a position near the center of the bed. Navigate to the OctoPrint terminal tab and run the PROBE_ACCURACY command. This command will run the probe ten times and produce output similar to the following: Recv: // probe accuracy: at X:0.000 Y:0.000 Z:10.000 Recv: // and read 10 times with speed of 5 mm/s Recv: // probe at -0.003,0.005 is z=2.506948 Recv: // probe at -0.003,0.005 is z=2.519448 Recv: // probe at -0.003,0.005 is z=2.519448 Recv: // probe at -0.003,0.005 is z=2.506948 Recv: // probe at -0.003,0.005 is z=2.519448 Recv: // probe at -0.003,0.005 is z=2.519448 Recv: // probe at -0.003,0.005 is z=2.506948 Recv: // probe at -0.003,0.005 is z=2.506948 Recv: // probe at -0.003,0.005 is z=2.519448 Recv: // probe at -0.003,0.005 is z=2.506948 Recv: // probe accuracy results: maximum 2.519448, minimum 2.506948, range 0.012500, average 2.513198, median 2.513198, standard deviation 0.006250 Ideally the tool will report an identical maximum and minimum value. (That is, ideally the probe obtains an identical result on all ten probes.) However, it's normal for the minimum and maximum values to differ by one Z \"step distance\" or up to 5 microns (.005mm). A \"step distance\" is rotation_distance/(full_steps_per_rotation*microsteps) . The distance between the minimum and the maximum value is called the range. So, in the above example, since the printer uses a Z step distance of .0125, a range of 0.012500 would be considered normal. If the results of the test show a range value that is greater than 25 microns (.025mm) then the probe does not have sufficient accuracy for typical bed leveling procedures. It may be possible to tune the probe speed and/or probe start height to improve the repeatability of the probe. The PROBE_ACCURACY command allows one to run tests with different parameters to see their impact - see the G-Codes document for further details. If the probe generally obtains repeatable results but has an occasional outlier, then it may be possible to account for that by using multiple samples on each probe - read the description of the probe samples config parameters in the config reference for more details. If new probe speed, samples count, or other settings are needed, then update the printer.cfg file and issue a RESTART command. If so, it is a good idea to calibrate the z_offset again. If repeatable results can not be obtained then don't use the probe for bed leveling. Klipper has several manual probing tools that can be used instead - see the Bed Level document for further details.","title":"Repeatability check"},{"location":"Probe_Calibrate.html#location-bias-check","text":"Some probes can have a systemic bias that corrupts the results of the probe at certain toolhead locations. For example, if the probe mount tilts slightly when moving along the Y axis then it could result in the probe reporting biased results at different Y positions. This is a common issue with probes on delta printers, however it can occur on all printers. One can check for a location bias by using the PROBE_CALIBRATE command to measuring the probe z_offset at various X and Y locations. Ideally, the probe z_offset would be a constant value at every printer location. For delta printers, try measuring the z_offset at a position near the A tower, at a position near the B tower, and at a position near the C tower. For cartesian, corexy, and similar printers, try measuring the z_offset at positions near the four corners of the bed. Before starting this test, first calibrate the probe X, Y, and Z offsets as described at the beginning of this document. Then home the printer and navigate to the first XY position. Follow the steps at calibrating probe Z offset to run the PROBE_CALIBRATE command, TESTZ commands, and ACCEPT command, but do not run SAVE_CONFIG . Note the reported z_offset found. Then navigate to the other XY positions, repeat these PROBE_CALIBRATE steps, and note the reported z_offset. If the difference between the minimum reported z_offset and the maximum reported z_offset is greater than 25 microns (.025mm) then the probe is not suitable for typical bed leveling procedures. See the Bed Level document for manual probe alternatives.","title":"Location Bias Check"},{"location":"Probe_Calibrate.html#temperature-bias","text":"Many probes have a systemic bias when probing at different temperatures. For example, the probe may consistently trigger at a lower height when the probe is at a higher temperature. It is recommended to run the bed leveling tools at a consistent temperature to account for this bias. For example, either always run the tools when the printer is at room temperature, or always run the tools after the printer has obtained a consistent print temperature. In either case, it is a good idea to wait several minutes after the desired temperature is reached, so that the printer apparatus is consistently at the desired temperature. To check for a temperature bias, start with the printer at room temperature and then home the printer, move the head to a position near the center of the bed, and run the PROBE_ACCURACY command. Note the results. Then, without homing or disabling the stepper motors, heat the printer nozzle and bed to printing temperature, and run the PROBE_ACCURACY command again. Ideally, the command will report identical results. As above, if the probe does have a temperature bias then be careful to always use the probe at a consistent temperature.","title":"Temperature Bias"},{"location":"Protocol.html","text":"Protocol \u00b6 The Klipper messaging protocol is used for low-level communication between the Klipper host software and the Klipper micro-controller software. At a high level the protocol can be thought of as a series of command and response strings that are compressed, transmitted, and then processed at the receiving side. An example series of commands in uncompressed human-readable format might look like: set_digital_out pin=PA3 value=1 set_digital_out pin=PA7 value=1 schedule_digital_out oid=8 clock=4000000 value=0 queue_step oid=7 interval=7458 count=10 add=331 queue_step oid=7 interval=11717 count=4 add=1281 See the mcu commands document for information on available commands. See the debugging document for information on how to translate a G-Code file into its corresponding human-readable micro-controller commands. This page provides a high-level description of the Klipper messaging protocol itself. It describes how messages are declared, encoded in binary format (the \"compression\" scheme), and transmitted. The goal of the protocol is to enable an error-free communication channel between the host and micro-controller that is low-latency, low-bandwidth, and low-complexity for the micro-controller. Micro-controller Interface \u00b6 The Klipper transmission protocol can be thought of as a RPC mechanism between micro-controller and host. The micro-controller software declares the commands that the host may invoke along with the response messages that it can generate. The host uses that information to command the micro-controller to perform actions and to interpret the results. Declaring commands \u00b6 The micro-controller software declares a \"command\" by using the DECL_COMMAND() macro in the C code. For example: DECL_COMMAND(command_update_digital_out, \"update_digital_out oid=%c value=%c\"); The above declares a command named \"update_digital_out\". This allows the host to \"invoke\" this command which would cause the command_update_digital_out() C function to be executed in the micro-controller. The above also indicates that the command takes two integer parameters. When the command_update_digital_out() C code is executed, it will be passed an array containing these two integers - the first corresponding to the 'oid' and the second corresponding to the 'value'. In general, the parameters are described with printf() style syntax (eg, \"%u\"). The formatting directly corresponds to the human-readable view of commands (eg, \"update_digital_out oid=7 value=1\"). In the above example, \"value=\" is a parameter name and \"%c\" indicates the parameter is an integer. Internally, the parameter name is only used as documentation. In this example, the \"%c\" is also used as documentation to indicate the expected integer is 1 byte in size (the declared integer size does not impact the parsing or encoding). The micro-controller build will collect all commands declared with DECL_COMMAND(), determine their parameters, and arrange for them to be callable. Declaring responses \u00b6 To send information from the micro-controller to the host a \"response\" is generated. These are both declared and transmitted using the sendf() C macro. For example: sendf(\"status clock=%u status=%c\", sched_read_time(), sched_is_shutdown()); The above transmits a \"status\" response message that contains two integer parameters (\"clock\" and \"status\"). The micro-controller build automatically finds all sendf() calls and generates encoders for them. The first parameter of the sendf() function describes the response and it is in the same format as command declarations. The host can arrange to register a callback function for each response. So, in effect, commands allow the host to invoke C functions in the micro-controller and responses allow the micro-controller software to invoke code in the host. The sendf() macro should only be invoked from command or task handlers, and it should not be invoked from interrupts or timers. The code does not need to issue a sendf() in response to a received command, it is not limited in the number of times sendf() may be invoked, and it may invoke sendf() at any time from a task handler. Output responses \u00b6 To simplify debugging, there is also an output() C function. For example: output(\"The value of %u is %s with size %u.\", x, buf, buf_len); The output() function is similar in usage to printf() - it is intended to generate and format arbitrary messages for human consumption. Declaring enumerations \u00b6 Enumerations allow the host code to use string identifiers for parameters that the micro-controller handles as integers. They are declared in the micro-controller code - for example: DECL_ENUMERATION(\"spi_bus\", \"spi\", 0); DECL_ENUMERATION_RANGE(\"pin\", \"PC0\", 16, 8); If the first example, the DECL_ENUMERATION() macro defines an enumeration for any command/response message with a parameter name of \"spi_bus\" or parameter name with a suffix of \"_spi_bus\". For those parameters the string \"spi\" is a valid value and it will be transmitted with an integer value of zero. It's also possible to declare an enumeration range. In the second example, a \"pin\" parameter (or any parameter with a suffix of \"_pin\") would accept PC0, PC1, PC2, ..., PC7 as valid values. The strings will be transmitted with integers 16, 17, 18, ..., 23. Declaring constants \u00b6 Constants can also be exported. For example, the following: DECL_CONSTANT(\"SERIAL_BAUD\", 250000); would export a constant named \"SERIAL_BAUD\" with a value of 250000 from the micro-controller to the host. It is also possible to declare a constant that is a string - for example: DECL_CONSTANT_STR(\"MCU\", \"pru\"); Low-level message encoding \u00b6 To accomplish the above RPC mechanism, each command and response is encoded into a binary format for transmission. This section describes the transmission system. Message Blocks \u00b6 All data sent from host to micro-controller and vice-versa are contained in \"message blocks\". A message block has a two byte header and a three byte trailer. The format of a message block is: <1 byte length><1 byte sequence><n-byte content><2 byte crc><1 byte sync> The length byte contains the number of bytes in the message block including the header and trailer bytes (thus the minimum message length is 5 bytes). The maximum message block length is currently 64 bytes. The sequence byte contains a 4 bit sequence number in the low-order bits and the high-order bits always contain 0x10 (the high-order bits are reserved for future use). The content bytes contain arbitrary data and its format is described in the following section. The crc bytes contain a 16bit CCITT CRC of the message block including the header bytes but excluding the trailer bytes. The sync byte is 0x7e. The format of the message block is inspired by HDLC message frames. Like in HDLC, the message block may optionally contain an additional sync character at the start of the block. Unlike in HDLC, a sync character is not exclusive to the framing and may be present in the message block content. Message Block Contents \u00b6 Each message block sent from host to micro-controller contains a series of zero or more message commands in its contents. Each command starts with a Variable Length Quantity (VLQ) encoded integer command-id followed by zero or more VLQ parameters for the given command. As an example, the following four commands might be placed in a single message block: update_digital_out oid=6 value=1 update_digital_out oid=5 value=0 get_config get_clock and encoded into the following eight VLQ integers: <id_update_digital_out><6><1><id_update_digital_out><5><0><id_get_config><id_get_clock> In order to encode and parse the message contents, both the host and micro-controller must agree on the command ids and the number of parameters each command has. So, in the above example, both the host and micro-controller would know that \"id_update_digital_out\" is always followed by two parameters, and \"id_get_config\" and \"id_get_clock\" have zero parameters. The host and micro-controller share a \"data dictionary\" that maps the command descriptions (eg, \"update_digital_out oid=%c value=%c\") to their integer command-ids. When processing the data, the parser will know to expect a specific number of VLQ encoded parameters following a given command id. The message contents for blocks sent from micro-controller to host follow the same format. The identifiers in these messages are \"response ids\", but they serve the same purpose and follow the same encoding rules. In practice, message blocks sent from the micro-controller to the host never contain more than one response in the message block contents. Variable Length Quantities \u00b6 See the wikipedia article for more information on the general format of VLQ encoded integers. Klipper uses an encoding scheme that supports both positive and negative integers. Integers close to zero use less bytes to encode and positive integers typically encode using less bytes than negative integers. The following table shows the number of bytes each integer takes to encode: Integer Encoded size -32 .. 95 1 -4096 .. 12287 2 -524288 .. 1572863 3 -67108864 .. 201326591 4 -2147483648 .. 4294967295 5 Variable length strings \u00b6 As an exception to the above encoding rules, if a parameter to a command or response is a dynamic string then the parameter is not encoded as a simple VLQ integer. Instead it is encoded by transmitting the length as a VLQ encoded integer followed by the contents itself: <VLQ encoded length><n-byte contents> The command descriptions found in the data dictionary allow both the host and micro-controller to know which command parameters use simple VLQ encoding and which parameters use string encoding. Data Dictionary \u00b6 In order for meaningful communications to be established between micro-controller and host, both sides must agree on a \"data dictionary\". This data dictionary contains the integer identifiers for commands and responses along with their descriptions. The micro-controller build uses the contents of DECL_COMMAND() and sendf() macros to generate the data dictionary. The build automatically assigns unique identifiers to each command and response. This system allows both the host and micro-controller code to seamlessly use descriptive human-readable names while still using minimal bandwidth. The host queries the data dictionary when it first connects to the micro-controller. Once the host downloads the data dictionary from the micro-controller, it uses that data dictionary to encode all commands and to parse all responses from the micro-controller. The host must therefore handle a dynamic data dictionary. However, to keep the micro-controller software simple, the micro-controller always uses its static (compiled in) data dictionary. The data dictionary is queried by sending \"identify\" commands to the micro-controller. The micro-controller will respond to each identify command with an \"identify_response\" message. Since these two commands are needed prior to obtaining the data dictionary, their integer ids and parameter types are hard-coded in both the micro-controller and the host. The \"identify_response\" response id is 0, the \"identify\" command id is 1. Other than having hard-coded ids the identify command and its response are declared and transmitted the same way as other commands and responses. No other command or response is hard-coded. The format of the transmitted data dictionary itself is a zlib compressed JSON string. The micro-controller build process generates the string, compresses it, and stores it in the text section of the micro-controller flash. The data dictionary can be much larger than the maximum message block size - the host downloads it by sending multiple identify commands requesting progressive chunks of the data dictionary. Once all chunks are obtained the host will assemble the chunks, uncompress the data, and parse the contents. In addition to information on the communication protocol, the data dictionary also contains the software version, enumerations (as defined by DECL_ENUMERATION), and constants (as defined by DECL_CONSTANT). Message flow \u00b6 Message commands sent from host to micro-controller are intended to be error-free. The micro-controller will check the CRC and sequence numbers in each message block to ensure the commands are accurate and in-order. The micro-controller always processes message blocks in-order - should it receive a block out-of-order it will discard it and any other out-of-order blocks until it receives blocks with the correct sequencing. The low-level host code implements an automatic retransmission system for lost and corrupt message blocks sent to the micro-controller. To facilitate this, the micro-controller transmits an \"ack message block\" after each successfully received message block. The host schedules a timeout after sending each block and it will retransmit should the timeout expire without receiving a corresponding \"ack\". In addition, if the micro-controller detects a corrupt or out-of-order block it may transmit a \"nak message block\" to facilitate fast retransmission. An \"ack\" is a message block with empty content (ie, a 5 byte message block) and a sequence number greater than the last received host sequence number. A \"nak\" is a message block with empty content and a sequence number less than the last received host sequence number. The protocol facilitates a \"window\" transmission system so that the host can have many outstanding message blocks in-flight at a time. (This is in addition to the many commands that may be present in a given message block.) This allows maximum bandwidth utilization even in the event of transmission latency. The timeout, retransmit, windowing, and ack mechanism are inspired by similar mechanisms in TCP . In the other direction, message blocks sent from micro-controller to host are designed to be error-free, but they do not have assured transmission. (Responses should not be corrupt, but they may go missing.) This is done to keep the implementation in the micro-controller simple. There is no automatic retransmission system for responses - the high-level code is expected to be capable of handling an occasional missing response (usually by re-requesting the content or setting up a recurring schedule of response transmission). The sequence number field in message blocks sent to the host is always one greater than the last received sequence number of message blocks received from the host. It is not used to track sequences of response message blocks.","title":"Protocol"},{"location":"Protocol.html#protocol","text":"The Klipper messaging protocol is used for low-level communication between the Klipper host software and the Klipper micro-controller software. At a high level the protocol can be thought of as a series of command and response strings that are compressed, transmitted, and then processed at the receiving side. An example series of commands in uncompressed human-readable format might look like: set_digital_out pin=PA3 value=1 set_digital_out pin=PA7 value=1 schedule_digital_out oid=8 clock=4000000 value=0 queue_step oid=7 interval=7458 count=10 add=331 queue_step oid=7 interval=11717 count=4 add=1281 See the mcu commands document for information on available commands. See the debugging document for information on how to translate a G-Code file into its corresponding human-readable micro-controller commands. This page provides a high-level description of the Klipper messaging protocol itself. It describes how messages are declared, encoded in binary format (the \"compression\" scheme), and transmitted. The goal of the protocol is to enable an error-free communication channel between the host and micro-controller that is low-latency, low-bandwidth, and low-complexity for the micro-controller.","title":"Protocol"},{"location":"Protocol.html#micro-controller-interface","text":"The Klipper transmission protocol can be thought of as a RPC mechanism between micro-controller and host. The micro-controller software declares the commands that the host may invoke along with the response messages that it can generate. The host uses that information to command the micro-controller to perform actions and to interpret the results.","title":"Micro-controller Interface"},{"location":"Protocol.html#declaring-commands","text":"The micro-controller software declares a \"command\" by using the DECL_COMMAND() macro in the C code. For example: DECL_COMMAND(command_update_digital_out, \"update_digital_out oid=%c value=%c\"); The above declares a command named \"update_digital_out\". This allows the host to \"invoke\" this command which would cause the command_update_digital_out() C function to be executed in the micro-controller. The above also indicates that the command takes two integer parameters. When the command_update_digital_out() C code is executed, it will be passed an array containing these two integers - the first corresponding to the 'oid' and the second corresponding to the 'value'. In general, the parameters are described with printf() style syntax (eg, \"%u\"). The formatting directly corresponds to the human-readable view of commands (eg, \"update_digital_out oid=7 value=1\"). In the above example, \"value=\" is a parameter name and \"%c\" indicates the parameter is an integer. Internally, the parameter name is only used as documentation. In this example, the \"%c\" is also used as documentation to indicate the expected integer is 1 byte in size (the declared integer size does not impact the parsing or encoding). The micro-controller build will collect all commands declared with DECL_COMMAND(), determine their parameters, and arrange for them to be callable.","title":"Declaring commands"},{"location":"Protocol.html#declaring-responses","text":"To send information from the micro-controller to the host a \"response\" is generated. These are both declared and transmitted using the sendf() C macro. For example: sendf(\"status clock=%u status=%c\", sched_read_time(), sched_is_shutdown()); The above transmits a \"status\" response message that contains two integer parameters (\"clock\" and \"status\"). The micro-controller build automatically finds all sendf() calls and generates encoders for them. The first parameter of the sendf() function describes the response and it is in the same format as command declarations. The host can arrange to register a callback function for each response. So, in effect, commands allow the host to invoke C functions in the micro-controller and responses allow the micro-controller software to invoke code in the host. The sendf() macro should only be invoked from command or task handlers, and it should not be invoked from interrupts or timers. The code does not need to issue a sendf() in response to a received command, it is not limited in the number of times sendf() may be invoked, and it may invoke sendf() at any time from a task handler.","title":"Declaring responses"},{"location":"Protocol.html#output-responses","text":"To simplify debugging, there is also an output() C function. For example: output(\"The value of %u is %s with size %u.\", x, buf, buf_len); The output() function is similar in usage to printf() - it is intended to generate and format arbitrary messages for human consumption.","title":"Output responses"},{"location":"Protocol.html#declaring-enumerations","text":"Enumerations allow the host code to use string identifiers for parameters that the micro-controller handles as integers. They are declared in the micro-controller code - for example: DECL_ENUMERATION(\"spi_bus\", \"spi\", 0); DECL_ENUMERATION_RANGE(\"pin\", \"PC0\", 16, 8); If the first example, the DECL_ENUMERATION() macro defines an enumeration for any command/response message with a parameter name of \"spi_bus\" or parameter name with a suffix of \"_spi_bus\". For those parameters the string \"spi\" is a valid value and it will be transmitted with an integer value of zero. It's also possible to declare an enumeration range. In the second example, a \"pin\" parameter (or any parameter with a suffix of \"_pin\") would accept PC0, PC1, PC2, ..., PC7 as valid values. The strings will be transmitted with integers 16, 17, 18, ..., 23.","title":"Declaring enumerations"},{"location":"Protocol.html#declaring-constants","text":"Constants can also be exported. For example, the following: DECL_CONSTANT(\"SERIAL_BAUD\", 250000); would export a constant named \"SERIAL_BAUD\" with a value of 250000 from the micro-controller to the host. It is also possible to declare a constant that is a string - for example: DECL_CONSTANT_STR(\"MCU\", \"pru\");","title":"Declaring constants"},{"location":"Protocol.html#low-level-message-encoding","text":"To accomplish the above RPC mechanism, each command and response is encoded into a binary format for transmission. This section describes the transmission system.","title":"Low-level message encoding"},{"location":"Protocol.html#message-blocks","text":"All data sent from host to micro-controller and vice-versa are contained in \"message blocks\". A message block has a two byte header and a three byte trailer. The format of a message block is: <1 byte length><1 byte sequence><n-byte content><2 byte crc><1 byte sync> The length byte contains the number of bytes in the message block including the header and trailer bytes (thus the minimum message length is 5 bytes). The maximum message block length is currently 64 bytes. The sequence byte contains a 4 bit sequence number in the low-order bits and the high-order bits always contain 0x10 (the high-order bits are reserved for future use). The content bytes contain arbitrary data and its format is described in the following section. The crc bytes contain a 16bit CCITT CRC of the message block including the header bytes but excluding the trailer bytes. The sync byte is 0x7e. The format of the message block is inspired by HDLC message frames. Like in HDLC, the message block may optionally contain an additional sync character at the start of the block. Unlike in HDLC, a sync character is not exclusive to the framing and may be present in the message block content.","title":"Message Blocks"},{"location":"Protocol.html#message-block-contents","text":"Each message block sent from host to micro-controller contains a series of zero or more message commands in its contents. Each command starts with a Variable Length Quantity (VLQ) encoded integer command-id followed by zero or more VLQ parameters for the given command. As an example, the following four commands might be placed in a single message block: update_digital_out oid=6 value=1 update_digital_out oid=5 value=0 get_config get_clock and encoded into the following eight VLQ integers: <id_update_digital_out><6><1><id_update_digital_out><5><0><id_get_config><id_get_clock> In order to encode and parse the message contents, both the host and micro-controller must agree on the command ids and the number of parameters each command has. So, in the above example, both the host and micro-controller would know that \"id_update_digital_out\" is always followed by two parameters, and \"id_get_config\" and \"id_get_clock\" have zero parameters. The host and micro-controller share a \"data dictionary\" that maps the command descriptions (eg, \"update_digital_out oid=%c value=%c\") to their integer command-ids. When processing the data, the parser will know to expect a specific number of VLQ encoded parameters following a given command id. The message contents for blocks sent from micro-controller to host follow the same format. The identifiers in these messages are \"response ids\", but they serve the same purpose and follow the same encoding rules. In practice, message blocks sent from the micro-controller to the host never contain more than one response in the message block contents.","title":"Message Block Contents"},{"location":"Protocol.html#variable-length-quantities","text":"See the wikipedia article for more information on the general format of VLQ encoded integers. Klipper uses an encoding scheme that supports both positive and negative integers. Integers close to zero use less bytes to encode and positive integers typically encode using less bytes than negative integers. The following table shows the number of bytes each integer takes to encode: Integer Encoded size -32 .. 95 1 -4096 .. 12287 2 -524288 .. 1572863 3 -67108864 .. 201326591 4 -2147483648 .. 4294967295 5","title":"Variable Length Quantities"},{"location":"Protocol.html#variable-length-strings","text":"As an exception to the above encoding rules, if a parameter to a command or response is a dynamic string then the parameter is not encoded as a simple VLQ integer. Instead it is encoded by transmitting the length as a VLQ encoded integer followed by the contents itself: <VLQ encoded length><n-byte contents> The command descriptions found in the data dictionary allow both the host and micro-controller to know which command parameters use simple VLQ encoding and which parameters use string encoding.","title":"Variable length strings"},{"location":"Protocol.html#data-dictionary","text":"In order for meaningful communications to be established between micro-controller and host, both sides must agree on a \"data dictionary\". This data dictionary contains the integer identifiers for commands and responses along with their descriptions. The micro-controller build uses the contents of DECL_COMMAND() and sendf() macros to generate the data dictionary. The build automatically assigns unique identifiers to each command and response. This system allows both the host and micro-controller code to seamlessly use descriptive human-readable names while still using minimal bandwidth. The host queries the data dictionary when it first connects to the micro-controller. Once the host downloads the data dictionary from the micro-controller, it uses that data dictionary to encode all commands and to parse all responses from the micro-controller. The host must therefore handle a dynamic data dictionary. However, to keep the micro-controller software simple, the micro-controller always uses its static (compiled in) data dictionary. The data dictionary is queried by sending \"identify\" commands to the micro-controller. The micro-controller will respond to each identify command with an \"identify_response\" message. Since these two commands are needed prior to obtaining the data dictionary, their integer ids and parameter types are hard-coded in both the micro-controller and the host. The \"identify_response\" response id is 0, the \"identify\" command id is 1. Other than having hard-coded ids the identify command and its response are declared and transmitted the same way as other commands and responses. No other command or response is hard-coded. The format of the transmitted data dictionary itself is a zlib compressed JSON string. The micro-controller build process generates the string, compresses it, and stores it in the text section of the micro-controller flash. The data dictionary can be much larger than the maximum message block size - the host downloads it by sending multiple identify commands requesting progressive chunks of the data dictionary. Once all chunks are obtained the host will assemble the chunks, uncompress the data, and parse the contents. In addition to information on the communication protocol, the data dictionary also contains the software version, enumerations (as defined by DECL_ENUMERATION), and constants (as defined by DECL_CONSTANT).","title":"Data Dictionary"},{"location":"Protocol.html#message-flow","text":"Message commands sent from host to micro-controller are intended to be error-free. The micro-controller will check the CRC and sequence numbers in each message block to ensure the commands are accurate and in-order. The micro-controller always processes message blocks in-order - should it receive a block out-of-order it will discard it and any other out-of-order blocks until it receives blocks with the correct sequencing. The low-level host code implements an automatic retransmission system for lost and corrupt message blocks sent to the micro-controller. To facilitate this, the micro-controller transmits an \"ack message block\" after each successfully received message block. The host schedules a timeout after sending each block and it will retransmit should the timeout expire without receiving a corresponding \"ack\". In addition, if the micro-controller detects a corrupt or out-of-order block it may transmit a \"nak message block\" to facilitate fast retransmission. An \"ack\" is a message block with empty content (ie, a 5 byte message block) and a sequence number greater than the last received host sequence number. A \"nak\" is a message block with empty content and a sequence number less than the last received host sequence number. The protocol facilitates a \"window\" transmission system so that the host can have many outstanding message blocks in-flight at a time. (This is in addition to the many commands that may be present in a given message block.) This allows maximum bandwidth utilization even in the event of transmission latency. The timeout, retransmit, windowing, and ack mechanism are inspired by similar mechanisms in TCP . In the other direction, message blocks sent from micro-controller to host are designed to be error-free, but they do not have assured transmission. (Responses should not be corrupt, but they may go missing.) This is done to keep the implementation in the micro-controller simple. There is no automatic retransmission system for responses - the high-level code is expected to be capable of handling an occasional missing response (usually by re-requesting the content or setting up a recurring schedule of response transmission). The sequence number field in message blocks sent to the host is always one greater than the last received sequence number of message blocks received from the host. It is not used to track sequences of response message blocks.","title":"Message flow"},{"location":"RPi_microcontroller.html","text":"RPi microcontroller \u00b6 This document describes the process of running Klipper on a RPi and use the same RPi as secondary mcu. Why use RPi as a secondary MCU? \u00b6 Often the MCUs dedicated to controlling 3D printers have a limited and pre-configured number of exposed pins to manage the main printing functions (thermal resistors, extruders, steppers ...). Using the RPi where Klipper is installed as a secondary MCU gives the possibility to directly use the GPIOs and the buses (i2c, spi) of the RPi inside klipper without using Octoprint plugins (if used) or external programs giving the ability to control everything within the print GCODE. Warning : If your platform is a Beaglebone and you have correctly followed the installation steps, the linux mcu is already installed and configured for your system. Install the rc script \u00b6 If you want to use the host as a secondary MCU the klipper_mcu process must run before the klippy process. After installing Klipper, install the script. run: cd ~/klipper/ sudo cp ./scripts/klipper-mcu.service /etc/systemd/system/ sudo systemctl enable klipper-mcu.service Building the micro-controller code \u00b6 To compile the Klipper micro-controller code, start by configuring it for the \"Linux process\": cd ~/klipper/ make menuconfig In the menu, set \"Microcontroller Architecture\" to \"Linux process,\" then save and exit. To build and install the new micro-controller code, run: sudo service klipper stop make flash sudo service klipper start If klippy.log reports a \"Permission denied\" error when attempting to connect to /tmp/klipper_host_mcu then you need to add your user to the tty group. The following command will add the \"pi\" user to the tty group: sudo usermod -a -G tty pi Remaining configuration \u00b6 Complete the installation by configuring Klipper secondary MCU following the instructions in RaspberryPi sample config and Multi MCU sample config . Optional: Enabling SPI \u00b6 Make sure the Linux SPI driver is enabled by running sudo raspi-config and enabling SPI under the \"Interfacing options\" menu. Optional: Enabling I2C \u00b6 Make sure the Linux I2C driver is enabled by running sudo raspi-config and enabling I2C under the \"Interfacing options\" menu. If planning to use I2C for the MPU accelerometer, it is also required to set the baud rate to 400000 by: adding/uncommenting dtparam=i2c_arm=on,i2c_arm_baudrate=400000 in /boot/config.txt (or /boot/firmware/config.txt in some distros). Optional: Identify the correct gpiochip \u00b6 On Raspberry Pi and on many clones the pins exposed on the GPIO belong to the first gpiochip. They can therefore be used on klipper simply by referring them with the name gpio0..n . However, there are cases in which the exposed pins belong to gpiochips other than the first. For example in the case of some OrangePi models or if a Port Expander is used. In these cases it is useful to use the commands to access the Linux GPIO character device to verify the configuration. To install the Linux GPIO character device - binary on a debian based distro like octopi run: sudo apt-get install gpiod To check available gpiochip run: gpiodetect To check the pin number and the pin availability tun: gpioinfo The chosen pin can thus be used within the configuration as gpiochip<n>/gpio<o> where n is the chip number as seen by the gpiodetect command and o is the line number seen by the gpioinfo command. Warning: only gpio marked as unused can be used. It is not possible for a line to be used by multiple processes simultaneously. For example on a RPi 3B+ where klipper use the GPIO20 for a switch: $ gpiodetect gpiochip0 [pinctrl-bcm2835] (54 lines) gpiochip1 [raspberrypi-exp-gpio] (8 lines) $ gpioinfo gpiochip0 - 54 lines: line 0: unnamed unused input active-high line 1: unnamed unused input active-high line 2: unnamed unused input active-high line 3: unnamed unused input active-high line 4: unnamed unused input active-high line 5: unnamed unused input active-high line 6: unnamed unused input active-high line 7: unnamed unused input active-high line 8: unnamed unused input active-high line 9: unnamed unused input active-high line 10: unnamed unused input active-high line 11: unnamed unused input active-high line 12: unnamed unused input active-high line 13: unnamed unused input active-high line 14: unnamed unused input active-high line 15: unnamed unused input active-high line 16: unnamed unused input active-high line 17: unnamed unused input active-high line 18: unnamed unused input active-high line 19: unnamed unused input active-high line 20: unnamed \"klipper\" output active-high [used] line 21: unnamed unused input active-high line 22: unnamed unused input active-high line 23: unnamed unused input active-high line 24: unnamed unused input active-high line 25: unnamed unused input active-high line 26: unnamed unused input active-high line 27: unnamed unused input active-high line 28: unnamed unused input active-high line 29: unnamed \"led0\" output active-high [used] line 30: unnamed unused input active-high line 31: unnamed unused input active-high line 32: unnamed unused input active-high line 33: unnamed unused input active-high line 34: unnamed unused input active-high line 35: unnamed unused input active-high line 36: unnamed unused input active-high line 37: unnamed unused input active-high line 38: unnamed unused input active-high line 39: unnamed unused input active-high line 40: unnamed unused input active-high line 41: unnamed unused input active-high line 42: unnamed unused input active-high line 43: unnamed unused input active-high line 44: unnamed unused input active-high line 45: unnamed unused input active-high line 46: unnamed unused input active-high line 47: unnamed unused input active-high line 48: unnamed unused input active-high line 49: unnamed unused input active-high line 50: unnamed unused input active-high line 51: unnamed unused input active-high line 52: unnamed unused input active-high line 53: unnamed unused input active-high gpiochip1 - 8 lines: line 0: unnamed unused input active-high line 1: unnamed unused input active-high line 2: unnamed \"led1\" output active-low [used] line 3: unnamed unused input active-high line 4: unnamed unused input active-high line 5: unnamed unused input active-high line 6: unnamed unused input active-high line 7: unnamed unused input active-high Optional: Hardware PWM \u00b6 Raspberry Pi's have two PWM channels (PWM0 and PWM1) which are exposed on the header or if not, can be routed to existing gpio pins. The Linux mcu daemon uses the pwmchip sysfs interface to control hardware pwm devices on Linux hosts. The pwm sysfs interface is not exposed by default on a Raspberry and can be activated by adding a line to /boot/config.txt : # Enable pwmchip sysfs interface dtoverlay=pwm,pin=12,func=4 This example enables only PWM0 and routes it to gpio12. If both PWM channels need to be enabled you can use pwm-2chan : # Enable pwmchip sysfs interface dtoverlay=pwm-2chan,pin=12,func=4,pin2=13,func2=4 This example additionally enables PWM1 and routes it to gpio13. The overlay does not expose the pwm line on sysfs on boot and needs to be exported by echo'ing the number of the pwm channel to /sys/class/pwm/pwmchip0/export . This will create device /sys/class/pwm/pwmchip0/pwm0 in the filesystem. The easiest way to do this is by adding this to /etc/rc.local before the exit 0 line: # Enable pwmchip sysfs interface echo 0 > /sys/class/pwm/pwmchip0/export When using both PWM channels, the number of the second channel needs to be echo'd as well: # Enable pwmchip sysfs interface echo 0 > /sys/class/pwm/pwmchip0/export echo 1 > /sys/class/pwm/pwmchip0/export With the sysfs in place, you can now use either the pwm channel(s) by adding the following piece of configuration to your printer.cfg : [output_pin caselight] pin: host:pwmchip0/pwm0 pwm: True hardware_pwm: True cycle_time: 0.000001 [output_pin beeper] pin: host:pwmchip0/pwm1 pwm: True hardware_pwm: True value: 0 shutdown_value: 0 cycle_time: 0.0005 This will add hardware pwm control to gpio12 and gpio13 on the Pi (because the overlay was configured to route pwm0 to pin=12 and pwm1 to pin=13). PWM0 can be routed to gpio12 and gpio18, PWM1 can be routed to gpio13 and gpio19: PWM gpio PIN Func 0 12 4 0 18 2 1 13 4 1 19 2","title":"RPi microcontroller"},{"location":"RPi_microcontroller.html#rpi-microcontroller","text":"This document describes the process of running Klipper on a RPi and use the same RPi as secondary mcu.","title":"RPi microcontroller"},{"location":"RPi_microcontroller.html#why-use-rpi-as-a-secondary-mcu","text":"Often the MCUs dedicated to controlling 3D printers have a limited and pre-configured number of exposed pins to manage the main printing functions (thermal resistors, extruders, steppers ...). Using the RPi where Klipper is installed as a secondary MCU gives the possibility to directly use the GPIOs and the buses (i2c, spi) of the RPi inside klipper without using Octoprint plugins (if used) or external programs giving the ability to control everything within the print GCODE. Warning : If your platform is a Beaglebone and you have correctly followed the installation steps, the linux mcu is already installed and configured for your system.","title":"Why use RPi as a secondary MCU?"},{"location":"RPi_microcontroller.html#install-the-rc-script","text":"If you want to use the host as a secondary MCU the klipper_mcu process must run before the klippy process. After installing Klipper, install the script. run: cd ~/klipper/ sudo cp ./scripts/klipper-mcu.service /etc/systemd/system/ sudo systemctl enable klipper-mcu.service","title":"Install the rc script"},{"location":"RPi_microcontroller.html#building-the-micro-controller-code","text":"To compile the Klipper micro-controller code, start by configuring it for the \"Linux process\": cd ~/klipper/ make menuconfig In the menu, set \"Microcontroller Architecture\" to \"Linux process,\" then save and exit. To build and install the new micro-controller code, run: sudo service klipper stop make flash sudo service klipper start If klippy.log reports a \"Permission denied\" error when attempting to connect to /tmp/klipper_host_mcu then you need to add your user to the tty group. The following command will add the \"pi\" user to the tty group: sudo usermod -a -G tty pi","title":"Building the micro-controller code"},{"location":"RPi_microcontroller.html#remaining-configuration","text":"Complete the installation by configuring Klipper secondary MCU following the instructions in RaspberryPi sample config and Multi MCU sample config .","title":"Remaining configuration"},{"location":"RPi_microcontroller.html#optional-enabling-spi","text":"Make sure the Linux SPI driver is enabled by running sudo raspi-config and enabling SPI under the \"Interfacing options\" menu.","title":"Optional: Enabling SPI"},{"location":"RPi_microcontroller.html#optional-enabling-i2c","text":"Make sure the Linux I2C driver is enabled by running sudo raspi-config and enabling I2C under the \"Interfacing options\" menu. If planning to use I2C for the MPU accelerometer, it is also required to set the baud rate to 400000 by: adding/uncommenting dtparam=i2c_arm=on,i2c_arm_baudrate=400000 in /boot/config.txt (or /boot/firmware/config.txt in some distros).","title":"Optional: Enabling I2C"},{"location":"RPi_microcontroller.html#optional-identify-the-correct-gpiochip","text":"On Raspberry Pi and on many clones the pins exposed on the GPIO belong to the first gpiochip. They can therefore be used on klipper simply by referring them with the name gpio0..n . However, there are cases in which the exposed pins belong to gpiochips other than the first. For example in the case of some OrangePi models or if a Port Expander is used. In these cases it is useful to use the commands to access the Linux GPIO character device to verify the configuration. To install the Linux GPIO character device - binary on a debian based distro like octopi run: sudo apt-get install gpiod To check available gpiochip run: gpiodetect To check the pin number and the pin availability tun: gpioinfo The chosen pin can thus be used within the configuration as gpiochip<n>/gpio<o> where n is the chip number as seen by the gpiodetect command and o is the line number seen by the gpioinfo command. Warning: only gpio marked as unused can be used. It is not possible for a line to be used by multiple processes simultaneously. For example on a RPi 3B+ where klipper use the GPIO20 for a switch: $ gpiodetect gpiochip0 [pinctrl-bcm2835] (54 lines) gpiochip1 [raspberrypi-exp-gpio] (8 lines) $ gpioinfo gpiochip0 - 54 lines: line 0: unnamed unused input active-high line 1: unnamed unused input active-high line 2: unnamed unused input active-high line 3: unnamed unused input active-high line 4: unnamed unused input active-high line 5: unnamed unused input active-high line 6: unnamed unused input active-high line 7: unnamed unused input active-high line 8: unnamed unused input active-high line 9: unnamed unused input active-high line 10: unnamed unused input active-high line 11: unnamed unused input active-high line 12: unnamed unused input active-high line 13: unnamed unused input active-high line 14: unnamed unused input active-high line 15: unnamed unused input active-high line 16: unnamed unused input active-high line 17: unnamed unused input active-high line 18: unnamed unused input active-high line 19: unnamed unused input active-high line 20: unnamed \"klipper\" output active-high [used] line 21: unnamed unused input active-high line 22: unnamed unused input active-high line 23: unnamed unused input active-high line 24: unnamed unused input active-high line 25: unnamed unused input active-high line 26: unnamed unused input active-high line 27: unnamed unused input active-high line 28: unnamed unused input active-high line 29: unnamed \"led0\" output active-high [used] line 30: unnamed unused input active-high line 31: unnamed unused input active-high line 32: unnamed unused input active-high line 33: unnamed unused input active-high line 34: unnamed unused input active-high line 35: unnamed unused input active-high line 36: unnamed unused input active-high line 37: unnamed unused input active-high line 38: unnamed unused input active-high line 39: unnamed unused input active-high line 40: unnamed unused input active-high line 41: unnamed unused input active-high line 42: unnamed unused input active-high line 43: unnamed unused input active-high line 44: unnamed unused input active-high line 45: unnamed unused input active-high line 46: unnamed unused input active-high line 47: unnamed unused input active-high line 48: unnamed unused input active-high line 49: unnamed unused input active-high line 50: unnamed unused input active-high line 51: unnamed unused input active-high line 52: unnamed unused input active-high line 53: unnamed unused input active-high gpiochip1 - 8 lines: line 0: unnamed unused input active-high line 1: unnamed unused input active-high line 2: unnamed \"led1\" output active-low [used] line 3: unnamed unused input active-high line 4: unnamed unused input active-high line 5: unnamed unused input active-high line 6: unnamed unused input active-high line 7: unnamed unused input active-high","title":"Optional: Identify the correct gpiochip"},{"location":"RPi_microcontroller.html#optional-hardware-pwm","text":"Raspberry Pi's have two PWM channels (PWM0 and PWM1) which are exposed on the header or if not, can be routed to existing gpio pins. The Linux mcu daemon uses the pwmchip sysfs interface to control hardware pwm devices on Linux hosts. The pwm sysfs interface is not exposed by default on a Raspberry and can be activated by adding a line to /boot/config.txt : # Enable pwmchip sysfs interface dtoverlay=pwm,pin=12,func=4 This example enables only PWM0 and routes it to gpio12. If both PWM channels need to be enabled you can use pwm-2chan : # Enable pwmchip sysfs interface dtoverlay=pwm-2chan,pin=12,func=4,pin2=13,func2=4 This example additionally enables PWM1 and routes it to gpio13. The overlay does not expose the pwm line on sysfs on boot and needs to be exported by echo'ing the number of the pwm channel to /sys/class/pwm/pwmchip0/export . This will create device /sys/class/pwm/pwmchip0/pwm0 in the filesystem. The easiest way to do this is by adding this to /etc/rc.local before the exit 0 line: # Enable pwmchip sysfs interface echo 0 > /sys/class/pwm/pwmchip0/export When using both PWM channels, the number of the second channel needs to be echo'd as well: # Enable pwmchip sysfs interface echo 0 > /sys/class/pwm/pwmchip0/export echo 1 > /sys/class/pwm/pwmchip0/export With the sysfs in place, you can now use either the pwm channel(s) by adding the following piece of configuration to your printer.cfg : [output_pin caselight] pin: host:pwmchip0/pwm0 pwm: True hardware_pwm: True cycle_time: 0.000001 [output_pin beeper] pin: host:pwmchip0/pwm1 pwm: True hardware_pwm: True value: 0 shutdown_value: 0 cycle_time: 0.0005 This will add hardware pwm control to gpio12 and gpio13 on the Pi (because the overlay was configured to route pwm0 to pin=12 and pwm1 to pin=13). PWM0 can be routed to gpio12 and gpio18, PWM1 can be routed to gpio13 and gpio19: PWM gpio PIN Func 0 12 4 0 18 2 1 13 4 1 19 2","title":"Optional: Hardware PWM"},{"location":"Releases.html","text":"Releases \u00b6 History of Klipper releases. Please see installation for information on installing Klipper. Klipper 0.13.0 \u00b6 Available on 20250411. Major changes in this release: New \"sweeping vibrations\" resonance testing mechanism for input shaper. Fans and GPIO pins can now be assigned a formula (via Jinja2 \"templates\"). The bed_mesh code now supports \"adaptive bed mesh\". The area probed can be adjusted for the size of the print. A new minimum_cruise_ratio kinematic parameter has been added (it replaces the previous max_accel_to_decel parameter). Several new sensors added: Support for ldc1612 \"eddy\" current sensors. This includes probing support, fast \"scan\" probing, and temperature calibration. New support for \"load cell\" measurements. Support for connecting these load cells to hx71x and ads1220 ADC sensors. Support for BMP180, BMP388, and SHT3x temperature sensors. Support for measuring temperature with ADS1x1x ADC chips. New lis3dh and icm20948 accelerometer support. Support for mt6816 and mt6826s \"hall angle\" sensors. New micro-controller improvements: New support for rp2350 micro-controllers. Existing rp2040 chips now run at 200MHz (up from 125Mhz). The micro-controller code can now define many more commands (up to 16384 from 128). Other modules added: aip31068_spi, canbus_stats, error_mcu, garbage_collection, pwm_cycle_time, pwm_tool, garbage_collection. Several bug fixes and code cleanups. Klipper 0.12.0 \u00b6 Available on 20231110. Major changes in this release: Support for COPY and MIRROR modes on IDEX printers. Several micro-controller improvements: Support for new ar100 and hc32f460 architectures. Support for stm32f7, stm32g0b0, stm32g07x, stm32g4, stm32h723, n32g45x, samc21, and samd21j18 chip variants. Improved DFU and Katapult reboot handling. Improved performance on USB to CANbus bridge mode. Improved performance on \"linux mcu\". New support for software based i2c. New hardware support for tmc2240 stepper motor drivers, lis2dw12 accelerometers, and aht10 temperature sensors. New axis_twist_compensation and temperature_combined modules added. New support for gcode arcs in XY, XZ, and YZ planes. Several bug fixes and code cleanups. Klipper 0.11.0 \u00b6 Available on 20221128. Major changes in this release: Trinamic stepper motor driver \"step on both edges\" optimization. Support for Python3. The Klipper host code will run with either Python2 or Python3. Enhanced CAN bus support. Support for CAN bus on rp2040, stm32g0, stm32h7, same51, and same54 chips. Support for \"USB to CAN bus bridge\" mode. Support for CanBoot bootloader. Support for mpu9250 and mpu6050 accelerometers. Improved error handling for max31856, max31855, max31865, and max6675 temperature sensors. It is now possible to configure LEDs to update during long running G-Code commands using LED \"template\" support. Several micro-controller improvements. New support for stm32h743, stm32h750, stm32l412, stm32g0b1, same70, same51, and same54 chips. Support for i2c reads on atsamd and stm32f0. Hardware pwm support on stm32. Linux mcu signal based event dispatch. New rp2040 support for \"make flash\", i2c, and rp2040-e5 USB errata. New modules added: angle, dac084S085, exclude_object, led, mpu9250, pca9632, smart_effector, z_thermal_adjust. New deltesian kinematics added. New dump_mcu tool added. Several bug fixes and code cleanups. Klipper 0.10.0 \u00b6 Available on 20210929. Major changes in this release: Support for \"Multi-MCU Homing\". It is now possible for a stepper motor and its endstop to be wired to separate micro-controllers. This simplifies wiring of Z probes on \"toolhead boards\". Klipper now has a Community Discord Server and a Community Discourse Server . The Klipper website now uses the \"mkdocs\" infrastructure. There is also a Klipper Translations project. Automated support for flashing firmware via sdcard on many boards. New kinematic support for \"Hybrid CoreXY\" and \"Hybrid CoreXZ\" printers. Klipper now uses rotation_distance to configure stepper motor travel distances. The main Klipper host code can now directly communicate with micro-controllers using CAN bus. New \"motion analysis\" system. Klipper's internal motion updates and sensor results can be tracked and logged for analysis. Trinamic stepper motor drivers are now continuously monitored for error conditions. Support for the rp2040 micro-controller (Raspberry Pi Pico boards). The \"make menuconfig\" system now utilizes kconfiglib. Many additional modules added: ds18b20, duplicate_pin_override, filament_motion_sensor, palette2, motion_report, pca9533, pulse_counter, save_variables, sdcard_loop, temperature_host, temperature_mcu Several bug fixes and code cleanups. Klipper 0.9.0 \u00b6 Available on 20201020. Major changes in this release: Support for \"Input Shaping\" - a mechanism to counteract printer resonance. It can reduce or eliminate \"ringing\" in prints. New \"Smooth Pressure Advance\" system. This implements \"Pressure Advance\" without introducing instantaneous velocity changes. It is also now possible to tune pressure advance using a \"Tuning Tower\" method. New \"webhooks\" API server. This provides a programmable JSON interface to Klipper. The LCD display and menu are now configurable using the Jinja2 template language. The TMC2208 stepper motor drivers can now be used in \"standalone\" mode with Klipper. Improved BL-Touch v3 support. Improved USB identification. Klipper now has its own USB identification code and micro-controllers can now report their unique serial numbers during USB identification. New kinematic support for \"Rotary Delta\" and \"CoreXZ\" printers. Micro-controller improvements: support for stm32f070, support for stm32f207, support for GPIO pins on \"Linux MCU\", stm32 \"HID bootloader\" support, Chitu bootloader support, MKS Robin bootloader support. Improved handling of Python \"garbage collection\" events. Many additional modules added: adc_scaled, adxl345, bme280, display_status, extruder_stepper, fan_generic, hall_filament_width_sensor, htu21d, homing_heaters, input_shaper, lm75, print_stats, resonance_tester, shaper_calibrate, query_adc, graph_accelerometer, graph_extruder, graph_motion, graph_shaper, graph_temp_sensor, whconsole Several bug fixes and code cleanups. Klipper 0.9.1 \u00b6 Available on 20201028. Release containing only bug fixes. Klipper 0.8.0 \u00b6 Available on 20191021. Major changes in this release: New G-Code command template support. G-Code in the config file is now evaluated with the Jinja2 template language. Improvements to Trinamic stepper drivers: New support for TMC2209 and TMC5160 drivers. Improved DUMP_TMC, SET_TMC_CURRENT, and INIT_TMC G-Code commands. Improved support for TMC UART handling with an analog mux. Improved homing, probing, and bed leveling support: New manual_probe, bed_screws, screws_tilt_adjust, skew_correction, safe_z_home modules added. Enhanced multi-sample probing with median, average, and retry logic. Improved documentation for BL-Touch, probe calibration, endstop calibration, delta calibration, sensorless homing, and endstop phase calibration. Improved homing support on a large Z axis. Many Klipper micro-controller improvements: Klipper ported to: SAM3X8C, SAM4S8C, SAMD51, STM32F042, STM32F4 New USB CDC driver implementations on SAM3X, SAM4, STM32F4. Enhanced support for flashing Klipper over USB. Software SPI support. Greatly improved temperature filtering on the LPC176x. Early output pin settings can be configured in the micro-controller. New website with the Klipper documentation: http://klipper3d.org/ Klipper now has a logo. Experimental support for polar and \"cable winch\" kinematics. The config file can now include other config files. Many additional modules added: board_pins, controller_fan, delayed_gcode, dotstar, filament_switch_sensor, firmware_retraction, gcode_arcs, gcode_button, heater_generic, manual_stepper, mcp4018, mcp4728, neopixel, pause_resume, respond, temperature_sensor tsl1401cl_filament_width_sensor, tuning_tower Many additional commands added: RESTORE_GCODE_STATE, SAVE_GCODE_STATE, SET_GCODE_VARIABLE, SET_HEATER_TEMPERATURE, SET_IDLE_TIMEOUT, SET_TEMPERATURE_FAN_TARGET Several bug fixes and code cleanups. Klipper 0.7.0 \u00b6 Available on 20181220. Major changes in this release: Klipper now supports \"mesh\" bed leveling New support for \"enhanced\" delta calibration (calibrates print x/y dimensions on delta printers) Support for run-time configuration of Trinamic stepper motor drivers (tmc2130, tmc2208, tmc2660) Improved temperature sensor support: MAX6675, MAX31855, MAX31856, MAX31865, custom thermistors, common pt100 style sensors Several new modules: temperature_fan, sx1509, force_move, mcp4451, z_tilt, quad_gantry_level, endstop_phase, bltouch Several new commands added: SAVE_CONFIG, SET_PRESSURE_ADVANCE, SET_GCODE_OFFSET, SET_VELOCITY_LIMIT, STEPPER_BUZZ, TURN_OFF_HEATERS, M204, custom g-code macros Expanded LCD display support: Support for run-time menus New display icons Support for \"uc1701\" and \"ssd1306\" displays Additional micro-controller support: Klipper ported to: LPC176x (Smoothieboards), SAM4E8E (Duet2), SAMD21 (Arduino Zero), STM32F103 (\"Blue pill\" devices), atmega32u4 New Generic USB CDC driver implemented on AVR, LPC176x, SAMD21, and STM32F103 Performance improvements on ARM processors The kinematics code was rewritten to use an \"iterative solver\" New automatic test cases for the Klipper host software Many new example config files for common off-the-shelf printers Documentation updates for bootloaders, benchmarking, micro-controller porting, config checks, pin mapping, slicer settings, packaging, and more Several bug fixes and code cleanups Klipper 0.6.0 \u00b6 Available on 20180331. Major changes in this release: Enhanced heater and thermistor hardware failure checks Support for Z probes Initial support for automatic parameter calibration on deltas (via a new delta_calibrate command) Initial support for bed tilt compensation (via bed_tilt_calibrate command) Initial support for \"safe homing\" and homing overrides Initial support for displaying status on RepRapDiscount style 2004 and 12864 displays New multi-extruder improvements: Support for shared heaters Initial support for dual carriages Support for configuring multiple steppers per axis (eg, dual Z) Support for custom digital and pwm output pins (with a new SET_PIN command) Initial support for a \"virtual sdcard\" that allows printing directly from Klipper (helps on machines too slow to run OctoPrint well) Support for setting different arm lengths on each tower of a delta Support for G-Code M220/M221 commands (speed factor override / extrude factor override) Several documentation updates: Many new example config files for common off-the-shelf printers New multiple MCU config example New bltouch sensor config example New FAQ, config check, and G-Code documents Initial support for continuous integration testing on all github commits Several bug fixes and code cleanups Klipper 0.5.0 \u00b6 Available on 20171025. Major changes in this release: Support for printers with multiple extruders. Initial support for running on the Beaglebone PRU. Initial support for the Replicape board. Initial support for running the micro-controller code in a real-time Linux process. Support for multiple micro-controllers. (For example, one could control an extruder with one micro-controller and the rest of the printer with another.) Software clock synchronization is implemented to coordinate actions between micro-controllers. Stepper performance improvements (20Mhz AVRs up to 189K steps per second). Support for controlling servos and support for defining nozzle cooling fans. Several bug fixes and code cleanups Klipper 0.4.0 \u00b6 Available on 20170503. Major changes in this release: Improved installation on Raspberry Pi machines. Most of the install is now scripted. Support for corexy kinematics Documentation updates: New Kinematics document, new Pressure Advance tuning guide, new example config files, and more Stepper performance improvements (20Mhz AVRs over 175K steps per second, Arduino Due over 460K) Support for automatic micro-controller resets. Support for resets via toggling USB power on Raspberry Pi. The pressure advance algorithm now works with look-ahead to reduce pressure changes during cornering. Support for limiting the top speed of short zigzag moves Support for AD595 sensors Several bug fixes and code cleanups Klipper 0.3.0 \u00b6 Available on 20161223. Major changes in this release: Improved documentation Support for robots with delta kinematics Support for Arduino Due micro-controller (ARM cortex-M3) Support for USB based AVR micro-controllers Support for \"pressure advance\" algorithm - it reduces ooze during prints. New \"stepper phased based endstop\" feature - enables higher precision on endstop homing. Support for \"extended g-code\" commands such as \"help\", \"restart\", and \"status\". Support for reloading the Klipper config and restarting the host software by issuing a \"restart\" command from the terminal. Stepper performance improvements (20Mhz AVRs up to 158K steps per second). Improved error reporting. Most errors now shown via the terminal along with help on how to resolve. Several bug fixes and code cleanups Klipper 0.2.0 \u00b6 Initial release of Klipper. Available on 20160525. Major features available in the initial release include: Basic support for cartesian printers (steppers, extruder, heated bed, cooling fan). Support for common g-code commands. Support for interfacing with OctoPrint. Acceleration and lookahead handling Support for AVR micro-controllers via standard serial ports","title":"Releases"},{"location":"Releases.html#releases","text":"History of Klipper releases. Please see installation for information on installing Klipper.","title":"Releases"},{"location":"Releases.html#klipper-0130","text":"Available on 20250411. Major changes in this release: New \"sweeping vibrations\" resonance testing mechanism for input shaper. Fans and GPIO pins can now be assigned a formula (via Jinja2 \"templates\"). The bed_mesh code now supports \"adaptive bed mesh\". The area probed can be adjusted for the size of the print. A new minimum_cruise_ratio kinematic parameter has been added (it replaces the previous max_accel_to_decel parameter). Several new sensors added: Support for ldc1612 \"eddy\" current sensors. This includes probing support, fast \"scan\" probing, and temperature calibration. New support for \"load cell\" measurements. Support for connecting these load cells to hx71x and ads1220 ADC sensors. Support for BMP180, BMP388, and SHT3x temperature sensors. Support for measuring temperature with ADS1x1x ADC chips. New lis3dh and icm20948 accelerometer support. Support for mt6816 and mt6826s \"hall angle\" sensors. New micro-controller improvements: New support for rp2350 micro-controllers. Existing rp2040 chips now run at 200MHz (up from 125Mhz). The micro-controller code can now define many more commands (up to 16384 from 128). Other modules added: aip31068_spi, canbus_stats, error_mcu, garbage_collection, pwm_cycle_time, pwm_tool, garbage_collection. Several bug fixes and code cleanups.","title":"Klipper 0.13.0"},{"location":"Releases.html#klipper-0120","text":"Available on 20231110. Major changes in this release: Support for COPY and MIRROR modes on IDEX printers. Several micro-controller improvements: Support for new ar100 and hc32f460 architectures. Support for stm32f7, stm32g0b0, stm32g07x, stm32g4, stm32h723, n32g45x, samc21, and samd21j18 chip variants. Improved DFU and Katapult reboot handling. Improved performance on USB to CANbus bridge mode. Improved performance on \"linux mcu\". New support for software based i2c. New hardware support for tmc2240 stepper motor drivers, lis2dw12 accelerometers, and aht10 temperature sensors. New axis_twist_compensation and temperature_combined modules added. New support for gcode arcs in XY, XZ, and YZ planes. Several bug fixes and code cleanups.","title":"Klipper 0.12.0"},{"location":"Releases.html#klipper-0110","text":"Available on 20221128. Major changes in this release: Trinamic stepper motor driver \"step on both edges\" optimization. Support for Python3. The Klipper host code will run with either Python2 or Python3. Enhanced CAN bus support. Support for CAN bus on rp2040, stm32g0, stm32h7, same51, and same54 chips. Support for \"USB to CAN bus bridge\" mode. Support for CanBoot bootloader. Support for mpu9250 and mpu6050 accelerometers. Improved error handling for max31856, max31855, max31865, and max6675 temperature sensors. It is now possible to configure LEDs to update during long running G-Code commands using LED \"template\" support. Several micro-controller improvements. New support for stm32h743, stm32h750, stm32l412, stm32g0b1, same70, same51, and same54 chips. Support for i2c reads on atsamd and stm32f0. Hardware pwm support on stm32. Linux mcu signal based event dispatch. New rp2040 support for \"make flash\", i2c, and rp2040-e5 USB errata. New modules added: angle, dac084S085, exclude_object, led, mpu9250, pca9632, smart_effector, z_thermal_adjust. New deltesian kinematics added. New dump_mcu tool added. Several bug fixes and code cleanups.","title":"Klipper 0.11.0"},{"location":"Releases.html#klipper-0100","text":"Available on 20210929. Major changes in this release: Support for \"Multi-MCU Homing\". It is now possible for a stepper motor and its endstop to be wired to separate micro-controllers. This simplifies wiring of Z probes on \"toolhead boards\". Klipper now has a Community Discord Server and a Community Discourse Server . The Klipper website now uses the \"mkdocs\" infrastructure. There is also a Klipper Translations project. Automated support for flashing firmware via sdcard on many boards. New kinematic support for \"Hybrid CoreXY\" and \"Hybrid CoreXZ\" printers. Klipper now uses rotation_distance to configure stepper motor travel distances. The main Klipper host code can now directly communicate with micro-controllers using CAN bus. New \"motion analysis\" system. Klipper's internal motion updates and sensor results can be tracked and logged for analysis. Trinamic stepper motor drivers are now continuously monitored for error conditions. Support for the rp2040 micro-controller (Raspberry Pi Pico boards). The \"make menuconfig\" system now utilizes kconfiglib. Many additional modules added: ds18b20, duplicate_pin_override, filament_motion_sensor, palette2, motion_report, pca9533, pulse_counter, save_variables, sdcard_loop, temperature_host, temperature_mcu Several bug fixes and code cleanups.","title":"Klipper 0.10.0"},{"location":"Releases.html#klipper-090","text":"Available on 20201020. Major changes in this release: Support for \"Input Shaping\" - a mechanism to counteract printer resonance. It can reduce or eliminate \"ringing\" in prints. New \"Smooth Pressure Advance\" system. This implements \"Pressure Advance\" without introducing instantaneous velocity changes. It is also now possible to tune pressure advance using a \"Tuning Tower\" method. New \"webhooks\" API server. This provides a programmable JSON interface to Klipper. The LCD display and menu are now configurable using the Jinja2 template language. The TMC2208 stepper motor drivers can now be used in \"standalone\" mode with Klipper. Improved BL-Touch v3 support. Improved USB identification. Klipper now has its own USB identification code and micro-controllers can now report their unique serial numbers during USB identification. New kinematic support for \"Rotary Delta\" and \"CoreXZ\" printers. Micro-controller improvements: support for stm32f070, support for stm32f207, support for GPIO pins on \"Linux MCU\", stm32 \"HID bootloader\" support, Chitu bootloader support, MKS Robin bootloader support. Improved handling of Python \"garbage collection\" events. Many additional modules added: adc_scaled, adxl345, bme280, display_status, extruder_stepper, fan_generic, hall_filament_width_sensor, htu21d, homing_heaters, input_shaper, lm75, print_stats, resonance_tester, shaper_calibrate, query_adc, graph_accelerometer, graph_extruder, graph_motion, graph_shaper, graph_temp_sensor, whconsole Several bug fixes and code cleanups.","title":"Klipper 0.9.0"},{"location":"Releases.html#klipper-091","text":"Available on 20201028. Release containing only bug fixes.","title":"Klipper 0.9.1"},{"location":"Releases.html#klipper-080","text":"Available on 20191021. Major changes in this release: New G-Code command template support. G-Code in the config file is now evaluated with the Jinja2 template language. Improvements to Trinamic stepper drivers: New support for TMC2209 and TMC5160 drivers. Improved DUMP_TMC, SET_TMC_CURRENT, and INIT_TMC G-Code commands. Improved support for TMC UART handling with an analog mux. Improved homing, probing, and bed leveling support: New manual_probe, bed_screws, screws_tilt_adjust, skew_correction, safe_z_home modules added. Enhanced multi-sample probing with median, average, and retry logic. Improved documentation for BL-Touch, probe calibration, endstop calibration, delta calibration, sensorless homing, and endstop phase calibration. Improved homing support on a large Z axis. Many Klipper micro-controller improvements: Klipper ported to: SAM3X8C, SAM4S8C, SAMD51, STM32F042, STM32F4 New USB CDC driver implementations on SAM3X, SAM4, STM32F4. Enhanced support for flashing Klipper over USB. Software SPI support. Greatly improved temperature filtering on the LPC176x. Early output pin settings can be configured in the micro-controller. New website with the Klipper documentation: http://klipper3d.org/ Klipper now has a logo. Experimental support for polar and \"cable winch\" kinematics. The config file can now include other config files. Many additional modules added: board_pins, controller_fan, delayed_gcode, dotstar, filament_switch_sensor, firmware_retraction, gcode_arcs, gcode_button, heater_generic, manual_stepper, mcp4018, mcp4728, neopixel, pause_resume, respond, temperature_sensor tsl1401cl_filament_width_sensor, tuning_tower Many additional commands added: RESTORE_GCODE_STATE, SAVE_GCODE_STATE, SET_GCODE_VARIABLE, SET_HEATER_TEMPERATURE, SET_IDLE_TIMEOUT, SET_TEMPERATURE_FAN_TARGET Several bug fixes and code cleanups.","title":"Klipper 0.8.0"},{"location":"Releases.html#klipper-070","text":"Available on 20181220. Major changes in this release: Klipper now supports \"mesh\" bed leveling New support for \"enhanced\" delta calibration (calibrates print x/y dimensions on delta printers) Support for run-time configuration of Trinamic stepper motor drivers (tmc2130, tmc2208, tmc2660) Improved temperature sensor support: MAX6675, MAX31855, MAX31856, MAX31865, custom thermistors, common pt100 style sensors Several new modules: temperature_fan, sx1509, force_move, mcp4451, z_tilt, quad_gantry_level, endstop_phase, bltouch Several new commands added: SAVE_CONFIG, SET_PRESSURE_ADVANCE, SET_GCODE_OFFSET, SET_VELOCITY_LIMIT, STEPPER_BUZZ, TURN_OFF_HEATERS, M204, custom g-code macros Expanded LCD display support: Support for run-time menus New display icons Support for \"uc1701\" and \"ssd1306\" displays Additional micro-controller support: Klipper ported to: LPC176x (Smoothieboards), SAM4E8E (Duet2), SAMD21 (Arduino Zero), STM32F103 (\"Blue pill\" devices), atmega32u4 New Generic USB CDC driver implemented on AVR, LPC176x, SAMD21, and STM32F103 Performance improvements on ARM processors The kinematics code was rewritten to use an \"iterative solver\" New automatic test cases for the Klipper host software Many new example config files for common off-the-shelf printers Documentation updates for bootloaders, benchmarking, micro-controller porting, config checks, pin mapping, slicer settings, packaging, and more Several bug fixes and code cleanups","title":"Klipper 0.7.0"},{"location":"Releases.html#klipper-060","text":"Available on 20180331. Major changes in this release: Enhanced heater and thermistor hardware failure checks Support for Z probes Initial support for automatic parameter calibration on deltas (via a new delta_calibrate command) Initial support for bed tilt compensation (via bed_tilt_calibrate command) Initial support for \"safe homing\" and homing overrides Initial support for displaying status on RepRapDiscount style 2004 and 12864 displays New multi-extruder improvements: Support for shared heaters Initial support for dual carriages Support for configuring multiple steppers per axis (eg, dual Z) Support for custom digital and pwm output pins (with a new SET_PIN command) Initial support for a \"virtual sdcard\" that allows printing directly from Klipper (helps on machines too slow to run OctoPrint well) Support for setting different arm lengths on each tower of a delta Support for G-Code M220/M221 commands (speed factor override / extrude factor override) Several documentation updates: Many new example config files for common off-the-shelf printers New multiple MCU config example New bltouch sensor config example New FAQ, config check, and G-Code documents Initial support for continuous integration testing on all github commits Several bug fixes and code cleanups","title":"Klipper 0.6.0"},{"location":"Releases.html#klipper-050","text":"Available on 20171025. Major changes in this release: Support for printers with multiple extruders. Initial support for running on the Beaglebone PRU. Initial support for the Replicape board. Initial support for running the micro-controller code in a real-time Linux process. Support for multiple micro-controllers. (For example, one could control an extruder with one micro-controller and the rest of the printer with another.) Software clock synchronization is implemented to coordinate actions between micro-controllers. Stepper performance improvements (20Mhz AVRs up to 189K steps per second). Support for controlling servos and support for defining nozzle cooling fans. Several bug fixes and code cleanups","title":"Klipper 0.5.0"},{"location":"Releases.html#klipper-040","text":"Available on 20170503. Major changes in this release: Improved installation on Raspberry Pi machines. Most of the install is now scripted. Support for corexy kinematics Documentation updates: New Kinematics document, new Pressure Advance tuning guide, new example config files, and more Stepper performance improvements (20Mhz AVRs over 175K steps per second, Arduino Due over 460K) Support for automatic micro-controller resets. Support for resets via toggling USB power on Raspberry Pi. The pressure advance algorithm now works with look-ahead to reduce pressure changes during cornering. Support for limiting the top speed of short zigzag moves Support for AD595 sensors Several bug fixes and code cleanups","title":"Klipper 0.4.0"},{"location":"Releases.html#klipper-030","text":"Available on 20161223. Major changes in this release: Improved documentation Support for robots with delta kinematics Support for Arduino Due micro-controller (ARM cortex-M3) Support for USB based AVR micro-controllers Support for \"pressure advance\" algorithm - it reduces ooze during prints. New \"stepper phased based endstop\" feature - enables higher precision on endstop homing. Support for \"extended g-code\" commands such as \"help\", \"restart\", and \"status\". Support for reloading the Klipper config and restarting the host software by issuing a \"restart\" command from the terminal. Stepper performance improvements (20Mhz AVRs up to 158K steps per second). Improved error reporting. Most errors now shown via the terminal along with help on how to resolve. Several bug fixes and code cleanups","title":"Klipper 0.3.0"},{"location":"Releases.html#klipper-020","text":"Initial release of Klipper. Available on 20160525. Major features available in the initial release include: Basic support for cartesian printers (steppers, extruder, heated bed, cooling fan). Support for common g-code commands. Support for interfacing with OctoPrint. Acceleration and lookahead handling Support for AVR micro-controllers via standard serial ports","title":"Klipper 0.2.0"},{"location":"Resonance_Compensation.html","text":"Resonance Compensation \u00b6 Klipper supports Input Shaping - a technique that can be used to reduce ringing (also known as echoing, ghosting or rippling) in prints. Ringing is a surface printing defect when, typically, elements like edges repeat themselves on a printed surface as a subtle 'echo': | | | Ringing is caused by mechanical vibrations in the printer due to quick changes of the printing direction. Note that ringing usually has mechanical origins: insufficiently rigid printer frame, non-tight or too springy belts, alignment issues of mechanical parts, heavy moving mass, etc. Those should be checked and fixed first, if possible. Input shaping is an open-loop control technique which creates a commanding signal that cancels its own vibrations. Input shaping requires some tuning and measurements before it can be enabled. Besides ringing, Input Shaping typically reduces the vibrations and shaking of the printer in general, and may also improve the reliability of the stealthChop mode of Trinamic stepper drivers. Tuning \u00b6 Basic tuning requires measuring the ringing frequencies of the printer by printing a test model. Slice the ringing test model, which can be found in docs/prints/ringing_tower.stl , in the slicer: Suggested layer height is 0.2 or 0.25 mm. Infill and top layers can be set to 0. Use 1-2 perimeters, or even better the smooth vase mode with 1-2 mm base. Use sufficiently high speed, around 80-100 mm/sec, for external perimeters. Make sure that the minimum layer time is at most 3 seconds. Make sure any \"dynamic acceleration control\" is disabled in the slicer. Do not turn the model. The model has X and Y marks at the back of the model. Note the unusual location of the marks vs. the axes of the printer - it is not a mistake. The marks can be used later in the tuning process as a reference, because they show which axis the measurements correspond to. Ringing frequency \u00b6 First, measure the ringing frequency . If square_corner_velocity parameter was changed, revert it back to 5.0. It is not advised to increase it when using input shaper because it can cause more smoothing in parts - it is better to use higher acceleration value instead. Disable the minimum_cruise_ratio feature by issuing the following command: SET_VELOCITY_LIMIT MINIMUM_CRUISE_RATIO=0 Disable Pressure Advance: SET_PRESSURE_ADVANCE ADVANCE=0 If you have already added [input_shaper] section to the printer.cfg, execute SET_INPUT_SHAPER SHAPER_FREQ_X=0 SHAPER_FREQ_Y=0 command. If you get \"Unknown command\" error, you can safely ignore it at this point and continue with the measurements. Execute the command: TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5 Basically, we try to make ringing more pronounced by setting different large values for acceleration. This command will increase the acceleration every 5 mm starting from 1500 mm/sec^2: 1500 mm/sec^2, 2000 mm/sec^2, 2500 mm/sec^2 and so forth up until 7000 mm/sec^2 at the last band. Print the test model sliced with the suggested parameters. You can stop the print earlier if the ringing is clearly visible and you see that acceleration gets too high for your printer (e.g. printer shakes too much or starts skipping steps). Use X and Y marks at the back of the model for reference. The measurements from the side with X mark should be used for X axis configuration , and Y mark - for Y axis configuration. Measure the distance D (in mm) between several oscillations on the part with X mark, near the notches, preferably skipping the first oscillation or two. To measure the distance between oscillations more easily, mark the oscillations first, then measure the distance between the marks with a ruler or calipers: | | | Count how many oscillations N the measured distance D corresponds to. If you are unsure how to count the oscillations, refer to the picture above, which shows N = 6 oscillations. Compute the ringing frequency of X axis as V \u00b7 N / D (Hz), where V is the velocity for outer perimeters (mm/sec). For the example above, we marked 6 oscillations, and the test was printed at 100 mm/sec velocity, so the frequency is 100 * 6 / 12.14 \u2248 49.4 Hz. Do (8) - (10) for Y mark as well. Note that ringing on the test print should follow the pattern of the curved notches, as in the picture above. If it doesn't, then this defect is not really a ringing and has a different origin - either mechanical, or an extruder issue. It should be fixed first before enabling and tuning input shapers. If the measurements are not reliable because, say, the distance between the oscillations is not stable, it might mean that the printer has several resonance frequencies on the same axis. One may try to follow the tuning process described in Unreliable measurements of ringing frequencies section instead and still get something out of the input shaping technique. Ringing frequency can depend on the position of the model within the buildplate and Z height, especially on delta printers ; you can check if you see the differences in frequencies at different positions along the sides of the test model and at different heights. You can calculate the average ringing frequencies over X and Y axes if that is the case. If the measured ringing frequency is very low (below approx 20-25 Hz), it might be a good idea to invest into stiffening the printer or decreasing the moving mass - depending on what is applicable in your case - before proceeding with further input shaping tuning, and re-measuring the frequencies afterwards. For many popular printer models there are often some solutions available already. Note that the ringing frequencies can change if the changes are made to the printer that affect the moving mass or change the stiffness of the system, for example: Some tools are installed, removed or replaced on the toolhead that change its mass, e.g. a new (heavier or lighter) stepper motor for direct extruder or a new hotend is installed, heavy fan with a duct is added, etc. Belts are tightened. Some addons to increase frame rigidity are installed. Different bed is installed on a bed-slinger printer, or glass added, etc. If such changes are made, it is a good idea to at least measure the ringing frequencies to see if they have changed. Input shaper configuration \u00b6 After the ringing frequencies for X and Y axes are measured, you can add the following section to your printer.cfg : [input_shaper] shaper_freq_x: ... # frequency for the X mark of the test model shaper_freq_y: ... # frequency for the Y mark of the test model For the example above, we get shaper_freq_x/y = 49.4. Choosing input shaper \u00b6 Klipper supports several input shapers. They differ in their sensitivity to errors determining the resonance frequency and how much smoothing they cause in the printed parts. Also, some of the shapers like 2HUMP_EI and 3HUMP_EI should usually not be used with shaper_freq = resonance frequency - they are configured from different considerations to reduce several resonances at once. For most of the printers, either MZV or EI shapers can be recommended. This section describes a testing process to choose between them, and figure out a few other related parameters. Print the ringing test model as follows: Restart the firmware: RESTART Prepare for test: SET_VELOCITY_LIMIT MINIMUM_CRUISE_RATIO=0 Disable Pressure Advance: SET_PRESSURE_ADVANCE ADVANCE=0 Execute: SET_INPUT_SHAPER SHAPER_TYPE=MZV Execute the command: TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5 Print the test model sliced with the suggested parameters. If you see no ringing at this point, then MZV shaper can be recommended for use. If you do see some ringing, re-measure the frequencies using steps (8)-(10) described in Ringing frequency section. If the frequencies differ significantly from the values you obtained earlier, a more complex input shaper configuration is needed. You can refer to Technical details of Input shapers section. Otherwise, proceed to the next step. Now try EI input shaper. To try it, repeat steps (1)-(6) from above, but executing at step 4 the following command instead: SET_INPUT_SHAPER SHAPER_TYPE=EI . Compare two prints with MZV and EI input shaper. If EI shows noticeably better results than MZV, use EI shaper, otherwise prefer MZV. Note that EI shaper will cause more smoothing in printed parts (see the next section for further details). Add shaper_type: mzv (or ei) parameter to [input_shaper] section, e.g.: [input_shaper] shaper_freq_x: ... shaper_freq_y: ... shaper_type: mzv A few notes on shaper selection: EI shaper may be more suited for bed slinger printers (if the resonance frequency and resulting smoothing allows): as more filament is deposited on the moving bed, the mass of the bed increases and the resonance frequency will decrease. Since EI shaper is more robust to resonance frequency changes, it may work better when printing large parts. Due to the nature of delta kinematics, resonance frequencies can differ a lot in different parts of the build volume. Therefore, EI shaper can be a better fit for delta printers rather than MZV or ZV, and should be considered for the use. If the resonance frequency is sufficiently large (more than 50-60 Hz), then one can even attempt to test 2HUMP_EI shaper (by running the suggested test above with SET_INPUT_SHAPER SHAPER_TYPE=2HUMP_EI ), but check the considerations in the section below before enabling it. Selecting max_accel \u00b6 You should have a printed test for the shaper you chose from the previous step (if you don't, print the test model sliced with the suggested parameters with the pressure advance disabled SET_PRESSURE_ADVANCE ADVANCE=0 and with the tuning tower enabled as TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5 ). Note that at very high accelerations, depending on the resonance frequency and the input shaper you chose (e.g. EI shaper creates more smoothing than MZV), input shaping may cause too much smoothing and rounding of the parts. So, max_accel should be chosen such as to prevent that. Another parameter that can impact smoothing is square_corner_velocity , so it is not advisable to increase it above the default 5 mm/sec to prevent increased smoothing. In order to select a suitable max_accel value, inspect the model for the chosen input shaper. First, take a note at which acceleration ringing is still small - that you are comfortable with it. Next, check the smoothing. To help with that, the test model has a small gap in the wall (0.15 mm): As the acceleration increases, so does the smoothing, and the actual gap in the print widens: In this picture, the acceleration increases left to right, and the gap starts to grow starting from 3500 mm/sec^2 (5-th band from the left). So the good value for max_accel = 3000 (mm/sec^2) in this case to avoid the excessive smoothing. Note the acceleration when the gap is still very small in your test print. If you see bulges, but no gap in the wall at all, even at high accelerations, it may be due to disabled Pressure Advance, especially on Bowden extruders. If that is the case, you may need to repeat the print with the PA enabled. It may also be a result of a miscalibrated (too high) filament flow, so it is a good idea to check that too. Choose the minimum out of the two acceleration values (from ringing and smoothing), and put it as max_accel into printer.cfg. As a note, it may happen - especially at low ringing frequencies - that EI shaper will cause too much smoothing even at lower accelerations. In this case, MZV may be a better choice, because it may allow higher acceleration values. At very low ringing frequencies (~25 Hz and below) even MZV shaper may create too much smoothing. If that is the case, you can also try to repeat the steps in Choosing input shaper section with ZV shaper, by using SET_INPUT_SHAPER SHAPER_TYPE=ZV command instead. ZV shaper should show even less smoothing than MZV, but is more sensitive to errors in measuring the ringing frequencies. Another consideration is that if a resonance frequency is too low (below 20-25 Hz), it might be a good idea to increase the printer stiffness or reduce the moving mass. Otherwise, acceleration and printing speed may be limited due too much smoothing now instead of ringing. Fine-tuning resonance frequencies \u00b6 Note that the precision of the resonance frequencies measurements using the ringing test model is sufficient for most purposes, so further tuning is not advised. If you still want to try to double-check your results (e.g. if you still see some ringing after printing a test model with an input shaper of your choice with the same frequencies as you have measured earlier), you can follow the steps in this section. Note that if you see ringing at different frequencies after enabling [input_shaper], this section will not help with that. Assuming that you have sliced the ringing model with suggested parameters, complete the following steps for each of the axes X and Y: Prepare for test: SET_VELOCITY_LIMIT MINIMUM_CRUISE_RATIO=0 Make sure Pressure Advance is disabled: SET_PRESSURE_ADVANCE ADVANCE=0 Execute: SET_INPUT_SHAPER SHAPER_TYPE=ZV From the existing ringing test model with your chosen input shaper select the acceleration that shows ringing sufficiently well, and set it with: SET_VELOCITY_LIMIT ACCEL=... Calculate the necessary parameters for the TUNING_TOWER command to tune shaper_freq_x parameter as follows: start = shaper_freq_x * 83 / 132 and factor = shaper_freq_x / 66, where shaper_freq_x here is the current value in printer.cfg . Execute the command: TUNING_TOWER COMMAND=SET_INPUT_SHAPER PARAMETER=SHAPER_FREQ_X START=start FACTOR=factor BAND=5 using start and factor values calculated at step (5). Print the test model. Reset the original frequency value: SET_INPUT_SHAPER SHAPER_FREQ_X=... . Find the band which shows ringing the least and count its number from the bottom starting at 1. Calculate the new shaper_freq_x value via old shaper_freq_x * (39 + 5 * #band-number) / 66. Repeat these steps for the Y axis in the same manner, replacing references to X axis with the axis Y (e.g. replace shaper_freq_x with shaper_freq_y in the formulae and in the TUNING_TOWER command). As an example, let's assume you have had measured the ringing frequency for one of the axis equal to 45 Hz. This gives start = 45 * 83 / 132 = 28.30 and factor = 45 / 66 = 0.6818 values for TUNING_TOWER command. Now let's assume that after printing the test model, the fourth band from the bottom gives the least ringing. This gives the updated shaper_freq_? value equal to 45 * (39 + 5 * 4) / 66 \u2248 40.23. After both new shaper_freq_x and shaper_freq_y parameters have been calculated, you can update [input_shaper] section in printer.cfg with the new shaper_freq_x and shaper_freq_y values. Pressure Advance \u00b6 If you use Pressure Advance, it may need to be re-tuned. Follow the instructions to find the new value, if it differs from the previous one. Make sure to restart Klipper before tuning Pressure Advance. Unreliable measurements of ringing frequencies \u00b6 If you are unable to measure the ringing frequencies, e.g. if the distance between the oscillations is not stable, you may still be able to take advantage of input shaping techniques, but the results may not be as good as with proper measurements of the frequencies, and will require a bit more tuning and printing the test model. Note that another possibility is to purchase and install an accelerometer and measure the resonances with it (refer to the docs describing the required hardware and the setup process) - but this option requires some crimping and soldering. For tuning, add empty [input_shaper] section to your printer.cfg . Then, assuming that you have sliced the ringing model with suggested parameters, print the test model 3 times as follows. First time, prior to printing, run RESTART SET_VELOCITY_LIMIT MINIMUM_CRUISE_RATIO=0 SET_PRESSURE_ADVANCE ADVANCE=0 SET_INPUT_SHAPER SHAPER_TYPE=2HUMP_EI SHAPER_FREQ_X=60 SHAPER_FREQ_Y=60 TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5 and print the model. Then print the model again, but before printing run instead SET_INPUT_SHAPER SHAPER_TYPE=2HUMP_EI SHAPER_FREQ_X=50 SHAPER_FREQ_Y=50 TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5 Then print the model for the 3rd time, but now run SET_INPUT_SHAPER SHAPER_TYPE=2HUMP_EI SHAPER_FREQ_X=40 SHAPER_FREQ_Y=40 TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5 Essentially, we are printing the ringing test model with TUNING_TOWER using 2HUMP_EI shaper with shaper_freq = 60 Hz, 50 Hz, and 40 Hz. If none of the models demonstrate improvements in ringing, then, unfortunately, it does not look like the input shaping techniques can help with your case. Otherwise, it may be that all models show no ringing, or some show the ringing and some - not so much. Choose the test model with the highest frequency that still shows good improvements in ringing. For example, if 40 Hz and 50 Hz models show almost no ringing, and 60 Hz model already shows some more ringing, stick with 50 Hz. Now check if EI shaper would be good enough in your case. Choose EI shaper frequency based on the frequency of 2HUMP_EI shaper you chose: For 2HUMP_EI 60 Hz shaper, use EI shaper with shaper_freq = 50 Hz. For 2HUMP_EI 50 Hz shaper, use EI shaper with shaper_freq = 40 Hz. For 2HUMP_EI 40 Hz shaper, use EI shaper with shaper_freq = 33 Hz. Now print the test model one more time, running SET_INPUT_SHAPER SHAPER_TYPE=EI SHAPER_FREQ_X=... SHAPER_FREQ_Y=... TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5 providing the shaper_freq_x=... and shaper_freq_y=... as determined previously. If EI shaper shows very comparable good results as 2HUMP_EI shaper, stick with EI shaper and the frequency determined earlier, otherwise use 2HUMP_EI shaper with the corresponding frequency. Add the results to printer.cfg as, e.g. [input_shaper] shaper_freq_x: 50 shaper_freq_y: 50 shaper_type: 2hump_ei Continue the tuning with Selecting max_accel section. Troubleshooting and FAQ \u00b6 I cannot get reliable measurements of resonance frequencies \u00b6 First, make sure it is not some other problem with the printer instead of ringing. If the measurements are not reliable because, say, the distance between the oscillations is not stable, it might mean that the printer has several resonance frequencies on the same axis. One may try to follow the tuning process described in Unreliable measurements of ringing frequencies section and still get something out of the input shaping technique. Another possibility is to install an accelerometer, measure the resonances with it, and auto-tune the input shaper using the results of those measurements. After enabling [input_shaper], I get too smoothed printed parts and fine details are lost \u00b6 Check the considerations in Selecting max_accel section. If the resonance frequency is low, one should not set too high max_accel or increase square_corner_velocity parameters. It might also be better to choose MZV or even ZV input shapers over EI (or 2HUMP_EI and 3HUMP_EI shapers). After successfully printing for some time without ringing, it appears to come back \u00b6 It is possible that after some time the resonance frequencies have changed. E.g. maybe the belts tension has changed (belts got more loose), etc. It is a good idea to check and re-measure the ringing frequencies as described in Ringing frequency section and update your config file if necessary. Is dual carriage setup supported with input shapers? \u00b6 Yes. In this case, one should measure the resonances twice for each carriage. For example, if the second (dual) carriage is installed on X axis, it is possible to set different input shapers for X axis for the primary and dual carriages. However, the input shaper for Y axis should be the same for both carriages (as ultimately this axis is driven by one or more stepper motors each commanded to perform exactly the same steps). One possibility to configure the input shaper for such setups is to keep [input_shaper] section empty and additionally define a [delayed_gcode] section in the printer.cfg as follows: [input_shaper] # Intentionally empty [delayed_gcode init_shaper] initial_duration: 0.1 gcode: SET_DUAL_CARRIAGE CARRIAGE=1 SET_INPUT_SHAPER SHAPER_TYPE_X=<dual_carriage_shaper> SHAPER_FREQ_X=<dual_carriage_freq> SHAPER_TYPE_Y=<y_shaper> SHAPER_FREQ_Y=<y_freq> SET_DUAL_CARRIAGE CARRIAGE=0 SET_INPUT_SHAPER SHAPER_TYPE_X=<primary_carriage_shaper> SHAPER_FREQ_X=<primary_carriage_freq> SHAPER_TYPE_Y=<y_shaper> SHAPER_FREQ_Y=<y_freq> Note that SHAPER_TYPE_Y and SHAPER_FREQ_Y should be the same in both commands. It is also possible to put a similar snippet into the start g-code in the slicer, however then the shaper will not be enabled until any print is started. Note that the input shaper only needs to be configured once. Subsequent changes of the carriages or their modes via SET_DUAL_CARRIAGE command will preserve the configured input shaper parameters. Does input_shaper affect print time? \u00b6 No, input_shaper feature has pretty much no impact on the print times by itself. However, the value of max_accel certainly does (tuning of this parameter described in this section ). Technical details \u00b6 Input shapers \u00b6 Input shapers used in Klipper are rather standard, and one can find more in-depth overview in the articles describing the corresponding shapers. This section contains a brief overview of some technical aspects of the supported input shapers. The table below shows some (usually approximate) parameters of each shaper. Input shaper Shaper duration Vibration reduction 20x (5% vibration tolerance) Vibration reduction 10x (10% vibration tolerance) ZV 0.5 / shaper_freq N/A \u00b1 5% shaper_freq MZV 0.75 / shaper_freq \u00b1 4% shaper_freq -10%...+15% shaper_freq ZVD 1 / shaper_freq \u00b1 15% shaper_freq \u00b1 22% shaper_freq EI 1 / shaper_freq \u00b1 20% shaper_freq \u00b1 25% shaper_freq 2HUMP_EI 1.5 / shaper_freq \u00b1 35% shaper_freq \u00b1 40 shaper_freq 3HUMP_EI 2 / shaper_freq -45...+50% shaper_freq -50%...+55% shaper_freq A note on vibration reduction: the values in the table above are approximate. If the damping ratio of the printer is known for each axis, the shaper can be configured more precisely and it will then reduce the resonances in a bit wider range of frequencies. However, the damping ratio is usually unknown and is hard to estimate without a special equipment, so Klipper uses 0.1 value by default, which is a good all-round value. The frequency ranges in the table cover a number of different possible damping ratios around that value (approx. from 0.05 to 0.2). Also note that EI, 2HUMP_EI, and 3HUMP_EI are tuned to reduce vibrations to 5%, so the values for 10% vibration tolerance are provided only for the reference. How to use this table: Shaper duration affects the smoothing in parts - the larger it is, the more smooth the parts are. This dependency is not linear, but can give a sense of which shapers 'smooth' more for the same frequency. The ordering by smoothing is like this: ZV < MZV < ZVD \u2248 EI < 2HUMP_EI < 3HUMP_EI. Also, it is rarely practical to set shaper_freq = resonance freq for shapers 2HUMP_EI and 3HUMP_EI (they should be used to reduce vibrations for several frequencies). One can estimate a range of frequencies in which the shaper reduces vibrations. For example, MZV with shaper_freq = 35 Hz reduces vibrations to 5% for frequencies [33.6, 36.4] Hz. 3HUMP_EI with shaper_freq = 50 Hz reduces vibrations to 5% in range [27.5, 75] Hz. One can use this table to check which shaper they should be using if they need to reduce vibrations at several frequencies. For example, if one has resonances at 35 Hz and 60 Hz on the same axis: a) EI shaper needs to have shaper_freq = 35 / (1 - 0.2) = 43.75 Hz, and it will reduce resonances until 43.75 * (1 + 0.2) = 52.5 Hz, so it is not sufficient; b) 2HUMP_EI shaper needs to have shaper_freq = 35 / (1 - 0.35) = 53.85 Hz and will reduce vibrations until 53.85 * (1 + 0.35) = 72.7 Hz - so this is an acceptable configuration. Always try to use as high shaper_freq as possible for a given shaper (perhaps with some safety margin, so in this example shaper_freq \u2248 50-52 Hz would work best), and try to use a shaper with as small shaper duration as possible. If one needs to reduce vibrations at several very different frequencies (say, 30 Hz and 100 Hz), they may see that the table above does not provide enough information. In this case one may have more luck with scripts/graph_shaper.py script, which is more flexible.","title":"Resonance Compensation"},{"location":"Resonance_Compensation.html#resonance-compensation","text":"Klipper supports Input Shaping - a technique that can be used to reduce ringing (also known as echoing, ghosting or rippling) in prints. Ringing is a surface printing defect when, typically, elements like edges repeat themselves on a printed surface as a subtle 'echo': | | | Ringing is caused by mechanical vibrations in the printer due to quick changes of the printing direction. Note that ringing usually has mechanical origins: insufficiently rigid printer frame, non-tight or too springy belts, alignment issues of mechanical parts, heavy moving mass, etc. Those should be checked and fixed first, if possible. Input shaping is an open-loop control technique which creates a commanding signal that cancels its own vibrations. Input shaping requires some tuning and measurements before it can be enabled. Besides ringing, Input Shaping typically reduces the vibrations and shaking of the printer in general, and may also improve the reliability of the stealthChop mode of Trinamic stepper drivers.","title":"Resonance Compensation"},{"location":"Resonance_Compensation.html#tuning","text":"Basic tuning requires measuring the ringing frequencies of the printer by printing a test model. Slice the ringing test model, which can be found in docs/prints/ringing_tower.stl , in the slicer: Suggested layer height is 0.2 or 0.25 mm. Infill and top layers can be set to 0. Use 1-2 perimeters, or even better the smooth vase mode with 1-2 mm base. Use sufficiently high speed, around 80-100 mm/sec, for external perimeters. Make sure that the minimum layer time is at most 3 seconds. Make sure any \"dynamic acceleration control\" is disabled in the slicer. Do not turn the model. The model has X and Y marks at the back of the model. Note the unusual location of the marks vs. the axes of the printer - it is not a mistake. The marks can be used later in the tuning process as a reference, because they show which axis the measurements correspond to.","title":"Tuning"},{"location":"Resonance_Compensation.html#ringing-frequency","text":"First, measure the ringing frequency . If square_corner_velocity parameter was changed, revert it back to 5.0. It is not advised to increase it when using input shaper because it can cause more smoothing in parts - it is better to use higher acceleration value instead. Disable the minimum_cruise_ratio feature by issuing the following command: SET_VELOCITY_LIMIT MINIMUM_CRUISE_RATIO=0 Disable Pressure Advance: SET_PRESSURE_ADVANCE ADVANCE=0 If you have already added [input_shaper] section to the printer.cfg, execute SET_INPUT_SHAPER SHAPER_FREQ_X=0 SHAPER_FREQ_Y=0 command. If you get \"Unknown command\" error, you can safely ignore it at this point and continue with the measurements. Execute the command: TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5 Basically, we try to make ringing more pronounced by setting different large values for acceleration. This command will increase the acceleration every 5 mm starting from 1500 mm/sec^2: 1500 mm/sec^2, 2000 mm/sec^2, 2500 mm/sec^2 and so forth up until 7000 mm/sec^2 at the last band. Print the test model sliced with the suggested parameters. You can stop the print earlier if the ringing is clearly visible and you see that acceleration gets too high for your printer (e.g. printer shakes too much or starts skipping steps). Use X and Y marks at the back of the model for reference. The measurements from the side with X mark should be used for X axis configuration , and Y mark - for Y axis configuration. Measure the distance D (in mm) between several oscillations on the part with X mark, near the notches, preferably skipping the first oscillation or two. To measure the distance between oscillations more easily, mark the oscillations first, then measure the distance between the marks with a ruler or calipers: | | | Count how many oscillations N the measured distance D corresponds to. If you are unsure how to count the oscillations, refer to the picture above, which shows N = 6 oscillations. Compute the ringing frequency of X axis as V \u00b7 N / D (Hz), where V is the velocity for outer perimeters (mm/sec). For the example above, we marked 6 oscillations, and the test was printed at 100 mm/sec velocity, so the frequency is 100 * 6 / 12.14 \u2248 49.4 Hz. Do (8) - (10) for Y mark as well. Note that ringing on the test print should follow the pattern of the curved notches, as in the picture above. If it doesn't, then this defect is not really a ringing and has a different origin - either mechanical, or an extruder issue. It should be fixed first before enabling and tuning input shapers. If the measurements are not reliable because, say, the distance between the oscillations is not stable, it might mean that the printer has several resonance frequencies on the same axis. One may try to follow the tuning process described in Unreliable measurements of ringing frequencies section instead and still get something out of the input shaping technique. Ringing frequency can depend on the position of the model within the buildplate and Z height, especially on delta printers ; you can check if you see the differences in frequencies at different positions along the sides of the test model and at different heights. You can calculate the average ringing frequencies over X and Y axes if that is the case. If the measured ringing frequency is very low (below approx 20-25 Hz), it might be a good idea to invest into stiffening the printer or decreasing the moving mass - depending on what is applicable in your case - before proceeding with further input shaping tuning, and re-measuring the frequencies afterwards. For many popular printer models there are often some solutions available already. Note that the ringing frequencies can change if the changes are made to the printer that affect the moving mass or change the stiffness of the system, for example: Some tools are installed, removed or replaced on the toolhead that change its mass, e.g. a new (heavier or lighter) stepper motor for direct extruder or a new hotend is installed, heavy fan with a duct is added, etc. Belts are tightened. Some addons to increase frame rigidity are installed. Different bed is installed on a bed-slinger printer, or glass added, etc. If such changes are made, it is a good idea to at least measure the ringing frequencies to see if they have changed.","title":"Ringing frequency"},{"location":"Resonance_Compensation.html#input-shaper-configuration","text":"After the ringing frequencies for X and Y axes are measured, you can add the following section to your printer.cfg : [input_shaper] shaper_freq_x: ... # frequency for the X mark of the test model shaper_freq_y: ... # frequency for the Y mark of the test model For the example above, we get shaper_freq_x/y = 49.4.","title":"Input shaper configuration"},{"location":"Resonance_Compensation.html#choosing-input-shaper","text":"Klipper supports several input shapers. They differ in their sensitivity to errors determining the resonance frequency and how much smoothing they cause in the printed parts. Also, some of the shapers like 2HUMP_EI and 3HUMP_EI should usually not be used with shaper_freq = resonance frequency - they are configured from different considerations to reduce several resonances at once. For most of the printers, either MZV or EI shapers can be recommended. This section describes a testing process to choose between them, and figure out a few other related parameters. Print the ringing test model as follows: Restart the firmware: RESTART Prepare for test: SET_VELOCITY_LIMIT MINIMUM_CRUISE_RATIO=0 Disable Pressure Advance: SET_PRESSURE_ADVANCE ADVANCE=0 Execute: SET_INPUT_SHAPER SHAPER_TYPE=MZV Execute the command: TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5 Print the test model sliced with the suggested parameters. If you see no ringing at this point, then MZV shaper can be recommended for use. If you do see some ringing, re-measure the frequencies using steps (8)-(10) described in Ringing frequency section. If the frequencies differ significantly from the values you obtained earlier, a more complex input shaper configuration is needed. You can refer to Technical details of Input shapers section. Otherwise, proceed to the next step. Now try EI input shaper. To try it, repeat steps (1)-(6) from above, but executing at step 4 the following command instead: SET_INPUT_SHAPER SHAPER_TYPE=EI . Compare two prints with MZV and EI input shaper. If EI shows noticeably better results than MZV, use EI shaper, otherwise prefer MZV. Note that EI shaper will cause more smoothing in printed parts (see the next section for further details). Add shaper_type: mzv (or ei) parameter to [input_shaper] section, e.g.: [input_shaper] shaper_freq_x: ... shaper_freq_y: ... shaper_type: mzv A few notes on shaper selection: EI shaper may be more suited for bed slinger printers (if the resonance frequency and resulting smoothing allows): as more filament is deposited on the moving bed, the mass of the bed increases and the resonance frequency will decrease. Since EI shaper is more robust to resonance frequency changes, it may work better when printing large parts. Due to the nature of delta kinematics, resonance frequencies can differ a lot in different parts of the build volume. Therefore, EI shaper can be a better fit for delta printers rather than MZV or ZV, and should be considered for the use. If the resonance frequency is sufficiently large (more than 50-60 Hz), then one can even attempt to test 2HUMP_EI shaper (by running the suggested test above with SET_INPUT_SHAPER SHAPER_TYPE=2HUMP_EI ), but check the considerations in the section below before enabling it.","title":"Choosing input shaper"},{"location":"Resonance_Compensation.html#selecting-max_accel","text":"You should have a printed test for the shaper you chose from the previous step (if you don't, print the test model sliced with the suggested parameters with the pressure advance disabled SET_PRESSURE_ADVANCE ADVANCE=0 and with the tuning tower enabled as TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5 ). Note that at very high accelerations, depending on the resonance frequency and the input shaper you chose (e.g. EI shaper creates more smoothing than MZV), input shaping may cause too much smoothing and rounding of the parts. So, max_accel should be chosen such as to prevent that. Another parameter that can impact smoothing is square_corner_velocity , so it is not advisable to increase it above the default 5 mm/sec to prevent increased smoothing. In order to select a suitable max_accel value, inspect the model for the chosen input shaper. First, take a note at which acceleration ringing is still small - that you are comfortable with it. Next, check the smoothing. To help with that, the test model has a small gap in the wall (0.15 mm): As the acceleration increases, so does the smoothing, and the actual gap in the print widens: In this picture, the acceleration increases left to right, and the gap starts to grow starting from 3500 mm/sec^2 (5-th band from the left). So the good value for max_accel = 3000 (mm/sec^2) in this case to avoid the excessive smoothing. Note the acceleration when the gap is still very small in your test print. If you see bulges, but no gap in the wall at all, even at high accelerations, it may be due to disabled Pressure Advance, especially on Bowden extruders. If that is the case, you may need to repeat the print with the PA enabled. It may also be a result of a miscalibrated (too high) filament flow, so it is a good idea to check that too. Choose the minimum out of the two acceleration values (from ringing and smoothing), and put it as max_accel into printer.cfg. As a note, it may happen - especially at low ringing frequencies - that EI shaper will cause too much smoothing even at lower accelerations. In this case, MZV may be a better choice, because it may allow higher acceleration values. At very low ringing frequencies (~25 Hz and below) even MZV shaper may create too much smoothing. If that is the case, you can also try to repeat the steps in Choosing input shaper section with ZV shaper, by using SET_INPUT_SHAPER SHAPER_TYPE=ZV command instead. ZV shaper should show even less smoothing than MZV, but is more sensitive to errors in measuring the ringing frequencies. Another consideration is that if a resonance frequency is too low (below 20-25 Hz), it might be a good idea to increase the printer stiffness or reduce the moving mass. Otherwise, acceleration and printing speed may be limited due too much smoothing now instead of ringing.","title":"Selecting max_accel"},{"location":"Resonance_Compensation.html#fine-tuning-resonance-frequencies","text":"Note that the precision of the resonance frequencies measurements using the ringing test model is sufficient for most purposes, so further tuning is not advised. If you still want to try to double-check your results (e.g. if you still see some ringing after printing a test model with an input shaper of your choice with the same frequencies as you have measured earlier), you can follow the steps in this section. Note that if you see ringing at different frequencies after enabling [input_shaper], this section will not help with that. Assuming that you have sliced the ringing model with suggested parameters, complete the following steps for each of the axes X and Y: Prepare for test: SET_VELOCITY_LIMIT MINIMUM_CRUISE_RATIO=0 Make sure Pressure Advance is disabled: SET_PRESSURE_ADVANCE ADVANCE=0 Execute: SET_INPUT_SHAPER SHAPER_TYPE=ZV From the existing ringing test model with your chosen input shaper select the acceleration that shows ringing sufficiently well, and set it with: SET_VELOCITY_LIMIT ACCEL=... Calculate the necessary parameters for the TUNING_TOWER command to tune shaper_freq_x parameter as follows: start = shaper_freq_x * 83 / 132 and factor = shaper_freq_x / 66, where shaper_freq_x here is the current value in printer.cfg . Execute the command: TUNING_TOWER COMMAND=SET_INPUT_SHAPER PARAMETER=SHAPER_FREQ_X START=start FACTOR=factor BAND=5 using start and factor values calculated at step (5). Print the test model. Reset the original frequency value: SET_INPUT_SHAPER SHAPER_FREQ_X=... . Find the band which shows ringing the least and count its number from the bottom starting at 1. Calculate the new shaper_freq_x value via old shaper_freq_x * (39 + 5 * #band-number) / 66. Repeat these steps for the Y axis in the same manner, replacing references to X axis with the axis Y (e.g. replace shaper_freq_x with shaper_freq_y in the formulae and in the TUNING_TOWER command). As an example, let's assume you have had measured the ringing frequency for one of the axis equal to 45 Hz. This gives start = 45 * 83 / 132 = 28.30 and factor = 45 / 66 = 0.6818 values for TUNING_TOWER command. Now let's assume that after printing the test model, the fourth band from the bottom gives the least ringing. This gives the updated shaper_freq_? value equal to 45 * (39 + 5 * 4) / 66 \u2248 40.23. After both new shaper_freq_x and shaper_freq_y parameters have been calculated, you can update [input_shaper] section in printer.cfg with the new shaper_freq_x and shaper_freq_y values.","title":"Fine-tuning resonance frequencies"},{"location":"Resonance_Compensation.html#pressure-advance","text":"If you use Pressure Advance, it may need to be re-tuned. Follow the instructions to find the new value, if it differs from the previous one. Make sure to restart Klipper before tuning Pressure Advance.","title":"Pressure Advance"},{"location":"Resonance_Compensation.html#unreliable-measurements-of-ringing-frequencies","text":"If you are unable to measure the ringing frequencies, e.g. if the distance between the oscillations is not stable, you may still be able to take advantage of input shaping techniques, but the results may not be as good as with proper measurements of the frequencies, and will require a bit more tuning and printing the test model. Note that another possibility is to purchase and install an accelerometer and measure the resonances with it (refer to the docs describing the required hardware and the setup process) - but this option requires some crimping and soldering. For tuning, add empty [input_shaper] section to your printer.cfg . Then, assuming that you have sliced the ringing model with suggested parameters, print the test model 3 times as follows. First time, prior to printing, run RESTART SET_VELOCITY_LIMIT MINIMUM_CRUISE_RATIO=0 SET_PRESSURE_ADVANCE ADVANCE=0 SET_INPUT_SHAPER SHAPER_TYPE=2HUMP_EI SHAPER_FREQ_X=60 SHAPER_FREQ_Y=60 TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5 and print the model. Then print the model again, but before printing run instead SET_INPUT_SHAPER SHAPER_TYPE=2HUMP_EI SHAPER_FREQ_X=50 SHAPER_FREQ_Y=50 TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5 Then print the model for the 3rd time, but now run SET_INPUT_SHAPER SHAPER_TYPE=2HUMP_EI SHAPER_FREQ_X=40 SHAPER_FREQ_Y=40 TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5 Essentially, we are printing the ringing test model with TUNING_TOWER using 2HUMP_EI shaper with shaper_freq = 60 Hz, 50 Hz, and 40 Hz. If none of the models demonstrate improvements in ringing, then, unfortunately, it does not look like the input shaping techniques can help with your case. Otherwise, it may be that all models show no ringing, or some show the ringing and some - not so much. Choose the test model with the highest frequency that still shows good improvements in ringing. For example, if 40 Hz and 50 Hz models show almost no ringing, and 60 Hz model already shows some more ringing, stick with 50 Hz. Now check if EI shaper would be good enough in your case. Choose EI shaper frequency based on the frequency of 2HUMP_EI shaper you chose: For 2HUMP_EI 60 Hz shaper, use EI shaper with shaper_freq = 50 Hz. For 2HUMP_EI 50 Hz shaper, use EI shaper with shaper_freq = 40 Hz. For 2HUMP_EI 40 Hz shaper, use EI shaper with shaper_freq = 33 Hz. Now print the test model one more time, running SET_INPUT_SHAPER SHAPER_TYPE=EI SHAPER_FREQ_X=... SHAPER_FREQ_Y=... TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5 providing the shaper_freq_x=... and shaper_freq_y=... as determined previously. If EI shaper shows very comparable good results as 2HUMP_EI shaper, stick with EI shaper and the frequency determined earlier, otherwise use 2HUMP_EI shaper with the corresponding frequency. Add the results to printer.cfg as, e.g. [input_shaper] shaper_freq_x: 50 shaper_freq_y: 50 shaper_type: 2hump_ei Continue the tuning with Selecting max_accel section.","title":"Unreliable measurements of ringing frequencies"},{"location":"Resonance_Compensation.html#troubleshooting-and-faq","text":"","title":"Troubleshooting and FAQ"},{"location":"Resonance_Compensation.html#i-cannot-get-reliable-measurements-of-resonance-frequencies","text":"First, make sure it is not some other problem with the printer instead of ringing. If the measurements are not reliable because, say, the distance between the oscillations is not stable, it might mean that the printer has several resonance frequencies on the same axis. One may try to follow the tuning process described in Unreliable measurements of ringing frequencies section and still get something out of the input shaping technique. Another possibility is to install an accelerometer, measure the resonances with it, and auto-tune the input shaper using the results of those measurements.","title":"I cannot get reliable measurements of resonance frequencies"},{"location":"Resonance_Compensation.html#after-enabling-input_shaper-i-get-too-smoothed-printed-parts-and-fine-details-are-lost","text":"Check the considerations in Selecting max_accel section. If the resonance frequency is low, one should not set too high max_accel or increase square_corner_velocity parameters. It might also be better to choose MZV or even ZV input shapers over EI (or 2HUMP_EI and 3HUMP_EI shapers).","title":"After enabling [input_shaper], I get too smoothed printed parts and fine details are lost"},{"location":"Resonance_Compensation.html#after-successfully-printing-for-some-time-without-ringing-it-appears-to-come-back","text":"It is possible that after some time the resonance frequencies have changed. E.g. maybe the belts tension has changed (belts got more loose), etc. It is a good idea to check and re-measure the ringing frequencies as described in Ringing frequency section and update your config file if necessary.","title":"After successfully printing for some time without ringing, it appears to come back"},{"location":"Resonance_Compensation.html#is-dual-carriage-setup-supported-with-input-shapers","text":"Yes. In this case, one should measure the resonances twice for each carriage. For example, if the second (dual) carriage is installed on X axis, it is possible to set different input shapers for X axis for the primary and dual carriages. However, the input shaper for Y axis should be the same for both carriages (as ultimately this axis is driven by one or more stepper motors each commanded to perform exactly the same steps). One possibility to configure the input shaper for such setups is to keep [input_shaper] section empty and additionally define a [delayed_gcode] section in the printer.cfg as follows: [input_shaper] # Intentionally empty [delayed_gcode init_shaper] initial_duration: 0.1 gcode: SET_DUAL_CARRIAGE CARRIAGE=1 SET_INPUT_SHAPER SHAPER_TYPE_X=<dual_carriage_shaper> SHAPER_FREQ_X=<dual_carriage_freq> SHAPER_TYPE_Y=<y_shaper> SHAPER_FREQ_Y=<y_freq> SET_DUAL_CARRIAGE CARRIAGE=0 SET_INPUT_SHAPER SHAPER_TYPE_X=<primary_carriage_shaper> SHAPER_FREQ_X=<primary_carriage_freq> SHAPER_TYPE_Y=<y_shaper> SHAPER_FREQ_Y=<y_freq> Note that SHAPER_TYPE_Y and SHAPER_FREQ_Y should be the same in both commands. It is also possible to put a similar snippet into the start g-code in the slicer, however then the shaper will not be enabled until any print is started. Note that the input shaper only needs to be configured once. Subsequent changes of the carriages or their modes via SET_DUAL_CARRIAGE command will preserve the configured input shaper parameters.","title":"Is dual carriage setup supported with input shapers?"},{"location":"Resonance_Compensation.html#does-input_shaper-affect-print-time","text":"No, input_shaper feature has pretty much no impact on the print times by itself. However, the value of max_accel certainly does (tuning of this parameter described in this section ).","title":"Does input_shaper affect print time?"},{"location":"Resonance_Compensation.html#technical-details","text":"","title":"Technical details"},{"location":"Resonance_Compensation.html#input-shapers","text":"Input shapers used in Klipper are rather standard, and one can find more in-depth overview in the articles describing the corresponding shapers. This section contains a brief overview of some technical aspects of the supported input shapers. The table below shows some (usually approximate) parameters of each shaper. Input shaper Shaper duration Vibration reduction 20x (5% vibration tolerance) Vibration reduction 10x (10% vibration tolerance) ZV 0.5 / shaper_freq N/A \u00b1 5% shaper_freq MZV 0.75 / shaper_freq \u00b1 4% shaper_freq -10%...+15% shaper_freq ZVD 1 / shaper_freq \u00b1 15% shaper_freq \u00b1 22% shaper_freq EI 1 / shaper_freq \u00b1 20% shaper_freq \u00b1 25% shaper_freq 2HUMP_EI 1.5 / shaper_freq \u00b1 35% shaper_freq \u00b1 40 shaper_freq 3HUMP_EI 2 / shaper_freq -45...+50% shaper_freq -50%...+55% shaper_freq A note on vibration reduction: the values in the table above are approximate. If the damping ratio of the printer is known for each axis, the shaper can be configured more precisely and it will then reduce the resonances in a bit wider range of frequencies. However, the damping ratio is usually unknown and is hard to estimate without a special equipment, so Klipper uses 0.1 value by default, which is a good all-round value. The frequency ranges in the table cover a number of different possible damping ratios around that value (approx. from 0.05 to 0.2). Also note that EI, 2HUMP_EI, and 3HUMP_EI are tuned to reduce vibrations to 5%, so the values for 10% vibration tolerance are provided only for the reference. How to use this table: Shaper duration affects the smoothing in parts - the larger it is, the more smooth the parts are. This dependency is not linear, but can give a sense of which shapers 'smooth' more for the same frequency. The ordering by smoothing is like this: ZV < MZV < ZVD \u2248 EI < 2HUMP_EI < 3HUMP_EI. Also, it is rarely practical to set shaper_freq = resonance freq for shapers 2HUMP_EI and 3HUMP_EI (they should be used to reduce vibrations for several frequencies). One can estimate a range of frequencies in which the shaper reduces vibrations. For example, MZV with shaper_freq = 35 Hz reduces vibrations to 5% for frequencies [33.6, 36.4] Hz. 3HUMP_EI with shaper_freq = 50 Hz reduces vibrations to 5% in range [27.5, 75] Hz. One can use this table to check which shaper they should be using if they need to reduce vibrations at several frequencies. For example, if one has resonances at 35 Hz and 60 Hz on the same axis: a) EI shaper needs to have shaper_freq = 35 / (1 - 0.2) = 43.75 Hz, and it will reduce resonances until 43.75 * (1 + 0.2) = 52.5 Hz, so it is not sufficient; b) 2HUMP_EI shaper needs to have shaper_freq = 35 / (1 - 0.35) = 53.85 Hz and will reduce vibrations until 53.85 * (1 + 0.35) = 72.7 Hz - so this is an acceptable configuration. Always try to use as high shaper_freq as possible for a given shaper (perhaps with some safety margin, so in this example shaper_freq \u2248 50-52 Hz would work best), and try to use a shaper with as small shaper duration as possible. If one needs to reduce vibrations at several very different frequencies (say, 30 Hz and 100 Hz), they may see that the table above does not provide enough information. In this case one may have more luck with scripts/graph_shaper.py script, which is more flexible.","title":"Input shapers"},{"location":"Rotation_Distance.html","text":"Rotation distance \u00b6 Stepper motor drivers on Klipper require a rotation_distance parameter in each stepper config section . The rotation_distance is the amount of distance that the axis moves with one full revolution of the stepper motor. This document describes how one can configure this value. Obtaining rotation_distance from steps_per_mm (or step_distance) \u00b6 The designers of your 3d printer originally calculated steps_per_mm from a rotation distance. If you know the steps_per_mm then it is possible to use this general formula to obtain that original rotation distance: rotation_distance = <full_steps_per_rotation> * <microsteps> / <steps_per_mm> Or, if you have an older Klipper configuration and know the step_distance parameter you can use this formula: rotation_distance = <full_steps_per_rotation> * <microsteps> * <step_distance> The <full_steps_per_rotation> setting is determined from the type of stepper motor. Most stepper motors are \"1.8 degree steppers\" and therefore have 200 full steps per rotation (360 divided by 1.8 is 200). Some stepper motors are \"0.9 degree steppers\" and thus have 400 full steps per rotation. Other stepper motors are rare. If unsure, do not set full_steps_per_rotation in the config file and use 200 in the formula above. The <microsteps> setting is determined by the stepper motor driver. Most drivers use 16 microsteps. If unsure, set microsteps: 16 in the config and use 16 in the formula above. Almost all printers should have a whole number for rotation_distance on X, Y, and Z type axes. If the above formula results in a rotation_distance that is within .01 of a whole number then round the final value to that whole_number. Calibrating rotation_distance on extruders \u00b6 On an extruder, the rotation_distance is the amount of distance the filament travels for one full rotation of the stepper motor. The best way to get an accurate value for this setting is to use a \"measure and trim\" procedure. First start with an initial guess for the rotation distance. This may be obtained from steps_per_mm or by inspecting the hardware . Then use the following procedure to \"measure and trim\": Make sure the extruder has filament in it, the hotend is heated to an appropriate temperature, and the printer is ready to extrude. Use a marker to place a mark on the filament around 70mm from the intake of the extruder body. Then use a digital calipers to measure the actual distance of that mark as precisely as one can. Note this as <initial_mark_distance> . Extrude 50mm of filament with the following command sequence: G91 followed by G1 E50 F60 . Note 50mm as <requested_extrude_distance> . Wait for the extruder to finish the move (it will take about 50 seconds). It is important to use the slow extrusion rate for this test as a faster rate can cause high pressure in the extruder which will skew the results. (Do not use the \"extrude button\" on graphical front-ends for this test as they extrude at a fast rate.) Use the digital calipers to measure the new distance between the extruder body and the mark on the filament. Note this as <subsequent_mark_distance> . Then calculate: actual_extrude_distance = <initial_mark_distance> - <subsequent_mark_distance> Calculate rotation_distance as: rotation_distance = <previous_rotation_distance> * <actual_extrude_distance> / <requested_extrude_distance> Round the new rotation_distance to three decimal places. If the actual_extrude_distance differs from requested_extrude_distance by more than about 2mm then it is a good idea to perform the steps above a second time. Note: Do not use a \"measure and trim\" type of method to calibrate x, y, or z type axes. The \"measure and trim\" method is not accurate enough for those axes and will likely lead to a worse configuration. Instead, if needed, those axes can be determined by measuring the belts, pulleys, and lead screw hardware . Obtaining rotation_distance by inspecting the hardware \u00b6 It's possible to calculate rotation_distance with knowledge of the stepper motors and printer kinematics. This may be useful if the steps_per_mm is not known or if designing a new printer. Belt driven axes \u00b6 It is easy to calculate rotation_distance for a linear axis that uses a belt and pulley. First determine the type of belt. Most printers use a 2mm belt pitch (that is, each tooth on the belt is 2mm apart). Then count the number of teeth on the stepper motor pulley. The rotation_distance is then calculated as: rotation_distance = <belt_pitch> * <number_of_teeth_on_pulley> For example, if a printer has a 2mm belt and uses a pulley with 20 teeth, then the rotation distance is 40. Axes with a lead screw \u00b6 It is easy to calculate the rotation_distance for common lead screws using the following formula: rotation_distance = <screw_pitch> * <number_of_separate_threads> For example, the common \"T8 leadscrew\" has a rotation distance of 8 (it has a pitch of 2mm and has 4 separate threads). Older printers with \"threaded rods\" have only one \"thread\" on the lead screw and thus the rotation distance is the pitch of the screw. (The screw pitch is the distance between each groove on the screw.) So, for example, an M6 metric rod has a rotation distance of 1 and an M8 rod has a rotation distance of 1.25. Extruder \u00b6 It's possible to obtain an initial rotation distance for extruders by measuring the diameter of the \"hobbed bolt\" that pushes the filament and using the following formula: rotation_distance = <diameter> * 3.14 If the extruder uses gears then it will also be necessary to determine and set the gear_ratio for the extruder. The actual rotation distance on an extruder will vary from printer to printer, because the grip of the \"hobbed bolt\" that engages the filament can vary. It can even vary between filament spools. After obtaining an initial rotation_distance, use the measure and trim procedure to obtain a more accurate setting. Using a gear_ratio \u00b6 Setting a gear_ratio can make it easier to configure the rotation_distance on steppers that have a gear box (or similar) attached to it. Most steppers do not have a gear box - if unsure then do not set gear_ratio in the config. When gear_ratio is set, the rotation_distance represents the distance the axis moves with one full rotation of the final gear on the gear box. If, for example, one is using a gearbox with a \"5:1\" ratio, then one could calculate the rotation_distance with knowledge of the hardware and then add gear_ratio: 5:1 to the config. For gearing implemented with belts and pulleys, it is possible to determine the gear_ratio by counting the teeth on the pulleys. For example, if a stepper with a 16 toothed pulley drives the next pulley with 80 teeth then one would use gear_ratio: 80:16 . Indeed, one could open a common off the shelf \"gear box\" and count the teeth in it to confirm its gear ratio. Note that sometimes a gearbox will have a slightly different gear ratio than what it is advertised as. The common BMG extruder motor gears are an example of this - they are advertised as \"3:1\" but actually use \"50:17\" gearing. (Using teeth numbers without a common denominator may improve overall gear wear as the teeth don't always mesh the same way with each revolution.) The common \"5.18:1 planetary gearbox\", is more accurately configured with gear_ratio: 57:11 . If several gears are used on an axis then it is possible to provide a comma separated list to gear_ratio. For example, a \"5:1\" gear box driving a 16 toothed to 80 toothed pulley could use gear_ratio: 5:1, 80:16 . In most cases, gear_ratio should be defined with whole numbers as common gears and pulleys have a whole number of teeth on them. However, in cases where a belt drives a pulley using friction instead of teeth, it may make sense to use a floating point number in the gear ratio (eg, gear_ratio: 107.237:16 ).","title":"Rotation distance"},{"location":"Rotation_Distance.html#rotation-distance","text":"Stepper motor drivers on Klipper require a rotation_distance parameter in each stepper config section . The rotation_distance is the amount of distance that the axis moves with one full revolution of the stepper motor. This document describes how one can configure this value.","title":"Rotation distance"},{"location":"Rotation_Distance.html#obtaining-rotation_distance-from-steps_per_mm-or-step_distance","text":"The designers of your 3d printer originally calculated steps_per_mm from a rotation distance. If you know the steps_per_mm then it is possible to use this general formula to obtain that original rotation distance: rotation_distance = <full_steps_per_rotation> * <microsteps> / <steps_per_mm> Or, if you have an older Klipper configuration and know the step_distance parameter you can use this formula: rotation_distance = <full_steps_per_rotation> * <microsteps> * <step_distance> The <full_steps_per_rotation> setting is determined from the type of stepper motor. Most stepper motors are \"1.8 degree steppers\" and therefore have 200 full steps per rotation (360 divided by 1.8 is 200). Some stepper motors are \"0.9 degree steppers\" and thus have 400 full steps per rotation. Other stepper motors are rare. If unsure, do not set full_steps_per_rotation in the config file and use 200 in the formula above. The <microsteps> setting is determined by the stepper motor driver. Most drivers use 16 microsteps. If unsure, set microsteps: 16 in the config and use 16 in the formula above. Almost all printers should have a whole number for rotation_distance on X, Y, and Z type axes. If the above formula results in a rotation_distance that is within .01 of a whole number then round the final value to that whole_number.","title":"Obtaining rotation_distance from steps_per_mm (or step_distance)"},{"location":"Rotation_Distance.html#calibrating-rotation_distance-on-extruders","text":"On an extruder, the rotation_distance is the amount of distance the filament travels for one full rotation of the stepper motor. The best way to get an accurate value for this setting is to use a \"measure and trim\" procedure. First start with an initial guess for the rotation distance. This may be obtained from steps_per_mm or by inspecting the hardware . Then use the following procedure to \"measure and trim\": Make sure the extruder has filament in it, the hotend is heated to an appropriate temperature, and the printer is ready to extrude. Use a marker to place a mark on the filament around 70mm from the intake of the extruder body. Then use a digital calipers to measure the actual distance of that mark as precisely as one can. Note this as <initial_mark_distance> . Extrude 50mm of filament with the following command sequence: G91 followed by G1 E50 F60 . Note 50mm as <requested_extrude_distance> . Wait for the extruder to finish the move (it will take about 50 seconds). It is important to use the slow extrusion rate for this test as a faster rate can cause high pressure in the extruder which will skew the results. (Do not use the \"extrude button\" on graphical front-ends for this test as they extrude at a fast rate.) Use the digital calipers to measure the new distance between the extruder body and the mark on the filament. Note this as <subsequent_mark_distance> . Then calculate: actual_extrude_distance = <initial_mark_distance> - <subsequent_mark_distance> Calculate rotation_distance as: rotation_distance = <previous_rotation_distance> * <actual_extrude_distance> / <requested_extrude_distance> Round the new rotation_distance to three decimal places. If the actual_extrude_distance differs from requested_extrude_distance by more than about 2mm then it is a good idea to perform the steps above a second time. Note: Do not use a \"measure and trim\" type of method to calibrate x, y, or z type axes. The \"measure and trim\" method is not accurate enough for those axes and will likely lead to a worse configuration. Instead, if needed, those axes can be determined by measuring the belts, pulleys, and lead screw hardware .","title":"Calibrating rotation_distance on extruders"},{"location":"Rotation_Distance.html#obtaining-rotation_distance-by-inspecting-the-hardware","text":"It's possible to calculate rotation_distance with knowledge of the stepper motors and printer kinematics. This may be useful if the steps_per_mm is not known or if designing a new printer.","title":"Obtaining rotation_distance by inspecting the hardware"},{"location":"Rotation_Distance.html#belt-driven-axes","text":"It is easy to calculate rotation_distance for a linear axis that uses a belt and pulley. First determine the type of belt. Most printers use a 2mm belt pitch (that is, each tooth on the belt is 2mm apart). Then count the number of teeth on the stepper motor pulley. The rotation_distance is then calculated as: rotation_distance = <belt_pitch> * <number_of_teeth_on_pulley> For example, if a printer has a 2mm belt and uses a pulley with 20 teeth, then the rotation distance is 40.","title":"Belt driven axes"},{"location":"Rotation_Distance.html#axes-with-a-lead-screw","text":"It is easy to calculate the rotation_distance for common lead screws using the following formula: rotation_distance = <screw_pitch> * <number_of_separate_threads> For example, the common \"T8 leadscrew\" has a rotation distance of 8 (it has a pitch of 2mm and has 4 separate threads). Older printers with \"threaded rods\" have only one \"thread\" on the lead screw and thus the rotation distance is the pitch of the screw. (The screw pitch is the distance between each groove on the screw.) So, for example, an M6 metric rod has a rotation distance of 1 and an M8 rod has a rotation distance of 1.25.","title":"Axes with a lead screw"},{"location":"Rotation_Distance.html#extruder","text":"It's possible to obtain an initial rotation distance for extruders by measuring the diameter of the \"hobbed bolt\" that pushes the filament and using the following formula: rotation_distance = <diameter> * 3.14 If the extruder uses gears then it will also be necessary to determine and set the gear_ratio for the extruder. The actual rotation distance on an extruder will vary from printer to printer, because the grip of the \"hobbed bolt\" that engages the filament can vary. It can even vary between filament spools. After obtaining an initial rotation_distance, use the measure and trim procedure to obtain a more accurate setting.","title":"Extruder"},{"location":"Rotation_Distance.html#using-a-gear_ratio","text":"Setting a gear_ratio can make it easier to configure the rotation_distance on steppers that have a gear box (or similar) attached to it. Most steppers do not have a gear box - if unsure then do not set gear_ratio in the config. When gear_ratio is set, the rotation_distance represents the distance the axis moves with one full rotation of the final gear on the gear box. If, for example, one is using a gearbox with a \"5:1\" ratio, then one could calculate the rotation_distance with knowledge of the hardware and then add gear_ratio: 5:1 to the config. For gearing implemented with belts and pulleys, it is possible to determine the gear_ratio by counting the teeth on the pulleys. For example, if a stepper with a 16 toothed pulley drives the next pulley with 80 teeth then one would use gear_ratio: 80:16 . Indeed, one could open a common off the shelf \"gear box\" and count the teeth in it to confirm its gear ratio. Note that sometimes a gearbox will have a slightly different gear ratio than what it is advertised as. The common BMG extruder motor gears are an example of this - they are advertised as \"3:1\" but actually use \"50:17\" gearing. (Using teeth numbers without a common denominator may improve overall gear wear as the teeth don't always mesh the same way with each revolution.) The common \"5.18:1 planetary gearbox\", is more accurately configured with gear_ratio: 57:11 . If several gears are used on an axis then it is possible to provide a comma separated list to gear_ratio. For example, a \"5:1\" gear box driving a 16 toothed to 80 toothed pulley could use gear_ratio: 5:1, 80:16 . In most cases, gear_ratio should be defined with whole numbers as common gears and pulleys have a whole number of teeth on them. However, in cases where a belt drives a pulley using friction instead of teeth, it may make sense to use a floating point number in the gear ratio (eg, gear_ratio: 107.237:16 ).","title":"Using a gear_ratio"},{"location":"SDCard_Updates.html","text":"SDCard updates \u00b6 Many of today's popular controller boards ship with a bootloader capable of updating firmware via SD Card. While this is convenient in many circumstances, these bootloaders typically provide no other way to update firmware. This can be a nuisance if your board is mounted in a location that is difficult to access or if you need to update firmware often. After Klipper has been initially flashed to a controller it is possible to transfer new firmware to the SD Card and initiate the flashing procedure via ssh. Typical Upgrade Procedure \u00b6 The procedure for updating MCU firmware using the SD Card is similar to that of other methods. Instead of using make flash it is necessary to run a helper script, flash-sdcard.sh . Updating a BigTreeTech SKR 1.3 might look like the following: sudo service klipper stop cd ~/klipper git pull make clean make menuconfig make ./scripts/flash-sdcard.sh /dev/ttyACM0 btt-skr-v1.3 sudo service klipper start It is up to the user to determine the device location and board name. If a user needs to flash multiple boards, flash-sdcard.sh (or make flash if appropriate) should be run for each board prior to restarting the Klipper service. Supported boards can be listed with the following command: ./scripts/flash-sdcard.sh -l If you do not see your board listed it may be necessary to add a new board definition as described below . Advanced Usage \u00b6 The above commands assume that your MCU connects at the default baud rate of 250000 and the firmware is located at ~/klipper/out/klipper.bin . The flash-sdcard.sh script provides options for changing these defaults. All options can be viewed by the help screen: ./scripts/flash-sdcard.sh -h SD Card upload utility for Klipper usage: flash_sdcard.sh [-h] [-l] [-c] [-b <baud>] [-f <firmware>] <device> <board> positional arguments: <device> device serial port <board> board type optional arguments: -h show this message -l list available boards -c run flash check/verify only (skip upload) -b <baud> serial baud rate (default is 250000) -f <firmware> path to klipper.bin If your board is flashed with firmware that connects at a custom baud rate it is possible to upgrade by specifying the -b option: ./scripts/flash-sdcard.sh -b 115200 /dev/ttyAMA0 btt-skr-v1.3 If you wish to flash a build of Klipper located somewhere other than the default location it can be done by specifying the -f option: ./scripts/flash-sdcard.sh -f ~/downloads/klipper.bin /dev/ttyAMA0 btt-skr-v1.3 Note that when upgrading a MKS Robin E3 it is not necessary to manually run update_mks_robin.py and supply the resulting binary to flash-sdcard.sh . This procedure is automated during the upload process. The -c option is used to perform a check or verify-only operation to test if the board is running the specified firmware correctly. This option is primarily intended for cases where a manual power-cycle is necessary to complete the flashing procedure, such as with bootloaders that use SDIO mode instead of SPI to access their SD Cards. (See Caveats below) But, it can also be used anytime to verify if the code flashed into the board matches the version in your build folder on any supported board. Caveats \u00b6 As mentioned in the introduction, this method only works for upgrading firmware. The initial flashing procedure must be done manually per the instructions that apply to your controller board. While it is possible to flash a build that changes the Serial Baud or connection interface (ie: from USB to UART), verification will always fail as the script will be unable to reconnect to the MCU to verify the current version. Only boards that use SPI for SD Card communication are supported. Boards that use SDIO, such as the Flymaker Flyboard and MKS Robin Nano V1/V2, will not work in SDIO mode. However, it's usually possible to flash such boards using Software SPI mode instead. But if the board's bootloader only uses SDIO mode to access the SD Card, a power-cycle of the board and SD Card will be necessary so that the mode can switch from SPI back to SDIO to complete reflashing. Such boards should be defined with skip_verify enabled to skip the verify step immediately after flashing. Then after the manual power-cycle, you can rerun the exact same ./scripts/flash-sdcard.sh command, but add the -c option to complete the check/verify operation. See Flashing Boards that use SDIO for examples. Board Definitions \u00b6 Most common boards should be available, however it is possible to add a new board definition if necessary. Board definitions are located in ~/klipper/scripts/spi_flash/board_defs.py . The definitions are stored in dictionary, for example: BOARD_DEFS = { 'generic-lpc1768' : { 'mcu' : \"lpc1768\" , 'spi_bus' : \"ssp1\" , \"cs_pin\" : \"P0.6\" }, ...< further definitions > } The following fields may be specified: mcu : The mcu type. This can be retrieved after configuring the build via make menuconfig by running cat .config | grep CONFIG_MCU . This field is required. spi_bus : The SPI bus connected to the SD Card. This should be retrieved from the board's schematic. This field is required. cs_pin : The Chip Select Pin connected to the SD Card. This should be retrieved from the board schematic. This field is required. firmware_path : The path on the SD Card where firmware should be transferred. The default is firmware.bin . current_firmware_path : The path on the SD Card where the renamed firmware file is located after a successful flash. The default is firmware.cur . skip_verify : This defines a boolean value which tells the scripts to skip the firmware verification step during the flashing process. The default is False . It can be set to True for boards that require a manual power-cycle to complete flashing. To verify the firmware afterward, run the script again with the -c option to perform the verification step. See caveats with SDIO cards If software SPI is required, the spi_bus field should be set to swspi and the following additional field should be specified: spi_pins : This should be 3 comma separated pins that are connected to the SD Card in the format of miso,mosi,sclk . It should be exceedingly rare that Software SPI is necessary, typically only boards with design errors or boards that normally only support SDIO mode for their SD Card will require it. The btt-skr-pro board definition provides an example of the former, and the btt-octopus-f446-v1 board definition provides an example of the latter. Prior to creating a new board definition one should check to see if an existing board definition meets the criteria necessary for the new board. If this is the case, a BOARD_ALIAS may be specified. For example, the following alias may be added to specify my-new-board as an alias for generic-lpc1768 : BOARD_ALIASES = { ...< previous aliases > , 'my-new-board' : BOARD_DEFS [ 'generic-lpc1768' ], } If you need a new board definition and you are uncomfortable with the procedure outlined above it is recommended that you request one in the Klipper Discord . Flashing Boards that use SDIO \u00b6 As mentioned in the Caveats , boards whose bootloader uses SDIO mode to access their SD Card require a power-cycle of the board, and specifically the SD Card itself, in order to switch from the SPI Mode used while writing the file to the SD Card back to SDIO mode for the bootloader to flash it into the board. These board definitions will use the skip_verify flag, which tells the flashing tool to stop after writing the firmware to the SD Card so that the board can be manually power-cycled and the verification step deferred until that's complete. There are two scenarios -- one with the RPi Host running on a separate power supply and the other when the RPi Host is running on the same power supply as the main board being flashed. The difference is whether or not it's necessary to also shutdown the RPi and then ssh again after the flashing is complete in order to do the verification step, or if the verification can be done immediately. Here's examples of the two scenarios: SDIO Programming with RPi on Separate Power Supply \u00b6 A typical session with the RPi on a Separate Power Supply looks like the following. You will, of course, need to use your proper device path and board name: sudo service klipper stop cd ~/klipper git pull make clean make menuconfig make ./scripts/flash-sdcard.sh /dev/ttyACM0 btt-octopus-f446-v1 [[[manually power-cycle the printer board here when instructed]]] ./scripts/flash-sdcard.sh -c /dev/ttyACM0 btt-octopus-f446-v1 sudo service klipper start SDIO Programming with RPi on the Same Power Supply \u00b6 A typical session with the RPi on the Same Power Supply looks like the following. You will, of course, need to use your proper device path and board name: sudo service klipper stop cd ~/klipper git pull make clean make menuconfig make ./scripts/flash-sdcard.sh /dev/ttyACM0 btt-octopus-f446-v1 sudo shutdown -h now [[[wait for the RPi to shutdown, then power-cycle and ssh again to the RPi when it restarts]]] sudo service klipper stop cd ~/klipper ./scripts/flash-sdcard.sh -c /dev/ttyACM0 btt-octopus-f446-v1 sudo service klipper start In this case, since the RPi Host is being restarted, which will restart the klipper service, it's necessary to stop klipper again before doing the verification step and restart it after verification is complete. SDIO to SPI Pin Mapping \u00b6 If your board's schematic uses SDIO for its SD Card, you can map the pins as described in the chart below to determine the compatible Software SPI pins to assign in the board_defs.py file: SD Card Pin Micro SD Card Pin SDIO Pin Name SPI Pin Name 9 1 DATA2 None (PU)* 1 2 CD/DATA3 CS 2 3 CMD MOSI 4 4 +3.3V (VDD) +3.3V (VDD) 5 5 CLK SCLK 3 6 GND (VSS) GND (VSS) 7 7 DATA0 MISO 8 8 DATA1 None (PU)* N/A 9 Card Detect (CD) Card Detect (CD) 6 10 GND GND * None (PU) indicates an unused pin with a pull-up resistor","title":"SDCard updates"},{"location":"SDCard_Updates.html#sdcard-updates","text":"Many of today's popular controller boards ship with a bootloader capable of updating firmware via SD Card. While this is convenient in many circumstances, these bootloaders typically provide no other way to update firmware. This can be a nuisance if your board is mounted in a location that is difficult to access or if you need to update firmware often. After Klipper has been initially flashed to a controller it is possible to transfer new firmware to the SD Card and initiate the flashing procedure via ssh.","title":"SDCard updates"},{"location":"SDCard_Updates.html#typical-upgrade-procedure","text":"The procedure for updating MCU firmware using the SD Card is similar to that of other methods. Instead of using make flash it is necessary to run a helper script, flash-sdcard.sh . Updating a BigTreeTech SKR 1.3 might look like the following: sudo service klipper stop cd ~/klipper git pull make clean make menuconfig make ./scripts/flash-sdcard.sh /dev/ttyACM0 btt-skr-v1.3 sudo service klipper start It is up to the user to determine the device location and board name. If a user needs to flash multiple boards, flash-sdcard.sh (or make flash if appropriate) should be run for each board prior to restarting the Klipper service. Supported boards can be listed with the following command: ./scripts/flash-sdcard.sh -l If you do not see your board listed it may be necessary to add a new board definition as described below .","title":"Typical Upgrade Procedure"},{"location":"SDCard_Updates.html#advanced-usage","text":"The above commands assume that your MCU connects at the default baud rate of 250000 and the firmware is located at ~/klipper/out/klipper.bin . The flash-sdcard.sh script provides options for changing these defaults. All options can be viewed by the help screen: ./scripts/flash-sdcard.sh -h SD Card upload utility for Klipper usage: flash_sdcard.sh [-h] [-l] [-c] [-b <baud>] [-f <firmware>] <device> <board> positional arguments: <device> device serial port <board> board type optional arguments: -h show this message -l list available boards -c run flash check/verify only (skip upload) -b <baud> serial baud rate (default is 250000) -f <firmware> path to klipper.bin If your board is flashed with firmware that connects at a custom baud rate it is possible to upgrade by specifying the -b option: ./scripts/flash-sdcard.sh -b 115200 /dev/ttyAMA0 btt-skr-v1.3 If you wish to flash a build of Klipper located somewhere other than the default location it can be done by specifying the -f option: ./scripts/flash-sdcard.sh -f ~/downloads/klipper.bin /dev/ttyAMA0 btt-skr-v1.3 Note that when upgrading a MKS Robin E3 it is not necessary to manually run update_mks_robin.py and supply the resulting binary to flash-sdcard.sh . This procedure is automated during the upload process. The -c option is used to perform a check or verify-only operation to test if the board is running the specified firmware correctly. This option is primarily intended for cases where a manual power-cycle is necessary to complete the flashing procedure, such as with bootloaders that use SDIO mode instead of SPI to access their SD Cards. (See Caveats below) But, it can also be used anytime to verify if the code flashed into the board matches the version in your build folder on any supported board.","title":"Advanced Usage"},{"location":"SDCard_Updates.html#caveats","text":"As mentioned in the introduction, this method only works for upgrading firmware. The initial flashing procedure must be done manually per the instructions that apply to your controller board. While it is possible to flash a build that changes the Serial Baud or connection interface (ie: from USB to UART), verification will always fail as the script will be unable to reconnect to the MCU to verify the current version. Only boards that use SPI for SD Card communication are supported. Boards that use SDIO, such as the Flymaker Flyboard and MKS Robin Nano V1/V2, will not work in SDIO mode. However, it's usually possible to flash such boards using Software SPI mode instead. But if the board's bootloader only uses SDIO mode to access the SD Card, a power-cycle of the board and SD Card will be necessary so that the mode can switch from SPI back to SDIO to complete reflashing. Such boards should be defined with skip_verify enabled to skip the verify step immediately after flashing. Then after the manual power-cycle, you can rerun the exact same ./scripts/flash-sdcard.sh command, but add the -c option to complete the check/verify operation. See Flashing Boards that use SDIO for examples.","title":"Caveats"},{"location":"SDCard_Updates.html#board-definitions","text":"Most common boards should be available, however it is possible to add a new board definition if necessary. Board definitions are located in ~/klipper/scripts/spi_flash/board_defs.py . The definitions are stored in dictionary, for example: BOARD_DEFS = { 'generic-lpc1768' : { 'mcu' : \"lpc1768\" , 'spi_bus' : \"ssp1\" , \"cs_pin\" : \"P0.6\" }, ...< further definitions > } The following fields may be specified: mcu : The mcu type. This can be retrieved after configuring the build via make menuconfig by running cat .config | grep CONFIG_MCU . This field is required. spi_bus : The SPI bus connected to the SD Card. This should be retrieved from the board's schematic. This field is required. cs_pin : The Chip Select Pin connected to the SD Card. This should be retrieved from the board schematic. This field is required. firmware_path : The path on the SD Card where firmware should be transferred. The default is firmware.bin . current_firmware_path : The path on the SD Card where the renamed firmware file is located after a successful flash. The default is firmware.cur . skip_verify : This defines a boolean value which tells the scripts to skip the firmware verification step during the flashing process. The default is False . It can be set to True for boards that require a manual power-cycle to complete flashing. To verify the firmware afterward, run the script again with the -c option to perform the verification step. See caveats with SDIO cards If software SPI is required, the spi_bus field should be set to swspi and the following additional field should be specified: spi_pins : This should be 3 comma separated pins that are connected to the SD Card in the format of miso,mosi,sclk . It should be exceedingly rare that Software SPI is necessary, typically only boards with design errors or boards that normally only support SDIO mode for their SD Card will require it. The btt-skr-pro board definition provides an example of the former, and the btt-octopus-f446-v1 board definition provides an example of the latter. Prior to creating a new board definition one should check to see if an existing board definition meets the criteria necessary for the new board. If this is the case, a BOARD_ALIAS may be specified. For example, the following alias may be added to specify my-new-board as an alias for generic-lpc1768 : BOARD_ALIASES = { ...< previous aliases > , 'my-new-board' : BOARD_DEFS [ 'generic-lpc1768' ], } If you need a new board definition and you are uncomfortable with the procedure outlined above it is recommended that you request one in the Klipper Discord .","title":"Board Definitions"},{"location":"SDCard_Updates.html#flashing-boards-that-use-sdio","text":"As mentioned in the Caveats , boards whose bootloader uses SDIO mode to access their SD Card require a power-cycle of the board, and specifically the SD Card itself, in order to switch from the SPI Mode used while writing the file to the SD Card back to SDIO mode for the bootloader to flash it into the board. These board definitions will use the skip_verify flag, which tells the flashing tool to stop after writing the firmware to the SD Card so that the board can be manually power-cycled and the verification step deferred until that's complete. There are two scenarios -- one with the RPi Host running on a separate power supply and the other when the RPi Host is running on the same power supply as the main board being flashed. The difference is whether or not it's necessary to also shutdown the RPi and then ssh again after the flashing is complete in order to do the verification step, or if the verification can be done immediately. Here's examples of the two scenarios:","title":"Flashing Boards that use SDIO"},{"location":"SDCard_Updates.html#sdio-programming-with-rpi-on-separate-power-supply","text":"A typical session with the RPi on a Separate Power Supply looks like the following. You will, of course, need to use your proper device path and board name: sudo service klipper stop cd ~/klipper git pull make clean make menuconfig make ./scripts/flash-sdcard.sh /dev/ttyACM0 btt-octopus-f446-v1 [[[manually power-cycle the printer board here when instructed]]] ./scripts/flash-sdcard.sh -c /dev/ttyACM0 btt-octopus-f446-v1 sudo service klipper start","title":"SDIO Programming with RPi on Separate Power Supply"},{"location":"SDCard_Updates.html#sdio-programming-with-rpi-on-the-same-power-supply","text":"A typical session with the RPi on the Same Power Supply looks like the following. You will, of course, need to use your proper device path and board name: sudo service klipper stop cd ~/klipper git pull make clean make menuconfig make ./scripts/flash-sdcard.sh /dev/ttyACM0 btt-octopus-f446-v1 sudo shutdown -h now [[[wait for the RPi to shutdown, then power-cycle and ssh again to the RPi when it restarts]]] sudo service klipper stop cd ~/klipper ./scripts/flash-sdcard.sh -c /dev/ttyACM0 btt-octopus-f446-v1 sudo service klipper start In this case, since the RPi Host is being restarted, which will restart the klipper service, it's necessary to stop klipper again before doing the verification step and restart it after verification is complete.","title":"SDIO Programming with RPi on the Same Power Supply"},{"location":"SDCard_Updates.html#sdio-to-spi-pin-mapping","text":"If your board's schematic uses SDIO for its SD Card, you can map the pins as described in the chart below to determine the compatible Software SPI pins to assign in the board_defs.py file: SD Card Pin Micro SD Card Pin SDIO Pin Name SPI Pin Name 9 1 DATA2 None (PU)* 1 2 CD/DATA3 CS 2 3 CMD MOSI 4 4 +3.3V (VDD) +3.3V (VDD) 5 5 CLK SCLK 3 6 GND (VSS) GND (VSS) 7 7 DATA0 MISO 8 8 DATA1 None (PU)* N/A 9 Card Detect (CD) Card Detect (CD) 6 10 GND GND * None (PU) indicates an unused pin with a pull-up resistor","title":"SDIO to SPI Pin Mapping"},{"location":"Skew_Correction.html","text":"Skew correction \u00b6 Software based skew correction can help resolve dimensional inaccuracies resulting from a printer assembly that is not perfectly square. Note that if your printer is significantly skewed it is strongly recommended to first use mechanical means to get your printer as square as possible prior to applying software based correction. Print a Calibration Object \u00b6 The first step in correcting skew is to print a calibration object along the plane you want to correct. There is also a calibration object that includes all planes in one model. You want the object oriented so that corner A is toward the origin of the plane. Make sure that no skew correction is applied during this print. You may do this by either removing the [skew_correction] module from printer.cfg or by issuing a SET_SKEW CLEAR=1 gcode. Take your measurements \u00b6 The [skew_correction] module requires 3 measurements for each plane you want to correct; the length from Corner A to Corner C, the length from Corner B to Corner D, and the length from Corner A to Corner D. When measuring length AD do not include the flats on the corners that some test objects provide. Configure your skew \u00b6 Make sure [skew_correction] is in printer.cfg. You may now use the SET_SKEW gcode to configure skew_correction. For example, if your measured lengths along XY are as follows: Length AC = 140.4 Length BD = 142.8 Length AD = 99.8 SET_SKEW can be used to configure skew correction for the XY plane. SET_SKEW XY=140.4,142.8,99.8 You may also add measurements for XZ and YZ to the gcode: SET_SKEW XY=140.4,142.8,99.8 XZ=141.6,141.4,99.8 YZ=142.4,140.5,99.5 The [skew_correction] module also supports profile management in a manner similar to [bed_mesh] . After setting skew using the SET_SKEW gcode, you may use the SKEW_PROFILE gcode to save it: SKEW_PROFILE SAVE=my_skew_profile After this command you will be prompted to issue a SAVE_CONFIG gcode to save the profile to persistent storage. If no profile is named my_skew_profile then a new profile will be created. If the named profile exists it will be overwritten. Once you have a saved profile, you may load it: SKEW_PROFILE LOAD=my_skew_profile It is also possible to remove an old or out of date profile: SKEW_PROFILE REMOVE=my_skew_profile After removing a profile you will be prompted to issue a SAVE_CONFIG to make this change persist. Verifying your correction \u00b6 After skew_correction has been configured you may reprint the calibration part with correction enabled. Use the following gcode to check your skew on each plane. The results should be lower than those reported via GET_CURRENT_SKEW . CALC_MEASURED_SKEW AC=<ac_length> BD=<bd_length> AD=<ad_length> Caveats \u00b6 Due to the nature of skew correction it is recommended to configure skew in your start gcode, after homing and any kind of movement that travels near the edge of the print area such as a purge or nozzle wipe. You may use use the SET_SKEW or SKEW_PROFILE gcodes to accomplish this. It is also recommended to issue a SET_SKEW CLEAR=1 in your end gcode. Keep in mind that it is possible for [skew_correction] to generate a correction that moves the tool beyond the printer's boundaries on the X and/or Y axes. It is recommended to arrange parts away from the edges when using [skew_correction] .","title":"Skew correction"},{"location":"Skew_Correction.html#skew-correction","text":"Software based skew correction can help resolve dimensional inaccuracies resulting from a printer assembly that is not perfectly square. Note that if your printer is significantly skewed it is strongly recommended to first use mechanical means to get your printer as square as possible prior to applying software based correction.","title":"Skew correction"},{"location":"Skew_Correction.html#print-a-calibration-object","text":"The first step in correcting skew is to print a calibration object along the plane you want to correct. There is also a calibration object that includes all planes in one model. You want the object oriented so that corner A is toward the origin of the plane. Make sure that no skew correction is applied during this print. You may do this by either removing the [skew_correction] module from printer.cfg or by issuing a SET_SKEW CLEAR=1 gcode.","title":"Print a Calibration Object"},{"location":"Skew_Correction.html#take-your-measurements","text":"The [skew_correction] module requires 3 measurements for each plane you want to correct; the length from Corner A to Corner C, the length from Corner B to Corner D, and the length from Corner A to Corner D. When measuring length AD do not include the flats on the corners that some test objects provide.","title":"Take your measurements"},{"location":"Skew_Correction.html#configure-your-skew","text":"Make sure [skew_correction] is in printer.cfg. You may now use the SET_SKEW gcode to configure skew_correction. For example, if your measured lengths along XY are as follows: Length AC = 140.4 Length BD = 142.8 Length AD = 99.8 SET_SKEW can be used to configure skew correction for the XY plane. SET_SKEW XY=140.4,142.8,99.8 You may also add measurements for XZ and YZ to the gcode: SET_SKEW XY=140.4,142.8,99.8 XZ=141.6,141.4,99.8 YZ=142.4,140.5,99.5 The [skew_correction] module also supports profile management in a manner similar to [bed_mesh] . After setting skew using the SET_SKEW gcode, you may use the SKEW_PROFILE gcode to save it: SKEW_PROFILE SAVE=my_skew_profile After this command you will be prompted to issue a SAVE_CONFIG gcode to save the profile to persistent storage. If no profile is named my_skew_profile then a new profile will be created. If the named profile exists it will be overwritten. Once you have a saved profile, you may load it: SKEW_PROFILE LOAD=my_skew_profile It is also possible to remove an old or out of date profile: SKEW_PROFILE REMOVE=my_skew_profile After removing a profile you will be prompted to issue a SAVE_CONFIG to make this change persist.","title":"Configure your skew"},{"location":"Skew_Correction.html#verifying-your-correction","text":"After skew_correction has been configured you may reprint the calibration part with correction enabled. Use the following gcode to check your skew on each plane. The results should be lower than those reported via GET_CURRENT_SKEW . CALC_MEASURED_SKEW AC=<ac_length> BD=<bd_length> AD=<ad_length>","title":"Verifying your correction"},{"location":"Skew_Correction.html#caveats","text":"Due to the nature of skew correction it is recommended to configure skew in your start gcode, after homing and any kind of movement that travels near the edge of the print area such as a purge or nozzle wipe. You may use use the SET_SKEW or SKEW_PROFILE gcodes to accomplish this. It is also recommended to issue a SET_SKEW CLEAR=1 in your end gcode. Keep in mind that it is possible for [skew_correction] to generate a correction that moves the tool beyond the printer's boundaries on the X and/or Y axes. It is recommended to arrange parts away from the edges when using [skew_correction] .","title":"Caveats"},{"location":"Slicers.html","text":"Slicers \u00b6 This document provides some tips for configuring a \"slicer\" application for use with Klipper. Common slicers used with Klipper are Slic3r, Cura, Simplify3D, etc. Set the G-Code flavor to Marlin \u00b6 Many slicers have an option to configure the \"G-Code flavor\". The default is frequently \"Marlin\" and that works well with Klipper. The \"Smoothieware\" setting also works well with Klipper. Klipper gcode_macro \u00b6 Slicers will often allow one to configure \"Start G-Code\" and \"End G-Code\" sequences. It is often convenient to define custom macros in the Klipper config file instead - such as: [gcode_macro START_PRINT] and [gcode_macro END_PRINT] . Then one can just run START_PRINT and END_PRINT in the slicer's configuration. Defining these actions in the Klipper configuration may make it easier to tweak the printer's start and end steps as changes do not require re-slicing. See sample-macros.cfg for example START_PRINT and END_PRINT macros. See the config reference for details on defining a gcode_macro. Large retraction settings may require tuning Klipper \u00b6 The maximum speed and acceleration of retraction moves are controlled in Klipper by the max_extrude_only_velocity and max_extrude_only_accel config settings. These settings have a default value that should work well on many printers. However, if one has configured a large retraction in the slicer (eg, 5mm or greater) then one may find they limit the desired speed of retractions. If using a large retraction, consider tuning Klipper's pressure advance instead. Otherwise, if one finds the toolhead seems to \"pause\" during retraction and priming, then consider explicitly defining max_extrude_only_velocity and max_extrude_only_accel in the Klipper config file. Do not enable \"coasting\" \u00b6 The \"coasting\" feature is likely to result in poor quality prints with Klipper. Consider using Klipper's pressure advance instead. Specifically, if the slicer dramatically changes the extrusion rate between moves then Klipper will perform deceleration and acceleration between moves. This is likely to make blobbing worse, not better. In contrast, it is okay (and often helpful) to use a slicer's \"retract\" setting, \"wipe\" setting, and/or \"wipe on retract\" setting. Do not use \"extra restart distance\" on Simplify3d \u00b6 This setting can cause dramatic changes to extrusion rates which can trigger Klipper's maximum extrusion cross-section check. Consider using Klipper's pressure advance or the regular Simplify3d retract setting instead. Disable \"PreloadVE\" on KISSlicer \u00b6 If using KISSlicer slicing software then set \"PreloadVE\" to zero. Consider using Klipper's pressure advance instead. Disable any \"advanced extruder pressure\" settings \u00b6 Some slicers advertise an \"advanced extruder pressure\" capability. It is recommended to keep these options disabled when using Klipper as they are likely to result in poor quality prints. Consider using Klipper's pressure advance instead. Specifically, these slicer settings can instruct the firmware to make wild changes to the extrusion rate in the hope that the firmware will approximate those requests and the printer will roughly obtain a desirable extruder pressure. Klipper, however, utilizes precise kinematic calculations and timing. When Klipper is commanded to make significant changes to the extrusion rate it will plan out the corresponding changes to velocity, acceleration, and extruder movement - which is not the slicer's intent. The slicer may even command excessive extrusion rates to the point that it triggers Klipper's maximum extrusion cross-section check. In contrast, it is okay (and often helpful) to use a slicer's \"retract\" setting, \"wipe\" setting, and/or \"wipe on retract\" setting. START_PRINT macros \u00b6 When using a START_PRINT macro or similar, it is useful to sometimes pass through parameters from the slicer variables to the macro. In Cura, to pass through temperatures, the following start gcode would be used: START_PRINT BED_TEMP={material_bed_temperature_layer_0} EXTRUDER_TEMP={material_print_temperature_layer_0} In slic3r derivatives such as PrusaSlicer and SuperSlicer, the following would be used: START_PRINT EXTRUDER_TEMP=[first_layer_temperature] BED_TEMP=[first_layer_bed_temperature] Also note that these slicers will insert their own heating codes when certain conditions are not met. In Cura, the existence of the {material_bed_temperature_layer_0} and {material_print_temperature_layer_0} variables is enough to mitigate this. In slic3r derivatives, you would use: M140 S0 M104 S0 before the macro call. Also note that SuperSlicer has a \"custom gcode only\" button option, which achieves the same outcome. An example of a START_PRINT macro using these parameters can be found in config/sample-macros.cfg","title":"Slicers"},{"location":"Slicers.html#slicers","text":"This document provides some tips for configuring a \"slicer\" application for use with Klipper. Common slicers used with Klipper are Slic3r, Cura, Simplify3D, etc.","title":"Slicers"},{"location":"Slicers.html#set-the-g-code-flavor-to-marlin","text":"Many slicers have an option to configure the \"G-Code flavor\". The default is frequently \"Marlin\" and that works well with Klipper. The \"Smoothieware\" setting also works well with Klipper.","title":"Set the G-Code flavor to Marlin"},{"location":"Slicers.html#klipper-gcode_macro","text":"Slicers will often allow one to configure \"Start G-Code\" and \"End G-Code\" sequences. It is often convenient to define custom macros in the Klipper config file instead - such as: [gcode_macro START_PRINT] and [gcode_macro END_PRINT] . Then one can just run START_PRINT and END_PRINT in the slicer's configuration. Defining these actions in the Klipper configuration may make it easier to tweak the printer's start and end steps as changes do not require re-slicing. See sample-macros.cfg for example START_PRINT and END_PRINT macros. See the config reference for details on defining a gcode_macro.","title":"Klipper gcode_macro"},{"location":"Slicers.html#large-retraction-settings-may-require-tuning-klipper","text":"The maximum speed and acceleration of retraction moves are controlled in Klipper by the max_extrude_only_velocity and max_extrude_only_accel config settings. These settings have a default value that should work well on many printers. However, if one has configured a large retraction in the slicer (eg, 5mm or greater) then one may find they limit the desired speed of retractions. If using a large retraction, consider tuning Klipper's pressure advance instead. Otherwise, if one finds the toolhead seems to \"pause\" during retraction and priming, then consider explicitly defining max_extrude_only_velocity and max_extrude_only_accel in the Klipper config file.","title":"Large retraction settings may require tuning Klipper"},{"location":"Slicers.html#do-not-enable-coasting","text":"The \"coasting\" feature is likely to result in poor quality prints with Klipper. Consider using Klipper's pressure advance instead. Specifically, if the slicer dramatically changes the extrusion rate between moves then Klipper will perform deceleration and acceleration between moves. This is likely to make blobbing worse, not better. In contrast, it is okay (and often helpful) to use a slicer's \"retract\" setting, \"wipe\" setting, and/or \"wipe on retract\" setting.","title":"Do not enable \"coasting\""},{"location":"Slicers.html#do-not-use-extra-restart-distance-on-simplify3d","text":"This setting can cause dramatic changes to extrusion rates which can trigger Klipper's maximum extrusion cross-section check. Consider using Klipper's pressure advance or the regular Simplify3d retract setting instead.","title":"Do not use \"extra restart distance\" on Simplify3d"},{"location":"Slicers.html#disable-preloadve-on-kisslicer","text":"If using KISSlicer slicing software then set \"PreloadVE\" to zero. Consider using Klipper's pressure advance instead.","title":"Disable \"PreloadVE\" on KISSlicer"},{"location":"Slicers.html#disable-any-advanced-extruder-pressure-settings","text":"Some slicers advertise an \"advanced extruder pressure\" capability. It is recommended to keep these options disabled when using Klipper as they are likely to result in poor quality prints. Consider using Klipper's pressure advance instead. Specifically, these slicer settings can instruct the firmware to make wild changes to the extrusion rate in the hope that the firmware will approximate those requests and the printer will roughly obtain a desirable extruder pressure. Klipper, however, utilizes precise kinematic calculations and timing. When Klipper is commanded to make significant changes to the extrusion rate it will plan out the corresponding changes to velocity, acceleration, and extruder movement - which is not the slicer's intent. The slicer may even command excessive extrusion rates to the point that it triggers Klipper's maximum extrusion cross-section check. In contrast, it is okay (and often helpful) to use a slicer's \"retract\" setting, \"wipe\" setting, and/or \"wipe on retract\" setting.","title":"Disable any \"advanced extruder pressure\" settings"},{"location":"Slicers.html#start_print-macros","text":"When using a START_PRINT macro or similar, it is useful to sometimes pass through parameters from the slicer variables to the macro. In Cura, to pass through temperatures, the following start gcode would be used: START_PRINT BED_TEMP={material_bed_temperature_layer_0} EXTRUDER_TEMP={material_print_temperature_layer_0} In slic3r derivatives such as PrusaSlicer and SuperSlicer, the following would be used: START_PRINT EXTRUDER_TEMP=[first_layer_temperature] BED_TEMP=[first_layer_bed_temperature] Also note that these slicers will insert their own heating codes when certain conditions are not met. In Cura, the existence of the {material_bed_temperature_layer_0} and {material_print_temperature_layer_0} variables is enough to mitigate this. In slic3r derivatives, you would use: M140 S0 M104 S0 before the macro call. Also note that SuperSlicer has a \"custom gcode only\" button option, which achieves the same outcome. An example of a START_PRINT macro using these parameters can be found in config/sample-macros.cfg","title":"START_PRINT macros"},{"location":"Sponsors.html","text":"Sponsors \u00b6 Klipper is Free Software. We depend on the generous support from sponsors. Please consider sponsoring Klipper or supporting our sponsors. BIGTREETECH \u00b6 BIGTREETECH is the official mainboard sponsor of Klipper. BIGTREETECH is committed to developing innovative and competitive products to serve the 3D printing community better. Follow them on Facebook or Twitter . Sponsors \u00b6 Klipper Developers \u00b6 Kevin O'Connor \u00b6 Kevin is the original author and current maintainer of Klipper. Donate at: https://ko-fi.com/koconnor or https://www.patreon.com/koconnor Eric Callahan \u00b6 Eric is the author of bed_mesh, spi_flash, and several other Klipper modules. Eric has a donations page at: https://ko-fi.com/arksine Related Klipper Projects \u00b6 Klipper is frequently used with other Free Software. Consider using or supporting these projects. Moonraker Mainsail Fluidd OctoPrint KlipperScreen","title":"Sponsors"},{"location":"Sponsors.html#sponsors","text":"Klipper is Free Software. We depend on the generous support from sponsors. Please consider sponsoring Klipper or supporting our sponsors.","title":"Sponsors"},{"location":"Sponsors.html#bigtreetech","text":"BIGTREETECH is the official mainboard sponsor of Klipper. BIGTREETECH is committed to developing innovative and competitive products to serve the 3D printing community better. Follow them on Facebook or Twitter .","title":"BIGTREETECH"},{"location":"Sponsors.html#sponsors_1","text":"","title":"Sponsors"},{"location":"Sponsors.html#klipper-developers","text":"","title":"Klipper Developers"},{"location":"Sponsors.html#kevin-oconnor","text":"Kevin is the original author and current maintainer of Klipper. Donate at: https://ko-fi.com/koconnor or https://www.patreon.com/koconnor","title":"Kevin O'Connor"},{"location":"Sponsors.html#eric-callahan","text":"Eric is the author of bed_mesh, spi_flash, and several other Klipper modules. Eric has a donations page at: https://ko-fi.com/arksine","title":"Eric Callahan"},{"location":"Sponsors.html#related-klipper-projects","text":"Klipper is frequently used with other Free Software. Consider using or supporting these projects. Moonraker Mainsail Fluidd OctoPrint KlipperScreen","title":"Related Klipper Projects"},{"location":"Status_Reference.html","text":"Status reference \u00b6 This document is a reference of printer status information available in Klipper macros , display fields , and via the API Server . The fields in this document are subject to change - if using an attribute be sure to review the Config Changes document when upgrading the Klipper software. angle \u00b6 The following information is available in angle some_name objects: temperature : The last temperature reading (in Celsius) from a tle5012b magnetic hall sensor. This value is only available if the angle sensor is a tle5012b chip and if measurements are in progress (otherwise it reports None ). bed_mesh \u00b6 The following information is available in the bed_mesh object: profile_name , mesh_min , mesh_max , probed_matrix , mesh_matrix : Information on the currently active bed_mesh. profiles : The set of currently defined profiles as setup using BED_MESH_PROFILE. bed_screws \u00b6 The following information is available in the bed_screws object: is_active : Returns True if the bed screws adjustment tool is currently active. state : The bed screws adjustment tool state. It is one of the following strings: \"adjust\", \"fine\". current_screw : The index for the current screw being adjusted. accepted_screws : The number of accepted screws. canbus_stats \u00b6 The following information is available in the canbus_stats some_mcu_name object (this object is automatically available if an mcu is configured to use canbus): rx_error : The number of receive errors detected by the micro-controller canbus hardware. tx_error : The number of transmit errors detected by the micro-controller canbus hardware. tx_retries : The number of transmit attempts that were retried due to bus contention or errors. bus_state : The status of the interface (typically \"active\" for a bus in normal operation, \"warn\" for a bus with recent errors, \"passive\" for a bus that will no longer transmit canbus error frames, or \"off\" for a bus that will no longer transmit or receive messages). Note that only the rp2XXX micro-controllers report a non-zero tx_retries field and the rp2XXX micro-controllers always report tx_error as zero and bus_state as \"active\". configfile \u00b6 The following information is available in the configfile object (this object is always available): settings.<section>.<option> : Returns the given config file setting (or default value) during the last software start or restart. (Any settings changed at run-time will not be reflected here.) config.<section>.<option> : Returns the given raw config file setting as read by Klipper during the last software start or restart. (Any settings changed at run-time will not be reflected here.) All values are returned as strings. save_config_pending : Returns true if there are updates that a SAVE_CONFIG command may persist to disk. save_config_pending_items : Contains the sections and options that were changed and would be persisted by a SAVE_CONFIG . warnings : A list of warnings about config options. Each entry in the list will be a dictionary containing a type and message field (both strings). Additional fields may be available depending on the type of warning. display_status \u00b6 The following information is available in the display_status object (this object is automatically available if a display config section is defined): progress : The progress value of the last M73 G-Code command (or virtual_sdcard.progress if no recent M73 received). message : The message contained in the last M117 G-Code command. endstop_phase \u00b6 The following information is available in the endstop_phase object: last_home.<stepper name>.phase : The phase of the stepper motor at the end of the last home attempt. last_home.<stepper name>.phases : The total number of phases available on the stepper motor. last_home.<stepper name>.mcu_position : The position (as tracked by the micro-controller) of the stepper motor at the end of the last home attempt. The position is the total number of steps taken in a forward direction minus the total number of steps taken in the reverse direction since the micro-controller was last restarted. exclude_object \u00b6 The following information is available in the exclude_object object: objects : An array of the known objects as provided by the EXCLUDE_OBJECT_DEFINE command. This is the same information provided by the EXCLUDE_OBJECT VERBOSE=1 command. The center and polygon fields will only be present if provided in the original EXCLUDE_OBJECT_DEFINE Here is a JSON sample: [ { \"polygon\": [ [ 156.25, 146.2511675 ], [ 156.25, 153.7488325 ], [ 163.75, 153.7488325 ], [ 163.75, 146.2511675 ] ], \"name\": \"CYLINDER_2_STL_ID_2_COPY_0\", \"center\": [ 160, 150 ] }, { \"polygon\": [ [ 146.25, 146.2511675 ], [ 146.25, 153.7488325 ], [ 153.75, 153.7488325 ], [ 153.75, 146.2511675 ] ], \"name\": \"CYLINDER_2_STL_ID_1_COPY_0\", \"center\": [ 150, 150 ] } ] excluded_objects : An array of strings listing the names of excluded objects. current_object : The name of the object currently being printed. extruder_stepper \u00b6 The following information is available for extruder_stepper objects (as well as extruder objects): pressure_advance : The current pressure advance value. smooth_time : The current pressure advance smooth time. motion_queue : The name of the extruder that this extruder stepper is currently synchronized to. This is reported as None if the extruder stepper is not currently associated with an extruder. fan \u00b6 The following information is available in fan , heater_fan some_name and controller_fan some_name objects: speed : The fan speed as a float between 0.0 and 1.0. rpm : The measured fan speed in rotations per minute if the fan has a tachometer_pin defined. filament_switch_sensor \u00b6 The following information is available in filament_switch_sensor some_name objects: enabled : Returns True if the switch sensor is currently enabled. filament_detected : Returns True if the sensor is in a triggered state. filament_motion_sensor \u00b6 The following information is available in filament_motion_sensor some_name objects: enabled : Returns True if the motion sensor is currently enabled. filament_detected : Returns True if the sensor is in a triggered state. firmware_retraction \u00b6 The following information is available in the firmware_retraction object: retract_length , retract_speed , unretract_extra_length , unretract_speed : The current settings for the firmware_retraction module. These settings may differ from the config file if a SET_RETRACTION command alters them. gcode \u00b6 The following information is available in the gcode object: commands : Returns a list of all currently available commands. For each command, if a help string is defined it will also be provided. gcode_button \u00b6 The following information is available in gcode_button some_name objects: state : The current button state returned as \"PRESSED\" or \"RELEASED\" gcode_macro \u00b6 The following information is available in gcode_macro some_name objects: <variable> : The current value of a gcode_macro variable . gcode_move \u00b6 The following information is available in the gcode_move object (this object is always available): gcode_position : The current position of the toolhead relative to the current G-Code origin. That is, positions that one might directly send to a G1 command. It is possible to access the x, y, z, and e components of this position (eg, gcode_position.x ). position : The last commanded position of the toolhead using the coordinate system specified in the config file. It is possible to access the x, y, z, and e components of this position (eg, position.x ). homing_origin : The origin of the gcode coordinate system (relative to the coordinate system specified in the config file) to use after a G28 command. The SET_GCODE_OFFSET command can alter this position. It is possible to access the x, y, and z components of this position (eg, homing_origin.x ). speed : The last speed set in a G1 command (in mm/s). speed_factor : The \"speed factor override\" as set by an M220 command. This is a floating point value such that 1.0 means no override and, for example, 2.0 would double requested speed. extrude_factor : The \"extrude factor override\" as set by an M221 command. This is a floating point value such that 1.0 means no override and, for example, 2.0 would double requested extrusions. absolute_coordinates : This returns True if in G90 absolute coordinate mode or False if in G91 relative mode. absolute_extrude : This returns True if in M82 absolute extrude mode or False if in M83 relative mode. hall_filament_width_sensor \u00b6 The following information is available in the hall_filament_width_sensor object: all items from filament_switch_sensor is_active : Returns True if the sensor is currently active. Diameter : The last reading from the sensor in mm. Raw : The last raw ADC reading from the sensor. heater \u00b6 The following information is available for heater objects such as extruder , heater_bed , and heater_generic : temperature : The last reported temperature (in Celsius as a float) for the given heater. target : The current target temperature (in Celsius as a float) for the given heater. power : The last setting of the PWM pin (a value between 0.0 and 1.0) associated with the heater. can_extrude : If extruder can extrude (defined by min_extrude_temp ), available only for extruder heaters \u00b6 The following information is available in the heaters object (this object is available if any heater is defined): available_heaters : Returns a list of all currently available heaters by their full config section names, e.g. [\"extruder\", \"heater_bed\", \"heater_generic my_custom_heater\"] . available_sensors : Returns a list of all currently available temperature sensors by their full config section names, e.g. [\"extruder\", \"heater_bed\", \"heater_generic my_custom_heater\", \"temperature_sensor electronics_temp\"] . available_monitors : Returns a list of all currently available temperature monitors by their full config section names, e.g. [\"tmc2240 stepper_x\"] . While a temperature sensor is always available to read, a temperature monitor may not be available and will return null in such case. idle_timeout \u00b6 The following information is available in the idle_timeout object (this object is always available): state : The current state of the printer as tracked by the idle_timeout module. It is one of the following strings: \"Idle\", \"Printing\", \"Ready\". printing_time : The amount of time (in seconds) the printer has been in the \"Printing\" state (as tracked by the idle_timeout module). idle_timeout : The current 'timeout' (in seconds) to wait for the gcode to be triggered. (as set by SET_IDLE_TIMEOUT ) led \u00b6 The following information is available for each [led led_name] , [neopixel led_name] , [dotstar led_name] , [pca9533 led_name] , and [pca9632 led_name] config section defined in printer.cfg: color_data : A list of color lists containing the RGBW values for a led in the chain. Each value is represented as a float from 0.0 to 1.0. Each color list contains 4 items (red, green, blue, white) even if the underlying LED supports fewer color channels. For example, the blue value (3rd item in color list) of the second neopixel in a chain could be accessed at printer[\"neopixel <config_name>\"].color_data[1][2] . load_cell \u00b6 The following information is available for each [load_cell name] : 'is_calibrated': True/False is the load cell calibrated 'counts_per_gram': The number of raw sensor counts that equals 1 gram of force 'reference_tare_counts': The reference number of raw sensor counts for 0 force 'tare_counts': The current number of raw sensor counts for 0 force 'force_g': The force in grams, averaged over the last polling period. 'min_force_g': The minimum force in grams, over the last polling period. 'max_force_g': The maximum force in grams, over the last polling period. load_cell_probe \u00b6 The following information is available for [load_cell_probe] : all items from load_cell all items from probe 'endstop_tare_counts': the load cell probe keeps a tare value independent of the load cell. This re-set at the start of each probe. 'last_trigger_time': timestamp of the last homing trigger manual_probe \u00b6 The following information is available in the manual_probe object: is_active : Returns True if a manual probing helper script is currently active. z_position : The current height of the nozzle (as the printer currently understands it). z_position_lower : Last probe attempt just lower than the current height. z_position_upper : Last probe attempt just greater than the current height. mcu \u00b6 The following information is available in mcu and mcu some_name objects: mcu_version : The Klipper code version reported by the micro-controller. mcu_build_versions : Information on the build tools used to generate the micro-controller code (as reported by the micro-controller). mcu_constants.<constant_name> : Compile time constants reported by the micro-controller. The available constants may differ between micro-controller architectures and with each code revision. last_stats.<statistics_name> : Statistics information on the micro-controller connection. motion_report \u00b6 The following information is available in the motion_report object (this object is automatically available if any stepper config section is defined): live_position : The requested toolhead position interpolated to the current time. live_velocity : The requested toolhead velocity (in mm/s) at the current time. live_extruder_velocity : The requested extruder velocity (in mm/s) at the current time. output_pin \u00b6 The following information is available in output_pin some_name and pwm_tool some_name objects: value : The \"value\" of the pin, as set by a SET_PIN command. palette2 \u00b6 The following information is available in the palette2 object: ping : Amount of the last reported Palette 2 ping in percent. remaining_load_length : When starting a Palette 2 print, this will be the amount of filament to load into the extruder. is_splicing : True when the Palette 2 is splicing filament. pause_resume \u00b6 The following information is available in the pause_resume object: is_paused : Returns true if a PAUSE command has been executed without a corresponding RESUME. print_stats \u00b6 The following information is available in the print_stats object (this object is automatically available if a virtual_sdcard config section is defined): filename , total_duration , print_duration , filament_used , state , message : Estimated information about the current print when a virtual_sdcard print is active. info.total_layer : The total layer value of the last SET_PRINT_STATS_INFO TOTAL_LAYER=<value> G-Code command. info.current_layer : The current layer value of the last SET_PRINT_STATS_INFO CURRENT_LAYER=<value> G-Code command. probe \u00b6 The following information is available in the probe object (this object is also available if a bltouch config section is defined): name : Returns the name of the probe in use. last_query : Returns True if the probe was reported as \"triggered\" during the last QUERY_PROBE command. Note, if this is used in a macro, due to the order of template expansion, the QUERY_PROBE command must be run prior to the macro containing this reference. last_z_result : Returns the Z result value of the last PROBE command. Note, if this is used in a macro, due to the order of template expansion, the PROBE (or similar) command must be run prior to the macro containing this reference. pwm_cycle_time \u00b6 The following information is available in pwm_cycle_time some_name objects: value : The \"value\" of the pin, as set by a SET_PIN command. quad_gantry_level \u00b6 The following information is available in the quad_gantry_level object (this object is available if quad_gantry_level is defined): applied : True if the gantry leveling process has been run and completed successfully. query_endstops \u00b6 The following information is available in the query_endstops object (this object is available if any endstop is defined): last_query[\"<endstop>\"] : Returns True if the given endstop was reported as \"triggered\" during the last QUERY_ENDSTOP command. Note, if this is used in a macro, due to the order of template expansion, the QUERY_ENDSTOP command must be run prior to the macro containing this reference. screws_tilt_adjust \u00b6 The following information is available in the screws_tilt_adjust object: error : Returns True if the most recent SCREWS_TILT_CALCULATE command included the MAX_DEVIATION parameter and any of the probed screw points exceeded the specified MAX_DEVIATION . max_deviation : Return the last MAX_DEVIATION value of the most recent SCREWS_TILT_CALCULATE command. results[\"<screw>\"] : A dictionary containing the following keys: z : The measured Z height of the screw location. sign : A string specifying the direction to turn to screw for the necessary adjustment. Either \"CW\" for clockwise or \"CCW\" for counterclockwise. adjust : The number of screw turns to adjust the screw, given in the format \"HH:MM,\" where \"HH\" is the number of full screw turns and \"MM\" is the number of \"minutes of a clock face\" representing a partial screw turn. (E.g. \"01:15\" would mean to turn the screw one and a quarter revolutions.) is_base : Returns True if this is the base screw. servo \u00b6 The following information is available in servo some_name objects: printer[\"servo <config_name>\"].value : The last setting of the PWM pin (a value between 0.0 and 1.0) associated with the servo. skew_correction.py \u00b6 The following information is available in the skew_correction object (this object is available if any skew_correction is defined): current_profile_name : Returns the name of the currently loaded SKEW_PROFILE. stepper_enable \u00b6 The following information is available in the stepper_enable object (this object is available if any stepper is defined): steppers[\"<stepper>\"] : Returns True if the given stepper is enabled. system_stats \u00b6 The following information is available in the system_stats object (this object is always available): sysload , cputime , memavail : Information on the host operating system and process load. temperature sensors \u00b6 The following information is available in bme280 config_section_name , htu21d config_section_name , sht3x config_section_name , lm75 config_section_name , temperature_host config_section_name and temperature_combined config_section_name objects: temperature : The last read temperature from the sensor. humidity , pressure , gas : The last read values from the sensor (only on bme280, htu21d, sht3x and lm75 sensors). temperature_fan \u00b6 The following information is available in temperature_fan some_name objects: temperature : The last read temperature from the sensor. target : The target temperature for the fan. temperature_sensor \u00b6 The following information is available in temperature_sensor some_name objects: temperature : The last read temperature from the sensor. measured_min_temp , measured_max_temp : The lowest and highest temperature seen by the sensor since the Klipper host software was last restarted. tmc drivers \u00b6 The following information is available in TMC stepper driver objects (eg, [tmc2208 stepper_x] ): mcu_phase_offset : The micro-controller stepper position corresponding with the driver's \"zero\" phase. This field may be null if the phase offset is not known. phase_offset_position : The \"commanded position\" corresponding to the driver's \"zero\" phase. This field may be null if the phase offset is not known. drv_status : The results of the last driver status query. (Only non-zero fields are reported.) This field will be null if the driver is not enabled (and thus is not periodically queried). temperature : The internal temperature reported by the driver. This field will be null if the driver is not enabled or if the driver does not support temperature reporting. run_current : The currently set run current. hold_current : The currently set hold current. toolhead \u00b6 The following information is available in the toolhead object (this object is always available): position : The last commanded position of the toolhead relative to the coordinate system specified in the config file. It is possible to access the x, y, z, and e components of this position (eg, position.x ). extruder : The name of the currently active extruder. For example, in a macro one could use printer[printer.toolhead.extruder].target to get the target temperature of the current extruder. homed_axes : The current cartesian axes considered to be in a \"homed\" state. This is a string containing one or more of \"x\", \"y\", \"z\". axis_minimum , axis_maximum : The axis travel limits (mm) after homing. It is possible to access the x, y, z components of this limit value (eg, axis_minimum.x , axis_maximum.z ). For Delta printers the cone_start_z is the max z height at maximum radius ( printer.toolhead.cone_start_z ). max_velocity , max_accel , minimum_cruise_ratio , square_corner_velocity : The current printing limits that are in effect. This may differ from the config file settings if a SET_VELOCITY_LIMIT (or M204 ) command alters them at run-time. stalls : The total number of times (since the last restart) that the printer had to be paused because the toolhead moved faster than moves could be read from the G-Code input. dual_carriage \u00b6 The following information is available in dual_carriage on a cartesian, hybrid_corexy or hybrid_corexz robot carriage_0 : The mode of the carriage 0. Possible values are: \"INACTIVE\" and \"PRIMARY\". carriage_1 : The mode of the carriage 1. Possible values are: \"INACTIVE\", \"PRIMARY\", \"COPY\", and \"MIRROR\". On a generic_cartesian kinematic, the following information is available in dual_carriage : carriages[\"<carriage>\"] : The mode of the carriage <carriage> . Possible values are \"INACTIVE\" and \"PRIMARY\" for the primary carriage and \"INACTIVE\", \"PRIMARY\", \"COPY\", and \"MIRROR\" for the dual carriage. virtual_sdcard \u00b6 The following information is available in the virtual_sdcard object: is_active : Returns True if a print from file is currently active. progress : An estimate of the current print progress (based of file size and file position). file_path : A full path to the file of currently loaded file. file_position : The current position (in bytes) of an active print. file_size : The file size (in bytes) of currently loaded file. webhooks \u00b6 The following information is available in the webhooks object (this object is always available): state : Returns a string indicating the current Klipper state. Possible values are: \"ready\", \"startup\", \"shutdown\", \"error\". state_message : A human readable string giving additional context on the current Klipper state. z_thermal_adjust \u00b6 The following information is available in the z_thermal_adjust object (this object is available if z_thermal_adjust is defined). enabled : Returns True if adjustment is enabled. temperature : Current (smoothed) temperature of the defined sensor. [degC] measured_min_temp : Minimum measured temperature. [degC] measured_max_temp : Maximum measured temperature. [degC] current_z_adjust : Last computed Z adjustment [mm]. z_adjust_ref_temperature : Current reference temperature used for calculation of Z current_z_adjust [degC]. z_tilt \u00b6 The following information is available in the z_tilt object (this object is available if z_tilt is defined): applied : True if the z-tilt leveling process has been run and completed successfully.","title":"Status reference"},{"location":"Status_Reference.html#status-reference","text":"This document is a reference of printer status information available in Klipper macros , display fields , and via the API Server . The fields in this document are subject to change - if using an attribute be sure to review the Config Changes document when upgrading the Klipper software.","title":"Status reference"},{"location":"Status_Reference.html#angle","text":"The following information is available in angle some_name objects: temperature : The last temperature reading (in Celsius) from a tle5012b magnetic hall sensor. This value is only available if the angle sensor is a tle5012b chip and if measurements are in progress (otherwise it reports None ).","title":"angle"},{"location":"Status_Reference.html#bed_mesh","text":"The following information is available in the bed_mesh object: profile_name , mesh_min , mesh_max , probed_matrix , mesh_matrix : Information on the currently active bed_mesh. profiles : The set of currently defined profiles as setup using BED_MESH_PROFILE.","title":"bed_mesh"},{"location":"Status_Reference.html#bed_screws","text":"The following information is available in the bed_screws object: is_active : Returns True if the bed screws adjustment tool is currently active. state : The bed screws adjustment tool state. It is one of the following strings: \"adjust\", \"fine\". current_screw : The index for the current screw being adjusted. accepted_screws : The number of accepted screws.","title":"bed_screws"},{"location":"Status_Reference.html#canbus_stats","text":"The following information is available in the canbus_stats some_mcu_name object (this object is automatically available if an mcu is configured to use canbus): rx_error : The number of receive errors detected by the micro-controller canbus hardware. tx_error : The number of transmit errors detected by the micro-controller canbus hardware. tx_retries : The number of transmit attempts that were retried due to bus contention or errors. bus_state : The status of the interface (typically \"active\" for a bus in normal operation, \"warn\" for a bus with recent errors, \"passive\" for a bus that will no longer transmit canbus error frames, or \"off\" for a bus that will no longer transmit or receive messages). Note that only the rp2XXX micro-controllers report a non-zero tx_retries field and the rp2XXX micro-controllers always report tx_error as zero and bus_state as \"active\".","title":"canbus_stats"},{"location":"Status_Reference.html#configfile","text":"The following information is available in the configfile object (this object is always available): settings.<section>.<option> : Returns the given config file setting (or default value) during the last software start or restart. (Any settings changed at run-time will not be reflected here.) config.<section>.<option> : Returns the given raw config file setting as read by Klipper during the last software start or restart. (Any settings changed at run-time will not be reflected here.) All values are returned as strings. save_config_pending : Returns true if there are updates that a SAVE_CONFIG command may persist to disk. save_config_pending_items : Contains the sections and options that were changed and would be persisted by a SAVE_CONFIG . warnings : A list of warnings about config options. Each entry in the list will be a dictionary containing a type and message field (both strings). Additional fields may be available depending on the type of warning.","title":"configfile"},{"location":"Status_Reference.html#display_status","text":"The following information is available in the display_status object (this object is automatically available if a display config section is defined): progress : The progress value of the last M73 G-Code command (or virtual_sdcard.progress if no recent M73 received). message : The message contained in the last M117 G-Code command.","title":"display_status"},{"location":"Status_Reference.html#endstop_phase","text":"The following information is available in the endstop_phase object: last_home.<stepper name>.phase : The phase of the stepper motor at the end of the last home attempt. last_home.<stepper name>.phases : The total number of phases available on the stepper motor. last_home.<stepper name>.mcu_position : The position (as tracked by the micro-controller) of the stepper motor at the end of the last home attempt. The position is the total number of steps taken in a forward direction minus the total number of steps taken in the reverse direction since the micro-controller was last restarted.","title":"endstop_phase"},{"location":"Status_Reference.html#exclude_object","text":"The following information is available in the exclude_object object: objects : An array of the known objects as provided by the EXCLUDE_OBJECT_DEFINE command. This is the same information provided by the EXCLUDE_OBJECT VERBOSE=1 command. The center and polygon fields will only be present if provided in the original EXCLUDE_OBJECT_DEFINE Here is a JSON sample: [ { \"polygon\": [ [ 156.25, 146.2511675 ], [ 156.25, 153.7488325 ], [ 163.75, 153.7488325 ], [ 163.75, 146.2511675 ] ], \"name\": \"CYLINDER_2_STL_ID_2_COPY_0\", \"center\": [ 160, 150 ] }, { \"polygon\": [ [ 146.25, 146.2511675 ], [ 146.25, 153.7488325 ], [ 153.75, 153.7488325 ], [ 153.75, 146.2511675 ] ], \"name\": \"CYLINDER_2_STL_ID_1_COPY_0\", \"center\": [ 150, 150 ] } ] excluded_objects : An array of strings listing the names of excluded objects. current_object : The name of the object currently being printed.","title":"exclude_object"},{"location":"Status_Reference.html#extruder_stepper","text":"The following information is available for extruder_stepper objects (as well as extruder objects): pressure_advance : The current pressure advance value. smooth_time : The current pressure advance smooth time. motion_queue : The name of the extruder that this extruder stepper is currently synchronized to. This is reported as None if the extruder stepper is not currently associated with an extruder.","title":"extruder_stepper"},{"location":"Status_Reference.html#fan","text":"The following information is available in fan , heater_fan some_name and controller_fan some_name objects: speed : The fan speed as a float between 0.0 and 1.0. rpm : The measured fan speed in rotations per minute if the fan has a tachometer_pin defined.","title":"fan"},{"location":"Status_Reference.html#filament_switch_sensor","text":"The following information is available in filament_switch_sensor some_name objects: enabled : Returns True if the switch sensor is currently enabled. filament_detected : Returns True if the sensor is in a triggered state.","title":"filament_switch_sensor"},{"location":"Status_Reference.html#filament_motion_sensor","text":"The following information is available in filament_motion_sensor some_name objects: enabled : Returns True if the motion sensor is currently enabled. filament_detected : Returns True if the sensor is in a triggered state.","title":"filament_motion_sensor"},{"location":"Status_Reference.html#firmware_retraction","text":"The following information is available in the firmware_retraction object: retract_length , retract_speed , unretract_extra_length , unretract_speed : The current settings for the firmware_retraction module. These settings may differ from the config file if a SET_RETRACTION command alters them.","title":"firmware_retraction"},{"location":"Status_Reference.html#gcode","text":"The following information is available in the gcode object: commands : Returns a list of all currently available commands. For each command, if a help string is defined it will also be provided.","title":"gcode"},{"location":"Status_Reference.html#gcode_button","text":"The following information is available in gcode_button some_name objects: state : The current button state returned as \"PRESSED\" or \"RELEASED\"","title":"gcode_button"},{"location":"Status_Reference.html#gcode_macro","text":"The following information is available in gcode_macro some_name objects: <variable> : The current value of a gcode_macro variable .","title":"gcode_macro"},{"location":"Status_Reference.html#gcode_move","text":"The following information is available in the gcode_move object (this object is always available): gcode_position : The current position of the toolhead relative to the current G-Code origin. That is, positions that one might directly send to a G1 command. It is possible to access the x, y, z, and e components of this position (eg, gcode_position.x ). position : The last commanded position of the toolhead using the coordinate system specified in the config file. It is possible to access the x, y, z, and e components of this position (eg, position.x ). homing_origin : The origin of the gcode coordinate system (relative to the coordinate system specified in the config file) to use after a G28 command. The SET_GCODE_OFFSET command can alter this position. It is possible to access the x, y, and z components of this position (eg, homing_origin.x ). speed : The last speed set in a G1 command (in mm/s). speed_factor : The \"speed factor override\" as set by an M220 command. This is a floating point value such that 1.0 means no override and, for example, 2.0 would double requested speed. extrude_factor : The \"extrude factor override\" as set by an M221 command. This is a floating point value such that 1.0 means no override and, for example, 2.0 would double requested extrusions. absolute_coordinates : This returns True if in G90 absolute coordinate mode or False if in G91 relative mode. absolute_extrude : This returns True if in M82 absolute extrude mode or False if in M83 relative mode.","title":"gcode_move"},{"location":"Status_Reference.html#hall_filament_width_sensor","text":"The following information is available in the hall_filament_width_sensor object: all items from filament_switch_sensor is_active : Returns True if the sensor is currently active. Diameter : The last reading from the sensor in mm. Raw : The last raw ADC reading from the sensor.","title":"hall_filament_width_sensor"},{"location":"Status_Reference.html#heater","text":"The following information is available for heater objects such as extruder , heater_bed , and heater_generic : temperature : The last reported temperature (in Celsius as a float) for the given heater. target : The current target temperature (in Celsius as a float) for the given heater. power : The last setting of the PWM pin (a value between 0.0 and 1.0) associated with the heater. can_extrude : If extruder can extrude (defined by min_extrude_temp ), available only for extruder","title":"heater"},{"location":"Status_Reference.html#heaters","text":"The following information is available in the heaters object (this object is available if any heater is defined): available_heaters : Returns a list of all currently available heaters by their full config section names, e.g. [\"extruder\", \"heater_bed\", \"heater_generic my_custom_heater\"] . available_sensors : Returns a list of all currently available temperature sensors by their full config section names, e.g. [\"extruder\", \"heater_bed\", \"heater_generic my_custom_heater\", \"temperature_sensor electronics_temp\"] . available_monitors : Returns a list of all currently available temperature monitors by their full config section names, e.g. [\"tmc2240 stepper_x\"] . While a temperature sensor is always available to read, a temperature monitor may not be available and will return null in such case.","title":"heaters"},{"location":"Status_Reference.html#idle_timeout","text":"The following information is available in the idle_timeout object (this object is always available): state : The current state of the printer as tracked by the idle_timeout module. It is one of the following strings: \"Idle\", \"Printing\", \"Ready\". printing_time : The amount of time (in seconds) the printer has been in the \"Printing\" state (as tracked by the idle_timeout module). idle_timeout : The current 'timeout' (in seconds) to wait for the gcode to be triggered. (as set by SET_IDLE_TIMEOUT )","title":"idle_timeout"},{"location":"Status_Reference.html#led","text":"The following information is available for each [led led_name] , [neopixel led_name] , [dotstar led_name] , [pca9533 led_name] , and [pca9632 led_name] config section defined in printer.cfg: color_data : A list of color lists containing the RGBW values for a led in the chain. Each value is represented as a float from 0.0 to 1.0. Each color list contains 4 items (red, green, blue, white) even if the underlying LED supports fewer color channels. For example, the blue value (3rd item in color list) of the second neopixel in a chain could be accessed at printer[\"neopixel <config_name>\"].color_data[1][2] .","title":"led"},{"location":"Status_Reference.html#load_cell","text":"The following information is available for each [load_cell name] : 'is_calibrated': True/False is the load cell calibrated 'counts_per_gram': The number of raw sensor counts that equals 1 gram of force 'reference_tare_counts': The reference number of raw sensor counts for 0 force 'tare_counts': The current number of raw sensor counts for 0 force 'force_g': The force in grams, averaged over the last polling period. 'min_force_g': The minimum force in grams, over the last polling period. 'max_force_g': The maximum force in grams, over the last polling period.","title":"load_cell"},{"location":"Status_Reference.html#load_cell_probe","text":"The following information is available for [load_cell_probe] : all items from load_cell all items from probe 'endstop_tare_counts': the load cell probe keeps a tare value independent of the load cell. This re-set at the start of each probe. 'last_trigger_time': timestamp of the last homing trigger","title":"load_cell_probe"},{"location":"Status_Reference.html#manual_probe","text":"The following information is available in the manual_probe object: is_active : Returns True if a manual probing helper script is currently active. z_position : The current height of the nozzle (as the printer currently understands it). z_position_lower : Last probe attempt just lower than the current height. z_position_upper : Last probe attempt just greater than the current height.","title":"manual_probe"},{"location":"Status_Reference.html#mcu","text":"The following information is available in mcu and mcu some_name objects: mcu_version : The Klipper code version reported by the micro-controller. mcu_build_versions : Information on the build tools used to generate the micro-controller code (as reported by the micro-controller). mcu_constants.<constant_name> : Compile time constants reported by the micro-controller. The available constants may differ between micro-controller architectures and with each code revision. last_stats.<statistics_name> : Statistics information on the micro-controller connection.","title":"mcu"},{"location":"Status_Reference.html#motion_report","text":"The following information is available in the motion_report object (this object is automatically available if any stepper config section is defined): live_position : The requested toolhead position interpolated to the current time. live_velocity : The requested toolhead velocity (in mm/s) at the current time. live_extruder_velocity : The requested extruder velocity (in mm/s) at the current time.","title":"motion_report"},{"location":"Status_Reference.html#output_pin","text":"The following information is available in output_pin some_name and pwm_tool some_name objects: value : The \"value\" of the pin, as set by a SET_PIN command.","title":"output_pin"},{"location":"Status_Reference.html#palette2","text":"The following information is available in the palette2 object: ping : Amount of the last reported Palette 2 ping in percent. remaining_load_length : When starting a Palette 2 print, this will be the amount of filament to load into the extruder. is_splicing : True when the Palette 2 is splicing filament.","title":"palette2"},{"location":"Status_Reference.html#pause_resume","text":"The following information is available in the pause_resume object: is_paused : Returns true if a PAUSE command has been executed without a corresponding RESUME.","title":"pause_resume"},{"location":"Status_Reference.html#print_stats","text":"The following information is available in the print_stats object (this object is automatically available if a virtual_sdcard config section is defined): filename , total_duration , print_duration , filament_used , state , message : Estimated information about the current print when a virtual_sdcard print is active. info.total_layer : The total layer value of the last SET_PRINT_STATS_INFO TOTAL_LAYER=<value> G-Code command. info.current_layer : The current layer value of the last SET_PRINT_STATS_INFO CURRENT_LAYER=<value> G-Code command.","title":"print_stats"},{"location":"Status_Reference.html#probe","text":"The following information is available in the probe object (this object is also available if a bltouch config section is defined): name : Returns the name of the probe in use. last_query : Returns True if the probe was reported as \"triggered\" during the last QUERY_PROBE command. Note, if this is used in a macro, due to the order of template expansion, the QUERY_PROBE command must be run prior to the macro containing this reference. last_z_result : Returns the Z result value of the last PROBE command. Note, if this is used in a macro, due to the order of template expansion, the PROBE (or similar) command must be run prior to the macro containing this reference.","title":"probe"},{"location":"Status_Reference.html#pwm_cycle_time","text":"The following information is available in pwm_cycle_time some_name objects: value : The \"value\" of the pin, as set by a SET_PIN command.","title":"pwm_cycle_time"},{"location":"Status_Reference.html#quad_gantry_level","text":"The following information is available in the quad_gantry_level object (this object is available if quad_gantry_level is defined): applied : True if the gantry leveling process has been run and completed successfully.","title":"quad_gantry_level"},{"location":"Status_Reference.html#query_endstops","text":"The following information is available in the query_endstops object (this object is available if any endstop is defined): last_query[\"<endstop>\"] : Returns True if the given endstop was reported as \"triggered\" during the last QUERY_ENDSTOP command. Note, if this is used in a macro, due to the order of template expansion, the QUERY_ENDSTOP command must be run prior to the macro containing this reference.","title":"query_endstops"},{"location":"Status_Reference.html#screws_tilt_adjust","text":"The following information is available in the screws_tilt_adjust object: error : Returns True if the most recent SCREWS_TILT_CALCULATE command included the MAX_DEVIATION parameter and any of the probed screw points exceeded the specified MAX_DEVIATION . max_deviation : Return the last MAX_DEVIATION value of the most recent SCREWS_TILT_CALCULATE command. results[\"<screw>\"] : A dictionary containing the following keys: z : The measured Z height of the screw location. sign : A string specifying the direction to turn to screw for the necessary adjustment. Either \"CW\" for clockwise or \"CCW\" for counterclockwise. adjust : The number of screw turns to adjust the screw, given in the format \"HH:MM,\" where \"HH\" is the number of full screw turns and \"MM\" is the number of \"minutes of a clock face\" representing a partial screw turn. (E.g. \"01:15\" would mean to turn the screw one and a quarter revolutions.) is_base : Returns True if this is the base screw.","title":"screws_tilt_adjust"},{"location":"Status_Reference.html#servo","text":"The following information is available in servo some_name objects: printer[\"servo <config_name>\"].value : The last setting of the PWM pin (a value between 0.0 and 1.0) associated with the servo.","title":"servo"},{"location":"Status_Reference.html#skew_correctionpy","text":"The following information is available in the skew_correction object (this object is available if any skew_correction is defined): current_profile_name : Returns the name of the currently loaded SKEW_PROFILE.","title":"skew_correction.py"},{"location":"Status_Reference.html#stepper_enable","text":"The following information is available in the stepper_enable object (this object is available if any stepper is defined): steppers[\"<stepper>\"] : Returns True if the given stepper is enabled.","title":"stepper_enable"},{"location":"Status_Reference.html#system_stats","text":"The following information is available in the system_stats object (this object is always available): sysload , cputime , memavail : Information on the host operating system and process load.","title":"system_stats"},{"location":"Status_Reference.html#temperature-sensors","text":"The following information is available in bme280 config_section_name , htu21d config_section_name , sht3x config_section_name , lm75 config_section_name , temperature_host config_section_name and temperature_combined config_section_name objects: temperature : The last read temperature from the sensor. humidity , pressure , gas : The last read values from the sensor (only on bme280, htu21d, sht3x and lm75 sensors).","title":"temperature sensors"},{"location":"Status_Reference.html#temperature_fan","text":"The following information is available in temperature_fan some_name objects: temperature : The last read temperature from the sensor. target : The target temperature for the fan.","title":"temperature_fan"},{"location":"Status_Reference.html#temperature_sensor","text":"The following information is available in temperature_sensor some_name objects: temperature : The last read temperature from the sensor. measured_min_temp , measured_max_temp : The lowest and highest temperature seen by the sensor since the Klipper host software was last restarted.","title":"temperature_sensor"},{"location":"Status_Reference.html#tmc-drivers","text":"The following information is available in TMC stepper driver objects (eg, [tmc2208 stepper_x] ): mcu_phase_offset : The micro-controller stepper position corresponding with the driver's \"zero\" phase. This field may be null if the phase offset is not known. phase_offset_position : The \"commanded position\" corresponding to the driver's \"zero\" phase. This field may be null if the phase offset is not known. drv_status : The results of the last driver status query. (Only non-zero fields are reported.) This field will be null if the driver is not enabled (and thus is not periodically queried). temperature : The internal temperature reported by the driver. This field will be null if the driver is not enabled or if the driver does not support temperature reporting. run_current : The currently set run current. hold_current : The currently set hold current.","title":"tmc drivers"},{"location":"Status_Reference.html#toolhead","text":"The following information is available in the toolhead object (this object is always available): position : The last commanded position of the toolhead relative to the coordinate system specified in the config file. It is possible to access the x, y, z, and e components of this position (eg, position.x ). extruder : The name of the currently active extruder. For example, in a macro one could use printer[printer.toolhead.extruder].target to get the target temperature of the current extruder. homed_axes : The current cartesian axes considered to be in a \"homed\" state. This is a string containing one or more of \"x\", \"y\", \"z\". axis_minimum , axis_maximum : The axis travel limits (mm) after homing. It is possible to access the x, y, z components of this limit value (eg, axis_minimum.x , axis_maximum.z ). For Delta printers the cone_start_z is the max z height at maximum radius ( printer.toolhead.cone_start_z ). max_velocity , max_accel , minimum_cruise_ratio , square_corner_velocity : The current printing limits that are in effect. This may differ from the config file settings if a SET_VELOCITY_LIMIT (or M204 ) command alters them at run-time. stalls : The total number of times (since the last restart) that the printer had to be paused because the toolhead moved faster than moves could be read from the G-Code input.","title":"toolhead"},{"location":"Status_Reference.html#dual_carriage","text":"The following information is available in dual_carriage on a cartesian, hybrid_corexy or hybrid_corexz robot carriage_0 : The mode of the carriage 0. Possible values are: \"INACTIVE\" and \"PRIMARY\". carriage_1 : The mode of the carriage 1. Possible values are: \"INACTIVE\", \"PRIMARY\", \"COPY\", and \"MIRROR\". On a generic_cartesian kinematic, the following information is available in dual_carriage : carriages[\"<carriage>\"] : The mode of the carriage <carriage> . Possible values are \"INACTIVE\" and \"PRIMARY\" for the primary carriage and \"INACTIVE\", \"PRIMARY\", \"COPY\", and \"MIRROR\" for the dual carriage.","title":"dual_carriage"},{"location":"Status_Reference.html#virtual_sdcard","text":"The following information is available in the virtual_sdcard object: is_active : Returns True if a print from file is currently active. progress : An estimate of the current print progress (based of file size and file position). file_path : A full path to the file of currently loaded file. file_position : The current position (in bytes) of an active print. file_size : The file size (in bytes) of currently loaded file.","title":"virtual_sdcard"},{"location":"Status_Reference.html#webhooks","text":"The following information is available in the webhooks object (this object is always available): state : Returns a string indicating the current Klipper state. Possible values are: \"ready\", \"startup\", \"shutdown\", \"error\". state_message : A human readable string giving additional context on the current Klipper state.","title":"webhooks"},{"location":"Status_Reference.html#z_thermal_adjust","text":"The following information is available in the z_thermal_adjust object (this object is available if z_thermal_adjust is defined). enabled : Returns True if adjustment is enabled. temperature : Current (smoothed) temperature of the defined sensor. [degC] measured_min_temp : Minimum measured temperature. [degC] measured_max_temp : Maximum measured temperature. [degC] current_z_adjust : Last computed Z adjustment [mm]. z_adjust_ref_temperature : Current reference temperature used for calculation of Z current_z_adjust [degC].","title":"z_thermal_adjust"},{"location":"Status_Reference.html#z_tilt","text":"The following information is available in the z_tilt object (this object is available if z_tilt is defined): applied : True if the z-tilt leveling process has been run and completed successfully.","title":"z_tilt"},{"location":"TMC_Drivers.html","text":"TMC drivers \u00b6 This document provides information on using Trinamic stepper motor drivers in SPI/UART mode on Klipper. Klipper can also use Trinamic drivers in their \"standalone mode\". However, when the drivers are in this mode, no special Klipper configuration is needed and the advanced Klipper features discussed in this document are not available. In addition to this document, be sure to review the TMC driver config reference . Tuning motor current \u00b6 A higher driver current increases positional accuracy and torque. However, a higher current also increases the heat produced by the stepper motor and the stepper motor driver. If the stepper motor driver gets too hot it will disable itself and Klipper will report an error. If the stepper motor gets too hot, it loses torque and positional accuracy. (If it gets very hot it may also melt plastic parts attached to it or near it.) As a general tuning tip, prefer higher current values as long as the stepper motor does not get too hot and the stepper motor driver does not report warnings or errors. In general, it is okay for the stepper motor to feel warm, but it should not become so hot that it is painful to touch. Prefer to not specify a hold_current \u00b6 If one configures a hold_current then the TMC driver can reduce current to the stepper motor when it detects that the stepper is not moving. However, changing motor current may itself introduce motor movement. This may occur due to \"detent forces\" within the stepper motor (the permanent magnet in the rotor pulls towards the iron teeth in the stator) or due to external forces on the axis carriage. Most stepper motors will not obtain a significant benefit to reducing current during normal prints, because few printing moves will leave a stepper motor idle for sufficiently long to activate the hold_current feature. And, it is unlikely that one would want to introduce subtle print artifacts to the few printing moves that do leave a stepper idle sufficiently long. If one wishes to reduce current to motors during print start routines, then consider issuing SET_TMC_CURRENT commands in a START_PRINT macro to adjust the current before and after normal printing moves. Some printers with dedicated Z motors that are idle during normal printing moves (no bed_mesh, no bed_tilt, no Z skew_correction, no \"vase mode\" prints, etc.) may find that Z motors do run cooler with a hold_current . If implementing this then be sure to take into account this type of uncommanded Z axis movement during bed leveling, bed probing, probe calibration, and similar. The driver_TPOWERDOWN and driver_IHOLDDELAY should also be calibrated accordingly. If unsure, prefer to not specify a hold_current . Setting \"spreadCycle\" vs \"stealthChop\" Mode \u00b6 By default, Klipper places the TMC drivers in \"spreadCycle\" mode. If the driver supports \"stealthChop\" then it can be enabled by adding stealthchop_threshold: 999999 to the TMC config section. In general, spreadCycle mode provides greater torque and greater positional accuracy than stealthChop mode. However, stealthChop mode may produce significantly lower audible noise on some printers. Tests comparing modes have shown an increased \"positional lag\" of around 75% of a full-step during constant velocity moves when using stealthChop mode (for example, on a printer with 40mm rotation_distance and 200 steps_per_rotation, position deviation of constant speed moves increased by ~0.150mm). However, this \"delay in obtaining the requested position\" may not manifest as a significant print defect and one may prefer the quieter behavior of stealthChop mode. It is recommended to always use \"spreadCycle\" mode (by not specifying stealthchop_threshold ) or to always use \"stealthChop\" mode (by setting stealthchop_threshold to 999999). Unfortunately, the drivers often produce poor and confusing results if the mode changes while the motor is at a non-zero velocity. Note that the stealthchop_threshold config option does not impact sensorless homing as Klipper automatically switches the TMC driver to an appropriate mode during sensorless homing operations. TMC interpolate setting introduces small position deviation \u00b6 The TMC driver interpolate setting may reduce the audible noise of printer movement at the cost of introducing a small systemic positional error. This systemic positional error results from the driver's delay in executing \"steps\" that Klipper sends it. During constant velocity moves, this delay results in a positional error of nearly half a configured microstep (more precisely, the error is half a microstep distance minus a 512th of a full step distance). For example, on an axis with a 40mm rotation_distance, 200 steps_per_rotation, and 16 microsteps, the systemic error introduced during constant velocity moves is ~0.006mm. For best positional accuracy consider using spreadCycle mode and disable interpolation (set interpolate: False in the TMC driver config). When configured this way, one may increase the microstep setting to reduce audible noise during stepper movement. Typically, a microstep setting of 64 or 128 will have similar audible noise as interpolation, and do so without introducing a systemic positional error. If using stealthChop mode then the positional inaccuracy from interpolation is small relative to the positional inaccuracy introduced from stealthChop mode. Therefore tuning interpolation is not considered useful when in stealthChop mode, and one can leave interpolation in its default state. Sensorless Homing \u00b6 Sensorless homing allows to home an axis without the need for a physical limit switch. Instead, the carriage on the axis is moved into the mechanical limit making the stepper motor lose steps. The stepper driver senses the lost steps and indicates this to the controlling MCU (Klipper) by toggling a pin. This information can be used by Klipper as end stop for the axis. This guide covers the setup of sensorless homing for the X axis of your (cartesian) printer. However, it works the same with all other axes (that require an end stop). You should configure and tune it for one axis at a time. Limitations \u00b6 Be sure that your mechanical components are able to handle the load of the carriage bumping into the limit of the axis repeatedly. Especially leadscrews might generate a lot of force. Homing a Z axis by bumping the nozzle into the printing surface might not be a good idea. For best results, verify that the axis carriage will make a firm contact with the axis limit. Further, sensorless homing might not be accurate enough for your printer. While homing X and Y axes on a cartesian machine can work well, homing the Z axis is generally not accurate enough and may result in an inconsistent first layer height. Homing a delta printer sensorless is not advisable due to missing accuracy. Further, the stall detection of the stepper driver is dependent on the mechanical load on the motor, the motor current and the motor temperature (coil resistance). Sensorless homing works best at medium motor speeds. For very slow speeds (less than 10 RPM) the motor does not generate significant back EMF and the TMC cannot reliably detect motor stalls. Further, at very high speeds, the back EMF of the motor approaches the supply voltage of the motor, so the TMC cannot detect stalls anymore. It is advised to have a look in the datasheet of your specific TMCs. There you can also find more details on limitations of this setup. Prerequisites \u00b6 A few prerequisites are needed to use sensorless homing: A stallGuard capable TMC stepper driver (tmc2130, tmc2209, tmc2660, or tmc5160). SPI / UART interface of the TMC driver wired to micro-controller (stand-alone mode does not work). The appropriate \"DIAG\" or \"SG_TST\" pin of TMC driver connected to the micro-controller. The steps in the config checks document must be run to confirm the stepper motors are configured and working properly. Tuning \u00b6 The procedure described here has six major steps: Choose a homing speed. Configure the printer.cfg file to enable sensorless homing. Find the stallguard setting with highest sensitivity that successfully homes. Find the stallguard setting with lowest sensitivity that successfully homes with a single touch. Update the printer.cfg with the desired stallguard setting. Create or update printer.cfg macros to home consistently. Choose homing speed \u00b6 The homing speed is an important choice when performing sensorless homing. It's desirable to use a slow homing speed so that the carriage does not exert excessive force on the frame when making contact with the end of the rail. However, the TMC drivers can't reliably detect a stall at very slow speeds. A good starting point for the homing speed is for the stepper motor to make a full rotation every two seconds. For many axes this will be the rotation_distance divided by two. For example: [stepper_x] rotation_distance: 40 homing_speed: 20 ... Configure printer.cfg for sensorless homing \u00b6 The homing_retract_dist setting must be set to zero in the stepper_x config section to disable the second homing move. The second homing attempt does not add value when using sensorless homing, it will not work reliably, and it will confuse the tuning process. Be sure that a hold_current setting is not specified in the TMC driver section of the config. (If a hold_current is set then after contact is made, the motor stops while the carriage is pressed against the end of the rail, and reducing the current while in that position may cause the carriage to move - that results in poor performance and will confuse the tuning process.) It is necessary to configure the sensorless homing pins and to configure initial \"stallguard\" settings. A tmc2209 example configuration for an X axis might look like: [tmc2209 stepper_x] diag_pin: ^PA1 # Set to MCU pin connected to TMC DIAG pin driver_SGTHRS: 255 # 255 is most sensitive value, 0 is least sensitive ... [stepper_x] endstop_pin: tmc2209_stepper_x:virtual_endstop homing_retract_dist: 0 ... An example tmc2130 or tmc5160 config might look like: [tmc2130 stepper_x] diag1_pin: ^!PA1 # Pin connected to TMC DIAG1 pin (or use diag0_pin / DIAG0 pin) driver_SGT: -64 # -64 is most sensitive value, 63 is least sensitive ... [stepper_x] endstop_pin: tmc2130_stepper_x:virtual_endstop homing_retract_dist: 0 ... An example tmc2660 config might look like: [tmc2660 stepper_x] driver_SGT: -64 # -64 is most sensitive value, 63 is least sensitive ... [stepper_x] endstop_pin: ^PA1 # Pin connected to TMC SG_TST pin homing_retract_dist: 0 ... The examples above only show settings specific to sensorless homing. See the config reference for all the available options. Find highest sensitivity that successfully homes \u00b6 Place the carriage near the center of the rail. Use the SET_TMC_FIELD command to set the highest sensitivity. For tmc2209: SET_TMC_FIELD STEPPER=stepper_x FIELD=SGTHRS VALUE=255 For tmc2130, tmc5160, and tmc2660: SET_TMC_FIELD STEPPER=stepper_x FIELD=sgt VALUE=-64 Then issue a G28 X0 command and verify the axis does not move at all or quickly stops moving. If the axis does not stop, then issue an M112 to halt the printer - something is not correct with the diag/sg_tst pin wiring or configuration and it must be corrected before continuing. Next, continually decrease the sensitivity of the VALUE setting and run the SET_TMC_FIELD G28 X0 commands again to find the highest sensitivity that results in the carriage successfully moving all the way to the endstop and halting. (For tmc2209 drivers this will be decreasing SGTHRS, for other drivers it will be increasing sgt.) Be sure to start each attempt with the carriage near the center of the rail (if needed issue M84 and then manually move the carriage to the center). It should be possible to find the highest sensitivity that homes reliably (settings with higher sensitivity result in small or no movement). Note the found value as maximum_sensitivity . (If the minimum possible sensitivity (SGTHRS=0 or sgt=63) is obtained without any carriage movement then something is not correct with the diag/sg_tst pin wiring or configuration and it must be corrected before continuing.) When searching for maximum_sensitivity, it may be convenient to jump to different VALUE settings (so as to bisect the VALUE parameter). If doing this then be prepared to issue an M112 command to halt the printer, as a setting with a very low sensitivity may cause the axis to repeatedly \"bang\" into the end of the rail. Be sure to wait a couple of seconds between each homing attempt. After the TMC driver detects a stall it may take a little time for it to clear its internal indicator and be capable of detecting another stall. During these tuning tests, if a G28 X0 command does not move all the way to the axis limit, then be careful with issuing any regular movement commands (eg, G1 ). Klipper will not have a correct understanding of the carriage position and a move command may cause undesirable and confusing results. Find lowest sensitivity that homes with one touch \u00b6 When homing with the found maximum_sensitivity value, the axis should move to the end of the rail and stop with a \"single touch\" - that is, there should not be a \"clicking\" or \"banging\" sound. (If there is a banging or clicking sound at maximum_sensitivity then the homing_speed may be too low, the driver current may be too low, or sensorless homing may not be a good choice for the axis.) The next step is to again continually move the carriage to a position near the center of the rail, decrease the sensitivity, and run the SET_TMC_FIELD G28 X0 commands - the goal is now to find the lowest sensitivity that still results in the carriage successfully homing with a \"single touch\". That is, it does not \"bang\" or \"click\" when contacting the end of the rail. Note the found value as minimum_sensitivity . Update printer.cfg with sensitivity value \u00b6 After finding maximum_sensitivity and minimum_sensitivity , use a calculator to obtain the recommend sensitivity as minimum_sensitivity + (maximum_sensitivity - minimum_sensitivity)/3 . The recommended sensitivity should be in the range between the minimum and maximum, but slightly closer to the minimum. Round the final value to the nearest integer value. For tmc2209 set this in the config as driver_SGTHRS , for other TMC drivers set this in the config as driver_SGT . If the range between maximum_sensitivity and minimum_sensitivity is small (eg, less than 5) then it may result in unstable homing. A faster homing speed may increase the range and make the operation more stable. Note that if any change is made to driver current, homing speed, or a notable change is made to the printer hardware, then it will be necessary to run the tuning process again. Using Macros when Homing \u00b6 After sensorless homing completes the carriage will be pressed against the end of the rail and the stepper will exert a force on the frame until the carriage is moved away. It is a good idea to create a macro to home the axis and immediately move the carriage away from the end of the rail. It is a good idea for the macro to pause at least 2 seconds prior to starting sensorless homing (or otherwise ensure that there has been no movement on the stepper for 2 seconds). Without a delay it is possible for the driver's internal stall flag to still be set from a previous move. It can also be useful to have that macro set the driver current before homing and set a new current after the carriage has moved away. An example macro might look something like: [gcode_macro SENSORLESS_HOME_X] gcode: {% set HOME_CUR = 0.700 %} {% set driver_config = printer.configfile.settings['tmc2209 stepper_x'] %} {% set RUN_CUR = driver_config.run_current %} # Set current for sensorless homing SET_TMC_CURRENT STEPPER=stepper_x CURRENT={HOME_CUR} # Pause to ensure driver stall flag is clear G4 P2000 # Home G28 X0 # Move away G90 G1 X5 F1200 # Set current during print SET_TMC_CURRENT STEPPER=stepper_x CURRENT={RUN_CUR} The resulting macro can be called from a homing_override config section or from a START_PRINT macro . Note that if the driver current during homing is changed, then the tuning process should be run again. Tips for sensorless homing on CoreXY \u00b6 It is possible to use sensorless homing on the X and Y carriages of a CoreXY printer. Klipper uses the [stepper_x] stepper to detect stalls when homing the X carriage and uses the [stepper_y] stepper to detect stalls when homing the Y carriage. Use the tuning guide described above to find the appropriate \"stall sensitivity\" for each carriage, but be aware of the following restrictions: When using sensorless homing on CoreXY, make sure there is no hold_current configured for either stepper. While tuning, make sure both the X and Y carriages are near the center of their rails before each home attempt. After tuning is complete, when homing both X and Y, use macros to ensure that one axis is homed first, then move that carriage away from the axis limit, pause for at least 2 seconds, and then start the homing of the other carriage. The move away from the axis avoids homing one axis while the other is pressed against the axis limit (which may skew the stall detection). The pause is necessary to ensure the driver's stall flag is cleared prior to homing again. An example CoreXY homing macro might look like: [gcode_macro HOME] gcode: G90 # Home Z G28 Z0 G1 Z10 F1200 # Home Y G28 Y0 G1 Y5 F1200 # Home X G4 P2000 G28 X0 G1 X5 F1200 Querying and diagnosing driver settings \u00b6 The ` DUMP_TMC command is a useful tool when configuring and diagnosing the drivers. It will report all fields configured by Klipper as well as all fields that can be queried from the driver. All of the reported fields are defined in the Trinamic datasheet for each driver. These datasheets can be found on the Trinamic website . Obtain and review the Trinamic datasheet for the driver to interpret the results of DUMP_TMC. Configuring driver_XXX settings \u00b6 Klipper supports configuring many low-level driver fields using driver_XXX settings. The TMC driver config reference has the full list of fields available for each type of driver. In addition, almost all fields can be modified at run-time using the SET_TMC_FIELD command . Each of these fields is defined in the Trinamic datasheet for each driver. These datasheets can be found on the Trinamic website . Note that the Trinamic datasheets sometime use wording that can confuse a high-level setting (such as \"hysteresis end\") with a low-level field value (eg, \"HEND\"). In Klipper, driver_XXX and SET_TMC_FIELD always set the low-level field value that is actually written to the driver. So, for example, if the Trinamic datasheet states that a value of 3 must be written to the HEND field to obtain a \"hysteresis end\" of 0, then set driver_HEND=3 to obtain the high-level value of 0. Common Questions \u00b6 Can I use stealthChop mode on an extruder with pressure advance? \u00b6 Many people successfully use \"stealthChop\" mode with Klipper's pressure advance. Klipper implements smooth pressure advance which does not introduce any instantaneous velocity changes. However, \"stealthChop\" mode may produce lower motor torque and/or produce higher motor heat. It may or may not be an adequate mode for your particular printer. I keep getting \"Unable to read tmc uart 'stepper_x' register IFCNT\" errors? \u00b6 This occurs when Klipper is unable to communicate with a tmc2208 or tmc2209 driver. Make sure that the motor power is enabled, as the stepper motor driver generally needs motor power before it can communicate with the micro-controller. If this error occurs after flashing Klipper for the first time, then the stepper driver may have been previously programmed in a state that is not compatible with Klipper. To reset the state, remove all power from the printer for several seconds (physically unplug both USB and power plugs). Otherwise, this error is typically the result of incorrect UART pin wiring or an incorrect Klipper configuration of the UART pin settings. I keep getting \"Unable to write tmc spi 'stepper_x' register ...\" errors? \u00b6 This occurs when Klipper is unable to communicate with a tmc2130 or tmc5160 driver. Make sure that the motor power is enabled, as the stepper motor driver generally needs motor power before it can communicate with the micro-controller. Otherwise, this error is typically the result of incorrect SPI wiring, an incorrect Klipper configuration of the SPI settings, or an incomplete configuration of devices on an SPI bus. Note that if the driver is on a shared SPI bus with multiple devices then be sure to fully configure every device on that shared SPI bus in Klipper. If a device on a shared SPI bus is not configured, then it may incorrectly respond to commands not intended for it and corrupt the communication to the intended device. If there is a device on a shared SPI bus that can not be configured in Klipper, then use a static_digital_output config section to set the CS pin of the unused device high (so that it will not attempt to use the SPI bus). The board's schematic is often a useful reference for finding which devices are on an SPI bus and their associated pins. Why did I get a \"TMC reports error: ...\" error? \u00b6 This type of error indicates the TMC driver detected a problem and has disabled itself. That is, the driver stopped holding its position and ignored movement commands. If Klipper detects that an active driver has disabled itself, it will transition the printer into a \"shutdown\" state. It's also possible that a TMC reports error shutdown occurs due to SPI errors that prevent communication with the driver (on tmc2130, tmc5160, or tmc2660). If this occurs, it's common for the reported driver status to show 00000000 or ffffffff - for example: TMC reports error: DRV_STATUS: ffffffff ... OR TMC reports error: READRSP@RDSEL2: 00000000 ... . Such a failure may be due to an SPI wiring problem or may be due to a self-reset or failure of the TMC driver. Some common errors and tips for diagnosing them: TMC reports error: ... ot=1(OvertempError!) \u00b6 This indicates the motor driver disabled itself because it became too hot. Typical solutions are to decrease the stepper motor current, increase cooling on the stepper motor driver, and/or increase cooling on the stepper motor. TMC reports error: ... ShortToGND OR ShortToSupply \u00b6 This indicates the driver has disabled itself because it detected very high current passing through the driver. This may indicate a loose or shorted wire to the stepper motor or within the stepper motor itself. This error may also occur if using stealthChop mode and the TMC driver is not able to accurately predict the mechanical load of the motor. (If the driver makes a poor prediction then it may send too much current through the motor and trigger its own over-current detection.) To test this, disable stealthChop mode and check if the errors continue to occur. TMC reports error: ... reset=1(Reset) OR CS_ACTUAL=0(Reset?) OR SE=0(Reset?) \u00b6 This indicates that the driver has reset itself mid-print. This may be due to voltage or wiring issues. TMC reports error: ... uv_cp=1(Undervoltage!) \u00b6 This indicates the driver has detected a low-voltage event and has disabled itself. This may be due to wiring or power supply issues. How do I tune spreadCycle/coolStep/etc. mode on my drivers? \u00b6 The Trinamic website has guides on configuring the drivers. These guides are often technical, low-level, and may require specialized hardware. Regardless, they are the best source of information.","title":"TMC drivers"},{"location":"TMC_Drivers.html#tmc-drivers","text":"This document provides information on using Trinamic stepper motor drivers in SPI/UART mode on Klipper. Klipper can also use Trinamic drivers in their \"standalone mode\". However, when the drivers are in this mode, no special Klipper configuration is needed and the advanced Klipper features discussed in this document are not available. In addition to this document, be sure to review the TMC driver config reference .","title":"TMC drivers"},{"location":"TMC_Drivers.html#tuning-motor-current","text":"A higher driver current increases positional accuracy and torque. However, a higher current also increases the heat produced by the stepper motor and the stepper motor driver. If the stepper motor driver gets too hot it will disable itself and Klipper will report an error. If the stepper motor gets too hot, it loses torque and positional accuracy. (If it gets very hot it may also melt plastic parts attached to it or near it.) As a general tuning tip, prefer higher current values as long as the stepper motor does not get too hot and the stepper motor driver does not report warnings or errors. In general, it is okay for the stepper motor to feel warm, but it should not become so hot that it is painful to touch.","title":"Tuning motor current"},{"location":"TMC_Drivers.html#prefer-to-not-specify-a-hold_current","text":"If one configures a hold_current then the TMC driver can reduce current to the stepper motor when it detects that the stepper is not moving. However, changing motor current may itself introduce motor movement. This may occur due to \"detent forces\" within the stepper motor (the permanent magnet in the rotor pulls towards the iron teeth in the stator) or due to external forces on the axis carriage. Most stepper motors will not obtain a significant benefit to reducing current during normal prints, because few printing moves will leave a stepper motor idle for sufficiently long to activate the hold_current feature. And, it is unlikely that one would want to introduce subtle print artifacts to the few printing moves that do leave a stepper idle sufficiently long. If one wishes to reduce current to motors during print start routines, then consider issuing SET_TMC_CURRENT commands in a START_PRINT macro to adjust the current before and after normal printing moves. Some printers with dedicated Z motors that are idle during normal printing moves (no bed_mesh, no bed_tilt, no Z skew_correction, no \"vase mode\" prints, etc.) may find that Z motors do run cooler with a hold_current . If implementing this then be sure to take into account this type of uncommanded Z axis movement during bed leveling, bed probing, probe calibration, and similar. The driver_TPOWERDOWN and driver_IHOLDDELAY should also be calibrated accordingly. If unsure, prefer to not specify a hold_current .","title":"Prefer to not specify a hold_current"},{"location":"TMC_Drivers.html#setting-spreadcycle-vs-stealthchop-mode","text":"By default, Klipper places the TMC drivers in \"spreadCycle\" mode. If the driver supports \"stealthChop\" then it can be enabled by adding stealthchop_threshold: 999999 to the TMC config section. In general, spreadCycle mode provides greater torque and greater positional accuracy than stealthChop mode. However, stealthChop mode may produce significantly lower audible noise on some printers. Tests comparing modes have shown an increased \"positional lag\" of around 75% of a full-step during constant velocity moves when using stealthChop mode (for example, on a printer with 40mm rotation_distance and 200 steps_per_rotation, position deviation of constant speed moves increased by ~0.150mm). However, this \"delay in obtaining the requested position\" may not manifest as a significant print defect and one may prefer the quieter behavior of stealthChop mode. It is recommended to always use \"spreadCycle\" mode (by not specifying stealthchop_threshold ) or to always use \"stealthChop\" mode (by setting stealthchop_threshold to 999999). Unfortunately, the drivers often produce poor and confusing results if the mode changes while the motor is at a non-zero velocity. Note that the stealthchop_threshold config option does not impact sensorless homing as Klipper automatically switches the TMC driver to an appropriate mode during sensorless homing operations.","title":"Setting \"spreadCycle\" vs \"stealthChop\" Mode"},{"location":"TMC_Drivers.html#tmc-interpolate-setting-introduces-small-position-deviation","text":"The TMC driver interpolate setting may reduce the audible noise of printer movement at the cost of introducing a small systemic positional error. This systemic positional error results from the driver's delay in executing \"steps\" that Klipper sends it. During constant velocity moves, this delay results in a positional error of nearly half a configured microstep (more precisely, the error is half a microstep distance minus a 512th of a full step distance). For example, on an axis with a 40mm rotation_distance, 200 steps_per_rotation, and 16 microsteps, the systemic error introduced during constant velocity moves is ~0.006mm. For best positional accuracy consider using spreadCycle mode and disable interpolation (set interpolate: False in the TMC driver config). When configured this way, one may increase the microstep setting to reduce audible noise during stepper movement. Typically, a microstep setting of 64 or 128 will have similar audible noise as interpolation, and do so without introducing a systemic positional error. If using stealthChop mode then the positional inaccuracy from interpolation is small relative to the positional inaccuracy introduced from stealthChop mode. Therefore tuning interpolation is not considered useful when in stealthChop mode, and one can leave interpolation in its default state.","title":"TMC interpolate setting introduces small position deviation"},{"location":"TMC_Drivers.html#sensorless-homing","text":"Sensorless homing allows to home an axis without the need for a physical limit switch. Instead, the carriage on the axis is moved into the mechanical limit making the stepper motor lose steps. The stepper driver senses the lost steps and indicates this to the controlling MCU (Klipper) by toggling a pin. This information can be used by Klipper as end stop for the axis. This guide covers the setup of sensorless homing for the X axis of your (cartesian) printer. However, it works the same with all other axes (that require an end stop). You should configure and tune it for one axis at a time.","title":"Sensorless Homing"},{"location":"TMC_Drivers.html#limitations","text":"Be sure that your mechanical components are able to handle the load of the carriage bumping into the limit of the axis repeatedly. Especially leadscrews might generate a lot of force. Homing a Z axis by bumping the nozzle into the printing surface might not be a good idea. For best results, verify that the axis carriage will make a firm contact with the axis limit. Further, sensorless homing might not be accurate enough for your printer. While homing X and Y axes on a cartesian machine can work well, homing the Z axis is generally not accurate enough and may result in an inconsistent first layer height. Homing a delta printer sensorless is not advisable due to missing accuracy. Further, the stall detection of the stepper driver is dependent on the mechanical load on the motor, the motor current and the motor temperature (coil resistance). Sensorless homing works best at medium motor speeds. For very slow speeds (less than 10 RPM) the motor does not generate significant back EMF and the TMC cannot reliably detect motor stalls. Further, at very high speeds, the back EMF of the motor approaches the supply voltage of the motor, so the TMC cannot detect stalls anymore. It is advised to have a look in the datasheet of your specific TMCs. There you can also find more details on limitations of this setup.","title":"Limitations"},{"location":"TMC_Drivers.html#prerequisites","text":"A few prerequisites are needed to use sensorless homing: A stallGuard capable TMC stepper driver (tmc2130, tmc2209, tmc2660, or tmc5160). SPI / UART interface of the TMC driver wired to micro-controller (stand-alone mode does not work). The appropriate \"DIAG\" or \"SG_TST\" pin of TMC driver connected to the micro-controller. The steps in the config checks document must be run to confirm the stepper motors are configured and working properly.","title":"Prerequisites"},{"location":"TMC_Drivers.html#tuning","text":"The procedure described here has six major steps: Choose a homing speed. Configure the printer.cfg file to enable sensorless homing. Find the stallguard setting with highest sensitivity that successfully homes. Find the stallguard setting with lowest sensitivity that successfully homes with a single touch. Update the printer.cfg with the desired stallguard setting. Create or update printer.cfg macros to home consistently.","title":"Tuning"},{"location":"TMC_Drivers.html#choose-homing-speed","text":"The homing speed is an important choice when performing sensorless homing. It's desirable to use a slow homing speed so that the carriage does not exert excessive force on the frame when making contact with the end of the rail. However, the TMC drivers can't reliably detect a stall at very slow speeds. A good starting point for the homing speed is for the stepper motor to make a full rotation every two seconds. For many axes this will be the rotation_distance divided by two. For example: [stepper_x] rotation_distance: 40 homing_speed: 20 ...","title":"Choose homing speed"},{"location":"TMC_Drivers.html#configure-printercfg-for-sensorless-homing","text":"The homing_retract_dist setting must be set to zero in the stepper_x config section to disable the second homing move. The second homing attempt does not add value when using sensorless homing, it will not work reliably, and it will confuse the tuning process. Be sure that a hold_current setting is not specified in the TMC driver section of the config. (If a hold_current is set then after contact is made, the motor stops while the carriage is pressed against the end of the rail, and reducing the current while in that position may cause the carriage to move - that results in poor performance and will confuse the tuning process.) It is necessary to configure the sensorless homing pins and to configure initial \"stallguard\" settings. A tmc2209 example configuration for an X axis might look like: [tmc2209 stepper_x] diag_pin: ^PA1 # Set to MCU pin connected to TMC DIAG pin driver_SGTHRS: 255 # 255 is most sensitive value, 0 is least sensitive ... [stepper_x] endstop_pin: tmc2209_stepper_x:virtual_endstop homing_retract_dist: 0 ... An example tmc2130 or tmc5160 config might look like: [tmc2130 stepper_x] diag1_pin: ^!PA1 # Pin connected to TMC DIAG1 pin (or use diag0_pin / DIAG0 pin) driver_SGT: -64 # -64 is most sensitive value, 63 is least sensitive ... [stepper_x] endstop_pin: tmc2130_stepper_x:virtual_endstop homing_retract_dist: 0 ... An example tmc2660 config might look like: [tmc2660 stepper_x] driver_SGT: -64 # -64 is most sensitive value, 63 is least sensitive ... [stepper_x] endstop_pin: ^PA1 # Pin connected to TMC SG_TST pin homing_retract_dist: 0 ... The examples above only show settings specific to sensorless homing. See the config reference for all the available options.","title":"Configure printer.cfg for sensorless homing"},{"location":"TMC_Drivers.html#find-highest-sensitivity-that-successfully-homes","text":"Place the carriage near the center of the rail. Use the SET_TMC_FIELD command to set the highest sensitivity. For tmc2209: SET_TMC_FIELD STEPPER=stepper_x FIELD=SGTHRS VALUE=255 For tmc2130, tmc5160, and tmc2660: SET_TMC_FIELD STEPPER=stepper_x FIELD=sgt VALUE=-64 Then issue a G28 X0 command and verify the axis does not move at all or quickly stops moving. If the axis does not stop, then issue an M112 to halt the printer - something is not correct with the diag/sg_tst pin wiring or configuration and it must be corrected before continuing. Next, continually decrease the sensitivity of the VALUE setting and run the SET_TMC_FIELD G28 X0 commands again to find the highest sensitivity that results in the carriage successfully moving all the way to the endstop and halting. (For tmc2209 drivers this will be decreasing SGTHRS, for other drivers it will be increasing sgt.) Be sure to start each attempt with the carriage near the center of the rail (if needed issue M84 and then manually move the carriage to the center). It should be possible to find the highest sensitivity that homes reliably (settings with higher sensitivity result in small or no movement). Note the found value as maximum_sensitivity . (If the minimum possible sensitivity (SGTHRS=0 or sgt=63) is obtained without any carriage movement then something is not correct with the diag/sg_tst pin wiring or configuration and it must be corrected before continuing.) When searching for maximum_sensitivity, it may be convenient to jump to different VALUE settings (so as to bisect the VALUE parameter). If doing this then be prepared to issue an M112 command to halt the printer, as a setting with a very low sensitivity may cause the axis to repeatedly \"bang\" into the end of the rail. Be sure to wait a couple of seconds between each homing attempt. After the TMC driver detects a stall it may take a little time for it to clear its internal indicator and be capable of detecting another stall. During these tuning tests, if a G28 X0 command does not move all the way to the axis limit, then be careful with issuing any regular movement commands (eg, G1 ). Klipper will not have a correct understanding of the carriage position and a move command may cause undesirable and confusing results.","title":"Find highest sensitivity that successfully homes"},{"location":"TMC_Drivers.html#find-lowest-sensitivity-that-homes-with-one-touch","text":"When homing with the found maximum_sensitivity value, the axis should move to the end of the rail and stop with a \"single touch\" - that is, there should not be a \"clicking\" or \"banging\" sound. (If there is a banging or clicking sound at maximum_sensitivity then the homing_speed may be too low, the driver current may be too low, or sensorless homing may not be a good choice for the axis.) The next step is to again continually move the carriage to a position near the center of the rail, decrease the sensitivity, and run the SET_TMC_FIELD G28 X0 commands - the goal is now to find the lowest sensitivity that still results in the carriage successfully homing with a \"single touch\". That is, it does not \"bang\" or \"click\" when contacting the end of the rail. Note the found value as minimum_sensitivity .","title":"Find lowest sensitivity that homes with one touch"},{"location":"TMC_Drivers.html#update-printercfg-with-sensitivity-value","text":"After finding maximum_sensitivity and minimum_sensitivity , use a calculator to obtain the recommend sensitivity as minimum_sensitivity + (maximum_sensitivity - minimum_sensitivity)/3 . The recommended sensitivity should be in the range between the minimum and maximum, but slightly closer to the minimum. Round the final value to the nearest integer value. For tmc2209 set this in the config as driver_SGTHRS , for other TMC drivers set this in the config as driver_SGT . If the range between maximum_sensitivity and minimum_sensitivity is small (eg, less than 5) then it may result in unstable homing. A faster homing speed may increase the range and make the operation more stable. Note that if any change is made to driver current, homing speed, or a notable change is made to the printer hardware, then it will be necessary to run the tuning process again.","title":"Update printer.cfg with sensitivity value"},{"location":"TMC_Drivers.html#using-macros-when-homing","text":"After sensorless homing completes the carriage will be pressed against the end of the rail and the stepper will exert a force on the frame until the carriage is moved away. It is a good idea to create a macro to home the axis and immediately move the carriage away from the end of the rail. It is a good idea for the macro to pause at least 2 seconds prior to starting sensorless homing (or otherwise ensure that there has been no movement on the stepper for 2 seconds). Without a delay it is possible for the driver's internal stall flag to still be set from a previous move. It can also be useful to have that macro set the driver current before homing and set a new current after the carriage has moved away. An example macro might look something like: [gcode_macro SENSORLESS_HOME_X] gcode: {% set HOME_CUR = 0.700 %} {% set driver_config = printer.configfile.settings['tmc2209 stepper_x'] %} {% set RUN_CUR = driver_config.run_current %} # Set current for sensorless homing SET_TMC_CURRENT STEPPER=stepper_x CURRENT={HOME_CUR} # Pause to ensure driver stall flag is clear G4 P2000 # Home G28 X0 # Move away G90 G1 X5 F1200 # Set current during print SET_TMC_CURRENT STEPPER=stepper_x CURRENT={RUN_CUR} The resulting macro can be called from a homing_override config section or from a START_PRINT macro . Note that if the driver current during homing is changed, then the tuning process should be run again.","title":"Using Macros when Homing"},{"location":"TMC_Drivers.html#tips-for-sensorless-homing-on-corexy","text":"It is possible to use sensorless homing on the X and Y carriages of a CoreXY printer. Klipper uses the [stepper_x] stepper to detect stalls when homing the X carriage and uses the [stepper_y] stepper to detect stalls when homing the Y carriage. Use the tuning guide described above to find the appropriate \"stall sensitivity\" for each carriage, but be aware of the following restrictions: When using sensorless homing on CoreXY, make sure there is no hold_current configured for either stepper. While tuning, make sure both the X and Y carriages are near the center of their rails before each home attempt. After tuning is complete, when homing both X and Y, use macros to ensure that one axis is homed first, then move that carriage away from the axis limit, pause for at least 2 seconds, and then start the homing of the other carriage. The move away from the axis avoids homing one axis while the other is pressed against the axis limit (which may skew the stall detection). The pause is necessary to ensure the driver's stall flag is cleared prior to homing again. An example CoreXY homing macro might look like: [gcode_macro HOME] gcode: G90 # Home Z G28 Z0 G1 Z10 F1200 # Home Y G28 Y0 G1 Y5 F1200 # Home X G4 P2000 G28 X0 G1 X5 F1200","title":"Tips for sensorless homing on CoreXY"},{"location":"TMC_Drivers.html#querying-and-diagnosing-driver-settings","text":"The ` DUMP_TMC command is a useful tool when configuring and diagnosing the drivers. It will report all fields configured by Klipper as well as all fields that can be queried from the driver. All of the reported fields are defined in the Trinamic datasheet for each driver. These datasheets can be found on the Trinamic website . Obtain and review the Trinamic datasheet for the driver to interpret the results of DUMP_TMC.","title":"Querying and diagnosing driver settings"},{"location":"TMC_Drivers.html#configuring-driver_xxx-settings","text":"Klipper supports configuring many low-level driver fields using driver_XXX settings. The TMC driver config reference has the full list of fields available for each type of driver. In addition, almost all fields can be modified at run-time using the SET_TMC_FIELD command . Each of these fields is defined in the Trinamic datasheet for each driver. These datasheets can be found on the Trinamic website . Note that the Trinamic datasheets sometime use wording that can confuse a high-level setting (such as \"hysteresis end\") with a low-level field value (eg, \"HEND\"). In Klipper, driver_XXX and SET_TMC_FIELD always set the low-level field value that is actually written to the driver. So, for example, if the Trinamic datasheet states that a value of 3 must be written to the HEND field to obtain a \"hysteresis end\" of 0, then set driver_HEND=3 to obtain the high-level value of 0.","title":"Configuring driver_XXX settings"},{"location":"TMC_Drivers.html#common-questions","text":"","title":"Common Questions"},{"location":"TMC_Drivers.html#can-i-use-stealthchop-mode-on-an-extruder-with-pressure-advance","text":"Many people successfully use \"stealthChop\" mode with Klipper's pressure advance. Klipper implements smooth pressure advance which does not introduce any instantaneous velocity changes. However, \"stealthChop\" mode may produce lower motor torque and/or produce higher motor heat. It may or may not be an adequate mode for your particular printer.","title":"Can I use stealthChop mode on an extruder with pressure advance?"},{"location":"TMC_Drivers.html#i-keep-getting-unable-to-read-tmc-uart-stepper_x-register-ifcnt-errors","text":"This occurs when Klipper is unable to communicate with a tmc2208 or tmc2209 driver. Make sure that the motor power is enabled, as the stepper motor driver generally needs motor power before it can communicate with the micro-controller. If this error occurs after flashing Klipper for the first time, then the stepper driver may have been previously programmed in a state that is not compatible with Klipper. To reset the state, remove all power from the printer for several seconds (physically unplug both USB and power plugs). Otherwise, this error is typically the result of incorrect UART pin wiring or an incorrect Klipper configuration of the UART pin settings.","title":"I keep getting \"Unable to read tmc uart 'stepper_x' register IFCNT\" errors?"},{"location":"TMC_Drivers.html#i-keep-getting-unable-to-write-tmc-spi-stepper_x-register-errors","text":"This occurs when Klipper is unable to communicate with a tmc2130 or tmc5160 driver. Make sure that the motor power is enabled, as the stepper motor driver generally needs motor power before it can communicate with the micro-controller. Otherwise, this error is typically the result of incorrect SPI wiring, an incorrect Klipper configuration of the SPI settings, or an incomplete configuration of devices on an SPI bus. Note that if the driver is on a shared SPI bus with multiple devices then be sure to fully configure every device on that shared SPI bus in Klipper. If a device on a shared SPI bus is not configured, then it may incorrectly respond to commands not intended for it and corrupt the communication to the intended device. If there is a device on a shared SPI bus that can not be configured in Klipper, then use a static_digital_output config section to set the CS pin of the unused device high (so that it will not attempt to use the SPI bus). The board's schematic is often a useful reference for finding which devices are on an SPI bus and their associated pins.","title":"I keep getting \"Unable to write tmc spi 'stepper_x' register ...\" errors?"},{"location":"TMC_Drivers.html#why-did-i-get-a-tmc-reports-error-error","text":"This type of error indicates the TMC driver detected a problem and has disabled itself. That is, the driver stopped holding its position and ignored movement commands. If Klipper detects that an active driver has disabled itself, it will transition the printer into a \"shutdown\" state. It's also possible that a TMC reports error shutdown occurs due to SPI errors that prevent communication with the driver (on tmc2130, tmc5160, or tmc2660). If this occurs, it's common for the reported driver status to show 00000000 or ffffffff - for example: TMC reports error: DRV_STATUS: ffffffff ... OR TMC reports error: READRSP@RDSEL2: 00000000 ... . Such a failure may be due to an SPI wiring problem or may be due to a self-reset or failure of the TMC driver. Some common errors and tips for diagnosing them:","title":"Why did I get a \"TMC reports error: ...\" error?"},{"location":"TMC_Drivers.html#tmc-reports-error-ot1overtemperror","text":"This indicates the motor driver disabled itself because it became too hot. Typical solutions are to decrease the stepper motor current, increase cooling on the stepper motor driver, and/or increase cooling on the stepper motor.","title":"TMC reports error: ... ot=1(OvertempError!)"},{"location":"TMC_Drivers.html#tmc-reports-error-shorttognd-or-shorttosupply","text":"This indicates the driver has disabled itself because it detected very high current passing through the driver. This may indicate a loose or shorted wire to the stepper motor or within the stepper motor itself. This error may also occur if using stealthChop mode and the TMC driver is not able to accurately predict the mechanical load of the motor. (If the driver makes a poor prediction then it may send too much current through the motor and trigger its own over-current detection.) To test this, disable stealthChop mode and check if the errors continue to occur.","title":"TMC reports error: ... ShortToGND OR ShortToSupply"},{"location":"TMC_Drivers.html#tmc-reports-error-reset1reset-or-cs_actual0reset-or-se0reset","text":"This indicates that the driver has reset itself mid-print. This may be due to voltage or wiring issues.","title":"TMC reports error: ... reset=1(Reset) OR CS_ACTUAL=0(Reset?) OR SE=0(Reset?)"},{"location":"TMC_Drivers.html#tmc-reports-error-uv_cp1undervoltage","text":"This indicates the driver has detected a low-voltage event and has disabled itself. This may be due to wiring or power supply issues.","title":"TMC reports error: ... uv_cp=1(Undervoltage!)"},{"location":"TMC_Drivers.html#how-do-i-tune-spreadcyclecoolstepetc-mode-on-my-drivers","text":"The Trinamic website has guides on configuring the drivers. These guides are often technical, low-level, and may require specialized hardware. Regardless, they are the best source of information.","title":"How do I tune spreadCycle/coolStep/etc. mode on my drivers?"},{"location":"TSL1401CL_Filament_Width_Sensor.html","text":"TSL1401CL filament width sensor \u00b6 This document describes Filament Width Sensor host module. Hardware used for developing this host module is based on TSL1401CL linear sensor array but it can work with any sensor array that has analog output. You can find designs at Thingiverse . To use a sensor array as a filament width sensor, read Config Reference and G-Code documentation . How does it work? \u00b6 Sensor generates analog output based on calculated filament width. Output voltage always equals to detected filament width (Ex. 1.65v, 1.70v, 3.0v). Host module monitors voltage changes and adjusts extrusion multiplier. Note: \u00b6 Sensor readings done with 10 mm intervals by default. If necessary you are free to change this setting by editing MEASUREMENT_INTERVAL_MM parameter in filament_width_sensor.py file.","title":"TSL1401CL filament width sensor"},{"location":"TSL1401CL_Filament_Width_Sensor.html#tsl1401cl-filament-width-sensor","text":"This document describes Filament Width Sensor host module. Hardware used for developing this host module is based on TSL1401CL linear sensor array but it can work with any sensor array that has analog output. You can find designs at Thingiverse . To use a sensor array as a filament width sensor, read Config Reference and G-Code documentation .","title":"TSL1401CL filament width sensor"},{"location":"TSL1401CL_Filament_Width_Sensor.html#how-does-it-work","text":"Sensor generates analog output based on calculated filament width. Output voltage always equals to detected filament width (Ex. 1.65v, 1.70v, 3.0v). Host module monitors voltage changes and adjusts extrusion multiplier.","title":"How does it work?"},{"location":"TSL1401CL_Filament_Width_Sensor.html#note","text":"Sensor readings done with 10 mm intervals by default. If necessary you are free to change this setting by editing MEASUREMENT_INTERVAL_MM parameter in filament_width_sensor.py file.","title":"Note:"},{"location":"Using_PWM_Tools.html","text":"Using PWM tools \u00b6 This document describes how to setup a PWM-controlled laser or spindle using pwm_tool and some macros. How does it work? \u00b6 With re-purposing the printhead's fan pwm output, you can control lasers or spindles. This is useful if you use switchable print heads, for example the E3D toolchanger or a DIY solution. Usually, cam-tools such as LaserWeb can be configured to use M3-M5 commands, which stand for spindle speed CW ( M3 S[0-255] ), spindle speed CCW ( M4 S[0-255] ) and spindle stop ( M5 ). Warning: When driving a laser, keep all security precautions that you can think of! Diode lasers are usually inverted. This means, that when the MCU restarts, the laser will be fully on for the time it takes the MCU to start up again. For good measure, it is recommended to always wear appropriate laser-goggles of the right wavelength if the laser is powered; and to disconnect the laser when it is not needed. Also, you should configure a safety timeout, so that when your host or MCU encounters an error, the tool will stop. For an example configuration, see config/sample-pwm-tool.cfg . Commands \u00b6 M3/M4 S<value> : Set PWM duty-cycle. Values between 0 and 255. M5 : Stop PWM output to shutdown value. Laserweb Configuration \u00b6 If you use Laserweb, a working configuration would be: GCODE START: M5 ; Disable Laser G21 ; Set units to mm G90 ; Absolute positioning G0 Z0 F7000 ; Set Non-Cutting speed GCODE END: M5 ; Disable Laser G91 ; relative G0 Z+20 F4000 ; G90 ; absolute GCODE HOMING: M5 ; Disable Laser G28 ; Home all axis TOOL ON: M3 $INTENSITY TOOL OFF: M5 ; Disable Laser LASER INTENSITY: S","title":"Using PWM tools"},{"location":"Using_PWM_Tools.html#using-pwm-tools","text":"This document describes how to setup a PWM-controlled laser or spindle using pwm_tool and some macros.","title":"Using PWM tools"},{"location":"Using_PWM_Tools.html#how-does-it-work","text":"With re-purposing the printhead's fan pwm output, you can control lasers or spindles. This is useful if you use switchable print heads, for example the E3D toolchanger or a DIY solution. Usually, cam-tools such as LaserWeb can be configured to use M3-M5 commands, which stand for spindle speed CW ( M3 S[0-255] ), spindle speed CCW ( M4 S[0-255] ) and spindle stop ( M5 ). Warning: When driving a laser, keep all security precautions that you can think of! Diode lasers are usually inverted. This means, that when the MCU restarts, the laser will be fully on for the time it takes the MCU to start up again. For good measure, it is recommended to always wear appropriate laser-goggles of the right wavelength if the laser is powered; and to disconnect the laser when it is not needed. Also, you should configure a safety timeout, so that when your host or MCU encounters an error, the tool will stop. For an example configuration, see config/sample-pwm-tool.cfg .","title":"How does it work?"},{"location":"Using_PWM_Tools.html#commands","text":"M3/M4 S<value> : Set PWM duty-cycle. Values between 0 and 255. M5 : Stop PWM output to shutdown value.","title":"Commands"},{"location":"Using_PWM_Tools.html#laserweb-configuration","text":"If you use Laserweb, a working configuration would be: GCODE START: M5 ; Disable Laser G21 ; Set units to mm G90 ; Absolute positioning G0 Z0 F7000 ; Set Non-Cutting speed GCODE END: M5 ; Disable Laser G91 ; relative G0 Z+20 F4000 ; G90 ; absolute GCODE HOMING: M5 ; Disable Laser G28 ; Home all axis TOOL ON: M3 $INTENSITY TOOL OFF: M5 ; Disable Laser LASER INTENSITY: S","title":"Laserweb Configuration"}]}
\ No newline at end of file
diff --git a/sitemap.xml.gz b/sitemap.xml.gz
index 1527abdf610b2d4b460341ba5f070a531db04262..6d4c74272e8edaf70da56cd4a616d83e13b439a9 100644
GIT binary patch
delta 15
WcmaFL_>_@dzMF&NW8cY%?DqgJLIz9#

delta 15
XcmaFL_>_@dzMF$%_sSC!+3x`WErA9w

diff --git a/zh-Hant/_klipper3d/__pycache__/mkdocs_hooks.cpython-38.pyc b/zh-Hant/_klipper3d/__pycache__/mkdocs_hooks.cpython-38.pyc
index feced514a009e58c06eda54ecdafe44a6178c40c..1c44076110e218c19b9c30fa172169a1eb6c8f2a 100644
GIT binary patch
delta 20
acmcc4ex02=l$V!_0SNB(o!rQMh8X}lPX+-1

delta 20
acmcc4ex02=l$V!_0SK0^Jh74c3^M>ZT?OI*

diff --git a/zh-Hant/sitemap.xml.gz b/zh-Hant/sitemap.xml.gz
index 504049935305cbf2f9f6e9862ea0f63bf55bdc97..755741c89114d0788ef2d713cd5823618ae0720c 100644
GIT binary patch
delta 15
WcmaFL_>_@dzMF&NYv0L<?DqgJS_V)6

delta 15
XcmaFL_>_@dzMF$%|H=~++3x`WEtv*1

diff --git a/zh/_klipper3d/__pycache__/mkdocs_hooks.cpython-38.pyc b/zh/_klipper3d/__pycache__/mkdocs_hooks.cpython-38.pyc
index feced514a009e58c06eda54ecdafe44a6178c40c..1c44076110e218c19b9c30fa172169a1eb6c8f2a 100644
GIT binary patch
delta 20
acmcc4ex02=l$V!_0SNB(o!rQMh8X}lPX+-1

delta 20
acmcc4ex02=l$V!_0SK0^Jh74c3^M>ZT?OI*

diff --git a/zh/sitemap.xml.gz b/zh/sitemap.xml.gz
index 0cf824ba52735f9038e92dfeabce6c8dbee7f1f4..8b74ece44a574ae35693ffc7efb7f8dd99f52c52 100644
GIT binary patch
delta 15
WcmaFL_>_@dzMF&NbKl8{?DqgJP6kc@

delta 15
XcmaFL_>_@dzMF$%@5&Ps+3x`WEsX{;