diff --git a/Code_Overview.html b/Code_Overview.html
index 1a41b49a7562..3370916aab39 100644
--- a/Code_Overview.html
+++ b/Code_Overview.html
@@ -1562,8 +1562,9 @@ <h2 id="code-flow-of-a-move-command">Code flow of a move command<a class="header
 <ul>
 <li>The ToolHead class (in toolhead.py) handles "look-ahead" and tracks
   the timing of printing actions. The main codepath for a move is:
-  <code>ToolHead.move() -&gt; MoveQueue.add_move() -&gt; MoveQueue.flush() -&gt;
-  Move.set_junction() -&gt; ToolHead._process_moves()</code>.<ul>
+  <code>ToolHead.move() -&gt; LookAheadQueue.add_move() -&gt;
+  LookAheadQueue.flush() -&gt; Move.set_junction() -&gt;
+  ToolHead._process_moves()</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
@@ -1572,10 +1573,10 @@ <h2 id="code-flow-of-a-move-command">Code flow of a move command<a class="header
 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.</li>
-<li>MoveQueue.add_move() places the move object on the "look-ahead"
-queue.</li>
-<li>MoveQueue.flush() determines the start and end velocities of each
-move.</li>
+<li>LookAheadQueue.add_move() places the move object on the
+"look-ahead" queue.</li>
+<li>LookAheadQueue.flush() determines the start and end velocities of
+each move.</li>
 <li>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
@@ -1599,17 +1600,18 @@ <h2 id="code-flow-of-a-move-command">Code flow of a move command<a class="header
   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._update_move_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>
