AHT10/AHT15/AHT20/AHT21/AHT30 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.
+sensor_type: AHT1X
+# Must be "AHT1X" , "AHT2X", "AHT3X"
+# Some AHT20 sensors can use "AHT1X"
#i2c_address:
# Default is 56 (0x38). Some AHT10 sensors give the option to use
# 57 (0x39) by moving a resistor.
diff --git a/Features.html b/Features.html
index 4a1d7952a..01920e35d 100644
--- a/Features.html
+++ b/Features.html
@@ -1558,7 +1558,7 @@
Support for common temperature sensors (eg, common thermistors,
AD595, AD597, AD849x, PT100, PT1000, MAX6675, MAX31855, MAX31856,
- MAX31865, BME280, HTU21D, DS18B20, AHT10, SHT3x, and LM75). Custom
+ MAX31865, BME280, HTU21D, DS18B20, AHT1X, AHT2X, AHT3X, SHT3x, and LM75). Custom
thermistors and custom analog temperature sensors can also be
configured. One can monitor the internal micro-controller
temperature sensor and the internal temperature sensor of a
diff --git a/_klipper3d/__pycache__/mkdocs_hooks.cpython-38.pyc b/_klipper3d/__pycache__/mkdocs_hooks.cpython-38.pyc
index f6dfab6b2..33a46e485 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 f6dfab6b2..33a46e485 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 941acf2f0..89f225fc9 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 f6dfab6b2..33a46e485 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 1147f32c8..541003cb8 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 f6dfab6b2..33a46e485 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 244805290..e490513dc 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 555ef956f..674b648b2 100644
--- a/search/search_index.json
+++ b/search/search_index.json
@@ -1 +1 @@
-{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"index.html","text":"The Klipper firmware controls 3d-Printers. It combines the power of a general purpose computer with one or more micro-controllers. See the features document for more information on why you should use the Klipper software. Start by installing Klipper software . Klipper software is Free Software. Read the documentation , see the license , or download the software. We depend on the generous support from our sponsors .","title":"Welcome"},{"location":"API_Server.html","text":"API server \u00b6 This document describes Klipper's Application Programmer Interface (API). This interface enables external applications to query and control the Klipper host software. Enabling the API socket \u00b6 In order to use the API server, the klippy.py host software must be started with the -a parameter. For example: ~/klippy-env/bin/python ~/klipper/klippy/klippy.py ~/printer.cfg -a /tmp/klippy_uds -l /tmp/klippy.log This causes the host software to create a Unix Domain Socket. A client can then open a connection on that socket and send commands to Klipper. See the Moonraker project for a popular tool that can forward HTTP requests to Klipper's API Server Unix Domain Socket. Request format \u00b6 Messages sent and received on the socket are JSON encoded strings terminated by an ASCII 0x03 character: <0x03><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 / . When making a request to an \"endpoint\", the full name must be set in the \"method\" parameter of the request dictionary (eg, {\"method\"=\"gcode/restart\"} ). info \u00b6 The \"info\" endpoint is used to obtain system and version information from Klipper. It is also used to provide the client's version information to Klipper. For example: {\"id\": 123, \"method\": \"info\", \"params\": { \"client_info\": { \"version\": \"v1\"}}} If present, the \"client_info\" parameter must be a dictionary, but that dictionary may have arbitrary contents. Clients are encouraged to provide the name of the client and its software version when first connecting to the Klipper API server. emergency_stop \u00b6 The \"emergency_stop\" endpoint is used to instruct Klipper to transition to a \"shutdown\" state. It behaves similarly to the G-Code M112 command. For example: {\"id\": 123, \"method\": \"emergency_stop\"} register_remote_method \u00b6 This endpoint allows clients to register methods that can be called from klipper. It will return an empty object upon success. For example: {\"id\": 123, \"method\": \"register_remote_method\", \"params\": {\"response_template\": {\"action\": \"run_paneldue_beep\"}, \"remote_method\": \"paneldue_beep\"}} will return: {\"id\": 123, \"result\": {}} The remote method paneldue_beep may now be called from Klipper. Note that if the method takes parameters they should be provided as keyword arguments. Below is an example of how it may called from a gcode_macro: [gcode_macro PANELDUE_BEEP] gcode: {action_call_remote_method(\"paneldue_beep\", frequency=300, duration=1.0)} When the PANELDUE_BEEP gcode macro is executed, Klipper would send something like the following over the socket: {\"action\": \"run_paneldue_beep\", \"params\": {\"frequency\": 300, \"duration\": 1.0}} objects/list \u00b6 This endpoint queries the list of available printer \"objects\" that one may query (via the \"objects/query\" endpoint). For example: {\"id\": 123, \"method\": \"objects/list\"} might return: {\"id\": 123, \"result\": {\"objects\": [\"webhooks\", \"configfile\", \"heaters\", \"gcode_move\", \"query_endstops\", \"idle_timeout\", \"toolhead\", \"extruder\"]}} objects/query \u00b6 This endpoint allows one to query information from printer objects. For example: {\"id\": 123, \"method\": \"objects/query\", \"params\": {\"objects\": {\"toolhead\": [\"position\"], \"webhooks\": null}}} might return: {\"id\": 123, \"result\": {\"status\": {\"webhooks\": {\"state\": \"ready\", \"state_message\": \"Printer is ready\"}, \"toolhead\": {\"position\": [0.0, 0.0, 0.0, 0.0]}}, \"eventtime\": 3051555.377933684}} The \"objects\" parameter in the request must be a dictionary containing the printer objects that are to be queried - the key contains the printer object name and the value is either \"null\" (to query all fields) or a list of field names. The response message will contain a \"status\" field containing a dictionary with the queried information - the key contains the printer object name and the value is a dictionary containing its fields. The response message will also contain an \"eventtime\" field containing the timestamp from when the query was taken. Available fields are documented in the Status Reference document. objects/subscribe \u00b6 This endpoint allows one to query and then subscribe to information from printer objects. The endpoint request and response is identical to the \"objects/query\" endpoint. For example: {\"id\": 123, \"method\": \"objects/subscribe\", \"params\": {\"objects\":{\"toolhead\": [\"position\"], \"webhooks\": [\"state\"]}, \"response_template\":{}}} might return: {\"id\": 123, \"result\": {\"status\": {\"webhooks\": {\"state\": \"ready\"}, \"toolhead\": {\"position\": [0.0, 0.0, 0.0, 0.0]}}, \"eventtime\": 3052153.382083195}} and result in subsequent asynchronous messages such as: {\"params\": {\"status\": {\"webhooks\": {\"state\": \"shutdown\"}}, \"eventtime\": 3052165.418815847}} gcode/help \u00b6 This endpoint allows one to query available G-Code commands that have a help string defined. For example: {\"id\": 123, \"method\": \"gcode/help\"} might return: {\"id\": 123, \"result\": {\"RESTORE_GCODE_STATE\": \"Restore a previously saved G-Code state\", \"PID_CALIBRATE\": \"Run PID calibration test\", \"QUERY_ADC\": \"Report the last value of an analog pin\", ...}} gcode/script \u00b6 This endpoint allows one to run a series of G-Code commands. For example: {\"id\": 123, \"method\": \"gcode/script\", \"params\": {\"script\": \"G90\"}} If the provided G-Code script raises an error, then an error response is generated. However, if the G-Code command produces terminal output, that terminal output is not provided in the response. (Use the \"gcode/subscribe_output\" endpoint to obtain G-Code terminal output.) If there is a G-Code command being processed when this request is received, then the provided script will be queued. This delay could be significant (eg, if a G-Code wait for temperature command is running). The JSON response message is sent when the processing of the script fully completes. gcode/restart \u00b6 This endpoint allows one to request a restart - it is similar to running the G-Code \"RESTART\" command. For example: {\"id\": 123, \"method\": \"gcode/restart\"} As with the \"gcode/script\" endpoint, this endpoint only completes after any pending G-Code commands complete. gcode/firmware_restart \u00b6 This is similar to the \"gcode/restart\" endpoint - it implements the G-Code \"FIRMWARE_RESTART\" command. For example: {\"id\": 123, \"method\": \"gcode/firmware_restart\"} As with the \"gcode/script\" endpoint, this endpoint only completes after any pending G-Code commands complete. gcode/subscribe_output \u00b6 This endpoint is used to subscribe to G-Code terminal messages that are generated by Klipper. For example: {\"id\": 123, \"method\": \"gcode/subscribe_output\", \"params\": {\"response_template\":{}}} might later produce asynchronous messages such as: {\"params\": {\"response\": \"// Klipper state: Shutdown\"}} This endpoint is intended to support human interaction via a \"terminal window\" interface. Parsing content from the G-Code terminal output is discouraged. Use the \"objects/subscribe\" endpoint to obtain updates on Klipper's state. motion_report/dump_stepper \u00b6 This endpoint is used to subscribe to Klipper's internal stepper queue_step command stream for a stepper. Obtaining these low-level motion updates may be useful for diagnostic and debugging purposes. Using this endpoint may increase Klipper's system load. A request may look like: {\"id\": 123, \"method\":\"motion_report/dump_stepper\", \"params\": {\"name\": \"stepper_x\", \"response_template\": {}}} and might return: {\"id\": 123, \"result\": {\"header\": [\"interval\", \"count\", \"add\"]}} and might later produce asynchronous messages such as: {\"params\": {\"first_clock\": 179601081, \"first_time\": 8.98, \"first_position\": 0, \"last_clock\": 219686097, \"last_time\": 10.984, \"data\": [[179601081, 1, 0], [29573, 2, -8685], [16230, 4, -1525], [10559, 6, -160], [10000, 976, 0], [10000, 1000, 0], [10000, 1000, 0], [10000, 1000, 0], [9855, 5, 187], [11632, 4, 1534], [20756, 2, 9442]]}} The \"header\" field in the initial query response is used to describe the fields found in later \"data\" responses. motion_report/dump_trapq \u00b6 This endpoint is used to subscribe to Klipper's internal \"trapezoid motion queue\". Obtaining these low-level motion updates may be useful for diagnostic and debugging purposes. Using this endpoint may increase Klipper's system load. A request may look like: {\"id\": 123, \"method\": \"motion_report/dump_trapq\", \"params\": {\"name\": \"toolhead\", \"response_template\":{}}} and might return: {\"id\": 1, \"result\": {\"header\": [\"time\", \"duration\", \"start_velocity\", \"acceleration\", \"start_position\", \"direction\"]}} and might later produce asynchronous messages such as: {\"params\": {\"data\": [[4.05, 1.0, 0.0, 0.0, [300.0, 0.0, 0.0], [0.0, 0.0, 0.0]], [5.054, 0.001, 0.0, 3000.0, [300.0, 0.0, 0.0], [-1.0, 0.0, 0.0]]]}} The \"header\" field in the initial query response is used to describe the fields found in later \"data\" responses. adxl345/dump_adxl345 \u00b6 This endpoint is used to subscribe to ADXL345 accelerometer data. Obtaining these low-level motion updates may be useful for diagnostic and debugging purposes. Using this endpoint may increase Klipper's system load. A request may look like: {\"id\": 123, \"method\":\"adxl345/dump_adxl345\", \"params\": {\"sensor\": \"adxl345\", \"response_template\": {}}} and might return: {\"id\": 123,\"result\":{\"header\":[\"time\",\"x_acceleration\",\"y_acceleration\", \"z_acceleration\"]}} and might later produce asynchronous messages such as: {\"params\":{\"overflows\":0,\"data\":[[3292.432935,-535.44309,-1529.8374,9561.4], [3292.433256,-382.45935,-1606.32927,9561.48375]]}} The \"header\" field in the initial query response is used to describe the fields found in later \"data\" responses. angle/dump_angle \u00b6 This endpoint is used to subscribe to angle sensor data . Obtaining these low-level motion updates may be useful for diagnostic and debugging purposes. Using this endpoint may increase Klipper's system load. A request may look like: {\"id\": 123, \"method\":\"angle/dump_angle\", \"params\": {\"sensor\": \"my_angle_sensor\", \"response_template\": {}}} and might return: {\"id\": 123,\"result\":{\"header\":[\"time\",\"angle\"]}} and might later produce asynchronous messages such as: {\"params\":{\"position_offset\":3.151562,\"errors\":0, \"data\":[[1290.951905,-5063],[1290.952321,-5065]]}} The \"header\" field in the initial query response is used to describe the fields found in later \"data\" responses. load_cell/dump_force \u00b6 This endpoint is used to subscribe to force data produced by a load_cell. Using this endpoint may increase Klipper's system load. A request may look like: {\"id\": 123, \"method\":\"load_cell/dump_force\", \"params\": {\"sensor\": \"load_cell\", \"response_template\": {}}} and might return: {\"id\": 123,\"result\":{\"header\":[\"time\", \"force (g)\", \"counts\", \"tare_counts\"]}} and might later produce asynchronous messages such as: {\"params\":{\"data\":[[3292.432935, 40.65, 562534, -234467]]}} The \"header\" field in the initial query response is used to describe the fields found in later \"data\" responses. load_cell_probe/dump_taps \u00b6 This endpoint is used to subscribe to details of probing \"tap\" events. Using this endpoint may increase Klipper's system load. A request may look like: {\"id\": 123, \"method\":\"load_cell/dump_force\", \"params\": {\"sensor\": \"load_cell\", \"response_template\": {}}} and might return: {\"id\": 123,\"result\":{\"header\":[\"probe_tap_event\"]}} and might later produce asynchronous messages such as: {\"params\":{\"tap\":'{ \"time\": [118032.28039, 118032.2834, ...], \"force\": [-459.4213119680034, -458.1640702543264, ...], }}} This data can be used to render: The time/force graph pause_resume/cancel \u00b6 This endpoint is similar to running the \"PRINT_CANCEL\" G-Code command. For example: {\"id\": 123, \"method\": \"pause_resume/cancel\"} As with the \"gcode/script\" endpoint, this endpoint only completes after any pending G-Code commands complete. pause_resume/pause \u00b6 This endpoint is similar to running the \"PAUSE\" G-Code command. For example: {\"id\": 123, \"method\": \"pause_resume/pause\"} As with the \"gcode/script\" endpoint, this endpoint only completes after any pending G-Code commands complete. pause_resume/resume \u00b6 This endpoint is similar to running the \"RESUME\" G-Code command. For example: {\"id\": 123, \"method\": \"pause_resume/resume\"} As with the \"gcode/script\" endpoint, this endpoint only completes after any pending G-Code commands complete. query_endstops/status \u00b6 This endpoint will query the active endpoints and return their status. For example: {\"id\": 123, \"method\": \"query_endstops/status\"} might return: {\"id\": 123, \"result\": {\"y\": \"open\", \"x\": \"open\", \"z\": \"TRIGGERED\"}} As with the \"gcode/script\" endpoint, this endpoint only completes after any pending G-Code commands complete. bed_mesh/dump_mesh \u00b6 Dumps the configuration and state for the current mesh and all saved profiles. For example: {\"id\": 123, \"method\": \"bed_mesh/dump_mesh\"} might return: { \"current_mesh\": { \"name\": \"eddy-scan-test\", \"probed_matrix\": [...], \"mesh_matrix\": [...], \"mesh_params\": { \"x_count\": 9, \"y_count\": 9, \"mesh_x_pps\": 2, \"mesh_y_pps\": 2, \"algo\": \"bicubic\", \"tension\": 0.5, \"min_x\": 20, \"max_x\": 330, \"min_y\": 30, \"max_y\": 320 } }, \"profiles\": { \"default\": { \"points\": [...], \"mesh_params\": { \"min_x\": 20, \"max_x\": 330, \"min_y\": 30, \"max_y\": 320, \"x_count\": 9, \"y_count\": 9, \"mesh_x_pps\": 2, \"mesh_y_pps\": 2, \"algo\": \"bicubic\", \"tension\": 0.5 } }, \"eddy-scan-test\": { \"points\": [...], \"mesh_params\": { \"x_count\": 9, \"y_count\": 9, \"mesh_x_pps\": 2, \"mesh_y_pps\": 2, \"algo\": \"bicubic\", \"tension\": 0.5, \"min_x\": 20, \"max_x\": 330, \"min_y\": 30, \"max_y\": 320 } }, \"eddy-rapid-test\": { \"points\": [...], \"mesh_params\": { \"x_count\": 9, \"y_count\": 9, \"mesh_x_pps\": 2, \"mesh_y_pps\": 2, \"algo\": \"bicubic\", \"tension\": 0.5, \"min_x\": 20, \"max_x\": 330, \"min_y\": 30, \"max_y\": 320 } } }, \"calibration\": { \"points\": [...], \"config\": { \"x_count\": 9, \"y_count\": 9, \"mesh_x_pps\": 2, \"mesh_y_pps\": 2, \"algo\": \"bicubic\", \"tension\": 0.5, \"mesh_min\": [ 20, 30 ], \"mesh_max\": [ 330, 320 ], \"origin\": null, \"radius\": null }, \"probe_path\": [...], \"rapid_path\": [...] }, \"probe_offsets\": [ 0, 25, 0.5 ], \"axis_minimum\": [ 0, 0, -5, 0 ], \"axis_maximum\": [ 351, 358, 330, 0 ] } The dump_mesh endpoint takes one optional parameter, mesh_args . This parameter must be an object, where the keys and values are parameters available to BED_MESH_CALIBRATE . This will update the mesh configuration and probe points using the supplied parameters prior to returning the result. It is recommended to omit mesh parameters unless it is desired to visualize the probe points and/or travel path before performing BED_MESH_CALIBRATE .","title":"API server"},{"location":"API_Server.html#api-server","text":"This document describes Klipper's Application Programmer Interface (API). This interface enables external applications to query and control the Klipper host software.","title":"API server"},{"location":"API_Server.html#enabling-the-api-socket","text":"In order to use the API server, the klippy.py host software must be started with the -a parameter. For example: ~/klippy-env/bin/python ~/klipper/klippy/klippy.py ~/printer.cfg -a /tmp/klippy_uds -l /tmp/klippy.log This causes the host software to create a Unix Domain Socket. A client can then open a connection on that socket and send commands to Klipper. See the Moonraker project for a popular tool that can forward HTTP requests to Klipper's API Server Unix Domain Socket.","title":"Enabling the API socket"},{"location":"API_Server.html#request-format","text":"Messages sent and received on the socket are JSON encoded strings terminated by an ASCII 0x03 character: <0x03><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 / . When making a request to an \"endpoint\", the full name must be set in the \"method\" parameter of the request dictionary (eg, {\"method\"=\"gcode/restart\"} ).","title":"Available \"endpoints\""},{"location":"API_Server.html#info","text":"The \"info\" endpoint is used to obtain system and version information from Klipper. It is also used to provide the client's version information to Klipper. For example: {\"id\": 123, \"method\": \"info\", \"params\": { \"client_info\": { \"version\": \"v1\"}}} If present, the \"client_info\" parameter must be a dictionary, but that dictionary may have arbitrary contents. Clients are encouraged to provide the name of the client and its software version when first connecting to the Klipper API server.","title":"info"},{"location":"API_Server.html#emergency_stop","text":"The \"emergency_stop\" endpoint is used to instruct Klipper to transition to a \"shutdown\" state. It behaves similarly to the G-Code M112 command. For example: {\"id\": 123, \"method\": \"emergency_stop\"}","title":"emergency_stop"},{"location":"API_Server.html#register_remote_method","text":"This endpoint allows clients to register methods that can be called from klipper. It will return an empty object upon success. For example: {\"id\": 123, \"method\": \"register_remote_method\", \"params\": {\"response_template\": {\"action\": \"run_paneldue_beep\"}, \"remote_method\": \"paneldue_beep\"}} will return: {\"id\": 123, \"result\": {}} The remote method paneldue_beep may now be called from Klipper. Note that if the method takes parameters they should be provided as keyword arguments. Below is an example of how it may called from a gcode_macro: [gcode_macro PANELDUE_BEEP] gcode: {action_call_remote_method(\"paneldue_beep\", frequency=300, duration=1.0)} When the PANELDUE_BEEP gcode macro is executed, Klipper would send something like the following over the socket: {\"action\": \"run_paneldue_beep\", \"params\": {\"frequency\": 300, \"duration\": 1.0}}","title":"register_remote_method"},{"location":"API_Server.html#objectslist","text":"This endpoint queries the list of available printer \"objects\" that one may query (via the \"objects/query\" endpoint). For example: {\"id\": 123, \"method\": \"objects/list\"} might return: {\"id\": 123, \"result\": {\"objects\": [\"webhooks\", \"configfile\", \"heaters\", \"gcode_move\", \"query_endstops\", \"idle_timeout\", \"toolhead\", \"extruder\"]}}","title":"objects/list"},{"location":"API_Server.html#objectsquery","text":"This endpoint allows one to query information from printer objects. For example: {\"id\": 123, \"method\": \"objects/query\", \"params\": {\"objects\": {\"toolhead\": [\"position\"], \"webhooks\": null}}} might return: {\"id\": 123, \"result\": {\"status\": {\"webhooks\": {\"state\": \"ready\", \"state_message\": \"Printer is ready\"}, \"toolhead\": {\"position\": [0.0, 0.0, 0.0, 0.0]}}, \"eventtime\": 3051555.377933684}} The \"objects\" parameter in the request must be a dictionary containing the printer objects that are to be queried - the key contains the printer object name and the value is either \"null\" (to query all fields) or a list of field names. The response message will contain a \"status\" field containing a dictionary with the queried information - the key contains the printer object name and the value is a dictionary containing its fields. The response message will also contain an \"eventtime\" field containing the timestamp from when the query was taken. Available fields are documented in the Status Reference document.","title":"objects/query"},{"location":"API_Server.html#objectssubscribe","text":"This endpoint allows one to query and then subscribe to information from printer objects. The endpoint request and response is identical to the \"objects/query\" endpoint. For example: {\"id\": 123, \"method\": \"objects/subscribe\", \"params\": {\"objects\":{\"toolhead\": [\"position\"], \"webhooks\": [\"state\"]}, \"response_template\":{}}} might return: {\"id\": 123, \"result\": {\"status\": {\"webhooks\": {\"state\": \"ready\"}, \"toolhead\": {\"position\": [0.0, 0.0, 0.0, 0.0]}}, \"eventtime\": 3052153.382083195}} and result in subsequent asynchronous messages such as: {\"params\": {\"status\": {\"webhooks\": {\"state\": \"shutdown\"}}, \"eventtime\": 3052165.418815847}}","title":"objects/subscribe"},{"location":"API_Server.html#gcodehelp","text":"This endpoint allows one to query available G-Code commands that have a help string defined. For example: {\"id\": 123, \"method\": \"gcode/help\"} might return: {\"id\": 123, \"result\": {\"RESTORE_GCODE_STATE\": \"Restore a previously saved G-Code state\", \"PID_CALIBRATE\": \"Run PID calibration test\", \"QUERY_ADC\": \"Report the last value of an analog pin\", ...}}","title":"gcode/help"},{"location":"API_Server.html#gcodescript","text":"This endpoint allows one to run a series of G-Code commands. For example: {\"id\": 123, \"method\": \"gcode/script\", \"params\": {\"script\": \"G90\"}} If the provided G-Code script raises an error, then an error response is generated. However, if the G-Code command produces terminal output, that terminal output is not provided in the response. (Use the \"gcode/subscribe_output\" endpoint to obtain G-Code terminal output.) If there is a G-Code command being processed when this request is received, then the provided script will be queued. This delay could be significant (eg, if a G-Code wait for temperature command is running). The JSON response message is sent when the processing of the script fully completes.","title":"gcode/script"},{"location":"API_Server.html#gcoderestart","text":"This endpoint allows one to request a restart - it is similar to running the G-Code \"RESTART\" command. For example: {\"id\": 123, \"method\": \"gcode/restart\"} As with the \"gcode/script\" endpoint, this endpoint only completes after any pending G-Code commands complete.","title":"gcode/restart"},{"location":"API_Server.html#gcodefirmware_restart","text":"This is similar to the \"gcode/restart\" endpoint - it implements the G-Code \"FIRMWARE_RESTART\" command. For example: {\"id\": 123, \"method\": \"gcode/firmware_restart\"} As with the \"gcode/script\" endpoint, this endpoint only completes after any pending G-Code commands complete.","title":"gcode/firmware_restart"},{"location":"API_Server.html#gcodesubscribe_output","text":"This endpoint is used to subscribe to G-Code terminal messages that are generated by Klipper. For example: {\"id\": 123, \"method\": \"gcode/subscribe_output\", \"params\": {\"response_template\":{}}} might later produce asynchronous messages such as: {\"params\": {\"response\": \"// Klipper state: Shutdown\"}} This endpoint is intended to support human interaction via a \"terminal window\" interface. Parsing content from the G-Code terminal output is discouraged. Use the \"objects/subscribe\" endpoint to obtain updates on Klipper's state.","title":"gcode/subscribe_output"},{"location":"API_Server.html#motion_reportdump_stepper","text":"This endpoint is used to subscribe to Klipper's internal stepper queue_step command stream for a stepper. Obtaining these low-level motion updates may be useful for diagnostic and debugging purposes. Using this endpoint may increase Klipper's system load. A request may look like: {\"id\": 123, \"method\":\"motion_report/dump_stepper\", \"params\": {\"name\": \"stepper_x\", \"response_template\": {}}} and might return: {\"id\": 123, \"result\": {\"header\": [\"interval\", \"count\", \"add\"]}} and might later produce asynchronous messages such as: {\"params\": {\"first_clock\": 179601081, \"first_time\": 8.98, \"first_position\": 0, \"last_clock\": 219686097, \"last_time\": 10.984, \"data\": [[179601081, 1, 0], [29573, 2, -8685], [16230, 4, -1525], [10559, 6, -160], [10000, 976, 0], [10000, 1000, 0], [10000, 1000, 0], [10000, 1000, 0], [9855, 5, 187], [11632, 4, 1534], [20756, 2, 9442]]}} The \"header\" field in the initial query response is used to describe the fields found in later \"data\" responses.","title":"motion_report/dump_stepper"},{"location":"API_Server.html#motion_reportdump_trapq","text":"This endpoint is used to subscribe to Klipper's internal \"trapezoid motion queue\". Obtaining these low-level motion updates may be useful for diagnostic and debugging purposes. Using this endpoint may increase Klipper's system load. A request may look like: {\"id\": 123, \"method\": \"motion_report/dump_trapq\", \"params\": {\"name\": \"toolhead\", \"response_template\":{}}} and might return: {\"id\": 1, \"result\": {\"header\": [\"time\", \"duration\", \"start_velocity\", \"acceleration\", \"start_position\", \"direction\"]}} and might later produce asynchronous messages such as: {\"params\": {\"data\": [[4.05, 1.0, 0.0, 0.0, [300.0, 0.0, 0.0], [0.0, 0.0, 0.0]], [5.054, 0.001, 0.0, 3000.0, [300.0, 0.0, 0.0], [-1.0, 0.0, 0.0]]]}} The \"header\" field in the initial query response is used to describe the fields found in later \"data\" responses.","title":"motion_report/dump_trapq"},{"location":"API_Server.html#adxl345dump_adxl345","text":"This endpoint is used to subscribe to ADXL345 accelerometer data. Obtaining these low-level motion updates may be useful for diagnostic and debugging purposes. Using this endpoint may increase Klipper's system load. A request may look like: {\"id\": 123, \"method\":\"adxl345/dump_adxl345\", \"params\": {\"sensor\": \"adxl345\", \"response_template\": {}}} and might return: {\"id\": 123,\"result\":{\"header\":[\"time\",\"x_acceleration\",\"y_acceleration\", \"z_acceleration\"]}} and might later produce asynchronous messages such as: {\"params\":{\"overflows\":0,\"data\":[[3292.432935,-535.44309,-1529.8374,9561.4], [3292.433256,-382.45935,-1606.32927,9561.48375]]}} The \"header\" field in the initial query response is used to describe the fields found in later \"data\" responses.","title":"adxl345/dump_adxl345"},{"location":"API_Server.html#angledump_angle","text":"This endpoint is used to subscribe to angle sensor data . Obtaining these low-level motion updates may be useful for diagnostic and debugging purposes. Using this endpoint may increase Klipper's system load. A request may look like: {\"id\": 123, \"method\":\"angle/dump_angle\", \"params\": {\"sensor\": \"my_angle_sensor\", \"response_template\": {}}} and might return: {\"id\": 123,\"result\":{\"header\":[\"time\",\"angle\"]}} and might later produce asynchronous messages such as: {\"params\":{\"position_offset\":3.151562,\"errors\":0, \"data\":[[1290.951905,-5063],[1290.952321,-5065]]}} The \"header\" field in the initial query response is used to describe the fields found in later \"data\" responses.","title":"angle/dump_angle"},{"location":"API_Server.html#load_celldump_force","text":"This endpoint is used to subscribe to force data produced by a load_cell. Using this endpoint may increase Klipper's system load. A request may look like: {\"id\": 123, \"method\":\"load_cell/dump_force\", \"params\": {\"sensor\": \"load_cell\", \"response_template\": {}}} and might return: {\"id\": 123,\"result\":{\"header\":[\"time\", \"force (g)\", \"counts\", \"tare_counts\"]}} and might later produce asynchronous messages such as: {\"params\":{\"data\":[[3292.432935, 40.65, 562534, -234467]]}} The \"header\" field in the initial query response is used to describe the fields found in later \"data\" responses.","title":"load_cell/dump_force"},{"location":"API_Server.html#load_cell_probedump_taps","text":"This endpoint is used to subscribe to details of probing \"tap\" events. Using this endpoint may increase Klipper's system load. A request may look like: {\"id\": 123, \"method\":\"load_cell/dump_force\", \"params\": {\"sensor\": \"load_cell\", \"response_template\": {}}} and might return: {\"id\": 123,\"result\":{\"header\":[\"probe_tap_event\"]}} and might later produce asynchronous messages such as: {\"params\":{\"tap\":'{ \"time\": [118032.28039, 118032.2834, ...], \"force\": [-459.4213119680034, -458.1640702543264, ...], }}} This data can be used to render: The time/force graph","title":"load_cell_probe/dump_taps"},{"location":"API_Server.html#pause_resumecancel","text":"This endpoint is similar to running the \"PRINT_CANCEL\" G-Code command. For example: {\"id\": 123, \"method\": \"pause_resume/cancel\"} As with the \"gcode/script\" endpoint, this endpoint only completes after any pending G-Code commands complete.","title":"pause_resume/cancel"},{"location":"API_Server.html#pause_resumepause","text":"This endpoint is similar to running the \"PAUSE\" G-Code command. For example: {\"id\": 123, \"method\": \"pause_resume/pause\"} As with the \"gcode/script\" endpoint, this endpoint only completes after any pending G-Code commands complete.","title":"pause_resume/pause"},{"location":"API_Server.html#pause_resumeresume","text":"This endpoint is similar to running the \"RESUME\" G-Code command. For example: {\"id\": 123, \"method\": \"pause_resume/resume\"} As with the \"gcode/script\" endpoint, this endpoint only completes after any pending G-Code commands complete.","title":"pause_resume/resume"},{"location":"API_Server.html#query_endstopsstatus","text":"This endpoint will query the active endpoints and return their status. For example: {\"id\": 123, \"method\": \"query_endstops/status\"} might return: {\"id\": 123, \"result\": {\"y\": \"open\", \"x\": \"open\", \"z\": \"TRIGGERED\"}} As with the \"gcode/script\" endpoint, this endpoint only completes after any pending G-Code commands complete.","title":"query_endstops/status"},{"location":"API_Server.html#bed_meshdump_mesh","text":"Dumps the configuration and state for the current mesh and all saved profiles. For example: {\"id\": 123, \"method\": \"bed_mesh/dump_mesh\"} might return: { \"current_mesh\": { \"name\": \"eddy-scan-test\", \"probed_matrix\": [...], \"mesh_matrix\": [...], \"mesh_params\": { \"x_count\": 9, \"y_count\": 9, \"mesh_x_pps\": 2, \"mesh_y_pps\": 2, \"algo\": \"bicubic\", \"tension\": 0.5, \"min_x\": 20, \"max_x\": 330, \"min_y\": 30, \"max_y\": 320 } }, \"profiles\": { \"default\": { \"points\": [...], \"mesh_params\": { \"min_x\": 20, \"max_x\": 330, \"min_y\": 30, \"max_y\": 320, \"x_count\": 9, \"y_count\": 9, \"mesh_x_pps\": 2, \"mesh_y_pps\": 2, \"algo\": \"bicubic\", \"tension\": 0.5 } }, \"eddy-scan-test\": { \"points\": [...], \"mesh_params\": { \"x_count\": 9, \"y_count\": 9, \"mesh_x_pps\": 2, \"mesh_y_pps\": 2, \"algo\": \"bicubic\", \"tension\": 0.5, \"min_x\": 20, \"max_x\": 330, \"min_y\": 30, \"max_y\": 320 } }, \"eddy-rapid-test\": { \"points\": [...], \"mesh_params\": { \"x_count\": 9, \"y_count\": 9, \"mesh_x_pps\": 2, \"mesh_y_pps\": 2, \"algo\": \"bicubic\", \"tension\": 0.5, \"min_x\": 20, \"max_x\": 330, \"min_y\": 30, \"max_y\": 320 } } }, \"calibration\": { \"points\": [...], \"config\": { \"x_count\": 9, \"y_count\": 9, \"mesh_x_pps\": 2, \"mesh_y_pps\": 2, \"algo\": \"bicubic\", \"tension\": 0.5, \"mesh_min\": [ 20, 30 ], \"mesh_max\": [ 330, 320 ], \"origin\": null, \"radius\": null }, \"probe_path\": [...], \"rapid_path\": [...] }, \"probe_offsets\": [ 0, 25, 0.5 ], \"axis_minimum\": [ 0, 0, -5, 0 ], \"axis_maximum\": [ 351, 358, 330, 0 ] } The dump_mesh endpoint takes one optional parameter, mesh_args . This parameter must be an object, where the keys and values are parameters available to BED_MESH_CALIBRATE . This will update the mesh configuration and probe points using the supplied parameters prior to returning the result. It is recommended to omit mesh parameters unless it is desired to visualize the probe points and/or travel path before performing BED_MESH_CALIBRATE .","title":"bed_mesh/dump_mesh"},{"location":"Axis_Twist_Compensation.html","text":"Axis Twist Compensation \u00b6 This document describes the [axis_twist_compensation] module. Some printers may have a small twist in their X rail which can skew the results of a probe attached to the X carriage. This is common in printers with designs like the Prusa MK3, Sovol SV06 etc and is further described under probe location bias . It may result in probe operations such as Bed Mesh , Screws Tilt Adjust , Z Tilt Adjust etc returning inaccurate representations of the bed. This module uses manual measurements by the user to correct the probe's results. Note that if your axis is significantly twisted it is strongly recommended to first use mechanical means to fix it prior to applying software corrections. Warning : This module is not compatible with dockable probes yet and will try to probe the bed without attaching the probe if you use it. Overview of compensation usage \u00b6 Tip: Make sure the probe X and Y offsets are correctly set as they greatly influence calibration. Basic Usage: X-Axis Calibration \u00b6 After setting up the [axis_twist_compensation] module, run: AXIS_TWIST_COMPENSATION_CALIBRATE This command will calibrate the X-axis by default. - The calibration wizard will prompt you to measure the probe Z offset at several points along the bed. - By default, the calibration uses 3 points, but you can specify a different number with the option: SAMPLE_COUNT= Adjust Your Z Offset: After completing the calibration, be sure to adjust your Z offset . Perform Bed Leveling Operations: Use probe-based operations as needed, such as: - Screws Tilt Adjust - Z Tilt Adjust Finalize the Setup: Home all axes, and perform a Bed Mesh if necessary. Run a test print, followed by any fine-tuning if needed. For Y-Axis Calibration \u00b6 The calibration process for the Y-axis is similar to the X-axis. To calibrate the Y-axis, use: AXIS_TWIST_COMPENSATION_CALIBRATE AXIS=Y This will guide you through the same measuring process as for the X-axis. Tip: Bed temperature and nozzle temperature and size do not seem to have an influence to the calibration process. [axis_twist_compensation] setup and commands \u00b6 Configuration options for [axis_twist_compensation] can be found in the Configuration Reference . Commands for [axis_twist_compensation] can be found in the G-Codes Reference","title":"Axis Twist Compensation"},{"location":"Axis_Twist_Compensation.html#axis-twist-compensation","text":"This document describes the [axis_twist_compensation] module. Some printers may have a small twist in their X rail which can skew the results of a probe attached to the X carriage. This is common in printers with designs like the Prusa MK3, Sovol SV06 etc and is further described under probe location bias . It may result in probe operations such as Bed Mesh , Screws Tilt Adjust , Z Tilt Adjust etc returning inaccurate representations of the bed. This module uses manual measurements by the user to correct the probe's results. Note that if your axis is significantly twisted it is strongly recommended to first use mechanical means to fix it prior to applying software corrections. Warning : This module is not compatible with dockable probes yet and will try to probe the bed without attaching the probe if you use it.","title":"Axis Twist Compensation"},{"location":"Axis_Twist_Compensation.html#overview-of-compensation-usage","text":"Tip: Make sure the probe X and Y offsets are correctly set as they greatly influence calibration.","title":"Overview of compensation usage"},{"location":"Axis_Twist_Compensation.html#basic-usage-x-axis-calibration","text":"After setting up the [axis_twist_compensation] module, run: AXIS_TWIST_COMPENSATION_CALIBRATE This command will calibrate the X-axis by default. - The calibration wizard will prompt you to measure the probe Z offset at several points along the bed. - By default, the calibration uses 3 points, but you can specify a different number with the option: SAMPLE_COUNT= Adjust Your Z Offset: After completing the calibration, be sure to adjust your Z offset . Perform Bed Leveling Operations: Use probe-based operations as needed, such as: - Screws Tilt Adjust - Z Tilt Adjust Finalize the Setup: Home all axes, and perform a Bed Mesh if necessary. Run a test print, followed by any fine-tuning if needed.","title":"Basic Usage: X-Axis Calibration"},{"location":"Axis_Twist_Compensation.html#for-y-axis-calibration","text":"The calibration process for the Y-axis is similar to the X-axis. To calibrate the Y-axis, use: AXIS_TWIST_COMPENSATION_CALIBRATE AXIS=Y This will guide you through the same measuring process as for the X-axis. Tip: Bed temperature and nozzle temperature and size do not seem to have an influence to the calibration process.","title":"For Y-Axis Calibration"},{"location":"Axis_Twist_Compensation.html#axis_twist_compensation-setup-and-commands","text":"Configuration options for [axis_twist_compensation] can be found in the Configuration Reference . Commands for [axis_twist_compensation] can be found in the G-Codes Reference","title":"[axis_twist_compensation] setup and commands"},{"location":"BLTouch.html","text":"BL-Touch \u00b6 Connecting BL-Touch \u00b6 A warning before you start: Avoid touching the BL-Touch pin with your bare fingers, since it is quite sensitive to finger grease. And if you do touch it, be very gentle, in order to not bend or push anything. Hook up the BL-Touch \"servo\" connector to a control_pin according to the BL-Touch documentation or your MCU documentation. Using the original wiring, the yellow wire from the triple is the control_pin and the white wire from the pair is the sensor_pin . You need to configure these pins according to your wiring. Most BL-Touch devices require a pullup on the sensor pin (prefix the pin name with \"^\"). For example: [bltouch] sensor_pin: ^P1.24 control_pin: P1.26 If the BL-Touch will be used to home the Z axis then set endstop_pin: probe:z_virtual_endstop and remove position_endstop in the [stepper_z] config section, then add a [safe_z_home] config section to raise the z axis, home the xy axes, move to the center of the bed, and home the z axis. For example: [safe_z_home] home_xy_position: 100, 100 # Change coordinates to the center of your print bed speed: 50 z_hop: 10 # Move up 10mm z_hop_speed: 5 It's important that the z_hop movement in safe_z_home is high enough that the probe doesn't hit anything even if the probe pin happens to be in its lowest state. Initial tests \u00b6 Before moving on, verify that the BL-Touch is mounted at the correct height, the pin should be roughly 2 mm above the nozzle when retracted When you turn on the printer, the BL-Touch probe should perform a self-test and move the pin up and down a couple of times. Once the self-test is completed, the pin should be retracted and the red LED on the probe should be lit. If there are any errors, for example the probe is flashing red or the pin is down instead of up, please turn off the printer and check the wiring and configuration. If the above is looking good, it's time to test that the control pin is working correctly. First run BLTOUCH_DEBUG COMMAND=pin_down in your printer terminal. Verify that the pin moves down and that the red LED on the probe turns off. If not, check your wiring and configuration again. Next issue a BLTOUCH_DEBUG COMMAND=pin_up , verify that the pin moves up, and that the red light turns on again. If it's flashing then there's some problem. The next step is to confirm that the sensor pin is working correctly. Run BLTOUCH_DEBUG COMMAND=pin_down , verify that the pin moves down, run BLTOUCH_DEBUG COMMAND=touch_mode , run QUERY_PROBE , and verify that command reports \"probe: open\". Then while gently pushing the pin up slightly with the nail of your finger run QUERY_PROBE again. Verify the command reports \"probe: TRIGGERED\". If either query does not report the correct message then it usually indicates an incorrect wiring or configuration (though some clones may require special handling). At the completion of this test run BLTOUCH_DEBUG COMMAND=pin_up and verify that the pin moves up. After completing the BL-Touch control pin and sensor pin tests, it is now time to test probing, but with a twist. Instead of letting the probe pin touch the print bed, let it touch the nail on your finger. Position the toolhead far from the bed, issue a G28 (or PROBE if not using probe:z_virtual_endstop), wait until the toolhead starts to move down, and stop the movement by very gently touching the pin with your nail. You may have to do it twice, since the default homing configuration probes twice. Be prepared to turn off the printer if it doesn't stop when you touch the pin. If that was successful, do another G28 (or PROBE ) but this time let it touch the bed as it should. BL-Touch gone bad \u00b6 Once the BL-Touch is in inconsistent state, it starts blinking red. You can force it to leave that state by issuing: BLTOUCH_DEBUG COMMAND=reset This may happen if its calibration is interrupted by the probe being blocked from being extracted. However, the BL-Touch may also not be able to calibrate itself anymore. This happens if the screw on its top is in the wrong position or the magnetic core inside the probe pin has moved. If it has moved up so that it sticks to the screw, it may not be able to lower its pin anymore. With this behavior you need to open the screw and use a ball-point pen to push it gently back into place. Re-Insert the pin into the BL-Touch so that it falls into the extracted position. Carefully readjust the headless screw into place. You need to find the right position so it is able to lower and raise the pin and the red light turns on and of. Use the reset , pin_up and pin_down commands to achieve this. BL-Touch \"clones\" \u00b6 Many BL-Touch \"clone\" devices work correctly with Klipper using the default configuration. However, some \"clone\" devices may not support the QUERY_PROBE command and some \"clone\" devices may require configuration of pin_up_reports_not_triggered or pin_up_touch_mode_reports_triggered . Important! Do not configure pin_up_reports_not_triggered or pin_up_touch_mode_reports_triggered to False without first following these directions. Do not configure either of these to False on a genuine BL-Touch. Incorrectly setting these to False can increase probing time and can increase the risk of damaging the printer. Some \"clone\" devices do not support touch_mode and as a result the QUERY_PROBE command does not work. Despite this, it may still be possible to perform probing and homing with these devices. On these devices the QUERY_PROBE command during the initial tests will not succeed, however the subsequent G28 (or PROBE ) test does succeed. It may be possible to use these \"clone\" devices with Klipper if one does not utilize the QUERY_PROBE command and one does not enable the probe_with_touch_mode feature. Some \"clone\" devices are unable to perform Klipper's internal sensor verification test. On these devices, attempts to home or probe can result in Klipper reporting a \"BLTouch failed to verify sensor state\" error. If this occurs, then manually run the steps to confirm the sensor pin is working as described in the initial tests section . If the QUERY_PROBE commands in that test always produce the expected results and \"BLTouch failed to verify sensor state\" errors still occur, then it may be necessary to set pin_up_touch_mode_reports_triggered to False in the Klipper config file. A rare number of old \"clone\" devices are unable to report when they have successfully raised their probe. On these devices Klipper will report a \"BLTouch failed to raise probe\" error after every home or probe attempt. One can test for these devices - move the head far from the bed, run BLTOUCH_DEBUG COMMAND=pin_down , verify the pin has moved down, run QUERY_PROBE , verify that command reports \"probe: open\", run BLTOUCH_DEBUG COMMAND=pin_up , verify the pin has moved up, and run QUERY_PROBE . If the pin remains up, the device does not enter an error state, and the first query reports \"probe: open\" while the second query reports \"probe: TRIGGERED\" then it indicates that pin_up_reports_not_triggered should be set to False in the Klipper config file. BL-Touch v3 \u00b6 Some BL-Touch v3.0 and BL-Touch 3.1 devices may require configuring probe_with_touch_mode in the printer config file. If the BL-Touch v3.0 has its signal wire connected to an endstop pin (with a noise filtering capacitor), then the BL-Touch v3.0 may not be able to consistently send a signal during homing and probing. If the QUERY_PROBE commands in the initial tests section always produce the expected results, but the toolhead does not always stop during G28/PROBE commands, then it is indicative of this issue. A workaround is to set probe_with_touch_mode: True in the config file. The BL-Touch v3.1 may incorrectly enter an error state after a successful probe attempt. The symptoms are an occasional flashing light on the BL-Touch v3.1 that lasts for a couple of seconds after it successfully contacts the bed. Klipper should clear this error automatically and it is generally harmless. However, one may set probe_with_touch_mode in the config file to avoid this issue. Important! Some \"clone\" devices and the BL-Touch v2.0 (and earlier) may have reduced accuracy when probe_with_touch_mode is set to True. Setting this to True also increases the time it takes to deploy the probe. If configuring this value on a \"clone\" or older BL-Touch device, be sure to test the probe accuracy before and after setting this value (use the PROBE_ACCURACY command to test). Multi-probing without stowing \u00b6 By default, Klipper will deploy the probe at the start of each probe attempt and then stow the probe afterwards. This repetitive deploying and stowing of the probe may increase the total time of calibration sequences that involve many probe measurements. Klipper supports leaving the probe deployed between consecutive probes, which can reduce the total time of probing. This mode is enabled by configuring stow_on_each_sample to False in the config file. Important! Setting stow_on_each_sample to False can lead to Klipper making horizontal toolhead movements while the probe is deployed. Be sure to verify all probing operations have sufficient Z clearance prior to setting this value to False. If there is insufficient clearance then a horizontal move may cause the pin to catch on an obstruction and result in damage to the printer. Important! It is recommended to use probe_with_touch_mode configured to True when using stow_on_each_sample configured to False. Some \"clone\" devices may not detect a subsequent bed contact if probe_with_touch_mode is not set. On all devices, using the combination of these two settings simplifies the device signaling, which can improve overall stability. Note, however, that some \"clone\" devices and the BL-Touch v2.0 (and earlier) may have reduced accuracy when probe_with_touch_mode is set to True. On these devices it is a good idea to test the probe accuracy before and after setting probe_with_touch_mode (use the PROBE_ACCURACY command to test). Calibrating the BL-Touch offsets \u00b6 Follow the directions in the Probe Calibrate guide to set the x_offset, y_offset, and z_offset config parameters. It's a good idea to verify that the Z offset is close to 1mm. If not, then you probably want to move the probe up or down to fix this. You want it to trigger well before the nozzle hits the bed, so that possible stuck filament or a warped bed doesn't affect any probing action. But at the same time, you want the retracted position to be as far above the nozzle as possible to avoid it touching printed parts. If an adjustment is made to the probe position, then rerun the probe calibration steps. BL-Touch output mode \u00b6 A BL-Touch V3.0 supports setting a 5V or OPEN-DRAIN output mode, a BL-Touch V3.1 supports this too, but can also store this in its internal EEPROM. If your controller board needs the fixed 5V high logic level of the 5V mode you may set the 'set_output_mode' parameter in the [bltouch] section of the printer config file to \"5V\". Only use the 5V mode if your controller boards input line is 5V tolerant. This is why the default configuration of these BL-Touch versions is OPEN-DRAIN mode. You could potentially damage your controller boards CPU So therefore: If a controller board NEEDs 5V mode AND it is 5V tolerant on its input signal line AND if you have a BL-Touch Smart V3.0, you need the use 'set_output_mode: 5V' parameter to ensure this setting at each startup, since the probe cannot remember the needed setting. you have a BL-Touch Smart V3.1, you have the choice of using 'set_output_mode: 5V' or storing the mode once by use of a 'BLTOUCH_STORE MODE=5V' command manually and NOT using the parameter 'set_output_mode:'. you have some other probe: Some probes have a trace on the circuit board to cut or a jumper to set in order to (permanently) set the output mode. In that case, omit the 'set_output_mode' parameter completely. If you have a V3.1, do not automate or repeat storing the output mode to avoid wearing out the EEPROM of the probe.The BLTouch EEPROM is good for about 100.000 updates. 100 stores per day would add up to about 3 years of operation prior to wearing it out. Thus, storing the output mode in a V3.1 is designed by the vendor to be a complicated operation (the factory default being a safe OPEN DRAIN mode) and is not suited to be repeatedly issued by any slicer, macro or anything else, it is preferably only to be used when first integrating the probe into a printers electronics.","title":"BL-Touch"},{"location":"BLTouch.html#bl-touch","text":"","title":"BL-Touch"},{"location":"BLTouch.html#connecting-bl-touch","text":"A warning before you start: Avoid touching the BL-Touch pin with your bare fingers, since it is quite sensitive to finger grease. And if you do touch it, be very gentle, in order to not bend or push anything. Hook up the BL-Touch \"servo\" connector to a control_pin according to the BL-Touch documentation or your MCU documentation. Using the original wiring, the yellow wire from the triple is the control_pin and the white wire from the pair is the sensor_pin . You need to configure these pins according to your wiring. Most BL-Touch devices require a pullup on the sensor pin (prefix the pin name with \"^\"). For example: [bltouch] sensor_pin: ^P1.24 control_pin: P1.26 If the BL-Touch will be used to home the Z axis then set endstop_pin: probe:z_virtual_endstop and remove position_endstop in the [stepper_z] config section, then add a [safe_z_home] config section to raise the z axis, home the xy axes, move to the center of the bed, and home the z axis. For example: [safe_z_home] home_xy_position: 100, 100 # Change coordinates to the center of your print bed speed: 50 z_hop: 10 # Move up 10mm z_hop_speed: 5 It's important that the z_hop movement in safe_z_home is high enough that the probe doesn't hit anything even if the probe pin happens to be in its lowest state.","title":"Connecting BL-Touch"},{"location":"BLTouch.html#initial-tests","text":"Before moving on, verify that the BL-Touch is mounted at the correct height, the pin should be roughly 2 mm above the nozzle when retracted When you turn on the printer, the BL-Touch probe should perform a self-test and move the pin up and down a couple of times. Once the self-test is completed, the pin should be retracted and the red LED on the probe should be lit. If there are any errors, for example the probe is flashing red or the pin is down instead of up, please turn off the printer and check the wiring and configuration. If the above is looking good, it's time to test that the control pin is working correctly. First run BLTOUCH_DEBUG COMMAND=pin_down in your printer terminal. Verify that the pin moves down and that the red LED on the probe turns off. If not, check your wiring and configuration again. Next issue a BLTOUCH_DEBUG COMMAND=pin_up , verify that the pin moves up, and that the red light turns on again. If it's flashing then there's some problem. The next step is to confirm that the sensor pin is working correctly. Run BLTOUCH_DEBUG COMMAND=pin_down , verify that the pin moves down, run BLTOUCH_DEBUG COMMAND=touch_mode , run QUERY_PROBE , and verify that command reports \"probe: open\". Then while gently pushing the pin up slightly with the nail of your finger run QUERY_PROBE again. Verify the command reports \"probe: TRIGGERED\". If either query does not report the correct message then it usually indicates an incorrect wiring or configuration (though some clones may require special handling). At the completion of this test run BLTOUCH_DEBUG COMMAND=pin_up and verify that the pin moves up. After completing the BL-Touch control pin and sensor pin tests, it is now time to test probing, but with a twist. Instead of letting the probe pin touch the print bed, let it touch the nail on your finger. Position the toolhead far from the bed, issue a G28 (or PROBE if not using probe:z_virtual_endstop), wait until the toolhead starts to move down, and stop the movement by very gently touching the pin with your nail. You may have to do it twice, since the default homing configuration probes twice. Be prepared to turn off the printer if it doesn't stop when you touch the pin. If that was successful, do another G28 (or PROBE ) but this time let it touch the bed as it should.","title":"Initial tests"},{"location":"BLTouch.html#bl-touch-gone-bad","text":"Once the BL-Touch is in inconsistent state, it starts blinking red. You can force it to leave that state by issuing: BLTOUCH_DEBUG COMMAND=reset This may happen if its calibration is interrupted by the probe being blocked from being extracted. However, the BL-Touch may also not be able to calibrate itself anymore. This happens if the screw on its top is in the wrong position or the magnetic core inside the probe pin has moved. If it has moved up so that it sticks to the screw, it may not be able to lower its pin anymore. With this behavior you need to open the screw and use a ball-point pen to push it gently back into place. Re-Insert the pin into the BL-Touch so that it falls into the extracted position. Carefully readjust the headless screw into place. You need to find the right position so it is able to lower and raise the pin and the red light turns on and of. Use the reset , pin_up and pin_down commands to achieve this.","title":"BL-Touch gone bad"},{"location":"BLTouch.html#bl-touch-clones","text":"Many BL-Touch \"clone\" devices work correctly with Klipper using the default configuration. However, some \"clone\" devices may not support the QUERY_PROBE command and some \"clone\" devices may require configuration of pin_up_reports_not_triggered or pin_up_touch_mode_reports_triggered . Important! Do not configure pin_up_reports_not_triggered or pin_up_touch_mode_reports_triggered to False without first following these directions. Do not configure either of these to False on a genuine BL-Touch. Incorrectly setting these to False can increase probing time and can increase the risk of damaging the printer. Some \"clone\" devices do not support touch_mode and as a result the QUERY_PROBE command does not work. Despite this, it may still be possible to perform probing and homing with these devices. On these devices the QUERY_PROBE command during the initial tests will not succeed, however the subsequent G28 (or PROBE ) test does succeed. It may be possible to use these \"clone\" devices with Klipper if one does not utilize the QUERY_PROBE command and one does not enable the probe_with_touch_mode feature. Some \"clone\" devices are unable to perform Klipper's internal sensor verification test. On these devices, attempts to home or probe can result in Klipper reporting a \"BLTouch failed to verify sensor state\" error. If this occurs, then manually run the steps to confirm the sensor pin is working as described in the initial tests section . If the QUERY_PROBE commands in that test always produce the expected results and \"BLTouch failed to verify sensor state\" errors still occur, then it may be necessary to set pin_up_touch_mode_reports_triggered to False in the Klipper config file. A rare number of old \"clone\" devices are unable to report when they have successfully raised their probe. On these devices Klipper will report a \"BLTouch failed to raise probe\" error after every home or probe attempt. One can test for these devices - move the head far from the bed, run BLTOUCH_DEBUG COMMAND=pin_down , verify the pin has moved down, run QUERY_PROBE , verify that command reports \"probe: open\", run BLTOUCH_DEBUG COMMAND=pin_up , verify the pin has moved up, and run QUERY_PROBE . If the pin remains up, the device does not enter an error state, and the first query reports \"probe: open\" while the second query reports \"probe: TRIGGERED\" then it indicates that pin_up_reports_not_triggered should be set to False in the Klipper config file.","title":"BL-Touch \"clones\""},{"location":"BLTouch.html#bl-touch-v3","text":"Some BL-Touch v3.0 and BL-Touch 3.1 devices may require configuring probe_with_touch_mode in the printer config file. If the BL-Touch v3.0 has its signal wire connected to an endstop pin (with a noise filtering capacitor), then the BL-Touch v3.0 may not be able to consistently send a signal during homing and probing. If the QUERY_PROBE commands in the initial tests section always produce the expected results, but the toolhead does not always stop during G28/PROBE commands, then it is indicative of this issue. A workaround is to set probe_with_touch_mode: True in the config file. The BL-Touch v3.1 may incorrectly enter an error state after a successful probe attempt. The symptoms are an occasional flashing light on the BL-Touch v3.1 that lasts for a couple of seconds after it successfully contacts the bed. Klipper should clear this error automatically and it is generally harmless. However, one may set probe_with_touch_mode in the config file to avoid this issue. Important! Some \"clone\" devices and the BL-Touch v2.0 (and earlier) may have reduced accuracy when probe_with_touch_mode is set to True. Setting this to True also increases the time it takes to deploy the probe. If configuring this value on a \"clone\" or older BL-Touch device, be sure to test the probe accuracy before and after setting this value (use the PROBE_ACCURACY command to test).","title":"BL-Touch v3"},{"location":"BLTouch.html#multi-probing-without-stowing","text":"By default, Klipper will deploy the probe at the start of each probe attempt and then stow the probe afterwards. This repetitive deploying and stowing of the probe may increase the total time of calibration sequences that involve many probe measurements. Klipper supports leaving the probe deployed between consecutive probes, which can reduce the total time of probing. This mode is enabled by configuring stow_on_each_sample to False in the config file. Important! Setting stow_on_each_sample to False can lead to Klipper making horizontal toolhead movements while the probe is deployed. Be sure to verify all probing operations have sufficient Z clearance prior to setting this value to False. If there is insufficient clearance then a horizontal move may cause the pin to catch on an obstruction and result in damage to the printer. Important! It is recommended to use probe_with_touch_mode configured to True when using stow_on_each_sample configured to False. Some \"clone\" devices may not detect a subsequent bed contact if probe_with_touch_mode is not set. On all devices, using the combination of these two settings simplifies the device signaling, which can improve overall stability. Note, however, that some \"clone\" devices and the BL-Touch v2.0 (and earlier) may have reduced accuracy when probe_with_touch_mode is set to True. On these devices it is a good idea to test the probe accuracy before and after setting probe_with_touch_mode (use the PROBE_ACCURACY command to test).","title":"Multi-probing without stowing"},{"location":"BLTouch.html#calibrating-the-bl-touch-offsets","text":"Follow the directions in the Probe Calibrate guide to set the x_offset, y_offset, and z_offset config parameters. It's a good idea to verify that the Z offset is close to 1mm. If not, then you probably want to move the probe up or down to fix this. You want it to trigger well before the nozzle hits the bed, so that possible stuck filament or a warped bed doesn't affect any probing action. But at the same time, you want the retracted position to be as far above the nozzle as possible to avoid it touching printed parts. If an adjustment is made to the probe position, then rerun the probe calibration steps.","title":"Calibrating the BL-Touch offsets"},{"location":"BLTouch.html#bl-touch-output-mode","text":"A BL-Touch V3.0 supports setting a 5V or OPEN-DRAIN output mode, a BL-Touch V3.1 supports this too, but can also store this in its internal EEPROM. If your controller board needs the fixed 5V high logic level of the 5V mode you may set the 'set_output_mode' parameter in the [bltouch] section of the printer config file to \"5V\". Only use the 5V mode if your controller boards input line is 5V tolerant. This is why the default configuration of these BL-Touch versions is OPEN-DRAIN mode. You could potentially damage your controller boards CPU So therefore: If a controller board NEEDs 5V mode AND it is 5V tolerant on its input signal line AND if you have a BL-Touch Smart V3.0, you need the use 'set_output_mode: 5V' parameter to ensure this setting at each startup, since the probe cannot remember the needed setting. you have a BL-Touch Smart V3.1, you have the choice of using 'set_output_mode: 5V' or storing the mode once by use of a 'BLTOUCH_STORE MODE=5V' command manually and NOT using the parameter 'set_output_mode:'. you have some other probe: Some probes have a trace on the circuit board to cut or a jumper to set in order to (permanently) set the output mode. In that case, omit the 'set_output_mode' parameter completely. If you have a V3.1, do not automate or repeat storing the output mode to avoid wearing out the EEPROM of the probe.The BLTouch EEPROM is good for about 100.000 updates. 100 stores per day would add up to about 3 years of operation prior to wearing it out. Thus, storing the output mode in a V3.1 is designed by the vendor to be a complicated operation (the factory default being a safe OPEN DRAIN mode) and is not suited to be repeatedly issued by any slicer, macro or anything else, it is preferably only to be used when first integrating the probe into a printers electronics.","title":"BL-Touch output mode"},{"location":"Beaglebone.html","text":"Beaglebone \u00b6 This document describes the process of running Klipper on a Beaglebone PRU. Building an OS image \u00b6 Start by installing the Debian 11.7 2023-09-02 4GB microSD IoT image. One may run the image from either a micro-SD card or from builtin eMMC. If using the eMMC, install it to eMMC now by following the instructions from the above link. Then ssh into the Beaglebone machine ( ssh debian@beaglebone -- password is temppwd ). Before start installing Klipper you need to free-up additional space. there are 3 options to do that: remove some BeagleBone \"Demo\" resources if you did boot from SD-Card, and it's bigger than 4Gb - you can expand current filesystem to take whole card space do option #1 and #2 together. To remove some BeagleBone \"Demo\" resources execute these commands sudo apt remove bb-node-red-installer sudo apt remove bb-code-server To expand filesystem to full size of your SD-Card execute this command, reboot is not required. sudo growpart /dev/mmcblk0 1 sudo resize2fs /dev/mmcblk0p1 Install Klipper by running the following commands: git clone https://github.com/Klipper3d/klipper.git ./klipper/scripts/install-beaglebone.sh After installing Klipper you need to decide what kind of deployment do you need, but take a note that BeagleBone is 3.3v based hardware and in most cases you can't directly connect pins to 5v or 12v based hardware without conversion boards. As Klipper have multimodule architecture on BeagleBone you can achieve many different use cases, but general ones are following: Use case 1: Use BeagleBone only as a host system to run Klipper and additional software like OctoPrint/Fluidd + Moonraker/... and this configuration will be driving external micro-controllers via serial/usb/canbus connections. Use case 2: Use BeagleBone with extension board (cape) like CRAMPS board. in this configuration BeagleBone will host Klipper + additional software, and it will drive extension board with BeagleBone PRU cores (2 additional cores 200Mh, 32Bit). Use case 3: It's same as \"Use case 1\" but additionally you want to drive BeagleBone GPIOs with high speed by utilizing PRU cores to offload main CPU. Installing Octoprint \u00b6 One may then install Octoprint or fully skip this section if desired other software: git clone https://github.com/foosel/OctoPrint.git cd OctoPrint/ virtualenv venv ./venv/bin/python setup.py install And setup OctoPrint to start at bootup: sudo cp ~/OctoPrint/scripts/octoprint.init /etc/init.d/octoprint sudo chmod +x /etc/init.d/octoprint sudo cp ~/OctoPrint/scripts/octoprint.default /etc/default/octoprint sudo update-rc.d octoprint defaults It is necessary to modify OctoPrint's /etc/default/octoprint configuration file. One must change the OCTOPRINT_USER user to debian , change NICELEVEL to 0 , uncomment the BASEDIR , CONFIGFILE , and DAEMON settings and change the references from /home/pi/ to /home/debian/ : sudo nano /etc/default/octoprint Then start the Octoprint service: sudo systemctl start octoprint Wait 1-2 minutes and make sure the OctoPrint web server is accessible - it should be at: http://beaglebone:5000/ Building the BeagleBone PRU micro-controller code (PRU firmware) \u00b6 This section is required for \"Use case 2\" and \"Use case 3\" mentioned above, you should skip it for \"Use case 1\". Check that required devices are present sudo beagle-version You should check that output contains successful \"remoteproc\" drivers loading and presence of PRU cores, in Kernel 5.10 they should be \"remoteproc1\" and \"remoteproc2\" (4a334000.pru, 4a338000.pru) Also check that many GPIOs are loaded they will look like \"Allocated GPIO id=0 name='P8_03'\" Usually everything is fine and no hardware configuration is required. If something is missing - try to play with \"uboot overlays\" options or with cape-overlays Just for reference some output of working BeagleBone Black configuration with CRAMPS board: model:[TI_AM335x_BeagleBone_Black] UBOOT: Booted Device-Tree:[am335x-boneblack-uboot-univ.dts] UBOOT: Loaded Overlay:[BB-ADC-00A0.bb.org-overlays] UBOOT: Loaded Overlay:[BB-BONE-eMMC1-01-00A0.bb.org-overlays] kernel:[5.10.168-ti-r71] /boot/uEnv.txt Settings: uboot_overlay_options:[enable_uboot_overlays=1] uboot_overlay_options:[disable_uboot_overlay_video=0] uboot_overlay_options:[disable_uboot_overlay_audio=1] uboot_overlay_options:[disable_uboot_overlay_wireless=1] uboot_overlay_options:[enable_uboot_cape_universal=1] pkg:[bb-cape-overlays]:[4.14.20210821.0-0~bullseye+20210821] pkg:[bb-customizations]:[1.20230720.1-0~bullseye+20230720] pkg:[bb-usb-gadgets]:[1.20230414.0-0~bullseye+20230414] pkg:[bb-wl18xx-firmware]:[1.20230414.0-0~bullseye+20230414] ............. ............. To compile the Klipper micro-controller code, start by configuring it for the \"Beaglebone PRU\", for \"BeagleBone Black\" additionally disable options \"Support GPIO Bit-banging devices\" and disable \"Support LCD devices\" inside the \"Optional features\" because they will not fit in 8Kb PRU firmware memory, then exit and save config: cd ~/klipper/ make menuconfig To build and install the new PRU micro-controller code, run: sudo service klipper stop make flash sudo service klipper start After previous commands was executed your PRU firmware should be ready and started to check if everything was fine you can execute following command dmesg and compare last messages with sample one which indicate that everything started properly: [ 71.105499] remoteproc remoteproc1: 4a334000.pru is available [ 71.157155] remoteproc remoteproc2: 4a338000.pru is available [ 73.256287] remoteproc remoteproc1: powering up 4a334000.pru [ 73.279246] remoteproc remoteproc1: Booting fw image am335x-pru0-fw, size 97112 [ 73.285807] remoteproc1#vdev0buffer: registered virtio0 (type 7) [ 73.285836] remoteproc remoteproc1: remote processor 4a334000.pru is now up [ 73.286322] remoteproc remoteproc2: powering up 4a338000.pru [ 73.313717] remoteproc remoteproc2: Booting fw image am335x-pru1-fw, size 188560 [ 73.313753] remoteproc remoteproc2: header-less resource table [ 73.329964] remoteproc remoteproc2: header-less resource table [ 73.348321] remoteproc remoteproc2: remote processor 4a338000.pru is now up [ 73.443355] virtio_rpmsg_bus virtio0: creating channel rpmsg-pru addr 0x1e [ 73.443727] virtio_rpmsg_bus virtio0: msg received with no recipient [ 73.444352] virtio_rpmsg_bus virtio0: rpmsg host is online [ 73.540993] rpmsg_pru virtio0.rpmsg-pru.-1.30: new rpmsg_pru device: /dev/rpmsg_pru30 take a note about \"/dev/rpmsg_pru30\" - it's your future serial device for main mcu configuration this device is required to be present, if it's absent - your PRU cores did not start properly. Building and installing Linux host micro-controller code \u00b6 This section is required for \"Use case 2\" and optional for \"Use case 3\" mentioned above It is also necessary to compile and install the micro-controller code for a Linux host process. Configure it a second time for a \"Linux process\": make menuconfig Then install this micro-controller code as well: sudo service klipper stop make flash sudo service klipper start take a note about \"/tmp/klipper_host_mcu\" - it will be your future serial device for \"mcu host\" if that file don't exist - refer to \"scripts/klipper-mcu.service\" file, it was installed by previous commands, and it's responsible for it. Take a note for \"Use case 2\" about following: when you will define printer configuration you should always use temperature sensors from \"mcu host\" because ADCs not present in default \"mcu\" (PRU cores). Sample configuration of \"sensor_pin\" for extruder and heated bed are available in \"generic-cramps.cfg\" You can use any other GPIO directly from \"mcu host\" by referencing them this way \"host:gpiochip1/gpio17\" but that should be avoided because it will be creating additional load on main CPU and most probably you can't use them for stepper control. Remaining configuration \u00b6 Complete the installation by configuring Klipper following the instructions in the main Installation document. Printing on the Beaglebone \u00b6 Unfortunately, the Beaglebone processor can sometimes struggle to run OctoPrint well. Print stalls have been known to occur on complex prints (the printer may move faster than OctoPrint can send movement commands). If this occurs, consider using the \"virtual_sdcard\" feature (see Config Reference for details) to print directly from Klipper and disable any DEBUG or VERBOSE logging options if you did enable them. AVR micro-controller code build \u00b6 This environment have everything to build necessary micro-controller code except AVR, AVR packages was removed because of conflict with PRU packages. if you still want to build AVR micro-controller code in this environment you need to remove PRU packages and install AVR packages by executing following commands sudo apt-get remove gcc-pru sudo apt-get install avrdude gcc-avr binutils-avr avr-libc if you need to restore PRU packages - then remove ARV packages before that sudo apt-get remove avrdude gcc-avr binutils-avr avr-libc sudo apt-get install gcc-pru Hardware Pin designation \u00b6 BeagleBone is very flexible in terms of pin designation, same pin can be configured for different function but always single function for single pin, same function can be present on different pins. So you can't have multiple functions on single pin or have same function on multiple pins. Example: P9_20 - i2c2_sda/can0_tx/spi1_cs0/gpio0_12/uart1_ctsn P9_19 - i2c2_scl/can0_rx/spi1_cs1/gpio0_13/uart1_rtsn P9_24 - i2c1_scl/can1_rx/gpio0_15/uart1_tx P9_26 - i2c1_sda/can1_tx/gpio0_14/uart1_rx Pin designation is defined by using special \"overlays\" which will be loaded during linux boot they are configured by editing file /boot/uEnv.txt with elevated permissions sudo editor /boot/uEnv.txt and defining which functionality to load, for example to enable CAN1 you need to define overlay for it uboot_overlay_addr4=/lib/firmware/BB-CAN1-00A0.dtbo This overlay BB-CAN1-00A0.dtbo will reconfigure all required pins for CAN1 and create CAN device in Linux. Any change in overlays will require system reboot to be applied. If you need to understand which pins are involved in some overlay - you can analyze source files in this location: /opt/sources/bb.org-overlays/src/arm/ or search info in BeagleBone forums. Enabling hardware SPI \u00b6 BeagleBone usually have multiple hardware SPI buses, for example BeagleBone Black can have 2 of them, they can work up to 48Mhz, but usually they are limited to 16Mhz by Kernel Device-tree. By default, in BeagleBone Black some of SPI1 pins are configured for HDMI-Audio output, to fully enable 4-wire SPI1 you need to disable HDMI Audio and enable SPI1 To do that edit file /boot/uEnv.txt with elevated permissions sudo editor /boot/uEnv.txt uncomment variable disable_uboot_overlay_audio=1 next uncomment variable and define it this way uboot_overlay_addr4=/lib/firmware/BB-SPIDEV1-00A0.dtbo Save changes in /boot/uEnv.txt and reboot the board. Now you have SPI1 Enabled, to verify its presence execute command ls /dev/spidev1.* Take a note that BeagleBone usually is 3.3v based hardware and to use 5V SPI devices you need to add Level-Shifting chip, for example SN74CBTD3861, SN74LVC1G34 or similar. If you are using CRAMPS board - it already contains Level-Shifting chip and SPI1 pins will become available on P503 port, and they can accept 5v hardware, check CRAMPS board Schematics for pin references. Enabling hardware I2C \u00b6 BeagleBone usually have multiple hardware I2C buses, for example BeagleBone Black can have 3 of them, they support speed up-to 400Kbit Fast mode. By default, in BeagleBone Black there are two of them (i2c-1 and i2c-2) usually both are already configured and present on P9, third ic2-0 usually reserved for internal use. If you are using CRAMPS board then i2c-2 is present on P303 port with 3.3v level, If you want to obtain I2c-1 in CRAMPS board - you can get them on Extruder1.Step, Extruder1.Dir pins, they also are 3.3v based, check CRAMPS board Schematics for pin references. Related overlays, for Hardware Pin designation : I2C1(100Kbit): BB-I2C1-00A0.dtbo I2C1(400Kbit): BB-I2C1-FAST-00A0.dtbo I2C2(100Kbit): BB-I2C2-00A0.dtbo I2C2(400Kbit): BB-I2C2-FAST-00A0.dtbo Enabling hardware UART(Serial)/CAN \u00b6 BeagleBone have up to 6 hardware UART(Serial) buses (up to 3Mbit) and up to 2 hardware CAN(1Mbit) buses. UART1(RX,TX) and CAN1(TX,RX) and I2C2(SDA,SCL) are using same pins - so you need to chose what to use UART1(CTSN,RTSN) and CAN0(TX,RX) and I2C1(SDA,SCL) are using same pins - so you need to chose what to use All UART/CAN related pins are 3.3v based, so you will need to use Transceiver chips/boards like SN74LVC2G241DCUR (for UART), SN65HVD230 (for CAN), TTL-RS485 (for RS-485) or something similar which can convert 3.3v signals to appropriate levels. Related overlays, for Hardware Pin designation CAN0: BB-CAN0-00A0.dtbo CAN1: BB-CAN1-00A0.dtbo UART0: - used for Console UART1(RX,TX): BB-UART1-00A0.dtbo UART1(RTS,CTS): BB-UART1-RTSCTS-00A0.dtbo UART2(RX,TX): BB-UART2-00A0.dtbo UART3(RX,TX): BB-UART3-00A0.dtbo UART4(RS-485): BB-UART4-RS485-00A0.dtbo UART5(RX,TX): BB-UART5-00A0.dtbo","title":"Beaglebone"},{"location":"Beaglebone.html#beaglebone","text":"This document describes the process of running Klipper on a Beaglebone PRU.","title":"Beaglebone"},{"location":"Beaglebone.html#building-an-os-image","text":"Start by installing the Debian 11.7 2023-09-02 4GB microSD IoT image. One may run the image from either a micro-SD card or from builtin eMMC. If using the eMMC, install it to eMMC now by following the instructions from the above link. Then ssh into the Beaglebone machine ( ssh debian@beaglebone -- password is temppwd ). Before start installing Klipper you need to free-up additional space. there are 3 options to do that: remove some BeagleBone \"Demo\" resources if you did boot from SD-Card, and it's bigger than 4Gb - you can expand current filesystem to take whole card space do option #1 and #2 together. To remove some BeagleBone \"Demo\" resources execute these commands sudo apt remove bb-node-red-installer sudo apt remove bb-code-server To expand filesystem to full size of your SD-Card execute this command, reboot is not required. sudo growpart /dev/mmcblk0 1 sudo resize2fs /dev/mmcblk0p1 Install Klipper by running the following commands: git clone https://github.com/Klipper3d/klipper.git ./klipper/scripts/install-beaglebone.sh After installing Klipper you need to decide what kind of deployment do you need, but take a note that BeagleBone is 3.3v based hardware and in most cases you can't directly connect pins to 5v or 12v based hardware without conversion boards. As Klipper have multimodule architecture on BeagleBone you can achieve many different use cases, but general ones are following: Use case 1: Use BeagleBone only as a host system to run Klipper and additional software like OctoPrint/Fluidd + Moonraker/... and this configuration will be driving external micro-controllers via serial/usb/canbus connections. Use case 2: Use BeagleBone with extension board (cape) like CRAMPS board. in this configuration BeagleBone will host Klipper + additional software, and it will drive extension board with BeagleBone PRU cores (2 additional cores 200Mh, 32Bit). Use case 3: It's same as \"Use case 1\" but additionally you want to drive BeagleBone GPIOs with high speed by utilizing PRU cores to offload main CPU.","title":"Building an OS image"},{"location":"Beaglebone.html#installing-octoprint","text":"One may then install Octoprint or fully skip this section if desired other software: git clone https://github.com/foosel/OctoPrint.git cd OctoPrint/ virtualenv venv ./venv/bin/python setup.py install And setup OctoPrint to start at bootup: sudo cp ~/OctoPrint/scripts/octoprint.init /etc/init.d/octoprint sudo chmod +x /etc/init.d/octoprint sudo cp ~/OctoPrint/scripts/octoprint.default /etc/default/octoprint sudo update-rc.d octoprint defaults It is necessary to modify OctoPrint's /etc/default/octoprint configuration file. One must change the OCTOPRINT_USER user to debian , change NICELEVEL to 0 , uncomment the BASEDIR , CONFIGFILE , and DAEMON settings and change the references from /home/pi/ to /home/debian/ : sudo nano /etc/default/octoprint Then start the Octoprint service: sudo systemctl start octoprint Wait 1-2 minutes and make sure the OctoPrint web server is accessible - it should be at: http://beaglebone:5000/","title":"Installing Octoprint"},{"location":"Beaglebone.html#building-the-beaglebone-pru-micro-controller-code-pru-firmware","text":"This section is required for \"Use case 2\" and \"Use case 3\" mentioned above, you should skip it for \"Use case 1\". Check that required devices are present sudo beagle-version You should check that output contains successful \"remoteproc\" drivers loading and presence of PRU cores, in Kernel 5.10 they should be \"remoteproc1\" and \"remoteproc2\" (4a334000.pru, 4a338000.pru) Also check that many GPIOs are loaded they will look like \"Allocated GPIO id=0 name='P8_03'\" Usually everything is fine and no hardware configuration is required. If something is missing - try to play with \"uboot overlays\" options or with cape-overlays Just for reference some output of working BeagleBone Black configuration with CRAMPS board: model:[TI_AM335x_BeagleBone_Black] UBOOT: Booted Device-Tree:[am335x-boneblack-uboot-univ.dts] UBOOT: Loaded Overlay:[BB-ADC-00A0.bb.org-overlays] UBOOT: Loaded Overlay:[BB-BONE-eMMC1-01-00A0.bb.org-overlays] kernel:[5.10.168-ti-r71] /boot/uEnv.txt Settings: uboot_overlay_options:[enable_uboot_overlays=1] uboot_overlay_options:[disable_uboot_overlay_video=0] uboot_overlay_options:[disable_uboot_overlay_audio=1] uboot_overlay_options:[disable_uboot_overlay_wireless=1] uboot_overlay_options:[enable_uboot_cape_universal=1] pkg:[bb-cape-overlays]:[4.14.20210821.0-0~bullseye+20210821] pkg:[bb-customizations]:[1.20230720.1-0~bullseye+20230720] pkg:[bb-usb-gadgets]:[1.20230414.0-0~bullseye+20230414] pkg:[bb-wl18xx-firmware]:[1.20230414.0-0~bullseye+20230414] ............. ............. To compile the Klipper micro-controller code, start by configuring it for the \"Beaglebone PRU\", for \"BeagleBone Black\" additionally disable options \"Support GPIO Bit-banging devices\" and disable \"Support LCD devices\" inside the \"Optional features\" because they will not fit in 8Kb PRU firmware memory, then exit and save config: cd ~/klipper/ make menuconfig To build and install the new PRU micro-controller code, run: sudo service klipper stop make flash sudo service klipper start After previous commands was executed your PRU firmware should be ready and started to check if everything was fine you can execute following command dmesg and compare last messages with sample one which indicate that everything started properly: [ 71.105499] remoteproc remoteproc1: 4a334000.pru is available [ 71.157155] remoteproc remoteproc2: 4a338000.pru is available [ 73.256287] remoteproc remoteproc1: powering up 4a334000.pru [ 73.279246] remoteproc remoteproc1: Booting fw image am335x-pru0-fw, size 97112 [ 73.285807] remoteproc1#vdev0buffer: registered virtio0 (type 7) [ 73.285836] remoteproc remoteproc1: remote processor 4a334000.pru is now up [ 73.286322] remoteproc remoteproc2: powering up 4a338000.pru [ 73.313717] remoteproc remoteproc2: Booting fw image am335x-pru1-fw, size 188560 [ 73.313753] remoteproc remoteproc2: header-less resource table [ 73.329964] remoteproc remoteproc2: header-less resource table [ 73.348321] remoteproc remoteproc2: remote processor 4a338000.pru is now up [ 73.443355] virtio_rpmsg_bus virtio0: creating channel rpmsg-pru addr 0x1e [ 73.443727] virtio_rpmsg_bus virtio0: msg received with no recipient [ 73.444352] virtio_rpmsg_bus virtio0: rpmsg host is online [ 73.540993] rpmsg_pru virtio0.rpmsg-pru.-1.30: new rpmsg_pru device: /dev/rpmsg_pru30 take a note about \"/dev/rpmsg_pru30\" - it's your future serial device for main mcu configuration this device is required to be present, if it's absent - your PRU cores did not start properly.","title":"Building the BeagleBone PRU micro-controller code (PRU firmware)"},{"location":"Beaglebone.html#building-and-installing-linux-host-micro-controller-code","text":"This section is required for \"Use case 2\" and optional for \"Use case 3\" mentioned above It is also necessary to compile and install the micro-controller code for a Linux host process. Configure it a second time for a \"Linux process\": make menuconfig Then install this micro-controller code as well: sudo service klipper stop make flash sudo service klipper start take a note about \"/tmp/klipper_host_mcu\" - it will be your future serial device for \"mcu host\" if that file don't exist - refer to \"scripts/klipper-mcu.service\" file, it was installed by previous commands, and it's responsible for it. Take a note for \"Use case 2\" about following: when you will define printer configuration you should always use temperature sensors from \"mcu host\" because ADCs not present in default \"mcu\" (PRU cores). Sample configuration of \"sensor_pin\" for extruder and heated bed are available in \"generic-cramps.cfg\" You can use any other GPIO directly from \"mcu host\" by referencing them this way \"host:gpiochip1/gpio17\" but that should be avoided because it will be creating additional load on main CPU and most probably you can't use them for stepper control.","title":"Building and installing Linux host micro-controller code"},{"location":"Beaglebone.html#remaining-configuration","text":"Complete the installation by configuring Klipper following the instructions in the main Installation document.","title":"Remaining configuration"},{"location":"Beaglebone.html#printing-on-the-beaglebone","text":"Unfortunately, the Beaglebone processor can sometimes struggle to run OctoPrint well. Print stalls have been known to occur on complex prints (the printer may move faster than OctoPrint can send movement commands). If this occurs, consider using the \"virtual_sdcard\" feature (see Config Reference for details) to print directly from Klipper and disable any DEBUG or VERBOSE logging options if you did enable them.","title":"Printing on the Beaglebone"},{"location":"Beaglebone.html#avr-micro-controller-code-build","text":"This environment have everything to build necessary micro-controller code except AVR, AVR packages was removed because of conflict with PRU packages. if you still want to build AVR micro-controller code in this environment you need to remove PRU packages and install AVR packages by executing following commands sudo apt-get remove gcc-pru sudo apt-get install avrdude gcc-avr binutils-avr avr-libc if you need to restore PRU packages - then remove ARV packages before that sudo apt-get remove avrdude gcc-avr binutils-avr avr-libc sudo apt-get install gcc-pru","title":"AVR micro-controller code build"},{"location":"Beaglebone.html#hardware-pin-designation","text":"BeagleBone is very flexible in terms of pin designation, same pin can be configured for different function but always single function for single pin, same function can be present on different pins. So you can't have multiple functions on single pin or have same function on multiple pins. Example: P9_20 - i2c2_sda/can0_tx/spi1_cs0/gpio0_12/uart1_ctsn P9_19 - i2c2_scl/can0_rx/spi1_cs1/gpio0_13/uart1_rtsn P9_24 - i2c1_scl/can1_rx/gpio0_15/uart1_tx P9_26 - i2c1_sda/can1_tx/gpio0_14/uart1_rx Pin designation is defined by using special \"overlays\" which will be loaded during linux boot they are configured by editing file /boot/uEnv.txt with elevated permissions sudo editor /boot/uEnv.txt and defining which functionality to load, for example to enable CAN1 you need to define overlay for it uboot_overlay_addr4=/lib/firmware/BB-CAN1-00A0.dtbo This overlay BB-CAN1-00A0.dtbo will reconfigure all required pins for CAN1 and create CAN device in Linux. Any change in overlays will require system reboot to be applied. If you need to understand which pins are involved in some overlay - you can analyze source files in this location: /opt/sources/bb.org-overlays/src/arm/ or search info in BeagleBone forums.","title":"Hardware Pin designation"},{"location":"Beaglebone.html#enabling-hardware-spi","text":"BeagleBone usually have multiple hardware SPI buses, for example BeagleBone Black can have 2 of them, they can work up to 48Mhz, but usually they are limited to 16Mhz by Kernel Device-tree. By default, in BeagleBone Black some of SPI1 pins are configured for HDMI-Audio output, to fully enable 4-wire SPI1 you need to disable HDMI Audio and enable SPI1 To do that edit file /boot/uEnv.txt with elevated permissions sudo editor /boot/uEnv.txt uncomment variable disable_uboot_overlay_audio=1 next uncomment variable and define it this way uboot_overlay_addr4=/lib/firmware/BB-SPIDEV1-00A0.dtbo Save changes in /boot/uEnv.txt and reboot the board. Now you have SPI1 Enabled, to verify its presence execute command ls /dev/spidev1.* Take a note that BeagleBone usually is 3.3v based hardware and to use 5V SPI devices you need to add Level-Shifting chip, for example SN74CBTD3861, SN74LVC1G34 or similar. If you are using CRAMPS board - it already contains Level-Shifting chip and SPI1 pins will become available on P503 port, and they can accept 5v hardware, check CRAMPS board Schematics for pin references.","title":"Enabling hardware SPI"},{"location":"Beaglebone.html#enabling-hardware-i2c","text":"BeagleBone usually have multiple hardware I2C buses, for example BeagleBone Black can have 3 of them, they support speed up-to 400Kbit Fast mode. By default, in BeagleBone Black there are two of them (i2c-1 and i2c-2) usually both are already configured and present on P9, third ic2-0 usually reserved for internal use. If you are using CRAMPS board then i2c-2 is present on P303 port with 3.3v level, If you want to obtain I2c-1 in CRAMPS board - you can get them on Extruder1.Step, Extruder1.Dir pins, they also are 3.3v based, check CRAMPS board Schematics for pin references. Related overlays, for Hardware Pin designation : I2C1(100Kbit): BB-I2C1-00A0.dtbo I2C1(400Kbit): BB-I2C1-FAST-00A0.dtbo I2C2(100Kbit): BB-I2C2-00A0.dtbo I2C2(400Kbit): BB-I2C2-FAST-00A0.dtbo","title":"Enabling hardware I2C"},{"location":"Beaglebone.html#enabling-hardware-uartserialcan","text":"BeagleBone have up to 6 hardware UART(Serial) buses (up to 3Mbit) and up to 2 hardware CAN(1Mbit) buses. UART1(RX,TX) and CAN1(TX,RX) and I2C2(SDA,SCL) are using same pins - so you need to chose what to use UART1(CTSN,RTSN) and CAN0(TX,RX) and I2C1(SDA,SCL) are using same pins - so you need to chose what to use All UART/CAN related pins are 3.3v based, so you will need to use Transceiver chips/boards like SN74LVC2G241DCUR (for UART), SN65HVD230 (for CAN), TTL-RS485 (for RS-485) or something similar which can convert 3.3v signals to appropriate levels. Related overlays, for Hardware Pin designation CAN0: BB-CAN0-00A0.dtbo CAN1: BB-CAN1-00A0.dtbo UART0: - used for Console UART1(RX,TX): BB-UART1-00A0.dtbo UART1(RTS,CTS): BB-UART1-RTSCTS-00A0.dtbo UART2(RX,TX): BB-UART2-00A0.dtbo UART3(RX,TX): BB-UART3-00A0.dtbo UART4(RS-485): BB-UART4-RS485-00A0.dtbo UART5(RX,TX): BB-UART5-00A0.dtbo","title":"Enabling hardware UART(Serial)/CAN"},{"location":"Bed_Level.html","text":"Bed leveling \u00b6 Bed leveling (sometimes also referred to as \"bed tramming\") is critical to getting high quality prints. If a bed is not properly \"leveled\" it can lead to poor bed adhesion, \"warping\", and subtle problems throughout the print. This document serves as a guide to performing bed leveling in Klipper. It's important to understand the goal of bed leveling. If the printer is commanded to a position X0 Y0 Z10 during a print, then the goal is for the printer's nozzle to be exactly 10mm from the printer's bed. Further, should the printer then be commanded to a position of X50 Z10 the goal is for the nozzle to maintain an exact distance of 10mm from the bed during that entire horizontal move. In order to get good quality prints the printer should be calibrated so that Z distances are accurate to within about 25 microns (.025mm). This is a small distance - significantly smaller than the width of a typical human hair. This scale can not be measured \"by eye\". Subtle effects (such as heat expansion) impact measurements at this scale. The secret to getting high accuracy is to use a repeatable process and to use a leveling method that leverages the high accuracy of the printer's own motion system. Choose the appropriate calibration mechanism \u00b6 Different types of printers use different methods for performing bed leveling. All of them ultimately depend on the \"paper test\" (described below). However, the actual process for a particular type of printer is described in other documents. Prior to running any of these calibration tools, be sure to run the checks described in the config check document . It is necessary to verify basic printer motion before performing bed leveling. For printers with an \"automatic Z probe\" be sure to calibrate the probe following the directions in the Probe Calibrate document. For delta printers, see the Delta Calibrate document. For printers with bed screws and traditional Z endstops, see the Manual Level document. During calibration it may be necessary to set the printer's Z position_min to a negative number (eg, position_min = -2 ). The printer enforces boundary checks even during calibration routines. Setting a negative number allows the printer to move below the nominal position of the bed, which may help when trying to determine the actual bed position. The \"paper test\" \u00b6 The primary bed calibration mechanism is the \"paper test\". It involves placing a regular piece of \"copy machine paper\" between the printer's bed and nozzle, and then commanding the nozzle to different Z heights until one feels a small amount of friction when pushing the paper back and forth. It is important to understand the \"paper test\" even if one has an \"automatic Z probe\". The probe itself often needs to be calibrated to get good results. That probe calibration is done using this \"paper test\". In order to perform the paper test, cut a small rectangular piece of paper using a pair of scissors (eg, 5x3 cm). The paper generally has a thickness of around 100 microns (0.100mm). (The exact thickness of the paper isn't crucial.) The first step of the paper test is to inspect the printer's nozzle and bed. Make sure there is no plastic (or other debris) on the nozzle or bed. Inspect the nozzle and bed to ensure no plastic is present! If one always prints on a particular tape or printing surface then one may perform the paper test with that tape/surface in place. However, note that tape itself has a thickness and different tapes (or any other printing surface) will impact Z measurements. Be sure to rerun the paper test to measure each type of surface that is in use. If there is plastic on the nozzle then heat up the extruder and use a metal tweezers to remove that plastic. Wait for the extruder to fully cool to room temperature before continuing with the paper test. While the nozzle is cooling, use the metal tweezers to remove any plastic that may ooze out. Always perform the paper test when both nozzle and bed are at room temperature! When the nozzle is heated, its position (relative to the bed) changes due to thermal expansion. This thermal expansion is typically around a 100 microns, which is about the same thickness as a typical piece of printer paper. The exact amount of thermal expansion isn't crucial, just as the exact thickness of the paper isn't crucial. Start with the assumption that the two are equal (see below for a method of determining the difference between the two distances). It may seem odd to calibrate the distance at room temperature when the goal is to have a consistent distance when heated. However, if one calibrates when the nozzle is heated, it tends to impart small amounts of molten plastic on to the paper, which changes the amount of friction felt. That makes it harder to get a good calibration. Calibrating while the bed/nozzle is hot also greatly increases the risk of burning oneself. The amount of thermal expansion is stable, so it is easily accounted for later in the calibration process. Use an automated tool to determine precise Z heights! Klipper has several helper scripts available (eg, MANUAL_PROBE, Z_ENDSTOP_CALIBRATE, PROBE_CALIBRATE, DELTA_CALIBRATE). See the documents described above to choose one of them. Run the appropriate command in the OctoPrint terminal window. The script will prompt for user interaction in the OctoPrint terminal output. It will look something like: Recv: // Starting manual Z probe. Use TESTZ to adjust position. Recv: // Finish with ACCEPT or ABORT command. Recv: // Z position: ?????? --> 5.000 <-- ?????? The current height of the nozzle (as the printer currently understands it) is shown between the \"--> <--\". The number to the right is the height of the last probe attempt just greater than the current height, and to the left is the last probe attempt less than the current height (or ?????? if no attempt has been made). Place the paper between the nozzle and bed. It can be useful to fold a corner of the paper so that it is easier to grab. (Try not to push down on the bed when moving the paper back and forth.) Use the TESTZ command to request the nozzle to move closer to the paper. For example: TESTZ Z=-.1 The TESTZ command will move the nozzle a relative distance from the nozzle's current position. (So, Z=-.1 requests the nozzle to move closer to the bed by .1mm.) After the nozzle stops moving, push the paper back and forth to check if the nozzle is in contact with the paper and to feel the amount of friction. Continue issuing TESTZ commands until one feels a small amount of friction when testing with the paper. If too much friction is found then one can use a positive Z value to move the nozzle up. It is also possible to use TESTZ Z=+ or TESTZ Z=- to \"bisect\" the last position - that is to move to a position half way between two positions. For example, if one received the following prompt from a TESTZ command: Recv: // Z position: 0.130 --> 0.230 <-- 0.280 Then a TESTZ Z=- would move the nozzle to a Z position of 0.180 (half way between 0.130 and 0.230). One can use this feature to help rapidly narrow down to a consistent friction. It is also possible to use Z=++ and Z=-- to return directly to a past measurement - for example, after the above prompt a TESTZ Z=-- command would move the nozzle to a Z position of 0.130. After finding a small amount of friction run the ACCEPT command: ACCEPT This will accept the given Z height and proceed with the given calibration tool. The exact amount of friction felt isn't crucial, just as the amount of thermal expansion and exact width of the paper isn't crucial. Just try to obtain the same amount of friction each time one runs the test. If something goes wrong during the test, one can use the ABORT command to exit the calibration tool. Determining Thermal Expansion \u00b6 After successfully performing bed leveling, one may go on to calculate a more precise value for the combined impact of \"thermal expansion\", \"thickness of the paper\", and \"amount of friction felt during the paper test\". This type of calculation is generally not needed as most users find the simple \"paper test\" provides good results. The easiest way to make this calculation is to print a test object that has straight walls on all sides. The large hollow square found in docs/prints/square.stl can be used for this. When slicing the object, make sure the slicer uses the same layer height and extrusion widths for the first level that it does for all subsequent layers. Use a coarse layer height (the layer height should be around 75% of the nozzle diameter) and do not use a brim or raft. Print the test object, wait for it to cool, and remove it from the bed. Inspect the lowest layer of the object. (It may also be useful to run a finger or nail along the bottom edge.) If one finds the bottom layer bulges out slightly along all sides of the object then it indicates the nozzle was slightly closer to the bed then it should be. One can issue a SET_GCODE_OFFSET Z=+.010 command to increase the height. In subsequent prints one can inspect for this behavior and make further adjustment as needed. Adjustments of this type are typically in 10s of microns (.010mm). If the bottom layer consistently appears narrower than subsequent layers then one can use the SET_GCODE_OFFSET command to make a negative Z adjustment. If one is unsure, then one can decrease the Z adjustment until the bottom layer of prints exhibit a small bulge, and then back-off until it disappears. The easiest way to apply the desired Z adjustment is to create a START_PRINT g-code macro, arrange for the slicer to call that macro during the start of each print, and add a SET_GCODE_OFFSET command to that macro. See the slicers document for further details.","title":"Bed leveling"},{"location":"Bed_Level.html#bed-leveling","text":"Bed leveling (sometimes also referred to as \"bed tramming\") is critical to getting high quality prints. If a bed is not properly \"leveled\" it can lead to poor bed adhesion, \"warping\", and subtle problems throughout the print. This document serves as a guide to performing bed leveling in Klipper. It's important to understand the goal of bed leveling. If the printer is commanded to a position X0 Y0 Z10 during a print, then the goal is for the printer's nozzle to be exactly 10mm from the printer's bed. Further, should the printer then be commanded to a position of X50 Z10 the goal is for the nozzle to maintain an exact distance of 10mm from the bed during that entire horizontal move. In order to get good quality prints the printer should be calibrated so that Z distances are accurate to within about 25 microns (.025mm). This is a small distance - significantly smaller than the width of a typical human hair. This scale can not be measured \"by eye\". Subtle effects (such as heat expansion) impact measurements at this scale. The secret to getting high accuracy is to use a repeatable process and to use a leveling method that leverages the high accuracy of the printer's own motion system.","title":"Bed leveling"},{"location":"Bed_Level.html#choose-the-appropriate-calibration-mechanism","text":"Different types of printers use different methods for performing bed leveling. All of them ultimately depend on the \"paper test\" (described below). However, the actual process for a particular type of printer is described in other documents. Prior to running any of these calibration tools, be sure to run the checks described in the config check document . It is necessary to verify basic printer motion before performing bed leveling. For printers with an \"automatic Z probe\" be sure to calibrate the probe following the directions in the Probe Calibrate document. For delta printers, see the Delta Calibrate document. For printers with bed screws and traditional Z endstops, see the Manual Level document. During calibration it may be necessary to set the printer's Z position_min to a negative number (eg, position_min = -2 ). The printer enforces boundary checks even during calibration routines. Setting a negative number allows the printer to move below the nominal position of the bed, which may help when trying to determine the actual bed position.","title":"Choose the appropriate calibration mechanism"},{"location":"Bed_Level.html#the-paper-test","text":"The primary bed calibration mechanism is the \"paper test\". It involves placing a regular piece of \"copy machine paper\" between the printer's bed and nozzle, and then commanding the nozzle to different Z heights until one feels a small amount of friction when pushing the paper back and forth. It is important to understand the \"paper test\" even if one has an \"automatic Z probe\". The probe itself often needs to be calibrated to get good results. That probe calibration is done using this \"paper test\". In order to perform the paper test, cut a small rectangular piece of paper using a pair of scissors (eg, 5x3 cm). The paper generally has a thickness of around 100 microns (0.100mm). (The exact thickness of the paper isn't crucial.) The first step of the paper test is to inspect the printer's nozzle and bed. Make sure there is no plastic (or other debris) on the nozzle or bed. Inspect the nozzle and bed to ensure no plastic is present! If one always prints on a particular tape or printing surface then one may perform the paper test with that tape/surface in place. However, note that tape itself has a thickness and different tapes (or any other printing surface) will impact Z measurements. Be sure to rerun the paper test to measure each type of surface that is in use. If there is plastic on the nozzle then heat up the extruder and use a metal tweezers to remove that plastic. Wait for the extruder to fully cool to room temperature before continuing with the paper test. While the nozzle is cooling, use the metal tweezers to remove any plastic that may ooze out. Always perform the paper test when both nozzle and bed are at room temperature! When the nozzle is heated, its position (relative to the bed) changes due to thermal expansion. This thermal expansion is typically around a 100 microns, which is about the same thickness as a typical piece of printer paper. The exact amount of thermal expansion isn't crucial, just as the exact thickness of the paper isn't crucial. Start with the assumption that the two are equal (see below for a method of determining the difference between the two distances). It may seem odd to calibrate the distance at room temperature when the goal is to have a consistent distance when heated. However, if one calibrates when the nozzle is heated, it tends to impart small amounts of molten plastic on to the paper, which changes the amount of friction felt. That makes it harder to get a good calibration. Calibrating while the bed/nozzle is hot also greatly increases the risk of burning oneself. The amount of thermal expansion is stable, so it is easily accounted for later in the calibration process. Use an automated tool to determine precise Z heights! Klipper has several helper scripts available (eg, MANUAL_PROBE, Z_ENDSTOP_CALIBRATE, PROBE_CALIBRATE, DELTA_CALIBRATE). See the documents described above to choose one of them. Run the appropriate command in the OctoPrint terminal window. The script will prompt for user interaction in the OctoPrint terminal output. It will look something like: Recv: // Starting manual Z probe. Use TESTZ to adjust position. Recv: // Finish with ACCEPT or ABORT command. Recv: // Z position: ?????? --> 5.000 <-- ?????? The current height of the nozzle (as the printer currently understands it) is shown between the \"--> <--\". The number to the right is the height of the last probe attempt just greater than the current height, and to the left is the last probe attempt less than the current height (or ?????? if no attempt has been made). Place the paper between the nozzle and bed. It can be useful to fold a corner of the paper so that it is easier to grab. (Try not to push down on the bed when moving the paper back and forth.) Use the TESTZ command to request the nozzle to move closer to the paper. For example: TESTZ Z=-.1 The TESTZ command will move the nozzle a relative distance from the nozzle's current position. (So, Z=-.1 requests the nozzle to move closer to the bed by .1mm.) After the nozzle stops moving, push the paper back and forth to check if the nozzle is in contact with the paper and to feel the amount of friction. Continue issuing TESTZ commands until one feels a small amount of friction when testing with the paper. If too much friction is found then one can use a positive Z value to move the nozzle up. It is also possible to use TESTZ Z=+ or TESTZ Z=- to \"bisect\" the last position - that is to move to a position half way between two positions. For example, if one received the following prompt from a TESTZ command: Recv: // Z position: 0.130 --> 0.230 <-- 0.280 Then a TESTZ Z=- would move the nozzle to a Z position of 0.180 (half way between 0.130 and 0.230). One can use this feature to help rapidly narrow down to a consistent friction. It is also possible to use Z=++ and Z=-- to return directly to a past measurement - for example, after the above prompt a TESTZ Z=-- command would move the nozzle to a Z position of 0.130. After finding a small amount of friction run the ACCEPT command: ACCEPT This will accept the given Z height and proceed with the given calibration tool. The exact amount of friction felt isn't crucial, just as the amount of thermal expansion and exact width of the paper isn't crucial. Just try to obtain the same amount of friction each time one runs the test. If something goes wrong during the test, one can use the ABORT command to exit the calibration tool.","title":"The \"paper test\""},{"location":"Bed_Level.html#determining-thermal-expansion","text":"After successfully performing bed leveling, one may go on to calculate a more precise value for the combined impact of \"thermal expansion\", \"thickness of the paper\", and \"amount of friction felt during the paper test\". This type of calculation is generally not needed as most users find the simple \"paper test\" provides good results. The easiest way to make this calculation is to print a test object that has straight walls on all sides. The large hollow square found in docs/prints/square.stl can be used for this. When slicing the object, make sure the slicer uses the same layer height and extrusion widths for the first level that it does for all subsequent layers. Use a coarse layer height (the layer height should be around 75% of the nozzle diameter) and do not use a brim or raft. Print the test object, wait for it to cool, and remove it from the bed. Inspect the lowest layer of the object. (It may also be useful to run a finger or nail along the bottom edge.) If one finds the bottom layer bulges out slightly along all sides of the object then it indicates the nozzle was slightly closer to the bed then it should be. One can issue a SET_GCODE_OFFSET Z=+.010 command to increase the height. In subsequent prints one can inspect for this behavior and make further adjustment as needed. Adjustments of this type are typically in 10s of microns (.010mm). If the bottom layer consistently appears narrower than subsequent layers then one can use the SET_GCODE_OFFSET command to make a negative Z adjustment. If one is unsure, then one can decrease the Z adjustment until the bottom layer of prints exhibit a small bulge, and then back-off until it disappears. The easiest way to apply the desired Z adjustment is to create a START_PRINT g-code macro, arrange for the slicer to call that macro during the start of each print, and add a SET_GCODE_OFFSET command to that macro. See the slicers document for further details.","title":"Determining Thermal Expansion"},{"location":"Bed_Mesh.html","text":"Bed Mesh \u00b6 The Bed Mesh module may be used to compensate for bed surface irregularities to achieve a better first layer across the entire bed. It should be noted that software based correction will not achieve perfect results, it can only approximate the shape of the bed. Bed Mesh also cannot compensate for mechanical and electrical issues. If an axis is skewed or a probe is not accurate then the bed_mesh module will not receive accurate results from the probing process. Prior to Mesh Calibration you will need to be sure that your Probe's Z-Offset is calibrated. If using an endstop for Z homing it will need to be calibrated as well. See Probe Calibrate and Z_ENDSTOP_CALIBRATE in Manual Level for more information. Basic Configuration \u00b6 Rectangular Beds \u00b6 This example assumes a printer with a 250 mm x 220 mm rectangular bed and a probe with an x-offset of 24 mm and y-offset of 5 mm. [bed_mesh] speed: 120 horizontal_move_z: 5 mesh_min: 35, 6 mesh_max: 240, 198 probe_count: 5, 3 speed: 120 Default Value: 50 The speed in which the tool moves between points. horizontal_move_z: 5 Default Value: 5 The Z coordinate the probe rises to prior to traveling between points. mesh_min: 35, 6 Required The first probed coordinate, nearest to the origin. This coordinate is relative to the probe's location. mesh_max: 240, 198 Required The probed coordinate farthest from the origin. This is not necessarily the last point probed, as the probing process occurs in a zig-zag fashion. As with mesh_min , this coordinate is relative to the probe's location. probe_count: 5, 3 Default Value: 3, 3 The number of points to probe on each axis, specified as X, Y integer values. In this example 5 points will be probed along the X axis, with 3 points along the Y axis, for a total of 15 probed points. Note that if you wanted a square grid, for example 3x3, this could be specified as a single integer value that is used for both axes, ie probe_count: 3 . Note that a mesh requires a minimum probe_count of 3 along each axis. The illustration below demonstrates how the mesh_min , mesh_max , and probe_count options are used to generate probe points. The arrows indicate the direction of the probing procedure, beginning at mesh_min . For reference, when the probe is at mesh_min the nozzle will be at (11, 1), and when the probe is at mesh_max , the nozzle will be at (206, 193). Round beds \u00b6 This example assumes a printer equipped with a round bed radius of 100mm. We will use the same probe offsets as the rectangular example, 24 mm on X and 5 mm on Y. [bed_mesh] speed: 120 horizontal_move_z: 5 mesh_radius: 75 mesh_origin: 0, 0 round_probe_count: 5 mesh_radius: 75 Required The radius of the probed mesh in mm, relative to the mesh_origin . Note that the probe's offsets limit the size of the mesh radius. In this example, a radius larger than 76 would move the tool beyond the range of the printer. mesh_origin: 0, 0 Default Value: 0, 0 The center point of the mesh. This coordinate is relative to the probe's location. While the default is 0, 0, it may be useful to adjust the origin in an effort to probe a larger portion of the bed. See the illustration below. round_probe_count: 5 Default Value: 5 This is an integer value that defines the maximum number of probed points along the X and Y axes. By \"maximum\", we mean the number of points probed along the mesh origin. This value must be an odd number, as it is required that the center of the mesh is probed. The illustration below shows how the probed points are generated. As you can see, setting the mesh_origin to (-10, 0) allows us to specify a larger mesh radius of 85. Advanced Configuration \u00b6 Below the more advanced configuration options are explained in detail. Each example will build upon the basic rectangular bed configuration shown above. Each of the advanced options apply to round beds in the same manner. Mesh Interpolation \u00b6 While its possible to sample the probed matrix directly using simple bi-linear interpolation to determine the Z-Values between probed points, it is often useful to interpolate extra points using more advanced interpolation algorithms to increase mesh density. These algorithms add curvature to the mesh, attempting to simulate the material properties of the bed. Bed Mesh offers lagrange and bicubic interpolation to accomplish this. [bed_mesh] speed: 120 horizontal_move_z: 5 mesh_min: 35, 6 mesh_max: 240, 198 probe_count: 5, 3 mesh_pps: 2, 3 algorithm: bicubic bicubic_tension: 0.2 mesh_pps: 2, 3 Default Value: 2, 2 The mesh_pps option is shorthand for Mesh Points Per Segment. This option specifies how many points to interpolate for each segment along the X and Y axes. Consider a 'segment' to be the space between each probed point. Like probe_count , mesh_pps is specified as an X, Y integer pair, and also may be specified a single integer that is applied to both axes. In this example there are 4 segments along the X axis and 2 segments along the Y axis. This evaluates to 8 interpolated points along X, 6 interpolated points along Y, which results in a 13x9 mesh. Note that if mesh_pps is set to 0 then mesh interpolation is disabled and the probed matrix will be sampled directly. algorithm: lagrange Default Value: lagrange The algorithm used to interpolate the mesh. May be lagrange or bicubic . Lagrange interpolation is capped at 6 probed points as oscillation tends to occur with a larger number of samples. Bicubic interpolation requires a minimum of 4 probed points along each axis, if less than 4 points are specified then lagrange sampling is forced. If mesh_pps is set to 0 then this value is ignored as no mesh interpolation is done. bicubic_tension: 0.2 Default Value: 0.2 If the algorithm option is set to bicubic it is possible to specify the tension value. The higher the tension the more slope is interpolated. Be careful when adjusting this, as higher values also create more overshoot, which will result in interpolated values higher or lower than your probed points. The illustration below shows how the options above are used to generate an interpolated mesh. Move Splitting \u00b6 Bed Mesh works by intercepting gcode move commands and applying a transform to their Z coordinate. Long moves must be split into smaller moves to correctly follow the shape of the bed. The options below control the splitting behavior. [bed_mesh] speed: 120 horizontal_move_z: 5 mesh_min: 35, 6 mesh_max: 240, 198 probe_count: 5, 3 move_check_distance: 5 split_delta_z: .025 move_check_distance: 5 Default Value: 5 The minimum distance to check for the desired change in Z before performing a split. In this example, a move longer than 5mm will be traversed by the algorithm. Each 5mm a mesh Z lookup will occur, comparing it with the Z value of the previous move. If the delta meets the threshold set by split_delta_z , the move will be split and traversal will continue. This process repeats until the end of the move is reached, where a final adjustment will be applied. Moves shorter than the move_check_distance have the correct Z adjustment applied directly to the move without traversal or splitting. split_delta_z: .025 Default Value: .025 As mentioned above, this is the minimum deviation required to trigger a move split. In this example, any Z value with a deviation +/- .025mm will trigger a split. Generally the default values for these options are sufficient, in fact the default value of 5mm for the move_check_distance may be overkill. However an advanced user may wish to experiment with these options in an effort to squeeze out the optimal first layer. Mesh Fade \u00b6 When \"fade\" is enabled Z adjustment is phased out over a distance defined by the configuration. This is accomplished by applying small adjustments to the layer height, either increasing or decreasing depending on the shape of the bed. When fade has completed, Z adjustment is no longer applied, allowing the top of the print to be flat rather than mirror the shape of the bed. Fade also may have some undesirable traits, if you fade too quickly it can result in visible artifacts on the print. Also, if your bed is significantly warped, fade can shrink or stretch the Z height of the print. As such, fade is disabled by default. [bed_mesh] speed: 120 horizontal_move_z: 5 mesh_min: 35, 6 mesh_max: 240, 198 probe_count: 5, 3 fade_start: 1 fade_end: 10 fade_target: 0 fade_start: 1 Default Value: 1 The Z height in which to start phasing out adjustment. It is a good idea to get a few layers down before starting the fade process. fade_end: 10 Default Value: 0 The Z height in which fade should complete. If this value is lower than fade_start then fade is disabled. This value may be adjusted depending on how warped the print surface is. A significantly warped surface should fade out over a longer distance. A near flat surface may be able to reduce this value to phase out more quickly. 10mm is a sane value to begin with if using the default value of 1 for fade_start . fade_target: 0 Default Value: The average Z value of the mesh The fade_target can be thought of as an additional Z offset applied to the entire bed after fade completes. Generally speaking we would like this value to be 0, however there are circumstances where it should not be. For example, lets assume your homing position on the bed is an outlier, its .2 mm lower than the average probed height of the bed. If the fade_target is 0, fade will shrink the print by an average of .2 mm across the bed. By setting the fade_target to .2, the homed area will expand by .2 mm, however, the rest of the bed will be accurately sized. Generally its a good idea to leave fade_target out of the configuration so the average height of the mesh is used, however it may be desirable to manually adjust the fade target if one wants to print on a specific portion of the bed. Configuring the zero reference position \u00b6 Many probes are susceptible to \"drift\", ie: inaccuracies in probing introduced by heat or interference. This can make calculating the probe's z-offset challenging, particularly at different bed temperatures. As such, some printers use an endstop for homing the Z axis and a probe for calibrating the mesh. In this configuration it is possible offset the mesh so that the (X, Y) reference position applies zero adjustment. The reference position should be the location on the bed where a Z_ENDSTOP_CALIBRATE paper test is performed. The bed_mesh module provides the zero_reference_position option for specifying this coordinate: [bed_mesh] speed: 120 horizontal_move_z: 5 mesh_min: 35, 6 mesh_max: 240, 198 zero_reference_position: 125, 110 probe_count: 5, 3 zero_reference_position: Default Value: None (disabled) The zero_reference_position expects an (X, Y) coordinate matching that of the reference position described above. If the coordinate lies within the mesh then the mesh will be offset so the reference position applies zero adjustment. If the coordinate lies outside of the mesh then the coordinate will be probed after calibration, with the resulting z-value used as the z-offset. Note that this coordinate must NOT be in a location specified as a faulty_region if a probe is necessary. Faulty Regions \u00b6 It is possible for some areas of a bed to report inaccurate results when probing due to a \"fault\" at specific locations. The best example of this are beds with series of integrated magnets used to retain removable steel sheets. The magnetic field at and around these magnets may cause an inductive probe to trigger at a distance higher or lower than it would otherwise, resulting in a mesh that does not accurately represent the surface at these locations. Note: This should not be confused with probe location bias, which produces inaccurate results across the entire bed. The faulty_region options may be configured to compensate for this affect. If a generated point lies within a faulty region bed mesh will attempt to probe up to 4 points at the boundaries of this region. These probed values will be averaged and inserted in the mesh as the Z value at the generated (X, Y) coordinate. [bed_mesh] speed: 120 horizontal_move_z: 5 mesh_min: 35, 6 mesh_max: 240, 198 probe_count: 5, 3 faulty_region_1_min: 130.0, 0.0 faulty_region_1_max: 145.0, 40.0 faulty_region_2_min: 225.0, 0.0 faulty_region_2_max: 250.0, 25.0 faulty_region_3_min: 165.0, 95.0 faulty_region_3_max: 205.0, 110.0 faulty_region_4_min: 30.0, 170.0 faulty_region_4_max: 45.0, 210.0 faulty_region_{1...99}_min faulty_region_{1..99}_max Default Value: None (disabled) Faulty Regions are defined in a way similar to that of mesh itself, where minimum and maximum (X, Y) coordinates must be specified for each region. A faulty region may extend outside of a mesh, however the alternate points generated will always be within the mesh boundary. No two regions may overlap. The image below illustrates how replacement points are generated when a generated point lies within a faulty region. The regions shown match those in the sample config above. The replacement points and their coordinates are identified in green. Adaptive Meshes \u00b6 Adaptive bed meshing is a way to speed up the bed mesh generation by only probing the area of the bed used by the objects being printed. When used, the method will automatically adjust the mesh parameters based on the area occupied by the defined print objects. The adapted mesh area will be computed from the area defined by the boundaries of all the defined print objects so it covers every object, including any margins defined in the configuration. After the area is computed, the number of probe points will be scaled down based on the ratio of the default mesh area and the adapted mesh area. To illustrate this consider the following example: For a 150mmx150mm bed with mesh_min set to 25,25 and mesh_max set to 125,125 , the default mesh area is a 100mmx100mm square. An adapted mesh area of 50,50 means a ratio of 0.5x0.5 between the adapted area and default mesh area. If the bed_mesh configuration specified probe_count as 7x7 , the adapted bed mesh will use 4x4 probe points (7 * 0.5 rounded up). [bed_mesh] speed: 120 horizontal_move_z: 5 mesh_min: 35, 6 mesh_max: 240, 198 probe_count: 5, 3 adaptive_margin: 5 adaptive_margin Default Value: 0 Margin (in mm) to add around the area of the bed used by the defined objects. The diagram below shows the adapted bed mesh area with an adaptive_margin of 5mm. The adapted mesh area (area in green) is computed as the used bed area (area in blue) plus the defined margin. By nature, adaptive bed meshes use the objects defined by the Gcode file being printed. Therefore, it is expected that each Gcode file will generate a mesh that probes a different area of the print bed. Therefore, adapted bed meshes should not be re-used. The expectation is that a new mesh will be generated for each print if adaptive meshing is used. It is also important to consider that adaptive bed meshing is best used on machines that can normally probe the entire bed and achieve a maximum variance less than or equal to 1 layer height. Machines with mechanical issues that a full bed mesh normally compensates for may have undesirable results when attempting print moves outside of the probed area. If a full bed mesh has a variance greater than 1 layer height, caution must be taken when using adaptive bed meshes and attempting print moves outside of the meshed area. Surface Scans \u00b6 Some probes, such as the Eddy Current Probe , are capable of \"scanning\" the surface of the bed. That is, these probes can sample a mesh without lifting the tool between samples. To activate scanning mode, the METHOD=scan or METHOD=rapid_scan probe parameter should be passed in the BED_MESH_CALIBRATE gcode command. Scan Height \u00b6 The scan height is set by the horizontal_move_z option in [bed_mesh] . In addition it can be supplied with the BED_MESH_CALIBRATE gcode command via the HORIZONTAL_MOVE_Z parameter. The scan height must be sufficiently low to avoid scanning errors. Typically a height of 2mm (ie: HORIZONTAL_MOVE_Z=2 ) should work well, presuming that the probe is mounted correctly. It should be noted that if the probe is more than 4mm above the surface then the results will be invalid. Thus, scanning is not possible on beds with severe surface deviation or beds with extreme tilt that hasn't been corrected. Rapid (Continuous) Scanning \u00b6 When performing a rapid_scan one should keep in mind that the results will have some amount of error. This error should be low enough to be useful on large print areas with reasonably thick layer heights. Some probes may be more prone to error than others. It is not recommended that rapid mode be used to scan a \"dense\" mesh. Some of the error introduced during a rapid scan may be gaussian noise from the sensor, and a dense mesh will reflect this noise (ie: there will be peaks and valleys). Bed Mesh will attempt to optimize the travel path to provide the best possible result based on the configuration. This includes avoiding faulty regions when collecting samples and \"overshooting\" the mesh when changing direction. This overshoot improves sampling at the edges of a mesh, however it requires that the mesh be configured in a way that allows the tool to travel outside of the mesh. [bed_mesh] speed: 120 horizontal_move_z: 5 mesh_min: 35, 6 mesh_max: 240, 198 probe_count: 5 scan_overshoot: 8 scan_overshoot Default Value: 0 (disabled) The maximum amount of travel (in mm) available outside of the mesh. For rectangular beds this applies to travel on the X axis, and for round beds it applies to the entire radius. The tool must be able to travel the amount specified outside of the mesh. This value is used to optimize the travel path when performing a \"rapid scan\". The minimum value that may be specified is 1. The default is no overshoot. If no scan overshoot is configured then travel path optimization will not be applied to changes in direction. Bed Mesh Gcodes \u00b6 Calibration \u00b6 BED_MESH_CALIBRATE PROFILE= METHOD=[manual | automatic | scan | rapid_scan] =] [=] [ADAPTIVE=[0|1] ] Default Profile: default Default Method: automatic if a probe is detected, otherwise manual Default Adaptive: 0 Default Adaptive Margin: 0 Initiates the probing procedure for Bed Mesh Calibration. The mesh will be immediately ready to use when the command completes and saved into a profile specified by the PROFILE parameter, or default if unspecified. The METHOD parameter takes one of the following values: METHOD=manual : enables manual probing using the nozzle and the paper test METHOD=automatic : Automatic (standard) probing. This is the default. METHOD=scan : Enables surface scanning. The tool will pause over each position to collect a sample. METHOD=rapid_scan : Enables continuous surface scanning. XY positions are automatically adjusted to include the X and/or Y offsets when a probing method other than manual is selected. It is possible to specify mesh parameters to modify the probed area. The following parameters are available: Rectangular beds (cartesian): MESH_MIN MESH_MAX PROBE_COUNT Round beds (delta): MESH_RADIUS MESH_ORIGIN ROUND_PROBE_COUNT All beds: MESH_PPS ALGORITHM ADAPTIVE ADAPTIVE_MARGIN See the configuration documentation above for details on how each parameter applies to the mesh. Profiles \u00b6 BED_MESH_PROFILE SAVE= LOAD= REMOVE= 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= the SAVE_CONFIG gcode may be executed to write the profile to printer.cfg. Profiles can be loaded by executing BED_MESH_PROFILE LOAD= . It should be noted that each time a BED_MESH_CALIBRATE occurs, the current state is automatically saved to the default profile. The default profile can be removed as follows: BED_MESH_PROFILE REMOVE=default Any other saved profile can be removed in the same fashion, replacing default with the named profile you wish to remove. Loading the default profile \u00b6 Previous versions of bed_mesh always loaded the profile named default on startup if it was present. This behavior has been removed in favor of allowing the user to determine when a profile is loaded. If a user wishes to load the default profile it is recommended to add BED_MESH_PROFILE LOAD=default to either their START_PRINT macro or their slicer's \"Start G-Code\" configuration, whichever is applicable. Note that this is not required if a new mesh is generated with BED_MESH_CALIBRATE in the START_PRINT macro or the slicer's \"Start G-Code\" and may produce unexpected results, especially with adaptive meshing. Alternatively the old behavior of loading a profile at startup can be restored with a [delayed_gcode] : [delayed_gcode bed_mesh_init] initial_duration : .01 gcode : BED_MESH_PROFILE LOAD = default Output \u00b6 BED_MESH_OUTPUT PGP=[0 | 1] Outputs the current mesh state to the terminal. Note that the mesh itself is output The PGP parameter is shorthand for \"Print Generated Points\". If PGP=1 is set, the generated probed points will be output to the terminal: // bed_mesh: generated points // Index | Tool Adjusted | Probe // 0 | (11.0, 1.0) | (35.0, 6.0) // 1 | (62.2, 1.0) | (86.2, 6.0) // 2 | (113.5, 1.0) | (137.5, 6.0) // 3 | (164.8, 1.0) | (188.8, 6.0) // 4 | (216.0, 1.0) | (240.0, 6.0) // 5 | (216.0, 97.0) | (240.0, 102.0) // 6 | (164.8, 97.0) | (188.8, 102.0) // 7 | (113.5, 97.0) | (137.5, 102.0) // 8 | (62.2, 97.0) | (86.2, 102.0) // 9 | (11.0, 97.0) | (35.0, 102.0) // 10 | (11.0, 193.0) | (35.0, 198.0) // 11 | (62.2, 193.0) | (86.2, 198.0) // 12 | (113.5, 193.0) | (137.5, 198.0) // 13 | (164.8, 193.0) | (188.8, 198.0) // 14 | (216.0, 193.0) | (240.0, 198.0) The \"Tool Adjusted\" points refer to the nozzle location for each point, and the \"Probe\" points refer to the probe location. Note that when manually probing the \"Probe\" points will refer to both the tool and nozzle locations. Clear Mesh State \u00b6 BED_MESH_CLEAR This gcode may be used to clear the internal mesh state. Apply X/Y offsets \u00b6 BED_MESH_OFFSET [X=] [Y=] [ZFADE=] This is useful for printers with multiple independent extruders, as an offset is necessary to produce correct Z adjustment after a tool change. Offsets should be specified relative to the primary extruder. That is, a positive X offset should be specified if the secondary extruder is mounted to the right of the primary extruder, a positive Y offset should be specified if the secondary extruder is mounted \"behind\" the primary extruder, and a positive ZFADE offset should be specified if the secondary extruder's nozzle is above the primary extruder's. Note that a ZFADE offset does NOT directly apply additional adjustment. It is intended to compensate for a gcode offset when mesh fade is enabled. For example, if a secondary extruder is higher than the primary and needs a negative gcode offset, ie: SET_GCODE_OFFSET Z=-.2 , it can be accounted for in bed_mesh with BED_MESH_OFFSET ZFADE=.2 . Bed Mesh Webhooks APIs \u00b6 Dumping mesh data \u00b6 {\"id\": 123, \"method\": \"bed_mesh/dump_mesh\"} Dumps the configuration and state for the current mesh and all saved profiles. The dump_mesh endpoint takes one optional parameter, mesh_args . This parameter must be an object, where the keys and values are parameters available to BED_MESH_CALIBRATE . This will update the mesh configuration and probe points using the supplied parameters prior to returning the result. It is recommended to omit mesh parameters unless it is desired to visualize the probe points and/or travel path before performing BED_MESH_CALIBRATE . Visualization and analysis \u00b6 Most users will likely find that the visualizers included with applications such as Mainsail, Fluidd, and Octoprint are sufficient for basic analysis. However, Klipper's scripts folder contains the graph_mesh.py script that may be used to perform additional visualizations and more detailed analysis, particularly useful for debugging hardware or the results produced by bed_mesh : usage: graph_mesh.py [-h] {list,plot,analyze,dump} ... Graph Bed Mesh Data positional arguments: {list,plot,analyze,dump} list List available plot types plot Plot a specified type analyze Perform analysis on mesh data dump Dump API response to json file options: -h, --help show this help message and exit Pre-requisites \u00b6 Like most graphing tools provided by Klipper, graph_mesh.py requires the matplotlib and numpy python dependencies. In addition, connecting to Klipper via Moonraker's websocket requires the websockets python dependency. While all visualizations can be output to an svg file, most of the visualizations offered by graph_mesh.py are better viewed in live preview mode on a desktop class PC. For example, the 3D visualizations may be rotated and zoomed in preview mode, and the path visualizations can optionally be animated in preview mode. Plotting Mesh data \u00b6 The graph_mesh.py tool can plot several types of visualizations. Available types can be shown by running graph_mesh.py list : graph_mesh.py list points Plot original generated points path Plot probe travel path rapid Plot rapid scan travel path probedz Plot probed Z values meshz Plot mesh Z values overlay Plots the current probed mesh overlaid with a profile delta Plots the delta between current probed mesh and a profile Several options are available when plotting visualizations: usage: graph_mesh.py plot [-h] [-a] [-s] [-p PROFILE_NAME] [-o OUTPUT] Type of data to graph METHOD=[manual | automatic | scan | rapid_scan] =] [=] [ADAPTIVE=[0|1] ] Default Profile: default Default Method: automatic if a probe is detected, otherwise manual Default Adaptive: 0 Default Adaptive Margin: 0 Initiates the probing procedure for Bed Mesh Calibration. The mesh will be immediately ready to use when the command completes and saved into a profile specified by the PROFILE parameter, or default if unspecified. The METHOD parameter takes one of the following values: METHOD=manual : enables manual probing using the nozzle and the paper test METHOD=automatic : Automatic (standard) probing. This is the default. METHOD=scan : Enables surface scanning. The tool will pause over each position to collect a sample. METHOD=rapid_scan : Enables continuous surface scanning. XY positions are automatically adjusted to include the X and/or Y offsets when a probing method other than manual is selected. It is possible to specify mesh parameters to modify the probed area. The following parameters are available: Rectangular beds (cartesian): MESH_MIN MESH_MAX PROBE_COUNT Round beds (delta): MESH_RADIUS MESH_ORIGIN ROUND_PROBE_COUNT All beds: MESH_PPS ALGORITHM ADAPTIVE ADAPTIVE_MARGIN See the configuration documentation above for details on how each parameter applies to the mesh.","title":"Calibration"},{"location":"Bed_Mesh.html#profiles","text":"BED_MESH_PROFILE SAVE= LOAD= REMOVE= 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= the SAVE_CONFIG gcode may be executed to write the profile to printer.cfg. Profiles can be loaded by executing BED_MESH_PROFILE LOAD= . It should be noted that each time a BED_MESH_CALIBRATE occurs, the current state is automatically saved to the default profile. The default profile can be removed as follows: BED_MESH_PROFILE REMOVE=default Any other saved profile can be removed in the same fashion, replacing default with the named profile you wish to remove.","title":"Profiles"},{"location":"Bed_Mesh.html#loading-the-default-profile","text":"Previous versions of bed_mesh always loaded the profile named default on startup if it was present. This behavior has been removed in favor of allowing the user to determine when a profile is loaded. If a user wishes to load the default profile it is recommended to add BED_MESH_PROFILE LOAD=default to either their START_PRINT macro or their slicer's \"Start G-Code\" configuration, whichever is applicable. Note that this is not required if a new mesh is generated with BED_MESH_CALIBRATE in the START_PRINT macro or the slicer's \"Start G-Code\" and may produce unexpected results, especially with adaptive meshing. Alternatively the old behavior of loading a profile at startup can be restored with a [delayed_gcode] : [delayed_gcode bed_mesh_init] initial_duration : .01 gcode : BED_MESH_PROFILE LOAD = default","title":"Loading the default profile"},{"location":"Bed_Mesh.html#output","text":"BED_MESH_OUTPUT PGP=[0 | 1] Outputs the current mesh state to the terminal. Note that the mesh itself is output The PGP parameter is shorthand for \"Print Generated Points\". If PGP=1 is set, the generated probed points will be output to the terminal: // bed_mesh: generated points // Index | Tool Adjusted | Probe // 0 | (11.0, 1.0) | (35.0, 6.0) // 1 | (62.2, 1.0) | (86.2, 6.0) // 2 | (113.5, 1.0) | (137.5, 6.0) // 3 | (164.8, 1.0) | (188.8, 6.0) // 4 | (216.0, 1.0) | (240.0, 6.0) // 5 | (216.0, 97.0) | (240.0, 102.0) // 6 | (164.8, 97.0) | (188.8, 102.0) // 7 | (113.5, 97.0) | (137.5, 102.0) // 8 | (62.2, 97.0) | (86.2, 102.0) // 9 | (11.0, 97.0) | (35.0, 102.0) // 10 | (11.0, 193.0) | (35.0, 198.0) // 11 | (62.2, 193.0) | (86.2, 198.0) // 12 | (113.5, 193.0) | (137.5, 198.0) // 13 | (164.8, 193.0) | (188.8, 198.0) // 14 | (216.0, 193.0) | (240.0, 198.0) The \"Tool Adjusted\" points refer to the nozzle location for each point, and the \"Probe\" points refer to the probe location. Note that when manually probing the \"Probe\" points will refer to both the tool and nozzle locations.","title":"Output"},{"location":"Bed_Mesh.html#clear-mesh-state","text":"BED_MESH_CLEAR This gcode may be used to clear the internal mesh state.","title":"Clear Mesh State"},{"location":"Bed_Mesh.html#apply-xy-offsets","text":"BED_MESH_OFFSET [X=] [Y=] [ZFADE=] This is useful for printers with multiple independent extruders, as an offset is necessary to produce correct Z adjustment after a tool change. Offsets should be specified relative to the primary extruder. That is, a positive X offset should be specified if the secondary extruder is mounted to the right of the primary extruder, a positive Y offset should be specified if the secondary extruder is mounted \"behind\" the primary extruder, and a positive ZFADE offset should be specified if the secondary extruder's nozzle is above the primary extruder's. Note that a ZFADE offset does NOT directly apply additional adjustment. It is intended to compensate for a gcode offset when mesh fade is enabled. For example, if a secondary extruder is higher than the primary and needs a negative gcode offset, ie: SET_GCODE_OFFSET Z=-.2 , it can be accounted for in bed_mesh with BED_MESH_OFFSET ZFADE=.2 .","title":"Apply X/Y offsets"},{"location":"Bed_Mesh.html#bed-mesh-webhooks-apis","text":"","title":"Bed Mesh Webhooks APIs"},{"location":"Bed_Mesh.html#dumping-mesh-data","text":"{\"id\": 123, \"method\": \"bed_mesh/dump_mesh\"} Dumps the configuration and state for the current mesh and all saved profiles. The dump_mesh endpoint takes one optional parameter, mesh_args . This parameter must be an object, where the keys and values are parameters available to BED_MESH_CALIBRATE . This will update the mesh configuration and probe points using the supplied parameters prior to returning the result. It is recommended to omit mesh parameters unless it is desired to visualize the probe points and/or travel path before performing BED_MESH_CALIBRATE .","title":"Dumping mesh data"},{"location":"Bed_Mesh.html#visualization-and-analysis","text":"Most users will likely find that the visualizers included with applications such as Mainsail, Fluidd, and Octoprint are sufficient for basic analysis. However, Klipper's scripts folder contains the graph_mesh.py script that may be used to perform additional visualizations and more detailed analysis, particularly useful for debugging hardware or the results produced by bed_mesh : usage: graph_mesh.py [-h] {list,plot,analyze,dump} ... Graph Bed Mesh Data positional arguments: {list,plot,analyze,dump} list List available plot types plot Plot a specified type analyze Perform analysis on mesh data dump Dump API response to json file options: -h, --help show this help message and exit","title":"Visualization and analysis"},{"location":"Bed_Mesh.html#pre-requisites","text":"Like most graphing tools provided by Klipper, graph_mesh.py requires the matplotlib and numpy python dependencies. In addition, connecting to Klipper via Moonraker's websocket requires the websockets python dependency. While all visualizations can be output to an svg file, most of the visualizations offered by graph_mesh.py are better viewed in live preview mode on a desktop class PC. For example, the 3D visualizations may be rotated and zoomed in preview mode, and the path visualizations can optionally be animated in preview mode.","title":"Pre-requisites"},{"location":"Bed_Mesh.html#plotting-mesh-data","text":"The graph_mesh.py tool can plot several types of visualizations. Available types can be shown by running graph_mesh.py list : graph_mesh.py list points Plot original generated points path Plot probe travel path rapid Plot rapid scan travel path probedz Plot probed Z values meshz Plot mesh Z values overlay Plots the current probed mesh overlaid with a profile delta Plots the delta between current probed mesh and a profile Several options are available when plotting visualizations: usage: graph_mesh.py plot [-h] [-a] [-s] [-p PROFILE_NAME] [-o OUTPUT] Type of data to graph \")' Entering bootloader on Where 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 . Picocom \u00b6 picocom -b 1200 Where is your serial device, such as /dev/serial.by-id/usb-Klipper[...] or /dev/ttyACM0 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 Request Serial Bootloader!!~ requests the bootloader. is an ASCII literal space, 0x20. 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 < /dev/ echo $'~ \\x1c Request Serial Bootloader!! ~' >> /dev/ Where is your serial port, such as /dev/ttyS0 , or /dev/serial/by-id/gpio-serial2 , and is the baud rate of the serial port, such as 115200 . CANBUS \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 -u -r Where is the can interface to use. If using can0 , both the -i and may be omitted. is the UUID of your CAN device. See the CANBUS Documentation for information on finding the CAN UUID of your devices. Entering the bootloader \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(\"\")' Entering bootloader on Where 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 .","title":"Python (with flash_usb)"},{"location":"Bootloader_Entry.html#picocom","text":"picocom -b 1200 Where is your serial device, such as /dev/serial.by-id/usb-Klipper[...] or /dev/ttyACM0 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 Request Serial Bootloader!!~ requests the bootloader. is an ASCII literal space, 0x20. 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 < /dev/ echo $'~ \\x1c Request Serial Bootloader!! ~' >> /dev/ Where is your serial port, such as /dev/ttyS0 , or /dev/serial/by-id/gpio-serial2 , and is the baud rate of the serial port, such as 115200 .","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 -u -r Where is the can interface to use. If using can0 , both the -i and may be omitted. is the UUID of your CAN device. See the CANBUS Documentation for information on finding the CAN UUID of your devices.","title":"Katapult's flashtool.py"},{"location":"Bootloader_Entry.html#entering-the-bootloader","text":"When klipper receives one of the above bootloader requests: If Katapult (formerly known as CANBoot) is available, klipper will request that Katapult stay active on the next boot, then reset the MCU (therefore entering Katapult). If Katapult is not available, klipper will then try to enter a platform-specific bootloader, such as STM32's DFU mode( see note ). In short, Klipper will reboot to Katapult if installed, then a hardware specific bootloader if available. For details about the specific bootloaders on various platforms see Bootloaders","title":"Entering the bootloader"},{"location":"Bootloader_Entry.html#notes","text":"","title":"Notes"},{"location":"Bootloader_Entry.html#stm32-dfu-warning","text":"Note that on some boards, like the Octopus Pro v1, entering DFU mode can cause undesired actions (such as powering the heater while in DFU mode). It is recommended to disconnect heaters, and otherwise prevent undesired operations when using DFU mode. Consult the documentation for your board for more details.","title":"STM32 DFU Warning"},{"location":"Bootloaders.html","text":"Bootloaders \u00b6 This document provides information on common bootloaders found on micro-controllers that Klipper supports. The bootloader is 3rd-party software that runs on the micro-controller when it is first powered on. It is typically used to flash a new application (eg, Klipper) to the micro-controller without requiring specialized hardware. Unfortunately, there is no industry wide standard for flashing a micro-controller, nor is there a standard bootloader that works across all micro-controllers. Worse, it is common for each bootloader to require a different set of steps to flash an application. If one can flash a bootloader to a micro-controller then one can generally also use that mechanism to flash an application, but care should be taken when doing this as one may inadvertently remove the bootloader. In contrast, a bootloader will generally only permit a user to flash an application. It is therefore recommended to use a bootloader to flash an application where possible. This document attempts to describe common bootloaders, the steps needed to flash a bootloader, and the steps needed to flash an application. This document is not an authoritative reference; it is intended as a collection of useful information that the Klipper developers have accumulated. AVR micro-controllers \u00b6 In general, the Arduino project is a good reference for bootloaders and flashing procedures on the 8-bit Atmel Atmega micro-controllers. In particular, the \"boards.txt\" file: https://github.com/arduino/Arduino/blob/1.8.5/hardware/arduino/avr/boards.txt is a useful reference. To flash a bootloader itself, the AVR chips require an external hardware flashing tool (which communicates with the chip using SPI). This tool can be purchased (for example, do a web search for \"avr isp\", \"arduino isp\", or \"usb tiny isp\"). It is also possible to use another Arduino or Raspberry Pi to flash an AVR bootloader (for example, do a web search for \"program an avr using raspberry pi\"). The examples below are written assuming an \"AVR ISP Mk2\" type device is in use. The \"avrdude\" program is the most common tool used to flash atmega chips (both bootloader flashing and application flashing). Atmega2560 \u00b6 This chip is typically found in the \"Arduino Mega\" and is very common in 3d printer boards. To flash the bootloader itself use something like: wget 'https://github.com/arduino/Arduino/raw/1.8.5/hardware/arduino/avr/bootloaders/stk500v2/stk500boot_v2_mega2560.hex' avrdude -cavrispv2 -patmega2560 -P/dev/ttyACM0 -b115200 -e -u -U lock:w:0x3F:m -U efuse:w:0xFD:m -U hfuse:w:0xD8:m -U lfuse:w:0xFF:m avrdude -cavrispv2 -patmega2560 -P/dev/ttyACM0 -b115200 -U flash:w:stk500boot_v2_mega2560.hex avrdude -cavrispv2 -patmega2560 -P/dev/ttyACM0 -b115200 -U lock:w:0x0F:m To flash an application use something like: avrdude -cwiring -patmega2560 -P/dev/ttyACM0 -b115200 -D -Uflash:w:out/klipper.elf.hex:i Atmega1280 \u00b6 This chip is typically found in earlier versions of the \"Arduino Mega\". To flash the bootloader itself use something like: wget 'https://github.com/arduino/Arduino/raw/1.8.5/hardware/arduino/avr/bootloaders/atmega/ATmegaBOOT_168_atmega1280.hex' avrdude -cavrispv2 -patmega1280 -P/dev/ttyACM0 -b115200 -e -u -U lock:w:0x3F:m -U efuse:w:0xF5:m -U hfuse:w:0xDA:m -U lfuse:w:0xFF:m avrdude -cavrispv2 -patmega1280 -P/dev/ttyACM0 -b115200 -U flash:w:ATmegaBOOT_168_atmega1280.hex avrdude -cavrispv2 -patmega1280 -P/dev/ttyACM0 -b115200 -U lock:w:0x0F:m To flash an application use something like: avrdude -carduino -patmega1280 -P/dev/ttyACM0 -b57600 -D -Uflash:w:out/klipper.elf.hex:i Atmega1284p \u00b6 This chip is commonly found in \"Melzi\" style 3d printer boards. To flash the bootloader itself use something like: wget 'https://github.com/Lauszus/Sanguino/raw/1.0.2/bootloaders/optiboot/optiboot_atmega1284p.hex' avrdude -cavrispv2 -patmega1284p -P/dev/ttyACM0 -b115200 -e -u -U lock:w:0x3F:m -U efuse:w:0xFD:m -U hfuse:w:0xDE:m -U lfuse:w:0xFF:m avrdude -cavrispv2 -patmega1284p -P/dev/ttyACM0 -b115200 -U flash:w:optiboot_atmega1284p.hex avrdude -cavrispv2 -patmega1284p -P/dev/ttyACM0 -b115200 -U lock:w:0x0F:m To flash an application use something like: avrdude -carduino -patmega1284p -P/dev/ttyACM0 -b115200 -D -Uflash:w:out/klipper.elf.hex:i Note that a number of \"Melzi\" style boards come preloaded with a bootloader that uses a baud rate of 57600. In this case, to flash an application use something like this instead: avrdude -carduino -patmega1284p -P/dev/ttyACM0 -b57600 -D -Uflash:w:out/klipper.elf.hex:i At90usb1286 \u00b6 This document does not cover the method to flash a bootloader to the At90usb1286 nor does it cover general application flashing to this device. The Teensy++ device from pjrc.com comes with a proprietary bootloader. It requires a custom flashing tool from https://github.com/PaulStoffregen/teensy_loader_cli . One can flash an application with it using something like: teensy_loader_cli --mcu=at90usb1286 out/klipper.elf.hex -v Atmega168 \u00b6 The atmega168 has limited flash space. If using a bootloader, it is recommended to use the Optiboot bootloader. To flash that bootloader use something like: wget 'https://github.com/arduino/Arduino/raw/1.8.5/hardware/arduino/avr/bootloaders/optiboot/optiboot_atmega168.hex' avrdude -cavrispv2 -patmega168 -P/dev/ttyACM0 -b115200 -e -u -U lock:w:0x3F:m -U efuse:w:0x04:m -U hfuse:w:0xDD:m -U lfuse:w:0xFF:m avrdude -cavrispv2 -patmega168 -P/dev/ttyACM0 -b115200 -U flash:w:optiboot_atmega168.hex avrdude -cavrispv2 -patmega168 -P/dev/ttyACM0 -b115200 -U lock:w:0x0F:m To flash an application via the Optiboot bootloader use something like: avrdude -carduino -patmega168 -P/dev/ttyACM0 -b115200 -D -Uflash:w:out/klipper.elf.hex:i SAM3 micro-controllers (Arduino Due) \u00b6 It is not common to use a bootloader with the SAM3 mcu. The chip itself has a ROM that allows the flash to be programmed from 3.3V serial port or from USB. To enable the ROM, the \"erase\" pin is held high during a reset, which erases the flash contents, and causes the ROM to run. On an Arduino Due, this sequence can be accomplished by setting a baud rate of 1200 on the \"programming usb port\" (the USB port closest to the power supply). The code at https://github.com/shumatech/BOSSA can be used to program the SAM3. It is recommended to use version 1.9 or later. To flash an application use something like: bossac -U -p /dev/ttyACM0 -a -e -w out/klipper.bin -v -b bossac -U -p /dev/ttyACM0 -R SAM4 micro-controllers (Duet Wifi) \u00b6 It is not common to use a bootloader with the SAM4 mcu. The chip itself has a ROM that allows the flash to be programmed from 3.3V serial port or from USB. To enable the ROM, the \"erase\" pin is held high during a reset, which erases the flash contents, and causes the ROM to run. The code at https://github.com/shumatech/BOSSA can be used to program the SAM4. It is necessary to use version 1.8.0 or higher. To flash an application use something like: bossac --port=/dev/ttyACM0 -b -U -e -w -v -R out/klipper.bin SAMDC21 micro-controllers (Duet3D Toolboard 1LC) \u00b6 The SAMC21 is flashed via the ARM Serial Wire Debug (SWD) interface. This is commonly done with a dedicated SWD hardware dongle. Alternatively, one can use a Raspberry Pi with OpenOCD . When using OpenOCD with the SAMC21, extra steps must be taken to first put the chip into Cold Plugging mode if the board makes use of the SWD pins for other purposes. If using OpenOCD on a Raspberry Pi, this can be done by running the following commands before invoking OpenOCD. SWCLK=25 SWDIO=24 SRST=18 echo \"Exporting SWCLK and SRST pins.\" echo $SWCLK > /sys/class/gpio/export echo $SRST > /sys/class/gpio/export echo \"out\" > /sys/class/gpio/gpio$SWCLK/direction echo \"out\" > /sys/class/gpio/gpio$SRST/direction echo \"Setting SWCLK low and pulsing SRST.\" echo \"0\" > /sys/class/gpio/gpio$SWCLK/value echo \"0\" > /sys/class/gpio/gpio$SRST/value echo \"1\" > /sys/class/gpio/gpio$SRST/value echo \"Unexporting SWCLK and SRST pins.\" echo $SWCLK > /sys/class/gpio/unexport echo $SRST > /sys/class/gpio/unexport To flash a program with OpenOCD use the following chip config: source [find target/at91samdXX.cfg] Obtain a program; for instance, klipper can be built for this chip. Flash with OpenOCD commands similar to: at91samd chip-erase at91samd bootloader 0 program out/klipper.elf verify SAMD21 micro-controllers (Arduino Zero) \u00b6 The SAMD21 bootloader is flashed via the ARM Serial Wire Debug (SWD) interface. This is commonly done with a dedicated SWD hardware dongle. Alternatively, one can use a Raspberry Pi with OpenOCD . To flash a bootloader with OpenOCD use the following chip config: source [find target/at91samdXX.cfg] Obtain a bootloader - for example: wget 'https://github.com/arduino/ArduinoCore-samd/raw/1.8.3/bootloaders/zero/samd21_sam_ba.bin' Flash with OpenOCD commands similar to: at91samd bootloader 0 program samd21_sam_ba.bin verify The most common bootloader on the SAMD21 is the one found on the \"Arduino Zero\". It uses an 8KiB bootloader (the application must be compiled with a start address of 8KiB). One can enter this bootloader by double clicking the reset button. To flash an application use something like: bossac -U -p /dev/ttyACM0 --offset=0x2000 -w out/klipper.bin -v -b -R In contrast, the \"Arduino M0\" uses a 16KiB bootloader (the application must be compiled with a start address of 16KiB). To flash an application on this bootloader, reset the micro-controller and run the flash command within the first few seconds of boot - something like: avrdude -c stk500v2 -p atmega2560 -P /dev/ttyACM0 -u -Uflash:w:out/klipper.elf.hex:i SAMD51 micro-controllers (Adafruit Metro-M4 and similar) \u00b6 Like the SAMD21, the SAMD51 bootloader is flashed via the ARM Serial Wire Debug (SWD) interface. To flash a bootloader with OpenOCD on a Raspberry Pi use the following chip config: source [find target/atsame5x.cfg] Obtain a bootloader - several bootloaders are available from https://github.com/adafruit/uf2-samdx1/releases/latest . For example: wget 'https://github.com/adafruit/uf2-samdx1/releases/download/v3.7.0/bootloader-itsybitsy_m4-v3.7.0.bin' Flash with OpenOCD commands similar to: at91samd bootloader 0 program bootloader-itsybitsy_m4-v3.7.0.bin verify at91samd bootloader 16384 The SAMD51 uses a 16KiB bootloader (the application must be compiled with a start address of 16KiB). To flash an application use something like: bossac -U -p /dev/ttyACM0 --offset=0x4000 -w out/klipper.bin -v -b -R STM32F103 micro-controllers (Blue Pill devices) \u00b6 The STM32F103 devices have a ROM that can flash a bootloader or application via 3.3V serial. Typically one would wire the PA10 (MCU Rx) and PA9 (MCU Tx) pins to a 3.3V UART adapter. To access the ROM, one should connect the \"boot 0\" pin to high and \"boot 1\" pin to low, and then reset the device. The \"stm32flash\" package can then be used to flash the device using something like: stm32flash -w out/klipper.bin -v -g 0 /dev/ttyAMA0 Note that if one is using a Raspberry Pi for the 3.3V serial, the stm32flash protocol uses a serial parity mode which the Raspberry Pi's \"mini UART\" does not support. See https://www.raspberrypi.com/documentation/computers/configuration.html#configuring-uarts for details on enabling the full uart on the Raspberry Pi GPIO pins. After flashing, set both \"boot 0\" and \"boot 1\" back to low so that future resets boot from flash. STM32F103 with stm32duino bootloader \u00b6 The \"stm32duino\" project has a USB capable bootloader - see: https://github.com/rogerclarkmelbourne/STM32duino-bootloader This bootloader can be flashed via 3.3V serial with something like: wget 'https://github.com/rogerclarkmelbourne/STM32duino-bootloader/raw/master/binaries/generic_boot20_pc13.bin' stm32flash -w generic_boot20_pc13.bin -v -g 0 /dev/ttyAMA0 This bootloader uses 8KiB of flash space (the application must be compiled with a start address of 8KiB). Flash an application with something like: dfu-util -d 1eaf:0003 -a 2 -R -D out/klipper.bin The bootloader typically runs for only a short period after boot. It may be necessary to time the above command so that it runs while the bootloader is still active (the bootloader will flash a board led while it is running). Alternatively, set the \"boot 0\" pin to low and \"boot 1\" pin to high to stay in the bootloader after a reset. STM32F103 with HID bootloader \u00b6 The HID bootloader is a compact, driverless bootloader capable of flashing over USB. Also available is a fork with builds specific to the SKR Mini E3 1.2 . For generic STM32F103 boards such as the blue pill it is possible to flash the bootloader via 3.3V serial using stm32flash as noted in the stm32duino section above, substituting the file name for the desired hid bootloader binary (ie: hid_generic_pc13.bin for the blue pill). It is not possible to use stm32flash for the SKR Mini E3 as the boot0 pin is tied directly to ground and not broken out via header pins. It is recommended to use a STLink V2 with STM32Cubeprogrammer to flash the bootloader. If you don't have access to a STLink it is also possible to use a Raspberry Pi and OpenOCD with the following chip config: source [find target/stm32f1x.cfg] If you wish you can make a backup of the current flash with the following command. Note that it may take some time to complete: flash read_bank 0 btt_skr_mini_e3_backup.bin finally, you can flash with commands similar to: stm32f1x mass_erase 0 program hid_btt_skr_mini_e3.bin verify 0x08000000 NOTES: The example above erases the chip then programs the bootloader. Regardless of the method chosen to flash it is recommended to erase the chip prior to flashing. Prior flashing the SKR Mini E3 with this bootloader you should be aware that you will no longer be able to update firmware via the sdcard. You may need to hold down the reset button on the board while launching OpenOCD. It should display something like: Open On-Chip Debugger 0.10.0+dev-01204-gc60252ac-dirty (2020-04-27-16:00) Licensed under GNU GPL v2 For bug reports, read http://openocd.org/doc/doxygen/bugs.html DEPRECATED! use 'adapter speed' not 'adapter_khz' Info : BCM2835 GPIO JTAG/SWD bitbang driver Info : JTAG and SWD modes enabled Info : clock speed 40 kHz Info : SWD DPIDR 0x1ba01477 Info : stm32f1x.cpu: hardware has 6 breakpoints, 4 watchpoints Info : stm32f1x.cpu: external reset detected Info : starting gdb server for stm32f1x.cpu on 3333 Info : Listening on port 3333 for gdb connections After which you can release the reset button. This bootloader requires 2KiB of flash space (the application must be compiled with a start address of 2KiB). The hid-flash program is used to upload a binary to the bootloader. You can install this software with the following commands: sudo apt install libusb-1.0 cd ~/klipper/lib/hidflash make If the bootloader is running you can flash with something like: ~/klipper/lib/hidflash/hid-flash ~/klipper/out/klipper.bin alternatively, you can use make flash to flash klipper directly: make flash FLASH_DEVICE=1209:BEBA OR if klipper has been previously flashed: make flash FLASH_DEVICE=/dev/ttyACM0 It may be necessary to manually enter the bootloader, this can be done by setting \"boot 0\" low and \"boot 1\" high. On the SKR Mini E3 \"Boot 1\" is not available, so it may be done by setting pin PA2 low if you flashed \"hid_btt_skr_mini_e3.bin\". This pin is labeled \"TX0\" on the TFT header in the SKR Mini E3's \"PIN\" document. There is a ground pin next to PA2 which you can use to pull PA2 low. STM32F103/STM32F072 with MSC bootloader \u00b6 The MSC bootloader is a driverless bootloader capable of flashing over USB. It is possible to flash the bootloader via 3.3V serial using stm32flash as noted in the stm32duino section above, substituting the file name for the desired MSC bootloader binary (ie: MSCboot-Bluepill.bin for the blue pill). For STM32F072 boards it is also possible to flash the bootloader over USB (via DFU) with something like: dfu-util -d 0483:df11 -a 0 -R -D MSCboot-STM32F072.bin -s0x08000000:leave This bootloader uses 8KiB or 16KiB of flash space, see description of the bootloader (the application must be compiled with with the corresponding starting address). The bootloader can be activated by pressing the reset button of the board twice. As soon as the bootloader is activated, the board appears as a USB flash drive onto which the klipper.bin file can be copied. STM32F103/STM32F0x2 with CanBoot bootloader \u00b6 The CanBoot bootloader provides an option for uploading Klipper firmware over the CANBUS. The bootloader itself is derived from Klipper's source code. Currently CanBoot supports the STM32F103, STM32F042, and STM32F072 models. It is recommended to use a ST-Link Programmer to flash CanBoot, however it should be possible to flash using stm32flash on STM32F103 devices, and dfu-util on STM32F042/STM32F072 devices. See the previous sections in this document for instructions on these flashing methods, substituting canboot.bin for the file name where appropriate. The CanBoot repository linked above provides instructions for building the bootloader. The first time CanBoot has been flashed it should detect that no application is present and enter the bootloader. If this doesn't occur it is possible to enter the bootloader by pressing the reset button twice in succession. The flash_can.py utility supplied in the lib/canboot folder may be used to upload Klipper firmware. The device UUID is necessary to flash. If you do not have a UUID it is possible to query nodes currently running the bootloader: python3 flash_can.py -q This will return UUIDs for all connected nodes not currently assigned a UUID. This should include all nodes currently in the bootloader. Once you have a UUID, you may upload firmware with following command: python3 flash_can.py -i can0 -f ~/klipper/out/klipper.bin -u aabbccddeeff Where aabbccddeeff is replaced by your UUID. Note that the -i and -f options may be omitted, they default to can0 and ~/klipper/out/klipper.bin respectively. When building Klipper for use with CanBoot, select the 8 KiB Bootloader option. STM32F4 micro-controllers (SKR Pro 1.1) \u00b6 STM32F4 micro-controllers come equipped with a built-in system bootloader capable of flashing over USB (via DFU), 3.3V Serial, and various other methods (see STM Document AN2606 for more information). Some STM32F4 boards, such as the SKR Pro 1.1, are not able to enter the DFU bootloader. The HID bootloader is available for STM32F405/407 based boards should the user prefer flashing over USB over using the sdcard. Note that you may need to configure and build a version specific to your board, a build for the SKR Pro 1.1 is available here . Unless your board is DFU capable the most accessible flashing method is likely via 3.3V serial, which follows the same procedure as flashing the STM32F103 using stm32flash . For example: wget https://github.com/Arksine/STM32_HID_Bootloader/releases/download/v0.5-beta/hid_bootloader_SKR_PRO.bin stm32flash -w hid_bootloader_SKR_PRO.bin -v -g 0 /dev/ttyAMA0 This bootloader requires 16Kib of flash space on the STM32F4 (the application must be compiled with a start address of 16KiB). As with the STM32F1, the STM32F4 uses the hid-flash tool to upload binaries to the MCU. See the instructions above for details on how to build and use hid-flash. It may be necessary to manually enter the bootloader, this can be done by setting \"boot 0\" low, \"boot 1\" high and plugging in the device. After programming is complete unplug the device and set \"boot 1\" back to low so the application will be loaded. LPC176x micro-controllers (Smoothieboards) \u00b6 This document does not describe the method to flash a bootloader itself - see: http://smoothieware.org/flashing-the-bootloader for further information on that topic. It is common for Smoothieboards to come with a bootloader from: https://github.com/triffid/LPC17xx-DFU-Bootloader . When using this bootloader the application must be compiled with a start address of 16KiB. The easiest way to flash an application with this bootloader is to copy the application file (eg, out/klipper.bin ) to a file named firmware.bin on an SD card, and then to reboot the micro-controller with that SD card. Running OpenOCD on the Raspberry PI \u00b6 OpenOCD is a software package that can perform low-level chip flashing and debugging. It can use the GPIO pins on a Raspberry Pi to communicate with a variety of ARM chips. This section describes how one can install and launch OpenOCD. It is derived from the instructions at: https://learn.adafruit.com/programming-microcontrollers-using-openocd-on-raspberry-pi Begin by downloading and compiling the software (each step may take several minutes and the \"make\" step may take 30+ minutes): sudo apt-get update sudo apt-get install autoconf libtool telnet mkdir ~/openocd cd ~/openocd/ git clone http://openocd.zylin.com/openocd cd openocd ./bootstrap ./configure --enable-sysfsgpio --enable-bcm2835gpio --prefix=/home/pi/openocd/install make make install Configure OpenOCD \u00b6 Create an OpenOCD config file: nano ~/openocd/openocd.cfg Use a config similar to the following: # Uses RPi pins: GPIO25 for SWDCLK, GPIO24 for SWDIO, GPIO18 for nRST source [find interface/raspberrypi2-native.cfg] bcm2835gpio_swd_nums 25 24 bcm2835gpio_srst_num 18 transport select swd # Use hardware reset wire for chip resets reset_config srst_only adapter_nsrst_delay 100 adapter_nsrst_assert_width 100 # Specify the chip type source [find target/atsame5x.cfg] # Set the adapter speed adapter_khz 40 # Connect to chip init targets reset halt Wire the Raspberry Pi to the target chip \u00b6 Poweroff both the the Raspberry Pi and the target chip before wiring! Verify the target chip uses 3.3V prior to connecting to a Raspberry Pi! Connect GND, SWDCLK, SWDIO, and RST on the target chip to GND, GPIO25, GPIO24, and GPIO18 respectively on the Raspberry Pi. Then power up the Raspberry Pi and provide power to the target chip. Run OpenOCD \u00b6 Run OpenOCD: cd ~/openocd/ sudo ~/openocd/install/bin/openocd -f ~/openocd/openocd.cfg The above should cause OpenOCD to emit some text messages and then wait (it should not immediately return to the Unix shell prompt). If OpenOCD exits on its own or if it continues to emit text messages then double check the wiring. Once OpenOCD is running and is stable, one can send it commands via telnet. Open another ssh session and run the following: telnet 127.0.0.1 4444 (One can exit telnet by pressing ctrl+] and then running the \"quit\" command.) OpenOCD and gdb \u00b6 It is possible to use OpenOCD with gdb to debug Klipper. The following commands assume one is running gdb on a desktop class machine. Add the following to the OpenOCD config file: bindto 0.0.0.0 gdb_port 44444 Restart OpenOCD on the Raspberry Pi and then run the following Unix command on the desktop machine: cd /path/to/klipper/ gdb out/klipper.elf Within gdb run: target remote octopi:44444 (Replace \"octopi\" with the host name of the Raspberry Pi.) Once gdb is running it is possible to set breakpoints and to inspect registers.","title":"Bootloaders"},{"location":"Bootloaders.html#bootloaders","text":"This document provides information on common bootloaders found on micro-controllers that Klipper supports. The bootloader is 3rd-party software that runs on the micro-controller when it is first powered on. It is typically used to flash a new application (eg, Klipper) to the micro-controller without requiring specialized hardware. Unfortunately, there is no industry wide standard for flashing a micro-controller, nor is there a standard bootloader that works across all micro-controllers. Worse, it is common for each bootloader to require a different set of steps to flash an application. If one can flash a bootloader to a micro-controller then one can generally also use that mechanism to flash an application, but care should be taken when doing this as one may inadvertently remove the bootloader. In contrast, a bootloader will generally only permit a user to flash an application. It is therefore recommended to use a bootloader to flash an application where possible. This document attempts to describe common bootloaders, the steps needed to flash a bootloader, and the steps needed to flash an application. This document is not an authoritative reference; it is intended as a collection of useful information that the Klipper developers have accumulated.","title":"Bootloaders"},{"location":"Bootloaders.html#avr-micro-controllers","text":"In general, the Arduino project is a good reference for bootloaders and flashing procedures on the 8-bit Atmel Atmega micro-controllers. In particular, the \"boards.txt\" file: https://github.com/arduino/Arduino/blob/1.8.5/hardware/arduino/avr/boards.txt is a useful reference. To flash a bootloader itself, the AVR chips require an external hardware flashing tool (which communicates with the chip using SPI). This tool can be purchased (for example, do a web search for \"avr isp\", \"arduino isp\", or \"usb tiny isp\"). It is also possible to use another Arduino or Raspberry Pi to flash an AVR bootloader (for example, do a web search for \"program an avr using raspberry pi\"). The examples below are written assuming an \"AVR ISP Mk2\" type device is in use. The \"avrdude\" program is the most common tool used to flash atmega chips (both bootloader flashing and application flashing).","title":"AVR micro-controllers"},{"location":"Bootloaders.html#atmega2560","text":"This chip is typically found in the \"Arduino Mega\" and is very common in 3d printer boards. To flash the bootloader itself use something like: wget 'https://github.com/arduino/Arduino/raw/1.8.5/hardware/arduino/avr/bootloaders/stk500v2/stk500boot_v2_mega2560.hex' avrdude -cavrispv2 -patmega2560 -P/dev/ttyACM0 -b115200 -e -u -U lock:w:0x3F:m -U efuse:w:0xFD:m -U hfuse:w:0xD8:m -U lfuse:w:0xFF:m avrdude -cavrispv2 -patmega2560 -P/dev/ttyACM0 -b115200 -U flash:w:stk500boot_v2_mega2560.hex avrdude -cavrispv2 -patmega2560 -P/dev/ttyACM0 -b115200 -U lock:w:0x0F:m To flash an application use something like: avrdude -cwiring -patmega2560 -P/dev/ttyACM0 -b115200 -D -Uflash:w:out/klipper.elf.hex:i","title":"Atmega2560"},{"location":"Bootloaders.html#atmega1280","text":"This chip is typically found in earlier versions of the \"Arduino Mega\". To flash the bootloader itself use something like: wget 'https://github.com/arduino/Arduino/raw/1.8.5/hardware/arduino/avr/bootloaders/atmega/ATmegaBOOT_168_atmega1280.hex' avrdude -cavrispv2 -patmega1280 -P/dev/ttyACM0 -b115200 -e -u -U lock:w:0x3F:m -U efuse:w:0xF5:m -U hfuse:w:0xDA:m -U lfuse:w:0xFF:m avrdude -cavrispv2 -patmega1280 -P/dev/ttyACM0 -b115200 -U flash:w:ATmegaBOOT_168_atmega1280.hex avrdude -cavrispv2 -patmega1280 -P/dev/ttyACM0 -b115200 -U lock:w:0x0F:m To flash an application use something like: avrdude -carduino -patmega1280 -P/dev/ttyACM0 -b57600 -D -Uflash:w:out/klipper.elf.hex:i","title":"Atmega1280"},{"location":"Bootloaders.html#atmega1284p","text":"This chip is commonly found in \"Melzi\" style 3d printer boards. To flash the bootloader itself use something like: wget 'https://github.com/Lauszus/Sanguino/raw/1.0.2/bootloaders/optiboot/optiboot_atmega1284p.hex' avrdude -cavrispv2 -patmega1284p -P/dev/ttyACM0 -b115200 -e -u -U lock:w:0x3F:m -U efuse:w:0xFD:m -U hfuse:w:0xDE:m -U lfuse:w:0xFF:m avrdude -cavrispv2 -patmega1284p -P/dev/ttyACM0 -b115200 -U flash:w:optiboot_atmega1284p.hex avrdude -cavrispv2 -patmega1284p -P/dev/ttyACM0 -b115200 -U lock:w:0x0F:m To flash an application use something like: avrdude -carduino -patmega1284p -P/dev/ttyACM0 -b115200 -D -Uflash:w:out/klipper.elf.hex:i Note that a number of \"Melzi\" style boards come preloaded with a bootloader that uses a baud rate of 57600. In this case, to flash an application use something like this instead: avrdude -carduino -patmega1284p -P/dev/ttyACM0 -b57600 -D -Uflash:w:out/klipper.elf.hex:i","title":"Atmega1284p"},{"location":"Bootloaders.html#at90usb1286","text":"This document does not cover the method to flash a bootloader to the At90usb1286 nor does it cover general application flashing to this device. The Teensy++ device from pjrc.com comes with a proprietary bootloader. It requires a custom flashing tool from https://github.com/PaulStoffregen/teensy_loader_cli . One can flash an application with it using something like: teensy_loader_cli --mcu=at90usb1286 out/klipper.elf.hex -v","title":"At90usb1286"},{"location":"Bootloaders.html#atmega168","text":"The atmega168 has limited flash space. If using a bootloader, it is recommended to use the Optiboot bootloader. To flash that bootloader use something like: wget 'https://github.com/arduino/Arduino/raw/1.8.5/hardware/arduino/avr/bootloaders/optiboot/optiboot_atmega168.hex' avrdude -cavrispv2 -patmega168 -P/dev/ttyACM0 -b115200 -e -u -U lock:w:0x3F:m -U efuse:w:0x04:m -U hfuse:w:0xDD:m -U lfuse:w:0xFF:m avrdude -cavrispv2 -patmega168 -P/dev/ttyACM0 -b115200 -U flash:w:optiboot_atmega168.hex avrdude -cavrispv2 -patmega168 -P/dev/ttyACM0 -b115200 -U lock:w:0x0F:m To flash an application via the Optiboot bootloader use something like: avrdude -carduino -patmega168 -P/dev/ttyACM0 -b115200 -D -Uflash:w:out/klipper.elf.hex:i","title":"Atmega168"},{"location":"Bootloaders.html#sam3-micro-controllers-arduino-due","text":"It is not common to use a bootloader with the SAM3 mcu. The chip itself has a ROM that allows the flash to be programmed from 3.3V serial port or from USB. To enable the ROM, the \"erase\" pin is held high during a reset, which erases the flash contents, and causes the ROM to run. On an Arduino Due, this sequence can be accomplished by setting a baud rate of 1200 on the \"programming usb port\" (the USB port closest to the power supply). The code at https://github.com/shumatech/BOSSA can be used to program the SAM3. It is recommended to use version 1.9 or later. To flash an application use something like: bossac -U -p /dev/ttyACM0 -a -e -w out/klipper.bin -v -b bossac -U -p /dev/ttyACM0 -R","title":"SAM3 micro-controllers (Arduino Due)"},{"location":"Bootloaders.html#sam4-micro-controllers-duet-wifi","text":"It is not common to use a bootloader with the SAM4 mcu. The chip itself has a ROM that allows the flash to be programmed from 3.3V serial port or from USB. To enable the ROM, the \"erase\" pin is held high during a reset, which erases the flash contents, and causes the ROM to run. The code at https://github.com/shumatech/BOSSA can be used to program the SAM4. It is necessary to use version 1.8.0 or higher. To flash an application use something like: bossac --port=/dev/ttyACM0 -b -U -e -w -v -R out/klipper.bin","title":"SAM4 micro-controllers (Duet Wifi)"},{"location":"Bootloaders.html#samdc21-micro-controllers-duet3d-toolboard-1lc","text":"The SAMC21 is flashed via the ARM Serial Wire Debug (SWD) interface. This is commonly done with a dedicated SWD hardware dongle. Alternatively, one can use a Raspberry Pi with OpenOCD . When using OpenOCD with the SAMC21, extra steps must be taken to first put the chip into Cold Plugging mode if the board makes use of the SWD pins for other purposes. If using OpenOCD on a Raspberry Pi, this can be done by running the following commands before invoking OpenOCD. SWCLK=25 SWDIO=24 SRST=18 echo \"Exporting SWCLK and SRST pins.\" echo $SWCLK > /sys/class/gpio/export echo $SRST > /sys/class/gpio/export echo \"out\" > /sys/class/gpio/gpio$SWCLK/direction echo \"out\" > /sys/class/gpio/gpio$SRST/direction echo \"Setting SWCLK low and pulsing SRST.\" echo \"0\" > /sys/class/gpio/gpio$SWCLK/value echo \"0\" > /sys/class/gpio/gpio$SRST/value echo \"1\" > /sys/class/gpio/gpio$SRST/value echo \"Unexporting SWCLK and SRST pins.\" echo $SWCLK > /sys/class/gpio/unexport echo $SRST > /sys/class/gpio/unexport To flash a program with OpenOCD use the following chip config: source [find target/at91samdXX.cfg] Obtain a program; for instance, klipper can be built for this chip. Flash with OpenOCD commands similar to: at91samd chip-erase at91samd bootloader 0 program out/klipper.elf verify","title":"SAMDC21 micro-controllers (Duet3D Toolboard 1LC)"},{"location":"Bootloaders.html#samd21-micro-controllers-arduino-zero","text":"The SAMD21 bootloader is flashed via the ARM Serial Wire Debug (SWD) interface. This is commonly done with a dedicated SWD hardware dongle. Alternatively, one can use a Raspberry Pi with OpenOCD . To flash a bootloader with OpenOCD use the following chip config: source [find target/at91samdXX.cfg] Obtain a bootloader - for example: wget 'https://github.com/arduino/ArduinoCore-samd/raw/1.8.3/bootloaders/zero/samd21_sam_ba.bin' Flash with OpenOCD commands similar to: at91samd bootloader 0 program samd21_sam_ba.bin verify The most common bootloader on the SAMD21 is the one found on the \"Arduino Zero\". It uses an 8KiB bootloader (the application must be compiled with a start address of 8KiB). One can enter this bootloader by double clicking the reset button. To flash an application use something like: bossac -U -p /dev/ttyACM0 --offset=0x2000 -w out/klipper.bin -v -b -R In contrast, the \"Arduino M0\" uses a 16KiB bootloader (the application must be compiled with a start address of 16KiB). To flash an application on this bootloader, reset the micro-controller and run the flash command within the first few seconds of boot - something like: avrdude -c stk500v2 -p atmega2560 -P /dev/ttyACM0 -u -Uflash:w:out/klipper.elf.hex:i","title":"SAMD21 micro-controllers (Arduino Zero)"},{"location":"Bootloaders.html#samd51-micro-controllers-adafruit-metro-m4-and-similar","text":"Like the SAMD21, the SAMD51 bootloader is flashed via the ARM Serial Wire Debug (SWD) interface. To flash a bootloader with OpenOCD on a Raspberry Pi use the following chip config: source [find target/atsame5x.cfg] Obtain a bootloader - several bootloaders are available from https://github.com/adafruit/uf2-samdx1/releases/latest . For example: wget 'https://github.com/adafruit/uf2-samdx1/releases/download/v3.7.0/bootloader-itsybitsy_m4-v3.7.0.bin' Flash with OpenOCD commands similar to: at91samd bootloader 0 program bootloader-itsybitsy_m4-v3.7.0.bin verify at91samd bootloader 16384 The SAMD51 uses a 16KiB bootloader (the application must be compiled with a start address of 16KiB). To flash an application use something like: bossac -U -p /dev/ttyACM0 --offset=0x4000 -w out/klipper.bin -v -b -R","title":"SAMD51 micro-controllers (Adafruit Metro-M4 and similar)"},{"location":"Bootloaders.html#stm32f103-micro-controllers-blue-pill-devices","text":"The STM32F103 devices have a ROM that can flash a bootloader or application via 3.3V serial. Typically one would wire the PA10 (MCU Rx) and PA9 (MCU Tx) pins to a 3.3V UART adapter. To access the ROM, one should connect the \"boot 0\" pin to high and \"boot 1\" pin to low, and then reset the device. The \"stm32flash\" package can then be used to flash the device using something like: stm32flash -w out/klipper.bin -v -g 0 /dev/ttyAMA0 Note that if one is using a Raspberry Pi for the 3.3V serial, the stm32flash protocol uses a serial parity mode which the Raspberry Pi's \"mini UART\" does not support. See https://www.raspberrypi.com/documentation/computers/configuration.html#configuring-uarts for details on enabling the full uart on the Raspberry Pi GPIO pins. After flashing, set both \"boot 0\" and \"boot 1\" back to low so that future resets boot from flash.","title":"STM32F103 micro-controllers (Blue Pill devices)"},{"location":"Bootloaders.html#stm32f103-with-stm32duino-bootloader","text":"The \"stm32duino\" project has a USB capable bootloader - see: https://github.com/rogerclarkmelbourne/STM32duino-bootloader This bootloader can be flashed via 3.3V serial with something like: wget 'https://github.com/rogerclarkmelbourne/STM32duino-bootloader/raw/master/binaries/generic_boot20_pc13.bin' stm32flash -w generic_boot20_pc13.bin -v -g 0 /dev/ttyAMA0 This bootloader uses 8KiB of flash space (the application must be compiled with a start address of 8KiB). Flash an application with something like: dfu-util -d 1eaf:0003 -a 2 -R -D out/klipper.bin The bootloader typically runs for only a short period after boot. It may be necessary to time the above command so that it runs while the bootloader is still active (the bootloader will flash a board led while it is running). Alternatively, set the \"boot 0\" pin to low and \"boot 1\" pin to high to stay in the bootloader after a reset.","title":"STM32F103 with stm32duino bootloader"},{"location":"Bootloaders.html#stm32f103-with-hid-bootloader","text":"The HID bootloader is a compact, driverless bootloader capable of flashing over USB. Also available is a fork with builds specific to the SKR Mini E3 1.2 . For generic STM32F103 boards such as the blue pill it is possible to flash the bootloader via 3.3V serial using stm32flash as noted in the stm32duino section above, substituting the file name for the desired hid bootloader binary (ie: hid_generic_pc13.bin for the blue pill). It is not possible to use stm32flash for the SKR Mini E3 as the boot0 pin is tied directly to ground and not broken out via header pins. It is recommended to use a STLink V2 with STM32Cubeprogrammer to flash the bootloader. If you don't have access to a STLink it is also possible to use a Raspberry Pi and OpenOCD with the following chip config: source [find target/stm32f1x.cfg] If you wish you can make a backup of the current flash with the following command. Note that it may take some time to complete: flash read_bank 0 btt_skr_mini_e3_backup.bin finally, you can flash with commands similar to: stm32f1x mass_erase 0 program hid_btt_skr_mini_e3.bin verify 0x08000000 NOTES: The example above erases the chip then programs the bootloader. Regardless of the method chosen to flash it is recommended to erase the chip prior to flashing. Prior flashing the SKR Mini E3 with this bootloader you should be aware that you will no longer be able to update firmware via the sdcard. You may need to hold down the reset button on the board while launching OpenOCD. It should display something like: Open On-Chip Debugger 0.10.0+dev-01204-gc60252ac-dirty (2020-04-27-16:00) Licensed under GNU GPL v2 For bug reports, read http://openocd.org/doc/doxygen/bugs.html DEPRECATED! use 'adapter speed' not 'adapter_khz' Info : BCM2835 GPIO JTAG/SWD bitbang driver Info : JTAG and SWD modes enabled Info : clock speed 40 kHz Info : SWD DPIDR 0x1ba01477 Info : stm32f1x.cpu: hardware has 6 breakpoints, 4 watchpoints Info : stm32f1x.cpu: external reset detected Info : starting gdb server for stm32f1x.cpu on 3333 Info : Listening on port 3333 for gdb connections After which you can release the reset button. This bootloader requires 2KiB of flash space (the application must be compiled with a start address of 2KiB). The hid-flash program is used to upload a binary to the bootloader. You can install this software with the following commands: sudo apt install libusb-1.0 cd ~/klipper/lib/hidflash make If the bootloader is running you can flash with something like: ~/klipper/lib/hidflash/hid-flash ~/klipper/out/klipper.bin alternatively, you can use make flash to flash klipper directly: make flash FLASH_DEVICE=1209:BEBA OR if klipper has been previously flashed: make flash FLASH_DEVICE=/dev/ttyACM0 It may be necessary to manually enter the bootloader, this can be done by setting \"boot 0\" low and \"boot 1\" high. On the SKR Mini E3 \"Boot 1\" is not available, so it may be done by setting pin PA2 low if you flashed \"hid_btt_skr_mini_e3.bin\". This pin is labeled \"TX0\" on the TFT header in the SKR Mini E3's \"PIN\" document. There is a ground pin next to PA2 which you can use to pull PA2 low.","title":"STM32F103 with HID bootloader"},{"location":"Bootloaders.html#stm32f103stm32f072-with-msc-bootloader","text":"The MSC bootloader is a driverless bootloader capable of flashing over USB. It is possible to flash the bootloader via 3.3V serial using stm32flash as noted in the stm32duino section above, substituting the file name for the desired MSC bootloader binary (ie: MSCboot-Bluepill.bin for the blue pill). For STM32F072 boards it is also possible to flash the bootloader over USB (via DFU) with something like: dfu-util -d 0483:df11 -a 0 -R -D MSCboot-STM32F072.bin -s0x08000000:leave This bootloader uses 8KiB or 16KiB of flash space, see description of the bootloader (the application must be compiled with with the corresponding starting address). The bootloader can be activated by pressing the reset button of the board twice. As soon as the bootloader is activated, the board appears as a USB flash drive onto which the klipper.bin file can be copied.","title":"STM32F103/STM32F072 with MSC bootloader"},{"location":"Bootloaders.html#stm32f103stm32f0x2-with-canboot-bootloader","text":"The CanBoot bootloader provides an option for uploading Klipper firmware over the CANBUS. The bootloader itself is derived from Klipper's source code. Currently CanBoot supports the STM32F103, STM32F042, and STM32F072 models. It is recommended to use a ST-Link Programmer to flash CanBoot, however it should be possible to flash using stm32flash on STM32F103 devices, and dfu-util on STM32F042/STM32F072 devices. See the previous sections in this document for instructions on these flashing methods, substituting canboot.bin for the file name where appropriate. The CanBoot repository linked above provides instructions for building the bootloader. The first time CanBoot has been flashed it should detect that no application is present and enter the bootloader. If this doesn't occur it is possible to enter the bootloader by pressing the reset button twice in succession. The flash_can.py utility supplied in the lib/canboot folder may be used to upload Klipper firmware. The device UUID is necessary to flash. If you do not have a UUID it is possible to query nodes currently running the bootloader: python3 flash_can.py -q This will return UUIDs for all connected nodes not currently assigned a UUID. This should include all nodes currently in the bootloader. Once you have a UUID, you may upload firmware with following command: python3 flash_can.py -i can0 -f ~/klipper/out/klipper.bin -u aabbccddeeff Where aabbccddeeff is replaced by your UUID. Note that the -i and -f options may be omitted, they default to can0 and ~/klipper/out/klipper.bin respectively. When building Klipper for use with CanBoot, select the 8 KiB Bootloader option.","title":"STM32F103/STM32F0x2 with CanBoot bootloader"},{"location":"Bootloaders.html#stm32f4-micro-controllers-skr-pro-11","text":"STM32F4 micro-controllers come equipped with a built-in system bootloader capable of flashing over USB (via DFU), 3.3V Serial, and various other methods (see STM Document AN2606 for more information). Some STM32F4 boards, such as the SKR Pro 1.1, are not able to enter the DFU bootloader. The HID bootloader is available for STM32F405/407 based boards should the user prefer flashing over USB over using the sdcard. Note that you may need to configure and build a version specific to your board, a build for the SKR Pro 1.1 is available here . Unless your board is DFU capable the most accessible flashing method is likely via 3.3V serial, which follows the same procedure as flashing the STM32F103 using stm32flash . For example: wget https://github.com/Arksine/STM32_HID_Bootloader/releases/download/v0.5-beta/hid_bootloader_SKR_PRO.bin stm32flash -w hid_bootloader_SKR_PRO.bin -v -g 0 /dev/ttyAMA0 This bootloader requires 16Kib of flash space on the STM32F4 (the application must be compiled with a start address of 16KiB). As with the STM32F1, the STM32F4 uses the hid-flash tool to upload binaries to the MCU. See the instructions above for details on how to build and use hid-flash. It may be necessary to manually enter the bootloader, this can be done by setting \"boot 0\" low, \"boot 1\" high and plugging in the device. After programming is complete unplug the device and set \"boot 1\" back to low so the application will be loaded.","title":"STM32F4 micro-controllers (SKR Pro 1.1)"},{"location":"Bootloaders.html#lpc176x-micro-controllers-smoothieboards","text":"This document does not describe the method to flash a bootloader itself - see: http://smoothieware.org/flashing-the-bootloader for further information on that topic. It is common for Smoothieboards to come with a bootloader from: https://github.com/triffid/LPC17xx-DFU-Bootloader . When using this bootloader the application must be compiled with a start address of 16KiB. The easiest way to flash an application with this bootloader is to copy the application file (eg, out/klipper.bin ) to a file named firmware.bin on an SD card, and then to reboot the micro-controller with that SD card.","title":"LPC176x micro-controllers (Smoothieboards)"},{"location":"Bootloaders.html#running-openocd-on-the-raspberry-pi","text":"OpenOCD is a software package that can perform low-level chip flashing and debugging. It can use the GPIO pins on a Raspberry Pi to communicate with a variety of ARM chips. This section describes how one can install and launch OpenOCD. It is derived from the instructions at: https://learn.adafruit.com/programming-microcontrollers-using-openocd-on-raspberry-pi Begin by downloading and compiling the software (each step may take several minutes and the \"make\" step may take 30+ minutes): sudo apt-get update sudo apt-get install autoconf libtool telnet mkdir ~/openocd cd ~/openocd/ git clone http://openocd.zylin.com/openocd cd openocd ./bootstrap ./configure --enable-sysfsgpio --enable-bcm2835gpio --prefix=/home/pi/openocd/install make make install","title":"Running OpenOCD on the Raspberry PI"},{"location":"Bootloaders.html#configure-openocd","text":"Create an OpenOCD config file: nano ~/openocd/openocd.cfg Use a config similar to the following: # Uses RPi pins: GPIO25 for SWDCLK, GPIO24 for SWDIO, GPIO18 for nRST source [find interface/raspberrypi2-native.cfg] bcm2835gpio_swd_nums 25 24 bcm2835gpio_srst_num 18 transport select swd # Use hardware reset wire for chip resets reset_config srst_only adapter_nsrst_delay 100 adapter_nsrst_assert_width 100 # Specify the chip type source [find target/atsame5x.cfg] # Set the adapter speed adapter_khz 40 # Connect to chip init targets reset halt","title":"Configure OpenOCD"},{"location":"Bootloaders.html#wire-the-raspberry-pi-to-the-target-chip","text":"Poweroff both the the Raspberry Pi and the target chip before wiring! Verify the target chip uses 3.3V prior to connecting to a Raspberry Pi! Connect GND, SWDCLK, SWDIO, and RST on the target chip to GND, GPIO25, GPIO24, and GPIO18 respectively on the Raspberry Pi. Then power up the Raspberry Pi and provide power to the target chip.","title":"Wire the Raspberry Pi to the target chip"},{"location":"Bootloaders.html#run-openocd","text":"Run OpenOCD: cd ~/openocd/ sudo ~/openocd/install/bin/openocd -f ~/openocd/openocd.cfg The above should cause OpenOCD to emit some text messages and then wait (it should not immediately return to the Unix shell prompt). If OpenOCD exits on its own or if it continues to emit text messages then double check the wiring. Once OpenOCD is running and is stable, one can send it commands via telnet. Open another ssh session and run the following: telnet 127.0.0.1 4444 (One can exit telnet by pressing ctrl+] and then running the \"quit\" command.)","title":"Run OpenOCD"},{"location":"Bootloaders.html#openocd-and-gdb","text":"It is possible to use OpenOCD with gdb to debug Klipper. The following commands assume one is running gdb on a desktop class machine. Add the following to the OpenOCD config file: bindto 0.0.0.0 gdb_port 44444 Restart OpenOCD on the Raspberry Pi and then run the following Unix command on the desktop machine: cd /path/to/klipper/ gdb out/klipper.elf Within gdb run: target remote octopi:44444 (Replace \"octopi\" with the host name of the Raspberry Pi.) Once gdb is running it is possible to set breakpoints and to inspect registers.","title":"OpenOCD and gdb"},{"location":"CANBUS.html","text":"CANBUS \u00b6 This document describes Klipper's CAN bus support. Device Hardware \u00b6 Klipper currently supports CAN on stm32, SAME5x, and rp2040 chips. In addition, the micro-controller chip must be on a board that has a CAN transceiver. To compile for CAN, run make menuconfig and select \"CAN bus\" as the communication interface. Finally, compile the micro-controller code and flash it to the target board. Host Hardware \u00b6 In order to use a CAN bus, it is necessary to have a host adapter. It is recommended to use a \"USB to CAN adapter\". There are many different USB to CAN adapters available from different manufacturers. When choosing one, we recommend verifying that the firmware can be updated on it. (Unfortunately, we've found some USB adapters run defective firmware and are locked down, so verify before purchasing.) Look for adapters that can run Klipper directly (in its \"USB to CAN bridge mode\") or that run the candlelight firmware . It is also necessary to configure the host operating system to use the adapter. This is typically done by creating a new file named /etc/network/interfaces.d/can0 with the following contents: allow-hotplug can0 iface can0 can static bitrate 1000000 up ip link set $IFACE txqueuelen 128 Terminating Resistors \u00b6 A CAN bus should have two 120 ohm resistors between the CANH and CANL wires. Ideally, one resistor located at each the end of the bus. Note that some devices have a builtin 120 ohm resistor that can not be easily removed. Some devices do not include a resistor at all. Other devices have a mechanism to select the resistor (typically by connecting a \"pin jumper\"). Be sure to check the schematics of all devices on the CAN bus to verify that there are two and only two 120 Ohm resistors on the bus. To test that the resistors are correct, one can remove power to the printer and use a multi-meter to check the resistance between the CANH and CANL wires - it should report ~60 ohms on a correctly wired CAN bus. Finding the canbus_uuid for new micro-controllers \u00b6 Each micro-controller on the CAN bus is assigned a unique id based on the factory chip identifier encoded into each micro-controller. To find each micro-controller device id, make sure the hardware is powered and wired correctly, and then run: ~/klippy-env/bin/python ~/klipper/scripts/canbus_query.py can0 If uninitialized CAN devices are detected the above command will report lines like the following: Found canbus_uuid=11aa22bb33cc, Application: Klipper Each device will have a unique identifier. In the above example, 11aa22bb33cc is the micro-controller's \"canbus_uuid\". Note that the canbus_query.py tool will only report uninitialized devices - if Klipper (or a similar tool) configures the device then it will no longer appear in the list. Configuring Klipper \u00b6 Update the Klipper mcu configuration to use the CAN bus to communicate with the device - for example: [mcu my_can_mcu] canbus_uuid: 11aa22bb33cc USB to CAN bus bridge mode \u00b6 Some micro-controllers support selecting \"USB to CAN bus bridge\" mode during Klipper's \"make menuconfig\". This mode may allow one to use a micro-controller as both a \"USB to CAN bus adapter\" and as a Klipper node. When Klipper uses this mode the micro-controller appears as a \"USB CAN bus adapter\" under Linux. The \"Klipper bridge mcu\" itself will appear as if it was on this CAN bus - it can be identified via canbus_query.py and it must be configured like other CAN bus Klipper nodes. Some important notes when using this mode: It is necessary to configure the can0 (or similar) interface in Linux in order to communicate with the bus. However, Linux CAN bus speed and CAN bus bit-timing options are ignored by Klipper. Currently, the CAN bus frequency is specified during \"make menuconfig\" and the bus speed specified in Linux is ignored. Whenever the \"bridge mcu\" is reset, Linux will disable the corresponding can0 interface. To ensure proper handling of FIRMWARE_RESTART and RESTART commands, it is recommended to use allow-hotplug in the /etc/network/interfaces.d/can0 file. For example: allow-hotplug can0 iface can0 can static bitrate 1000000 up ip link set $IFACE txqueuelen 128 The \"bridge mcu\" is not actually on the CAN bus. Messages to and from the bridge mcu will not be seen by other adapters that may be on the CAN bus. The available bandwidth to both the \"bridge mcu\" itself and all devices on the CAN bus is effectively limited by the CAN bus frequency. As a result, it is recommended to use a CAN bus frequency of 1000000 when using \"USB to CAN bus bridge mode\". It is only valid to use USB to CAN bridge mode if there is a functioning CAN bus with at least one other node available (in addition to the bridge node itself). Use a standard USB configuration if the goal is to communicate only with the single USB device. Using USB to CAN bridge mode without a fully functioning CAN bus (including terminating resistors and an additional node) may result in sporadic errors even when communicating with the bridge node. A USB to CAN bridge board will not appear as a USB serial device, it will not show up when running ls /dev/serial/by-id , and it can not be configured in Klipper's printer.cfg file with a serial: parameter. The bridge board appears as a \"USB CAN adapter\" and it is configured in the printer.cfg as a CAN node . Tips for troubleshooting \u00b6 See the CAN bus troubleshooting document.","title":"CANBUS"},{"location":"CANBUS.html#canbus","text":"This document describes Klipper's CAN bus support.","title":"CANBUS"},{"location":"CANBUS.html#device-hardware","text":"Klipper currently supports CAN on stm32, SAME5x, and rp2040 chips. In addition, the micro-controller chip must be on a board that has a CAN transceiver. To compile for CAN, run make menuconfig and select \"CAN bus\" as the communication interface. Finally, compile the micro-controller code and flash it to the target board.","title":"Device Hardware"},{"location":"CANBUS.html#host-hardware","text":"In order to use a CAN bus, it is necessary to have a host adapter. It is recommended to use a \"USB to CAN adapter\". There are many different USB to CAN adapters available from different manufacturers. When choosing one, we recommend verifying that the firmware can be updated on it. (Unfortunately, we've found some USB adapters run defective firmware and are locked down, so verify before purchasing.) Look for adapters that can run Klipper directly (in its \"USB to CAN bridge mode\") or that run the candlelight firmware . It is also necessary to configure the host operating system to use the adapter. This is typically done by creating a new file named /etc/network/interfaces.d/can0 with the following contents: allow-hotplug can0 iface can0 can static bitrate 1000000 up ip link set $IFACE txqueuelen 128","title":"Host Hardware"},{"location":"CANBUS.html#terminating-resistors","text":"A CAN bus should have two 120 ohm resistors between the CANH and CANL wires. Ideally, one resistor located at each the end of the bus. Note that some devices have a builtin 120 ohm resistor that can not be easily removed. Some devices do not include a resistor at all. Other devices have a mechanism to select the resistor (typically by connecting a \"pin jumper\"). Be sure to check the schematics of all devices on the CAN bus to verify that there are two and only two 120 Ohm resistors on the bus. To test that the resistors are correct, one can remove power to the printer and use a multi-meter to check the resistance between the CANH and CANL wires - it should report ~60 ohms on a correctly wired CAN bus.","title":"Terminating Resistors"},{"location":"CANBUS.html#finding-the-canbus_uuid-for-new-micro-controllers","text":"Each micro-controller on the CAN bus is assigned a unique id based on the factory chip identifier encoded into each micro-controller. To find each micro-controller device id, make sure the hardware is powered and wired correctly, and then run: ~/klippy-env/bin/python ~/klipper/scripts/canbus_query.py can0 If uninitialized CAN devices are detected the above command will report lines like the following: Found canbus_uuid=11aa22bb33cc, Application: Klipper Each device will have a unique identifier. In the above example, 11aa22bb33cc is the micro-controller's \"canbus_uuid\". Note that the canbus_query.py tool will only report uninitialized devices - if Klipper (or a similar tool) configures the device then it will no longer appear in the list.","title":"Finding the canbus_uuid for new micro-controllers"},{"location":"CANBUS.html#configuring-klipper","text":"Update the Klipper mcu configuration to use the CAN bus to communicate with the device - for example: [mcu my_can_mcu] canbus_uuid: 11aa22bb33cc","title":"Configuring Klipper"},{"location":"CANBUS.html#usb-to-can-bus-bridge-mode","text":"Some micro-controllers support selecting \"USB to CAN bus bridge\" mode during Klipper's \"make menuconfig\". This mode may allow one to use a micro-controller as both a \"USB to CAN bus adapter\" and as a Klipper node. When Klipper uses this mode the micro-controller appears as a \"USB CAN bus adapter\" under Linux. The \"Klipper bridge mcu\" itself will appear as if it was on this CAN bus - it can be identified via canbus_query.py and it must be configured like other CAN bus Klipper nodes. Some important notes when using this mode: It is necessary to configure the can0 (or similar) interface in Linux in order to communicate with the bus. However, Linux CAN bus speed and CAN bus bit-timing options are ignored by Klipper. Currently, the CAN bus frequency is specified during \"make menuconfig\" and the bus speed specified in Linux is ignored. Whenever the \"bridge mcu\" is reset, Linux will disable the corresponding can0 interface. To ensure proper handling of FIRMWARE_RESTART and RESTART commands, it is recommended to use allow-hotplug in the /etc/network/interfaces.d/can0 file. For example: allow-hotplug can0 iface can0 can static bitrate 1000000 up ip link set $IFACE txqueuelen 128 The \"bridge mcu\" is not actually on the CAN bus. Messages to and from the bridge mcu will not be seen by other adapters that may be on the CAN bus. The available bandwidth to both the \"bridge mcu\" itself and all devices on the CAN bus is effectively limited by the CAN bus frequency. As a result, it is recommended to use a CAN bus frequency of 1000000 when using \"USB to CAN bus bridge mode\". It is only valid to use USB to CAN bridge mode if there is a functioning CAN bus with at least one other node available (in addition to the bridge node itself). Use a standard USB configuration if the goal is to communicate only with the single USB device. Using USB to CAN bridge mode without a fully functioning CAN bus (including terminating resistors and an additional node) may result in sporadic errors even when communicating with the bridge node. A USB to CAN bridge board will not appear as a USB serial device, it will not show up when running ls /dev/serial/by-id , and it can not be configured in Klipper's printer.cfg file with a serial: parameter. The bridge board appears as a \"USB CAN adapter\" and it is configured in the printer.cfg as a CAN node .","title":"USB to CAN bus bridge mode"},{"location":"CANBUS.html#tips-for-troubleshooting","text":"See the CAN bus troubleshooting document.","title":"Tips for troubleshooting"},{"location":"CANBUS_Troubleshooting.html","text":"CANBUS Troubleshooting \u00b6 This document provides information on troubleshooting communication issues when using Klipper with CAN bus . Verify CAN bus wiring \u00b6 The first step in troubleshooting communication issues is to verify the CAN bus wiring. Be sure there are exactly two 120 Ohm terminating resistors on the CAN bus. If the resistors are not properly installed then messages may not be able to be sent at all or the connection may have sporadic instability. The CANH and CANL bus wiring should be twisted around each other. At a minimum, the wiring should have a twist every few centimeters. Avoid twisting the CANH and CANL wiring around power wires and ensure that power wires that travel parallel to the CANH and CANL wires do not have the same amount of twists. Verify that all plugs and wire crimps on the CAN bus wiring are fully secured. Movement of the printer toolhead may jostle the CAN bus wiring causing a bad wire crimp or unsecured plug to result in intermittent communication errors. Check for incrementing bytes_invalid counter \u00b6 The Klipper log file will report a Stats line once a second when the printer is active. These \"Stats\" lines will have a bytes_invalid counter for each micro-controller. This counter should not increment during normal printer operation (it is normal for the counter to be non-zero after a RESTART and it is not a concern if the counter increments once a month or so). If this counter increments on a CAN bus micro-controller during normal printing (it increments every few hours or more frequently) then it is an indication of a severe problem. Incrementing bytes_invalid on a CAN bus connection is a symptom of reordered messages on the CAN bus. If seen, make sure to: Use a Linux kernel version 6.6.0 or later. If using a USB-to-CANBUS adapter running candlelight firmware, use v2.0 or later of candleLight_fw. If using Klipper's USB-to-CANBUS bridge mode, make sure the bridge node is flashed with Klipper v0.12.0 or later. Reordered messages is a severe problem that must be fixed. It will result in unstable behavior and can lead to confusing errors at any part of a print. An incrementing bytes_invalid is not caused by wiring or similar hardware issues and can only be fixed by identifying and updating the faulty software. Older versions of the Linux kernel had a bug in the gs_usb canbus driver code that could cause reordered canbus packets. The issue is thought to be fixed in Linux commit 24bc41b4 which was released in v6.6.0. In some cases, older Linux versions may not show the problem (due to how hardware interrupts are configured), however if problems are seen the recommended solution is to upgrade to a newer kernel. Older versions of candlelight firmware could reorder canbus packets, and the issue is thought to be fixed in candlelight_fw commit 8b3a7b45 . Older versions of Klipper's USB-to-CANBUS bridge code could incorrectly drop canbus messages. This is not as severe as reordering messages, but it should still be fixed. It is thought to be fixed with Klipper PR #6175 . Use an appropriate txqueuelen setting \u00b6 The Klipper code uses the Linux kernel to manage CAN bus traffic. By default, the kernel will only queue 10 CAN transmit packets. It is recommended to configure the can0 device with a txqueuelen 128 to increase that size. If Klipper transmits a packet and Linux has filled all of its transmit queue space then Linux will drop that packet and messages like the following will appear in the Klipper log: Got error -1 in can write: (105)No buffer space available Klipper will automatically retransmit the lost messages as part of its normal application level message retransmit system. Thus, this log message is a warning and it does not indicate an unrecoverable error. If a complete CAN bus failure occurs (such as a CAN wire break) then Linux will not be able to transmit any messages on the CAN bus and it is common to find the above message in the Klipper log. In this case, the log message is a symptom of a larger problem (the inability to transmit any messages) and is not directly related to Linux txqueuelen . One may check the current queue size by running the Linux command ip link show can0 . It should report a bunch of text including the snippet qlen 128 . If one sees something like qlen 10 then it indicates the CAN device has not been properly configured. It is not recommended to use a txqueuelen significantly larger than 128. A CAN bus running at a frequency of 1000000 will typically take around 120us to transmit a CAN packet. Thus a queue of 128 packets is likely to take around 15-20ms to drain. A substantially larger queue could cause excessive spikes in message round-trip-time which could lead to unrecoverable errors. Said another way, Klipper's application retransmit system is more robust if it does not have to wait for Linux to drain an excessively large queue of possibly stale data. This is analogous to the problem of bufferbloat on internet routers. Under normal circumstances Klipper may utilize ~25 queue slots per MCU - typically only utilizing more slots during retransmits. (Specifically, the Klipper host may transmit up to 192 bytes to each Klipper MCU before receiving an acknowledgment from that MCU.) If a single CAN bus has 5 or more Klipper MCUs on it, then it might be necessary to increase the txqueuelen above the recommended value of 128. However, as above, care should be taken when selecting a new value to avoid excessive round-trip-time latency. Use canbus_query.py only to identify nodes never previously seen \u00b6 It is only valid to use the canbus_query.py tool to identify micro-controllers that have never been previously identified. Once all nodes on a bus are identified, record the resulting uuids in the printer.cfg, and avoid running the tool unnecessarily. The tool is implemented using a low-level mechanism that can cause nodes to internally observe bus errors. These internal errors may result in communication interruptions and may result is some nodes disconnecting from the bus. It is not valid to use the tool to \"ping\" if a node is connected. Do not run the tool during an active print. Obtaining candump logs \u00b6 The CAN bus messages sent to and from the micro-controller are handled by the Linux kernel. It is possible to capture these messages from the kernel for debugging purposes. A log of these messages may be of use in diagnostics. The Linux can-utils tool provides the capture software. It is typically installed on a machine by running: sudo apt-get update && sudo apt-get install can-utils Once installed, one may obtain a capture of all CAN bus messages on an interface with the following command: candump -tz -Ddex can0,#FFFFFFFF > mycanlog One can view the resulting log file ( mycanlog in the example above) to see each raw CAN bus message that was sent and received by Klipper. Understanding the content of these messages will likely require low-level knowledge of Klipper's CANBUS protocol and Klipper's MCU commands . Parsing Klipper messages in a candump log \u00b6 One may use the parsecandump.py tool to parse the low-level Klipper micro-controller messages contained in a candump log. Using this tool is an advanced topic that requires knowledge of Klipper MCU commands . For example: ./scripts/parsecandump.py mycanlog 108 ./out/klipper.dict This tool produces output similar to the parsedump tool . See the documentation for that tool for information on generating the Klipper micro-controller data dictionary. In the above example, 108 is the CAN bus id . It is a hexadecimal number. The id 108 is assigned by Klipper to the first micro-controller. If the CAN bus has multiple micro-controllers on it, then the second micro-controller would be 10a , the third would be 10c , and so on. The candump log must be produced using the -tz -Ddex command-line arguments (for example: candump -tz -Ddex can0,#FFFFFFFF ) in order to use the parsecandump.py tool. Using a logic analyzer on the canbus wiring \u00b6 The Sigrok Pulseview software along with a low-cost logic analyzer can be useful for diagnosing CAN bus signaling. This is an advanced topic likely only of interest to experts. One can often find \"USB logic analyzers\" for under $15 (US pricing as of 2023). These devices are often listed as \"Saleae logic clones\" or as \"24MHz 8 channel USB logic analyzers\". The above picture was taken while using Pulseview with a \"Saleae clone\" logic analyzer. The Sigrok and Pulseview software was installed on a desktop machine (also install the \"fx2lafw\" firmware if that is packaged separately). The CH0 pin on the logic analyzer was routed to the CAN Rx line, the CH1 pin was wired to the CAN Tx pin, and GND was wired to GND. Pulseview was configured to only display the D0 and D1 lines (red \"probe\" icon center top toolbar). The number of samples was set to 5 million (top toolbar) and the sample rate was set to 24Mhz (top toolbar). The CAN decoder was added (yellow and green \"bubble icon\" right top toolbar). The D0 channel was labeled as RX and set to trigger on a falling edge (click on black D0 label at left). The D1 channel was labeled as TX (click on brown D1 label at left). The CAN decoder was configured for 1Mbit rate (click on green CAN label at left). The CAN decoder was moved to the top of the display (click and drag green CAN label). Finally, the capture was started (click \"Run\" at top left) and a packet was transmitted on the CAN bus ( cansend can0 123#121212121212 ). The logic analyzer provides an independent tool for capturing packets and verifying bit timing.","title":"CANBUS Troubleshooting"},{"location":"CANBUS_Troubleshooting.html#canbus-troubleshooting","text":"This document provides information on troubleshooting communication issues when using Klipper with CAN bus .","title":"CANBUS Troubleshooting"},{"location":"CANBUS_Troubleshooting.html#verify-can-bus-wiring","text":"The first step in troubleshooting communication issues is to verify the CAN bus wiring. Be sure there are exactly two 120 Ohm terminating resistors on the CAN bus. If the resistors are not properly installed then messages may not be able to be sent at all or the connection may have sporadic instability. The CANH and CANL bus wiring should be twisted around each other. At a minimum, the wiring should have a twist every few centimeters. Avoid twisting the CANH and CANL wiring around power wires and ensure that power wires that travel parallel to the CANH and CANL wires do not have the same amount of twists. Verify that all plugs and wire crimps on the CAN bus wiring are fully secured. Movement of the printer toolhead may jostle the CAN bus wiring causing a bad wire crimp or unsecured plug to result in intermittent communication errors.","title":"Verify CAN bus wiring"},{"location":"CANBUS_Troubleshooting.html#check-for-incrementing-bytes_invalid-counter","text":"The Klipper log file will report a Stats line once a second when the printer is active. These \"Stats\" lines will have a bytes_invalid counter for each micro-controller. This counter should not increment during normal printer operation (it is normal for the counter to be non-zero after a RESTART and it is not a concern if the counter increments once a month or so). If this counter increments on a CAN bus micro-controller during normal printing (it increments every few hours or more frequently) then it is an indication of a severe problem. Incrementing bytes_invalid on a CAN bus connection is a symptom of reordered messages on the CAN bus. If seen, make sure to: Use a Linux kernel version 6.6.0 or later. If using a USB-to-CANBUS adapter running candlelight firmware, use v2.0 or later of candleLight_fw. If using Klipper's USB-to-CANBUS bridge mode, make sure the bridge node is flashed with Klipper v0.12.0 or later. Reordered messages is a severe problem that must be fixed. It will result in unstable behavior and can lead to confusing errors at any part of a print. An incrementing bytes_invalid is not caused by wiring or similar hardware issues and can only be fixed by identifying and updating the faulty software. Older versions of the Linux kernel had a bug in the gs_usb canbus driver code that could cause reordered canbus packets. The issue is thought to be fixed in Linux commit 24bc41b4 which was released in v6.6.0. In some cases, older Linux versions may not show the problem (due to how hardware interrupts are configured), however if problems are seen the recommended solution is to upgrade to a newer kernel. Older versions of candlelight firmware could reorder canbus packets, and the issue is thought to be fixed in candlelight_fw commit 8b3a7b45 . Older versions of Klipper's USB-to-CANBUS bridge code could incorrectly drop canbus messages. This is not as severe as reordering messages, but it should still be fixed. It is thought to be fixed with Klipper PR #6175 .","title":"Check for incrementing bytes_invalid counter"},{"location":"CANBUS_Troubleshooting.html#use-an-appropriate-txqueuelen-setting","text":"The Klipper code uses the Linux kernel to manage CAN bus traffic. By default, the kernel will only queue 10 CAN transmit packets. It is recommended to configure the can0 device with a txqueuelen 128 to increase that size. If Klipper transmits a packet and Linux has filled all of its transmit queue space then Linux will drop that packet and messages like the following will appear in the Klipper log: Got error -1 in can write: (105)No buffer space available Klipper will automatically retransmit the lost messages as part of its normal application level message retransmit system. Thus, this log message is a warning and it does not indicate an unrecoverable error. If a complete CAN bus failure occurs (such as a CAN wire break) then Linux will not be able to transmit any messages on the CAN bus and it is common to find the above message in the Klipper log. In this case, the log message is a symptom of a larger problem (the inability to transmit any messages) and is not directly related to Linux txqueuelen . One may check the current queue size by running the Linux command ip link show can0 . It should report a bunch of text including the snippet qlen 128 . If one sees something like qlen 10 then it indicates the CAN device has not been properly configured. It is not recommended to use a txqueuelen significantly larger than 128. A CAN bus running at a frequency of 1000000 will typically take around 120us to transmit a CAN packet. Thus a queue of 128 packets is likely to take around 15-20ms to drain. A substantially larger queue could cause excessive spikes in message round-trip-time which could lead to unrecoverable errors. Said another way, Klipper's application retransmit system is more robust if it does not have to wait for Linux to drain an excessively large queue of possibly stale data. This is analogous to the problem of bufferbloat on internet routers. Under normal circumstances Klipper may utilize ~25 queue slots per MCU - typically only utilizing more slots during retransmits. (Specifically, the Klipper host may transmit up to 192 bytes to each Klipper MCU before receiving an acknowledgment from that MCU.) If a single CAN bus has 5 or more Klipper MCUs on it, then it might be necessary to increase the txqueuelen above the recommended value of 128. However, as above, care should be taken when selecting a new value to avoid excessive round-trip-time latency.","title":"Use an appropriate txqueuelen setting"},{"location":"CANBUS_Troubleshooting.html#use-canbus_querypy-only-to-identify-nodes-never-previously-seen","text":"It is only valid to use the canbus_query.py tool to identify micro-controllers that have never been previously identified. Once all nodes on a bus are identified, record the resulting uuids in the printer.cfg, and avoid running the tool unnecessarily. The tool is implemented using a low-level mechanism that can cause nodes to internally observe bus errors. These internal errors may result in communication interruptions and may result is some nodes disconnecting from the bus. It is not valid to use the tool to \"ping\" if a node is connected. Do not run the tool during an active print.","title":"Use canbus_query.py only to identify nodes never previously seen"},{"location":"CANBUS_Troubleshooting.html#obtaining-candump-logs","text":"The CAN bus messages sent to and from the micro-controller are handled by the Linux kernel. It is possible to capture these messages from the kernel for debugging purposes. A log of these messages may be of use in diagnostics. The Linux can-utils tool provides the capture software. It is typically installed on a machine by running: sudo apt-get update && sudo apt-get install can-utils Once installed, one may obtain a capture of all CAN bus messages on an interface with the following command: candump -tz -Ddex can0,#FFFFFFFF > mycanlog One can view the resulting log file ( mycanlog in the example above) to see each raw CAN bus message that was sent and received by Klipper. Understanding the content of these messages will likely require low-level knowledge of Klipper's CANBUS protocol and Klipper's MCU commands .","title":"Obtaining candump logs"},{"location":"CANBUS_Troubleshooting.html#parsing-klipper-messages-in-a-candump-log","text":"One may use the parsecandump.py tool to parse the low-level Klipper micro-controller messages contained in a candump log. Using this tool is an advanced topic that requires knowledge of Klipper MCU commands . For example: ./scripts/parsecandump.py mycanlog 108 ./out/klipper.dict This tool produces output similar to the parsedump tool . See the documentation for that tool for information on generating the Klipper micro-controller data dictionary. In the above example, 108 is the CAN bus id . It is a hexadecimal number. The id 108 is assigned by Klipper to the first micro-controller. If the CAN bus has multiple micro-controllers on it, then the second micro-controller would be 10a , the third would be 10c , and so on. The candump log must be produced using the -tz -Ddex command-line arguments (for example: candump -tz -Ddex can0,#FFFFFFFF ) in order to use the parsecandump.py tool.","title":"Parsing Klipper messages in a candump log"},{"location":"CANBUS_Troubleshooting.html#using-a-logic-analyzer-on-the-canbus-wiring","text":"The Sigrok Pulseview software along with a low-cost logic analyzer can be useful for diagnosing CAN bus signaling. This is an advanced topic likely only of interest to experts. One can often find \"USB logic analyzers\" for under $15 (US pricing as of 2023). These devices are often listed as \"Saleae logic clones\" or as \"24MHz 8 channel USB logic analyzers\". The above picture was taken while using Pulseview with a \"Saleae clone\" logic analyzer. The Sigrok and Pulseview software was installed on a desktop machine (also install the \"fx2lafw\" firmware if that is packaged separately). The CH0 pin on the logic analyzer was routed to the CAN Rx line, the CH1 pin was wired to the CAN Tx pin, and GND was wired to GND. Pulseview was configured to only display the D0 and D1 lines (red \"probe\" icon center top toolbar). The number of samples was set to 5 million (top toolbar) and the sample rate was set to 24Mhz (top toolbar). The CAN decoder was added (yellow and green \"bubble icon\" right top toolbar). The D0 channel was labeled as RX and set to trigger on a falling edge (click on black D0 label at left). The D1 channel was labeled as TX (click on brown D1 label at left). The CAN decoder was configured for 1Mbit rate (click on green CAN label at left). The CAN decoder was moved to the top of the display (click and drag green CAN label). Finally, the capture was started (click \"Run\" at top left) and a packet was transmitted on the CAN bus ( cansend can0 123#121212121212 ). The logic analyzer provides an independent tool for capturing packets and verifying bit timing.","title":"Using a logic analyzer on the canbus wiring"},{"location":"CANBUS_protocol.html","text":"CANBUS protocol \u00b6 This document describes the protocol Klipper uses to communicate over CAN bus . See CANBUS.md for information on configuring Klipper with CAN bus. Micro-controller id assignment \u00b6 Klipper uses only CAN 2.0A standard size CAN bus packets, which are limited to 8 data bytes and an 11-bit CAN bus identifier. In order to support efficient communication, each micro-controller is assigned at run-time a unique 1-byte CAN bus nodeid ( canbus_nodeid ) for general Klipper command and response traffic. Klipper command messages going from host to micro-controller use the CAN bus id of canbus_nodeid * 2 + 256 , while Klipper response messages from micro-controller to host use canbus_nodeid * 2 + 256 + 1 . Each micro-controller has a factory assigned unique chip identifier that is used during id assignment. This identifier can exceed the length of one CAN packet, so a hash function is used to generate a unique 6-byte id ( canbus_uuid ) from the factory id. Admin messages \u00b6 Admin messages are used for id assignment. Admin messages sent from host to micro-controller use the CAN bus id 0x3f0 and messages sent from micro-controller to host use the CAN bus id 0x3f1 . All micro-controllers listen to messages on id 0x3f0 ; that id can be thought of as a \"broadcast address\". CMD_QUERY_UNASSIGNED message \u00b6 This command queries all micro-controllers that have not yet been assigned a canbus_nodeid . Unassigned micro-controllers will respond with a RESP_NEED_NODEID response message. The CMD_QUERY_UNASSIGNED message format is: <1-byte message_id = 0x00> CMD_SET_KLIPPER_NODEID message \u00b6 This command assigns a canbus_nodeid to the micro-controller with a given canbus_uuid . The CMD_SET_KLIPPER_NODEID message format is: <1-byte message_id = 0x01><6-byte canbus_uuid><1-byte canbus_nodeid> RESP_NEED_NODEID message \u00b6 The RESP_NEED_NODEID message format is: <1-byte message_id = 0x20><6-byte canbus_uuid><1-byte set_klipper_nodeid = 0x01> Data Packets \u00b6 A micro-controller that has been assigned a nodeid via the CMD_SET_KLIPPER_NODEID command can send and receive data packets. The packet data in messages using the node's receive CAN bus id ( canbus_nodeid * 2 + 256 ) are simply appended to a buffer, and when a complete mcu protocol message is found its contents are parsed and processed. The data is treated as a byte stream - there is no requirement for the start of a Klipper message block to align with the start of a CAN bus packet. Similarly, mcu protocol message responses are sent from micro-controller to host by copying the message data into one or more packets with the node's transmit CAN bus id ( canbus_nodeid * 2 + 256 + 1 ).","title":"CANBUS protocol"},{"location":"CANBUS_protocol.html#canbus-protocol","text":"This document describes the protocol Klipper uses to communicate over CAN bus . See CANBUS.md for information on configuring Klipper with CAN bus.","title":"CANBUS protocol"},{"location":"CANBUS_protocol.html#micro-controller-id-assignment","text":"Klipper uses only CAN 2.0A standard size CAN bus packets, which are limited to 8 data bytes and an 11-bit CAN bus identifier. In order to support efficient communication, each micro-controller is assigned at run-time a unique 1-byte CAN bus nodeid ( canbus_nodeid ) for general Klipper command and response traffic. Klipper command messages going from host to micro-controller use the CAN bus id of canbus_nodeid * 2 + 256 , while Klipper response messages from micro-controller to host use canbus_nodeid * 2 + 256 + 1 . Each micro-controller has a factory assigned unique chip identifier that is used during id assignment. This identifier can exceed the length of one CAN packet, so a hash function is used to generate a unique 6-byte id ( canbus_uuid ) from the factory id.","title":"Micro-controller id assignment"},{"location":"CANBUS_protocol.html#admin-messages","text":"Admin messages are used for id assignment. Admin messages sent from host to micro-controller use the CAN bus id 0x3f0 and messages sent from micro-controller to host use the CAN bus id 0x3f1 . All micro-controllers listen to messages on id 0x3f0 ; that id can be thought of as a \"broadcast address\".","title":"Admin messages"},{"location":"CANBUS_protocol.html#cmd_query_unassigned-message","text":"This command queries all micro-controllers that have not yet been assigned a canbus_nodeid . Unassigned micro-controllers will respond with a RESP_NEED_NODEID response message. The CMD_QUERY_UNASSIGNED message format is: <1-byte message_id = 0x00>","title":"CMD_QUERY_UNASSIGNED message"},{"location":"CANBUS_protocol.html#cmd_set_klipper_nodeid-message","text":"This command assigns a canbus_nodeid to the micro-controller with a given canbus_uuid . The CMD_SET_KLIPPER_NODEID message format is: <1-byte message_id = 0x01><6-byte canbus_uuid><1-byte canbus_nodeid>","title":"CMD_SET_KLIPPER_NODEID message"},{"location":"CANBUS_protocol.html#resp_need_nodeid-message","text":"The RESP_NEED_NODEID message format is: <1-byte message_id = 0x20><6-byte canbus_uuid><1-byte set_klipper_nodeid = 0x01>","title":"RESP_NEED_NODEID message"},{"location":"CANBUS_protocol.html#data-packets","text":"A micro-controller that has been assigned a nodeid via the CMD_SET_KLIPPER_NODEID command can send and receive data packets. The packet data in messages using the node's receive CAN bus id ( canbus_nodeid * 2 + 256 ) are simply appended to a buffer, and when a complete mcu protocol message is found its contents are parsed and processed. The data is treated as a byte stream - there is no requirement for the start of a Klipper message block to align with the start of a CAN bus packet. Similarly, mcu protocol message responses are sent from micro-controller to host by copying the message data into one or more packets with the node's transmit CAN bus id ( canbus_nodeid * 2 + 256 + 1 ).","title":"Data Packets"},{"location":"CONTRIBUTING.html","text":"Contributing to Klipper \u00b6 Thank you for contributing to Klipper! This document describes the process for contributing changes to Klipper. Please see the contact page for information on reporting an issue or for details on contacting the developers. Overview of Contribution Process \u00b6 Contributions to Klipper generally follow a high-level process: A submitter starts by creating a GitHub Pull Request when a submission is ready for widespread deployment. When a reviewer is available to review the submission, they will assign themselves to the Pull Request on GitHub. The goal of the review is to look for defects and to check that the submission follows documented guidelines. After a successful review, the reviewer will \"approve the review\" on GitHub and a maintainer will commit the change to the Klipper master branch. When working on enhancements, consider starting (or contributing to) a topic on Klipper Discourse . An ongoing discussion on the forum can improve visibility of development work and may attract others interested in testing new work. What to expect in a review \u00b6 Contributions to Klipper are reviewed before merging. The primary goal of the review process is to check for defects and to check that the submission follows guidelines specified in the Klipper documentation. It is understood that there are many ways to accomplish a task; it is not the intent of the review to discuss the \"best\" implementation. Where possible, review discussions focused on facts and measurements are preferable. The majority of submissions will result in feedback from a review. Be prepared to obtain feedback, provide further details, and to update the submission if needed. Common things a reviewer will look for: Is the submission free of defects and is it ready to be widely deployed? Submitters are expected to test their changes prior to submission. The reviewers look for errors, but they don't, in general, test submissions. An accepted submission is often deployed to thousands of printers within a few weeks of acceptance. Quality of submissions is therefore considered a priority. The main Klipper3d/klipper GitHub repository does not accept experimental work. Submitters should perform experimentation, debugging, and testing in their own repositories. The Klipper Discourse server is a good place to raise awareness of new work and to find users interested in providing real-world feedback. Submissions must pass all regression test cases . When fixing a defect in the code, submitters should have a general understanding of the root cause of that defect, and the fix should target that root cause. Code submissions should not contain excessive debugging code, debugging options, nor run-time debug logging. Comments in code submissions should focus on enhancing code maintenance. Submissions should not contain \"commented out code\" nor excessive comments describing past implementations. There should not be excessive \"todo\" comments. Updates to documentation should not declare that they are a \"work in progress\". Does the submission provide a \"high impact\" benefit to real-world users performing real-world tasks? Reviewers need to identify, at least in their own minds, roughly \"who the target audience is\", a rough scale of \"the size of that audience\", the \"benefit\" they will obtain, how the \"benefit is measured\", and the \"results of those measurement tests\". In most cases this will be obvious to both the submitter and the reviewer, and it is not explicitly stated during a review. Submissions to the master Klipper branch are expected to have a noteworthy target audience. As a general \"rule of thumb\", submissions should target a user base of at least a 100 real-world users. If a reviewer asks for details on the \"benefit\" of a submission, please don't consider it criticism. Being able to understand the real-world benefits of a change is a natural part of a review. When discussing benefits it is preferable to discuss \"facts and measurements\". In general, reviewers are not looking for responses of the form \"someone may find option X useful\", nor are they looking for responses of the form \"this submission adds a feature that firmware X implements\". Instead, it is generally preferable to discuss details on how the quality improvement was measured and what were the results of those measurements - for example, \"tests on Acme X1000 printers show improved corners as seen in picture ...\", or for example \"print time of real-world object X on a Foomatic X900 printer went from 4 hours to 3.5 hours\". It is understood that testing of this type can take significant time and effort. Some of Klipper's most notable features took months of discussion, rework, testing, and documentation prior to being merged into the master branch. All new modules, config options, commands, command parameters, and documents should have \"high impact\". We do not want to burden users with options that they can not reasonably configure nor do we want to burden them with options that don't provide a notable benefit. A reviewer may ask for clarification on how a user is to configure an option - an ideal response will contain details on the process - for example, \"users of the MegaX500 are expected to set option X to 99.3 while users of the Elite100Y are expected to calibrate option X using procedure ...\". If the goal of an option is to make the code more modular then prefer using code constants instead of user facing config options. New modules, new options, and new parameters should not provide similar functionality to existing modules - if the differences are arbitrary than it's preferable to utilize the existing system or refactor the existing code. Is the copyright of the submission clear, non-gratuitous, and compatible? New C files and Python files should have an unambiguous copyright statement. See the existing files for the preferred format. Declaring a copyright on an existing file when making minor changes to that file is discouraged. Code taken from 3rd party sources must be compatible with the Klipper license (GNU GPLv3). Large 3rd party code additions should be added to the lib/ directory (and follow the format described in lib/README ). Submitters must provide a Signed-off-by line using their full real name. It indicates the submitter agrees with the developer certificate of origin . Does the submission follow guidelines specified in the Klipper documentation? In particular, code should follow the guidelines in Code_Overview.md and config files should follow the guidelines in Example_Configs.md . Is the Klipper documentation updated to reflect new changes? At a minimum, the reference documentation must be updated with corresponding changes to the code: All commands and command parameters must be documented in G-Codes.md . All user facing modules and their config parameters must be documented in Config_Reference.md . All exported \"status variables\" must be documented in Status_Reference.md . All new \"webhooks\" and their parameters must be documented in API_Server.md . Any change that makes a non-backwards compatible change to a command or config file setting must be documented in Config_Changes.md . New documents should be added to Overview.md and be added to the website index docs/_klipper3d/mkdocs.yml . Are commits well formed, address a single topic per commit, and independent? Commit messages should follow the preferred format . Commits must not have a merge conflict. New additions to the Klipper master branch are always done via a \"rebase\" or \"squash and rebase\". It is generally not necessary for submitters to re-merge their submission on every update to the Klipper master repository. However, if there is a merge conflict, then submitters are recommended to use git rebase to address the conflict. Each commit should address a single high-level change. Large changes should be broken up into multiple independent commits. Each commit should \"stand on its own\" so that tools like git bisect and git revert work reliably. Whitespace changes should not be mixed with functional changes. In general, gratuitous whitespace changes are not accepted unless they are from the established \"owner\" of the code being modified. Klipper does not implement a strict \"coding style guide\", but modifications to existing code should follow the high-level code flow, code indentation style, and format of that existing code. Submissions of new modules and systems have more flexibility in coding style, but it is preferable for that new code to follow an internally consistent style and to generally follow industry wide coding norms. It is not a goal of a review to discuss \"better implementations\". However, if a reviewer struggles to understand the implementation of a submission, then they may ask for changes to make the implementation more transparent. In particular, if reviewers can not convince themselves that a submission is free of defects then changes may be necessary. As part of a review, a reviewer may create an alternate Pull Request for a topic. This may be done to avoid excessive \"back and forth\" on minor procedural items and thus streamline the submission process. It may also be done because the discussion inspires a reviewer to build an alternative implementation. Both situations are a normal result of a review and should not be considered criticism of the original submission. Helping with reviews \u00b6 We appreciate help with reviews! It is not necessary to be a listed reviewer to perform a review. Submitters of GitHub Pull Requests are also encouraged to review their own submissions. To help with a review, follow the steps outlined in what to expect in a review to verify the submission. After completing the review, add a comment to the GitHub Pull Request with your findings. If the submission passes the review then please state that explicitly in the comment - for example something like \"I reviewed this change according to the steps in the CONTRIBUTING document and everything looks good to me\". If unable to complete some steps in the review then please explicitly state which steps were reviewed and which steps were not reviewed - for example something like \"I didn't check the code for defects, but I reviewed everything else in the CONTRIBUTING document and it looks good\". We also appreciate testing of submissions. If the code was tested then please add a comment to the GitHub Pull Request with the results of your test - success or failure. Please explicitly state that the code was tested and the results - for example something like \"I tested this code on my Acme900Z printer with a vase print and the results were good\". Reviewers \u00b6 The Klipper \"reviewers\" are: Name GitHub Id Areas of interest Dmitry Butyugin @dmbutyugin Input shaping, resonance testing, kinematics Eric Callahan @Arksine Bed leveling, MCU flashing James Hartley @JamesH1978 Configuration files Kevin O'Connor @KevinOConnor Core motion system, Micro-controller code Please do not \"ping\" any of the reviewers and please do not direct submissions at them. All of the reviewers monitor the forums and PRs, and will take on reviews when they have time to. The Klipper \"maintainers\" are: Name GitHub name Kevin O'Connor @KevinOConnor Format of commit messages \u00b6 Each commit should have a commit message formatted similar to the following: module: Capitalized, short (50 chars or less) summary More detailed explanatory text, if necessary. Wrap it to about 75 characters or so. In some contexts, the first line is treated as the subject of an email and the rest of the text as the body. The blank line separating the summary from the body is critical (unless you omit the body entirely); tools like rebase can get confused if you run the two together. Further paragraphs come after blank lines.. Signed-off-by: My Name In the above example, module should be the name of a file or directory in the repository (without a file extension). For example, clocksync: Fix typo in pause() call at connect time . The purpose of specifying a module name in the commit message is to help provide context for the commit comments. It is important to have a \"Signed-off-by\" line on each commit - it certifies that you agree to the developer certificate of origin . It must contain your real name (sorry, no pseudonyms or anonymous contributions) and contain a current email address. Contributing to Klipper Translations \u00b6 Klipper-translations Project is a project dedicated to translating Klipper to different languages. Weblate hosts all the Gettext strings for translating and reviewing. Locales can be displayed on klipper3d.org once they satisfy the following requirements: 75% Total coverage All titles (H1) are translated An updated navigation hierarchy PR in klipper-translations. To reduce the frustration of translating domain-specific terms and gain awareness of the ongoing translations, you can submit a PR modifying the Klipper-translations Project readme.md . Once a translation is ready, the corresponding modification to the Klipper project can be made. If a translation already exists in the Klipper repository and no longer meets the checklist above, it will be marked out-of-date after a month without updates. Once the requirements are met, you need to: update klipper-translations repository active_translations Optional: add a manual-index.md file in klipper-translations repository's docs\\locals\\ 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 In the above example, module should be the name of a file or directory in the repository (without a file extension). For example, clocksync: Fix typo in pause() call at connect time . The purpose of specifying a module name in the commit message is to help provide context for the commit comments. It is important to have a \"Signed-off-by\" line on each commit - it certifies that you agree to the developer certificate of origin . It must contain your real name (sorry, no pseudonyms or anonymous contributions) and contain a current email address.","title":"Format of commit messages"},{"location":"CONTRIBUTING.html#contributing-to-klipper-translations","text":"Klipper-translations Project is a project dedicated to translating Klipper to different languages. Weblate hosts all the Gettext strings for translating and reviewing. Locales can be displayed on klipper3d.org once they satisfy the following requirements: 75% Total coverage All titles (H1) are translated An updated navigation hierarchy PR in klipper-translations. To reduce the frustration of translating domain-specific terms and gain awareness of the ongoing translations, you can submit a PR modifying the Klipper-translations Project readme.md . Once a translation is ready, the corresponding modification to the Klipper project can be made. If a translation already exists in the Klipper repository and no longer meets the checklist above, it will be marked out-of-date after a month without updates. Once the requirements are met, you need to: update klipper-translations repository active_translations Optional: add a manual-index.md file in klipper-translations repository's docs\\locals\\ folder to replace the language specific index.md (generated index.md does not render correctly). Known Issues: Currently, there isn't a method for correctly translating pictures in the documentation It is impossible to translate titles in mkdocs.yml.","title":"Contributing to Klipper Translations"},{"location":"Code_Overview.html","text":"Code overview \u00b6 This document describes the overall code layout and major code flow of Klipper. Directory Layout \u00b6 The src/ directory contains the C source for the micro-controller code. The src/atsam/ , src/atsamd/ , src/avr/ , src/linux/ , src/lpc176x/ , src/pru/ , and src/stm32/ directories contain architecture specific micro-controller code. The src/simulator/ contains code stubs that allow the micro-controller to be test compiled on other architectures. The src/generic/ directory contains helper code that may be useful across different architectures. The build arranges for includes of \"board/somefile.h\" to first look in the current architecture directory (eg, src/avr/somefile.h) and then in the generic directory (eg, src/generic/somefile.h). The klippy/ directory contains the host software. Most of the host software is written in Python, however the klippy/chelper/ directory contains some C code helpers. The klippy/kinematics/ directory contains the robot kinematics code. The klippy/extras/ directory contains the host code extensible \"modules\". The lib/ directory contains external 3rd-party library code that is necessary to build some targets. The config/ directory contains example printer configuration files. The scripts/ directory contains build-time scripts useful for compiling the micro-controller code. The test/ directory contains automated test cases. During compilation, the build may create an out/ directory. This contains temporary build time objects. The final micro-controller object that is built is out/klipper.elf.hex on AVR and out/klipper.bin on ARM. Micro-controller code flow \u00b6 Execution of the micro-controller code starts in architecture specific code (eg, src/avr/main.c ) which ultimately calls sched_main() located in src/sched.c . The sched_main() code starts by running all functions that have been tagged with the DECL_INIT() macro. It then goes on to repeatedly run all functions tagged with the DECL_TASK() macro. One of the main task functions is command_dispatch() located in src/command.c . This function is called from the board specific input/output code (eg, src/avr/serial.c , src/generic/serial_irq.c ) and it runs the command functions associated with the commands found in the input stream. Command functions are declared using the DECL_COMMAND() macro (see the protocol document for more information). Task, init, and command functions always run with interrupts enabled (however, they can temporarily disable interrupts if needed). These functions should avoid long pauses, delays, or do work that lasts a significant time. (Long delays in these \"task\" functions result in scheduling jitter for other \"tasks\" - delays over 100us may become noticeable, delays over 500us may result in command retransmissions, delays over 100ms may result in watchdog reboots.) These functions schedule work at specific times by scheduling timers. Timer functions are scheduled by calling sched_add_timer() (located in src/sched.c ). The scheduler code will arrange for the given function to be called at the requested clock time. Timer interrupts are initially handled in an architecture specific interrupt handler (eg, src/avr/timer.c ) which calls sched_timer_dispatch() located in src/sched.c . The timer interrupt leads to execution of schedule timer functions. Timer functions always run with interrupts disabled. The timer functions should always complete within a few micro-seconds. At completion of the timer event, the function may choose to reschedule itself. In the event an error is detected the code can invoke shutdown() (a macro which calls sched_shutdown() located in src/sched.c ). Invoking shutdown() causes all functions tagged with the DECL_SHUTDOWN() macro to be run. Shutdown functions always run with interrupts disabled. Much of the functionality of the micro-controller involves working with General-Purpose Input/Output pins (GPIO). In order to abstract the low-level architecture specific code from the high-level task code, all GPIO events are implemented in architecture specific wrappers (eg, src/avr/gpio.c ). The code is compiled with gcc's \"-flto -fwhole-program\" optimization which does an excellent job of inlining functions across compilation units, so most of these tiny gpio functions are inlined into their callers, and there is no run-time cost to using them. Klippy code overview \u00b6 The host code (Klippy) is intended to run on a low-cost computer (such as a Raspberry Pi) paired with the micro-controller. The code is primarily written in Python, however it does use CFFI to implement some functionality in C code. Initial execution starts in klippy/klippy.py . This reads the command-line arguments, opens the printer config file, instantiates the main printer objects, and starts the serial connection. The main execution of G-code commands is in the _process_commands() method in klippy/gcode.py . This code translates the G-code commands into printer object calls, which frequently translate the actions to commands to be executed on the micro-controller (as declared via the DECL_COMMAND macro in the micro-controller code). There are several threads in the Klipper host code: There is a Python \"main thread\" that handles incoming G-Code commands and is the starting point for most actions. This thread runs the reactor ( klippy/reactor.py ) and most high-level actions originate from IO and timer event callbacks from that reactor. A thread for writing messages to the log so that the other threads do not block on log writes. This thread resides in the klippy/queuelogger.py code and its multi-threaded nature is not exposed to the main Python thread. A thread per micro-controller that performs the low-level reading and writing of messages to that micro-controller. It resides in the klippy/chelper/serialqueue.c C code and its multi-threaded nature is not exposed to the Python code. A thread per micro-controller for processing messages received from that micro-controller in the Python code. This thread is created in klippy/serialhdl.py . Care must be taken in Python callbacks invoked from this thread as this thread may directly interact with the main Python thread. A thread per stepper motor that calculates the timing of stepper motor step pulses and compresses those times. This thread resides in the klippy/chelper/steppersync.c C code and its multi-threaded nature is not exposed to the Python code. Code flow of a move command \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() , then ToolHead.move() -> ToolHead._process_lookahead() -> LookAheadQueue.flush() -> Move.set_junction() , and then ToolHead._process_lookahead() -> trapq_append() . ToolHead.move() creates a Move() object with the parameters of the move (in cartesian space and in units of seconds and millimeters). The kinematics class is given the opportunity to audit each move ( ToolHead.move() -> kin.check_move() ). The kinematics classes are located in the klippy/kinematics/ directory. The check_move() code may raise an error if the move is not valid. If check_move() completes successfully then the underlying kinematics must be able to handle the move. LookAheadQueue.add_move() places the move object on the \"look-ahead\" queue. LookAheadQueue.flush() determines the start and end velocities of each move. Move.set_junction() implements the \"trapezoid generator\" on a move. The \"trapezoid generator\" breaks every move into three parts: a constant acceleration phase, followed by a constant velocity phase, followed by a constant deceleration phase. Every move contains these three phases in this order, but some phases may be of zero duration. When ToolHead._process_lookahead() resumes, everything about the move is known - its start location, its end location, its acceleration, its start/cruising/end velocity, and distance traveled during acceleration/cruising/deceleration. All the information is stored in the Move() class and is in cartesian space in units of millimeters and seconds. The moves are then placed on a \"trapezoid motion queue\" via trapq_append() (in klippy/chelper/trapq.c). The trapq stores all the information in the Move() class in a C struct accessible to the host C code. Note that the extruder is handled in its own kinematic class: ToolHead._process_lookahead() -> PrinterExtruder.process_move() . Since the Move() class specifies the exact movement time and since step pulses are sent to the micro-controller with specific timing, stepper movements produced by the extruder class will be in sync with head movement even though the code is kept separate. For efficiency reasons, stepper motion is generated in the C code in a thread per stepper motor. The threads are notified when steps should be generated by the motion_queuing module (klippy/extras/motion_queuing.py): PrinterMotionQueuing._flush_handler() -> PrinterMotionQueuing._advance_move_time() -> steppersyncmgr_gen_steps() -> se_start_gen_steps() . Klipper uses an iterative solver to generate the step times for each stepper. The step times are generated from the background thread (klippy/chelper/steppersync.c): se_background_thread() -> se_generate_steps() -> itersolve_generate_steps() -> itersolve_gen_steps_range() (in klippy/chelper/itersolve.c). The goal of the iterative solver is to find step times given a function that calculates a stepper position from a time. This is done by repeatedly \"guessing\" various times until the stepper position formula returns the desired position of the next step on the stepper. The feedback produced from each guess is used to improve future guesses so that the process rapidly converges to the desired time. The kinematic stepper position formulas are located in the klippy/chelper/ directory (eg, kin_cart.c, kin_corexy.c, kin_delta.c, kin_extruder.c). After the iterative solver calculates the step times they are added to an array: itersolve_gen_steps_range() -> stepcompress_append() (in klippy/chelper/stepcompress.c). The array (struct stepcompress.queue) stores the corresponding micro-controller clock counter times for every step. Here the \"micro-controller clock counter\" value directly corresponds to the micro-controller's hardware counter - it is relative to when the micro-controller was last powered up. The next major step is to compress the steps: stepcompress_flush() -> compress_bisect_add() (in klippy/chelper/stepcompress.c). This code generates and encodes a series of micro-controller \"queue_step\" commands that correspond to the list of stepper step times built in the previous stage. These \"queue_step\" commands are then queued, prioritized, and sent to the micro-controller (via steppersync.c:steppersync and serialqueue.c:serialqueue). Processing of the queue_step commands on the micro-controller starts in src/command.c which parses the command and calls command_queue_step() . The command_queue_step() code (in src/stepper.c) just appends the parameters of each queue_step command to a per stepper queue. Under normal operation the queue_step command is parsed and queued at least 100ms before the time of its first step. Finally, the generation of stepper events is done in stepper_event() . It's called from the hardware timer interrupt at the scheduled time of the first step. The stepper_event() code generates a step pulse and then reschedules itself to run at the time of the next step pulse for the given queue_step parameters. The parameters for each queue_step command are \"interval\", \"count\", and \"add\". At a high-level, stepper_event() runs the following, 'count' times: do_step(); next_wake_time = last_wake_time + interval; interval += add; The above may seem like a lot of complexity to execute a movement. However, the only really interesting parts are in the ToolHead and kinematic classes. It's this part of the code which specifies the movements and their timings. The remaining parts of the processing is mostly just communication and plumbing. Adding a host module \u00b6 The Klippy host code has a dynamic module loading capability. If a config section named \"[my_module]\" is found in the printer config file then the software will automatically attempt to load the python module klippy/extras/my_module.py . This module system is the preferred method for adding new functionality to Klipper. The easiest way to add a new module is to use an existing module as a reference - see klippy/extras/servo.py as an example. The following may also be useful: Execution of the module starts in the module level load_config() function (for config sections of the form [my_module]) or in load_config_prefix() (for config sections of the form [my_module my_name]). This function is passed a \"config\" object and it must return a new \"printer object\" associated with the given config section. During the process of instantiating a new printer object, the config object can be used to read parameters from the given config section. This is done using config.get() , config.getfloat() , config.getint() , etc. methods. Be sure to read all values from the config during the construction of the printer object - if the user specifies a config parameter that is not read during this phase then it will be assumed it is a typo in the config and an error will be raised. Use the config.get_printer() method to obtain a reference to the main \"printer\" class. This \"printer\" class stores references to all the \"printer objects\" that have been instantiated. Use the printer.lookup_object() method to find references to other printer objects. Almost all functionality (even core kinematic modules) are encapsulated in one of these printer objects. Note, though, that when a new module is instantiated, not all other printer objects will have been instantiated. The \"gcode\" and \"pins\" modules will always be available, but for other modules it is a good idea to defer the lookup. Register event handlers using the printer.register_event_handler() method if the code needs to be called during \"events\" raised by other printer objects. Each event name is a string, and by convention it is the name of the main source module that raises the event along with a short name for the action that is occurring (eg, \"klippy:connect\"). The parameters passed to each event handler are specific to the given event (as are exception handling and execution context). Two common startup events are: klippy:connect - This event is generated after all printer objects are instantiated. It is commonly used to lookup other printer objects, to verify config settings, and to perform an initial \"handshake\" with printer hardware. klippy:ready - This event is generated after all connect handlers have completed successfully. It indicates the printer is transitioning to a state ready to handle normal operations. Do not raise an error in this callback. If there is an error in the user's config, be sure to raise it during the load_config() or \"connect event\" phases. Use either raise config.error(\"my error\") or raise printer.config_error(\"my error\") to report the error. Do not store a reference to the config object in a class member variable (nor in any similar location that may persist past initial module loading). The config object is a reference to a \"config loading phase\" class and it is not valid to invoke its methods after the \"config loading phase\" has completed. Use the \"pins\" module to configure a pin on a micro-controller. This is typically done with something similar to printer.lookup_object(\"pins\").setup_pin(\"pwm\", config.get(\"my_pin\")) . The returned object can then be commanded at run-time. If the printer object defines a get_status() method then the module can export status information via macros and via the API Server . The get_status() method must return a Python dictionary with keys that are strings and values that are integers, floats, strings, lists, dictionaries, True, False, or None. Tuples (and named tuples) may also be used (these appear as lists when accessed via the API Server). Lists and dictionaries that are exported must be treated as \"immutable\" - if their contents change then a new object must be returned from get_status() , otherwise the API Server will not detect those changes. If the module needs access to system timing or external file descriptors then use printer.get_reactor() to obtain access to the global \"event reactor\" class. This reactor class allows one to schedule timers, wait for input on file descriptors, and to \"sleep\" the host code. Do not use global variables. All state should be stored in the printer object returned from the load_config() function. This is important as otherwise the RESTART command may not perform as expected. Also, for similar reasons, if any external files (or sockets) are opened then be sure to register a \"klippy:disconnect\" event handler and close them from that callback. Avoid accessing the internal member variables (or calling methods that start with an underscore) of other printer objects. Observing this convention makes it easier to manage future changes. It is recommended to assign a value to all member variables in the Python constructor of Python classes. (And therefore avoid utilizing Python's ability to dynamically create new member variables.) If a Python variable is to store a floating point value then it is recommended to always assign and manipulate that variable with floating point constants (and never use integer constants). For example, prefer self.speed = 1. over self.speed = 1 , and prefer self.speed = 2. * x over self.speed = 2 * x . Consistent use of floating point values can avoid hard to debug quirks in Python type conversions. If submitting the module for inclusion in the main Klipper code, be sure to place a copyright notice at the top of the module. See the existing modules for the preferred format. Adding new kinematics \u00b6 This section provides some tips on adding support to Klipper for additional types of printer kinematics. This type of activity requires excellent understanding of the math formulas for the target kinematics. It also requires software development skills - though one should only need to update the host software. Useful steps: Start by studying the \" code flow of a move \" section and the Kinematics document . Review the existing kinematic classes in the klippy/kinematics/ directory. The kinematic classes are tasked with converting a move in cartesian coordinates to the movement on each stepper. One should be able to copy one of these files as a starting point. Implement the C stepper kinematic position functions for each stepper if they are not already available (see kin_cart.c, kin_corexy.c, and kin_delta.c in klippy/chelper/). The function should call move_get_coord() to convert a given move time (in seconds) to a cartesian coordinate (in millimeters), and then calculate the desired stepper position (in millimeters) from that cartesian coordinate. Implement the calc_position() method in the new kinematics class. This method calculates the position of the toolhead in cartesian coordinates from the position of each stepper. It does not need to be efficient as it is typically only called during homing and probing operations. Other methods. Implement the check_move() , get_status() , get_steppers() , home() , clear_homing_state() , and set_position() methods. These functions are typically used to provide kinematic specific checks. However, at the start of development one can use boiler-plate code here. Implement test cases. Create a g-code file with a series of moves that can test important cases for the given kinematics. Follow the debugging documentation to convert this g-code file to micro-controller commands. This is useful to exercise corner cases and to check for regressions. Porting to a new micro-controller \u00b6 This section provides some tips on porting Klipper's micro-controller code to a new architecture. This type of activity requires good knowledge of embedded development and hands-on access to the target micro-controller. Useful steps: Start by identifying any 3rd party libraries that will be used during the port. Common examples include \"CMSIS\" wrappers and manufacturer \"HAL\" libraries. All 3rd party code needs to be GNU GPLv3 compatible. The 3rd party code should be committed to the Klipper lib/ directory. Update the lib/README file with information on where and when the library was obtained. It is preferable to copy the code into the Klipper repository unchanged, but if any changes are required then those changes should be listed explicitly in the lib/README file. Create a new architecture sub-directory in the src/ directory and add initial Kconfig and Makefile support. Use the existing architectures as a guide. The src/simulator provides a basic example of a minimum starting point. The first main coding task is to bring up communication support to the target board. This is the most difficult step in a new port. Once basic communication is working, the remaining steps tend to be much easier. It is typical to use a UART type serial device during initial development as these types of hardware devices are generally easier to enable and control. During this phase, make liberal use of helper code from the src/generic/ directory (check how src/simulator/Makefile includes the generic C code into the build). It is also necessary to define timer_read_time() (which returns the current system clock) in this phase, but it is not necessary to fully support timer irq handling. Get familiar with the the console.py tool (as described in the debugging document ) and verify connectivity to the micro-controller with it. This tool translates the low-level micro-controller communication protocol to a human readable form. Add support for timer dispatch from hardware interrupts. See Klipper commit 970831ee as an example of steps 1-5 done for the LPC176x architecture. Bring up basic GPIO input and output support. See Klipper commit c78b9076 as an example of this. Bring up additional peripherals - for example see Klipper commit 65613aed , c812a40a , and c381d03a . Create a sample Klipper config file in the config/ directory. Test the micro-controller with the main klippy.py program. Consider adding build test cases in the test/ directory. Additional coding tips: Avoid using \"C bitfields\" to access IO registers; prefer direct read and write operations of 32bit, 16bit, or 8bit integers. The C language specifications don't clearly specify how the compiler must implement C bitfields (eg, endianness, and bit layout), and it's difficult to determine what IO operations will occur on a C bitfield read or write. Prefer writing explicit values to IO registers instead of using read-modify-write operations. That is, if updating a field in an IO register where the other fields have known values, then it is preferable to explicitly write the full contents of the register. Explicit writes produce code that is smaller, faster, and easier to debug. Coordinate Systems \u00b6 Internally, Klipper primarily tracks the position of the toolhead in cartesian coordinates that are relative to the coordinate system specified in the config file. That is, most of the Klipper code will never experience a change in coordinate systems. If the user makes a request to change the origin (eg, a G92 command) then that effect is obtained by translating future commands to the primary coordinate system. However, in some cases it is useful to obtain the toolhead position in some other coordinate system and Klipper has several tools to facilitate that. This can be seen by running the GET_POSITION command. For example: Send: GET_POSITION Recv: // mcu: stepper_a:-2060 stepper_b:-1169 stepper_c:-1613 Recv: // stepper: stepper_a:457.254159 stepper_b:466.085669 stepper_c:465.382132 Recv: // kinematic: X:8.339144 Y:-3.131558 Z:233.347121 Recv: // toolhead: X:8.338078 Y:-3.123175 Z:233.347878 E:0.000000 Recv: // gcode: X:8.338078 Y:-3.123175 Z:233.347878 E:0.000000 Recv: // gcode base: X:0.000000 Y:0.000000 Z:0.000000 E:0.000000 Recv: // gcode homing: X:0.000000 Y:0.000000 Z:0.000000 The \"mcu\" position ( stepper.get_mcu_position() in the code) is the total number of steps the micro-controller has issued in a positive direction minus the number of steps issued in a negative direction since the micro-controller was last reset. If the robot is in motion when the query is issued then the reported value includes moves buffered on the micro-controller, but does not include moves on the look-ahead queue. The \"stepper\" position ( stepper.get_commanded_position() ) is the position of the given stepper as tracked by the kinematics code. This generally corresponds to the position (in mm) of the carriage along its rail, relative to the position_endstop specified in the config file. (Some kinematics track stepper positions in radians instead of millimeters.) If the robot is in motion when the query is issued then the reported value includes moves buffered on the micro-controller, but does not include moves on the look-ahead queue. One may use the toolhead.flush_step_generation() or toolhead.wait_moves() calls to fully flush the look-ahead and step generation code. The \"kinematic\" position ( kin.calc_position() ) is the cartesian position of the toolhead as derived from \"stepper\" positions and is relative to the coordinate system specified in the config file. This may differ from the requested cartesian position due to the granularity of the stepper motors. If the robot is in motion when the \"stepper\" positions are taken then the reported value includes moves buffered on the micro-controller, but does not include moves on the look-ahead queue. One may use the toolhead.flush_step_generation() or toolhead.wait_moves() calls to fully flush the look-ahead and step generation code. The \"toolhead\" position ( toolhead.get_position() ) is the last requested position of the toolhead in cartesian coordinates relative to the coordinate system specified in the config file. If the robot is in motion when the query is issued then the reported value includes all requested moves (even those in buffers waiting to be issued to the stepper motor drivers). The \"gcode\" position is the last requested position from a G1 (or G0 ) command in cartesian coordinates relative to the coordinate system specified in the config file. This may differ from the \"toolhead\" position if a g-code transformation (eg, bed_mesh, bed_tilt, skew_correction) is in effect. This may differ from the actual coordinates specified in the last G1 command if the g-code origin has been changed (eg, G92 , SET_GCODE_OFFSET , M221 ). The M114 command ( gcode_move.get_status()['gcode_position'] ) will report the last g-code position relative to the current g-code coordinate system. The \"gcode base\" is the location of the g-code origin in cartesian coordinates relative to the coordinate system specified in the config file. Commands such as G92 , SET_GCODE_OFFSET , and M221 alter this value. The \"gcode homing\" is the location to use for the g-code origin (in cartesian coordinates relative to the coordinate system specified in the config file) after a G28 home command. The SET_GCODE_OFFSET command can alter this value. Time \u00b6 Fundamental to the operation of Klipper is the handling of clocks, times, and timestamps. Klipper executes actions on the printer by scheduling events to occur in the near future. For example, to turn on a fan, the code might schedule a change to a GPIO pin in a 100ms. It is rare for the code to attempt to take an instantaneous action. Thus, the handling of time within Klipper is critical to correct operation. There are three types of times tracked internally in the Klipper host software: System time. The system time uses the system's monotonic clock - it is a floating point number stored as seconds and it is (generally) relative to when the host computer was last started. System times have limited use in the software - they are primarily used when interacting with the operating system. Within the host code, system times are frequently stored in variables named eventtime or curtime . Print time. The print time is synchronized to the main micro-controller clock (the micro-controller defined in the \"[mcu]\" config section). It is a floating point number stored as seconds and is relative to when the main mcu was last restarted. It is possible to convert from a \"print time\" to the main micro-controller's hardware clock by multiplying the print time by the mcu's statically configured frequency rate. The high-level host code uses print times to calculate almost all physical actions (eg, head movement, heater changes, etc.). Within the host code, print times are generally stored in variables named print_time or move_time . MCU clock. This is the hardware clock counter on each micro-controller. It is stored as an integer and its update rate is relative to the frequency of the given micro-controller. The host software translates its internal times to clocks before transmission to the mcu. The mcu code only ever tracks time in clock ticks. Within the host code, clock values are tracked as 64bit integers, while the mcu code uses 32bit integers. Within the host code, clocks are generally stored in variables with names containing clock or ticks . Conversion between the different time formats is primarily implemented in the klippy/clocksync.py code. Some things to be aware of when reviewing the code: 32bit and 64bit clocks: To reduce bandwidth and to improve micro-controller efficiency, clocks on the micro-controller are tracked as 32bit integers. When comparing two clocks in the mcu code, the timer_is_before() function must always be used to ensure integer rollovers are handled properly. The host software converts 32bit clocks to 64bit clocks by appending the high-order bits from the last mcu timestamp it has received - no message from the mcu is ever more than 2^31 clock ticks in the future or past so this conversion is never ambiguous. The host converts from 64bit clocks to 32bit clocks by simply truncating the high-order bits. To ensure there is no ambiguity in this conversion, the klippy/chelper/serialqueue.c code will buffer messages until they are within 2^31 clock ticks of their target time. Multiple micro-controllers: The host software supports using multiple micro-controllers on a single printer. In this case, the \"MCU clock\" of each micro-controller is tracked separately. The clocksync.py code handles clock drift between micro-controllers by modifying the way it converts from \"print time\" to \"MCU clock\". On secondary mcus, the mcu frequency that is used in this conversion is regularly updated to account for measured drift.","title":"Code overview"},{"location":"Code_Overview.html#code-overview","text":"This document describes the overall code layout and major code flow of Klipper.","title":"Code overview"},{"location":"Code_Overview.html#directory-layout","text":"The src/ directory contains the C source for the micro-controller code. The src/atsam/ , src/atsamd/ , src/avr/ , src/linux/ , src/lpc176x/ , src/pru/ , and src/stm32/ directories contain architecture specific micro-controller code. The src/simulator/ contains code stubs that allow the micro-controller to be test compiled on other architectures. The src/generic/ directory contains helper code that may be useful across different architectures. The build arranges for includes of \"board/somefile.h\" to first look in the current architecture directory (eg, src/avr/somefile.h) and then in the generic directory (eg, src/generic/somefile.h). The klippy/ directory contains the host software. Most of the host software is written in Python, however the klippy/chelper/ directory contains some C code helpers. The klippy/kinematics/ directory contains the robot kinematics code. The klippy/extras/ directory contains the host code extensible \"modules\". The lib/ directory contains external 3rd-party library code that is necessary to build some targets. The config/ directory contains example printer configuration files. The scripts/ directory contains build-time scripts useful for compiling the micro-controller code. The test/ directory contains automated test cases. During compilation, the build may create an out/ directory. This contains temporary build time objects. The final micro-controller object that is built is out/klipper.elf.hex on AVR and out/klipper.bin on ARM.","title":"Directory Layout"},{"location":"Code_Overview.html#micro-controller-code-flow","text":"Execution of the micro-controller code starts in architecture specific code (eg, src/avr/main.c ) which ultimately calls sched_main() located in src/sched.c . The sched_main() code starts by running all functions that have been tagged with the DECL_INIT() macro. It then goes on to repeatedly run all functions tagged with the DECL_TASK() macro. One of the main task functions is command_dispatch() located in src/command.c . This function is called from the board specific input/output code (eg, src/avr/serial.c , src/generic/serial_irq.c ) and it runs the command functions associated with the commands found in the input stream. Command functions are declared using the DECL_COMMAND() macro (see the protocol document for more information). Task, init, and command functions always run with interrupts enabled (however, they can temporarily disable interrupts if needed). These functions should avoid long pauses, delays, or do work that lasts a significant time. (Long delays in these \"task\" functions result in scheduling jitter for other \"tasks\" - delays over 100us may become noticeable, delays over 500us may result in command retransmissions, delays over 100ms may result in watchdog reboots.) These functions schedule work at specific times by scheduling timers. Timer functions are scheduled by calling sched_add_timer() (located in src/sched.c ). The scheduler code will arrange for the given function to be called at the requested clock time. Timer interrupts are initially handled in an architecture specific interrupt handler (eg, src/avr/timer.c ) which calls sched_timer_dispatch() located in src/sched.c . The timer interrupt leads to execution of schedule timer functions. Timer functions always run with interrupts disabled. The timer functions should always complete within a few micro-seconds. At completion of the timer event, the function may choose to reschedule itself. In the event an error is detected the code can invoke shutdown() (a macro which calls sched_shutdown() located in src/sched.c ). Invoking shutdown() causes all functions tagged with the DECL_SHUTDOWN() macro to be run. Shutdown functions always run with interrupts disabled. Much of the functionality of the micro-controller involves working with General-Purpose Input/Output pins (GPIO). In order to abstract the low-level architecture specific code from the high-level task code, all GPIO events are implemented in architecture specific wrappers (eg, src/avr/gpio.c ). The code is compiled with gcc's \"-flto -fwhole-program\" optimization which does an excellent job of inlining functions across compilation units, so most of these tiny gpio functions are inlined into their callers, and there is no run-time cost to using them.","title":"Micro-controller code flow"},{"location":"Code_Overview.html#klippy-code-overview","text":"The host code (Klippy) is intended to run on a low-cost computer (such as a Raspberry Pi) paired with the micro-controller. The code is primarily written in Python, however it does use CFFI to implement some functionality in C code. Initial execution starts in klippy/klippy.py . This reads the command-line arguments, opens the printer config file, instantiates the main printer objects, and starts the serial connection. The main execution of G-code commands is in the _process_commands() method in klippy/gcode.py . This code translates the G-code commands into printer object calls, which frequently translate the actions to commands to be executed on the micro-controller (as declared via the DECL_COMMAND macro in the micro-controller code). There are several threads in the Klipper host code: There is a Python \"main thread\" that handles incoming G-Code commands and is the starting point for most actions. This thread runs the reactor ( klippy/reactor.py ) and most high-level actions originate from IO and timer event callbacks from that reactor. A thread for writing messages to the log so that the other threads do not block on log writes. This thread resides in the klippy/queuelogger.py code and its multi-threaded nature is not exposed to the main Python thread. A thread per micro-controller that performs the low-level reading and writing of messages to that micro-controller. It resides in the klippy/chelper/serialqueue.c C code and its multi-threaded nature is not exposed to the Python code. A thread per micro-controller for processing messages received from that micro-controller in the Python code. This thread is created in klippy/serialhdl.py . Care must be taken in Python callbacks invoked from this thread as this thread may directly interact with the main Python thread. A thread per stepper motor that calculates the timing of stepper motor step pulses and compresses those times. This thread resides in the klippy/chelper/steppersync.c C code and its multi-threaded nature is not exposed to the Python code.","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() , then ToolHead.move() -> ToolHead._process_lookahead() -> LookAheadQueue.flush() -> Move.set_junction() , and then ToolHead._process_lookahead() -> trapq_append() . ToolHead.move() creates a Move() object with the parameters of the move (in cartesian space and in units of seconds and millimeters). The kinematics class is given the opportunity to audit each move ( ToolHead.move() -> kin.check_move() ). The kinematics classes are located in the klippy/kinematics/ directory. The check_move() code may raise an error if the move is not valid. If check_move() completes successfully then the underlying kinematics must be able to handle the move. LookAheadQueue.add_move() places the move object on the \"look-ahead\" queue. LookAheadQueue.flush() determines the start and end velocities of each move. Move.set_junction() implements the \"trapezoid generator\" on a move. The \"trapezoid generator\" breaks every move into three parts: a constant acceleration phase, followed by a constant velocity phase, followed by a constant deceleration phase. Every move contains these three phases in this order, but some phases may be of zero duration. When ToolHead._process_lookahead() resumes, everything about the move is known - its start location, its end location, its acceleration, its start/cruising/end velocity, and distance traveled during acceleration/cruising/deceleration. All the information is stored in the Move() class and is in cartesian space in units of millimeters and seconds. The moves are then placed on a \"trapezoid motion queue\" via trapq_append() (in klippy/chelper/trapq.c). The trapq stores all the information in the Move() class in a C struct accessible to the host C code. Note that the extruder is handled in its own kinematic class: ToolHead._process_lookahead() -> PrinterExtruder.process_move() . Since the Move() class specifies the exact movement time and since step pulses are sent to the micro-controller with specific timing, stepper movements produced by the extruder class will be in sync with head movement even though the code is kept separate. For efficiency reasons, stepper motion is generated in the C code in a thread per stepper motor. The threads are notified when steps should be generated by the motion_queuing module (klippy/extras/motion_queuing.py): PrinterMotionQueuing._flush_handler() -> PrinterMotionQueuing._advance_move_time() -> steppersyncmgr_gen_steps() -> se_start_gen_steps() . Klipper uses an iterative solver to generate the step times for each stepper. The step times are generated from the background thread (klippy/chelper/steppersync.c): se_background_thread() -> se_generate_steps() -> itersolve_generate_steps() -> itersolve_gen_steps_range() (in klippy/chelper/itersolve.c). The goal of the iterative solver is to find step times given a function that calculates a stepper position from a time. This is done by repeatedly \"guessing\" various times until the stepper position formula returns the desired position of the next step on the stepper. The feedback produced from each guess is used to improve future guesses so that the process rapidly converges to the desired time. The kinematic stepper position formulas are located in the klippy/chelper/ directory (eg, kin_cart.c, kin_corexy.c, kin_delta.c, kin_extruder.c). After the iterative solver calculates the step times they are added to an array: itersolve_gen_steps_range() -> stepcompress_append() (in klippy/chelper/stepcompress.c). The array (struct stepcompress.queue) stores the corresponding micro-controller clock counter times for every step. Here the \"micro-controller clock counter\" value directly corresponds to the micro-controller's hardware counter - it is relative to when the micro-controller was last powered up. The next major step is to compress the steps: stepcompress_flush() -> compress_bisect_add() (in klippy/chelper/stepcompress.c). This code generates and encodes a series of micro-controller \"queue_step\" commands that correspond to the list of stepper step times built in the previous stage. These \"queue_step\" commands are then queued, prioritized, and sent to the micro-controller (via steppersync.c:steppersync and serialqueue.c:serialqueue). Processing of the queue_step commands on the micro-controller starts in src/command.c which parses the command and calls command_queue_step() . The command_queue_step() code (in src/stepper.c) just appends the parameters of each queue_step command to a per stepper queue. Under normal operation the queue_step command is parsed and queued at least 100ms before the time of its first step. Finally, the generation of stepper events is done in stepper_event() . It's called from the hardware timer interrupt at the scheduled time of the first step. The stepper_event() code generates a step pulse and then reschedules itself to run at the time of the next step pulse for the given queue_step parameters. The parameters for each queue_step command are \"interval\", \"count\", and \"add\". At a high-level, stepper_event() runs the following, 'count' times: do_step(); next_wake_time = last_wake_time + interval; interval += add; The above may seem like a lot of complexity to execute a movement. However, the only really interesting parts are in the ToolHead and kinematic classes. It's this part of the code which specifies the movements and their timings. The remaining parts of the processing is mostly just communication and plumbing.","title":"Code flow of a move command"},{"location":"Code_Overview.html#adding-a-host-module","text":"The Klippy host code has a dynamic module loading capability. If a config section named \"[my_module]\" is found in the printer config file then the software will automatically attempt to load the python module klippy/extras/my_module.py . This module system is the preferred method for adding new functionality to Klipper. The easiest way to add a new module is to use an existing module as a reference - see klippy/extras/servo.py as an example. The following may also be useful: Execution of the module starts in the module level load_config() function (for config sections of the form [my_module]) or in load_config_prefix() (for config sections of the form [my_module my_name]). This function is passed a \"config\" object and it must return a new \"printer object\" associated with the given config section. During the process of instantiating a new printer object, the config object can be used to read parameters from the given config section. This is done using config.get() , config.getfloat() , config.getint() , etc. methods. Be sure to read all values from the config during the construction of the printer object - if the user specifies a config parameter that is not read during this phase then it will be assumed it is a typo in the config and an error will be raised. Use the config.get_printer() method to obtain a reference to the main \"printer\" class. This \"printer\" class stores references to all the \"printer objects\" that have been instantiated. Use the printer.lookup_object() method to find references to other printer objects. Almost all functionality (even core kinematic modules) are encapsulated in one of these printer objects. Note, though, that when a new module is instantiated, not all other printer objects will have been instantiated. The \"gcode\" and \"pins\" modules will always be available, but for other modules it is a good idea to defer the lookup. Register event handlers using the printer.register_event_handler() method if the code needs to be called during \"events\" raised by other printer objects. Each event name is a string, and by convention it is the name of the main source module that raises the event along with a short name for the action that is occurring (eg, \"klippy:connect\"). The parameters passed to each event handler are specific to the given event (as are exception handling and execution context). Two common startup events are: klippy:connect - This event is generated after all printer objects are instantiated. It is commonly used to lookup other printer objects, to verify config settings, and to perform an initial \"handshake\" with printer hardware. klippy:ready - This event is generated after all connect handlers have completed successfully. It indicates the printer is transitioning to a state ready to handle normal operations. Do not raise an error in this callback. If there is an error in the user's config, be sure to raise it during the load_config() or \"connect event\" phases. Use either raise config.error(\"my error\") or raise printer.config_error(\"my error\") to report the error. Do not store a reference to the config object in a class member variable (nor in any similar location that may persist past initial module loading). The config object is a reference to a \"config loading phase\" class and it is not valid to invoke its methods after the \"config loading phase\" has completed. Use the \"pins\" module to configure a pin on a micro-controller. This is typically done with something similar to printer.lookup_object(\"pins\").setup_pin(\"pwm\", config.get(\"my_pin\")) . The returned object can then be commanded at run-time. If the printer object defines a get_status() method then the module can export status information via macros and via the API Server . The get_status() method must return a Python dictionary with keys that are strings and values that are integers, floats, strings, lists, dictionaries, True, False, or None. Tuples (and named tuples) may also be used (these appear as lists when accessed via the API Server). Lists and dictionaries that are exported must be treated as \"immutable\" - if their contents change then a new object must be returned from get_status() , otherwise the API Server will not detect those changes. If the module needs access to system timing or external file descriptors then use printer.get_reactor() to obtain access to the global \"event reactor\" class. This reactor class allows one to schedule timers, wait for input on file descriptors, and to \"sleep\" the host code. Do not use global variables. All state should be stored in the printer object returned from the load_config() function. This is important as otherwise the RESTART command may not perform as expected. Also, for similar reasons, if any external files (or sockets) are opened then be sure to register a \"klippy:disconnect\" event handler and close them from that callback. Avoid accessing the internal member variables (or calling methods that start with an underscore) of other printer objects. Observing this convention makes it easier to manage future changes. It is recommended to assign a value to all member variables in the Python constructor of Python classes. (And therefore avoid utilizing Python's ability to dynamically create new member variables.) If a Python variable is to store a floating point value then it is recommended to always assign and manipulate that variable with floating point constants (and never use integer constants). For example, prefer self.speed = 1. over self.speed = 1 , and prefer self.speed = 2. * x over self.speed = 2 * x . Consistent use of floating point values can avoid hard to debug quirks in Python type conversions. If submitting the module for inclusion in the main Klipper code, be sure to place a copyright notice at the top of the module. See the existing modules for the preferred format.","title":"Adding a host module"},{"location":"Code_Overview.html#adding-new-kinematics","text":"This section provides some tips on adding support to Klipper for additional types of printer kinematics. This type of activity requires excellent understanding of the math formulas for the target kinematics. It also requires software development skills - though one should only need to update the host software. Useful steps: Start by studying the \" code flow of a move \" section and the Kinematics document . Review the existing kinematic classes in the klippy/kinematics/ directory. The kinematic classes are tasked with converting a move in cartesian coordinates to the movement on each stepper. One should be able to copy one of these files as a starting point. Implement the C stepper kinematic position functions for each stepper if they are not already available (see kin_cart.c, kin_corexy.c, and kin_delta.c in klippy/chelper/). The function should call move_get_coord() to convert a given move time (in seconds) to a cartesian coordinate (in millimeters), and then calculate the desired stepper position (in millimeters) from that cartesian coordinate. Implement the calc_position() method in the new kinematics class. This method calculates the position of the toolhead in cartesian coordinates from the position of each stepper. It does not need to be efficient as it is typically only called during homing and probing operations. Other methods. Implement the check_move() , get_status() , get_steppers() , home() , clear_homing_state() , and set_position() methods. These functions are typically used to provide kinematic specific checks. However, at the start of development one can use boiler-plate code here. Implement test cases. Create a g-code file with a series of moves that can test important cases for the given kinematics. Follow the debugging documentation to convert this g-code file to micro-controller commands. This is useful to exercise corner cases and to check for regressions.","title":"Adding new kinematics"},{"location":"Code_Overview.html#porting-to-a-new-micro-controller","text":"This section provides some tips on porting Klipper's micro-controller code to a new architecture. This type of activity requires good knowledge of embedded development and hands-on access to the target micro-controller. Useful steps: Start by identifying any 3rd party libraries that will be used during the port. Common examples include \"CMSIS\" wrappers and manufacturer \"HAL\" libraries. All 3rd party code needs to be GNU GPLv3 compatible. The 3rd party code should be committed to the Klipper lib/ directory. Update the lib/README file with information on where and when the library was obtained. It is preferable to copy the code into the Klipper repository unchanged, but if any changes are required then those changes should be listed explicitly in the lib/README file. Create a new architecture sub-directory in the src/ directory and add initial Kconfig and Makefile support. Use the existing architectures as a guide. The src/simulator provides a basic example of a minimum starting point. The first main coding task is to bring up communication support to the target board. This is the most difficult step in a new port. Once basic communication is working, the remaining steps tend to be much easier. It is typical to use a UART type serial device during initial development as these types of hardware devices are generally easier to enable and control. During this phase, make liberal use of helper code from the src/generic/ directory (check how src/simulator/Makefile includes the generic C code into the build). It is also necessary to define timer_read_time() (which returns the current system clock) in this phase, but it is not necessary to fully support timer irq handling. Get familiar with the the console.py tool (as described in the debugging document ) and verify connectivity to the micro-controller with it. This tool translates the low-level micro-controller communication protocol to a human readable form. Add support for timer dispatch from hardware interrupts. See Klipper commit 970831ee as an example of steps 1-5 done for the LPC176x architecture. Bring up basic GPIO input and output support. See Klipper commit c78b9076 as an example of this. Bring up additional peripherals - for example see Klipper commit 65613aed , c812a40a , and c381d03a . Create a sample Klipper config file in the config/ directory. Test the micro-controller with the main klippy.py program. Consider adding build test cases in the test/ directory. Additional coding tips: Avoid using \"C bitfields\" to access IO registers; prefer direct read and write operations of 32bit, 16bit, or 8bit integers. The C language specifications don't clearly specify how the compiler must implement C bitfields (eg, endianness, and bit layout), and it's difficult to determine what IO operations will occur on a C bitfield read or write. Prefer writing explicit values to IO registers instead of using read-modify-write operations. That is, if updating a field in an IO register where the other fields have known values, then it is preferable to explicitly write the full contents of the register. Explicit writes produce code that is smaller, faster, and easier to debug.","title":"Porting to a new micro-controller"},{"location":"Code_Overview.html#coordinate-systems","text":"Internally, Klipper primarily tracks the position of the toolhead in cartesian coordinates that are relative to the coordinate system specified in the config file. That is, most of the Klipper code will never experience a change in coordinate systems. If the user makes a request to change the origin (eg, a G92 command) then that effect is obtained by translating future commands to the primary coordinate system. However, in some cases it is useful to obtain the toolhead position in some other coordinate system and Klipper has several tools to facilitate that. This can be seen by running the GET_POSITION command. For example: Send: GET_POSITION Recv: // mcu: stepper_a:-2060 stepper_b:-1169 stepper_c:-1613 Recv: // stepper: stepper_a:457.254159 stepper_b:466.085669 stepper_c:465.382132 Recv: // kinematic: X:8.339144 Y:-3.131558 Z:233.347121 Recv: // toolhead: X:8.338078 Y:-3.123175 Z:233.347878 E:0.000000 Recv: // gcode: X:8.338078 Y:-3.123175 Z:233.347878 E:0.000000 Recv: // gcode base: X:0.000000 Y:0.000000 Z:0.000000 E:0.000000 Recv: // gcode homing: X:0.000000 Y:0.000000 Z:0.000000 The \"mcu\" position ( stepper.get_mcu_position() in the code) is the total number of steps the micro-controller has issued in a positive direction minus the number of steps issued in a negative direction since the micro-controller was last reset. If the robot is in motion when the query is issued then the reported value includes moves buffered on the micro-controller, but does not include moves on the look-ahead queue. The \"stepper\" position ( stepper.get_commanded_position() ) is the position of the given stepper as tracked by the kinematics code. This generally corresponds to the position (in mm) of the carriage along its rail, relative to the position_endstop specified in the config file. (Some kinematics track stepper positions in radians instead of millimeters.) If the robot is in motion when the query is issued then the reported value includes moves buffered on the micro-controller, but does not include moves on the look-ahead queue. One may use the toolhead.flush_step_generation() or toolhead.wait_moves() calls to fully flush the look-ahead and step generation code. The \"kinematic\" position ( kin.calc_position() ) is the cartesian position of the toolhead as derived from \"stepper\" positions and is relative to the coordinate system specified in the config file. This may differ from the requested cartesian position due to the granularity of the stepper motors. If the robot is in motion when the \"stepper\" positions are taken then the reported value includes moves buffered on the micro-controller, but does not include moves on the look-ahead queue. One may use the toolhead.flush_step_generation() or toolhead.wait_moves() calls to fully flush the look-ahead and step generation code. The \"toolhead\" position ( toolhead.get_position() ) is the last requested position of the toolhead in cartesian coordinates relative to the coordinate system specified in the config file. If the robot is in motion when the query is issued then the reported value includes all requested moves (even those in buffers waiting to be issued to the stepper motor drivers). The \"gcode\" position is the last requested position from a G1 (or G0 ) command in cartesian coordinates relative to the coordinate system specified in the config file. This may differ from the \"toolhead\" position if a g-code transformation (eg, bed_mesh, bed_tilt, skew_correction) is in effect. This may differ from the actual coordinates specified in the last G1 command if the g-code origin has been changed (eg, G92 , SET_GCODE_OFFSET , M221 ). The M114 command ( gcode_move.get_status()['gcode_position'] ) will report the last g-code position relative to the current g-code coordinate system. The \"gcode base\" is the location of the g-code origin in cartesian coordinates relative to the coordinate system specified in the config file. Commands such as G92 , SET_GCODE_OFFSET , and M221 alter this value. The \"gcode homing\" is the location to use for the g-code origin (in cartesian coordinates relative to the coordinate system specified in the config file) after a G28 home command. The SET_GCODE_OFFSET command can alter this value.","title":"Coordinate Systems"},{"location":"Code_Overview.html#time","text":"Fundamental to the operation of Klipper is the handling of clocks, times, and timestamps. Klipper executes actions on the printer by scheduling events to occur in the near future. For example, to turn on a fan, the code might schedule a change to a GPIO pin in a 100ms. It is rare for the code to attempt to take an instantaneous action. Thus, the handling of time within Klipper is critical to correct operation. There are three types of times tracked internally in the Klipper host software: System time. The system time uses the system's monotonic clock - it is a floating point number stored as seconds and it is (generally) relative to when the host computer was last started. System times have limited use in the software - they are primarily used when interacting with the operating system. Within the host code, system times are frequently stored in variables named eventtime or curtime . Print time. The print time is synchronized to the main micro-controller clock (the micro-controller defined in the \"[mcu]\" config section). It is a floating point number stored as seconds and is relative to when the main mcu was last restarted. It is possible to convert from a \"print time\" to the main micro-controller's hardware clock by multiplying the print time by the mcu's statically configured frequency rate. The high-level host code uses print times to calculate almost all physical actions (eg, head movement, heater changes, etc.). Within the host code, print times are generally stored in variables named print_time or move_time . MCU clock. This is the hardware clock counter on each micro-controller. It is stored as an integer and its update rate is relative to the frequency of the given micro-controller. The host software translates its internal times to clocks before transmission to the mcu. The mcu code only ever tracks time in clock ticks. Within the host code, clock values are tracked as 64bit integers, while the mcu code uses 32bit integers. Within the host code, clocks are generally stored in variables with names containing clock or ticks . Conversion between the different time formats is primarily implemented in the klippy/clocksync.py code. Some things to be aware of when reviewing the code: 32bit and 64bit clocks: To reduce bandwidth and to improve micro-controller efficiency, clocks on the micro-controller are tracked as 32bit integers. When comparing two clocks in the mcu code, the timer_is_before() function must always be used to ensure integer rollovers are handled properly. The host software converts 32bit clocks to 64bit clocks by appending the high-order bits from the last mcu timestamp it has received - no message from the mcu is ever more than 2^31 clock ticks in the future or past so this conversion is never ambiguous. The host converts from 64bit clocks to 32bit clocks by simply truncating the high-order bits. To ensure there is no ambiguity in this conversion, the klippy/chelper/serialqueue.c code will buffer messages until they are within 2^31 clock ticks of their target time. Multiple micro-controllers: The host software supports using multiple micro-controllers on a single printer. In this case, the \"MCU clock\" of each micro-controller is tracked separately. The clocksync.py code handles clock drift between micro-controllers by modifying the way it converts from \"print time\" to \"MCU clock\". On secondary mcus, the mcu frequency that is used in this conversion is regularly updated to account for measured drift.","title":"Time"},{"location":"Command_Templates.html","text":"Commands templates \u00b6 This document provides information on implementing G-Code command sequences in gcode_macro (and similar) config sections. G-Code Macro Naming \u00b6 Case is not important for the G-Code macro name - MY_MACRO and my_macro will evaluate the same and may be called in either upper or lower case. If any numbers are used in the macro name then they must all be at the end of the name (eg, TEST_MACRO25 is valid, but MACRO25_TEST3 is not). Formatting of G-Code in the config \u00b6 Indentation is important when defining a macro in the config file. To specify a multi-line G-Code sequence it is important for each line to have proper indentation. For example: [gcode_macro blink_led] gcode: SET_PIN PIN=my_led VALUE=1 G4 P2000 SET_PIN PIN=my_led VALUE=0 Note how the gcode: config option always starts at the beginning of the line and subsequent lines in the G-Code macro never start at the beginning. Add a description to your macro \u00b6 To help identify the functionality a short description can be added. Add description: with a short text to describe the functionality. Default is \"G-Code macro\" if not specified. For example: [gcode_macro blink_led] description: Blink my_led one time gcode: SET_PIN PIN=my_led VALUE=1 G4 P2000 SET_PIN PIN=my_led VALUE=0 The terminal will display the description when you use the HELP command or the autocomplete function. Save/Restore state for G-Code moves \u00b6 Unfortunately, the G-Code command language can be challenging to use. The standard mechanism to move the toolhead is via the G1 command (the G0 command is an alias for G1 and it can be used interchangeably with it). However, this command relies on the \"G-Code parsing state\" setup by M82 , M83 , G90 , G91 , G92 , and previous G1 commands. When creating a G-Code macro it is a good idea to always explicitly set the G-Code parsing state prior to issuing a G1 command. (Otherwise, there is a risk the G1 command will make an undesirable request.) A common way to accomplish that is to wrap the G1 moves in SAVE_GCODE_STATE , G91 , and RESTORE_GCODE_STATE . For example: [gcode_macro MOVE_UP] gcode: SAVE_GCODE_STATE NAME=my_move_up_state G91 G1 Z10 F300 RESTORE_GCODE_STATE NAME=my_move_up_state The G91 command places the G-Code parsing state into \"relative move mode\" and the RESTORE_GCODE_STATE command restores the state to what it was prior to entering the macro. Be sure to specify an explicit speed (via the F parameter) on the first G1 command. Template expansion \u00b6 The gcode_macro gcode: config section is evaluated using the Jinja2 template language. One can evaluate expressions at run-time by wrapping them in { } characters or use conditional statements wrapped in {% %} . See the Jinja2 documentation for further information on the syntax. An example of a complex macro: [gcode_macro clean_nozzle] gcode: {% set wipe_count = 8 %} SAVE_GCODE_STATE NAME=clean_nozzle_state G90 G0 Z15 F300 {% for wipe in range(wipe_count) %} {% for coordinate in [(275, 4),(235, 4)] %} G0 X{coordinate[0]} Y{coordinate[1] + 0.25 * wipe} Z9.7 F12000 {% endfor %} {% endfor %} RESTORE_GCODE_STATE NAME=clean_nozzle_state Macro parameters \u00b6 It is often useful to inspect parameters passed to the macro when it is called. These parameters are available via the params pseudo-variable. For example, if the macro: [gcode_macro SET_PERCENT] gcode: M117 Now at { params.VALUE|float * 100 }% were invoked as SET_PERCENT VALUE=.2 it would evaluate to M117 Now at 20% . Note that parameter names are always in upper-case when evaluated in the macro and are always passed as strings. If performing math then they must be explicitly converted to integers or floats. It's common to use the Jinja2 set directive to use a default parameter and assign the result to a local name. For example: [gcode_macro SET_BED_TEMPERATURE] gcode: {% set bed_temp = params.TEMPERATURE|default(40)|float %} M140 S{bed_temp} The \"rawparams\" variable \u00b6 The full unparsed parameters for the running macro can be access via the rawparams pseudo-variable. Note that this will include any comments that were part of the original command. See the sample-macros.cfg file for an example showing how to override the M117 command using rawparams . The \"printer\" Variable \u00b6 It is possible to inspect (and alter) the current state of the printer via the printer pseudo-variable. For example: [gcode_macro slow_fan] gcode: M106 S{ printer.fan.speed * 0.9 * 255} Available fields are defined in the Status Reference document. Important! Macros are first evaluated in entirety and only then are the resulting commands executed. If a macro issues a command that alters the state of the printer, the results of that state change will not be visible during the evaluation of the macro. This can also result in subtle behavior when a macro generates commands that call other macros, as the called macro is evaluated when it is invoked (which is after the entire evaluation of the calling macro). By convention, the name immediately following printer is the name of a config section. So, for example, printer.fan refers to the fan object created by the [fan] config section. There are some exceptions to this rule - notably the gcode_move and toolhead objects. If the config section contains spaces in it, then one can access it via the [ ] accessor - for example: printer[\"generic_heater my_chamber_heater\"].temperature . Note that the Jinja2 set directive can assign a local name to an object in the printer hierarchy. This can make macros more readable and reduce typing. For example: [gcode_macro QUERY_HTU21D] gcode: {% set sensor = printer[\"htu21d my_sensor\"] %} M117 Temp:{sensor.temperature} Humidity:{sensor.humidity} Actions \u00b6 There are some commands available that can alter the state of the printer. For example, { action_emergency_stop() } would cause the printer to go into a shutdown state. Note that these actions are taken at the time that the macro is evaluated, which may be a significant amount of time before the generated g-code commands are executed. Available \"action\" commands: action_respond_info(msg) : Write the given msg to the /tmp/printer pseudo-terminal. Each line of msg will be sent with a \"// \" prefix. action_raise_error(msg) : Abort the current macro (and any calling macros) and write the given msg to the /tmp/printer pseudo-terminal. The first line of msg will be sent with a \"!! \" prefix and subsequent lines will have a \"// \" prefix. action_emergency_stop(msg) : Transition the printer to a shutdown state. The msg parameter is optional, it may be useful to describe the reason for the shutdown. action_call_remote_method(method_name) : Calls a method registered by a remote client. If the method takes parameters they should be provided via keyword arguments, ie: action_call_remote_method(\"print_stuff\", my_arg=\"hello_world\") Variables \u00b6 The SET_GCODE_VARIABLE command may be useful for saving state between macro calls. Variable names may not contain any upper case characters. For example: [gcode_macro start_probe] variable_bed_temp: 0 gcode: # Save target temperature to bed_temp variable SET_GCODE_VARIABLE MACRO=start_probe VARIABLE=bed_temp VALUE={printer.heater_bed.target} # Disable bed heater M140 # Perform probe PROBE # Call finish_probe macro at completion of probe finish_probe [gcode_macro finish_probe] gcode: # Restore temperature M140 S{printer[\"gcode_macro start_probe\"].bed_temp} Be sure to take the timing of macro evaluation and command execution into account when using SET_GCODE_VARIABLE. Delayed Gcodes \u00b6 The [delayed_gcode] configuration option can be used to execute a delayed gcode sequence: [delayed_gcode clear_display] gcode: M117 [gcode_macro load_filament] gcode: G91 G1 E50 G90 M400 M117 Load Complete! UPDATE_DELAYED_GCODE ID=clear_display DURATION=10 When the load_filament macro above executes, it will display a \"Load Complete!\" message after the extrusion is finished. The last line of gcode enables the \"clear_display\" delayed_gcode, set to execute in 10 seconds. The initial_duration config option can be set to execute the delayed_gcode on printer startup. The countdown begins when the printer enters the \"ready\" state. For example, the below delayed_gcode will execute 5 seconds after the printer is ready, initializing the display with a \"Welcome!\" message: [delayed_gcode welcome] initial_duration: 5. gcode: M117 Welcome! Its possible for a delayed gcode to repeat by updating itself in the gcode option: [delayed_gcode report_temp] initial_duration: 2. gcode: {action_respond_info(\"Extruder Temp: %.1f\" % (printer.extruder0.temperature))} UPDATE_DELAYED_GCODE ID=report_temp DURATION=2 The above delayed_gcode will send \"// Extruder Temp: [ex0_temp]\" to Octoprint every 2 seconds. This can be canceled with the following gcode: UPDATE_DELAYED_GCODE ID=report_temp DURATION=0 Menu templates \u00b6 If a display config section is enabled, then it is possible to customize the menu with menu config sections. The following read-only attributes are available in menu templates: menu.width - element width (number of display columns) menu.ns - element namespace menu.event - name of the event that triggered the script menu.input - input value, only available in input script context The following actions are available in menu templates: menu.back(force, update) : will execute menu back command, optional boolean parameters and . When is set True then it will also stop editing. Default value is False. When is set False then parent container items are not updated. Default value is True. menu.exit(force) - will execute menu exit command, optional boolean parameter default value False. When 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= 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 and . When is set True then it will also stop editing. Default value is False. When is set False then parent container items are not updated. Default value is True. menu.exit(force) - will execute menu exit command, optional boolean parameter default value False. When 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= 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 20251122: An option axis has been added to [carriage ] sections for generic_cartesian kinematics, allowing arbitrary names for primary carriages. Users are encouraged to explicitly specify axis option now. 20251106: The status fields {printer.toolhead.position} , {printer.gcode_move.position} , {printer.gcode_move.gcode_position} , and {printer.motion_report.live_position} are changing. These coordinates used to always contain four components, but now may contain additional components. The ordering and number of components may change at run-time - see the status reference for important details. Accessing any of these coordinates in macros using the \".e\" accessor is deprecated - use something like {printer.toolhead.position[printer.gcode_move.axis_map.E]} as an alternative. 20251106: The status fields {printer.gcode_move.homing_origin} , {printer.toolhead.axis_min} , and {printer.toolhead.axis_max} currently contain four components where the fourth component is always zero. This behavior is deprecated. In the future these coordinates may contain only three components. For additional information see the status reference . 20251010: During normal printing the command processing will now attempt to stay one second ahead of printer movement (reduced from two seconds previously). 20251003: Support for the undocumented max_stepper_error option in the [printer] config section has been removed. 20250916: The definitions of EI, 2HUMP_EI, and 3HUMP_EI input shapers were updated. For best performance it is recommended to recalibrate input shapers, especially if some of these shapers are currently used. 20250811: Support for the max_accel_to_decel parameter in the [printer] config section has been removed and support for the ACCEL_TO_DECEL parameter in the SET_VELOCITY_LIMIT command has been removed. These capabilities were deprecated on 20240313. 20250721: The [pca9632] and [mcp4018] modules no longer accept the scl_pin and sda_pin options. Use i2c_software_scl_pin and i2c_software_sda_pin instead. 20250428: The maximum cycle_time for pwm [output_pin] , [pwm_cycle_time] , [pwm_tool] , and similar config sections is now 3 seconds (reduced from 5 seconds). The maximum_mcu_duration in [pwm_tool] is now also 3 seconds. 20250418: The manual_stepper STOP_ON_ENDSTOP feature may now take less time to complete. Previously, the command would wait the entire time the move could possibly take even if the endstop triggered earlier. Now, the command finishes shortly after the endstop trigger. 20250417: SPI devices using \"software SPI\" are now rate limited. Previously, the spi_speed in the config was ignored and the transmission speed was only limited by the processing speed of the micro-controller. Now, speeds are limited by the spi_speed config parameter (actual hardware speeds are likely to be lower than the configured value due to software overhead). 20250411: Klipper v0.13.0 released. 20250308: The AUTO parameter of the AXIS_TWIST_COMPENSATION_CALIBRATE command has been removed. 20250131: Option VARIABLE= in SAVE_VARIABLE requires lowercase value. For example, extruder instead of mixedcase Extruder or uppercase EXTRUDER . Using any uppercase letter will raise an error. 20241203: The resonance test has been changed to include slow sweeping moves. This change requires that testing point(s) have some clearance in X/Y plane (+/- 30 mm from the test point should suffice when using the default settings). The new test should generally produce more accurate and reliable test results. However, if required, the previous test behavior can be restored by adding options sweeping_period: 0 and accel_per_hz: 75 to the [resonance_tester] config section. 20241201: In some cases Klipper may have ignored leading characters or spaces in a traditional G-Code command. For example, \"99M123\" may have been interpreted as \"M123\" and \"M 321\" may have been interpreted as \"M321\". Klipper will now report these cases with an \"Unknown command\" warning. 20241112: Option CHIPS= in TEST_RESONANCES and SHAPER_CALIBRATE requires specifying the full name(s) of the accel chip(s). For example, adxl345 rpi instead of short name - rpi . 20240912: SET_PIN , SET_SERVO , SET_FAN_SPEED , M106 , and M107 commands are now collated. Previously, if many updates to the same object were issued faster than the minimum scheduling time (typically 100ms) then actual updates could be queued far into the future. Now if many updates are issued in rapid succession then it is possible that only the latest request will be applied. If the previous behavior is required then consider adding explicit G4 delay commands between updates. 20240912: Support for maximum_mcu_duration and static_value parameters in [output_pin] config sections have been removed. These options have been deprecated since 20240123. 20240415: The on_error_gcode parameter in the [virtual_sdcard] config section now has a default. If this parameter is not specified it now defaults to TURN_OFF_HEATERS . If the previous behavior is desired (take no default action on an error during a virtual_sdcard print) then define on_error_gcode with an empty value. 20240313: The max_accel_to_decel parameter in the [printer] config section has been deprecated. The ACCEL_TO_DECEL parameter of the SET_VELOCITY_LIMIT command has been deprecated. The printer.toolhead.max_accel_to_decel status has been removed. Use the minimum_cruise_ratio parameter instead. The deprecated features will be removed in the near future, and using them in the interim may result in subtly different behavior. 20240215: Several deprecated features have been removed. Using \"NTC 100K beta 3950\" as a thermistor name has been removed (deprecated on 20211110). The SYNC_STEPPER_TO_EXTRUDER and SET_EXTRUDER_STEP_DISTANCE commands have been removed, and the extruder shared_heater config option has been removed (deprecated on 20220210). The bed_mesh relative_reference_index option has been removed (deprecated on 20230619). 20240123: The output_pin SET_PIN CYCLE_TIME parameter has been removed. Use the new pwm_cycle_time module if it is necessary to dynamically change a pwm pin's cycle time. 20240123: The output_pin maximum_mcu_duration parameter is deprecated. Use a pwm_tool config section instead. The option will be removed in the near future. 20240123: The output_pin static_value parameter is deprecated. Replace with value and shutdown_value parameters. The option will be removed in the near future. 20231216: The [hall_filament_width_sensor] is changed to trigger filament runout when the thickness of the filament exceeds max_diameter . The maximum diameter defaults to default_nominal_filament_diameter + max_difference . See [hall_filament_width_sensor] configuration reference for more details. 20231207: Several undocumented config parameters in the [printer] config section have been removed (the buffer_time_low, buffer_time_high, buffer_time_start, and move_flush_time parameters). 20231110: Klipper v0.12.0 released. 20230826: If safe_distance is set or calculated to be 0 in [dual_carriage] , the carriages proximity checks will be disabled as per documentation. A user may wish to configure safe_distance explicitly to prevent accidental crashes of the carriages with each other. Additionally, the homing order of the primary and the dual carriage is changed in some configurations (certain configurations when both carriages home in the same direction, see [dual_carriage] configuration reference for more details). 20230810: The flash-sdcard.sh script now supports both variants of the Bigtreetech SKR-3, STM32H743 and STM32H723. For this, the original tag of btt-skr-3 now has changed to be either btt-skr-3-h743 or btt-skr-3-h723. 20230729: The exported status for dual_carriage is changed. Instead of exporting mode and active_carriage , the individual modes for each carriage are exported as printer.dual_carriage.carriage_0 and printer.dual_carriage.carriage_1 . 20230619: The relative_reference_index option has been deprecated and superseded by the zero_reference_position option. Refer to the Bed Mesh Documentation for details on how to update the configuration. With this deprecation the RELATIVE_REFERENCE_INDEX is no longer available as a parameter for the BED_MESH_CALIBRATE gcode command. 20230530: The default canbus frequency in \"make menuconfig\" is now 1000000. If using canbus and using canbus with some other frequency is required, then be sure to select \"Enable extra low-level configuration options\" and specify the desired \"CAN bus speed\" in \"make menuconfig\" when compiling and flashing the micro-controller. 20230525: SHAPER_CALIBRATE command immediately applies input shaper parameters if [input_shaper] was enabled already. 20230407: The stalled_bytes counter in the log and in the printer.mcu.last_stats field has been renamed to upcoming_bytes . 20230323: On tmc5160 drivers multistep_filt is now enabled by default. Set driver_MULTISTEP_FILT: False in the tmc5160 config for the previous behavior. 20230304: The SET_TMC_CURRENT command now properly adjusts the globalscaler register for drivers that have it. This removes a limitation where on tmc5160, the currents could not be raised higher with SET_TMC_CURRENT than the run_current value set in the config file. However, this has a side effect: After running SET_TMC_CURRENT , the stepper must be held at standstill for >130ms in case StealthChop2 is used so that the AT#1 calibration gets executed by the driver. 20230202: The format of the printer.screws_tilt_adjust status information has changed. The information is now stored as a dictionary of screws with the resulting measurements. See the status reference for details. 20230201: The [bed_mesh] module no longer loads the default profile on startup. It is recommended that users who use the default profile add BED_MESH_PROFILE LOAD=default to their START_PRINT macro (or to their slicer's \"Start G-Code\" configuration when applicable). 20230103: It is now possible with the flash-sdcard.sh script to flash both variants of the Bigtreetech SKR-2, STM32F407 and STM32F429. This means that the original tag of btt-skr2 now has changed to either btt-skr-2-f407 or btt-skr-2-f429. 20221128: Klipper v0.11.0 released. 20221122: Previously, with safe_z_home, it was possible that the z_hop after the g28 homing would go in the negative z direction. Now, a z_hop is performed after g28 only if it results in a positive hop, mirroring the behavior of the z_hop that occurs before the g28 homing. 20220616: It was previously possible to flash an rp2040 in bootloader mode by running make flash FLASH_DEVICE=first . The equivalent command is now make flash FLASH_DEVICE=2e8a:0003 . 20220612: The rp2040 micro-controller now has a workaround for the \"rp2040-e5\" USB errata. This should make initial USB connections more reliable. However, it may result in a change in behavior for the gpio15 pin. It is unlikely the gpio15 behavior change will be noticeable. 20220407: The temperature_fan pid_integral_max config option has been removed (it was deprecated on 20210612). 20220407: The default color order for pca9632 LEDs is now \"RGBW\". Add an explicit color_order: RBGW setting to the pca9632 config section to obtain the previous behavior. 20220330: The format of the printer.neopixel.color_data status information for neopixel and dotstar modules has changed. The information is now stored as a list of color lists (instead of a list of dictionaries). See the status reference for details. 20220307: M73 will no longer set print progress to 0 if P is missing. 20220304: There is no longer a default for the extruder parameter of extruder_stepper config sections. If desired, specify extruder: extruder explicitly to associate the stepper motor with the \"extruder\" motion queue at startup. 20220210: The SYNC_STEPPER_TO_EXTRUDER command is deprecated; the SET_EXTRUDER_STEP_DISTANCE command is deprecated; the extruder shared_heater config option is deprecated. These features will be removed in the near future. Replace SET_EXTRUDER_STEP_DISTANCE with SET_EXTRUDER_ROTATION_DISTANCE . Replace SYNC_STEPPER_TO_EXTRUDER with SYNC_EXTRUDER_MOTION . Replace extruder config sections using shared_heater with extruder_stepper config sections and update any activation macros to use SYNC_EXTRUDER_MOTION . 20220116: The tmc2130, tmc2208, tmc2209, and tmc2660 run_current calculation code has changed. For some run_current settings the drivers may now be configured differently. This new configuration should be more accurate, but it may invalidate previous tmc driver tuning. 20211230: Scripts to tune input shaper ( scripts/calibrate_shaper.py and scripts/graph_accelerometer.py ) were migrated to use Python3 by default. As a result, users must install Python3 versions of certain packages (e.g. sudo apt install python3-numpy python3-matplotlib ) to continue using these scripts. For more details, refer to Software installation . Alternatively, users can temporarily force the execution of these scripts under Python 2 by explicitly calling Python2 interpretor in the console: python2 ~/klipper/scripts/calibrate_shaper.py ... 20211110: The \"NTC 100K beta 3950\" temperature sensor is deprecated. This sensor will be removed in the near future. Most users will find the \"Generic 3950\" temperature sensor more accurate. To continue to use the older (typically less accurate) definition, define a custom thermistor with temperature1: 25 , resistance1: 100000 , and beta: 3950 . 20211104: The \"step pulse duration\" option in \"make menuconfig\" has been removed. The default step duration for TMC drivers configured in UART or SPI mode is now 100ns. A new step_pulse_duration setting in the stepper config section should be set for all steppers that need a custom pulse duration. 20211102: Several deprecated features have been removed. The stepper step_distance option has been removed (deprecated on 20201222). The rpi_temperature sensor alias has been removed (deprecated on 20210219). The mcu pin_map option has been removed (deprecated on 20210325). The gcode_macro default_parameter_ 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_ config option is deprecated. Use the params pseudo-variable to access macro parameters. Other methods for accessing macro parameters will be removed in the near future. Most users can replace a default_parameter_NAME: VALUE config option with a line like the following in the start of the macro: {% set NAME = params.NAME|default(VALUE)|float %} . See the Command Templates document for examples. 20210430: The SET_VELOCITY_LIMIT (and M204) command may now set a velocity, acceleration, and square_corner_velocity larger than the specified values in the config file. 20210325: Support for the pin_map config option is deprecated. Use the sample-aliases.cfg file to translate to the actual micro-controller pin names. The pin_map config option will be removed in the near future. 20210313: Klipper's support for micro-controllers that communicate with CAN bus has changed. If using CAN bus then all micro-controllers must be reflashed and the Klipper configuration must be updated . 20210310: The TMC2660 default for driver_SFILT has been changed from 1 to 0. 20210227: TMC stepper motor drivers in UART or SPI mode are now queried once per second whenever they are enabled - if the driver can not be contacted or if the driver reports an error, then Klipper will transition to a shutdown state. 20210219: The rpi_temperature module has been renamed to temperature_host . Replace any occurrences of sensor_type: rpi_temperature with sensor_type: temperature_host . The path to the temperature file may be specified in the sensor_path config variable. The rpi_temperature name is deprecated and will be removed in the near future. 20210201: The TEST_RESONANCES command will now disable input shaping if it was previously enabled (and re-enable it after the test). In order to override this behavior and keep the input shaping enabled, one can pass an additional parameter INPUT_SHAPING=1 to the command. 20210201: The ACCELEROMETER_MEASURE command will now append the name of the accelerometer chip to the output file name if the chip was given a name in the corresponding adxl345 section of the printer.cfg. 20201222: The step_distance setting in the stepper config sections is deprecated. It is advised to update the config to use the rotation_distance setting. Support for step_distance will be removed in the near future. 20201218: The endstop_phase setting in the endstop_phase module has been replaced with trigger_phase . If using the endstop phases module then it will be necessary to convert to rotation_distance and recalibrate any endstop phases by running the ENDSTOP_PHASE_CALIBRATE command. 20201218: Rotary delta and polar printers must now specify a gear_ratio for their rotary steppers, and they may no longer specify a step_distance parameter. See the config reference for the format of the new gear_ratio parameter. 20201213: It is not valid to specify a Z \"position_endstop\" when using \"probe:z_virtual_endstop\". An error will now be raised if a Z \"position_endstop\" is specified with \"probe:z_virtual_endstop\". Remove the Z \"position_endstop\" definition to fix the error. 20201120: The [board_pins] config section now specifies the mcu name in an explicit mcu: parameter. If using board_pins for a secondary mcu, then the config must be updated to specify that name. See the config reference for further details. 20201112: The time reported by print_stats.print_duration has changed. The duration prior to the first detected extrusion is now excluded. 20201029: The neopixel color_order_GRB config option has been removed. If necessary, update the config to set the new color_order option to RGB, GRB, RGBW, or GRBW. 20201029: The serial option in the mcu config section no longer defaults to /dev/ttyS0. In the rare situation where /dev/ttyS0 is the desired serial port, it must be specified explicitly. 20201020: Klipper v0.9.0 released. 20200902: The RTD resistance-to-temperature calculation for MAX31865 converters has been corrected to not read low. If you are using such a device, you should recalibrate your print temperature and PID settings. 20200816: The gcode macro printer.gcode object has been renamed to printer.gcode_move . Several undocumented variables in printer.toolhead and printer.gcode have been removed. See docs/Command_Templates.md for a list of available template variables. 20200816: The gcode macro \"action_\" system has changed. Replace any calls to printer.gcode.action_emergency_stop() with action_emergency_stop() , printer.gcode.action_respond_info() with action_respond_info() , and printer.gcode.action_respond_error() with action_raise_error() . 20200809: The menu system has been rewritten. If the menu has been customized then it will be necessary to update to the new configuration. See config/example-menu.cfg for configuration details and see klippy/extras/display/menu.cfg for examples. 20200731: The behavior of the progress attribute reported by the virtual_sdcard printer object has changed. Progress is no longer reset to 0 when a print is paused. It will now always report progress based on the internal file position, or 0 if no file is currently loaded. 20200725: The servo enable config parameter and the SET_SERVO ENABLE parameter have been removed. Update any macros to use SET_SERVO SERVO=my_servo WIDTH=0 to disable a servo. 20200608: The LCD display support has changed the name of some internal \"glyphs\". If a custom display layout was implemented it may be necessary to update to the latest glyph names (see klippy/extras/display/display.cfg for a list of available glyphs). 20200606: The pin names on linux mcu have changed. Pins now have names of the form gpiochip/gpio . For gpiochip0 you can also use a short 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":"20251122: An option axis has been added to [carriage ] sections for generic_cartesian kinematics, allowing arbitrary names for primary carriages. Users are encouraged to explicitly specify axis option now. 20251106: The status fields {printer.toolhead.position} , {printer.gcode_move.position} , {printer.gcode_move.gcode_position} , and {printer.motion_report.live_position} are changing. These coordinates used to always contain four components, but now may contain additional components. The ordering and number of components may change at run-time - see the status reference for important details. Accessing any of these coordinates in macros using the \".e\" accessor is deprecated - use something like {printer.toolhead.position[printer.gcode_move.axis_map.E]} as an alternative. 20251106: The status fields {printer.gcode_move.homing_origin} , {printer.toolhead.axis_min} , and {printer.toolhead.axis_max} currently contain four components where the fourth component is always zero. This behavior is deprecated. In the future these coordinates may contain only three components. For additional information see the status reference . 20251010: During normal printing the command processing will now attempt to stay one second ahead of printer movement (reduced from two seconds previously). 20251003: Support for the undocumented max_stepper_error option in the [printer] config section has been removed. 20250916: The definitions of EI, 2HUMP_EI, and 3HUMP_EI input shapers were updated. For best performance it is recommended to recalibrate input shapers, especially if some of these shapers are currently used. 20250811: Support for the max_accel_to_decel parameter in the [printer] config section has been removed and support for the ACCEL_TO_DECEL parameter in the SET_VELOCITY_LIMIT command has been removed. These capabilities were deprecated on 20240313. 20250721: The [pca9632] and [mcp4018] modules no longer accept the scl_pin and sda_pin options. Use i2c_software_scl_pin and i2c_software_sda_pin instead. 20250428: The maximum cycle_time for pwm [output_pin] , [pwm_cycle_time] , [pwm_tool] , and similar config sections is now 3 seconds (reduced from 5 seconds). The maximum_mcu_duration in [pwm_tool] is now also 3 seconds. 20250418: The manual_stepper STOP_ON_ENDSTOP feature may now take less time to complete. Previously, the command would wait the entire time the move could possibly take even if the endstop triggered earlier. Now, the command finishes shortly after the endstop trigger. 20250417: SPI devices using \"software SPI\" are now rate limited. Previously, the spi_speed in the config was ignored and the transmission speed was only limited by the processing speed of the micro-controller. Now, speeds are limited by the spi_speed config parameter (actual hardware speeds are likely to be lower than the configured value due to software overhead). 20250411: Klipper v0.13.0 released. 20250308: The AUTO parameter of the AXIS_TWIST_COMPENSATION_CALIBRATE command has been removed. 20250131: Option VARIABLE= in SAVE_VARIABLE requires lowercase value. For example, extruder instead of mixedcase Extruder or uppercase EXTRUDER . Using any uppercase letter will raise an error. 20241203: The resonance test has been changed to include slow sweeping moves. This change requires that testing point(s) have some clearance in X/Y plane (+/- 30 mm from the test point should suffice when using the default settings). The new test should generally produce more accurate and reliable test results. However, if required, the previous test behavior can be restored by adding options sweeping_period: 0 and accel_per_hz: 75 to the [resonance_tester] config section. 20241201: In some cases Klipper may have ignored leading characters or spaces in a traditional G-Code command. For example, \"99M123\" may have been interpreted as \"M123\" and \"M 321\" may have been interpreted as \"M321\". Klipper will now report these cases with an \"Unknown command\" warning. 20241112: Option CHIPS= in TEST_RESONANCES and SHAPER_CALIBRATE requires specifying the full name(s) of the accel chip(s). For example, adxl345 rpi instead of short name - rpi . 20240912: SET_PIN , SET_SERVO , SET_FAN_SPEED , M106 , and M107 commands are now collated. Previously, if many updates to the same object were issued faster than the minimum scheduling time (typically 100ms) then actual updates could be queued far into the future. Now if many updates are issued in rapid succession then it is possible that only the latest request will be applied. If the previous behavior is required then consider adding explicit G4 delay commands between updates. 20240912: Support for maximum_mcu_duration and static_value parameters in [output_pin] config sections have been removed. These options have been deprecated since 20240123. 20240415: The on_error_gcode parameter in the [virtual_sdcard] config section now has a default. If this parameter is not specified it now defaults to TURN_OFF_HEATERS . If the previous behavior is desired (take no default action on an error during a virtual_sdcard print) then define on_error_gcode with an empty value. 20240313: The max_accel_to_decel parameter in the [printer] config section has been deprecated. The ACCEL_TO_DECEL parameter of the SET_VELOCITY_LIMIT command has been deprecated. The printer.toolhead.max_accel_to_decel status has been removed. Use the minimum_cruise_ratio parameter instead. The deprecated features will be removed in the near future, and using them in the interim may result in subtly different behavior. 20240215: Several deprecated features have been removed. Using \"NTC 100K beta 3950\" as a thermistor name has been removed (deprecated on 20211110). The SYNC_STEPPER_TO_EXTRUDER and SET_EXTRUDER_STEP_DISTANCE commands have been removed, and the extruder shared_heater config option has been removed (deprecated on 20220210). The bed_mesh relative_reference_index option has been removed (deprecated on 20230619). 20240123: The output_pin SET_PIN CYCLE_TIME parameter has been removed. Use the new pwm_cycle_time module if it is necessary to dynamically change a pwm pin's cycle time. 20240123: The output_pin maximum_mcu_duration parameter is deprecated. Use a pwm_tool config section instead. The option will be removed in the near future. 20240123: The output_pin static_value parameter is deprecated. Replace with value and shutdown_value parameters. The option will be removed in the near future. 20231216: The [hall_filament_width_sensor] is changed to trigger filament runout when the thickness of the filament exceeds max_diameter . The maximum diameter defaults to default_nominal_filament_diameter + max_difference . See [hall_filament_width_sensor] configuration reference for more details. 20231207: Several undocumented config parameters in the [printer] config section have been removed (the buffer_time_low, buffer_time_high, buffer_time_start, and move_flush_time parameters). 20231110: Klipper v0.12.0 released. 20230826: If safe_distance is set or calculated to be 0 in [dual_carriage] , the carriages proximity checks will be disabled as per documentation. A user may wish to configure safe_distance explicitly to prevent accidental crashes of the carriages with each other. Additionally, the homing order of the primary and the dual carriage is changed in some configurations (certain configurations when both carriages home in the same direction, see [dual_carriage] configuration reference for more details). 20230810: The flash-sdcard.sh script now supports both variants of the Bigtreetech SKR-3, STM32H743 and STM32H723. For this, the original tag of btt-skr-3 now has changed to be either btt-skr-3-h743 or btt-skr-3-h723. 20230729: The exported status for dual_carriage is changed. Instead of exporting mode and active_carriage , the individual modes for each carriage are exported as printer.dual_carriage.carriage_0 and printer.dual_carriage.carriage_1 . 20230619: The relative_reference_index option has been deprecated and superseded by the zero_reference_position option. Refer to the Bed Mesh Documentation for details on how to update the configuration. With this deprecation the RELATIVE_REFERENCE_INDEX is no longer available as a parameter for the BED_MESH_CALIBRATE gcode command. 20230530: The default canbus frequency in \"make menuconfig\" is now 1000000. If using canbus and using canbus with some other frequency is required, then be sure to select \"Enable extra low-level configuration options\" and specify the desired \"CAN bus speed\" in \"make menuconfig\" when compiling and flashing the micro-controller. 20230525: SHAPER_CALIBRATE command immediately applies input shaper parameters if [input_shaper] was enabled already. 20230407: The stalled_bytes counter in the log and in the printer.mcu.last_stats field has been renamed to upcoming_bytes . 20230323: On tmc5160 drivers multistep_filt is now enabled by default. Set driver_MULTISTEP_FILT: False in the tmc5160 config for the previous behavior. 20230304: The SET_TMC_CURRENT command now properly adjusts the globalscaler register for drivers that have it. This removes a limitation where on tmc5160, the currents could not be raised higher with SET_TMC_CURRENT than the run_current value set in the config file. However, this has a side effect: After running SET_TMC_CURRENT , the stepper must be held at standstill for >130ms in case StealthChop2 is used so that the AT#1 calibration gets executed by the driver. 20230202: The format of the printer.screws_tilt_adjust status information has changed. The information is now stored as a dictionary of screws with the resulting measurements. See the status reference for details. 20230201: The [bed_mesh] module no longer loads the default profile on startup. It is recommended that users who use the default profile add BED_MESH_PROFILE LOAD=default to their START_PRINT macro (or to their slicer's \"Start G-Code\" configuration when applicable). 20230103: It is now possible with the flash-sdcard.sh script to flash both variants of the Bigtreetech SKR-2, STM32F407 and STM32F429. This means that the original tag of btt-skr2 now has changed to either btt-skr-2-f407 or btt-skr-2-f429. 20221128: Klipper v0.11.0 released. 20221122: Previously, with safe_z_home, it was possible that the z_hop after the g28 homing would go in the negative z direction. Now, a z_hop is performed after g28 only if it results in a positive hop, mirroring the behavior of the z_hop that occurs before the g28 homing. 20220616: It was previously possible to flash an rp2040 in bootloader mode by running make flash FLASH_DEVICE=first . The equivalent command is now make flash FLASH_DEVICE=2e8a:0003 . 20220612: The rp2040 micro-controller now has a workaround for the \"rp2040-e5\" USB errata. This should make initial USB connections more reliable. However, it may result in a change in behavior for the gpio15 pin. It is unlikely the gpio15 behavior change will be noticeable. 20220407: The temperature_fan pid_integral_max config option has been removed (it was deprecated on 20210612). 20220407: The default color order for pca9632 LEDs is now \"RGBW\". Add an explicit color_order: RBGW setting to the pca9632 config section to obtain the previous behavior. 20220330: The format of the printer.neopixel.color_data status information for neopixel and dotstar modules has changed. The information is now stored as a list of color lists (instead of a list of dictionaries). See the status reference for details. 20220307: M73 will no longer set print progress to 0 if P is missing. 20220304: There is no longer a default for the extruder parameter of extruder_stepper config sections. If desired, specify extruder: extruder explicitly to associate the stepper motor with the \"extruder\" motion queue at startup. 20220210: The SYNC_STEPPER_TO_EXTRUDER command is deprecated; the SET_EXTRUDER_STEP_DISTANCE command is deprecated; the extruder shared_heater config option is deprecated. These features will be removed in the near future. Replace SET_EXTRUDER_STEP_DISTANCE with SET_EXTRUDER_ROTATION_DISTANCE . Replace SYNC_STEPPER_TO_EXTRUDER with SYNC_EXTRUDER_MOTION . Replace extruder config sections using shared_heater with extruder_stepper config sections and update any activation macros to use SYNC_EXTRUDER_MOTION . 20220116: The tmc2130, tmc2208, tmc2209, and tmc2660 run_current calculation code has changed. For some run_current settings the drivers may now be configured differently. This new configuration should be more accurate, but it may invalidate previous tmc driver tuning. 20211230: Scripts to tune input shaper ( scripts/calibrate_shaper.py and scripts/graph_accelerometer.py ) were migrated to use Python3 by default. As a result, users must install Python3 versions of certain packages (e.g. sudo apt install python3-numpy python3-matplotlib ) to continue using these scripts. For more details, refer to Software installation . Alternatively, users can temporarily force the execution of these scripts under Python 2 by explicitly calling Python2 interpretor in the console: python2 ~/klipper/scripts/calibrate_shaper.py ... 20211110: The \"NTC 100K beta 3950\" temperature sensor is deprecated. This sensor will be removed in the near future. Most users will find the \"Generic 3950\" temperature sensor more accurate. To continue to use the older (typically less accurate) definition, define a custom thermistor with temperature1: 25 , resistance1: 100000 , and beta: 3950 . 20211104: The \"step pulse duration\" option in \"make menuconfig\" has been removed. The default step duration for TMC drivers configured in UART or SPI mode is now 100ns. A new step_pulse_duration setting in the stepper config section should be set for all steppers that need a custom pulse duration. 20211102: Several deprecated features have been removed. The stepper step_distance option has been removed (deprecated on 20201222). The rpi_temperature sensor alias has been removed (deprecated on 20210219). The mcu pin_map option has been removed (deprecated on 20210325). The gcode_macro default_parameter_ 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_ config option is deprecated. Use the params pseudo-variable to access macro parameters. Other methods for accessing macro parameters will be removed in the near future. Most users can replace a default_parameter_NAME: VALUE config option with a line like the following in the start of the macro: {% set NAME = params.NAME|default(VALUE)|float %} . See the Command Templates document for examples. 20210430: The SET_VELOCITY_LIMIT (and M204) command may now set a velocity, acceleration, and square_corner_velocity larger than the specified values in the config file. 20210325: Support for the pin_map config option is deprecated. Use the sample-aliases.cfg file to translate to the actual micro-controller pin names. The pin_map config option will be removed in the near future. 20210313: Klipper's support for micro-controllers that communicate with CAN bus has changed. If using CAN bus then all micro-controllers must be reflashed and the Klipper configuration must be updated . 20210310: The TMC2660 default for driver_SFILT has been changed from 1 to 0. 20210227: TMC stepper motor drivers in UART or SPI mode are now queried once per second whenever they are enabled - if the driver can not be contacted or if the driver reports an error, then Klipper will transition to a shutdown state. 20210219: The rpi_temperature module has been renamed to temperature_host . Replace any occurrences of sensor_type: rpi_temperature with sensor_type: temperature_host . The path to the temperature file may be specified in the sensor_path config variable. The rpi_temperature name is deprecated and will be removed in the near future. 20210201: The TEST_RESONANCES command will now disable input shaping if it was previously enabled (and re-enable it after the test). In order to override this behavior and keep the input shaping enabled, one can pass an additional parameter INPUT_SHAPING=1 to the command. 20210201: The ACCELEROMETER_MEASURE command will now append the name of the accelerometer chip to the output file name if the chip was given a name in the corresponding adxl345 section of the printer.cfg. 20201222: The step_distance setting in the stepper config sections is deprecated. It is advised to update the config to use the rotation_distance setting. Support for step_distance will be removed in the near future. 20201218: The endstop_phase setting in the endstop_phase module has been replaced with trigger_phase . If using the endstop phases module then it will be necessary to convert to rotation_distance and recalibrate any endstop phases by running the ENDSTOP_PHASE_CALIBRATE command. 20201218: Rotary delta and polar printers must now specify a gear_ratio for their rotary steppers, and they may no longer specify a step_distance parameter. See the config reference for the format of the new gear_ratio parameter. 20201213: It is not valid to specify a Z \"position_endstop\" when using \"probe:z_virtual_endstop\". An error will now be raised if a Z \"position_endstop\" is specified with \"probe:z_virtual_endstop\". Remove the Z \"position_endstop\" definition to fix the error. 20201120: The [board_pins] config section now specifies the mcu name in an explicit mcu: parameter. If using board_pins for a secondary mcu, then the config must be updated to specify that name. See the config reference for further details. 20201112: The time reported by print_stats.print_duration has changed. The duration prior to the first detected extrusion is now excluded. 20201029: The neopixel color_order_GRB config option has been removed. If necessary, update the config to set the new color_order option to RGB, GRB, RGBW, or GRBW. 20201029: The serial option in the mcu config section no longer defaults to /dev/ttyS0. In the rare situation where /dev/ttyS0 is the desired serial port, it must be specified explicitly. 20201020: Klipper v0.9.0 released. 20200902: The RTD resistance-to-temperature calculation for MAX31865 converters has been corrected to not read low. If you are using such a device, you should recalibrate your print temperature and PID settings. 20200816: The gcode macro printer.gcode object has been renamed to printer.gcode_move . Several undocumented variables in printer.toolhead and printer.gcode have been removed. See docs/Command_Templates.md for a list of available template variables. 20200816: The gcode macro \"action_\" system has changed. Replace any calls to printer.gcode.action_emergency_stop() with action_emergency_stop() , printer.gcode.action_respond_info() with action_respond_info() , and printer.gcode.action_respond_error() with action_raise_error() . 20200809: The menu system has been rewritten. If the menu has been customized then it will be necessary to update to the new configuration. See config/example-menu.cfg for configuration details and see klippy/extras/display/menu.cfg for examples. 20200731: The behavior of the progress attribute reported by the virtual_sdcard printer object has changed. Progress is no longer reset to 0 when a print is paused. It will now always report progress based on the internal file position, or 0 if no file is currently loaded. 20200725: The servo enable config parameter and the SET_SERVO ENABLE parameter have been removed. Update any macros to use SET_SERVO SERVO=my_servo WIDTH=0 to disable a servo. 20200608: The LCD display support has changed the name of some internal \"glyphs\". If a custom display layout was implemented it may be necessary to update to the latest glyph names (see klippy/extras/display/display.cfg for a list of available glyphs). 20200606: The pin names on linux mcu have changed. Pins now have names of the form gpiochip/gpio . For gpiochip0 you can also use a short gpio . For example, what was previously referred to as P20 now becomes gpio20 or gpiochip0/gpio20 . 20200603: The default 16x4 LCD layout will no longer show the estimated time remaining in a print. (Only the elapsed time will be shown.) If the old behavior is desired one can customize the menu display with that information (see the description of display_data in config/example-extras.cfg for details). 20200531: The default USB vendor/product id is now 0x1d50/0x614e. These new ids are reserved for Klipper (thanks to the openmoko project). This change should not require any config changes, but the new ids may appear in system logs. 20200524: The default value for the tmc5160 pwm_freq field is now zero (instead of one). 20200425: The gcode_macro command template variable printer.heater was renamed to printer.heaters . 20200313: The default lcd layout for multi-extruder printers with a 16x4 screen has changed. The single extruder screen layout is now the default and it will show the currently active extruder. To use the previous display layout set \"display_group: _multiextruder_16x4\" in the [display] section of the printer.cfg file. 20200308: The default __test menu item was removed. If the config file has a custom menu then be sure to remove all references to this __test menu item. 20200308: The menu \"deck\" and \"card\" options were removed. To customize the layout of an lcd screen use the new display_data config sections (see config/example-extras.cfg for the details). 20200109: The bed_mesh module now references the probe's location in for the mesh configuration. As such, some configuration options have been renamed to more accurately reflect their intended functionality. For rectangular beds, min_point and max_point have been renamed to mesh_min and mesh_max respectively. For round beds, bed_radius has been renamed to mesh_radius . A new mesh_origin option has also been added for round beds. Note that these changes are also incompatible with previously saved mesh profiles. If an incompatible profile is detected it will be ignored and scheduled for removal. The removal process can be completed by issuing the SAVE_CONFIG command. The user will need to re-calibrate each profile. 20191218: The display config section no longer supports \"lcd_type: st7567\". Use the \"uc1701\" display type instead - set \"lcd_type: uc1701\" and change the \"rs_pin: some_pin\" to \"rst_pin: some_pin\". It may also be necessary to add a \"contrast: 60\" config setting. 20191210: The builtin T0, T1, T2, ... commands have been removed. The extruder activate_gcode and deactivate_gcode config options have been removed. If these commands (and scripts) are needed then define individual [gcode_macro T0] style macros that call the ACTIVATE_EXTRUDER command. See the config/sample-idex.cfg and sample-multi-extruder.cfg files for examples. 20191210: Support for the M206 command has been removed. Replace with calls to SET_GCODE_OFFSET. If support for M206 is needed, add a [gcode_macro M206] config section that calls SET_GCODE_OFFSET. (For example \"SET_GCODE_OFFSET Z=-{params.Z}\".) 20191202: Support for the undocumented \"S\" parameter of the \"G4\" command has been removed. Replace any occurrences of S with the standard \"P\" parameter (the delay specified in milliseconds). 20191126: The USB names have changed on micro-controllers with native USB support. They now use a unique chip id by default (where available). If an \"mcu\" config section uses a \"serial\" setting that starts with \"/dev/serial/by-id/\" then it may be necessary to update the config. Run \"ls /dev/serial/by-id/*\" in an ssh terminal to determine the new id. 20191121: The pressure_advance_lookahead_time parameter has been removed. See example.cfg for alternate configuration settings. 20191112: The tmc stepper driver virtual enable capability is now automatically enabled if the stepper does not have a dedicated stepper enable pin. Remove references to tmcXXXX:virtual_enable from the config. The ability to control multiple pins in the stepper enable_pin config has been removed. If multiple pins are needed then use a multi_pin config section. 20191107: The primary extruder config section must be specified as \"extruder\" and may no longer be specified as \"extruder0\". Gcode command templates that query the extruder status are now accessed via \"{printer.extruder}\". 20191021: Klipper v0.8.0 released 20191003: The move_to_previous option in [safe_z_homing] now defaults to False. (It was effectively False prior to 20190918.) 20190918: The zhop option in [safe_z_homing] is always re-applied after Z axis homing completed. This might need users to update custom scripts based on this module. 20190806: The SET_NEOPIXEL command has been renamed to SET_LED. 20190726: The mcp4728 digital-to-analog code has changed. The default i2c_address is now 0x60 and the voltage reference is now relative to the mcp4728's internal 2.048 volt reference. 20190710: The z_hop option was removed from the [firmware_retract] config section. The z_hop support was incomplete and could cause incorrect behavior with several common slicers. 20190710: The optional parameters of the PROBE_ACCURACY command have changed. It may be necessary to update any macros or scripts that use that command. 20190628: All configuration options have been removed from the [skew_correction] section. Configuration for skew_correction is now done via the SET_SKEW gcode. See Skew Correction for recommended usage. 20190607: The \"variable_X\" parameters of gcode_macro (along with the VALUE parameter of SET_GCODE_VARIABLE) are now parsed as Python literals. If a value needs to be assigned a string then wrap the value in quotes so that it is evaluated as a string. 20190606: The \"samples\", \"samples_result\", and \"sample_retract_dist\" config options have been moved to the \"probe\" config section. These options are no longer supported in the \"delta_calibrate\", \"bed_tilt\", \"bed_mesh\", \"screws_tilt_adjust\", \"z_tilt\", or \"quad_gantry_level\" config sections. 20190528: The magic \"status\" variable in gcode_macro template evaluation has been renamed to \"printer\". 20190520: The SET_GCODE_OFFSET command has changed; update any g-code macros accordingly. The command will no longer apply the requested offset to the next G1 command. The old behavior may be approximated by using the new \"MOVE=1\" parameter. 20190404: The Python host software packages were updated. Users will need to rerun the ~/klipper/scripts/install-octopi.sh script (or otherwise upgrade the python dependencies if not using a standard OctoPi installation). 20190404: The i2c_bus and spi_bus parameters (in various config sections) now take a bus name instead of a number. 20190404: The sx1509 config parameters have changed. The 'address' parameter is now 'i2c_address' and it must be specified as a decimal number. Where 0x3E was previously used, specify 62. 20190328: The min_speed value in [temperature_fan] config will now be respected and the fan will always run at this speed or higher in PID mode. 20190322: The default value for \"driver_HEND\" in [tmc2660] config sections was changed from 6 to 3. The \"driver_VSENSE\" field was removed (it is now automatically calculated from run_current). 20190310: The [controller_fan] config section now always takes a name (such as [controller_fan my_controller_fan]). 20190308: The \"driver_BLANK_TIME_SELECT\" field in [tmc2130] and [tmc2208] config sections has been renamed to \"driver_TBL\". 20190308: The [tmc2660] config section has changed. A new sense_resistor config parameter must now be provided. The meaning of several of the driver_XXX parameters has changed. 20190228: Users of SPI or I2C on SAMD21 boards must now specify the bus pins via a [samd_sercom] config section. 20190224: The bed_shape option has been removed from bed_mesh. The radius option has been renamed to bed_radius. Users with round beds should supply the bed_radius and round_probe_count options. 20190107: The i2c_address parameter in the mcp4451 config section changed. This is a common setting on Smoothieboards. The new value is half the old value (88 should be changed to 44, and 90 should be changed to 45). 20181220: Klipper v0.7.0 released","title":"Changes"},{"location":"Config_Reference.html","text":"Configuration reference \u00b6 This document is a reference for options available in the Klipper config file. The descriptions in this document are formatted so that it is possible to cut-and-paste them into a printer config file. See the installation document for information on setting up Klipper and choosing an initial config file. Micro-controller configuration \u00b6 Format of micro-controller pin names \u00b6 Many config options require the name of a micro-controller pin. Klipper uses the hardware names for these pins - for example PA4 . Pin names may be preceded by ! to indicate that a reverse polarity should be used (eg, trigger on low instead of high). Input pins may be preceded by ^ to indicate that a hardware pull-up resistor should be enabled for the pin. If the micro-controller supports pull-down resistors then an input pin may alternatively be preceded by ~ . Note, some config sections may \"create\" additional pins. Where this occurs, the config section defining the pins must be listed in the config file before any sections using those pins. [mcu] \u00b6 Configuration of the primary micro-controller. [mcu] serial: # The serial port to connect to the MCU. If unsure (or if it # changes) see the \"Where's my serial port?\" section of the FAQ. # This parameter must be provided when using a serial port. #baud: 250000 # The baud rate to use. The default is 250000. #canbus_uuid: # If using a device connected to a CAN bus then this sets the unique # chip identifier to connect to. This value must be provided when using # CAN bus for communication. #canbus_interface: # If using a device connected to a CAN bus then this sets the CAN # network interface to use. The default is 'can0'. #restart_method: # This controls the mechanism the host will use to reset the # micro-controller. The choices are 'arduino', 'cheetah', 'rpi_usb', # and 'command'. The 'arduino' method (toggle DTR) is common on # Arduino boards and clones. The 'cheetah' method is a special # method needed for some Fysetc Cheetah boards. The 'rpi_usb' method # is useful on Raspberry Pi boards with micro-controllers powered # over USB - it briefly disables power to all USB ports to # accomplish a micro-controller reset. The 'command' method involves # sending a Klipper command to the micro-controller so that it can # reset itself. The default is 'arduino' if the micro-controller # communicates over a serial port, 'command' otherwise. [mcu my_extra_mcu] \u00b6 Additional micro-controllers (one may define any number of sections with an \"mcu\" prefix). Additional micro-controllers introduce additional pins that may be configured as heaters, steppers, fans, etc.. For example, if an \"[mcu extra_mcu]\" section is introduced, then pins such as \"extra_mcu:ar9\" may then be used elsewhere in the config (where \"ar9\" is a hardware pin name or alias name on the given mcu). [mcu my_extra_mcu] # See the \"mcu\" section for configuration parameters. Common kinematic settings \u00b6 [printer] \u00b6 The printer section controls high level printer settings. [printer] kinematics: # The type of printer in use. This option may be one of: cartesian, # corexy, corexz, hybrid_corexy, hybrid_corexz, generic_cartesian, # rotary_delta, delta, deltesian, polar, winch, or none. # This parameter must be specified. max_velocity: # Maximum velocity (in mm/s) of the toolhead (relative to the # print). This value may be changed at runtime using the # SET_VELOCITY_LIMIT command. This parameter must be specified. max_accel: # Maximum acceleration (in mm/s^2) of the toolhead (relative to the # print). Although this parameter is described as a \"maximum\" # acceleration, in practice most moves that accelerate or decelerate # will do so at the rate specified here. The value specified here # may be changed at runtime using the SET_VELOCITY_LIMIT command. # This parameter must be specified. #minimum_cruise_ratio: 0.5 # Most moves will accelerate to a cruising speed, travel at that # cruising speed, and then decelerate. However, some moves that # travel a short distance could nominally accelerate and then # immediately decelerate. This option reduces the top speed of these # moves to ensure there is always a minimum distance traveled at a # cruising speed. That is, it enforces a minimum distance traveled # at cruising speed relative to the total distance traveled. It is # intended to reduce the top speed of short zigzag moves (and thus # reduce printer vibration from these moves). For example, a # minimum_cruise_ratio of 0.5 would ensure that a standalone 1.5mm # move would have a minimum cruising distance of 0.75mm. Specify a # ratio of 0.0 to disable this feature (there would be no minimum # cruising distance enforced between acceleration and deceleration). # The value specified here may be changed at runtime using the # SET_VELOCITY_LIMIT command. The default is 0.5. #square_corner_velocity: 5.0 # The maximum velocity (in mm/s) that the toolhead may travel a 90 # degree corner at. A non-zero value can reduce changes in extruder # flow rates by enabling instantaneous velocity changes of the # toolhead during cornering. This value configures the internal # centripetal velocity cornering algorithm; corners with angles # larger than 90 degrees will have a higher cornering velocity while # corners with angles less than 90 degrees will have a lower # cornering velocity. If this is set to zero then the toolhead will # decelerate to zero at each corner. The value specified here may be # changed at runtime using the SET_VELOCITY_LIMIT command. The # default is 5mm/s. [stepper] \u00b6 Stepper motor definitions. Different printer types (as specified by the \"kinematics\" option in the [printer] config section) require different names for the stepper (eg, stepper_x vs stepper_a ). Below are common stepper definitions. See the rotation distance document for information on calculating the rotation_distance parameter. See the Multi-MCU homing document for information on homing using multiple micro-controllers. [stepper_x] step_pin: # Step GPIO pin (triggered high). This parameter must be provided. dir_pin: # Direction GPIO pin (high indicates positive direction). This # parameter must be provided. enable_pin: # Enable pin (default is enable high; use ! to indicate enable # low). If this parameter is not provided then the stepper motor # driver must always be enabled. rotation_distance: # Distance (in mm) that the axis travels with one full rotation of # the stepper motor (or final gear if gear_ratio is specified). # This parameter must be provided. microsteps: # The number of microsteps the stepper motor driver uses. This # parameter must be provided. #full_steps_per_rotation: 200 # The number of full steps for one rotation of the stepper motor. # Set this to 200 for a 1.8 degree stepper motor or set to 400 for a # 0.9 degree motor. The default is 200. #gear_ratio: # The gear ratio if the stepper motor is connected to the axis via a # gearbox. For example, one may specify \"5:1\" if a 5 to 1 gearbox is # in use. If the axis has multiple gearboxes one may specify a comma # separated list of gear ratios (for example, \"57:11, 2:1\"). If a # gear_ratio is specified then rotation_distance specifies the # distance the axis travels for one full rotation of the final gear. # The default is to not use a gear ratio. #step_pulse_duration: # The minimum time between the step pulse signal edge and the # following \"unstep\" signal edge. This is also used to set the # minimum time between a step pulse and a direction change signal. # The default is 0.000000100 (100ns) for TMC steppers that are # configured in UART or SPI mode, and the default is 0.000002 (which # is 2us) for all other steppers. endstop_pin: # Endstop switch detection pin. If this endstop pin is on a # different mcu than the stepper motor then it enables \"multi-mcu # homing\". This parameter must be provided for the X, Y, and Z # steppers on cartesian style printers. #position_min: 0 # Minimum valid distance (in mm) the user may command the stepper to # move to. The default is 0mm. position_endstop: # Location of the endstop (in mm). This parameter must be provided # for the X, Y, and Z steppers on cartesian style printers. position_max: # Maximum valid distance (in mm) the user may command the stepper to # move to. This parameter must be provided for the X, Y, and Z # steppers on cartesian style printers. #homing_speed: 5.0 # Maximum velocity (in mm/s) of the stepper when homing. The default # is 5mm/s. #homing_retract_dist: 5.0 # Distance to backoff (in mm) before homing a second time during # homing. Set this to zero to disable the second home. The default # is 5mm. #homing_retract_speed: # Speed to use on the retract move after homing in case this should # be different from the homing speed, which is the default for this # parameter #second_homing_speed: # Velocity (in mm/s) of the stepper when performing the second home. # The default is homing_speed/2. #homing_positive_dir: # If true, homing will cause the stepper to move in a positive # direction (away from zero); if false, home towards zero. It is # better to use the default than to specify this parameter. The # default is true if position_endstop is near position_max and false # if near position_min. Cartesian Kinematics \u00b6 See example-cartesian.cfg for an example cartesian kinematics config file. Only parameters specific to cartesian printers are described here - see common kinematic settings for available parameters. [printer] kinematics: cartesian max_z_velocity: # This sets the maximum velocity (in mm/s) of movement along the z # axis. This setting can be used to restrict the maximum speed of # the z stepper motor. The default is to use max_velocity for # max_z_velocity. max_z_accel: # This sets the maximum acceleration (in mm/s^2) of movement along # the z axis. It limits the acceleration of the z stepper motor. The # default is to use max_accel for max_z_accel. # The stepper_x section is used to describe the stepper controlling # the X axis in a cartesian robot. [stepper_x] # The stepper_y section is used to describe the stepper controlling # the Y axis in a cartesian robot. [stepper_y] # The stepper_z section is used to describe the stepper controlling # the Z axis in a cartesian robot. [stepper_z] Linear Delta Kinematics \u00b6 See example-delta.cfg for an example linear delta kinematics config file. See the delta calibrate guide for information on calibration. Only parameters specific to linear delta printers are described here - see common kinematic settings for available parameters. [printer] kinematics: delta max_z_velocity: # For delta printers this limits the maximum velocity (in mm/s) of # moves with z axis movement. This setting can be used to reduce the # maximum speed of up/down moves (which require a higher step rate # than other moves on a delta printer). The default is to use # max_velocity for max_z_velocity. #max_z_accel: # This sets the maximum acceleration (in mm/s^2) of movement along # the z axis. Setting this may be useful if the printer can reach higher # acceleration on XY moves than Z moves (eg, when using input shaper). # The default is to use max_accel for max_z_accel. #minimum_z_position: 0 # The minimum Z position that the user may command the head to move # to. The default is 0. delta_radius: # Radius (in mm) of the horizontal circle formed by the three linear # axis towers. This parameter may also be calculated as: # delta_radius = smooth_rod_offset - effector_offset - carriage_offset # This parameter must be provided. #print_radius: # The radius (in mm) of valid toolhead XY coordinates. One may use # this setting to customize the range checking of toolhead moves. If # a large value is specified here then it may be possible to command # the toolhead into a collision with a tower. The default is to use # delta_radius for print_radius (which would normally prevent a # tower collision). # The stepper_a section describes the stepper controlling the front # left tower (at 210 degrees). This section also controls the homing # parameters (homing_speed, homing_retract_dist) for all towers. [stepper_a] position_endstop: # Distance (in mm) between the nozzle and the bed when the nozzle is # in the center of the build area and the endstop triggers. This # parameter must be provided for stepper_a; for stepper_b and # stepper_c this parameter defaults to the value specified for # stepper_a. arm_length: # Length (in mm) of the diagonal rod that connects this tower to the # print head. This parameter must be provided for stepper_a; for # stepper_b and stepper_c this parameter defaults to the value # specified for stepper_a. #angle: # This option specifies the angle (in degrees) that the tower is # at. The default is 210 for stepper_a, 330 for stepper_b, and 90 # for stepper_c. # The stepper_b section describes the stepper controlling the front # right tower (at 330 degrees). [stepper_b] # The stepper_c section describes the stepper controlling the rear # tower (at 90 degrees). [stepper_c] # The delta_calibrate section enables a DELTA_CALIBRATE extended # g-code command that can calibrate the tower endstop positions and # angles. [delta_calibrate] radius: # Radius (in mm) of the area that may be probed. This is the radius # of nozzle coordinates to be probed; if using an automatic probe # with an XY offset then choose a radius small enough so that the # probe always fits over the bed. This parameter must be provided. #speed: 50 # The speed (in mm/s) of non-probing moves during the calibration. # The default is 50. #horizontal_move_z: 5 # The height (in mm) that the head should be commanded to move to # just prior to starting a probe operation. The default is 5. Deltesian Kinematics \u00b6 See example-deltesian.cfg for an example deltesian kinematics config file. Only parameters specific to deltesian printers are described here - see common kinematic settings for available parameters. [printer] kinematics: deltesian max_z_velocity: # For deltesian printers, this limits the maximum velocity (in mm/s) of # moves with z axis movement. This setting can be used to reduce the # maximum speed of up/down moves (which require a higher step rate # than other moves on a deltesian printer). The default is to use # max_velocity for max_z_velocity. #max_z_accel: # This sets the maximum acceleration (in mm/s^2) of movement along # the z axis. Setting this may be useful if the printer can reach higher # acceleration on XY moves than Z moves (eg, when using input shaper). # The default is to use max_accel for max_z_accel. #minimum_z_position: 0 # The minimum Z position that the user may command the head to move # to. The default is 0. #min_angle: 5 # This represents the minimum angle (in degrees) relative to horizontal # that the deltesian arms are allowed to achieve. This parameter is # intended to restrict the arms from becoming completely horizontal, # which would risk accidental inversion of the XZ axis. The default is 5. #print_width: # The distance (in mm) of valid toolhead X coordinates. One may use # this setting to customize the range checking of toolhead moves. If # a large value is specified here then it may be possible to command # the toolhead into a collision with a tower. This setting usually # corresponds to bed width (in mm). #slow_ratio: 3 # The ratio used to limit velocity and acceleration on moves near the # extremes of the X axis. If vertical distance divided by horizontal # distance exceeds the value of slow_ratio, then velocity and # acceleration are limited to half their nominal values. If vertical # distance divided by horizontal distance exceeds twice the value of # the slow_ratio, then velocity and acceleration are limited to one # quarter of their nominal values. The default is 3. # The stepper_left section is used to describe the stepper controlling # the left tower. This section also controls the homing parameters # (homing_speed, homing_retract_dist) for all towers. [stepper_left] position_endstop: # Distance (in mm) between the nozzle and the bed when the nozzle is # in the center of the build area and the endstops are triggered. This # parameter must be provided for stepper_left; for stepper_right this # parameter defaults to the value specified for stepper_left. arm_length: # Length (in mm) of the diagonal rod that connects the tower carriage to # the print head. This parameter must be provided for stepper_left; for # stepper_right, this parameter defaults to the value specified for # stepper_left. arm_x_length: # Horizontal distance between the print head and the tower when the # printers is homed. This parameter must be provided for stepper_left; # for stepper_right, this parameter defaults to the value specified for # stepper_left. # The stepper_right section is used to describe the stepper controlling the # right tower. [stepper_right] # The stepper_y section is used to describe the stepper controlling # the Y axis in a deltesian robot. [stepper_y] CoreXY Kinematics \u00b6 See example-corexy.cfg for an example corexy (and h-bot) kinematics file. Only parameters specific to corexy printers are described here - see common kinematic settings for available parameters. [printer] kinematics: corexy max_z_velocity: # This sets the maximum velocity (in mm/s) of movement along the z # axis. This setting can be used to restrict the maximum speed of # the z stepper motor. The default is to use max_velocity for # max_z_velocity. max_z_accel: # This sets the maximum acceleration (in mm/s^2) of movement along # the z axis. It limits the acceleration of the z stepper motor. The # default is to use max_accel for max_z_accel. # The stepper_x section is used to describe the X axis as well as the # stepper controlling the X+Y movement. [stepper_x] # The stepper_y section is used to describe the Y axis as well as the # stepper controlling the X-Y movement. [stepper_y] # The stepper_z section is used to describe the stepper controlling # the Z axis. [stepper_z] CoreXZ Kinematics \u00b6 See example-corexz.cfg for an example corexz kinematics config file. Only parameters specific to corexz printers are described here - see common kinematic settings for available parameters. [printer] kinematics: corexz max_z_velocity: # This sets the maximum velocity (in mm/s) of movement along the z # axis. The default is to use max_velocity for max_z_velocity. max_z_accel: # This sets the maximum acceleration (in mm/s^2) of movement along # the z axis. The default is to use max_accel for max_z_accel. # The stepper_x section is used to describe the X axis as well as the # stepper controlling the X+Z movement. [stepper_x] # The stepper_y section is used to describe the stepper controlling # the Y axis. [stepper_y] # The stepper_z section is used to describe the Z axis as well as the # stepper controlling the X-Z movement. [stepper_z] Hybrid-CoreXY Kinematics \u00b6 See example-hybrid-corexy.cfg for an example hybrid corexy kinematics config file. This kinematic is also known as Markforged kinematic. Only parameters specific to hybrid corexy printers are described here see common kinematic settings for available parameters. [printer] kinematics: hybrid_corexy max_z_velocity: # This sets the maximum velocity (in mm/s) of movement along the z # axis. The default is to use max_velocity for max_z_velocity. max_z_accel: # This sets the maximum acceleration (in mm/s^2) of movement along # the z axis. The default is to use max_accel for max_z_accel. # The stepper_x section is used to describe the X axis as well as the # stepper controlling the X-Y movement. [stepper_x] # The stepper_y section is used to describe the stepper controlling # the Y axis. [stepper_y] # The stepper_z section is used to describe the stepper controlling # the Z axis. [stepper_z] Hybrid-CoreXZ Kinematics \u00b6 See example-hybrid-corexz.cfg for an example hybrid corexz kinematics config file. This kinematic is also known as Markforged kinematic. Only parameters specific to hybrid corexy printers are described here see common kinematic settings for available parameters. [printer] kinematics: hybrid_corexz max_z_velocity: # This sets the maximum velocity (in mm/s) of movement along the z # axis. The default is to use max_velocity for max_z_velocity. max_z_accel: # This sets the maximum acceleration (in mm/s^2) of movement along # the z axis. The default is to use max_accel for max_z_accel. # The stepper_x section is used to describe the X axis as well as the # stepper controlling the X-Z movement. [stepper_x] # The stepper_y section is used to describe the stepper controlling # the Y axis. [stepper_y] # The stepper_z section is used to describe the stepper controlling # the Z axis. [stepper_z] Polar Kinematics \u00b6 See example-polar.cfg for an example polar kinematics config file. Only parameters specific to polar printers are described here - see common kinematic settings for available parameters. POLAR KINEMATICS ARE A WORK IN PROGRESS. Moves around the 0, 0 position are known to not work properly. [printer] kinematics: polar max_z_velocity: # This sets the maximum velocity (in mm/s) of movement along the z # axis. This setting can be used to restrict the maximum speed of # the z stepper motor. The default is to use max_velocity for # max_z_velocity. max_z_accel: # This sets the maximum acceleration (in mm/s^2) of movement along # the z axis. It limits the acceleration of the z stepper motor. The # default is to use max_accel for max_z_accel. # The stepper_bed section is used to describe the stepper controlling # the bed. [stepper_bed] gear_ratio: # A gear_ratio must be specified and rotation_distance may not be # specified. For example, if the bed has an 80 toothed pulley driven # by a stepper with a 16 toothed pulley then one would specify a # gear ratio of \"80:16\". This parameter must be provided. # The stepper_arm section is used to describe the stepper controlling # the carriage on the arm. [stepper_arm] # The stepper_z section is used to describe the stepper controlling # the Z axis. [stepper_z] Rotary delta Kinematics \u00b6 See example-rotary-delta.cfg for an example rotary delta kinematics config file. Only parameters specific to rotary delta printers are described here - see common kinematic settings for available parameters. ROTARY DELTA KINEMATICS ARE A WORK IN PROGRESS. Homing moves may timeout and some boundary checks are not implemented. [printer] kinematics: rotary_delta max_z_velocity: # For delta printers this limits the maximum velocity (in mm/s) of # moves with z axis movement. This setting can be used to reduce the # maximum speed of up/down moves (which require a higher step rate # than other moves on a delta printer). The default is to use # max_velocity for max_z_velocity. #minimum_z_position: 0 # The minimum Z position that the user may command the head to move # to. The default is 0. shoulder_radius: # Radius (in mm) of the horizontal circle formed by the three # shoulder joints, minus the radius of the circle formed by the # effector joints. This parameter may also be calculated as: # shoulder_radius = (delta_f - delta_e) / sqrt(12) # This parameter must be provided. shoulder_height: # Distance (in mm) of the shoulder joints from the bed, minus the # effector toolhead height. This parameter must be provided. # The stepper_a section describes the stepper controlling the rear # right arm (at 30 degrees). This section also controls the homing # parameters (homing_speed, homing_retract_dist) for all arms. [stepper_a] gear_ratio: # A gear_ratio must be specified and rotation_distance may not be # specified. For example, if the arm has an 80 toothed pulley driven # by a pulley with 16 teeth, which is in turn connected to a 60 # toothed pulley driven by a stepper with a 16 toothed pulley, then # one would specify a gear ratio of \"80:16, 60:16\". This parameter # must be provided. position_endstop: # Distance (in mm) between the nozzle and the bed when the nozzle is # in the center of the build area and the endstop triggers. This # parameter must be provided for stepper_a; for stepper_b and # stepper_c this parameter defaults to the value specified for # stepper_a. upper_arm_length: # Length (in mm) of the arm connecting the \"shoulder joint\" to the # \"elbow joint\". This parameter must be provided for stepper_a; for # stepper_b and stepper_c this parameter defaults to the value # specified for stepper_a. lower_arm_length: # Length (in mm) of the arm connecting the \"elbow joint\" to the # \"effector joint\". This parameter must be provided for stepper_a; # for stepper_b and stepper_c this parameter defaults to the value # specified for stepper_a. #angle: # This option specifies the angle (in degrees) that the arm is at. # The default is 30 for stepper_a, 150 for stepper_b, and 270 for # stepper_c. # The stepper_b section describes the stepper controlling the rear # left arm (at 150 degrees). [stepper_b] # The stepper_c section describes the stepper controlling the front # arm (at 270 degrees). [stepper_c] # The delta_calibrate section enables a DELTA_CALIBRATE extended # g-code command that can calibrate the shoulder endstop positions. [delta_calibrate] radius: # Radius (in mm) of the area that may be probed. This is the radius # of nozzle coordinates to be probed; if using an automatic probe # with an XY offset then choose a radius small enough so that the # probe always fits over the bed. This parameter must be provided. #speed: 50 # The speed (in mm/s) of non-probing moves during the calibration. # The default is 50. #horizontal_move_z: 5 # The height (in mm) that the head should be commanded to move to # just prior to starting a probe operation. The default is 5. Cable winch Kinematics \u00b6 See the example-winch.cfg for an example cable winch kinematics config file. Only parameters specific to cable winch printers are described here - see common kinematic settings for available parameters. CABLE WINCH SUPPORT IS EXPERIMENTAL. Homing is not implemented on cable winch kinematics. In order to home the printer, manually send movement commands until the toolhead is at 0, 0, 0 and then issue a G28 command. [printer] kinematics: winch # The stepper_a section describes the stepper connected to the first # cable winch. A minimum of 3 and a maximum of 26 cable winches may be # defined (stepper_a to stepper_z) though it is common to define 4. [stepper_a] rotation_distance: # The rotation_distance is the nominal distance (in mm) the toolhead # moves towards the cable winch for each full rotation of the # stepper motor. This parameter must be provided. anchor_x: anchor_y: anchor_z: # The X, Y, and Z position of the cable winch in cartesian space. # These parameters must be provided. Generic Cartesian Kinematics \u00b6 See example-generic-cartesian.cfg for an example generic Cartesian kinematics config file. This printer kinematic class allows a user to define in a pretty flexible manner an arbitrary Cartesian-style kinematics. In principle, the regular cartesian, corexy, hybrid_corexy can be defined this way too. However, more importantly, various otherwise unsupported kinematics such as inverted hybrid_corexy or corexyuv can be defined using this kinematic. Notably, the definition of a generic Cartesian kinematic deviates significantly from the other kinematic types. It follows the following convention: a user defines a set of carriages with certain range of motion that can move independently from each other (they should move over the Cartesian axes X, Y, and Z, hence the name of the kinematic) and corresponding endstops that allow the firmware to determine the position of carriages during homing, as well as a set of steppers that move those carriages. The [printer] section must specify the kinematic and other printer-level settings same as the regular Cartesian kinematic: [printer] kinematics: generic_cartesian max_velocity: max_accel: #minimum_cruise_ratio: #square_corner_velocity: #max_z_velocity: #max_z_accel: Then a user must define three carriages for X, Y, and Z axes, e.g.: [carriage carriage_x] axis: # Axis of a carriage, either x, y, or z. This parameter must be provided, # unless a carriage name is x, y, or z itself. endstop_pin: # Endstop switch detection pin. If this endstop pin is on a # different mcu than the stepper motor(s) moving this carriage, # then it enables \"multi-mcu homing\". This parameter must be provided. #position_min: 0 # Minimum valid distance (in mm) the user may command the carriage to # move to. The default is 0mm. position_endstop: # Location of the endstop (in mm). This parameter must be provided. position_max: # Maximum valid distance (in mm) the user may command the stepper to # move to. This parameter must be provided. #homing_speed: 5.0 # Maximum velocity (in mm/s) of the carriage when homing. The default # is 5mm/s. #homing_retract_dist: 5.0 # Distance to backoff (in mm) before homing a second time during # homing. Set this to zero to disable the second home. The default # is 5mm. #homing_retract_speed: # Speed to use on the retract move after homing in case this should # be different from the homing speed, which is the default for this # parameter #second_homing_speed: # Velocity (in mm/s) of the carriage when performing the second home. # The default is homing_speed/2. #homing_positive_dir: # If true, homing will cause the carriage to move in a positive # direction (away from zero); if false, home towards zero. It is # better to use the default than to specify this parameter. The # default is true if position_endstop is near position_max and false # if near position_min. Afterwards, a user specifies the stepper motors that move these carriages, for instance [stepper my_stepper] carriages: # A string describing the carriages the stepper moves. All defined # carriages can be specified here, as well as their linear combinations, # e.g. carriage_x, carriage_x+carriage_y, carriage_y-0.5*carriage_z, # carriage_x-carriage_z, etc. This parameter must be provided. step_pin: dir_pin: enable_pin: rotation_distance: microsteps: #full_steps_per_rotation: 200 #gear_ratio: #step_pulse_duration: See stepper section for more information on the regular stepper parameters. The carriages parameter defines how the stepper affects the motion of the carriages. For example, carriage_x+carriage_y indicates that the motion of the stepper in the positive direction by the distance d moves the carriages carriage_x and carriage_y by the same distance d in the positive direction, while carriage_x-0.5*carriage_y means the motion of the stepper in the positive direction by the distance d moves the carriage carriage_x by the distance d in the positive direction, but the carriage carriage_y will travel distance d/2 in the negative direction. More than a single stepper motor can be defined to drive the same axis or belt. For example, on a CoreXY AWD setups two motors driving the same belt can be defined as [carriage carriage_x] endstop_pin: ... ... [carriage carriage_y] endstop_pin: ... ... [stepper a0] carriages: carriage_x-carriage_y step_pin: ... dir_pin: ... enable_pin: ... rotation_distance: ... ... [stepper a1] carriages: carriage_x-carriage_y step_pin: ... dir_pin: ... enable_pin: ... rotation_distance: ... ... with a0 and a1 steppers having their own control pins, but sharing the same carriages and corresponding endstops. There are situations when a user wants to have more than one endstop per axis. Examples of such configurations include Y axis driven by two independent stepper motors with belts attached to both ends of the X gantry, with effectively two carriages on Y axis each having an independent endstop, and multi-stepper Z axis with each stepper having its own endstop (not to be confused with the configurations with multiple Z motors but only a single endstop). These configurations can be declared by specifying additional carriage(s) with their endstops: [extra_carriage my_carriage] primary_carriage: # The name of the primary carriage this carriage corresponds to. # It also effectively defines the axis the carriage moves over. # This parameter must be provided. endstop_pin: # Endstop switch detection pin. This parameter must be provided. and the corresponding stepper motors, for example: [extra_carriage carriage_y1] primary_carriage: carriage_y endstop_pin: ... [stepper sy1] carriages: carriage_y1 ... Notably, an [extra_carriage] does not define parameters such as position_min , position_max , and position_endstop , but instead inherits them from the specified primary_carriage , thus sharing the same range of motion with the primary carriage. For the references on how to configure IDEX setups, see the dual carriage section. None Kinematics \u00b6 It is possible to define a special \"none\" kinematics to disable kinematic support in Klipper. This may be useful for controlling devices that are not typical 3d-printers or for debugging purposes. [printer] kinematics: none max_velocity: 1 max_accel: 1 # The max_velocity and max_accel parameters must be defined. The # values are not used for \"none\" kinematics. Common extruder and heated bed support \u00b6 [extruder] \u00b6 The extruder section is used to describe the heater parameters for the nozzle hotend along with the stepper controlling the extruder. See the command reference for additional information. See the pressure advance guide for information on tuning pressure advance. [extruder] step_pin: dir_pin: enable_pin: microsteps: rotation_distance: #full_steps_per_rotation: #gear_ratio: # See the \"stepper\" section for a description of the above # parameters. If none of the above parameters are specified then no # stepper will be associated with the nozzle hotend (though a # SYNC_EXTRUDER_MOTION command may associate one at run-time). nozzle_diameter: # Diameter of the nozzle orifice (in mm). This parameter must be # provided. filament_diameter: # The nominal diameter of the raw filament (in mm) as it enters the # extruder. This parameter must be provided. #max_extrude_cross_section: # Maximum area (in mm^2) of an extrusion cross section (eg, # extrusion width multiplied by layer height). This setting prevents # excessive amounts of extrusion during relatively small XY moves. # If a move requests an extrusion rate that would exceed this value # it will cause an error to be returned. The default is: 4.0 * # nozzle_diameter^2 #instantaneous_corner_velocity: 1.000 # The maximum instantaneous velocity change (in mm/s) of the # extruder during the junction of two moves. The default is 1mm/s. #max_extrude_only_distance: 50.0 # Maximum length (in mm of raw filament) that a retraction or # extrude-only move may have. If a retraction or extrude-only move # requests a distance greater than this value it will cause an error # to be returned. The default is 50mm. #max_extrude_only_velocity: #max_extrude_only_accel: # Maximum velocity (in mm/s) and acceleration (in mm/s^2) of the # extruder motor for retractions and extrude-only moves. These # settings do not have any impact on normal printing moves. If not # specified then they are calculated to match the limit an XY # printing move with a cross section of 4.0*nozzle_diameter^2 would # have. #pressure_advance: 0.0 # The amount of raw filament to push into the extruder during # extruder acceleration. An equal amount of filament is retracted # during deceleration. It is measured in millimeters per # millimeter/second. The default is 0, which disables pressure # advance. #pressure_advance_smooth_time: 0.040 # A time range (in seconds) to use when calculating the average # extruder velocity for pressure advance. A larger value results in # smoother extruder movements. This parameter may not exceed 200ms. # This setting only applies if pressure_advance is non-zero. The # default is 0.040 (40 milliseconds). # # The remaining variables describe the extruder heater. heater_pin: # PWM output pin controlling the heater. This parameter must be # provided. #max_power: 1.0 # The maximum power (expressed as a value from 0.0 to 1.0) that the # heater_pin may be set to. The value 1.0 allows the pin to be set # fully enabled for extended periods, while a value of 0.5 would # allow the pin to be enabled for no more than half the time. This # setting may be used to limit the total power output (over extended # periods) to the heater. The default is 1.0. sensor_type: # Type of sensor - common thermistors are \"EPCOS 100K B57560G104F\", # \"ATC Semitec 104GT-2\", \"ATC Semitec 104NT-4-R025H42G\", \"Generic # 3950\",\"Honeywell 100K 135-104LAG-J01\", \"NTC 100K MGB18-104F39050L32\", # \"SliceEngineering 450\", and \"TDK NTCG104LH104JT1\". See the # \"Temperature sensors\" section for other sensors. This parameter # must be provided. sensor_pin: # Analog input pin connected to the sensor. This parameter must be # provided. #pullup_resistor: 4700 # The resistance (in ohms) of the pullup attached to the thermistor. # This parameter is only valid when the sensor is a thermistor. The # default is 4700 ohms. #smooth_time: 1.0 # A time value (in seconds) over which temperature measurements will # be smoothed to reduce the impact of measurement noise. The default # is 1 seconds. control: # Control algorithm (either pid or watermark). This parameter must # be provided. pid_Kp: pid_Ki: pid_Kd: # The proportional (pid_Kp), integral (pid_Ki), and derivative # (pid_Kd) settings for the PID feedback control system. Klipper # evaluates the PID settings with the following general formula: # heater_pwm = (Kp*error + Ki*integral(error) - Kd*derivative(error)) / 255 # Where \"error\" is \"requested_temperature - measured_temperature\" # and \"heater_pwm\" is the requested heating rate with 0.0 being full # off and 1.0 being full on. Consider using the PID_CALIBRATE # command to obtain these parameters. The pid_Kp, pid_Ki, and pid_Kd # parameters must be provided for PID heaters. #max_delta: 2.0 # On 'watermark' controlled heaters this is the number of degrees in # Celsius above the target temperature before disabling the heater # as well as the number of degrees below the target before # re-enabling the heater. The default is 2 degrees Celsius. #pwm_cycle_time: 0.100 # Time in seconds for each software PWM cycle of the heater. It is # not recommended to set this unless there is an electrical # requirement to switch the heater faster than 10 times a second. # The default is 0.100 seconds. #min_extrude_temp: 170 # The minimum temperature (in Celsius) at which extruder move # commands may be issued. The default is 170 Celsius. min_temp: max_temp: # The maximum range of valid temperatures (in Celsius) that the # heater must remain within. This controls a safety feature # implemented in the micro-controller code - should the measured # temperature ever fall outside this range then the micro-controller # will go into a shutdown state. This check can help detect some # heater and sensor hardware failures. Set this range just wide # enough so that reasonable temperatures do not result in an error. # These parameters must be provided. [heater_bed] \u00b6 The heater_bed section describes a heated bed. It uses the same heater settings described in the \"extruder\" section. [heater_bed] heater_pin: sensor_type: sensor_pin: control: min_temp: max_temp: # See the \"extruder\" section for a description of the above parameters. Bed level support \u00b6 [bed_mesh] \u00b6 Mesh Bed Leveling. One may define a bed_mesh config section to enable move transformations that offset the z axis based on a mesh generated from probed points. When using a probe to home the z-axis, it is recommended to define a safe_z_home section in printer.cfg to home toward the center of the print area. See the bed mesh guide and command reference for additional information. Visual Examples: rectangular bed, probe_count = 3, 3: x---x---x (max_point) | x---x---x | (min_point) x---x---x round bed, round_probe_count = 5, bed_radius = r: x (0, r) end / x---x---x \\ (-r, 0) x---x---x---x---x (r, 0) \\ x---x---x / x (0, -r) start [bed_mesh] #speed: 50 # The speed (in mm/s) of non-probing moves during the calibration. # The default is 50. #horizontal_move_z: 5 # The height (in mm) that the head should be commanded to move to # just prior to starting a probe operation. The default is 5. #mesh_radius: # Defines the radius of the mesh to probe for round beds. Note that # the radius is relative to the coordinate specified by the # mesh_origin option. This parameter must be provided for round beds # and omitted for rectangular beds. #mesh_origin: # Defines the center X, Y coordinate of the mesh for round beds. This # coordinate is relative to the probe's location. It may be useful # to adjust the mesh_origin in an effort to maximize the size of the # mesh radius. Default is 0, 0. This parameter must be omitted for # rectangular beds. #mesh_min: # Defines the minimum X, Y coordinate of the mesh for rectangular # beds. This coordinate is relative to the probe's location. This # will be the first point probed, nearest to the origin. This # parameter must be provided for rectangular beds. #mesh_max: # Defines the maximum X, Y coordinate of the mesh for rectangular # beds. Adheres to the same principle as mesh_min, however this will # be the furthest point probed from the bed's origin. This parameter # must be provided for rectangular beds. #probe_count: 3, 3 # For rectangular beds, this is a comma separate pair of integer # values X, Y defining the number of points to probe along each # axis. A single value is also valid, in which case that value will # be applied to both axes. Default is 3, 3. #round_probe_count: 5 # For round beds, this integer value defines the maximum number of # points to probe along each axis. This value must be an odd number. # Default is 5. #fade_start: 1.0 # The gcode z position in which to start phasing out z-adjustment # when fade is enabled. Default is 1.0. #fade_end: 0.0 # The gcode z position in which phasing out completes. When set to a # value below fade_start, fade is disabled. It should be noted that # fade may add unwanted scaling along the z-axis of a print. If a # user wishes to enable fade, a value of 10.0 is recommended. # Default is 0.0, which disables fade. #fade_target: # The z position in which fade should converge. When this value is # set to a non-zero value it must be within the range of z-values in # the mesh. Users that wish to converge to the z homing position # should set this to 0. Default is the average z value of the mesh. #split_delta_z: .025 # The amount of Z difference (in mm) along a move that will trigger # a split. Default is .025. #move_check_distance: 5.0 # The distance (in mm) along a move to check for split_delta_z. # This is also the minimum length that a move can be split. Default # is 5.0. #mesh_pps: 2, 2 # A comma separated pair of integers X, Y defining the number of # points per segment to interpolate in the mesh along each axis. A # \"segment\" can be defined as the space between each probed point. # The user may enter a single value which will be applied to both # axes. Default is 2, 2. #algorithm: lagrange # The interpolation algorithm to use. May be either \"lagrange\" or # \"bicubic\". This option will not affect 3x3 grids, which are forced # to use lagrange sampling. Default is lagrange. #bicubic_tension: .2 # When using the bicubic algorithm the tension parameter above may # be applied to change the amount of slope interpolated. Larger # numbers will increase the amount of slope, which results in more # curvature in the mesh. Default is .2. #zero_reference_position: # An optional X,Y coordinate that specifies the location on the bed # where Z = 0. When this option is specified the mesh will be offset # so that zero Z adjustment occurs at this location. The default is # no zero reference. #faulty_region_1_min: #faulty_region_1_max: # Optional points that define a faulty region. See docs/Bed_Mesh.md # for details on faulty regions. Up to 99 faulty regions may be added. # By default no faulty regions are set. #adaptive_margin: # An optional margin (in mm) to be added around the bed area used by # the defined print objects when generating an adaptive mesh. #scan_overshoot: # The maximum amount of travel (in mm) available outside of the mesh. # For rectangular beds this applies to travel on the X axis, and for round beds # it applies to the entire radius. The tool must be able to travel the amount # specified outside of the mesh. This value is used to optimize the travel # path when performing a \"rapid scan\". The minimum value that may be specified # is 1. The default is no overshoot. [bed_tilt] \u00b6 Bed tilt compensation. One may define a bed_tilt config section to enable move transformations that account for a tilted bed. Note that bed_mesh and bed_tilt are incompatible; both cannot be defined. See the command reference for additional information. [bed_tilt] #x_adjust: 0 # The amount to add to each move's Z height for each mm on the X # axis. The default is 0. #y_adjust: 0 # The amount to add to each move's Z height for each mm on the Y # axis. The default is 0. #z_adjust: 0 # The amount to add to the Z height when the nozzle is nominally at # 0, 0. The default is 0. # The remaining parameters control a BED_TILT_CALIBRATE extended # g-code command that may be used to calibrate appropriate x and y # adjustment parameters. #points: # A list of X, Y coordinates (one per line; subsequent lines # indented) that should be probed during a BED_TILT_CALIBRATE # command. Specify coordinates of the nozzle and be sure the probe # is above the bed at the given nozzle coordinates. The default is # to not enable the command. #speed: 50 # The speed (in mm/s) of non-probing moves during the calibration. # The default is 50. #horizontal_move_z: 5 # The height (in mm) that the head should be commanded to move to # just prior to starting a probe operation. The default is 5. [bed_screws] \u00b6 Tool to help adjust bed leveling screws. One may define a [bed_screws] config section to enable a BED_SCREWS_ADJUST g-code command. See the leveling guide and command reference for additional information. [bed_screws] #screw1: # The X, Y coordinate of the first bed leveling screw. This is a # position to command the nozzle to that is directly above the bed # screw (or as close as possible while still being above the bed). # This parameter must be provided. #screw1_name: # An arbitrary name for the given screw. This name is displayed when # the helper script runs. The default is to use a name based upon # the screw XY location. #screw1_fine_adjust: # An X, Y coordinate to command the nozzle to so that one can fine # tune the bed leveling screw. The default is to not perform fine # adjustments on the bed screw. #screw2: #screw2_name: #screw2_fine_adjust: #... # Additional bed leveling screws. At least three screws must be # defined. #horizontal_move_z: 5 # The height (in mm) that the head should be commanded to move to # when moving from one screw location to the next. The default is 5. #probe_height: 0 # The height of the probe (in mm) after adjusting for the thermal # expansion of bed and nozzle. The default is zero. #speed: 50 # The speed (in mm/s) of non-probing moves during the calibration. # The default is 50. #probe_speed: 5 # The speed (in mm/s) when moving from a horizontal_move_z position # to a probe_height position. The default is 5. [screws_tilt_adjust] \u00b6 Tool to help adjust bed screws tilt using Z probe. One may define a screws_tilt_adjust config section to enable a SCREWS_TILT_CALCULATE g-code command. See the leveling guide and command reference for additional information. [screws_tilt_adjust] #screw1: # The (X, Y) coordinate of the first bed leveling screw. This is a # position to command the nozzle to so that the probe is directly # above the bed screw (or as close as possible while still being # above the bed). This is the base screw used in calculations. This # parameter must be provided. #screw1_name: # An arbitrary name for the given screw. This name is displayed when # the helper script runs. The default is to use a name based upon # the screw XY location. #screw2: #screw2_name: #... # Additional bed leveling screws. At least two screws must be # defined. #speed: 50 # The speed (in mm/s) of non-probing moves during the calibration. # The default is 50. #horizontal_move_z: 5 # The height (in mm) that the head should be commanded to move to # just prior to starting a probe operation. The default is 5. #screw_thread: CW-M3 # The type of screw used for bed leveling, M3, M4, or M5, and the # rotation direction of the knob that is used to level the bed. # Accepted values: CW-M3, CCW-M3, CW-M4, CCW-M4, CW-M5, CCW-M5. # Default value is CW-M3 which most printers use. A clockwise # rotation of the knob decreases the gap between the nozzle and the # bed. Conversely, a counter-clockwise rotation increases the gap. [z_tilt] \u00b6 Multiple Z stepper tilt adjustment. This feature enables independent adjustment of multiple z steppers (see the \"stepper_z1\" section) to adjust for tilt. If this section is present then a Z_TILT_ADJUST extended G-Code command becomes available. [z_tilt] #z_positions: # A list of X, Y coordinates (one per line; subsequent lines # indented) describing the location of each bed \"pivot point\". The # \"pivot point\" is the point where the bed attaches to the given Z # stepper. It is described using nozzle coordinates (the X, Y position # of the nozzle if it could move directly above the point). The # first entry corresponds to stepper_z, the second to stepper_z1, # the third to stepper_z2, etc. This parameter must be provided. #points: # A list of X, Y coordinates (one per line; subsequent lines # indented) that should be probed during a Z_TILT_ADJUST command. # Specify coordinates of the nozzle and be sure the probe is above # the bed at the given nozzle coordinates. This parameter must be # provided. #speed: 50 # The speed (in mm/s) of non-probing moves during the calibration. # The default is 50. #horizontal_move_z: 5 # The height (in mm) that the head should be commanded to move to # just prior to starting a probe operation. The default is 5. #retries: 0 # Number of times to retry if the probed points aren't within # tolerance. #retry_tolerance: 0 # If retries are enabled then retry if largest and smallest probed # points differ more than retry_tolerance. Note the smallest unit of # change here would be a single step. However if you are probing # more points than steppers then you will likely have a fixed # minimum value for the range of probed points which you can learn # by observing command output. [quad_gantry_level] \u00b6 Moving gantry leveling using 4 independently controlled Z motors. Corrects hyperbolic parabola effects (potato chip) on moving gantry which is more flexible. WARNING: Using this on a moving bed may lead to undesirable results. If this section is present then a QUAD_GANTRY_LEVEL extended G-Code command becomes available. This routine assumes the following Z motor configuration: ---------------- |Z1 Z2| | --------- | | | | | | | | | | x-------- | |Z Z3| ---------------- Where x is the 0, 0 point on the bed [quad_gantry_level] #gantry_corners: # A newline separated list of X, Y coordinates describing the two # opposing corners of the gantry. The first entry corresponds to Z, # the second to Z2. This parameter must be provided. #points: # A newline separated list of four X, Y points that should be probed # during a QUAD_GANTRY_LEVEL command. Order of the locations is # important, and should correspond to Z, Z1, Z2, and Z3 location in # order. This parameter must be provided. For maximum accuracy, # ensure your probe offsets are configured. #speed: 50 # The speed (in mm/s) of non-probing moves during the calibration. # The default is 50. #horizontal_move_z: 5 # The height (in mm) that the head should be commanded to move to # just prior to starting a probe operation. The default is 5. #max_adjust: 4 # Safety limit if an adjustment greater than this value is requested # quad_gantry_level will abort. #retries: 0 # Number of times to retry if the probed points aren't within # tolerance. #retry_tolerance: 0 # If retries are enabled then retry if largest and smallest probed # points differ more than retry_tolerance. [skew_correction] \u00b6 Printer Skew Correction. It is possible to use software to correct printer skew across 3 planes, xy, xz, yz. This is done by printing a calibration model along a plane and measuring three lengths. Due to the nature of skew correction these lengths are set via gcode. See Skew Correction and Command Reference for details. [skew_correction] [z_thermal_adjust] \u00b6 Temperature-dependant toolhead Z position adjustment. Compensate for vertical toolhead movement caused by thermal expansion of the printer's frame in real-time using a temperature sensor (typically coupled to a vertical section of frame). See also: extended g-code commands . [z_thermal_adjust] #temp_coeff: # The temperature coefficient of expansion, in mm/degC. For example, a # temp_coeff of 0.01 mm/degC will move the Z axis downwards by 0.01 mm for # every degree Celsius that the temperature sensor increases. Defaults to # 0.0 mm/degC, which applies no adjustment. #smooth_time: # Smoothing window applied to the temperature sensor, in seconds. Can reduce # motor noise from excessive small corrections in response to sensor noise. # The default is 2.0 seconds. #z_adjust_off_above: # Disables adjustments above this Z height [mm]. The last computed correction # will remain applied until the toolhead moves below the specified Z height # again. The default is 99999999.0 mm (always on). #max_z_adjustment: # Maximum absolute adjustment that can be applied to the Z axis [mm]. The # default is 99999999.0 mm (unlimited). #sensor_type: #sensor_pin: #min_temp: #max_temp: # Temperature sensor configuration. # See the \"extruder\" section for the definition of the above # parameters. #gcode_id: # See the \"heater_generic\" section for the definition of this # parameter. Customized homing \u00b6 [safe_z_home] \u00b6 Safe Z homing. One may use this mechanism to home the Z axis at a specific X, Y coordinate. This is useful if the toolhead, for example has to move to the center of the bed before Z can be homed. [safe_z_home] home_xy_position: # A X, Y coordinate (e.g. 100, 100) where the Z homing should be # performed. This parameter must be provided. #speed: 50.0 # Speed at which the toolhead is moved to the safe Z home # coordinate. The default is 50 mm/s #z_hop: # Distance (in mm) to lift the Z axis prior to homing. This is # applied to any homing command, even if it doesn't home the Z axis. # If the Z axis is already homed and the current Z position is less # than z_hop, then this will lift the head to a height of z_hop. If # the Z axis is not already homed the head is lifted by z_hop. # The default is to not implement Z hop. #z_hop_speed: 15.0 # Speed (in mm/s) at which the Z axis is lifted prior to homing. The # default is 15 mm/s. #move_to_previous: False # When set to True, the X and Y axes are reset to their previous # positions after Z axis homing. The default is False. [homing_override] \u00b6 Homing override. One may use this mechanism to run a series of g-code commands in place of a G28 found in the normal g-code input. This may be useful on printers that require a specific procedure to home the machine. [homing_override] gcode: # A list of G-Code commands to execute in place of G28 commands # found in the normal g-code input. See docs/Command_Templates.md # for G-Code format. If a G28 is contained in this list of commands # then it will invoke the normal homing procedure for the printer. # The commands listed here must home all axes. This parameter must # be provided. #axes: xyz # The axes to override. For example, if this is set to \"z\" then the # override script will only be run when the z axis is homed (eg, via # a \"G28\" or \"G28 Z0\" command). Note, the override script should # still home all axes. The default is \"xyz\" which causes the # override script to be run in place of all G28 commands. #set_position_x: #set_position_y: #set_position_z: # If specified, the printer will assume the axis is at the specified # position prior to running the above g-code commands. Setting this # disables homing checks for that axis. This may be useful if the # head must move prior to invoking the normal G28 mechanism for an # axis. The default is to not force a position for an axis. [endstop_phase] \u00b6 Stepper phase adjusted endstops. To use this feature, define a config section with an \"endstop_phase\" prefix followed by the name of the corresponding stepper config section (for example, \"[endstop_phase stepper_z]\"). This feature can improve the accuracy of endstop switches. Add a bare \"[endstop_phase]\" declaration to enable the ENDSTOP_PHASE_CALIBRATE command. See the endstop phases guide and command reference for additional information. [endstop_phase stepper_z] #endstop_accuracy: # Sets the expected accuracy (in mm) of the endstop. This represents # the maximum error distance the endstop may trigger (eg, if an # endstop may occasionally trigger 100um early or up to 100um late # then set this to 0.200 for 200um). The default is # 4*rotation_distance/full_steps_per_rotation. #trigger_phase: # This specifies the phase of the stepper motor driver to expect # when hitting the endstop. It is composed of two numbers separated # by a forward slash character - the phase and the total number of # phases (eg, \"7/64\"). Only set this value if one is sure the # stepper motor driver is reset every time the mcu is reset. If this # is not set, then the stepper phase will be detected on the first # home and that phase will be used on all subsequent homes. #endstop_align_zero: False # If true then the position_endstop of the axis will effectively be # modified so that the zero position for the axis occurs at a full # step on the stepper motor. (If used on the Z axis and the print # layer height is a multiple of a full step distance then every # layer will occur on a full step.) The default is False. G-Code macros and events \u00b6 [gcode_macro] \u00b6 G-Code macros (one may define any number of sections with a \"gcode_macro\" prefix). See the command template guide for more information. [gcode_macro my_cmd] #gcode: # A list of G-Code commands to execute in place of \"my_cmd\". See # docs/Command_Templates.md for G-Code format. This parameter must # be provided. #variable_: # One may specify any number of options with a \"variable_\" prefix. # The given variable name will be assigned the given value (parsed # as a Python literal) and will be available during macro expansion. # For example, a config with \"variable_fan_speed = 75\" might have # gcode commands containing \"M106 S{ fan_speed * 255 }\". Variables # can be changed at run-time using the SET_GCODE_VARIABLE command # (see docs/Command_Templates.md for details). Variable names may # not use upper case characters. #rename_existing: # This option will cause the macro to override an existing G-Code # command and provide the previous definition of the command via the # name provided here. This can be used to override builtin G-Code # commands. Care should be taken when overriding commands as it can # cause complex and unexpected results. The default is to not # override an existing G-Code command. #description: G-Code macro # This will add a short description used at the HELP command or while # using the auto completion feature. Default \"G-Code macro\" [delayed_gcode] \u00b6 Execute a gcode on a set delay. See the command template guide and command reference for more information. [delayed_gcode my_delayed_gcode] gcode: # A list of G-Code commands to execute when the delay duration has # elapsed. G-Code templates are supported. This parameter must be # provided. #initial_duration: 0.0 # The duration of the initial delay (in seconds). If set to a # non-zero value the delayed_gcode will execute the specified number # of seconds after the printer enters the \"ready\" state. This can be # useful for initialization procedures or a repeating delayed_gcode. # If set to 0 the delayed_gcode will not execute on startup. # Default is 0. [save_variables] \u00b6 Support saving variables to disk so that they are retained across restarts. See command templates and G-Code reference for further information. [save_variables] filename: # Required - provide a filename that would be used to save the # variables to disk e.g. ~/variables.cfg [idle_timeout] \u00b6 Idle timeout. An idle timeout is automatically enabled - add an explicit idle_timeout config section to change the default settings. [idle_timeout] #gcode: # A list of G-Code commands to execute on an idle timeout. See # docs/Command_Templates.md for G-Code format. The default is to run # \"TURN_OFF_HEATERS\" and \"M84\". #timeout: 600 # Idle time (in seconds) to wait before running the above G-Code # commands. The default is 600 seconds. Optional G-Code features \u00b6 [virtual_sdcard] \u00b6 A virtual sdcard may be useful if the host machine is not fast enough to run OctoPrint well. It allows the Klipper host software to directly print gcode files stored in a directory on the host using standard sdcard G-Code commands (eg, M24). [virtual_sdcard] path: # The path of the local directory on the host machine to look for # g-code files. This is a read-only directory (sdcard file writes # are not supported). One may point this to OctoPrint's upload # directory (generally ~/.octoprint/uploads/ ). This parameter must # be provided. #on_error_gcode: # A list of G-Code commands to execute when an error is reported. # See docs/Command_Templates.md for G-Code format. The default is to # run TURN_OFF_HEATERS. [sdcard_loop] \u00b6 Some printers with stage-clearing features, such as a part ejector or a belt printer, can find use in looping sections of the sdcard file. (For example, to print the same part over and over, or repeat the a section of a part for a chain or other repeated pattern). See the command reference for supported commands. See the sample-macros.cfg file for a Marlin compatible M808 G-Code macro. [sdcard_loop] [force_move] \u00b6 Support manually moving stepper motors for diagnostic purposes. Note, using this feature may place the printer in an invalid state - see the command reference for important details. [force_move] #enable_force_move: False # Set to true to enable FORCE_MOVE and SET_KINEMATIC_POSITION # extended G-Code commands. The default is false. [pause_resume] \u00b6 Pause/Resume functionality with support of position capture and restore. See the command reference for more information. [pause_resume] #recover_velocity: 50. # When capture/restore is enabled, the speed at which to return to # the captured position (in mm/s). Default is 50.0 mm/s. [firmware_retraction] \u00b6 Firmware filament retraction. This enables G10 (retract) and G11 (unretract) GCODE commands issued by many slicers. The parameters below provide startup defaults, although the values can be adjusted via the SET_RETRACTION command ), allowing per-filament settings and runtime tuning. [firmware_retraction] #retract_length: 0 # The length of filament (in mm) to retract when G10 is activated, # and to unretract when G11 is activated (but see # unretract_extra_length below). The default is 0 mm. #retract_speed: 20 # The speed of retraction, in mm/s. The default is 20 mm/s. #unretract_extra_length: 0 # The length (in mm) of *additional* filament to add when # unretracting. #unretract_speed: 10 # The speed of unretraction, in mm/s. The default is 10 mm/s. [gcode_arcs] \u00b6 Support for gcode arc (G2/G3) commands. [gcode_arcs] #resolution: 1.0 # An arc will be split into segments. Each segment's length will # equal the resolution in mm set above. Lower values will produce a # finer arc, but also more work for your machine. Arcs smaller than # the configured value will become straight lines. The default is # 1mm. [respond] \u00b6 Enable the \"M118\" and \"RESPOND\" extended commands . [respond] #default_type: echo # Sets the default prefix of the \"M118\" and \"RESPOND\" output to one # of the following: # echo: \"echo: \" (This is the default) # command: \"// \" # error: \"!! \" #default_prefix: echo: # Directly sets the default prefix. If present, this value will # override the \"default_type\". [exclude_object] \u00b6 Enables support to exclude or cancel individual objects during the printing process. See the exclude objects guide and command reference for additional information. See the sample-macros.cfg file for a Marlin/RepRapFirmware compatible M486 G-Code macro. [exclude_object] Resonance compensation \u00b6 [input_shaper] \u00b6 Enables resonance compensation . Also see the command reference . [input_shaper] #shaper_freq_x: 0 # A frequency (in Hz) of the input shaper for X axis. This is # usually a resonance frequency of X axis that the input shaper # should suppress. For more complex shapers, like 2- and 3-hump EI # input shapers, this parameter can be set from different # considerations. The default value is 0, which disables input # shaping for X axis. #shaper_freq_y: 0 # A frequency (in Hz) of the input shaper for Y axis. This is # usually a resonance frequency of Y axis that the input shaper # should suppress. For more complex shapers, like 2- and 3-hump EI # input shapers, this parameter can be set from different # considerations. The default value is 0, which disables input # shaping for Y axis. #shaper_freq_z: 0 # A frequency (in Hz) of the input shaper for Z axis. The default # value is 0, which disables input shaping for Z axis. #shaper_type: mzv # A type of the input shaper to use for all 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: #shaper_type_z: # If shaper_type is not set, these parameters can be used to # configure different input shapers for X, Y, and Z axes. The same # values are supported as for shaper_type parameter. #damping_ratio_x: 0.1 #damping_ratio_y: 0.1 #damping_ratio_z: 0.1 # Damping ratios of vibrations of X and Y axes used by input shapers # to improve vibration suppression. Default value is 0.1 which is a # good all-round value for most printers. In most circumstances this # parameter requires no tuning and should not be changed. [adxl345] \u00b6 Support for ADXL345 accelerometers. This support allows one to query accelerometer measurements from the sensor. This enables an ACCELEROMETER_MEASURE command (see G-Codes for more information). The default chip name is \"default\", but one may specify an explicit name (eg, [adxl345 my_chip_name]). [adxl345] cs_pin: # The SPI enable pin for the sensor. This parameter must be provided. #spi_speed: 5000000 # The SPI speed (in hz) to use when communicating with the chip. # The default is 5000000. #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #axes_map: x, y, z # The accelerometer axis for each of the printer's X, Y, and Z axes. # This may be useful if the accelerometer is mounted in an # orientation that does not match the printer orientation. For # example, one could set this to \"y, x, z\" to swap the X and Y axes. # It is also possible to negate an axis if the accelerometer # direction is reversed (eg, \"x, z, -y\"). The default is \"x, y, z\". #rate: 3200 # Output data rate for ADXL345. ADXL345 supports the following data # rates: 3200, 1600, 800, 400, 200, 100, 50, and 25. Note that it is # not recommended to change this rate from the default 3200, and # rates below 800 will considerably affect the quality of resonance # measurements. [icm20948] \u00b6 Support for icm20948 accelerometers. [icm20948] #i2c_address: # Default is 104 (0x68). If AD0 is high, it would be 0x69 instead. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: 400000 # See the \"common I2C settings\" section for a description of the # above parameters. The default \"i2c_speed\" is 400000. #axes_map: x, y, z # See the \"adxl345\" section for information on this parameter. [lis2dw] \u00b6 Support for LIS2DW accelerometers. [lis2dw] #cs_pin: # The SPI enable pin for the sensor. This parameter must be provided # if using SPI. #spi_speed: 5000000 # The SPI speed (in hz) to use when communicating with the chip. # The default is 5000000. #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #i2c_address: # Default is 25 (0x19). If SA0 is high, it would be 24 (0x18) instead. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: 400000 # See the \"common I2C settings\" section for a description of the # above parameters. The default \"i2c_speed\" is 400000. #axes_map: x, y, z # See the \"adxl345\" section for information on this parameter. [lis3dh] \u00b6 Support for LIS3DH accelerometers. [lis3dh] #cs_pin: # The SPI enable pin for the sensor. This parameter must be provided # if using SPI. #spi_speed: 5000000 # The SPI speed (in hz) to use when communicating with the chip. # The default is 5000000. #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #i2c_address: # Default is 25 (0x19). If SA0 is high, it would be 24 (0x18) instead. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: 400000 # See the \"common I2C settings\" section for a description of the # above parameters. The default \"i2c_speed\" is 400000. #axes_map: x, y, z # See the \"adxl345\" section for information on this parameter. [mpu9250] \u00b6 Support for MPU-9250, MPU-9255, MPU-6515, MPU-6050, and MPU-6500 accelerometers (one may define any number of sections with an \"mpu9250\" prefix). [mpu9250 my_accelerometer] #i2c_address: # Default is 104 (0x68). If AD0 is high, it would be 0x69 instead. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: 400000 # See the \"common I2C settings\" section for a description of the # above parameters. The default \"i2c_speed\" is 400000. #axes_map: x, y, z # See the \"adxl345\" section for information on this parameter. [resonance_tester] \u00b6 Support for resonance testing and automatic input shaper calibration. In order to use most of the functionality of this module, additional software dependencies must be installed; refer to Measuring Resonances and the command reference for more information. See the Max smoothing section of the measuring resonances guide for more information on max_smoothing parameter and its use. [resonance_tester] #probe_points: # A list of X, Y, Z coordinates of points (one point per line) to test # resonances at. At least one point is required. Make sure that all # points with some safety margin in XY plane (~a few centimeters) # are reachable by the toolhead. #accel_chip: # A name of the accelerometer chip to use for measurements. If # an accelerometer was defined without an explicit name, this parameter # can simply reference it by type, e.g. \"accel_chip: adxl345\", otherwise # a full name must be supplied, 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. #accel_chip_z: # A name of the accelerometer chip to use for measurements of Z axis. # This parameter has the same format as 'accel_chip'. The default is # not to configure an accelerometer for Z axis. #max_smoothing: # Maximum input shaper smoothing to allow for each axis during shaper # auto-calibration (with 'SHAPER_CALIBRATE' command). By default no # maximum smoothing is specified. Refer to Measuring_Resonances guide # for more details on using this feature. #move_speed: 50 # The speed (in mm/s) to move the toolhead to and between test points # during the calibration. The default is 50. #min_freq: 5 # Minimum frequency to test for resonances. The default is 5 Hz. #max_freq: 135 # Maximum frequency to test for resonances. The default is 135 Hz. #max_freq_z: 100 # Maximum frequency to test Z axis for resonances. The default is 100 Hz. #accel_per_hz: 60 # This parameter is used to determine which acceleration to use to # test a specific frequency: accel = accel_per_hz * freq. Higher the # value, the higher is the energy of the oscillations. Can be set to # a lower than the default value if the resonances get too strong on # the printer. However, lower values make measurements of high-frequency # resonances less precise. The default value is 60 (mm/sec). #accel_per_hz_z: 15 # This parameter has the same meaning as accel_per_hz, but applies to # Z axis specifically. The default is 15 (mm/sec). #hz_per_sec: 1 # Determines the speed of the test. When testing all frequencies in # range [min_freq, max_freq], each second the frequency increases by # hz_per_sec. Small values make the test slow, and the large values # will decrease the precision of the test. The default value is 1.0 # (Hz/sec == sec^-2). #sweeping_accel: 400 # An acceleration of slow sweeping moves. The default is 400 mm/sec^2. #sweeping_accel_z: 50 # Same as sweeping_accel above, but for Z axis. The default is 50 mm/sec^2. #sweeping_period: 1.2 # A period of slow sweeping moves. Setting this parameter to 0 # disables slow sweeping moves. Avoid setting it to a too small # non-zero value in order to not poison the measurements. # The default is 1.2 sec which is a good all-round choice. Config file helpers \u00b6 [board_pins] \u00b6 Board pin aliases (one may define any number of sections with a \"board_pins\" prefix). Use this to define aliases for the pins on a micro-controller. [board_pins my_aliases] mcu: mcu # A comma separated list of micro-controllers that may use the # aliases. The default is to apply the aliases to the main \"mcu\". aliases: aliases_: # 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=\" would reserve \"EXP1_9\"). Any number of options # starting with \"aliases_\" may be specified. [include] \u00b6 Include file support. One may include additional config file from the main printer config file. Wildcards may also be used (eg, \"configs/*.cfg\"). [include my_other_config.cfg] [duplicate_pin_override] \u00b6 This tool allows a single micro-controller pin to be defined multiple times in a config file without normal error checking. This is intended for diagnostic and debugging purposes. This section is not needed where Klipper supports using the same pin multiple times, and using this override may cause confusing and unexpected results. [duplicate_pin_override] pins: # A comma separated list of pins that may be used multiple times in # a config file without normal error checks. This parameter must be # provided. Bed probing hardware \u00b6 [probe] \u00b6 Z height probe. One may define this section to enable Z height probing hardware. When this section is enabled, PROBE and QUERY_PROBE extended g-code commands become available. Also, see the probe calibrate guide . The probe section also creates a virtual \"probe:z_virtual_endstop\" pin. One may set the stepper_z endstop_pin to this virtual pin on cartesian style printers that use the probe in place of a z endstop. If using \"probe:z_virtual_endstop\" then do not define a position_endstop in the stepper_z config section. [probe] pin: # Probe detection pin. If the pin is on a different microcontroller # than the Z steppers then it enables \"multi-mcu homing\". This # parameter must be provided. #deactivate_on_each_sample: True # This determines if Klipper should execute deactivation gcode # between each probe attempt when performing a multiple probe # sequence. The default is True. #x_offset: 0.0 # The distance (in mm) between the probe and the nozzle along the # x-axis. The default is 0. #y_offset: 0.0 # The distance (in mm) between the probe and the nozzle along the # y-axis. The default is 0. z_offset: # The distance (in mm) between the bed and the nozzle when the probe # triggers. This parameter must be provided. #speed: 5.0 # Speed (in mm/s) of the Z axis when probing. The default is 5mm/s. #samples: 1 # The number of times to probe each point. The probed z-values will # be averaged. The default is to probe 1 time. #sample_retract_dist: 2.0 # The distance (in mm) to lift the toolhead between each sample (if # sampling more than once). The default is 2mm. #lift_speed: # Speed (in mm/s) of the Z axis when lifting the probe between # samples. The default is to use the same value as the 'speed' # parameter. #samples_result: average # The calculation method when sampling more than once - either # \"median\" or \"average\". The default is average. #samples_tolerance: 0.100 # The maximum Z distance (in mm) that a sample may differ from other # samples. If this tolerance is exceeded then either an error is # reported or the attempt is restarted (see # samples_tolerance_retries). The default is 0.100mm. #samples_tolerance_retries: 0 # The number of times to retry if a sample is found that exceeds # samples_tolerance. On a retry, all current samples are discarded # and the probe attempt is restarted. If a valid set of samples are # not obtained in the given number of retries then an error is # reported. The default is zero which causes an error to be reported # on the first sample that exceeds samples_tolerance. #activate_gcode: # A list of G-Code commands to execute prior to each probe attempt. # See docs/Command_Templates.md for G-Code format. This may be # useful if the probe needs to be activated in some way. Do not # issue any commands here that move the toolhead (eg, G1). The # default is to not run any special G-Code commands on activation. #deactivate_gcode: # A list of G-Code commands to execute after each probe attempt # completes. See docs/Command_Templates.md for G-Code format. Do not # issue any commands here that move the toolhead. The default is to # not run any special G-Code commands on deactivation. [bltouch] \u00b6 BLTouch probe. One may define this section (instead of a probe section) to enable a BLTouch probe. See BL-Touch guide and command reference for further information. A virtual \"probe:z_virtual_endstop\" pin is also created (see the \"probe\" section for the details). [bltouch] sensor_pin: # Pin connected to the BLTouch sensor pin. Most BLTouch devices # require a pullup on the sensor pin (prefix the pin name with \"^\"). # This parameter must be provided. control_pin: # Pin connected to the BLTouch control pin. This parameter must be # provided. #pin_move_time: 0.680 # The amount of time (in seconds) to wait for the BLTouch pin to # move up or down. The default is 0.680 seconds. #stow_on_each_sample: True # This determines if Klipper should command the pin to move up # between each probe attempt when performing a multiple probe # sequence. Read the directions in docs/BLTouch.md before setting # this to False. The default is True. #probe_with_touch_mode: False # If this is set to True then Klipper will probe with the device in # \"touch_mode\". The default is False (probing in \"pin_down\" mode). #pin_up_reports_not_triggered: True # Set if the BLTouch consistently reports the probe in a \"not # triggered\" state after a successful \"pin_up\" command. This should # be True for all genuine BLTouch devices. Read the directions in # docs/BLTouch.md before setting this to False. The default is True. #pin_up_touch_mode_reports_triggered: True # Set if the BLTouch consistently reports a \"triggered\" state after # the commands \"pin_up\" followed by \"touch_mode\". This should be # True for all genuine BLTouch devices. Read the directions in # docs/BLTouch.md before setting this to False. The default is True. #set_output_mode: # Request a specific sensor pin output mode on the BLTouch V3.0 (and # later). This setting should not be used on other types of probes. # Set to \"5V\" to request a sensor pin output of 5 Volts (only use if # the controller board needs 5V mode and is 5V tolerant on its input # signal line). Set to \"OD\" to request the sensor pin output use # open drain mode. The default is to not request an output mode. #x_offset: #y_offset: #z_offset: #speed: #lift_speed: #samples: #sample_retract_dist: #samples_result: #samples_tolerance: #samples_tolerance_retries: # See the \"probe\" section for information on these parameters. [smart_effector] \u00b6 The \"Smart Effector\" from Duet3d implements a Z probe using a force sensor. One may define this section instead of [probe] to enable the Smart Effector specific features. This also enables runtime commands to adjust the parameters of the Smart Effector at run time. [smart_effector] pin: # Pin connected to the Smart Effector Z Probe output pin (pin 5). Note that # pullup resistor on the board is generally not required. However, if the # output pin is connected to the board pin with a pullup resistor, that # resistor must be high value (e.g. 10K Ohm or more). Some boards have a low # value pullup resistor on the Z probe input, which will likely result in an # always-triggered probe state. In this case, connect the Smart Effector to # a different pin on the board. This parameter is required. #control_pin: # Pin connected to the Smart Effector control input pin (pin 7). If provided, # Smart Effector sensitivity programming commands become available. #probe_accel: # If set, limits the acceleration of the probing moves (in mm/sec^2). # A sudden large acceleration at the beginning of the probing move may # cause spurious probe triggering, especially if the hotend is heavy. # To prevent that, it may be necessary to reduce the acceleration of # the probing moves via this parameter. #recovery_time: 0.4 # A delay between the travel moves and the probing moves in seconds. A fast # travel move prior to probing may result in a spurious probe triggering. # This may cause 'Probe triggered prior to movement' errors if no delay # is set. Value 0 disables the recovery delay. # Default value is 0.4. #x_offset: #y_offset: # Should be left unset (or set to 0). z_offset: # Trigger height of the probe. Start with -0.1 (mm), and adjust later using # `PROBE_CALIBRATE` command. This parameter must be provided. #speed: # Speed (in mm/s) of the Z axis when probing. It is recommended to start # with the probing speed of 20 mm/s and adjust it as necessary to improve # the accuracy and repeatability of the probe triggering. #samples: #sample_retract_dist: #samples_result: #samples_tolerance: #samples_tolerance_retries: #activate_gcode: #deactivate_gcode: #deactivate_on_each_sample: # See the \"probe\" section for more information on the parameters above. [probe_eddy_current] \u00b6 Support for eddy current inductive probes. One may define this section (instead of a probe section) to enable this probe. See the command reference for further information. [probe_eddy_current my_eddy_probe] sensor_type: ldc1612 # The sensor chip used to perform eddy current measurements. This # parameter must be provided and must be set to ldc1612. #frequency: # The external crystal frequency (in Hz) of the LDC1612 chip. # The default is 12000000. #intb_pin: # MCU gpio pin connected to the ldc1612 sensor's INTB pin (if # available). The default is to not use the INTB pin. #z_offset: # The nominal distance (in mm) between the nozzle and bed that a # probing attempt should stop at. This parameter must be provided. #i2c_address: #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # The i2c settings for the sensor chip. See the \"common I2C # settings\" section for a description of the above parameters. #x_offset: #y_offset: #speed: #lift_speed: #samples: #sample_retract_dist: #samples_result: #samples_tolerance: #samples_tolerance_retries: # See the \"probe\" section for information on these parameters. [axis_twist_compensation] \u00b6 A tool to compensate for inaccurate probe readings due to twist in X or Y gantry. See the Axis Twist Compensation Guide for more detailed information regarding symptoms, configuration and setup. [axis_twist_compensation] #speed: 50 # The speed (in mm/s) of non-probing moves during the calibration. # The default is 50. #horizontal_move_z: 5 # The height (in mm) that the head should be commanded to move to # just prior to starting a probe operation. The default is 5. calibrate_start_x: 20 # Defines the minimum X coordinate of the calibration # This should be the X coordinate that positions the nozzle at the starting # calibration position. calibrate_end_x: 200 # Defines the maximum X coordinate of the calibration # This should be the X coordinate that positions the nozzle at the ending # calibration position. calibrate_y: 112.5 # Defines the Y coordinate of the calibration # This should be the Y coordinate that positions the nozzle during the # calibration process. This parameter is recommended to # be near the center of the bed # For Y-axis twist compensation, specify the following parameters: calibrate_start_y: ... # Defines the minimum Y coordinate of the calibration # This should be the Y coordinate that positions the nozzle at the starting # calibration position for the Y axis. This parameter must be provided if # compensating for Y axis twist. calibrate_end_y: ... # Defines the maximum Y coordinate of the calibration # This should be the Y coordinate that positions the nozzle at the ending # calibration position for the Y axis. This parameter must be provided if # compensating for Y axis twist. calibrate_x: ... # Defines the X coordinate of the calibration for Y axis twist compensation # This should be the X coordinate that positions the nozzle during the # calibration process for Y axis twist compensation. This parameter must be # provided and is recommended to be near the center of the bed. Additional stepper motors and extruders \u00b6 [stepper_z1] \u00b6 Multi-stepper axes. On a cartesian style printer, the stepper controlling a given axis may have additional config blocks defining steppers that should be stepped in concert with the primary stepper. One may define any number of sections with a numeric suffix starting at 1 (for example, \"stepper_z1\", \"stepper_z2\", etc.). [stepper_z1] #step_pin: #dir_pin: #enable_pin: #microsteps: #rotation_distance: # See the \"stepper\" section for the definition of the above parameters. #endstop_pin: # If an endstop_pin is defined for the additional stepper then the # stepper will home until the endstop is triggered. Otherwise, the # stepper will home until the endstop on the primary stepper for the # axis is triggered. [extruder1] \u00b6 In a multi-extruder printer add an additional extruder section for each additional extruder. The additional extruder sections should be named \"extruder1\", \"extruder2\", \"extruder3\", and so on. See the \"extruder\" section for a description of available parameters. See sample-multi-extruder.cfg for an example configuration. [extruder1] #step_pin: #dir_pin: #... # See the \"extruder\" section for available stepper and heater # parameters. #shared_heater: # This option is deprecated and should no longer be specified. [dual_carriage] \u00b6 Support for cartesian, generic_cartesian and hybrid_corexy/z printers with dual carriages on a single axis. The carriage mode can be set via the SET_DUAL_CARRIAGE extended g-code command. For example, \"SET_DUAL_CARRIAGE CARRIAGE=1\" command will activate the carriage defined in this section (CARRIAGE=0 will return activation to the primary carriage). Dual carriage support is typically combined with extra extruders - the SET_DUAL_CARRIAGE command is often called at the same time as the ACTIVATE_EXTRUDER command. Be sure to park the carriages during deactivation. Note that during G28 homing, typically the primary carriage is homed first followed by the carriage defined in the [dual_carriage] config section. However, the [dual_carriage] carriage will be homed first if both carriages home in a positive direction and the [dual_carriage] carriage has a position_endstop greater than the primary carriage, or if both carriages home in a negative direction and the [dual_carriage] carriage has a position_endstop less than the primary carriage. Additionally, one could use \"SET_DUAL_CARRIAGE CARRIAGE=1 MODE=COPY\" or \"SET_DUAL_CARRIAGE CARRIAGE=1 MODE=MIRROR\" commands to activate either copying or mirroring mode of the dual carriage, in which case it will follow the motion of the carriage 0 accordingly. These commands can be used to print two parts simultaneously - either two identical parts (in COPY mode) or mirrored parts (in MIRROR mode). Note that COPY and MIRROR modes also require appropriate configuration of the extruder on the dual carriage, which can typically be achieved with \"SYNC_EXTRUDER_MOTION MOTION_QUEUE=extruder EXTRUDER= \" or a similar command. See sample-idex.cfg for an example configuration with a regular Cartesian kinematic. [dual_carriage] axis: # The axis this extra carriage is on (either x or y). This parameter # must be provided. #safe_distance: # The minimum distance (in mm) to enforce between the dual and the primary # carriages. If a G-Code command is executed that will bring the carriages # closer than the specified limit, such a command will be rejected with an # error. If safe_distance is not provided, it will be inferred from # position_min and position_max for the dual and primary carriages. If set # to 0 (or safe_distance is unset and position_min and position_max are # identical for the primary and dual carriages), the carriages proximity # checks will be disabled. #step_pin: #dir_pin: #enable_pin: #microsteps: #rotation_distance: #endstop_pin: #position_endstop: #position_min: #position_max: # See the \"stepper\" section for the definition of the above parameters. For an example of dual carriage configuration with generic_cartesian kinematic, see the following configuration sample . Please note that in this case the [dual_carriage] configuration deviates from the configuration described above: [dual_carriage my_dc_carriage] primary_carriage: # Defines the matching primary carriage of this dual carriage and # the corresponding IDEX axis. Must match a name of a defined `[carriage]`. # This parameter must be provided. #safe_distance: # The minimum distance (in mm) to enforce between the dual and the primary # carriages. If a G-Code command is executed that will bring the carriages # closer than the specified limit, such a command will be rejected with an # error. If safe_distance is not provided, it will be inferred from # position_min and position_max for the dual and primary carriages. If set # to 0 (or safe_distance is unset and position_min and position_max are # identical for the primary and dual carriages), the carriages proximity # checks will be disabled. endstop_pin: #position_min: position_endstop: position_max: #homing_speed: #homing_retract_dist: #homing_retract_speed: #second_homing_speed: #homing_positive_dir: ... Refer to generic cartesian section for more information on the regular carriage parameters. Then a user must define one or more stepper motors moving the dual carriage (and other carriages as appropriate), for instance [carriage carriage_x] ... [carriage carriage_y] ... [dual_carriage carriage_u] primary_carriage: carriage_x ... [stepper dc_stepper] carriages: carriage_u-carriage_y ... [dual_carriage] requires special configuration for the input shaper. In general, it is necessary to run input shaper calibration twice - for the dual_carriage and its primary_carriage for the axis they share. Then the input shaper can be configured as follows, assuming the example above: [input_shaper] # Intentionally empty [delayed_gcode init_shaper] initial_duration: 0.1 gcode: SET_DUAL_CARRIAGE CARRIAGE=carriage_u SET_INPUT_SHAPER SHAPER_TYPE_X= SHAPER_FREQ_X= SHAPER_TYPE_Y= SHAPER_FREQ_Y= SET_DUAL_CARRIAGE CARRIAGE=carriage_x SET_INPUT_SHAPER SHAPER_TYPE_X= SHAPER_FREQ_X= SHAPER_TYPE_Y= SHAPER_FREQ_Y= Note that SHAPER_TYPE_Y and SHAPER_FREQ_Y must be the same in both commands in this case, since the same motors drive Y axis when either of the carriage_x and carriage_u carriages are active. It is worth noting that generic_cartesian kinematic can support two dual carriages for X and Y axes. For reference, see for instance a sample of CoreXYUV configuration. [extruder_stepper] \u00b6 Support for additional steppers synchronized to the movement of an extruder (one may define any number of sections with an \"extruder_stepper\" prefix). See the command reference for more information. [extruder_stepper my_extra_stepper] extruder: # The extruder this stepper is synchronized to. If this is set to an # empty string then the stepper will not be synchronized to an # extruder. This parameter must be provided. #step_pin: #dir_pin: #enable_pin: #microsteps: #rotation_distance: # See the \"stepper\" section for the definition of the above # parameters. [manual_stepper] \u00b6 Manual steppers (one may define any number of sections with a \"manual_stepper\" prefix). These are steppers that are controlled by the MANUAL_STEPPER g-code command. For example: \"MANUAL_STEPPER STEPPER=my_stepper MOVE=10 SPEED=5\". See G-Codes file for a description of the MANUAL_STEPPER command. The steppers are not connected to the normal printer kinematics. [manual_stepper my_stepper] #step_pin: #dir_pin: #enable_pin: #microsteps: #rotation_distance: # See the \"stepper\" section for a description of these parameters. #velocity: # Set the default velocity (in mm/s) for the stepper. This value # will be used if a MANUAL_STEPPER command does not specify a SPEED # parameter. The default is 5mm/s. #accel: # Set the default acceleration (in mm/s^2) for the stepper. An # acceleration of zero will result in no acceleration. This value # will be used if a MANUAL_STEPPER command does not specify an ACCEL # parameter. The default is zero. #endstop_pin: # Endstop switch detection pin. If specified, then one may perform # \"homing moves\" by adding a STOP_ON_ENDSTOP parameter to # MANUAL_STEPPER movement commands. #position_min: #position_max: # The minimum and maximum position the stepper can be commanded to # move to. If specified then one may not command the stepper to move # past the given position. Note that these limits do not prevent # setting an arbitrary position with the `MANUAL_STEPPER # SET_POSITION=x` command. The default is to not enforce a limit. Custom heaters and sensors \u00b6 [verify_heater] \u00b6 Heater and temperature sensor verification. Heater verification is automatically enabled for each heater that is configured on the printer. Use verify_heater sections to change the default settings. [verify_heater heater_config_name] #max_error: 120 # The maximum \"cumulative temperature error\" before raising an # error. Smaller values result in stricter checking and larger # values allow for more time before an error is reported. # Specifically, the temperature is inspected once a second and if it # is close to the target temperature then an internal \"error # counter\" is reset; otherwise, if the temperature is below the # target range then the counter is increased by the amount the # reported temperature differs from that range. Should the counter # exceed this \"max_error\" then an error is raised. The default is # 120. #check_gain_time: # This controls heater verification during initial heating. Smaller # values result in stricter checking and larger values allow for # more time before an error is reported. Specifically, during # initial heating, as long as the heater increases in temperature # within this time frame (specified in seconds) then the internal # \"error counter\" is reset. The default is 20 seconds for extruders # and 60 seconds for heater_bed. #hysteresis: 5 # The maximum temperature difference (in Celsius) to a target # temperature that is considered in range of the target. This # controls the max_error range check. It is rare to customize this # value. The default is 5. #heating_gain: 2 # The minimum temperature (in Celsius) that the heater must increase # by during the check_gain_time check. It is rare to customize this # value. The default is 2. [homing_heaters] \u00b6 Tool to disable heaters when homing or probing an axis. [homing_heaters] #steppers: # A comma separated list of steppers that should cause heaters to be # disabled. The default is to disable heaters for any homing/probing # move. # Typical example: stepper_z #heaters: # A comma separated list of heaters to disable during homing/probing # moves. The default is to disable all heaters. # Typical example: extruder, heater_bed [thermistor] \u00b6 Custom thermistors (one may define any number of sections with a \"thermistor\" prefix). A custom thermistor may be used in the sensor_type field of a heater config section. (For example, if one defines a \"[thermistor my_thermistor]\" section then one may use a \"sensor_type: my_thermistor\" when defining a heater.) Be sure to place the thermistor section in the config file above its first use in a heater section. [thermistor my_thermistor] #temperature1: #resistance1: #temperature2: #resistance2: #temperature3: #resistance3: # Three resistance measurements (in Ohms) at the given temperatures # (in Celsius). The three measurements will be used to calculate the # Steinhart-Hart coefficients for the thermistor. These parameters # must be provided when using Steinhart-Hart to define the # thermistor. #beta: # Alternatively, one may define temperature1, resistance1, and beta # to define the thermistor parameters. This parameter must be # provided when using \"beta\" to define the thermistor. [adc_temperature] \u00b6 Custom ADC temperature sensors (one may define any number of sections with an \"adc_temperature\" prefix). This allows one to define a custom temperature sensor that measures a voltage on an Analog to Digital Converter (ADC) pin and uses linear interpolation between a set of configured temperature/voltage (or temperature/resistance) measurements to determine the temperature. The resulting sensor can be used as a sensor_type in a heater section. (For example, if one defines a \"[adc_temperature my_sensor]\" section then one may use a \"sensor_type: my_sensor\" when defining a heater.) Be sure to place the sensor section in the config file above its first use in a heater section. [adc_temperature my_sensor] #temperature1: #voltage1: #temperature2: #voltage2: #... # A set of temperatures (in Celsius) and voltages (in Volts) to use # as reference when converting a temperature. A heater section using # this sensor may also specify adc_voltage and voltage_offset # parameters to define the ADC voltage (see \"Common temperature # amplifiers\" section for details). At least two measurements must # be provided. #temperature1: #resistance1: #temperature2: #resistance2: #... # Alternatively one may specify a set of temperatures (in Celsius) # and resistance (in Ohms) to use as reference when converting a # temperature. A heater section using this sensor may also specify a # pullup_resistor parameter (see \"extruder\" section for details). At # least two measurements must be provided. [heater_generic] \u00b6 Generic heaters (one may define any number of sections with a \"heater_generic\" prefix). These heaters behave similarly to standard heaters (extruders, heated beds). Use the SET_HEATER_TEMPERATURE command (see G-Codes for details) to set the target temperature. [heater_generic my_generic_heater] #gcode_id: # The id to use when reporting the temperature in the M105 command. # This parameter must be provided. #heater_pin: #max_power: #sensor_type: #sensor_pin: #smooth_time: #control: #pid_Kp: #pid_Ki: #pid_Kd: #pwm_cycle_time: #min_temp: #max_temp: # See the \"extruder\" section for the definition of the above # parameters. [temperature_sensor] \u00b6 Generic temperature sensors. One can define any number of additional temperature sensors that are reported via the M105 command. [temperature_sensor my_sensor] #sensor_type: #sensor_pin: #min_temp: #max_temp: # See the \"extruder\" section for the definition of the above # parameters. #gcode_id: # See the \"heater_generic\" section for the definition of this # parameter. [temperature_probe] \u00b6 Reports probe coil temperature. Includes optional thermal drift calibration for eddy current based probes. A [temperature_probe] section may be linked to a [probe_eddy_current] by using the same postfix for both sections. [temperature_probe my_probe] #sensor_type: #sensor_pin: #min_temp: #max_temp: # Temperature sensor configuration. # See the \"extruder\" section for the definition of the above # parameters. #smooth_time: # A time value (in seconds) over which temperature measurements will # be smoothed to reduce the impact of measurement noise. The default # is 2.0 seconds. #gcode_id: # See the \"heater_generic\" section for the definition of this # parameter. #speed: # The travel speed [mm/s] for xy moves during calibration. Default # is the speed defined by the probe. #horizontal_move_z: # The z distance [mm] from the bed at which xy moves will occur # during calibration. Default is 2mm. #resting_z: # The z distance [mm] from the bed at which the tool will rest # to heat the probe coil during calibration. Default is .4mm #calibration_position: # The X, Y, Z position where the tool should be moved when # probe drift calibration initializes. This is the location # where the first manual probe will occur. If omitted, the # default behavior is not to move the tool prior to the first # manual probe. #calibration_bed_temp: # The maximum safe bed temperature (in C) used to heat the probe # during probe drift calibration. When set, the calibration # procedure will turn on the bed after the first sample is # taken. When the calibration procedure is complete the bed # temperature will be set to zero. When omitted the default # behavior is not to set the bed temperature. #calibration_extruder_temp: # The extruder temperature (in C) set probe during drift calibration. # When this option is supplied the procedure will wait for until the # specified temperature is reached before requesting the first manual # probe. When the calibration procedure is complete the extruder # temperature will be set to 0. When omitted the default behavior is # not to set the extruder temperature. #extruder_heating_z: 50. # The Z location where extruder heating will occur if the # \"calibration_extruder_temp\" option is set. Its recommended to heat # the extruder some distance from the bed to minimize its impact on # the probe coil temperature. The default is 50. #max_validation_temp: 60. # The maximum temperature used to validate the calibration. It is # recommended to set this to a value between 100 and 120 for enclosed # printers. The default is 60. Temperature sensors \u00b6 Klipper includes definitions for many types of temperature sensors. These sensors may be used in any config section that requires a temperature sensor (such as an [extruder] or [heater_bed] section). Common thermistors \u00b6 Common thermistors. The following parameters are available in heater sections that use one of these sensors. sensor_type: # One of \"EPCOS 100K B57560G104F\", \"ATC Semitec 104GT-2\", # \"ATC Semitec 104NT-4-R025H42G\", \"Generic 3950\", # \"Honeywell 100K 135-104LAG-J01\", \"NTC 100K MGB18-104F39050L32\", # \"SliceEngineering 450\", or \"TDK NTCG104LH104JT1\" sensor_pin: # Analog input pin connected to the thermistor. This parameter must # be provided. #pullup_resistor: 4700 # The resistance (in ohms) of the pullup attached to the thermistor. # The default is 4700 ohms. #inline_resistor: 0 # The resistance (in ohms) of an extra (not heat varying) resistor # that is placed inline with the thermistor. It is rare to set this. # The default is 0 ohms. Common temperature amplifiers \u00b6 Common temperature amplifiers. The following parameters are available in heater sections that use one of these sensors. sensor_type: # One of \"PT100 INA826\", \"AD595\", \"AD597\", \"AD8494\", \"AD8495\", # \"AD8496\", or \"AD8497\". sensor_pin: # Analog input pin connected to the sensor. This parameter must be # provided. #adc_voltage: 5.0 # The ADC comparison voltage (in Volts). The default is 5 volts. #voltage_offset: 0 # The ADC voltage offset (in Volts). The default is 0. Directly connected PT1000 sensor \u00b6 Directly connected PT1000 sensor. The following parameters are available in heater sections that use one of these sensors. sensor_type: PT1000 sensor_pin: # Analog input pin connected to the sensor. This parameter must be # provided. #pullup_resistor: 4700 # The resistance (in ohms) of the pullup attached to the sensor. The # default is 4700 ohms. MAXxxxxx temperature sensors \u00b6 MAXxxxxx serial peripheral interface (SPI) temperature based sensors. The following parameters are available in heater sections that use one of these sensor types. sensor_type: # One of \"MAX6675\", \"MAX31855\", \"MAX31856\", or \"MAX31865\". sensor_pin: # The chip select line for the sensor chip. This parameter must be # provided. #spi_speed: 4000000 # The SPI speed (in hz) to use when communicating with the chip. # The default is 4000000. #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #tc_type: K #tc_use_50Hz_filter: False #tc_averaging_count: 1 # The above parameters control the sensor parameters of MAX31856 # chips. The defaults for each parameter are next to the parameter # name in the above list. #rtd_nominal_r: 100 #rtd_reference_r: 430 #rtd_num_of_wires: 2 #rtd_use_50Hz_filter: False # The above parameters control the sensor parameters of MAX31865 # chips. The defaults for each parameter are next to the parameter # name in the above list. BMP180/BMP280/BME280/BMP388/BME680 temperature sensor \u00b6 BMP180/BMP280/BME280/BMP388/BME680 two wire interface (I2C) environmental sensors. Note that these sensors are not intended for use with extruders and heater beds, but rather for monitoring ambient temperature (C), pressure (hPa), relative humidity and in case of the BME680 gas level. See sample-macros.cfg for a gcode_macro that may be used to report pressure and humidity in addition to temperature. sensor_type: BME280 #i2c_address: # Default is 118 (0x76). The BMP180, BMP388 and some BME280 sensors # have an address of 119 (0x77). #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. AHT10/AHT20/AHT21 temperature sensor \u00b6 AHT10/AHT20/AHT21 two wire interface (I2C) environmental sensors. Note that these sensors are not intended for use with extruders and heater beds, but rather for monitoring ambient temperature (C) and relative humidity. See sample-macros.cfg for a gcode_macro that may be used to report humidity in addition to temperature. sensor_type: AHT10 # Also use AHT10 for AHT20 and AHT21 sensors. #i2c_address: # Default is 56 (0x38). Some AHT10 sensors give the option to use # 57 (0x39) by moving a resistor. #i2c_mcu: #i2c_bus: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #aht10_report_time: # Interval in seconds between readings. Default is 30, minimum is 5 HTU21D sensor \u00b6 HTU21D family two wire interface (I2C) environmental sensor. Note that this sensor is not intended for use with extruders and heater beds, but rather for monitoring ambient temperature (C) and relative humidity. See sample-macros.cfg for a gcode_macro that may be used to report humidity in addition to temperature. sensor_type: # Must be \"HTU21D\" , \"SI7013\", \"SI7020\", \"SI7021\" or \"SHT21\" #i2c_address: # Default is 64 (0x40). #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #htu21d_hold_master: # If the sensor can hold the I2C buf while reading. If True no other # bus communication can be performed while reading is in progress. # Default is False. #htu21d_resolution: # The resolution of temperature and humidity reading. # Valid values are: # 'TEMP14_HUM12' -> 14bit for Temp and 12bit for humidity # 'TEMP13_HUM10' -> 13bit for Temp and 10bit for humidity # 'TEMP12_HUM08' -> 12bit for Temp and 08bit for humidity # 'TEMP11_HUM11' -> 11bit for Temp and 11bit for humidity # Default is: \"TEMP11_HUM11\" #htu21d_report_time: # Interval in seconds between readings. Default is 30 SHT3X sensor \u00b6 SHT3X family two wire interface (I2C) environmental sensor. These sensors have a range of -55~125 C, so are usable for e.g. chamber temperature monitoring. They can also function as simple fan/heater controllers. sensor_type: SHT3X #i2c_address: # Default is 68 (0x44). #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. LM75 temperature sensor \u00b6 LM75/LM75A two wire (I2C) connected temperature sensors. These sensors have a range of -55~125 C, so are usable for e.g. chamber temperature monitoring. They can also function as simple fan/heater controllers. sensor_type: LM75 #i2c_address: # Default is 72 (0x48). Normal range is 72-79 (0x48-0x4F) and the 3 # low bits of the address are configured via pins on the chip # (usually with jumpers or hard wired). #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #lm75_report_time: # Interval in seconds between readings. Default is 0.8, with minimum # 0.5. Builtin micro-controller temperature sensor \u00b6 The atsam, atsamd, stm32 and rp2040 micro-controllers contain an internal temperature sensor. One can use the \"temperature_mcu\" sensor to monitor these temperatures. sensor_type: temperature_mcu #sensor_mcu: mcu # The micro-controller to read from. The default is \"mcu\". #sensor_temperature1: #sensor_adc1: # Specify the above two parameters (a temperature in Celsius and an # ADC value as a float between 0.0 and 1.0) to calibrate the # micro-controller temperature. This may improve the reported # temperature accuracy on some chips. A typical way to obtain this # calibration information is to completely remove power from the # printer for a few hours (to ensure it is at the ambient # temperature), then power it up and use the QUERY_ADC command to # obtain an ADC measurement. Use some other temperature sensor on # the printer to find the corresponding ambient temperature. The # default is to use the factory calibration data on the # micro-controller (if applicable) or the nominal values from the # micro-controller specification. #sensor_temperature2: #sensor_adc2: # If sensor_temperature1/sensor_adc1 is specified then one may also # specify sensor_temperature2/sensor_adc2 calibration data. Doing so # may provide calibrated \"temperature slope\" information. The # default is to use the factory calibration data on the # micro-controller (if applicable) or the nominal values from the # micro-controller specification. Host temperature sensor \u00b6 Temperature from the machine (eg Raspberry Pi) running the host software. sensor_type: temperature_host #sensor_path: # The path to temperature system file. The default is # \"/sys/class/thermal/thermal_zone0/temp\" which is the temperature # system file on a Raspberry Pi computer. DS18B20 temperature sensor \u00b6 DS18B20 is a 1-wire (w1) digital temperature sensor. Note that this sensor is not intended for use with extruders and heater beds, but rather for monitoring ambient temperature (C). These sensors have range up to 125 C, so are usable for e.g. chamber temperature monitoring. They can also function as simple fan/heater controllers. DS18B20 sensors are only supported on the \"host mcu\", e.g. the Raspberry Pi. The w1-gpio Linux kernel module must be installed. sensor_type: DS18B20 serial_no: # Each 1-wire device has a unique serial number used to identify the device, # usually in the format 28-031674b175ff. This parameter must be provided. # Attached 1-wire devices can be listed using the following Linux command: # ls /sys/bus/w1/devices/ #ds18_report_time: # Interval in seconds between readings. Default is 3.0, with a minimum of 1.0 #sensor_mcu: # The micro-controller to read from. Must be the host_mcu Combined temperature sensor \u00b6 Combined temperature sensor is a virtual temperature sensor based on several other sensors. This sensor can be used with extruders, heater_generic and heater beds. sensor_type: temperature_combined #sensor_list: # Must be provided. List of sensors to combine to new \"virtual\" # sensor. # E.g. 'temperature_sensor sensor1,extruder,heater_bed' #combination_method: # Must be provided. Combination method used for the sensor. # Available options are 'max', 'min', 'mean'. #maximum_deviation: # Must be provided. Maximum permissible deviation between the sensors # to combine (e.g. 5 degrees). To disable it, use a large value (e.g. 999.9) Fans \u00b6 [fan] \u00b6 Print cooling fan. [fan] pin: # Output pin controlling the fan. This parameter must be provided. #max_power: 1.0 # The maximum power (expressed as a value from 0.0 to 1.0) that the # pin may be set to. The value 1.0 allows the pin to be set fully # enabled for extended periods, while a value of 0.5 would allow the # pin to be enabled for no more than half the time. This setting may # be used to limit the total power output (over extended periods) to # the fan. If this value is less than 1.0 then fan speed requests # will be scaled between zero and max_power (for example, if # max_power is .9 and a fan speed of 80% is requested then the fan # power will be set to 72%). The default is 1.0. #shutdown_speed: 0 # The desired fan speed (expressed as a value from 0.0 to 1.0) if # the micro-controller software enters an error state. The default # is 0. #cycle_time: 0.010 # The amount of time (in seconds) for each PWM power cycle to the # fan. It is recommended this be 10 milliseconds or greater when # using software based PWM. The default is 0.010 seconds. #hardware_pwm: False # Enable this to use hardware PWM instead of software PWM. Most fans # do not work well with hardware PWM, so it is not recommended to # enable this unless there is an electrical requirement to switch at # very high speeds. When using hardware PWM the actual cycle time is # constrained by the implementation and may be significantly # different than the requested cycle_time. The default is False. #kick_start_time: 0.100 # Time (in seconds) to run the fan at full speed when either first # enabling or increasing it by more than 50% (helps get the fan # spinning). The default is 0.100 seconds. #off_below: 0.0 # The minimum input speed which will power the fan (expressed as a # value from 0.0 to 1.0). When a speed lower than off_below is # requested the fan will instead be turned off. This setting may be # used to prevent fan stalls and to ensure kick starts are # effective. The default is 0.0. # # This setting should be recalibrated whenever max_power is adjusted. # To calibrate this setting, start with off_below set to 0.0 and the # fan spinning. Gradually lower the fan speed to determine the lowest # input speed which reliably drives the fan without stalls. Set # off_below to the duty cycle corresponding to this value (for # example, 12% -> 0.12) or slightly higher. #tachometer_pin: # Tachometer input pin for monitoring fan speed. A pullup is generally # required. This parameter is optional. #tachometer_ppr: 2 # When tachometer_pin is specified, this is the number of pulses per # revolution of the tachometer signal. For a BLDC fan this is # normally half the number of poles. The default is 2. #tachometer_poll_interval: 0.0015 # When tachometer_pin is specified, this is the polling period of the # tachometer pin, in seconds. The default is 0.0015, which is fast # enough for fans below 10000 RPM at 2 PPR. This must be smaller than # 30/(tachometer_ppr*rpm), with some margin, where rpm is the # maximum speed (in RPM) of the fan. #enable_pin: # Optional pin to enable power to the fan. This can be useful for fans # with dedicated PWM inputs. Some of these fans stay on even at 0% PWM # input. In such a case, the PWM pin can be used normally, and e.g. a # ground-switched FET(standard fan pin) can be used to control power to # the fan. [heater_fan] \u00b6 Heater cooling fans (one may define any number of sections with a \"heater_fan\" prefix). A \"heater fan\" is a fan that will be enabled whenever its associated heater is active. By default, a heater_fan has a shutdown_speed equal to max_power. [heater_fan heatbreak_cooling_fan] #pin: #max_power: #shutdown_speed: #cycle_time: #hardware_pwm: #kick_start_time: #off_below: #tachometer_pin: #tachometer_ppr: #tachometer_poll_interval: #enable_pin: # See the \"fan\" section for a description of the above parameters. #heater: extruder # Name of the config section defining the heater that this fan is # associated with. If a comma separated list of heater names is # provided here, then the fan will be enabled when any of the given # heaters are enabled. The default is \"extruder\". #heater_temp: 50.0 # A temperature (in Celsius) that the heater must drop below before # the fan is disabled. The default is 50 Celsius. #fan_speed: 1.0 # The fan speed (expressed as a value from 0.0 to 1.0) that the fan # will be set to when its associated heater is enabled. The default # is 1.0 [controller_fan] \u00b6 Controller cooling fan (one may define any number of sections with a \"controller_fan\" prefix). A \"controller fan\" is a fan that will be enabled whenever its associated heater or its associated stepper driver is active. The fan will stop whenever an idle_timeout is reached to ensure no overheating will occur after deactivating a watched component. [controller_fan my_controller_fan] #pin: #max_power: #shutdown_speed: #cycle_time: #hardware_pwm: #kick_start_time: #off_below: #tachometer_pin: #tachometer_ppr: #tachometer_poll_interval: #enable_pin: # See the \"fan\" section for a description of the above parameters. #fan_speed: 1.0 # The fan speed (expressed as a value from 0.0 to 1.0) that the fan # will be set to when a heater or stepper driver is active. # The default is 1.0 #idle_timeout: # The amount of time (in seconds) after a stepper driver or heater # was active and the fan should be kept running. The default # is 30 seconds. #idle_speed: # The fan speed (expressed as a value from 0.0 to 1.0) that the fan # will be set to when a heater or stepper driver was active and # before the idle_timeout is reached. The default is fan_speed. #heater: #stepper: # Name of the config section defining the heater/stepper that this fan # is associated with. If a comma separated list of heater/stepper names # is provided here, then the fan will be enabled when any of the given # heaters/steppers are enabled. The default heater is \"extruder\", the # default stepper is all of them. [temperature_fan] \u00b6 Temperature-triggered cooling fans (one may define any number of sections with a \"temperature_fan\" prefix). A \"temperature fan\" is a fan that will be enabled whenever its associated sensor is above a set temperature. By default, a temperature_fan has a shutdown_speed equal to max_power. See the command reference for additional information. [temperature_fan my_temp_fan] #pin: #max_power: #shutdown_speed: #cycle_time: #hardware_pwm: #kick_start_time: #off_below: #tachometer_pin: #tachometer_ppr: #tachometer_poll_interval: #enable_pin: # See the \"fan\" section for a description of the above parameters. #sensor_type: #sensor_pin: #control: #max_delta: #min_temp: #max_temp: # See the \"extruder\" section for a description of the above parameters. #pid_Kp: #pid_Ki: #pid_Kd: # The proportional (pid_Kp), integral (pid_Ki), and derivative # (pid_Kd) settings for the PID feedback control system. Klipper # evaluates the PID settings with the following general formula: # fan_pwm = max_power - (Kp*e + Ki*integral(e) - Kd*derivative(e)) / 255 # Where \"e\" is \"target_temperature - measured_temperature\" and # \"fan_pwm\" is the requested fan rate with 0.0 being full off and # 1.0 being full on. The pid_Kp, pid_Ki, and pid_Kd parameters must # be provided when the PID control algorithm is enabled. #pid_deriv_time: 2.0 # A time value (in seconds) over which temperature measurements will # be smoothed when using the PID control algorithm. This may reduce # the impact of measurement noise. The default is 2 seconds. #target_temp: 40.0 # A temperature (in Celsius) that will be the target temperature. # The default is 40 degrees. #max_speed: 1.0 # The fan speed (expressed as a value from 0.0 to 1.0) that the fan # will be set to when the sensor temperature exceeds the set value. # The default is 1.0. #min_speed: 0.3 # The minimum fan speed (expressed as a value from 0.0 to 1.0) that # the fan will be set to for PID temperature fans. # The default is 0.3. #gcode_id: # If set, the temperature will be reported in M105 queries using the # given id. The default is to not report the temperature via M105. [fan_generic] \u00b6 Manually controlled fan (one may define any number of sections with a \"fan_generic\" prefix). The speed of a manually controlled fan is set with the SET_FAN_SPEED gcode command . [fan_generic extruder_partfan] #pin: #max_power: #shutdown_speed: #cycle_time: #hardware_pwm: #kick_start_time: #off_below: #tachometer_pin: #tachometer_ppr: #tachometer_poll_interval: #enable_pin: # See the \"fan\" section for a description of the above parameters. LEDs \u00b6 [led] \u00b6 Support for LEDs (and LED strips) controlled via micro-controller PWM pins (one may define any number of sections with an \"led\" prefix). See the command reference for more information. [led my_led] #red_pin: #green_pin: #blue_pin: #white_pin: # The pin controlling the given LED color. At least one of the above # parameters must be provided. #cycle_time: 0.010 # The amount of time (in seconds) per PWM cycle. It is recommended # this be 10 milliseconds or greater when using software based PWM. # The default is 0.010 seconds. #hardware_pwm: False # Enable this to use hardware PWM instead of software PWM. When # using hardware PWM the actual cycle time is constrained by the # implementation and may be significantly different than the # requested cycle_time. The default is False. #initial_RED: 0.0 #initial_GREEN: 0.0 #initial_BLUE: 0.0 #initial_WHITE: 0.0 # Sets the initial LED color. Each value should be between 0.0 and # 1.0. The default for each color is 0. [neopixel] \u00b6 Neopixel (aka WS2812) LED support (one may define any number of sections with a \"neopixel\" prefix). See the command reference for more information. Note that the linux mcu implementation does not currently support directly connected neopixels. The current design using the Linux kernel interface does not allow this scenario because the kernel GPIO interface is not fast enough to provide the required pulse rates. [neopixel my_neopixel] pin: # The pin connected to the neopixel. This parameter must be # provided. #chain_count: # The number of Neopixel chips that are \"daisy chained\" to the # provided pin. The default is 1 (which indicates only a single # Neopixel is connected to the pin). #color_order: GRB # Set the pixel order required by the LED hardware (using a string # containing the letters R, G, B, W with W optional). Alternatively, # this may be a comma separated list of pixel orders - one for each # LED in the chain. The default is GRB. #initial_RED: 0.0 #initial_GREEN: 0.0 #initial_BLUE: 0.0 #initial_WHITE: 0.0 # See the \"led\" section for information on these parameters. [dotstar] \u00b6 Dotstar (aka APA102) LED support (one may define any number of sections with a \"dotstar\" prefix). See the command reference for more information. [dotstar my_dotstar] data_pin: # The pin connected to the data line of the dotstar. This parameter # must be provided. clock_pin: # The pin connected to the clock line of the dotstar. This parameter # must be provided. #chain_count: # See the \"neopixel\" section for information on this parameter. #initial_RED: 0.0 #initial_GREEN: 0.0 #initial_BLUE: 0.0 # See the \"led\" section for information on these parameters. [pca9533] \u00b6 PCA9533 LED support. The PCA9533 is used on the mightyboard. [pca9533 my_pca9533] #i2c_address: 98 # The i2c address that the chip is using on the i2c bus. Use 98 for # the PCA9533/1, 99 for the PCA9533/2. The default is 98. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #initial_RED: 0.0 #initial_GREEN: 0.0 #initial_BLUE: 0.0 #initial_WHITE: 0.0 # See the \"led\" section for information on these parameters. [pca9632] \u00b6 PCA9632 LED support. The PCA9632 is used on the FlashForge Dreamer. [pca9632 my_pca9632] #i2c_address: 98 # The i2c address that the chip is using on the i2c bus. This may be # 96, 97, 98, or 99. The default is 98. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #color_order: RGBW # Set the pixel order of the LED (using a string containing the # letters R, G, B, W). The default is RGBW. #initial_RED: 0.0 #initial_GREEN: 0.0 #initial_BLUE: 0.0 #initial_WHITE: 0.0 # See the \"led\" section for information on these parameters. Additional servos, buttons, and other pins \u00b6 [servo] \u00b6 Servos (one may define any number of sections with a \"servo\" prefix). The servos may be controlled using the SET_SERVO g-code command . For example: SET_SERVO SERVO=my_servo ANGLE=180 [servo my_servo] pin: # PWM output pin controlling the servo. This parameter must be # provided. #maximum_servo_angle: 180 # The maximum angle (in degrees) that this servo can be set to. The # default is 180 degrees. #minimum_pulse_width: 0.001 # The minimum pulse width time (in seconds). This should correspond # with an angle of 0 degrees. The default is 0.001 seconds. #maximum_pulse_width: 0.002 # The maximum pulse width time (in seconds). This should correspond # with an angle of maximum_servo_angle. The default is 0.002 # seconds. #initial_angle: # Initial angle (in degrees) to set the servo to. The default is to # not send any signal at startup. #initial_pulse_width: # Initial pulse width time (in seconds) to set the servo to. (This # is only valid if initial_angle is not set.) The default is to not # send any signal at startup. [gcode_button] \u00b6 Execute gcode when a button is pressed or released (or when a pin changes state). You can check the state of the button by using QUERY_BUTTON button=my_gcode_button . [gcode_button my_gcode_button] pin: # The pin on which the button is connected. This parameter must be # provided. #analog_range: # Two comma separated resistances (in Ohms) specifying the minimum # and maximum resistance range for the button. If analog_range is # provided then the pin must be an analog capable pin. The default # is to use digital gpio for the button. #analog_pullup_resistor: # The pullup resistance (in Ohms) when analog_range is specified. # The default is 4700 ohms. #press_gcode: # A list of G-Code commands to execute when the button is pressed. # G-Code templates are supported. This parameter must be provided. #release_gcode: # A list of G-Code commands to execute when the button is released. # G-Code templates are supported. The default is to not run any # commands on a button release. #debounce_delay: # A period of time in seconds to debounce events prior to running the # button gcode. If the button is pressed and released during this # delay, the entire button press is ignored. Default is 0. [output_pin] \u00b6 Run-time configurable output pins (one may define any number of sections with an \"output_pin\" prefix). Pins configured here will be setup as output pins and one may modify them at run-time using \"SET_PIN PIN=my_pin VALUE=.1\" type extended g-code commands . [output_pin my_pin] pin: # The pin to configure as an output. This parameter must be # provided. #pwm: False # Set if the output pin should be capable of pulse-width-modulation. # If this is true, the value fields should be between 0 and 1; if it # is false the value fields should be either 0 or 1. The default is # False. #value: # The value to initially set the pin to during MCU configuration. # The default is 0 (for low voltage). #shutdown_value: # The value to set the pin to on an MCU shutdown event. The default # is 0 (for low voltage). #cycle_time: 0.100 # The amount of time (in seconds) per PWM cycle. It is recommended # this be 10 milliseconds or greater when using software based PWM. # The default is 0.100 seconds for pwm pins. #hardware_pwm: False # Enable this to use hardware PWM instead of software PWM. When # using hardware PWM the actual cycle time is constrained by the # implementation and may be significantly different than the # requested cycle_time. The default is False. #scale: # This parameter can be used to alter how the 'value' and # 'shutdown_value' parameters are interpreted for pwm pins. If # provided, then the 'value' parameter should be between 0.0 and # 'scale'. This may be useful when configuring a PWM pin that # controls a stepper voltage reference. The 'scale' can be set to # the equivalent stepper amperage if the PWM were fully enabled, and # then the 'value' parameter can be specified using the desired # amperage for the stepper. The default is to not scale the 'value' # parameter. #maximum_mcu_duration: #static_value: # These options are deprecated and should no longer be specified. [pwm_tool] \u00b6 Pulse width modulation digital output pins capable of high speed updates (one may define any number of sections with an \"output_pin\" prefix). Pins configured here will be setup as output pins and one may modify them at run-time using \"SET_PIN PIN=my_pin VALUE=.1\" type extended g-code commands . [pwm_tool my_tool] pin: # The pin to configure as an output. This parameter must be provided. #maximum_mcu_duration: # The maximum duration a non-shutdown value may be driven by the MCU # without an acknowledge from the host. # If host can not keep up with an update, the MCU will shutdown # and set all pins to their respective shutdown values. # Default: 0 (disabled) # Usual values are around 5 seconds. #value: #shutdown_value: #cycle_time: 0.100 #hardware_pwm: False #scale: # See the \"output_pin\" section for the definition of these parameters. [pwm_cycle_time] \u00b6 Run-time configurable output pins with dynamic pwm cycle timing (one may define any number of sections with an \"pwm_cycle_time\" prefix). Pins configured here will be setup as output pins and one may modify them at run-time using \"SET_PIN PIN=my_pin VALUE=.1 CYCLE_TIME=0.100\" type extended g-code commands . [pwm_cycle_time my_pin] pin: #value: #shutdown_value: #cycle_time: 0.100 #scale: # See the \"output_pin\" section for information on these parameters. [static_digital_output] \u00b6 Statically configured digital output pins (one may define any number of sections with a \"static_digital_output\" prefix). Pins configured here will be setup as a GPIO output during MCU configuration. They can not be changed at run-time. [static_digital_output my_output_pins] pins: # A comma separated list of pins to be set as GPIO output pins. The # pin will be set to a high level unless the pin name is prefaced # with \"!\". This parameter must be provided. [multi_pin] \u00b6 Multiple pin outputs (one may define any number of sections with a \"multi_pin\" prefix). A multi_pin output creates an internal pin alias that can modify multiple output pins each time the alias pin is set. For example, one could define a \"[multi_pin my_fan]\" object containing two pins and then set \"pin=multi_pin:my_fan\" in the \"[fan]\" section - on each fan change both output pins would be updated. These aliases may not be used with stepper motor pins. [multi_pin my_multi_pin] pins: # A comma separated list of pins associated with this alias. This # parameter must be provided. TMC stepper driver configuration \u00b6 Configuration of Trinamic stepper motor drivers in UART/SPI mode. Additional information is in the TMC Drivers guide and in the command reference . [tmc2130] \u00b6 Configure a TMC2130 stepper motor driver via SPI bus. To use this feature, define a config section with a \"tmc2130\" prefix followed by the name of the corresponding stepper config section (for example, \"[tmc2130 stepper_x]\"). [tmc2130 stepper_x] cs_pin: # The pin corresponding to the TMC2130 chip select line. This pin # will be set to low at the start of SPI messages and raised to high # after the message completes. This parameter must be provided. #spi_speed: #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #chain_position: #chain_length: # These parameters configure an SPI daisy chain. The two parameters # define the stepper position in the chain and the total chain length. # Position 1 corresponds to the stepper that connects to the MOSI signal. # The default is to not use an SPI daisy chain. #interpolate: True # If true, enable step interpolation (the driver will internally # step at a rate of 256 micro-steps). This interpolation does # introduce a small systemic positional deviation - see # TMC_Drivers.md for details. The default is True. run_current: # The amount of current (in amps RMS) to configure the driver to use # during stepper movement. This parameter must be provided. #hold_current: # The amount of current (in amps RMS) to configure the driver to use # when the stepper is not moving. Setting a hold_current is not # recommended (see TMC_Drivers.md for details). The default is to # not reduce the current. #sense_resistor: 0.110 # The resistance (in ohms) of the motor sense resistor. The default # is 0.110 ohms. #stealthchop_threshold: 0 # The velocity (in mm/s) to set the \"stealthChop\" threshold to. When # set, \"stealthChop\" mode will be enabled if the stepper motor # velocity is below this value. Note that the \"sensorless homing\" # code may temporarily override this setting during homing # operations. The default is 0, which disables \"stealthChop\" mode. #coolstep_threshold: # The velocity (in mm/s) to set the TMC driver internal \"CoolStep\" # threshold to. If set, the coolstep feature will be enabled when # the stepper motor velocity is near or above this value. Important # - if coolstep_threshold is set and \"sensorless homing\" is used, # then one must ensure that the homing speed is above the coolstep # threshold! The default is to not enable the coolstep feature. #high_velocity_threshold: # The velocity (in mm/s) to set the TMC driver internal \"high # velocity\" threshold (THIGH) to. This is typically used to disable # the \"CoolStep\" feature at high speeds. The default is to not set a # TMC \"high velocity\" threshold. #driver_MSLUT0: 2863314260 #driver_MSLUT1: 1251300522 #driver_MSLUT2: 608774441 #driver_MSLUT3: 269500962 #driver_MSLUT4: 4227858431 #driver_MSLUT5: 3048961917 #driver_MSLUT6: 1227445590 #driver_MSLUT7: 4211234 #driver_W0: 2 #driver_W1: 1 #driver_W2: 1 #driver_W3: 1 #driver_X1: 128 #driver_X2: 255 #driver_X3: 255 #driver_START_SIN: 0 #driver_START_SIN90: 247 # These fields control the Microstep Table registers directly. The optimal # wave table is specific to each motor and might vary with current. An # optimal configuration will have minimal print artifacts caused by # non-linear stepper movement. The values specified above are the default # values used by the driver. The value must be specified as a decimal integer # (hex form is not supported). In order to compute the wave table fields, # see the tmc2130 \"Calculation Sheet\" from the Trinamic website. #driver_IHOLDDELAY: 8 #driver_TPOWERDOWN: 0 #driver_TBL: 1 #driver_TOFF: 4 #driver_HEND: 7 #driver_HSTRT: 0 #driver_VHIGHFS: 0 #driver_VHIGHCHM: 0 #driver_PWM_AUTOSCALE: True #driver_PWM_FREQ: 1 #driver_PWM_GRAD: 4 #driver_PWM_AMPL: 128 #driver_FREEWHEEL: 0 #driver_SGT: 0 #driver_SEMIN: 0 #driver_SEUP: 0 #driver_SEMAX: 0 #driver_SEDN: 0 #driver_SEIMIN: 0 #driver_SFILT: 0 # Set the given register during the configuration of the TMC2130 # chip. This may be used to set custom motor parameters. The # defaults for each parameter are next to the parameter name in the # above list. #diag0_pin: #diag1_pin: # The micro-controller pin attached to one of the DIAG lines of the # TMC2130 chip. Only a single diag pin should be specified. The pin # is \"active low\" and is thus normally prefaced with \"^!\". Setting # this creates a \"tmc2130_stepper_x:virtual_endstop\" virtual pin # which may be used as the stepper's endstop_pin. Doing this enables # \"sensorless homing\". (Be sure to also set driver_SGT to an # appropriate sensitivity value.) The default is to not enable # sensorless homing. [tmc2208] \u00b6 Configure a TMC2208 (or TMC2224) stepper motor driver via single wire UART. To use this feature, define a config section with a \"tmc2208\" prefix followed by the name of the corresponding stepper config section (for example, \"[tmc2208 stepper_x]\"). [tmc2208 stepper_x] uart_pin: # The pin connected to the TMC2208 PDN_UART line. This parameter # must be provided. #tx_pin: # If using separate receive and transmit lines to communicate with # the driver then set uart_pin to the receive pin and tx_pin to the # transmit pin. The default is to use uart_pin for both reading and # writing. #select_pins: # A comma separated list of pins to set prior to accessing the # tmc2208 UART. This may be useful for configuring an analog mux for # UART communication. The default is to not configure any pins. #interpolate: True # If true, enable step interpolation (the driver will internally # step at a rate of 256 micro-steps). This interpolation does # introduce a small systemic positional deviation - see # TMC_Drivers.md for details. The default is True. run_current: # The amount of current (in amps RMS) to configure the driver to use # during stepper movement. This parameter must be provided. #hold_current: # The amount of current (in amps RMS) to configure the driver to use # when the stepper is not moving. Setting a hold_current is not # recommended (see TMC_Drivers.md for details). The default is to # not reduce the current. #sense_resistor: 0.110 # The resistance (in ohms) of the motor sense resistor. The default # is 0.110 ohms. #stealthchop_threshold: 0 # The velocity (in mm/s) to set the \"stealthChop\" threshold to. When # set, \"stealthChop\" mode will be enabled if the stepper motor # velocity is below this value. Note that the \"sensorless homing\" # code may temporarily override this setting during homing # operations. The default is 0, which disables \"stealthChop\" mode. #driver_MULTISTEP_FILT: True #driver_IHOLDDELAY: 8 #driver_TPOWERDOWN: 20 #driver_TBL: 2 #driver_TOFF: 3 #driver_HEND: 0 #driver_HSTRT: 5 #driver_PWM_AUTOGRAD: True #driver_PWM_AUTOSCALE: True #driver_PWM_LIM: 12 #driver_PWM_REG: 8 #driver_PWM_FREQ: 1 #driver_PWM_GRAD: 14 #driver_PWM_OFS: 36 #driver_FREEWHEEL: 0 # Set the given register during the configuration of the TMC2208 # chip. This may be used to set custom motor parameters. The # defaults for each parameter are next to the parameter name in the # above list. [tmc2209] \u00b6 Configure a TMC2209 stepper motor driver via single wire UART. To use this feature, define a config section with a \"tmc2209\" prefix followed by the name of the corresponding stepper config section (for example, \"[tmc2209 stepper_x]\"). [tmc2209 stepper_x] uart_pin: #tx_pin: #select_pins: #interpolate: True run_current: #hold_current: #sense_resistor: 0.110 #stealthchop_threshold: 0 # See the \"tmc2208\" section for the definition of these parameters. #coolstep_threshold: # The velocity (in mm/s) to set the TMC driver internal \"CoolStep\" # threshold to. If set, the coolstep feature will be enabled when # the stepper motor velocity is near or above this value. Important # - if coolstep_threshold is set and \"sensorless homing\" is used, # then one must ensure that the homing speed is above the coolstep # threshold! The default is to not enable the coolstep feature. #uart_address: # The address of the TMC2209 chip for UART messages (an integer # between 0 and 3). This is typically used when multiple TMC2209 # chips are connected to the same UART pin. The default is zero. #driver_MULTISTEP_FILT: True #driver_IHOLDDELAY: 8 #driver_TPOWERDOWN: 20 #driver_TBL: 2 #driver_TOFF: 3 #driver_HEND: 0 #driver_HSTRT: 5 #driver_PWM_AUTOGRAD: True #driver_PWM_AUTOSCALE: True #driver_PWM_LIM: 12 #driver_PWM_REG: 8 #driver_PWM_FREQ: 1 #driver_PWM_GRAD: 14 #driver_PWM_OFS: 36 #driver_FREEWHEEL: 0 #driver_SGTHRS: 0 #driver_SEMIN: 0 #driver_SEUP: 0 #driver_SEMAX: 0 #driver_SEDN: 0 #driver_SEIMIN: 0 # Set the given register during the configuration of the TMC2209 # chip. This may be used to set custom motor parameters. The # defaults for each parameter are next to the parameter name in the # above list. #diag_pin: # The micro-controller pin attached to the DIAG line of the TMC2209 # chip. The pin is normally prefaced with \"^\" to enable a pullup. # Setting this creates a \"tmc2209_stepper_x:virtual_endstop\" virtual # pin which may be used as the stepper's endstop_pin. Doing this # enables \"sensorless homing\". (Be sure to also set driver_SGTHRS to # an appropriate sensitivity value.) The default is to not enable # sensorless homing. [tmc2660] \u00b6 Configure a TMC2660 stepper motor driver via SPI bus. To use this feature, define a config section with a tmc2660 prefix followed by the name of the corresponding stepper config section (for example, \"[tmc2660 stepper_x]\"). [tmc2660 stepper_x] cs_pin: # The pin corresponding to the TMC2660 chip select line. This pin # will be set to low at the start of SPI messages and set to high # after the message transfer completes. This parameter must be # provided. #spi_speed: 4000000 # SPI bus frequency used to communicate with the TMC2660 stepper # driver. The default is 4000000. #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #interpolate: True # If true, enable step interpolation (the driver will internally # step at a rate of 256 micro-steps). This only works if microsteps # is set to 16. Interpolation does introduce a small systemic # positional deviation - see TMC_Drivers.md for details. The default # is True. run_current: # The amount of current (in amps RMS) used by the driver during # stepper movement. This parameter must be provided. #sense_resistor: # The resistance (in ohms) of the motor sense resistor. This # parameter must be provided. #idle_current_percent: 100 # The percentage of the run_current the stepper driver will be # lowered to when the idle timeout expires (you need to set up the # timeout using a [idle_timeout] config section). The current will # be raised again once the stepper has to move again. Make sure to # set this to a high enough value such that the steppers do not lose # their position. There is also small delay until the current is # raised again, so take this into account when commanding fast moves # while the stepper is idling. The default is 100 (no reduction). #driver_TBL: 2 #driver_RNDTF: 0 #driver_HDEC: 0 #driver_CHM: 0 #driver_HEND: 3 #driver_HSTRT: 3 #driver_TOFF: 4 #driver_SEIMIN: 0 #driver_SEDN: 0 #driver_SEMAX: 0 #driver_SEUP: 0 #driver_SEMIN: 0 #driver_SFILT: 0 #driver_SGT: 0 #driver_SLPH: 0 #driver_SLPL: 0 #driver_DISS2G: 0 #driver_TS2G: 3 # Set the given parameter during the configuration of the TMC2660 # chip. This may be used to set custom driver parameters. The # defaults for each parameter are next to the parameter name in the # list above. See the TMC2660 datasheet about what each parameter # does and what the restrictions on parameter combinations are. Be # especially aware of the CHOPCONF register, where setting CHM to # either zero or one will lead to layout changes (the first bit of # HDEC) is interpreted as the MSB of HSTRT in this case). [tmc2240] \u00b6 Configure a TMC2240 stepper motor driver via SPI bus or UART. To use this feature, define a config section with a \"tmc2240\" prefix followed by the name of the corresponding stepper config section (for example, \"[tmc2240 stepper_x]\"). [tmc2240 stepper_x] cs_pin: # The pin corresponding to the TMC2240 chip select line. This pin # will be set to low at the start of SPI messages and raised to high # after the message completes. This parameter must be provided. #spi_speed: #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #uart_pin: # The pin connected to the TMC2240 DIAG1/SW line. If this parameter # is provided UART communication is used rather then SPI. #chain_position: #chain_length: # These parameters configure an SPI daisy chain. The two parameters # define the stepper position in the chain and the total chain length. # Position 1 corresponds to the stepper that connects to the MOSI signal. # The default is to not use an SPI daisy chain. #interpolate: True # If true, enable step interpolation (the driver will internally # step at a rate of 256 micro-steps). The default is True. run_current: # The amount of current (in amps RMS) to configure the driver to use # during stepper movement. This parameter must be provided. #hold_current: # The amount of current (in amps RMS) to configure the driver to use # when the stepper is not moving. Setting a hold_current is not # recommended (see TMC_Drivers.md for details). The default is to # not reduce the current. #rref: 12000 # The resistance (in ohms) of the resistor between IREF and GND. The # default is 12000. #stealthchop_threshold: 0 # The velocity (in mm/s) to set the \"stealthChop\" threshold to. When # set, \"stealthChop\" mode will be enabled if the stepper motor # velocity is below this value. Note that the \"sensorless homing\" # code may temporarily override this setting during homing # operations. The default is 0, which disables \"stealthChop\" mode. #coolstep_threshold: # The velocity (in mm/s) to set the TMC driver internal \"CoolStep\" # threshold to. If set, the coolstep feature will be enabled when # the stepper motor velocity is near or above this value. Important # - if coolstep_threshold is set and \"sensorless homing\" is used, # then one must ensure that the homing speed is above the coolstep # threshold! The default is to not enable the coolstep feature. #high_velocity_threshold: # The velocity (in mm/s) to set the TMC driver internal \"high # velocity\" threshold (THIGH) to. This is typically used to disable # the \"CoolStep\" feature at high speeds. The default is to not set a # TMC \"high velocity\" threshold. #driver_MSLUT0: 2863314260 #driver_MSLUT1: 1251300522 #driver_MSLUT2: 608774441 #driver_MSLUT3: 269500962 #driver_MSLUT4: 4227858431 #driver_MSLUT5: 3048961917 #driver_MSLUT6: 1227445590 #driver_MSLUT7: 4211234 #driver_W0: 2 #driver_W1: 1 #driver_W2: 1 #driver_W3: 1 #driver_X1: 128 #driver_X2: 255 #driver_X3: 255 #driver_START_SIN: 0 #driver_START_SIN90: 247 #driver_OFFSET_SIN90: 0 # These fields control the Microstep Table registers directly. The optimal # wave table is specific to each motor and might vary with current. An # optimal configuration will have minimal print artifacts caused by # non-linear stepper movement. The values specified above are the default # values used by the driver. The value must be specified as a decimal integer # (hex form is not supported). In order to compute the wave table fields, # see the tmc2130 \"Calculation Sheet\" from the Trinamic website. # Additionally, this driver also has the OFFSET_SIN90 field which can be used # to tune a motor with unbalanced coils. See the `Sine Wave Lookup Table` # section in the datasheet for information about this field and how to tune # it. #driver_MULTISTEP_FILT: True #driver_IHOLDDELAY: 6 #driver_IRUNDELAY: 4 #driver_TPOWERDOWN: 10 #driver_TBL: 2 #driver_TOFF: 3 #driver_HEND: 2 #driver_HSTRT: 5 #driver_FD3: 0 #driver_TPFD: 4 #driver_CHM: 0 #driver_VHIGHFS: 0 #driver_VHIGHCHM: 0 #driver_DISS2G: 0 #driver_DISS2VS: 0 #driver_PWM_AUTOSCALE: True #driver_PWM_AUTOGRAD: True #driver_PWM_FREQ: 0 #driver_FREEWHEEL: 0 #driver_PWM_GRAD: 0 #driver_PWM_OFS: 29 #driver_PWM_REG: 4 #driver_PWM_LIM: 12 #driver_SGT: 0 #driver_SEMIN: 0 #driver_SEUP: 0 #driver_SEMAX: 0 #driver_SEDN: 0 #driver_SEIMIN: 0 #driver_SFILT: 0 #driver_SG4_ANGLE_OFFSET: 1 #driver_SLOPE_CONTROL: 0 # Set the given register during the configuration of the TMC2240 # chip. This may be used to set custom motor parameters. The # defaults for each parameter are next to the parameter name in the # above list. #diag0_pin: #diag1_pin: # The micro-controller pin attached to one of the DIAG lines of the # TMC2240 chip. Only a single diag pin should be specified. The pin # is \"active low\" and is thus normally prefaced with \"^!\". Setting # this creates a \"tmc2240_stepper_x:virtual_endstop\" virtual pin # which may be used as the stepper's endstop_pin. Doing this enables # \"sensorless homing\". (Be sure to also set driver_SGT to an # appropriate sensitivity value.) The default is to not enable # sensorless homing. [tmc5160] \u00b6 Configure a TMC5160 stepper motor driver via SPI bus. To use this feature, define a config section with a \"tmc5160\" prefix followed by the name of the corresponding stepper config section (for example, \"[tmc5160 stepper_x]\"). [tmc5160 stepper_x] cs_pin: # The pin corresponding to the TMC5160 chip select line. This pin # will be set to low at the start of SPI messages and raised to high # after the message completes. This parameter must be provided. #spi_speed: #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #chain_position: #chain_length: # These parameters configure an SPI daisy chain. The two parameters # define the stepper position in the chain and the total chain length. # Position 1 corresponds to the stepper that connects to the MOSI signal. # The default is to not use an SPI daisy chain. #interpolate: True # If true, enable step interpolation (the driver will internally # step at a rate of 256 micro-steps). The default is True. run_current: # The amount of current (in amps RMS) to configure the driver to use # during stepper movement. This parameter must be provided. #hold_current: # The amount of current (in amps RMS) to configure the driver to use # when the stepper is not moving. Setting a hold_current is not # recommended (see TMC_Drivers.md for details). The default is to # not reduce the current. #sense_resistor: 0.075 # The resistance (in ohms) of the motor sense resistor. The default # is 0.075 ohms. #stealthchop_threshold: 0 # The velocity (in mm/s) to set the \"stealthChop\" threshold to. When # set, \"stealthChop\" mode will be enabled if the stepper motor # velocity is below this value. Note that the \"sensorless homing\" # code may temporarily override this setting during homing # operations. The default is 0, which disables \"stealthChop\" mode. #coolstep_threshold: # The velocity (in mm/s) to set the TMC driver internal \"CoolStep\" # threshold to. If set, the coolstep feature will be enabled when # the stepper motor velocity is near or above this value. Important # - if coolstep_threshold is set and \"sensorless homing\" is used, # then one must ensure that the homing speed is above the coolstep # threshold! The default is to not enable the coolstep feature. #high_velocity_threshold: # The velocity (in mm/s) to set the TMC driver internal \"high # velocity\" threshold (THIGH) to. This is typically used to disable # the \"CoolStep\" feature at high speeds. The default is to not set a # TMC \"high velocity\" threshold. #driver_MSLUT0: 2863314260 #driver_MSLUT1: 1251300522 #driver_MSLUT2: 608774441 #driver_MSLUT3: 269500962 #driver_MSLUT4: 4227858431 #driver_MSLUT5: 3048961917 #driver_MSLUT6: 1227445590 #driver_MSLUT7: 4211234 #driver_W0: 2 #driver_W1: 1 #driver_W2: 1 #driver_W3: 1 #driver_X1: 128 #driver_X2: 255 #driver_X3: 255 #driver_START_SIN: 0 #driver_START_SIN90: 247 # These fields control the Microstep Table registers directly. The optimal # wave table is specific to each motor and might vary with current. An # optimal configuration will have minimal print artifacts caused by # non-linear stepper movement. The values specified above are the default # values used by the driver. The value must be specified as a decimal integer # (hex form is not supported). In order to compute the wave table fields, # see the tmc2130 \"Calculation Sheet\" from the Trinamic website. #driver_MULTISTEP_FILT: True #driver_IHOLDDELAY: 6 #driver_TPOWERDOWN: 10 #driver_TBL: 2 #driver_TOFF: 3 #driver_HEND: 2 #driver_HSTRT: 5 #driver_FD3: 0 #driver_TPFD: 4 #driver_CHM: 0 #driver_VHIGHFS: 0 #driver_VHIGHCHM: 0 #driver_DISS2G: 0 #driver_DISS2VS: 0 #driver_PWM_AUTOSCALE: True #driver_PWM_AUTOGRAD: True #driver_PWM_FREQ: 0 #driver_FREEWHEEL: 0 #driver_PWM_GRAD: 0 #driver_PWM_OFS: 30 #driver_PWM_REG: 4 #driver_PWM_LIM: 12 #driver_SGT: 0 #driver_SEMIN: 0 #driver_SEUP: 0 #driver_SEMAX: 0 #driver_SEDN: 0 #driver_SEIMIN: 0 #driver_SFILT: 0 #driver_DRVSTRENGTH: 0 #driver_BBMCLKS: 4 #driver_BBMTIME: 0 #driver_FILT_ISENSE: 0 # Set the given register during the configuration of the TMC5160 # chip. This may be used to set custom motor parameters. The # defaults for each parameter are next to the parameter name in the # above list. #diag0_pin: #diag1_pin: # The micro-controller pin attached to one of the DIAG lines of the # TMC5160 chip. Only a single diag pin should be specified. The pin # is \"active low\" and is thus normally prefaced with \"^!\". Setting # this creates a \"tmc5160_stepper_x:virtual_endstop\" virtual pin # which may be used as the stepper's endstop_pin. Doing this enables # \"sensorless homing\". (Be sure to also set driver_SGT to an # appropriate sensitivity value.) The default is to not enable # sensorless homing. Run-time stepper motor current configuration \u00b6 [ad5206] \u00b6 Statically configured AD5206 digipots connected via SPI bus (one may define any number of sections with an \"ad5206\" prefix). [ad5206 my_digipot] enable_pin: # The pin corresponding to the AD5206 chip select line. This pin # will be set to low at the start of SPI messages and raised to high # after the message completes. This parameter must be provided. #spi_speed: #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #channel_1: #channel_2: #channel_3: #channel_4: #channel_5: #channel_6: # The value to statically set the given AD5206 channel to. This is # typically set to a number between 0.0 and 1.0 with 1.0 being the # highest resistance and 0.0 being the lowest resistance. However, # the range may be changed with the 'scale' parameter (see below). # If a channel is not specified then it is left unconfigured. #scale: # This parameter can be used to alter how the 'channel_x' parameters # are interpreted. If provided, then the 'channel_x' parameters # should be between 0.0 and 'scale'. This may be useful when the # AD5206 is used to set stepper voltage references. The 'scale' can # be set to the equivalent stepper amperage if the AD5206 were at # its highest resistance, and then the 'channel_x' parameters can be # specified using the desired amperage value for the stepper. The # default is to not scale the 'channel_x' parameters. [mcp4451] \u00b6 Statically configured MCP4451 digipot connected via I2C bus (one may define any number of sections with an \"mcp4451\" prefix). [mcp4451 my_digipot] i2c_address: # The i2c address that the chip is using on the i2c bus. This # parameter must be provided. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #wiper_0: #wiper_1: #wiper_2: #wiper_3: # The value to statically set the given MCP4451 \"wiper\" to. This is # typically set to a number between 0.0 and 1.0 with 1.0 being the # highest resistance and 0.0 being the lowest resistance. However, # the range may be changed with the 'scale' parameter (see below). # If a wiper is not specified then it is left unconfigured. #scale: # This parameter can be used to alter how the 'wiper_x' parameters # are interpreted. If provided, then the 'wiper_x' parameters should # be between 0.0 and 'scale'. This may be useful when the MCP4451 is # used to set stepper voltage references. The 'scale' can be set to # the equivalent stepper amperage if the MCP4451 were at its highest # resistance, and then the 'wiper_x' parameters can be specified # using the desired amperage value for the stepper. The default is # to not scale the 'wiper_x' parameters. [mcp4728] \u00b6 Statically configured MCP4728 digital-to-analog converter connected via I2C bus (one may define any number of sections with an \"mcp4728\" prefix). [mcp4728 my_dac] #i2c_address: 96 # The i2c address that the chip is using on the i2c bus. The default # is 96. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #channel_a: #channel_b: #channel_c: #channel_d: # The value to statically set the given MCP4728 channel to. This is # typically set to a number between 0.0 and 1.0 with 1.0 being the # highest voltage (2.048V) and 0.0 being the lowest voltage. # However, the range may be changed with the 'scale' parameter (see # below). If a channel is not specified then it is left # unconfigured. #scale: # This parameter can be used to alter how the 'channel_x' parameters # are interpreted. If provided, then the 'channel_x' parameters # should be between 0.0 and 'scale'. This may be useful when the # MCP4728 is used to set stepper voltage references. The 'scale' can # be set to the equivalent stepper amperage if the MCP4728 were at # its highest voltage (2.048V), and then the 'channel_x' parameters # can be specified using the desired amperage value for the # stepper. The default is to not scale the 'channel_x' parameters. [mcp4018] \u00b6 Statically configured MCP4018 digipot connected via i2c (one may define any number of sections with an \"mcp4018\" prefix). [mcp4018 my_digipot] #i2c_address: 47 # The i2c address that the chip is using on the i2c bus. The default # is 47. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. wiper: # The value to statically set the given MCP4018 \"wiper\" to. This is # typically set to a number between 0.0 and 1.0 with 1.0 being the # highest resistance and 0.0 being the lowest resistance. However, # the range may be changed with the 'scale' parameter (see below). # This parameter must be provided. #scale: # This parameter can be used to alter how the 'wiper' parameter is # interpreted. If provided, then the 'wiper' parameter should be # between 0.0 and 'scale'. This may be useful when the MCP4018 is # used to set stepper voltage references. The 'scale' can be set to # the equivalent stepper amperage if the MCP4018 is at its highest # resistance, and then the 'wiper' parameter can be specified using # the desired amperage value for the stepper. The default is to not # scale the 'wiper' parameter. Display support \u00b6 [display] \u00b6 Support for a display attached to the micro-controller. [display] lcd_type: # The type of LCD chip in use. This may be \"hd44780\", \"hd44780_spi\", # \"aip31068_spi\", \"st7920\", \"emulated_st7920\", \"uc1701\", \"ssd1306\", or # \"sh1106\". # See the display sections below for information on each type and # additional parameters they provide. This parameter must be # provided. #display_group: # The name of the display_data group to show on the display. This # controls the content of the screen (see the \"display_data\" section # for more information). The default is _default_20x4 for hd44780 or # aip31068_spi displays and _default_16x4 for other displays. #menu_timeout: # Timeout for menu. Being inactive this amount of seconds will # trigger menu exit or return to root menu when having autorun # enabled. The default is 0 seconds (disabled) #menu_root: # Name of the main menu section to show when clicking the encoder # on the home screen. The defaults is __main, and this shows the # the default menus as defined in klippy/extras/display/menu.cfg #menu_reverse_navigation: # When enabled it will reverse up and down directions for list # navigation. The default is False. This parameter is optional. #encoder_pins: # The pins connected to encoder. 2 pins must be provided when using # encoder. This parameter must be provided when using menu. #encoder_steps_per_detent: # How many steps the encoder emits per detent (\"click\"). If the # encoder takes two detents to move between entries or moves two # entries from one detent, try changing this. Allowed values are 2 # (half-stepping) or 4 (full-stepping). The default is 4. #click_pin: # The pin connected to 'enter' button or encoder 'click'. This # parameter must be provided when using menu. The presence of an # 'analog_range_click_pin' config parameter turns this parameter # from digital to analog. #back_pin: # The pin connected to 'back' button. This parameter is optional, # menu can be used without it. The presence of an # 'analog_range_back_pin' config parameter turns this parameter from # digital to analog. #up_pin: # The pin connected to 'up' button. This parameter must be provided # when using menu without encoder. The presence of an # 'analog_range_up_pin' config parameter turns this parameter from # digital to analog. #down_pin: # The pin connected to 'down' button. This parameter must be # provided when using menu without encoder. The presence of an # 'analog_range_down_pin' config parameter turns this parameter from # digital to analog. #kill_pin: # The pin connected to 'kill' button. This button will call # emergency stop. The presence of an 'analog_range_kill_pin' config # parameter turns this parameter from digital to analog. #analog_pullup_resistor: 4700 # The resistance (in ohms) of the pullup attached to the analog # button. The default is 4700 ohms. #analog_range_click_pin: # The resistance range for a 'enter' button. Range minimum and # maximum comma-separated values must be provided when using analog # button. #analog_range_back_pin: # The resistance range for a 'back' button. Range minimum and # maximum comma-separated values must be provided when using analog # button. #analog_range_up_pin: # The resistance range for a 'up' button. Range minimum and maximum # comma-separated values must be provided when using analog button. #analog_range_down_pin: # The resistance range for a 'down' button. Range minimum and # maximum comma-separated values must be provided when using analog # button. #analog_range_kill_pin: # The resistance range for a 'kill' button. Range minimum and # maximum comma-separated values must be provided when using analog # button. hd44780 display \u00b6 Information on configuring hd44780 displays (which is used in \"RepRapDiscount 2004 Smart Controller\" type displays). [display] lcd_type: hd44780 # Set to \"hd44780\" for hd44780 displays. rs_pin: e_pin: d4_pin: d5_pin: d6_pin: d7_pin: # The pins connected to an hd44780 type lcd. These parameters must # be provided. #hd44780_protocol_init: True # Perform 8-bit/4-bit protocol initialization on an hd44780 display. # This is necessary on real hd44780 devices. However, one may need # to disable this on some \"clone\" devices. The default is True. #line_length: # Set the number of characters per line for an hd44780 type lcd. # Possible values are 20 (default) and 16. The number of lines is # fixed to 4. ... hd44780_spi display \u00b6 Information on configuring an hd44780_spi display - a 20x04 display controlled via a hardware \"shift register\" (which is used in mightyboard based printers). [display] lcd_type: hd44780_spi # Set to \"hd44780_spi\" for hd44780_spi displays. latch_pin: spi_software_sclk_pin: spi_software_mosi_pin: spi_software_miso_pin: # The pins connected to the shift register controlling the display. # The spi_software_miso_pin needs to be set to an unused pin of the # printer mainboard as the shift register does not have a MISO pin, # but the software spi implementation requires this pin to be # configured. #hd44780_protocol_init: True # Perform 8-bit/4-bit protocol initialization on an hd44780 display. # This is necessary on real hd44780 devices. However, one may need # to disable this on some \"clone\" devices. The default is True. #line_length: # Set the number of characters per line for an hd44780 type lcd. # Possible values are 20 (default) and 16. The number of lines is # fixed to 4. ... aip31068_spi display \u00b6 Information on configuring an aip31068_spi display - a very similar to hd44780_spi a 20x04 (20 symbols by 4 lines) display with slightly different internal protocol. [display] lcd_type: aip31068_spi latch_pin: spi_software_sclk_pin: spi_software_mosi_pin: spi_software_miso_pin: # The pins connected to the shift register controlling the display. # The spi_software_miso_pin needs to be set to an unused pin of the # printer mainboard as the shift register does not have a MISO pin, # but the software spi implementation requires this pin to be # configured. #line_length: # Set the number of characters per line for an hd44780 type lcd. # Possible values are 20 (default) and 16. The number of lines is # fixed to 4. ... st7920 display \u00b6 Information on configuring st7920 displays (which is used in \"RepRapDiscount 12864 Full Graphic Smart Controller\" type displays). [display] lcd_type: st7920 # Set to \"st7920\" for st7920 displays. cs_pin: sclk_pin: sid_pin: # The pins connected to an st7920 type lcd. These parameters must be # provided. ... emulated_st7920 display \u00b6 Information on configuring an emulated st7920 display - found in some \"2.4 inch touchscreen devices\" and similar. [display] lcd_type: emulated_st7920 # Set to \"emulated_st7920\" for emulated_st7920 displays. en_pin: spi_software_sclk_pin: spi_software_mosi_pin: spi_software_miso_pin: # The pins connected to an emulated_st7920 type lcd. The en_pin # corresponds to the cs_pin of the st7920 type lcd, # spi_software_sclk_pin corresponds to sclk_pin and # spi_software_mosi_pin corresponds to sid_pin. The # spi_software_miso_pin needs to be set to an unused pin of the # printer mainboard as the st7920 as no MISO pin but the software # spi implementation requires this pin to be configured. ... uc1701 display \u00b6 Information on configuring uc1701 displays (which is used in \"MKS Mini 12864\" type displays). [display] lcd_type: uc1701 # Set to \"uc1701\" for uc1701 displays. cs_pin: a0_pin: # The pins connected to a uc1701 type lcd. These parameters must be # provided. #rst_pin: # The pin connected to the \"rst\" pin on the lcd. If it is not # specified then the hardware must have a pull-up on the # corresponding lcd line. #contrast: # The contrast to set. The value may range from 0 to 63 and the # default is 40. ... ssd1306 and sh1106 displays \u00b6 Information on configuring ssd1306 and sh1106 displays. [display] lcd_type: # Set to either \"ssd1306\" or \"sh1106\" for the given display type. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # Optional parameters available for displays connected via an i2c # bus. See the \"common I2C settings\" section for a description of # the above parameters. #cs_pin: #dc_pin: #spi_speed: #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # The pins connected to the lcd when in \"4-wire\" spi mode. See the # \"common SPI settings\" section for a description of the parameters # that start with \"spi_\". The default is to use i2c mode for the # display. #reset_pin: # A reset pin may be specified on the display. If it is not # specified then the hardware must have a pull-up on the # corresponding lcd line. #contrast: # The contrast to set. The value may range from 0 to 256 and the # default is 239. #vcomh: 0 # Set the Vcomh value on the display. This value is associated with # a \"smearing\" effect on some OLED displays. The value may range # from 0 to 63. Default is 0. #invert: False # TRUE inverts the pixels on certain OLED displays. The default is # False. #x_offset: 0 # Set the horizontal offset value on SH1106 displays. The default is # 0. ... [display_data] \u00b6 Support for displaying custom data on an lcd screen. One may create any number of display groups and any number of data items under those groups. The display will show all the data items for a given group if the display_group option in the [display] section is set to the given group name. A default set of display groups are automatically created. One can replace or extend these display_data items by overriding the defaults in the main printer.cfg config file. [display_data my_group_name my_data_name] position: # Comma separated row and column of the display position that should # be used to display the information. This parameter must be # provided. text: # The text to show at the given position. This field is evaluated # using command templates (see docs/Command_Templates.md). This # parameter must be provided. [display_template] \u00b6 Display data text \"macros\" (one may define any number of sections with a display_template prefix). See the command templates document for information on template evaluation. This feature allows one to reduce repetitive definitions in display_data sections. One may use the builtin render() function in display_data sections to evaluate a template. For example, if one were to define [display_template my_template] then one could use { render('my_template') } in a display_data section. This feature can also be used for continuous LED updates using the SET_LED_TEMPLATE command. [display_template my_template_name] #param_: # One may specify any number of options with a \"param_\" prefix. The # given name will be assigned the given value (parsed as a Python # literal) and will be available during macro expansion. If the # parameter is passed in the call to render() then that value will # be used during macro expansion. For example, a config with # \"param_speed = 75\" might have a caller with # \"render('my_template_name', param_speed=80)\". Parameter names may # not use upper case characters. text: # The text to return when the this template is rendered. This field # is evaluated using command templates (see # docs/Command_Templates.md). This parameter must be provided. [display_glyph] \u00b6 Display a custom glyph on displays that support it. The given name will be assigned the given display data which can then be referenced in the display templates by their name surrounded by two \"tilde\" symbols i.e. ~my_display_glyph~ See sample-glyphs.cfg for some examples. [display_glyph my_display_glyph] #data: # The display data, stored as 16 lines consisting of 16 bits (1 per # pixel) where '.' is a blank pixel and '*' is an on pixel (e.g., # \"****************\" to display a solid horizontal line). # Alternatively, one can use '0' for a blank pixel and '1' for an on # pixel. Put each display line into a separate config line. The # glyph must consist of exactly 16 lines with 16 bits each. This # parameter is optional. #hd44780_data: # Glyph to use on 20x4 hd44780 displays. The glyph must consist of # exactly 8 lines with 5 bits each. This parameter is optional. #hd44780_slot: # The hd44780 hardware index (0..7) to store the glyph at. If # multiple distinct images use the same slot then make sure to only # use one of those images in any given screen. This parameter is # required if hd44780_data is specified. [display my_extra_display] \u00b6 If a primary [display] section has been defined in printer.cfg as shown above it is possible to define multiple auxiliary displays. Note that auxiliary displays do not currently support menu functionality, thus they do not support the \"menu\" options or button configuration. [display my_extra_display] # See the \"display\" section for available parameters. [menu] \u00b6 Customizable lcd display menus. A default set of menus are automatically created. One can replace or extend the menu by overriding the defaults in the main printer.cfg config file. See the command template document for information on menu attributes available during template rendering. # Common parameters available for all menu config sections. #[menu __some_list __some_name] #type: disabled # Permanently disabled menu element, only required attribute is 'type'. # Allows you to easily disable/hide existing menu items. #[menu some_name] #type: # One of command, input, list, text: # command - basic menu element with various script triggers # input - same like 'command' but has value changing capabilities. # Press will start/stop edit mode. # list - it allows for menu items to be grouped together in a # scrollable list. Add to the list by creating menu # configurations using \"some_list\" as a prefix - for # example: [menu some_list some_item_in_the_list] # vsdlist - same as 'list' but will append files from virtual sdcard # (will be removed in the future) #name: # Name of menu item - evaluated as a template. #enable: # Template that evaluates to True or False. #index: # Position where an item needs to be inserted in list. By default # the item is added at the end. #[menu some_list] #type: list #name: #enable: # See above for a description of these parameters. #[menu some_list some_command] #type: command #name: #enable: # See above for a description of these parameters. #gcode: # Script to run on button click or long click. Evaluated as a # template. #[menu some_list some_input] #type: input #name: #enable: # See above for a description of these parameters. #input: # Initial value to use when editing - evaluated as a template. # Result must be float. #input_min: # Minimum value of range - evaluated as a template. Default -99999. #input_max: # Maximum value of range - evaluated as a template. Default 99999. #input_step: # Editing step - Must be a positive integer or float value. It has # internal fast rate step. When \"(input_max - input_min) / # input_step > 100\" then fast rate step is 10 * input_step else fast # rate step is same input_step. #realtime: # This attribute accepts static boolean value. When enabled then # gcode script is run after each value change. The default is False. #gcode: # Script to run on button click, long click or value change. # Evaluated as a template. The button click will trigger the edit # mode start or end. Filament sensors \u00b6 [filament_switch_sensor] \u00b6 Filament Switch Sensor. Support for filament insert and runout detection using a switch sensor, such as an endstop switch. See the command reference for more information. [filament_switch_sensor my_sensor] #pause_on_runout: True # When set to True, a PAUSE will execute immediately after a runout # is detected. Note that if pause_on_runout is False and the # runout_gcode is omitted then runout detection is disabled. Default # is True. #runout_gcode: # A list of G-Code commands to execute after a filament runout is # detected. See docs/Command_Templates.md for G-Code format. If # pause_on_runout is set to True this G-Code will run after the # PAUSE is complete. The default is not to run any G-Code commands. #insert_gcode: # A list of G-Code commands to execute after a filament insert is # detected. See docs/Command_Templates.md for G-Code format. The # default is not to run any G-Code commands, which disables insert # detection. #event_delay: 3.0 # The minimum amount of time in seconds to delay between events. # Events triggered during this time period will be silently # ignored. The default is 3 seconds. #pause_delay: 0.5 # The amount of time to delay, in seconds, between the pause command # dispatch and execution of the runout_gcode. It may be useful to # increase this delay if OctoPrint exhibits strange pause behavior. # Default is 0.5 seconds. #debounce_delay: # A period of time in seconds to debounce events prior to running the # switch gcode. The switch must he held in a single state for at least # this long to activate. If the switch is toggled on/off during this delay, # the event is ignored. Default is 0. #switch_pin: # The pin on which the switch is connected. This parameter must be # provided. [filament_motion_sensor] \u00b6 Filament Motion Sensor. Support for filament insert and runout detection using an encoder that toggles the output pin during filament movement through the sensor. See the command reference for more information. [filament_motion_sensor my_sensor] detection_length: 7.0 # The minimum length of filament pulled through the sensor to trigger # a state change on the switch_pin # Default is 7 mm. extruder: # The name of the extruder or extruder_stepper section this sensor # is associated with. This parameter must be provided. switch_pin: #pause_on_runout: #runout_gcode: #insert_gcode: #event_delay: #pause_delay: # See the \"filament_switch_sensor\" section for a description of the # above parameters. [tsl1401cl_filament_width_sensor] \u00b6 TSLl401CL Based Filament Width Sensor. See the guide for more information. [tsl1401cl_filament_width_sensor] #pin: #default_nominal_filament_diameter: 1.75 # (mm) # Maximum allowed filament diameter difference as mm. #max_difference: 0.2 # The distance from sensor to the melting chamber as mm. #measurement_delay: 100 [hall_filament_width_sensor] \u00b6 Hall filament width sensor (see Hall Filament Width Sensor ). [hall_filament_width_sensor] adc1: adc2: # Analog input pins connected to the sensor. These parameters must # be provided. #cal_dia1: 1.50 #cal_dia2: 2.00 # The calibration values (in mm) for the sensors. The default is # 1.50 for cal_dia1 and 2.00 for cal_dia2. #raw_dia1: 9500 #raw_dia2: 10500 # The raw calibration values for the sensors. The default is 9500 # for raw_dia1 and 10500 for raw_dia2. #default_nominal_filament_diameter: 1.75 # The nominal filament diameter. This parameter must be provided. #max_difference: 0.200 # Maximum allowed filament diameter difference in millimeters (mm). # If difference between nominal filament diameter and sensor output # is more than +- max_difference, extrusion multiplier is set back # to %100. The default is 0.200. #measurement_delay: 70 # The distance from sensor to the melting chamber/hot-end in # millimeters (mm). The filament between the sensor and the hot-end # will be treated as the default_nominal_filament_diameter. Host # module works with FIFO logic. It keeps each sensor value and # position in an array and POP them back in correct position. This # parameter must be provided. #enable: False # Sensor enabled or disabled after power on. The default is to # disable. #measurement_interval: 10 # The approximate distance (in mm) between sensor readings. The # default is 10mm. #logging: False # Out diameter to terminal and klipper.log can be turn on|of by # command. #min_diameter: 1.0 # Minimal diameter for trigger virtual filament_switch_sensor. #max_diameter: # Maximum diameter for triggering virtual filament_switch_sensor. # The default is default_nominal_filament_diameter + max_difference. #use_current_dia_while_delay: False # Use the current diameter instead of the nominal diameter while # the measurement delay has not run through. #pause_on_runout: #runout_gcode: #insert_gcode: #event_delay: #pause_delay: # See the \"filament_switch_sensor\" section for a description of the # above parameters. Load Cells \u00b6 [load_cell] \u00b6 Load Cell. Uses an ADC sensor attached to a load cell to create a digital scale. [load_cell] sensor_type: # This must be one of the supported sensor types, see below. #counts_per_gram: # The floating point number of sensor counts that indicates 1 gram of force. # This value is calculated by the LOAD_CELL_CALIBRATE command. #reference_tare_counts: # The integer tare value, in raw sensor counts, taken when LOAD_CELL_CALIBRATE # is run. This is the default tare value when klipper starts up. #sensor_orientation: # Change the sensor's orientation. Can be either 'normal' or 'inverted'. # The default is 'normal'. Use 'inverted' if the sensor reports a # decreasing force value when placed under load. HX711 \u00b6 This is a 24 bit low sample rate chip using \"bit-bang\" communications. It is suitable for filament scales. [load_cell] sensor_type: hx711 sclk_pin: # The pin connected to the HX711 clock line. This parameter must be provided. dout_pin: # The pin connected to the HX711 data output line. This parameter must be # provided. #gain: A-128 # Valid values for gain are: A-128, A-64, B-32. The default is A-128. # 'A' denotes the input channel and the number denotes the gain. Only the 3 # listed combinations are supported by the chip. Note that changing the gain # setting also selects the channel being read. #sample_rate: 80 # Valid values for sample_rate are 80 or 10. The default value is 80. # This must match the wiring of the chip. The sample rate cannot be changed # in software. HX717 \u00b6 This is the 4x higher sample rate version of the HX711, suitable for probing. [load_cell] sensor_type: hx717 sclk_pin: # The pin connected to the HX717 clock line. This parameter must be provided. dout_pin: # The pin connected to the HX717 data output line. This parameter must be # provided. #gain: A-128 # Valid values for gain are A-128, B-64, A-64, B-8. # 'A' denotes the input channel and the number denotes the gain setting. # Only the 4 listed combinations are supported by the chip. Note that # changing the gain setting also selects the channel being read. #sample_rate: 320 # Valid values for sample_rate are: 10, 20, 80, 320. The default is 320. # This must match the wiring of the chip. The sample rate cannot be changed # in software. ADS1220 \u00b6 The ADS1220 is a 24 bit ADC supporting up to a 2Khz sample rate configurable in software. [load_cell] sensor_type: ads1220 cs_pin: # The pin connected to the ADS1220 chip select line. This parameter must # be provided. #spi_speed: 512000 # This chip supports 2 speeds: 256000 or 512000. The faster speed is only # enabled when one of the Turbo sample rates is used. The correct spi_speed # is selected based on the sample rate. #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. data_ready_pin: # Pin connected to the ADS1220 data ready line. This parameter must be # provided. #gain: 128 # Valid gain values are 128, 64, 32, 16, 8, 4, 2, 1 # The default is 128 #pga_bypass: False # Disable the internal Programmable Gain Amplifier. If # True the PGA will be disabled for gains 1, 2, and 4. The PGA is always # enabled for gain settings 8 to 128, regardless of the pga_bypass setting. # If AVSS is used as an input pga_bypass is forced to True. # The default is False. #sample_rate: 660 # This chip supports two ranges of sample rates, Normal and Turbo. In turbo # mode the chip's internal clock runs twice as fast and the SPI communication # speed is also doubled. # Normal sample rates: 20, 45, 90, 175, 330, 600, 1000 # Turbo sample rates: 40, 90, 180, 350, 660, 1200, 2000 # The default is 660 #input_mux: # Input multiplexer configuration, select a pair of pins to use. The first pin # is the positive, AINP, and the second pin is the negative, AINN. Valid # values are: 'AIN0_AIN1', 'AIN0_AIN2', 'AIN0_AIN3', 'AIN1_AIN2', 'AIN1_AIN3', # 'AIN2_AIN3', 'AIN1_AIN0', 'AIN3_AIN2', 'AIN0_AVSS', 'AIN1_AVSS', 'AIN2_AVSS' # and 'AIN3_AVSS'. If AVSS is used the PGA is bypassed and the pga_bypass # setting will be forced to True. # The default is AIN0_AIN1. #vref: # The selected voltage reference. Valid values are: 'internal', 'REF0', 'REF1' # and 'analog_supply'. Default is 'internal'. [load_cell_probe] \u00b6 Load Cell Probe. This combines the functionality of a [probe] and a [load_cell]. [load_cell_probe] sensor_type: # This must be one of the supported bulk ADC sensor types and support # load cell endstops on the mcu. #counts_per_gram: #reference_tare_counts: #sensor_orientation: # These parameters must be configured before the probe will operate. # See the [load_cell] section for further details. #force_safety_limit: 2000 # The safe limit for probing force relative to the reference_tare_counts on # the load_cell. The default is +/-2Kg. #trigger_force: 75.0 # The force that the probe will trigger at. 75g is the default. #drift_filter_cutoff_frequency: 0.8 # Enable optional continuous taring while homing & probing to reject drift. # The value is a frequency, in Hz, below which drift will be ignored. This # option requires the SciPy library. Default: None #drift_filter_delay: 2 # The delay, or 'order', of the drift filter. This controls the number of # samples required to make a trigger detection. Can be 1 or 2, the default # is 2. #buzz_filter_cutoff_frequency: 100.0 # The value is a frequency, in Hz, above which high frequency noise in the # load cell will be igfiltered outnored. This option requires the SciPy # library. Default: None #buzz_filter_delay: 2 # The delay, or 'order', of the buzz filter. This controls the number of # samples required to make a trigger detection. Can be 1 or 2, the default # is 2. #notch_filter_frequencies: 50, 60 # 1 or 2 frequencies, in Hz, to filter out of the load cell data. This is # intended to reject power line noise. This option requires the SciPy # library. Default: None #notch_filter_quality: 2.0 # Controls how narrow the range of frequencies are that the notch filter # removes. Larger numbers produce a narrower filter. Minimum value is 0.5 and # maximum is 3.0. Default: 2.0 #tare_time: # The rime in seconds used for taring the load_cell before each probe. The # default value is: 4 / 60 = 0.066. This collects samples from 4 cycles of # 60Hz mains power to cancel power line noise. #z_offset: #speed: #samples: #sample_retract_dist: #lift_speed: #samples_result: #samples_tolerance: #samples_tolerance_retries: #activate_gcode: #deactivate_gcode: # See the \"[probe]\" section for a description of the above parameters. Board specific hardware support \u00b6 [sx1509] \u00b6 Configure an SX1509 I2C to GPIO expander. Due to the delay incurred by I2C communication you should NOT use SX1509 pins as stepper enable, step or dir pins or any other pin that requires fast bit-banging. They are best used as static or gcode controlled digital outputs or hardware-pwm pins for e.g. fans. One may define any number of sections with an \"sx1509\" prefix. Each expander provides a set of 16 pins (sx1509_my_sx1509:PIN_0 to sx1509_my_sx1509:PIN_15) which can be used in the printer configuration. See the generic-duet2-duex.cfg file for an example. [sx1509 my_sx1509] i2c_address: # I2C address used by this expander. Depending on the hardware # jumpers this is one out of the following addresses: 62 63 112 # 113. This parameter must be provided. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. [samd_sercom] \u00b6 SAMD SERCOM configuration to specify which pins to use on a given SERCOM. One may define any number of sections with a \"samd_sercom\" prefix. Each SERCOM must be configured prior to using it as SPI or I2C peripheral. Place this config section above any other section that makes use of SPI or I2C buses. [samd_sercom my_sercom] sercom: # The name of the sercom bus to configure in the micro-controller. # Available names are \"sercom0\", \"sercom1\", etc.. This parameter # must be provided. tx_pin: # MOSI pin for SPI communication, or SDA (data) pin for I2C # communication. The pin must have a valid pinmux configuration # for the given SERCOM peripheral. This parameter must be provided. #rx_pin: # MISO pin for SPI communication. This pin is not used for I2C # communication (I2C uses tx_pin for both sending and receiving). # The pin must have a valid pinmux configuration for the given # SERCOM peripheral. This parameter is optional. clk_pin: # CLK pin for SPI communication, or SCL (clock) pin for I2C # communication. The pin must have a valid pinmux configuration # for the given SERCOM peripheral. This parameter must be provided. [adc_scaled] \u00b6 Duet2 Maestro analog scaling by vref and vssa readings. Defining an adc_scaled section enables virtual adc pins (such as \"my_name:PB0\") that are automatically adjusted by the board's vref and vssa monitoring pins. Be sure to define this config section above any config sections that use one these virtual pins. See the generic-duet2-maestro.cfg file for an example. [adc_scaled my_name] vref_pin: # The ADC pin to use for VREF monitoring. This parameter must be # provided. vssa_pin: # The ADC pin to use for VSSA monitoring. This parameter must be # provided. #smooth_time: 2.0 # A time value (in seconds) over which the vref and vssa # measurements will be smoothed to reduce the impact of measurement # noise. The default is 2 seconds. [ads1x1x] \u00b6 ADS1013, ADS1014, ADS1015, ADS1113, ADS1114 and ADS1115 are I2C based Analog to Digital Converters that can be used for temperature sensors. They provide 4 analog input pins either as single line or as differential input. Note: Use caution if using this sensor to control heaters. The heater min_temp and max_temp are only verified in the host and only if the host is running and operating normally. (ADC inputs directly connected to the micro-controller verify min_temp and max_temp within the micro-controller and do not require a working connection to the host.) [ads1x1x my_ads1x1x] chip: ADS1115 #pga: 4.096V # Default value is 4.096V. The maximum voltage range used for the input. This # scales all values read from the ADC. Options are: 6.144V, 4.096V, 2.048V, # 1.024V, 0.512V, 0.256V #adc_voltage: 3.3 # The supply voltage for the device. This allows additional software scaling # for all values read from the ADC. i2c_mcu: host i2c_bus: i2c.1 #address_pin: GND # Default value is GND. There can be up to four addressed devices depending # upon wiring of the device. Check the datasheet for details. The i2c_address # can be specified directly instead of using the address_pin. The chip provides pins that can be used on other sensors. sensor_type: ... # Can be any thermistor or adc_temperature. sensor_pin: my_ads1x1x:AIN0 # A combination of the name of the ads1x1x chip and the pin. Possible # pin values are AIN0, AIN1, AIN2 and AIN3 for single ended lines and # DIFF01, DIFF03, DIFF13 and DIFF23 for differential between their # corresponding lines. For example # DIFF03 measures the differential between line 0 and 3. Only specific # combinations for the differentials are allowed. [replicape] \u00b6 Replicape support - see the beaglebone guide and the generic-replicape.cfg file for an example. # The \"replicape\" config section adds \"replicape:stepper_x_enable\" # virtual stepper enable pins (for steppers X, Y, Z, E, and H) and # \"replicape:power_x\" PWM output pins (for hotbed, e, h, fan0, fan1, # fan2, and fan3) that may then be used elsewhere in the config file. [replicape] revision: # The replicape hardware revision. Currently only revision \"B3\" is # supported. This parameter must be provided. #enable_pin: !gpio0_20 # The replicape global enable pin. The default is !gpio0_20 (aka # P9_41). host_mcu: # The name of the mcu config section that communicates with the # Klipper \"linux process\" mcu instance. This parameter must be # provided. #standstill_power_down: False # This parameter controls the CFG6_ENN line on all stepper # motors. True sets the enable lines to \"open\". The default is # False. #stepper_x_microstep_mode: #stepper_y_microstep_mode: #stepper_z_microstep_mode: #stepper_e_microstep_mode: #stepper_h_microstep_mode: # This parameter controls the CFG1 and CFG2 pins of the given # stepper motor driver. Available options are: disable, 1, 2, # spread2, 4, 16, spread4, spread16, stealth4, and stealth16. The # default is disable. #stepper_x_current: #stepper_y_current: #stepper_z_current: #stepper_e_current: #stepper_h_current: # The configured maximum current (in Amps) of the stepper motor # driver. This parameter must be provided if the stepper is not in a # disable mode. #stepper_x_chopper_off_time_high: #stepper_y_chopper_off_time_high: #stepper_z_chopper_off_time_high: #stepper_e_chopper_off_time_high: #stepper_h_chopper_off_time_high: # This parameter controls the CFG0 pin of the stepper motor driver # (True sets CFG0 high, False sets it low). The default is False. #stepper_x_chopper_hysteresis_high: #stepper_y_chopper_hysteresis_high: #stepper_z_chopper_hysteresis_high: #stepper_e_chopper_hysteresis_high: #stepper_h_chopper_hysteresis_high: # This parameter controls the CFG4 pin of the stepper motor driver # (True sets CFG4 high, False sets it low). The default is False. #stepper_x_chopper_blank_time_high: #stepper_y_chopper_blank_time_high: #stepper_z_chopper_blank_time_high: #stepper_e_chopper_blank_time_high: #stepper_h_chopper_blank_time_high: # This parameter controls the CFG5 pin of the stepper motor driver # (True sets CFG5 high, False sets it low). The default is True. Other Custom Modules \u00b6 [palette2] \u00b6 Palette 2 multimaterial support - provides a tighter integration supporting Palette 2 devices in connected mode. This modules also requires [virtual_sdcard] and [pause_resume] for full functionality. If you use this module, do not use the Palette 2 plugin for Octoprint as they will conflict, and 1 will fail to initialize properly likely aborting your print. If you use Octoprint and stream gcode over the serial port instead of printing from virtual_sd, then remove M1 and M0 from Pausing commands in Settings > Serial Connection > Firmware & protocol will prevent the need to start print on the Palette 2 and unpausing in Octoprint for your print to begin. [palette2] serial: # The serial port to connect to the Palette 2. #baud: 115200 # The baud rate to use. The default is 115200. #feedrate_splice: 0.8 # The feedrate to use when splicing, default is 0.8 #feedrate_normal: 1.0 # The feedrate to use after splicing, default is 1.0 #auto_load_speed: 2 # Extrude feedrate when autoloading, default is 2 (mm/s) #auto_cancel_variation: 0.1 # Auto cancel print when ping variation is above this threshold [angle] \u00b6 Magnetic hall angle sensor support for reading stepper motor angle shaft measurements using a1333, as5047d, mt6816, mt6826s, or tle5012b SPI chips. The measurements are available via the API Server and motion analysis tool . See the G-Code reference for available commands. [angle my_angle_sensor] sensor_type: # The type of the magnetic hall sensor chip. Available choices are # \"a1333\", \"as5047d\", \"mt6816\", \"mt6826s\", and \"tle5012b\". This parameter must be # specified. #sample_period: 0.000400 # The query period (in seconds) to use during measurements. The # default is 0.000400 (which is 2500 samples per second). #stepper: # The name of the stepper that the angle sensor is attached to (eg, # \"stepper_x\"). Setting this value enables an angle calibration # tool. To use this feature, the Python \"numpy\" package must be # installed. The default is to not enable angle calibration for the # angle sensor. cs_pin: # The SPI enable pin for the sensor. This parameter must be provided. #spi_speed: #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. Common bus parameters \u00b6 Common SPI settings \u00b6 The following parameters are generally available for devices using an SPI bus. #spi_speed: # The SPI speed (in hz) to use when communicating with the device. # The default depends on the type of device. #spi_bus: # If the micro-controller supports multiple SPI busses then one may # specify the micro-controller bus name here. The default depends on # the type of micro-controller. #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # Specify the above parameters to use \"software based SPI\". This # mode does not require micro-controller hardware support (typically # any general purpose pins may be used). The default is to not use # \"software spi\". Common I2C settings \u00b6 The following parameters are generally available for devices using an I2C bus. Note that Klipper's current micro-controller support for I2C is generally not tolerant to line noise. Unexpected errors on the I2C wires may result in Klipper raising a run-time error. Klipper's support for error recovery varies between each micro-controller type. It is generally recommended to only use I2C devices that are on the same printed circuit board as the micro-controller. Most Klipper micro-controller implementations only support an i2c_speed of 100000 ( standard mode , 100kbit/s). The Klipper \"Linux\" micro-controller supports a 400000 speed ( fast mode , 400kbit/s), but it must be set in the operating system and the i2c_speed parameter is otherwise ignored. The Klipper \"RP2040\" micro-controller and ATmega AVR family and some STM32 (F0, G0, G4, L4, F7, H7) support a rate of 400000 via the i2c_speed parameter. All other Klipper micro-controllers use a 100000 rate and ignore the i2c_speed parameter. #i2c_address: # The i2c address of the device. This must specified as a decimal # number (not in hex). The default depends on the type of device. #i2c_mcu: # The name of the micro-controller that the chip is connected to. # The default is \"mcu\". #i2c_bus: # If the micro-controller supports multiple I2C busses then one may # specify the micro-controller bus name here. The default depends on # the type of micro-controller. #i2c_software_scl_pin: #i2c_software_sda_pin: # Specify these parameters to use micro-controller software based # I2C \"bit-banging\" support. The two parameters should the two pins # on the micro-controller to use for the scl and sda wires. The # default is to use hardware based I2C support as specified by the # i2c_bus parameter. #i2c_speed: # The I2C speed (in Hz) to use when communicating with the device. # The Klipper implementation on most micro-controllers is hard-coded # to 100000 and changing this value has no effect. The default is # 100000. Linux, RP2040 and ATmega support 400000.","title":"Configuration reference"},{"location":"Config_Reference.html#configuration-reference","text":"This document is a reference for options available in the Klipper config file. The descriptions in this document are formatted so that it is possible to cut-and-paste them into a printer config file. See the installation document for information on setting up Klipper and choosing an initial config file.","title":"Configuration reference"},{"location":"Config_Reference.html#micro-controller-configuration","text":"","title":"Micro-controller configuration"},{"location":"Config_Reference.html#format-of-micro-controller-pin-names","text":"Many config options require the name of a micro-controller pin. Klipper uses the hardware names for these pins - for example PA4 . Pin names may be preceded by ! to indicate that a reverse polarity should be used (eg, trigger on low instead of high). Input pins may be preceded by ^ to indicate that a hardware pull-up resistor should be enabled for the pin. If the micro-controller supports pull-down resistors then an input pin may alternatively be preceded by ~ . Note, some config sections may \"create\" additional pins. Where this occurs, the config section defining the pins must be listed in the config file before any sections using those pins.","title":"Format of micro-controller pin names"},{"location":"Config_Reference.html#mcu","text":"Configuration of the primary micro-controller. [mcu] serial: # The serial port to connect to the MCU. If unsure (or if it # changes) see the \"Where's my serial port?\" section of the FAQ. # This parameter must be provided when using a serial port. #baud: 250000 # The baud rate to use. The default is 250000. #canbus_uuid: # If using a device connected to a CAN bus then this sets the unique # chip identifier to connect to. This value must be provided when using # CAN bus for communication. #canbus_interface: # If using a device connected to a CAN bus then this sets the CAN # network interface to use. The default is 'can0'. #restart_method: # This controls the mechanism the host will use to reset the # micro-controller. The choices are 'arduino', 'cheetah', 'rpi_usb', # and 'command'. The 'arduino' method (toggle DTR) is common on # Arduino boards and clones. The 'cheetah' method is a special # method needed for some Fysetc Cheetah boards. The 'rpi_usb' method # is useful on Raspberry Pi boards with micro-controllers powered # over USB - it briefly disables power to all USB ports to # accomplish a micro-controller reset. The 'command' method involves # sending a Klipper command to the micro-controller so that it can # reset itself. The default is 'arduino' if the micro-controller # communicates over a serial port, 'command' otherwise.","title":"[mcu]"},{"location":"Config_Reference.html#mcu-my_extra_mcu","text":"Additional micro-controllers (one may define any number of sections with an \"mcu\" prefix). Additional micro-controllers introduce additional pins that may be configured as heaters, steppers, fans, etc.. For example, if an \"[mcu extra_mcu]\" section is introduced, then pins such as \"extra_mcu:ar9\" may then be used elsewhere in the config (where \"ar9\" is a hardware pin name or alias name on the given mcu). [mcu my_extra_mcu] # See the \"mcu\" section for configuration parameters.","title":"[mcu my_extra_mcu]"},{"location":"Config_Reference.html#common-kinematic-settings","text":"","title":"Common kinematic settings"},{"location":"Config_Reference.html#printer","text":"The printer section controls high level printer settings. [printer] kinematics: # The type of printer in use. This option may be one of: cartesian, # corexy, corexz, hybrid_corexy, hybrid_corexz, generic_cartesian, # rotary_delta, delta, deltesian, polar, winch, or none. # This parameter must be specified. max_velocity: # Maximum velocity (in mm/s) of the toolhead (relative to the # print). This value may be changed at runtime using the # SET_VELOCITY_LIMIT command. This parameter must be specified. max_accel: # Maximum acceleration (in mm/s^2) of the toolhead (relative to the # print). Although this parameter is described as a \"maximum\" # acceleration, in practice most moves that accelerate or decelerate # will do so at the rate specified here. The value specified here # may be changed at runtime using the SET_VELOCITY_LIMIT command. # This parameter must be specified. #minimum_cruise_ratio: 0.5 # Most moves will accelerate to a cruising speed, travel at that # cruising speed, and then decelerate. However, some moves that # travel a short distance could nominally accelerate and then # immediately decelerate. This option reduces the top speed of these # moves to ensure there is always a minimum distance traveled at a # cruising speed. That is, it enforces a minimum distance traveled # at cruising speed relative to the total distance traveled. It is # intended to reduce the top speed of short zigzag moves (and thus # reduce printer vibration from these moves). For example, a # minimum_cruise_ratio of 0.5 would ensure that a standalone 1.5mm # move would have a minimum cruising distance of 0.75mm. Specify a # ratio of 0.0 to disable this feature (there would be no minimum # cruising distance enforced between acceleration and deceleration). # The value specified here may be changed at runtime using the # SET_VELOCITY_LIMIT command. The default is 0.5. #square_corner_velocity: 5.0 # The maximum velocity (in mm/s) that the toolhead may travel a 90 # degree corner at. A non-zero value can reduce changes in extruder # flow rates by enabling instantaneous velocity changes of the # toolhead during cornering. This value configures the internal # centripetal velocity cornering algorithm; corners with angles # larger than 90 degrees will have a higher cornering velocity while # corners with angles less than 90 degrees will have a lower # cornering velocity. If this is set to zero then the toolhead will # decelerate to zero at each corner. The value specified here may be # changed at runtime using the SET_VELOCITY_LIMIT command. The # default is 5mm/s.","title":"[printer]"},{"location":"Config_Reference.html#stepper","text":"Stepper motor definitions. Different printer types (as specified by the \"kinematics\" option in the [printer] config section) require different names for the stepper (eg, stepper_x vs stepper_a ). Below are common stepper definitions. See the rotation distance document for information on calculating the rotation_distance parameter. See the Multi-MCU homing document for information on homing using multiple micro-controllers. [stepper_x] step_pin: # Step GPIO pin (triggered high). This parameter must be provided. dir_pin: # Direction GPIO pin (high indicates positive direction). This # parameter must be provided. enable_pin: # Enable pin (default is enable high; use ! to indicate enable # low). If this parameter is not provided then the stepper motor # driver must always be enabled. rotation_distance: # Distance (in mm) that the axis travels with one full rotation of # the stepper motor (or final gear if gear_ratio is specified). # This parameter must be provided. microsteps: # The number of microsteps the stepper motor driver uses. This # parameter must be provided. #full_steps_per_rotation: 200 # The number of full steps for one rotation of the stepper motor. # Set this to 200 for a 1.8 degree stepper motor or set to 400 for a # 0.9 degree motor. The default is 200. #gear_ratio: # The gear ratio if the stepper motor is connected to the axis via a # gearbox. For example, one may specify \"5:1\" if a 5 to 1 gearbox is # in use. If the axis has multiple gearboxes one may specify a comma # separated list of gear ratios (for example, \"57:11, 2:1\"). If a # gear_ratio is specified then rotation_distance specifies the # distance the axis travels for one full rotation of the final gear. # The default is to not use a gear ratio. #step_pulse_duration: # The minimum time between the step pulse signal edge and the # following \"unstep\" signal edge. This is also used to set the # minimum time between a step pulse and a direction change signal. # The default is 0.000000100 (100ns) for TMC steppers that are # configured in UART or SPI mode, and the default is 0.000002 (which # is 2us) for all other steppers. endstop_pin: # Endstop switch detection pin. If this endstop pin is on a # different mcu than the stepper motor then it enables \"multi-mcu # homing\". This parameter must be provided for the X, Y, and Z # steppers on cartesian style printers. #position_min: 0 # Minimum valid distance (in mm) the user may command the stepper to # move to. The default is 0mm. position_endstop: # Location of the endstop (in mm). This parameter must be provided # for the X, Y, and Z steppers on cartesian style printers. position_max: # Maximum valid distance (in mm) the user may command the stepper to # move to. This parameter must be provided for the X, Y, and Z # steppers on cartesian style printers. #homing_speed: 5.0 # Maximum velocity (in mm/s) of the stepper when homing. The default # is 5mm/s. #homing_retract_dist: 5.0 # Distance to backoff (in mm) before homing a second time during # homing. Set this to zero to disable the second home. The default # is 5mm. #homing_retract_speed: # Speed to use on the retract move after homing in case this should # be different from the homing speed, which is the default for this # parameter #second_homing_speed: # Velocity (in mm/s) of the stepper when performing the second home. # The default is homing_speed/2. #homing_positive_dir: # If true, homing will cause the stepper to move in a positive # direction (away from zero); if false, home towards zero. It is # better to use the default than to specify this parameter. The # default is true if position_endstop is near position_max and false # if near position_min.","title":"[stepper]"},{"location":"Config_Reference.html#cartesian-kinematics","text":"See example-cartesian.cfg for an example cartesian kinematics config file. Only parameters specific to cartesian printers are described here - see common kinematic settings for available parameters. [printer] kinematics: cartesian max_z_velocity: # This sets the maximum velocity (in mm/s) of movement along the z # axis. This setting can be used to restrict the maximum speed of # the z stepper motor. The default is to use max_velocity for # max_z_velocity. max_z_accel: # This sets the maximum acceleration (in mm/s^2) of movement along # the z axis. It limits the acceleration of the z stepper motor. The # default is to use max_accel for max_z_accel. # The stepper_x section is used to describe the stepper controlling # the X axis in a cartesian robot. [stepper_x] # The stepper_y section is used to describe the stepper controlling # the Y axis in a cartesian robot. [stepper_y] # The stepper_z section is used to describe the stepper controlling # the Z axis in a cartesian robot. [stepper_z]","title":"Cartesian Kinematics"},{"location":"Config_Reference.html#linear-delta-kinematics","text":"See example-delta.cfg for an example linear delta kinematics config file. See the delta calibrate guide for information on calibration. Only parameters specific to linear delta printers are described here - see common kinematic settings for available parameters. [printer] kinematics: delta max_z_velocity: # For delta printers this limits the maximum velocity (in mm/s) of # moves with z axis movement. This setting can be used to reduce the # maximum speed of up/down moves (which require a higher step rate # than other moves on a delta printer). The default is to use # max_velocity for max_z_velocity. #max_z_accel: # This sets the maximum acceleration (in mm/s^2) of movement along # the z axis. Setting this may be useful if the printer can reach higher # acceleration on XY moves than Z moves (eg, when using input shaper). # The default is to use max_accel for max_z_accel. #minimum_z_position: 0 # The minimum Z position that the user may command the head to move # to. The default is 0. delta_radius: # Radius (in mm) of the horizontal circle formed by the three linear # axis towers. This parameter may also be calculated as: # delta_radius = smooth_rod_offset - effector_offset - carriage_offset # This parameter must be provided. #print_radius: # The radius (in mm) of valid toolhead XY coordinates. One may use # this setting to customize the range checking of toolhead moves. If # a large value is specified here then it may be possible to command # the toolhead into a collision with a tower. The default is to use # delta_radius for print_radius (which would normally prevent a # tower collision). # The stepper_a section describes the stepper controlling the front # left tower (at 210 degrees). This section also controls the homing # parameters (homing_speed, homing_retract_dist) for all towers. [stepper_a] position_endstop: # Distance (in mm) between the nozzle and the bed when the nozzle is # in the center of the build area and the endstop triggers. This # parameter must be provided for stepper_a; for stepper_b and # stepper_c this parameter defaults to the value specified for # stepper_a. arm_length: # Length (in mm) of the diagonal rod that connects this tower to the # print head. This parameter must be provided for stepper_a; for # stepper_b and stepper_c this parameter defaults to the value # specified for stepper_a. #angle: # This option specifies the angle (in degrees) that the tower is # at. The default is 210 for stepper_a, 330 for stepper_b, and 90 # for stepper_c. # The stepper_b section describes the stepper controlling the front # right tower (at 330 degrees). [stepper_b] # The stepper_c section describes the stepper controlling the rear # tower (at 90 degrees). [stepper_c] # The delta_calibrate section enables a DELTA_CALIBRATE extended # g-code command that can calibrate the tower endstop positions and # angles. [delta_calibrate] radius: # Radius (in mm) of the area that may be probed. This is the radius # of nozzle coordinates to be probed; if using an automatic probe # with an XY offset then choose a radius small enough so that the # probe always fits over the bed. This parameter must be provided. #speed: 50 # The speed (in mm/s) of non-probing moves during the calibration. # The default is 50. #horizontal_move_z: 5 # The height (in mm) that the head should be commanded to move to # just prior to starting a probe operation. The default is 5.","title":"Linear Delta Kinematics"},{"location":"Config_Reference.html#deltesian-kinematics","text":"See example-deltesian.cfg for an example deltesian kinematics config file. Only parameters specific to deltesian printers are described here - see common kinematic settings for available parameters. [printer] kinematics: deltesian max_z_velocity: # For deltesian printers, this limits the maximum velocity (in mm/s) of # moves with z axis movement. This setting can be used to reduce the # maximum speed of up/down moves (which require a higher step rate # than other moves on a deltesian printer). The default is to use # max_velocity for max_z_velocity. #max_z_accel: # This sets the maximum acceleration (in mm/s^2) of movement along # the z axis. Setting this may be useful if the printer can reach higher # acceleration on XY moves than Z moves (eg, when using input shaper). # The default is to use max_accel for max_z_accel. #minimum_z_position: 0 # The minimum Z position that the user may command the head to move # to. The default is 0. #min_angle: 5 # This represents the minimum angle (in degrees) relative to horizontal # that the deltesian arms are allowed to achieve. This parameter is # intended to restrict the arms from becoming completely horizontal, # which would risk accidental inversion of the XZ axis. The default is 5. #print_width: # The distance (in mm) of valid toolhead X coordinates. One may use # this setting to customize the range checking of toolhead moves. If # a large value is specified here then it may be possible to command # the toolhead into a collision with a tower. This setting usually # corresponds to bed width (in mm). #slow_ratio: 3 # The ratio used to limit velocity and acceleration on moves near the # extremes of the X axis. If vertical distance divided by horizontal # distance exceeds the value of slow_ratio, then velocity and # acceleration are limited to half their nominal values. If vertical # distance divided by horizontal distance exceeds twice the value of # the slow_ratio, then velocity and acceleration are limited to one # quarter of their nominal values. The default is 3. # The stepper_left section is used to describe the stepper controlling # the left tower. This section also controls the homing parameters # (homing_speed, homing_retract_dist) for all towers. [stepper_left] position_endstop: # Distance (in mm) between the nozzle and the bed when the nozzle is # in the center of the build area and the endstops are triggered. This # parameter must be provided for stepper_left; for stepper_right this # parameter defaults to the value specified for stepper_left. arm_length: # Length (in mm) of the diagonal rod that connects the tower carriage to # the print head. This parameter must be provided for stepper_left; for # stepper_right, this parameter defaults to the value specified for # stepper_left. arm_x_length: # Horizontal distance between the print head and the tower when the # printers is homed. This parameter must be provided for stepper_left; # for stepper_right, this parameter defaults to the value specified for # stepper_left. # The stepper_right section is used to describe the stepper controlling the # right tower. [stepper_right] # The stepper_y section is used to describe the stepper controlling # the Y axis in a deltesian robot. [stepper_y]","title":"Deltesian Kinematics"},{"location":"Config_Reference.html#corexy-kinematics","text":"See example-corexy.cfg for an example corexy (and h-bot) kinematics file. Only parameters specific to corexy printers are described here - see common kinematic settings for available parameters. [printer] kinematics: corexy max_z_velocity: # This sets the maximum velocity (in mm/s) of movement along the z # axis. This setting can be used to restrict the maximum speed of # the z stepper motor. The default is to use max_velocity for # max_z_velocity. max_z_accel: # This sets the maximum acceleration (in mm/s^2) of movement along # the z axis. It limits the acceleration of the z stepper motor. The # default is to use max_accel for max_z_accel. # The stepper_x section is used to describe the X axis as well as the # stepper controlling the X+Y movement. [stepper_x] # The stepper_y section is used to describe the Y axis as well as the # stepper controlling the X-Y movement. [stepper_y] # The stepper_z section is used to describe the stepper controlling # the Z axis. [stepper_z]","title":"CoreXY Kinematics"},{"location":"Config_Reference.html#corexz-kinematics","text":"See example-corexz.cfg for an example corexz kinematics config file. Only parameters specific to corexz printers are described here - see common kinematic settings for available parameters. [printer] kinematics: corexz max_z_velocity: # This sets the maximum velocity (in mm/s) of movement along the z # axis. The default is to use max_velocity for max_z_velocity. max_z_accel: # This sets the maximum acceleration (in mm/s^2) of movement along # the z axis. The default is to use max_accel for max_z_accel. # The stepper_x section is used to describe the X axis as well as the # stepper controlling the X+Z movement. [stepper_x] # The stepper_y section is used to describe the stepper controlling # the Y axis. [stepper_y] # The stepper_z section is used to describe the Z axis as well as the # stepper controlling the X-Z movement. [stepper_z]","title":"CoreXZ Kinematics"},{"location":"Config_Reference.html#hybrid-corexy-kinematics","text":"See example-hybrid-corexy.cfg for an example hybrid corexy kinematics config file. This kinematic is also known as Markforged kinematic. Only parameters specific to hybrid corexy printers are described here see common kinematic settings for available parameters. [printer] kinematics: hybrid_corexy max_z_velocity: # This sets the maximum velocity (in mm/s) of movement along the z # axis. The default is to use max_velocity for max_z_velocity. max_z_accel: # This sets the maximum acceleration (in mm/s^2) of movement along # the z axis. The default is to use max_accel for max_z_accel. # The stepper_x section is used to describe the X axis as well as the # stepper controlling the X-Y movement. [stepper_x] # The stepper_y section is used to describe the stepper controlling # the Y axis. [stepper_y] # The stepper_z section is used to describe the stepper controlling # the Z axis. [stepper_z]","title":"Hybrid-CoreXY Kinematics"},{"location":"Config_Reference.html#hybrid-corexz-kinematics","text":"See example-hybrid-corexz.cfg for an example hybrid corexz kinematics config file. This kinematic is also known as Markforged kinematic. Only parameters specific to hybrid corexy printers are described here see common kinematic settings for available parameters. [printer] kinematics: hybrid_corexz max_z_velocity: # This sets the maximum velocity (in mm/s) of movement along the z # axis. The default is to use max_velocity for max_z_velocity. max_z_accel: # This sets the maximum acceleration (in mm/s^2) of movement along # the z axis. The default is to use max_accel for max_z_accel. # The stepper_x section is used to describe the X axis as well as the # stepper controlling the X-Z movement. [stepper_x] # The stepper_y section is used to describe the stepper controlling # the Y axis. [stepper_y] # The stepper_z section is used to describe the stepper controlling # the Z axis. [stepper_z]","title":"Hybrid-CoreXZ Kinematics"},{"location":"Config_Reference.html#polar-kinematics","text":"See example-polar.cfg for an example polar kinematics config file. Only parameters specific to polar printers are described here - see common kinematic settings for available parameters. POLAR KINEMATICS ARE A WORK IN PROGRESS. Moves around the 0, 0 position are known to not work properly. [printer] kinematics: polar max_z_velocity: # This sets the maximum velocity (in mm/s) of movement along the z # axis. This setting can be used to restrict the maximum speed of # the z stepper motor. The default is to use max_velocity for # max_z_velocity. max_z_accel: # This sets the maximum acceleration (in mm/s^2) of movement along # the z axis. It limits the acceleration of the z stepper motor. The # default is to use max_accel for max_z_accel. # The stepper_bed section is used to describe the stepper controlling # the bed. [stepper_bed] gear_ratio: # A gear_ratio must be specified and rotation_distance may not be # specified. For example, if the bed has an 80 toothed pulley driven # by a stepper with a 16 toothed pulley then one would specify a # gear ratio of \"80:16\". This parameter must be provided. # The stepper_arm section is used to describe the stepper controlling # the carriage on the arm. [stepper_arm] # The stepper_z section is used to describe the stepper controlling # the Z axis. [stepper_z]","title":"Polar Kinematics"},{"location":"Config_Reference.html#rotary-delta-kinematics","text":"See example-rotary-delta.cfg for an example rotary delta kinematics config file. Only parameters specific to rotary delta printers are described here - see common kinematic settings for available parameters. ROTARY DELTA KINEMATICS ARE A WORK IN PROGRESS. Homing moves may timeout and some boundary checks are not implemented. [printer] kinematics: rotary_delta max_z_velocity: # For delta printers this limits the maximum velocity (in mm/s) of # moves with z axis movement. This setting can be used to reduce the # maximum speed of up/down moves (which require a higher step rate # than other moves on a delta printer). The default is to use # max_velocity for max_z_velocity. #minimum_z_position: 0 # The minimum Z position that the user may command the head to move # to. The default is 0. shoulder_radius: # Radius (in mm) of the horizontal circle formed by the three # shoulder joints, minus the radius of the circle formed by the # effector joints. This parameter may also be calculated as: # shoulder_radius = (delta_f - delta_e) / sqrt(12) # This parameter must be provided. shoulder_height: # Distance (in mm) of the shoulder joints from the bed, minus the # effector toolhead height. This parameter must be provided. # The stepper_a section describes the stepper controlling the rear # right arm (at 30 degrees). This section also controls the homing # parameters (homing_speed, homing_retract_dist) for all arms. [stepper_a] gear_ratio: # A gear_ratio must be specified and rotation_distance may not be # specified. For example, if the arm has an 80 toothed pulley driven # by a pulley with 16 teeth, which is in turn connected to a 60 # toothed pulley driven by a stepper with a 16 toothed pulley, then # one would specify a gear ratio of \"80:16, 60:16\". This parameter # must be provided. position_endstop: # Distance (in mm) between the nozzle and the bed when the nozzle is # in the center of the build area and the endstop triggers. This # parameter must be provided for stepper_a; for stepper_b and # stepper_c this parameter defaults to the value specified for # stepper_a. upper_arm_length: # Length (in mm) of the arm connecting the \"shoulder joint\" to the # \"elbow joint\". This parameter must be provided for stepper_a; for # stepper_b and stepper_c this parameter defaults to the value # specified for stepper_a. lower_arm_length: # Length (in mm) of the arm connecting the \"elbow joint\" to the # \"effector joint\". This parameter must be provided for stepper_a; # for stepper_b and stepper_c this parameter defaults to the value # specified for stepper_a. #angle: # This option specifies the angle (in degrees) that the arm is at. # The default is 30 for stepper_a, 150 for stepper_b, and 270 for # stepper_c. # The stepper_b section describes the stepper controlling the rear # left arm (at 150 degrees). [stepper_b] # The stepper_c section describes the stepper controlling the front # arm (at 270 degrees). [stepper_c] # The delta_calibrate section enables a DELTA_CALIBRATE extended # g-code command that can calibrate the shoulder endstop positions. [delta_calibrate] radius: # Radius (in mm) of the area that may be probed. This is the radius # of nozzle coordinates to be probed; if using an automatic probe # with an XY offset then choose a radius small enough so that the # probe always fits over the bed. This parameter must be provided. #speed: 50 # The speed (in mm/s) of non-probing moves during the calibration. # The default is 50. #horizontal_move_z: 5 # The height (in mm) that the head should be commanded to move to # just prior to starting a probe operation. The default is 5.","title":"Rotary delta Kinematics"},{"location":"Config_Reference.html#cable-winch-kinematics","text":"See the example-winch.cfg for an example cable winch kinematics config file. Only parameters specific to cable winch printers are described here - see common kinematic settings for available parameters. CABLE WINCH SUPPORT IS EXPERIMENTAL. Homing is not implemented on cable winch kinematics. In order to home the printer, manually send movement commands until the toolhead is at 0, 0, 0 and then issue a G28 command. [printer] kinematics: winch # The stepper_a section describes the stepper connected to the first # cable winch. A minimum of 3 and a maximum of 26 cable winches may be # defined (stepper_a to stepper_z) though it is common to define 4. [stepper_a] rotation_distance: # The rotation_distance is the nominal distance (in mm) the toolhead # moves towards the cable winch for each full rotation of the # stepper motor. This parameter must be provided. anchor_x: anchor_y: anchor_z: # The X, Y, and Z position of the cable winch in cartesian space. # These parameters must be provided.","title":"Cable winch Kinematics"},{"location":"Config_Reference.html#generic-cartesian-kinematics","text":"See example-generic-cartesian.cfg for an example generic Cartesian kinematics config file. This printer kinematic class allows a user to define in a pretty flexible manner an arbitrary Cartesian-style kinematics. In principle, the regular cartesian, corexy, hybrid_corexy can be defined this way too. However, more importantly, various otherwise unsupported kinematics such as inverted hybrid_corexy or corexyuv can be defined using this kinematic. Notably, the definition of a generic Cartesian kinematic deviates significantly from the other kinematic types. It follows the following convention: a user defines a set of carriages with certain range of motion that can move independently from each other (they should move over the Cartesian axes X, Y, and Z, hence the name of the kinematic) and corresponding endstops that allow the firmware to determine the position of carriages during homing, as well as a set of steppers that move those carriages. The [printer] section must specify the kinematic and other printer-level settings same as the regular Cartesian kinematic: [printer] kinematics: generic_cartesian max_velocity: max_accel: #minimum_cruise_ratio: #square_corner_velocity: #max_z_velocity: #max_z_accel: Then a user must define three carriages for X, Y, and Z axes, e.g.: [carriage carriage_x] axis: # Axis of a carriage, either x, y, or z. This parameter must be provided, # unless a carriage name is x, y, or z itself. endstop_pin: # Endstop switch detection pin. If this endstop pin is on a # different mcu than the stepper motor(s) moving this carriage, # then it enables \"multi-mcu homing\". This parameter must be provided. #position_min: 0 # Minimum valid distance (in mm) the user may command the carriage to # move to. The default is 0mm. position_endstop: # Location of the endstop (in mm). This parameter must be provided. position_max: # Maximum valid distance (in mm) the user may command the stepper to # move to. This parameter must be provided. #homing_speed: 5.0 # Maximum velocity (in mm/s) of the carriage when homing. The default # is 5mm/s. #homing_retract_dist: 5.0 # Distance to backoff (in mm) before homing a second time during # homing. Set this to zero to disable the second home. The default # is 5mm. #homing_retract_speed: # Speed to use on the retract move after homing in case this should # be different from the homing speed, which is the default for this # parameter #second_homing_speed: # Velocity (in mm/s) of the carriage when performing the second home. # The default is homing_speed/2. #homing_positive_dir: # If true, homing will cause the carriage to move in a positive # direction (away from zero); if false, home towards zero. It is # better to use the default than to specify this parameter. The # default is true if position_endstop is near position_max and false # if near position_min. Afterwards, a user specifies the stepper motors that move these carriages, for instance [stepper my_stepper] carriages: # A string describing the carriages the stepper moves. All defined # carriages can be specified here, as well as their linear combinations, # e.g. carriage_x, carriage_x+carriage_y, carriage_y-0.5*carriage_z, # carriage_x-carriage_z, etc. This parameter must be provided. step_pin: dir_pin: enable_pin: rotation_distance: microsteps: #full_steps_per_rotation: 200 #gear_ratio: #step_pulse_duration: See stepper section for more information on the regular stepper parameters. The carriages parameter defines how the stepper affects the motion of the carriages. For example, carriage_x+carriage_y indicates that the motion of the stepper in the positive direction by the distance d moves the carriages carriage_x and carriage_y by the same distance d in the positive direction, while carriage_x-0.5*carriage_y means the motion of the stepper in the positive direction by the distance d moves the carriage carriage_x by the distance d in the positive direction, but the carriage carriage_y will travel distance d/2 in the negative direction. More than a single stepper motor can be defined to drive the same axis or belt. For example, on a CoreXY AWD setups two motors driving the same belt can be defined as [carriage carriage_x] endstop_pin: ... ... [carriage carriage_y] endstop_pin: ... ... [stepper a0] carriages: carriage_x-carriage_y step_pin: ... dir_pin: ... enable_pin: ... rotation_distance: ... ... [stepper a1] carriages: carriage_x-carriage_y step_pin: ... dir_pin: ... enable_pin: ... rotation_distance: ... ... with a0 and a1 steppers having their own control pins, but sharing the same carriages and corresponding endstops. There are situations when a user wants to have more than one endstop per axis. Examples of such configurations include Y axis driven by two independent stepper motors with belts attached to both ends of the X gantry, with effectively two carriages on Y axis each having an independent endstop, and multi-stepper Z axis with each stepper having its own endstop (not to be confused with the configurations with multiple Z motors but only a single endstop). These configurations can be declared by specifying additional carriage(s) with their endstops: [extra_carriage my_carriage] primary_carriage: # The name of the primary carriage this carriage corresponds to. # It also effectively defines the axis the carriage moves over. # This parameter must be provided. endstop_pin: # Endstop switch detection pin. This parameter must be provided. and the corresponding stepper motors, for example: [extra_carriage carriage_y1] primary_carriage: carriage_y endstop_pin: ... [stepper sy1] carriages: carriage_y1 ... Notably, an [extra_carriage] does not define parameters such as position_min , position_max , and position_endstop , but instead inherits them from the specified primary_carriage , thus sharing the same range of motion with the primary carriage. For the references on how to configure IDEX setups, see the dual carriage section.","title":"Generic Cartesian Kinematics"},{"location":"Config_Reference.html#none-kinematics","text":"It is possible to define a special \"none\" kinematics to disable kinematic support in Klipper. This may be useful for controlling devices that are not typical 3d-printers or for debugging purposes. [printer] kinematics: none max_velocity: 1 max_accel: 1 # The max_velocity and max_accel parameters must be defined. The # values are not used for \"none\" kinematics.","title":"None Kinematics"},{"location":"Config_Reference.html#common-extruder-and-heated-bed-support","text":"","title":"Common extruder and heated bed support"},{"location":"Config_Reference.html#extruder","text":"The extruder section is used to describe the heater parameters for the nozzle hotend along with the stepper controlling the extruder. See the command reference for additional information. See the pressure advance guide for information on tuning pressure advance. [extruder] step_pin: dir_pin: enable_pin: microsteps: rotation_distance: #full_steps_per_rotation: #gear_ratio: # See the \"stepper\" section for a description of the above # parameters. If none of the above parameters are specified then no # stepper will be associated with the nozzle hotend (though a # SYNC_EXTRUDER_MOTION command may associate one at run-time). nozzle_diameter: # Diameter of the nozzle orifice (in mm). This parameter must be # provided. filament_diameter: # The nominal diameter of the raw filament (in mm) as it enters the # extruder. This parameter must be provided. #max_extrude_cross_section: # Maximum area (in mm^2) of an extrusion cross section (eg, # extrusion width multiplied by layer height). This setting prevents # excessive amounts of extrusion during relatively small XY moves. # If a move requests an extrusion rate that would exceed this value # it will cause an error to be returned. The default is: 4.0 * # nozzle_diameter^2 #instantaneous_corner_velocity: 1.000 # The maximum instantaneous velocity change (in mm/s) of the # extruder during the junction of two moves. The default is 1mm/s. #max_extrude_only_distance: 50.0 # Maximum length (in mm of raw filament) that a retraction or # extrude-only move may have. If a retraction or extrude-only move # requests a distance greater than this value it will cause an error # to be returned. The default is 50mm. #max_extrude_only_velocity: #max_extrude_only_accel: # Maximum velocity (in mm/s) and acceleration (in mm/s^2) of the # extruder motor for retractions and extrude-only moves. These # settings do not have any impact on normal printing moves. If not # specified then they are calculated to match the limit an XY # printing move with a cross section of 4.0*nozzle_diameter^2 would # have. #pressure_advance: 0.0 # The amount of raw filament to push into the extruder during # extruder acceleration. An equal amount of filament is retracted # during deceleration. It is measured in millimeters per # millimeter/second. The default is 0, which disables pressure # advance. #pressure_advance_smooth_time: 0.040 # A time range (in seconds) to use when calculating the average # extruder velocity for pressure advance. A larger value results in # smoother extruder movements. This parameter may not exceed 200ms. # This setting only applies if pressure_advance is non-zero. The # default is 0.040 (40 milliseconds). # # The remaining variables describe the extruder heater. heater_pin: # PWM output pin controlling the heater. This parameter must be # provided. #max_power: 1.0 # The maximum power (expressed as a value from 0.0 to 1.0) that the # heater_pin may be set to. The value 1.0 allows the pin to be set # fully enabled for extended periods, while a value of 0.5 would # allow the pin to be enabled for no more than half the time. This # setting may be used to limit the total power output (over extended # periods) to the heater. The default is 1.0. sensor_type: # Type of sensor - common thermistors are \"EPCOS 100K B57560G104F\", # \"ATC Semitec 104GT-2\", \"ATC Semitec 104NT-4-R025H42G\", \"Generic # 3950\",\"Honeywell 100K 135-104LAG-J01\", \"NTC 100K MGB18-104F39050L32\", # \"SliceEngineering 450\", and \"TDK NTCG104LH104JT1\". See the # \"Temperature sensors\" section for other sensors. This parameter # must be provided. sensor_pin: # Analog input pin connected to the sensor. This parameter must be # provided. #pullup_resistor: 4700 # The resistance (in ohms) of the pullup attached to the thermistor. # This parameter is only valid when the sensor is a thermistor. The # default is 4700 ohms. #smooth_time: 1.0 # A time value (in seconds) over which temperature measurements will # be smoothed to reduce the impact of measurement noise. The default # is 1 seconds. control: # Control algorithm (either pid or watermark). This parameter must # be provided. pid_Kp: pid_Ki: pid_Kd: # The proportional (pid_Kp), integral (pid_Ki), and derivative # (pid_Kd) settings for the PID feedback control system. Klipper # evaluates the PID settings with the following general formula: # heater_pwm = (Kp*error + Ki*integral(error) - Kd*derivative(error)) / 255 # Where \"error\" is \"requested_temperature - measured_temperature\" # and \"heater_pwm\" is the requested heating rate with 0.0 being full # off and 1.0 being full on. Consider using the PID_CALIBRATE # command to obtain these parameters. The pid_Kp, pid_Ki, and pid_Kd # parameters must be provided for PID heaters. #max_delta: 2.0 # On 'watermark' controlled heaters this is the number of degrees in # Celsius above the target temperature before disabling the heater # as well as the number of degrees below the target before # re-enabling the heater. The default is 2 degrees Celsius. #pwm_cycle_time: 0.100 # Time in seconds for each software PWM cycle of the heater. It is # not recommended to set this unless there is an electrical # requirement to switch the heater faster than 10 times a second. # The default is 0.100 seconds. #min_extrude_temp: 170 # The minimum temperature (in Celsius) at which extruder move # commands may be issued. The default is 170 Celsius. min_temp: max_temp: # The maximum range of valid temperatures (in Celsius) that the # heater must remain within. This controls a safety feature # implemented in the micro-controller code - should the measured # temperature ever fall outside this range then the micro-controller # will go into a shutdown state. This check can help detect some # heater and sensor hardware failures. Set this range just wide # enough so that reasonable temperatures do not result in an error. # These parameters must be provided.","title":"[extruder]"},{"location":"Config_Reference.html#heater_bed","text":"The heater_bed section describes a heated bed. It uses the same heater settings described in the \"extruder\" section. [heater_bed] heater_pin: sensor_type: sensor_pin: control: min_temp: max_temp: # See the \"extruder\" section for a description of the above parameters.","title":"[heater_bed]"},{"location":"Config_Reference.html#bed-level-support","text":"","title":"Bed level support"},{"location":"Config_Reference.html#bed_mesh","text":"Mesh Bed Leveling. One may define a bed_mesh config section to enable move transformations that offset the z axis based on a mesh generated from probed points. When using a probe to home the z-axis, it is recommended to define a safe_z_home section in printer.cfg to home toward the center of the print area. See the bed mesh guide and command reference for additional information. Visual Examples: rectangular bed, probe_count = 3, 3: x---x---x (max_point) | x---x---x | (min_point) x---x---x round bed, round_probe_count = 5, bed_radius = r: x (0, r) end / x---x---x \\ (-r, 0) x---x---x---x---x (r, 0) \\ x---x---x / x (0, -r) start [bed_mesh] #speed: 50 # The speed (in mm/s) of non-probing moves during the calibration. # The default is 50. #horizontal_move_z: 5 # The height (in mm) that the head should be commanded to move to # just prior to starting a probe operation. The default is 5. #mesh_radius: # Defines the radius of the mesh to probe for round beds. Note that # the radius is relative to the coordinate specified by the # mesh_origin option. This parameter must be provided for round beds # and omitted for rectangular beds. #mesh_origin: # Defines the center X, Y coordinate of the mesh for round beds. This # coordinate is relative to the probe's location. It may be useful # to adjust the mesh_origin in an effort to maximize the size of the # mesh radius. Default is 0, 0. This parameter must be omitted for # rectangular beds. #mesh_min: # Defines the minimum X, Y coordinate of the mesh for rectangular # beds. This coordinate is relative to the probe's location. This # will be the first point probed, nearest to the origin. This # parameter must be provided for rectangular beds. #mesh_max: # Defines the maximum X, Y coordinate of the mesh for rectangular # beds. Adheres to the same principle as mesh_min, however this will # be the furthest point probed from the bed's origin. This parameter # must be provided for rectangular beds. #probe_count: 3, 3 # For rectangular beds, this is a comma separate pair of integer # values X, Y defining the number of points to probe along each # axis. A single value is also valid, in which case that value will # be applied to both axes. Default is 3, 3. #round_probe_count: 5 # For round beds, this integer value defines the maximum number of # points to probe along each axis. This value must be an odd number. # Default is 5. #fade_start: 1.0 # The gcode z position in which to start phasing out z-adjustment # when fade is enabled. Default is 1.0. #fade_end: 0.0 # The gcode z position in which phasing out completes. When set to a # value below fade_start, fade is disabled. It should be noted that # fade may add unwanted scaling along the z-axis of a print. If a # user wishes to enable fade, a value of 10.0 is recommended. # Default is 0.0, which disables fade. #fade_target: # The z position in which fade should converge. When this value is # set to a non-zero value it must be within the range of z-values in # the mesh. Users that wish to converge to the z homing position # should set this to 0. Default is the average z value of the mesh. #split_delta_z: .025 # The amount of Z difference (in mm) along a move that will trigger # a split. Default is .025. #move_check_distance: 5.0 # The distance (in mm) along a move to check for split_delta_z. # This is also the minimum length that a move can be split. Default # is 5.0. #mesh_pps: 2, 2 # A comma separated pair of integers X, Y defining the number of # points per segment to interpolate in the mesh along each axis. A # \"segment\" can be defined as the space between each probed point. # The user may enter a single value which will be applied to both # axes. Default is 2, 2. #algorithm: lagrange # The interpolation algorithm to use. May be either \"lagrange\" or # \"bicubic\". This option will not affect 3x3 grids, which are forced # to use lagrange sampling. Default is lagrange. #bicubic_tension: .2 # When using the bicubic algorithm the tension parameter above may # be applied to change the amount of slope interpolated. Larger # numbers will increase the amount of slope, which results in more # curvature in the mesh. Default is .2. #zero_reference_position: # An optional X,Y coordinate that specifies the location on the bed # where Z = 0. When this option is specified the mesh will be offset # so that zero Z adjustment occurs at this location. The default is # no zero reference. #faulty_region_1_min: #faulty_region_1_max: # Optional points that define a faulty region. See docs/Bed_Mesh.md # for details on faulty regions. Up to 99 faulty regions may be added. # By default no faulty regions are set. #adaptive_margin: # An optional margin (in mm) to be added around the bed area used by # the defined print objects when generating an adaptive mesh. #scan_overshoot: # The maximum amount of travel (in mm) available outside of the mesh. # For rectangular beds this applies to travel on the X axis, and for round beds # it applies to the entire radius. The tool must be able to travel the amount # specified outside of the mesh. This value is used to optimize the travel # path when performing a \"rapid scan\". The minimum value that may be specified # is 1. The default is no overshoot.","title":"[bed_mesh]"},{"location":"Config_Reference.html#bed_tilt","text":"Bed tilt compensation. One may define a bed_tilt config section to enable move transformations that account for a tilted bed. Note that bed_mesh and bed_tilt are incompatible; both cannot be defined. See the command reference for additional information. [bed_tilt] #x_adjust: 0 # The amount to add to each move's Z height for each mm on the X # axis. The default is 0. #y_adjust: 0 # The amount to add to each move's Z height for each mm on the Y # axis. The default is 0. #z_adjust: 0 # The amount to add to the Z height when the nozzle is nominally at # 0, 0. The default is 0. # The remaining parameters control a BED_TILT_CALIBRATE extended # g-code command that may be used to calibrate appropriate x and y # adjustment parameters. #points: # A list of X, Y coordinates (one per line; subsequent lines # indented) that should be probed during a BED_TILT_CALIBRATE # command. Specify coordinates of the nozzle and be sure the probe # is above the bed at the given nozzle coordinates. The default is # to not enable the command. #speed: 50 # The speed (in mm/s) of non-probing moves during the calibration. # The default is 50. #horizontal_move_z: 5 # The height (in mm) that the head should be commanded to move to # just prior to starting a probe operation. The default is 5.","title":"[bed_tilt]"},{"location":"Config_Reference.html#bed_screws","text":"Tool to help adjust bed leveling screws. One may define a [bed_screws] config section to enable a BED_SCREWS_ADJUST g-code command. See the leveling guide and command reference for additional information. [bed_screws] #screw1: # The X, Y coordinate of the first bed leveling screw. This is a # position to command the nozzle to that is directly above the bed # screw (or as close as possible while still being above the bed). # This parameter must be provided. #screw1_name: # An arbitrary name for the given screw. This name is displayed when # the helper script runs. The default is to use a name based upon # the screw XY location. #screw1_fine_adjust: # An X, Y coordinate to command the nozzle to so that one can fine # tune the bed leveling screw. The default is to not perform fine # adjustments on the bed screw. #screw2: #screw2_name: #screw2_fine_adjust: #... # Additional bed leveling screws. At least three screws must be # defined. #horizontal_move_z: 5 # The height (in mm) that the head should be commanded to move to # when moving from one screw location to the next. The default is 5. #probe_height: 0 # The height of the probe (in mm) after adjusting for the thermal # expansion of bed and nozzle. The default is zero. #speed: 50 # The speed (in mm/s) of non-probing moves during the calibration. # The default is 50. #probe_speed: 5 # The speed (in mm/s) when moving from a horizontal_move_z position # to a probe_height position. The default is 5.","title":"[bed_screws]"},{"location":"Config_Reference.html#screws_tilt_adjust","text":"Tool to help adjust bed screws tilt using Z probe. One may define a screws_tilt_adjust config section to enable a SCREWS_TILT_CALCULATE g-code command. See the leveling guide and command reference for additional information. [screws_tilt_adjust] #screw1: # The (X, Y) coordinate of the first bed leveling screw. This is a # position to command the nozzle to so that the probe is directly # above the bed screw (or as close as possible while still being # above the bed). This is the base screw used in calculations. This # parameter must be provided. #screw1_name: # An arbitrary name for the given screw. This name is displayed when # the helper script runs. The default is to use a name based upon # the screw XY location. #screw2: #screw2_name: #... # Additional bed leveling screws. At least two screws must be # defined. #speed: 50 # The speed (in mm/s) of non-probing moves during the calibration. # The default is 50. #horizontal_move_z: 5 # The height (in mm) that the head should be commanded to move to # just prior to starting a probe operation. The default is 5. #screw_thread: CW-M3 # The type of screw used for bed leveling, M3, M4, or M5, and the # rotation direction of the knob that is used to level the bed. # Accepted values: CW-M3, CCW-M3, CW-M4, CCW-M4, CW-M5, CCW-M5. # Default value is CW-M3 which most printers use. A clockwise # rotation of the knob decreases the gap between the nozzle and the # bed. Conversely, a counter-clockwise rotation increases the gap.","title":"[screws_tilt_adjust]"},{"location":"Config_Reference.html#z_tilt","text":"Multiple Z stepper tilt adjustment. This feature enables independent adjustment of multiple z steppers (see the \"stepper_z1\" section) to adjust for tilt. If this section is present then a Z_TILT_ADJUST extended G-Code command becomes available. [z_tilt] #z_positions: # A list of X, Y coordinates (one per line; subsequent lines # indented) describing the location of each bed \"pivot point\". The # \"pivot point\" is the point where the bed attaches to the given Z # stepper. It is described using nozzle coordinates (the X, Y position # of the nozzle if it could move directly above the point). The # first entry corresponds to stepper_z, the second to stepper_z1, # the third to stepper_z2, etc. This parameter must be provided. #points: # A list of X, Y coordinates (one per line; subsequent lines # indented) that should be probed during a Z_TILT_ADJUST command. # Specify coordinates of the nozzle and be sure the probe is above # the bed at the given nozzle coordinates. This parameter must be # provided. #speed: 50 # The speed (in mm/s) of non-probing moves during the calibration. # The default is 50. #horizontal_move_z: 5 # The height (in mm) that the head should be commanded to move to # just prior to starting a probe operation. The default is 5. #retries: 0 # Number of times to retry if the probed points aren't within # tolerance. #retry_tolerance: 0 # If retries are enabled then retry if largest and smallest probed # points differ more than retry_tolerance. Note the smallest unit of # change here would be a single step. However if you are probing # more points than steppers then you will likely have a fixed # minimum value for the range of probed points which you can learn # by observing command output.","title":"[z_tilt]"},{"location":"Config_Reference.html#quad_gantry_level","text":"Moving gantry leveling using 4 independently controlled Z motors. Corrects hyperbolic parabola effects (potato chip) on moving gantry which is more flexible. WARNING: Using this on a moving bed may lead to undesirable results. If this section is present then a QUAD_GANTRY_LEVEL extended G-Code command becomes available. This routine assumes the following Z motor configuration: ---------------- |Z1 Z2| | --------- | | | | | | | | | | x-------- | |Z Z3| ---------------- Where x is the 0, 0 point on the bed [quad_gantry_level] #gantry_corners: # A newline separated list of X, Y coordinates describing the two # opposing corners of the gantry. The first entry corresponds to Z, # the second to Z2. This parameter must be provided. #points: # A newline separated list of four X, Y points that should be probed # during a QUAD_GANTRY_LEVEL command. Order of the locations is # important, and should correspond to Z, Z1, Z2, and Z3 location in # order. This parameter must be provided. For maximum accuracy, # ensure your probe offsets are configured. #speed: 50 # The speed (in mm/s) of non-probing moves during the calibration. # The default is 50. #horizontal_move_z: 5 # The height (in mm) that the head should be commanded to move to # just prior to starting a probe operation. The default is 5. #max_adjust: 4 # Safety limit if an adjustment greater than this value is requested # quad_gantry_level will abort. #retries: 0 # Number of times to retry if the probed points aren't within # tolerance. #retry_tolerance: 0 # If retries are enabled then retry if largest and smallest probed # points differ more than retry_tolerance.","title":"[quad_gantry_level]"},{"location":"Config_Reference.html#skew_correction","text":"Printer Skew Correction. It is possible to use software to correct printer skew across 3 planes, xy, xz, yz. This is done by printing a calibration model along a plane and measuring three lengths. Due to the nature of skew correction these lengths are set via gcode. See Skew Correction and Command Reference for details. [skew_correction]","title":"[skew_correction]"},{"location":"Config_Reference.html#z_thermal_adjust","text":"Temperature-dependant toolhead Z position adjustment. Compensate for vertical toolhead movement caused by thermal expansion of the printer's frame in real-time using a temperature sensor (typically coupled to a vertical section of frame). See also: extended g-code commands . [z_thermal_adjust] #temp_coeff: # The temperature coefficient of expansion, in mm/degC. For example, a # temp_coeff of 0.01 mm/degC will move the Z axis downwards by 0.01 mm for # every degree Celsius that the temperature sensor increases. Defaults to # 0.0 mm/degC, which applies no adjustment. #smooth_time: # Smoothing window applied to the temperature sensor, in seconds. Can reduce # motor noise from excessive small corrections in response to sensor noise. # The default is 2.0 seconds. #z_adjust_off_above: # Disables adjustments above this Z height [mm]. The last computed correction # will remain applied until the toolhead moves below the specified Z height # again. The default is 99999999.0 mm (always on). #max_z_adjustment: # Maximum absolute adjustment that can be applied to the Z axis [mm]. The # default is 99999999.0 mm (unlimited). #sensor_type: #sensor_pin: #min_temp: #max_temp: # Temperature sensor configuration. # See the \"extruder\" section for the definition of the above # parameters. #gcode_id: # See the \"heater_generic\" section for the definition of this # parameter.","title":"[z_thermal_adjust]"},{"location":"Config_Reference.html#customized-homing","text":"","title":"Customized homing"},{"location":"Config_Reference.html#safe_z_home","text":"Safe Z homing. One may use this mechanism to home the Z axis at a specific X, Y coordinate. This is useful if the toolhead, for example has to move to the center of the bed before Z can be homed. [safe_z_home] home_xy_position: # A X, Y coordinate (e.g. 100, 100) where the Z homing should be # performed. This parameter must be provided. #speed: 50.0 # Speed at which the toolhead is moved to the safe Z home # coordinate. The default is 50 mm/s #z_hop: # Distance (in mm) to lift the Z axis prior to homing. This is # applied to any homing command, even if it doesn't home the Z axis. # If the Z axis is already homed and the current Z position is less # than z_hop, then this will lift the head to a height of z_hop. If # the Z axis is not already homed the head is lifted by z_hop. # The default is to not implement Z hop. #z_hop_speed: 15.0 # Speed (in mm/s) at which the Z axis is lifted prior to homing. The # default is 15 mm/s. #move_to_previous: False # When set to True, the X and Y axes are reset to their previous # positions after Z axis homing. The default is False.","title":"[safe_z_home]"},{"location":"Config_Reference.html#homing_override","text":"Homing override. One may use this mechanism to run a series of g-code commands in place of a G28 found in the normal g-code input. This may be useful on printers that require a specific procedure to home the machine. [homing_override] gcode: # A list of G-Code commands to execute in place of G28 commands # found in the normal g-code input. See docs/Command_Templates.md # for G-Code format. If a G28 is contained in this list of commands # then it will invoke the normal homing procedure for the printer. # The commands listed here must home all axes. This parameter must # be provided. #axes: xyz # The axes to override. For example, if this is set to \"z\" then the # override script will only be run when the z axis is homed (eg, via # a \"G28\" or \"G28 Z0\" command). Note, the override script should # still home all axes. The default is \"xyz\" which causes the # override script to be run in place of all G28 commands. #set_position_x: #set_position_y: #set_position_z: # If specified, the printer will assume the axis is at the specified # position prior to running the above g-code commands. Setting this # disables homing checks for that axis. This may be useful if the # head must move prior to invoking the normal G28 mechanism for an # axis. The default is to not force a position for an axis.","title":"[homing_override]"},{"location":"Config_Reference.html#endstop_phase","text":"Stepper phase adjusted endstops. To use this feature, define a config section with an \"endstop_phase\" prefix followed by the name of the corresponding stepper config section (for example, \"[endstop_phase stepper_z]\"). This feature can improve the accuracy of endstop switches. Add a bare \"[endstop_phase]\" declaration to enable the ENDSTOP_PHASE_CALIBRATE command. See the endstop phases guide and command reference for additional information. [endstop_phase stepper_z] #endstop_accuracy: # Sets the expected accuracy (in mm) of the endstop. This represents # the maximum error distance the endstop may trigger (eg, if an # endstop may occasionally trigger 100um early or up to 100um late # then set this to 0.200 for 200um). The default is # 4*rotation_distance/full_steps_per_rotation. #trigger_phase: # This specifies the phase of the stepper motor driver to expect # when hitting the endstop. It is composed of two numbers separated # by a forward slash character - the phase and the total number of # phases (eg, \"7/64\"). Only set this value if one is sure the # stepper motor driver is reset every time the mcu is reset. If this # is not set, then the stepper phase will be detected on the first # home and that phase will be used on all subsequent homes. #endstop_align_zero: False # If true then the position_endstop of the axis will effectively be # modified so that the zero position for the axis occurs at a full # step on the stepper motor. (If used on the Z axis and the print # layer height is a multiple of a full step distance then every # layer will occur on a full step.) The default is False.","title":"[endstop_phase]"},{"location":"Config_Reference.html#g-code-macros-and-events","text":"","title":"G-Code macros and events"},{"location":"Config_Reference.html#gcode_macro","text":"G-Code macros (one may define any number of sections with a \"gcode_macro\" prefix). See the command template guide for more information. [gcode_macro my_cmd] #gcode: # A list of G-Code commands to execute in place of \"my_cmd\". See # docs/Command_Templates.md for G-Code format. This parameter must # be provided. #variable_: # One may specify any number of options with a \"variable_\" prefix. # The given variable name will be assigned the given value (parsed # as a Python literal) and will be available during macro expansion. # For example, a config with \"variable_fan_speed = 75\" might have # gcode commands containing \"M106 S{ fan_speed * 255 }\". Variables # can be changed at run-time using the SET_GCODE_VARIABLE command # (see docs/Command_Templates.md for details). Variable names may # not use upper case characters. #rename_existing: # This option will cause the macro to override an existing G-Code # command and provide the previous definition of the command via the # name provided here. This can be used to override builtin G-Code # commands. Care should be taken when overriding commands as it can # cause complex and unexpected results. The default is to not # override an existing G-Code command. #description: G-Code macro # This will add a short description used at the HELP command or while # using the auto completion feature. Default \"G-Code macro\"","title":"[gcode_macro]"},{"location":"Config_Reference.html#delayed_gcode","text":"Execute a gcode on a set delay. See the command template guide and command reference for more information. [delayed_gcode my_delayed_gcode] gcode: # A list of G-Code commands to execute when the delay duration has # elapsed. G-Code templates are supported. This parameter must be # provided. #initial_duration: 0.0 # The duration of the initial delay (in seconds). If set to a # non-zero value the delayed_gcode will execute the specified number # of seconds after the printer enters the \"ready\" state. This can be # useful for initialization procedures or a repeating delayed_gcode. # If set to 0 the delayed_gcode will not execute on startup. # Default is 0.","title":"[delayed_gcode]"},{"location":"Config_Reference.html#save_variables","text":"Support saving variables to disk so that they are retained across restarts. See command templates and G-Code reference for further information. [save_variables] filename: # Required - provide a filename that would be used to save the # variables to disk e.g. ~/variables.cfg","title":"[save_variables]"},{"location":"Config_Reference.html#idle_timeout","text":"Idle timeout. An idle timeout is automatically enabled - add an explicit idle_timeout config section to change the default settings. [idle_timeout] #gcode: # A list of G-Code commands to execute on an idle timeout. See # docs/Command_Templates.md for G-Code format. The default is to run # \"TURN_OFF_HEATERS\" and \"M84\". #timeout: 600 # Idle time (in seconds) to wait before running the above G-Code # commands. The default is 600 seconds.","title":"[idle_timeout]"},{"location":"Config_Reference.html#optional-g-code-features","text":"","title":"Optional G-Code features"},{"location":"Config_Reference.html#virtual_sdcard","text":"A virtual sdcard may be useful if the host machine is not fast enough to run OctoPrint well. It allows the Klipper host software to directly print gcode files stored in a directory on the host using standard sdcard G-Code commands (eg, M24). [virtual_sdcard] path: # The path of the local directory on the host machine to look for # g-code files. This is a read-only directory (sdcard file writes # are not supported). One may point this to OctoPrint's upload # directory (generally ~/.octoprint/uploads/ ). This parameter must # be provided. #on_error_gcode: # A list of G-Code commands to execute when an error is reported. # See docs/Command_Templates.md for G-Code format. The default is to # run TURN_OFF_HEATERS.","title":"[virtual_sdcard]"},{"location":"Config_Reference.html#sdcard_loop","text":"Some printers with stage-clearing features, such as a part ejector or a belt printer, can find use in looping sections of the sdcard file. (For example, to print the same part over and over, or repeat the a section of a part for a chain or other repeated pattern). See the command reference for supported commands. See the sample-macros.cfg file for a Marlin compatible M808 G-Code macro. [sdcard_loop]","title":"[sdcard_loop]"},{"location":"Config_Reference.html#force_move","text":"Support manually moving stepper motors for diagnostic purposes. Note, using this feature may place the printer in an invalid state - see the command reference for important details. [force_move] #enable_force_move: False # Set to true to enable FORCE_MOVE and SET_KINEMATIC_POSITION # extended G-Code commands. The default is false.","title":"[force_move]"},{"location":"Config_Reference.html#pause_resume","text":"Pause/Resume functionality with support of position capture and restore. See the command reference for more information. [pause_resume] #recover_velocity: 50. # When capture/restore is enabled, the speed at which to return to # the captured position (in mm/s). Default is 50.0 mm/s.","title":"[pause_resume]"},{"location":"Config_Reference.html#firmware_retraction","text":"Firmware filament retraction. This enables G10 (retract) and G11 (unretract) GCODE commands issued by many slicers. The parameters below provide startup defaults, although the values can be adjusted via the SET_RETRACTION command ), allowing per-filament settings and runtime tuning. [firmware_retraction] #retract_length: 0 # The length of filament (in mm) to retract when G10 is activated, # and to unretract when G11 is activated (but see # unretract_extra_length below). The default is 0 mm. #retract_speed: 20 # The speed of retraction, in mm/s. The default is 20 mm/s. #unretract_extra_length: 0 # The length (in mm) of *additional* filament to add when # unretracting. #unretract_speed: 10 # The speed of unretraction, in mm/s. The default is 10 mm/s.","title":"[firmware_retraction]"},{"location":"Config_Reference.html#gcode_arcs","text":"Support for gcode arc (G2/G3) commands. [gcode_arcs] #resolution: 1.0 # An arc will be split into segments. Each segment's length will # equal the resolution in mm set above. Lower values will produce a # finer arc, but also more work for your machine. Arcs smaller than # the configured value will become straight lines. The default is # 1mm.","title":"[gcode_arcs]"},{"location":"Config_Reference.html#respond","text":"Enable the \"M118\" and \"RESPOND\" extended commands . [respond] #default_type: echo # Sets the default prefix of the \"M118\" and \"RESPOND\" output to one # of the following: # echo: \"echo: \" (This is the default) # command: \"// \" # error: \"!! \" #default_prefix: echo: # Directly sets the default prefix. If present, this value will # override the \"default_type\".","title":"[respond]"},{"location":"Config_Reference.html#exclude_object","text":"Enables support to exclude or cancel individual objects during the printing process. See the exclude objects guide and command reference for additional information. See the sample-macros.cfg file for a Marlin/RepRapFirmware compatible M486 G-Code macro. [exclude_object]","title":"[exclude_object]"},{"location":"Config_Reference.html#resonance-compensation","text":"","title":"Resonance compensation"},{"location":"Config_Reference.html#input_shaper","text":"Enables resonance compensation . Also see the command reference . [input_shaper] #shaper_freq_x: 0 # A frequency (in Hz) of the input shaper for X axis. This is # usually a resonance frequency of X axis that the input shaper # should suppress. For more complex shapers, like 2- and 3-hump EI # input shapers, this parameter can be set from different # considerations. The default value is 0, which disables input # shaping for X axis. #shaper_freq_y: 0 # A frequency (in Hz) of the input shaper for Y axis. This is # usually a resonance frequency of Y axis that the input shaper # should suppress. For more complex shapers, like 2- and 3-hump EI # input shapers, this parameter can be set from different # considerations. The default value is 0, which disables input # shaping for Y axis. #shaper_freq_z: 0 # A frequency (in Hz) of the input shaper for Z axis. The default # value is 0, which disables input shaping for Z axis. #shaper_type: mzv # A type of the input shaper to use for all 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: #shaper_type_z: # If shaper_type is not set, these parameters can be used to # configure different input shapers for X, Y, and Z axes. The same # values are supported as for shaper_type parameter. #damping_ratio_x: 0.1 #damping_ratio_y: 0.1 #damping_ratio_z: 0.1 # Damping ratios of vibrations of X and Y axes used by input shapers # to improve vibration suppression. Default value is 0.1 which is a # good all-round value for most printers. In most circumstances this # parameter requires no tuning and should not be changed.","title":"[input_shaper]"},{"location":"Config_Reference.html#adxl345","text":"Support for ADXL345 accelerometers. This support allows one to query accelerometer measurements from the sensor. This enables an ACCELEROMETER_MEASURE command (see G-Codes for more information). The default chip name is \"default\", but one may specify an explicit name (eg, [adxl345 my_chip_name]). [adxl345] cs_pin: # The SPI enable pin for the sensor. This parameter must be provided. #spi_speed: 5000000 # The SPI speed (in hz) to use when communicating with the chip. # The default is 5000000. #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #axes_map: x, y, z # The accelerometer axis for each of the printer's X, Y, and Z axes. # This may be useful if the accelerometer is mounted in an # orientation that does not match the printer orientation. For # example, one could set this to \"y, x, z\" to swap the X and Y axes. # It is also possible to negate an axis if the accelerometer # direction is reversed (eg, \"x, z, -y\"). The default is \"x, y, z\". #rate: 3200 # Output data rate for ADXL345. ADXL345 supports the following data # rates: 3200, 1600, 800, 400, 200, 100, 50, and 25. Note that it is # not recommended to change this rate from the default 3200, and # rates below 800 will considerably affect the quality of resonance # measurements.","title":"[adxl345]"},{"location":"Config_Reference.html#icm20948","text":"Support for icm20948 accelerometers. [icm20948] #i2c_address: # Default is 104 (0x68). If AD0 is high, it would be 0x69 instead. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: 400000 # See the \"common I2C settings\" section for a description of the # above parameters. The default \"i2c_speed\" is 400000. #axes_map: x, y, z # See the \"adxl345\" section for information on this parameter.","title":"[icm20948]"},{"location":"Config_Reference.html#lis2dw","text":"Support for LIS2DW accelerometers. [lis2dw] #cs_pin: # The SPI enable pin for the sensor. This parameter must be provided # if using SPI. #spi_speed: 5000000 # The SPI speed (in hz) to use when communicating with the chip. # The default is 5000000. #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #i2c_address: # Default is 25 (0x19). If SA0 is high, it would be 24 (0x18) instead. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: 400000 # See the \"common I2C settings\" section for a description of the # above parameters. The default \"i2c_speed\" is 400000. #axes_map: x, y, z # See the \"adxl345\" section for information on this parameter.","title":"[lis2dw]"},{"location":"Config_Reference.html#lis3dh","text":"Support for LIS3DH accelerometers. [lis3dh] #cs_pin: # The SPI enable pin for the sensor. This parameter must be provided # if using SPI. #spi_speed: 5000000 # The SPI speed (in hz) to use when communicating with the chip. # The default is 5000000. #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #i2c_address: # Default is 25 (0x19). If SA0 is high, it would be 24 (0x18) instead. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: 400000 # See the \"common I2C settings\" section for a description of the # above parameters. The default \"i2c_speed\" is 400000. #axes_map: x, y, z # See the \"adxl345\" section for information on this parameter.","title":"[lis3dh]"},{"location":"Config_Reference.html#mpu9250","text":"Support for MPU-9250, MPU-9255, MPU-6515, MPU-6050, and MPU-6500 accelerometers (one may define any number of sections with an \"mpu9250\" prefix). [mpu9250 my_accelerometer] #i2c_address: # Default is 104 (0x68). If AD0 is high, it would be 0x69 instead. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: 400000 # See the \"common I2C settings\" section for a description of the # above parameters. The default \"i2c_speed\" is 400000. #axes_map: x, y, z # See the \"adxl345\" section for information on this parameter.","title":"[mpu9250]"},{"location":"Config_Reference.html#resonance_tester","text":"Support for resonance testing and automatic input shaper calibration. In order to use most of the functionality of this module, additional software dependencies must be installed; refer to Measuring Resonances and the command reference for more information. See the Max smoothing section of the measuring resonances guide for more information on max_smoothing parameter and its use. [resonance_tester] #probe_points: # A list of X, Y, Z coordinates of points (one point per line) to test # resonances at. At least one point is required. Make sure that all # points with some safety margin in XY plane (~a few centimeters) # are reachable by the toolhead. #accel_chip: # A name of the accelerometer chip to use for measurements. If # an accelerometer was defined without an explicit name, this parameter # can simply reference it by type, e.g. \"accel_chip: adxl345\", otherwise # a full name must be supplied, 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. #accel_chip_z: # A name of the accelerometer chip to use for measurements of Z axis. # This parameter has the same format as 'accel_chip'. The default is # not to configure an accelerometer for Z axis. #max_smoothing: # Maximum input shaper smoothing to allow for each axis during shaper # auto-calibration (with 'SHAPER_CALIBRATE' command). By default no # maximum smoothing is specified. Refer to Measuring_Resonances guide # for more details on using this feature. #move_speed: 50 # The speed (in mm/s) to move the toolhead to and between test points # during the calibration. The default is 50. #min_freq: 5 # Minimum frequency to test for resonances. The default is 5 Hz. #max_freq: 135 # Maximum frequency to test for resonances. The default is 135 Hz. #max_freq_z: 100 # Maximum frequency to test Z axis for resonances. The default is 100 Hz. #accel_per_hz: 60 # This parameter is used to determine which acceleration to use to # test a specific frequency: accel = accel_per_hz * freq. Higher the # value, the higher is the energy of the oscillations. Can be set to # a lower than the default value if the resonances get too strong on # the printer. However, lower values make measurements of high-frequency # resonances less precise. The default value is 60 (mm/sec). #accel_per_hz_z: 15 # This parameter has the same meaning as accel_per_hz, but applies to # Z axis specifically. The default is 15 (mm/sec). #hz_per_sec: 1 # Determines the speed of the test. When testing all frequencies in # range [min_freq, max_freq], each second the frequency increases by # hz_per_sec. Small values make the test slow, and the large values # will decrease the precision of the test. The default value is 1.0 # (Hz/sec == sec^-2). #sweeping_accel: 400 # An acceleration of slow sweeping moves. The default is 400 mm/sec^2. #sweeping_accel_z: 50 # Same as sweeping_accel above, but for Z axis. The default is 50 mm/sec^2. #sweeping_period: 1.2 # A period of slow sweeping moves. Setting this parameter to 0 # disables slow sweeping moves. Avoid setting it to a too small # non-zero value in order to not poison the measurements. # The default is 1.2 sec which is a good all-round choice.","title":"[resonance_tester]"},{"location":"Config_Reference.html#config-file-helpers","text":"","title":"Config file helpers"},{"location":"Config_Reference.html#board_pins","text":"Board pin aliases (one may define any number of sections with a \"board_pins\" prefix). Use this to define aliases for the pins on a micro-controller. [board_pins my_aliases] mcu: mcu # A comma separated list of micro-controllers that may use the # aliases. The default is to apply the aliases to the main \"mcu\". aliases: aliases_: # 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=\" would reserve \"EXP1_9\"). Any number of options # starting with \"aliases_\" may be specified.","title":"[board_pins]"},{"location":"Config_Reference.html#include","text":"Include file support. One may include additional config file from the main printer config file. Wildcards may also be used (eg, \"configs/*.cfg\"). [include my_other_config.cfg]","title":"[include]"},{"location":"Config_Reference.html#duplicate_pin_override","text":"This tool allows a single micro-controller pin to be defined multiple times in a config file without normal error checking. This is intended for diagnostic and debugging purposes. This section is not needed where Klipper supports using the same pin multiple times, and using this override may cause confusing and unexpected results. [duplicate_pin_override] pins: # A comma separated list of pins that may be used multiple times in # a config file without normal error checks. This parameter must be # provided.","title":"[duplicate_pin_override]"},{"location":"Config_Reference.html#bed-probing-hardware","text":"","title":"Bed probing hardware"},{"location":"Config_Reference.html#probe","text":"Z height probe. One may define this section to enable Z height probing hardware. When this section is enabled, PROBE and QUERY_PROBE extended g-code commands become available. Also, see the probe calibrate guide . The probe section also creates a virtual \"probe:z_virtual_endstop\" pin. One may set the stepper_z endstop_pin to this virtual pin on cartesian style printers that use the probe in place of a z endstop. If using \"probe:z_virtual_endstop\" then do not define a position_endstop in the stepper_z config section. [probe] pin: # Probe detection pin. If the pin is on a different microcontroller # than the Z steppers then it enables \"multi-mcu homing\". This # parameter must be provided. #deactivate_on_each_sample: True # This determines if Klipper should execute deactivation gcode # between each probe attempt when performing a multiple probe # sequence. The default is True. #x_offset: 0.0 # The distance (in mm) between the probe and the nozzle along the # x-axis. The default is 0. #y_offset: 0.0 # The distance (in mm) between the probe and the nozzle along the # y-axis. The default is 0. z_offset: # The distance (in mm) between the bed and the nozzle when the probe # triggers. This parameter must be provided. #speed: 5.0 # Speed (in mm/s) of the Z axis when probing. The default is 5mm/s. #samples: 1 # The number of times to probe each point. The probed z-values will # be averaged. The default is to probe 1 time. #sample_retract_dist: 2.0 # The distance (in mm) to lift the toolhead between each sample (if # sampling more than once). The default is 2mm. #lift_speed: # Speed (in mm/s) of the Z axis when lifting the probe between # samples. The default is to use the same value as the 'speed' # parameter. #samples_result: average # The calculation method when sampling more than once - either # \"median\" or \"average\". The default is average. #samples_tolerance: 0.100 # The maximum Z distance (in mm) that a sample may differ from other # samples. If this tolerance is exceeded then either an error is # reported or the attempt is restarted (see # samples_tolerance_retries). The default is 0.100mm. #samples_tolerance_retries: 0 # The number of times to retry if a sample is found that exceeds # samples_tolerance. On a retry, all current samples are discarded # and the probe attempt is restarted. If a valid set of samples are # not obtained in the given number of retries then an error is # reported. The default is zero which causes an error to be reported # on the first sample that exceeds samples_tolerance. #activate_gcode: # A list of G-Code commands to execute prior to each probe attempt. # See docs/Command_Templates.md for G-Code format. This may be # useful if the probe needs to be activated in some way. Do not # issue any commands here that move the toolhead (eg, G1). The # default is to not run any special G-Code commands on activation. #deactivate_gcode: # A list of G-Code commands to execute after each probe attempt # completes. See docs/Command_Templates.md for G-Code format. Do not # issue any commands here that move the toolhead. The default is to # not run any special G-Code commands on deactivation.","title":"[probe]"},{"location":"Config_Reference.html#bltouch","text":"BLTouch probe. One may define this section (instead of a probe section) to enable a BLTouch probe. See BL-Touch guide and command reference for further information. A virtual \"probe:z_virtual_endstop\" pin is also created (see the \"probe\" section for the details). [bltouch] sensor_pin: # Pin connected to the BLTouch sensor pin. Most BLTouch devices # require a pullup on the sensor pin (prefix the pin name with \"^\"). # This parameter must be provided. control_pin: # Pin connected to the BLTouch control pin. This parameter must be # provided. #pin_move_time: 0.680 # The amount of time (in seconds) to wait for the BLTouch pin to # move up or down. The default is 0.680 seconds. #stow_on_each_sample: True # This determines if Klipper should command the pin to move up # between each probe attempt when performing a multiple probe # sequence. Read the directions in docs/BLTouch.md before setting # this to False. The default is True. #probe_with_touch_mode: False # If this is set to True then Klipper will probe with the device in # \"touch_mode\". The default is False (probing in \"pin_down\" mode). #pin_up_reports_not_triggered: True # Set if the BLTouch consistently reports the probe in a \"not # triggered\" state after a successful \"pin_up\" command. This should # be True for all genuine BLTouch devices. Read the directions in # docs/BLTouch.md before setting this to False. The default is True. #pin_up_touch_mode_reports_triggered: True # Set if the BLTouch consistently reports a \"triggered\" state after # the commands \"pin_up\" followed by \"touch_mode\". This should be # True for all genuine BLTouch devices. Read the directions in # docs/BLTouch.md before setting this to False. The default is True. #set_output_mode: # Request a specific sensor pin output mode on the BLTouch V3.0 (and # later). This setting should not be used on other types of probes. # Set to \"5V\" to request a sensor pin output of 5 Volts (only use if # the controller board needs 5V mode and is 5V tolerant on its input # signal line). Set to \"OD\" to request the sensor pin output use # open drain mode. The default is to not request an output mode. #x_offset: #y_offset: #z_offset: #speed: #lift_speed: #samples: #sample_retract_dist: #samples_result: #samples_tolerance: #samples_tolerance_retries: # See the \"probe\" section for information on these parameters.","title":"[bltouch]"},{"location":"Config_Reference.html#smart_effector","text":"The \"Smart Effector\" from Duet3d implements a Z probe using a force sensor. One may define this section instead of [probe] to enable the Smart Effector specific features. This also enables runtime commands to adjust the parameters of the Smart Effector at run time. [smart_effector] pin: # Pin connected to the Smart Effector Z Probe output pin (pin 5). Note that # pullup resistor on the board is generally not required. However, if the # output pin is connected to the board pin with a pullup resistor, that # resistor must be high value (e.g. 10K Ohm or more). Some boards have a low # value pullup resistor on the Z probe input, which will likely result in an # always-triggered probe state. In this case, connect the Smart Effector to # a different pin on the board. This parameter is required. #control_pin: # Pin connected to the Smart Effector control input pin (pin 7). If provided, # Smart Effector sensitivity programming commands become available. #probe_accel: # If set, limits the acceleration of the probing moves (in mm/sec^2). # A sudden large acceleration at the beginning of the probing move may # cause spurious probe triggering, especially if the hotend is heavy. # To prevent that, it may be necessary to reduce the acceleration of # the probing moves via this parameter. #recovery_time: 0.4 # A delay between the travel moves and the probing moves in seconds. A fast # travel move prior to probing may result in a spurious probe triggering. # This may cause 'Probe triggered prior to movement' errors if no delay # is set. Value 0 disables the recovery delay. # Default value is 0.4. #x_offset: #y_offset: # Should be left unset (or set to 0). z_offset: # Trigger height of the probe. Start with -0.1 (mm), and adjust later using # `PROBE_CALIBRATE` command. This parameter must be provided. #speed: # Speed (in mm/s) of the Z axis when probing. It is recommended to start # with the probing speed of 20 mm/s and adjust it as necessary to improve # the accuracy and repeatability of the probe triggering. #samples: #sample_retract_dist: #samples_result: #samples_tolerance: #samples_tolerance_retries: #activate_gcode: #deactivate_gcode: #deactivate_on_each_sample: # See the \"probe\" section for more information on the parameters above.","title":"[smart_effector]"},{"location":"Config_Reference.html#probe_eddy_current","text":"Support for eddy current inductive probes. One may define this section (instead of a probe section) to enable this probe. See the command reference for further information. [probe_eddy_current my_eddy_probe] sensor_type: ldc1612 # The sensor chip used to perform eddy current measurements. This # parameter must be provided and must be set to ldc1612. #frequency: # The external crystal frequency (in Hz) of the LDC1612 chip. # The default is 12000000. #intb_pin: # MCU gpio pin connected to the ldc1612 sensor's INTB pin (if # available). The default is to not use the INTB pin. #z_offset: # The nominal distance (in mm) between the nozzle and bed that a # probing attempt should stop at. This parameter must be provided. #i2c_address: #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # The i2c settings for the sensor chip. See the \"common I2C # settings\" section for a description of the above parameters. #x_offset: #y_offset: #speed: #lift_speed: #samples: #sample_retract_dist: #samples_result: #samples_tolerance: #samples_tolerance_retries: # See the \"probe\" section for information on these parameters.","title":"[probe_eddy_current]"},{"location":"Config_Reference.html#axis_twist_compensation","text":"A tool to compensate for inaccurate probe readings due to twist in X or Y gantry. See the Axis Twist Compensation Guide for more detailed information regarding symptoms, configuration and setup. [axis_twist_compensation] #speed: 50 # The speed (in mm/s) of non-probing moves during the calibration. # The default is 50. #horizontal_move_z: 5 # The height (in mm) that the head should be commanded to move to # just prior to starting a probe operation. The default is 5. calibrate_start_x: 20 # Defines the minimum X coordinate of the calibration # This should be the X coordinate that positions the nozzle at the starting # calibration position. calibrate_end_x: 200 # Defines the maximum X coordinate of the calibration # This should be the X coordinate that positions the nozzle at the ending # calibration position. calibrate_y: 112.5 # Defines the Y coordinate of the calibration # This should be the Y coordinate that positions the nozzle during the # calibration process. This parameter is recommended to # be near the center of the bed # For Y-axis twist compensation, specify the following parameters: calibrate_start_y: ... # Defines the minimum Y coordinate of the calibration # This should be the Y coordinate that positions the nozzle at the starting # calibration position for the Y axis. This parameter must be provided if # compensating for Y axis twist. calibrate_end_y: ... # Defines the maximum Y coordinate of the calibration # This should be the Y coordinate that positions the nozzle at the ending # calibration position for the Y axis. This parameter must be provided if # compensating for Y axis twist. calibrate_x: ... # Defines the X coordinate of the calibration for Y axis twist compensation # This should be the X coordinate that positions the nozzle during the # calibration process for Y axis twist compensation. This parameter must be # provided and is recommended to be near the center of the bed.","title":"[axis_twist_compensation]"},{"location":"Config_Reference.html#additional-stepper-motors-and-extruders","text":"","title":"Additional stepper motors and extruders"},{"location":"Config_Reference.html#stepper_z1","text":"Multi-stepper axes. On a cartesian style printer, the stepper controlling a given axis may have additional config blocks defining steppers that should be stepped in concert with the primary stepper. One may define any number of sections with a numeric suffix starting at 1 (for example, \"stepper_z1\", \"stepper_z2\", etc.). [stepper_z1] #step_pin: #dir_pin: #enable_pin: #microsteps: #rotation_distance: # See the \"stepper\" section for the definition of the above parameters. #endstop_pin: # If an endstop_pin is defined for the additional stepper then the # stepper will home until the endstop is triggered. Otherwise, the # stepper will home until the endstop on the primary stepper for the # axis is triggered.","title":"[stepper_z1]"},{"location":"Config_Reference.html#extruder1","text":"In a multi-extruder printer add an additional extruder section for each additional extruder. The additional extruder sections should be named \"extruder1\", \"extruder2\", \"extruder3\", and so on. See the \"extruder\" section for a description of available parameters. See sample-multi-extruder.cfg for an example configuration. [extruder1] #step_pin: #dir_pin: #... # See the \"extruder\" section for available stepper and heater # parameters. #shared_heater: # This option is deprecated and should no longer be specified.","title":"[extruder1]"},{"location":"Config_Reference.html#dual_carriage","text":"Support for cartesian, generic_cartesian and hybrid_corexy/z printers with dual carriages on a single axis. The carriage mode can be set via the SET_DUAL_CARRIAGE extended g-code command. For example, \"SET_DUAL_CARRIAGE CARRIAGE=1\" command will activate the carriage defined in this section (CARRIAGE=0 will return activation to the primary carriage). Dual carriage support is typically combined with extra extruders - the SET_DUAL_CARRIAGE command is often called at the same time as the ACTIVATE_EXTRUDER command. Be sure to park the carriages during deactivation. Note that during G28 homing, typically the primary carriage is homed first followed by the carriage defined in the [dual_carriage] config section. However, the [dual_carriage] carriage will be homed first if both carriages home in a positive direction and the [dual_carriage] carriage has a position_endstop greater than the primary carriage, or if both carriages home in a negative direction and the [dual_carriage] carriage has a position_endstop less than the primary carriage. Additionally, one could use \"SET_DUAL_CARRIAGE CARRIAGE=1 MODE=COPY\" or \"SET_DUAL_CARRIAGE CARRIAGE=1 MODE=MIRROR\" commands to activate either copying or mirroring mode of the dual carriage, in which case it will follow the motion of the carriage 0 accordingly. These commands can be used to print two parts simultaneously - either two identical parts (in COPY mode) or mirrored parts (in MIRROR mode). Note that COPY and MIRROR modes also require appropriate configuration of the extruder on the dual carriage, which can typically be achieved with \"SYNC_EXTRUDER_MOTION MOTION_QUEUE=extruder EXTRUDER= \" or a similar command. See sample-idex.cfg for an example configuration with a regular Cartesian kinematic. [dual_carriage] axis: # The axis this extra carriage is on (either x or y). This parameter # must be provided. #safe_distance: # The minimum distance (in mm) to enforce between the dual and the primary # carriages. If a G-Code command is executed that will bring the carriages # closer than the specified limit, such a command will be rejected with an # error. If safe_distance is not provided, it will be inferred from # position_min and position_max for the dual and primary carriages. If set # to 0 (or safe_distance is unset and position_min and position_max are # identical for the primary and dual carriages), the carriages proximity # checks will be disabled. #step_pin: #dir_pin: #enable_pin: #microsteps: #rotation_distance: #endstop_pin: #position_endstop: #position_min: #position_max: # See the \"stepper\" section for the definition of the above parameters. For an example of dual carriage configuration with generic_cartesian kinematic, see the following configuration sample . Please note that in this case the [dual_carriage] configuration deviates from the configuration described above: [dual_carriage my_dc_carriage] primary_carriage: # Defines the matching primary carriage of this dual carriage and # the corresponding IDEX axis. Must match a name of a defined `[carriage]`. # This parameter must be provided. #safe_distance: # The minimum distance (in mm) to enforce between the dual and the primary # carriages. If a G-Code command is executed that will bring the carriages # closer than the specified limit, such a command will be rejected with an # error. If safe_distance is not provided, it will be inferred from # position_min and position_max for the dual and primary carriages. If set # to 0 (or safe_distance is unset and position_min and position_max are # identical for the primary and dual carriages), the carriages proximity # checks will be disabled. endstop_pin: #position_min: position_endstop: position_max: #homing_speed: #homing_retract_dist: #homing_retract_speed: #second_homing_speed: #homing_positive_dir: ... Refer to generic cartesian section for more information on the regular carriage parameters. Then a user must define one or more stepper motors moving the dual carriage (and other carriages as appropriate), for instance [carriage carriage_x] ... [carriage carriage_y] ... [dual_carriage carriage_u] primary_carriage: carriage_x ... [stepper dc_stepper] carriages: carriage_u-carriage_y ... [dual_carriage] requires special configuration for the input shaper. In general, it is necessary to run input shaper calibration twice - for the dual_carriage and its primary_carriage for the axis they share. Then the input shaper can be configured as follows, assuming the example above: [input_shaper] # Intentionally empty [delayed_gcode init_shaper] initial_duration: 0.1 gcode: SET_DUAL_CARRIAGE CARRIAGE=carriage_u SET_INPUT_SHAPER SHAPER_TYPE_X= SHAPER_FREQ_X= SHAPER_TYPE_Y= SHAPER_FREQ_Y= SET_DUAL_CARRIAGE CARRIAGE=carriage_x SET_INPUT_SHAPER SHAPER_TYPE_X= SHAPER_FREQ_X= SHAPER_TYPE_Y= SHAPER_FREQ_Y= Note that SHAPER_TYPE_Y and SHAPER_FREQ_Y must be the same in both commands in this case, since the same motors drive Y axis when either of the carriage_x and carriage_u carriages are active. It is worth noting that generic_cartesian kinematic can support two dual carriages for X and Y axes. For reference, see for instance a sample of CoreXYUV configuration.","title":"[dual_carriage]"},{"location":"Config_Reference.html#extruder_stepper","text":"Support for additional steppers synchronized to the movement of an extruder (one may define any number of sections with an \"extruder_stepper\" prefix). See the command reference for more information. [extruder_stepper my_extra_stepper] extruder: # The extruder this stepper is synchronized to. If this is set to an # empty string then the stepper will not be synchronized to an # extruder. This parameter must be provided. #step_pin: #dir_pin: #enable_pin: #microsteps: #rotation_distance: # See the \"stepper\" section for the definition of the above # parameters.","title":"[extruder_stepper]"},{"location":"Config_Reference.html#manual_stepper","text":"Manual steppers (one may define any number of sections with a \"manual_stepper\" prefix). These are steppers that are controlled by the MANUAL_STEPPER g-code command. For example: \"MANUAL_STEPPER STEPPER=my_stepper MOVE=10 SPEED=5\". See G-Codes file for a description of the MANUAL_STEPPER command. The steppers are not connected to the normal printer kinematics. [manual_stepper my_stepper] #step_pin: #dir_pin: #enable_pin: #microsteps: #rotation_distance: # See the \"stepper\" section for a description of these parameters. #velocity: # Set the default velocity (in mm/s) for the stepper. This value # will be used if a MANUAL_STEPPER command does not specify a SPEED # parameter. The default is 5mm/s. #accel: # Set the default acceleration (in mm/s^2) for the stepper. An # acceleration of zero will result in no acceleration. This value # will be used if a MANUAL_STEPPER command does not specify an ACCEL # parameter. The default is zero. #endstop_pin: # Endstop switch detection pin. If specified, then one may perform # \"homing moves\" by adding a STOP_ON_ENDSTOP parameter to # MANUAL_STEPPER movement commands. #position_min: #position_max: # The minimum and maximum position the stepper can be commanded to # move to. If specified then one may not command the stepper to move # past the given position. Note that these limits do not prevent # setting an arbitrary position with the `MANUAL_STEPPER # SET_POSITION=x` command. The default is to not enforce a limit.","title":"[manual_stepper]"},{"location":"Config_Reference.html#custom-heaters-and-sensors","text":"","title":"Custom heaters and sensors"},{"location":"Config_Reference.html#verify_heater","text":"Heater and temperature sensor verification. Heater verification is automatically enabled for each heater that is configured on the printer. Use verify_heater sections to change the default settings. [verify_heater heater_config_name] #max_error: 120 # The maximum \"cumulative temperature error\" before raising an # error. Smaller values result in stricter checking and larger # values allow for more time before an error is reported. # Specifically, the temperature is inspected once a second and if it # is close to the target temperature then an internal \"error # counter\" is reset; otherwise, if the temperature is below the # target range then the counter is increased by the amount the # reported temperature differs from that range. Should the counter # exceed this \"max_error\" then an error is raised. The default is # 120. #check_gain_time: # This controls heater verification during initial heating. Smaller # values result in stricter checking and larger values allow for # more time before an error is reported. Specifically, during # initial heating, as long as the heater increases in temperature # within this time frame (specified in seconds) then the internal # \"error counter\" is reset. The default is 20 seconds for extruders # and 60 seconds for heater_bed. #hysteresis: 5 # The maximum temperature difference (in Celsius) to a target # temperature that is considered in range of the target. This # controls the max_error range check. It is rare to customize this # value. The default is 5. #heating_gain: 2 # The minimum temperature (in Celsius) that the heater must increase # by during the check_gain_time check. It is rare to customize this # value. The default is 2.","title":"[verify_heater]"},{"location":"Config_Reference.html#homing_heaters","text":"Tool to disable heaters when homing or probing an axis. [homing_heaters] #steppers: # A comma separated list of steppers that should cause heaters to be # disabled. The default is to disable heaters for any homing/probing # move. # Typical example: stepper_z #heaters: # A comma separated list of heaters to disable during homing/probing # moves. The default is to disable all heaters. # Typical example: extruder, heater_bed","title":"[homing_heaters]"},{"location":"Config_Reference.html#thermistor","text":"Custom thermistors (one may define any number of sections with a \"thermistor\" prefix). A custom thermistor may be used in the sensor_type field of a heater config section. (For example, if one defines a \"[thermistor my_thermistor]\" section then one may use a \"sensor_type: my_thermistor\" when defining a heater.) Be sure to place the thermistor section in the config file above its first use in a heater section. [thermistor my_thermistor] #temperature1: #resistance1: #temperature2: #resistance2: #temperature3: #resistance3: # Three resistance measurements (in Ohms) at the given temperatures # (in Celsius). The three measurements will be used to calculate the # Steinhart-Hart coefficients for the thermistor. These parameters # must be provided when using Steinhart-Hart to define the # thermistor. #beta: # Alternatively, one may define temperature1, resistance1, and beta # to define the thermistor parameters. This parameter must be # provided when using \"beta\" to define the thermistor.","title":"[thermistor]"},{"location":"Config_Reference.html#adc_temperature","text":"Custom ADC temperature sensors (one may define any number of sections with an \"adc_temperature\" prefix). This allows one to define a custom temperature sensor that measures a voltage on an Analog to Digital Converter (ADC) pin and uses linear interpolation between a set of configured temperature/voltage (or temperature/resistance) measurements to determine the temperature. The resulting sensor can be used as a sensor_type in a heater section. (For example, if one defines a \"[adc_temperature my_sensor]\" section then one may use a \"sensor_type: my_sensor\" when defining a heater.) Be sure to place the sensor section in the config file above its first use in a heater section. [adc_temperature my_sensor] #temperature1: #voltage1: #temperature2: #voltage2: #... # A set of temperatures (in Celsius) and voltages (in Volts) to use # as reference when converting a temperature. A heater section using # this sensor may also specify adc_voltage and voltage_offset # parameters to define the ADC voltage (see \"Common temperature # amplifiers\" section for details). At least two measurements must # be provided. #temperature1: #resistance1: #temperature2: #resistance2: #... # Alternatively one may specify a set of temperatures (in Celsius) # and resistance (in Ohms) to use as reference when converting a # temperature. A heater section using this sensor may also specify a # pullup_resistor parameter (see \"extruder\" section for details). At # least two measurements must be provided.","title":"[adc_temperature]"},{"location":"Config_Reference.html#heater_generic","text":"Generic heaters (one may define any number of sections with a \"heater_generic\" prefix). These heaters behave similarly to standard heaters (extruders, heated beds). Use the SET_HEATER_TEMPERATURE command (see G-Codes for details) to set the target temperature. [heater_generic my_generic_heater] #gcode_id: # The id to use when reporting the temperature in the M105 command. # This parameter must be provided. #heater_pin: #max_power: #sensor_type: #sensor_pin: #smooth_time: #control: #pid_Kp: #pid_Ki: #pid_Kd: #pwm_cycle_time: #min_temp: #max_temp: # See the \"extruder\" section for the definition of the above # parameters.","title":"[heater_generic]"},{"location":"Config_Reference.html#temperature_sensor","text":"Generic temperature sensors. One can define any number of additional temperature sensors that are reported via the M105 command. [temperature_sensor my_sensor] #sensor_type: #sensor_pin: #min_temp: #max_temp: # See the \"extruder\" section for the definition of the above # parameters. #gcode_id: # See the \"heater_generic\" section for the definition of this # parameter.","title":"[temperature_sensor]"},{"location":"Config_Reference.html#temperature_probe","text":"Reports probe coil temperature. Includes optional thermal drift calibration for eddy current based probes. A [temperature_probe] section may be linked to a [probe_eddy_current] by using the same postfix for both sections. [temperature_probe my_probe] #sensor_type: #sensor_pin: #min_temp: #max_temp: # Temperature sensor configuration. # See the \"extruder\" section for the definition of the above # parameters. #smooth_time: # A time value (in seconds) over which temperature measurements will # be smoothed to reduce the impact of measurement noise. The default # is 2.0 seconds. #gcode_id: # See the \"heater_generic\" section for the definition of this # parameter. #speed: # The travel speed [mm/s] for xy moves during calibration. Default # is the speed defined by the probe. #horizontal_move_z: # The z distance [mm] from the bed at which xy moves will occur # during calibration. Default is 2mm. #resting_z: # The z distance [mm] from the bed at which the tool will rest # to heat the probe coil during calibration. Default is .4mm #calibration_position: # The X, Y, Z position where the tool should be moved when # probe drift calibration initializes. This is the location # where the first manual probe will occur. If omitted, the # default behavior is not to move the tool prior to the first # manual probe. #calibration_bed_temp: # The maximum safe bed temperature (in C) used to heat the probe # during probe drift calibration. When set, the calibration # procedure will turn on the bed after the first sample is # taken. When the calibration procedure is complete the bed # temperature will be set to zero. When omitted the default # behavior is not to set the bed temperature. #calibration_extruder_temp: # The extruder temperature (in C) set probe during drift calibration. # When this option is supplied the procedure will wait for until the # specified temperature is reached before requesting the first manual # probe. When the calibration procedure is complete the extruder # temperature will be set to 0. When omitted the default behavior is # not to set the extruder temperature. #extruder_heating_z: 50. # The Z location where extruder heating will occur if the # \"calibration_extruder_temp\" option is set. Its recommended to heat # the extruder some distance from the bed to minimize its impact on # the probe coil temperature. The default is 50. #max_validation_temp: 60. # The maximum temperature used to validate the calibration. It is # recommended to set this to a value between 100 and 120 for enclosed # printers. The default is 60.","title":"[temperature_probe]"},{"location":"Config_Reference.html#temperature-sensors","text":"Klipper includes definitions for many types of temperature sensors. These sensors may be used in any config section that requires a temperature sensor (such as an [extruder] or [heater_bed] section).","title":"Temperature sensors"},{"location":"Config_Reference.html#common-thermistors","text":"Common thermistors. The following parameters are available in heater sections that use one of these sensors. sensor_type: # One of \"EPCOS 100K B57560G104F\", \"ATC Semitec 104GT-2\", # \"ATC Semitec 104NT-4-R025H42G\", \"Generic 3950\", # \"Honeywell 100K 135-104LAG-J01\", \"NTC 100K MGB18-104F39050L32\", # \"SliceEngineering 450\", or \"TDK NTCG104LH104JT1\" sensor_pin: # Analog input pin connected to the thermistor. This parameter must # be provided. #pullup_resistor: 4700 # The resistance (in ohms) of the pullup attached to the thermistor. # The default is 4700 ohms. #inline_resistor: 0 # The resistance (in ohms) of an extra (not heat varying) resistor # that is placed inline with the thermistor. It is rare to set this. # The default is 0 ohms.","title":"Common thermistors"},{"location":"Config_Reference.html#common-temperature-amplifiers","text":"Common temperature amplifiers. The following parameters are available in heater sections that use one of these sensors. sensor_type: # One of \"PT100 INA826\", \"AD595\", \"AD597\", \"AD8494\", \"AD8495\", # \"AD8496\", or \"AD8497\". sensor_pin: # Analog input pin connected to the sensor. This parameter must be # provided. #adc_voltage: 5.0 # The ADC comparison voltage (in Volts). The default is 5 volts. #voltage_offset: 0 # The ADC voltage offset (in Volts). The default is 0.","title":"Common temperature amplifiers"},{"location":"Config_Reference.html#directly-connected-pt1000-sensor","text":"Directly connected PT1000 sensor. The following parameters are available in heater sections that use one of these sensors. sensor_type: PT1000 sensor_pin: # Analog input pin connected to the sensor. This parameter must be # provided. #pullup_resistor: 4700 # The resistance (in ohms) of the pullup attached to the sensor. The # default is 4700 ohms.","title":"Directly connected PT1000 sensor"},{"location":"Config_Reference.html#maxxxxxx-temperature-sensors","text":"MAXxxxxx serial peripheral interface (SPI) temperature based sensors. The following parameters are available in heater sections that use one of these sensor types. sensor_type: # One of \"MAX6675\", \"MAX31855\", \"MAX31856\", or \"MAX31865\". sensor_pin: # The chip select line for the sensor chip. This parameter must be # provided. #spi_speed: 4000000 # The SPI speed (in hz) to use when communicating with the chip. # The default is 4000000. #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #tc_type: K #tc_use_50Hz_filter: False #tc_averaging_count: 1 # The above parameters control the sensor parameters of MAX31856 # chips. The defaults for each parameter are next to the parameter # name in the above list. #rtd_nominal_r: 100 #rtd_reference_r: 430 #rtd_num_of_wires: 2 #rtd_use_50Hz_filter: False # The above parameters control the sensor parameters of MAX31865 # chips. The defaults for each parameter are next to the parameter # name in the above list.","title":"MAXxxxxx temperature sensors"},{"location":"Config_Reference.html#bmp180bmp280bme280bmp388bme680-temperature-sensor","text":"BMP180/BMP280/BME280/BMP388/BME680 two wire interface (I2C) environmental sensors. Note that these sensors are not intended for use with extruders and heater beds, but rather for monitoring ambient temperature (C), pressure (hPa), relative humidity and in case of the BME680 gas level. See sample-macros.cfg for a gcode_macro that may be used to report pressure and humidity in addition to temperature. sensor_type: BME280 #i2c_address: # Default is 118 (0x76). The BMP180, BMP388 and some BME280 sensors # have an address of 119 (0x77). #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters.","title":"BMP180/BMP280/BME280/BMP388/BME680 temperature sensor"},{"location":"Config_Reference.html#aht10aht20aht21-temperature-sensor","text":"AHT10/AHT20/AHT21 two wire interface (I2C) environmental sensors. Note that these sensors are not intended for use with extruders and heater beds, but rather for monitoring ambient temperature (C) and relative humidity. See sample-macros.cfg for a gcode_macro that may be used to report humidity in addition to temperature. sensor_type: AHT10 # Also use AHT10 for AHT20 and AHT21 sensors. #i2c_address: # Default is 56 (0x38). Some AHT10 sensors give the option to use # 57 (0x39) by moving a resistor. #i2c_mcu: #i2c_bus: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #aht10_report_time: # Interval in seconds between readings. Default is 30, minimum is 5","title":"AHT10/AHT20/AHT21 temperature sensor"},{"location":"Config_Reference.html#htu21d-sensor","text":"HTU21D family two wire interface (I2C) environmental sensor. Note that this sensor is not intended for use with extruders and heater beds, but rather for monitoring ambient temperature (C) and relative humidity. See sample-macros.cfg for a gcode_macro that may be used to report humidity in addition to temperature. sensor_type: # Must be \"HTU21D\" , \"SI7013\", \"SI7020\", \"SI7021\" or \"SHT21\" #i2c_address: # Default is 64 (0x40). #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #htu21d_hold_master: # If the sensor can hold the I2C buf while reading. If True no other # bus communication can be performed while reading is in progress. # Default is False. #htu21d_resolution: # The resolution of temperature and humidity reading. # Valid values are: # 'TEMP14_HUM12' -> 14bit for Temp and 12bit for humidity # 'TEMP13_HUM10' -> 13bit for Temp and 10bit for humidity # 'TEMP12_HUM08' -> 12bit for Temp and 08bit for humidity # 'TEMP11_HUM11' -> 11bit for Temp and 11bit for humidity # Default is: \"TEMP11_HUM11\" #htu21d_report_time: # Interval in seconds between readings. Default is 30","title":"HTU21D sensor"},{"location":"Config_Reference.html#sht3x-sensor","text":"SHT3X family two wire interface (I2C) environmental sensor. These sensors have a range of -55~125 C, so are usable for e.g. chamber temperature monitoring. They can also function as simple fan/heater controllers. sensor_type: SHT3X #i2c_address: # Default is 68 (0x44). #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters.","title":"SHT3X sensor"},{"location":"Config_Reference.html#lm75-temperature-sensor","text":"LM75/LM75A two wire (I2C) connected temperature sensors. These sensors have a range of -55~125 C, so are usable for e.g. chamber temperature monitoring. They can also function as simple fan/heater controllers. sensor_type: LM75 #i2c_address: # Default is 72 (0x48). Normal range is 72-79 (0x48-0x4F) and the 3 # low bits of the address are configured via pins on the chip # (usually with jumpers or hard wired). #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #lm75_report_time: # Interval in seconds between readings. Default is 0.8, with minimum # 0.5.","title":"LM75 temperature sensor"},{"location":"Config_Reference.html#builtin-micro-controller-temperature-sensor","text":"The atsam, atsamd, stm32 and rp2040 micro-controllers contain an internal temperature sensor. One can use the \"temperature_mcu\" sensor to monitor these temperatures. sensor_type: temperature_mcu #sensor_mcu: mcu # The micro-controller to read from. The default is \"mcu\". #sensor_temperature1: #sensor_adc1: # Specify the above two parameters (a temperature in Celsius and an # ADC value as a float between 0.0 and 1.0) to calibrate the # micro-controller temperature. This may improve the reported # temperature accuracy on some chips. A typical way to obtain this # calibration information is to completely remove power from the # printer for a few hours (to ensure it is at the ambient # temperature), then power it up and use the QUERY_ADC command to # obtain an ADC measurement. Use some other temperature sensor on # the printer to find the corresponding ambient temperature. The # default is to use the factory calibration data on the # micro-controller (if applicable) or the nominal values from the # micro-controller specification. #sensor_temperature2: #sensor_adc2: # If sensor_temperature1/sensor_adc1 is specified then one may also # specify sensor_temperature2/sensor_adc2 calibration data. Doing so # may provide calibrated \"temperature slope\" information. The # default is to use the factory calibration data on the # micro-controller (if applicable) or the nominal values from the # micro-controller specification.","title":"Builtin micro-controller temperature sensor"},{"location":"Config_Reference.html#host-temperature-sensor","text":"Temperature from the machine (eg Raspberry Pi) running the host software. sensor_type: temperature_host #sensor_path: # The path to temperature system file. The default is # \"/sys/class/thermal/thermal_zone0/temp\" which is the temperature # system file on a Raspberry Pi computer.","title":"Host temperature sensor"},{"location":"Config_Reference.html#ds18b20-temperature-sensor","text":"DS18B20 is a 1-wire (w1) digital temperature sensor. Note that this sensor is not intended for use with extruders and heater beds, but rather for monitoring ambient temperature (C). These sensors have range up to 125 C, so are usable for e.g. chamber temperature monitoring. They can also function as simple fan/heater controllers. DS18B20 sensors are only supported on the \"host mcu\", e.g. the Raspberry Pi. The w1-gpio Linux kernel module must be installed. sensor_type: DS18B20 serial_no: # Each 1-wire device has a unique serial number used to identify the device, # usually in the format 28-031674b175ff. This parameter must be provided. # Attached 1-wire devices can be listed using the following Linux command: # ls /sys/bus/w1/devices/ #ds18_report_time: # Interval in seconds between readings. Default is 3.0, with a minimum of 1.0 #sensor_mcu: # The micro-controller to read from. Must be the host_mcu","title":"DS18B20 temperature sensor"},{"location":"Config_Reference.html#combined-temperature-sensor","text":"Combined temperature sensor is a virtual temperature sensor based on several other sensors. This sensor can be used with extruders, heater_generic and heater beds. sensor_type: temperature_combined #sensor_list: # Must be provided. List of sensors to combine to new \"virtual\" # sensor. # E.g. 'temperature_sensor sensor1,extruder,heater_bed' #combination_method: # Must be provided. Combination method used for the sensor. # Available options are 'max', 'min', 'mean'. #maximum_deviation: # Must be provided. Maximum permissible deviation between the sensors # to combine (e.g. 5 degrees). To disable it, use a large value (e.g. 999.9)","title":"Combined temperature sensor"},{"location":"Config_Reference.html#fans","text":"","title":"Fans"},{"location":"Config_Reference.html#fan","text":"Print cooling fan. [fan] pin: # Output pin controlling the fan. This parameter must be provided. #max_power: 1.0 # The maximum power (expressed as a value from 0.0 to 1.0) that the # pin may be set to. The value 1.0 allows the pin to be set fully # enabled for extended periods, while a value of 0.5 would allow the # pin to be enabled for no more than half the time. This setting may # be used to limit the total power output (over extended periods) to # the fan. If this value is less than 1.0 then fan speed requests # will be scaled between zero and max_power (for example, if # max_power is .9 and a fan speed of 80% is requested then the fan # power will be set to 72%). The default is 1.0. #shutdown_speed: 0 # The desired fan speed (expressed as a value from 0.0 to 1.0) if # the micro-controller software enters an error state. The default # is 0. #cycle_time: 0.010 # The amount of time (in seconds) for each PWM power cycle to the # fan. It is recommended this be 10 milliseconds or greater when # using software based PWM. The default is 0.010 seconds. #hardware_pwm: False # Enable this to use hardware PWM instead of software PWM. Most fans # do not work well with hardware PWM, so it is not recommended to # enable this unless there is an electrical requirement to switch at # very high speeds. When using hardware PWM the actual cycle time is # constrained by the implementation and may be significantly # different than the requested cycle_time. The default is False. #kick_start_time: 0.100 # Time (in seconds) to run the fan at full speed when either first # enabling or increasing it by more than 50% (helps get the fan # spinning). The default is 0.100 seconds. #off_below: 0.0 # The minimum input speed which will power the fan (expressed as a # value from 0.0 to 1.0). When a speed lower than off_below is # requested the fan will instead be turned off. This setting may be # used to prevent fan stalls and to ensure kick starts are # effective. The default is 0.0. # # This setting should be recalibrated whenever max_power is adjusted. # To calibrate this setting, start with off_below set to 0.0 and the # fan spinning. Gradually lower the fan speed to determine the lowest # input speed which reliably drives the fan without stalls. Set # off_below to the duty cycle corresponding to this value (for # example, 12% -> 0.12) or slightly higher. #tachometer_pin: # Tachometer input pin for monitoring fan speed. A pullup is generally # required. This parameter is optional. #tachometer_ppr: 2 # When tachometer_pin is specified, this is the number of pulses per # revolution of the tachometer signal. For a BLDC fan this is # normally half the number of poles. The default is 2. #tachometer_poll_interval: 0.0015 # When tachometer_pin is specified, this is the polling period of the # tachometer pin, in seconds. The default is 0.0015, which is fast # enough for fans below 10000 RPM at 2 PPR. This must be smaller than # 30/(tachometer_ppr*rpm), with some margin, where rpm is the # maximum speed (in RPM) of the fan. #enable_pin: # Optional pin to enable power to the fan. This can be useful for fans # with dedicated PWM inputs. Some of these fans stay on even at 0% PWM # input. In such a case, the PWM pin can be used normally, and e.g. a # ground-switched FET(standard fan pin) can be used to control power to # the fan.","title":"[fan]"},{"location":"Config_Reference.html#heater_fan","text":"Heater cooling fans (one may define any number of sections with a \"heater_fan\" prefix). A \"heater fan\" is a fan that will be enabled whenever its associated heater is active. By default, a heater_fan has a shutdown_speed equal to max_power. [heater_fan heatbreak_cooling_fan] #pin: #max_power: #shutdown_speed: #cycle_time: #hardware_pwm: #kick_start_time: #off_below: #tachometer_pin: #tachometer_ppr: #tachometer_poll_interval: #enable_pin: # See the \"fan\" section for a description of the above parameters. #heater: extruder # Name of the config section defining the heater that this fan is # associated with. If a comma separated list of heater names is # provided here, then the fan will be enabled when any of the given # heaters are enabled. The default is \"extruder\". #heater_temp: 50.0 # A temperature (in Celsius) that the heater must drop below before # the fan is disabled. The default is 50 Celsius. #fan_speed: 1.0 # The fan speed (expressed as a value from 0.0 to 1.0) that the fan # will be set to when its associated heater is enabled. The default # is 1.0","title":"[heater_fan]"},{"location":"Config_Reference.html#controller_fan","text":"Controller cooling fan (one may define any number of sections with a \"controller_fan\" prefix). A \"controller fan\" is a fan that will be enabled whenever its associated heater or its associated stepper driver is active. The fan will stop whenever an idle_timeout is reached to ensure no overheating will occur after deactivating a watched component. [controller_fan my_controller_fan] #pin: #max_power: #shutdown_speed: #cycle_time: #hardware_pwm: #kick_start_time: #off_below: #tachometer_pin: #tachometer_ppr: #tachometer_poll_interval: #enable_pin: # See the \"fan\" section for a description of the above parameters. #fan_speed: 1.0 # The fan speed (expressed as a value from 0.0 to 1.0) that the fan # will be set to when a heater or stepper driver is active. # The default is 1.0 #idle_timeout: # The amount of time (in seconds) after a stepper driver or heater # was active and the fan should be kept running. The default # is 30 seconds. #idle_speed: # The fan speed (expressed as a value from 0.0 to 1.0) that the fan # will be set to when a heater or stepper driver was active and # before the idle_timeout is reached. The default is fan_speed. #heater: #stepper: # Name of the config section defining the heater/stepper that this fan # is associated with. If a comma separated list of heater/stepper names # is provided here, then the fan will be enabled when any of the given # heaters/steppers are enabled. The default heater is \"extruder\", the # default stepper is all of them.","title":"[controller_fan]"},{"location":"Config_Reference.html#temperature_fan","text":"Temperature-triggered cooling fans (one may define any number of sections with a \"temperature_fan\" prefix). A \"temperature fan\" is a fan that will be enabled whenever its associated sensor is above a set temperature. By default, a temperature_fan has a shutdown_speed equal to max_power. See the command reference for additional information. [temperature_fan my_temp_fan] #pin: #max_power: #shutdown_speed: #cycle_time: #hardware_pwm: #kick_start_time: #off_below: #tachometer_pin: #tachometer_ppr: #tachometer_poll_interval: #enable_pin: # See the \"fan\" section for a description of the above parameters. #sensor_type: #sensor_pin: #control: #max_delta: #min_temp: #max_temp: # See the \"extruder\" section for a description of the above parameters. #pid_Kp: #pid_Ki: #pid_Kd: # The proportional (pid_Kp), integral (pid_Ki), and derivative # (pid_Kd) settings for the PID feedback control system. Klipper # evaluates the PID settings with the following general formula: # fan_pwm = max_power - (Kp*e + Ki*integral(e) - Kd*derivative(e)) / 255 # Where \"e\" is \"target_temperature - measured_temperature\" and # \"fan_pwm\" is the requested fan rate with 0.0 being full off and # 1.0 being full on. The pid_Kp, pid_Ki, and pid_Kd parameters must # be provided when the PID control algorithm is enabled. #pid_deriv_time: 2.0 # A time value (in seconds) over which temperature measurements will # be smoothed when using the PID control algorithm. This may reduce # the impact of measurement noise. The default is 2 seconds. #target_temp: 40.0 # A temperature (in Celsius) that will be the target temperature. # The default is 40 degrees. #max_speed: 1.0 # The fan speed (expressed as a value from 0.0 to 1.0) that the fan # will be set to when the sensor temperature exceeds the set value. # The default is 1.0. #min_speed: 0.3 # The minimum fan speed (expressed as a value from 0.0 to 1.0) that # the fan will be set to for PID temperature fans. # The default is 0.3. #gcode_id: # If set, the temperature will be reported in M105 queries using the # given id. The default is to not report the temperature via M105.","title":"[temperature_fan]"},{"location":"Config_Reference.html#fan_generic","text":"Manually controlled fan (one may define any number of sections with a \"fan_generic\" prefix). The speed of a manually controlled fan is set with the SET_FAN_SPEED gcode command . [fan_generic extruder_partfan] #pin: #max_power: #shutdown_speed: #cycle_time: #hardware_pwm: #kick_start_time: #off_below: #tachometer_pin: #tachometer_ppr: #tachometer_poll_interval: #enable_pin: # See the \"fan\" section for a description of the above parameters.","title":"[fan_generic]"},{"location":"Config_Reference.html#leds","text":"","title":"LEDs"},{"location":"Config_Reference.html#led","text":"Support for LEDs (and LED strips) controlled via micro-controller PWM pins (one may define any number of sections with an \"led\" prefix). See the command reference for more information. [led my_led] #red_pin: #green_pin: #blue_pin: #white_pin: # The pin controlling the given LED color. At least one of the above # parameters must be provided. #cycle_time: 0.010 # The amount of time (in seconds) per PWM cycle. It is recommended # this be 10 milliseconds or greater when using software based PWM. # The default is 0.010 seconds. #hardware_pwm: False # Enable this to use hardware PWM instead of software PWM. When # using hardware PWM the actual cycle time is constrained by the # implementation and may be significantly different than the # requested cycle_time. The default is False. #initial_RED: 0.0 #initial_GREEN: 0.0 #initial_BLUE: 0.0 #initial_WHITE: 0.0 # Sets the initial LED color. Each value should be between 0.0 and # 1.0. The default for each color is 0.","title":"[led]"},{"location":"Config_Reference.html#neopixel","text":"Neopixel (aka WS2812) LED support (one may define any number of sections with a \"neopixel\" prefix). See the command reference for more information. Note that the linux mcu implementation does not currently support directly connected neopixels. The current design using the Linux kernel interface does not allow this scenario because the kernel GPIO interface is not fast enough to provide the required pulse rates. [neopixel my_neopixel] pin: # The pin connected to the neopixel. This parameter must be # provided. #chain_count: # The number of Neopixel chips that are \"daisy chained\" to the # provided pin. The default is 1 (which indicates only a single # Neopixel is connected to the pin). #color_order: GRB # Set the pixel order required by the LED hardware (using a string # containing the letters R, G, B, W with W optional). Alternatively, # this may be a comma separated list of pixel orders - one for each # LED in the chain. The default is GRB. #initial_RED: 0.0 #initial_GREEN: 0.0 #initial_BLUE: 0.0 #initial_WHITE: 0.0 # See the \"led\" section for information on these parameters.","title":"[neopixel]"},{"location":"Config_Reference.html#dotstar","text":"Dotstar (aka APA102) LED support (one may define any number of sections with a \"dotstar\" prefix). See the command reference for more information. [dotstar my_dotstar] data_pin: # The pin connected to the data line of the dotstar. This parameter # must be provided. clock_pin: # The pin connected to the clock line of the dotstar. This parameter # must be provided. #chain_count: # See the \"neopixel\" section for information on this parameter. #initial_RED: 0.0 #initial_GREEN: 0.0 #initial_BLUE: 0.0 # See the \"led\" section for information on these parameters.","title":"[dotstar]"},{"location":"Config_Reference.html#pca9533","text":"PCA9533 LED support. The PCA9533 is used on the mightyboard. [pca9533 my_pca9533] #i2c_address: 98 # The i2c address that the chip is using on the i2c bus. Use 98 for # the PCA9533/1, 99 for the PCA9533/2. The default is 98. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #initial_RED: 0.0 #initial_GREEN: 0.0 #initial_BLUE: 0.0 #initial_WHITE: 0.0 # See the \"led\" section for information on these parameters.","title":"[pca9533]"},{"location":"Config_Reference.html#pca9632","text":"PCA9632 LED support. The PCA9632 is used on the FlashForge Dreamer. [pca9632 my_pca9632] #i2c_address: 98 # The i2c address that the chip is using on the i2c bus. This may be # 96, 97, 98, or 99. The default is 98. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #color_order: RGBW # Set the pixel order of the LED (using a string containing the # letters R, G, B, W). The default is RGBW. #initial_RED: 0.0 #initial_GREEN: 0.0 #initial_BLUE: 0.0 #initial_WHITE: 0.0 # See the \"led\" section for information on these parameters.","title":"[pca9632]"},{"location":"Config_Reference.html#additional-servos-buttons-and-other-pins","text":"","title":"Additional servos, buttons, and other pins"},{"location":"Config_Reference.html#servo","text":"Servos (one may define any number of sections with a \"servo\" prefix). The servos may be controlled using the SET_SERVO g-code command . For example: SET_SERVO SERVO=my_servo ANGLE=180 [servo my_servo] pin: # PWM output pin controlling the servo. This parameter must be # provided. #maximum_servo_angle: 180 # The maximum angle (in degrees) that this servo can be set to. The # default is 180 degrees. #minimum_pulse_width: 0.001 # The minimum pulse width time (in seconds). This should correspond # with an angle of 0 degrees. The default is 0.001 seconds. #maximum_pulse_width: 0.002 # The maximum pulse width time (in seconds). This should correspond # with an angle of maximum_servo_angle. The default is 0.002 # seconds. #initial_angle: # Initial angle (in degrees) to set the servo to. The default is to # not send any signal at startup. #initial_pulse_width: # Initial pulse width time (in seconds) to set the servo to. (This # is only valid if initial_angle is not set.) The default is to not # send any signal at startup.","title":"[servo]"},{"location":"Config_Reference.html#gcode_button","text":"Execute gcode when a button is pressed or released (or when a pin changes state). You can check the state of the button by using QUERY_BUTTON button=my_gcode_button . [gcode_button my_gcode_button] pin: # The pin on which the button is connected. This parameter must be # provided. #analog_range: # Two comma separated resistances (in Ohms) specifying the minimum # and maximum resistance range for the button. If analog_range is # provided then the pin must be an analog capable pin. The default # is to use digital gpio for the button. #analog_pullup_resistor: # The pullup resistance (in Ohms) when analog_range is specified. # The default is 4700 ohms. #press_gcode: # A list of G-Code commands to execute when the button is pressed. # G-Code templates are supported. This parameter must be provided. #release_gcode: # A list of G-Code commands to execute when the button is released. # G-Code templates are supported. The default is to not run any # commands on a button release. #debounce_delay: # A period of time in seconds to debounce events prior to running the # button gcode. If the button is pressed and released during this # delay, the entire button press is ignored. Default is 0.","title":"[gcode_button]"},{"location":"Config_Reference.html#output_pin","text":"Run-time configurable output pins (one may define any number of sections with an \"output_pin\" prefix). Pins configured here will be setup as output pins and one may modify them at run-time using \"SET_PIN PIN=my_pin VALUE=.1\" type extended g-code commands . [output_pin my_pin] pin: # The pin to configure as an output. This parameter must be # provided. #pwm: False # Set if the output pin should be capable of pulse-width-modulation. # If this is true, the value fields should be between 0 and 1; if it # is false the value fields should be either 0 or 1. The default is # False. #value: # The value to initially set the pin to during MCU configuration. # The default is 0 (for low voltage). #shutdown_value: # The value to set the pin to on an MCU shutdown event. The default # is 0 (for low voltage). #cycle_time: 0.100 # The amount of time (in seconds) per PWM cycle. It is recommended # this be 10 milliseconds or greater when using software based PWM. # The default is 0.100 seconds for pwm pins. #hardware_pwm: False # Enable this to use hardware PWM instead of software PWM. When # using hardware PWM the actual cycle time is constrained by the # implementation and may be significantly different than the # requested cycle_time. The default is False. #scale: # This parameter can be used to alter how the 'value' and # 'shutdown_value' parameters are interpreted for pwm pins. If # provided, then the 'value' parameter should be between 0.0 and # 'scale'. This may be useful when configuring a PWM pin that # controls a stepper voltage reference. The 'scale' can be set to # the equivalent stepper amperage if the PWM were fully enabled, and # then the 'value' parameter can be specified using the desired # amperage for the stepper. The default is to not scale the 'value' # parameter. #maximum_mcu_duration: #static_value: # These options are deprecated and should no longer be specified.","title":"[output_pin]"},{"location":"Config_Reference.html#pwm_tool","text":"Pulse width modulation digital output pins capable of high speed updates (one may define any number of sections with an \"output_pin\" prefix). Pins configured here will be setup as output pins and one may modify them at run-time using \"SET_PIN PIN=my_pin VALUE=.1\" type extended g-code commands . [pwm_tool my_tool] pin: # The pin to configure as an output. This parameter must be provided. #maximum_mcu_duration: # The maximum duration a non-shutdown value may be driven by the MCU # without an acknowledge from the host. # If host can not keep up with an update, the MCU will shutdown # and set all pins to their respective shutdown values. # Default: 0 (disabled) # Usual values are around 5 seconds. #value: #shutdown_value: #cycle_time: 0.100 #hardware_pwm: False #scale: # See the \"output_pin\" section for the definition of these parameters.","title":"[pwm_tool]"},{"location":"Config_Reference.html#pwm_cycle_time","text":"Run-time configurable output pins with dynamic pwm cycle timing (one may define any number of sections with an \"pwm_cycle_time\" prefix). Pins configured here will be setup as output pins and one may modify them at run-time using \"SET_PIN PIN=my_pin VALUE=.1 CYCLE_TIME=0.100\" type extended g-code commands . [pwm_cycle_time my_pin] pin: #value: #shutdown_value: #cycle_time: 0.100 #scale: # See the \"output_pin\" section for information on these parameters.","title":"[pwm_cycle_time]"},{"location":"Config_Reference.html#static_digital_output","text":"Statically configured digital output pins (one may define any number of sections with a \"static_digital_output\" prefix). Pins configured here will be setup as a GPIO output during MCU configuration. They can not be changed at run-time. [static_digital_output my_output_pins] pins: # A comma separated list of pins to be set as GPIO output pins. The # pin will be set to a high level unless the pin name is prefaced # with \"!\". This parameter must be provided.","title":"[static_digital_output]"},{"location":"Config_Reference.html#multi_pin","text":"Multiple pin outputs (one may define any number of sections with a \"multi_pin\" prefix). A multi_pin output creates an internal pin alias that can modify multiple output pins each time the alias pin is set. For example, one could define a \"[multi_pin my_fan]\" object containing two pins and then set \"pin=multi_pin:my_fan\" in the \"[fan]\" section - on each fan change both output pins would be updated. These aliases may not be used with stepper motor pins. [multi_pin my_multi_pin] pins: # A comma separated list of pins associated with this alias. This # parameter must be provided.","title":"[multi_pin]"},{"location":"Config_Reference.html#tmc-stepper-driver-configuration","text":"Configuration of Trinamic stepper motor drivers in UART/SPI mode. Additional information is in the TMC Drivers guide and in the command reference .","title":"TMC stepper driver configuration"},{"location":"Config_Reference.html#tmc2130","text":"Configure a TMC2130 stepper motor driver via SPI bus. To use this feature, define a config section with a \"tmc2130\" prefix followed by the name of the corresponding stepper config section (for example, \"[tmc2130 stepper_x]\"). [tmc2130 stepper_x] cs_pin: # The pin corresponding to the TMC2130 chip select line. This pin # will be set to low at the start of SPI messages and raised to high # after the message completes. This parameter must be provided. #spi_speed: #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #chain_position: #chain_length: # These parameters configure an SPI daisy chain. The two parameters # define the stepper position in the chain and the total chain length. # Position 1 corresponds to the stepper that connects to the MOSI signal. # The default is to not use an SPI daisy chain. #interpolate: True # If true, enable step interpolation (the driver will internally # step at a rate of 256 micro-steps). This interpolation does # introduce a small systemic positional deviation - see # TMC_Drivers.md for details. The default is True. run_current: # The amount of current (in amps RMS) to configure the driver to use # during stepper movement. This parameter must be provided. #hold_current: # The amount of current (in amps RMS) to configure the driver to use # when the stepper is not moving. Setting a hold_current is not # recommended (see TMC_Drivers.md for details). The default is to # not reduce the current. #sense_resistor: 0.110 # The resistance (in ohms) of the motor sense resistor. The default # is 0.110 ohms. #stealthchop_threshold: 0 # The velocity (in mm/s) to set the \"stealthChop\" threshold to. When # set, \"stealthChop\" mode will be enabled if the stepper motor # velocity is below this value. Note that the \"sensorless homing\" # code may temporarily override this setting during homing # operations. The default is 0, which disables \"stealthChop\" mode. #coolstep_threshold: # The velocity (in mm/s) to set the TMC driver internal \"CoolStep\" # threshold to. If set, the coolstep feature will be enabled when # the stepper motor velocity is near or above this value. Important # - if coolstep_threshold is set and \"sensorless homing\" is used, # then one must ensure that the homing speed is above the coolstep # threshold! The default is to not enable the coolstep feature. #high_velocity_threshold: # The velocity (in mm/s) to set the TMC driver internal \"high # velocity\" threshold (THIGH) to. This is typically used to disable # the \"CoolStep\" feature at high speeds. The default is to not set a # TMC \"high velocity\" threshold. #driver_MSLUT0: 2863314260 #driver_MSLUT1: 1251300522 #driver_MSLUT2: 608774441 #driver_MSLUT3: 269500962 #driver_MSLUT4: 4227858431 #driver_MSLUT5: 3048961917 #driver_MSLUT6: 1227445590 #driver_MSLUT7: 4211234 #driver_W0: 2 #driver_W1: 1 #driver_W2: 1 #driver_W3: 1 #driver_X1: 128 #driver_X2: 255 #driver_X3: 255 #driver_START_SIN: 0 #driver_START_SIN90: 247 # These fields control the Microstep Table registers directly. The optimal # wave table is specific to each motor and might vary with current. An # optimal configuration will have minimal print artifacts caused by # non-linear stepper movement. The values specified above are the default # values used by the driver. The value must be specified as a decimal integer # (hex form is not supported). In order to compute the wave table fields, # see the tmc2130 \"Calculation Sheet\" from the Trinamic website. #driver_IHOLDDELAY: 8 #driver_TPOWERDOWN: 0 #driver_TBL: 1 #driver_TOFF: 4 #driver_HEND: 7 #driver_HSTRT: 0 #driver_VHIGHFS: 0 #driver_VHIGHCHM: 0 #driver_PWM_AUTOSCALE: True #driver_PWM_FREQ: 1 #driver_PWM_GRAD: 4 #driver_PWM_AMPL: 128 #driver_FREEWHEEL: 0 #driver_SGT: 0 #driver_SEMIN: 0 #driver_SEUP: 0 #driver_SEMAX: 0 #driver_SEDN: 0 #driver_SEIMIN: 0 #driver_SFILT: 0 # Set the given register during the configuration of the TMC2130 # chip. This may be used to set custom motor parameters. The # defaults for each parameter are next to the parameter name in the # above list. #diag0_pin: #diag1_pin: # The micro-controller pin attached to one of the DIAG lines of the # TMC2130 chip. Only a single diag pin should be specified. The pin # is \"active low\" and is thus normally prefaced with \"^!\". Setting # this creates a \"tmc2130_stepper_x:virtual_endstop\" virtual pin # which may be used as the stepper's endstop_pin. Doing this enables # \"sensorless homing\". (Be sure to also set driver_SGT to an # appropriate sensitivity value.) The default is to not enable # sensorless homing.","title":"[tmc2130]"},{"location":"Config_Reference.html#tmc2208","text":"Configure a TMC2208 (or TMC2224) stepper motor driver via single wire UART. To use this feature, define a config section with a \"tmc2208\" prefix followed by the name of the corresponding stepper config section (for example, \"[tmc2208 stepper_x]\"). [tmc2208 stepper_x] uart_pin: # The pin connected to the TMC2208 PDN_UART line. This parameter # must be provided. #tx_pin: # If using separate receive and transmit lines to communicate with # the driver then set uart_pin to the receive pin and tx_pin to the # transmit pin. The default is to use uart_pin for both reading and # writing. #select_pins: # A comma separated list of pins to set prior to accessing the # tmc2208 UART. This may be useful for configuring an analog mux for # UART communication. The default is to not configure any pins. #interpolate: True # If true, enable step interpolation (the driver will internally # step at a rate of 256 micro-steps). This interpolation does # introduce a small systemic positional deviation - see # TMC_Drivers.md for details. The default is True. run_current: # The amount of current (in amps RMS) to configure the driver to use # during stepper movement. This parameter must be provided. #hold_current: # The amount of current (in amps RMS) to configure the driver to use # when the stepper is not moving. Setting a hold_current is not # recommended (see TMC_Drivers.md for details). The default is to # not reduce the current. #sense_resistor: 0.110 # The resistance (in ohms) of the motor sense resistor. The default # is 0.110 ohms. #stealthchop_threshold: 0 # The velocity (in mm/s) to set the \"stealthChop\" threshold to. When # set, \"stealthChop\" mode will be enabled if the stepper motor # velocity is below this value. Note that the \"sensorless homing\" # code may temporarily override this setting during homing # operations. The default is 0, which disables \"stealthChop\" mode. #driver_MULTISTEP_FILT: True #driver_IHOLDDELAY: 8 #driver_TPOWERDOWN: 20 #driver_TBL: 2 #driver_TOFF: 3 #driver_HEND: 0 #driver_HSTRT: 5 #driver_PWM_AUTOGRAD: True #driver_PWM_AUTOSCALE: True #driver_PWM_LIM: 12 #driver_PWM_REG: 8 #driver_PWM_FREQ: 1 #driver_PWM_GRAD: 14 #driver_PWM_OFS: 36 #driver_FREEWHEEL: 0 # Set the given register during the configuration of the TMC2208 # chip. This may be used to set custom motor parameters. The # defaults for each parameter are next to the parameter name in the # above list.","title":"[tmc2208]"},{"location":"Config_Reference.html#tmc2209","text":"Configure a TMC2209 stepper motor driver via single wire UART. To use this feature, define a config section with a \"tmc2209\" prefix followed by the name of the corresponding stepper config section (for example, \"[tmc2209 stepper_x]\"). [tmc2209 stepper_x] uart_pin: #tx_pin: #select_pins: #interpolate: True run_current: #hold_current: #sense_resistor: 0.110 #stealthchop_threshold: 0 # See the \"tmc2208\" section for the definition of these parameters. #coolstep_threshold: # The velocity (in mm/s) to set the TMC driver internal \"CoolStep\" # threshold to. If set, the coolstep feature will be enabled when # the stepper motor velocity is near or above this value. Important # - if coolstep_threshold is set and \"sensorless homing\" is used, # then one must ensure that the homing speed is above the coolstep # threshold! The default is to not enable the coolstep feature. #uart_address: # The address of the TMC2209 chip for UART messages (an integer # between 0 and 3). This is typically used when multiple TMC2209 # chips are connected to the same UART pin. The default is zero. #driver_MULTISTEP_FILT: True #driver_IHOLDDELAY: 8 #driver_TPOWERDOWN: 20 #driver_TBL: 2 #driver_TOFF: 3 #driver_HEND: 0 #driver_HSTRT: 5 #driver_PWM_AUTOGRAD: True #driver_PWM_AUTOSCALE: True #driver_PWM_LIM: 12 #driver_PWM_REG: 8 #driver_PWM_FREQ: 1 #driver_PWM_GRAD: 14 #driver_PWM_OFS: 36 #driver_FREEWHEEL: 0 #driver_SGTHRS: 0 #driver_SEMIN: 0 #driver_SEUP: 0 #driver_SEMAX: 0 #driver_SEDN: 0 #driver_SEIMIN: 0 # Set the given register during the configuration of the TMC2209 # chip. This may be used to set custom motor parameters. The # defaults for each parameter are next to the parameter name in the # above list. #diag_pin: # The micro-controller pin attached to the DIAG line of the TMC2209 # chip. The pin is normally prefaced with \"^\" to enable a pullup. # Setting this creates a \"tmc2209_stepper_x:virtual_endstop\" virtual # pin which may be used as the stepper's endstop_pin. Doing this # enables \"sensorless homing\". (Be sure to also set driver_SGTHRS to # an appropriate sensitivity value.) The default is to not enable # sensorless homing.","title":"[tmc2209]"},{"location":"Config_Reference.html#tmc2660","text":"Configure a TMC2660 stepper motor driver via SPI bus. To use this feature, define a config section with a tmc2660 prefix followed by the name of the corresponding stepper config section (for example, \"[tmc2660 stepper_x]\"). [tmc2660 stepper_x] cs_pin: # The pin corresponding to the TMC2660 chip select line. This pin # will be set to low at the start of SPI messages and set to high # after the message transfer completes. This parameter must be # provided. #spi_speed: 4000000 # SPI bus frequency used to communicate with the TMC2660 stepper # driver. The default is 4000000. #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #interpolate: True # If true, enable step interpolation (the driver will internally # step at a rate of 256 micro-steps). This only works if microsteps # is set to 16. Interpolation does introduce a small systemic # positional deviation - see TMC_Drivers.md for details. The default # is True. run_current: # The amount of current (in amps RMS) used by the driver during # stepper movement. This parameter must be provided. #sense_resistor: # The resistance (in ohms) of the motor sense resistor. This # parameter must be provided. #idle_current_percent: 100 # The percentage of the run_current the stepper driver will be # lowered to when the idle timeout expires (you need to set up the # timeout using a [idle_timeout] config section). The current will # be raised again once the stepper has to move again. Make sure to # set this to a high enough value such that the steppers do not lose # their position. There is also small delay until the current is # raised again, so take this into account when commanding fast moves # while the stepper is idling. The default is 100 (no reduction). #driver_TBL: 2 #driver_RNDTF: 0 #driver_HDEC: 0 #driver_CHM: 0 #driver_HEND: 3 #driver_HSTRT: 3 #driver_TOFF: 4 #driver_SEIMIN: 0 #driver_SEDN: 0 #driver_SEMAX: 0 #driver_SEUP: 0 #driver_SEMIN: 0 #driver_SFILT: 0 #driver_SGT: 0 #driver_SLPH: 0 #driver_SLPL: 0 #driver_DISS2G: 0 #driver_TS2G: 3 # Set the given parameter during the configuration of the TMC2660 # chip. This may be used to set custom driver parameters. The # defaults for each parameter are next to the parameter name in the # list above. See the TMC2660 datasheet about what each parameter # does and what the restrictions on parameter combinations are. Be # especially aware of the CHOPCONF register, where setting CHM to # either zero or one will lead to layout changes (the first bit of # HDEC) is interpreted as the MSB of HSTRT in this case).","title":"[tmc2660]"},{"location":"Config_Reference.html#tmc2240","text":"Configure a TMC2240 stepper motor driver via SPI bus or UART. To use this feature, define a config section with a \"tmc2240\" prefix followed by the name of the corresponding stepper config section (for example, \"[tmc2240 stepper_x]\"). [tmc2240 stepper_x] cs_pin: # The pin corresponding to the TMC2240 chip select line. This pin # will be set to low at the start of SPI messages and raised to high # after the message completes. This parameter must be provided. #spi_speed: #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #uart_pin: # The pin connected to the TMC2240 DIAG1/SW line. If this parameter # is provided UART communication is used rather then SPI. #chain_position: #chain_length: # These parameters configure an SPI daisy chain. The two parameters # define the stepper position in the chain and the total chain length. # Position 1 corresponds to the stepper that connects to the MOSI signal. # The default is to not use an SPI daisy chain. #interpolate: True # If true, enable step interpolation (the driver will internally # step at a rate of 256 micro-steps). The default is True. run_current: # The amount of current (in amps RMS) to configure the driver to use # during stepper movement. This parameter must be provided. #hold_current: # The amount of current (in amps RMS) to configure the driver to use # when the stepper is not moving. Setting a hold_current is not # recommended (see TMC_Drivers.md for details). The default is to # not reduce the current. #rref: 12000 # The resistance (in ohms) of the resistor between IREF and GND. The # default is 12000. #stealthchop_threshold: 0 # The velocity (in mm/s) to set the \"stealthChop\" threshold to. When # set, \"stealthChop\" mode will be enabled if the stepper motor # velocity is below this value. Note that the \"sensorless homing\" # code may temporarily override this setting during homing # operations. The default is 0, which disables \"stealthChop\" mode. #coolstep_threshold: # The velocity (in mm/s) to set the TMC driver internal \"CoolStep\" # threshold to. If set, the coolstep feature will be enabled when # the stepper motor velocity is near or above this value. Important # - if coolstep_threshold is set and \"sensorless homing\" is used, # then one must ensure that the homing speed is above the coolstep # threshold! The default is to not enable the coolstep feature. #high_velocity_threshold: # The velocity (in mm/s) to set the TMC driver internal \"high # velocity\" threshold (THIGH) to. This is typically used to disable # the \"CoolStep\" feature at high speeds. The default is to not set a # TMC \"high velocity\" threshold. #driver_MSLUT0: 2863314260 #driver_MSLUT1: 1251300522 #driver_MSLUT2: 608774441 #driver_MSLUT3: 269500962 #driver_MSLUT4: 4227858431 #driver_MSLUT5: 3048961917 #driver_MSLUT6: 1227445590 #driver_MSLUT7: 4211234 #driver_W0: 2 #driver_W1: 1 #driver_W2: 1 #driver_W3: 1 #driver_X1: 128 #driver_X2: 255 #driver_X3: 255 #driver_START_SIN: 0 #driver_START_SIN90: 247 #driver_OFFSET_SIN90: 0 # These fields control the Microstep Table registers directly. The optimal # wave table is specific to each motor and might vary with current. An # optimal configuration will have minimal print artifacts caused by # non-linear stepper movement. The values specified above are the default # values used by the driver. The value must be specified as a decimal integer # (hex form is not supported). In order to compute the wave table fields, # see the tmc2130 \"Calculation Sheet\" from the Trinamic website. # Additionally, this driver also has the OFFSET_SIN90 field which can be used # to tune a motor with unbalanced coils. See the `Sine Wave Lookup Table` # section in the datasheet for information about this field and how to tune # it. #driver_MULTISTEP_FILT: True #driver_IHOLDDELAY: 6 #driver_IRUNDELAY: 4 #driver_TPOWERDOWN: 10 #driver_TBL: 2 #driver_TOFF: 3 #driver_HEND: 2 #driver_HSTRT: 5 #driver_FD3: 0 #driver_TPFD: 4 #driver_CHM: 0 #driver_VHIGHFS: 0 #driver_VHIGHCHM: 0 #driver_DISS2G: 0 #driver_DISS2VS: 0 #driver_PWM_AUTOSCALE: True #driver_PWM_AUTOGRAD: True #driver_PWM_FREQ: 0 #driver_FREEWHEEL: 0 #driver_PWM_GRAD: 0 #driver_PWM_OFS: 29 #driver_PWM_REG: 4 #driver_PWM_LIM: 12 #driver_SGT: 0 #driver_SEMIN: 0 #driver_SEUP: 0 #driver_SEMAX: 0 #driver_SEDN: 0 #driver_SEIMIN: 0 #driver_SFILT: 0 #driver_SG4_ANGLE_OFFSET: 1 #driver_SLOPE_CONTROL: 0 # Set the given register during the configuration of the TMC2240 # chip. This may be used to set custom motor parameters. The # defaults for each parameter are next to the parameter name in the # above list. #diag0_pin: #diag1_pin: # The micro-controller pin attached to one of the DIAG lines of the # TMC2240 chip. Only a single diag pin should be specified. The pin # is \"active low\" and is thus normally prefaced with \"^!\". Setting # this creates a \"tmc2240_stepper_x:virtual_endstop\" virtual pin # which may be used as the stepper's endstop_pin. Doing this enables # \"sensorless homing\". (Be sure to also set driver_SGT to an # appropriate sensitivity value.) The default is to not enable # sensorless homing.","title":"[tmc2240]"},{"location":"Config_Reference.html#tmc5160","text":"Configure a TMC5160 stepper motor driver via SPI bus. To use this feature, define a config section with a \"tmc5160\" prefix followed by the name of the corresponding stepper config section (for example, \"[tmc5160 stepper_x]\"). [tmc5160 stepper_x] cs_pin: # The pin corresponding to the TMC5160 chip select line. This pin # will be set to low at the start of SPI messages and raised to high # after the message completes. This parameter must be provided. #spi_speed: #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #chain_position: #chain_length: # These parameters configure an SPI daisy chain. The two parameters # define the stepper position in the chain and the total chain length. # Position 1 corresponds to the stepper that connects to the MOSI signal. # The default is to not use an SPI daisy chain. #interpolate: True # If true, enable step interpolation (the driver will internally # step at a rate of 256 micro-steps). The default is True. run_current: # The amount of current (in amps RMS) to configure the driver to use # during stepper movement. This parameter must be provided. #hold_current: # The amount of current (in amps RMS) to configure the driver to use # when the stepper is not moving. Setting a hold_current is not # recommended (see TMC_Drivers.md for details). The default is to # not reduce the current. #sense_resistor: 0.075 # The resistance (in ohms) of the motor sense resistor. The default # is 0.075 ohms. #stealthchop_threshold: 0 # The velocity (in mm/s) to set the \"stealthChop\" threshold to. When # set, \"stealthChop\" mode will be enabled if the stepper motor # velocity is below this value. Note that the \"sensorless homing\" # code may temporarily override this setting during homing # operations. The default is 0, which disables \"stealthChop\" mode. #coolstep_threshold: # The velocity (in mm/s) to set the TMC driver internal \"CoolStep\" # threshold to. If set, the coolstep feature will be enabled when # the stepper motor velocity is near or above this value. Important # - if coolstep_threshold is set and \"sensorless homing\" is used, # then one must ensure that the homing speed is above the coolstep # threshold! The default is to not enable the coolstep feature. #high_velocity_threshold: # The velocity (in mm/s) to set the TMC driver internal \"high # velocity\" threshold (THIGH) to. This is typically used to disable # the \"CoolStep\" feature at high speeds. The default is to not set a # TMC \"high velocity\" threshold. #driver_MSLUT0: 2863314260 #driver_MSLUT1: 1251300522 #driver_MSLUT2: 608774441 #driver_MSLUT3: 269500962 #driver_MSLUT4: 4227858431 #driver_MSLUT5: 3048961917 #driver_MSLUT6: 1227445590 #driver_MSLUT7: 4211234 #driver_W0: 2 #driver_W1: 1 #driver_W2: 1 #driver_W3: 1 #driver_X1: 128 #driver_X2: 255 #driver_X3: 255 #driver_START_SIN: 0 #driver_START_SIN90: 247 # These fields control the Microstep Table registers directly. The optimal # wave table is specific to each motor and might vary with current. An # optimal configuration will have minimal print artifacts caused by # non-linear stepper movement. The values specified above are the default # values used by the driver. The value must be specified as a decimal integer # (hex form is not supported). In order to compute the wave table fields, # see the tmc2130 \"Calculation Sheet\" from the Trinamic website. #driver_MULTISTEP_FILT: True #driver_IHOLDDELAY: 6 #driver_TPOWERDOWN: 10 #driver_TBL: 2 #driver_TOFF: 3 #driver_HEND: 2 #driver_HSTRT: 5 #driver_FD3: 0 #driver_TPFD: 4 #driver_CHM: 0 #driver_VHIGHFS: 0 #driver_VHIGHCHM: 0 #driver_DISS2G: 0 #driver_DISS2VS: 0 #driver_PWM_AUTOSCALE: True #driver_PWM_AUTOGRAD: True #driver_PWM_FREQ: 0 #driver_FREEWHEEL: 0 #driver_PWM_GRAD: 0 #driver_PWM_OFS: 30 #driver_PWM_REG: 4 #driver_PWM_LIM: 12 #driver_SGT: 0 #driver_SEMIN: 0 #driver_SEUP: 0 #driver_SEMAX: 0 #driver_SEDN: 0 #driver_SEIMIN: 0 #driver_SFILT: 0 #driver_DRVSTRENGTH: 0 #driver_BBMCLKS: 4 #driver_BBMTIME: 0 #driver_FILT_ISENSE: 0 # Set the given register during the configuration of the TMC5160 # chip. This may be used to set custom motor parameters. The # defaults for each parameter are next to the parameter name in the # above list. #diag0_pin: #diag1_pin: # The micro-controller pin attached to one of the DIAG lines of the # TMC5160 chip. Only a single diag pin should be specified. The pin # is \"active low\" and is thus normally prefaced with \"^!\". Setting # this creates a \"tmc5160_stepper_x:virtual_endstop\" virtual pin # which may be used as the stepper's endstop_pin. Doing this enables # \"sensorless homing\". (Be sure to also set driver_SGT to an # appropriate sensitivity value.) The default is to not enable # sensorless homing.","title":"[tmc5160]"},{"location":"Config_Reference.html#run-time-stepper-motor-current-configuration","text":"","title":"Run-time stepper motor current configuration"},{"location":"Config_Reference.html#ad5206","text":"Statically configured AD5206 digipots connected via SPI bus (one may define any number of sections with an \"ad5206\" prefix). [ad5206 my_digipot] enable_pin: # The pin corresponding to the AD5206 chip select line. This pin # will be set to low at the start of SPI messages and raised to high # after the message completes. This parameter must be provided. #spi_speed: #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. #channel_1: #channel_2: #channel_3: #channel_4: #channel_5: #channel_6: # The value to statically set the given AD5206 channel to. This is # typically set to a number between 0.0 and 1.0 with 1.0 being the # highest resistance and 0.0 being the lowest resistance. However, # the range may be changed with the 'scale' parameter (see below). # If a channel is not specified then it is left unconfigured. #scale: # This parameter can be used to alter how the 'channel_x' parameters # are interpreted. If provided, then the 'channel_x' parameters # should be between 0.0 and 'scale'. This may be useful when the # AD5206 is used to set stepper voltage references. The 'scale' can # be set to the equivalent stepper amperage if the AD5206 were at # its highest resistance, and then the 'channel_x' parameters can be # specified using the desired amperage value for the stepper. The # default is to not scale the 'channel_x' parameters.","title":"[ad5206]"},{"location":"Config_Reference.html#mcp4451","text":"Statically configured MCP4451 digipot connected via I2C bus (one may define any number of sections with an \"mcp4451\" prefix). [mcp4451 my_digipot] i2c_address: # The i2c address that the chip is using on the i2c bus. This # parameter must be provided. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #wiper_0: #wiper_1: #wiper_2: #wiper_3: # The value to statically set the given MCP4451 \"wiper\" to. This is # typically set to a number between 0.0 and 1.0 with 1.0 being the # highest resistance and 0.0 being the lowest resistance. However, # the range may be changed with the 'scale' parameter (see below). # If a wiper is not specified then it is left unconfigured. #scale: # This parameter can be used to alter how the 'wiper_x' parameters # are interpreted. If provided, then the 'wiper_x' parameters should # be between 0.0 and 'scale'. This may be useful when the MCP4451 is # used to set stepper voltage references. The 'scale' can be set to # the equivalent stepper amperage if the MCP4451 were at its highest # resistance, and then the 'wiper_x' parameters can be specified # using the desired amperage value for the stepper. The default is # to not scale the 'wiper_x' parameters.","title":"[mcp4451]"},{"location":"Config_Reference.html#mcp4728","text":"Statically configured MCP4728 digital-to-analog converter connected via I2C bus (one may define any number of sections with an \"mcp4728\" prefix). [mcp4728 my_dac] #i2c_address: 96 # The i2c address that the chip is using on the i2c bus. The default # is 96. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. #channel_a: #channel_b: #channel_c: #channel_d: # The value to statically set the given MCP4728 channel to. This is # typically set to a number between 0.0 and 1.0 with 1.0 being the # highest voltage (2.048V) and 0.0 being the lowest voltage. # However, the range may be changed with the 'scale' parameter (see # below). If a channel is not specified then it is left # unconfigured. #scale: # This parameter can be used to alter how the 'channel_x' parameters # are interpreted. If provided, then the 'channel_x' parameters # should be between 0.0 and 'scale'. This may be useful when the # MCP4728 is used to set stepper voltage references. The 'scale' can # be set to the equivalent stepper amperage if the MCP4728 were at # its highest voltage (2.048V), and then the 'channel_x' parameters # can be specified using the desired amperage value for the # stepper. The default is to not scale the 'channel_x' parameters.","title":"[mcp4728]"},{"location":"Config_Reference.html#mcp4018","text":"Statically configured MCP4018 digipot connected via i2c (one may define any number of sections with an \"mcp4018\" prefix). [mcp4018 my_digipot] #i2c_address: 47 # The i2c address that the chip is using on the i2c bus. The default # is 47. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters. wiper: # The value to statically set the given MCP4018 \"wiper\" to. This is # typically set to a number between 0.0 and 1.0 with 1.0 being the # highest resistance and 0.0 being the lowest resistance. However, # the range may be changed with the 'scale' parameter (see below). # This parameter must be provided. #scale: # This parameter can be used to alter how the 'wiper' parameter is # interpreted. If provided, then the 'wiper' parameter should be # between 0.0 and 'scale'. This may be useful when the MCP4018 is # used to set stepper voltage references. The 'scale' can be set to # the equivalent stepper amperage if the MCP4018 is at its highest # resistance, and then the 'wiper' parameter can be specified using # the desired amperage value for the stepper. The default is to not # scale the 'wiper' parameter.","title":"[mcp4018]"},{"location":"Config_Reference.html#display-support","text":"","title":"Display support"},{"location":"Config_Reference.html#display","text":"Support for a display attached to the micro-controller. [display] lcd_type: # The type of LCD chip in use. This may be \"hd44780\", \"hd44780_spi\", # \"aip31068_spi\", \"st7920\", \"emulated_st7920\", \"uc1701\", \"ssd1306\", or # \"sh1106\". # See the display sections below for information on each type and # additional parameters they provide. This parameter must be # provided. #display_group: # The name of the display_data group to show on the display. This # controls the content of the screen (see the \"display_data\" section # for more information). The default is _default_20x4 for hd44780 or # aip31068_spi displays and _default_16x4 for other displays. #menu_timeout: # Timeout for menu. Being inactive this amount of seconds will # trigger menu exit or return to root menu when having autorun # enabled. The default is 0 seconds (disabled) #menu_root: # Name of the main menu section to show when clicking the encoder # on the home screen. The defaults is __main, and this shows the # the default menus as defined in klippy/extras/display/menu.cfg #menu_reverse_navigation: # When enabled it will reverse up and down directions for list # navigation. The default is False. This parameter is optional. #encoder_pins: # The pins connected to encoder. 2 pins must be provided when using # encoder. This parameter must be provided when using menu. #encoder_steps_per_detent: # How many steps the encoder emits per detent (\"click\"). If the # encoder takes two detents to move between entries or moves two # entries from one detent, try changing this. Allowed values are 2 # (half-stepping) or 4 (full-stepping). The default is 4. #click_pin: # The pin connected to 'enter' button or encoder 'click'. This # parameter must be provided when using menu. The presence of an # 'analog_range_click_pin' config parameter turns this parameter # from digital to analog. #back_pin: # The pin connected to 'back' button. This parameter is optional, # menu can be used without it. The presence of an # 'analog_range_back_pin' config parameter turns this parameter from # digital to analog. #up_pin: # The pin connected to 'up' button. This parameter must be provided # when using menu without encoder. The presence of an # 'analog_range_up_pin' config parameter turns this parameter from # digital to analog. #down_pin: # The pin connected to 'down' button. This parameter must be # provided when using menu without encoder. The presence of an # 'analog_range_down_pin' config parameter turns this parameter from # digital to analog. #kill_pin: # The pin connected to 'kill' button. This button will call # emergency stop. The presence of an 'analog_range_kill_pin' config # parameter turns this parameter from digital to analog. #analog_pullup_resistor: 4700 # The resistance (in ohms) of the pullup attached to the analog # button. The default is 4700 ohms. #analog_range_click_pin: # The resistance range for a 'enter' button. Range minimum and # maximum comma-separated values must be provided when using analog # button. #analog_range_back_pin: # The resistance range for a 'back' button. Range minimum and # maximum comma-separated values must be provided when using analog # button. #analog_range_up_pin: # The resistance range for a 'up' button. Range minimum and maximum # comma-separated values must be provided when using analog button. #analog_range_down_pin: # The resistance range for a 'down' button. Range minimum and # maximum comma-separated values must be provided when using analog # button. #analog_range_kill_pin: # The resistance range for a 'kill' button. Range minimum and # maximum comma-separated values must be provided when using analog # button.","title":"[display]"},{"location":"Config_Reference.html#hd44780-display","text":"Information on configuring hd44780 displays (which is used in \"RepRapDiscount 2004 Smart Controller\" type displays). [display] lcd_type: hd44780 # Set to \"hd44780\" for hd44780 displays. rs_pin: e_pin: d4_pin: d5_pin: d6_pin: d7_pin: # The pins connected to an hd44780 type lcd. These parameters must # be provided. #hd44780_protocol_init: True # Perform 8-bit/4-bit protocol initialization on an hd44780 display. # This is necessary on real hd44780 devices. However, one may need # to disable this on some \"clone\" devices. The default is True. #line_length: # Set the number of characters per line for an hd44780 type lcd. # Possible values are 20 (default) and 16. The number of lines is # fixed to 4. ...","title":"hd44780 display"},{"location":"Config_Reference.html#hd44780_spi-display","text":"Information on configuring an hd44780_spi display - a 20x04 display controlled via a hardware \"shift register\" (which is used in mightyboard based printers). [display] lcd_type: hd44780_spi # Set to \"hd44780_spi\" for hd44780_spi displays. latch_pin: spi_software_sclk_pin: spi_software_mosi_pin: spi_software_miso_pin: # The pins connected to the shift register controlling the display. # The spi_software_miso_pin needs to be set to an unused pin of the # printer mainboard as the shift register does not have a MISO pin, # but the software spi implementation requires this pin to be # configured. #hd44780_protocol_init: True # Perform 8-bit/4-bit protocol initialization on an hd44780 display. # This is necessary on real hd44780 devices. However, one may need # to disable this on some \"clone\" devices. The default is True. #line_length: # Set the number of characters per line for an hd44780 type lcd. # Possible values are 20 (default) and 16. The number of lines is # fixed to 4. ...","title":"hd44780_spi display"},{"location":"Config_Reference.html#aip31068_spi-display","text":"Information on configuring an aip31068_spi display - a very similar to hd44780_spi a 20x04 (20 symbols by 4 lines) display with slightly different internal protocol. [display] lcd_type: aip31068_spi latch_pin: spi_software_sclk_pin: spi_software_mosi_pin: spi_software_miso_pin: # The pins connected to the shift register controlling the display. # The spi_software_miso_pin needs to be set to an unused pin of the # printer mainboard as the shift register does not have a MISO pin, # but the software spi implementation requires this pin to be # configured. #line_length: # Set the number of characters per line for an hd44780 type lcd. # Possible values are 20 (default) and 16. The number of lines is # fixed to 4. ...","title":"aip31068_spi display"},{"location":"Config_Reference.html#st7920-display","text":"Information on configuring st7920 displays (which is used in \"RepRapDiscount 12864 Full Graphic Smart Controller\" type displays). [display] lcd_type: st7920 # Set to \"st7920\" for st7920 displays. cs_pin: sclk_pin: sid_pin: # The pins connected to an st7920 type lcd. These parameters must be # provided. ...","title":"st7920 display"},{"location":"Config_Reference.html#emulated_st7920-display","text":"Information on configuring an emulated st7920 display - found in some \"2.4 inch touchscreen devices\" and similar. [display] lcd_type: emulated_st7920 # Set to \"emulated_st7920\" for emulated_st7920 displays. en_pin: spi_software_sclk_pin: spi_software_mosi_pin: spi_software_miso_pin: # The pins connected to an emulated_st7920 type lcd. The en_pin # corresponds to the cs_pin of the st7920 type lcd, # spi_software_sclk_pin corresponds to sclk_pin and # spi_software_mosi_pin corresponds to sid_pin. The # spi_software_miso_pin needs to be set to an unused pin of the # printer mainboard as the st7920 as no MISO pin but the software # spi implementation requires this pin to be configured. ...","title":"emulated_st7920 display"},{"location":"Config_Reference.html#uc1701-display","text":"Information on configuring uc1701 displays (which is used in \"MKS Mini 12864\" type displays). [display] lcd_type: uc1701 # Set to \"uc1701\" for uc1701 displays. cs_pin: a0_pin: # The pins connected to a uc1701 type lcd. These parameters must be # provided. #rst_pin: # The pin connected to the \"rst\" pin on the lcd. If it is not # specified then the hardware must have a pull-up on the # corresponding lcd line. #contrast: # The contrast to set. The value may range from 0 to 63 and the # default is 40. ...","title":"uc1701 display"},{"location":"Config_Reference.html#ssd1306-and-sh1106-displays","text":"Information on configuring ssd1306 and sh1106 displays. [display] lcd_type: # Set to either \"ssd1306\" or \"sh1106\" for the given display type. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # Optional parameters available for displays connected via an i2c # bus. See the \"common I2C settings\" section for a description of # the above parameters. #cs_pin: #dc_pin: #spi_speed: #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # The pins connected to the lcd when in \"4-wire\" spi mode. See the # \"common SPI settings\" section for a description of the parameters # that start with \"spi_\". The default is to use i2c mode for the # display. #reset_pin: # A reset pin may be specified on the display. If it is not # specified then the hardware must have a pull-up on the # corresponding lcd line. #contrast: # The contrast to set. The value may range from 0 to 256 and the # default is 239. #vcomh: 0 # Set the Vcomh value on the display. This value is associated with # a \"smearing\" effect on some OLED displays. The value may range # from 0 to 63. Default is 0. #invert: False # TRUE inverts the pixels on certain OLED displays. The default is # False. #x_offset: 0 # Set the horizontal offset value on SH1106 displays. The default is # 0. ...","title":"ssd1306 and sh1106 displays"},{"location":"Config_Reference.html#display_data","text":"Support for displaying custom data on an lcd screen. One may create any number of display groups and any number of data items under those groups. The display will show all the data items for a given group if the display_group option in the [display] section is set to the given group name. A default set of display groups are automatically created. One can replace or extend these display_data items by overriding the defaults in the main printer.cfg config file. [display_data my_group_name my_data_name] position: # Comma separated row and column of the display position that should # be used to display the information. This parameter must be # provided. text: # The text to show at the given position. This field is evaluated # using command templates (see docs/Command_Templates.md). This # parameter must be provided.","title":"[display_data]"},{"location":"Config_Reference.html#display_template","text":"Display data text \"macros\" (one may define any number of sections with a display_template prefix). See the command templates document for information on template evaluation. This feature allows one to reduce repetitive definitions in display_data sections. One may use the builtin render() function in display_data sections to evaluate a template. For example, if one were to define [display_template my_template] then one could use { render('my_template') } in a display_data section. This feature can also be used for continuous LED updates using the SET_LED_TEMPLATE command. [display_template my_template_name] #param_: # One may specify any number of options with a \"param_\" prefix. The # given name will be assigned the given value (parsed as a Python # literal) and will be available during macro expansion. If the # parameter is passed in the call to render() then that value will # be used during macro expansion. For example, a config with # \"param_speed = 75\" might have a caller with # \"render('my_template_name', param_speed=80)\". Parameter names may # not use upper case characters. text: # The text to return when the this template is rendered. This field # is evaluated using command templates (see # docs/Command_Templates.md). This parameter must be provided.","title":"[display_template]"},{"location":"Config_Reference.html#display_glyph","text":"Display a custom glyph on displays that support it. The given name will be assigned the given display data which can then be referenced in the display templates by their name surrounded by two \"tilde\" symbols i.e. ~my_display_glyph~ See sample-glyphs.cfg for some examples. [display_glyph my_display_glyph] #data: # The display data, stored as 16 lines consisting of 16 bits (1 per # pixel) where '.' is a blank pixel and '*' is an on pixel (e.g., # \"****************\" to display a solid horizontal line). # Alternatively, one can use '0' for a blank pixel and '1' for an on # pixel. Put each display line into a separate config line. The # glyph must consist of exactly 16 lines with 16 bits each. This # parameter is optional. #hd44780_data: # Glyph to use on 20x4 hd44780 displays. The glyph must consist of # exactly 8 lines with 5 bits each. This parameter is optional. #hd44780_slot: # The hd44780 hardware index (0..7) to store the glyph at. If # multiple distinct images use the same slot then make sure to only # use one of those images in any given screen. This parameter is # required if hd44780_data is specified.","title":"[display_glyph]"},{"location":"Config_Reference.html#display-my_extra_display","text":"If a primary [display] section has been defined in printer.cfg as shown above it is possible to define multiple auxiliary displays. Note that auxiliary displays do not currently support menu functionality, thus they do not support the \"menu\" options or button configuration. [display my_extra_display] # See the \"display\" section for available parameters.","title":"[display my_extra_display]"},{"location":"Config_Reference.html#menu","text":"Customizable lcd display menus. A default set of menus are automatically created. One can replace or extend the menu by overriding the defaults in the main printer.cfg config file. See the command template document for information on menu attributes available during template rendering. # Common parameters available for all menu config sections. #[menu __some_list __some_name] #type: disabled # Permanently disabled menu element, only required attribute is 'type'. # Allows you to easily disable/hide existing menu items. #[menu some_name] #type: # One of command, input, list, text: # command - basic menu element with various script triggers # input - same like 'command' but has value changing capabilities. # Press will start/stop edit mode. # list - it allows for menu items to be grouped together in a # scrollable list. Add to the list by creating menu # configurations using \"some_list\" as a prefix - for # example: [menu some_list some_item_in_the_list] # vsdlist - same as 'list' but will append files from virtual sdcard # (will be removed in the future) #name: # Name of menu item - evaluated as a template. #enable: # Template that evaluates to True or False. #index: # Position where an item needs to be inserted in list. By default # the item is added at the end. #[menu some_list] #type: list #name: #enable: # See above for a description of these parameters. #[menu some_list some_command] #type: command #name: #enable: # See above for a description of these parameters. #gcode: # Script to run on button click or long click. Evaluated as a # template. #[menu some_list some_input] #type: input #name: #enable: # See above for a description of these parameters. #input: # Initial value to use when editing - evaluated as a template. # Result must be float. #input_min: # Minimum value of range - evaluated as a template. Default -99999. #input_max: # Maximum value of range - evaluated as a template. Default 99999. #input_step: # Editing step - Must be a positive integer or float value. It has # internal fast rate step. When \"(input_max - input_min) / # input_step > 100\" then fast rate step is 10 * input_step else fast # rate step is same input_step. #realtime: # This attribute accepts static boolean value. When enabled then # gcode script is run after each value change. The default is False. #gcode: # Script to run on button click, long click or value change. # Evaluated as a template. The button click will trigger the edit # mode start or end.","title":"[menu]"},{"location":"Config_Reference.html#filament-sensors","text":"","title":"Filament sensors"},{"location":"Config_Reference.html#filament_switch_sensor","text":"Filament Switch Sensor. Support for filament insert and runout detection using a switch sensor, such as an endstop switch. See the command reference for more information. [filament_switch_sensor my_sensor] #pause_on_runout: True # When set to True, a PAUSE will execute immediately after a runout # is detected. Note that if pause_on_runout is False and the # runout_gcode is omitted then runout detection is disabled. Default # is True. #runout_gcode: # A list of G-Code commands to execute after a filament runout is # detected. See docs/Command_Templates.md for G-Code format. If # pause_on_runout is set to True this G-Code will run after the # PAUSE is complete. The default is not to run any G-Code commands. #insert_gcode: # A list of G-Code commands to execute after a filament insert is # detected. See docs/Command_Templates.md for G-Code format. The # default is not to run any G-Code commands, which disables insert # detection. #event_delay: 3.0 # The minimum amount of time in seconds to delay between events. # Events triggered during this time period will be silently # ignored. The default is 3 seconds. #pause_delay: 0.5 # The amount of time to delay, in seconds, between the pause command # dispatch and execution of the runout_gcode. It may be useful to # increase this delay if OctoPrint exhibits strange pause behavior. # Default is 0.5 seconds. #debounce_delay: # A period of time in seconds to debounce events prior to running the # switch gcode. The switch must he held in a single state for at least # this long to activate. If the switch is toggled on/off during this delay, # the event is ignored. Default is 0. #switch_pin: # The pin on which the switch is connected. This parameter must be # provided.","title":"[filament_switch_sensor]"},{"location":"Config_Reference.html#filament_motion_sensor","text":"Filament Motion Sensor. Support for filament insert and runout detection using an encoder that toggles the output pin during filament movement through the sensor. See the command reference for more information. [filament_motion_sensor my_sensor] detection_length: 7.0 # The minimum length of filament pulled through the sensor to trigger # a state change on the switch_pin # Default is 7 mm. extruder: # The name of the extruder or extruder_stepper section this sensor # is associated with. This parameter must be provided. switch_pin: #pause_on_runout: #runout_gcode: #insert_gcode: #event_delay: #pause_delay: # See the \"filament_switch_sensor\" section for a description of the # above parameters.","title":"[filament_motion_sensor]"},{"location":"Config_Reference.html#tsl1401cl_filament_width_sensor","text":"TSLl401CL Based Filament Width Sensor. See the guide for more information. [tsl1401cl_filament_width_sensor] #pin: #default_nominal_filament_diameter: 1.75 # (mm) # Maximum allowed filament diameter difference as mm. #max_difference: 0.2 # The distance from sensor to the melting chamber as mm. #measurement_delay: 100","title":"[tsl1401cl_filament_width_sensor]"},{"location":"Config_Reference.html#hall_filament_width_sensor","text":"Hall filament width sensor (see Hall Filament Width Sensor ). [hall_filament_width_sensor] adc1: adc2: # Analog input pins connected to the sensor. These parameters must # be provided. #cal_dia1: 1.50 #cal_dia2: 2.00 # The calibration values (in mm) for the sensors. The default is # 1.50 for cal_dia1 and 2.00 for cal_dia2. #raw_dia1: 9500 #raw_dia2: 10500 # The raw calibration values for the sensors. The default is 9500 # for raw_dia1 and 10500 for raw_dia2. #default_nominal_filament_diameter: 1.75 # The nominal filament diameter. This parameter must be provided. #max_difference: 0.200 # Maximum allowed filament diameter difference in millimeters (mm). # If difference between nominal filament diameter and sensor output # is more than +- max_difference, extrusion multiplier is set back # to %100. The default is 0.200. #measurement_delay: 70 # The distance from sensor to the melting chamber/hot-end in # millimeters (mm). The filament between the sensor and the hot-end # will be treated as the default_nominal_filament_diameter. Host # module works with FIFO logic. It keeps each sensor value and # position in an array and POP them back in correct position. This # parameter must be provided. #enable: False # Sensor enabled or disabled after power on. The default is to # disable. #measurement_interval: 10 # The approximate distance (in mm) between sensor readings. The # default is 10mm. #logging: False # Out diameter to terminal and klipper.log can be turn on|of by # command. #min_diameter: 1.0 # Minimal diameter for trigger virtual filament_switch_sensor. #max_diameter: # Maximum diameter for triggering virtual filament_switch_sensor. # The default is default_nominal_filament_diameter + max_difference. #use_current_dia_while_delay: False # Use the current diameter instead of the nominal diameter while # the measurement delay has not run through. #pause_on_runout: #runout_gcode: #insert_gcode: #event_delay: #pause_delay: # See the \"filament_switch_sensor\" section for a description of the # above parameters.","title":"[hall_filament_width_sensor]"},{"location":"Config_Reference.html#load-cells","text":"","title":"Load Cells"},{"location":"Config_Reference.html#load_cell","text":"Load Cell. Uses an ADC sensor attached to a load cell to create a digital scale. [load_cell] sensor_type: # This must be one of the supported sensor types, see below. #counts_per_gram: # The floating point number of sensor counts that indicates 1 gram of force. # This value is calculated by the LOAD_CELL_CALIBRATE command. #reference_tare_counts: # The integer tare value, in raw sensor counts, taken when LOAD_CELL_CALIBRATE # is run. This is the default tare value when klipper starts up. #sensor_orientation: # Change the sensor's orientation. Can be either 'normal' or 'inverted'. # The default is 'normal'. Use 'inverted' if the sensor reports a # decreasing force value when placed under load.","title":"[load_cell]"},{"location":"Config_Reference.html#hx711","text":"This is a 24 bit low sample rate chip using \"bit-bang\" communications. It is suitable for filament scales. [load_cell] sensor_type: hx711 sclk_pin: # The pin connected to the HX711 clock line. This parameter must be provided. dout_pin: # The pin connected to the HX711 data output line. This parameter must be # provided. #gain: A-128 # Valid values for gain are: A-128, A-64, B-32. The default is A-128. # 'A' denotes the input channel and the number denotes the gain. Only the 3 # listed combinations are supported by the chip. Note that changing the gain # setting also selects the channel being read. #sample_rate: 80 # Valid values for sample_rate are 80 or 10. The default value is 80. # This must match the wiring of the chip. The sample rate cannot be changed # in software.","title":"HX711"},{"location":"Config_Reference.html#hx717","text":"This is the 4x higher sample rate version of the HX711, suitable for probing. [load_cell] sensor_type: hx717 sclk_pin: # The pin connected to the HX717 clock line. This parameter must be provided. dout_pin: # The pin connected to the HX717 data output line. This parameter must be # provided. #gain: A-128 # Valid values for gain are A-128, B-64, A-64, B-8. # 'A' denotes the input channel and the number denotes the gain setting. # Only the 4 listed combinations are supported by the chip. Note that # changing the gain setting also selects the channel being read. #sample_rate: 320 # Valid values for sample_rate are: 10, 20, 80, 320. The default is 320. # This must match the wiring of the chip. The sample rate cannot be changed # in software.","title":"HX717"},{"location":"Config_Reference.html#ads1220","text":"The ADS1220 is a 24 bit ADC supporting up to a 2Khz sample rate configurable in software. [load_cell] sensor_type: ads1220 cs_pin: # The pin connected to the ADS1220 chip select line. This parameter must # be provided. #spi_speed: 512000 # This chip supports 2 speeds: 256000 or 512000. The faster speed is only # enabled when one of the Turbo sample rates is used. The correct spi_speed # is selected based on the sample rate. #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters. data_ready_pin: # Pin connected to the ADS1220 data ready line. This parameter must be # provided. #gain: 128 # Valid gain values are 128, 64, 32, 16, 8, 4, 2, 1 # The default is 128 #pga_bypass: False # Disable the internal Programmable Gain Amplifier. If # True the PGA will be disabled for gains 1, 2, and 4. The PGA is always # enabled for gain settings 8 to 128, regardless of the pga_bypass setting. # If AVSS is used as an input pga_bypass is forced to True. # The default is False. #sample_rate: 660 # This chip supports two ranges of sample rates, Normal and Turbo. In turbo # mode the chip's internal clock runs twice as fast and the SPI communication # speed is also doubled. # Normal sample rates: 20, 45, 90, 175, 330, 600, 1000 # Turbo sample rates: 40, 90, 180, 350, 660, 1200, 2000 # The default is 660 #input_mux: # Input multiplexer configuration, select a pair of pins to use. The first pin # is the positive, AINP, and the second pin is the negative, AINN. Valid # values are: 'AIN0_AIN1', 'AIN0_AIN2', 'AIN0_AIN3', 'AIN1_AIN2', 'AIN1_AIN3', # 'AIN2_AIN3', 'AIN1_AIN0', 'AIN3_AIN2', 'AIN0_AVSS', 'AIN1_AVSS', 'AIN2_AVSS' # and 'AIN3_AVSS'. If AVSS is used the PGA is bypassed and the pga_bypass # setting will be forced to True. # The default is AIN0_AIN1. #vref: # The selected voltage reference. Valid values are: 'internal', 'REF0', 'REF1' # and 'analog_supply'. Default is 'internal'.","title":"ADS1220"},{"location":"Config_Reference.html#load_cell_probe","text":"Load Cell Probe. This combines the functionality of a [probe] and a [load_cell]. [load_cell_probe] sensor_type: # This must be one of the supported bulk ADC sensor types and support # load cell endstops on the mcu. #counts_per_gram: #reference_tare_counts: #sensor_orientation: # These parameters must be configured before the probe will operate. # See the [load_cell] section for further details. #force_safety_limit: 2000 # The safe limit for probing force relative to the reference_tare_counts on # the load_cell. The default is +/-2Kg. #trigger_force: 75.0 # The force that the probe will trigger at. 75g is the default. #drift_filter_cutoff_frequency: 0.8 # Enable optional continuous taring while homing & probing to reject drift. # The value is a frequency, in Hz, below which drift will be ignored. This # option requires the SciPy library. Default: None #drift_filter_delay: 2 # The delay, or 'order', of the drift filter. This controls the number of # samples required to make a trigger detection. Can be 1 or 2, the default # is 2. #buzz_filter_cutoff_frequency: 100.0 # The value is a frequency, in Hz, above which high frequency noise in the # load cell will be igfiltered outnored. This option requires the SciPy # library. Default: None #buzz_filter_delay: 2 # The delay, or 'order', of the buzz filter. This controls the number of # samples required to make a trigger detection. Can be 1 or 2, the default # is 2. #notch_filter_frequencies: 50, 60 # 1 or 2 frequencies, in Hz, to filter out of the load cell data. This is # intended to reject power line noise. This option requires the SciPy # library. Default: None #notch_filter_quality: 2.0 # Controls how narrow the range of frequencies are that the notch filter # removes. Larger numbers produce a narrower filter. Minimum value is 0.5 and # maximum is 3.0. Default: 2.0 #tare_time: # The rime in seconds used for taring the load_cell before each probe. The # default value is: 4 / 60 = 0.066. This collects samples from 4 cycles of # 60Hz mains power to cancel power line noise. #z_offset: #speed: #samples: #sample_retract_dist: #lift_speed: #samples_result: #samples_tolerance: #samples_tolerance_retries: #activate_gcode: #deactivate_gcode: # See the \"[probe]\" section for a description of the above parameters.","title":"[load_cell_probe]"},{"location":"Config_Reference.html#board-specific-hardware-support","text":"","title":"Board specific hardware support"},{"location":"Config_Reference.html#sx1509","text":"Configure an SX1509 I2C to GPIO expander. Due to the delay incurred by I2C communication you should NOT use SX1509 pins as stepper enable, step or dir pins or any other pin that requires fast bit-banging. They are best used as static or gcode controlled digital outputs or hardware-pwm pins for e.g. fans. One may define any number of sections with an \"sx1509\" prefix. Each expander provides a set of 16 pins (sx1509_my_sx1509:PIN_0 to sx1509_my_sx1509:PIN_15) which can be used in the printer configuration. See the generic-duet2-duex.cfg file for an example. [sx1509 my_sx1509] i2c_address: # I2C address used by this expander. Depending on the hardware # jumpers this is one out of the following addresses: 62 63 112 # 113. This parameter must be provided. #i2c_mcu: #i2c_bus: #i2c_software_scl_pin: #i2c_software_sda_pin: #i2c_speed: # See the \"common I2C settings\" section for a description of the # above parameters.","title":"[sx1509]"},{"location":"Config_Reference.html#samd_sercom","text":"SAMD SERCOM configuration to specify which pins to use on a given SERCOM. One may define any number of sections with a \"samd_sercom\" prefix. Each SERCOM must be configured prior to using it as SPI or I2C peripheral. Place this config section above any other section that makes use of SPI or I2C buses. [samd_sercom my_sercom] sercom: # The name of the sercom bus to configure in the micro-controller. # Available names are \"sercom0\", \"sercom1\", etc.. This parameter # must be provided. tx_pin: # MOSI pin for SPI communication, or SDA (data) pin for I2C # communication. The pin must have a valid pinmux configuration # for the given SERCOM peripheral. This parameter must be provided. #rx_pin: # MISO pin for SPI communication. This pin is not used for I2C # communication (I2C uses tx_pin for both sending and receiving). # The pin must have a valid pinmux configuration for the given # SERCOM peripheral. This parameter is optional. clk_pin: # CLK pin for SPI communication, or SCL (clock) pin for I2C # communication. The pin must have a valid pinmux configuration # for the given SERCOM peripheral. This parameter must be provided.","title":"[samd_sercom]"},{"location":"Config_Reference.html#adc_scaled","text":"Duet2 Maestro analog scaling by vref and vssa readings. Defining an adc_scaled section enables virtual adc pins (such as \"my_name:PB0\") that are automatically adjusted by the board's vref and vssa monitoring pins. Be sure to define this config section above any config sections that use one these virtual pins. See the generic-duet2-maestro.cfg file for an example. [adc_scaled my_name] vref_pin: # The ADC pin to use for VREF monitoring. This parameter must be # provided. vssa_pin: # The ADC pin to use for VSSA monitoring. This parameter must be # provided. #smooth_time: 2.0 # A time value (in seconds) over which the vref and vssa # measurements will be smoothed to reduce the impact of measurement # noise. The default is 2 seconds.","title":"[adc_scaled]"},{"location":"Config_Reference.html#ads1x1x","text":"ADS1013, ADS1014, ADS1015, ADS1113, ADS1114 and ADS1115 are I2C based Analog to Digital Converters that can be used for temperature sensors. They provide 4 analog input pins either as single line or as differential input. Note: Use caution if using this sensor to control heaters. The heater min_temp and max_temp are only verified in the host and only if the host is running and operating normally. (ADC inputs directly connected to the micro-controller verify min_temp and max_temp within the micro-controller and do not require a working connection to the host.) [ads1x1x my_ads1x1x] chip: ADS1115 #pga: 4.096V # Default value is 4.096V. The maximum voltage range used for the input. This # scales all values read from the ADC. Options are: 6.144V, 4.096V, 2.048V, # 1.024V, 0.512V, 0.256V #adc_voltage: 3.3 # The supply voltage for the device. This allows additional software scaling # for all values read from the ADC. i2c_mcu: host i2c_bus: i2c.1 #address_pin: GND # Default value is GND. There can be up to four addressed devices depending # upon wiring of the device. Check the datasheet for details. The i2c_address # can be specified directly instead of using the address_pin. The chip provides pins that can be used on other sensors. sensor_type: ... # Can be any thermistor or adc_temperature. sensor_pin: my_ads1x1x:AIN0 # A combination of the name of the ads1x1x chip and the pin. Possible # pin values are AIN0, AIN1, AIN2 and AIN3 for single ended lines and # DIFF01, DIFF03, DIFF13 and DIFF23 for differential between their # corresponding lines. For example # DIFF03 measures the differential between line 0 and 3. Only specific # combinations for the differentials are allowed.","title":"[ads1x1x]"},{"location":"Config_Reference.html#replicape","text":"Replicape support - see the beaglebone guide and the generic-replicape.cfg file for an example. # The \"replicape\" config section adds \"replicape:stepper_x_enable\" # virtual stepper enable pins (for steppers X, Y, Z, E, and H) and # \"replicape:power_x\" PWM output pins (for hotbed, e, h, fan0, fan1, # fan2, and fan3) that may then be used elsewhere in the config file. [replicape] revision: # The replicape hardware revision. Currently only revision \"B3\" is # supported. This parameter must be provided. #enable_pin: !gpio0_20 # The replicape global enable pin. The default is !gpio0_20 (aka # P9_41). host_mcu: # The name of the mcu config section that communicates with the # Klipper \"linux process\" mcu instance. This parameter must be # provided. #standstill_power_down: False # This parameter controls the CFG6_ENN line on all stepper # motors. True sets the enable lines to \"open\". The default is # False. #stepper_x_microstep_mode: #stepper_y_microstep_mode: #stepper_z_microstep_mode: #stepper_e_microstep_mode: #stepper_h_microstep_mode: # This parameter controls the CFG1 and CFG2 pins of the given # stepper motor driver. Available options are: disable, 1, 2, # spread2, 4, 16, spread4, spread16, stealth4, and stealth16. The # default is disable. #stepper_x_current: #stepper_y_current: #stepper_z_current: #stepper_e_current: #stepper_h_current: # The configured maximum current (in Amps) of the stepper motor # driver. This parameter must be provided if the stepper is not in a # disable mode. #stepper_x_chopper_off_time_high: #stepper_y_chopper_off_time_high: #stepper_z_chopper_off_time_high: #stepper_e_chopper_off_time_high: #stepper_h_chopper_off_time_high: # This parameter controls the CFG0 pin of the stepper motor driver # (True sets CFG0 high, False sets it low). The default is False. #stepper_x_chopper_hysteresis_high: #stepper_y_chopper_hysteresis_high: #stepper_z_chopper_hysteresis_high: #stepper_e_chopper_hysteresis_high: #stepper_h_chopper_hysteresis_high: # This parameter controls the CFG4 pin of the stepper motor driver # (True sets CFG4 high, False sets it low). The default is False. #stepper_x_chopper_blank_time_high: #stepper_y_chopper_blank_time_high: #stepper_z_chopper_blank_time_high: #stepper_e_chopper_blank_time_high: #stepper_h_chopper_blank_time_high: # This parameter controls the CFG5 pin of the stepper motor driver # (True sets CFG5 high, False sets it low). The default is True.","title":"[replicape]"},{"location":"Config_Reference.html#other-custom-modules","text":"","title":"Other Custom Modules"},{"location":"Config_Reference.html#palette2","text":"Palette 2 multimaterial support - provides a tighter integration supporting Palette 2 devices in connected mode. This modules also requires [virtual_sdcard] and [pause_resume] for full functionality. If you use this module, do not use the Palette 2 plugin for Octoprint as they will conflict, and 1 will fail to initialize properly likely aborting your print. If you use Octoprint and stream gcode over the serial port instead of printing from virtual_sd, then remove M1 and M0 from Pausing commands in Settings > Serial Connection > Firmware & protocol will prevent the need to start print on the Palette 2 and unpausing in Octoprint for your print to begin. [palette2] serial: # The serial port to connect to the Palette 2. #baud: 115200 # The baud rate to use. The default is 115200. #feedrate_splice: 0.8 # The feedrate to use when splicing, default is 0.8 #feedrate_normal: 1.0 # The feedrate to use after splicing, default is 1.0 #auto_load_speed: 2 # Extrude feedrate when autoloading, default is 2 (mm/s) #auto_cancel_variation: 0.1 # Auto cancel print when ping variation is above this threshold","title":"[palette2]"},{"location":"Config_Reference.html#angle","text":"Magnetic hall angle sensor support for reading stepper motor angle shaft measurements using a1333, as5047d, mt6816, mt6826s, or tle5012b SPI chips. The measurements are available via the API Server and motion analysis tool . See the G-Code reference for available commands. [angle my_angle_sensor] sensor_type: # The type of the magnetic hall sensor chip. Available choices are # \"a1333\", \"as5047d\", \"mt6816\", \"mt6826s\", and \"tle5012b\". This parameter must be # specified. #sample_period: 0.000400 # The query period (in seconds) to use during measurements. The # default is 0.000400 (which is 2500 samples per second). #stepper: # The name of the stepper that the angle sensor is attached to (eg, # \"stepper_x\"). Setting this value enables an angle calibration # tool. To use this feature, the Python \"numpy\" package must be # installed. The default is to not enable angle calibration for the # angle sensor. cs_pin: # The SPI enable pin for the sensor. This parameter must be provided. #spi_speed: #spi_bus: #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # See the \"common SPI settings\" section for a description of the # above parameters.","title":"[angle]"},{"location":"Config_Reference.html#common-bus-parameters","text":"","title":"Common bus parameters"},{"location":"Config_Reference.html#common-spi-settings","text":"The following parameters are generally available for devices using an SPI bus. #spi_speed: # The SPI speed (in hz) to use when communicating with the device. # The default depends on the type of device. #spi_bus: # If the micro-controller supports multiple SPI busses then one may # specify the micro-controller bus name here. The default depends on # the type of micro-controller. #spi_software_sclk_pin: #spi_software_mosi_pin: #spi_software_miso_pin: # Specify the above parameters to use \"software based SPI\". This # mode does not require micro-controller hardware support (typically # any general purpose pins may be used). The default is to not use # \"software spi\".","title":"Common SPI settings"},{"location":"Config_Reference.html#common-i2c-settings","text":"The following parameters are generally available for devices using an I2C bus. Note that Klipper's current micro-controller support for I2C is generally not tolerant to line noise. Unexpected errors on the I2C wires may result in Klipper raising a run-time error. Klipper's support for error recovery varies between each micro-controller type. It is generally recommended to only use I2C devices that are on the same printed circuit board as the micro-controller. Most Klipper micro-controller implementations only support an i2c_speed of 100000 ( standard mode , 100kbit/s). The Klipper \"Linux\" micro-controller supports a 400000 speed ( fast mode , 400kbit/s), but it must be set in the operating system and the i2c_speed parameter is otherwise ignored. The Klipper \"RP2040\" micro-controller and ATmega AVR family and some STM32 (F0, G0, G4, L4, F7, H7) support a rate of 400000 via the i2c_speed parameter. All other Klipper micro-controllers use a 100000 rate and ignore the i2c_speed parameter. #i2c_address: # The i2c address of the device. This must specified as a decimal # number (not in hex). The default depends on the type of device. #i2c_mcu: # The name of the micro-controller that the chip is connected to. # The default is \"mcu\". #i2c_bus: # If the micro-controller supports multiple I2C busses then one may # specify the micro-controller bus name here. The default depends on # the type of micro-controller. #i2c_software_scl_pin: #i2c_software_sda_pin: # Specify these parameters to use micro-controller software based # I2C \"bit-banging\" support. The two parameters should the two pins # on the micro-controller to use for the scl and sda wires. The # default is to use hardware based I2C support as specified by the # i2c_bus parameter. #i2c_speed: # The I2C speed (in Hz) to use when communicating with the device. # The Klipper implementation on most micro-controllers is hard-coded # to 100000 and changing this value has no effect. The default is # 100000. Linux, RP2040 and ATmega support 400000.","title":"Common I2C settings"},{"location":"Config_checks.html","text":"Configuration checks \u00b6 This document provides a list of steps to help confirm the pin settings in the Klipper printer.cfg file. It is a good idea to run through these steps after following the steps in the installation document . During this guide, it may be necessary to make changes to the Klipper config file. Be sure to issue a RESTART command after every change to the config file to ensure that the change takes effect (type \"restart\" in the Octoprint terminal tab and then click \"Send\"). It's also a good idea to issue a STATUS command after every RESTART to verify that the config file is successfully loaded. Verify temperature \u00b6 Start by verifying that temperatures are being properly reported. Navigate to the temperature graph section in the user interface. Verify that the temperature of the nozzle and bed (if applicable) are present and not increasing. If it is increasing, remove power from the printer. If the temperatures are not accurate, review the \"sensor_type\" and \"sensor_pin\" settings for the nozzle and/or bed. Verify M112 \u00b6 Navigate to the command console and issue an M112 command in the terminal box. This command requests Klipper to go into a \"shutdown\" state. It will cause an error to show, which can be cleared with a FIRMWARE_RESTART command in the command console. Octoprint will also require a reconnect. Then navigate to the temperature graph section and verify that temperatures continue to update and the temperatures are not increasing. If temperatures are increasing, remove power from the printer. Verify heaters \u00b6 Navigate to the temperature graph section and type in 50 followed by enter in the extruder/tool temperature box. The extruder temperature in the graph should start to increase (within about 30 seconds or so). Then go to the extruder temperature drop-down box and select \"Off\". After several minutes the temperature should start to return to its initial room temperature value. If the temperature does not increase then verify the \"heater_pin\" setting in the config. If the printer has a heated bed then perform the above test again with the bed. Verify stepper motor enable pin \u00b6 Verify that all of the printer axes can manually move freely (the stepper motors are disabled). If not, issue an M84 command to disable the motors. If any of the axes still can not move freely, then verify the stepper \"enable_pin\" configuration for the given axis. On most commodity stepper motor drivers, the motor enable pin is \"active low\" and therefore the enable pin should have a \"!\" before the pin (for example, \"enable_pin: !PA1\"). Verify endstops \u00b6 Manually move all the printer axes so that none of them are in contact with an endstop. Send a QUERY_ENDSTOPS command via the command console. It should respond with the current state of all of the configured endstops and they should all report a state of \"open\". For each of the endstops, rerun the QUERY_ENDSTOPS command while manually triggering the endstop. The QUERY_ENDSTOPS command should report the endstop as \"TRIGGERED\". If the endstop appears inverted (it reports \"open\" when triggered and vice-versa) then add a \"!\" to the pin definition (for example, \"endstop_pin: ^!PA2\"), or remove the \"!\" if there is already one present. If the endstop does not change at all then it generally indicates that the endstop is connected to a different pin. However, it may also require a change to the pullup setting of the pin (the '^' at the start of the endstop_pin name - most printers will use a pullup resistor and the '^' should be present). Verify stepper motors \u00b6 Use the STEPPER_BUZZ command to verify the connectivity of each stepper motor. Start by manually positioning the given axis to a midway point and then run STEPPER_BUZZ STEPPER=stepper_x in the command console. The STEPPER_BUZZ command will cause the given stepper to move one millimeter in a positive direction and then it will return to its starting position. (If the endstop is defined at position_endstop=0 then at the start of each movement the stepper will move away from the endstop.) It will perform this oscillation ten times. If the stepper does not move at all, then verify the \"enable_pin\" and \"step_pin\" settings for the stepper. If the stepper motor moves but does not return to its original position then verify the \"dir_pin\" setting. If the stepper motor oscillates in an incorrect direction, then it generally indicates that the \"dir_pin\" for the axis needs to be inverted. This is done by adding a '!' to the \"dir_pin\" in the printer config file (or removing it if one is already there). If the motor moves significantly more or significantly less than one millimeter then verify the \"rotation_distance\" setting. Run the above test for each stepper motor defined in the config file. (Set the STEPPER parameter of the STEPPER_BUZZ command to the name of the config section that is to be tested.) If there is no filament in the extruder then one can use STEPPER_BUZZ to verify the extruder motor connectivity (use STEPPER=extruder). Otherwise, it's best to test the extruder motor separately (see the next section). After verifying all endstops and verifying all stepper motors the homing mechanism should be tested. Issue a G28 command to home all axes. Remove power from the printer if it does not home properly. Rerun the endstop and stepper motor verification steps if necessary. Verify extruder motor \u00b6 To test the extruder motor it will be necessary to heat the extruder to a printing temperature. Navigate to the temperature graph section and select a target temperature from the temperature drop-down box (or manually enter an appropriate temperature). Wait for the printer to reach the desired temperature. Then navigate to the command console and click the \"Extrude\" button. Verify that the extruder motor turns in the correct direction. If it does not, see the troubleshooting tips in the previous section to confirm the \"enable_pin\", \"step_pin\", and \"dir_pin\" settings for the extruder. Calibrate PID settings \u00b6 Klipper supports PID control for the extruder and bed heaters. In order to use this control mechanism, it is necessary to calibrate the PID settings on each printer (PID settings found in other firmwares or in the example configuration files often work poorly). To calibrate the extruder, navigate to the command console and run the PID_CALIBRATE command. For example: PID_CALIBRATE HEATER=extruder TARGET=170 At the completion of the tuning test run SAVE_CONFIG to update the printer.cfg file the new PID settings. If the printer has a heated bed and it supports being driven by PWM (Pulse Width Modulation) then it is recommended to use PID control for the bed. (When the bed heater is controlled using the PID algorithm it may turn on and off ten times a second, which may not be suitable for heaters using a mechanical switch.) A typical bed PID calibration command is: PID_CALIBRATE HEATER=heater_bed TARGET=60 Next steps \u00b6 This guide is intended to help with basic verification of pin settings in the Klipper configuration file. Be sure to read the bed leveling guide. Also see the Slicers document for information on configuring a slicer with Klipper. After one has verified that basic printing works, it is a good idea to consider calibrating pressure advance . It may be necessary to perform other types of detailed printer calibration - a number of guides are available online to help with this (for example, do a web search for \"3d printer calibration\"). As an example, if you experience the effect called ringing, you may try following resonance compensation tuning guide.","title":"Configuration checks"},{"location":"Config_checks.html#configuration-checks","text":"This document provides a list of steps to help confirm the pin settings in the Klipper printer.cfg file. It is a good idea to run through these steps after following the steps in the installation document . During this guide, it may be necessary to make changes to the Klipper config file. Be sure to issue a RESTART command after every change to the config file to ensure that the change takes effect (type \"restart\" in the Octoprint terminal tab and then click \"Send\"). It's also a good idea to issue a STATUS command after every RESTART to verify that the config file is successfully loaded.","title":"Configuration checks"},{"location":"Config_checks.html#verify-temperature","text":"Start by verifying that temperatures are being properly reported. Navigate to the temperature graph section in the user interface. Verify that the temperature of the nozzle and bed (if applicable) are present and not increasing. If it is increasing, remove power from the printer. If the temperatures are not accurate, review the \"sensor_type\" and \"sensor_pin\" settings for the nozzle and/or bed.","title":"Verify temperature"},{"location":"Config_checks.html#verify-m112","text":"Navigate to the command console and issue an M112 command in the terminal box. This command requests Klipper to go into a \"shutdown\" state. It will cause an error to show, which can be cleared with a FIRMWARE_RESTART command in the command console. Octoprint will also require a reconnect. Then navigate to the temperature graph section and verify that temperatures continue to update and the temperatures are not increasing. If temperatures are increasing, remove power from the printer.","title":"Verify M112"},{"location":"Config_checks.html#verify-heaters","text":"Navigate to the temperature graph section and type in 50 followed by enter in the extruder/tool temperature box. The extruder temperature in the graph should start to increase (within about 30 seconds or so). Then go to the extruder temperature drop-down box and select \"Off\". After several minutes the temperature should start to return to its initial room temperature value. If the temperature does not increase then verify the \"heater_pin\" setting in the config. If the printer has a heated bed then perform the above test again with the bed.","title":"Verify heaters"},{"location":"Config_checks.html#verify-stepper-motor-enable-pin","text":"Verify that all of the printer axes can manually move freely (the stepper motors are disabled). If not, issue an M84 command to disable the motors. If any of the axes still can not move freely, then verify the stepper \"enable_pin\" configuration for the given axis. On most commodity stepper motor drivers, the motor enable pin is \"active low\" and therefore the enable pin should have a \"!\" before the pin (for example, \"enable_pin: !PA1\").","title":"Verify stepper motor enable pin"},{"location":"Config_checks.html#verify-endstops","text":"Manually move all the printer axes so that none of them are in contact with an endstop. Send a QUERY_ENDSTOPS command via the command console. It should respond with the current state of all of the configured endstops and they should all report a state of \"open\". For each of the endstops, rerun the QUERY_ENDSTOPS command while manually triggering the endstop. The QUERY_ENDSTOPS command should report the endstop as \"TRIGGERED\". If the endstop appears inverted (it reports \"open\" when triggered and vice-versa) then add a \"!\" to the pin definition (for example, \"endstop_pin: ^!PA2\"), or remove the \"!\" if there is already one present. If the endstop does not change at all then it generally indicates that the endstop is connected to a different pin. However, it may also require a change to the pullup setting of the pin (the '^' at the start of the endstop_pin name - most printers will use a pullup resistor and the '^' should be present).","title":"Verify endstops"},{"location":"Config_checks.html#verify-stepper-motors","text":"Use the STEPPER_BUZZ command to verify the connectivity of each stepper motor. Start by manually positioning the given axis to a midway point and then run STEPPER_BUZZ STEPPER=stepper_x in the command console. The STEPPER_BUZZ command will cause the given stepper to move one millimeter in a positive direction and then it will return to its starting position. (If the endstop is defined at position_endstop=0 then at the start of each movement the stepper will move away from the endstop.) It will perform this oscillation ten times. If the stepper does not move at all, then verify the \"enable_pin\" and \"step_pin\" settings for the stepper. If the stepper motor moves but does not return to its original position then verify the \"dir_pin\" setting. If the stepper motor oscillates in an incorrect direction, then it generally indicates that the \"dir_pin\" for the axis needs to be inverted. This is done by adding a '!' to the \"dir_pin\" in the printer config file (or removing it if one is already there). If the motor moves significantly more or significantly less than one millimeter then verify the \"rotation_distance\" setting. Run the above test for each stepper motor defined in the config file. (Set the STEPPER parameter of the STEPPER_BUZZ command to the name of the config section that is to be tested.) If there is no filament in the extruder then one can use STEPPER_BUZZ to verify the extruder motor connectivity (use STEPPER=extruder). Otherwise, it's best to test the extruder motor separately (see the next section). After verifying all endstops and verifying all stepper motors the homing mechanism should be tested. Issue a G28 command to home all axes. Remove power from the printer if it does not home properly. Rerun the endstop and stepper motor verification steps if necessary.","title":"Verify stepper motors"},{"location":"Config_checks.html#verify-extruder-motor","text":"To test the extruder motor it will be necessary to heat the extruder to a printing temperature. Navigate to the temperature graph section and select a target temperature from the temperature drop-down box (or manually enter an appropriate temperature). Wait for the printer to reach the desired temperature. Then navigate to the command console and click the \"Extrude\" button. Verify that the extruder motor turns in the correct direction. If it does not, see the troubleshooting tips in the previous section to confirm the \"enable_pin\", \"step_pin\", and \"dir_pin\" settings for the extruder.","title":"Verify extruder motor"},{"location":"Config_checks.html#calibrate-pid-settings","text":"Klipper supports PID control for the extruder and bed heaters. In order to use this control mechanism, it is necessary to calibrate the PID settings on each printer (PID settings found in other firmwares or in the example configuration files often work poorly). To calibrate the extruder, navigate to the command console and run the PID_CALIBRATE command. For example: PID_CALIBRATE HEATER=extruder TARGET=170 At the completion of the tuning test run SAVE_CONFIG to update the printer.cfg file the new PID settings. If the printer has a heated bed and it supports being driven by PWM (Pulse Width Modulation) then it is recommended to use PID control for the bed. (When the bed heater is controlled using the PID algorithm it may turn on and off ten times a second, which may not be suitable for heaters using a mechanical switch.) A typical bed PID calibration command is: PID_CALIBRATE HEATER=heater_bed TARGET=60","title":"Calibrate PID settings"},{"location":"Config_checks.html#next-steps","text":"This guide is intended to help with basic verification of pin settings in the Klipper configuration file. Be sure to read the bed leveling guide. Also see the Slicers document for information on configuring a slicer with Klipper. After one has verified that basic printing works, it is a good idea to consider calibrating pressure advance . It may be necessary to perform other types of detailed printer calibration - a number of guides are available online to help with this (for example, do a web search for \"3d printer calibration\"). As an example, if you experience the effect called ringing, you may try following resonance compensation tuning guide.","title":"Next steps"},{"location":"Contact.html","text":"Contact \u00b6 This document provides contact information for Klipper. Discourse Forum \u00b6 There is a Klipper Community Discourse server for \"forum\" style discussions on Klipper. Note that Discourse is not Discord. Discord Chat \u00b6 There is a Discord server dedicated to Klipper at: https://discord.klipper3d.org . Note that Discord is not Discourse. This server is run by a community of Klipper enthusiasts dedicated to discussions on Klipper. It allows users to chat with other users in real-time. I have a question about Klipper \u00b6 Many questions we receive are already answered in the Klipper documentation . Please be sure to to read the documentation and follow the directions provided there. It is also possible to search for similar questions in the Klipper Discourse Forum . If you are interested in sharing your knowledge and experience with other Klipper users then you can join the Klipper Discourse Forum or Klipper Discord Chat . Both are communities where Klipper users can discuss Klipper with other users. If you have a general question or are experiencing general printing problems, then also consider a general 3d-printing forum or a forum dedicated to the printer hardware. I have a feature request \u00b6 All new features require someone interested and able to implement that feature. If you are interested in helping to implement or test a new feature, you can search for ongoing developments in the Klipper Discourse Forum . There is also Klipper Discord Chat for discussions between collaborators. Help! It doesn't work! \u00b6 If you are experiencing problems we recommend you carefully read the Klipper documentation and double check that all steps were followed. If you are experiencing a printing problem, then we recommend carefully inspecting the printer hardware (all joints, wires, screws, etc.) and verify nothing is abnormal. We find most printing problems are not related to the Klipper software. If you do find a problem with the printer hardware then consider searching general 3d-printing forums or forums dedicated to the printer hardware. It is also possible to search for similar issues in the Klipper Discourse Forum . If you are interested in sharing your knowledge and experience with other Klipper users then you can join the Klipper Discourse Forum or Klipper Discord Chat . Both are communities where Klipper users can discuss Klipper with other users. I found a bug in the Klipper software \u00b6 Klipper is an open-source project and we appreciate when collaborators diagnose errors in the software. Problems should be reported in the Klipper Discourse Forum . There is important information that will be needed in order to fix a bug. Please follow these steps: Make sure you are running unmodified code from https://github.com/Klipper3d/klipper . If the code has been modified or is obtained from another source, then you should reproduce the problem on the unmodified code from https://github.com/Klipper3d/klipper prior to reporting. If possible, run an M112 command immediately after the undesirable event occurs. This causes Klipper to go into a \"shutdown state\" and it will cause additional debugging information to be written to the log file. Obtain the Klipper log file from the event. The log file has been engineered to answer common questions the Klipper developers have about the software and its environment (software version, hardware type, configuration, event timing, and hundreds of other questions). Dedicated Klipper web interfaces have the ability to directly obtain the Klipper log file. It's the easiest way to obtain the log when using one of these interfaces. Otherwise, an \"scp\" or \"sftp\" utility is needed to copy the log file to your desktop computer. The \"scp\" utility comes standard with Linux and MacOS desktops. There are freely available scp utilities for other desktops (eg, WinSCP). The log file may be located in the ~/printer_data/logs/klippy.log file (if using a graphical scp utility, look for the \"printer_data\" folder, then the \"logs\" folder under that, then the klippy.log file). The log file may alternatively be located in the /tmp/klippy.log file (if using a graphical scp utility that can not directly copy /tmp/klippy.log then repeatedly click on .. or \"parent folder\" until reaching the root directory, click on the tmp folder, and then select the klippy.log file). Copy the log file to your desktop so that it can be attached to an issue report. Do not modify the log file in any way; do not provide a snippet of the log. Only the full unmodified log file provides the necessary information. It is a good idea to compress the log file with zip or gzip. Open a new topic on the Klipper Discourse Forum and provide a clear description of the problem. Other Klipper contributors will need to understand what steps were taken, what the desired outcome was, and what outcome actually occurred. The compressed Klipper log file should be attached to that topic. I am making changes that I'd like to include in Klipper \u00b6 Klipper is open-source software and we appreciate new contributions. See the CONTRIBUTING document for information. There are several documents for developers . If you have questions on the code then you can also ask in the Klipper Discourse Forum or on the Klipper Discord Chat . Professional Services \u00b6 Custom software development, software support, and solutions: https://ko-fi.com/koconnor","title":"Contact"},{"location":"Contact.html#contact","text":"This document provides contact information for Klipper.","title":"Contact"},{"location":"Contact.html#discourse-forum","text":"There is a Klipper Community Discourse server for \"forum\" style discussions on Klipper. Note that Discourse is not Discord.","title":"Discourse Forum"},{"location":"Contact.html#discord-chat","text":"There is a Discord server dedicated to Klipper at: https://discord.klipper3d.org . Note that Discord is not Discourse. This server is run by a community of Klipper enthusiasts dedicated to discussions on Klipper. It allows users to chat with other users in real-time.","title":"Discord Chat"},{"location":"Contact.html#i-have-a-question-about-klipper","text":"Many questions we receive are already answered in the Klipper documentation . Please be sure to to read the documentation and follow the directions provided there. It is also possible to search for similar questions in the Klipper Discourse Forum . If you are interested in sharing your knowledge and experience with other Klipper users then you can join the Klipper Discourse Forum or Klipper Discord Chat . Both are communities where Klipper users can discuss Klipper with other users. If you have a general question or are experiencing general printing problems, then also consider a general 3d-printing forum or a forum dedicated to the printer hardware.","title":"I have a question about Klipper"},{"location":"Contact.html#i-have-a-feature-request","text":"All new features require someone interested and able to implement that feature. If you are interested in helping to implement or test a new feature, you can search for ongoing developments in the Klipper Discourse Forum . There is also Klipper Discord Chat for discussions between collaborators.","title":"I have a feature request"},{"location":"Contact.html#help-it-doesnt-work","text":"If you are experiencing problems we recommend you carefully read the Klipper documentation and double check that all steps were followed. If you are experiencing a printing problem, then we recommend carefully inspecting the printer hardware (all joints, wires, screws, etc.) and verify nothing is abnormal. We find most printing problems are not related to the Klipper software. If you do find a problem with the printer hardware then consider searching general 3d-printing forums or forums dedicated to the printer hardware. It is also possible to search for similar issues in the Klipper Discourse Forum . If you are interested in sharing your knowledge and experience with other Klipper users then you can join the Klipper Discourse Forum or Klipper Discord Chat . Both are communities where Klipper users can discuss Klipper with other users.","title":"Help! It doesn't work!"},{"location":"Contact.html#i-found-a-bug-in-the-klipper-software","text":"Klipper is an open-source project and we appreciate when collaborators diagnose errors in the software. Problems should be reported in the Klipper Discourse Forum . There is important information that will be needed in order to fix a bug. Please follow these steps: Make sure you are running unmodified code from https://github.com/Klipper3d/klipper . If the code has been modified or is obtained from another source, then you should reproduce the problem on the unmodified code from https://github.com/Klipper3d/klipper prior to reporting. If possible, run an M112 command immediately after the undesirable event occurs. This causes Klipper to go into a \"shutdown state\" and it will cause additional debugging information to be written to the log file. Obtain the Klipper log file from the event. The log file has been engineered to answer common questions the Klipper developers have about the software and its environment (software version, hardware type, configuration, event timing, and hundreds of other questions). Dedicated Klipper web interfaces have the ability to directly obtain the Klipper log file. It's the easiest way to obtain the log when using one of these interfaces. Otherwise, an \"scp\" or \"sftp\" utility is needed to copy the log file to your desktop computer. The \"scp\" utility comes standard with Linux and MacOS desktops. There are freely available scp utilities for other desktops (eg, WinSCP). The log file may be located in the ~/printer_data/logs/klippy.log file (if using a graphical scp utility, look for the \"printer_data\" folder, then the \"logs\" folder under that, then the klippy.log file). The log file may alternatively be located in the /tmp/klippy.log file (if using a graphical scp utility that can not directly copy /tmp/klippy.log then repeatedly click on .. or \"parent folder\" until reaching the root directory, click on the tmp folder, and then select the klippy.log file). Copy the log file to your desktop so that it can be attached to an issue report. Do not modify the log file in any way; do not provide a snippet of the log. Only the full unmodified log file provides the necessary information. It is a good idea to compress the log file with zip or gzip. Open a new topic on the Klipper Discourse Forum and provide a clear description of the problem. Other Klipper contributors will need to understand what steps were taken, what the desired outcome was, and what outcome actually occurred. The compressed Klipper log file should be attached to that topic.","title":"I found a bug in the Klipper software"},{"location":"Contact.html#i-am-making-changes-that-id-like-to-include-in-klipper","text":"Klipper is open-source software and we appreciate new contributions. See the CONTRIBUTING document for information. There are several documents for developers . If you have questions on the code then you can also ask in the Klipper Discourse Forum or on the Klipper Discord Chat .","title":"I am making changes that I'd like to include in Klipper"},{"location":"Contact.html#professional-services","text":"Custom software development, software support, and solutions: https://ko-fi.com/koconnor","title":"Professional Services"},{"location":"Debugging.html","text":"Debugging \u00b6 This document describes some of the Klipper debugging tools. Running the regression tests \u00b6 The main Klipper GitHub repository uses \"github actions\" to run a series of regression tests. It can be useful to run some of these tests locally. The source code \"whitespace check\" can be run with: ./scripts/check_whitespace.sh The Klippy regression test suite requires \"data dictionaries\" from many platforms. The easiest way to obtain them is to download them from github . Once the data dictionaries are downloaded, use the following to run the regression suite: tar xfz klipper-dict-20??????.tar.gz ~/klippy-env/bin/python ~/klipper/scripts/test_klippy.py -d dict/ ~/klipper/test/klippy/*.test Manually sending commands to the micro-controller \u00b6 Normally, the host klippy.py process would be used to translate gcode commands to Klipper micro-controller commands. However, it's also possible to manually send these MCU commands (functions marked with the DECL_COMMAND() macro in the Klipper source code). To do so, run: ~/klippy-env/bin/python ./klippy/console.py /tmp/pseudoserial See the \"HELP\" command within the tool for more information on its functionality. Some command-line options are available. For more information run: ~/klippy-env/bin/python ./klippy/console.py --help Translating gcode files to micro-controller commands \u00b6 The Klippy host code can run in a batch mode to produce the low-level micro-controller commands associated with a gcode file. Inspecting these low-level commands is useful when trying to understand the actions of the low-level hardware. It can also be useful to compare the difference in micro-controller commands after a code change. To run Klippy in this batch mode, there is a one time step necessary to generate the micro-controller \"data dictionary\". This is done by compiling the micro-controller code to obtain the out/klipper.dict file: make menuconfig make Once the above is done it is possible to run Klipper in batch mode (see installation for the steps necessary to build the python virtual environment and a printer.cfg file): ~/klippy-env/bin/python ./klippy/klippy.py ~/printer.cfg -i test.gcode -o test.serial -v -d out/klipper.dict The above will produce a file test.serial with the binary serial output. This output can be translated to readable text with: ~/klippy-env/bin/python ./klippy/parsedump.py out/klipper.dict test.serial > test.txt The resulting file test.txt contains a human readable list of micro-controller commands. The batch mode disables certain response / request commands in order to function. As a result, there will be some differences between actual commands and the above output. The generated data is useful for testing and inspection; it is not useful for sending to a real micro-controller. Motion analysis and data logging \u00b6 Klipper supports logging its internal motion history, which can be later analyzed. To use this feature, Klipper must be started with the API Server enabled. Data logging is enabled with the data_logger.py tool. For example: ~/klipper/scripts/motan/data_logger.py /tmp/klippy_uds mylog This command will connect to the Klipper API Server, subscribe to status and motion information, and log the results. Two files are generated - a compressed data file and an index file (eg, mylog.json.gz and mylog.index.gz ). After starting the logging, it is possible to complete prints and other actions - the logging will continue in the background. When done logging, hit ctrl-c to exit from the data_logger.py tool. The resulting files can be read and graphed using the motan_graph.py tool. To generate graphs on a Raspberry Pi, a one time step is necessary to install the \"matplotlib\" package: sudo apt-get update sudo apt-get install python-matplotlib However, it may be more convenient to copy the data files to a desktop class machine along with the Python code in the scripts/motan/ directory. The motion analysis scripts should run on any machine with a recent version of Python and Matplotlib installed. Graphs can be generated with a command like the following: ~/klipper/scripts/motan/motan_graph.py mylog -o mygraph.png One can use the -g option to specify the datasets to graph (it takes a Python literal containing a list of lists). For example: ~/klipper/scripts/motan/motan_graph.py mylog -g '[[\"trapq(toolhead,velocity)\"], [\"trapq(toolhead,accel)\"]]' The list of available datasets can be found using the -l option - for example: ~/klipper/scripts/motan/motan_graph.py -l It is also possible to specify matplotlib plot options for each dataset: ~/klipper/scripts/motan/motan_graph.py mylog -g '[[\"trapq(toolhead,velocity)?color=red&alpha=0.4\"]]' Many matplotlib options are available; some examples are \"color\", \"label\", \"alpha\", and \"linestyle\". The motan_graph.py tool supports several other command-line options - use the --help option to see a list. It may also be convenient to view/modify the motan_graph.py script itself. The raw data logs produced by the data_logger.py tool follow the format described in the API Server . It may be useful to inspect the data with a Unix command like the following: gunzip < mylog.json.gz | tr '\\03' '\\n' | less Generating load graphs \u00b6 The Klippy log file (/tmp/klippy.log) stores statistics on bandwidth, micro-controller load, and host buffer load. It can be useful to graph these statistics after a print. To generate a graph, a one time step is necessary to install the \"matplotlib\" package: sudo apt-get update sudo apt-get install python-matplotlib Then graphs can be produced with: ~/klipper/scripts/graphstats.py /tmp/klippy.log -o loadgraph.png One can then view the resulting loadgraph.png file. Different graphs can be produced. For more information run: ~/klipper/scripts/graphstats.py --help Extracting information from the klippy.log file \u00b6 The Klippy log file (/tmp/klippy.log) also contains debugging information. There is a logextract.py script that may be useful when analyzing a micro-controller shutdown or similar problem. It is typically run with something like: mkdir work_directory cd work_directory cp /tmp/klippy.log . ~/klipper/scripts/logextract.py ./klippy.log The script will extract the printer config file and will extract MCU shutdown information. The information dumps from an MCU shutdown (if present) will be reordered by timestamp to assist in diagnosing cause and effect scenarios. Testing with simulavr \u00b6 The simulavr tool enables one to simulate an Atmel ATmega micro-controller. This section describes how one can run test gcode files through simulavr. It is recommended to run this on a desktop class machine (not a Raspberry Pi) as it does require significant cpu to run efficiently. To use simulavr, download the simulavr package and compile with python support. Note that the build system may need to have some packages (such as swig) installed in order to build the python module. git clone git://git.savannah.nongnu.org/simulavr.git cd simulavr make python make build Make sure a file like ./build/pysimulavr/_pysimulavr.*.so is present after the above compilation: ls ./build/pysimulavr/_pysimulavr.*.so This command should report a specific file (e.g. ./build/pysimulavr/_pysimulavr.cpython-39-x86_64-linux-gnu.so ) and not an error. If you are on a Debian-based system (Debian, Ubuntu, etc.) you can install the following packages and generate *.deb files for system-wide installation of simulavr: sudo apt update sudo apt install g++ make cmake swig rst2pdf help2man texinfo make cfgclean python debian sudo dpkg -i build/debian/python3-simulavr*.deb To compile Klipper for use in simulavr, run: cd /path/to/klipper make menuconfig and compile the micro-controller software for an AVR atmega644p and select SIMULAVR software emulation support. Then one can compile Klipper (run make ) and then start the simulation with: PYTHONPATH=/path/to/simulavr/build/pysimulavr/ ./scripts/avrsim.py out/klipper.elf Note that if you have installed python3-simulavr system-wide, you do not need to set PYTHONPATH , and can simply run the simulator as ./scripts/avrsim.py out/klipper.elf Then, with simulavr running in another window, one can run the following to read gcode from a file (eg, \"test.gcode\"), process it with Klippy, and send it to Klipper running in simulavr (see installation for the steps necessary to build the python virtual environment): ~/klippy-env/bin/python ./klippy/klippy.py config/generic-simulavr.cfg -i test.gcode -v Using simulavr with gtkwave \u00b6 One useful feature of simulavr is its ability to create signal wave generation files with the exact timing of events. To do this, follow the directions above, but run avrsim.py with a command-line like the following: PYTHONPATH=/path/to/simulavr/src/python/ ./scripts/avrsim.py out/klipper.elf -t PORTA.PORT,PORTC.PORT The above would create a file avrsim.vcd with information on each change to the GPIOs on PORTA and PORTB. This could then be viewed using gtkwave with: gtkwave avrsim.vcd","title":"Debugging"},{"location":"Debugging.html#debugging","text":"This document describes some of the Klipper debugging tools.","title":"Debugging"},{"location":"Debugging.html#running-the-regression-tests","text":"The main Klipper GitHub repository uses \"github actions\" to run a series of regression tests. It can be useful to run some of these tests locally. The source code \"whitespace check\" can be run with: ./scripts/check_whitespace.sh The Klippy regression test suite requires \"data dictionaries\" from many platforms. The easiest way to obtain them is to download them from github . Once the data dictionaries are downloaded, use the following to run the regression suite: tar xfz klipper-dict-20??????.tar.gz ~/klippy-env/bin/python ~/klipper/scripts/test_klippy.py -d dict/ ~/klipper/test/klippy/*.test","title":"Running the regression tests"},{"location":"Debugging.html#manually-sending-commands-to-the-micro-controller","text":"Normally, the host klippy.py process would be used to translate gcode commands to Klipper micro-controller commands. However, it's also possible to manually send these MCU commands (functions marked with the DECL_COMMAND() macro in the Klipper source code). To do so, run: ~/klippy-env/bin/python ./klippy/console.py /tmp/pseudoserial See the \"HELP\" command within the tool for more information on its functionality. Some command-line options are available. For more information run: ~/klippy-env/bin/python ./klippy/console.py --help","title":"Manually sending commands to the micro-controller"},{"location":"Debugging.html#translating-gcode-files-to-micro-controller-commands","text":"The Klippy host code can run in a batch mode to produce the low-level micro-controller commands associated with a gcode file. Inspecting these low-level commands is useful when trying to understand the actions of the low-level hardware. It can also be useful to compare the difference in micro-controller commands after a code change. To run Klippy in this batch mode, there is a one time step necessary to generate the micro-controller \"data dictionary\". This is done by compiling the micro-controller code to obtain the out/klipper.dict file: make menuconfig make Once the above is done it is possible to run Klipper in batch mode (see installation for the steps necessary to build the python virtual environment and a printer.cfg file): ~/klippy-env/bin/python ./klippy/klippy.py ~/printer.cfg -i test.gcode -o test.serial -v -d out/klipper.dict The above will produce a file test.serial with the binary serial output. This output can be translated to readable text with: ~/klippy-env/bin/python ./klippy/parsedump.py out/klipper.dict test.serial > test.txt The resulting file test.txt contains a human readable list of micro-controller commands. The batch mode disables certain response / request commands in order to function. As a result, there will be some differences between actual commands and the above output. The generated data is useful for testing and inspection; it is not useful for sending to a real micro-controller.","title":"Translating gcode files to micro-controller commands"},{"location":"Debugging.html#motion-analysis-and-data-logging","text":"Klipper supports logging its internal motion history, which can be later analyzed. To use this feature, Klipper must be started with the API Server enabled. Data logging is enabled with the data_logger.py tool. For example: ~/klipper/scripts/motan/data_logger.py /tmp/klippy_uds mylog This command will connect to the Klipper API Server, subscribe to status and motion information, and log the results. Two files are generated - a compressed data file and an index file (eg, mylog.json.gz and mylog.index.gz ). After starting the logging, it is possible to complete prints and other actions - the logging will continue in the background. When done logging, hit ctrl-c to exit from the data_logger.py tool. The resulting files can be read and graphed using the motan_graph.py tool. To generate graphs on a Raspberry Pi, a one time step is necessary to install the \"matplotlib\" package: sudo apt-get update sudo apt-get install python-matplotlib However, it may be more convenient to copy the data files to a desktop class machine along with the Python code in the scripts/motan/ directory. The motion analysis scripts should run on any machine with a recent version of Python and Matplotlib installed. Graphs can be generated with a command like the following: ~/klipper/scripts/motan/motan_graph.py mylog -o mygraph.png One can use the -g option to specify the datasets to graph (it takes a Python literal containing a list of lists). For example: ~/klipper/scripts/motan/motan_graph.py mylog -g '[[\"trapq(toolhead,velocity)\"], [\"trapq(toolhead,accel)\"]]' The list of available datasets can be found using the -l option - for example: ~/klipper/scripts/motan/motan_graph.py -l It is also possible to specify matplotlib plot options for each dataset: ~/klipper/scripts/motan/motan_graph.py mylog -g '[[\"trapq(toolhead,velocity)?color=red&alpha=0.4\"]]' Many matplotlib options are available; some examples are \"color\", \"label\", \"alpha\", and \"linestyle\". The motan_graph.py tool supports several other command-line options - use the --help option to see a list. It may also be convenient to view/modify the motan_graph.py script itself. The raw data logs produced by the data_logger.py tool follow the format described in the API Server . It may be useful to inspect the data with a Unix command like the following: gunzip < mylog.json.gz | tr '\\03' '\\n' | less","title":"Motion analysis and data logging"},{"location":"Debugging.html#generating-load-graphs","text":"The Klippy log file (/tmp/klippy.log) stores statistics on bandwidth, micro-controller load, and host buffer load. It can be useful to graph these statistics after a print. To generate a graph, a one time step is necessary to install the \"matplotlib\" package: sudo apt-get update sudo apt-get install python-matplotlib Then graphs can be produced with: ~/klipper/scripts/graphstats.py /tmp/klippy.log -o loadgraph.png One can then view the resulting loadgraph.png file. Different graphs can be produced. For more information run: ~/klipper/scripts/graphstats.py --help","title":"Generating load graphs"},{"location":"Debugging.html#extracting-information-from-the-klippylog-file","text":"The Klippy log file (/tmp/klippy.log) also contains debugging information. There is a logextract.py script that may be useful when analyzing a micro-controller shutdown or similar problem. It is typically run with something like: mkdir work_directory cd work_directory cp /tmp/klippy.log . ~/klipper/scripts/logextract.py ./klippy.log The script will extract the printer config file and will extract MCU shutdown information. The information dumps from an MCU shutdown (if present) will be reordered by timestamp to assist in diagnosing cause and effect scenarios.","title":"Extracting information from the klippy.log file"},{"location":"Debugging.html#testing-with-simulavr","text":"The simulavr tool enables one to simulate an Atmel ATmega micro-controller. This section describes how one can run test gcode files through simulavr. It is recommended to run this on a desktop class machine (not a Raspberry Pi) as it does require significant cpu to run efficiently. To use simulavr, download the simulavr package and compile with python support. Note that the build system may need to have some packages (such as swig) installed in order to build the python module. git clone git://git.savannah.nongnu.org/simulavr.git cd simulavr make python make build Make sure a file like ./build/pysimulavr/_pysimulavr.*.so is present after the above compilation: ls ./build/pysimulavr/_pysimulavr.*.so This command should report a specific file (e.g. ./build/pysimulavr/_pysimulavr.cpython-39-x86_64-linux-gnu.so ) and not an error. If you are on a Debian-based system (Debian, Ubuntu, etc.) you can install the following packages and generate *.deb files for system-wide installation of simulavr: sudo apt update sudo apt install g++ make cmake swig rst2pdf help2man texinfo make cfgclean python debian sudo dpkg -i build/debian/python3-simulavr*.deb To compile Klipper for use in simulavr, run: cd /path/to/klipper make menuconfig and compile the micro-controller software for an AVR atmega644p and select SIMULAVR software emulation support. Then one can compile Klipper (run make ) and then start the simulation with: PYTHONPATH=/path/to/simulavr/build/pysimulavr/ ./scripts/avrsim.py out/klipper.elf Note that if you have installed python3-simulavr system-wide, you do not need to set PYTHONPATH , and can simply run the simulator as ./scripts/avrsim.py out/klipper.elf Then, with simulavr running in another window, one can run the following to read gcode from a file (eg, \"test.gcode\"), process it with Klippy, and send it to Klipper running in simulavr (see installation for the steps necessary to build the python virtual environment): ~/klippy-env/bin/python ./klippy/klippy.py config/generic-simulavr.cfg -i test.gcode -v","title":"Testing with simulavr"},{"location":"Debugging.html#using-simulavr-with-gtkwave","text":"One useful feature of simulavr is its ability to create signal wave generation files with the exact timing of events. To do this, follow the directions above, but run avrsim.py with a command-line like the following: PYTHONPATH=/path/to/simulavr/src/python/ ./scripts/avrsim.py out/klipper.elf -t PORTA.PORT,PORTC.PORT The above would create a file avrsim.vcd with information on each change to the GPIOs on PORTA and PORTB. This could then be viewed using gtkwave with: gtkwave avrsim.vcd","title":"Using simulavr with gtkwave"},{"location":"Delta_Calibrate.html","text":"Delta calibration \u00b6 This document describes Klipper's automatic calibration system for \"delta\" style printers. Delta calibration involves finding the tower endstop positions, tower angles, delta radius, and delta arm lengths. These settings control printer motion on a delta printer. Each one of these parameters has a non-obvious and non-linear impact and it is difficult to calibrate them manually. In contrast, the software calibration code can provide excellent results with just a few minutes of time. No special probing hardware is necessary. Ultimately, the delta calibration is dependent on the precision of the tower endstop switches. If one is using Trinamic stepper motor drivers then consider enabling endstop phase detection to improve the accuracy of those switches. Automatic vs manual probing \u00b6 Klipper supports calibrating the delta parameters via a manual probing method or via an automatic Z probe. A number of delta printer kits come with automatic Z probes that are not sufficiently accurate (specifically, small differences in arm length can cause effector tilt which can skew an automatic probe). If using an automatic probe then first calibrate the probe and then check for a probe location bias . If the automatic probe has a bias of more than 25 microns (.025mm) then use manual probing instead. Manual probing only takes a few minutes and it eliminates error introduced by the probe. If using a probe that is mounted on the side of the hotend (that is, it has an X or Y offset) then note that performing delta calibration will invalidate the results of probe calibration. These types of probes are rarely suitable for use on a delta (because minor effector tilt will result in a probe location bias). If using the probe anyway, then be sure to rerun probe calibration after any delta calibration. Basic delta calibration \u00b6 Klipper has a DELTA_CALIBRATE command that can perform basic delta calibration. This command probes seven different points on the bed and calculates new values for the tower angles, tower endstops, and delta radius. In order to perform this calibration the initial delta parameters (arm lengths, radius, and endstop positions) must be provided and they should have an accuracy to within a few millimeters. Most delta printer kits will provide these parameters - configure the printer with these initial defaults and then go on to run the DELTA_CALIBRATE command as described below. If no defaults are available then search online for a delta calibration guide that can provide a basic starting point. During the delta calibration process it may be necessary for the printer to probe below what would otherwise be considered the plane of the bed. It is typical to permit this during calibration by updating the config so that the printer's minimum_z_position=-5 . (Once calibration completes, one can remove this setting from the config.) There are two ways to perform the probing - manual probing ( DELTA_CALIBRATE METHOD=manual ) and automatic probing ( DELTA_CALIBRATE ). The manual probing method will move the head near the bed and then wait for the user to follow the steps described at \"the paper test\" to determine the actual distance between the nozzle and bed at the given location. To perform the basic probe, make sure the config has a [delta_calibrate] section defined and then run the tool: G28 DELTA_CALIBRATE METHOD=manual After probing the seven points new delta parameters will be calculated. Save and apply these parameters by running: SAVE_CONFIG The basic calibration should provide delta parameters that are accurate enough for basic printing. If this is a new printer, this is a good time to print some basic objects and verify general functionality. Enhanced delta calibration \u00b6 The basic delta calibration generally does a good job of calculating delta parameters such that the nozzle is the correct distance from the bed. However, it does not attempt to calibrate X and Y dimensional accuracy. It's a good idea to perform an enhanced delta calibration to verify dimensional accuracy. This calibration procedure requires printing a test object and measuring parts of that test object with digital calipers. Prior to running an enhanced delta calibration one must run the basic delta calibration (via the DELTA_CALIBRATE command) and save the results (via the SAVE_CONFIG command). Make sure there hasn't been any notable change to the printer configuration nor hardware since last performing a basic delta calibration (if unsure, rerun the basic delta calibration , including SAVE_CONFIG, just prior to printing the test object described below.) Use a slicer to generate G-Code from the docs/prints/calibrate_size.stl file. Slice the object using a slow speed (eg, 40mm/s). If possible, use a stiff plastic (such as PLA) for the object. The object has a diameter of 140mm. If this is too large for the printer then one can scale it down (but be sure to uniformly scale both the X and Y axes). If the printer supports significantly larger prints then this object can also be increased in size. A larger size can improve the measurement accuracy, but good print adhesion is more important than a larger print size. Print the test object and wait for it to fully cool. The commands described below must be run with the same printer settings used to print the calibration object (don't run DELTA_CALIBRATE between printing and measuring, or do something that would otherwise change the printer configuration). If possible, perform the measurements described below while the object is still attached to the print bed, but don't worry if the part detaches from the bed - just try to avoid bending the object when performing the measurements. Start by measuring the distance between the center pillar and the pillar next to the \"A\" label (which should also be pointing towards the \"A\" tower). Then go counterclockwise and measure the distances between the center pillar and the other pillars (distance from center to pillar across from C label, distance from center to pillar with B label, etc.). Enter these parameters into Klipper with a comma separated list of floating point numbers: DELTA_ANALYZE CENTER_DISTS=,,,,, 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=,,,,, 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=,, 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=,,,,, 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=,,,,, 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=,,,,, 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=,, 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=,,,,, If the object was scaled to a smaller or larger size then provide the scale factor that was used when slicing the object: DELTA_ANALYZE SCALE=1.0 (A scale value of 2.0 would mean the object is twice its original size, 0.5 would be half its original size.) Finally, perform the enhanced delta calibration by running: DELTA_ANALYZE CALIBRATE=extended This command can take several minutes to complete. After completion it will calculate updated delta parameters (delta radius, tower angles, endstop positions, and arm lengths). Use the SAVE_CONFIG command to save and apply the settings: SAVE_CONFIG The SAVE_CONFIG command will save both the updated delta parameters and information from the distance measurements. Future DELTA_CALIBRATE commands will also utilize this distance information. Do not attempt to reenter the raw distance measurements after running SAVE_CONFIG, as this command changes the printer configuration and the raw measurements no longer apply.","title":"Enhanced delta calibration"},{"location":"Delta_Calibrate.html#additional-notes","text":"If the delta printer has good dimensional accuracy then the distance between any two pillars should be around 74mm and the width of every pillar should be around 9mm. (Specifically, the goal is for the distance between any two pillars minus the width of one of the pillars to be exactly 65mm.) Should there be a dimensional inaccuracy in the part then the DELTA_ANALYZE routine will calculate new delta parameters using both the distance measurements and the previous height measurements from the last DELTA_CALIBRATE command. DELTA_ANALYZE may produce delta parameters that are surprising. For example, it may suggest arm lengths that do not match the printer's actual arm lengths. Despite this, testing has shown that DELTA_ANALYZE often produces superior results. It is believed that the calculated delta parameters are able to account for slight errors elsewhere in the hardware. For example, small differences in arm length may result in a tilt to the effector and some of that tilt may be accounted for by adjusting the arm length parameters.","title":"Additional notes"},{"location":"Delta_Calibrate.html#using-bed-mesh-on-a-delta","text":"It is possible to use bed mesh on a delta. However, it is important to obtain good delta calibration prior to enabling a bed mesh. Running bed mesh with poor delta calibration will result in confusing and poor results. Note that performing delta calibration will invalidate any previously obtained bed mesh. After performing a new delta calibration be sure to rerun BED_MESH_CALIBRATE.","title":"Using Bed Mesh on a Delta"},{"location":"Eddy_Probe.html","text":"Eddy Current Inductive probe \u00b6 This document describes how to use an eddy current inductive probe in Klipper. Currently, an eddy current probe can not be used for Z homing. The sensor can only be used for Z probing. Start by declaring a probe_eddy_current config section in the printer.cfg file. It is recommended to set the z_offset to 0.5mm. It is typical for the sensor to require an x_offset and y_offset . If these values are not known, one should estimate the values during initial calibration. The first step in calibration is to determine the appropriate DRIVE_CURRENT for the sensor. Home the printer and navigate the toolhead so that the sensor is near the center of the bed and is about 20mm above the bed. Then issue an LDC_CALIBRATE_DRIVE_CURRENT CHIP= command. For example, if the config section was named [probe_eddy_current my_eddy_probe] then one would run LDC_CALIBRATE_DRIVE_CURRENT CHIP=my_eddy_probe . This command should complete in a few seconds. After it completes, issue a SAVE_CONFIG command to save the results to the printer.cfg and restart. The second step in calibration is to correlate the sensor readings to the corresponding Z heights. Home the printer and navigate the toolhead so that the nozzle is near the center of the bed. Then run a PROBE_EDDY_CURRENT_CALIBRATE CHIP=my_eddy_probe command. Once the tool starts, follow the steps described at \"the paper test\" to determine the actual distance between the nozzle and bed at the given location. Once those steps are complete one can ACCEPT the position. The tool will then move the toolhead so that the sensor is above the point where the nozzle used to be and run a series of movements to correlate the sensor to Z positions. This will take a couple of minutes. After the tool completes, issue a SAVE_CONFIG command to save the results to the printer.cfg and restart. After initial calibration it is a good idea to verify that the x_offset and y_offset are accurate. Follow the steps to calibrate probe x and y offsets . If either the x_offset or y_offset is modified then be sure to run the PROBE_EDDY_CURRENT_CALIBRATE command (as described above) after making the change. Once calibration is complete, one may use all the standard Klipper tools that use a Z probe. Note that eddy current sensors (and inductive probes in general) are susceptible to \"thermal drift\". That is, changes in temperature can result in changes in reported Z height. Changes in either the bed surface temperature or sensor hardware temperature can skew the results. It is important that calibration and probing is only done when the printer is at a stable temperature. Thermal Drift Calibration \u00b6 As with all inductive probes, eddy current probes are subject to significant thermal drift. If the eddy probe has a temperature sensor on the coil it is possible to configure a [temperature_probe] to report coil temperature and enable software drift compensation. To link a temperature probe to an eddy current probe the [temperature_probe] section must share a name with the [probe_eddy_current] section. For example: [probe_eddy_current my_probe] # eddy probe configuration... [temperature_probe my_probe] # temperature probe configuration... See the configuration reference for further details on how to configure a temperature_probe . It is advised to configure the calibration_position , calibration_extruder_temp , extruder_heating_z , and calibration_bed_temp options, as doing so will automate some of the steps outlined below. If the printer to be calibrated is enclosed, it is strongly recommended to set the max_validation_temp option to a value between 100 and 120. Eddy probe manufacturers may offer a stock drift calibration that can be manually added to drift_calibration option of the [probe_eddy_current] section. If they do not, or if the stock calibration does not perform well on your system, the temperature_probe module offers a manual calibration procedure via the TEMPERATURE_PROBE_CALIBRATE gcode command. Prior to performing calibration the user should have an idea of what the maximum attainable temperature probe coil temperature is. This temperature should be used to set the TARGET parameter of the TEMPERATURE_PROBE_CALIBRATE command. The goal is to calibrate across the widest temperature range possible, thus its desirable to start with the printer cold and finish with the coil at the maximum temperature it can reach. Once a [temperature_probe] is configured, the following steps may be taken to perform thermal drift calibration: The probe must be calibrated using PROBE_EDDY_CURRENT_CALIBRATE when a [temperature_probe] is configured and linked. This captures the temperature during calibration which is necessary to perform thermal drift compensation. Make sure the nozzle is free of debris and filament. The bed, nozzle, and probe coil should be cold prior to calibration. The following steps are required if the calibration_position , calibration_extruder_temp , and extruder_heating_z options in [temperature_probe] are NOT configured: Move the tool to the center of the bed. Z should be 30mm+ above the bed. Heat the extruder to a temperature above the maximum safe bed temperature. 150-170C should be sufficient for most configurations. The purpose of heating the extruder is to avoid nozzle expansion during calibration. When the extruder temperature has settled, move the Z axis down to about 1mm above the bed. Start drift calibration. If the probe's name is my_probe and the maximum probe temperature we can achieve is 80C, the appropriate gcode command is TEMPERATURE_PROBE_CALIBRATE PROBE=my_probe TARGET=80 . If configured, the tool will move to the X,Y coordinate specified by the calibration_position and the Z value specified by extruder_heating_z . After heating the extruder to the specified temperature the tool will move to the Z value specified by the calibration_position . The procedure will request a manual probe. Perform the manual probe with the paper test and ACCEPT . The calibration procedure will take the first set of samples with the probe then park the probe in the heating position. If the calibration_bed_temp is NOT configured turn on the bed heat to the maximum safe temperature. Otherwise this step will be performed automatically. By default the calibration procedure will request a manual probe every 2C between samples until the TARGET is reached. The temperature delta between samples can be customized by setting the STEP parameter in TEMPERATURE_PROBE_CALIBRATE . Care should be taken when setting a custom STEP value, a value too high may request too few samples resulting in a poor calibration. The following additional gcode commands are available during drift calibration: TEMPERATURE_PROBE_NEXT may be used to force a new sample before the step delta has been reached. TEMPERATURE_PROBE_COMPLETE may be used to complete calibration before the TARGET has been reached. ABORT may be used to end calibration and discard results. When calibration is finished use SAVE_CONFIG to store the drift calibration. As one may conclude, the calibration process outlined above is more challenging and time consuming than most other procedures. It may require practice and several attempts to achieve an optimal calibration.","title":"Eddy Current Inductive probe"},{"location":"Eddy_Probe.html#eddy-current-inductive-probe","text":"This document describes how to use an eddy current inductive probe in Klipper. Currently, an eddy current probe can not be used for Z homing. The sensor can only be used for Z probing. Start by declaring a probe_eddy_current config section in the printer.cfg file. It is recommended to set the z_offset to 0.5mm. It is typical for the sensor to require an x_offset and y_offset . If these values are not known, one should estimate the values during initial calibration. The first step in calibration is to determine the appropriate DRIVE_CURRENT for the sensor. Home the printer and navigate the toolhead so that the sensor is near the center of the bed and is about 20mm above the bed. Then issue an LDC_CALIBRATE_DRIVE_CURRENT CHIP= command. For example, if the config section was named [probe_eddy_current my_eddy_probe] then one would run LDC_CALIBRATE_DRIVE_CURRENT CHIP=my_eddy_probe . This command should complete in a few seconds. After it completes, issue a SAVE_CONFIG command to save the results to the printer.cfg and restart. The second step in calibration is to correlate the sensor readings to the corresponding Z heights. Home the printer and navigate the toolhead so that the nozzle is near the center of the bed. Then run a PROBE_EDDY_CURRENT_CALIBRATE CHIP=my_eddy_probe command. Once the tool starts, follow the steps described at \"the paper test\" to determine the actual distance between the nozzle and bed at the given location. Once those steps are complete one can ACCEPT the position. The tool will then move the toolhead so that the sensor is above the point where the nozzle used to be and run a series of movements to correlate the sensor to Z positions. This will take a couple of minutes. After the tool completes, issue a SAVE_CONFIG command to save the results to the printer.cfg and restart. After initial calibration it is a good idea to verify that the x_offset and y_offset are accurate. Follow the steps to calibrate probe x and y offsets . If either the x_offset or y_offset is modified then be sure to run the PROBE_EDDY_CURRENT_CALIBRATE command (as described above) after making the change. Once calibration is complete, one may use all the standard Klipper tools that use a Z probe. Note that eddy current sensors (and inductive probes in general) are susceptible to \"thermal drift\". That is, changes in temperature can result in changes in reported Z height. Changes in either the bed surface temperature or sensor hardware temperature can skew the results. It is important that calibration and probing is only done when the printer is at a stable temperature.","title":"Eddy Current Inductive probe"},{"location":"Eddy_Probe.html#thermal-drift-calibration","text":"As with all inductive probes, eddy current probes are subject to significant thermal drift. If the eddy probe has a temperature sensor on the coil it is possible to configure a [temperature_probe] to report coil temperature and enable software drift compensation. To link a temperature probe to an eddy current probe the [temperature_probe] section must share a name with the [probe_eddy_current] section. For example: [probe_eddy_current my_probe] # eddy probe configuration... [temperature_probe my_probe] # temperature probe configuration... See the configuration reference for further details on how to configure a temperature_probe . It is advised to configure the calibration_position , calibration_extruder_temp , extruder_heating_z , and calibration_bed_temp options, as doing so will automate some of the steps outlined below. If the printer to be calibrated is enclosed, it is strongly recommended to set the max_validation_temp option to a value between 100 and 120. Eddy probe manufacturers may offer a stock drift calibration that can be manually added to drift_calibration option of the [probe_eddy_current] section. If they do not, or if the stock calibration does not perform well on your system, the temperature_probe module offers a manual calibration procedure via the TEMPERATURE_PROBE_CALIBRATE gcode command. Prior to performing calibration the user should have an idea of what the maximum attainable temperature probe coil temperature is. This temperature should be used to set the TARGET parameter of the TEMPERATURE_PROBE_CALIBRATE command. The goal is to calibrate across the widest temperature range possible, thus its desirable to start with the printer cold and finish with the coil at the maximum temperature it can reach. Once a [temperature_probe] is configured, the following steps may be taken to perform thermal drift calibration: The probe must be calibrated using PROBE_EDDY_CURRENT_CALIBRATE when a [temperature_probe] is configured and linked. This captures the temperature during calibration which is necessary to perform thermal drift compensation. Make sure the nozzle is free of debris and filament. The bed, nozzle, and probe coil should be cold prior to calibration. The following steps are required if the calibration_position , calibration_extruder_temp , and extruder_heating_z options in [temperature_probe] are NOT configured: Move the tool to the center of the bed. Z should be 30mm+ above the bed. Heat the extruder to a temperature above the maximum safe bed temperature. 150-170C should be sufficient for most configurations. The purpose of heating the extruder is to avoid nozzle expansion during calibration. When the extruder temperature has settled, move the Z axis down to about 1mm above the bed. Start drift calibration. If the probe's name is my_probe and the maximum probe temperature we can achieve is 80C, the appropriate gcode command is TEMPERATURE_PROBE_CALIBRATE PROBE=my_probe TARGET=80 . If configured, the tool will move to the X,Y coordinate specified by the calibration_position and the Z value specified by extruder_heating_z . After heating the extruder to the specified temperature the tool will move to the Z value specified by the calibration_position . The procedure will request a manual probe. Perform the manual probe with the paper test and ACCEPT . The calibration procedure will take the first set of samples with the probe then park the probe in the heating position. If the calibration_bed_temp is NOT configured turn on the bed heat to the maximum safe temperature. Otherwise this step will be performed automatically. By default the calibration procedure will request a manual probe every 2C between samples until the TARGET is reached. The temperature delta between samples can be customized by setting the STEP parameter in TEMPERATURE_PROBE_CALIBRATE . Care should be taken when setting a custom STEP value, a value too high may request too few samples resulting in a poor calibration. The following additional gcode commands are available during drift calibration: TEMPERATURE_PROBE_NEXT may be used to force a new sample before the step delta has been reached. TEMPERATURE_PROBE_COMPLETE may be used to complete calibration before the TARGET has been reached. ABORT may be used to end calibration and discard results. When calibration is finished use SAVE_CONFIG to store the drift calibration. As one may conclude, the calibration process outlined above is more challenging and time consuming than most other procedures. It may require practice and several attempts to achieve an optimal calibration.","title":"Thermal Drift Calibration"},{"location":"Endstop_Phase.html","text":"Endstop phase \u00b6 This document describes Klipper's stepper phase adjusted endstop system. This functionality can improve the accuracy of traditional endstop switches. It is most useful when using a Trinamic stepper motor driver that has run-time configuration. A typical endstop switch has an accuracy of around 100 microns. (Each time an axis is homed the switch may trigger slightly earlier or slightly later.) Although this is a relatively small error, it can result in unwanted artifacts. In particular, this positional deviation may be noticeable when printing the first layer of an object. In contrast, typical stepper motors can obtain significantly higher precision. The stepper phase adjusted endstop mechanism can use the precision of the stepper motors to improve the precision of the endstop switches. A stepper motor moves by cycling through a series of phases until in completes four \"full steps\". So, a stepper motor using 16 micro-steps would have 64 phases and when moving in a positive direction it would cycle through phases: 0, 1, 2, ... 61, 62, 63, 0, 1, 2, etc. Crucially, when the stepper motor is at a particular position on a linear rail it should always be at the same stepper phase. Thus, when a carriage triggers the endstop switch the stepper controlling that carriage should always be at the same stepper motor phase. Klipper's endstop phase system combines the stepper phase with the endstop trigger to improve the accuracy of the endstop. In order to use this functionality it is necessary to be able to identify the phase of the stepper motor. If one is using Trinamic TMC2130, TMC2208, TMC2224 or TMC2660 drivers in run-time configuration mode (ie, not stand-alone mode) then Klipper can query the stepper phase from the driver. (It is also possible to use this system on traditional stepper drivers if one can reliably reset the stepper drivers - see below for details.) Calibrating endstop phases \u00b6 If using Trinamic stepper motor drivers with run-time configuration then one can calibrate the endstop phases using the ENDSTOP_PHASE_CALIBRATE command. Start by adding the following to the config file: [endstop_phase] Then RESTART the printer and run a G28 command followed by an ENDSTOP_PHASE_CALIBRATE command. Then move the toolhead to a new location and run G28 again. Try moving the toolhead to several different locations and rerun G28 from each position. Run at least five G28 commands. After performing the above, the ENDSTOP_PHASE_CALIBRATE command will often report the same (or nearly the same) phase for the stepper. This phase can be saved in the config file so that all future G28 commands use that phase. (So, in future homing operations, Klipper will obtain the same position even if the endstop triggers a little earlier or a little later.) To save the endstop phase for a particular stepper motor, run something like the following: ENDSTOP_PHASE_CALIBRATE STEPPER=stepper_z Run the above for all the steppers one wishes to save. Typically, one would use this on stepper_z for cartesian and corexy printers, and for stepper_a, stepper_b, and stepper_c on delta printers. Finally, run the following to update the configuration file with the data: SAVE_CONFIG Additional notes \u00b6 This feature is most useful on delta printers and on the Z endstop of cartesian/corexy printers. It is possible to use this feature on the XY endstops of cartesian printers, but that isn't particularly useful as a minor error in X/Y endstop position is unlikely to impact print quality. It is not valid to use this feature on the XY endstops of corexy printers (as the XY position is not determined by a single stepper on corexy kinematics). It is not valid to use this feature on a printer using a \"probe:z_virtual_endstop\" Z endstop (as the stepper phase is only stable if the endstop is at a static location on a rail). After calibrating the endstop phase, if the endstop is later moved or adjusted then it will be necessary to recalibrate the endstop. Remove the calibration data from the config file and rerun the steps above. In order to use this system the endstop must be accurate enough to identify the stepper position within two \"full steps\". So, for example, if a stepper is using 16 micro-steps with a step distance of 0.005mm then the endstop must have an accuracy of at least 0.160mm. If one gets \"Endstop stepper_z incorrect phase\" type error messages than in may be due to an endstop that is not sufficiently accurate. If recalibration does not help then disable endstop phase adjustments by removing them from the config file. If one is using a traditional stepper controlled Z axis (as on a cartesian or corexy printer) along with traditional bed leveling screws then it is also possible to use this system to arrange for each print layer to be performed on a \"full step\" boundary. To enable this feature be sure the G-Code slicer is configured with a layer height that is a multiple of a \"full step\", manually enable the endstop_align_zero option in the endstop_phase config section (see config reference for further details), and then re-level the bed screws. It is possible to use this system with traditional (non-Trinamic) stepper motor drivers. However, doing this requires making sure that the stepper motor drivers are reset every time the micro-controller is reset. (If the two are always reset together then Klipper can determine the stepper phase by tracking the total number of steps it has commanded the stepper to move.) Currently, the only way to do this reliably is if both the micro-controller and stepper motor drivers are powered solely from USB and that USB power is provided from a host running on a Raspberry Pi. In this situation one can specify an mcu config with \"restart_method: rpi_usb\" - that option will arrange for the micro-controller to always be reset via a USB power reset, which would arrange for both the micro-controller and stepper motor drivers to be reset together. If using this mechanism, one would then need to manually configure the \"trigger_phase\" config sections (see config reference for the details).","title":"Endstop phase"},{"location":"Endstop_Phase.html#endstop-phase","text":"This document describes Klipper's stepper phase adjusted endstop system. This functionality can improve the accuracy of traditional endstop switches. It is most useful when using a Trinamic stepper motor driver that has run-time configuration. A typical endstop switch has an accuracy of around 100 microns. (Each time an axis is homed the switch may trigger slightly earlier or slightly later.) Although this is a relatively small error, it can result in unwanted artifacts. In particular, this positional deviation may be noticeable when printing the first layer of an object. In contrast, typical stepper motors can obtain significantly higher precision. The stepper phase adjusted endstop mechanism can use the precision of the stepper motors to improve the precision of the endstop switches. A stepper motor moves by cycling through a series of phases until in completes four \"full steps\". So, a stepper motor using 16 micro-steps would have 64 phases and when moving in a positive direction it would cycle through phases: 0, 1, 2, ... 61, 62, 63, 0, 1, 2, etc. Crucially, when the stepper motor is at a particular position on a linear rail it should always be at the same stepper phase. Thus, when a carriage triggers the endstop switch the stepper controlling that carriage should always be at the same stepper motor phase. Klipper's endstop phase system combines the stepper phase with the endstop trigger to improve the accuracy of the endstop. In order to use this functionality it is necessary to be able to identify the phase of the stepper motor. If one is using Trinamic TMC2130, TMC2208, TMC2224 or TMC2660 drivers in run-time configuration mode (ie, not stand-alone mode) then Klipper can query the stepper phase from the driver. (It is also possible to use this system on traditional stepper drivers if one can reliably reset the stepper drivers - see below for details.)","title":"Endstop phase"},{"location":"Endstop_Phase.html#calibrating-endstop-phases","text":"If using Trinamic stepper motor drivers with run-time configuration then one can calibrate the endstop phases using the ENDSTOP_PHASE_CALIBRATE command. Start by adding the following to the config file: [endstop_phase] Then RESTART the printer and run a G28 command followed by an ENDSTOP_PHASE_CALIBRATE command. Then move the toolhead to a new location and run G28 again. Try moving the toolhead to several different locations and rerun G28 from each position. Run at least five G28 commands. After performing the above, the ENDSTOP_PHASE_CALIBRATE command will often report the same (or nearly the same) phase for the stepper. This phase can be saved in the config file so that all future G28 commands use that phase. (So, in future homing operations, Klipper will obtain the same position even if the endstop triggers a little earlier or a little later.) To save the endstop phase for a particular stepper motor, run something like the following: ENDSTOP_PHASE_CALIBRATE STEPPER=stepper_z Run the above for all the steppers one wishes to save. Typically, one would use this on stepper_z for cartesian and corexy printers, and for stepper_a, stepper_b, and stepper_c on delta printers. Finally, run the following to update the configuration file with the data: SAVE_CONFIG","title":"Calibrating endstop phases"},{"location":"Endstop_Phase.html#additional-notes","text":"This feature is most useful on delta printers and on the Z endstop of cartesian/corexy printers. It is possible to use this feature on the XY endstops of cartesian printers, but that isn't particularly useful as a minor error in X/Y endstop position is unlikely to impact print quality. It is not valid to use this feature on the XY endstops of corexy printers (as the XY position is not determined by a single stepper on corexy kinematics). It is not valid to use this feature on a printer using a \"probe:z_virtual_endstop\" Z endstop (as the stepper phase is only stable if the endstop is at a static location on a rail). After calibrating the endstop phase, if the endstop is later moved or adjusted then it will be necessary to recalibrate the endstop. Remove the calibration data from the config file and rerun the steps above. In order to use this system the endstop must be accurate enough to identify the stepper position within two \"full steps\". So, for example, if a stepper is using 16 micro-steps with a step distance of 0.005mm then the endstop must have an accuracy of at least 0.160mm. If one gets \"Endstop stepper_z incorrect phase\" type error messages than in may be due to an endstop that is not sufficiently accurate. If recalibration does not help then disable endstop phase adjustments by removing them from the config file. If one is using a traditional stepper controlled Z axis (as on a cartesian or corexy printer) along with traditional bed leveling screws then it is also possible to use this system to arrange for each print layer to be performed on a \"full step\" boundary. To enable this feature be sure the G-Code slicer is configured with a layer height that is a multiple of a \"full step\", manually enable the endstop_align_zero option in the endstop_phase config section (see config reference for further details), and then re-level the bed screws. It is possible to use this system with traditional (non-Trinamic) stepper motor drivers. However, doing this requires making sure that the stepper motor drivers are reset every time the micro-controller is reset. (If the two are always reset together then Klipper can determine the stepper phase by tracking the total number of steps it has commanded the stepper to move.) Currently, the only way to do this reliably is if both the micro-controller and stepper motor drivers are powered solely from USB and that USB power is provided from a host running on a Raspberry Pi. In this situation one can specify an mcu config with \"restart_method: rpi_usb\" - that option will arrange for the micro-controller to always be reset via a USB power reset, which would arrange for both the micro-controller and stepper motor drivers to be reset together. If using this mechanism, one would then need to manually configure the \"trigger_phase\" config sections (see config reference for the details).","title":"Additional notes"},{"location":"Example_Configs.html","text":"Example configurations \u00b6 This document contains guidelines for contributing an example Klipper configuration to the Klipper github repository (located in the config directory ). Note that the Klipper Community Discourse server is also a useful resource for finding and sharing config files. Guidelines \u00b6 Select the appropriate config filename prefix: The printer prefix is used for stock printers sold by a mainstream manufacturer. The generic prefix is used for a 3d printer board that may be used in many different types of printers. The kit prefix is for 3d printers that are assembled according to a widely used specification. These \"kit\" printers are generally distinct from normal \"printers\" in that they are not sold by a manufacturer. The sample prefix is used for config \"snippets\" that one may copy-and-paste into the main config file. The example prefix is used to describe printer kinematics. This type of config is typically only added along with code for a new type of printer kinematics. All configuration files must end in a .cfg suffix. The printer config files must end in a year followed by .cfg (eg, -2019.cfg ). In this case, the year is an approximate year the given printer was sold. Do not use spaces or special characters in the config filename. The filename should contain only characters A-Z , a-z , 0-9 , - , and . . Klipper must be able to start printer , generic , and kit example config file without error. These config files should be added to the test/klippy/printers.test regression test case. Add new config files to that test case in the appropriate section and in alphabetical order within that section. The example configuration should be for the \"stock\" configuration of the printer. (There are too many \"customized\" configurations to track in the main Klipper repository.) Similarly, we only add example config files for printers, kits, and boards that have mainstream popularity (eg, there should be at least a 100 of them in active use). Consider using the Klipper Community Discourse server for other configs. Only specify those devices present on the given printer or board. Do not specify settings specific to your particular setup. For generic config files, only those devices on the mainboard should be described. For example, it would not make sense to add a display config section to a \"generic\" config as there is no way to know if the board will be attached to that type of display. If the board has a specific hardware port to facilitate an optional peripheral (eg, a bltouch port) then one can add a \"commented out\" config section for the given device. Do not specify pressure_advance in an example config, as that value is specific to the filament, not the printer hardware. Similarly, do not specify max_extrude_only_velocity nor max_extrude_only_accel settings. Do not specify a config section containing a host path or host hardware. For example, do not specify [virtual_sdcard] nor [temperature_host] config sections. Only define macros that utilize functionality specific to the given printer or to define g-codes that are commonly emitted by slicers configured for the given printer. Where possible, it is best to use the same wording, phrasing, indentation, and section ordering as the existing config files. The top of each config file should list the type of micro-controller the user should select during \"make menuconfig\". It should also have a reference to \"docs/Config_Reference.md\". Do not copy the field documentation into the example config files. (Doing so creates a maintenance burden as an update to the documentation would then require changing it in many places.) Example config files should not contain a \"SAVE_CONFIG\" section. If necessary, copy the relevant fields from the SAVE_CONFIG section to the appropriate section in the main config area. Use field: value syntax instead of field=value . When adding an extruder rotation_distance it is preferable to specify a gear_ratio if the extruder has a gearing mechanism. We expect the rotation_distance in the example configs to correlate with the circumference of the hobbed gear in the extruder - it is normally in the range of 20 to 35mm. When specifying a gear_ratio it is preferable to specify the actual gears on the mechanism (eg, prefer gear_ratio: 80:20 over gear_ratio: 4:1 ). See the rotation distance document for more information. Avoid defining field values that are set to their default value. For example, one should not specify min_extrude_temp: 170 as that is already the default value. Where possible, lines should not exceed 80 columns. Avoid adding attribution or revision messages to the config files. (For example, avoid adding lines like \"this file was created by ...\".) Place attribution and change history in the git commit message. Do not use any deprecated features in the example config file. Do not disable a default safety system in an example config file. For example, a config should not specify a custom max_extrude_cross_section . Do not enable debugging features. For example there should not be a force_move config section. All known boards that Klipper supports can use the default serial baud rate of 250000. Do not recommend a different baud rate in an example config file. Example config files are submitted by creating a github \"pull request\". Please also follow the directions in the contributing document .","title":"Example configurations"},{"location":"Example_Configs.html#example-configurations","text":"This document contains guidelines for contributing an example Klipper configuration to the Klipper github repository (located in the config directory ). Note that the Klipper Community Discourse server is also a useful resource for finding and sharing config files.","title":"Example configurations"},{"location":"Example_Configs.html#guidelines","text":"Select the appropriate config filename prefix: The printer prefix is used for stock printers sold by a mainstream manufacturer. The generic prefix is used for a 3d printer board that may be used in many different types of printers. The kit prefix is for 3d printers that are assembled according to a widely used specification. These \"kit\" printers are generally distinct from normal \"printers\" in that they are not sold by a manufacturer. The sample prefix is used for config \"snippets\" that one may copy-and-paste into the main config file. The example prefix is used to describe printer kinematics. This type of config is typically only added along with code for a new type of printer kinematics. All configuration files must end in a .cfg suffix. The printer config files must end in a year followed by .cfg (eg, -2019.cfg ). In this case, the year is an approximate year the given printer was sold. Do not use spaces or special characters in the config filename. The filename should contain only characters A-Z , a-z , 0-9 , - , and . . Klipper must be able to start printer , generic , and kit example config file without error. These config files should be added to the test/klippy/printers.test regression test case. Add new config files to that test case in the appropriate section and in alphabetical order within that section. The example configuration should be for the \"stock\" configuration of the printer. (There are too many \"customized\" configurations to track in the main Klipper repository.) Similarly, we only add example config files for printers, kits, and boards that have mainstream popularity (eg, there should be at least a 100 of them in active use). Consider using the Klipper Community Discourse server for other configs. Only specify those devices present on the given printer or board. Do not specify settings specific to your particular setup. For generic config files, only those devices on the mainboard should be described. For example, it would not make sense to add a display config section to a \"generic\" config as there is no way to know if the board will be attached to that type of display. If the board has a specific hardware port to facilitate an optional peripheral (eg, a bltouch port) then one can add a \"commented out\" config section for the given device. Do not specify pressure_advance in an example config, as that value is specific to the filament, not the printer hardware. Similarly, do not specify max_extrude_only_velocity nor max_extrude_only_accel settings. Do not specify a config section containing a host path or host hardware. For example, do not specify [virtual_sdcard] nor [temperature_host] config sections. Only define macros that utilize functionality specific to the given printer or to define g-codes that are commonly emitted by slicers configured for the given printer. Where possible, it is best to use the same wording, phrasing, indentation, and section ordering as the existing config files. The top of each config file should list the type of micro-controller the user should select during \"make menuconfig\". It should also have a reference to \"docs/Config_Reference.md\". Do not copy the field documentation into the example config files. (Doing so creates a maintenance burden as an update to the documentation would then require changing it in many places.) Example config files should not contain a \"SAVE_CONFIG\" section. If necessary, copy the relevant fields from the SAVE_CONFIG section to the appropriate section in the main config area. Use field: value syntax instead of field=value . When adding an extruder rotation_distance it is preferable to specify a gear_ratio if the extruder has a gearing mechanism. We expect the rotation_distance in the example configs to correlate with the circumference of the hobbed gear in the extruder - it is normally in the range of 20 to 35mm. When specifying a gear_ratio it is preferable to specify the actual gears on the mechanism (eg, prefer gear_ratio: 80:20 over gear_ratio: 4:1 ). See the rotation distance document for more information. Avoid defining field values that are set to their default value. For example, one should not specify min_extrude_temp: 170 as that is already the default value. Where possible, lines should not exceed 80 columns. Avoid adding attribution or revision messages to the config files. (For example, avoid adding lines like \"this file was created by ...\".) Place attribution and change history in the git commit message. Do not use any deprecated features in the example config file. Do not disable a default safety system in an example config file. For example, a config should not specify a custom max_extrude_cross_section . Do not enable debugging features. For example there should not be a force_move config section. All known boards that Klipper supports can use the default serial baud rate of 250000. Do not recommend a different baud rate in an example config file. Example config files are submitted by creating a github \"pull request\". Please also follow the directions in the contributing document .","title":"Guidelines"},{"location":"Exclude_Object.html","text":"Exclude Objects \u00b6 The [exclude_object] module allows Klipper to exclude objects while a print is in progress. To enable this feature include an exclude_object config section (also see the command reference and sample-macros.cfg file for a Marlin/RepRapFirmware compatible M486 G-Code macro.) Unlike other 3D printer firmware options, a printer running Klipper utilizes a suite of components and users have many options to choose from. Therefore, in order to provide a a consistent user experience, the [exclude_object] module will establish a contract or API of sorts. The contract covers the contents of the gcode file, how the internal state of the module is controlled, and how that state is provided to clients. Workflow Overview \u00b6 A typical workflow for printing a file might look like this: Slicing is completed and the file is uploaded for printing. During the upload, the file is processed and [exclude_object] markers are added to the file. Alternately, slicers may be configured to prepare object exclusion markers natively, or in it's own pre-processing step. When printing starts, Klipper will reset the [exclude_object] status . When Klipper processes the EXCLUDE_OBJECT_DEFINE block, it will update the status with the known objects and pass it on to clients. The client may use that information to present a UI to the user so that progress can be tracked. Klipper will update the status to include the currently printing object which the client can use for display purposes. If the user requests that an object be cancelled, the client will issue an EXCLUDE_OBJECT NAME= 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= command to Klipper. When Klipper process the command, it will add the object to the list of excluded objects and update the status for the client. The client will receive the updated status from Klipper and can use that information to reflect the object's status in the UI. When printing finishes, the [exclude_object] status will continue to be available until another action resets it.","title":"Workflow Overview"},{"location":"Exclude_Object.html#the-gcode-file","text":"The specialized gcode processing needed to support excluding objects does not fit into Klipper's core design goals. Therefore, this module requires that the file is processed before being sent to Klipper for printing. Using a post-process script in the slicer or having middleware process the file on upload are two possibilities for preparing the file for Klipper. A reference post-processing script is available both as an executable and a python library, see cancelobject-preprocessor .","title":"The GCode File"},{"location":"Exclude_Object.html#object-definitions","text":"The EXCLUDE_OBJECT_DEFINE command is used to provide a summary of each object in the gcode file to be printed. Provides a summary of an object in the file. Objects don't need to be defined in order to be referenced by other commands. The primary purpose of this command is to provide information to the UI without needing to parse the entire gcode file. Object definitions are named, to allow users to easily select an object to be excluded, and additional metadata may be provided to allow for graphical cancellation displays. Currently defined metadata includes a CENTER X,Y coordinate, and a POLYGON list of X,Y points representing a minimal outline of the object. This could be a simple bounding box, or a complicated hull for showing more detailed visualizations of the printed objects. Especially when gcode files include multiple parts with overlapping bounding regions, center points become hard to visually distinguish. POLYGONS must be a json-compatible array of point [X,Y] tuples without whitespace. Additional parameters will be saved as strings in the object definition and provided in status updates. EXCLUDE_OBJECT_DEFINE NAME=calibration_pyramid CENTER=50,50 POLYGON=[[40,40],[50,60],[60,40]] All available G-Code commands are documented in the G-Code Reference","title":"Object Definitions"},{"location":"Exclude_Object.html#status-information","text":"The state of this module is provided to clients by the exclude_object status . The status is reset when: The Klipper firmware is restarted. There is a reset of the [virtual_sdcard] . Notably, this is reset by Klipper at the start of a print. When an EXCLUDE_OBJECT_DEFINE RESET=1 command is issued. The list of defined objects is represented in the exclude_object.objects status field. In a well defined gcode file, this will be done with EXCLUDE_OBJECT_DEFINE commands at the beginning of the file. This will provide clients with object names and coordinates so the UI can provide a graphical representation of the objects if desired. As the print progresses, the exclude_object.current_object status field will be updated as Klipper processes EXCLUDE_OBJECT_START and EXCLUDE_OBJECT_END commands. The current_object field will be set even if the object has been excluded. Undefined objects marked with a EXCLUDE_OBJECT_START will be added to the known objects to assist in UI hinting, without any additional metadata. As EXCLUDE_OBJECT commands are issued, the list of excluded objects is provided in the exclude_object.excluded_objects array. Since Klipper looks ahead to process upcoming gcode, there may be a delay between when the command is issued and when the status is updated.","title":"Status Information"},{"location":"FAQ.html","text":"Frequently Asked Questions \u00b6 How can I donate to the project? \u00b6 Thank you for your support. See the Sponsors page for information. How do I calculate the rotation_distance config parameter? \u00b6 See the rotation distance document . Where's my serial port? \u00b6 The general way to find a USB serial port is to run ls /dev/serial/by-id/* from an ssh terminal on the host machine. It will likely produce output similar to the following: /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 The name found in the above command is stable and it is possible to use it in the config file and while flashing the micro-controller code. For example, a flash command might look similar to: sudo service klipper stop make flash FLASH_DEVICE=/dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 sudo service klipper start and the updated config might look like: [mcu] serial: /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 Be sure to copy-and-paste the name from the \"ls\" command that you ran above as the name will be different for each printer. If you are using multiple micro-controllers and they do not have unique ids (common on boards with a CH340 USB chip) then follow the directions above using the command ls /dev/serial/by-path/* instead. When the micro-controller restarts the device changes to /dev/ttyUSB1 \u00b6 Follow the directions in the \" Where's my serial port? \" section to prevent this from occurring. The \"make flash\" command doesn't work \u00b6 The code attempts to flash the device using the most common method for each platform. Unfortunately, there is a lot of variance in flashing methods, so the \"make flash\" command may not work on all boards. If you're having an intermittent failure or you do have a standard setup, then double check that Klipper isn't running when flashing (sudo service klipper stop), make sure OctoPrint isn't trying to connect directly to the device (open the Connection tab in the web page and click Disconnect if the Serial Port is set to the device), and make sure FLASH_DEVICE is set correctly for your board (see the question above ). However, if \"make flash\" just doesn't work for your board, then you will need to manually flash. See if there is a config file in the config directory with specific instructions for flashing the device. Also, check the board manufacturer's documentation to see if it describes how to flash the device. Finally, it may be possible to manually flash the device using tools such as \"avrdude\" or \"bossac\" - see the bootloader document for additional information. How do I change the serial baud rate? \u00b6 The recommended baud rate for Klipper is 250000. This baud rate works well on all micro-controller boards that Klipper supports. If you've found an online guide recommending a different baud rate, then ignore that part of the guide and continue with the default value of 250000. If you want to change the baud rate anyway, then the new rate will need to be configured in the micro-controller (during make menuconfig ) and that updated code will need to be compiled and flashed to the micro-controller. The Klipper printer.cfg file will also need to be updated to match that baud rate (see the config reference for details). For example: [mcu] baud: 250000 The baud rate shown on the OctoPrint web page has no impact on the internal Klipper micro-controller baud rate. Always set the OctoPrint baud rate to 250000 when using Klipper. The Klipper micro-controller baud rate is not related to the baud rate of the micro-controller's bootloader. See the bootloader document for additional information on bootloaders. Can I run Klipper on something other than a Raspberry Pi 3? \u00b6 The recommended hardware is a Raspberry Pi Zero2w, Raspberry Pi 3, Raspberry Pi 4 or Raspberry Pi 5. Klipper will also run on other SBC devices as well as x86 hardware, as described below. Klipper will run on a Raspberry Pi 1, 2 and on the Raspberry Pi Zero1, but these boards don't have enough processing power to run Klipper well. It is common for print stalls to occur on these slower machines when printing (The printer may move faster than Klipper can send movement commands.) It is not reccomended to run Klipper on these older machines. For running on the Beaglebone, see the Beaglebone specific installation instructions . Klipper has been run on other machines. The Klipper host software only requires Python running on a Linux (or similar) computer. However, if you wish to run it on a different machine you will need Linux admin knowledge to install the system prerequisites for that particular machine. See the install-octopi.sh script for further information on the necessary Linux admin steps. If you are looking to run the Klipper host software on a low-end chip, then be aware that, at a minimum, a machine with \"double precision floating point\" hardware is required. If you are looking to run the Klipper host software on a shared general-purpose desktop or server class machine, then note that Klipper has some real-time scheduling requirements. If, during a print, the host computer also performs an intensive general-purpose computing task (such as defragmenting a hard drive, 3d rendering, heavy swapping, etc.), then it may cause Klipper to report print errors. Note: If you are not using an OctoPi image, be aware that several Linux distributions enable a \"ModemManager\" (or similar) package that can disrupt serial communication. (Which can cause Klipper to report seemingly random \"Lost communication with MCU\" errors.) If you install Klipper on one of these distributions you may need to disable that package. Can I run multiple instances of Klipper on the same host machine? \u00b6 It is possible to run multiple instances of the Klipper host software, but doing so requires Linux admin knowledge. The Klipper installation scripts ultimately cause the following Unix command to be run: ~/klippy-env/bin/python ~/klipper/klippy/klippy.py ~/printer.cfg -l /tmp/klippy.log One can run multiple instances of the above command as long as each instance has its own printer config file, its own log file, and its own pseudo-tty. For example: ~/klippy-env/bin/python ~/klipper/klippy/klippy.py ~/printer2.cfg -l /tmp/klippy2.log -I /tmp/printer2 If you choose to do this, you will need to implement the necessary start, stop, and installation scripts (if any). The install-octopi.sh script and the klipper-start.sh script may be useful as examples. Do I have to use OctoPrint? \u00b6 The Klipper software is not dependent on OctoPrint. It is possible to use alternative software to send commands to Klipper, but doing so requires Linux admin knowledge. Klipper creates a \"virtual serial port\" via the \"/tmp/printer\" file, and it emulates a classic 3d-printer serial interface via that file. In general, alternative software may work with Klipper as long as it can be configured to use \"/tmp/printer\" for the printer serial port. Why can't I move the stepper before homing the printer? \u00b6 The code does this to reduce the chance of accidentally commanding the head into the bed or a wall. Once the printer is homed the software attempts to verify each move is within the position_min/max defined in the config file. If the motors are disabled (via an M84 or M18 command) then the motors will need to be homed again prior to movement. If you want to move the head after canceling a print via OctoPrint, consider changing the OctoPrint cancel sequence to do that for you. It's configured in OctoPrint via a web browser under: Settings->GCODE Scripts If you want to move the head after a print finishes, consider adding the desired movement to the \"custom g-code\" section of your slicer. If the printer requires some additional movement as part of the homing process itself (or fundamentally does not have a homing process) then consider using a safe_z_home or homing_override section in the config file. If you need to move a stepper for diagnostic or debugging purposes then consider adding a force_move section to the config file. See config reference for further details on these options. Why is the Z position_endstop set to 0.5 in the default configs? \u00b6 For cartesian style printers the Z position_endstop specifies how far the nozzle is from the bed when the endstop triggers. If possible, it is recommended to use a Z-max endstop and home away from the bed (as this reduces the potential for bed collisions). However, if one must home towards the bed then it is recommended to position the endstop so it triggers when the nozzle is still a small distance away from the bed. This way, when homing the axis, it will stop before the nozzle touches the bed. See the bed level document for more information. I converted my config from Marlin and the X/Y axes work fine, but I just get a screeching noise when homing the Z axis \u00b6 Short answer: First, make sure you have verified the stepper configuration as described in the config check document . If the problem persists, try reducing the max_z_velocity setting in the printer config. Long answer: In practice Marlin can typically only step at a rate of around 10000 steps per second. If it is requested to move at a speed that would require a higher step rate then Marlin will generally just step as fast as it can. Klipper is able to achieve much higher step rates, but the stepper motor may not have sufficient torque to move at a higher speed. So, for a Z axis with a high gearing ratio or high microsteps setting the actual obtainable max_z_velocity may be smaller than what is configured in Marlin. My TMC motor driver turns off in the middle of a print \u00b6 If using the TMC2208 (or TMC2224) driver in \"standalone mode\" then make sure to use the latest version of Klipper . A workaround for a TMC2208 \"stealthchop\" driver problem was added to Klipper in mid-March of 2020. I keep getting random \"Lost communication with MCU\" errors \u00b6 This is commonly caused by hardware errors on the USB connection between the host machine and the micro-controller. Things to look for: Use a good quality USB cable between the host machine and micro-controller. Make sure the plugs are secure. If using a Raspberry Pi, use a good quality power supply for the Raspberry Pi and use a good quality USB cable to connect that power supply to the Pi. If you get \"under voltage\" warnings from OctoPrint, this is related to the power supply and it must be fixed. Make sure the printer's power supply is not being overloaded. (Power fluctuations to the micro-controller's USB chip may result in resets of that chip.) Verify stepper, heater, and other printer wires are not crimped or frayed. (Printer movement may place stress on a faulty wire causing it to lose contact, briefly short, or generate excessive noise.) There have been reports of high USB noise when both the printer's power supply and the host's 5V power supply are mixed. (If you find that the micro-controller powers on when either the printer's power supply is on or the USB cable is plugged in, then it indicates the 5V power supplies are being mixed.) It may help to configure the micro-controller to use power from only one source. (Alternatively, if the micro-controller board can not configure its power source, one may modify a USB cable so that it does not carry 5V power between the host and micro-controller.) My Raspberry Pi keeps rebooting during prints \u00b6 This is most likely do to voltage fluctuations. Follow the same troubleshooting steps for a \"Lost communication with MCU\" error. When I set restart_method=command my AVR device just hangs on a restart \u00b6 Some old versions of the AVR bootloader have a known bug in watchdog event handling. This typically manifests when the printer.cfg file has restart_method set to \"command\". When the bug occurs, the AVR device will be unresponsive until power is removed and reapplied to the device (the power or status LEDs may also blink repeatedly until the power is removed). The workaround is to use a restart_method other than \"command\" or to flash an updated bootloader to the AVR device. Flashing a new bootloader is a one time step that typically requires an external programmer - see Bootloaders for further details. Will the heaters be left on if the Raspberry Pi crashes? \u00b6 The software has been designed to prevent that. Once the host enables a heater, the host software needs to confirm that enablement every 5 seconds. If the micro-controller does not receive a confirmation every 5 seconds it goes into a \"shutdown\" state which is designed to turn off all heaters and stepper motors. See the \"config_digital_out\" command in the MCU commands document for further details. In addition, the micro-controller software is configured with a minimum and maximum temperature range for each heater at startup (see the min_temp and max_temp parameters in the config reference for details). If the micro-controller detects that the temperature is outside of that range then it will also enter a \"shutdown\" state. Separately, the host software also implements code to check that heaters and temperature sensors are functioning correctly. See the config reference for further details. How do I convert a Marlin pin number to a Klipper pin name? \u00b6 Short answer: A mapping is available in the sample-aliases.cfg file. Use that file as a guide to finding the actual micro-controller pin names. (It is also possible to copy the relevant board_pins config section into your config file and use the aliases in your config, but it is preferable to translate and use the actual micro-controller pin names.) Note that the sample-aliases.cfg file uses pin names that start with the prefix \"ar\" instead of \"D\" (eg, Arduino pin D23 is Klipper alias ar23 ) and the prefix \"analog\" instead of \"A\" (eg, Arduino pin A14 is Klipper alias analog14 ). Long answer: Klipper uses the standard pin names defined by the micro-controller. On the Atmega chips these hardware pins have names like PA4 , PC7 , or PD2 . Long ago, the Arduino project decided to avoid using the standard hardware names in favor of their own pin names based on incrementing numbers - these Arduino names generally look like D23 or A14 . This was an unfortunate choice that has lead to a great deal of confusion. In particular the Arduino pin numbers frequently don't translate to the same hardware names. For example, D21 is PD0 on one common Arduino board, but is PC7 on another common Arduino board. To avoid this confusion, the core Klipper code uses the standard pin names defined by the micro-controller. Do I have to wire my device to a specific type of micro-controller pin? \u00b6 It depends on the type of device and type of pin: ADC pins (or Analog pins): For thermistors and similar \"analog\" sensors, the device must be wired to an \"analog\" or \"ADC\" capable pin on the micro-controller. If you configure Klipper to use a pin that is not analog capable, Klipper will report a \"Not a valid ADC pin\" error. PWM pins (or Timer pins): Klipper does not use hardware PWM by default for any device. So, in general, one may wire heaters, fans, and similar devices to any general purpose IO pin. However, fans and output_pin devices may be optionally configured to use hardware_pwm: True , in which case the micro-controller must support hardware PWM on the pin (otherwise, Klipper will report a \"Not a valid PWM pin\" error). IRQ pins (or Interrupt pins): Klipper does not use hardware interrupts on IO pins, so it is never necessary to wire a device to one of these micro-controller pins. SPI pins: When using hardware SPI it is necessary to wire the pins to the micro-controller's SPI capable pins. However, most devices can be configured to use \"software SPI\", in which case any general purpose IO pins may be used. I2C pins: When using I2C it is necessary to wire the pins to the micro-controller's I2C capable pins. Other devices may be wired to any general purpose IO pin. For example, steppers, heaters, fans, Z probes, servos, LEDs, common hd44780/st7920 LCD displays, the Trinamic UART control line may be wired to any general purpose IO pin. How do I cancel an M109/M190 \"wait for temperature\" request? \u00b6 Navigate to the OctoPrint terminal tab and issue an M112 command in the terminal box. The M112 command will cause Klipper to enter into a \"shutdown\" state, and it will cause OctoPrint to disconnect from Klipper. Navigate to the OctoPrint connection area and click on \"Connect\" to cause OctoPrint to reconnect. Navigate back to the terminal tab and issue a FIRMWARE_RESTART command to clear the Klipper error state. After completing this sequence, the previous heating request will be canceled and a new print may be started. Can I find out whether the printer has lost steps? \u00b6 In a way, yes. Home the printer, issue a GET_POSITION command, run your print, home again and issue another GET_POSITION . Then compare the values in the mcu: line. This might be helpful to tune settings like stepper motor currents, accelerations and speeds without needing to actually print something and waste filament: just run some high-speed moves in between the GET_POSITION commands. Note that endstop switches themselves tend to trigger at slightly different positions, so a difference of a couple of microsteps is likely the result of endstop inaccuracies. A stepper motor itself can only lose steps in increments of 4 full steps. (So, if one is using 16 microsteps, then a lost step on the stepper would result in the \"mcu:\" step counter being off by a multiple of 64 microsteps.) Why does Klipper report errors? I lost my print! \u00b6 Short answer: We want to know if our printers detect a problem so that the underlying issue can be fixed and we can obtain great quality prints. We definitely do not want our printers to silently produce low quality prints. Long answer: Klipper has been engineered to automatically workaround many transient problems. For example, it automatically detects communication errors and will retransmit; it schedules actions in advance and buffers commands at multiple layers to enable precise timing even with intermittent interference. However, should the software detect an error that it can not recover from, if it is commanded to take an invalid action, or if it detects it is hopelessly unable to perform its commanded task, then Klipper will report an error. In these situations there is a high risk of producing a low-quality print (or worse). It is hoped that alerting the user will empower them to fix the underlying issue and improve the overall quality of their prints. There are some related questions: Why doesn't Klipper pause the print instead? Report a warning instead? Check for errors before the print? Ignore errors in user typed commands? etc? Currently Klipper reads commands using the G-Code protocol, and unfortunately the G-Code command protocol is not flexible enough to make these alternatives practical today. There is developer interest in improving the user experience during abnormal events, but it is expected that will require notable infrastructure work (including a shift away from G-Code). How do I upgrade to the latest software? \u00b6 The first step to upgrading the software is to review the latest config changes document. On occasion, changes are made to the software that require users to update their settings as part of a software upgrade. It is a good idea to review this document prior to upgrading. When ready to upgrade, the general method is to ssh into the Raspberry Pi and run: cd ~/klipper git pull ~/klipper/scripts/install-octopi.sh Then one can recompile and flash the micro-controller code. For example: make menuconfig make clean make sudo service klipper stop make flash FLASH_DEVICE=/dev/ttyACM0 sudo service klipper start However, it's often the case that only the host software changes. In this case, one can update and restart just the host software with: cd ~/klipper git pull sudo service klipper restart If after using this shortcut the software warns about needing to reflash the micro-controller or some other unusual error occurs, then follow the full upgrade steps outlined above. If any errors persist then double check the config changes document, as you may need to modify the printer configuration. Note that the RESTART and FIRMWARE_RESTART g-code commands do not load new software - the above \"sudo service klipper restart\" and \"make flash\" commands are needed for a software change to take effect. How do I uninstall Klipper? \u00b6 On the firmware end, nothing special needs to happen. Just follow the flashing directions for the new firmware. On the raspberry pi end, an uninstall script is available in scripts/klipper-uninstall.sh . For example: sudo ~/klipper/scripts/klipper-uninstall.sh rm -rf ~/klippy-env ~/klipper","title":"Frequently Asked Questions"},{"location":"FAQ.html#frequently-asked-questions","text":"","title":"Frequently Asked Questions"},{"location":"FAQ.html#how-can-i-donate-to-the-project","text":"Thank you for your support. See the Sponsors page for information.","title":"How can I donate to the project?"},{"location":"FAQ.html#how-do-i-calculate-the-rotation_distance-config-parameter","text":"See the rotation distance document .","title":"How do I calculate the rotation_distance config parameter?"},{"location":"FAQ.html#wheres-my-serial-port","text":"The general way to find a USB serial port is to run ls /dev/serial/by-id/* from an ssh terminal on the host machine. It will likely produce output similar to the following: /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 The name found in the above command is stable and it is possible to use it in the config file and while flashing the micro-controller code. For example, a flash command might look similar to: sudo service klipper stop make flash FLASH_DEVICE=/dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 sudo service klipper start and the updated config might look like: [mcu] serial: /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 Be sure to copy-and-paste the name from the \"ls\" command that you ran above as the name will be different for each printer. If you are using multiple micro-controllers and they do not have unique ids (common on boards with a CH340 USB chip) then follow the directions above using the command ls /dev/serial/by-path/* instead.","title":"Where's my serial port?"},{"location":"FAQ.html#when-the-micro-controller-restarts-the-device-changes-to-devttyusb1","text":"Follow the directions in the \" Where's my serial port? \" section to prevent this from occurring.","title":"When the micro-controller restarts the device changes to /dev/ttyUSB1"},{"location":"FAQ.html#the-make-flash-command-doesnt-work","text":"The code attempts to flash the device using the most common method for each platform. Unfortunately, there is a lot of variance in flashing methods, so the \"make flash\" command may not work on all boards. If you're having an intermittent failure or you do have a standard setup, then double check that Klipper isn't running when flashing (sudo service klipper stop), make sure OctoPrint isn't trying to connect directly to the device (open the Connection tab in the web page and click Disconnect if the Serial Port is set to the device), and make sure FLASH_DEVICE is set correctly for your board (see the question above ). However, if \"make flash\" just doesn't work for your board, then you will need to manually flash. See if there is a config file in the config directory with specific instructions for flashing the device. Also, check the board manufacturer's documentation to see if it describes how to flash the device. Finally, it may be possible to manually flash the device using tools such as \"avrdude\" or \"bossac\" - see the bootloader document for additional information.","title":"The \"make flash\" command doesn't work"},{"location":"FAQ.html#how-do-i-change-the-serial-baud-rate","text":"The recommended baud rate for Klipper is 250000. This baud rate works well on all micro-controller boards that Klipper supports. If you've found an online guide recommending a different baud rate, then ignore that part of the guide and continue with the default value of 250000. If you want to change the baud rate anyway, then the new rate will need to be configured in the micro-controller (during make menuconfig ) and that updated code will need to be compiled and flashed to the micro-controller. The Klipper printer.cfg file will also need to be updated to match that baud rate (see the config reference for details). For example: [mcu] baud: 250000 The baud rate shown on the OctoPrint web page has no impact on the internal Klipper micro-controller baud rate. Always set the OctoPrint baud rate to 250000 when using Klipper. The Klipper micro-controller baud rate is not related to the baud rate of the micro-controller's bootloader. See the bootloader document for additional information on bootloaders.","title":"How do I change the serial baud rate?"},{"location":"FAQ.html#can-i-run-klipper-on-something-other-than-a-raspberry-pi-3","text":"The recommended hardware is a Raspberry Pi Zero2w, Raspberry Pi 3, Raspberry Pi 4 or Raspberry Pi 5. Klipper will also run on other SBC devices as well as x86 hardware, as described below. Klipper will run on a Raspberry Pi 1, 2 and on the Raspberry Pi Zero1, but these boards don't have enough processing power to run Klipper well. It is common for print stalls to occur on these slower machines when printing (The printer may move faster than Klipper can send movement commands.) It is not reccomended to run Klipper on these older machines. For running on the Beaglebone, see the Beaglebone specific installation instructions . Klipper has been run on other machines. The Klipper host software only requires Python running on a Linux (or similar) computer. However, if you wish to run it on a different machine you will need Linux admin knowledge to install the system prerequisites for that particular machine. See the install-octopi.sh script for further information on the necessary Linux admin steps. If you are looking to run the Klipper host software on a low-end chip, then be aware that, at a minimum, a machine with \"double precision floating point\" hardware is required. If you are looking to run the Klipper host software on a shared general-purpose desktop or server class machine, then note that Klipper has some real-time scheduling requirements. If, during a print, the host computer also performs an intensive general-purpose computing task (such as defragmenting a hard drive, 3d rendering, heavy swapping, etc.), then it may cause Klipper to report print errors. Note: If you are not using an OctoPi image, be aware that several Linux distributions enable a \"ModemManager\" (or similar) package that can disrupt serial communication. (Which can cause Klipper to report seemingly random \"Lost communication with MCU\" errors.) If you install Klipper on one of these distributions you may need to disable that package.","title":"Can I run Klipper on something other than a Raspberry Pi 3?"},{"location":"FAQ.html#can-i-run-multiple-instances-of-klipper-on-the-same-host-machine","text":"It is possible to run multiple instances of the Klipper host software, but doing so requires Linux admin knowledge. The Klipper installation scripts ultimately cause the following Unix command to be run: ~/klippy-env/bin/python ~/klipper/klippy/klippy.py ~/printer.cfg -l /tmp/klippy.log One can run multiple instances of the above command as long as each instance has its own printer config file, its own log file, and its own pseudo-tty. For example: ~/klippy-env/bin/python ~/klipper/klippy/klippy.py ~/printer2.cfg -l /tmp/klippy2.log -I /tmp/printer2 If you choose to do this, you will need to implement the necessary start, stop, and installation scripts (if any). The install-octopi.sh script and the klipper-start.sh script may be useful as examples.","title":"Can I run multiple instances of Klipper on the same host machine?"},{"location":"FAQ.html#do-i-have-to-use-octoprint","text":"The Klipper software is not dependent on OctoPrint. It is possible to use alternative software to send commands to Klipper, but doing so requires Linux admin knowledge. Klipper creates a \"virtual serial port\" via the \"/tmp/printer\" file, and it emulates a classic 3d-printer serial interface via that file. In general, alternative software may work with Klipper as long as it can be configured to use \"/tmp/printer\" for the printer serial port.","title":"Do I have to use OctoPrint?"},{"location":"FAQ.html#why-cant-i-move-the-stepper-before-homing-the-printer","text":"The code does this to reduce the chance of accidentally commanding the head into the bed or a wall. Once the printer is homed the software attempts to verify each move is within the position_min/max defined in the config file. If the motors are disabled (via an M84 or M18 command) then the motors will need to be homed again prior to movement. If you want to move the head after canceling a print via OctoPrint, consider changing the OctoPrint cancel sequence to do that for you. It's configured in OctoPrint via a web browser under: Settings->GCODE Scripts If you want to move the head after a print finishes, consider adding the desired movement to the \"custom g-code\" section of your slicer. If the printer requires some additional movement as part of the homing process itself (or fundamentally does not have a homing process) then consider using a safe_z_home or homing_override section in the config file. If you need to move a stepper for diagnostic or debugging purposes then consider adding a force_move section to the config file. See config reference for further details on these options.","title":"Why can't I move the stepper before homing the printer?"},{"location":"FAQ.html#why-is-the-z-position_endstop-set-to-05-in-the-default-configs","text":"For cartesian style printers the Z position_endstop specifies how far the nozzle is from the bed when the endstop triggers. If possible, it is recommended to use a Z-max endstop and home away from the bed (as this reduces the potential for bed collisions). However, if one must home towards the bed then it is recommended to position the endstop so it triggers when the nozzle is still a small distance away from the bed. This way, when homing the axis, it will stop before the nozzle touches the bed. See the bed level document for more information.","title":"Why is the Z position_endstop set to 0.5 in the default configs?"},{"location":"FAQ.html#i-converted-my-config-from-marlin-and-the-xy-axes-work-fine-but-i-just-get-a-screeching-noise-when-homing-the-z-axis","text":"Short answer: First, make sure you have verified the stepper configuration as described in the config check document . If the problem persists, try reducing the max_z_velocity setting in the printer config. Long answer: In practice Marlin can typically only step at a rate of around 10000 steps per second. If it is requested to move at a speed that would require a higher step rate then Marlin will generally just step as fast as it can. Klipper is able to achieve much higher step rates, but the stepper motor may not have sufficient torque to move at a higher speed. So, for a Z axis with a high gearing ratio or high microsteps setting the actual obtainable max_z_velocity may be smaller than what is configured in Marlin.","title":"I converted my config from Marlin and the X/Y axes work fine, but I just get a screeching noise when homing the Z axis"},{"location":"FAQ.html#my-tmc-motor-driver-turns-off-in-the-middle-of-a-print","text":"If using the TMC2208 (or TMC2224) driver in \"standalone mode\" then make sure to use the latest version of Klipper . A workaround for a TMC2208 \"stealthchop\" driver problem was added to Klipper in mid-March of 2020.","title":"My TMC motor driver turns off in the middle of a print"},{"location":"FAQ.html#i-keep-getting-random-lost-communication-with-mcu-errors","text":"This is commonly caused by hardware errors on the USB connection between the host machine and the micro-controller. Things to look for: Use a good quality USB cable between the host machine and micro-controller. Make sure the plugs are secure. If using a Raspberry Pi, use a good quality power supply for the Raspberry Pi and use a good quality USB cable to connect that power supply to the Pi. If you get \"under voltage\" warnings from OctoPrint, this is related to the power supply and it must be fixed. Make sure the printer's power supply is not being overloaded. (Power fluctuations to the micro-controller's USB chip may result in resets of that chip.) Verify stepper, heater, and other printer wires are not crimped or frayed. (Printer movement may place stress on a faulty wire causing it to lose contact, briefly short, or generate excessive noise.) There have been reports of high USB noise when both the printer's power supply and the host's 5V power supply are mixed. (If you find that the micro-controller powers on when either the printer's power supply is on or the USB cable is plugged in, then it indicates the 5V power supplies are being mixed.) It may help to configure the micro-controller to use power from only one source. (Alternatively, if the micro-controller board can not configure its power source, one may modify a USB cable so that it does not carry 5V power between the host and micro-controller.)","title":"I keep getting random \"Lost communication with MCU\" errors"},{"location":"FAQ.html#my-raspberry-pi-keeps-rebooting-during-prints","text":"This is most likely do to voltage fluctuations. Follow the same troubleshooting steps for a \"Lost communication with MCU\" error.","title":"My Raspberry Pi keeps rebooting during prints"},{"location":"FAQ.html#when-i-set-restart_methodcommand-my-avr-device-just-hangs-on-a-restart","text":"Some old versions of the AVR bootloader have a known bug in watchdog event handling. This typically manifests when the printer.cfg file has restart_method set to \"command\". When the bug occurs, the AVR device will be unresponsive until power is removed and reapplied to the device (the power or status LEDs may also blink repeatedly until the power is removed). The workaround is to use a restart_method other than \"command\" or to flash an updated bootloader to the AVR device. Flashing a new bootloader is a one time step that typically requires an external programmer - see Bootloaders for further details.","title":"When I set restart_method=command my AVR device just hangs on a restart"},{"location":"FAQ.html#will-the-heaters-be-left-on-if-the-raspberry-pi-crashes","text":"The software has been designed to prevent that. Once the host enables a heater, the host software needs to confirm that enablement every 5 seconds. If the micro-controller does not receive a confirmation every 5 seconds it goes into a \"shutdown\" state which is designed to turn off all heaters and stepper motors. See the \"config_digital_out\" command in the MCU commands document for further details. In addition, the micro-controller software is configured with a minimum and maximum temperature range for each heater at startup (see the min_temp and max_temp parameters in the config reference for details). If the micro-controller detects that the temperature is outside of that range then it will also enter a \"shutdown\" state. Separately, the host software also implements code to check that heaters and temperature sensors are functioning correctly. See the config reference for further details.","title":"Will the heaters be left on if the Raspberry Pi crashes?"},{"location":"FAQ.html#how-do-i-convert-a-marlin-pin-number-to-a-klipper-pin-name","text":"Short answer: A mapping is available in the sample-aliases.cfg file. Use that file as a guide to finding the actual micro-controller pin names. (It is also possible to copy the relevant board_pins config section into your config file and use the aliases in your config, but it is preferable to translate and use the actual micro-controller pin names.) Note that the sample-aliases.cfg file uses pin names that start with the prefix \"ar\" instead of \"D\" (eg, Arduino pin D23 is Klipper alias ar23 ) and the prefix \"analog\" instead of \"A\" (eg, Arduino pin A14 is Klipper alias analog14 ). Long answer: Klipper uses the standard pin names defined by the micro-controller. On the Atmega chips these hardware pins have names like PA4 , PC7 , or PD2 . Long ago, the Arduino project decided to avoid using the standard hardware names in favor of their own pin names based on incrementing numbers - these Arduino names generally look like D23 or A14 . This was an unfortunate choice that has lead to a great deal of confusion. In particular the Arduino pin numbers frequently don't translate to the same hardware names. For example, D21 is PD0 on one common Arduino board, but is PC7 on another common Arduino board. To avoid this confusion, the core Klipper code uses the standard pin names defined by the micro-controller.","title":"How do I convert a Marlin pin number to a Klipper pin name?"},{"location":"FAQ.html#do-i-have-to-wire-my-device-to-a-specific-type-of-micro-controller-pin","text":"It depends on the type of device and type of pin: ADC pins (or Analog pins): For thermistors and similar \"analog\" sensors, the device must be wired to an \"analog\" or \"ADC\" capable pin on the micro-controller. If you configure Klipper to use a pin that is not analog capable, Klipper will report a \"Not a valid ADC pin\" error. PWM pins (or Timer pins): Klipper does not use hardware PWM by default for any device. So, in general, one may wire heaters, fans, and similar devices to any general purpose IO pin. However, fans and output_pin devices may be optionally configured to use hardware_pwm: True , in which case the micro-controller must support hardware PWM on the pin (otherwise, Klipper will report a \"Not a valid PWM pin\" error). IRQ pins (or Interrupt pins): Klipper does not use hardware interrupts on IO pins, so it is never necessary to wire a device to one of these micro-controller pins. SPI pins: When using hardware SPI it is necessary to wire the pins to the micro-controller's SPI capable pins. However, most devices can be configured to use \"software SPI\", in which case any general purpose IO pins may be used. I2C pins: When using I2C it is necessary to wire the pins to the micro-controller's I2C capable pins. Other devices may be wired to any general purpose IO pin. For example, steppers, heaters, fans, Z probes, servos, LEDs, common hd44780/st7920 LCD displays, the Trinamic UART control line may be wired to any general purpose IO pin.","title":"Do I have to wire my device to a specific type of micro-controller pin?"},{"location":"FAQ.html#how-do-i-cancel-an-m109m190-wait-for-temperature-request","text":"Navigate to the OctoPrint terminal tab and issue an M112 command in the terminal box. The M112 command will cause Klipper to enter into a \"shutdown\" state, and it will cause OctoPrint to disconnect from Klipper. Navigate to the OctoPrint connection area and click on \"Connect\" to cause OctoPrint to reconnect. Navigate back to the terminal tab and issue a FIRMWARE_RESTART command to clear the Klipper error state. After completing this sequence, the previous heating request will be canceled and a new print may be started.","title":"How do I cancel an M109/M190 \"wait for temperature\" request?"},{"location":"FAQ.html#can-i-find-out-whether-the-printer-has-lost-steps","text":"In a way, yes. Home the printer, issue a GET_POSITION command, run your print, home again and issue another GET_POSITION . Then compare the values in the mcu: line. This might be helpful to tune settings like stepper motor currents, accelerations and speeds without needing to actually print something and waste filament: just run some high-speed moves in between the GET_POSITION commands. Note that endstop switches themselves tend to trigger at slightly different positions, so a difference of a couple of microsteps is likely the result of endstop inaccuracies. A stepper motor itself can only lose steps in increments of 4 full steps. (So, if one is using 16 microsteps, then a lost step on the stepper would result in the \"mcu:\" step counter being off by a multiple of 64 microsteps.)","title":"Can I find out whether the printer has lost steps?"},{"location":"FAQ.html#why-does-klipper-report-errors-i-lost-my-print","text":"Short answer: We want to know if our printers detect a problem so that the underlying issue can be fixed and we can obtain great quality prints. We definitely do not want our printers to silently produce low quality prints. Long answer: Klipper has been engineered to automatically workaround many transient problems. For example, it automatically detects communication errors and will retransmit; it schedules actions in advance and buffers commands at multiple layers to enable precise timing even with intermittent interference. However, should the software detect an error that it can not recover from, if it is commanded to take an invalid action, or if it detects it is hopelessly unable to perform its commanded task, then Klipper will report an error. In these situations there is a high risk of producing a low-quality print (or worse). It is hoped that alerting the user will empower them to fix the underlying issue and improve the overall quality of their prints. There are some related questions: Why doesn't Klipper pause the print instead? Report a warning instead? Check for errors before the print? Ignore errors in user typed commands? etc? Currently Klipper reads commands using the G-Code protocol, and unfortunately the G-Code command protocol is not flexible enough to make these alternatives practical today. There is developer interest in improving the user experience during abnormal events, but it is expected that will require notable infrastructure work (including a shift away from G-Code).","title":"Why does Klipper report errors? I lost my print!"},{"location":"FAQ.html#how-do-i-upgrade-to-the-latest-software","text":"The first step to upgrading the software is to review the latest config changes document. On occasion, changes are made to the software that require users to update their settings as part of a software upgrade. It is a good idea to review this document prior to upgrading. When ready to upgrade, the general method is to ssh into the Raspberry Pi and run: cd ~/klipper git pull ~/klipper/scripts/install-octopi.sh Then one can recompile and flash the micro-controller code. For example: make menuconfig make clean make sudo service klipper stop make flash FLASH_DEVICE=/dev/ttyACM0 sudo service klipper start However, it's often the case that only the host software changes. In this case, one can update and restart just the host software with: cd ~/klipper git pull sudo service klipper restart If after using this shortcut the software warns about needing to reflash the micro-controller or some other unusual error occurs, then follow the full upgrade steps outlined above. If any errors persist then double check the config changes document, as you may need to modify the printer configuration. Note that the RESTART and FIRMWARE_RESTART g-code commands do not load new software - the above \"sudo service klipper restart\" and \"make flash\" commands are needed for a software change to take effect.","title":"How do I upgrade to the latest software?"},{"location":"FAQ.html#how-do-i-uninstall-klipper","text":"On the firmware end, nothing special needs to happen. Just follow the flashing directions for the new firmware. On the raspberry pi end, an uninstall script is available in scripts/klipper-uninstall.sh . For example: sudo ~/klipper/scripts/klipper-uninstall.sh rm -rf ~/klippy-env ~/klipper","title":"How do I uninstall Klipper?"},{"location":"Features.html","text":"Features \u00b6 Klipper has several compelling features: High precision stepper movement. Klipper utilizes an application processor (such as a low-cost Raspberry Pi) when calculating printer movements. The application processor determines when to step each stepper motor, it compresses those events, transmits them to the micro-controller, and then the micro-controller executes each event at the requested time. Each stepper event is scheduled with a precision of 25 micro-seconds or better. The software does not use kinematic estimations (such as the Bresenham algorithm) - instead it calculates precise step times based on the physics of acceleration and the physics of the machine kinematics. More precise stepper movement provides quieter and more stable printer operation. Best in class performance. Klipper is able to achieve high stepping rates on both new and old micro-controllers. Even old 8-bit micro-controllers can obtain rates over 175K steps per second. On more recent micro-controllers, several million steps per second are possible. Higher stepper rates enable higher print velocities. The stepper event timing remains precise even at high speeds which improves overall stability. Klipper supports printers with multiple micro-controllers. For example, one micro-controller could be used to control an extruder, while another controls the printer's heaters, while a third controls the rest of the printer. The Klipper host software implements clock synchronization to account for clock drift between micro-controllers. No special code is needed to enable multiple micro-controllers - it just requires a few extra lines in the config file. Configuration via simple config file. There's no need to reflash the micro-controller to change a setting. All of Klipper's configuration is stored in a standard config file which can be easily edited. This makes it easier to setup and maintain the hardware. Klipper supports \"Smooth Pressure Advance\" - a mechanism to account for the effects of pressure within an extruder. This reduces extruder \"ooze\" and improves the quality of print corners. Klipper's implementation does not introduce instantaneous extruder speed changes, which improves overall stability and robustness. Klipper supports \"Input Shaping\" to reduce the impact of vibrations on print quality. This can reduce or eliminate \"ringing\" (also known as \"ghosting\", \"echoing\", or \"rippling\") in prints. It may also allow one to obtain faster printing speeds while still maintaining high print quality. Klipper uses an \"iterative solver\" to calculate precise step times from simple kinematic equations. This makes porting Klipper to new types of robots easier and it keeps timing precise even with complex kinematics (no \"line segmentation\" is needed). Klipper is hardware agnostic. One should get the same precise timing independent of the low-level electronics hardware. The Klipper micro-controller code is designed to faithfully follow the schedule provided by the Klipper host software (or prominently alert the user if it is unable to). This makes it easier to use available hardware, to upgrade to new hardware, and to have confidence in the hardware. Portable code. Klipper works on ARM, AVR, PRU, and other micro-controllers. Existing \"reprap\" style printers can run Klipper without hardware modification - just add a Raspberry Pi. Klipper's internal code layout makes it easier to support other micro-controller architectures as well. Simpler code. Klipper uses a very high level language (Python) for most code. The kinematics algorithms, the G-code parsing, the heating and thermistor algorithms, etc. are all written in Python. This makes it easier to develop new functionality. Custom programmable macros. New G-Code commands can be defined in the printer config file (no code changes are necessary). Those commands are programmable - allowing them to produce different actions depending on the state of the printer. Builtin API server. In addition to the standard G-Code interface, Klipper supports a rich JSON based application interface. This enables programmers to build external applications with detailed control of the printer. Additional features \u00b6 Klipper supports many standard 3d printer features: Several web interfaces available. Works with Mainsail, Fluidd, OctoPrint and others. This allows the printer to be controlled using a regular web-browser. The same Raspberry Pi that runs Klipper can also run the web interface. Standard G-Code support. Common g-code commands that are produced by typical \"slicers\" (SuperSlicer, Cura, PrusaSlicer, etc.) are supported. Support for multiple extruders. Extruders with shared heaters and extruders on independent carriages (IDEX) are also supported. Support for cartesian, delta, corexy, corexz, hybrid-corexy, hybrid-corexz, deltesian, rotary delta, polar, and cable winch style printers. Automatic bed leveling support. Klipper can be configured for basic bed tilt detection or full mesh bed leveling. The bed mesh can be customized to the print size (adaptive bed mesh). If the bed uses multiple Z steppers then Klipper can also level by independently manipulating the Z steppers. Most Z height probes are supported, including BL-Touch probes and servo activated probes. Probes may be calibrated for axis twist compensation. If using an \"eddy current probe\" then one can utilize fast bed mesh scanning, Automatic delta calibration support. The calibration tool can perform basic height calibration as well as an enhanced X and Y dimension calibration. The calibration can be done with a Z height probe or via manual probing. Run-time \"exclude object\" support. When configured, this module may facilitate canceling of just one object in a multi-part print. Support for common temperature sensors (eg, common thermistors, AD595, AD597, AD849x, PT100, PT1000, MAX6675, MAX31855, MAX31856, MAX31865, BME280, HTU21D, DS18B20, AHT10, SHT3x, and LM75). Custom thermistors and custom analog temperature sensors can also be configured. One can monitor the internal micro-controller temperature sensor and the internal temperature sensor of a Raspberry Pi. Basic thermal heater protection enabled by default. Support for standard fans, nozzle fans, and temperature controlled fans. No need to keep fans running when the printer is idle. Fan speed can be monitored on fans that have a tachometer. One can assign a \"math formula\" to a fan for automatic fan speed updating. Support for run-time configuration of TMC2130, TMC2208/TMC2224, TMC2209, TMC2240, TMC2660, and TMC5160 stepper motor drivers. There is also support for current control of traditional stepper drivers via AD5206, DAC084S085, MCP4451, MCP4728, MCP4018, and PWM pins. Support for common LCD displays attached directly to the printer. A default menu is also available. The contents of the display and menu can be fully customized via the config file. Constant acceleration and \"look-ahead\" support. All printer moves will gradually accelerate from standstill to cruising speed and then decelerate back to a standstill. The incoming stream of G-Code movement commands are queued and analyzed - the acceleration between movements in a similar direction will be optimized to reduce print stalls and improve overall print time. Klipper implements a \"stepper phase endstop\" algorithm that can improve the accuracy of typical endstop switches. When properly tuned it can improve a print's first layer bed adhesion. Support for filament presence sensors, filament motion sensors, and filament width sensors. Support for measuring and recording acceleration using adxl345, mpu9250, mpu6050, lis2dw12, lis3dh, and icm20948 accelerometers. Support for limiting the top speed of short \"zigzag\" moves to reduce printer vibration and noise. See the kinematics document for more information. Sample configuration files are available for many common printers. Check the config directory for a list. To get started with Klipper, read the installation guide. Step Benchmarks \u00b6 Below are the results of stepper performance tests. The numbers shown represent total number of steps per second on the micro-controller. Micro-controller 1 stepper active 3 steppers active 16Mhz AVR 157K 99K 20Mhz AVR 196K 123K SAMD21 686K 471K STM32F042 814K 578K Beaglebone PRU 866K 708K STM32G0B1 1103K 790K STM32F103 1180K 818K SAM3X8E 1273K 981K SAM4S8C 1690K 1385K LPC1768 1923K 1351K LPC1769 2353K 1622K SAM4E8E 2500K 1674K SAMD51 3077K 1885K AR100 3529K 2507K STM32G431 3617K 2452K STM32F407 3652K 2459K STM32F446 3913K 2634K RP2040 4000K 2571K RP2350 4167K 2663K SAME70 6667K 4737K STM32H723 7429K 8619K If unsure of the micro-controller on a particular board, find the appropriate config file , and look for the micro-controller name in the comments at the top of that file. Further details on the benchmarks are available in the Benchmarks document .","title":"Features"},{"location":"Features.html#features","text":"Klipper has several compelling features: High precision stepper movement. Klipper utilizes an application processor (such as a low-cost Raspberry Pi) when calculating printer movements. The application processor determines when to step each stepper motor, it compresses those events, transmits them to the micro-controller, and then the micro-controller executes each event at the requested time. Each stepper event is scheduled with a precision of 25 micro-seconds or better. The software does not use kinematic estimations (such as the Bresenham algorithm) - instead it calculates precise step times based on the physics of acceleration and the physics of the machine kinematics. More precise stepper movement provides quieter and more stable printer operation. Best in class performance. Klipper is able to achieve high stepping rates on both new and old micro-controllers. Even old 8-bit micro-controllers can obtain rates over 175K steps per second. On more recent micro-controllers, several million steps per second are possible. Higher stepper rates enable higher print velocities. The stepper event timing remains precise even at high speeds which improves overall stability. Klipper supports printers with multiple micro-controllers. For example, one micro-controller could be used to control an extruder, while another controls the printer's heaters, while a third controls the rest of the printer. The Klipper host software implements clock synchronization to account for clock drift between micro-controllers. No special code is needed to enable multiple micro-controllers - it just requires a few extra lines in the config file. Configuration via simple config file. There's no need to reflash the micro-controller to change a setting. All of Klipper's configuration is stored in a standard config file which can be easily edited. This makes it easier to setup and maintain the hardware. Klipper supports \"Smooth Pressure Advance\" - a mechanism to account for the effects of pressure within an extruder. This reduces extruder \"ooze\" and improves the quality of print corners. Klipper's implementation does not introduce instantaneous extruder speed changes, which improves overall stability and robustness. Klipper supports \"Input Shaping\" to reduce the impact of vibrations on print quality. This can reduce or eliminate \"ringing\" (also known as \"ghosting\", \"echoing\", or \"rippling\") in prints. It may also allow one to obtain faster printing speeds while still maintaining high print quality. Klipper uses an \"iterative solver\" to calculate precise step times from simple kinematic equations. This makes porting Klipper to new types of robots easier and it keeps timing precise even with complex kinematics (no \"line segmentation\" is needed). Klipper is hardware agnostic. One should get the same precise timing independent of the low-level electronics hardware. The Klipper micro-controller code is designed to faithfully follow the schedule provided by the Klipper host software (or prominently alert the user if it is unable to). This makes it easier to use available hardware, to upgrade to new hardware, and to have confidence in the hardware. Portable code. Klipper works on ARM, AVR, PRU, and other micro-controllers. Existing \"reprap\" style printers can run Klipper without hardware modification - just add a Raspberry Pi. Klipper's internal code layout makes it easier to support other micro-controller architectures as well. Simpler code. Klipper uses a very high level language (Python) for most code. The kinematics algorithms, the G-code parsing, the heating and thermistor algorithms, etc. are all written in Python. This makes it easier to develop new functionality. Custom programmable macros. New G-Code commands can be defined in the printer config file (no code changes are necessary). Those commands are programmable - allowing them to produce different actions depending on the state of the printer. Builtin API server. In addition to the standard G-Code interface, Klipper supports a rich JSON based application interface. This enables programmers to build external applications with detailed control of the printer.","title":"Features"},{"location":"Features.html#additional-features","text":"Klipper supports many standard 3d printer features: Several web interfaces available. Works with Mainsail, Fluidd, OctoPrint and others. This allows the printer to be controlled using a regular web-browser. The same Raspberry Pi that runs Klipper can also run the web interface. Standard G-Code support. Common g-code commands that are produced by typical \"slicers\" (SuperSlicer, Cura, PrusaSlicer, etc.) are supported. Support for multiple extruders. Extruders with shared heaters and extruders on independent carriages (IDEX) are also supported. Support for cartesian, delta, corexy, corexz, hybrid-corexy, hybrid-corexz, deltesian, rotary delta, polar, and cable winch style printers. Automatic bed leveling support. Klipper can be configured for basic bed tilt detection or full mesh bed leveling. The bed mesh can be customized to the print size (adaptive bed mesh). If the bed uses multiple Z steppers then Klipper can also level by independently manipulating the Z steppers. Most Z height probes are supported, including BL-Touch probes and servo activated probes. Probes may be calibrated for axis twist compensation. If using an \"eddy current probe\" then one can utilize fast bed mesh scanning, Automatic delta calibration support. The calibration tool can perform basic height calibration as well as an enhanced X and Y dimension calibration. The calibration can be done with a Z height probe or via manual probing. Run-time \"exclude object\" support. When configured, this module may facilitate canceling of just one object in a multi-part print. Support for common temperature sensors (eg, common thermistors, AD595, AD597, AD849x, PT100, PT1000, MAX6675, MAX31855, MAX31856, MAX31865, BME280, HTU21D, DS18B20, AHT10, SHT3x, and LM75). Custom thermistors and custom analog temperature sensors can also be configured. One can monitor the internal micro-controller temperature sensor and the internal temperature sensor of a Raspberry Pi. Basic thermal heater protection enabled by default. Support for standard fans, nozzle fans, and temperature controlled fans. No need to keep fans running when the printer is idle. Fan speed can be monitored on fans that have a tachometer. One can assign a \"math formula\" to a fan for automatic fan speed updating. Support for run-time configuration of TMC2130, TMC2208/TMC2224, TMC2209, TMC2240, TMC2660, and TMC5160 stepper motor drivers. There is also support for current control of traditional stepper drivers via AD5206, DAC084S085, MCP4451, MCP4728, MCP4018, and PWM pins. Support for common LCD displays attached directly to the printer. A default menu is also available. The contents of the display and menu can be fully customized via the config file. Constant acceleration and \"look-ahead\" support. All printer moves will gradually accelerate from standstill to cruising speed and then decelerate back to a standstill. The incoming stream of G-Code movement commands are queued and analyzed - the acceleration between movements in a similar direction will be optimized to reduce print stalls and improve overall print time. Klipper implements a \"stepper phase endstop\" algorithm that can improve the accuracy of typical endstop switches. When properly tuned it can improve a print's first layer bed adhesion. Support for filament presence sensors, filament motion sensors, and filament width sensors. Support for measuring and recording acceleration using adxl345, mpu9250, mpu6050, lis2dw12, lis3dh, and icm20948 accelerometers. Support for limiting the top speed of short \"zigzag\" moves to reduce printer vibration and noise. See the kinematics document for more information. Sample configuration files are available for many common printers. Check the config directory for a list. To get started with Klipper, read the installation guide.","title":"Additional features"},{"location":"Features.html#step-benchmarks","text":"Below are the results of stepper performance tests. The numbers shown represent total number of steps per second on the micro-controller. Micro-controller 1 stepper active 3 steppers active 16Mhz AVR 157K 99K 20Mhz AVR 196K 123K SAMD21 686K 471K STM32F042 814K 578K Beaglebone PRU 866K 708K STM32G0B1 1103K 790K STM32F103 1180K 818K SAM3X8E 1273K 981K SAM4S8C 1690K 1385K LPC1768 1923K 1351K LPC1769 2353K 1622K SAM4E8E 2500K 1674K SAMD51 3077K 1885K AR100 3529K 2507K STM32G431 3617K 2452K STM32F407 3652K 2459K STM32F446 3913K 2634K RP2040 4000K 2571K RP2350 4167K 2663K SAME70 6667K 4737K STM32H723 7429K 8619K If unsure of the micro-controller on a particular board, find the appropriate config file , and look for the micro-controller name in the comments at the top of that file. Further details on the benchmarks are available in the Benchmarks document .","title":"Step Benchmarks"},{"location":"G-Codes.html","text":"G-Codes \u00b6 This document describes the commands that Klipper supports. These are commands that one may enter into the OctoPrint terminal tab. G-Code commands \u00b6 Klipper supports the following standard G-Code commands: Move (G0 or G1): G1 [X] [Y] [Z] [E] [F] Dwell: G4 P 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] [Y] [Z] [E] Set speed factor override percentage: M220 S Set extrude factor override percentage: M221 S Set acceleration: M204 S OR M204 P T 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] [S] Set extruder temperature and wait: M109 [T] S Note: M109 always waits for temperature to settle at requested value Set bed temperature: M140 [S] Set bed temperature and wait: M190 S Note: M190 always waits for temperature to settle at requested value Set fan speed: M106 S 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=] [NAME=] : 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--.csv where is the name of the accelerometer chip ( my_chip_name from [adxl345 my_chip_name] ) and 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 part of the name is not generated. ACCELEROMETER_QUERY \u00b6 ACCELEROMETER_QUERY [CHIP=] [RATE=] : 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=] REG= : queries ADXL345 register \"register\" (e.g. 44 or 0x2C). Can be useful for debugging purposes. ACCELEROMETER_DEBUG_WRITE \u00b6 ACCELEROMETER_DEBUG_WRITE [CHIP=] REG= VAL= : 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= : Perform angle calibration on the given sensor (there must be an [angle chip_name] config section that has specified a stepper parameter). IMPORTANT - this tool will command the stepper motor to move without checking the normal kinematic boundary limits. Ideally the motor should be disconnected from any printer carriage before performing calibration. If the stepper can not be disconnected from the printer, make sure the carriage is near the center of its rail before starting calibration. (The stepper motor may move forwards or backwards two full rotations during this test.) After completing this test use the SAVE_CONFIG command to save the calibration data to the config file. In order to use this tool the Python \"numpy\" package must be installed (see the measuring resonance document for more information). ANGLE_CHIP_CALIBRATE \u00b6 ANGLE_CHIP_CALIBRATE CHIP= : Perform internal sensor calibration, if implemented (MT6826S/MT6835). MT68XX : The motor should be disconnected from any printer carriage before performing calibration. After calibration, the sensor should be reset by disconnecting the power. ANGLE_DEBUG_READ \u00b6 ANGLE_DEBUG_READ CHIP= REG= : 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= REG= VAL= : Writes raw \"value\" into register \"register\". Both \"value\" and \"register\" can be a decimal or a hexadecimal integer. Use with care, and refer to sensor data sheet for the reference. This is only available for tle5012b chips. [axis_twist_compensation] \u00b6 The following commands are available when the axis_twist_compensation config section is enabled. AXIS_TWIST_COMPENSATION_CALIBRATE \u00b6 AXIS_TWIST_COMPENSATION_CALIBRATE [AXIS=