+  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:
diff --git a/_klipper3d/__pycache__/mkdocs_hooks.cpython-38.pyc b/_klipper3d/__pycache__/mkdocs_hooks.cpython-38.pyc
index 9d1a40d66dcd..c19006b2809f 100644
Binary files a/_klipper3d/__pycache__/mkdocs_hooks.cpython-38.pyc and b/_klipper3d/__pycache__/mkdocs_hooks.cpython-38.pyc differ
diff --git a/fr/_klipper3d/__pycache__/mkdocs_hooks.cpython-38.pyc b/fr/_klipper3d/__pycache__/mkdocs_hooks.cpython-38.pyc
index 9d1a40d66dcd..c19006b2809f 100644
Binary files a/fr/_klipper3d/__pycache__/mkdocs_hooks.cpython-38.pyc and b/fr/_klipper3d/__pycache__/mkdocs_hooks.cpython-38.pyc differ
diff --git a/fr/sitemap.xml.gz b/fr/sitemap.xml.gz
index a19ef033abf8..efab4a043ac5 100644
Binary files a/fr/sitemap.xml.gz and b/fr/sitemap.xml.gz differ
diff --git a/hu/_klipper3d/__pycache__/mkdocs_hooks.cpython-38.pyc b/hu/_klipper3d/__pycache__/mkdocs_hooks.cpython-38.pyc
index 9d1a40d66dcd..c19006b2809f 100644
Binary files a/hu/_klipper3d/__pycache__/mkdocs_hooks.cpython-38.pyc and b/hu/_klipper3d/__pycache__/mkdocs_hooks.cpython-38.pyc differ
diff --git a/hu/sitemap.xml.gz b/hu/sitemap.xml.gz
index 714dacfac03f..38a3f892c141 100644
Binary files a/hu/sitemap.xml.gz and b/hu/sitemap.xml.gz differ
diff --git a/it/_klipper3d/__pycache__/mkdocs_hooks.cpython-38.pyc b/it/_klipper3d/__pycache__/mkdocs_hooks.cpython-38.pyc
index 9d1a40d66dcd..c19006b2809f 100644
Binary files a/it/_klipper3d/__pycache__/mkdocs_hooks.cpython-38.pyc and b/it/_klipper3d/__pycache__/mkdocs_hooks.cpython-38.pyc differ
diff --git a/it/sitemap.xml.gz b/it/sitemap.xml.gz
index 1ca3bb99d973..d98039eef676 100644
Binary files a/it/sitemap.xml.gz and b/it/sitemap.xml.gz differ
diff --git a/search/search_index.json b/search/search_index.json
index c734d875653c..84996c75b83d 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":"Klipper is a 3d-Printer firmware. It combines the power of a general purpose computer with one or more micro-controllers. See the features document for more information on why you should use Klipper. To begin using Klipper start by installing it. Klipper is Free Software. Read the documentation or view the Klipper code on github . 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. 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.","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#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":"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. After setting up the [axis_twist_compensation] module, perform AXIS_TWIST_COMPENSATION_CALIBRATE * The calibration wizard will prompt you to measure the probe Z offset at a few points along the bed * The calibration defaults to 3 points but you can use the option SAMPLE_COUNT= to use a different number. Adjust your Z offset Perform automatic/probe-based bed tramming operations, such as Screws Tilt Adjust , Z Tilt Adjust etc Home all axis, then perform a Bed Mesh if required Perform a test print, followed by any fine-tuning as desired 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. After setting up the [axis_twist_compensation] module, perform AXIS_TWIST_COMPENSATION_CALIBRATE * The calibration wizard will prompt you to measure the probe Z offset at a few points along the bed * The calibration defaults to 3 points but you can use the option SAMPLE_COUNT= to use a different number. Adjust your Z offset Perform automatic/probe-based bed tramming operations, such as Screws Tilt Adjust , Z Tilt Adjust etc Home all axis, then perform a Bed Mesh if required Perform a test print, followed by any fine-tuning as desired Tip: Bed temperature and nozzle temperature and size do not seem to have an influence to the calibration process.","title":"Overview of compensation usage"},{"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 9.9 2019-08-03 4GB SD 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 ) and install Klipper by running the following commands: git clone https://github.com/Klipper3d/klipper ./klipper/scripts/install-beaglebone.sh Install Octoprint \u00b6 One may then install Octoprint: 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 Make sure the OctoPrint web server is accessible - it should be at: http://beaglebone:5000/ Building the micro-controller code \u00b6 To compile the Klipper micro-controller code, start by configuring it for the \"Beaglebone PRU\": cd ~/klipper/ make menuconfig To build and install the new micro-controller code, run: sudo service klipper stop make flash sudo service klipper start 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 Remaining configuration \u00b6 Complete the installation by configuring Klipper and Octoprint 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.","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 9.9 2019-08-03 4GB SD 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 ) and install Klipper by running the following commands: git clone https://github.com/Klipper3d/klipper ./klipper/scripts/install-beaglebone.sh","title":"Building an OS image"},{"location":"Beaglebone.html#install-octoprint","text":"One may then install Octoprint: 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 Make sure the OctoPrint web server is accessible - it should be at: http://beaglebone:5000/","title":"Install Octoprint"},{"location":"Beaglebone.html#building-the-micro-controller-code","text":"To compile the Klipper micro-controller code, start by configuring it for the \"Beaglebone PRU\": cd ~/klipper/ make menuconfig To build and install the new micro-controller code, run: sudo service klipper stop make flash sudo service klipper start 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","title":"Building the micro-controller code"},{"location":"Beaglebone.html#remaining-configuration","text":"Complete the installation by configuring Klipper and Octoprint 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.","title":"Printing on the Beaglebone"},{"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 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 postion 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. The deprecated relative_reference_index \u00b6 Existing configurations using the relative_reference_index option must be updated to use the zero_reference_position . The response to the BED_MESH_OUTPUT PGP=1 gcode command will include the (X, Y) coordinate associated with the index; this position may be used as the value for the zero_reference_position . The output will look similar to the following: // bed_mesh: generated points // Index | Tool Adjusted | Probe // 0 | (1.0, 1.0) | (24.0, 6.0) // 1 | (36.7, 1.0) | (59.7, 6.0) // 2 | (72.3, 1.0) | (95.3, 6.0) // 3 | (108.0, 1.0) | (131.0, 6.0) ... (additional generated points) // bed_mesh: relative_reference_index 24 is (131.5, 108.0) Note: The above output is also printed in klippy.log during initialization. Using the example above we see that the relative_reference_index is printed along with its coordinate. Thus the zero_reference_position is 131.5, 108 . 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. Bed Mesh Gcodes \u00b6 Calibration \u00b6 BED_MESH_CALIBRATE PROFILE=<name> METHOD=[manual | automatic] [<probe_parameter>=<value>] [<mesh_parameter>=<value>] Default Profile: default Default Method: automatic if a probe is detected, otherwise manual Initiates the probing procedure for Bed Mesh Calibration. The mesh will be saved into a profile specified by the PROFILE parameter, or default if unspecified. If METHOD=manual is selected then manual probing will occur. When switching between automatic and manual probing the generated mesh points will automatically be adjusted. 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: ALGORITHM 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. 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>] 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, and a positive Y offset should be specified if the secondary extruder is mounted \"behind\" the primary extruder.","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 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 postion 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#the-deprecated-relative_reference_index","text":"Existing configurations using the relative_reference_index option must be updated to use the zero_reference_position . The response to the BED_MESH_OUTPUT PGP=1 gcode command will include the (X, Y) coordinate associated with the index; this position may be used as the value for the zero_reference_position . The output will look similar to the following: // bed_mesh: generated points // Index | Tool Adjusted | Probe // 0 | (1.0, 1.0) | (24.0, 6.0) // 1 | (36.7, 1.0) | (59.7, 6.0) // 2 | (72.3, 1.0) | (95.3, 6.0) // 3 | (108.0, 1.0) | (131.0, 6.0) ... (additional generated points) // bed_mesh: relative_reference_index 24 is (131.5, 108.0) Note: The above output is also printed in klippy.log during initialization. Using the example above we see that the relative_reference_index is printed along with its coordinate. Thus the zero_reference_position is 131.5, 108 .","title":"The deprecated relative_reference_index"},{"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#bed-mesh-gcodes","text":"","title":"Bed Mesh Gcodes"},{"location":"Bed_Mesh.html#calibration","text":"BED_MESH_CALIBRATE PROFILE=<name> METHOD=[manual | automatic] [<probe_parameter>=<value>] [<mesh_parameter>=<value>] Default Profile: default Default Method: automatic if a probe is detected, otherwise manual Initiates the probing procedure for Bed Mesh Calibration. The mesh will be saved into a profile specified by the PROFILE parameter, or default if unspecified. If METHOD=manual is selected then manual probing will occur. When switching between automatic and manual probing the generated mesh points will automatically be adjusted. 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: ALGORITHM 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. 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>] 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, and a positive Y offset should be specified if the secondary extruder is mounted \"behind\" the primary extruder.","title":"Apply X/Y offsets"},{"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 a STM32H743VIT6: allocate_oids count=3 config_stepper oid=0 step_pin=PD4 dir_pin=PD3 invert_step=-1 step_pulse_ticks=0 config_stepper oid=1 step_pin=PA15 dir_pin=PA8 invert_step=-1 step_pulse_ticks=0 config_stepper oid=2 step_pin=PE2 dir_pin=PE3 invert_step=-1 step_pulse_ticks=0 finalize_config crc=0 The test was last run on commit 00191b5c with gcc version arm-none-eabi-gcc (15:8-2019-q3-1+b1) 8.3.1 20190703 (release) [gcc-8-branch revision 273027] . stm32h7 ticks 1 stepper 44 3 stepper 198 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 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 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 08d037c6 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 RP2040 step rate benchmark \u00b6 The following configuration sequence is used on the RP2040: 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 59314d99 with gcc version arm-none-eabi-gcc (Fedora 10.2.0-4.fc34) 10.2.0 on a Raspberry Pi Pico board. rp2040 ticks 1 stepper 5 3 stepper 22 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 . Note that this test may saturate the USB/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 high-speed hub. MCU Rate Build Build compiler stm32f042 (CAN) 18K c105adc8 arm-none-eabi-gcc (GNU Tools 7-2018-q3-update) 7.3.1 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 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) 873K c5667193 arm-none-eabi-gcc (Fedora 10.2.0-4.fc34) 10.2.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 a STM32H743VIT6: allocate_oids count=3 config_stepper oid=0 step_pin=PD4 dir_pin=PD3 invert_step=-1 step_pulse_ticks=0 config_stepper oid=1 step_pin=PA15 dir_pin=PA8 invert_step=-1 step_pulse_ticks=0 config_stepper oid=2 step_pin=PE2 dir_pin=PE3 invert_step=-1 step_pulse_ticks=0 finalize_config crc=0 The test was last run on commit 00191b5c with gcc version arm-none-eabi-gcc (15:8-2019-q3-1+b1) 8.3.1 20190703 (release) [gcc-8-branch revision 273027] . stm32h7 ticks 1 stepper 44 3 stepper 198","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#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#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 08d037c6 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#rp2040-step-rate-benchmark","text":"The following configuration sequence is used on the RP2040: 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 59314d99 with gcc version arm-none-eabi-gcc (Fedora 10.2.0-4.fc34) 10.2.0 on a Raspberry Pi Pico board. rp2040 ticks 1 stepper 5 3 stepper 22","title":"RP2040 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 . Note that this test may saturate the USB/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 high-speed hub. MCU Rate Build Build compiler stm32f042 (CAN) 18K c105adc8 arm-none-eabi-gcc (GNU Tools 7-2018-q3-update) 7.3.1 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 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) 873K c5667193 arm-none-eabi-gcc (Fedora 10.2.0-4.fc34) 10.2.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 Rasberry 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 Rasberry 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 ifconfig $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 ifconfig $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\". Even at a CAN bus frequency of 1000000, there may not be sufficient bandwidth to run a SHAPER_CALIBRATE test if both the XY steppers and the accelerometer all communicate via a single \"USB to CAN bus\" interface. 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 ifconfig $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 ifconfig $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\". Even at a CAN bus frequency of 1000000, there may not be sufficient bandwidth to run a SHAPER_CALIBRATE test if both the XY steppers and the accelerometer all communicate via a single \"USB to CAN bus\" interface. 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. There are two known causes of reordered messages: Old versions of the popular candlight_firmware for USB CAN adapters had a bug that could cause reordered messages. If using a USB CAN adapter running this firmware then make sure to update to the latest firmware if incrementing bytes_invalid is observed. Some Linux kernel builds for embedded devices have been known to reorder CAN bus messages. It may be necessary to use an alternative Linux kernel or to use alternative hardware that supports mainstream Linux kernels that do not exhibit this problem. 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. 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. There are two known causes of reordered messages: Old versions of the popular candlight_firmware for USB CAN adapters had a bug that could cause reordered messages. If using a USB CAN adapter running this firmware then make sure to update to the latest firmware if incrementing bytes_invalid is observed. Some Linux kernel builds for embedded devices have been known to reorder CAN bus messages. It may be necessary to use an alternative Linux kernel or to use alternative hardware that supports mainstream Linux kernels that do not exhibit this problem. 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.","title":"Check for incrementing bytes_invalid counter"},{"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-tranlations 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-tranlations 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() -> MoveQueue.add_move() -> MoveQueue.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. MoveQueue.add_move() places the move object on the \"look-ahead\" queue. MoveQueue.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._update_move_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. 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() , 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() -> MoveQueue.add_move() -> MoveQueue.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. MoveQueue.add_move() places the move object on the \"look-ahead\" queue. MoveQueue.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._update_move_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. 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() , 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 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 superceded 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 paramter. 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":"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 superceded 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 paramter. 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, 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. #max_accel_to_decel: # A pseudo acceleration (in mm/s^2) controlling how fast the # toolhead may go from acceleration to deceleration. It is used to # reduce the top speed of short zig-zag moves (and thus reduce # printer vibration from these moves). The value specified here may # be changed at runtime using the SET_VELOCITY_LIMIT command. The # default is half of max_accel. #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. 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. #relative_reference_index: # **DEPRECATED, use the \"zero_reference_position\" option** # The legacy option superceded by the \"zero reference position\". # Rather than a coordinate this option takes an integer \"index\" that # refers to the location of one of the generated points. It is recommended # to use the \"zero_reference_position\" instead of this option for new # configurations. The default is no relative reference index. #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. [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. [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. [lis2dw] \u00b6 Support for LIS2DW accelerometers. [lis2dw] 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 # 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. #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: 75 # 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). 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. [axis_twist_compensation] \u00b6 A tool to compensate for inaccurate probe readings due to twist in X 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. This parameter must be provided. 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. This parameter must be provided. 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 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 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. [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 carraiges), 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. [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. 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 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/BME680 temperature sensor \u00b6 BMP180/BMP280/BME280/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 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 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. #scl_pin: #sda_pin: # Alternatively, if the pca9632 is not connected to a hardware I2C # bus, then one may specify the \"clock\" (scl_pin) and \"data\" # (sda_pin) pins. The default is to use hardware I2C. #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. [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. #static_value: # If this is set, then the pin is assigned to this value at startup # and the pin can not be changed during runtime. A static pin uses # slightly less ram in the micro-controller. The default is to use # runtime configuration of pins. #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). #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. #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. [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. #value: #shutdown_value: #maximum_mcu_duration: #cycle_time: 0.100 #hardware_pwm: False #scale: # See the \"output_pin\" section for the definition of 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. The default is 0, which disables # \"stealthChop\" mode. #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_PWM_AUTOSCALE: True #driver_PWM_FREQ: 1 #driver_PWM_GRAD: 4 #driver_PWM_AMPL: 128 #driver_SGT: 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. 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 # 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. #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_SGTHRS: 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. The default is 0, which disables # \"stealthChop\" mode. #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 # 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. The default is 0, which disables # \"stealthChop\" mode. #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 two gpio \"bit banging\" pins (one may define any number of sections with an \"mcp4018\" prefix). [mcp4018 my_digipot] scl_pin: # The SCL \"clock\" pin. This parameter must be provided. sda_pin: # The SDA \"data\" pin. This parameter must be provided. 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\", # \"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 # 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. ... 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. #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 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. 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. [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 remo 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, 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\", 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 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, 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. #max_accel_to_decel: # A pseudo acceleration (in mm/s^2) controlling how fast the # toolhead may go from acceleration to deceleration. It is used to # reduce the top speed of short zig-zag moves (and thus reduce # printer vibration from these moves). The value specified here may # be changed at runtime using the SET_VELOCITY_LIMIT command. The # default is half of max_accel. #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#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. #relative_reference_index: # **DEPRECATED, use the \"zero_reference_position\" option** # The legacy option superceded by the \"zero reference position\". # Rather than a coordinate this option takes an integer \"index\" that # refers to the location of one of the generated points. It is recommended # to use the \"zero_reference_position\" instead of this option for new # configurations. The default is no relative reference index. #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.","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.","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#lis2dw","text":"Support for LIS2DW accelerometers. [lis2dw] 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 # See the \"adxl345\" section for information on this parameter.","title":"[lis2dw]"},{"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. #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: 75 # 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).","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#axis_twist_compensation","text":"A tool to compensate for inaccurate probe readings due to twist in X 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. This parameter must be provided. 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. This parameter must be provided. 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 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 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. [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 carraiges), 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.","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.","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-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#bmp180bmp280bme280bme680-temperature-sensor","text":"BMP180/BMP280/BME280/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 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/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#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. #scl_pin: #sda_pin: # Alternatively, if the pca9632 is not connected to a hardware I2C # bus, then one may specify the \"clock\" (scl_pin) and \"data\" # (sda_pin) pins. The default is to use hardware I2C. #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.","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. #static_value: # If this is set, then the pin is assigned to this value at startup # and the pin can not be changed during runtime. A static pin uses # slightly less ram in the micro-controller. The default is to use # runtime configuration of pins. #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). #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. #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.","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. #value: #shutdown_value: #maximum_mcu_duration: #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#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. The default is 0, which disables # \"stealthChop\" mode. #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_PWM_AUTOSCALE: True #driver_PWM_FREQ: 1 #driver_PWM_GRAD: 4 #driver_PWM_AMPL: 128 #driver_SGT: 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. 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 # 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. #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_SGTHRS: 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. The default is 0, which disables # \"stealthChop\" mode. #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 # 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. The default is 0, which disables # \"stealthChop\" mode. #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 two gpio \"bit banging\" pins (one may define any number of sections with an \"mcp4018\" prefix). [mcp4018 my_digipot] scl_pin: # The SCL \"clock\" pin. This parameter must be provided. sda_pin: # The SDA \"data\" pin. This parameter must be provided. 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\", # \"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 # 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#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. #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 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#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#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 remo 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, 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\", 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 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 .","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":"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":"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 2, Raspberry Pi 3, or Raspberry Pi 4. Klipper will run on a Raspberry Pi 1 and on the Raspberry Pi Zero, but these boards don't have enough processing power to run OctoPrint well. It is common for print stalls to occur on these slower machines when printing directly from OctoPrint. (The printer may move faster than OctoPrint can send movement commands.) If you wish to run on one one of these slower boards anyway, consider using the \"virtual_sdcard\" feature when printing (see config reference for details). 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 2, Raspberry Pi 3, or Raspberry Pi 4. Klipper will run on a Raspberry Pi 1 and on the Raspberry Pi Zero, but these boards don't have enough processing power to run OctoPrint well. It is common for print stalls to occur on these slower machines when printing directly from OctoPrint. (The printer may move faster than OctoPrint can send movement commands.) If you wish to run on one one of these slower boards anyway, consider using the \"virtual_sdcard\" feature when printing (see config reference for details). 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. 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. 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, 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. 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, and lis2dw12 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 RP2040 2400K 1636K SAM4E8E 2500K 1674K SAMD51 3077K 1885K AR100 3529K 2507K STM32F407 3652K 2459K STM32F446 3913K 2634K STM32H743 9091K 6061K 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. 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. 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, 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. 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, and lis2dw12 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 RP2040 2400K 1636K SAM4E8E 2500K 1674K SAMD51 3077K 1885K AR100 3529K 2507K STM32F407 3652K 2459K STM32F446 3913K 2634K STM32H743 9091K 6061K 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_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. [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 [METHOD=manual] [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>] [<mesh_parameter>=<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. 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. 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>] : Applies X and/or Y 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. [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=[0|1] [MODE=[PRIMARY|COPY|MIRROR]] : This command will change the mode of the specified carriage. If no MODE is provided it defaults to PRIMARY . 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 CARRIAGE=1 . When set to either of these modes, carriage 1 will then track the subsequent moves of the carriage 0 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 carraige. [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. SET_EXTRUDER_STEP_DISTANCE \u00b6 This command is deprecated and will be removed in the near future. SYNC_STEPPER_TO_EXTRUDER \u00b6 This command is deprecated and will be removed in the near future. [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. [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>] : Force the low-level kinematic code to believe the toolhead is at the given cartesian position. This is a diagnostic and debugging command; use SET_GCODE_OFFSET and/or G92 for regular axis transformations. If an axis is not specified then it will default to the position that the head was last commanded to. Setting an incorrect or invalid position may lead to internal software errors. This command may invalidate future boundary checks; issue a G28 afterwards to reset the kinematics. [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. [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. [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. [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'. [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). [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> [CYCLE_TIME=<cycle_time>] : 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. Some pins (currently only \"soft PWM\" pins) support 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 output_pin config section). [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. [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. [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. [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. [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>] [HZ_PER_SEC=<hz_per_sec>] [CHIPS=<adxl345_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. adxl345_chip_name can be one or more configured adxl345 chip,delimited with comma, for example CHIPS=\"adxl345, adxl345 rpi\" . Note that adxl345 can be omitted from named adxl345 chips. 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>] [HZ_PER_SEC=<hz_per_sec>] [CHIPS=<adxl345_chip_name>] [MAX_SMOOTHING=<max_smoothing>] : 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. 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. [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>] [ACCEL_TO_DECEL=<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. [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 [SAMPLE_COUNT=<value>] : Initiates the X twist calibration wizard. SAMPLE_COUNT specifies the number of points along the X axis to calibrate at and defaults to 3. [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 [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 HORIZONTAL_MOVE_Z value overrides the horizontal_move_z option 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_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#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 [METHOD=manual] [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>] [<mesh_parameter>=<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. 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_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>] : Applies X and/or Y 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.","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=[0|1] [MODE=[PRIMARY|COPY|MIRROR]] : This command will change the mode of the specified carriage. If no MODE is provided it defaults to PRIMARY . 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 CARRIAGE=1 . When set to either of these modes, carriage 1 will then track the subsequent moves of the carriage 0 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 carraige.","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#set_extruder_step_distance","text":"This command is deprecated and will be removed in the near future.","title":"SET_EXTRUDER_STEP_DISTANCE"},{"location":"G-Codes.html#sync_stepper_to_extruder","text":"This command is deprecated and will be removed in the near future.","title":"SYNC_STEPPER_TO_EXTRUDER"},{"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.","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>] : Force the low-level kinematic code to believe the toolhead is at the given cartesian position. This is a diagnostic and debugging command; use SET_GCODE_OFFSET and/or G92 for regular axis transformations. If an axis is not specified then it will default to the position that the head was last commanded to. Setting an incorrect or invalid position may lead to internal software errors. This command may invalidate future boundary checks; issue a G28 afterwards to reset the kinematics.","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#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#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.","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#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#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> [CYCLE_TIME=<cycle_time>] : 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. Some pins (currently only \"soft PWM\" pins) support 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 output_pin config section).","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#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#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#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#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>] [HZ_PER_SEC=<hz_per_sec>] [CHIPS=<adxl345_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. adxl345_chip_name can be one or more configured adxl345 chip,delimited with comma, for example CHIPS=\"adxl345, adxl345 rpi\" . Note that adxl345 can be omitted from named adxl345 chips. 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>] [HZ_PER_SEC=<hz_per_sec>] [CHIPS=<adxl345_chip_name>] [MAX_SMOOTHING=<max_smoothing>] : 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. 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#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>] [ACCEL_TO_DECEL=<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#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 [SAMPLE_COUNT=<value>] : Initiates the X twist calibration wizard. SAMPLE_COUNT specifies the number of points along the X axis to calibrate at and defaults to 3.","title":"AXIS_TWIST_COMPENSATION_CALIBRATE"},{"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 [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 HORIZONTAL_MOVE_Z value overrides the horizontal_move_z option 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 Raspberry Pi computer in conjunction with OctoPrint. It is recommended that a Raspberry Pi 2 (or later) be used as the host machine (see the FAQ for other machines). Obtain a Klipper Configuration File \u00b6 Most Klipper settings are determined by a \"printer configuration file\" that will be stored on the Raspberry Pi. 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. Prepping an OS image \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 to v1.4.2 or later. After installing OctoPi and upgrading OctoPrint, it will be necessary to ssh into the target machine to run a handful of system commands. If using a Linux or MacOS desktop, then the \"ssh\" software should already be installed on the desktop. There are free ssh clients available for other desktops (eg, PuTTY ). Use the ssh utility to connect to the Raspberry Pi ( ssh pi@octopi -- password is \"raspberry\") and run the following commands: git clone https://github.com/Klipper3d/klipper ./klipper/scripts/install-octopi.sh The above will download Klipper, install some 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. Building and flashing the micro-controller \u00b6 To compile the micro-controller code, start by running these commands on the Raspberry Pi: 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 (see the FAQ for more information). For common micro-controllers, 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. When flashing for the first time, make sure that OctoPrint is not connected directly to the printer (from the OctoPrint web page, under the \"Connection\" section, click \"Disconnect\"). 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 /tmp/printer . Then click \"Save\". Enter the Settings tab again and under \"Serial Connection\" change the \"Serial Port\" setting to /tmp/printer . 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 /tmp/printer and click \"Connect\". (If /tmp/printer is not an 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. Proceed to the next section. Configuring Klipper \u00b6 The next step is to copy the printer configuration file to the Raspberry Pi. Arguably the easiest way to set the Klipper configuration file 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 Raspberry Pi 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 OctoPrint web terminal to load the config. A \"status\" command will report 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 OctoPrint terminal tab. The \"status\" command can be used to re-report error messages. The default Klipper startup script also places a log in /tmp/klippy.log which provides more detailed information. 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 Raspberry Pi computer in conjunction with OctoPrint. It is recommended that a Raspberry Pi 2 (or later) be used as the host machine (see the FAQ for other machines).","title":"Installation"},{"location":"Installation.html#obtain-a-klipper-configuration-file","text":"Most Klipper settings are determined by a \"printer configuration file\" that will be stored on the Raspberry Pi. 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#prepping-an-os-image","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 to v1.4.2 or later. After installing OctoPi and upgrading OctoPrint, it will be necessary to ssh into the target machine to run a handful of system commands. If using a Linux or MacOS desktop, then the \"ssh\" software should already be installed on the desktop. There are free ssh clients available for other desktops (eg, PuTTY ). Use the ssh utility to connect to the Raspberry Pi ( ssh pi@octopi -- password is \"raspberry\") and run the following commands: git clone https://github.com/Klipper3d/klipper ./klipper/scripts/install-octopi.sh The above will download Klipper, install some 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":"Prepping an OS image"},{"location":"Installation.html#building-and-flashing-the-micro-controller","text":"To compile the micro-controller code, start by running these commands on the Raspberry Pi: 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 (see the FAQ for more information). For common micro-controllers, 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. When flashing for the first time, make sure that OctoPrint is not connected directly to the printer (from the OctoPrint web page, under the \"Connection\" section, click \"Disconnect\").","title":"Building and flashing the micro-controller"},{"location":"Installation.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 /tmp/printer . Then click \"Save\". Enter the Settings tab again and under \"Serial Connection\" change the \"Serial Port\" setting to /tmp/printer . 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 /tmp/printer and click \"Connect\". (If /tmp/printer is not an 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. Proceed to the next section.","title":"Configuring OctoPrint to use Klipper"},{"location":"Installation.html#configuring-klipper","text":"The next step is to copy the printer configuration file to the Raspberry Pi. Arguably the easiest way to set the Klipper configuration file 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 Raspberry Pi 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 OctoPrint web terminal to load the config. A \"status\" command will report 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 OctoPrint terminal tab. The \"status\" command can be used to re-report error messages. The default Klipper startup script also places a log in /tmp/klippy.log which provides more detailed information. 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 Smoothed look-ahead \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. To reduce this, Klipper tracks both regular move acceleration as well as a virtual \"acceleration to deceleration\" rate. Using this system, the top speed of these short \"zigzag\" moves are limited to smooth out the printer motion: Specifically, the code calculates what the velocity of each move would be if it were limited to this virtual \"acceleration to deceleration\" rate (half the normal acceleration rate by default). 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#smoothed-look-ahead","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. To reduce this, Klipper tracks both regular move acceleration as well as a virtual \"acceleration to deceleration\" rate. Using this system, the top speed of these short \"zigzag\" moves are limited to smooth out the printer motion: Specifically, the code calculates what the velocity of each move would be if it were limited to this virtual \"acceleration to deceleration\" rate (half the normal acceleration rate by default). 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":"Smoothed look-ahead"},{"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":"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 and LIS2DW 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/LIS2DW 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. 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/LIS2DWs, 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-6500s 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 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 \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 buit-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 Next, in order to install NumPy in the Klipper environment, run the command: ~/klippy-env/bin/pip install -v numpy 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. 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 \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 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 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 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. To do that, run the following commands: ~/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. 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. 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 and LIS2DW 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/LIS2DW 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. 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/LIS2DWs, 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-6500s 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","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-6500","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 buit-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"},{"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 Next, in order to install NumPy in the Klipper environment, run the command: ~/klippy-env/bin/pip install -v numpy 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.","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","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"},{"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","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","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 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. To do that, run the following commands: ~/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. 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#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":"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. 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","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. 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","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\" is 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\" is 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.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-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. Increase max_accel_to_decel by issuing the following command: SET_VELOCITY_LIMIT ACCEL_TO_DECEL=7000 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 ACCEL_TO_DECEL=7000 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 ACCEL_TO_DECEL=7000 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 ACCEL_TO_DECEL=7000 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. Increase max_accel_to_decel by issuing the following command: SET_VELOCITY_LIMIT ACCEL_TO_DECEL=7000 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 ACCEL_TO_DECEL=7000 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 ACCEL_TO_DECEL=7000 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 ACCEL_TO_DECEL=7000 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_correcton] 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_correcton. 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_correcton] 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_correcton. 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 paramaters 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 paramaters 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 Config_Reference.md#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. 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: 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). 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 underyling 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] . 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. 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. 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 , 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, 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 , max_accel_to_decel , 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\". 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 Config_Reference.md#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#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: 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).","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 underyling 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#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#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#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 , 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, 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 , max_accel_to_decel , 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\".","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. 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.","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":"Klipper is a 3d-Printer firmware. It combines the power of a general purpose computer with one or more micro-controllers. See the features document for more information on why you should use Klipper. To begin using Klipper start by installing it. Klipper is Free Software. Read the documentation or view the Klipper code on github . 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. 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.","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#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":"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. After setting up the [axis_twist_compensation] module, perform AXIS_TWIST_COMPENSATION_CALIBRATE * The calibration wizard will prompt you to measure the probe Z offset at a few points along the bed * The calibration defaults to 3 points but you can use the option SAMPLE_COUNT= to use a different number. Adjust your Z offset Perform automatic/probe-based bed tramming operations, such as Screws Tilt Adjust , Z Tilt Adjust etc Home all axis, then perform a Bed Mesh if required Perform a test print, followed by any fine-tuning as desired 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. After setting up the [axis_twist_compensation] module, perform AXIS_TWIST_COMPENSATION_CALIBRATE * The calibration wizard will prompt you to measure the probe Z offset at a few points along the bed * The calibration defaults to 3 points but you can use the option SAMPLE_COUNT= to use a different number. Adjust your Z offset Perform automatic/probe-based bed tramming operations, such as Screws Tilt Adjust , Z Tilt Adjust etc Home all axis, then perform a Bed Mesh if required Perform a test print, followed by any fine-tuning as desired Tip: Bed temperature and nozzle temperature and size do not seem to have an influence to the calibration process.","title":"Overview of compensation usage"},{"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 9.9 2019-08-03 4GB SD 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 ) and install Klipper by running the following commands: git clone https://github.com/Klipper3d/klipper ./klipper/scripts/install-beaglebone.sh Install Octoprint \u00b6 One may then install Octoprint: 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 Make sure the OctoPrint web server is accessible - it should be at: http://beaglebone:5000/ Building the micro-controller code \u00b6 To compile the Klipper micro-controller code, start by configuring it for the \"Beaglebone PRU\": cd ~/klipper/ make menuconfig To build and install the new micro-controller code, run: sudo service klipper stop make flash sudo service klipper start 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 Remaining configuration \u00b6 Complete the installation by configuring Klipper and Octoprint 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.","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 9.9 2019-08-03 4GB SD 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 ) and install Klipper by running the following commands: git clone https://github.com/Klipper3d/klipper ./klipper/scripts/install-beaglebone.sh","title":"Building an OS image"},{"location":"Beaglebone.html#install-octoprint","text":"One may then install Octoprint: 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 Make sure the OctoPrint web server is accessible - it should be at: http://beaglebone:5000/","title":"Install Octoprint"},{"location":"Beaglebone.html#building-the-micro-controller-code","text":"To compile the Klipper micro-controller code, start by configuring it for the \"Beaglebone PRU\": cd ~/klipper/ make menuconfig To build and install the new micro-controller code, run: sudo service klipper stop make flash sudo service klipper start 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","title":"Building the micro-controller code"},{"location":"Beaglebone.html#remaining-configuration","text":"Complete the installation by configuring Klipper and Octoprint 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.","title":"Printing on the Beaglebone"},{"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 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 postion 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. The deprecated relative_reference_index \u00b6 Existing configurations using the relative_reference_index option must be updated to use the zero_reference_position . The response to the BED_MESH_OUTPUT PGP=1 gcode command will include the (X, Y) coordinate associated with the index; this position may be used as the value for the zero_reference_position . The output will look similar to the following: // bed_mesh: generated points // Index | Tool Adjusted | Probe // 0 | (1.0, 1.0) | (24.0, 6.0) // 1 | (36.7, 1.0) | (59.7, 6.0) // 2 | (72.3, 1.0) | (95.3, 6.0) // 3 | (108.0, 1.0) | (131.0, 6.0) ... (additional generated points) // bed_mesh: relative_reference_index 24 is (131.5, 108.0) Note: The above output is also printed in klippy.log during initialization. Using the example above we see that the relative_reference_index is printed along with its coordinate. Thus the zero_reference_position is 131.5, 108 . 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. Bed Mesh Gcodes \u00b6 Calibration \u00b6 BED_MESH_CALIBRATE PROFILE=<name> METHOD=[manual | automatic] [<probe_parameter>=<value>] [<mesh_parameter>=<value>] Default Profile: default Default Method: automatic if a probe is detected, otherwise manual Initiates the probing procedure for Bed Mesh Calibration. The mesh will be saved into a profile specified by the PROFILE parameter, or default if unspecified. If METHOD=manual is selected then manual probing will occur. When switching between automatic and manual probing the generated mesh points will automatically be adjusted. 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: ALGORITHM 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. 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>] 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, and a positive Y offset should be specified if the secondary extruder is mounted \"behind\" the primary extruder.","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 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 postion 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#the-deprecated-relative_reference_index","text":"Existing configurations using the relative_reference_index option must be updated to use the zero_reference_position . The response to the BED_MESH_OUTPUT PGP=1 gcode command will include the (X, Y) coordinate associated with the index; this position may be used as the value for the zero_reference_position . The output will look similar to the following: // bed_mesh: generated points // Index | Tool Adjusted | Probe // 0 | (1.0, 1.0) | (24.0, 6.0) // 1 | (36.7, 1.0) | (59.7, 6.0) // 2 | (72.3, 1.0) | (95.3, 6.0) // 3 | (108.0, 1.0) | (131.0, 6.0) ... (additional generated points) // bed_mesh: relative_reference_index 24 is (131.5, 108.0) Note: The above output is also printed in klippy.log during initialization. Using the example above we see that the relative_reference_index is printed along with its coordinate. Thus the zero_reference_position is 131.5, 108 .","title":"The deprecated relative_reference_index"},{"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#bed-mesh-gcodes","text":"","title":"Bed Mesh Gcodes"},{"location":"Bed_Mesh.html#calibration","text":"BED_MESH_CALIBRATE PROFILE=<name> METHOD=[manual | automatic] [<probe_parameter>=<value>] [<mesh_parameter>=<value>] Default Profile: default Default Method: automatic if a probe is detected, otherwise manual Initiates the probing procedure for Bed Mesh Calibration. The mesh will be saved into a profile specified by the PROFILE parameter, or default if unspecified. If METHOD=manual is selected then manual probing will occur. When switching between automatic and manual probing the generated mesh points will automatically be adjusted. 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: ALGORITHM 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. 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>] 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, and a positive Y offset should be specified if the secondary extruder is mounted \"behind\" the primary extruder.","title":"Apply X/Y offsets"},{"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 a STM32H743VIT6: allocate_oids count=3 config_stepper oid=0 step_pin=PD4 dir_pin=PD3 invert_step=-1 step_pulse_ticks=0 config_stepper oid=1 step_pin=PA15 dir_pin=PA8 invert_step=-1 step_pulse_ticks=0 config_stepper oid=2 step_pin=PE2 dir_pin=PE3 invert_step=-1 step_pulse_ticks=0 finalize_config crc=0 The test was last run on commit 00191b5c with gcc version arm-none-eabi-gcc (15:8-2019-q3-1+b1) 8.3.1 20190703 (release) [gcc-8-branch revision 273027] . stm32h7 ticks 1 stepper 44 3 stepper 198 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 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 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 08d037c6 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 RP2040 step rate benchmark \u00b6 The following configuration sequence is used on the RP2040: 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 59314d99 with gcc version arm-none-eabi-gcc (Fedora 10.2.0-4.fc34) 10.2.0 on a Raspberry Pi Pico board. rp2040 ticks 1 stepper 5 3 stepper 22 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 . Note that this test may saturate the USB/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 high-speed hub. MCU Rate Build Build compiler stm32f042 (CAN) 18K c105adc8 arm-none-eabi-gcc (GNU Tools 7-2018-q3-update) 7.3.1 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 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) 873K c5667193 arm-none-eabi-gcc (Fedora 10.2.0-4.fc34) 10.2.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 a STM32H743VIT6: allocate_oids count=3 config_stepper oid=0 step_pin=PD4 dir_pin=PD3 invert_step=-1 step_pulse_ticks=0 config_stepper oid=1 step_pin=PA15 dir_pin=PA8 invert_step=-1 step_pulse_ticks=0 config_stepper oid=2 step_pin=PE2 dir_pin=PE3 invert_step=-1 step_pulse_ticks=0 finalize_config crc=0 The test was last run on commit 00191b5c with gcc version arm-none-eabi-gcc (15:8-2019-q3-1+b1) 8.3.1 20190703 (release) [gcc-8-branch revision 273027] . stm32h7 ticks 1 stepper 44 3 stepper 198","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#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#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 08d037c6 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#rp2040-step-rate-benchmark","text":"The following configuration sequence is used on the RP2040: 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 59314d99 with gcc version arm-none-eabi-gcc (Fedora 10.2.0-4.fc34) 10.2.0 on a Raspberry Pi Pico board. rp2040 ticks 1 stepper 5 3 stepper 22","title":"RP2040 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 . Note that this test may saturate the USB/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 high-speed hub. MCU Rate Build Build compiler stm32f042 (CAN) 18K c105adc8 arm-none-eabi-gcc (GNU Tools 7-2018-q3-update) 7.3.1 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 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) 873K c5667193 arm-none-eabi-gcc (Fedora 10.2.0-4.fc34) 10.2.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 Rasberry 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 Rasberry 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 ifconfig $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 ifconfig $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\". Even at a CAN bus frequency of 1000000, there may not be sufficient bandwidth to run a SHAPER_CALIBRATE test if both the XY steppers and the accelerometer all communicate via a single \"USB to CAN bus\" interface. 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 ifconfig $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 ifconfig $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\". Even at a CAN bus frequency of 1000000, there may not be sufficient bandwidth to run a SHAPER_CALIBRATE test if both the XY steppers and the accelerometer all communicate via a single \"USB to CAN bus\" interface. 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. There are two known causes of reordered messages: Old versions of the popular candlight_firmware for USB CAN adapters had a bug that could cause reordered messages. If using a USB CAN adapter running this firmware then make sure to update to the latest firmware if incrementing bytes_invalid is observed. Some Linux kernel builds for embedded devices have been known to reorder CAN bus messages. It may be necessary to use an alternative Linux kernel or to use alternative hardware that supports mainstream Linux kernels that do not exhibit this problem. 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. 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. There are two known causes of reordered messages: Old versions of the popular candlight_firmware for USB CAN adapters had a bug that could cause reordered messages. If using a USB CAN adapter running this firmware then make sure to update to the latest firmware if incrementing bytes_invalid is observed. Some Linux kernel builds for embedded devices have been known to reorder CAN bus messages. It may be necessary to use an alternative Linux kernel or to use alternative hardware that supports mainstream Linux kernels that do not exhibit this problem. 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.","title":"Check for incrementing bytes_invalid counter"},{"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-tranlations 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-tranlations 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. 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() , 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. 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() , 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 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 superceded 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 paramter. 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":"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 superceded 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 paramter. 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, 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. #max_accel_to_decel: # A pseudo acceleration (in mm/s^2) controlling how fast the # toolhead may go from acceleration to deceleration. It is used to # reduce the top speed of short zig-zag moves (and thus reduce # printer vibration from these moves). The value specified here may # be changed at runtime using the SET_VELOCITY_LIMIT command. The # default is half of max_accel. #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. 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. #relative_reference_index: # **DEPRECATED, use the \"zero_reference_position\" option** # The legacy option superceded by the \"zero reference position\". # Rather than a coordinate this option takes an integer \"index\" that # refers to the location of one of the generated points. It is recommended # to use the \"zero_reference_position\" instead of this option for new # configurations. The default is no relative reference index. #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. [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. [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. [lis2dw] \u00b6 Support for LIS2DW accelerometers. [lis2dw] 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 # 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. #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: 75 # 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). 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. [axis_twist_compensation] \u00b6 A tool to compensate for inaccurate probe readings due to twist in X 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. This parameter must be provided. 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. This parameter must be provided. 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 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 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. [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 carraiges), 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. [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. 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 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/BME680 temperature sensor \u00b6 BMP180/BMP280/BME280/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 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 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. #scl_pin: #sda_pin: # Alternatively, if the pca9632 is not connected to a hardware I2C # bus, then one may specify the \"clock\" (scl_pin) and \"data\" # (sda_pin) pins. The default is to use hardware I2C. #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. [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. #static_value: # If this is set, then the pin is assigned to this value at startup # and the pin can not be changed during runtime. A static pin uses # slightly less ram in the micro-controller. The default is to use # runtime configuration of pins. #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). #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. #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. [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. #value: #shutdown_value: #maximum_mcu_duration: #cycle_time: 0.100 #hardware_pwm: False #scale: # See the \"output_pin\" section for the definition of 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. The default is 0, which disables # \"stealthChop\" mode. #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_PWM_AUTOSCALE: True #driver_PWM_FREQ: 1 #driver_PWM_GRAD: 4 #driver_PWM_AMPL: 128 #driver_SGT: 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. 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 # 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. #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_SGTHRS: 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. The default is 0, which disables # \"stealthChop\" mode. #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 # 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. The default is 0, which disables # \"stealthChop\" mode. #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 two gpio \"bit banging\" pins (one may define any number of sections with an \"mcp4018\" prefix). [mcp4018 my_digipot] scl_pin: # The SCL \"clock\" pin. This parameter must be provided. sda_pin: # The SDA \"data\" pin. This parameter must be provided. 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\", # \"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 # 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. ... 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. #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 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. 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. [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 remo 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, 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\", 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 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, 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. #max_accel_to_decel: # A pseudo acceleration (in mm/s^2) controlling how fast the # toolhead may go from acceleration to deceleration. It is used to # reduce the top speed of short zig-zag moves (and thus reduce # printer vibration from these moves). The value specified here may # be changed at runtime using the SET_VELOCITY_LIMIT command. The # default is half of max_accel. #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#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. #relative_reference_index: # **DEPRECATED, use the \"zero_reference_position\" option** # The legacy option superceded by the \"zero reference position\". # Rather than a coordinate this option takes an integer \"index\" that # refers to the location of one of the generated points. It is recommended # to use the \"zero_reference_position\" instead of this option for new # configurations. The default is no relative reference index. #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.","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.","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#lis2dw","text":"Support for LIS2DW accelerometers. [lis2dw] 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 # See the \"adxl345\" section for information on this parameter.","title":"[lis2dw]"},{"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. #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: 75 # 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).","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#axis_twist_compensation","text":"A tool to compensate for inaccurate probe readings due to twist in X 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. This parameter must be provided. 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. This parameter must be provided. 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 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 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. [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 carraiges), 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.","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.","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-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#bmp180bmp280bme280bme680-temperature-sensor","text":"BMP180/BMP280/BME280/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 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/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#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. #scl_pin: #sda_pin: # Alternatively, if the pca9632 is not connected to a hardware I2C # bus, then one may specify the \"clock\" (scl_pin) and \"data\" # (sda_pin) pins. The default is to use hardware I2C. #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.","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. #static_value: # If this is set, then the pin is assigned to this value at startup # and the pin can not be changed during runtime. A static pin uses # slightly less ram in the micro-controller. The default is to use # runtime configuration of pins. #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). #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. #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.","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. #value: #shutdown_value: #maximum_mcu_duration: #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#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. The default is 0, which disables # \"stealthChop\" mode. #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_PWM_AUTOSCALE: True #driver_PWM_FREQ: 1 #driver_PWM_GRAD: 4 #driver_PWM_AMPL: 128 #driver_SGT: 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. 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 # 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. #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_SGTHRS: 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. The default is 0, which disables # \"stealthChop\" mode. #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 # 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. The default is 0, which disables # \"stealthChop\" mode. #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 two gpio \"bit banging\" pins (one may define any number of sections with an \"mcp4018\" prefix). [mcp4018 my_digipot] scl_pin: # The SCL \"clock\" pin. This parameter must be provided. sda_pin: # The SDA \"data\" pin. This parameter must be provided. 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\", # \"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 # 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#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. #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 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#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#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 remo 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, 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\", 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 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 .","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":"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":"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 2, Raspberry Pi 3, or Raspberry Pi 4. Klipper will run on a Raspberry Pi 1 and on the Raspberry Pi Zero, but these boards don't have enough processing power to run OctoPrint well. It is common for print stalls to occur on these slower machines when printing directly from OctoPrint. (The printer may move faster than OctoPrint can send movement commands.) If you wish to run on one one of these slower boards anyway, consider using the \"virtual_sdcard\" feature when printing (see config reference for details). 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 2, Raspberry Pi 3, or Raspberry Pi 4. Klipper will run on a Raspberry Pi 1 and on the Raspberry Pi Zero, but these boards don't have enough processing power to run OctoPrint well. It is common for print stalls to occur on these slower machines when printing directly from OctoPrint. (The printer may move faster than OctoPrint can send movement commands.) If you wish to run on one one of these slower boards anyway, consider using the \"virtual_sdcard\" feature when printing (see config reference for details). 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. 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. 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, 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. 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, and lis2dw12 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 RP2040 2400K 1636K SAM4E8E 2500K 1674K SAMD51 3077K 1885K AR100 3529K 2507K STM32F407 3652K 2459K STM32F446 3913K 2634K STM32H743 9091K 6061K 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. 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. 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, 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. 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, and lis2dw12 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 RP2040 2400K 1636K SAM4E8E 2500K 1674K SAMD51 3077K 1885K AR100 3529K 2507K STM32F407 3652K 2459K STM32F446 3913K 2634K STM32H743 9091K 6061K 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_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. [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 [METHOD=manual] [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>] [<mesh_parameter>=<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. 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. 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>] : Applies X and/or Y 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. [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=[0|1] [MODE=[PRIMARY|COPY|MIRROR]] : This command will change the mode of the specified carriage. If no MODE is provided it defaults to PRIMARY . 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 CARRIAGE=1 . When set to either of these modes, carriage 1 will then track the subsequent moves of the carriage 0 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 carraige. [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. SET_EXTRUDER_STEP_DISTANCE \u00b6 This command is deprecated and will be removed in the near future. SYNC_STEPPER_TO_EXTRUDER \u00b6 This command is deprecated and will be removed in the near future. [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. [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>] : Force the low-level kinematic code to believe the toolhead is at the given cartesian position. This is a diagnostic and debugging command; use SET_GCODE_OFFSET and/or G92 for regular axis transformations. If an axis is not specified then it will default to the position that the head was last commanded to. Setting an incorrect or invalid position may lead to internal software errors. This command may invalidate future boundary checks; issue a G28 afterwards to reset the kinematics. [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. [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. [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. [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'. [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). [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> [CYCLE_TIME=<cycle_time>] : 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. Some pins (currently only \"soft PWM\" pins) support 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 output_pin config section). [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. [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. [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. [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. [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>] [HZ_PER_SEC=<hz_per_sec>] [CHIPS=<adxl345_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. adxl345_chip_name can be one or more configured adxl345 chip,delimited with comma, for example CHIPS=\"adxl345, adxl345 rpi\" . Note that adxl345 can be omitted from named adxl345 chips. 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>] [HZ_PER_SEC=<hz_per_sec>] [CHIPS=<adxl345_chip_name>] [MAX_SMOOTHING=<max_smoothing>] : 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. 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. [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>] [ACCEL_TO_DECEL=<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. [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 [SAMPLE_COUNT=<value>] : Initiates the X twist calibration wizard. SAMPLE_COUNT specifies the number of points along the X axis to calibrate at and defaults to 3. [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 [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 HORIZONTAL_MOVE_Z value overrides the horizontal_move_z option 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_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#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 [METHOD=manual] [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>] [<mesh_parameter>=<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. 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_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>] : Applies X and/or Y 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.","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=[0|1] [MODE=[PRIMARY|COPY|MIRROR]] : This command will change the mode of the specified carriage. If no MODE is provided it defaults to PRIMARY . 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 CARRIAGE=1 . When set to either of these modes, carriage 1 will then track the subsequent moves of the carriage 0 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 carraige.","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#set_extruder_step_distance","text":"This command is deprecated and will be removed in the near future.","title":"SET_EXTRUDER_STEP_DISTANCE"},{"location":"G-Codes.html#sync_stepper_to_extruder","text":"This command is deprecated and will be removed in the near future.","title":"SYNC_STEPPER_TO_EXTRUDER"},{"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.","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>] : Force the low-level kinematic code to believe the toolhead is at the given cartesian position. This is a diagnostic and debugging command; use SET_GCODE_OFFSET and/or G92 for regular axis transformations. If an axis is not specified then it will default to the position that the head was last commanded to. Setting an incorrect or invalid position may lead to internal software errors. This command may invalidate future boundary checks; issue a G28 afterwards to reset the kinematics.","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#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#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.","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#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#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> [CYCLE_TIME=<cycle_time>] : 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. Some pins (currently only \"soft PWM\" pins) support 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 output_pin config section).","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#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#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#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#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>] [HZ_PER_SEC=<hz_per_sec>] [CHIPS=<adxl345_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. adxl345_chip_name can be one or more configured adxl345 chip,delimited with comma, for example CHIPS=\"adxl345, adxl345 rpi\" . Note that adxl345 can be omitted from named adxl345 chips. 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>] [HZ_PER_SEC=<hz_per_sec>] [CHIPS=<adxl345_chip_name>] [MAX_SMOOTHING=<max_smoothing>] : 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. 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#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>] [ACCEL_TO_DECEL=<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#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 [SAMPLE_COUNT=<value>] : Initiates the X twist calibration wizard. SAMPLE_COUNT specifies the number of points along the X axis to calibrate at and defaults to 3.","title":"AXIS_TWIST_COMPENSATION_CALIBRATE"},{"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 [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 HORIZONTAL_MOVE_Z value overrides the horizontal_move_z option 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 Raspberry Pi computer in conjunction with OctoPrint. It is recommended that a Raspberry Pi 2 (or later) be used as the host machine (see the FAQ for other machines). Obtain a Klipper Configuration File \u00b6 Most Klipper settings are determined by a \"printer configuration file\" that will be stored on the Raspberry Pi. 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. Prepping an OS image \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 to v1.4.2 or later. After installing OctoPi and upgrading OctoPrint, it will be necessary to ssh into the target machine to run a handful of system commands. If using a Linux or MacOS desktop, then the \"ssh\" software should already be installed on the desktop. There are free ssh clients available for other desktops (eg, PuTTY ). Use the ssh utility to connect to the Raspberry Pi ( ssh pi@octopi -- password is \"raspberry\") and run the following commands: git clone https://github.com/Klipper3d/klipper ./klipper/scripts/install-octopi.sh The above will download Klipper, install some 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. Building and flashing the micro-controller \u00b6 To compile the micro-controller code, start by running these commands on the Raspberry Pi: 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 (see the FAQ for more information). For common micro-controllers, 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. When flashing for the first time, make sure that OctoPrint is not connected directly to the printer (from the OctoPrint web page, under the \"Connection\" section, click \"Disconnect\"). 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 /tmp/printer . Then click \"Save\". Enter the Settings tab again and under \"Serial Connection\" change the \"Serial Port\" setting to /tmp/printer . 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 /tmp/printer and click \"Connect\". (If /tmp/printer is not an 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. Proceed to the next section. Configuring Klipper \u00b6 The next step is to copy the printer configuration file to the Raspberry Pi. Arguably the easiest way to set the Klipper configuration file 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 Raspberry Pi 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 OctoPrint web terminal to load the config. A \"status\" command will report 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 OctoPrint terminal tab. The \"status\" command can be used to re-report error messages. The default Klipper startup script also places a log in /tmp/klippy.log which provides more detailed information. 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 Raspberry Pi computer in conjunction with OctoPrint. It is recommended that a Raspberry Pi 2 (or later) be used as the host machine (see the FAQ for other machines).","title":"Installation"},{"location":"Installation.html#obtain-a-klipper-configuration-file","text":"Most Klipper settings are determined by a \"printer configuration file\" that will be stored on the Raspberry Pi. 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#prepping-an-os-image","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 to v1.4.2 or later. After installing OctoPi and upgrading OctoPrint, it will be necessary to ssh into the target machine to run a handful of system commands. If using a Linux or MacOS desktop, then the \"ssh\" software should already be installed on the desktop. There are free ssh clients available for other desktops (eg, PuTTY ). Use the ssh utility to connect to the Raspberry Pi ( ssh pi@octopi -- password is \"raspberry\") and run the following commands: git clone https://github.com/Klipper3d/klipper ./klipper/scripts/install-octopi.sh The above will download Klipper, install some 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":"Prepping an OS image"},{"location":"Installation.html#building-and-flashing-the-micro-controller","text":"To compile the micro-controller code, start by running these commands on the Raspberry Pi: 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 (see the FAQ for more information). For common micro-controllers, 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. When flashing for the first time, make sure that OctoPrint is not connected directly to the printer (from the OctoPrint web page, under the \"Connection\" section, click \"Disconnect\").","title":"Building and flashing the micro-controller"},{"location":"Installation.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 /tmp/printer . Then click \"Save\". Enter the Settings tab again and under \"Serial Connection\" change the \"Serial Port\" setting to /tmp/printer . 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 /tmp/printer and click \"Connect\". (If /tmp/printer is not an 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. Proceed to the next section.","title":"Configuring OctoPrint to use Klipper"},{"location":"Installation.html#configuring-klipper","text":"The next step is to copy the printer configuration file to the Raspberry Pi. Arguably the easiest way to set the Klipper configuration file 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 Raspberry Pi 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 OctoPrint web terminal to load the config. A \"status\" command will report 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 OctoPrint terminal tab. The \"status\" command can be used to re-report error messages. The default Klipper startup script also places a log in /tmp/klippy.log which provides more detailed information. 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 Smoothed look-ahead \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. To reduce this, Klipper tracks both regular move acceleration as well as a virtual \"acceleration to deceleration\" rate. Using this system, the top speed of these short \"zigzag\" moves are limited to smooth out the printer motion: Specifically, the code calculates what the velocity of each move would be if it were limited to this virtual \"acceleration to deceleration\" rate (half the normal acceleration rate by default). 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#smoothed-look-ahead","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. To reduce this, Klipper tracks both regular move acceleration as well as a virtual \"acceleration to deceleration\" rate. Using this system, the top speed of these short \"zigzag\" moves are limited to smooth out the printer motion: Specifically, the code calculates what the velocity of each move would be if it were limited to this virtual \"acceleration to deceleration\" rate (half the normal acceleration rate by default). 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":"Smoothed look-ahead"},{"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":"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 and LIS2DW 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/LIS2DW 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. 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/LIS2DWs, 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-6500s 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 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 \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 buit-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 Next, in order to install NumPy in the Klipper environment, run the command: ~/klippy-env/bin/pip install -v numpy 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. 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 \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 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 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 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. To do that, run the following commands: ~/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. 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. 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 and LIS2DW 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/LIS2DW 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. 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/LIS2DWs, 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-6500s 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","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-6500","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 buit-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"},{"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 Next, in order to install NumPy in the Klipper environment, run the command: ~/klippy-env/bin/pip install -v numpy 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.","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","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"},{"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","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","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 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. To do that, run the following commands: ~/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. 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#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":"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. 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","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. 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","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\" is 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\" is 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.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-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. Increase max_accel_to_decel by issuing the following command: SET_VELOCITY_LIMIT ACCEL_TO_DECEL=7000 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 ACCEL_TO_DECEL=7000 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 ACCEL_TO_DECEL=7000 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 ACCEL_TO_DECEL=7000 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. Increase max_accel_to_decel by issuing the following command: SET_VELOCITY_LIMIT ACCEL_TO_DECEL=7000 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 ACCEL_TO_DECEL=7000 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 ACCEL_TO_DECEL=7000 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 ACCEL_TO_DECEL=7000 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_correcton] 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_correcton. 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_correcton] 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_correcton. 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 paramaters 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 paramaters 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 Config_Reference.md#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. 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: 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). 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 underyling 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] . 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. 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. 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 , 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, 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 , max_accel_to_decel , 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\". 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 Config_Reference.md#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#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: 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).","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 underyling 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#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#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#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 , 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, 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 , max_accel_to_decel , 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\".","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. 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.","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 6aac67031ee0..f4502061ab81 100644
Binary files a/sitemap.xml.gz and b/sitemap.xml.gz differ
diff --git a/zh-Hant/_klipper3d/__pycache__/mkdocs_hooks.cpython-38.pyc b/zh-Hant/_klipper3d/__pycache__/mkdocs_hooks.cpython-38.pyc
index 9d1a40d66dcd..c19006b2809f 100644
Binary files a/zh-Hant/_klipper3d/__pycache__/mkdocs_hooks.cpython-38.pyc and b/zh-Hant/_klipper3d/__pycache__/mkdocs_hooks.cpython-38.pyc differ
diff --git a/zh-Hant/sitemap.xml.gz b/zh-Hant/sitemap.xml.gz
index 0de502d9d556..dc63cb217a4d 100644
Binary files a/zh-Hant/sitemap.xml.gz and b/zh-Hant/sitemap.xml.gz differ
diff --git a/zh/_klipper3d/__pycache__/mkdocs_hooks.cpython-38.pyc b/zh/_klipper3d/__pycache__/mkdocs_hooks.cpython-38.pyc
index 9d1a40d66dcd..c19006b2809f 100644
Binary files a/zh/_klipper3d/__pycache__/mkdocs_hooks.cpython-38.pyc and b/zh/_klipper3d/__pycache__/mkdocs_hooks.cpython-38.pyc differ
diff --git a/zh/sitemap.xml.gz b/zh/sitemap.xml.gz
index f20a4236179c..39d7ec850ea7 100644
Binary files a/zh/sitemap.xml.gz and b/zh/sitemap.xml.gz differ