diff --git a/Config_Reference.html b/Config_Reference.html index 4a9908a49..360349f0a 100644 --- a/Config_Reference.html +++ b/Config_Reference.html @@ -708,6 +708,15 @@ + + +
  • + + + [pid_profile] + + +
    • @@ -3900,6 +3909,15 @@ + + +
  • + + + [pid_profile] + + +
    • @@ -6438,6 +6456,34 @@

    [heater_bed][pid_profile]

    +

    Pid Profiles specify a set of PID values that can be loaded at runtime.

    +
    [pid_profile <heater> <profile-name>]
+pid_version: 1
+# This defines the version it was saved with and is important for compatibility
+# checks, leave it at 1!
+pid_target:
+# For reference only, specifies the temperature the profile was calibrated for.
+# If you create a custom profile, either enter the temperature that profile is
+# intended to be used at or leave it blank.
+pid_tolerance: 
+# The tolerance that was used when autocalibrating the profile. If you define
+# a custom profile, leave it empty.
+control: <pid|pid_v>
+# Has to be either pid or pid_v.
+# This parameter is required.
+pid_kp: 
+# The P value for the PID Control.
+# This parameter is required.
+pid_ki:
+# The I value for the PID Control.
+# This parameter is required.
+pid_kd: 
+# The D value for the PID Control.
+# This parameter is required.
+
    + +

    For more information, read up on docs/PID.md

    Bed level support

    [bed_mesh]

    Mesh Bed Leveling. One may define a bed_mesh config section to enable diff --git a/_kalico/__pycache__/mkdocs_hooks.cpython-310.pyc b/_kalico/__pycache__/mkdocs_hooks.cpython-310.pyc index c7e643b4a..0963afdaf 100644 Binary files a/_kalico/__pycache__/mkdocs_hooks.cpython-310.pyc and b/_kalico/__pycache__/mkdocs_hooks.cpython-310.pyc differ diff --git a/search/search_index.json b/search/search_index.json index 841be28d6..36030bd60 100644 --- a/search/search_index.json +++ b/search/search_index.json @@ -1 +1 @@ -{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"index.html","title":"Welcome to the Kalico documentation!","text":"

    Kalico is a community-maintained fork of the Klipper 3D-Printer firmware. It combines the power of a general purpose computer with one or more micro-controllers. See the features document for more information on why you should use Kalico.

    To begin using Kalico start by installing it. If you consider migrating from Klipper to Kalico, please read our dedicated migration guide.

    Kalico is Free Software. Read the documentation or view the Kalico code on GitHub.

    We depend on the generous support from our sponsors.

    "},{"location":"API_Server.html","title":"API server","text":"

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

    "},{"location":"API_Server.html#enabling-the-api-socket","title":"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\n

    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 Kalico.

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

    "},{"location":"API_Server.html#request-format","title":"Request format","text":"

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

    <json_object_1><0x03><json_object_2><0x03>...\n

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

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

    This tool can read a series of JSON commands from stdin, send them to Kalico, 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 Kalico API server does not have a newline requirement.)

    "},{"location":"API_Server.html#api-protocol","title":"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 Kalico \"endpoint\".

    The request dictionary may contain a \"params\" parameter which must be of a dictionary type. The \"params\" provide additional parameter information to the Kalico \"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 Kalico will respond to the request with a response message containing that \"id\". If \"id\" is omitted (or set to a JSON \"null\" value) then Kalico 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\"}}

    Kalico 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.

    "},{"location":"API_Server.html#subscriptions","title":"Subscriptions","text":"

    Some Kalico \"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 Kalico 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, Kalico 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 ({}).

    "},{"location":"API_Server.html#available-endpoints","title":"Available \"endpoints\"","text":"

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

    "},{"location":"API_Server.html#info","title":"info","text":"

    The \"info\" endpoint is used to obtain system and version information from Kalico. It is also used to provide the client's version information to Kalico. 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 Kalico API server.

    "},{"location":"API_Server.html#emergency_stop","title":"emergency_stop","text":"

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

    "},{"location":"API_Server.html#register_remote_method","title":"register_remote_method","text":"

    This endpoint allows clients to register methods that can be called from Kalico. 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 KliKalicopper. 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]\ngcode:\n  {action_call_remote_method(\"paneldue_beep\", frequency=300, duration=1.0)}\n

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

    "},{"location":"API_Server.html#objectslist","title":"objects/list","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\"]}}

    "},{"location":"API_Server.html#objectsquery","title":"objects/query","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.

    "},{"location":"API_Server.html#objectssubscribe","title":"objects/subscribe","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}}

    "},{"location":"API_Server.html#gcodehelp","title":"gcode/help","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\", ...}}

    "},{"location":"API_Server.html#gcodescript","title":"gcode/script","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.

    "},{"location":"API_Server.html#gcoderestart","title":"gcode/restart","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.

    "},{"location":"API_Server.html#gcodefirmware_restart","title":"gcode/firmware_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.

    "},{"location":"API_Server.html#gcodesubscribe_output","title":"gcode/subscribe_output","text":"

    This endpoint is used to subscribe to G-Code terminal messages that are generated by Kalico. 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 Kalico's state.

    "},{"location":"API_Server.html#motion_reportdump_stepper","title":"motion_report/dump_stepper","text":"

    This endpoint is used to subscribe to Kalico'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 Kalico'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.

    "},{"location":"API_Server.html#motion_reportdump_trapq","title":"motion_report/dump_trapq","text":"

    This endpoint is used to subscribe to Kalico's internal \"trapezoid motion queue\". Obtaining these low-level motion updates may be useful for diagnostic and debugging purposes. Using this endpoint may increase Kalico'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.

    "},{"location":"API_Server.html#adxl345dump_adxl345","title":"adxl345/dump_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 Kalico'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.

    "},{"location":"API_Server.html#angledump_angle","title":"angle/dump_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 Kalico'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.

    "},{"location":"API_Server.html#hx71xdump_hx71x","title":"hx71x/dump_hx71x","text":"

    This endpoint is used to subscribe to raw HX711 and HX717 ADC data. Obtaining these low-level ADC updates may be useful for diagnostic and debugging purposes. Using this endpoint may increase Kalico's system load.

    A request may look like: {\"id\": 123, \"method\":\"hx71x/dump_hx71x\", \"params\": {\"sensor\": \"load_cell\", \"response_template\": {}}} and might return: {\"id\": 123,\"result\":{\"header\":[\"time\",\"counts\",\"value\"]}} and might later produce asynchronous messages such as: {\"params\":{\"data\":[[3292.432935, 562534, 0.067059278], [3292.4394937, 5625322, 0.670590639]]}}

    "},{"location":"API_Server.html#ads1220dump_ads1220","title":"ads1220/dump_ads1220","text":"

    This endpoint is used to subscribe to raw ADS1220 ADC data. Obtaining these low-level ADC updates may be useful for diagnostic and debugging purposes. Using this endpoint may increase Kalico's system load.

    A request may look like: {\"id\": 123, \"method\":\"ads1220/dump_ads1220\", \"params\": {\"sensor\": \"load_cell\", \"response_template\": {}}} and might return: {\"id\": 123,\"result\":{\"header\":[\"time\",\"counts\",\"value\"]}} and might later produce asynchronous messages such as: {\"params\":{\"data\":[[3292.432935, 562534, 0.067059278], [3292.4394937, 5625322, 0.670590639]]}}

    "},{"location":"API_Server.html#pause_resumecancel","title":"pause_resume/cancel","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.

    "},{"location":"API_Server.html#pause_resumepause","title":"pause_resume/pause","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.

    "},{"location":"API_Server.html#pause_resumeresume","title":"pause_resume/resume","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.

    "},{"location":"API_Server.html#query_endstopsstatus","title":"query_endstops/status","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.

    "},{"location":"Axis_Twist_Compensation.html","title":"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, as the calibration could be affected by issues with probe accuracy, bed flatness, Z axis alignment, etc.

    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.

    "},{"location":"Axis_Twist_Compensation.html#overview-of-compensation-usage","title":"Overview of compensation usage","text":"

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

    "},{"location":"Axis_Twist_Compensation.html#basic-usage-x-axis-calibration","title":"Basic Usage: X-Axis Calibration","text":"
    1. After setting up the [axis_twist_compensation] module, run:
    AXIS_TWIST_COMPENSATION_CALIBRATE\n

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

    1. Adjust Your Z Offset: After completing the calibration, be sure to [adjust your Z offset] (Probe_Calibrate.md#calibrating-probe-z-offset).

    2. Perform Bed Leveling Operations: Use probe-based operations as needed, such as: - Screws Tilt Adjust - Z Tilt Adjust

    3. Finalize the Setup: - Home all axes, and perform a Bed Mesh if necessary. - Run a test print, followed by any fine-tuning if needed.

    "},{"location":"Axis_Twist_Compensation.html#for-y-axis-calibration","title":"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\n

    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.

    "},{"location":"Axis_Twist_Compensation.html#axis_twist_compensation-setup-and-commands","title":"[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

    "},{"location":"BLTouch.html","title":"BL-Touch","text":""},{"location":"BLTouch.html#connecting-bl-touch","title":"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]\nsensor_pin: ^P1.24\ncontrol_pin: P1.26\n

    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]\nhome_xy_position: 100, 100 # Change coordinates to the center of your print bed\nspeed: 50\nz_hop: 10                 # Move up 10mm\nz_hop_speed: 5\n

    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.

    "},{"location":"BLTouch.html#initial-tests","title":"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.

    "},{"location":"BLTouch.html#bl-touch-gone-bad","title":"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.

    "},{"location":"BLTouch.html#bl-touch-clones","title":"BL-Touch \"clones\"","text":"

    Many BL-Touch \"clone\" devices work correctly with Kalico 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 Kalico 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 Kalico's internal sensor verification test. On these devices, attempts to home or probe can result in Kalico 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 Kalico config file.

    A rare number of old \"clone\" devices are unable to report when they have successfully raised their probe. On these devices Kalico 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 Kalico config file.

    "},{"location":"BLTouch.html#bl-touch-v3","title":"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. Kalico 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).

    "},{"location":"BLTouch.html#multi-probing-without-stowing","title":"Multi-probing without stowing","text":"

    By default, Kalico 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. Kalico 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 Kalico 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).

    "},{"location":"BLTouch.html#calibrating-the-bl-touch-offsets","title":"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.

    "},{"location":"BLTouch.html#bl-touch-output-mode","title":"BL-Touch output mode","text":""},{"location":"Beaglebone.html","title":"Beaglebone","text":"

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

    "},{"location":"Beaglebone.html#building-an-os-image","title":"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 Kalico you need to free-up additional space. there are 3 options to do that:

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

    To remove some BeagleBone \"Demo\" resources execute these commands

    sudo apt remove bb-node-red-installer\nsudo apt remove bb-code-server\n

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

    sudo growpart /dev/mmcblk0 1\nsudo resize2fs /dev/mmcblk0p1\n

    Install Kalico by running the following commands:

    git clone https://github.com/KalicoCrew/kalico klipper\n./klipper/scripts/install-beaglebone.sh\n

    After installing Kalico 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 Kalico 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 Kalico 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 Kalico + 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.

    "},{"location":"Beaglebone.html#installing-octoprint","title":"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\ncd OctoPrint/\nvirtualenv venv\n./venv/bin/python setup.py install\n

    And setup OctoPrint to start at bootup:

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

    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\n

    Then start the Octoprint service:

    sudo systemctl start octoprint\n

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

    "},{"location":"Beaglebone.html#building-the-beaglebone-pru-micro-controller-code-pru-firmware","title":"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\n

    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]\nUBOOT: Booted Device-Tree:[am335x-boneblack-uboot-univ.dts]\nUBOOT: Loaded Overlay:[BB-ADC-00A0.bb.org-overlays]\nUBOOT: Loaded Overlay:[BB-BONE-eMMC1-01-00A0.bb.org-overlays]\nkernel:[5.10.168-ti-r71]\n/boot/uEnv.txt Settings:\nuboot_overlay_options:[enable_uboot_overlays=1]\nuboot_overlay_options:[disable_uboot_overlay_video=0]\nuboot_overlay_options:[disable_uboot_overlay_audio=1]\nuboot_overlay_options:[disable_uboot_overlay_wireless=1]\nuboot_overlay_options:[enable_uboot_cape_universal=1]\npkg:[bb-cape-overlays]:[4.14.20210821.0-0~bullseye+20210821]\npkg:[bb-customizations]:[1.20230720.1-0~bullseye+20230720]\npkg:[bb-usb-gadgets]:[1.20230414.0-0~bullseye+20230414]\npkg:[bb-wl18xx-firmware]:[1.20230414.0-0~bullseye+20230414]\n.............\n.............\n

    To compile the Kalico 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/\nmake menuconfig\n

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

    sudo service klipper stop\nmake flash\nsudo service klipper start\n

    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\n

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

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

    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.

    "},{"location":"Beaglebone.html#building-and-installing-linux-host-micro-controller-code","title":"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\n

    Then install this micro-controller code as well:

    sudo service klipper stop\nmake flash\nsudo service klipper start\n

    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.

    "},{"location":"Beaglebone.html#remaining-configuration","title":"Remaining configuration","text":"

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

    "},{"location":"Beaglebone.html#printing-on-the-beaglebone","title":"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 Kalico and disable any DEBUG or VERBOSE logging options if you did enable them.

    "},{"location":"Beaglebone.html#avr-micro-controller-code-build","title":"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\nsudo apt-get install avrdude gcc-avr binutils-avr avr-libc\n

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

    sudo apt-get remove avrdude gcc-avr binutils-avr avr-libc\nsudo apt-get install gcc-pru\n
    "},{"location":"Beaglebone.html#hardware-pin-designation","title":"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\n

    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\n

    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.

    "},{"location":"Beaglebone.html#enabling-hardware-spi","title":"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\n

    uncomment variable

    disable_uboot_overlay_audio=1\n

    next uncomment variable and define it this way

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

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

    ls /dev/spidev1.*\n

    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.

    "},{"location":"Beaglebone.html#enabling-hardware-i2c","title":"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

    "},{"location":"Beaglebone.html#enabling-hardware-uartserialcan","title":"Enabling hardware UART(Serial)/CAN","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

    "},{"location":"Bed_Level.html","title":"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 Kalico.

    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.

    "},{"location":"Bed_Level.html#choose-the-appropriate-calibration-mechanism","title":"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.

    "},{"location":"Bed_Level.html#the-paper-test","title":"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!

    Kalico 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.\nRecv: // Finish with ACCEPT or ABORT command.\nRecv: // Z position: ?????? --> 5.000 <-- ??????\n

    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\n

    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\n

    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\n

    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.

    "},{"location":"Bed_Level.html#determining-thermal-expansion","title":"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 layer 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.

    "},{"location":"Bed_Mesh.html","title":"Bed Mesh","text":"

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

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

    "},{"location":"Bed_Mesh.html#basic-configuration","title":"Basic Configuration","text":""},{"location":"Bed_Mesh.html#rectangular-beds","title":"Rectangular Beds","text":"

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

    [bed_mesh]\nspeed: 120\nhorizontal_move_z: 5\nmesh_min: 35, 6\nmesh_max: 240, 198\nprobe_count: 5, 3\n

    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).

    "},{"location":"Bed_Mesh.html#round-beds","title":"Round beds","text":"

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

    [bed_mesh]\nspeed: 120\nhorizontal_move_z: 5\nmesh_radius: 75\nmesh_origin: 0, 0\nround_probe_count: 5\n

    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.

    "},{"location":"Bed_Mesh.html#advanced-configuration","title":"Advanced Configuration","text":"

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

    "},{"location":"Bed_Mesh.html#mesh-interpolation","title":"Mesh Interpolation","text":"

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

    [bed_mesh]\nspeed: 120\nhorizontal_move_z: 5\nmesh_min: 35, 6\nmesh_max: 240, 198\nprobe_count: 5, 3\nmesh_pps: 2, 3\nalgorithm: bicubic\nbicubic_tension: 0.2\n

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

    "},{"location":"Bed_Mesh.html#move-splitting","title":"Move Splitting","text":"

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

    [bed_mesh]\nspeed: 120\nhorizontal_move_z: 5\nmesh_min: 35, 6\nmesh_max: 240, 198\nprobe_count: 5, 3\nmove_check_distance: 5\nsplit_delta_z: .025\n

    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.

    "},{"location":"Bed_Mesh.html#mesh-fade","title":"Mesh Fade","text":"

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

    [bed_mesh]\nspeed: 120\nhorizontal_move_z: 5\nmesh_min: 35, 6\nmesh_max: 240, 198\nprobe_count: 5, 3\nfade_start: 1\nfade_end: 10\nfade_target: 0\n
    "},{"location":"Bed_Mesh.html#configuring-the-zero-reference-position","title":"Configuring the zero reference position","text":"

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

    [bed_mesh]\nspeed: 120\nhorizontal_move_z: 5\nmesh_min: 35, 6\nmesh_max: 240, 198\nzero_reference_position: 125, 110\nprobe_count: 5, 3\n
    "},{"location":"Bed_Mesh.html#the-deprecated-relative_reference_index","title":"The deprecated relative_reference_index","text":"

    Existing configurations using the relative_reference_index option must be updated to use the zero_reference_position. The response to the BED_MESH_OUTPUT PGP=1 gcode command will include the (X, Y) coordinate associated with the index; this position may be used as the value for the zero_reference_position. The output will look similar to the following:

    // bed_mesh: generated points\n// Index | Tool Adjusted | Probe\n// 0 | (1.0, 1.0) | (24.0, 6.0)\n// 1 | (36.7, 1.0) | (59.7, 6.0)\n// 2 | (72.3, 1.0) | (95.3, 6.0)\n// 3 | (108.0, 1.0) | (131.0, 6.0)\n... (additional generated points)\n// bed_mesh: relative_reference_index 24 is (131.5, 108.0)\n

    Note: The above output is also printed in klippy.log during initialization.

    Using the example above we see that the relative_reference_index is printed along with its coordinate. Thus the zero_reference_position is 131.5, 108.

    "},{"location":"Bed_Mesh.html#faulty-regions","title":"Faulty Regions","text":"

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

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

    [bed_mesh]\nspeed: 120\nhorizontal_move_z: 5\nmesh_min: 35, 6\nmesh_max: 240, 198\nprobe_count: 5, 3\nfaulty_region_1_min: 130.0, 0.0\nfaulty_region_1_max: 145.0, 40.0\nfaulty_region_2_min: 225.0, 0.0\nfaulty_region_2_max: 250.0, 25.0\nfaulty_region_3_min: 165.0, 95.0\nfaulty_region_3_max: 205.0, 110.0\nfaulty_region_4_min: 30.0, 170.0\nfaulty_region_4_max: 45.0, 210.0\n

    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.

    "},{"location":"Bed_Mesh.html#adaptive-meshes","title":"Adaptive Meshes","text":"

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

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

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

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

    [bed_mesh]\nspeed: 120\nhorizontal_move_z: 5\nmesh_min: 35, 6\nmesh_max: 240, 198\nprobe_count: 5, 3\nadaptive_margin: 5\n

    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.

    "},{"location":"Bed_Mesh.html#bed-mesh-gcodes","title":"Bed Mesh Gcodes","text":""},{"location":"Bed_Mesh.html#calibration","title":"Calibration","text":"

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

    Initiates the probing procedure for Bed Mesh Calibration.

    The mesh will be saved into a profile specified by the PROFILE parameter, or default if unspecified. If METHOD=manual is selected then manual probing will occur. When switching between automatic and manual probing the generated mesh points will automatically be adjusted.

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

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

    "},{"location":"Bed_Mesh.html#profiles","title":"Profiles","text":"

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

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

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

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

    BED_MESH_PROFILE REMOVE=default

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

    "},{"location":"Bed_Mesh.html#loading-the-default-profile","title":"Loading the default profile","text":"

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

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

    [delayed_gcode bed_mesh_init]\ninitial_duration: .01\ngcode:\n  BED_MESH_PROFILE LOAD=default\n
    "},{"location":"Bed_Mesh.html#output","title":"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\n// Index | Tool Adjusted | Probe\n// 0 | (11.0, 1.0) | (35.0, 6.0)\n// 1 | (62.2, 1.0) | (86.2, 6.0)\n// 2 | (113.5, 1.0) | (137.5, 6.0)\n// 3 | (164.8, 1.0) | (188.8, 6.0)\n// 4 | (216.0, 1.0) | (240.0, 6.0)\n// 5 | (216.0, 97.0) | (240.0, 102.0)\n// 6 | (164.8, 97.0) | (188.8, 102.0)\n// 7 | (113.5, 97.0) | (137.5, 102.0)\n// 8 | (62.2, 97.0) | (86.2, 102.0)\n// 9 | (11.0, 97.0) | (35.0, 102.0)\n// 10 | (11.0, 193.0) | (35.0, 198.0)\n// 11 | (62.2, 193.0) | (86.2, 198.0)\n// 12 | (113.5, 193.0) | (137.5, 198.0)\n// 13 | (164.8, 193.0) | (188.8, 198.0)\n// 14 | (216.0, 193.0) | (240.0, 198.0)\n

    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.

    "},{"location":"Bed_Mesh.html#clear-mesh-state","title":"Clear Mesh State","text":"

    BED_MESH_CLEAR

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

    "},{"location":"Bed_Mesh.html#apply-xy-offsets","title":"Apply X/Y offsets","text":"

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

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

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

    "},{"location":"Benchmarks.html","title":"Benchmarks","text":"

    This document describes Kalico benchmarks.

    "},{"location":"Benchmarks.html#micro-controller-benchmarks","title":"Micro-controller Benchmarks","text":"

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

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

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

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

    "},{"location":"Benchmarks.html#step-rate-benchmark-test","title":"Step rate benchmark test","text":"

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

    SET start_clock {clock+freq}\nSET ticks 1000\n\nreset_step_clock oid=0 clock={start_clock}\nset_next_step_dir oid=0 dir=0\nqueue_step oid=0 interval={ticks} count=60000 add=0\nset_next_step_dir oid=0 dir=1\nqueue_step oid=0 interval=3000 count=1 add=0\n\nreset_step_clock oid=1 clock={start_clock}\nset_next_step_dir oid=1 dir=0\nqueue_step oid=1 interval={ticks} count=60000 add=0\nset_next_step_dir oid=1 dir=1\nqueue_step oid=1 interval=3000 count=1 add=0\n\nreset_step_clock oid=2 clock={start_clock}\nset_next_step_dir oid=2 dir=0\nqueue_step oid=2 interval={ticks} count=60000 add=0\nset_next_step_dir oid=2 dir=1\nqueue_step oid=2 interval=3000 count=1 add=0\n

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

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

    clear_shutdown\n

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

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

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

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

    "},{"location":"Benchmarks.html#avr-step-rate-benchmark","title":"AVR step rate benchmark","text":"

    The following configuration sequence is used on AVR chips:

    allocate_oids count=3\nconfig_stepper oid=0 step_pin=PA5 dir_pin=PA4 invert_step=0 step_pulse_ticks=32\nconfig_stepper oid=1 step_pin=PA3 dir_pin=PA2 invert_step=0 step_pulse_ticks=32\nconfig_stepper oid=2 step_pin=PC7 dir_pin=PC6 invert_step=0 step_pulse_ticks=32\nfinalize_config crc=0\n

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

    avr ticks 1 stepper 102 3 stepper 486"},{"location":"Benchmarks.html#arduino-due-step-rate-benchmark","title":"Arduino Due step rate benchmark","text":"

    The following configuration sequence is used on the Due:

    allocate_oids count=3\nconfig_stepper oid=0 step_pin=PB27 dir_pin=PA21 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=1 step_pin=PB26 dir_pin=PC30 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=2 step_pin=PA21 dir_pin=PC30 invert_step=-1 step_pulse_ticks=0\nfinalize_config crc=0\n

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

    sam3x8e ticks 1 stepper 66 3 stepper 257"},{"location":"Benchmarks.html#duet-maestro-step-rate-benchmark","title":"Duet Maestro step rate benchmark","text":"

    The following configuration sequence is used on the Duet Maestro:

    allocate_oids count=3\nconfig_stepper oid=0 step_pin=PC26 dir_pin=PC18 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=1 step_pin=PC26 dir_pin=PA8 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=2 step_pin=PC26 dir_pin=PB4 invert_step=-1 step_pulse_ticks=0\nfinalize_config crc=0\n

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

    sam4s8c ticks 1 stepper 71 3 stepper 260"},{"location":"Benchmarks.html#duet-wifi-step-rate-benchmark","title":"Duet Wifi step rate benchmark","text":"

    The following configuration sequence is used on the Duet Wifi:

    allocate_oids count=3\nconfig_stepper oid=0 step_pin=PD6 dir_pin=PD11 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=1 step_pin=PD7 dir_pin=PD12 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=2 step_pin=PD8 dir_pin=PD13 invert_step=-1 step_pulse_ticks=0\nfinalize_config crc=0\n

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

    sam4e8e ticks 1 stepper 48 3 stepper 215"},{"location":"Benchmarks.html#beaglebone-pru-step-rate-benchmark","title":"Beaglebone PRU step rate benchmark","text":"

    The following configuration sequence is used on the PRU:

    allocate_oids count=3\nconfig_stepper oid=0 step_pin=gpio0_23 dir_pin=gpio1_12 invert_step=0 step_pulse_ticks=20\nconfig_stepper oid=1 step_pin=gpio1_15 dir_pin=gpio0_26 invert_step=0 step_pulse_ticks=20\nconfig_stepper oid=2 step_pin=gpio0_22 dir_pin=gpio2_1 invert_step=0 step_pulse_ticks=20\nfinalize_config crc=0\n

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

    pru ticks 1 stepper 231 3 stepper 847"},{"location":"Benchmarks.html#stm32f042-step-rate-benchmark","title":"STM32F042 step rate benchmark","text":"

    The following configuration sequence is used on the STM32F042:

    allocate_oids count=3\nconfig_stepper oid=0 step_pin=PA1 dir_pin=PA2 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=1 step_pin=PA3 dir_pin=PA2 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=2 step_pin=PB8 dir_pin=PA2 invert_step=-1 step_pulse_ticks=0\nfinalize_config crc=0\n

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

    stm32f042 ticks 1 stepper 59 3 stepper 249"},{"location":"Benchmarks.html#stm32f103-step-rate-benchmark","title":"STM32F103 step rate benchmark","text":"

    The following configuration sequence is used on the STM32F103:

    allocate_oids count=3\nconfig_stepper oid=0 step_pin=PC13 dir_pin=PB5 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=1 step_pin=PB3 dir_pin=PB6 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=2 step_pin=PA4 dir_pin=PB7 invert_step=-1 step_pulse_ticks=0\nfinalize_config crc=0\n

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

    stm32f103 ticks 1 stepper 61 3 stepper 264"},{"location":"Benchmarks.html#stm32f4-step-rate-benchmark","title":"STM32F4 step rate benchmark","text":"

    The following configuration sequence is used on the STM32F4:

    allocate_oids count=3\nconfig_stepper oid=0 step_pin=PA5 dir_pin=PB5 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=1 step_pin=PB2 dir_pin=PB6 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=2 step_pin=PB3 dir_pin=PB7 invert_step=-1 step_pulse_ticks=0\nfinalize_config crc=0\n

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

    stm32f446 ticks 1 stepper 46 3 stepper 205 stm32f407 ticks 1 stepper 46 3 stepper 205"},{"location":"Benchmarks.html#stm32h7-step-rate-benchmark","title":"STM32H7 step rate benchmark","text":"

    The following configuration sequence is used on a STM32H743VIT6:

    allocate_oids count=3\nconfig_stepper oid=0 step_pin=PD4 dir_pin=PD3 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=1 step_pin=PA15 dir_pin=PA8 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=2 step_pin=PE2 dir_pin=PE3 invert_step=-1 step_pulse_ticks=0\nfinalize_config crc=0\n

    The test was last run on commit 00191b5c with gcc version arm-none-eabi-gcc (15:8-2019-q3-1+b1) 8.3.1 20190703 (release) [gcc-8-branch revision 273027].

    stm32h7 ticks 1 stepper 44 3 stepper 198"},{"location":"Benchmarks.html#stm32g0b1-step-rate-benchmark","title":"STM32G0B1 step rate benchmark","text":"

    The following configuration sequence is used on the STM32G0B1:

    allocate_oids count=3\nconfig_stepper oid=0 step_pin=PB13 dir_pin=PB12 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=1 step_pin=PB10 dir_pin=PB2 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=2 step_pin=PB0 dir_pin=PC5 invert_step=-1 step_pulse_ticks=0\nfinalize_config crc=0\n

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

    stm32g0b1 ticks 1 stepper 58 3 stepper 243"},{"location":"Benchmarks.html#lpc176x-step-rate-benchmark","title":"LPC176x step rate benchmark","text":"

    The following configuration sequence is used on the LPC176x:

    allocate_oids count=3\nconfig_stepper oid=0 step_pin=P1.20 dir_pin=P1.18 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=1 step_pin=P1.21 dir_pin=P1.18 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=2 step_pin=P1.23 dir_pin=P1.18 invert_step=-1 step_pulse_ticks=0\nfinalize_config crc=0\n

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

    lpc1768 ticks 1 stepper 52 3 stepper 222 lpc1769 ticks 1 stepper 51 3 stepper 222"},{"location":"Benchmarks.html#samd21-step-rate-benchmark","title":"SAMD21 step rate benchmark","text":"

    The following configuration sequence is used on the SAMD21:

    allocate_oids count=3\nconfig_stepper oid=0 step_pin=PA27 dir_pin=PA20 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=1 step_pin=PB3 dir_pin=PA21 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=2 step_pin=PA17 dir_pin=PA21 invert_step=-1 step_pulse_ticks=0\nfinalize_config crc=0\n

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

    samd21 ticks 1 stepper 70 3 stepper 306"},{"location":"Benchmarks.html#samd51-step-rate-benchmark","title":"SAMD51 step rate benchmark","text":"

    The following configuration sequence is used on the SAMD51:

    allocate_oids count=3\nconfig_stepper oid=0 step_pin=PA22 dir_pin=PA20 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=1 step_pin=PA22 dir_pin=PA21 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=2 step_pin=PA22 dir_pin=PA19 invert_step=-1 step_pulse_ticks=0\nfinalize_config crc=0\n

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

    samd51 ticks 1 stepper 39 3 stepper 191 1 stepper (200Mhz) 39 3 stepper (200Mhz) 181"},{"location":"Benchmarks.html#same70-step-rate-benchmark","title":"SAME70 step rate benchmark","text":"

    The following configuration sequence is used on the SAME70:

    allocate_oids count=3\nconfig_stepper oid=0 step_pin=PC18 dir_pin=PB5 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=1 step_pin=PC16 dir_pin=PD10 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=2 step_pin=PC28 dir_pin=PA4 invert_step=-1 step_pulse_ticks=0\nfinalize_config crc=0\n

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

    same70 ticks 1 stepper 45 3 stepper 190"},{"location":"Benchmarks.html#ar100-step-rate-benchmark","title":"AR100 step rate benchmark","text":"

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

    allocate_oids count=3\nconfig_stepper oid=0 step_pin=PL10 dir_pin=PE14 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=1 step_pin=PL11 dir_pin=PE15 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=2 step_pin=PL12 dir_pin=PE16 invert_step=-1 step_pulse_ticks=0\nfinalize_config crc=0\n

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

    AR100 R_PIO ticks 1 stepper 85 3 stepper 359"},{"location":"Benchmarks.html#rpxxxx-step-rate-benchmark","title":"RPxxxx step rate benchmark","text":"

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

    allocate_oids count=3\nconfig_stepper oid=0 step_pin=gpio25 dir_pin=gpio3 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=1 step_pin=gpio26 dir_pin=gpio4 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=2 step_pin=gpio27 dir_pin=gpio5 invert_step=-1 step_pulse_ticks=0\nfinalize_config crc=0\n

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

    rp2040 (*) ticks 1 stepper 5 3 stepper 22 rp2350 ticks 1 stepper 36 3 stepper 169

    (*) Note that the reported rp2040 ticks are relative to a 12Mhz scheduling timer and do not correspond to its 125Mhz internal ARM processing rate. It is expected that 5 scheduling ticks corresponds to ~47 ARM core cycles and 22 scheduling ticks corresponds to ~224 ARM core cycles.

    "},{"location":"Benchmarks.html#linux-mcu-step-rate-benchmark","title":"Linux MCU step rate benchmark","text":"

    The following configuration sequence is used on a Raspberry Pi:

    allocate_oids count=3\nconfig_stepper oid=0 step_pin=gpio2 dir_pin=gpio3 invert_step=0 step_pulse_ticks=5\nconfig_stepper oid=1 step_pin=gpio4 dir_pin=gpio5 invert_step=0 step_pulse_ticks=5\nconfig_stepper oid=2 step_pin=gpio6 dir_pin=gpio17 invert_step=0 step_pulse_ticks=5\nfinalize_config crc=0\n

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

    Linux (RPi3) ticks 1 stepper 160 3 stepper 380"},{"location":"Benchmarks.html#command-dispatch-benchmark","title":"Command dispatch benchmark","text":"

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

    DELAY {clock + 2*freq} get_uptime\nFLOOD 100000 0.0 debug_nop\nget_uptime\n

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

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

    MCU Rate Build Build compiler stm32f042 (CAN) 18K c105adc8 arm-none-eabi-gcc (GNU Tools 7-2018-q3-update) 7.3.1 atmega2560 (serial) 23K b161a69e avr-gcc (GCC) 4.8.1 sam3x8e (serial) 23K b161a69e arm-none-eabi-gcc (Fedora 7.1.0-5.fc27) 7.1.0 at90usb1286 (USB) 75K 01d2183f avr-gcc (GCC) 5.4.0 ar100 (serial) 138K 08d037c6 or1k-linux-musl-gcc 9.3.0 samd21 (USB) 223K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 pru (shared memory) 260K c5968a08 pru-gcc (GCC) 8.0.0 20170530 (experimental) stm32f103 (USB) 355K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 sam3x8e (USB) 418K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 lpc1768 (USB) 534K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 lpc1769 (USB) 628K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 sam4s8c (USB) 650K 8d4a5c16 arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 samd51 (USB) 864K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 stm32f446 (USB) 870K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 rp2040 (USB) 885K f6718291 arm-none-eabi-gcc (Fedora 14.1.0-1.fc40) 14.1.0 rp2350 (USB) 885K f6718291 arm-none-eabi-gcc (Fedora 14.1.0-1.fc40) 14.1.0"},{"location":"Benchmarks.html#host-benchmarks","title":"Host Benchmarks","text":"

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

    time ~/klippy-env/bin/python ./klippy/klippy.py config/example-cartesian.cfg -i something_complex.gcode -o /dev/null -d out/klipper.dict\n
    "},{"location":"Bleeding_Edge.html","title":"Bleeding Edge Features Documentation","text":"

    The following are experimental features found in the bleeding edge branch of Kalico and should be used at your own caution. The support for these features is limited and your experience may vary! If you do use the features and find them useful, discover bugs, or have improvements please use the Kalico Discord server to discuss your findings.

    Refer to the Bleeding Edge Configuration Reference for details on printer configurations for these features.

    "},{"location":"Bleeding_Edge.html#high-precision-stepping-and-new-stepcompress-protocol","title":"High precision stepping and new stepcompress protocol","text":"

    Reference Discussion of this feature: https://klipper.discourse.group/t/improved-stepcompress-implementation/3203

    "},{"location":"Bleeding_Edge.html#overview","title":"Overview","text":"

    The new stepcompress protocol and precision stepping feature is a proposed improvement in the control and accuracy of stepper motor movements. This feature enhances the step compression algorithm, crucial for transmitting stepper commands accurately.

    "},{"location":"Bleeding_Edge.html#existing-step-compression-mechanism","title":"Existing Step Compression Mechanism","text":""},{"location":"Bleeding_Edge.html#limitations-of-current-method","title":"Limitations of Current Method","text":""},{"location":"Bleeding_Edge.html#improved-step-compression-schema","title":"Improved Step Compression Schema","text":""},{"location":"Bleeding_Edge.html#advantages-of-new-method","title":"Advantages of New Method","text":""},{"location":"Bleeding_Edge.html#computational-considerations","title":"Computational Considerations","text":""},{"location":"Bleeding_Edge.html#real-world-testing-and-results","title":"Real-World Testing and Results","text":""},{"location":"Bleeding_Edge.html#smooth-input-shapers","title":"Smooth Input Shapers","text":"

    Reference Discussion of this feature: https://klipper.discourse.group/t/scurve-pa-branch/7621/3

    "},{"location":"Bleeding_Edge.html#overview_1","title":"Overview","text":"

    The Smooth Input Shaper feature employs polynomial smooth functions designed to cancel vibrations at certain frequencies, similar to regular input shapers. The feature aims to provide shapers that have somewhat better overall characteristics.

    "},{"location":"Bleeding_Edge.html#key-features","title":"Key Features","text":" "},{"location":"Bleeding_Edge.html#smooth-shapers-avaliable","title":"Smooth shapers avaliable","text":""},{"location":"Bleeding_Edge.html#custom-smooth-shapers","title":"Custom smooth shapers","text":""},{"location":"Bleeding_Edge.html#hardware-requirements","title":"Hardware Requirements","text":" "},{"location":"Bleeding_Edge.html#configuration-and-usage","title":"Configuration and Usage","text":" "},{"location":"Bleeding_Edge.html#extruder-pa-synchronization-with-input-shaping","title":"Extruder PA Synchronization with Input Shaping","text":"

    Reference Discussion of this feature: https://klipper.discourse.group/t/extruder-pa-synchronization-with-input-shaping/3843

    "},{"location":"Bleeding_Edge.html#overview_2","title":"Overview","text":"

    The Extruder PA Synchronization with Input Shaping feature synchronizes filament extrusion (Pressure Advance - PA) with the toolhead's motion. This synchronization aims to reduce artifacts by compensating for changes in toolhead motion, especially in scenarios where input shaping is employed to minimize vibration and ringing.

    "},{"location":"Bleeding_Edge.html#background","title":"Background","text":"

    Input shaping is a technique used to alter toolhead motion to reduce vibrations. While Klipper's existing pressure advance algorithm helps in synchronizing filament extrusion with toolhead motion, it is not fully aligned with the input shaping alterations. This misalignment can be particularly noticeable in scenarios where X and Y axes have different resonance frequencies, or the PA smooth time significantly deviates from the input shaper duration.

    "},{"location":"Bleeding_Edge.html#implementation","title":"Implementation","text":"

    The feature involves:

    1. Calculating toolhead motion across X, Y, and Z axes.
    2. Applying input shaping to the X and Y axes.
    3. Using linearization to project this motion onto the E (extruder) axis.

    If the input shaper is consistent for both X and Y axes, the synchronization is precise for XY motion. In other cases, the feature provides a linear approximation over X/Y deviations, which is an improvement over the previous state.

    "},{"location":"Bleeding_Edge.html#observations-and-improvements","title":"Observations and Improvements","text":""},{"location":"Bleeding_Edge.html#hardware-requirements_1","title":"Hardware Requirements","text":""},{"location":"Bleeding_Edge.html#testing-and-results","title":"Testing and Results","text":"

    The feature has been tested over several months, showing modest improvements in the quality of real prints. It is particularly effective for direct drive extruders with short filament paths. The impact on bowden extruders is expected to be neutral.

    "},{"location":"Bleeding_Edge.html#usage-recommendations","title":"Usage Recommendations","text":""},{"location":"Bleeding_Edge.html#ringing-tower-test-print","title":"Ringing tower test print","text":"

    Reference Discussion of this feature: https://klipper.discourse.group/t/alternative-ringing-tower-print-for-input-shaping-calibration/4517

    "},{"location":"Bleeding_Edge.html#overview_3","title":"Overview","text":"

    The new test methodology for input shaper calibration addresses a critical limitation of the existing ringing_tower test. This improvement is centered around isolating the vibrations on each axis during the calibration process, thereby providing more accurate and reliable results.

    "},{"location":"Bleeding_Edge.html#limitation-of-current-ringing-tower-test","title":"Limitation of Current Ringing Tower Test","text":""},{"location":"Bleeding_Edge.html#new-test-methodology-concept","title":"New Test Methodology Concept","text":""},{"location":"Bleeding_Edge.html#advantages","title":"Advantages","text":""},{"location":"Bleeding_Edge.html#considerations","title":"Considerations","text":""},{"location":"Bleeding_Edge.html#sample-run-command","title":"Sample run command:","text":"

    Note, it is not reccomended to run the command directly without the helper macros configured.

    RUN_RINGING_TEST NOZZLE=0.4 TARGET_TEMP=210 BED_TEMP=55.

    "},{"location":"Bleeding_Edge.html#sample-helper-macros","title":"Sample helper macros","text":"

    This sample Gcode can be included in printer.cfg or s seperate *.cfg file and #included in printer.cfg. Specific start/end printing Gcode for the printer should be added to ensure it aligned with the standard printing process such as the appropriate heating, homing and bed meshing sequences and additional functions such as enabling fan, additional purge lines, pressure advance setup, or adjusting the flow rate.

    [ringing_test]\n\n[delayed_gcode start_ringing_test]\n\ngcode:\n    {% set vars = printer[\"gcode_macro RUN_RINGING_TEST\"] %}\n    # Add your start GCode here, for example:\n    # G28\n    # M190 S{vars.bed_temp}\n    # M109 S{vars.hotend_temp}\n    # M106 S255\n    {% set flow_percent = vars.flow_rate|float * 100.0 %}\n    {% if flow_percent > 0 %}\n    M221 S{flow_percent}\n    {% endif %}\n    {% set layer_height = vars.nozzle * 0.5 %}\n    {% set first_layer_height = layer_height * 1.25 %}\n    PRINT_RINGING_TOWER {vars.rawparams} LAYER_HEIGHT={layer_height} FIRST_LAYER_HEIGHT={first_layer_height} FINAL_GCODE_ID=end_ringing_test\n\n[delayed_gcode end_ringing_test]\ngcode:\n    # Add your end GCode here, for example:\n    # M104 S0 ; turn off temperature\n    # M140 S0 ; turn off heatbed\n    # M107 ; turn off fan\n    # G91 ; relative positioning\n    # G1 Z5 ; raise Z\n    # G90 ; absolute positioning\n    # G1 X0 Y200 ; present print\n    # M84 ; disable steppers\n    RESTORE_GCODE_STATE NAME=RINGING_TEST_STATE\n\n[gcode_macro RUN_RINGING_TEST]\nvariable_bed_temp: -1\nvariable_hotend_temp: -1\nvariable_nozzle: -1\nvariable_flow_rate: -1\nvariable_rawparams: ''\ngcode:\n    # Fail early if the required parameters are not provided\n    {% if params.NOZZLE is not defined %}\n    {action_raise_error('NOZZLE= parameter must be provided')}\n    {% endif %}\n    {% if params.TARGET_TEMP is not defined %}\n    {action_raise_error('TARGET_TEMP= parameter must be provided')}\n    {% endif %}\n    SET_GCODE_VARIABLE MACRO=RUN_RINGING_TEST VARIABLE=bed_temp VALUE={params.BED_TEMP|default(60)}\n    SET_GCODE_VARIABLE MACRO=RUN_RINGING_TEST VARIABLE=hotend_temp VALUE={params.TARGET_TEMP}\n    SET_GCODE_VARIABLE MACRO=RUN_RINGING_TEST VARIABLE=nozzle VALUE={params.NOZZLE}\n    SET_GCODE_VARIABLE MACRO=RUN_RINGING_TEST VARIABLE=flow_rate VALUE={params.FLOW_RATE|default(-1)}\n    SET_GCODE_VARIABLE MACRO=RUN_RINGING_TEST VARIABLE=rawparams VALUE=\"'{rawparams}'\"\n    SAVE_GCODE_STATE NAME=RINGING_TEST_STATE\n    UPDATE_DELAYED_GCODE ID=start_ringing_test DURATION=0.01\n
    "},{"location":"Bleeding_Edge.html#pa-tower-test-print","title":"PA tower test print","text":"

    Reference Discussion of this feature: https://klipper.discourse.group/t/extruder-pa-synchronization-with-input-shaping/3843/27

    "},{"location":"Bleeding_Edge.html#overview_4","title":"Overview","text":"

    The features introduces a new module for printing a Pressure Advance (PA) calibration tower directly from the firmware. This module simplifies the process of calibrating the PA settings, enhancing the precision and ease of tuning for optimal print quality.

    "},{"location":"Bleeding_Edge.html#key-features_1","title":"Key Features","text":""},{"location":"Bleeding_Edge.html#configuration","title":"Configuration","text":""},{"location":"Bleeding_Edge.html#operation","title":"Operation","text":""},{"location":"Bleeding_Edge.html#advantages-over-other-methods","title":"Advantages Over Other Methods","text":""},{"location":"Bleeding_Edge.html#sample-run-command_1","title":"Sample run command:","text":"

    Note, it is not reccomended to run the command directly without the helper macros configured.

    RUN_PA_TEST NOZZLE=0.4 TARGET_TEMP=205 BED_TEMP=55

    "},{"location":"Bleeding_Edge.html#sample-helper-macros_1","title":"Sample helper macros","text":"

    This sample Gcode can be included in printer.cfg or s seperate *.cfg file and #included in printer.cfg. Specific start/end printing Gcode for the printer should be added to ensure it aligned with the standard printing process such as the appropriate heating, homing and bed meshing sequences and additional functions such as enabling fan, additional purge lines, pressure advance setup, or adjusting the flow rate.

    [delayed_gcode start_pa_test]\ngcode:\n    {% set vars = printer[\"gcode_macro RUN_PA_TEST\"] %}\n    # Add your start GCode here, for example:\n    # G28\n    # M190 S{vars.bed_temp}\n    # M109 S{vars.hotend_temp}\n    {% set flow_percent = vars.flow_rate|float * 100.0 %}\n    {% if flow_percent > 0 %}\n        M221 S{flow_percent}\n    {% endif %}\n    {% set height = printer.configfile.settings.pa_test.height %}  \n    {% set pavalue = vars.pa_value %}\n    ; If pa_value is 0 then we test the full pa range starting from 0\n    {% if  vars.pa_value == 0 %} \n        TUNING_TOWER COMMAND=SET_PRESSURE_ADVANCE PARAMETER=ADVANCE START=0 FACTOR=.005\n    {% else %}\n        ; make sure that delta and start can not be lower then 0\n        {% if vars.pa_value - vars.pa_range <= 0%} \n            {% set delta = vars.pa_range %}\n            {% set start = 0 %}\n        {% else %}\n            ; calculate the pa range that we want to test\n            {% set delta = (vars.pa_value + vars.pa_range)  - (vars.pa_value - vars.pa_range)  %} \n            ; calculate the pa start value\n            {% set start = vars.pa_value - vars.pa_range %} \n        {% endif %}\n        TUNING_TOWER COMMAND=SET_PRESSURE_ADVANCE PARAMETER=ADVANCE START={start} FACTOR={delta / height}\n    {% endif %}\n    ; PRINT_PA_TOWER must be the last command in the start_pa_test script:\n    ; it starts a print and then immediately returns without waiting for the print to finish\n    PRINT_PA_TOWER {vars.rawparams} FINAL_GCODE_ID=end_pa_test\n\n[delayed_gcode end_pa_test]\ngcode:\n    # Add your end GCode here, for example:\n    # M104 S0 ; turn off temperature\n    # M140 S0 ; turn off heatbed\n    # M107 ; turn off fan\n    # G91 ; relative positioning\n    # G1 Z5 ; raise Z\n    # G90 ; absolute positioning\n    # G1 X0 Y200 ; present print\n    # M84 ; disable steppers\n    RESTORE_GCODE_STATE NAME=PA_TEST_STATE\n\n[gcode_macro RUN_PA_TEST]\nvariable_bed_temp: -1\nvariable_hotend_temp: -1\nvariable_pa_value: 0             # Used for further tuning of pa value. If value is not 0 than the tested pa value will only be +/- (determined by the pa_range variable) around of the pa_value variable\nvariable_pa_range: 0.03          # Only use if pa_value is set to heigher than 0. Used to set the +/- area around pa_value that should be tested\nvariable_flow_rate: -1\nvariable_rawparams: ''\ngcode:\n    # Fail early if the required parameters are not provided\n    {% if params.NOZZLE is not defined %}\n    {action_raise_error('NOZZLE= parameter must be provided')}\n    {% endif %}\n    {% if params.TARGET_TEMP is not defined %}\n    {action_raise_error('TARGET_TEMP= parameter must be provided')}\n    {% endif %}\n    SET_GCODE_VARIABLE MACRO=RUN_PA_TEST VARIABLE=bed_temp VALUE={params.BED_TEMP|default(60)}\n    SET_GCODE_VARIABLE MACRO=RUN_PA_TEST VARIABLE=hotend_temp VALUE={params.TARGET_TEMP}\n    SET_GCODE_VARIABLE MACRO=RUN_PA_TEST VARIABLE=pa_value VALUE={params.PA_VALUE|default(0)}\n    SET_GCODE_VARIABLE MACRO=RUN_PA_TEST VARIABLE=pa_range VALUE={params.PA_RANGE|default(0.01)}\n    SET_GCODE_VARIABLE MACRO=RUN_PA_TEST VARIABLE=flow_rate VALUE={params.FLOW_RATE|default(-1)}\n    SET_GCODE_VARIABLE MACRO=RUN_PA_TEST VARIABLE=rawparams VALUE=\"'{rawparams}'\"\n    SAVE_GCODE_STATE NAME=PA_TEST_STATE\n    UPDATE_DELAYED_GCODE ID=start_pa_test DURATION=0.01\n
    "},{"location":"Bootloader_Entry.html","title":"Bootloader Entry","text":"

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

    "},{"location":"Bootloader_Entry.html#requesting-the-bootloader","title":"Requesting the bootloader","text":""},{"location":"Bootloader_Entry.html#virtual-serial","title":"Virtual Serial","text":"

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

    "},{"location":"Bootloader_Entry.html#python-with-flash_usb","title":"Python (with flash_usb)","text":"

    To enter the bootloader using python (using flash_usb):

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

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

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

    "},{"location":"Bootloader_Entry.html#picocom","title":"Picocom","text":"
    picocom -b 1200 <DEVICE>\n<Ctrl-A><Ctrl-P>\n

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

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

    "},{"location":"Bootloader_Entry.html#physical-serial","title":"Physical serial","text":"

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

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

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

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

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

    "},{"location":"Bootloader_Entry.html#shell","title":"Shell","text":"
    stty <BAUD> < /dev/<DEVICE>\necho $'~ \\x1c Request Serial Bootloader!! ~' >> /dev/<DEVICE>\n

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

    <BAUD> is the baud rate of the serial port, such as 115200.

    "},{"location":"Bootloader_Entry.html#canbus","title":"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.

    "},{"location":"Bootloader_Entry.html#katapults-flashtoolpy","title":"Katapult's flashtool.py","text":"
    python3 ./katapult/scripts/flashtool.py -i <CAN_IFACE> -u <UUID> -r\n

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

    <UUID> is the UUID of your CAN device.

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

    "},{"location":"Bootloader_Entry.html#entering-the-bootloader","title":"Entering the bootloader","text":"

    When Kalico receives one of the above bootloader requests:

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

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

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

    For details about the specific bootloaders on various platforms see Bootloaders

    "},{"location":"Bootloader_Entry.html#notes","title":"Notes","text":""},{"location":"Bootloader_Entry.html#stm32-dfu-warning","title":"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.

    "},{"location":"Bootloaders.html","title":"Bootloaders","text":"

    This document provides information on common bootloaders found on micro-controllers that Kalico 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, Kalico) 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 Kalico developers have accumulated.

    "},{"location":"Bootloaders.html#avr-micro-controllers","title":"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).

    "},{"location":"Bootloaders.html#atmega2560","title":"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'\n\navrdude -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\navrdude -cavrispv2 -patmega2560 -P/dev/ttyACM0 -b115200 -U flash:w:stk500boot_v2_mega2560.hex\navrdude -cavrispv2 -patmega2560 -P/dev/ttyACM0 -b115200 -U lock:w:0x0F:m\n

    To flash an application use something like:

    avrdude -cwiring -patmega2560 -P/dev/ttyACM0 -b115200 -D -Uflash:w:out/klipper.elf.hex:i\n
    "},{"location":"Bootloaders.html#atmega1280","title":"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'\n\navrdude -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\navrdude -cavrispv2 -patmega1280 -P/dev/ttyACM0 -b115200 -U flash:w:ATmegaBOOT_168_atmega1280.hex\navrdude -cavrispv2 -patmega1280 -P/dev/ttyACM0 -b115200 -U lock:w:0x0F:m\n

    To flash an application use something like:

    avrdude -carduino -patmega1280 -P/dev/ttyACM0 -b57600 -D -Uflash:w:out/klipper.elf.hex:i\n
    "},{"location":"Bootloaders.html#atmega1284p","title":"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'\n\navrdude -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\navrdude -cavrispv2 -patmega1284p -P/dev/ttyACM0 -b115200 -U flash:w:optiboot_atmega1284p.hex\navrdude -cavrispv2 -patmega1284p -P/dev/ttyACM0 -b115200 -U lock:w:0x0F:m\n

    To flash an application use something like:

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

    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\n
    "},{"location":"Bootloaders.html#at90usb1286","title":"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\n
    "},{"location":"Bootloaders.html#atmega168","title":"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'\n\navrdude -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\navrdude -cavrispv2 -patmega168 -P/dev/ttyACM0 -b115200 -U flash:w:optiboot_atmega168.hex\navrdude -cavrispv2 -patmega168 -P/dev/ttyACM0 -b115200 -U lock:w:0x0F:m\n

    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\n
    "},{"location":"Bootloaders.html#sam3-micro-controllers-arduino-due","title":"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\nbossac -U -p /dev/ttyACM0 -R\n
    "},{"location":"Bootloaders.html#sam4-micro-controllers-duet-wifi","title":"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\n
    "},{"location":"Bootloaders.html#samdc21-micro-controllers-duet3d-toolboard-1lc","title":"SAMDC21 micro-controllers (Duet3D Toolboard 1LC)","text":"

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

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

    SWCLK=25\nSWDIO=24\nSRST=18\n\necho \"Exporting SWCLK and SRST pins.\"\necho $SWCLK > /sys/class/gpio/export\necho $SRST > /sys/class/gpio/export\necho \"out\" > /sys/class/gpio/gpio$SWCLK/direction\necho \"out\" > /sys/class/gpio/gpio$SRST/direction\n\necho \"Setting SWCLK low and pulsing SRST.\"\necho \"0\" > /sys/class/gpio/gpio$SWCLK/value\necho \"0\" > /sys/class/gpio/gpio$SRST/value\necho \"1\" > /sys/class/gpio/gpio$SRST/value\n\necho \"Unexporting SWCLK and SRST pins.\"\necho $SWCLK > /sys/class/gpio/unexport\necho $SRST > /sys/class/gpio/unexport\n

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

    source [find target/at91samdXX.cfg]\n

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

    at91samd chip-erase\nat91samd bootloader 0\nprogram out/klipper.elf verify\n
    "},{"location":"Bootloaders.html#samd21-micro-controllers-arduino-zero","title":"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]\n

    Obtain a bootloader - for example:

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

    Flash with OpenOCD commands similar to:

    at91samd bootloader 0\nprogram samd21_sam_ba.bin verify\n

    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\n

    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\n
    "},{"location":"Bootloaders.html#samd51-micro-controllers-adafruit-metro-m4-and-similar","title":"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]\n

    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'\n

    Flash with OpenOCD commands similar to:

    at91samd bootloader 0\nprogram bootloader-itsybitsy_m4-v3.7.0.bin verify\nat91samd bootloader 16384\n

    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\n
    "},{"location":"Bootloaders.html#stm32f103-micro-controllers-blue-pill-devices","title":"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\n

    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.

    "},{"location":"Bootloaders.html#stm32f103-with-stm32duino-bootloader","title":"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'\n\nstm32flash -w generic_boot20_pc13.bin -v -g 0 /dev/ttyAMA0\n

    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\n

    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.

    "},{"location":"Bootloaders.html#stm32f103-with-hid-bootloader","title":"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]\n

    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\n

    finally, you can flash with commands similar to:

    stm32f1x mass_erase 0\nprogram hid_btt_skr_mini_e3.bin verify 0x08000000\n

    NOTES:

    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\ncd ~/klipper/lib/hidflash\nmake\n

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

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

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

    make flash FLASH_DEVICE=1209:BEBA\n

    OR if Kalico has been previously flashed:

    make flash FLASH_DEVICE=/dev/ttyACM0\n

    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.

    "},{"location":"Bootloaders.html#stm32f103stm32f072-with-msc-bootloader","title":"STM32F103/STM32F072 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\n

    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.

    "},{"location":"Bootloaders.html#stm32f103stm32f0x2-with-canboot-bootloader","title":"STM32F103/STM32F0x2 with CanBoot bootloader","text":"

    The CanBoot bootloader provides an option for uploading Kalico firmware over the CANBUS. The bootloader itself is derived from Kalico'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 Kalico 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\n

    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\n

    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 Kalico for use with CanBoot, select the 8 KiB Bootloader option.

    "},{"location":"Bootloaders.html#stm32f4-micro-controllers-skr-pro-11","title":"STM32F4 micro-controllers (SKR Pro 1.1)","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\n\nstm32flash -w hid_bootloader_SKR_PRO.bin -v -g 0 /dev/ttyAMA0\n

    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.

    "},{"location":"Bootloaders.html#lpc176x-micro-controllers-smoothieboards","title":"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.

    "},{"location":"Bootloaders.html#running-openocd-on-the-raspberry-pi","title":"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\nsudo apt-get install autoconf libtool telnet\nmkdir ~/openocd\ncd ~/openocd/\ngit clone http://openocd.zylin.com/openocd\ncd openocd\n./bootstrap\n./configure --enable-sysfsgpio --enable-bcm2835gpio --prefix=/home/pi/openocd/install\nmake\nmake install\n
    "},{"location":"Bootloaders.html#configure-openocd","title":"Configure OpenOCD","text":"

    Create an OpenOCD config file:

    nano ~/openocd/openocd.cfg\n

    Use a config similar to the following:

    # Uses RPi pins: GPIO25 for SWDCLK, GPIO24 for SWDIO, GPIO18 for nRST\nsource [find interface/raspberrypi2-native.cfg]\nbcm2835gpio_swd_nums 25 24\nbcm2835gpio_srst_num 18\ntransport select swd\n\n# Use hardware reset wire for chip resets\nreset_config srst_only\nadapter_nsrst_delay 100\nadapter_nsrst_assert_width 100\n\n# Specify the chip type\nsource [find target/atsame5x.cfg]\n\n# Set the adapter speed\nadapter_khz 40\n\n# Connect to chip\ninit\ntargets\nreset halt\n
    "},{"location":"Bootloaders.html#wire-the-raspberry-pi-to-the-target-chip","title":"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.

    "},{"location":"Bootloaders.html#run-openocd","title":"Run OpenOCD","text":"

    Run OpenOCD:

    cd ~/openocd/\nsudo ~/openocd/install/bin/openocd -f ~/openocd/openocd.cfg\n

    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\n

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

    "},{"location":"Bootloaders.html#openocd-and-gdb","title":"OpenOCD and gdb","text":"

    It is possible to use OpenOCD with gdb to debug Kalico. 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\ngdb_port 44444\n

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

    cd /path/to/klipper/\ngdb out/klipper.elf\n

    Within gdb run:

    target remote octopi:44444\n

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

    "},{"location":"CANBUS.html","title":"CANBUS","text":"

    This document describes Kalico's CAN bus support.

    "},{"location":"CANBUS.html#device-hardware","title":"Device Hardware","text":"

    Kalico 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.

    "},{"location":"CANBUS.html#host-hardware","title":"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 Kalico 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\niface can0 can static\n    bitrate 1000000\n    up ip link set $IFACE txqueuelen 128\n
    "},{"location":"CANBUS.html#terminating-resistors","title":"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.

    "},{"location":"CANBUS.html#finding-the-canbus_uuid-for-new-micro-controllers","title":"\u26a0\ufe0f 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\n

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

    Found canbus_uuid=11aa22bb33cc, Application: Klipper, Unassigned\nFound canbus_uuid=11aa22bb33cc, Application: Kalico, Assigned: 77\n

    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 Kalico (or a similar tool) configures the device then it will no longer appear in the list.

    \u26a0\ufe0f Note that only devices flashed with a Kalico firmware will respond while assigned a device node ID. Devices using a Klipper firmware will no longer appear in the list once configured

    "},{"location":"CANBUS.html#configuring-kalico","title":"Configuring Kalico","text":"

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

    [mcu my_can_mcu]\ncanbus_uuid: 11aa22bb33cc\n
    "},{"location":"CANBUS.html#usb-to-can-bus-bridge-mode","title":"USB to CAN bus bridge mode","text":"

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

    When Kalico uses this mode the micro-controller appears as a \"USB CAN bus adapter\" under Linux. The \"Kalico 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 Kalico nodes.

    Some important notes when using this mode:

    allow-hotplug can0\niface can0 can static\n    bitrate 1000000\n    up ip link set $IFACE txqueuelen 128\n
    "},{"location":"CANBUS.html#tips-for-troubleshooting","title":"Tips for troubleshooting","text":"

    See the CAN bus troubleshooting document.

    "},{"location":"CANBUS_Troubleshooting.html","title":"CANBUS Troubleshooting","text":"

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

    "},{"location":"CANBUS_Troubleshooting.html#verify-can-bus-wiring","title":"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.

    "},{"location":"CANBUS_Troubleshooting.html#check-for-incrementing-bytes_invalid-counter","title":"Check for incrementing bytes_invalid counter","text":"

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

    Incrementing bytes_invalid on a CAN bus connection is a symptom of reordered messages on the CAN bus. There are two known causes of reordered messages:

    1. Old versions of the popular candlight_firmware for USB CAN adapters had a bug that could cause reordered messages. If using a USB CAN adapter running this firmware then make sure to update to the latest firmware if incrementing bytes_invalid is observed.
    2. Some Linux kernel builds for embedded devices have been known to reorder CAN bus messages. It may be necessary to use an alternative Linux kernel or to use alternative hardware that supports mainstream Linux kernels that do not exhibit this problem.

    Reordered messages is a severe problem that must be fixed. It will result in unstable behavior and can lead to confusing errors at any part of a print.

    "},{"location":"CANBUS_Troubleshooting.html#use-an-appropriate-txqueuelen-setting","title":"Use an appropriate txqueuelen setting","text":"

    The Kalico 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 Kalico 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 Kalico log:

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

    Kalico 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 Kalico 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, Kalico'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 Kalico may utilize ~25 queue slots per MCU - typically only utilizing more slots during retransmits. (Specifically, the Kalico host may transmit up to 192 bytes to each Kalico MCU before receiving an acknowledgment from that MCU.) If a single CAN bus has 5 or more Kalico 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.

    "},{"location":"CANBUS_Troubleshooting.html#obtaining-candump-logs","title":"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\n

    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\n

    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 Kalico. Understanding the content of these messages will likely require low-level knowledge of Kalico's CANBUS protocol and Kalico's MCU commands.

    "},{"location":"CANBUS_Troubleshooting.html#parsing-kalico-messages-in-a-candump-log","title":"Parsing Kalico messages in a candump log","text":"

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

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

    This tool produces output similar to the parsedump tool. See the documentation for that tool for information on generating the Kalico 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 Kalico 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.

    "},{"location":"CANBUS_Troubleshooting.html#using-a-logic-analyzer-on-the-canbus-wiring","title":"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.

    "},{"location":"CANBUS_protocol.html","title":"CANBUS protocol","text":"

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

    "},{"location":"CANBUS_protocol.html#micro-controller-id-assignment","title":"Micro-controller id assignment","text":"

    Kalico 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 Kalico command and response traffic. Kalico command messages going from host to micro-controller use the CAN bus id of canbus_nodeid * 2 + 256, while Kalico 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.

    "},{"location":"CANBUS_protocol.html#admin-messages","title":"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\".

    "},{"location":"CANBUS_protocol.html#cmd_query_unassigned-message","title":"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>

    "},{"location":"CANBUS_protocol.html#cmd_set_klipper_nodeid-message","title":"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>

    "},{"location":"CANBUS_protocol.html#resp_need_nodeid-message","title":"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>

    "},{"location":"CANBUS_protocol.html#data-packets","title":"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 Kalico 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).

    "},{"location":"CONTRIBUTING.html","title":"Contributing to Kalico","text":"

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

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

    "},{"location":"CONTRIBUTING.html#overview-of-contribution-process","title":"Overview of Contribution Process","text":"

    Contributions to Kalico generally follow a high-level process:

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

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

    "},{"location":"CONTRIBUTING.html#what-to-expect-in-a-review","title":"What to expect in a review","text":"

    Contributions to Kalico 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 Kalico documentation.

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

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

    Common things a reviewer will look for:

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

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

      The main KalicoCrew/kalico GitHub repository might accept experimental work, but we encourage submitters should perform experimentation, debugging, and testing in their own repositories. The Kalico Discord server is a good place to raise awareness of new work and to find users interested in providing real-world feedback.

      Submissions must pass all regression test cases.

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

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

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

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

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

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

      Submissions to the main Kalico 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 Kalico's most notable features took months of discussion, rework, testing, and documentation prior to being merged into the main branch.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

      Commit messages should follow the preferred format.

      Commits must not have a merge conflict. New additions to the Kalico main 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 Kalico main branch. 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.

    Kalico implements a soft-strict \"coding style guide\" on the Python code. Modifications to existing code should follow the high-level code flow, code indentation style, and format of that existing code.

    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.

    "},{"location":"CONTRIBUTING.html#helping-with-reviews","title":"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\".

    "},{"location":"CONTRIBUTING.html#reviewers","title":"Reviewers","text":"

    The Kalico \"reviewers\" are:

    Name GitHub Id Areas of interest

    TODO

    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 Kalico \"maintainers\" are:

    Name GitHub name Bea Nance @bwnance Rogerio Goncalves @rogerlz Lasse Dalegaard @dalegaard"},{"location":"CONTRIBUTING.html#format-of-commit-messages","title":"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\n\nMore detailed explanatory text, if necessary.  Wrap it to about 75\ncharacters or so.  In some contexts, the first line is treated as the\nsubject of an email and the rest of the text as the body.  The blank\nline separating the summary from the body is critical (unless you omit\nthe body entirely); tools like rebase can get confused if you run the\ntwo together.\n\nFurther paragraphs come after blank lines..\n\nSigned-off-by: My Name <myemail@example.org>\n

    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.

    "},{"location":"Code_Overview.html","title":"Code overview","text":"

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

    "},{"location":"Code_Overview.html#directory-layout","title":"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.

    "},{"location":"Code_Overview.html#micro-controller-code-flow","title":"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.

    "},{"location":"Code_Overview.html#klippy-code-overview","title":"Klippy code overview","text":"

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

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

    There are four threads in the Klippy host code. The main thread handles incoming gcode commands. A second thread (which resides entirely in the klippy/chelper/serialqueue.c C code) handles low-level IO with the serial port. The third thread is used to process response messages from the micro-controller in the Python code (see klippy/serialhdl.py). The fourth thread writes debug messages to the log (see klippy/queuelogger.py) so that the other threads never block on log writes.

    "},{"location":"Code_Overview.html#code-flow-of-a-move-command","title":"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.

    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.

    "},{"location":"Code_Overview.html#adding-a-host-module","title":"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 Kalico.

    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:

    "},{"location":"Code_Overview.html#adding-new-kinematics","title":"Adding new kinematics","text":"

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

    Useful steps:

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

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

    Useful steps:

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

    Additional coding tips:

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

    Internally, Kalico 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 Kalico 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 Kalico has several tools to facilitate that. This can be seen by running the GET_POSITION command. For example:

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

    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.

    "},{"location":"Code_Overview.html#time","title":"Time","text":"

    Fundamental to the operation of Kalico is the handling of clocks, times, and timestamps. Kalico 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 Kalico is critical to correct operation.

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

    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:

    "},{"location":"Command_Templates.html","title":"Commands templates","text":"

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

    "},{"location":"Command_Templates.html#g-code-macro-naming","title":"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).

    "},{"location":"Command_Templates.html#formatting-of-g-code-in-the-config","title":"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]\ngcode:\n  SET_PIN PIN=my_led VALUE=1\n  G4 P2000\n  SET_PIN PIN=my_led VALUE=0\n

    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.

    "},{"location":"Command_Templates.html#add-a-description-to-your-macro","title":"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]\ndescription: Blink my_led one time\ngcode:\n  SET_PIN PIN=my_led VALUE=1\n  G4 P2000\n  SET_PIN PIN=my_led VALUE=0\n

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

    "},{"location":"Command_Templates.html#saverestore-state-for-g-code-moves","title":"Save/Restore 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]\ngcode:\n  SAVE_GCODE_STATE NAME=my_move_up_state\n  G91\n  G1 Z10 F300\n  RESTORE_GCODE_STATE NAME=my_move_up_state\n

    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.

    "},{"location":"Command_Templates.html#template-expansion","title":"Template expansion","text":"

    The gcode_macro gcode: config section is evaluated using either the Jinja2 template language or Python.

    "},{"location":"Command_Templates.html#jinja2","title":"Jinja2","text":"

    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 Jinja2 macro:

    [gcode_macro clean_nozzle]\ngcode:\n  {% set wipe_count = 8 %}\n  SAVE_GCODE_STATE NAME=clean_nozzle_state\n  G90\n  G0 Z15 F300\n  {% for wipe in range(wipe_count) %}\n    {% for coordinate in [(275, 4),(235, 4)] %}\n      G0 X{coordinate[0]} Y{coordinate[1] + 0.25 * wipe} Z9.7 F12000\n    {% endfor %}\n  {% endfor %}\n  RESTORE_GCODE_STATE NAME=clean_nozzle_state\n
    "},{"location":"Command_Templates.html#jinja2-macro-parameters","title":"Jinja2: 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]\ngcode:\n  M117 Now at { params.VALUE|float * 100 }%\n

    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]\ngcode:\n  {% set bed_temp = params.TEMPERATURE|default(40)|float %}\n  M140 S{bed_temp}\n
    "},{"location":"Command_Templates.html#jinja2-the-rawparams-variable","title":"Jinja2: 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.

    "},{"location":"Command_Templates.html#jinja2-the-printer-variable","title":"Jinja2 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]\ngcode:\n  M106 S{ printer.fan.speed * 0.9 * 255}\n

    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]\ngcode:\n    {% set sensor = printer[\"htu21d my_sensor\"] %}\n    M117 Temp:{sensor.temperature} Humidity:{sensor.humidity}\n
    "},{"location":"Command_Templates.html#python","title":"Python","text":"

    Templates can also be written in Python code. The template will automatically be interpreted as Python if lines are prefixed with !. Note: You can't mix Python and Jinja2.

    An example of a complex Python macro:

    [gcode_macro clean_nozzle]\ngcode:\n  !wipe_count = 8\n  !emit(\"G90\")\n  !emit(\"G0 Z15 F300\")\n  !for wipe in range(wipe_count):\n  !  for coordinate in [(275, 4), (235, 4)]:\n  !    emit(f\"G0 X{coordinate[0]} Y{coordinate[1] + 0.25 * wipe} Z9.7 F12000\")\n
    "},{"location":"Command_Templates.html#python-rawparams","title":"Python: Rawparams","text":"
    [gcode_macro G4]\nrename_existing: G4.1\ngcode:\n  !if rawparams and \"S\" in rawparams:\n  !  s = int(rawparams.split(\"S\")[1])\n  !  respond_info(f\"Sleeping for {s} seconds\")\n  !  emit(f\"G4.1 P{s * 1000}\")\n  !else:\n  !  p = int(rawparams.split(\"P\")[1])\n  !  respond_info(f\"Sleeping for {p/1000} seconds\")\n  !  emit(f\"G4.1 {rawparams}\")\n
    "},{"location":"Command_Templates.html#python-variables","title":"Python: Variables","text":"
    [gcode_macro POKELOOP]\nvariable_count: 10\nvariable_speed: 3\ngcode:\n  !for i in range(own_vars.count):\n  !  emit(f\"BEACON_POKE SPEED={own_vars.speed} TOP=5 BOTTOM=-0.3\")\n
    "},{"location":"Command_Templates.html#python-printer-objects","title":"Python: Printer objects","text":"
    [gcode_macro EXTRUDER_TEMP]\ngcode:\n    !ACTUAL_TEMP = printer[\"extruder\"][\"temperature\"]\n    !TARGET_TEMP = printer[\"extruder\"][\"target\"]\n    !\n    !respond_info(\"Extruder Target: %.1fC, Actual: %.1fC\" % (TARGET_TEMP, ACTUAL_TEMP))\n
    "},{"location":"Command_Templates.html#python-helpers","title":"Python: Helpers","text":""},{"location":"Command_Templates.html#actions","title":"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:

    "},{"location":"Command_Templates.html#variables","title":"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]\nvariable_bed_temp: 0\ngcode:\n  # Save target temperature to bed_temp variable\n  SET_GCODE_VARIABLE MACRO=start_probe VARIABLE=bed_temp VALUE={printer.heater_bed.target}\n  # Disable bed heater\n  M140\n  # Perform probe\n  PROBE\n  # Call finish_probe macro at completion of probe\n  finish_probe\n\n[gcode_macro finish_probe]\ngcode:\n  # Restore temperature\n  M140 S{printer[\"gcode_macro start_probe\"].bed_temp}\n

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

    "},{"location":"Command_Templates.html#delayed-gcodes","title":"Delayed Gcodes","text":"

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

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

    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]\ninitial_duration: 5.\ngcode:\n  M117 Welcome!\n

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

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

    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\n
    "},{"location":"Command_Templates.html#menu-templates","title":"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:

    The following actions are available in menu templates:

    "},{"location":"Command_Templates.html#menu-dialogs","title":"Menu Dialogs","text":"

    When a menu dialog is used, and additional read-only attribute is availabe in templates.

    [menu __main __setup __tuning __hotend_mpc_dialog] in the default set of menus can be used as reference for how to build more complex dialogs.

    "},{"location":"Command_Templates.html#save-variables-to-disk","title":"Save Variables to disk","text":"

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

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

    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]\ngcode:\n  ACTIVATE_EXTRUDER extruder=extruder1\n  SAVE_VARIABLE VARIABLE=currentextruder VALUE='\"extruder1\"'\n\n[gcode_macro T0]\ngcode:\n  ACTIVATE_EXTRUDER extruder=extruder\n  SAVE_VARIABLE VARIABLE=currentextruder VALUE='\"extruder\"'\n\n[gcode_macro START_GCODE]\ngcode:\n  {% set svv = printer.save_variables.variables %}\n  ACTIVATE_EXTRUDER extruder={svv.currentextruder}\n
    "},{"location":"Config_Changes.html","title":"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 Kalico software.

    All dates in this document are approximate.

    "},{"location":"Config_Changes.html#changes","title":"Changes","text":"

    20250107: The rref parameter for tmc2240 is now mandatory with no default value.

    20241202: The sense_resistor parameter is now mandatory with no default value.

    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.

    20241125: The off_below parameter in fans config section is deprecated. It will be removed in the near future. Use min_power instead. The printer[fan object].speed status will be replaced by printer[fan object].value and printer[fan object].power.

    20241223: The CLEAR_RETRACTION command does not reset parameters to default config values anymore, a RESET_RETRACTION command was added to achieve this. Automatic resetting behavior on events was removed.

    20240430: The adc_ignore_limits parameter in the [danger_options] config section has been renamed to temp_ignore_limits and it now covers all possible temperature sensors.

    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).

    20240128: printer.kinematics now accepts limited_cartesian and limited_cartesian and limited_corexy that enables max_{x,y}_accel and max_{x,y}_velocity (only for limited_cartesian). In the future, this functionality may be moved into the original kinematics module (as optional settings).

    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.

    20230801: The setting fan.off_bellow has been changed to fan.min_power. However, this change will not affect users who do not utilize this setting. With this update, a PWM scaling has been introduced between min_power and max_power. Fans that require a higher min_power will now have access to their full \"safe\" power curve. By properly setting min_power, any fan (such as CPAP) should engage even at M106 S1. It's recommended to review your slicer/macros to adjust your fan speeds. Your previously designated 20% fan speed may no longer represent your lowest fan setting but will now correspond to an actual 20% fan speed. If you had previously set max_power to anything below 1.0 (default), it is advisable to recalibrate min_power and kick_start_time again, with the settings min_power: 0 and max_power: 1.

    20230729: The exported status for dual_carriage is changed. Instead of exporting mode and active_carriage, the individual modes for each carriage are exported as printer.dual_carriage.carriage_0 and printer.dual_carriage.carriage_1.

    20230619: The relative_reference_index option has been deprecated and superceded by the zero_reference_position option. Refer to the Bed Mesh Documentation for details on how to update the configuration. With this deprecation the RELATIVE_REFERENCE_INDEX is no longer available as a parameter for the BED_MESH_CALIBRATE gcode command.

    20230530: The default canbus frequency in \"make menuconfig\" is now 1000000. If using canbus and using canbus with some other frequency is required, then be sure to select \"Enable extra low-level configuration options\" and specify the desired \"CAN bus speed\" in \"make menuconfig\" when compiling and flashing the micro-controller.

    20230525: SHAPER_CALIBRATE command immediately applies input shaper parameters if [input_shaper] was enabled already.

    20230407: The stalled_bytes counter in the log and in the printer.mcu.last_stats field has been renamed to upcoming_bytes.

    20230323: On tmc5160 drivers multistep_filt is now enabled by default. Set driver_MULTISTEP_FILT: False in the tmc5160 config for the previous behavior.

    20230304: The SET_TMC_CURRENT command now properly adjusts the globalscaler register for drivers that have it. This removes a limitation where on tmc5160, the currents could not be raised higher with SET_TMC_CURRENT than the run_current value set in the config file. However, this has a side effect: After running SET_TMC_CURRENT, the stepper must be held at standstill for >130ms in case StealthChop2 is used so that the AT#1 calibration gets executed by the driver.

    20230202: The format of the printer.screws_tilt_adjust status information has changed. The information is now stored as a dictionary of screws with the resulting measurements. See the status reference for details.

    20230201: The [bed_mesh] module no longer loads the default profile on startup. It is recommended that users who use the default profile add BED_MESH_PROFILE LOAD=default to their START_PRINT macro (or to their slicer's \"Start G-Code\" configuration when applicable).

    20230103: It is now possible with the flash-sdcard.sh script to flash both variants of the Bigtreetech SKR-2, STM32F407 and STM32F429. This means that the original tag of btt-skr2 now has changed to either btt-skr-2-f407 or btt-skr-2-f429.

    20221128: Klipper v0.11.0 released.

    20221122: Previously, with safe_z_home, it was possible that the z_hop after the g28 homing would go in the negative z direction. Now, a z_hop is performed after g28 only if it results in a positive hop, mirroring the behavior of the z_hop that occurs before the g28 homing.

    20220616: It was previously possible to flash an rp2040 in bootloader mode by running make flash FLASH_DEVICE=first. The equivalent command is now make flash FLASH_DEVICE=2e8a:0003.

    20220612: The rp2040 micro-controller now has a workaround for the \"rp2040-e5\" USB errata. This should make initial USB connections more reliable. However, it may result in a change in behavior for the gpio15 pin. It is unlikely the gpio15 behavior change will be noticeable.

    20220407: The temperature_fan pid_integral_max config option has been removed (it was deprecated on 20210612).

    20220407: The default color order for pca9632 LEDs is now \"RGBW\". Add an explicit color_order: RBGW setting to the pca9632 config section to obtain the previous behavior.

    20220330: The format of the printer.neopixel.color_data status information for neopixel and dotstar modules has changed. The information is now stored as a list of color lists (instead of a list of dictionaries). See the status reference for details.

    20220307: M73 will no longer set print progress to 0 if P is missing.

    20220304: There is no longer a default for the extruder parameter of extruder_stepper config sections. If desired, specify extruder: extruder explicitly to associate the stepper motor with the \"extruder\" motion queue at startup.

    20220210: The SYNC_STEPPER_TO_EXTRUDER command is deprecated; the SET_EXTRUDER_STEP_DISTANCE command is deprecated; the extruder shared_heater config option is deprecated. These features will be removed in the near future. Replace SET_EXTRUDER_STEP_DISTANCE with SET_EXTRUDER_ROTATION_DISTANCE. Replace SYNC_STEPPER_TO_EXTRUDER with SYNC_EXTRUDER_MOTION. Replace extruder config sections using shared_heater with extruder_stepper config sections and update any activation macros to use SYNC_EXTRUDER_MOTION.

    20220116: The tmc2130, tmc2208, tmc2209, and tmc2660 run_current calculation code has changed. For some run_current settings the drivers may now be configured differently. This new configuration should be more accurate, but it may invalidate previous tmc driver tuning.

    20211230: Scripts to tune input shaper (scripts/calibrate_shaper.py and scripts/graph_accelerometer.py) were migrated to use Python3 by default. As a result, users must install Python3 versions of certain packages (e.g. sudo apt install python3-numpy python3-matplotlib) to continue using these scripts. For more details, refer to Software installation. Alternatively, users can temporarily force the execution of these scripts under Python 2 by explicitly calling Python2 interpretor in the console: python2 ~/klipper/scripts/calibrate_shaper.py ...

    20211110: The \"NTC 100K beta 3950\" temperature sensor is deprecated. This sensor will be removed in the near future. Most users will find the \"Generic 3950\" temperature sensor more accurate. To continue to use the older (typically less accurate) definition, define a custom thermistor with temperature1: 25, resistance1: 100000, and beta: 3950.

    20211104: The \"step pulse duration\" option in \"make menuconfig\" has been removed. The default step duration for TMC drivers configured in UART or SPI mode is now 100ns. A new step_pulse_duration setting in the stepper config section should be set for all steppers that need a custom pulse duration.

    20211102: Several deprecated features have been removed. The stepper step_distance option has been removed (deprecated on 20201222). The rpi_temperature sensor alias has been removed (deprecated on 20210219). The mcu pin_map option has been removed (deprecated on 20210325). The gcode_macro default_parameter_<name> and macro access to command parameters other than via the params pseudo-variable has been removed (deprecated on 20210503). The heater pid_integral_max option has been removed (deprecated on 20210612).

    20210929: Klipper v0.10.0 released.

    20210903: The default smooth_time for heaters has changed to 1 second (from 2 seconds). For most printers this will result in more stable temperature control.

    20210830: The default adxl345 name is now \"adxl345\". The default CHIP parameter for the ACCELEROMETER_MEASURE and ACCELEROMETER_QUERY is now also \"adxl345\".

    20210830: The adxl345 ACCELEROMETER_MEASURE command no longer supports a RATE parameter. To alter the query rate, update the printer.cfg file and issue a RESTART command.

    20210821: Several config settings in printer.configfile.settings will now be reported as lists instead of raw strings. If the actual raw string is desired, use printer.configfile.config instead.

    20210819: In some cases, a G28 homing move may end in a position that is nominally outside the valid movement range. In rare situations this may result in confusing \"Move out of range\" errors after homing. If this occurs, change your start scripts to move the toolhead to a valid position immediately after homing.

    20210814: The analog only pseudo-pins on the atmega168 and atmega328 have been renamed from PE0/PE1 to PE2/PE3.

    20210720: A controller_fan section now monitors all stepper motors by default (not just the kinematic stepper motors). If the previous behavior is desired, see the stepper config option in the config reference.

    20210703: A samd_sercom config section must now specify the sercom bus it is configuring via the sercom option.

    20210612: The pid_integral_max config option in heater and temperature_fan sections is deprecated. The option will be removed in the near future.

    20210503: The gcode_macro default_parameter_<name> config option is deprecated. Use the params pseudo-variable to access macro parameters. Other methods for accessing macro parameters will be removed in the near future. Most users can replace a default_parameter_NAME: VALUE config option with a line like the following in the start of the macro: {% set NAME = params.NAME|default(VALUE)|float %}. See the Command Templates document for examples.

    20210430: The SET_VELOCITY_LIMIT (and M204) command may now set a velocity, acceleration, and square_corner_velocity larger than the specified values in the config file.

    20210325: Support for the pin_map config option is deprecated. Use the sample-aliases.cfg file to translate to the actual micro-controller pin names. The pin_map config option will be removed in the near future.

    20210313: Klipper's support for micro-controllers that communicate with CAN bus has changed. If using CAN bus then all micro-controllers must be reflashed and the Klipper configuration must be updated.

    20210310: The TMC2660 default for driver_SFILT has been changed from 1 to 0.

    20210227: TMC stepper motor drivers in UART or SPI mode are now queried once per second whenever they are enabled - if the driver can not be contacted or if the driver reports an error, then Klipper will transition to a shutdown state.

    20210219: The rpi_temperature module has been renamed to temperature_host. Replace any occurrences of sensor_type: rpi_temperature with sensor_type: temperature_host. The path to the temperature file may be specified in the sensor_path config variable. The rpi_temperature name is deprecated and will be removed in the near future.

    20210201: The TEST_RESONANCES command will now disable input shaping if it was previously enabled (and re-enable it after the test). In order to override this behavior and keep the input shaping enabled, one can pass an additional parameter INPUT_SHAPING=1 to the command.

    20210201: The ACCELEROMETER_MEASURE command will now append the name of the accelerometer chip to the output file name if the chip was given a name in the corresponding adxl345 section of the printer.cfg.

    20201222: The step_distance setting in the stepper config sections is deprecated. It is advised to update the config to use the rotation_distance setting. Support for step_distance will be removed in the near future.

    20201218: The endstop_phase setting in the endstop_phase module has been replaced with trigger_phase. If using the endstop phases module then it will be necessary to convert to rotation_distance and recalibrate any endstop phases by running the ENDSTOP_PHASE_CALIBRATE command.

    20201218: Rotary delta and polar printers must now specify a gear_ratio for their rotary steppers, and they may no longer specify a step_distance parameter. See the config reference for the format of the new gear_ratio paramter.

    20201213: It is not valid to specify a Z \"position_endstop\" when using \"probe:z_virtual_endstop\". An error will now be raised if a Z \"position_endstop\" is specified with \"probe:z_virtual_endstop\". Remove the Z \"position_endstop\" definition to fix the error.

    20201120: The [board_pins] config section now specifies the mcu name in an explicit mcu: parameter. If using board_pins for a secondary mcu, then the config must be updated to specify that name. See the config reference for further details.

    20201112: The time reported by print_stats.print_duration has changed. The duration prior to the first detected extrusion is now excluded.

    20201029: The neopixel color_order_GRB config option has been removed. If necessary, update the config to set the new color_order option to RGB, GRB, RGBW, or GRBW.

    20201029: The serial option in the mcu config section no longer defaults to /dev/ttyS0. In the rare situation where /dev/ttyS0 is the desired serial port, it must be specified explicitly.

    20201020: Klipper v0.9.0 released.

    20200902: The RTD resistance-to-temperature calculation for MAX31865 converters has been corrected to not read low. If you are using such a device, you should recalibrate your print temperature and PID settings.

    20200816: The gcode macro printer.gcode object has been renamed to printer.gcode_move. Several undocumented variables in printer.toolhead and printer.gcode have been removed. See docs/Command_Templates.md for a list of available template variables.

    20200816: The gcode macro \"action_\" system has changed. Replace any calls to printer.gcode.action_emergency_stop() with action_emergency_stop(), printer.gcode.action_respond_info() with action_respond_info(), and printer.gcode.action_respond_error() with action_raise_error().

    20200809: The menu system has been rewritten. If the menu has been customized then it will be necessary to update to the new configuration. See config/example-menu.cfg for configuration details and see klippy/extras/display/menu.cfg for examples.

    20200731: The behavior of the progress attribute reported by the virtual_sdcard printer object has changed. Progress is no longer reset to 0 when a print is paused. It will now always report progress based on the internal file position, or 0 if no file is currently loaded.

    20200725: The servo enable config parameter and the SET_SERVO ENABLE parameter have been removed. Update any macros to use SET_SERVO SERVO=my_servo WIDTH=0 to disable a servo.

    20200608: The LCD display support has changed the name of some internal \"glyphs\". If a custom display layout was implemented it may be necessary to update to the latest glyph names (see klippy/extras/display/display.cfg for a list of available glyphs).

    20200606: The pin names on linux mcu have changed. Pins now have names of the form gpiochip<chipid>/gpio<gpio>. For gpiochip0 you can also use a short gpio<gpio>. For example, what was previously referred to as P20 now becomes gpio20 or gpiochip0/gpio20.

    20200603: The default 16x4 LCD layout will no longer show the estimated time remaining in a print. (Only the elapsed time will be shown.) If the old behavior is desired one can customize the menu display with that information (see the description of display_data in config/example-extras.cfg for details).

    20200531: The default USB vendor/product id is now 0x1d50/0x614e. These new ids are reserved for Klipper (thanks to the openmoko project). This change should not require any config changes, but the new ids may appear in system logs.

    20200524: The default value for the tmc5160 pwm_freq field is now zero (instead of one).

    20200425: The gcode_macro command template variable printer.heater was renamed to printer.heaters.

    20200313: The default lcd layout for multi-extruder printers with a 16x4 screen has changed. The single extruder screen layout is now the default and it will show the currently active extruder. To use the previous display layout set \"display_group: _multiextruder_16x4\" in the [display] section of the printer.cfg file.

    20200308: The default __test menu item was removed. If the config file has a custom menu then be sure to remove all references to this __test menu item.

    20200308: The menu \"deck\" and \"card\" options were removed. To customize the layout of an lcd screen use the new display_data config sections (see config/example-extras.cfg for the details).

    20200109: The bed_mesh module now references the probe's location in for the mesh configuration. As such, some configuration options have been renamed to more accurately reflect their intended functionality. For rectangular beds, min_point and max_point have been renamed to mesh_min and mesh_max respectively. For round beds, bed_radius has been renamed to mesh_radius. A new mesh_origin option has also been added for round beds. Note that these changes are also incompatible with previously saved mesh profiles. If an incompatible profile is detected it will be ignored and scheduled for removal. The removal process can be completed by issuing the SAVE_CONFIG command. The user will need to re-calibrate each profile.

    20191218: The display config section no longer supports \"lcd_type: st7567\". Use the \"uc1701\" display type instead - set \"lcd_type: uc1701\" and change the \"rs_pin: some_pin\" to \"rst_pin: some_pin\". It may also be necessary to add a \"contrast: 60\" config setting.

    20191210: The builtin T0, T1, T2, ... commands have been removed. The extruder activate_gcode and deactivate_gcode config options have been removed. If these commands (and scripts) are needed then define individual [gcode_macro T0] style macros that call the ACTIVATE_EXTRUDER command. See the config/sample-idex.cfg and sample-multi-extruder.cfg files for examples.

    20191210: Support for the M206 command has been removed. Replace with calls to SET_GCODE_OFFSET. If support for M206 is needed, add a [gcode_macro M206] config section that calls SET_GCODE_OFFSET. (For example \"SET_GCODE_OFFSET Z=-{params.Z}\".)

    20191202: Support for the undocumented \"S\" parameter of the \"G4\" command has been removed. Replace any occurrences of S with the standard \"P\" parameter (the delay specified in milliseconds).

    20191126: The USB names have changed on micro-controllers with native USB support. They now use a unique chip id by default (where available). If an \"mcu\" config section uses a \"serial\" setting that starts with \"/dev/serial/by-id/\" then it may be necessary to update the config. Run \"ls /dev/serial/by-id/*\" in an ssh terminal to determine the new id.

    20191121: The pressure_advance_lookahead_time parameter has been removed. See example.cfg for alternate configuration settings.

    20191112: The tmc stepper driver virtual enable capability is now automatically enabled if the stepper does not have a dedicated stepper enable pin. Remove references to tmcXXXX:virtual_enable from the config. The ability to control multiple pins in the stepper enable_pin config has been removed. If multiple pins are needed then use a multi_pin config section.

    20191107: The primary extruder config section must be specified as \"extruder\" and may no longer be specified as \"extruder0\". Gcode command templates that query the extruder status are now accessed via \"{printer.extruder}\".

    20191021: Klipper v0.8.0 released

    20191003: The move_to_previous option in [safe_z_homing] now defaults to False. (It was effectively False prior to 20190918.)

    20190918: The zhop option in [safe_z_homing] is always re-applied after Z axis homing completed. This might need users to update custom scripts based on this module.

    20190806: The SET_NEOPIXEL command has been renamed to SET_LED.

    20190726: The mcp4728 digital-to-analog code has changed. The default i2c_address is now 0x60 and the voltage reference is now relative to the mcp4728's internal 2.048 volt reference.

    20190710: The z_hop option was removed from the [firmware_retract] config section. The z_hop support was incomplete and could cause incorrect behavior with several common slicers.

    20190710: The optional parameters of the PROBE_ACCURACY command have changed. It may be necessary to update any macros or scripts that use that command.

    20190628: All configuration options have been removed from the [skew_correction] section. Configuration for skew_correction is now done via the SET_SKEW gcode. See Skew Correction for recommended usage.

    20190607: The \"variable_X\" parameters of gcode_macro (along with the VALUE parameter of SET_GCODE_VARIABLE) are now parsed as Python literals. If a value needs to be assigned a string then wrap the value in quotes so that it is evaluated as a string.

    20190606: The \"samples\", \"samples_result\", and \"sample_retract_dist\" config options have been moved to the \"probe\" config section. These options are no longer supported in the \"delta_calibrate\", \"bed_tilt\", \"bed_mesh\", \"screws_tilt_adjust\", \"z_tilt\", or \"quad_gantry_level\" config sections.

    20190528: The magic \"status\" variable in gcode_macro template evaluation has been renamed to \"printer\".

    20190520: The SET_GCODE_OFFSET command has changed; update any g-code macros accordingly. The command will no longer apply the requested offset to the next G1 command. The old behavior may be approximated by using the new \"MOVE=1\" parameter.

    20190404: The Python host software packages were updated. Users will need to rerun the ~/klipper/scripts/install-octopi.sh script (or otherwise upgrade the python dependencies if not using a standard OctoPi installation).

    20190404: The i2c_bus and spi_bus parameters (in various config sections) now take a bus name instead of a number.

    20190404: The sx1509 config parameters have changed. The 'address' parameter is now 'i2c_address' and it must be specified as a decimal number. Where 0x3E was previously used, specify 62.

    20190328: The min_speed value in [temperature_fan] config will now be respected and the fan will always run at this speed or higher in PID mode.

    20190322: The default value for \"driver_HEND\" in [tmc2660] config sections was changed from 6 to 3. The \"driver_VSENSE\" field was removed (it is now automatically calculated from run_current).

    20190310: The [controller_fan] config section now always takes a name (such as [controller_fan my_controller_fan]).

    20190308: The \"driver_BLANK_TIME_SELECT\" field in [tmc2130] and [tmc2208] config sections has been renamed to \"driver_TBL\".

    20190308: The [tmc2660] config section has changed. A new sense_resistor config parameter must now be provided. The meaning of several of the driver_XXX parameters has changed.

    20190228: Users of SPI or I2C on SAMD21 boards must now specify the bus pins via a [samd_sercom] config section.

    20190224: The bed_shape option has been removed from bed_mesh. The radius option has been renamed to bed_radius. Users with round beds should supply the bed_radius and round_probe_count options.

    20190107: The i2c_address parameter in the mcp4451 config section changed. This is a common setting on Smoothieboards. The new value is half the old value (88 should be changed to 44, and 90 should be changed to 45).

    20181220: Klipper v0.7.0 released

    "},{"location":"Config_Reference.html","title":"Configuration reference","text":"

    This document is a reference for options available in the Kalico config file.

    Sections and options are marked with an \u26a0\ufe0f to denote configurations that are changed from stock Klipper.

    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 Kalico and choosing an initial config file.

    "},{"location":"Config_Reference.html#micro-controller-configuration","title":"Micro-controller configuration","text":""},{"location":"Config_Reference.html#format-of-micro-controller-pin-names","title":"Format of micro-controller pin names","text":"

    Many config options require the name of a micro-controller pin. Kalico 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.

    "},{"location":"Config_Reference.html#mcu","title":"[mcu]","text":"

    Configuration of the primary micro-controller.

    [mcu]\nserial:\n#   The serial port to connect to the MCU. If unsure (or if it\n#   changes) see the \"Where's my serial port?\" section of the FAQ.\n#   This parameter must be provided when using a serial port.\n#baud: 250000\n#   The baud rate to use. The default is 250000.\n#canbus_uuid:\n#   If using a device connected to a CAN bus then this sets the unique\n#   chip identifier to connect to. This value must be provided when using\n#   CAN bus for communication.\n#canbus_interface:\n#   If using a device connected to a CAN bus then this sets the CAN\n#   network interface to use. The default is 'can0'.\n#restart_method:\n#   This controls the mechanism the host will use to reset the\n#   micro-controller. The choices are 'arduino', 'cheetah', 'rpi_usb',\n#   and 'command'. The 'arduino' method (toggle DTR) is common on\n#   Arduino boards and clones. The 'cheetah' method is a special\n#   method needed for some Fysetc Cheetah boards. The 'rpi_usb' method\n#   is useful on Raspberry Pi boards with micro-controllers powered\n#   over USB - it briefly disables power to all USB ports to\n#   accomplish a micro-controller reset. The 'command' method involves\n#   sending a Kalico command to the micro-controller so that it can\n#   reset itself. The default is 'arduino' if the micro-controller\n#   communicates over a serial port, 'command' otherwise.\n#is_non_critical: False\n#   Setting this to True will allow the mcu to be disconnected and\n#   reconnected at will without errors. Helpful for USB-accelerometer boards\n#   and USB-probes\n
    "},{"location":"Config_Reference.html#mcu-my_extra_mcu","title":"[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]\n# See the \"mcu\" section for configuration parameters.\n
    "},{"location":"Config_Reference.html#danger-options","title":"\u26a0\ufe0f Danger Options","text":"

    A collection of Kalico-specific system options

    [danger_options]\n#error_on_unused_config_options: True\n#   If an unused config option or section should cause an error\n#   if False, will warn but allow Kalico to still run.\n#   The default is True.\n#allow_plugin_override: False\n#   Allows modules in `plugins` to override modules of the same name in `extras`\n#   The default is False.\n#multi_mcu_trsync_timeout: 0.025\n#   The timeout (in seconds) for MCU synchronization during the homing process when\n#   multiple MCUs are in use. The default is 0.025\n#homing_elapsed_distance_tolerance: 0.5\n#   Tolerance (in mm) for distance moved in the second homing. Ensures the\n#   second homing distance closely matches the `min_home_dist` when using\n#   sensorless homing. The default is 0.5mm.\n#temp_ignore_limits: False\n#   When set to true, this parameter ignores the min_value and max_value\n#   limits for temperature sensors. It prevents shutdowns due to\n#   'ADC out of range' and similar errors by allowing readings outside the\n#   specified range without triggering a shutdown. The default is False.\n#autosave_includes: False\n#   When set to true, SAVE_CONFIG will recursively read [include ...] blocks\n#   for conflicts to autosave data. Any configurations updated will be backed\n#   up to configs/config_backups.\n#bgflush_extra_time: 0.250\n#   This allows to set extra flush time (in seconds). Under certain conditions,\n#   a low value will result in an error if message is not get flushed, a high value\n#   (0.250) will result in homing/probing latency. The default is 0.250\n#homing_start_delay: 0.001\n#   How long to dwell before beginning a drip move for homing\n#endstop_sample_time: 0.000015\n#   How often the MCU should sample the endstop state\n#endstop_sample_count: 4\n#   How many times we should check the endstop state when homing\n#   Unless your endstop is noisy and unreliable, you should be able to lower this to 1\n\n\n# Logging options:\n\n#minimal_logging: False\n#   Set all log parameters log options to False. The default is False.\n#log_statistics: True\n#   If statistics should be logged\n#   (helpful for keeping the log clean during development)\n#   The default is True.\n#log_config_file_at_startup: True\n#   If the config file should be logged at startup\n#   The default is True.\n#log_bed_mesh_at_startup: True\n#   If the bed mesh should be logged at startup\n#   (helpful for keeping the log clean during development)\n#   The default is True.\n#log_velocity_limit_changes: True\n#   If changes to velocity limits should be logged. If False, velocity limits will only\n#   be logged at rollover. Some slicers emit very frequent SET_VELOCITY_LIMIT commands\n#   The default is True\n#log_pressure_advance_changes: True\n#   If changes to pressure advance should be logged. If false, pressure advance data\n#   will only be logged at rollover.\n#   The default is True.\n#log_shutdown_info: True\n#   If we should log detailed crash info when an exception occurs\n#   Most of it is overly-verbose and fluff and we still get a stack trace\n#   for normal exceptions, so setting to False can help save time while developing\n#   The default is True.\n#log_serial_reader_warnings: True\n#log_startup_info: True\n#log_webhook_method_register_messages: False\n
    "},{"location":"Config_Reference.html#configuration-references","title":"\u26a0\ufe0f Configuration references","text":"

    In your configuration, you can reference other values to share configuration between multiple sections. References take the form of ${option} to copy a value in the current section, or ${section.option} to look up a value elsewhere in your configuration. Note, that constants must always be lower case.

    Optionally, a [constants] section may be used specifically to store these values. Unlike the rest of your configuration, unused constants will show a warning instead of causing an error.

    [constants]\nrun_current_ab:  1.0\ni_am_not_used: True  # Will show \"Constant 'i_am_not_used' is unused\"\n\n[tmc5160 stepper_x]\nrun_current: ${constants.run_current_ab}\n\n[tmc5160 stepper_y]\nrun_current: ${tmc5160 stepper_x.run_current}\n#   Nested references work, but are not advised\n
    "},{"location":"Config_Reference.html#common-kinematic-settings","title":"Common kinematic settings","text":""},{"location":"Config_Reference.html#printer","title":"[printer]","text":"

    The printer section controls high level printer settings.

    [printer]\nkinematics:\n#   The type of printer in use. This option may be one of: cartesian,\n#   corexy, corexz, hybrid_corexy, hybrid_corexz, rotary_delta, delta,\n#   deltesian, polar, winch, or none. This parameter must be specified.\nmax_velocity:\n#   Maximum velocity (in mm/s) of the toolhead (relative to the\n#   print). This value may be changed at runtime using the\n#   SET_VELOCITY_LIMIT command. This parameter must be specified.\nmax_accel:\n#   Maximum acceleration (in mm/s^2) of the toolhead (relative to the\n#   print). Although this parameter is described as a \"maximum\"\n#   acceleration, in practice most moves that accelerate or decelerate\n#   will do so at the rate specified here. The value specified here\n#   may be changed at runtime using the SET_VELOCITY_LIMIT command.\n#   This parameter must be specified.\n#minimum_cruise_ratio: 0.5\n#   Most moves will accelerate to a cruising speed, travel at that\n#   cruising speed, and then decelerate. However, some moves that\n#   travel a short distance could nominally accelerate and then\n#   immediately decelerate. This option reduces the top speed of these\n#   moves to ensure there is always a minimum distance traveled at a\n#   cruising speed. That is, it enforces a minimum distance traveled\n#   at cruising speed relative to the total distance traveled. It is\n#   intended to reduce the top speed of short zigzag moves (and thus\n#   reduce printer vibration from these moves). For example, a\n#   minimum_cruise_ratio of 0.5 would ensure that a standalone 1.5mm\n#   move would have a minimum cruising distance of 0.75mm. Specify a\n#   ratio of 0.0 to disable this feature (there would be no minimum\n#   cruising distance enforced between acceleration and deceleration).\n#   The value specified here may be changed at runtime using the\n#   SET_VELOCITY_LIMIT command. The default is 0.5.\n#square_corner_velocity: 5.0\n#   The maximum velocity (in mm/s) that the toolhead may travel a 90\n#   degree corner at. A non-zero value can reduce changes in extruder\n#   flow rates by enabling instantaneous velocity changes of the\n#   toolhead during cornering. This value configures the internal\n#   centripetal velocity cornering algorithm; corners with angles\n#   larger than 90 degrees will have a higher cornering velocity while\n#   corners with angles less than 90 degrees will have a lower\n#   cornering velocity. If this is set to zero then the toolhead will\n#   decelerate to zero at each corner. The value specified here may be\n#   changed at runtime using the SET_VELOCITY_LIMIT command. The\n#   default is 5mm/s.\n#max_accel_to_decel:\n#   This parameter is deprecated and should no longer be used.\n
    "},{"location":"Config_Reference.html#stepper","title":"[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]\nstep_pin:\n#   Step GPIO pin (triggered high). This parameter must be provided.\ndir_pin:\n#   Direction GPIO pin (high indicates positive direction). This\n#   parameter must be provided.\nenable_pin:\n#   Enable pin (default is enable high; use ! to indicate enable\n#   low). If this parameter is not provided then the stepper motor\n#   driver must always be enabled.\nrotation_distance:\n#   Distance (in mm) that the axis travels with one full rotation of\n#   the stepper motor (or final gear if gear_ratio is specified).\n#   This parameter must be provided.\nmicrosteps:\n#   The number of microsteps the stepper motor driver uses. This\n#   parameter must be provided.\n#full_steps_per_rotation: 200\n#   The number of full steps for one rotation of the stepper motor.\n#   Set this to 200 for a 1.8 degree stepper motor or set to 400 for a\n#   0.9 degree motor. The default is 200.\n#gear_ratio:\n#   The gear ratio if the stepper motor is connected to the axis via a\n#   gearbox. For example, one may specify \"5:1\" if a 5 to 1 gearbox is\n#   in use. If the axis has multiple gearboxes one may specify a comma\n#   separated list of gear ratios (for example, \"57:11, 2:1\"). If a\n#   gear_ratio is specified then rotation_distance specifies the\n#   distance the axis travels for one full rotation of the final gear.\n#   The default is to not use a gear ratio.\n#step_pulse_duration:\n#   The minimum time between the step pulse signal edge and the\n#   following \"unstep\" signal edge. This is also used to set the\n#   minimum time between a step pulse and a direction change signal.\n#   The default is 0.000000100 (100ns) for TMC steppers that are\n#   configured in UART or SPI mode, and the default is 0.000002 (which\n#   is 2us) for all other steppers.\nendstop_pin:\n#   Endstop switch detection pin. If this endstop pin is on a\n#   different mcu than the stepper motor then it enables \"multi-mcu\n#   homing\". This parameter must be provided for the X, Y, and Z\n#   steppers on cartesian style printers.\n#position_min: 0\n#   Minimum valid distance (in mm) the user may command the stepper to\n#   move to.  The default is 0mm.\nposition_endstop:\n#   Location of the endstop (in mm). This parameter must be provided\n#   for the X, Y, and Z steppers on cartesian style printers.\nposition_max:\n#   Maximum valid distance (in mm) the user may command the stepper to\n#   move to. This parameter must be provided for the X, Y, and Z\n#   steppers on cartesian style printers.\n#homing_speed: 5.0\n#   Maximum velocity (in mm/s) of the stepper when homing. The default\n#   is 5mm/s.\n#homing_retract_dist: 5.0\n#   Distance to backoff (in mm) before homing a second time during\n#   homing. If `use_sensorless_homing` is false, this setting can be set\n#   to zero to disable the second home. If `use_sensorless_homing` is\n#   true, this setting can be > 0 to backoff after homing. The default\n#   is 5mm.\n#homing_retract_speed:\n#   Speed to use on the retract move after homing in case this should\n#   be different from the homing speed, which is the default for this\n#   parameter\n#min_home_dist:\n#   Minimum distance (in mm) for toolhead before sensorless homing. If closer\n#   than `min_home_dist` to endstop, it moves away to this distance, then homes.\n#   If further, it directly homes and retracts to `homing_retract_dist`.\n#   The default is equal to `homing_retract_dist`.\n#second_homing_speed:\n#   Velocity (in mm/s) of the stepper when performing the second home.\n#   The default is homing_speed/2.\n#homing_positive_dir:\n#   If true, homing will cause the stepper to move in a positive\n#   direction (away from zero); if false, home towards zero. It is\n#   better to use the default than to specify this parameter. The\n#   default is true if position_endstop is near position_max and false\n#   if near position_min.\n#use_sensorless_homing:\n#   If true, disables the second home action if homing_retract_dist > 0.\n#   The default is true if endstop_pin is configured to use virtual_endstop\n
    "},{"location":"Config_Reference.html#cartesian-kinematics","title":"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]\nkinematics: cartesian\nmax_z_velocity:\n#   This sets the maximum velocity (in mm/s) of movement along the z\n#   axis. This setting can be used to restrict the maximum speed of\n#   the z stepper motor. The default is to use max_velocity for\n#   max_z_velocity.\nmax_z_accel:\n#   This sets the maximum acceleration (in mm/s^2) of movement along\n#   the z axis. It limits the acceleration of the z stepper motor. The\n#   default is to use max_accel for max_z_accel.\n\n# The stepper_x section is used to describe the stepper controlling\n# the X axis in a cartesian robot.\n[stepper_x]\n\n# The stepper_y section is used to describe the stepper controlling\n# the Y axis in a cartesian robot.\n[stepper_y]\n\n# The stepper_z section is used to describe the stepper controlling\n# the Z axis in a cartesian robot.\n[stepper_z]\n
    "},{"location":"Config_Reference.html#cartesian-kinematics-with-limits-for-x-and-y-axes","title":"\u26a0\ufe0f Cartesian Kinematics with limits for X and Y axes","text":"

    Behaves exactly the as cartesian kinematics, but allows to set a velocity and acceleration limit for X and Y axis. This also makes command SET_KINEMATICS_LIMIT available to sets these limits at runtime.

    [printer]\nkinematics: limited_cartesian\nmax_x_velocity:\n#   This sets the maximum velocity (in mm/s) of movement along the x\n#   axis. This setting can be used to restrict the maximum speed of\n#   the x stepper motor. The default is to use max_velocity for\n#   max_x_velocity.\nmax_y_velocity:\n#   This sets the maximum velocity (in mm/s) of movement along the y\n#   axis. This setting can be used to restrict the maximum speed of\n#   the y stepper motor. The default is to use max_velocity for\n#   max_x_velocity.\nmax_z_velocity:\n#   See cartesian above.\nmax_velocity:\n#   In order to get maximum velocity gains on diagonals, this should be equal or\n#   greater than the hypotenuse (sqrt(x*x + y*y)) of max_x_velocity and\n#   max_y_velocity.\nmax_x_accel:\n#   This sets the maximum acceleration (in mm/s^2) of movement along\n#   the x axis. It limits the acceleration of the x stepper motor. The\n#   default is to use max_accel for max_x_accel.\nmax_y_accel:\n#   This sets the maximum acceleration (in mm/s^2) of movement along\n#   the y axis. It limits the acceleration of the y stepper motor. The\n#   default is to use max_accel for max_y_accel.\nmax_z_accel:\n# See cartesian above.\nmax_accel:\n# See cartesian above.\nscale_xy_accel: False\n#   When true, scales the XY limits by the current tool head acceleration.\n#   The factor is: slicer accel / hypot(max_x_accel, max_y_accel).\n#   See below.\n

    If scale_xy_accel is False, the acceleration set by max_accel, M204 or SET_VELOCITY_LIMIT, acts as a third limit. In that case, this module doesn't apply limitations on moves having an acceleration lower than max_x_accel`` andmax_y_accel. When scale_xy_accel isTrue,max_x_accelandmax_y_accelare scaled by the ratio of the dynamically set acceleration and the hypotenuse of max_x_accel andmax_y_accel, as reported fromSET_KINEMATICS_LIMIT`. This implies that the actual acceleration will always depend on the direction. For example, these settings:

    [printer]\nmax_x_accel: 12000\nmax_y_accel: 9000\nscale_xy_accel: true\n

    SET_KINEMATICS_LIMIT will report a maximum acceleration of 15000 mm/s^2 on 37\u00b0 diagonals. If the slicer emit M204 S3000 (3000 mm/s^2 accel). On these 37\u00b0 and 143\u00b0 diagonals, the toolhead will accelerate at 3000 mm/s^2. On the X axis, the acceleration will be 12000 * 3000 / 15000 = 2400 mm/s^2, and 18000 mm/s^2 for pure Y moves.

    [printer]\nkinematics: delta\nmax_z_velocity:\n#   For delta printers this limits the maximum velocity (in mm/s) of\n#   moves with z axis movement. This setting can be used to reduce the\n#   maximum speed of up/down moves (which require a higher step rate\n#   than other moves on a delta printer). The default is to use\n#   max_velocity for max_z_velocity.\n#max_z_accel:\n#   This sets the maximum acceleration (in mm/s^2) of movement along\n#   the z axis. Setting this may be useful if the printer can reach higher\n#   acceleration on XY moves than Z moves (eg, when using input shaper).\n#   The default is to use max_accel for max_z_accel.\n#minimum_z_position: 0\n#   The minimum Z position that the user may command the head to move\n#   to. The default is 0.\ndelta_radius:\n#   Radius (in mm) of the horizontal circle formed by the three linear\n#   axis towers. This parameter may also be calculated as:\n#    delta_radius = smooth_rod_offset - effector_offset - carriage_offset\n#   This parameter must be provided.\n#print_radius:\n#   The radius (in mm) of valid toolhead XY coordinates. One may use\n#   this setting to customize the range checking of toolhead moves. If\n#   a large value is specified here then it may be possible to command\n#   the toolhead into a collision with a tower. The default is to use\n#   delta_radius for print_radius (which would normally prevent a\n#   tower collision).\n\n# The stepper_a section describes the stepper controlling the front\n# left tower (at 210 degrees). This section also controls the homing\n# parameters (homing_speed, homing_retract_dist) for all towers.\n[stepper_a]\nposition_endstop:\n#   Distance (in mm) between the nozzle and the bed when the nozzle is\n#   in the center of the build area and the endstop triggers. This\n#   parameter must be provided for stepper_a; for stepper_b and\n#   stepper_c this parameter defaults to the value specified for\n#   stepper_a.\narm_length:\n#   Length (in mm) of the diagonal rod that connects this tower to the\n#   print head. This parameter must be provided for stepper_a; for\n#   stepper_b and stepper_c this parameter defaults to the value\n#   specified for stepper_a.\n#angle:\n#   This option specifies the angle (in degrees) that the tower is\n#   at. The default is 210 for stepper_a, 330 for stepper_b, and 90\n#   for stepper_c.\n\n# The stepper_b section describes the stepper controlling the front\n# right tower (at 330 degrees).\n[stepper_b]\n\n# The stepper_c section describes the stepper controlling the rear\n# tower (at 90 degrees).\n[stepper_c]\n\n# The delta_calibrate section enables a DELTA_CALIBRATE extended\n# g-code command that can calibrate the tower endstop positions and\n# angles.\n[delta_calibrate]\nradius:\n#   Radius (in mm) of the area that may be probed. This is the radius\n#   of nozzle coordinates to be probed; if using an automatic probe\n#   with an XY offset then choose a radius small enough so that the\n#   probe always fits over the bed. This parameter must be provided.\n#speed: 50\n#   The speed (in mm/s) of non-probing moves during the calibration.\n#   The default is 50.\n#horizontal_move_z: 5\n#   The height (in mm) that the head should be commanded to move to\n#   just prior to starting a probe operation. The default is 5.\n#use_probe_xy_offsets: False\n#   If True, apply the `[probe]` XY offsets to the probed positions. The\n#   default is False.\n
    "},{"location":"Config_Reference.html#deltesian-kinematics","title":"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]\nkinematics: deltesian\nmax_z_velocity:\n#   For deltesian printers, this limits the maximum velocity (in mm/s) of\n#   moves with z axis movement. This setting can be used to reduce the\n#   maximum speed of up/down moves (which require a higher step rate\n#   than other moves on a deltesian printer). The default is to use\n#   max_velocity for max_z_velocity.\n#max_z_accel:\n#   This sets the maximum acceleration (in mm/s^2) of movement along\n#   the z axis. Setting this may be useful if the printer can reach higher\n#   acceleration on XY moves than Z moves (eg, when using input shaper).\n#   The default is to use max_accel for max_z_accel.\n#minimum_z_position: 0\n#   The minimum Z position that the user may command the head to move\n#   to. The default is 0.\n#min_angle: 5\n#   This represents the minimum angle (in degrees) relative to horizontal\n#   that the deltesian arms are allowed to achieve. This parameter is\n#   intended to restrict the arms from becoming completely horizontal,\n#   which would risk accidental inversion of the XZ axis. The default is 5.\n#print_width:\n#   The distance (in mm) of valid toolhead X coordinates. One may use\n#   this setting to customize the range checking of toolhead moves. If\n#   a large value is specified here then it may be possible to command\n#   the toolhead into a collision with a tower. This setting usually\n#   corresponds to bed width (in mm).\n#slow_ratio: 3\n#   The ratio used to limit velocity and acceleration on moves near the\n#   extremes of the X axis. If vertical distance divided by horizontal\n#   distance exceeds the value of slow_ratio, then velocity and\n#   acceleration are limited to half their nominal values. If vertical\n#   distance divided by horizontal distance exceeds twice the value of\n#   the slow_ratio, then velocity and acceleration are limited to one\n#   quarter of their nominal values. The default is 3.\n\n# The stepper_left section is used to describe the stepper controlling\n# the left tower. This section also controls the homing parameters\n# (homing_speed, homing_retract_dist) for all towers.\n[stepper_left]\nposition_endstop:\n#   Distance (in mm) between the nozzle and the bed when the nozzle is\n#   in the center of the build area and the endstops are triggered. This\n#   parameter must be provided for stepper_left; for stepper_right this\n#   parameter defaults to the value specified for stepper_left.\narm_length:\n#   Length (in mm) of the diagonal rod that connects the tower carriage to\n#   the print head. This parameter must be provided for stepper_left; for\n#   stepper_right, this parameter defaults to the value specified for\n#   stepper_left.\narm_x_length:\n#   Horizontal distance between the print head and the tower when the\n#   printers is homed. This parameter must be provided for stepper_left;\n#   for stepper_right, this parameter defaults to the value specified for\n#   stepper_left.\n\n# The stepper_right section is used to describe the stepper controlling the\n# right tower.\n[stepper_right]\n\n# The stepper_y section is used to describe the stepper controlling\n# the Y axis in a deltesian robot.\n[stepper_y]\n
    "},{"location":"Config_Reference.html#corexy-kinematics","title":"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]\nkinematics: corexy\nmax_z_velocity:\n#   This sets the maximum velocity (in mm/s) of movement along the z\n#   axis. This setting can be used to restrict the maximum speed of\n#   the z stepper motor. The default is to use max_velocity for\n#   max_z_velocity.\nmax_z_accel:\n#   This sets the maximum acceleration (in mm/s^2) of movement along\n#   the z axis. It limits the acceleration of the z stepper motor. The\n#   default is to use max_accel for max_z_accel.\n\n# The stepper_x section is used to describe the X axis as well as the\n# stepper controlling the X+Y movement.\n[stepper_x]\n\n# The stepper_y section is used to describe the Y axis as well as the\n# stepper controlling the X-Y movement.\n[stepper_y]\n\n# The stepper_z section is used to describe the stepper controlling\n# the Z axis.\n[stepper_z]\n
    "},{"location":"Config_Reference.html#corexy-kinematics-with-limits-for-x-and-y-axes","title":"\u26a0\ufe0f CoreXY Kinematics with limits for X and Y axes","text":"

    Behaves exactly the as CoreXY kinematics, but allows to set a acceleration limit for X and Y axis.

    There is no velocity limits for X and Y, since on a CoreXY the pull-out velocity are identical on both axes.

    [printer]\nkinematics: limited_corexy\nmax_z_velocity:\n#   See CoreXY above.\nmax_x_accel:\n#   This sets the maximum acceleration (in mm/s^2) of movement along\n#   the x axis. It limits the acceleration of the x stepper motor. The\n#   default is to use max_accel for max_x_accel.\nmax_y_accel:\n#   This sets the maximum acceleration (in mm/s^2) of movement along\n#   the y axis. It limits the acceleration of the y stepper motor. The\n#   default is to use max_accel for max_y_accel.\nmax_z_accel:\n# See CoreXY above.\nmax_accel:\n# See CoreXY above..\nscale_xy_accel:\n#   When True, scales the XY limits by the current tool head acceleration.\n#   The factor is: slicer accel / max(max_x_accel, max_y_accel).\n
    "},{"location":"Config_Reference.html#corexz-kinematics","title":"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]\nkinematics: corexz\nmax_z_velocity:\n#   This sets the maximum velocity (in mm/s) of movement along the z\n#   axis. The default is to use max_velocity for max_z_velocity.\nmax_z_accel:\n#   This sets the maximum acceleration (in mm/s^2) of movement along\n#   the z axis. The default is to use max_accel for max_z_accel.\n\n# The stepper_x section is used to describe the X axis as well as the\n# stepper controlling the X+Z movement.\n[stepper_x]\n\n# The stepper_y section is used to describe the stepper controlling\n# the Y axis.\n[stepper_y]\n\n# The stepper_z section is used to describe the Z axis as well as the\n# stepper controlling the X-Z movement.\n[stepper_z]\n
    "},{"location":"Config_Reference.html#corexz-kinematics-with-limits-for-x-and-y-axes","title":"\u26a0\ufe0f CoreXZ Kinematics with limits for X and Y axes","text":"
    [printer]\nkinematics: limited_corexz\nmax_velocity: 500 # Hypotenuse of the two values bellow\nmax_x_velocity: 400\nmax_y_velocity: 300\nmax_z_velocity: 5\nmax_accel: 1500 # Default acceleration of your choice\nmax_x_accel: 12000\nmax_y_accel: 9000\nmax_z_accel: 100\nscale_xy_accel: [True/False, default False]\n

    max_velocity is usually the hypotenuses of X and Y velocity, For example: with max_x_velocity: 300 and max_y_velocity: 400, the recommended value is max_velocity: 500.

    If scale_xy_accel is False, max_accel, set by M204 or SET_VELOCITY_LIMIT, acts as a third limit. In that case, this module doesn't apply limitations to moves with an acceleration lower than max_x_accel and max_y_accel.

    When scale_xy_accel is True, max_x_accel and max_y_accel are scaled by the ratio of the dynamically set acceleration and the hypotenuse of max_x_accel and max_y_accel, as reported from SET_KINEMATICS_LIMIT. This means that the actual acceleration will always depend on the direction.

    For example with these settings:

    [printer]\nmax_x_accel: 12000\nmax_y_accel: 9000\nscale_xy_accel: True\n

    SET_KINEMATICS_LIMIT will report a maximum acceleration of 15000 mm/s^2 on 37 degrees diagonals. Thus, setting an acceleration of 3000 mm/s^2 in the slicer will make the toolhead accelerate at 3000 mm/s^2 on these 37 and 143 degrees diagonals, but only 12000 * 3000 / 15000 = 2400 mm/s^2 for moves aligned with the X axis and 18000 mm/s^2 for pure Y moves.

    "},{"location":"Config_Reference.html#hybrid-corexy-kinematics","title":"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]\nkinematics: hybrid_corexy\ninvert_kinematics: False\n# \u26a0\ufe0f Some hybrid_corexy machines with dual carriages may need to\n#   invert the kinematics if the toolheads move in reverse\nmax_z_velocity:\n#   This sets the maximum velocity (in mm/s) of movement along the z\n#   axis. The default is to use max_velocity for max_z_velocity.\nmax_z_accel:\n#   This sets the maximum acceleration (in mm/s^2) of movement along\n#   the z axis. The default is to use max_accel for max_z_accel.\n\n# The stepper_x section is used to describe the X axis as well as the\n# stepper controlling the X-Y movement.\n[stepper_x]\n\n# The stepper_y section is used to describe the stepper controlling\n# the Y axis.\n[stepper_y]\n\n# The stepper_z section is used to describe the stepper controlling\n# the Z axis.\n[stepper_z]\n
    "},{"location":"Config_Reference.html#hybrid-corexz-kinematics","title":"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]\nkinematics: hybrid_corexz\ninvert_kinematics: False\n# \u26a0\ufe0f Some hybrid_corexy machines with dual carriages may need to\n#   invert the kinematics if the toolheads move in reverse\nmax_z_velocity:\n#   This sets the maximum velocity (in mm/s) of movement along the z\n#   axis. The default is to use max_velocity for max_z_velocity.\nmax_z_accel:\n#   This sets the maximum acceleration (in mm/s^2) of movement along\n#   the z axis. The default is to use max_accel for max_z_accel.\n\n# The stepper_x section is used to describe the X axis as well as the\n# stepper controlling the X-Z movement.\n[stepper_x]\n\n# The stepper_y section is used to describe the stepper controlling\n# the Y axis.\n[stepper_y]\n\n# The stepper_z section is used to describe the stepper controlling\n# the Z axis.\n[stepper_z]\n
    "},{"location":"Config_Reference.html#polar-kinematics","title":"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]\nkinematics: polar\nmax_z_velocity:\n#   This sets the maximum velocity (in mm/s) of movement along the z\n#   axis. This setting can be used to restrict the maximum speed of\n#   the z stepper motor. The default is to use max_velocity for\n#   max_z_velocity.\nmax_z_accel:\n#   This sets the maximum acceleration (in mm/s^2) of movement along\n#   the z axis. It limits the acceleration of the z stepper motor. The\n#   default is to use max_accel for max_z_accel.\n\n# The stepper_bed section is used to describe the stepper controlling\n# the bed.\n[stepper_bed]\ngear_ratio:\n#   A gear_ratio must be specified and rotation_distance may not be\n#   specified. For example, if the bed has an 80 toothed pulley driven\n#   by a stepper with a 16 toothed pulley then one would specify a\n#   gear ratio of \"80:16\". This parameter must be provided.\n\n# The stepper_arm section is used to describe the stepper controlling\n# the carriage on the arm.\n[stepper_arm]\n\n# The stepper_z section is used to describe the stepper controlling\n# the Z axis.\n[stepper_z]\n
    "},{"location":"Config_Reference.html#rotary-delta-kinematics","title":"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]\nkinematics: rotary_delta\nmax_z_velocity:\n#   For delta printers this limits the maximum velocity (in mm/s) of\n#   moves with z axis movement. This setting can be used to reduce the\n#   maximum speed of up/down moves (which require a higher step rate\n#   than other moves on a delta printer). The default is to use\n#   max_velocity for max_z_velocity.\n#minimum_z_position: 0\n#   The minimum Z position that the user may command the head to move\n#   to.  The default is 0.\nshoulder_radius:\n#   Radius (in mm) of the horizontal circle formed by the three\n#   shoulder joints, minus the radius of the circle formed by the\n#   effector joints. This parameter may also be calculated as:\n#     shoulder_radius = (delta_f - delta_e) / sqrt(12)\n#   This parameter must be provided.\nshoulder_height:\n#   Distance (in mm) of the shoulder joints from the bed, minus the\n#   effector toolhead height. This parameter must be provided.\n\n# The stepper_a section describes the stepper controlling the rear\n# right arm (at 30 degrees). This section also controls the homing\n# parameters (homing_speed, homing_retract_dist) for all arms.\n[stepper_a]\ngear_ratio:\n#   A gear_ratio must be specified and rotation_distance may not be\n#   specified. For example, if the arm has an 80 toothed pulley driven\n#   by a pulley with 16 teeth, which is in turn connected to a 60\n#   toothed pulley driven by a stepper with a 16 toothed pulley, then\n#   one would specify a gear ratio of \"80:16, 60:16\". This parameter\n#   must be provided.\nposition_endstop:\n#   Distance (in mm) between the nozzle and the bed when the nozzle is\n#   in the center of the build area and the endstop triggers. This\n#   parameter must be provided for stepper_a; for stepper_b and\n#   stepper_c this parameter defaults to the value specified for\n#   stepper_a.\nupper_arm_length:\n#   Length (in mm) of the arm connecting the \"shoulder joint\" to the\n#   \"elbow joint\". This parameter must be provided for stepper_a; for\n#   stepper_b and stepper_c this parameter defaults to the value\n#   specified for stepper_a.\nlower_arm_length:\n#   Length (in mm) of the arm connecting the \"elbow joint\" to the\n#   \"effector joint\". This parameter must be provided for stepper_a;\n#   for stepper_b and stepper_c this parameter defaults to the value\n#   specified for stepper_a.\n#angle:\n#   This option specifies the angle (in degrees) that the arm is at.\n#   The default is 30 for stepper_a, 150 for stepper_b, and 270 for\n#   stepper_c.\n\n# The stepper_b section describes the stepper controlling the rear\n# left arm (at 150 degrees).\n[stepper_b]\n\n# The stepper_c section describes the stepper controlling the front\n# arm (at 270 degrees).\n[stepper_c]\n\n# The delta_calibrate section enables a DELTA_CALIBRATE extended\n# g-code command that can calibrate the shoulder endstop positions.\n[delta_calibrate]\nradius:\n#   Radius (in mm) of the area that may be probed. This is the radius\n#   of nozzle coordinates to be probed; if using an automatic probe\n#   with an XY offset then choose a radius small enough so that the\n#   probe always fits over the bed. This parameter must be provided.\n#speed: 50\n#   The speed (in mm/s) of non-probing moves during the calibration.\n#   The default is 50.\n#horizontal_move_z: 5\n#   The height (in mm) that the head should be commanded to move to\n#   just prior to starting a probe operation. The default is 5.\n
    "},{"location":"Config_Reference.html#cable-winch-kinematics","title":"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]\nkinematics: winch\n\n# The stepper_a section describes the stepper connected to the first\n# cable winch. A minimum of 3 and a maximum of 26 cable winches may be\n# defined (stepper_a to stepper_z) though it is common to define 4.\n[stepper_a]\nrotation_distance:\n#   The rotation_distance is the nominal distance (in mm) the toolhead\n#   moves towards the cable winch for each full rotation of the\n#   stepper motor. This parameter must be provided.\nanchor_x:\nanchor_y:\nanchor_z:\n#   The X, Y, and Z position of the cable winch in cartesian space.\n#   These parameters must be provided.\n
    "},{"location":"Config_Reference.html#none-kinematics","title":"None Kinematics","text":"

    It is possible to define a special \"none\" kinematics to disable kinematic support in Kalico. This may be useful for controlling devices that are not typical 3d-printers or for debugging purposes.

    [printer]\nkinematics: none\nmax_velocity: 1\nmax_accel: 1\n#   The max_velocity and max_accel parameters must be defined. The\n#   values are not used for \"none\" kinematics.\n
    "},{"location":"Config_Reference.html#common-extruder-and-heated-bed-support","title":"Common extruder and heated bed support","text":""},{"location":"Config_Reference.html#extruder","title":"[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. See PID or MPC for more detailed information about the control methods.

    [extruder]\nstep_pin:\ndir_pin:\nenable_pin:\nmicrosteps:\nrotation_distance:\n#full_steps_per_rotation:\n#gear_ratio:\n#   See the \"stepper\" section for a description of the above\n#   parameters. If none of the above parameters are specified then no\n#   stepper will be associated with the nozzle hotend (though a\n#   SYNC_EXTRUDER_MOTION command may associate one at run-time).\nnozzle_diameter:\n#   Diameter of the nozzle orifice (in mm). This parameter must be\n#   provided.\nfilament_diameter:\n#   The nominal diameter of the raw filament (in mm) as it enters the\n#   extruder. This parameter must be provided.\n#max_extrude_cross_section:\n#   Maximum area (in mm^2) of an extrusion cross section (eg,\n#   extrusion width multiplied by layer height). This setting prevents\n#   excessive amounts of extrusion during relatively small XY moves.\n#   If a move requests an extrusion rate that would exceed this value\n#   it will cause an error to be returned. The default is: 4.0 *\n#   nozzle_diameter^2\n#instantaneous_corner_velocity: 1.000\n#   The maximum instantaneous velocity change (in mm/s) of the\n#   extruder during the junction of two moves. The default is 1mm/s.\n#max_extrude_only_distance: 50.0\n#   Maximum length (in mm of raw filament) that a retraction or\n#   extrude-only move may have. If a retraction or extrude-only move\n#   requests a distance greater than this value it will cause an error\n#   to be returned. The default is 50mm.\n#max_extrude_only_velocity:\n#max_extrude_only_accel:\n#   Maximum velocity (in mm/s) and acceleration (in mm/s^2) of the\n#   extruder motor for retractions and extrude-only moves. These\n#   settings do not have any impact on normal printing moves. If not\n#   specified then they are calculated to match the limit an XY\n#   printing move with a cross section of 4.0*nozzle_diameter^2 would\n#   have.\n#pressure_advance: 0.0\n#   The amount of raw filament to push into the extruder during\n#   extruder acceleration. An equal amount of filament is retracted\n#   during deceleration. It is measured in millimeters per\n#   millimeter/second. The default is 0, which disables pressure\n#   advance.\n#pressure_advance_smooth_time: 0.040\n#   A time range (in seconds) to use when calculating the average\n#   extruder velocity for pressure advance. A larger value results in\n#   smoother extruder movements. This parameter may not exceed 200ms.\n#   This setting only applies if pressure_advance is non-zero. The\n#   default is 0.040 (40 milliseconds).\n#\n# The remaining variables describe the extruder heater.\nheater_pin:\n#   PWM output pin controlling the heater. This parameter must be\n#   provided.\n#max_power: 1.0\n#   The maximum power (expressed as a value from 0.0 to 1.0) that the\n#   heater_pin may be set to. The value 1.0 allows the pin to be set\n#   fully enabled for extended periods, while a value of 0.5 would\n#   allow the pin to be enabled for no more than half the time. This\n#   setting may be used to limit the total power output (over extended\n#   periods) to the heater. The default is 1.0.\nsensor_type:\n#   Type of sensor - common thermistors are \"EPCOS 100K B57560G104F\",\n#   \"ATC Semitec 104GT-2\", \"ATC Semitec 104NT-4-R025H42G\", \"Generic\n#   3950\",\"Honeywell 100K 135-104LAG-J01\", \"NTC 100K MGB18-104F39050L32\",\n#   \"SliceEngineering 450\", and \"TDK NTCG104LH104JT1\". See the\n#   \"Temperature sensors\" section for other sensors. This parameter\n#   must be provided.\nsensor_pin:\n#   Analog input pin connected to the sensor. This parameter must be\n#   provided.\n#pullup_resistor: 4700\n#   The resistance (in ohms) of the pullup attached to the thermistor.\n#   This parameter is only valid when the sensor is a thermistor. The\n#   default is 4700 ohms.\n#smooth_time: 1.0\n#   A time value (in seconds) over which temperature measurements will\n#   be smoothed to reduce the impact of measurement noise. The default\n#   is 1 seconds.\ncontrol:\n#   Control algorithm (either pid, pid_v, watermark or mpc). This parameter must\n#   be provided. pid_v should only be used on well calibrated heaters with\n#   low to moderate noise.\n#\n#   If control: pid or pid_v\n#pid_Kp:\n#pid_Ki:\n#pid_Kd:\n#   The proportional (pid_Kp), integral (pid_Ki), and derivative\n#   (pid_Kd) settings for the PID feedback control system. Kalico\n#   evaluates the PID settings with the following general formula:\n#     heater_pwm = (Kp*error + Ki*integral(error) - Kd*derivative(error)) / 255\n#   Where \"error\" is \"requested_temperature - measured_temperature\"\n#   and \"heater_pwm\" is the requested heating rate with 0.0 being full\n#   off and 1.0 being full on. Consider using the PID_CALIBRATE\n#   command to obtain these parameters. The pid_Kp, pid_Ki, and pid_Kd\n#   parameters must be provided for PID heaters.\n#\n#   If control: watermark\n#max_delta: 2.0\n#   On 'watermark' controlled heaters this is the number of degrees in\n#   Celsius above the target temperature before disabling the heater\n#   as well as the number of degrees below the target before\n#   re-enabling the heater. The default is 2 degrees Celsius.\n#\n#   If control: mpc\n#   See MPC.md for details about these parameters.\n#heater_power:\n#cooling_fan:\n#ambient_temp_sensor:\n#filament_diameter: 1.75\n#filament_density: 1.2\n#filament_heat_capacity: 1.8\n#\n#pwm_cycle_time: 0.100\n#   Time in seconds for each software PWM cycle of the heater. It is\n#   not recommended to set this unless there is an electrical\n#   requirement to switch the heater faster than 10 times a second.\n#   The default is 0.100 seconds.\n#min_extrude_temp: 170\n#   The minimum temperature (in Celsius) at which extruder move\n#   commands may be issued. The default is 170 Celsius.\nmin_temp:\nmax_temp:\n#   The maximum range of valid temperatures (in Celsius) that the\n#   heater must remain within. This controls a safety feature\n#   implemented in the micro-controller code - should the measured\n#   temperature ever fall outside this range then the micro-controller\n#   will go into a shutdown state. This check can help detect some\n#   heater and sensor hardware failures. Set this range just wide\n#   enough so that reasonable temperatures do not result in an error.\n#   These parameters must be provided.\nper_move_pressure_advance: False\n#   If true, uses pressure advance constant from trapq when processing moves\n#   This causes changes to pressure advance be taken into account immediately,\n#   for all moves in the current queue, rather than ~250ms later once the queue gets flushed\n
    "},{"location":"Config_Reference.html#heater_bed","title":"[heater_bed]","text":"

    The heater_bed section describes a heated bed. It uses the same heater settings described in the \"extruder\" section.

    [heater_bed]\nheater_pin:\nsensor_type:\nsensor_pin:\ncontrol:\nmin_temp:\nmax_temp:\n#   See the \"extruder\" section for a description of the above parameters.\n
    "},{"location":"Config_Reference.html#bed-level-support","title":"Bed level support","text":""},{"location":"Config_Reference.html#bed_mesh","title":"[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:\n             x---x---x (max_point)\n             |\n             x---x---x\n                     |\n (min_point) x---x---x\n\n round bed, round_probe_count = 5, bed_radius = r:\n                 x (0, r) end\n               /\n             x---x---x\n                       \\\n (-r, 0) x---x---x---x---x (r, 0)\n           \\\n             x---x---x\n                   /\n                 x  (0, -r) start\n
    [bed_mesh]\n#speed: 50\n#   The speed (in mm/s) of non-probing moves during the calibration.\n#   The default is 50.\n#horizontal_move_z: 5\n#   The height (in mm) that the head should be commanded to move to\n#   just prior to starting a probe operation. The default is 5.\n#mesh_radius:\n#   Defines the radius of the mesh to probe for round beds. Note that\n#   the radius is relative to the coordinate specified by the\n#   mesh_origin option. This parameter must be provided for round beds\n#   and omitted for rectangular beds.\n#mesh_origin:\n#   Defines the center X, Y coordinate of the mesh for round beds. This\n#   coordinate is relative to the probe's location. It may be useful\n#   to adjust the mesh_origin in an effort to maximize the size of the\n#   mesh radius. Default is 0, 0. This parameter must be omitted for\n#   rectangular beds.\n#mesh_min:\n#   Defines the minimum X, Y coordinate of the mesh for rectangular\n#   beds. This coordinate is relative to the probe's location. This\n#   will be the first point probed, nearest to the origin. This\n#   parameter must be provided for rectangular beds.\n#mesh_max:\n#   Defines the maximum X, Y coordinate of the mesh for rectangular\n#   beds. Adheres to the same principle as mesh_min, however this will\n#   be the furthest point probed from the bed's origin. This parameter\n#   must be provided for rectangular beds.\n#probe_count: 3, 3\n#   For rectangular beds, this is a comma separate pair of integer\n#   values X, Y defining the number of points to probe along each\n#   axis. A single value is also valid, in which case that value will\n#   be applied to both axes. Default is 3, 3.\n#round_probe_count: 5\n#   For round beds, this integer value defines the maximum number of\n#   points to probe along each axis. This value must be an odd number.\n#   Default is 5.\n#fade_start: 1.0\n#   The gcode z position in which to start phasing out z-adjustment\n#   when fade is enabled. Default is 1.0.\n#fade_end: 0.0\n#   The gcode z position in which phasing out completes. When set to a\n#   value below fade_start, fade is disabled. It should be noted that\n#   fade may add unwanted scaling along the z-axis of a print. If a\n#   user wishes to enable fade, a value of 10.0 is recommended.\n#   Default is 0.0, which disables fade.\n#fade_target:\n#   The z position in which fade should converge. When this value is\n#   set to a non-zero value it must be within the range of z-values in\n#   the mesh. Users that wish to converge to the z homing position\n#   should set this to 0. Default is the average z value of the mesh.\n#split_delta_z: .025\n#   The amount of Z difference (in mm) along a move that will trigger\n#   a split. Default is .025.\n#move_check_distance: 5.0\n#   The distance (in mm) along a move to check for split_delta_z.\n#   This is also the minimum length that a move can be split. Default\n#   is 5.0.\n#mesh_pps: 2, 2\n#   A comma separated pair of integers X, Y defining the number of\n#   points per segment to interpolate in the mesh along each axis. A\n#   \"segment\" can be defined as the space between each probed point.\n#   The user may enter a single value which will be applied to both\n#   axes. Default is 2, 2.\n#algorithm: lagrange\n#   The interpolation algorithm to use. May be either \"lagrange\" or\n#   \"bicubic\". This option will not affect 3x3 grids, which are forced\n#   to use lagrange sampling. Default is lagrange.\n#bicubic_tension: .2\n#   When using the bicubic algorithm the tension parameter above may\n#   be applied to change the amount of slope interpolated. Larger\n#   numbers will increase the amount of slope, which results in more\n#   curvature in the mesh. Default is .2.\n#zero_reference_position:\n#   An optional X,Y coordinate that specifies the location on the bed\n#   where Z = 0.  When this option is specified the mesh will be offset\n#   so that zero Z adjustment occurs at this location.  The default is\n#   no zero reference.\n#faulty_region_1_min:\n#faulty_region_1_max:\n#   Optional points that define a faulty region.  See docs/Bed_Mesh.md\n#   for details on faulty regions.  Up to 99 faulty regions may be added.\n#   By default no faulty regions are set.\n#adaptive_margin:\n#   An optional margin (in mm) to be added around the bed area used by\n#   the defined print objects when generating an adaptive mesh.\n#bed_mesh_default:\n#   Optionally provide the name of a profile you would like loaded on init.\n#   By default, no profile is loaded.\n#use_probe_xy_offsets: True\n#   If True, apply the `[probe]` XY offsets to the probed positions. The\n#   default is True.\n
    "},{"location":"Config_Reference.html#bed_tilt","title":"[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]\n#x_adjust: 0\n#   The amount to add to each move's Z height for each mm on the X\n#   axis. The default is 0.\n#y_adjust: 0\n#   The amount to add to each move's Z height for each mm on the Y\n#   axis. The default is 0.\n#z_adjust: 0\n#   The amount to add to the Z height when the nozzle is nominally at\n#   0, 0. The default is 0.\n# The remaining parameters control a BED_TILT_CALIBRATE extended\n# g-code command that may be used to calibrate appropriate x and y\n# adjustment parameters.\n#points:\n#   A list of X, Y coordinates (one per line; subsequent lines\n#   indented) that should be probed during a BED_TILT_CALIBRATE\n#   command. Specify coordinates of the nozzle and be sure the probe\n#   is above the bed at the given nozzle coordinates. The default is\n#   to not enable the command.\n#speed: 50\n#   The speed (in mm/s) of non-probing moves during the calibration.\n#   The default is 50.\n#horizontal_move_z: 5\n#   The height (in mm) that the head should be commanded to move to\n#   just prior to starting a probe operation. The default is 5.\n#use_probe_xy_offsets: False\n#   If True, apply the `[probe]` XY offsets to the probed positions. The\n#   default is False.\n
    "},{"location":"Config_Reference.html#bed_screws","title":"[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]\n#screw1:\n#   The X, Y coordinate of the first bed leveling screw. This is a\n#   position to command the nozzle to that is directly above the bed\n#   screw (or as close as possible while still being above the bed).\n#   This parameter must be provided.\n#screw1_name:\n#   An arbitrary name for the given screw. This name is displayed when\n#   the helper script runs. The default is to use a name based upon\n#   the screw XY location.\n#screw1_fine_adjust:\n#   An X, Y coordinate to command the nozzle to so that one can fine\n#   tune the bed leveling screw. The default is to not perform fine\n#   adjustments on the bed screw.\n#screw2:\n#screw2_name:\n#screw2_fine_adjust:\n#...\n#   Additional bed leveling screws. At least three screws must be\n#   defined.\n#horizontal_move_z: 5\n#   The height (in mm) that the head should be commanded to move to\n#   when moving from one screw location to the next. The default is 5.\n#probe_height: 0\n#   The height of the probe (in mm) after adjusting for the thermal\n#   expansion of bed and nozzle. The default is zero.\n#speed: 50\n#   The speed (in mm/s) of non-probing moves during the calibration.\n#   The default is 50.\n#probe_speed: 5\n#   The speed (in mm/s) when moving from a horizontal_move_z position\n#   to a probe_height position. The default is 5.\n
    "},{"location":"Config_Reference.html#screws_tilt_adjust","title":"[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]\n#screw1:\n#   The (X, Y) coordinate of the first bed leveling screw. This is a\n#   position to command the nozzle to so that the probe is directly\n#   above the bed screw (or as close as possible while still being\n#   above the bed). This is the base screw used in calculations. This\n#   parameter must be provided.\n#screw1_name:\n#   An arbitrary name for the given screw. This name is displayed when\n#   the helper script runs. The default is to use a name based upon\n#   the screw XY location.\n#screw2:\n#screw2_name:\n#...\n#   Additional bed leveling screws. At least two screws must be\n#   defined.\n#speed: 50\n#   The speed (in mm/s) of non-probing moves during the calibration.\n#   The default is 50.\n#horizontal_move_z: 5\n#   The height (in mm) that the head should be commanded to move to\n#   just prior to starting a probe operation. The default is 5.\n#screw_thread: CW-M3\n#   The type of screw used for bed leveling, M3, M4, or M5, and the\n#   rotation direction of the knob that is used to level the bed.\n#   Accepted values: CW-M3, CCW-M3, CW-M4, CCW-M4, CW-M5, CCW-M5, CW-M8, CCW-M8.\n#   Default value is CW-M3 which most printers use. A clockwise\n#   rotation of the knob decreases the gap between the nozzle and the\n#   bed. Conversely, a counter-clockwise rotation increases the gap.\n#use_probe_xy_offsets: False\n#   If True, apply the `[probe]` XY offsets to the probed positions. The\n#   default is False.\n
    "},{"location":"Config_Reference.html#z_tilt","title":"[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]\n#z_positions:\n#   A list of X, Y coordinates (one per line; subsequent lines\n#   indented) describing the location of each bed \"pivot point\". The\n#   \"pivot point\" is the point where the bed attaches to the given Z\n#   stepper. It is described using nozzle coordinates (the X, Y position\n#   of the nozzle if it could move directly above the point). The\n#   first entry corresponds to stepper_z, the second to stepper_z1,\n#   the third to stepper_z2, etc. This parameter must be provided.\n#points:\n#   A list of X, Y coordinates (one per line; subsequent lines\n#   indented) that should be probed during a Z_TILT_ADJUST command.\n#   Specify coordinates of the nozzle and be sure the probe is above\n#   the bed at the given nozzle coordinates. This parameter must be\n#   provided.\n#speed: 50\n#   The speed (in mm/s) of non-probing moves during the calibration.\n#   The default is 50.\n#horizontal_move_z: 5\n#   The height (in mm) that the head should be commanded to move to\n#   just prior to starting a probe operation. The default is 5.\n#min_horizontal_move_z: 1.0\n#   minimum value for horizontal move z\n#   (only used when adaptive_horizontal_move_z is True)\n#adaptive_horizontal_move_z: False\n#   if we should adjust horizontal move z after the first adjustment round,\n#   based on error.\n#   when set to True, initial horizontal_move_z is the config value,\n#   subsequent iterations will set horizontal_move_z to\n#   the ceil of error, or min_horizontal_move_z - whichever is greater.\n#retries: 0\n#   Number of times to retry if the probed points aren't within\n#   tolerance.\n#retry_tolerance: 0\n#   If retries are enabled then retry if largest and smallest probed\n#   points differ more than retry_tolerance. Note the smallest unit of\n#   change here would be a single step. However if you are probing\n#   more points than steppers then you will likely have a fixed\n#   minimum value for the range of probed points which you can learn\n#   by observing command output.\n#increasing_threshold: 0.0000001\n#   Sets the threshold that probe points can increase before z_tilt aborts.\n#   To disable the validation, set this parameter to a high value.\n#use_probe_xy_offsets: False\n#   If True, apply the `[probe]` XY offsets to the probed positions. The\n#   default is False.\n
    "},{"location":"Config_Reference.html#z_tilt_ng","title":"[z_tilt_ng]","text":"

    z_tilt's next generation, adding the Z_TILT_CALIBRATE and Z_TILT_AUTODETECT extended G-Code commands. Z_TILT_CALIBRATE performs multiple probing runs to calculate z_offsets, enabling accurate tilt adjustment with fewer probe points. Z_TILT_AUTODETECT automatically determines pivot positions for each Z stepper through iterative probing. When this section is present, these extended commands become available, enhancing bed leveling accuracy and calibration efficiency.

    [z_tilt_ng]\n#z_positions:\n# See [z_tilt]. This parameter must be provided,\n#   unless the parameter \"extra_points\" is provided. In that case only\n#   the command Z_TILT_AUTODETECT can be run to automatically determine\n#   the z_positions. See 'extra_points' below.\n#z_offsets:\n#   A list of Z offsets for each z_position. The z_offset is added to each\n#   probed value during Z_TILT_ADJUST to offset for unevenness of the bed.\n#   This values can also be automatically detected by running\n#   Z_TILT_CALIBRATE. See \"extra_points\" below.\n#points:\n# See [z_tilt]\n#speed: 50\n# See [z_tilt]\n#horizontal_move_z: 5\n# See [z_tilt]\n#min_horizontal_move_z: 1.0\n# See [z_tilt]\n#adaptive_horizontal_move_z: False\n# See [z_tilt]\n#retries: 0\n# See [z_tilt]\n#retry_tolerance: 0\n# See [z_tilt]\n#increasing_threshold: 0.0000001\n# See [z_tilt]\n#use_probe_xy_offsets: False\n# See [z_tilt]\n#extra_points:\n#   A list in the same format as \"points\" above. This list contains\n#   additional points to be probed during the two calibration commands\n#   Z_TILT_CALIBRATE and Z_TILT_AUTODETECT. If the bed is not perfectly\n#   level, it is possible to specify more probing points with \"points\".\n#   In that Z_TILT_ADJUST will determine the best fit via a least squares\n#   algorithm. As this comes with additional overhead on each Z_TILT_ADJUST\n#   run, it is instead possible to move the additional probing points here,\n#   and use Z_TILT_CALIBRATE to find z_offsets to use for the probing points\n#   used in Z_TILT_ADJUST.\n#   The extra points are also used during T_ZILT_AUTODETECT. This command\n#   can determine the z_positions automatically by during several probings\n#   with intentionally tilted bed. It is currently only implemented for 3\n#   z steppers.\n#   Note that for both commands to work numpy has to be installed.\n#averaging_len: 3\n#   Z_TILT_CALIBRATE and Z_TILT_AUTODETECT both run repeatedly until the\n#   result can no longer be improved. To determine this, the probed values\n#   are averaged. The number of runs to average over is configured with this\n#   parameter.\n#autodetect_delta: 1.0\n#   The amount by which Z_TILT_AUTODETECT intentionally tilts the bed. Higher\n#   values yield better results, but can also lead to situations where the\n#   bed is tilted in a way that the nozzle touched the bed before the probe.\n#   The default is conservative.\n
    "},{"location":"Config_Reference.html#quad_gantry_level","title":"[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:

     ----------------\n |Z1          Z2|\n |  ---------   |\n |  |       |   |\n |  |       |   |\n |  x--------   |\n |Z           Z3|\n ----------------\n

    Where x is the 0, 0 point on the bed

    [quad_gantry_level]\n#gantry_corners:\n#   A newline separated list of X, Y coordinates describing the two\n#   opposing corners of the gantry. The first entry corresponds to Z,\n#   the second to Z2. This parameter must be provided.\n#points:\n#   A newline separated list of four X, Y points that should be probed\n#   during a QUAD_GANTRY_LEVEL command. Order of the locations is\n#   important, and should correspond to Z, Z1, Z2, and Z3 location in\n#   order. This parameter must be provided. For maximum accuracy,\n#   ensure your probe offsets are configured.\n#speed: 50\n#   The speed (in mm/s) of non-probing moves during the calibration.\n#   The default is 50.\n#horizontal_move_z: 5\n#   The height (in mm) that the head should be commanded to move to\n#   just prior to starting a probe operation. The default is 5.\n#min_horizontal_move_z: 1.0\n#   minimum value for horizontal move z\n#   (only used when adaptive_horizontal_move_z is True)\n#adaptive_horizontal_move_z: False\n#   if we should adjust horizontal move z after the first adjustment round,\n#   based on error.\n#   when set to True, initial horizontal_move_z is the config value,\n#   subsequent iterations will set horizontal_move_z to\n#   the ceil of error, or min_horizontal_move_z - whichever is greater.\n#max_adjust: 4\n#   Safety limit if an adjustment greater than this value is requested\n#   quad_gantry_level will abort.\n#retries: 0\n#   Number of times to retry if the probed points aren't within\n#   tolerance.\n#retry_tolerance: 0\n#   If retries are enabled then retry if largest and smallest probed\n#   points differ more than retry_tolerance.\n#increasing_threshold: 0.0000001\n#   Sets the threshold that probe points can increase before qgl aborts.\n#   To disable the validation, set this parameter to a high value.\n#use_probe_xy_offsets: False\n#   If True, apply the `[probe]` XY offsets to the probed positions. The\n#   default is False.\n
    "},{"location":"Config_Reference.html#skew_correction","title":"[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]\n
    "},{"location":"Config_Reference.html#z_thermal_adjust","title":"[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]\n#temp_coeff:\n#   The temperature coefficient of expansion, in mm/degC. For example, a\n#   temp_coeff of 0.01 mm/degC will move the Z axis downwards by 0.01 mm for\n#   every degree Celsius that the temperature sensor increases. Defaults to\n#   0.0 mm/degC, which applies no adjustment.\n#smooth_time:\n#   Smoothing window applied to the temperature sensor, in seconds. Can reduce\n#   motor noise from excessive small corrections in response to sensor noise.\n#   The default is 2.0 seconds.\n#z_adjust_off_above:\n#   Disables adjustments above this Z height [mm]. The last computed correction\n#   will remain applied until the toolhead moves below the specified Z height\n#   again. The default is 99999999.0 mm (always on).\n#max_z_adjustment:\n#   Maximum absolute adjustment that can be applied to the Z axis [mm]. The\n#   default is 99999999.0 mm (unlimited).\n#sensor_type:\n#sensor_pin:\n#min_temp:\n#max_temp:\n#   Temperature sensor configuration.\n#   See the \"extruder\" section for the definition of the above\n#   parameters.\n#gcode_id:\n#   See the \"heater_generic\" section for the definition of this\n#   parameter.\n
    "},{"location":"Config_Reference.html#customized-homing","title":"Customized homing","text":""},{"location":"Config_Reference.html#safe_z_home","title":"[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]\nhome_xy_position:\n#   A X, Y coordinate (e.g. 100, 100) where the Z homing should be\n#   performed. This parameter must be provided.\n#speed: 50.0\n#   Speed at which the toolhead is moved to the safe Z home\n#   coordinate. The default is 50 mm/s\n#z_hop:\n#   Distance (in mm) to lift the Z axis prior to homing. This is\n#   applied to any homing command, even if it doesn't home the Z axis.\n#   If the Z axis is already homed and the current Z position is less\n#   than z_hop, then this will lift the head to a height of z_hop. If\n#   the Z axis is not already homed the head is lifted by z_hop.\n#   The default is to not implement Z hop.\n#z_hop_speed: 15.0\n#   Speed (in mm/s) at which the Z axis is lifted prior to homing. The\n#   default is 15 mm/s.\n#move_to_previous: False\n#   When set to True, the X and Y axes are reset to their previous\n#   positions after Z axis homing. The default is False.\n#home_y_before_x: False\n#  # If True, the Y axis will home first. The default is False.\n
    "},{"location":"Config_Reference.html#homing_override","title":"[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]\ngcode:\n#   A list of G-Code commands to execute in place of G28 commands\n#   found in the normal g-code input. See docs/Command_Templates.md\n#   for G-Code format. If a G28 is contained in this list of commands\n#   then it will invoke the normal homing procedure for the printer.\n#   The commands listed here must home all axes. This parameter must\n#   be provided.\n#axes: xyz\n#   The axes to override. For example, if this is set to \"z\" then the\n#   override script will only be run when the z axis is homed (eg, via\n#   a \"G28\" or \"G28 Z0\" command). Note, the override script should\n#   still home all axes. The default is \"xyz\" which causes the\n#   override script to be run in place of all G28 commands.\n#set_position_x:\n#set_position_y:\n#set_position_z:\n#   If specified, the printer will assume the axis is at the specified\n#   position prior to running the above g-code commands. Setting this\n#   disables homing checks for that axis. This may be useful if the\n#   head must move prior to invoking the normal G28 mechanism for an\n#   axis. The default is to not force a position for an axis.\n
    "},{"location":"Config_Reference.html#endstop_phase","title":"[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]\n#endstop_accuracy:\n#   Sets the expected accuracy (in mm) of the endstop. This represents\n#   the maximum error distance the endstop may trigger (eg, if an\n#   endstop may occasionally trigger 100um early or up to 100um late\n#   then set this to 0.200 for 200um). The default is\n#   4*rotation_distance/full_steps_per_rotation.\n#trigger_phase:\n#   This specifies the phase of the stepper motor driver to expect\n#   when hitting the endstop. It is composed of two numbers separated\n#   by a forward slash character - the phase and the total number of\n#   phases (eg, \"7/64\"). Only set this value if one is sure the\n#   stepper motor driver is reset every time the mcu is reset. If this\n#   is not set, then the stepper phase will be detected on the first\n#   home and that phase will be used on all subsequent homes.\n#endstop_align_zero: False\n#   If true then the position_endstop of the axis will effectively be\n#   modified so that the zero position for the axis occurs at a full\n#   step on the stepper motor. (If used on the Z axis and the print\n#   layer height is a multiple of a full step distance then every\n#   layer will occur on a full step.) The default is False.\n
    "},{"location":"Config_Reference.html#g-code-macros-and-events","title":"G-Code macros and events","text":""},{"location":"Config_Reference.html#gcode_macro","title":"[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]\n#gcode:\n#   A list of G-Code commands to execute in place of \"my_cmd\". See\n#   docs/Command_Templates.md for G-Code format. This parameter must\n#   be provided.\n#variable_<name>:\n#   One may specify any number of options with a \"variable_\" prefix.\n#   The given variable name will be assigned the given value (parsed\n#   as a Python literal) and will be available during macro expansion.\n#   For example, a config with \"variable_fan_speed = 75\" might have\n#   gcode commands containing \"M106 S{ fan_speed * 255 }\". Variables\n#   can be changed at run-time using the SET_GCODE_VARIABLE command\n#   (see docs/Command_Templates.md for details). Variable names may\n#   not use upper case characters.\n#rename_existing:\n#   This option will cause the macro to override an existing G-Code\n#   command and provide the previous definition of the command via the\n#   name provided here. This can be used to override builtin G-Code\n#   commands. Care should be taken when overriding commands as it can\n#   cause complex and unexpected results. The default is to not\n#   override an existing G-Code command.\n#description: G-Code macro\n#   This will add a short description used at the HELP command or while\n#   using the auto completion feature. Default \"G-Code macro\"\n
    "},{"location":"Config_Reference.html#delayed_gcode","title":"[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]\ngcode:\n#   A list of G-Code commands to execute when the delay duration has\n#   elapsed. G-Code templates are supported. This parameter must be\n#   provided.\n#initial_duration: 0.0\n#   The duration of the initial delay (in seconds). If set to a\n#   non-zero value the delayed_gcode will execute the specified number\n#   of seconds after the printer enters the \"ready\" state. This can be\n#   useful for initialization procedures or a repeating delayed_gcode.\n#   If set to 0 the delayed_gcode will not execute on startup.\n#   Default is 0.\n
    "},{"location":"Config_Reference.html#save_variables","title":"[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]\nfilename:\n#   Required - provide a filename that would be used to save the\n#   variables to disk e.g. ~/variables.cfg\n
    "},{"location":"Config_Reference.html#idle_timeout","title":"[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]\n#gcode:\n#   A list of G-Code commands to execute on an idle timeout. See\n#   docs/Command_Templates.md for G-Code format. The default is to run\n#   \"TURN_OFF_HEATERS\" and \"M84\".\n#timeout: 600\n#   Idle time (in seconds) to wait before running the above G-Code\n#   commands. Set it to 0 to disable the timeout feature.\n#   The default is 600 seconds.\n
    "},{"location":"Config_Reference.html#optional-g-code-features","title":"Optional G-Code features","text":""},{"location":"Config_Reference.html#virtual_sdcard","title":"[virtual_sdcard]","text":"

    A virtual sdcard may be useful if the host machine is not fast enough to run OctoPrint well. It allows the Kalico host software to directly print gcode files stored in a directory on the host using standard sdcard G-Code commands (eg, M24).

    [virtual_sdcard]\npath:\n#   The path of the local directory on the host machine to look for\n#   g-code files. This is a read-only directory (sdcard file writes\n#   are not supported). One may point this to OctoPrint's upload\n#   directory (generally ~/.octoprint/uploads/ ). This parameter must\n#   be provided.\n#on_error_gcode:\n#   A list of G-Code commands to execute when an error is reported.\n#   See docs/Command_Templates.md for G-Code format. The default is to\n#   run TURN_OFF_HEATERS.\n#with_subdirs: False\n#   Enable scanning of subdirectories for the menu and for the\n#   M20 and M23 commands. The default is False.\n
    "},{"location":"Config_Reference.html#sdcard_loop","title":"[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]\n
    "},{"location":"Config_Reference.html#force_move","title":"\u26a0\ufe0f [force_move]","text":"

    This module is enabled by default in Kalico!

    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]\n#enable_force_move: True\n#   Set to `True` to enable FORCE_MOVE and SET_KINEMATIC_POSITION\n#   extended G-Code commands. The default is `True`.\n
    "},{"location":"Config_Reference.html#pause_resume","title":"[pause_resume]","text":"

    Pause/Resume functionality with support of position capture and restore. See the command reference for more information.

    [pause_resume]\n#recover_velocity: 50.\n#   When capture/restore is enabled, the speed at which to return to\n#   the captured position (in mm/s). Default is 50.0 mm/s.\n
    "},{"location":"Config_Reference.html#firmware_retraction","title":"[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]\n#retract_length: 0.0\n#   The length of filament (in mm) to retract when a G10 command is\n#   executed. When a G11 command is executed, the unretract_length\n#   is the sum of the retract_length and the unretract_extra_length\n#   (see below). The minimum value and default are 0 mm, which\n#   disables firmware retraction.\n#retract_speed: 20.0\n#   The speed of filament retraction moves (in mm/s).\n#   This value is typically set relatively high (>40 mm/s),\n#   except for soft and/oozy filaments like TPU and PETG\n#   (20 to 30 mm/s). The minimum value is 1 mm/s, the default value\n#   is 20 mm/s.\n#unretract_extra_length: 0.0\n#   The *additional* length (in mm) to add or the length to subtract\n#   from the filament move when unretracting compared to the retract\n#   move length. This allows priming the nozzle (positive extra length)\n#   or delaying extrusion after unretracting (negative length). The\n#   latter may help reduce blobbing. The minimum value is -1 mm\n#   (2.41 mm3 volume for 1.75 mm filament), the default value is 0 mm.\n#unretract_speed: 10.0\n#   The speed of filament unretraction moves (in mm/s).\n#   This parameter is not particularly critical, although often lower\n#   than retract_speed. The minimum value is 1 mm/s, the default value\n#   is 10 mm/s.\n#z_hop_height: 0.0\n#   The vertical height by which the nozzle is lifted from the print to\n#   prevent collisions with the print during travel moves when retracted.\n#   The minimum value is 0 mm, the default value is 0 mm, which disables\n#   zhop moves. The value will be reduced if the zhop move reaches\n#   maximum z.\n#clear_zhop_on_z_moves: False\n#   If True, when a change in Z is sent while toolhead is retracted,\n#   z_hop is cancelled until next retraction. Otherwise,\n#   `z_hop_height` is applied as an offset to all movements.\n
    "},{"location":"Config_Reference.html#gcode_arcs","title":"[gcode_arcs]","text":"

    Support for gcode arc (G2/G3) commands.

    [gcode_arcs]\n#resolution: 1.0\n#   An arc will be split into segments. Each segment's length will\n#   equal the resolution in mm set above. Lower values will produce a\n#   finer arc, but also more work for your machine. Arcs smaller than\n#   the configured value will become straight lines. The default is\n#   1mm.\n
    "},{"location":"Config_Reference.html#respond","title":"[respond]","text":"

    This module is enabled by default in Kalico!

    Enable the \"M118\" and \"RESPOND\" extended commands.

    [respond]\n#default_type: echo\n#   Sets the default prefix of the \"M118\" and \"RESPOND\" output to one\n#   of the following:\n#       echo: \"echo: \" (This is the default)\n#       command: \"// \"\n#       error: \"!! \"\n#default_prefix: echo:\n#   Directly sets the default prefix. If present, this value will\n#   override the \"default_type\".\n#enable_respond: True\n#   Set to `True` to enable M118 and RESPOND\n#   extended G-Code commands. The default is `True`.\n
    "},{"location":"Config_Reference.html#exclude_object","title":"[exclude_object]","text":"

    This module is enabled by default in Kalico!

    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]\n#enable_exclude_object: True\n#   Set to `True` to enable `EXCLUDE_OBJECT_*` extended G-Code commands.\n#   The default is `True`.\n
    "},{"location":"Config_Reference.html#resonance-compensation","title":"Resonance compensation","text":""},{"location":"Config_Reference.html#input_shaper","title":"[input_shaper]","text":"

    Enables resonance compensation. Also see the command reference.

    [input_shaper]\n#shaper_freq_x: 0\n#   A frequency (in Hz) of the input shaper for X axis. This is\n#   usually a resonance frequency of X axis that the input shaper\n#   should suppress. For more complex shapers, like 2- and 3-hump EI\n#   input shapers, this parameter can be set from different\n#   considerations. The default value is 0, which disables input\n#   shaping for X axis.\n#shaper_freq_y: 0\n#   A frequency (in Hz) of the input shaper for Y axis. This is\n#   usually a resonance frequency of Y axis that the input shaper\n#   should suppress. For more complex shapers, like 2- and 3-hump EI\n#   input shapers, this parameter can be set from different\n#   considerations. The default value is 0, which disables input\n#   shaping for Y axis.\n#shaper_type: mzv\n#   A type of the input shaper to use for both X and Y axes. Supported\n#   shapers are zv, mzv, zvd, ei, 2hump_ei, and 3hump_ei. The default\n#   is mzv input shaper.\n#shaper_type_x:\n#shaper_type_y:\n#   If shaper_type is not set, these two parameters can be used to\n#   configure different input shapers for X and Y axes. The same\n#   values are supported as for shaper_type parameter.\n#damping_ratio_x: 0.1\n#damping_ratio_y: 0.1\n#   Damping ratios of vibrations of X and Y axes used by input shapers\n#   to improve vibration suppression. Default value is 0.1 which is a\n#   good all-round value for most printers. In most circumstances this\n#   parameter requires no tuning and should not be changed.\n
    "},{"location":"Config_Reference.html#adxl345","title":"[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]\ncs_pin:\n#   The SPI enable pin for the sensor. This parameter must be provided.\n#spi_speed: 5000000\n#   The SPI speed (in hz) to use when communicating with the chip.\n#   The default is 5000000.\n#spi_bus:\n#spi_software_sclk_pin:\n#spi_software_mosi_pin:\n#spi_software_miso_pin:\n#   See the \"common SPI settings\" section for a description of the\n#   above parameters.\n#axes_map: x, y, z\n#   The accelerometer axis for each of the printer's X, Y, and Z axes.\n#   This may be useful if the accelerometer is mounted in an\n#   orientation that does not match the printer orientation. For\n#   example, one could set this to \"y, x, z\" to swap the X and Y axes.\n#   It is also possible to negate an axis if the accelerometer\n#   direction is reversed (eg, \"x, z, -y\"). The default is \"x, y, z\".\n#rate: 3200\n#   Output data rate for ADXL345. ADXL345 supports the following data\n#   rates: 3200, 1600, 800, 400, 200, 100, 50, and 25. Note that it is\n#   not recommended to change this rate from the default 3200, and\n#   rates below 800 will considerably affect the quality of resonance\n#   measurements.\n
    "},{"location":"Config_Reference.html#lis2dw","title":"[lis2dw]","text":"

    Support for LIS2DW accelerometers.

    [lis2dw]\n#cs_pin:\n#   The SPI enable pin for the sensor. This parameter must be provided\n#   if using SPI.\n#spi_speed: 5000000\n#   The SPI speed (in hz) to use when communicating with the chip.\n#   The default is 5000000.\n#spi_bus:\n#spi_software_sclk_pin:\n#spi_software_mosi_pin:\n#spi_software_miso_pin:\n#   See the \"common SPI settings\" section for a description of the\n#   above parameters.\n#i2c_address:\n#   Default is 25 (0x19). If SA0 is high, it would be 24 (0x18) instead.\n#i2c_mcu:\n#i2c_bus:\n#i2c_software_scl_pin:\n#i2c_software_sda_pin:\n#i2c_speed: 400000\n#   See the \"common I2C settings\" section for a description of the\n#   above parameters. The default \"i2c_speed\" is 400000.\n#axes_map: x, y, z\n#   See the \"adxl345\" section for information on this parameter.\n
    "},{"location":"Config_Reference.html#lis3dh","title":"[lis3dh]","text":"

    Support for LIS3DH accelerometers.

    [lis3dh]\n#cs_pin:\n#   The SPI enable pin for the sensor. This parameter must be provided\n#   if using SPI.\n#spi_speed: 5000000\n#   The SPI speed (in hz) to use when communicating with the chip.\n#   The default is 5000000.\n#spi_bus:\n#spi_software_sclk_pin:\n#spi_software_mosi_pin:\n#spi_software_miso_pin:\n#   See the \"common SPI settings\" section for a description of the\n#   above parameters.\n#i2c_address:\n#   Default is 25 (0x19). If SA0 is high, it would be 24 (0x18) instead.\n#i2c_mcu:\n#i2c_bus:\n#i2c_software_scl_pin:\n#i2c_software_sda_pin:\n#i2c_speed: 400000\n#   See the \"common I2C settings\" section for a description of the\n#   above parameters. The default \"i2c_speed\" is 400000.\n#axes_map: x, y, z\n#   See the \"adxl345\" section for information on this parameter.\n
    "},{"location":"Config_Reference.html#mpu9250","title":"[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]\n#i2c_address:\n#   Default is 104 (0x68). If AD0 is high, it would be 0x69 instead.\n#i2c_mcu:\n#i2c_bus:\n#i2c_software_scl_pin:\n#i2c_software_sda_pin:\n#i2c_speed: 400000\n#   See the \"common I2C settings\" section for a description of the\n#   above parameters. The default \"i2c_speed\" is 400000.\n#axes_map: x, y, z\n#   See the \"adxl345\" section for information on this parameter.\n
    "},{"location":"Config_Reference.html#resonance_tester","title":"[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]\n#probe_points:\n#   A list of X, Y, Z coordinates of points (one point per line) to test\n#   resonances at. At least one point is required. Make sure that all\n#   points with some safety margin in XY plane (~a few centimeters)\n#   are reachable by the toolhead.\n#accel_chip:\n#   A name of the accelerometer chip to use for measurements. If\n#   adxl345 chip was defined without an explicit name, this parameter\n#   can simply reference it as \"accel_chip: adxl345\", otherwise an\n#   explicit name must be supplied as well, e.g. \"accel_chip: adxl345\n#   my_chip_name\". Either this, or the next two parameters must be\n#   set.\n#accel_chip_x:\n#accel_chip_y:\n#   Names of the accelerometer chips to use for measurements for each\n#   of the axis. Can be useful, for instance, on bed slinger printer,\n#   if two separate accelerometers are mounted on the bed (for Y axis)\n#   and on the toolhead (for X axis). These parameters have the same\n#   format as 'accel_chip' parameter. Only 'accel_chip' or these two\n#   parameters must be provided.\n#max_smoothing:\n#   Maximum input shaper smoothing to allow for each axis during shaper\n#   auto-calibration (with 'SHAPER_CALIBRATE' command). By default no\n#   maximum smoothing is specified. Refer to Measuring_Resonances guide\n#   for more details on using this feature.\n#move_speed: 50\n#   The speed (in mm/s) to move the toolhead to and between test points\n#   during the calibration. The default is 50.\n#min_freq: 5\n#   Minimum frequency to test for resonances. The default is 5 Hz.\n#max_freq: 133.33\n#   Maximum frequency to test for resonances. The default is 133.33 Hz.\n#accel_per_hz: 75\n#   This parameter is used to determine which acceleration to use to\n#   test a specific frequency: accel = accel_per_hz * freq. Higher the\n#   value, the higher is the energy of the oscillations. Can be set to\n#   a lower than the default value if the resonances get too strong on\n#   the printer. However, lower values make measurements of\n#   high-frequency resonances less precise. The default value is 75\n#   (mm/sec).\n#   Set it to 60 as a good baseline when using the sweeping resonance tester.\n#hz_per_sec: 1\n#   Determines the speed of the test. When testing all frequencies in\n#   range [min_freq, max_freq], each second the frequency increases by\n#   hz_per_sec. Small values make the test slow, and the large values\n#   will decrease the precision of the test. The default value is 1.0\n#   (Hz/sec == sec^-2).\n#sweeping_accel: 400\n#   An acceleration of slow sweeping moves. The default is 400 mm/sec^2.\n#sweeping_period: 0\n#   A period of slow sweeping moves. Avoid setting it to a too small\n#   non-zero value in order to not poison the measurements.\n#   To enable it, start by setting it to 1.2 sec which is a good all-round\n#   choice. Set it to 0 do disable it. The default is 0.\n
    "},{"location":"Config_Reference.html#config-file-helpers","title":"Config file helpers","text":""},{"location":"Config_Reference.html#board_pins","title":"[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]\nmcu: mcu\n#   A comma separated list of micro-controllers that may use the\n#   aliases. The default is to apply the aliases to the main \"mcu\".\naliases:\naliases_<name>:\n#   A comma separated list of \"name=value\" aliases to create for the\n#   given micro-controller. For example, \"EXP1_1=PE6\" would create an\n#   \"EXP1_1\" alias for the \"PE6\" pin. However, if \"value\" is enclosed\n#   in \"<>\" then \"name\" is created as a reserved pin (for example,\n#   \"EXP1_9=<GND>\" would reserve \"EXP1_9\"). Any number of options\n#   starting with \"aliases_\" may be specified.\n
    "},{"location":"Config_Reference.html#include","title":"[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\", or \"configs/**/*.cfg\" if using python version >=3.5).

    [include my_other_config.cfg]\n
    "},{"location":"Config_Reference.html#duplicate_pin_override","title":"[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 Kalico supports using the same pin multiple times, and using this override may cause confusing and unexpected results. One may specify an explicit name (eg, [duplicate_pin_override my_name]) to define multiple instances of it.

    [duplicate_pin_override]\npins:\n#   A comma separated list of pins that may be used multiple times in\n#   a config file without normal error checks. This parameter must be\n#   provided.\n
    "},{"location":"Config_Reference.html#bed-probing-hardware","title":"Bed probing hardware","text":""},{"location":"Config_Reference.html#probe","title":"[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]\npin:\n#   Probe detection pin. If the pin is on a different microcontroller\n#   than the Z steppers then it enables \"multi-mcu homing\". This\n#   parameter must be provided.\n#deactivate_on_each_sample: True\n#   This determines if Kalico should execute deactivation gcode\n#   between each probe attempt when performing a multiple probe\n#   sequence. The default is True.\n#x_offset: 0.0\n#   The distance (in mm) between the probe and the nozzle along the\n#   x-axis. The default is 0.\n#y_offset: 0.0\n#   The distance (in mm) between the probe and the nozzle along the\n#   y-axis. The default is 0.\nz_offset:\n#   The distance (in mm) between the bed and the nozzle when the probe\n#   triggers. This parameter must be provided.\n#speed: 5.0\n#   Speed (in mm/s) of the Z axis when probing. The default is 5mm/s.\n#samples: 1\n#   The number of times to probe each point. The probed z-values will\n#   be averaged. The default is to probe 1 time.\n#sample_retract_dist: 2.0\n#   The distance (in mm) to lift the toolhead between each sample (if\n#   sampling more than once). The default is 2mm.\n#lift_speed:\n#   Speed (in mm/s) of the Z axis when lifting the probe between\n#   samples. The default is to use the same value as the 'speed'\n#   parameter.\n#samples_result: average\n#   The calculation method when sampling more than once - either\n#   \"median\" or \"average\". The default is average.\n#samples_tolerance: 0.100\n#   The maximum Z distance (in mm) that a sample may differ from other\n#   samples. If this tolerance is exceeded then either an error is\n#   reported or the attempt is restarted (see\n#   samples_tolerance_retries). The default is 0.100mm.\n#samples_tolerance_retries: 0\n#   The number of times to retry if a sample is found that exceeds\n#   samples_tolerance. On a retry, all current samples are discarded\n#   and the probe attempt is restarted. If a valid set of samples are\n#   not obtained in the given number of retries then an error is\n#   reported. The default is zero which causes an error to be reported\n#   on the first sample that exceeds samples_tolerance.\n#activate_gcode:\n#   A list of G-Code commands to execute prior to each probe attempt.\n#   See docs/Command_Templates.md for G-Code format. This may be\n#   useful if the probe needs to be activated in some way. Do not\n#   issue any commands here that move the toolhead (eg, G1). The\n#   default is to not run any special G-Code commands on activation.\n#deactivate_gcode:\n#   A list of G-Code commands to execute after each probe attempt\n#   completes. See docs/Command_Templates.md for G-Code format. Do not\n#   issue any commands here that move the toolhead. The default is to\n#   not run any special G-Code commands on deactivation.\n#drop_first_result: False\n#   Set to `True` will probe one extra time and remove the first\n#   sample from calculation. This can improve probe accuracy for\n#   printers that have an outlier first sample.\n
    "},{"location":"Config_Reference.html#bltouch","title":"[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]\nsensor_pin:\n#   Pin connected to the BLTouch sensor pin. Most BLTouch devices\n#   require a pullup on the sensor pin (prefix the pin name with \"^\").\n#   This parameter must be provided.\ncontrol_pin:\n#   Pin connected to the BLTouch control pin. This parameter must be\n#   provided.\n#pin_move_time: 0.680\n#   The amount of time (in seconds) to wait for the BLTouch pin to\n#   move up or down. The default is 0.680 seconds.\n#stow_on_each_sample: True\n#   This determines if Kalico should command the pin to move up\n#   between each probe attempt when performing a multiple probe\n#   sequence. Read the directions in docs/BLTouch.md before setting\n#   this to False. The default is True.\n#probe_with_touch_mode: False\n#   If this is set to True then Kalico will probe with the device in\n#   \"touch_mode\". The default is False (probing in \"pin_down\" mode).\n#pin_up_reports_not_triggered: True\n#   Set if the BLTouch consistently reports the probe in a \"not\n#   triggered\" state after a successful \"pin_up\" command. This should\n#   be True for all genuine BLTouch devices. Read the directions in\n#   docs/BLTouch.md before setting this to False. The default is True.\n#pin_up_touch_mode_reports_triggered: True\n#   Set if the BLTouch consistently reports a \"triggered\" state after\n#   the commands \"pin_up\" followed by \"touch_mode\". This should be\n#   True for all genuine BLTouch devices. Read the directions in\n#   docs/BLTouch.md before setting this to False. The default is True.\n#set_output_mode:\n#   Request a specific sensor pin output mode on the BLTouch V3.0 (and\n#   later). This setting should not be used on other types of probes.\n#   Set to \"5V\" to request a sensor pin output of 5 Volts (only use if\n#   the controller board needs 5V mode and is 5V tolerant on its input\n#   signal line). Set to \"OD\" to request the sensor pin output use\n#   open drain mode. The default is to not request an output mode.\n#x_offset:\n#y_offset:\n#z_offset:\n#speed:\n#lift_speed:\n#samples:\n#sample_retract_dist:\n#samples_result:\n#samples_tolerance:\n#samples_tolerance_retries:\n#   See the \"probe\" section for information on these parameters.\n
    "},{"location":"Config_Reference.html#dockable_probe","title":"[dockable_probe]","text":"

    Certain probes are magnetically coupled to the toolhead and stowed in a dock when not in use. One should define this section instead of a probe section if the probe uses magnets to attach and a dock for storage. See Dockable Probe Guide for more detailed information regarding configuration and setup.

    [dockable_probe]\ndock_position: 0,0,0\n#   The physical position of the probe dock relative to the origin of\n#   the bed. The coordinates are specified as a comma separated X, Y, Z\n#   list of values. Certain dock designs are independent of the Z axis.\n#   If Z is specified the toolhead will move to the Z location before the X, Y\n#   coordinates.\n#   This parameter is required.\napproach_position: 0,0,0\n#   The X, Y, Z position where the toolhead needs to be prior to moving into the\n#   dock so that the probe is aligned properly for attaching or detaching.\n#   If Z is specified the toolhead will move to the Z location before the X, Y\n#   coordinates.\n#   This parameter is required.\ndetach_position: 0,0,0\n#   Similar to the approach_position, the detach_position is the coordinates\n#   where the toolhead is moved after the probe has been docked.\n#   For magnetically coupled probes, this is typically perpendicular to\n#   the approach_position in a direction that does not cause the tool to\n#   collide with the printer.\n#   If Z is specified the toolhead will move to the Z location before the X, Y\n#   coordinates.\n#   This parameter is required.\n#extract_position: 0,0,0\n#   Similar to the approach_position, the extract_position is the coordinates\n#   where the toolhead is moved to extract the probe from the dock.\n#   If Z is specified the toolhead will move to the Z location before the X, Y\n#   coordinates.\n#   The default value is approach_probe value.\n#insert_position: 0,0,0\n#   Similar to the extract_position, the insert_position is the coordinates\n#   where the toolhead is moved before inserting the probe into the dock.\n#   If Z is specified the toolhead will move to the Z location before the X, Y\n#   coordinates.\n#   The default value is extract_probe value.\n#safe_dock_distance :\n#   This setting defines a security area around dock during ATTACH/DETACH_PROBE\n#   commands. While inside the area, the toolhead move away prior to reach the\n#   approach or insert position.\n#   Default is the smallest distance to the dock of approach, detach, insert\n#   position. It could be only lower than the Default value.\n#safe_position : approach_position\n#   A safe position to ensure MOVE_AVOIDING_DOCK travel does not move the\n#   toolhead out of range.\n#z_hop: 15.0\n#   Distance (in mm) to lift the Z axis prior to attaching/detaching the probe.\n#   If the Z axis is already homed and the current Z position is less\n#   than `z_hop`, then this will lift the head to a height of `z_hop`. If\n#   the Z axis is not already homed the head is lifted by `z_hop`.\n#   The default is to not implement Z hop.\n#restore_toolhead: True\n#   While True, the position of the toolhead is restored to the position prior\n#   to the attach/detach movements.\n#   The default value is True.\n#dock_retries:\n#   The number of times to attempt to attach/dock the probe before raising\n#   an error and aborting probing.\n#   The default is 0.\n#auto_attach_detach: False\n#   Enable/Disable the automatic attaching/detaching of the probe during\n#   actions that require the probe.\n#   The default is True.\n#attach_speed:\n#detach_speed:\n#travel_speed:\n#   Optional speeds used during moves.\n#   The default is to use `speed` of `probe` or 5.0.\n#check_open_attach:\n#   The probe status should be verified prior to homing. Setting this option\n#   to true will check the probe \"endstop\" is \"open\" after attaching and\n#   will abort probing if not, also checking for \"triggered\" after docking.\n#   Conversively, setting this to false, the probe should read \"triggered\"\n#   after attaching and \"open\" after docking. If not, probing will abort.\n#probe_sense_pin:\n#   This supplemental pin can be defined to determine an attached state\n#   instead of check_open_attach.\n#dock_sense_pin:\n#   This supplemental pin can be defined to determine a docked state in\n#   addition to probe_sense_pin or check_open_attach.\n#x_offset:\n#y_offset:\n#z_offset:\n#lift_speed:\n#speed:\n#samples:\n#sample_retract_dist:\n#samples_result:\n#samples_tolerance:\n#samples_tolerance_retries:\n#activate_gcode:\n#deactivate_gcode:\n#   See the \"probe\" section for information on these parameters.\n
    "},{"location":"Config_Reference.html#smart_effector","title":"[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]\npin:\n#   Pin connected to the Smart Effector Z Probe output pin (pin 5). Note that\n#   pullup resistor on the board is generally not required. However, if the\n#   output pin is connected to the board pin with a pullup resistor, that\n#   resistor must be high value (e.g. 10K Ohm or more). Some boards have a low\n#   value pullup resistor on the Z probe input, which will likely result in an\n#   always-triggered probe state. In this case, connect the Smart Effector to\n#   a different pin on the board. This parameter is required.\n#control_pin:\n#   Pin connected to the Smart Effector control input pin (pin 7). If provided,\n#   Smart Effector sensitivity programming commands become available.\n#probe_accel:\n#   If set, limits the acceleration of the probing moves (in mm/sec^2).\n#   A sudden large acceleration at the beginning of the probing move may\n#   cause spurious probe triggering, especially if the hotend is heavy.\n#   To prevent that, it may be necessary to reduce the acceleration of\n#   the probing moves via this parameter.\n#recovery_time: 0.4\n#   A delay between the travel moves and the probing moves in seconds. A fast\n#   travel move prior to probing may result in a spurious probe triggering.\n#   This may cause 'Probe triggered prior to movement' errors if no delay\n#   is set. Value 0 disables the recovery delay.\n#   Default value is 0.4.\n#x_offset:\n#y_offset:\n#   Should be left unset (or set to 0).\nz_offset:\n#   Trigger height of the probe. Start with -0.1 (mm), and adjust later using\n#   `PROBE_CALIBRATE` command. This parameter must be provided.\n#speed:\n#   Speed (in mm/s) of the Z axis when probing. It is recommended to start\n#   with the probing speed of 20 mm/s and adjust it as necessary to improve\n#   the accuracy and repeatability of the probe triggering.\n#samples:\n#sample_retract_dist:\n#samples_result:\n#samples_tolerance:\n#samples_tolerance_retries:\n#activate_gcode:\n#deactivate_gcode:\n#deactivate_on_each_sample:\n#   See the \"probe\" section for more information on the parameters above.\n
    "},{"location":"Config_Reference.html#probe_eddy_current","title":"[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]\nsensor_type: ldc1612\n#   The sensor chip used to perform eddy current measurements. This\n#   parameter must be provided and must be set to ldc1612.\n#intb_pin:\n#   MCU gpio pin connected to the ldc1612 sensor's INTB pin (if\n#   available). The default is to not use the INTB pin.\n#z_offset:\n#   The nominal distance (in mm) between the nozzle and bed that a\n#   probing attempt should stop at. This parameter must be provided.\n#i2c_address:\n#i2c_mcu:\n#i2c_bus:\n#i2c_software_scl_pin:\n#i2c_software_sda_pin:\n#i2c_speed:\n#   The i2c settings for the sensor chip. See the \"common I2C\n#   settings\" section for a description of the above parameters.\n#x_offset:\n#y_offset:\n#speed:\n#lift_speed:\n#samples:\n#sample_retract_dist:\n#samples_result:\n#samples_tolerance:\n#samples_tolerance_retries:\n#   See the \"probe\" section for information on these parameters.\n
    "},{"location":"Config_Reference.html#axis_twist_compensation","title":"[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]\n#speed: 50\n#   The speed (in mm/s) of non-probing moves during the calibration.\n#   The default is 50.\n#horizontal_move_z: 5\n#   The height (in mm) that the head should be commanded to move to\n#   just prior to starting a probe operation. The default is 5.\ncalibrate_start_x: 20\n#   Defines the minimum X coordinate of the calibration\n#   This should be the X coordinate that positions the nozzle at the starting\n#   calibration position.\ncalibrate_end_x: 200\n#   Defines the maximum X coordinate of the calibration\n#   This should be the X coordinate that positions the nozzle at the ending\n#   calibration position.\ncalibrate_y: 112.5\n#   Defines the Y coordinate of the calibration\n#   This should be the Y coordinate that positions the nozzle during the\n#   calibration process. This parameter is recommended to\n#   be near the center of the bed\n\n# For Y-axis twist compensation, specify the following parameters:\ncalibrate_start_y: ...\n#   Defines the minimum Y coordinate of the calibration\n#   This should be the Y coordinate that positions the nozzle at the starting\n#   calibration position for the Y axis. This parameter must be provided if\n#   compensating for Y axis twist.\ncalibrate_end_y: ...\n#   Defines the maximum Y coordinate of the calibration\n#   This should be the Y coordinate that positions the nozzle at the ending\n#   calibration position for the Y axis. This parameter must be provided if\n#   compensating for Y axis twist.\ncalibrate_x: ...\n#   Defines the X coordinate of the calibration for Y axis twist compensation\n#   This should be the X coordinate that positions the nozzle during the\n#   calibration process for Y axis twist compensation. This parameter must be\n#   provided and is recommended to be near the center of the bed.\n
    "},{"location":"Config_Reference.html#z_calibration","title":"\u26a0\ufe0f [z_calibration]","text":"

    Automatic Z offset calibration. One may define this section if the printer is able to calibrate the nozzle's offset automatically. See Z-Calibration guide for further information.

    [z_calibration]\nnozzle_xy_position:\n#   A X, Y coordinate (e.g. 100,100) of the nozzle, clicking on the Z endstop.\nswitch_xy_position:\n#   A X, Y coordinate (e.g. 100,100) of the probe's switch body, clicking on\n#   the Z endstop.\nbed_xy_position: default from relative_reference_index of bed_mesh\n#   a X, Y coordinate (e.g. 100,100) where the print surface (e.g. the center\n#   point) is probed. These coordinates will be adapted by the\n#   probe's X and Y offsets. The default is the relative_reference_index\n#   of the configured bed_mesh, if configured. It's possible to change the relative\n#   reference index at runtime or use the GCode argument BED_POSITION of CALIBRATE_Z.\nswitch_offset:\n#   The trigger point offset of the used mag-probe switch.\n#   Larger values will position the nozzle closer to the bed.\n#   This needs to be find out manually. More on this later\n#   in this section..\nmax_deviation: 1.0\n#   The maximum allowed deviation of the calculated offset.\n#   If the offset exceeds this value, it will stop!\n#   The default is 1.0 mm.\nsamples: default from \"probe:samples\" section\n#   The number of times to probe each point. The probed z-values\n#   will be averaged. The default is from the probe's configuration.\nsamples_tolerance: default from \"probe:samples_tolerance\" section\n#   The maximum Z distance (in mm) that a sample may differ from other\n#   samples. The default is from the probe's configuration.\nsamples_tolerance_retries: default from \"probe:samples_tolerance_retries\" section\n#   The number of times to retry if a sample is found that exceeds\n#   samples_tolerance. The default is from the probe's configuration.\nsamples_result: default from \"probe:samples_result\" section\n#   The calculation method when sampling more than once - either\n#   \"median\" or \"average\". The default is from the probe's configuration.\nclearance: 2 * z_offset from the \"probe:z_offset\" section\n#   The distance in mm to move up before moving to the next\n#   position. The default is two times the z_offset from the probe's\n#   configuration.\nposition_min: default from \"stepper_z:position_min\" section.\n#   Minimum valid distance (in mm) used for probing move. The\n#   default is from the Z rail configuration.\nspeed: 50\n#   The moving speed in X and Y. The default is 50 mm/s.\nlift_speed: default from \"probe:lift_speed\" section\n#   Speed (in mm/s) of the Z axis when lifting the probe between\n#   samples and clearance moves. The default is from the probe's\n#   configuration.\nprobing_speed: default from \"stepper_z:homing_speed\" section.\n#   The fast probing speed (in mm/s) used, when probing_first_fast\n#   is activated. The default is from the Z rail configuration.\nprobing_second_speed: default from \"stepper_z:second_homing_speed\" section.\n#   The slower speed (in mm/s) for probing the recorded samples.\n#   The default is second_homing_speed of the Z rail configuration.\nprobing_retract_dist: default from \"stepper_z:homing_retract_dist\" section.\n#   Distance to retract (in mm) before probing the next sample.\n#   The default is homing_retract_dist from the Z rail configuration.\nprobing_first_fast: false\n#   If true, the first probing is done faster by the probing speed.\n#   This is to get faster down and the result is not recorded as a\n#   probing sample. The default is false.\nstart_gcode:\n#   A list of G-Code commands to execute prior to each calibration command.\n#   See docs/Command_Templates.md for G-Code format. This can be used to\n#   attach the probe.\nbefore_switch_gcode:\n#   A list of G-Code commands to execute prior to each probing on the\n#   mag-probe. See docs/Command_Templates.md for G-Code format. This can be\n#   used to attach the probe after probing on the nozzle and before probing\n#   on the mag-probe.\nend_gcode:\n#   A list of G-Code commands to execute after each calibration command.\n#   See docs/Command_Templates.md for G-Code format. This can be used to\n#   detach the probe afterwards.\n
    "},{"location":"Config_Reference.html#additional-stepper-motors-and-extruders","title":"Additional stepper motors and extruders","text":""},{"location":"Config_Reference.html#stepper_z1","title":"[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]\n#step_pin:\n#dir_pin:\n#enable_pin:\n#microsteps:\n#rotation_distance:\n#   See the \"stepper\" section for the definition of the above parameters.\n#endstop_pin:\n#   If an endstop_pin is defined for the additional stepper then the\n#   stepper will home until the endstop is triggered. Otherwise, the\n#   stepper will home until the endstop on the primary stepper for the\n#   axis is triggered.\n
    "},{"location":"Config_Reference.html#extruder1","title":"[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]\n#step_pin:\n#dir_pin:\n#...\n#   See the \"extruder\" section for available stepper and heater\n#   parameters.\n#shared_heater:\n#   This option is deprecated and should no longer be specified.\n
    "},{"location":"Config_Reference.html#dual_carriage","title":"[dual_carriage]","text":"

    Support for cartesian and hybrid_corexy/z printers with dual carriages on a single axis. The carriage mode can be set via the SET_DUAL_CARRIAGE extended g-code command. For example, \"SET_DUAL_CARRIAGE CARRIAGE=1\" command will activate the carriage defined in this section (CARRIAGE=0 will return activation to the primary carriage). Dual carriage support is typically combined with extra extruders - the SET_DUAL_CARRIAGE command is often called at the same time as the ACTIVATE_EXTRUDER command. Be sure to park the carriages during deactivation. Note that during G28 homing, typically the primary carriage is homed first followed by the carriage defined in the [dual_carriage] config section. However, the [dual_carriage] carriage will be homed first if both carriages home in a positive direction and the [dual_carriage] carriage has a position_endstop greater than the primary carriage, or if both carriages home in a negative direction and the [dual_carriage] carriage has a position_endstop less than the primary carriage.

    Additionally, one could use \"SET_DUAL_CARRIAGE CARRIAGE=1 MODE=COPY\" or \"SET_DUAL_CARRIAGE CARRIAGE=1 MODE=MIRROR\" commands to activate either copying or mirroring mode of the dual carriage, in which case it will follow the motion of the carriage 0 accordingly. These commands can be used to print two parts simultaneously - either two identical parts (in COPY mode) or mirrored parts (in MIRROR mode). Note that COPY and MIRROR modes also require appropriate configuration of the extruder on the dual carriage, which can typically be achieved with \"SYNC_EXTRUDER_MOTION MOTION_QUEUE=extruder EXTRUDER=\" or a similar command.

    See sample-idex.cfg for an example configuration.

    [dual_carriage]\naxis:\n#   The axis this extra carriage is on (either x or y). This parameter\n#   must be provided.\n#safe_distance:\n#   The minimum distance (in mm) to enforce between the dual and the primary\n#   carriages. If a G-Code command is executed that will bring the carriages\n#   closer than the specified limit, such a command will be rejected with an\n#   error. If safe_distance is not provided, it will be inferred from\n#   position_min and position_max for the dual and primary carriages. If set\n#   to 0 (or safe_distance is unset and position_min and position_max are\n#   identical for the primary and dual carraiges), the carriages proximity\n#   checks will be disabled.\n#step_pin:\n#dir_pin:\n#enable_pin:\n#microsteps:\n#rotation_distance:\n#endstop_pin:\n#position_endstop:\n#position_min:\n#position_max:\n#   See the \"stepper\" section for the definition of the above parameters.\n
    "},{"location":"Config_Reference.html#extruder_stepper","title":"[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]\nextruder:\n#   The extruder this stepper is synchronized to. If this is set to an\n#   empty string then the stepper will not be synchronized to an\n#   extruder. This parameter must be provided.\n#step_pin:\n#dir_pin:\n#enable_pin:\n#microsteps:\n#rotation_distance:\n#   See the \"stepper\" section for the definition of the above\n#   parameters.\n
    "},{"location":"Config_Reference.html#manual_stepper","title":"[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]\n#step_pin:\n#dir_pin:\n#enable_pin:\n#microsteps:\n#rotation_distance:\n#   See the \"stepper\" section for a description of these parameters.\n#velocity:\n#   Set the default velocity (in mm/s) for the stepper. This value\n#   will be used if a MANUAL_STEPPER command does not specify a SPEED\n#   parameter. The default is 5mm/s.\n#accel:\n#   Set the default acceleration (in mm/s^2) for the stepper. An\n#   acceleration of zero will result in no acceleration. This value\n#   will be used if a MANUAL_STEPPER command does not specify an ACCEL\n#   parameter. The default is zero.\n#endstop_pin:\n#   Endstop switch detection pin. If specified, then one may perform\n#   \"homing moves\" by adding a STOP_ON_ENDSTOP parameter to\n#   MANUAL_STEPPER movement commands.\n
    "},{"location":"Config_Reference.html#mixing_extruder","title":"[mixing_extruder]","text":"

    A mixing printhead which has in-1out mixing nozzle. When activated additional G-Code Commands are available. See G-Codes for a detailed description of the additional commands. 

    [mixing_extruder]\n#steppers:\n#   Which steppers feed into the hotend/nozzle. provide a comma\n#   separated list, eg. \"extruder,extruder1,extruder2\". Should be\n#   the names of either extruder sections or extruder_stepper sections\n#   This configuration is required.\n#extruder_name:\n#   The name of the extruder to synchronize the steppers in the steppers\n#   list to.\n#   The default is the first entry in the\n#   \"steppers\" list.\n
    "},{"location":"Config_Reference.html#custom-heaters-and-sensors","title":"Custom heaters and sensors","text":""},{"location":"Config_Reference.html#verify_heater","title":"[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]\n#max_error: 120\n#   The maximum \"cumulative temperature error\" before raising an\n#   error. Smaller values result in stricter checking and larger\n#   values allow for more time before an error is reported.\n#   Specifically, the temperature is inspected once a second and if it\n#   is close to the target temperature then an internal \"error\n#   counter\" is reset; otherwise, if the temperature is below the\n#   target range then the counter is increased by the amount the\n#   reported temperature differs from that range. Should the counter\n#   exceed this \"max_error\" then an error is raised. The default is\n#   120.\n#check_gain_time:\n#   This controls heater verification during initial heating. Smaller\n#   values result in stricter checking and larger values allow for\n#   more time before an error is reported. Specifically, during\n#   initial heating, as long as the heater increases in temperature\n#   within this time frame (specified in seconds) then the internal\n#   \"error counter\" is reset. The default is 20 seconds for extruders\n#   and 60 seconds for heater_bed.\n#hysteresis: 5\n#   The maximum temperature difference (in Celsius) to a target\n#   temperature that is considered in range of the target. This\n#   controls the max_error range check. It is rare to customize this\n#   value. The default is 5.\n#heating_gain: 2\n#   The minimum temperature (in Celsius) that the heater must increase\n#   by during the check_gain_time check. It is rare to customize this\n#   value. The default is 2.\n
    "},{"location":"Config_Reference.html#homing_heaters","title":"[homing_heaters]","text":"

    Tool to disable heaters when homing or probing an axis.

    [homing_heaters]\n#steppers:\n#   A comma separated list of steppers that should cause heaters to be\n#   disabled. The default is to disable heaters for any homing/probing\n#   move.\n#   Typical example: stepper_z\n#heaters:\n#   A comma separated list of heaters to disable during homing/probing\n#   moves. The default is to disable all heaters.\n#   Typical example: extruder, heater_bed\n
    "},{"location":"Config_Reference.html#thermistor","title":"[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]\n#temperature1:\n#resistance1:\n#temperature2:\n#resistance2:\n#temperature3:\n#resistance3:\n#   Three resistance measurements (in Ohms) at the given temperatures\n#   (in Celsius). The three measurements will be used to calculate the\n#   Steinhart-Hart coefficients for the thermistor. These parameters\n#   must be provided when using Steinhart-Hart to define the\n#   thermistor.\n#beta:\n#   Alternatively, one may define temperature1, resistance1, and beta\n#   to define the thermistor parameters. This parameter must be\n#   provided when using \"beta\" to define the thermistor.\n
    "},{"location":"Config_Reference.html#adc_temperature","title":"[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]\n#temperature1:\n#voltage1:\n#temperature2:\n#voltage2:\n#...\n#   A set of temperatures (in Celsius) and voltages (in Volts) to use\n#   as reference when converting a temperature. A heater section using\n#   this sensor may also specify adc_voltage and voltage_offset\n#   parameters to define the ADC voltage (see \"Common temperature\n#   amplifiers\" section for details). At least two measurements must\n#   be provided.\n#temperature1:\n#resistance1:\n#temperature2:\n#resistance2:\n#...\n#   Alternatively one may specify a set of temperatures (in Celsius)\n#   and resistance (in Ohms) to use as reference when converting a\n#   temperature. A heater section using this sensor may also specify a\n#   pullup_resistor parameter (see \"extruder\" section for details). At\n#   least two measurements must be provided.\n
    "},{"location":"Config_Reference.html#heater_generic","title":"[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]\n#gcode_id:\n#   The id to use when reporting the temperature in the M105 command.\n#   This parameter must be provided.\n#heater_pin:\n#max_power:\n#sensor_type:\n#sensor_pin:\n#smooth_time:\n#control:\n#pid_Kp:\n#pid_Ki:\n#pid_Kd:\n#pwm_cycle_time:\n#min_temp:\n#max_temp:\n#   See the \"extruder\" section for the definition of the above\n#   parameters.\n
    "},{"location":"Config_Reference.html#temperature_sensor","title":"[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]\n#sensor_type:\n#sensor_pin:\n#min_temp:\n#max_temp:\n#   See the \"extruder\" section for the definition of the above\n#   parameters.\n#gcode_id:\n#   See the \"heater_generic\" section for the definition of this\n#   parameter.\n
    "},{"location":"Config_Reference.html#temperature-sensors","title":"Temperature sensors","text":"

    Kalico 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).

    "},{"location":"Config_Reference.html#common-thermistors","title":"Common thermistors","text":"

    Common thermistors. The following parameters are available in heater sections that use one of these sensors.

    sensor_type:\n#   One of \"EPCOS 100K B57560G104F\", \"ATC Semitec 104GT-2\",\n#   \"ATC Semitec 104NT-4-R025H42G\", \"Generic 3950\",\n#   \"Honeywell 100K 135-104LAG-J01\", \"NTC 100K MGB18-104F39050L32\",\n#   \"SliceEngineering 450\", or \"TDK NTCG104LH104JT1\"\nsensor_pin:\n#   Analog input pin connected to the thermistor. This parameter must\n#   be provided.\n#pullup_resistor: 4700\n#   The resistance (in ohms) of the pullup attached to the thermistor.\n#   The default is 4700 ohms.\n#inline_resistor: 0\n#   The resistance (in ohms) of an extra (not heat varying) resistor\n#   that is placed inline with the thermistor. It is rare to set this.\n#   The default is 0 ohms.\n
    "},{"location":"Config_Reference.html#common-temperature-amplifiers","title":"Common temperature amplifiers","text":"

    Common temperature amplifiers. The following parameters are available in heater sections that use one of these sensors.

    sensor_type:\n#   One of \"PT100 INA826\", \"AD595\", \"AD597\", \"AD8494\", \"AD8495\",\n#   \"AD8496\", or \"AD8497\".\nsensor_pin:\n#   Analog input pin connected to the sensor. This parameter must be\n#   provided.\n#adc_voltage: 5.0\n#   The ADC comparison voltage (in Volts). The default is 5 volts.\n#voltage_offset: 0\n#   The ADC voltage offset (in Volts). The default is 0.\n
    "},{"location":"Config_Reference.html#directly-connected-pt1000-sensor","title":"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\nsensor_pin:\n#   Analog input pin connected to the sensor. This parameter must be\n#   provided.\n#pullup_resistor: 4700\n#   The resistance (in ohms) of the pullup attached to the sensor. The\n#   default is 4700 ohms.\n
    "},{"location":"Config_Reference.html#maxxxxxx-temperature-sensors","title":"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:\n#   One of \"MAX6675\", \"MAX31855\", \"MAX31856\", or \"MAX31865\".\nsensor_pin:\n#   The chip select line for the sensor chip. This parameter must be\n#   provided.\n#spi_speed: 4000000\n#   The SPI speed (in hz) to use when communicating with the chip.\n#   The default is 4000000.\n#spi_bus:\n#spi_software_sclk_pin:\n#spi_software_mosi_pin:\n#spi_software_miso_pin:\n#   See the \"common SPI settings\" section for a description of the\n#   above parameters.\n#tc_type: K\n#tc_use_50Hz_filter: False\n#tc_averaging_count: 1\n#   The above parameters control the sensor parameters of MAX31856\n#   chips. The defaults for each parameter are next to the parameter\n#   name in the above list.\n#rtd_nominal_r: 100\n#rtd_reference_r: 430\n#rtd_num_of_wires: 2\n#rtd_use_50Hz_filter: False\n#   The above parameters control the sensor parameters of MAX31865\n#   chips. The defaults for each parameter are next to the parameter\n#   name in the above list.\n
    "},{"location":"Config_Reference.html#bmp180bmp280bme280bmp388bme680-temperature-sensor","title":"BMP180/BMP280/BME280/BMP388/BME680 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\n#i2c_address:\n#   Default is 118 (0x76). The BMP180, BMP388 and some BME280 sensors\n#   have an address of 119 (0x77).\n#i2c_mcu:\n#i2c_bus:\n#i2c_software_scl_pin:\n#i2c_software_sda_pin:\n#i2c_speed:\n#   See the \"common I2C settings\" section for a description of the\n#   above parameters.\n
    "},{"location":"Config_Reference.html#aht10aht20aht21-temperature-sensor","title":"AHT10/AHT20/AHT21 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\n#   Also use AHT10 for AHT20 and AHT21 sensors.\n#i2c_address:\n#   Default is 56 (0x38). Some AHT10 sensors give the option to use\n#   57 (0x39) by moving a resistor.\n#i2c_mcu:\n#i2c_bus:\n#i2c_speed:\n#   See the \"common I2C settings\" section for a description of the\n#   above parameters.\n#aht10_report_time:\n#   Interval in seconds between readings. Default is 30, minimum is 5\n
    "},{"location":"Config_Reference.html#htu21d-sensor","title":"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:\n#   Must be \"HTU21D\" , \"SI7013\", \"SI7020\", \"SI7021\" or \"SHT21\"\n#i2c_address:\n#   Default is 64 (0x40).\n#i2c_mcu:\n#i2c_bus:\n#i2c_software_scl_pin:\n#i2c_software_sda_pin:\n#i2c_speed:\n#   See the \"common I2C settings\" section for a description of the\n#   above parameters.\n#htu21d_hold_master:\n#   If the sensor can hold the I2C buf while reading. If True no other\n#   bus communication can be performed while reading is in progress.\n#   Default is False.\n#htu21d_resolution:\n#   The resolution of temperature and humidity reading.\n#   Valid values are:\n#    'TEMP14_HUM12' -> 14bit for Temp and 12bit for humidity\n#    'TEMP13_HUM10' -> 13bit for Temp and 10bit for humidity\n#    'TEMP12_HUM08' -> 12bit for Temp and 08bit for humidity\n#    'TEMP11_HUM11' -> 11bit for Temp and 11bit for humidity\n#   Default is: \"TEMP11_HUM11\"\n#htu21d_report_time:\n#   Interval in seconds between readings. Default is 30\n
    "},{"location":"Config_Reference.html#sht3x-sensor","title":"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\n#i2c_address:\n#   Default is 68 (0x44).\n#i2c_mcu:\n#i2c_bus:\n#i2c_software_scl_pin:\n#i2c_software_sda_pin:\n#i2c_speed:\n#   See the \"common I2C settings\" section for a description of the\n#   above parameters.\n
    "},{"location":"Config_Reference.html#lm75-temperature-sensor","title":"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\n#i2c_address:\n#   Default is 72 (0x48). Normal range is 72-79 (0x48-0x4F) and the 3\n#   low bits of the address are configured via pins on the chip\n#   (usually with jumpers or hard wired).\n#i2c_mcu:\n#i2c_bus:\n#i2c_software_scl_pin:\n#i2c_software_sda_pin:\n#i2c_speed:\n#   See the \"common I2C settings\" section for a description of the\n#   above parameters.\n#lm75_report_time:\n#   Interval in seconds between readings. Default is 0.8, with minimum\n#   0.5.\n
    "},{"location":"Config_Reference.html#builtin-micro-controller-temperature-sensor","title":"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\n#sensor_mcu: mcu\n#   The micro-controller to read from. The default is \"mcu\".\n#reference_voltage:\n#   The reference voltage for the ADC of the mcu. Default is 3.3\n#sensor_temperature1:\n#sensor_adc1:\n#   Specify the above two parameters (a temperature in Celsius and an\n#   ADC value as a float between 0.0 and 1.0) to calibrate the\n#   micro-controller temperature. This may improve the reported\n#   temperature accuracy on some chips. A typical way to obtain this\n#   calibration information is to completely remove power from the\n#   printer for a few hours (to ensure it is at the ambient\n#   temperature), then power it up and use the QUERY_ADC command to\n#   obtain an ADC measurement. Use some other temperature sensor on\n#   the printer to find the corresponding ambient temperature. The\n#   default is to use the factory calibration data on the\n#   micro-controller (if applicable) or the nominal values from the\n#   micro-controller specification.\n#sensor_temperature2:\n#sensor_adc2:\n#   If sensor_temperature1/sensor_adc1 is specified then one may also\n#   specify sensor_temperature2/sensor_adc2 calibration data. Doing so\n#   may provide calibrated \"temperature slope\" information. The\n#   default is to use the factory calibration data on the\n#   micro-controller (if applicable) or the nominal values from the\n#   micro-controller specification.\n
    "},{"location":"Config_Reference.html#host-temperature-sensor","title":"Host temperature sensor","text":"

    Temperature from the machine (eg Raspberry Pi) running the host software.

    sensor_type: temperature_host\n#sensor_path:\n#   The path to temperature system file. The default is\n#   \"/sys/class/thermal/thermal_zone0/temp\" which is the temperature\n#   system file on a Raspberry Pi computer.\n
    "},{"location":"Config_Reference.html#ds18b20-temperature-sensor","title":"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\nserial_no:\n#   Each 1-wire device has a unique serial number used to identify the device,\n#   usually in the format 28-031674b175ff. This parameter must be provided.\n#   Attached 1-wire devices can be listed using the following Linux command:\n#   ls /sys/bus/w1/devices/\n#ds18_report_time:\n#   Interval in seconds between readings. Default is 3.0, with a minimum of 1.0\n#sensor_mcu:\n#   The micro-controller to read from. Must be the host_mcu\n
    "},{"location":"Config_Reference.html#combined-temperature-sensor","title":"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\n#sensor_list:\n#   Must be provided. List of sensors to combine to new \"virtual\"\n#   sensor.\n#   E.g. 'temperature_sensor sensor1,extruder,heater_bed'\n#combination_method:\n#   Must be provided. Combination method used for the sensor.\n#   Available options are 'max', 'min', 'mean'.\n#maximum_deviation:\n#   Must be provided. Maximum permissible deviation between the sensors\n#   to combine (e.g. 5 degrees). To disable it, use a large value (e.g. 999.9)\n
    "},{"location":"Config_Reference.html#fans","title":"Fans","text":""},{"location":"Config_Reference.html#fan","title":"[fan]","text":"

    Print cooling fan.

    [fan]\npin:\n#   Output pin controlling the fan. This parameter must be provided.\n#max_power: 1.0\n#   The maximum power (0.0 to 1.0) that the pin may be set to. A value\n#   of 1.0 enables the pin fully for extended periods, while 0.5 allows\n#   it for no more than half the time. Use it to limit total power output\n#   (over extended periods) to the fan. This value is combined with\n#   min_power to scale fan speed. With `min_power` at 0.3 and\n#   `max_power` at 1.0, fan speed request scales between 0.3 (min_power)\n#   and 1.0 (max_power). Requesting 10% fan speed results in a value of\n#   0.37. Default is 1.0.\n#shutdown_speed: 0\n#   The desired fan speed (expressed as a value from 0.0 to 1.0) if\n#   the micro-controller software enters an error state. The default\n#   is 0.\n#cycle_time: 0.010\n#   The amount of time (in seconds) for each PWM power cycle to the\n#   fan. It is recommended this be 10 milliseconds or greater when\n#   using software based PWM. The default is 0.010 seconds.\n#hardware_pwm: False\n#   Enable this to use hardware PWM instead of software PWM. Most fans\n#   do not work well with hardware PWM, so it is not recommended to\n#   enable this unless there is an electrical requirement to switch at\n#   very high speeds. When using hardware PWM the actual cycle time is\n#   constrained by the implementation and may be significantly\n#   different than the requested cycle_time. The default is False.\n#kick_start_time: 0.100\n#   Time (in seconds) to run the fan at full speed when either first\n#   enabling or increasing it by more than 50% (helps get the fan\n#   spinning). The default is 0.100 seconds.\n#min_power: 0.0\n#   The minimum input power which will power the fan (expressed as a\n#   value from 0.0 to 1.0). The default is 0.0.\n#\n#   To calibrate this setting, start with min_power=0 and max_power=1\n#   Gradually lower the fan speed to determine the lowest\n#   input speed which reliably drives the fan without stalls. Set\n#   min_power to the duty cycle corresponding to this value (for\n#   example, 12% -> 0.12) or slightly higher.\n#tachometer_pin:\n#   Tachometer input pin for monitoring fan speed. A pullup is generally\n#   required. This parameter is optional.\n#tachometer_ppr: 2\n#   When tachometer_pin is specified, this is the number of pulses per\n#   revolution of the tachometer signal. For a BLDC fan this is\n#   normally half the number of poles. The default is 2.\n#tachometer_poll_interval: 0.0015\n#   When tachometer_pin is specified, this is the polling period of the\n#   tachometer pin, in seconds. The default is 0.0015, which is fast\n#   enough for fans below 10000 RPM at 2 PPR. This must be smaller than\n#   30/(tachometer_ppr*rpm), with some margin, where rpm is the\n#   maximum speed (in RPM) of the fan.\n#enable_pin:\n#   Optional pin to enable power to the fan. This can be useful for fans\n#   with dedicated PWM inputs. Some of these fans stay on even at 0% PWM\n#   input. In such a case, the PWM pin can be used normally, and e.g. a\n#   ground-switched FET(standard fan pin) can be used to control power to\n#   the fan.\n#off_below:\n#   These option is deprecated and should no longer be specified.\n#   Use `min_power` instead.\n#initial_speed:\n#   Fan speed will be set to this value on startup if specified. Value\n#   is from 0.0 to 1.0.\n
    "},{"location":"Config_Reference.html#heated_fan","title":"[heated_fan]","text":"

    Heated print cooling fans. An experimental module for high-temperature printing that requires part cooling air to be closer to the printed part temperature.

    [heated_fan]\n#   See the \"fan\" section for a description for fan parameters.\n#   See the \"heater_generic\" section for a description for the heater\n#   parameters.\n#heater_temp: 50\n#   The target temperature (in Celsius) for the heater when the fan is\n#   turned on. The default is 50 Celsius.\n#min_speed: 1.0\n#   The minimum fan speed (expressed as a value from 0.0 to 1.0) that the\n#   fan will be set to when its associated heater is on (e.g.: to protect\n#   ducts from melting). If the fan is set to a speed lower than min_speed,\n#   the min_speed value is applied. The default is 1.0 (100%)\n#idle_timeout: 60\n#   A timeout in seconds for the fan to stay on when it is requested to turn\n#   off, to protect ducts from melting. The default is 60 (s).\n
    "},{"location":"Config_Reference.html#heater_fan","title":"[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]\n#pin:\n#max_power:\n#shutdown_speed:\n#cycle_time:\n#hardware_pwm:\n#kick_start_time:\n#min_power:\n#tachometer_pin:\n#tachometer_ppr:\n#tachometer_poll_interval:\n#enable_pin:\n#initial_speed:\n#   See the \"fan\" section for a description of the above parameters.\n#heater: extruder\n#   Name of the config section defining the heater that this fan is\n#   associated with. If a comma separated list of heater names is\n#   provided here, then the fan will be enabled when any of the given\n#   heaters are enabled. The default is \"extruder\".\n#heater_temp: 50.0\n#   A temperature (in Celsius) that the heater must drop below before\n#   the fan is disabled. The default is 50 Celsius.\n#fan_speed: 1.0\n#   The fan speed (expressed as a value from 0.0 to 1.0) that the fan\n#   will be set to when its associated heater is enabled. The default\n#   is 1.0\n
    "},{"location":"Config_Reference.html#controller_fan","title":"[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]\n#pin:\n#max_power:\n#shutdown_speed:\n#cycle_time:\n#hardware_pwm:\n#kick_start_time:\n#min_power:\n#tachometer_pin:\n#tachometer_ppr:\n#tachometer_poll_interval:\n#enable_pin:\n#   See the \"fan\" section for a description of the above parameters.\n#fan_speed: 1.0\n#   The fan speed (expressed as a value from 0.0 to 1.0) that the fan\n#   will be set to when a heater or stepper driver is active.\n#   The default is 1.0\n#idle_timeout:\n#   The amount of time (in seconds) after a stepper driver or heater\n#   was active and the fan should be kept running. The default\n#   is 30 seconds.\n#idle_speed:\n#   The fan speed (expressed as a value from 0.0 to 1.0) that the fan\n#   will be set to when a heater or stepper driver was active and\n#   before the idle_timeout is reached. The default is fan_speed.\n#heater:\n#stepper:\n#   Name of the config section defining the heater/stepper that this fan\n#   is associated with. If a comma separated list of heater/stepper names\n#   is provided here, then the fan will be enabled when any of the given\n#   heaters/steppers are enabled. The default heater is \"extruder\", the\n#   default stepper is all of them.\n
    "},{"location":"Config_Reference.html#temperature_fan","title":"[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]\n#pin:\n#max_power:\n#shutdown_speed:\n#cycle_time:\n#hardware_pwm:\n#kick_start_time:\n#min_power:\n#tachometer_pin:\n#tachometer_ppr:\n#tachometer_poll_interval:\n#enable_pin:\n#   See the \"fan\" section for a description of the above parameters.\n#sensor_type:\n#sensor_pin:\n#control:\n#max_delta:\n#min_temp:\n#max_temp:\n#   See the \"extruder\" section for a description of the above parameters.\n#pid_Kp:\n#pid_Ki:\n#pid_Kd:\n#   The proportional (pid_Kp), integral (pid_Ki), and derivative\n#   (pid_Kd) settings for the PID feedback control system. Kalico\n#   evaluates the PID settings with the following general formula:\n#     fan_pwm = max_power - (Kp*e + Ki*integral(e) - Kd*derivative(e)) / 255\n#   Where \"e\" is \"target_temperature - measured_temperature\" and\n#   \"fan_pwm\" is the requested fan rate with 0.0 being full off and\n#   1.0 being full on. The pid_Kp, pid_Ki, and pid_Kd parameters must\n#   be provided when the PID control algorithm is enabled.\n#pid_deriv_time: 2.0\n#   A time value (in seconds) over which temperature measurements will\n#   be smoothed when using the PID control algorithm. This may reduce\n#   the impact of measurement noise. The default is 2 seconds.\n#target_temp: 40.0\n#   A temperature (in Celsius) that will be the target temperature.\n#   The default is 40 degrees.\n#max_speed: 1.0\n#   The fan speed (expressed as a value from 0.0 to 1.0) that the fan\n#   will be set to when the sensor temperature exceeds the set value.\n#   The default is 1.0.\n#min_speed: 0.3\n#   The minimum fan speed (expressed as a value from 0.0 to 1.0) that\n#   the fan will be set to for PID temperature fans.\n#   The default is 0.3.\n#gcode_id:\n#   If set, the temperature will be reported in M105 queries using the\n#   given id. The default is to not report the temperature via M105.\n#reverse: False\n#   If true, the working mode of the fan is reversed. If the temperature\n#   is lower than the target temperature, the fan speed increases;\n#   otherwise, the fan speed decreases.\n#   The default is False.\n
    control: curve\n#points:\n#  50.0, 0.0\n#  55.0, 0.5\n#   A user might defne a list of points which consist of a temperature with\n#   it's associated fan speed (temp, fan_speed).\n#   The target_temp value defines the temperature at which the fan will run\n#   at full speed.\n#   The algorithm will use linear interpolation to get the fan speeds\n#   between two points (if one has defined 0.0 for 50\u00b0 and 1.0 for 60\u00b0 the\n#   fan would run with 0.5 at 55\u00b0)\n#cooling_hysteresis: 0.0\n#   define the temperature hysteresis for lowering the fan speed\n#   (in simple terms this setting offsets the fan curve when cooling down\n#   by the specified amount of degrees celsius. For example, if the\n#   hysteresis is set to 5\u00b0C, the fan curve will be moved by -5\u00b0C. This\n#   setting can be used to reduce the effects of quickly changing\n#   temperatures around a target temperature which would cause the fan to\n#   speed up and slow down repeatedly.)\n#heating_hysteresis: 0.0\n#   same as cooling_hysteresis but for increasing the fan speed, it is\n#   recommended to be left at 0 for safety reasons\n#smooth_readings: 10\n#   This parameter is deprecated and should no longer be used.\n
    "},{"location":"Config_Reference.html#fan_generic","title":"[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]\n#pin:\n#max_power:\n#shutdown_speed:\n#cycle_time:\n#hardware_pwm:\n#kick_start_time:\n#min_power:\n#tachometer_pin:\n#tachometer_ppr:\n#tachometer_poll_interval:\n#enable_pin:\n#   See the \"fan\" section for a description of the above parameters.\n
    "},{"location":"Config_Reference.html#leds","title":"LEDs","text":""},{"location":"Config_Reference.html#led","title":"[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]\n#red_pin:\n#green_pin:\n#blue_pin:\n#white_pin:\n#   The pin controlling the given LED color. At least one of the above\n#   parameters must be provided.\n#cycle_time: 0.010\n#   The amount of time (in seconds) per PWM cycle. It is recommended\n#   this be 10 milliseconds or greater when using software based PWM.\n#   The default is 0.010 seconds.\n#hardware_pwm: False\n#   Enable this to use hardware PWM instead of software PWM. When\n#   using hardware PWM the actual cycle time is constrained by the\n#   implementation and may be significantly different than the\n#   requested cycle_time. The default is False.\n#initial_RED: 0.0\n#initial_GREEN: 0.0\n#initial_BLUE: 0.0\n#initial_WHITE: 0.0\n#   Sets the initial LED color. Each value should be between 0.0 and\n#   1.0. The default for each color is 0.\n
    "},{"location":"Config_Reference.html#neopixel","title":"[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]\npin:\n#   The pin connected to the neopixel. This parameter must be\n#   provided.\n#chain_count:\n#   The number of Neopixel chips that are \"daisy chained\" to the\n#   provided pin. The default is 1 (which indicates only a single\n#   Neopixel is connected to the pin).\n#color_order: GRB\n#   Set the pixel order required by the LED hardware (using a string\n#   containing the letters R, G, B, W with W optional). Alternatively,\n#   this may be a comma separated list of pixel orders - one for each\n#   LED in the chain. The default is GRB.\n#initial_RED: 0.0\n#initial_GREEN: 0.0\n#initial_BLUE: 0.0\n#initial_WHITE: 0.0\n#   See the \"led\" section for information on these parameters.\n
    "},{"location":"Config_Reference.html#dotstar","title":"[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]\ndata_pin:\n#   The pin connected to the data line of the dotstar. This parameter\n#   must be provided.\nclock_pin:\n#   The pin connected to the clock line of the dotstar. This parameter\n#   must be provided.\n#chain_count:\n#   See the \"neopixel\" section for information on this parameter.\n#initial_RED: 0.0\n#initial_GREEN: 0.0\n#initial_BLUE: 0.0\n#   See the \"led\" section for information on these parameters.\n
    "},{"location":"Config_Reference.html#pca9533","title":"[pca9533]","text":"

    PCA9533 LED support. The PCA9533 is used on the mightyboard.

    [pca9533 my_pca9533]\n#i2c_address: 98\n#   The i2c address that the chip is using on the i2c bus. Use 98 for\n#   the PCA9533/1, 99 for the PCA9533/2. The default is 98.\n#i2c_mcu:\n#i2c_bus:\n#i2c_software_scl_pin:\n#i2c_software_sda_pin:\n#i2c_speed:\n#   See the \"common I2C settings\" section for a description of the\n#   above parameters.\n#initial_RED: 0.0\n#initial_GREEN: 0.0\n#initial_BLUE: 0.0\n#initial_WHITE: 0.0\n#   See the \"led\" section for information on these parameters.\n
    "},{"location":"Config_Reference.html#pca9632","title":"[pca9632]","text":"

    PCA9632 LED support. The PCA9632 is used on the FlashForge Dreamer.

    [pca9632 my_pca9632]\n#i2c_address: 98\n#   The i2c address that the chip is using on the i2c bus. This may be\n#   96, 97, 98, or 99.  The default is 98.\n#i2c_mcu:\n#i2c_bus:\n#i2c_software_scl_pin:\n#i2c_software_sda_pin:\n#i2c_speed:\n#   See the \"common I2C settings\" section for a description of the\n#   above parameters.\n#scl_pin:\n#sda_pin:\n#   Alternatively, if the pca9632 is not connected to a hardware I2C\n#   bus, then one may specify the \"clock\" (scl_pin) and \"data\"\n#   (sda_pin) pins. The default is to use hardware I2C.\n#color_order: RGBW\n#   Set the pixel order of the LED (using a string containing the\n#   letters R, G, B, W). The default is RGBW.\n#initial_RED: 0.0\n#initial_GREEN: 0.0\n#initial_BLUE: 0.0\n#initial_WHITE: 0.0\n#   See the \"led\" section for information on these parameters.\n
    "},{"location":"Config_Reference.html#additional-servos-buttons-and-other-pins","title":"Additional servos, buttons, and other pins","text":""},{"location":"Config_Reference.html#servo","title":"[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]\npin:\n#   PWM output pin controlling the servo. This parameter must be\n#   provided.\n#maximum_servo_angle: 180\n#   The maximum angle (in degrees) that this servo can be set to. The\n#   default is 180 degrees.\n#minimum_pulse_width: 0.001\n#   The minimum pulse width time (in seconds). This should correspond\n#   with an angle of 0 degrees. The default is 0.001 seconds.\n#maximum_pulse_width: 0.002\n#   The maximum pulse width time (in seconds). This should correspond\n#   with an angle of maximum_servo_angle. The default is 0.002\n#   seconds.\n#initial_angle:\n#   Initial angle (in degrees) to set the servo to. The default is to\n#   not send any signal at startup.\n#initial_pulse_width:\n#   Initial pulse width time (in seconds) to set the servo to. (This\n#   is only valid if initial_angle is not set.) The default is to not\n#   send any signal at startup.\n
    "},{"location":"Config_Reference.html#gcode_button","title":"[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]\npin:\n#   The pin on which the button is connected. This parameter must be\n#   provided.\n#analog_range:\n#   Two comma separated resistances (in Ohms) specifying the minimum\n#   and maximum resistance range for the button. If analog_range is\n#   provided then the pin must be an analog capable pin. The default\n#   is to use digital gpio for the button.\n#analog_pullup_resistor:\n#   The pullup resistance (in Ohms) when analog_range is specified.\n#   The default is 4700 ohms.\n#press_gcode:\n#   A list of G-Code commands to execute when the button is pressed.\n#   G-Code templates are supported. This parameter must be provided.\n#release_gcode:\n#   A list of G-Code commands to execute when the button is released.\n#   G-Code templates are supported. The default is to not run any\n#   commands on a button release.\n
    "},{"location":"Config_Reference.html#output_pin","title":"[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]\npin:\n#   The pin to configure as an output. This parameter must be\n#   provided.\n#pwm: False\n#   Set if the output pin should be capable of pulse-width-modulation.\n#   If this is true, the value fields should be between 0 and 1; if it\n#   is false the value fields should be either 0 or 1. The default is\n#   False.\n#value:\n#   The value to initially set the pin to during MCU configuration.\n#   The default is 0 (for low voltage).\n#shutdown_value:\n#   The value to set the pin to on an MCU shutdown event. The default\n#   is 0 (for low voltage).\n#cycle_time: 0.100\n#   The amount of time (in seconds) per PWM cycle. It is recommended\n#   this be 10 milliseconds or greater when using software based PWM.\n#   The default is 0.100 seconds for pwm pins.\n#hardware_pwm: False\n#   Enable this to use hardware PWM instead of software PWM. When\n#   using hardware PWM the actual cycle time is constrained by the\n#   implementation and may be significantly different than the\n#   requested cycle_time. The default is False.\n#scale:\n#   This parameter can be used to alter how the 'value' and\n#   'shutdown_value' parameters are interpreted for pwm pins. If\n#   provided, then the 'value' parameter should be between 0.0 and\n#   'scale'. This may be useful when configuring a PWM pin that\n#   controls a stepper voltage reference. The 'scale' can be set to\n#   the equivalent stepper amperage if the PWM were fully enabled, and\n#   then the 'value' parameter can be specified using the desired\n#   amperage for the stepper. The default is to not scale the 'value'\n#   parameter.\n#maximum_mcu_duration:\n#static_value:\n#   These options are deprecated and should no longer be specified.\n
    "},{"location":"Config_Reference.html#pwm_tool","title":"[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]\npin:\n#   The pin to configure as an output. This parameter must be provided.\n#maximum_mcu_duration:\n#   The maximum duration a non-shutdown value may be driven by the MCU\n#   without an acknowledge from the host.\n#   If host can not keep up with an update, the MCU will shutdown\n#   and set all pins to their respective shutdown values.\n#   Default: 0 (disabled)\n#   Usual values are around 5 seconds.\n#value:\n#shutdown_value:\n#cycle_time: 0.100\n#hardware_pwm: False\n#scale:\n#   See the \"output_pin\" section for the definition of these parameters.\n
    "},{"location":"Config_Reference.html#pwm_cycle_time","title":"[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]\npin:\n#value:\n#shutdown_value:\n#cycle_time: 0.100\n#scale:\n#   See the \"output_pin\" section for information on these parameters.\n
    "},{"location":"Config_Reference.html#static_digital_output","title":"[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]\npins:\n#   A comma separated list of pins to be set as GPIO output pins. The\n#   pin will be set to a high level unless the pin name is prefaced\n#   with \"!\". This parameter must be provided.\n
    "},{"location":"Config_Reference.html#multi_pin","title":"[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]\npins:\n#   A comma separated list of pins associated with this alias. This\n#   parameter must be provided.\n
    "},{"location":"Config_Reference.html#tmc-stepper-driver-configuration","title":"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.

    "},{"location":"Config_Reference.html#tmc2130","title":"[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]\ncs_pin:\n#   The pin corresponding to the TMC2130 chip select line. This pin\n#   will be set to low at the start of SPI messages and raised to high\n#   after the message completes. This parameter must be provided.\n#spi_speed:\n#spi_bus:\n#spi_software_sclk_pin:\n#spi_software_mosi_pin:\n#spi_software_miso_pin:\n#   See the \"common SPI settings\" section for a description of the\n#   above parameters.\n#chain_position:\n#chain_length:\n#   These parameters configure an SPI daisy chain. The two parameters\n#   define the stepper position in the chain and the total chain length.\n#   Position 1 corresponds to the stepper that connects to the MOSI signal.\n#   The default is to not use an SPI daisy chain.\n#interpolate: True\n#   If true, enable step interpolation (the driver will internally\n#   step at a rate of 256 micro-steps). This interpolation does\n#   introduce a small systemic positional deviation - see\n#   TMC_Drivers.md for details. The default is True.\nrun_current:\n#   The amount of current (in amps RMS) to configure the driver to use\n#   during stepper movement. This parameter must be provided.\n#hold_current:\n#   The amount of current (in amps RMS) to configure the driver to use\n#   when the stepper is not moving. Setting a hold_current is not\n#   recommended (see TMC_Drivers.md for details). The default is to\n#   not reduce the current.\n#home_current:\n#   The amount of current (in amps RMS) to configure the driver to use\n#   during homing procedures. The default is to not reduce the current.\n#current_change_dwell_time:\n#   The amount of time (in seconds) to wait after changing homing current.\n#   The default is 0.5 seconds.\nsense_resistor:\n#   The resistance (in ohms) of the driver sense resistor. This\n#   parameter must be provided.\n#stealthchop_threshold: 0\n#   The velocity (in mm/s) to set the \"stealthChop\" threshold to. When\n#   set, \"stealthChop\" mode will be enabled if the stepper motor\n#   velocity is below this value. The default is 0, which disables\n#   \"stealthChop\" mode.\n#coolstep_threshold:\n#   The velocity (in mm/s) to set the TMC driver internal \"CoolStep\"\n#   threshold to. If set, the coolstep feature will be enabled when\n#   the stepper motor velocity is near or above this value. Important\n#   - if coolstep_threshold is set and \"sensorless homing\" is used,\n#   then one must ensure that the homing speed is above the coolstep\n#   threshold! The default is to not enable the coolstep feature.\n#high_velocity_threshold:\n#   The velocity (in mm/s) to set the TMC driver internal \"high\n#   velocity\" threshold (THIGH) to. This is typically used to disable\n#   the \"CoolStep\" feature at high speeds. The default is to not set a\n#   TMC \"high velocity\" threshold.\n#driver_MSLUT0: 2863314260\n#driver_MSLUT1: 1251300522\n#driver_MSLUT2: 608774441\n#driver_MSLUT3: 269500962\n#driver_MSLUT4: 4227858431\n#driver_MSLUT5: 3048961917\n#driver_MSLUT6: 1227445590\n#driver_MSLUT7: 4211234\n#driver_W0: 2\n#driver_W1: 1\n#driver_W2: 1\n#driver_W3: 1\n#driver_X1: 128\n#driver_X2: 255\n#driver_X3: 255\n#driver_START_SIN: 0\n#driver_START_SIN90: 247\n#   These fields control the Microstep Table registers directly. The optimal\n#   wave table is specific to each motor and might vary with current. An\n#   optimal configuration will have minimal print artifacts caused by\n#   non-linear stepper movement. The values specified above are the default\n#   values used by the driver. The value must be specified as a decimal integer\n#   (hex form is not supported). In order to compute the wave table fields,\n#   see the tmc2130 \"Calculation Sheet\" from the Trinamic website.\n#driver_IHOLDDELAY: 8\n#driver_TPOWERDOWN: 0\n#driver_TBL: 1\n#driver_TOFF: 4\n#driver_HEND: 7\n#driver_HSTRT: 0\n#driver_PWM_AUTOSCALE: True\n#driver_PWM_FREQ: 1\n#driver_PWM_GRAD: 4\n#driver_PWM_AMPL: 128\n#driver_SGT: 0\n#   Set the given register during the configuration of the TMC2130\n#   chip. This may be used to set custom motor parameters. The\n#   defaults for each parameter are next to the parameter name in the\n#   above list.\n#diag0_pin:\n#diag1_pin:\n#   The micro-controller pin attached to one of the DIAG lines of the\n#   TMC2130 chip. Only a single diag pin should be specified. The pin\n#   is \"active low\" and is thus normally prefaced with \"^!\". Setting\n#   this creates a \"tmc2130_stepper_x:virtual_endstop\" virtual pin\n#   which may be used as the stepper's endstop_pin. Doing this enables\n#   \"sensorless homing\". (Be sure to also set driver_SGT to an\n#   appropriate sensitivity value.) The default is to not enable\n#   sensorless homing.\n
    "},{"location":"Config_Reference.html#tmc2208","title":"[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]\nuart_pin:\n#   The pin connected to the TMC2208 PDN_UART line. This parameter\n#   must be provided.\n#tx_pin:\n#   If using separate receive and transmit lines to communicate with\n#   the driver then set uart_pin to the receive pin and tx_pin to the\n#   transmit pin. The default is to use uart_pin for both reading and\n#   writing.\n#select_pins:\n#   A comma separated list of pins to set prior to accessing the\n#   tmc2208 UART. This may be useful for configuring an analog mux for\n#   UART communication. The default is to not configure any pins.\n#interpolate: True\n#   If true, enable step interpolation (the driver will internally\n#   step at a rate of 256 micro-steps). This interpolation does\n#   introduce a small systemic positional deviation - see\n#   TMC_Drivers.md for details. The default is True.\nrun_current:\n#   The amount of current (in amps RMS) to configure the driver to use\n#   during stepper movement. This parameter must be provided.\n#hold_current:\n#   The amount of current (in amps RMS) to configure the driver to use\n#   when the stepper is not moving. Setting a hold_current is not\n#   recommended (see TMC_Drivers.md for details). The default is to\n#   not reduce the current.\n#home_current:\n#   The amount of current (in amps RMS) to configure the driver to use\n#   during homing procedures. The default is to not reduce the current.\n#current_change_dwell_time:\n#   The amount of time (in seconds) to wait after changing homing current.\n#   The default is 0.5 seconds.\nsense_resistor:\n#   The resistance (in ohms) of the driver sense resistor. This\n#   parameter must be provided.\n#stealthchop_threshold: 0\n#   The velocity (in mm/s) to set the \"stealthChop\" threshold to. When\n#   set, \"stealthChop\" mode will be enabled if the stepper motor\n#   velocity is below this value. The default is 0, which disables\n#   \"stealthChop\" mode.\n#driver_MULTISTEP_FILT: True\n#driver_IHOLDDELAY: 8\n#driver_TPOWERDOWN: 20\n#driver_TBL: 2\n#driver_TOFF: 3\n#driver_HEND: 0\n#driver_HSTRT: 5\n#driver_PWM_AUTOGRAD: True\n#driver_PWM_AUTOSCALE: True\n#driver_PWM_LIM: 12\n#driver_PWM_REG: 8\n#driver_PWM_FREQ: 1\n#driver_PWM_GRAD: 14\n#driver_PWM_OFS: 36\n#   Set the given register during the configuration of the TMC2208\n#   chip. This may be used to set custom motor parameters. The\n#   defaults for each parameter are next to the parameter name in the\n#   above list.\n
    "},{"location":"Config_Reference.html#tmc2209","title":"[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]\nuart_pin:\n#tx_pin:\n#select_pins:\n#interpolate: True\nrun_current:\n#hold_current:\n#home_current:\n#current_change_dwell_time:\nsense_resistor:\n#stealthchop_threshold: 0\n#   See the \"tmc2208\" section for the definition of these parameters.\n#coolstep_threshold:\n#   The velocity (in mm/s) to set the TMC driver internal \"CoolStep\"\n#   threshold to. If set, the coolstep feature will be enabled when\n#   the stepper motor velocity is near or above this value. Important\n#   - if coolstep_threshold is set and \"sensorless homing\" is used,\n#   then one must ensure that the homing speed is above the coolstep\n#   threshold! The default is to not enable the coolstep feature.\n#uart_address:\n#   The address of the TMC2209 chip for UART messages (an integer\n#   between 0 and 3). This is typically used when multiple TMC2209\n#   chips are connected to the same UART pin. The default is zero.\n#driver_MULTISTEP_FILT: True\n#driver_IHOLDDELAY: 8\n#driver_TPOWERDOWN: 20\n#driver_TBL: 2\n#driver_TOFF: 3\n#driver_HEND: 0\n#driver_HSTRT: 5\n#driver_PWM_AUTOGRAD: True\n#driver_PWM_AUTOSCALE: True\n#driver_PWM_LIM: 12\n#driver_PWM_REG: 8\n#driver_PWM_FREQ: 1\n#driver_PWM_GRAD: 14\n#driver_PWM_OFS: 36\n#driver_SGTHRS: 0\n#   Set the given register during the configuration of the TMC2209\n#   chip. This may be used to set custom motor parameters. The\n#   defaults for each parameter are next to the parameter name in the\n#   above list.\n#diag_pin:\n#   The micro-controller pin attached to the DIAG line of the TMC2209\n#   chip. The pin is normally prefaced with \"^\" to enable a pullup.\n#   Setting this creates a \"tmc2209_stepper_x:virtual_endstop\" virtual\n#   pin which may be used as the stepper's endstop_pin. Doing this\n#   enables \"sensorless homing\". (Be sure to also set driver_SGTHRS to\n#   an appropriate sensitivity value.) The default is to not enable\n#   sensorless homing.\n
    "},{"location":"Config_Reference.html#tmc2660","title":"[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]\ncs_pin:\n#   The pin corresponding to the TMC2660 chip select line. This pin\n#   will be set to low at the start of SPI messages and set to high\n#   after the message transfer completes. This parameter must be\n#   provided.\n#spi_speed: 4000000\n#   SPI bus frequency used to communicate with the TMC2660 stepper\n#   driver. The default is 4000000.\n#spi_bus:\n#spi_software_sclk_pin:\n#spi_software_mosi_pin:\n#spi_software_miso_pin:\n#   See the \"common SPI settings\" section for a description of the\n#   above parameters.\n#interpolate: True\n#   If true, enable step interpolation (the driver will internally\n#   step at a rate of 256 micro-steps). This only works if microsteps\n#   is set to 16. Interpolation does introduce a small systemic\n#   positional deviation - see TMC_Drivers.md for details. The default\n#   is True.\nrun_current:\n#   The amount of current (in amps RMS) used by the driver during\n#   stepper movement. This parameter must be provided.\n#home_current:\n#   The amount of current (in amps RMS) to configure the driver to use\n#   during homing procedures. The default is to not reduce the current.\n#current_change_dwell_time:\n#   The amount of time (in seconds) to wait after changing homing current.\n#   The default is 0.5 seconds.\nsense_resistor:\n#   The resistance (in ohms) of the driver sense resistor. This\n#   parameter must be provided.\n#idle_current_percent: 100\n#   The percentage of the run_current the stepper driver will be\n#   lowered to when the idle timeout expires (you need to set up the\n#   timeout using a [idle_timeout] config section). The current will\n#   be raised again once the stepper has to move again. Make sure to\n#   set this to a high enough value such that the steppers do not lose\n#   their position. There is also small delay until the current is\n#   raised again, so take this into account when commanding fast moves\n#   while the stepper is idling. The default is 100 (no reduction).\n#driver_TBL: 2\n#driver_RNDTF: 0\n#driver_HDEC: 0\n#driver_CHM: 0\n#driver_HEND: 3\n#driver_HSTRT: 3\n#driver_TOFF: 4\n#driver_SEIMIN: 0\n#driver_SEDN: 0\n#driver_SEMAX: 0\n#driver_SEUP: 0\n#driver_SEMIN: 0\n#driver_SFILT: 0\n#driver_SGT: 0\n#driver_SLPH: 0\n#driver_SLPL: 0\n#driver_DISS2G: 0\n#driver_TS2G: 3\n#   Set the given parameter during the configuration of the TMC2660\n#   chip. This may be used to set custom driver parameters. The\n#   defaults for each parameter are next to the parameter name in the\n#   list above. See the TMC2660 datasheet about what each parameter\n#   does and what the restrictions on parameter combinations are. Be\n#   especially aware of the CHOPCONF register, where setting CHM to\n#   either zero or one will lead to layout changes (the first bit of\n#   HDEC) is interpreted as the MSB of HSTRT in this case).\n
    "},{"location":"Config_Reference.html#tmc2240","title":"[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]\ncs_pin:\n#   The pin corresponding to the TMC2240 chip select line. This pin\n#   will be set to low at the start of SPI messages and raised to high\n#   after the message completes. This parameter must be provided.\n#spi_speed:\n#spi_bus:\n#spi_software_sclk_pin:\n#spi_software_mosi_pin:\n#spi_software_miso_pin:\n#   See the \"common SPI settings\" section for a description of the\n#   above parameters.\n#uart_pin:\n#   The pin connected to the TMC2240 DIAG1/SW line. If this parameter\n#   is provided UART communication is used rather then SPI.\n#chain_position:\n#chain_length:\n#   These parameters configure an SPI daisy chain. The two parameters\n#   define the stepper position in the chain and the total chain length.\n#   Position 1 corresponds to the stepper that connects to the MOSI signal.\n#   The default is to not use an SPI daisy chain.\n#interpolate: True\n#   If true, enable step interpolation (the driver will internally\n#   step at a rate of 256 micro-steps). The default is True.\nrun_current:\n#   The amount of current (in amps RMS) to configure the driver to use\n#   during stepper movement. This parameter must be provided.\n#hold_current:\n#   The amount of current (in amps RMS) to configure the driver to use\n#   when the stepper is not moving. Setting a hold_current is not\n#   recommended (see TMC_Drivers.md for details). The default is to\n#   not reduce the current.\n#home_current:\n#   The amount of current (in amps RMS) to configure the driver to use\n#   during homing procedures. The default is to not reduce the current.\n#current_change_dwell_time:\n#   The amount of time (in seconds) to wait after changing homing current.\n#   The default is 0.5 seconds.\n#rref:\n#   The resistance (in ohms) of the resistor between IREF and GND. This\n#   parameter must be provided.\n#stealthchop_threshold: 0\n#   The velocity (in mm/s) to set the \"stealthChop\" threshold to. When\n#   set, \"stealthChop\" mode will be enabled if the stepper motor\n#   velocity is below this value. The default is 0, which disables\n#   \"stealthChop\" mode.\n#coolstep_threshold:\n#   The velocity (in mm/s) to set the TMC driver internal \"CoolStep\"\n#   threshold to. If set, the coolstep feature will be enabled when\n#   the stepper motor velocity is near or above this value. Important\n#   - if coolstep_threshold is set and \"sensorless homing\" is used,\n#   then one must ensure that the homing speed is above the coolstep\n#   threshold! The default is to not enable the coolstep feature.\n#high_velocity_threshold:\n#   The velocity (in mm/s) to set the TMC driver internal \"high\n#   velocity\" threshold (THIGH) to. This is typically used to disable\n#   the \"CoolStep\" feature at high speeds. The default is to not set a\n#   TMC \"high velocity\" threshold.\n#driver_MSLUT0: 2863314260\n#driver_MSLUT1: 1251300522\n#driver_MSLUT2: 608774441\n#driver_MSLUT3: 269500962\n#driver_MSLUT4: 4227858431\n#driver_MSLUT5: 3048961917\n#driver_MSLUT6: 1227445590\n#driver_MSLUT7: 4211234\n#driver_W0: 2\n#driver_W1: 1\n#driver_W2: 1\n#driver_W3: 1\n#driver_X1: 128\n#driver_X2: 255\n#driver_X3: 255\n#driver_START_SIN: 0\n#driver_START_SIN90: 247\n#driver_OFFSET_SIN90: 0\n#   These fields control the Microstep Table registers directly. The optimal\n#   wave table is specific to each motor and might vary with current. An\n#   optimal configuration will have minimal print artifacts caused by\n#   non-linear stepper movement. The values specified above are the default\n#   values used by the driver. The value must be specified as a decimal integer\n#   (hex form is not supported). In order to compute the wave table fields,\n#   see the tmc2130 \"Calculation Sheet\" from the Trinamic website.\n#   Additionally, this driver also has the OFFSET_SIN90 field which can be used\n#   to tune a motor with unbalanced coils. See the `Sine Wave Lookup Table`\n#   section in the datasheet for information about this field and how to tune\n#   it.\n#driver_MULTISTEP_FILT: True\n#driver_IHOLDDELAY: 6\n#driver_IRUNDELAY: 4\n#driver_TPOWERDOWN: 10\n#driver_TBL: 2\n#driver_TOFF: 3\n#driver_HEND: 2\n#driver_HSTRT: 5\n#driver_FD3: 0\n#driver_TPFD: 4\n#driver_CHM: 0\n#driver_VHIGHFS: 0\n#driver_VHIGHCHM: 0\n#driver_DISS2G: 0\n#driver_DISS2VS: 0\n#driver_PWM_AUTOSCALE: True\n#driver_PWM_AUTOGRAD: True\n#driver_PWM_FREQ: 0\n#driver_FREEWHEEL: 0\n#driver_PWM_GRAD: 0\n#driver_PWM_OFS: 29\n#driver_PWM_REG: 4\n#driver_PWM_LIM: 12\n#driver_SLOPE_CONTROL: 0\n#   The chip has a default value of 0, corresponding to 100V/\u00b5s.\n#   Setting this value to 2, corresponding to 400V/\u00b5s, approximately\n#   matches the TMC2209. This lowers the power dissipation at a 50kHz\n#   chopper frequency by around 1W.\n#driver_SGT: 0\n#driver_SEMIN: 0\n#driver_SEUP: 0\n#driver_SEMAX: 0\n#driver_SEDN: 0\n#driver_SEIMIN: 0\n#driver_SFILT: 0\n#driver_SG4_ANGLE_OFFSET: 1\n#   Set the given register during the configuration of the TMC2240\n#   chip. This may be used to set custom motor parameters. The\n#   defaults for each parameter are next to the parameter name in the\n#   above list.\n#diag0_pin:\n#diag1_pin:\n#   The micro-controller pin attached to one of the DIAG lines of the\n#   TMC2240 chip. Only a single diag pin should be specified. The pin\n#   is \"active low\" and is thus normally prefaced with \"^!\". Setting\n#   this creates a \"tmc2240_stepper_x:virtual_endstop\" virtual pin\n#   which may be used as the stepper's endstop_pin. Doing this enables\n#   \"sensorless homing\". (Be sure to also set driver_SGT to an\n#   appropriate sensitivity value.) The default is to not enable\n#   sensorless homing.\n
    "},{"location":"Config_Reference.html#tmc5160","title":"[tmc5160]","text":"

    Configure a TMC5160 or TMC2160 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]\ncs_pin:\n#   The pin corresponding to the TMC5160 or TMC2160 chip select line.\n#   This pin will be set to low at the start of SPI messages and raised\n#   to high after the message completes. This parameter must be provided.\n#spi_speed:\n#spi_bus:\n#spi_software_sclk_pin:\n#spi_software_mosi_pin:\n#spi_software_miso_pin:\n#   See the \"common SPI settings\" section for a description of the\n#   above parameters.\n#chain_position:\n#chain_length:\n#   These parameters configure an SPI daisy chain. The two parameters\n#   define the stepper position in the chain and the total chain length.\n#   Position 1 corresponds to the stepper that connects to the MOSI signal.\n#   The default is to not use an SPI daisy chain.\n#interpolate: True\n#   If true, enable step interpolation (the driver will internally\n#   step at a rate of 256 micro-steps). The default is True.\nrun_current:\n#   The amount of current (in amps RMS) to configure the driver to use\n#   during stepper movement. This parameter must be provided.\n#hold_current:\n#   The amount of current (in amps RMS) to configure the driver to use\n#   when the stepper is not moving. Setting a hold_current is not\n#   recommended (see TMC_Drivers.md for details). The default is to\n#   not reduce the current.\n#home_current:\n#   The amount of current (in amps RMS) to configure the driver to use\n#   during homing procedures. The default is to not reduce the current.\n#current_change_dwell_time:\n#   The amount of time (in seconds) to wait after changing homing current.\n#   The default is 0.5 seconds.\nsense_resistor:\n#   The resistance (in ohms) of the driver sense resistor. This\n#   parameter must be provided.\n#stealthchop_threshold: 0\n#   The velocity (in mm/s) to set the \"stealthChop\" threshold to. When\n#   set, \"stealthChop\" mode will be enabled if the stepper motor\n#   velocity is below this value. The default is 0, which disables\n#   \"stealthChop\" mode.\n#coolstep_threshold:\n#   The velocity (in mm/s) to set the TMC driver internal \"CoolStep\"\n#   threshold to. If set, the coolstep feature will be enabled when\n#   the stepper motor velocity is near or above this value. Important\n#   - if coolstep_threshold is set and \"sensorless homing\" is used,\n#   then one must ensure that the homing speed is above the coolstep\n#   threshold! The default is to not enable the coolstep feature.\n#high_velocity_threshold:\n#   The velocity (in mm/s) to set the TMC driver internal \"high\n#   velocity\" threshold (THIGH) to. This is typically used to disable\n#   the \"CoolStep\" feature at high speeds. The default is to not set a\n#   TMC \"high velocity\" threshold.\n#driver_MSLUT0: 2863314260\n#driver_MSLUT1: 1251300522\n#driver_MSLUT2: 608774441\n#driver_MSLUT3: 269500962\n#driver_MSLUT4: 4227858431\n#driver_MSLUT5: 3048961917\n#driver_MSLUT6: 1227445590\n#driver_MSLUT7: 4211234\n#driver_W0: 2\n#driver_W1: 1\n#driver_W2: 1\n#driver_W3: 1\n#driver_X1: 128\n#driver_X2: 255\n#driver_X3: 255\n#driver_START_SIN: 0\n#driver_START_SIN90: 247\n#   These fields control the Microstep Table registers directly. The optimal\n#   wave table is specific to each motor and might vary with current. An\n#   optimal configuration will have minimal print artifacts caused by\n#   non-linear stepper movement. The values specified above are the default\n#   values used by the driver. The value must be specified as a decimal integer\n#   (hex form is not supported). In order to compute the wave table fields,\n#   see the tmc2130 \"Calculation Sheet\" from the Trinamic website.\n#driver_MULTISTEP_FILT: True\n#driver_IHOLDDELAY: 6\n#driver_TPOWERDOWN: 10\n#driver_TBL: 2\n#driver_TOFF: 3\n#driver_HEND: 2\n#driver_HSTRT: 5\n#driver_FD3: 0\n#driver_TPFD: 4\n#driver_CHM: 0\n#driver_VHIGHFS: 0\n#driver_VHIGHCHM: 0\n#driver_DISS2G: 0\n#driver_DISS2VS: 0\n#driver_PWM_AUTOSCALE: True\n#driver_PWM_AUTOGRAD: True\n#driver_PWM_FREQ: 0\n#driver_FREEWHEEL: 0\n#driver_PWM_GRAD: 0\n#driver_PWM_OFS: 30\n#driver_PWM_REG: 4\n#driver_PWM_LIM: 12\n#driver_SGT: 0\n#driver_SEMIN: 0\n#driver_SEUP: 0\n#driver_SEMAX: 0\n#driver_SEDN: 0\n#driver_SEIMIN: 0\n#driver_SFILT: 0\n#driver_DRVSTRENGTH: 0\n#driver_BBMCLKS: 4\n#driver_BBMTIME: 0\n#driver_FILT_ISENSE: 0\n#   Set the given register during the configuration of the TMC5160 or\n#   TMC2160 chip. This may be used to set custom motor parameters. The\n#   defaults for each parameter are next to the parameter name in the\n#   above list.\n#\u26a0\ufe0fdriver_s2vs_level: 6   # Short to Supply tolerance, from 4 to 15\n#\u26a0\ufe0fdriver_s2g_level: 6    # Short to Ground tolerance, from 2 to 15\n#\u26a0\ufe0fdriver_shortdelay: 0   # Short trigger delay, 0=750ns, 1=1500ns\n#\u26a0\ufe0fdriver_short_filter: 1\n#   Short filtering bandwidth. 0=100ns, 1=1us (Default), 2=2us, 3=3us\n#diag0_pin:\n#diag1_pin:\n#   The micro-controller pin attached to one of the DIAG lines of the\n#   TMC5160 or TMC2160 chip. Only a single diag pin should be specified.\n#   The pin is \"active low\" and is thus normally prefaced with \"^!\".\n#   Setting this creates a \"tmc5160_stepper_x:virtual_endstop\" virtual pin\n#   which may be used as the stepper's endstop_pin. Doing this enables\n#   \"sensorless homing\". (Be sure to also set driver_SGT to an\n#   appropriate sensitivity value.) The default is to not enable\n#   sensorless homing.\n
    "},{"location":"Config_Reference.html#run-time-stepper-motor-current-configuration","title":"Run-time stepper motor current configuration","text":""},{"location":"Config_Reference.html#ad5206","title":"[ad5206]","text":"

    Statically configured AD5206 digipots connected via SPI bus (one may define any number of sections with an \"ad5206\" prefix).

    [ad5206 my_digipot]\nenable_pin:\n#   The pin corresponding to the AD5206 chip select line. This pin\n#   will be set to low at the start of SPI messages and raised to high\n#   after the message completes. This parameter must be provided.\n#spi_speed:\n#spi_bus:\n#spi_software_sclk_pin:\n#spi_software_mosi_pin:\n#spi_software_miso_pin:\n#   See the \"common SPI settings\" section for a description of the\n#   above parameters.\n#channel_1:\n#channel_2:\n#channel_3:\n#channel_4:\n#channel_5:\n#channel_6:\n#   The value to statically set the given AD5206 channel to. This is\n#   typically set to a number between 0.0 and 1.0 with 1.0 being the\n#   highest resistance and 0.0 being the lowest resistance. However,\n#   the range may be changed with the 'scale' parameter (see below).\n#   If a channel is not specified then it is left unconfigured.\n#scale:\n#   This parameter can be used to alter how the 'channel_x' parameters\n#   are interpreted. If provided, then the 'channel_x' parameters\n#   should be between 0.0 and 'scale'. This may be useful when the\n#   AD5206 is used to set stepper voltage references. The 'scale' can\n#   be set to the equivalent stepper amperage if the AD5206 were at\n#   its highest resistance, and then the 'channel_x' parameters can be\n#   specified using the desired amperage value for the stepper. The\n#   default is to not scale the 'channel_x' parameters.\n
    "},{"location":"Config_Reference.html#mcp4451","title":"[mcp4451]","text":"

    Statically configured MCP4451 digipot connected via I2C bus (one may define any number of sections with an \"mcp4451\" prefix).

    [mcp4451 my_digipot]\ni2c_address:\n#   The i2c address that the chip is using on the i2c bus. This\n#   parameter must be provided.\n#i2c_mcu:\n#i2c_bus:\n#i2c_software_scl_pin:\n#i2c_software_sda_pin:\n#i2c_speed:\n#   See the \"common I2C settings\" section for a description of the\n#   above parameters.\n#wiper_0:\n#wiper_1:\n#wiper_2:\n#wiper_3:\n#   The value to statically set the given MCP4451 \"wiper\" to. This is\n#   typically set to a number between 0.0 and 1.0 with 1.0 being the\n#   highest resistance and 0.0 being the lowest resistance. However,\n#   the range may be changed with the 'scale' parameter (see below).\n#   If a wiper is not specified then it is left unconfigured.\n#scale:\n#   This parameter can be used to alter how the 'wiper_x' parameters\n#   are interpreted. If provided, then the 'wiper_x' parameters should\n#   be between 0.0 and 'scale'. This may be useful when the MCP4451 is\n#   used to set stepper voltage references. The 'scale' can be set to\n#   the equivalent stepper amperage if the MCP4451 were at its highest\n#   resistance, and then the 'wiper_x' parameters can be specified\n#   using the desired amperage value for the stepper. The default is\n#   to not scale the 'wiper_x' parameters.\n
    "},{"location":"Config_Reference.html#mcp4728","title":"[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]\n#i2c_address: 96\n#   The i2c address that the chip is using on the i2c bus. The default\n#   is 96.\n#i2c_mcu:\n#i2c_bus:\n#i2c_software_scl_pin:\n#i2c_software_sda_pin:\n#i2c_speed:\n#   See the \"common I2C settings\" section for a description of the\n#   above parameters.\n#channel_a:\n#channel_b:\n#channel_c:\n#channel_d:\n#   The value to statically set the given MCP4728 channel to. This is\n#   typically set to a number between 0.0 and 1.0 with 1.0 being the\n#   highest voltage (2.048V) and 0.0 being the lowest voltage.\n#   However, the range may be changed with the 'scale' parameter (see\n#   below). If a channel is not specified then it is left\n#   unconfigured.\n#scale:\n#   This parameter can be used to alter how the 'channel_x' parameters\n#   are interpreted. If provided, then the 'channel_x' parameters\n#   should be between 0.0 and 'scale'. This may be useful when the\n#   MCP4728 is used to set stepper voltage references. The 'scale' can\n#   be set to the equivalent stepper amperage if the MCP4728 were at\n#   its highest voltage (2.048V), and then the 'channel_x' parameters\n#   can be specified using the desired amperage value for the\n#   stepper. The default is to not scale the 'channel_x' parameters.\n
    "},{"location":"Config_Reference.html#mcp4018","title":"[mcp4018]","text":"

    Statically configured MCP4018 digipot connected via two gpio \"bit banging\" pins (one may define any number of sections with an \"mcp4018\" prefix).

    [mcp4018 my_digipot]\nscl_pin:\n#   The SCL \"clock\" pin. This parameter must be provided.\nsda_pin:\n#   The SDA \"data\" pin. This parameter must be provided.\nwiper:\n#   The value to statically set the given MCP4018 \"wiper\" to. This is\n#   typically set to a number between 0.0 and 1.0 with 1.0 being the\n#   highest resistance and 0.0 being the lowest resistance. However,\n#   the range may be changed with the 'scale' parameter (see below).\n#   This parameter must be provided.\n#scale:\n#   This parameter can be used to alter how the 'wiper' parameter is\n#   interpreted. If provided, then the 'wiper' parameter should be\n#   between 0.0 and 'scale'. This may be useful when the MCP4018 is\n#   used to set stepper voltage references. The 'scale' can be set to\n#   the equivalent stepper amperage if the MCP4018 is at its highest\n#   resistance, and then the 'wiper' parameter can be specified using\n#   the desired amperage value for the stepper. The default is to not\n#   scale the 'wiper' parameter.\n
    "},{"location":"Config_Reference.html#display-support","title":"Display support","text":""},{"location":"Config_Reference.html#display","title":"[display]","text":"

    Support for a display attached to the micro-controller.

    [display]\nlcd_type:\n#   The type of LCD chip in use. This may be \"hd44780\", \"hd44780_spi\",\n#   \"aip31068_spi\", \"st7920\", \"emulated_st7920\", \"uc1701\", \"ssd1306\", or\n#   \"sh1106\".\n#   See the display sections below for information on each type and\n#   additional parameters they provide. This parameter must be\n#   provided.\n#display_group:\n#   The name of the display_data group to show on the display. This\n#   controls the content of the screen (see the \"display_data\" section\n#   for more information). The default is _default_20x4 for hd44780 or\n#   aip31068_spi displays and _default_16x4 for other displays.\n#menu_timeout:\n#   Timeout for menu. Being inactive this amount of seconds will\n#   trigger menu exit or return to root menu when having autorun\n#   enabled. The default is 0 seconds (disabled)\n#menu_root:\n#   Name of the main menu section to show when clicking the encoder\n#   on the home screen. The defaults is __main, and this shows the\n#   the default menus as defined in klippy/extras/display/menu.cfg\n#menu_reverse_navigation:\n#   When enabled it will reverse up and down directions for list\n#   navigation. The default is False. This parameter is optional.\n#encoder_pins:\n#   The pins connected to encoder. 2 pins must be provided when using\n#   encoder. This parameter must be provided when using menu.\n#encoder_steps_per_detent:\n#   How many steps the encoder emits per detent (\"click\"). If the\n#   encoder takes two detents to move between entries or moves two\n#   entries from one detent, try changing this. Allowed values are 2\n#   (half-stepping) or 4 (full-stepping). The default is 4.\n#click_pin:\n#   The pin connected to 'enter' button or encoder 'click'. This\n#   parameter must be provided when using menu. The presence of an\n#   'analog_range_click_pin' config parameter turns this parameter\n#   from digital to analog.\n#back_pin:\n#   The pin connected to 'back' button. This parameter is optional,\n#   menu can be used without it. The presence of an\n#   'analog_range_back_pin' config parameter turns this parameter from\n#   digital to analog.\n#up_pin:\n#   The pin connected to 'up' button. This parameter must be provided\n#   when using menu without encoder. The presence of an\n#   'analog_range_up_pin' config parameter turns this parameter from\n#   digital to analog.\n#down_pin:\n#   The pin connected to 'down' button. This parameter must be\n#   provided when using menu without encoder. The presence of an\n#   'analog_range_down_pin' config parameter turns this parameter from\n#   digital to analog.\n#kill_pin:\n#   The pin connected to 'kill' button. This button will call\n#   emergency stop. The presence of an 'analog_range_kill_pin' config\n#   parameter turns this parameter from digital to analog.\n#analog_pullup_resistor: 4700\n#   The resistance (in ohms) of the pullup attached to the analog\n#   button. The default is 4700 ohms.\n#analog_range_click_pin:\n#   The resistance range for a 'enter' button. Range minimum and\n#   maximum comma-separated values must be provided when using analog\n#   button.\n#analog_range_back_pin:\n#   The resistance range for a 'back' button. Range minimum and\n#   maximum comma-separated values must be provided when using analog\n#   button.\n#analog_range_up_pin:\n#   The resistance range for a 'up' button. Range minimum and maximum\n#   comma-separated values must be provided when using analog button.\n#analog_range_down_pin:\n#   The resistance range for a 'down' button. Range minimum and\n#   maximum comma-separated values must be provided when using analog\n#   button.\n#analog_range_kill_pin:\n#   The resistance range for a 'kill' button. Range minimum and\n#   maximum comma-separated values must be provided when using analog\n#   button.\n
    "},{"location":"Config_Reference.html#hd44780-display","title":"hd44780 display","text":"

    Information on configuring hd44780 displays (which is used in \"RepRapDiscount 2004 Smart Controller\" type displays).

    [display]\nlcd_type: hd44780\n#   Set to \"hd44780\" for hd44780 displays.\nrs_pin:\ne_pin:\nd4_pin:\nd5_pin:\nd6_pin:\nd7_pin:\n#   The pins connected to an hd44780 type lcd. These parameters must\n#   be provided.\n#hd44780_protocol_init: True\n#   Perform 8-bit/4-bit protocol initialization on an hd44780 display.\n#   This is necessary on real hd44780 devices. However, one may need\n#   to disable this on some \"clone\" devices. The default is True.\n#line_length:\n#   Set the number of characters per line for an hd44780 type lcd.\n#   Possible values are 20 (default) and 16. The number of lines is\n#   fixed to 4.\n...\n
    "},{"location":"Config_Reference.html#hd44780_spi-display","title":"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]\nlcd_type: hd44780_spi\n#   Set to \"hd44780_spi\" for hd44780_spi displays.\nlatch_pin:\nspi_software_sclk_pin:\nspi_software_mosi_pin:\nspi_software_miso_pin:\n#   The pins connected to the shift register controlling the display.\n#   The spi_software_miso_pin needs to be set to an unused pin of the\n#   printer mainboard as the shift register does not have a MISO pin,\n#   but the software spi implementation requires this pin to be\n#   configured.\n#hd44780_protocol_init: True\n#   Perform 8-bit/4-bit protocol initialization on an hd44780 display.\n#   This is necessary on real hd44780 devices. However, one may need\n#   to disable this on some \"clone\" devices. The default is True.\n#line_length:\n#   Set the number of characters per line for an hd44780 type lcd.\n#   Possible values are 20 (default) and 16. The number of lines is\n#   fixed to 4.\n...\n
    "},{"location":"Config_Reference.html#aip31068_spi-display","title":"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]\nlcd_type: aip31068_spi\nlatch_pin:\nspi_software_sclk_pin:\nspi_software_mosi_pin:\nspi_software_miso_pin:\n#   The pins connected to the shift register controlling the display.\n#   The spi_software_miso_pin needs to be set to an unused pin of the\n#   printer mainboard as the shift register does not have a MISO pin,\n#   but the software spi implementation requires this pin to be\n#   configured.\n#line_length:\n#   Set the number of characters per line for an hd44780 type lcd.\n#   Possible values are 20 (default) and 16. The number of lines is\n#   fixed to 4.\n...\n
    "},{"location":"Config_Reference.html#st7920-display","title":"st7920 display","text":"

    Information on configuring st7920 displays (which is used in \"RepRapDiscount 12864 Full Graphic Smart Controller\" type displays).

    [display]\nlcd_type: st7920\n#   Set to \"st7920\" for st7920 displays.\ncs_pin:\nsclk_pin:\nsid_pin:\n#   The pins connected to an st7920 type lcd. These parameters must be\n#   provided.\n...\n
    "},{"location":"Config_Reference.html#emulated_st7920-display","title":"emulated_st7920 display","text":"

    Information on configuring an emulated st7920 display - found in some \"2.4 inch touchscreen devices\" and similar.

    [display]\nlcd_type: emulated_st7920\n#   Set to \"emulated_st7920\" for emulated_st7920 displays.\nen_pin:\nspi_software_sclk_pin:\nspi_software_mosi_pin:\nspi_software_miso_pin:\n#   The pins connected to an emulated_st7920 type lcd. The en_pin\n#   corresponds to the cs_pin of the st7920 type lcd,\n#   spi_software_sclk_pin corresponds to sclk_pin and\n#   spi_software_mosi_pin corresponds to sid_pin. The\n#   spi_software_miso_pin needs to be set to an unused pin of the\n#   printer mainboard as the st7920 as no MISO pin but the software\n#   spi implementation requires this pin to be configured.\n...\n
    "},{"location":"Config_Reference.html#uc1701-display","title":"uc1701 display","text":"

    Information on configuring uc1701 displays (which is used in \"MKS Mini 12864\" type displays).

    [display]\nlcd_type: uc1701\n#   Set to \"uc1701\" for uc1701 displays.\ncs_pin:\na0_pin:\n#   The pins connected to a uc1701 type lcd. These parameters must be\n#   provided.\n#rst_pin:\n#   The pin connected to the \"rst\" pin on the lcd. If it is not\n#   specified then the hardware must have a pull-up on the\n#   corresponding lcd line.\n#contrast:\n#   The contrast to set. The value may range from 0 to 63 and the\n#   default is 40.\n...\n
    "},{"location":"Config_Reference.html#ssd1306-and-sh1106-displays","title":"ssd1306 and sh1106 displays","text":"

    Information on configuring ssd1306 and sh1106 displays.

    [display]\nlcd_type:\n#   Set to either \"ssd1306\" or \"sh1106\" for the given display type.\n#i2c_mcu:\n#i2c_bus:\n#i2c_software_scl_pin:\n#i2c_software_sda_pin:\n#i2c_speed:\n#   Optional parameters available for displays connected via an i2c\n#   bus. See the \"common I2C settings\" section for a description of\n#   the above parameters.\n#cs_pin:\n#dc_pin:\n#spi_speed:\n#spi_bus:\n#spi_software_sclk_pin:\n#spi_software_mosi_pin:\n#spi_software_miso_pin:\n#   The pins connected to the lcd when in \"4-wire\" spi mode. See the\n#   \"common SPI settings\" section for a description of the parameters\n#   that start with \"spi_\". The default is to use i2c mode for the\n#   display.\n#reset_pin:\n#   A reset pin may be specified on the display. If it is not\n#   specified then the hardware must have a pull-up on the\n#   corresponding lcd line.\n#contrast:\n#   The contrast to set. The value may range from 0 to 256 and the\n#   default is 239.\n#vcomh: 0\n#   Set the Vcomh value on the display. This value is associated with\n#   a \"smearing\" effect on some OLED displays. The value may range\n#   from 0 to 63. Default is 0.\n#invert: False\n#   TRUE inverts the pixels on certain OLED displays.  The default is\n#   False.\n#x_offset: 0\n#   Set the horizontal offset value on SH1106 displays. The default is\n#   0.\n...\n
    "},{"location":"Config_Reference.html#display_data","title":"[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]\nposition:\n#   Comma separated row and column of the display position that should\n#   be used to display the information. This parameter must be\n#   provided.\ntext:\n#   The text to show at the given position. This field is evaluated\n#   using command templates (see docs/Command_Templates.md). This\n#   parameter must be provided.\n
    "},{"location":"Config_Reference.html#display_template","title":"[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]\n#param_<name>:\n#   One may specify any number of options with a \"param_\" prefix. The\n#   given name will be assigned the given value (parsed as a Python\n#   literal) and will be available during macro expansion. If the\n#   parameter is passed in the call to render() then that value will\n#   be used during macro expansion. For example, a config with\n#   \"param_speed = 75\" might have a caller with\n#   \"render('my_template_name', param_speed=80)\". Parameter names may\n#   not use upper case characters.\ntext:\n#   The text to return when the this template is rendered. This field\n#   is evaluated using command templates (see\n#   docs/Command_Templates.md). This parameter must be provided.\n
    "},{"location":"Config_Reference.html#display_glyph","title":"[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]\n#data:\n#   The display data, stored as 16 lines consisting of 16 bits (1 per\n#   pixel) where '.' is a blank pixel and '*' is an on pixel (e.g.,\n#   \"****************\" to display a solid horizontal line).\n#   Alternatively, one can use '0' for a blank pixel and '1' for an on\n#   pixel. Put each display line into a separate config line. The\n#   glyph must consist of exactly 16 lines with 16 bits each. This\n#   parameter is optional.\n#hd44780_data:\n#   Glyph to use on 20x4 hd44780 displays. The glyph must consist of\n#   exactly 8 lines with 5 bits each. This parameter is optional.\n#hd44780_slot:\n#   The hd44780 hardware index (0..7) to store the glyph at. If\n#   multiple distinct images use the same slot then make sure to only\n#   use one of those images in any given screen. This parameter is\n#   required if hd44780_data is specified.\n
    "},{"location":"Config_Reference.html#display-my_extra_display","title":"[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]\n# See the \"display\" section for available parameters.\n
    "},{"location":"Config_Reference.html#menu","title":"\u26a0\ufe0f [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.\n#[menu __some_list __some_name]\n#type: disabled\n#   Permanently disabled menu element, only required attribute is 'type'.\n#   Allows you to easily disable/hide existing menu items.\n\n#[menu some_name]\n#type:\n#   One of command, input, list, text:\n#       command      - basic menu element with various script triggers\n#       input        - same like 'command' but has value changing capabilities.\n#                      Press will start/stop edit mode.\n#       list         - it allows for menu items to be grouped together in a\n#                      scrollable list.  Add to the list by creating menu\n#                      configurations using \"some_list\" as a prefix - for\n#                      example: [menu some_list some_item_in_the_list]\n#       vsdlist      - same as 'list' but will append files from virtual sdcard\n#                      (deprecated, will be removed in the future)\n#    \u26a0\ufe0f file_browser - Extended SD Card browser, supporting directories and\n#                      sorting. (replaces vsdlist)\n#    \u26a0\ufe0f dialog       - Menu Dialogs, a list of inputs with a final choice to\n#                      confirm or cancel. Used for more complex scenarios like\n#                      PID/MPC calibration where you may want to set multiple\n#                      values for a single command\n#name:\n#   Name of menu item - evaluated as a template.\n#enable:\n#   Template that evaluates to True or False.\n#index:\n#   Position where an item needs to be inserted in list. By default\n#   the item is added at the end.\n\n#[menu some_list]\n#type: list\n#name:\n#enable:\n#   See above for a description of these parameters.\n\n#[menu sdcard]\n#type: file_browser\n#name:\n#sort_by:\n#   `last_modified` (default) or `name`\n#enable:\n#   See above for a description of these parameters.\n\n#[menu some_list some_command]\n#type: command\n#name:\n#enable:\n#   See above for a description of these parameters.\n#gcode:\n#   Script to run on button click or long click. Evaluated as a\n#   template.\n\n#[menu some_list some_input]\n#type: input\n#name:\n#enable:\n#   See above for a description of these parameters.\n#input:\n#   Initial value to use when editing - evaluated as a template.\n#   Result must be float.\n#input_min:\n#   Minimum value of range - evaluated as a template. Default -99999.\n#input_max:\n#   Maximum value of range - evaluated as a template. Default 99999.\n#input_step:\n#   Editing step - Must be a positive integer or float value. It has\n#   internal fast rate step. When \"(input_max - input_min) /\n#   input_step > 100\" then fast rate step is 10 * input_step else fast\n#   rate step is same input_step.\n#realtime:\n#   This attribute accepts static boolean value. When enabled then\n#   gcode script is run after each value change. The default is False.\n#gcode:\n#   Script to run on button click, long click or value change.\n#   Evaluated as a template. The button click will trigger the edit\n#   mode start or end.\n\n#[menu neopixel]\n#type: dialog\n#name:\n#enable:\n#   See above for a description of these parameters.\n#title:\n#   An optional title to display at the top of the dialog. `name` will\n#   used if not set\n#confirm_text:\n#cancel_text\n#   Templates for the confirmation and cancel options\n#gcode:\n#   G-Code to run on confirmation. The dialog will be closed on\n#   confirmation. `{menu.exit()}` may be used to close the menu\n#   instead.\n
    "},{"location":"Config_Reference.html#filament-sensors","title":"Filament sensors","text":""},{"location":"Config_Reference.html#filament_switch_sensor","title":"[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]\n#pause_on_runout: True\n#   When set to True, a PAUSE will execute immediately after a runout\n#   is detected. Note that if pause_on_runout is False and the\n#   runout_gcode is omitted then runout detection is disabled. Default\n#   is True.\n#runout_gcode:\n#   A list of G-Code commands to execute after a filament runout is\n#   detected. See docs/Command_Templates.md for G-Code format. If\n#   pause_on_runout is set to True this G-Code will run after the\n#   PAUSE is complete. The default is not to run any G-Code commands.\n#immediate_runout_gcode:\n#   A list of G-Code commands to execute immediately after a filament\n#   runout is detected and runout_distance is greater than 0.\n#   See docs/Command_Templates.md for G-Code format.\n#insert_gcode:\n#   A list of G-Code commands to execute after a filament insert is\n#   detected. See docs/Command_Templates.md for G-Code format. The\n#   default is not to run any G-Code commands, which disables insert\n#   detection.\n#runout_distance: 0.0\n#   Defines how much filament can still be pulled after the\n#   switch sensor triggered (e.g. you have a 60cm reverse bowden between your\n#   extruder and your sensor, you would then set runout_distance to something\n#   like 590 to leave a small safety margin and now the print will not\n#   immediately pause when the sensor triggers but rather keep printing until\n#   the filament is at the extruder). The default is 0 millimeters.\n#event_delay: 3.0\n#   The minimum amount of time in seconds to delay between events.\n#   Events triggered during this time period will be silently\n#   ignored. The default is 3 seconds.\n#pause_delay: 0.5\n#   The amount of time to delay, in seconds, between the pause command\n#   dispatch and execution of the runout_gcode. It may be useful to\n#   increase this delay if OctoPrint exhibits strange pause behavior.\n#   Default is 0.5 seconds.\n#switch_pin:\n#   The pin on which the switch is connected. This parameter must be\n#   provided.\n#smart:\n#   If set to true the sensor will use the virtual_sd_card module to determine\n#   whether the printer is printing which is more reliable but will not work\n#   when streaming a print over usb or similar.\n#always_fire_events:\n#   If set to true, runout events will always fire no matter whether the sensor\n#   is enabled or disabled. Usefull for MMUs\n#check_on_print_start:\n#   If set to true, the sensor will be reevaluated when a print starts and if\n#   no filament is detected the runout_gcode will be run no matter the defined\n#   runout_distance(immediate_runout_gcode will not be run in this case)\n
    "},{"location":"Config_Reference.html#filament_motion_sensor","title":"[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]\ndetection_length: 7.0\n#   The minimum length of filament pulled through the sensor to trigger\n#   a state change on the switch_pin\n#   Default is 7 mm.\nextruder:\n#   The name of the extruder section this sensor is associated with.\n#   This parameter must be provided.\nswitch_pin:\n#pause_on_runout:\n#runout_gcode:\n#insert_gcode:\n#event_delay:\n#pause_delay:\n#smart:\n#always_fire_events:\n#   See the \"filament_switch_sensor\" section for a description of the\n#   above parameters.\n
    "},{"location":"Config_Reference.html#tsl1401cl_filament_width_sensor","title":"[tsl1401cl_filament_width_sensor]","text":"

    TSLl401CL Based Filament Width Sensor. See the guide for more information.

    [tsl1401cl_filament_width_sensor]\n#pin:\n#default_nominal_filament_diameter: 1.75 # (mm)\n#   Maximum allowed filament diameter difference as mm.\n#max_difference: 0.2\n#   The distance from sensor to the melting chamber as mm.\n#measurement_delay: 100\n
    "},{"location":"Config_Reference.html#hall_filament_width_sensor","title":"[hall_filament_width_sensor]","text":"

    Hall filament width sensor (see Hall Filament Width Sensor).

    [hall_filament_width_sensor]\nadc1:\nadc2:\n#   Analog input pins connected to the sensor. These parameters must\n#   be provided.\n#cal_dia1: 1.50\n#cal_dia2: 2.00\n#   The calibration values (in mm) for the sensors. The default is\n#   1.50 for cal_dia1 and 2.00 for cal_dia2.\n#raw_dia1: 9500\n#raw_dia2: 10500\n#   The raw calibration values for the sensors. The default is 9500\n#   for raw_dia1 and 10500 for raw_dia2.\n#default_nominal_filament_diameter: 1.75\n#   The nominal filament diameter. This parameter must be provided.\n#max_difference: 0.200\n#   Maximum allowed filament diameter difference in millimeters (mm).\n#   If difference between nominal filament diameter and sensor output\n#   is more than +- max_difference, extrusion multiplier is set back\n#   to %100. The default is 0.200.\n#measurement_delay: 70\n#   The distance from sensor to the melting chamber/hot-end in\n#   millimeters (mm). The filament between the sensor and the hot-end\n#   will be treated as the default_nominal_filament_diameter. Host\n#   module works with FIFO logic. It keeps each sensor value and\n#   position in an array and POP them back in correct position. This\n#   parameter must be provided.\n#enable: False\n#   Sensor enabled or disabled after power on. The default is to\n#   disable.\n#measurement_interval: 10\n#   The approximate distance (in mm) between sensor readings. The\n#   default is 10mm.\n#logging: False\n#   Out diameter to terminal and klippy.log can be turn on|of by\n#   command.\n#min_diameter: 1.0\n#   Minimal diameter for trigger virtual filament_switch_sensor.\n#max_diameter:\n#   Maximum diameter for triggering virtual filament_switch_sensor.\n#   The default is default_nominal_filament_diameter + max_difference.\n#use_current_dia_while_delay: False\n#   Use the current diameter instead of the nominal diameter while\n#   the measurement delay has not run through.\n#pause_on_runout:\n#immediate_runout_gcode:\n#runout_gcode:\n#insert_gcode:\n#event_delay:\n#pause_delay:\n#smart:\n#always_fire_events:\n#check_on_print_start:\n#   See the \"filament_switch_sensor\" section for a description of the\n#   above parameters.\n
    "},{"location":"Config_Reference.html#belay","title":"[belay]","text":"

    Belay extruder sync sensors (one may define any number of sections with a \"belay\" prefix).

    [belay my_belay]\nextruder_type:\n#   The type of secondary extruder. Available choices are 'trad_rack'\n#   or 'extruder_stepper'. This parameter must be specified.\nextruder_stepper_name:\n#   The name of the extruder_stepper being used as the secondary\n#   extruder. Must be specified if extruder_type is set to\n#   'extruder_stepper', but should not be specified otherwise. For\n#   example, if the config section for the secondary extruder is\n#   [extruder_stepper my_extruder_stepper], this parameter's value\n#   would be 'my_extruder_stepper'.\nsensor_pin:\n#   Input pin connected to the sensor. This parameter must be\n#   provided.\n#multiplier_high: 1.05\n#   High multiplier to set for the secondary extruder when extruding\n#   forward and Belay is compressed or when extruding backward and\n#   Belay is expanded. The default is 1.05.\n#multiplier_low: 0.95\n#   Low multiplier to set for the secondary extruder when extruding\n#   forward and Belay is expanded or when extruding backward and\n#   Belay is compressed. The default is 0.95.\n#debug_level: 0\n#   Controls messages sent to the console. If set to 0, no messages\n#   will be sent. If set to 1, multiplier resets will be reported, and\n#   the multiplier will be reported whenever it is set in response to\n#   a switch state change. If set to 2, the behavior is the same as 1\n#   but with an additional message whenever the multiplier is set in\n#   response to detecting an extrusion direction change. The default\n#   is 0.\n
    "},{"location":"Config_Reference.html#load-cells","title":"Load Cells","text":""},{"location":"Config_Reference.html#load_cell","title":"[load_cell]","text":"

    Load Cell. Uses an ADC sensor attached to a load cell to create a digital scale.

    [load_cell]\nsensor_type:\n#   This must be one of the supported sensor types, see below.\n
    "},{"location":"Config_Reference.html#hx711","title":"HX711","text":"

    This is a 24 bit low sample rate chip using \"bit-bang\" communications. It is suitable for filament scales.

    [load_cell]\nsensor_type: hx711\nsclk_pin:\n#   The pin connected to the HX711 clock line. This parameter must be provided.\ndout_pin:\n#   The pin connected to the HX711 data output line. This parameter must be\n#   provided.\n#gain: A-128\n#   Valid values for gain are: A-128, A-64, B-32. The default is A-128.\n#   'A' denotes the input channel and the number denotes the gain. Only the 3\n#   listed combinations are supported by the chip. Note that changing the gain\n#   setting also selects the channel being read.\n#sample_rate: 80\n#   Valid values for sample_rate are 80 or 10. The default value is 80.\n#   This must match the wiring of the chip. The sample rate cannot be changed\n#   in software.\n
    "},{"location":"Config_Reference.html#hx717","title":"HX717","text":"

    This is the 4x higher sample rate version of the HX711, suitable for probing.

    [load_cell]\nsensor_type: hx717\nsclk_pin:\n#   The pin connected to the HX717 clock line. This parameter must be provided.\ndout_pin:\n#   The pin connected to the HX717 data output line. This parameter must be\n#   provided.\n#gain: A-128\n#   Valid values for gain are A-128, B-64, A-64, B-8.\n#   'A' denotes the input channel and the number denotes the gain setting.\n#   Only the 4 listed combinations are supported by the chip. Note that\n#   changing the gain setting also selects the channel being read.\n#sample_rate: 320\n#   Valid values for sample_rate are: 10, 20, 80, 320. The default is 320.\n#   This must match the wiring of the chip. The sample rate cannot be changed\n#   in software.\n
    "},{"location":"Config_Reference.html#ads1220","title":"ADS1220","text":"

    The ADS1220 is a 24 bit ADC supporting up to a 2Khz sample rate configurable in software.

    [load_cell]\nsensor_type: ads1220\ncs_pin:\n#   The pin connected to the ADS1220 chip select line. This parameter must\n#   be provided.\n#spi_speed: 512000\n#   This chip supports 2 speeds: 256000 or 512000. The faster speed is only\n#   enabled when one of the Turbo sample rates is used. The correct spi_speed\n#   is selected based on the sample rate.\n#spi_bus:\n#spi_software_sclk_pin:\n#spi_software_mosi_pin:\n#spi_software_miso_pin:\n#   See the \"common SPI settings\" section for a description of the\n#   above parameters.\ndata_ready_pin:\n#   Pin connected to the ADS1220 data ready line. This parameter must be\n#   provided.\n#gain: 128\n#   Valid gain values are 128, 64, 32, 16, 8, 4, 2, 1\n#   The default is 128\n#pga_bypass: False\n#   Disable the internal Programmable Gain Amplifier. If\n#   True the PGA will be disabled for gains 1, 2, and 4. The PGA is always\n#   enabled for gain settings 8 to 128, regardless of the pga_bypass setting.\n#   If AVSS is used as an input pga_bypass is forced to True.\n#   The default is False.\n#sample_rate: 660\n#   This chip supports two ranges of sample rates, Normal and Turbo. In turbo\n#   mode the chip's internal clock runs twice as fast and the SPI communication\n#   speed is also doubled.\n#   Normal sample rates: 20, 45, 90, 175, 330, 600, 1000\n#   Turbo sample rates: 40, 90, 180, 350, 660, 1200, 2000\n#   The default is 660\n#input_mux:\n#   Input multiplexer configuration, select a pair of pins to use. The first pin\n#   is the positive, AINP, and the second pin is the negative, AINN. Valid\n#   values are: 'AIN0_AIN1', 'AIN0_AIN2', 'AIN0_AIN3', 'AIN1_AIN2', 'AIN1_AIN3',\n#   'AIN2_AIN3', 'AIN1_AIN0', 'AIN3_AIN2', 'AIN0_AVSS', 'AIN1_AVSS', 'AIN2_AVSS'\n#   and 'AIN3_AVSS'. If AVSS is used the PGA is bypassed and the pga_bypass\n#   setting will be forced to True.\n#   The default is AIN0_AIN1.\n#vref:\n#   The selected voltage reference. Valid values are: 'internal', 'REF0', 'REF1'\n#   and 'analog_supply'. Default is 'internal'.\n
    "},{"location":"Config_Reference.html#board-specific-hardware-support","title":"Board specific hardware support","text":""},{"location":"Config_Reference.html#sx1509","title":"[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]\ni2c_address:\n#   I2C address used by this expander. Depending on the hardware\n#   jumpers this is one out of the following addresses: 62 63 112\n#   113. This parameter must be provided.\n#i2c_mcu:\n#i2c_bus:\n#i2c_software_scl_pin:\n#i2c_software_sda_pin:\n#i2c_speed:\n#   See the \"common I2C settings\" section for a description of the\n#   above parameters.\n
    "},{"location":"Config_Reference.html#samd_sercom","title":"[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]\nsercom:\n#   The name of the sercom bus to configure in the micro-controller.\n#   Available names are \"sercom0\", \"sercom1\", etc.. This parameter\n#   must be provided.\ntx_pin:\n#   MOSI pin for SPI communication, or SDA (data) pin for I2C\n#   communication. The pin must have a valid pinmux configuration\n#   for the given SERCOM peripheral. This parameter must be provided.\n#rx_pin:\n#   MISO pin for SPI communication. This pin is not used for I2C\n#   communication (I2C uses tx_pin for both sending and receiving).\n#   The pin must have a valid pinmux configuration for the given\n#   SERCOM peripheral. This parameter is optional.\nclk_pin:\n#   CLK pin for SPI communication, or SCL (clock) pin for I2C\n#   communication. The pin must have a valid pinmux configuration\n#   for the given SERCOM peripheral. This parameter must be provided.\n
    "},{"location":"Config_Reference.html#adc_scaled","title":"[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]\nvref_pin:\n#   The ADC pin to use for VREF monitoring. This parameter must be\n#   provided.\nvssa_pin:\n#   The ADC pin to use for VSSA monitoring. This parameter must be\n#   provided.\n#smooth_time: 2.0\n#   A time value (in seconds) over which the vref and vssa\n#   measurements will be smoothed to reduce the impact of measurement\n#   noise. The default is 2 seconds.\n
    "},{"location":"Config_Reference.html#replicape","title":"[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\"\n# virtual stepper enable pins (for steppers X, Y, Z, E, and H) and\n# \"replicape:power_x\" PWM output pins (for hotbed, e, h, fan0, fan1,\n# fan2, and fan3) that may then be used elsewhere in the config file.\n[replicape]\nrevision:\n#   The replicape hardware revision. Currently only revision \"B3\" is\n#   supported. This parameter must be provided.\n#enable_pin: !gpio0_20\n#   The replicape global enable pin. The default is !gpio0_20 (aka\n#   P9_41).\nhost_mcu:\n#   The name of the mcu config section that communicates with the\n#   Kalico \"linux process\" mcu instance. This parameter must be\n#   provided.\n#standstill_power_down: False\n#   This parameter controls the CFG6_ENN line on all stepper\n#   motors. True sets the enable lines to \"open\". The default is\n#   False.\n#stepper_x_microstep_mode:\n#stepper_y_microstep_mode:\n#stepper_z_microstep_mode:\n#stepper_e_microstep_mode:\n#stepper_h_microstep_mode:\n#   This parameter controls the CFG1 and CFG2 pins of the given\n#   stepper motor driver. Available options are: disable, 1, 2,\n#   spread2, 4, 16, spread4, spread16, stealth4, and stealth16. The\n#   default is disable.\n#stepper_x_current:\n#stepper_y_current:\n#stepper_z_current:\n#stepper_e_current:\n#stepper_h_current:\n#   The configured maximum current (in Amps) of the stepper motor\n#   driver. This parameter must be provided if the stepper is not in a\n#   disable mode.\n#stepper_x_chopper_off_time_high:\n#stepper_y_chopper_off_time_high:\n#stepper_z_chopper_off_time_high:\n#stepper_e_chopper_off_time_high:\n#stepper_h_chopper_off_time_high:\n#   This parameter controls the CFG0 pin of the stepper motor driver\n#   (True sets CFG0 high, False sets it low). The default is False.\n#stepper_x_chopper_hysteresis_high:\n#stepper_y_chopper_hysteresis_high:\n#stepper_z_chopper_hysteresis_high:\n#stepper_e_chopper_hysteresis_high:\n#stepper_h_chopper_hysteresis_high:\n#   This parameter controls the CFG4 pin of the stepper motor driver\n#   (True sets CFG4 high, False sets it low). The default is False.\n#stepper_x_chopper_blank_time_high:\n#stepper_y_chopper_blank_time_high:\n#stepper_z_chopper_blank_time_high:\n#stepper_e_chopper_blank_time_high:\n#stepper_h_chopper_blank_time_high:\n#   This parameter controls the CFG5 pin of the stepper motor driver\n#   (True sets CFG5 high, False sets it low). The default is True.\n
    "},{"location":"Config_Reference.html#other-custom-modules","title":"Other Custom Modules","text":""},{"location":"Config_Reference.html#palette2","title":"[palette2]","text":"

    Palette 2 multimaterial support - provides a tighter integration supporting Palette 2 devices in connected mode.

    This modules also requires [virtual_sdcard] and [pause_resume] for full functionality.

    If you use this module, do not use the Palette 2 plugin for Octoprint as they will conflict, and 1 will fail to initialize properly likely aborting your print.

    If you use Octoprint and stream gcode over the serial port instead of printing from virtual_sd, then remo M1 and M0 from Pausing commands in Settings > Serial Connection > Firmware & protocol will prevent the need to start print on the Palette 2 and unpausing in Octoprint for your print to begin.

    [palette2]\nserial:\n#   The serial port to connect to the Palette 2.\n#baud: 115200\n#   The baud rate to use. The default is 115200.\n#feedrate_splice: 0.8\n#   The feedrate to use when splicing, default is 0.8\n#feedrate_normal: 1.0\n#   The feedrate to use after splicing, default is 1.0\n#auto_load_speed: 2\n#   Extrude feedrate when autoloading, default is 2 (mm/s)\n#auto_cancel_variation: 0.1\n#   Auto cancel print when ping variation is above this threshold\n
    "},{"location":"Config_Reference.html#angle","title":"[angle]","text":"

    Magnetic hall angle sensor support for reading stepper motor angle shaft measurements using a1333, as5047d, or tle5012b SPI chips. The measurements are available via the API Server and motion analysis tool. See the G-Code reference for available commands.

    [angle my_angle_sensor]\nsensor_type:\n#   The type of the magnetic hall sensor chip. Available choices are\n#   \"a1333\", \"as5047d\", and \"tle5012b\". This parameter must be\n#   specified.\n#sample_period: 0.000400\n#   The query period (in seconds) to use during measurements. The\n#   default is 0.000400 (which is 2500 samples per second).\n#stepper:\n#   The name of the stepper that the angle sensor is attached to (eg,\n#   \"stepper_x\"). Setting this value enables an angle calibration\n#   tool. To use this feature, the Python \"numpy\" package must be\n#   installed. The default is to not enable angle calibration for the\n#   angle sensor.\ncs_pin:\n#   The SPI enable pin for the sensor. This parameter must be provided.\n#spi_speed:\n#spi_bus:\n#spi_software_sclk_pin:\n#spi_software_mosi_pin:\n#spi_software_miso_pin:\n#   See the \"common SPI settings\" section for a description of the\n#   above parameters.\n
    "},{"location":"Config_Reference.html#tools_calibrate","title":"\u26a0\ufe0f [tools_calibrate]","text":"

    Multi-toolhead nozzle offset calibration, using a 3-axis nozzle contact probe such as Zruncho3D's Nudge Probe.

    [tools_calibrate]\npin:\ntravel_speed: 20\n#   X and Y travel speed in mm/sec\nspread: 5\n#spread_x:\n#spread_y:\n#   X and Y travel distance around the probe\n#initial_spread:\n#initial_spread_x:\n#initial_spread_y:\n#   X and Y travel distance for the initial probe locating moves\nlower_z: 1.0\n#   Distance to lower in Z for contact with the sides of the probe\nspeed: 2\n#   The speed (in mm/sec) to retract between probes\nlift_speed: 4\n#   Z Lift speed after probing\nfinal_lift_z: 6\n#   Z lift distance after calibration, must be greater than any\n#   height variance between tools\ntrigger_to_bottom_z: 0.25\n#   Offset from probe trigger to vertical motion bottoms out.\n#   decrease if the nozzle is too high, increase if too low.\n#samples: 1\n#   The number of times to probe each point. The probed z-values will\n#   be averaged. The default is to probe 1 time.\n#sample_retract_dist: 2.0\n#   The distance (in mm) to lift the toolhead between each sample (if\n#   sampling more than once). The default is 2mm.\n#samples_result: average\n#   The calculation method when sampling more than once - either\n#   \"median\" or \"average\". The default is average.\n#samples_tolerance: 0.100\n#   The maximum Z distance (in mm) that a sample may differ from other\n#   samples. If this tolerance is exceeded then either an error is\n#   reported or the attempt is restarted (see\n#   samples_tolerance_retries). The default is 0.100mm.\n
    "},{"location":"Config_Reference.html#trad_rack","title":"[trad_rack]","text":"

    Trad Rack multimaterial system support. See the following documents from the TradRack repo for additional information:

    [trad_rack]\nselector_max_velocity:\n#   Maximum velocity (in mm/s) of the selector.\n#   This parameter must be specified.\nselector_max_accel:\n#   Maximum acceleration (in mm/s^2) of the selector.\n#   This parameter must be specified.\n#filament_max_velocity:\n#   Maximum velocity (in mm/s) for filament movement.\n#   Defaults to buffer_pull_speed.\n#filament_max_accel: 1500.0\n#   Maximum acceleration (in mm/s^2) for filament movement.\n#   The default is 1500.0.\ntoolhead_fil_sensor_pin:\n#   The pin on which the toolhead filament sensor is connected.\n#   If a pin is not specified, no toolhead filament sensor will\n#   be used.\nlane_count:\n#   The number of filament lanes. This parameter must be specified.\nlane_spacing:\n#   Spacing (in mm) between filament lanes.\n#   This parameter must be specified.\n#lane_offset_<lane index>:\n#   Options with a \"lane_offset_\" prefix may be specified for any of\n#   the lanes (from 0 to lane_count - 1). The option will apply an\n#   offset (in mm) to the corresponding lane's position. Lane offsets\n#   do not affect the position of any lanes besides the one specified\n#   in the option name. This option is intended for fine adjustment\n#   of each lane's position to ensure that the filament paths in the\n#   lane module and selector line up with each other.\n#   The default is 0.0 for each lane.\n#lane_spacing_mod_<lane index>:\n#   Options with a \"lane_spacing_mod_\" prefix may be specified for any\n#   of the lanes (from 0 to lane_count - 1). The option will apply an\n#   offset (in mm) to the corresponding lane's position, as well as\n#   any lane with a higher index. For example, if lane_spacing_mod_2\n#   is 4.0, any lane with an index of 2 or above will have its\n#   position increased by 4.0. This option is intended to account for\n#   variations in a lane module that will affect its position as well\n#   as the positions of any subsequent modules with a higher index.\n#   The default is 0.0 for each lane.\nservo_down_angle:\n#   The angle (in degrees) for the servo's down position.\n#   This parameter must be specified.\nservo_up_angle:\n#   The angle (in degrees) for the servo's up position.\n#   This parameter must be specified.\n#servo_wait_ms: 500\n#   Time (in milliseconds) to wait for the servo to complete moves\n#   between the up and down angles. The default is 500.\nselector_unload_length:\n#   Length (in mm) to retract a piece of filament out of the selector\n#   and back into the lane module after the selector sensor has been\n#   triggered or untriggered. This parameter must be specified.\n#selector_unload_length_extra: 0.0\n#   Extra length (in mm) that is added to selector_unload_length when\n#   retracting a piece of filament out of the selector and back into\n#   the lane module. After the retraction, the filament is moved\n#   forward by this length as well (so this option's value has no\n#   effect on the final position of the filament). This option may be\n#   useful when using Trad Rack with a motorized spool rewinder that\n#   senses tension or compression in the filament between the spool\n#   and Trad Rack in order to determine when to rotate the spool. The\n#   extra forward movement of the filament after retracting is\n#   intended to force the rewinder's sensor to detect tension in the\n#   filament, causing rewinding to cease immediately so the filament\n#   tip is not moved out of position by excess spool movement. The\n#   default is 0.0.\n#eject_length: 10.0\n#   Length (in mm) to eject the filament into the lane module past the\n#   length defined by selector_unload_length. The filament is ejected\n#   whenever unloading a depleted spool after a runout to make sure\n#   that filament segment is not loaded again until it has been\n#   replaced.\nbowden_length:\n#   Length (in mm) to quickly move filament through the bowden tube\n#   between Trad Rack and the toolhead during loads and unloads.\n#   See Tuning.md for details. This parameter must be specified.\nextruder_load_length:\n#   Length (in mm) to move filament into the extruder when loading the\n#   toolhead. See Tuning.md for details.\n#   This parameter must be specified.\nhotend_load_length:\n#   Length (in mm) to move filament into the hotend when loading the\n#   toolhead. See Tuning.md for details.\n#   This parameter must be specified.\ntoolhead_unload_length:\n#   Length (in mm) to move filament out of the toolhead during an\n#   unload. See Tuning.md for details. If toolhead_fil_sensor_pin is\n#   specified, this parameter must be specified.\n#   If toolhead_fil_sensor_pin is not specified, the default is\n#   extruder_load_length + hotend_load_length.\n#selector_sense_speed: 40.0\n#   Speed (in mm/s) when moving filament until the selector\n#   sensor is triggered or untriggered. See Tuning.md for details\n#   on when this speed is applied. The default is 40.0.\n#selector_unload_speed: 60.0\n#   Speed (in mm/s) to move filament when unloading the selector.\n#   The default is 60.0.\n#eject_speed: 80.0\n#   Speed (in mm/s) to move the filament when ejecting a filament\n#   segment into the lane module.\n#spool_pull_speed: 100.0\n#   Speed (in mm/s) to move filament through the bowden tube when\n#   loading from a spool. See Tuning.md for details.\n#   The default is 100.0.\n#buffer_pull_speed:\n#   Speed (in mm/s) to move filament through the bowden tube when\n#   unloading or loading from a buffer. See Tuning.md for details.\n#   Defaults to spool_pull_speed.\n#toolhead_sense_speed:\n#   Speed (in mm/s) when moving filament until the toolhead\n#   sensor is triggered or untriggered. See Tuning.md for details on\n#   when this speed is applied. Defaults to selector_sense_speed.\n#extruder_load_speed:\n#   Speed (in mm/s) to move filament into the extruder when loading\n#   the toolhead. See Tuning.md for details. The default is 60.0.\n#hotend_load_speed:\n#   Speed (in mm/s) to move filament into the hotend when loading the\n#   toolhead. See Tuning.md for details. The default is 7.0.\n#toolhead_unload_speed:\n#   Speed (in mm/s) to move filament when unloading the toolhead.\n#   See Tuning.md for details. Defaults to extruder_load_speed.\n#load_with_toolhead_sensor: True\n#   Whether to use the toolhead sensor when loading the toolhead.\n#   See Tuning.md for details. Defaults to True but is ignored if\n#   toolhead_fil_sensor_pin is not specified.\n#unload_with_toolhead_sensor: True\n#   Whether to use the toolhead sensor when unloading the toolhead.\n#   See Tuning.md for details. Defaults to True but is ignored if\n#   toolhead_fil_sensor_pin is not specified.\n#fil_homing_retract_dist: 20.0\n#   Distance (in mm) to retract filament away from a filament sensor\n#   before moving on to the next move. This retraction occurs whenever\n#   a filament sensor is triggered early during a fast move through\n#   the bowden tube. See Tuning.md for details. The default is 20.0.\n#target_toolhead_homing_dist:\n#   Target filament travel distance (in mm) when homing to the\n#   toolhead filament sensor during a load. See Tuning.md for details.\n#   Defaults to either 10.0 or toolhead_unload_length, whichever is\n#   greater.\n#target_selector_homing_dist:\n#   Target filament travel distance (in mm) when homing to the\n#   selector filament sensor during an unload. See Tuning.md for\n#   details. The default is 10.0.\n#bowden_length_samples: 10\n#   Maximum number of samples that are averaged to set bowden lengths\n#   for loading and unloading. See Tuning.md for details. The default\n#   is 10.\n#load_lane_time: 15\n#   Approximate maximum time (in seconds) to wait for filament to\n#   reach the selector filament sensor when loading a lane with the\n#   TR_LOAD_LANE gcode command. This time starts when the user is\n#   prompted to insert filament and determines when the command will\n#   be halted early if no filament is detected. The default is 15.\n#load_selector_homing_dist:\n#   Maximum distance to try to move filament when loading from a lane\n#   module to the selector filament sensor before halting the homing\n#   move. This value is not used by the TR_LOAD_LANE command but is\n#   used in similar scenarios that do not involve user interaction.\n#   Defaults to selector_unload_length * 2.\n#bowden_load_homing_dist:\n#   Maximum distance to try to move filament near the end of a\n#   toolhead load (during the slow homing move to the toolhead sensor)\n#   before halting the homing move. Defaults to bowden_length.\n#bowden_unload_homing_dist:\n#   Maximum distance to try to move filament near the end of a\n#   toolhead unload (during the slow homing move to the selector\n#   sensor) before halting the homing move. Defaults to bowden_length.\n#unload_toolhead_homing_dist:\n#   Maximum distance to try to move filament near the beginning of a\n#   toolhead unload (during the homing move to the toolhead sensor)\n#   before halting the homing move.\n#   Defaults to (extruder_load_length + hotend_load_length) * 2.\n#sync_to_extruder: False\n#   Syncs Trad Rack's filament driver to the extruder during printing,\n#   as well as during any extrusion moves within toolhead loading or\n#   unloading that would normally involve only the extruder.\n#   The default is False.\n#user_wait_time: 15\n#   Time (in seconds) to wait for the user to take an action\n#   before continuing automatically. If set to -1, Trad Rack will wait\n#   for the user indefinitely. This value is currently used by the\n#   TR_LOCATE_SELECTOR gcode command. The default is 15.\n#register_toolchange_commands: True\n#   Whether to register gcode commands T0, T1, T2, etc. so that they\n#   can be used to initiate toolchanges with Trad Rack. If set to\n#   False, the TR_LOAD_TOOLHEAD command can still be used as a\n#   substitute to initiate toolchanges. The default is True.\n#save_active_lane: True\n#   Whether to save the active lane to disk whenever it is set using\n#   save_variables. If set to True, the TR_LOCATE_SELECTOR gcode\n#   command will infer the active lane if the selector filament sensor\n#   is triggered and an active lane was saved previously.\n#   The default is True.\n#log_bowden_lengths: False\n#   Whether to log bowden load length data and bowden unload length\n#   data (to ~/bowden_load_lengths.csv and ~/bowden_unload_lengths.csv\n#   respectively). The default is False.\n#pre_unload_gcode:\n#   Gcode command template that is run before the toolhead is\n#   unloaded. The default is to run no extra commands.\n#post_unload_gcode:\n#   Gcode command template that is run after the toolhead is\n#   unloaded. The default is to run no extra commands.\n#pre_load_gcode:\n#   Gcode command template that is run before the toolhead is\n#   loaded. The default is to run no extra commands.\n#post_load_gcode:\n#   Gcode command template that is run after the toolhead is\n#   loaded. The default is to run no extra commands.\n#pause_gcode:\n#   Gcode command template that is run whenever Trad Rack needs to\n#   pause the print (usually due to a failed load or unload). The\n#   default is to run the PAUSE gcode command.\n#resume_gcode:\n#   Gcode command template that is run whenever the TR_RESUME command\n#   needs to resume the print. The default is to run the RESUME\n#   gcode command.\n
    "},{"location":"Config_Reference.html#common-bus-parameters","title":"Common bus parameters","text":""},{"location":"Config_Reference.html#common-spi-settings","title":"Common SPI settings","text":"

    The following parameters are generally available for devices using an SPI bus.

    #spi_speed:\n#   The SPI speed (in hz) to use when communicating with the device.\n#   The default depends on the type of device.\n#spi_bus:\n#   If the micro-controller supports multiple SPI busses then one may\n#   specify the micro-controller bus name here. The default depends on\n#   the type of micro-controller.\n#spi_software_sclk_pin:\n#spi_software_mosi_pin:\n#spi_software_miso_pin:\n#   Specify the above parameters to use \"software based SPI\". This\n#   mode does not require micro-controller hardware support (typically\n#   any general purpose pins may be used). The default is to not use\n#   \"software spi\".\n
    "},{"location":"Config_Reference.html#common-i2c-settings","title":"Common I2C settings","text":"

    The following parameters are generally available for devices using an I2C bus.

    Note that Kalico's current micro-controller support for I2C is generally not tolerant to line noise. Unexpected errors on the I2C wires may result in Kalico raising a run-time error. Kalico'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 Kalico micro-controller implementations only support an i2c_speed of 100000 (standard mode, 100kbit/s). The Kalico \"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 Kalico \"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 Kalico micro-controllers use a 100000 rate and ignore the i2c_speed parameter.

    #i2c_address:\n#   The i2c address of the device. This must specified as a decimal\n#   number (not in hex). The default depends on the type of device.\n#i2c_mcu:\n#   The name of the micro-controller that the chip is connected to.\n#   The default is \"mcu\".\n#i2c_bus:\n#   If the micro-controller supports multiple I2C busses then one may\n#   specify the micro-controller bus name here. The default depends on\n#   the type of micro-controller.\n#i2c_software_scl_pin:\n#i2c_software_sda_pin:\n#   Specify these parameters to use micro-controller software based\n#   I2C \"bit-banging\" support. The two parameters should the two pins\n#   on the micro-controller to use for the scl and sda wires. The\n#   default is to use hardware based I2C support as specified by the\n#   i2c_bus parameter.\n#i2c_speed:\n#   The I2C speed (in Hz) to use when communicating with the device.\n#   The Kalico implementation on most micro-controllers is hard-coded\n#   to 100000 and changing this value has no effect. The default is\n#   100000. Linux, RP2040 and ATmega support 400000.\n
    "},{"location":"Config_Reference_Bleeding_Edge.html","title":"Configuration reference for Bleeding Edge features","text":"

    This document is a reference for options available in the Kalico config file for bleeding edge features. Refer to the Bleeding Edge Documentation for details on specific features.

    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 Kalico and choosing an initial config file.

    "},{"location":"Config_Reference_Bleeding_Edge.html#high-precision-stepping-and-new-stepcompress-protocol","title":"High precision stepping and new stepcompress protocol","text":"

    This feature is enabled during Kalico firmware compile by selecting \"High-precision stepping support\" option in menuconfig. The firmware then needs to be flashed to all MCU(s) using this feature.

    The following configuration line should be added to each stepper in printer.cfg. For example in a CoreXY system the config line would be added to [stepper_x] and [stepper_y] so that it is enabled in both steppers controlling the X-Y movement of the toolhead.

    [stepper_... ]\nhigh_precision_step_compress: True\n

    Note that enabling this feature in the config without recompiling and flashing the firmware will give an error.

    "},{"location":"Config_Reference_Bleeding_Edge.html#input-shaper","title":"Input shaper","text":""},{"location":"Config_Reference_Bleeding_Edge.html#input_shaper","title":"[input_shaper]","text":"

    Extruder PA Synchronization with Input Shaping

    [input_shaper]\nenabled_extruders: extruder\n

    Smooth Input Shapers

    [input_shaper]\nshaper_type:\n#   A type of the input shaper to use for both X and Y axes. Supported\n#   shapers are smooth_zv, smooth_mzv, smooth_ei, smooth_2hump_ei, smooth_zvd_ei,\n#   smooth_si, mzv, ei, 2hump_ei.\n#shaper_type_x:\n#shaper_type_y:\n#   If shaper_type is not set, these two parameters can be used to\n#   configure different input shapers for X and Y axes. The same\n#   values are supported as for shaper_type parameter.\nsmoother_freq_x: 0\n#  A frequency (in Hz) of the smooth input shaper for X axis.\nsmoother_freq_y: 0\n#  A frequency (in Hz) of the smooth input shaper for Y axis.\n#damping_ratio_x: 0.1\n#damping_ratio_y: 0.1\n#   Damping ratios of vibrations of X and Y axes used by input shapers\n#   to improve vibration suppression. Default value is 0.1 which is a\n#   good all-round value for most printers. In most circumstances this\n#   parameter requires no tuning and should not be changed.\n#   Note: Damping ratios are not currently supported for input smoothers.\n
    "},{"location":"Config_Reference_Bleeding_Edge.html#test-print-utilities","title":"Test print utilities","text":""},{"location":"Config_Reference_Bleeding_Edge.html#ringing_test","title":"[ringing_test]","text":"

    Ringing tower test print utility which isolates vibrations to one axis at a time.

    [ringing_test]\nsize: 100\n#   X-Y Size of tower footprint (mm)\nheight: 60\n#   Height of of tower (mm)\nband: 5\n#   Height for each ringing step (mm)\nperimeters: 2\n#   Number of perimeters to be printed for the tower\nvelocity: 80\n#   Is the velocity one must use as V in a formula V * N / D when\n#   calculating the resonance frequency. N and D are the number of\n#   oscillations and the distance between them as usual:\nbrim_velocity: 30\n#   Speed for brim printing in (mm/s)\naccel_start: 1500\n#   The acceleration of the start of the test\naccel_step: 500\n#   The increment of the acceleration every `band` (mm/s^2)\nlayer_height: 0.2\nfirst_layer_height: 0.2\nfilament_diameter: 1.75\n\n#   Parameters that are computed automatically, but may be adjusted if necessary\n\n#center_x:\n#   Center of the bed by default (if detected correctly)\n#center_y:\n#   Center of the bed by default (if detected correctly)\n#brim_width:\n#   Computed based on the model size, but may be increased\n\n#   Parameters that are better left at their default values\n\n#notch: 1\n#   Size of the notch in mm\n#notch_offset:\n#   0.275 * size by default\n#deceleration_points: 100\n
    "},{"location":"Config_Reference_Bleeding_Edge.html#pa_test","title":"[pa_test]","text":"

    Pressure advance tower test print utility

    [pa_test]\nsize_x: 100\n#    X dimension tower size  (mm)\nsize_y: 50\n#    Y dimension tower size  (mm)\nheight: 50\n#   Height of tower (mm)\norigin_x:\n#   Center of the bed in x\norigin_y:\n#   Center of the bed in y\nlayer_height: 0.2\nfirst_layer_height: 0.3\nperimeters: 2\n#   Number of perimeters to be printed for the tower\nbrim_width: 10\n#   Width of brim (mm)\nslow_velocity: 20\n#   Start velocity for PA test segment (mm/s)\nmedium_velocity: 50\n#   Medium velocity for PA test segment (mm/s)\nfast_velocity: 80\n#   End velocity for PA test segment (mm/s)\nfilament_diameter: 1.75\n
    "},{"location":"Config_checks.html","title":"Configuration checks","text":"

    This document provides a list of steps to help confirm the pin settings in the Kalico 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 Kalico 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.

    "},{"location":"Config_checks.html#verify-temperature","title":"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.

    "},{"location":"Config_checks.html#verify-m112","title":"Verify M112","text":"

    Navigate to the command console and issue an M112 command in the terminal box. This command requests Kalico 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.

    "},{"location":"Config_checks.html#verify-heaters","title":"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.

    "},{"location":"Config_checks.html#verify-stepper-motor-enable-pin","title":"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\").

    "},{"location":"Config_checks.html#verify-endstops","title":"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).

    "},{"location":"Config_checks.html#verify-stepper-motors","title":"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.

    "},{"location":"Config_checks.html#verify-extruder-motor","title":"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.

    "},{"location":"Config_checks.html#calibrate-pid-settings","title":"Calibrate PID settings","text":"

    Kalico 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

    "},{"location":"Config_checks.html#next-steps","title":"Next steps","text":"

    This guide is intended to help with basic verification of pin settings in the Kalico configuration file. Be sure to read the bed leveling guide. Also see the Slicers document for information on configuring a slicer with Kalico.

    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.

    "},{"location":"Contact.html","title":"Contact","text":"

    This document provides contact information for Kalico. Kalico a community-maintained fork of the Kalico firmware.

    "},{"location":"Contact.html#discord","title":"Discord","text":"

    Kalico has a dedicated Discord server where you can chat with the developers and users of Kalico in real-time.

    You can join the server here: kalico.gg/discord

    "},{"location":"Contact.html#i-have-a-question-about-kalico","title":"I have a question about Kalico","text":"

    Many questions we receive are already answered in the Overview. Please be sure to to read the documentation and follow the directions provided there.

    If you are interested in sharing your knowledge and experience with other Kalico users then you can join the Kalico Discord server

    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.

    "},{"location":"Contact.html#i-have-a-feature-request","title":"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 on the GitHub issues page and pull requests page

    There also are discussions between collaborators on the Kalico Discord server.

    "},{"location":"Contact.html#help-it-doesnt-work","title":"Help! It doesn't work!","text":"

    If you are experiencing problems we recommend you carefully read the Overview 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 Kalico 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.

    "},{"location":"Contact.html#i-found-a-bug-in-the-kalico-software","title":"I found a bug in the Kalico software","text":"

    Kalico is an open-source project and we appreciate when collaborators diagnose errors in the software.

    Problems should be reported on the Discord server

    There is important information that will be needed in order to fix a bug. Please follow these steps:

    1. Make sure you are running unmodified code from https://github.com/KalicoCrew/kalico. 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/KalicoCrew/kalico prior to reporting.
    2. If possible, run an M112 command immediately after the undesirable event occurs. This causes Kalico to go into a \"shutdown state\" and it will cause additional debugging information to be written to the log file.
    3. Obtain the Kalico log file from the event. The log file has been engineered to answer common questions the Kalico developers have about the software and its environment (software version, hardware type, configuration, event timing, and hundreds of other questions).
      1. Dedicated Kalico web interfaces have the ability to directly obtain the Kalico 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).
      2. Copy the log file to your desktop so that it can be attached to an issue report.
      3. 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.
      4. It is a good idea to compress the log file with zip or gzip.
    4. Open a new thread on the Discord server and provide a clear description of the problem. Other Kalico contributors will need to understand what steps were taken, what the desired outcome was, and what outcome actually occurred. The compressed Kalico log file should be attached to that topic.
    "},{"location":"Contact.html#i-am-making-changes-that-id-like-to-include-in-kalico","title":"I am making changes that I'd like to include in Kalico","text":"

    Kalico 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 on the Discord server

    "},{"location":"Debugging.html","title":"Debugging","text":"

    This document describes some of the Kalico debugging tools.

    "},{"location":"Debugging.html#running-the-regression-tests","title":"Running the regression tests","text":"

    The main Kalico 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\n

    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\n~/klippy-env/bin/python ~/klipper/scripts/test_klippy.py -d dict/ ~/klipper/test/klippy/*.test\n
    "},{"location":"Debugging.html#manually-sending-commands-to-the-micro-controller","title":"Manually sending commands to the micro-controller","text":"

    Normally, the host klippy.py process would be used to translate gcode commands to Kalico micro-controller commands. However, it's also possible to manually send these MCU commands (functions marked with the DECL_COMMAND() macro in the Kalico source code). To do so, run:

    ~/klippy-env/bin/python ./klippy/console.py /tmp/pseudoserial\n

    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

    "},{"location":"Debugging.html#translating-gcode-files-to-micro-controller-commands","title":"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\nmake\n

    Once the above is done it is possible to run Kalico 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\n

    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\n

    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.

    "},{"location":"Debugging.html#motion-analysis-and-data-logging","title":"Motion analysis and data logging","text":"

    Kalico supports logging its internal motion history, which can be later analyzed. To use this feature, Kalico 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\n

    This command will connect to the Kalico 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\nsudo apt-get install python-matplotlib\n

    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\n

    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)\"]]'\n

    The list of available datasets can be found using the -l option - for example:

    ~/klipper/scripts/motan/motan_graph.py -l\n

    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\"]]'\n

    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

    "},{"location":"Debugging.html#generating-load-graphs","title":"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\nsudo apt-get install python-matplotlib\n

    Then graphs can be produced with:

    ~/klipper/scripts/graphstats.py /tmp/klippy.log -o loadgraph.png\n

    One can then view the resulting loadgraph.png file.

    Different graphs can be produced. For more information run: ~/klipper/scripts/graphstats.py --help

    "},{"location":"Debugging.html#extracting-information-from-the-klippylog-file","title":"Extracting information from the klippy.log 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\ncd work_directory\ncp /tmp/klippy.log .\n~/klipper/scripts/logextract.py ./klippy.log\n

    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.

    "},{"location":"Debugging.html#testing-with-simulavr","title":"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\ncd simulavr\nmake python\nmake build\n

    Make sure a file like ./build/pysimulavr/_pysimulavr.*.so is present after the above compilation:

    ls ./build/pysimulavr/_pysimulavr.*.so\n

    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\nsudo apt install g++ make cmake swig rst2pdf help2man texinfo\nmake cfgclean python debian\nsudo dpkg -i build/debian/python3-simulavr*.deb\n

    To compile Kalico for use in simulavr, run:

    cd /path/to/kalico\nmake menuconfig\n

    and compile the micro-controller software for an AVR atmega644p and select SIMULAVR software emulation support. Then one can compile Kalico (run make) and then start the simulation with:

    PYTHONPATH=/path/to/simulavr/build/pysimulavr/ ./scripts/avrsim.py out/klipper.elf\n

    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\n

    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 Kalico 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\n
    "},{"location":"Debugging.html#using-simulavr-with-gtkwave","title":"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\n

    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\n
    "},{"location":"Delta_Calibrate.html","title":"Delta calibration","text":"

    This document describes Kalico'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.

    "},{"location":"Delta_Calibrate.html#automatic-vs-manual-probing","title":"Automatic vs manual probing","text":"

    Kalico 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.

    "},{"location":"Delta_Calibrate.html#basic-delta-calibration","title":"Basic delta calibration","text":"

    Kalico 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\nDELTA_CALIBRATE METHOD=manual\n

    After probing the seven points new delta parameters will be calculated. Save and apply these parameters by running:

    SAVE_CONFIG\n

    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.

    "},{"location":"Delta_Calibrate.html#enhanced-delta-calibration","title":"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 Kalico with a comma separated list of floating point numbers:

    DELTA_ANALYZE CENTER_DISTS=<a_dist>,<far_c_dist>,<b_dist>,<far_a_dist>,<c_dist>,<far_b_dist>\n

    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 Kalico:

    DELTA_ANALYZE OUTER_DISTS=<a_to_far_c>,<far_c_to_b>,<b_to_far_a>,<far_a_to_c>,<c_to_far_b>,<far_b_to_a>\n

    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 Kalico:

    DELTA_ANALYZE CENTER_PILLAR_WIDTHS=<a>,<b>,<c>\n

    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 Kalico:

    DELTA_ANALYZE OUTER_PILLAR_WIDTHS=<a>,<far_c>,<b>,<far_a>,<c>,<far_b>\n

    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\n

    (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\n

    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\n

    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.

    "},{"location":"Delta_Calibrate.html#additional-notes","title":"Additional notes","text":" "},{"location":"Delta_Calibrate.html#using-bed-mesh-on-a-delta","title":"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.

    "},{"location":"Dockable_Probe.html","title":"Dockable Probe","text":"

    Dockable probes are typically microswitches mounted to a printed body that attaches to the toolhead through some means of mechanical coupling. This coupling is commonly done with magnets though there is support for a variety of designs including servo and stepper actuated couplings.

    "},{"location":"Dockable_Probe.html#basic-configuration","title":"Basic Configuration","text":"

    To use a dockable probe the following options are required at a minimum. Some users may be transitioning from a macro based set of commands and many of the options for the [probe] config section are the same. The [dockable_probe] module is first and foremost a [probe] but with additional functionality. Most of the options that can be specified for [probe] are valid for [dockable_probe].

    [dockable_probe]\npin:\nz_offset:\nsample_retract_dist:\napproach_position:\ndock_position:\ndetach_position:\n(check_open_attach: OR probe_sense_pin:) AND/OR dock_sense_pin:\n
    "},{"location":"Dockable_Probe.html#attaching-and-detaching-positions","title":"Attaching and Detaching Positions","text":" Command Module restore_th=True restore_th=False notes ATTACH_PROBE dockable_probe.py True False Z_TILT_ADJUST probe.py True False QUAD_GANTRY_LEVEL probe.py True False PROBE probe.py True True PROBE_ACCURACY probe.py True True AXIS_TWIST_COMPENSATION probe.py True True CALIBRATE_Z z_calibration.py True False G28 Z probe.py True True only for z_virtual_endstop"},{"location":"Dockable_Probe.html#position-examples","title":"Position Examples","text":"

    Probe mounted on frame at back of print bed at a fixed Z position. To attach the probe, the toolhead will move back and then forward. To detach, the toolhead will move back, and then to the side.

    +--------+\n|   p>   |\n|   ^    |\n|        |\n+--------+\n
    approach_position: 150, 300, 5\ndock_position: 150, 330, 5\ndetach_position: 170, 330\n

    Probe mounted at side of moving gantry with fixed bed. Here the probe is attachable regardless of the Z position. To attach the probe, the toolhead will move to the side and back. To detach the toolhead will move to the side and then forward.

    +--------+\n|        |\n| p<     |\n| v      |\n+--------+\n
    approach_position: 50, 150\ndock_position: 10, 150\ndetach_position: 10, 130\n

    Probe mounted at side of fixed gantry with bed moving on Z. Probe is attachable regardless of Z but force Z hop for safety. The toolhead movement is the same as above.

    +--------+\n|        |\n| p<     |\n| v      |\n+--------+\n
    approach_position: 50, 150\ndock_position: 10, 150\ndetach_position: 10, 130\nz_hop: 15\n

    Euclid style probe that requires the attach and detach movements to happen in opposite order. Attach: approach, move to dock, extract. Detach: move to extract position, move to dock, move to approach position. The approach and detach positions are the same, as are the extract and insert positions.

    Attach:\n+--------+\n|        |\n| p<     |\n| v      |\n+--------+\nDetach:\n+--------+\n|        |\n| p>     |\n| ^      |\n+--------+\n
    approach_position: 50, 150\ndock_position: 10, 150\nextract_position: 10, 130\ndetach_position: 50, 150\nz_hop: 15\n
    "},{"location":"Dockable_Probe.html#homing","title":"Homing","text":"

    No configuration specific to the dockable probe is required. However, when using the probe as a virtual endstop, it's required to use [safe_z_home] or [homing_override].

    "},{"location":"Dockable_Probe.html#examples-for-probe-as-virtual-endstop","title":"Examples for probe as virtual endstop","text":"
    [homing_override]\naxes: xyz\nset_position_z: 0\ngcode:\n\n  G90\n  {% set home_all = 'X' not in params and 'Y' not in params and 'Z' not in params %}\n\n  {% if home_all or 'X' in params %}\n    G0 Z10\n    G28 X\n  {% endif %}\n\n  {% if home_all or 'Y' in params %}\n    G0 Z10\n    G28 Y\n  {% endif %}\n\n  {% if home_all or 'Z' in params %}\n    ATTACH_PROBE\n    MOVE_AVOIDING_DOCK X=150 Y=150 SPEED=300\n    # Probe is already attached, no need to make a return trip to the dock.\n    G28 Z  \n  {% endif %}\n
    [safe_z_home]\nhome_xy_position: 150,150\nz_hop: 10\n
    "},{"location":"Dockable_Probe.html#homing-override","title":"Homing override","text":""},{"location":"Dockable_Probe.html#safe_z_home","title":"safe_z_home","text":"While homing Z with safe_z_home, the toolhead will move to home_xy_position then will move to the dock and return back to home_xy_position."},{"location":"Dockable_Probe.html#probe-attachment-verification","title":"Probe Attachment Verification","text":"

    Given the nature of this type of probe, it is necessary to verify whether or not it has successfully attached prior to attempting a probing move. Several methods can be used to verify probe attachment states.

    "},{"location":"Dockable_Probe.html#tool-velocities","title":"Tool Velocities","text":" "},{"location":"Dockable_Probe.html#safe-dock-area","title":"Safe dock area","text":"

    A safe dock area is defined to avoid collision with the dock during probe attachment/detachment moves. see MOVE_AVOIDING_DOCK.

    "},{"location":"Dockable_Probe.html#move_avoiding_dock-description","title":"MOVE_AVOIDING_DOCK description","text":"

    The strategy described below is used by the attach and detach commands to avoid dock collision.

    Note

    The default safe_position is approach_position. To help determine the avoiding path and prevent moving out of range, it should be configured as a point next to the safe area, farthest from the \"move out of range\" zone.

    Several cases are illustrated:

    1. Moving from A to B: The requested trajectory passes over the safe dock area, so the calculated trajectory passes around the dock area, close to the safe position.
    2. Moving from A' to B: The toolhead leaves the safe dock area by the shortest path and reaches B as before.
    3. Moving from A to B': Since B' is in the safe area, the toolhead stops at B\".
    4. Moving from A' to B': The toolhead leaves the safe dock area by the shortest path.
    "},{"location":"Dockable_Probe.html#dockable-probe-gcodes","title":"Dockable Probe Gcodes","text":""},{"location":"Dockable_Probe.html#general","title":"General","text":"

    ATTACH_PROBE

    This command will move the toolhead to the dock, attach the probe, and return it to its previous position. If the probe is already attached, the command does nothing.

    This command will call MOVE_TO_APPROACH_PROBE, MOVE_TO_DOCK_PROBE, and MOVE_TO_EXTRACT_PROBE.

    DETACH_PROBE

    This command will move the toolhead to the dock, detach the probe, and return it to its previous position. If the probe is already detached, the command will do nothing.

    This command will call MOVE_TO_APPROACH_PROBE, MOVE_TO_DOCK_PROBE, and MOVE_TO_DETACH_PROBE.

    "},{"location":"Dockable_Probe.html#individual-movements","title":"Individual Movements","text":"

    These commands are useful during setup to prevent the full attach/detach sequence from crashing into the bed or damaging the probe/dock.

    If your probe has special setup/teardown steps (e.g. moving a servo), accommodating that could be accomplished by overriding these gcodes.

    MOVE_TO_APPROACH_PROBE

    This command will move the toolhead to the approach_position. It can be overridden to move a servo if that's required for attaching your probe.

    MOVE_TO_DOCK_PROBE

    This command will move the toolhead to the dock_position.

    MOVE_TO_EXTRACT_PROBE

    This command will move the toolhead to the extract_position.

    MOVE_TO_INSERT_PROBE

    This command will move the toolhead to the insert_position.

    MOVE_TO_DETACH_PROBE

    This command will move the toolhead to the detach_position. It can be overridden to move a servo if that's required for detaching your probe.

    MOVE_AVOIDING_DOCK [X=<value>] [Y=<value>] [SPEED=<value>]

    This command will move the toolhead to the absolute coordinates, avoiding the safe dock area.

    "},{"location":"Dockable_Probe.html#status","title":"Status","text":"

    QUERY_DOCKABLE_PROBE

    Responds in the gcode terminal with the current probe status. Valid states are UNKNOWN, ATTACHED, and DOCKED. This is useful during setup to confirm probe configuration is working as intended.

    SET_DOCKABLE_PROBE AUTO_ATTACH_DETACH=0|1

    Enable/Disable the automatic attaching/detaching of the probe during actions that require the probe.

    This command can be helpful in print-start macros where multiple actions will be performed with the probe and there's no need to detach the probe. For example:

    SET_DOCKABLE_PROBE AUTO_ATTACH_DETACH=0\nG28\nATTACH_PROBE                             # Explicitly attach the probe\nQUAD_GANTRY_LEVEL                        # Tram the gantry parallel to the bed\nBED_MESH_CALIBRATE                       # Create a bed mesh\nDETACH_PROBE                             # Manually detach the probe\nSET_DOCKABLE_PROBE AUTO_ATTACH_DETACH=1  # Make sure the probe is attached in future\n
    "},{"location":"Dockable_Probe.html#typical-probe-execution-flow","title":"Typical probe execution flow","text":""},{"location":"Dockable_Probe.html#probing-is-started","title":"Probing is Started:","text":" "},{"location":"Dockable_Probe.html#probing-is-finished","title":"Probing is Finished:","text":" "},{"location":"Endstop_Phase.html","title":"Endstop phase","text":"

    This document describes Kalico'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. Kalico'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 Kalico 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.)

    "},{"location":"Endstop_Phase.html#calibrating-endstop-phases","title":"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]\n

    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, Kalico 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\n

    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\n
    "},{"location":"Endstop_Phase.html#additional-notes","title":"Additional notes","text":" "},{"location":"Example_Configs.html","title":"Example configurations","text":"

    This document contains guidelines for contributing an example Kalico configuration to the Kalico 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.

    "},{"location":"Example_Configs.html#guidelines","title":"Guidelines","text":"
    1. Select the appropriate config filename prefix:
      1. The printer prefix is used for stock printers sold by a mainstream manufacturer.
      2. The generic prefix is used for a 3d printer board that may be used in many different types of printers.
      3. 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.
      4. The sample prefix is used for config \"snippets\" that one may copy-and-paste into the main config file.
      5. 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.
    2. 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.
    3. Do not use spaces or special characters in the config filename. The filename should contain only characters A-Z, a-z, 0-9, -, and ..
    4. Kalico 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.
    5. The example configuration should be for the \"stock\" configuration of the printer. (There are too many \"customized\" configurations to track in the main Kalico 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.
    6. Only specify those devices present on the given printer or board. Do not specify settings specific to your particular setup.
      1. 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.
      2. 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.
      3. 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.
      4. 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.
    7. Where possible, it is best to use the same wording, phrasing, indentation, and section ordering as the existing config files.
      1. 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\".
      2. 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.)
      3. 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.
      4. Use field: value syntax instead of field=value.
      5. 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.
      6. 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.
      7. Where possible, lines should not exceed 80 columns.
      8. 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.
    8. Do not use any deprecated features in the example config file.
    9. 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.
    10. All known boards that Kalico 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.

    "},{"location":"Exclude_Object.html","title":"Exclude Objects","text":"

    The [exclude_object] module allows Kalico 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 Kalico 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.

    "},{"location":"Exclude_Object.html#workflow-overview","title":"Workflow Overview","text":"

    A typical workflow for printing a file might look like this:

    1. 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.
    2. When printing starts, Kalico will reset the [exclude_object] status.
    3. When Kalico processes the EXCLUDE_OBJECT_DEFINE block, it will update the status with the known objects and pass it on to clients.
    4. The client may use that information to present a UI to the user so that progress can be tracked. Kalico will update the status to include the currently printing object which the client can use for display purposes.
    5. If the user requests that an object be cancelled, the client will issue an EXCLUDE_OBJECT NAME=<name> command to Kalico.
    6. When Kalico process the command, it will add the object to the list of excluded objects and update the status for the client.
    7. The client will receive the updated status from Kalico and can use that information to reflect the object's status in the UI.
    8. When printing finishes, the [exclude_object] status will continue to be available until another action resets it.
    "},{"location":"Exclude_Object.html#the-gcode-file","title":"The GCode File","text":"

    The specialized gcode processing needed to support excluding objects does not fit into Kalico's core design goals. Therefore, this module requires that the file is processed before being sent to Kalico 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 Kalico. A reference post-processing script is available both as an executable and a python library, see cancelobject-preprocessor.

    "},{"location":"Exclude_Object.html#object-definitions","title":"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

    "},{"location":"Exclude_Object.html#status-information","title":"Status Information","text":"

    The state of this module is provided to clients by the exclude_object status.

    The status is reset when:

    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 Kalico 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 Kalico looks ahead to process upcoming gcode, there may be a delay between when the command is issued and when the status is updated.

    "},{"location":"FAQ.html","title":"Frequently Asked Questions","text":""},{"location":"FAQ.html#how-can-i-donate-to-the-project","title":"How can I donate to the project?","text":"

    Thank you for your support. See the Sponsors page for information.

    "},{"location":"FAQ.html#how-do-i-calculate-the-rotation_distance-config-parameter","title":"How do I calculate the rotation_distance config parameter?","text":"

    See the rotation distance document.

    "},{"location":"FAQ.html#wheres-my-serial-port","title":"Where's 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\n

    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\nmake flash FLASH_DEVICE=/dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0\nsudo service klipper start\n

    and the updated config might look like:

    [mcu]\nserial: /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0\n

    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.

    "},{"location":"FAQ.html#when-the-micro-controller-restarts-the-device-changes-to-devttyusb1","title":"When the micro-controller restarts the device changes to /dev/ttyUSB1","text":"

    Follow the directions in the \"Where's my serial port?\" section to prevent this from occurring.

    "},{"location":"FAQ.html#the-make-flash-command-doesnt-work","title":"The \"make flash\" command doesn't 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 Kalico 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.

    "},{"location":"FAQ.html#how-do-i-change-the-serial-baud-rate","title":"How do I change the serial baud rate?","text":"

    The recommended baud rate for Kalico is 250000. This baud rate works well on all micro-controller boards that Kalico 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 Kalico printer.cfg file will also need to be updated to match that baud rate (see the config reference for details). For example:

    [mcu]\nbaud: 250000\n

    The baud rate shown on the OctoPrint web page has no impact on the internal Kalico micro-controller baud rate. Always set the OctoPrint baud rate to 250000 when using Kalico.

    The Kalico 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.

    "},{"location":"FAQ.html#can-i-run-kalico-on-something-other-than-a-raspberry-pi-3","title":"Can I run Kalico on something other than a Raspberry Pi 3?","text":"

    The recommended hardware is a Raspberry Pi 2, Raspberry Pi 3, or Raspberry Pi 4.

    Kalico will run on a Raspberry Pi 1 and on the Raspberry Pi Zero, but these boards don't have enough processing power to run OctoPrint well. It is common for print stalls to occur on these slower machines when printing directly from OctoPrint. (The printer may move faster than OctoPrint can send movement commands.) If you wish to run on one one of these slower boards anyway, consider using the \"virtual_sdcard\" feature when printing (see config reference for details).

    For running on the Beaglebone, see the Beaglebone specific installation instructions.

    Kalico has been run on other machines. The Kalico 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 Kalico 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 Kalico host software on a shared general-purpose desktop or server class machine, then note that Kalico 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 Kalico 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 Kalico to report seemingly random \"Lost communication with MCU\" errors.) If you install Kalico on one of these distributions you may need to disable that package.

    "},{"location":"FAQ.html#can-i-run-multiple-instances-of-kalico-on-the-same-host-machine","title":"Can I run multiple instances of Kalico on the same host machine?","text":"

    It is possible to run multiple instances of the Kalico host software, but doing so requires Linux admin knowledge. The Kalico 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\n

    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\n

    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.

    "},{"location":"FAQ.html#do-i-have-to-use-octoprint","title":"Do I have to use OctoPrint?","text":"

    The Kalico software is not dependent on OctoPrint. It is possible to use alternative software to send commands to Kalico, but doing so requires Linux admin knowledge.

    Kalico 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 Kalico as long as it can be configured to use \"/tmp/printer\" for the printer serial port.

    "},{"location":"FAQ.html#why-cant-i-move-the-stepper-before-homing-the-printer","title":"Why can't 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.

    "},{"location":"FAQ.html#why-is-the-z-position_endstop-set-to-05-in-the-default-configs","title":"Why is the Z position_endstop set to 0.5 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.

    "},{"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","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","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. Kalico 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.

    "},{"location":"FAQ.html#my-tmc-motor-driver-turns-off-in-the-middle-of-a-print","title":"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 Kalico. A workaround for a TMC2208 \"stealthchop\" driver problem was added to Kalico in mid-March of 2020.

    "},{"location":"FAQ.html#i-keep-getting-random-lost-communication-with-mcu-errors","title":"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:

    "},{"location":"FAQ.html#my-raspberry-pi-keeps-rebooting-during-prints","title":"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.

    "},{"location":"FAQ.html#when-i-set-restart_methodcommand-my-avr-device-just-hangs-on-a-restart","title":"When I set restart_method=command 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.

    "},{"location":"FAQ.html#will-the-heaters-be-left-on-if-the-raspberry-pi-crashes","title":"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.

    "},{"location":"FAQ.html#how-do-i-convert-a-marlin-pin-number-to-a-kalico-pin-name","title":"How do I convert a Marlin pin number to a Kalico 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 Kalico alias ar23) and the prefix \"analog\" instead of \"A\" (eg, Arduino pin A14 is Kalico alias analog14).

    Long answer: Kalico 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 Kalico code uses the standard pin names defined by the micro-controller.

    "},{"location":"FAQ.html#do-i-have-to-wire-my-device-to-a-specific-type-of-micro-controller-pin","title":"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 Kalico to use a pin that is not analog capable, Kalico will report a \"Not a valid ADC pin\" error.

    PWM pins (or Timer pins): Kalico 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, Kalico will report a \"Not a valid PWM pin\" error).

    IRQ pins (or Interrupt pins): Kalico 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.

    "},{"location":"FAQ.html#how-do-i-cancel-an-m109m190-wait-for-temperature-request","title":"How do I cancel an M109/M190 \"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 Kalico to enter into a \"shutdown\" state, and it will cause OctoPrint to disconnect from Kalico. 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 Kalico error state. After completing this sequence, the previous heating request will be canceled and a new print may be started.

    "},{"location":"FAQ.html#can-i-find-out-whether-the-printer-has-lost-steps","title":"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.)

    "},{"location":"FAQ.html#why-does-kalico-report-errors-i-lost-my-print","title":"Why does Kalico 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: Kalico 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 Kalico 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 Kalico pause the print instead? Report a warning instead? Check for errors before the print? Ignore errors in user typed commands? etc? Currently Kalico 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).

    "},{"location":"FAQ.html#how-do-i-upgrade-to-the-latest-software","title":"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\ngit pull\n~/klipper/scripts/install-octopi.sh\n

    Then one can recompile and flash the micro-controller code. For example:

    make menuconfig\nmake clean\nmake\n\nsudo service klipper stop\nmake flash FLASH_DEVICE=/dev/ttyACM0\nsudo service klipper start\n

    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\ngit pull\nsudo service klipper restart\n

    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.

    "},{"location":"FAQ.html#how-do-i-uninstall-kalico","title":"How do I uninstall Kalico?","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\nrm -rf ~/klippy-env ~/klipper\n
    "},{"location":"Features.html","title":"Features","text":"

    Kalico has several compelling features:

    "},{"location":"Features.html#additional-features","title":"Additional features","text":"

    Kalico supports many standard 3d printer features:

    To get started with Kalico, read the installation guide.

    "},{"location":"Features.html#step-benchmarks","title":"Step Benchmarks","text":"

    Below are the results of stepper performance tests. The numbers shown represent total number of steps per second on the micro-controller.

    Micro-controller 1 stepper active 3 steppers active 16Mhz AVR 157K 99K 20Mhz AVR 196K 123K SAMD21 686K 471K STM32F042 814K 578K Beaglebone PRU 866K 708K STM32G0B1 1103K 790K STM32F103 1180K 818K SAM3X8E 1273K 981K SAM4S8C 1690K 1385K LPC1768 1923K 1351K LPC1769 2353K 1622K RP2040 2400K 1636K SAM4E8E 2500K 1674K SAMD51 3077K 1885K AR100 3529K 2507K STM32F407 3652K 2459K STM32F446 3913K 2634K RP2350 4167K 2663K SAME70 6667K 4737K STM32H743 9091K 6061K

    If unsure of the micro-controller on a particular board, find the appropriate config file, and look for the micro-controller name in the comments at the top of that file.

    Further details on the benchmarks are available in the Benchmarks document.

    "},{"location":"G-Code_Shell_Command.html","title":"G-Code Shell Command Extension","text":""},{"location":"G-Code_Shell_Command.html#creator-of-this-extension-is-arksine","title":"Creator of this extension is Arksine.","text":"

    This is a brief explanation of how to use the shell command extension for Kalico, which you can install with KIAUH.

    After installing the extension you can execute linux commands or even scripts from within Kalico with custom commands defined in your printer.cfg.

    "},{"location":"G-Code_Shell_Command.html#how-to-configure-a-shell-command","title":"How to configure a shell command:","text":"
    # Runs a linux command or script from within Kalico.  Note that sudo commands\n# that require password authentication are disallowed. All executable scripts\n# should include a shebang.\n# [gcode_shell_command my_shell_cmd]\n#command:\n#  The linux shell command/script to be executed.  This parameter must be\n#  provided\n#timeout: 2.\n#  The timeout in seconds until the command is forcably terminated.  Default\n#  is 2 seconds.\n#verbose: True\n#  If enabled, the command's output will be forwarded to the terminal.  Its\n#  recommended to set this to false for commands that my run in quick\n#  succession.  Default is True.\n

    Once you have set up a shell command with the given parameters from above in your printer.cfg you can run the command as follows: RUN_SHELL_COMMAND CMD=name

    Example:

    [gcode_shell_command hello_world]\ncommand: echo hello world\ntimeout: 2.\nverbose: True\n

    Execute with: RUN_SHELL_COMMAND CMD=hello_world

    "},{"location":"G-Code_Shell_Command.html#passing-parameters","title":"Passing parameters:","text":"

    As of commit f231fa9 it is also possible to pass optional parameters to a gcode_shell_command. The following short example shows storing the extruder temperature into a variable, passing that value with a parameter to a gcode_shell_command, which then, once the gcode_macro runs and the gcode_shell_command gets called, executes the script.sh. The script then echoes a message to the console (if verbose: True) and writes the value of the parameter into a textfile called test.txt located in the home directory.

    Content of the gcode_shell_command and the gcode_macro:

    [gcode_shell_command print_to_file]\ncommand: sh /home/pi/printer_data/config/script.sh\ntimeout: 30.\nverbose: True\n\n[gcode_macro GET_TEMP]\ngcode:\n    {% set temp = printer.extruder.temperature %}\n    { action_respond_info(\"%s\" % (temp)) }\n    RUN_SHELL_COMMAND CMD=print_to_file PARAMS={temp}\n

    Content of script.sh:

    #!/bin/sh\n\necho \"temp is: $1\"\necho \"$1\" >> \"${HOME}/test.txt\"\n
    "},{"location":"G-Code_Shell_Command.html#warning","title":"Warning","text":"

    This extension may have a high potential for abuse if not used carefully! Also, depending on the command you execute, high system loads may occur and can cause system instabilities. Use this extension at your own risk and only if you know what you are doing!

    "},{"location":"G-Codes.html","title":"G-Codes","text":"

    This document describes the commands that Kalico supports. These are commands that one may enter into the OctoPrint terminal tab.

    Sections and commands marked with an \u26a0\ufe0f show commands that are new or behave differently from Klipper

    "},{"location":"G-Codes.html#g-code-commands","title":"G-Code commands","text":"

    Kalico supports the following standard G-Code commands:

    For further details on the above commands see the RepRap G-Code documentation.

    Kalico'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, Kalico 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 Kalico 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.

    "},{"location":"G-Codes.html#additional-commands","title":"Additional Commands","text":"

    Kalico 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 Kalico module name, which generally follows the section names specified in the printer configuration file. Note that some modules are automatically loaded.

    "},{"location":"G-Codes.html#adxl345","title":"[adxl345]","text":"

    The following commands are available when an adxl345 config section is enabled.

    "},{"location":"G-Codes.html#accelerometer_measure","title":"ACCELEROMETER_MEASURE","text":"

    ACCELEROMETER_MEASURE [CHIP=<config_name>] [NAME=<value>]: Starts accelerometer measurements at the requested number of samples per second. If CHIP is not specified it defaults to \"adxl345\". The command works in a start-stop mode: when executed for the first time, it starts the measurements, next execution stops them. The results of measurements are written to a file named /tmp/adxl345-<chip>-<name>.csv where <chip> is the name of the accelerometer chip (my_chip_name from [adxl345 my_chip_name]) and <name> is the optional NAME parameter. If NAME is not specified it defaults to the current time in \"YYYYMMDD_HHMMSS\" format. If the accelerometer does not have a name in its config section (simply [adxl345]) then <chip> part of the name is not generated.

    "},{"location":"G-Codes.html#accelerometer_query","title":"ACCELEROMETER_QUERY","text":"

    ACCELEROMETER_QUERY [CHIP=<config_name>] [RATE=<value>] [SAMPLES=<value>] [RETURN=<value>]: queries accelerometer for the current value. If CHIP is not specified it defaults to \"adxl345\". If RATE is not specified, the default value is used. This command is useful to test the connection to the ADXL345 accelerometer: one of the returned values should be a free-fall acceleration (+/- some noise of the chip). The SAMPLES parameter can be set to sample multiple readings from the sensor. The readings will be averaged together. The default is to collect a single sample. The RETURN parameter can take on the values vector(the default) or tilt. In vector mode, the raw free-fall acceleration vector is returned. In tilt mode, X and Y angles of a plane perpendicular to the free-fall vector are calculated and displayed.

    "},{"location":"G-Codes.html#accelerometer_debug_read","title":"ACCELEROMETER_DEBUG_READ","text":"

    ACCELEROMETER_DEBUG_READ [CHIP=<config_name>] REG=<register>: queries ADXL345 register \"register\" (e.g. 44 or 0x2C). Can be useful for debugging purposes.

    "},{"location":"G-Codes.html#accelerometer_debug_write","title":"ACCELEROMETER_DEBUG_WRITE","text":"

    ACCELEROMETER_DEBUG_WRITE [CHIP=<config_name>] REG=<register> VAL=<value>: Writes raw \"value\" into a register \"register\". Both \"value\" and \"register\" can be a decimal or a hexadecimal integer. Use with care, and refer to ADXL345 data sheet for the reference.

    "},{"location":"G-Codes.html#angle","title":"[angle]","text":"

    The following commands are available when an angle config section is enabled.

    "},{"location":"G-Codes.html#angle_calibrate","title":"ANGLE_CALIBRATE","text":"

    ANGLE_CALIBRATE CHIP=<chip_name>: Perform angle calibration on the given sensor (there must be an [angle chip_name] config section that has specified a stepper parameter). IMPORTANT - this tool will command the stepper motor to move without checking the normal kinematic boundary limits. Ideally the motor should be disconnected from any printer carriage before performing calibration. If the stepper can not be disconnected from the printer, make sure the carriage is near the center of its rail before starting calibration. (The stepper motor may move forwards or backwards two full rotations during this test.) After completing this test use the SAVE_CONFIG command to save the calibration data to the config file. In order to use this tool the Python \"numpy\" package must be installed (see the measuring resonance document for more information).

    "},{"location":"G-Codes.html#angle_debug_read","title":"ANGLE_DEBUG_READ","text":"

    ANGLE_DEBUG_READ CHIP=<config_name> REG=<register>: Queries sensor register \"register\" (e.g. 44 or 0x2C). Can be useful for debugging purposes. This is only available for tle5012b chips.

    "},{"location":"G-Codes.html#angle_debug_write","title":"ANGLE_DEBUG_WRITE","text":"

    ANGLE_DEBUG_WRITE CHIP=<config_name> REG=<register> VAL=<value>: Writes raw \"value\" into register \"register\". Both \"value\" and \"register\" can be a decimal or a hexadecimal integer. Use with care, and refer to sensor data sheet for the reference. This is only available for tle5012b chips.

    "},{"location":"G-Codes.html#axis_twist_compensation","title":"[axis_twist_compensation]","text":"

    The following commands are available when the axis_twist_compensation config section is enabled.

    "},{"location":"G-Codes.html#axis_twist_compensation_calibrate","title":"AXIS_TWIST_COMPENSATION_CALIBRATE","text":"

    AXIS_TWIST_COMPENSATION_CALIBRATE [AXIS=<X|Y>] [SAMPLE_COUNT=<value>] [<probe_parameter>=<value>]:

    Calibrates axis twist compensation by specifying the target axis or enabling automatic calibration.

    "},{"location":"G-Codes.html#bed_mesh","title":"[bed_mesh]","text":"

    The following commands are available when the bed_mesh config section is enabled (also see the bed mesh guide).

    "},{"location":"G-Codes.html#bed_mesh_calibrate","title":"BED_MESH_CALIBRATE","text":"

    BED_MESH_CALIBRATE [PROFILE=<name>] [METHOD=manual] [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>] [<mesh_parameter>=<value>] [ADAPTIVE=1] [ADAPTIVE_MARGIN=<value>]: This command probes the bed using generated points specified by the parameters in the config. After probing, a mesh is generated and z-movement is adjusted according to the mesh. The mesh will be saved into a profile specified by the PROFILE parameter, or default if unspecified. See the PROBE command for details on the optional probe parameters. If METHOD=manual is specified then the manual probing tool is activated - see the MANUAL_PROBE command above for details on the additional commands available while this tool is active. The optional HORIZONTAL_MOVE_Z value overrides the horizontal_move_z option specified in the config file. If ADAPTIVE=1 is specified then the objects defined by the Gcode file being printed will be used to define the probed area. The optional ADAPTIVE_MARGIN value overrides the adaptive_margin option specified in the config file.

    "},{"location":"G-Codes.html#bed_mesh_output","title":"BED_MESH_OUTPUT","text":"

    BED_MESH_OUTPUT PGP=[<0:1>]: This command outputs the current probed z values and current mesh values to the terminal. If PGP=1 is specified the X, Y coordinates generated by bed_mesh, along with their associated indices, will be output to the terminal.

    "},{"location":"G-Codes.html#bed_mesh_map","title":"BED_MESH_MAP","text":"

    BED_MESH_MAP: Like to BED_MESH_OUTPUT, this command prints the current state of the mesh to the terminal. Instead of printing the values in a human readable format, the state is serialized in json format. This allows octoprint plugins to easily capture the data and generate height maps approximating the bed's surface.

    "},{"location":"G-Codes.html#bed_mesh_clear","title":"BED_MESH_CLEAR","text":"

    BED_MESH_CLEAR: This command clears the mesh and removes all z adjustment. It is recommended to put this in your end-gcode.

    "},{"location":"G-Codes.html#bed_mesh_profile","title":"BED_MESH_PROFILE","text":"

    BED_MESH_PROFILE LOAD=<name> SAVE=<name> REMOVE=<name>: This command provides profile management for mesh state. LOAD will restore the mesh state from the profile matching the supplied name. SAVE will save the current mesh state to a profile matching the supplied name. Remove will delete the profile matching the supplied name from persistent memory. Note that after SAVE or REMOVE operations have been run the SAVE_CONFIG gcode must be run to make the changes to persistent memory permanent.

    "},{"location":"G-Codes.html#bed_mesh_offset","title":"BED_MESH_OFFSET","text":"

    BED_MESH_OFFSET [X=<value>] [Y=<value>] [ZFADE=<value]: Applies X, Y, and/or ZFADE offsets to the mesh lookup. This is useful for printers with independent extruders, as an offset is necessary to produce correct Z adjustment after a tool change. Note that a ZFADE offset does not apply additional z-adjustment directly, it is used to correct the fade calculation when a gcode offset has been applied to the Z axis.

    "},{"location":"G-Codes.html#bed_screws","title":"[bed_screws]","text":"

    The following commands are available when the bed_screws config section is enabled (also see the manual level guide).

    "},{"location":"G-Codes.html#bed_screws_adjust","title":"BED_SCREWS_ADJUST","text":"

    BED_SCREWS_ADJUST: This command will invoke the bed screws adjustment tool. It will command the nozzle to different locations (as defined in the config file) and allow one to make adjustments to the bed screws so that the bed is a constant distance from the nozzle.

    "},{"location":"G-Codes.html#bed_tilt","title":"[bed_tilt]","text":"

    The following commands are available when the bed_tilt config section is enabled.

    "},{"location":"G-Codes.html#bed_tilt_calibrate","title":"BED_TILT_CALIBRATE","text":"

    BED_TILT_CALIBRATE [METHOD=manual] [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>]: This command will probe the points specified in the config and then recommend updated x and y tilt adjustments. See the PROBE command for details on the optional probe parameters. If METHOD=manual is specified then the manual probing tool is activated - see the MANUAL_PROBE command above for details on the additional commands available while this tool is active. The optional HORIZONTAL_MOVE_Z value overrides the horizontal_move_z option specified in the config file.

    "},{"location":"G-Codes.html#belay","title":"[belay]","text":"

    The following commands are available when a belay config section is enabled.

    "},{"location":"G-Codes.html#query_belay","title":"QUERY_BELAY","text":"

    QUERY_BELAY BELAY=<config_name>: Queries the state of the belay specified by BELAY.

    "},{"location":"G-Codes.html#belay_set_multiplier","title":"BELAY_SET_MULTIPLIER","text":"

    BELAY_SET_MULTIPLIER BELAY=<config_name> [HIGH=<multiplier_high>] [LOW=<multiplier_low>]: Sets the values of multiplier_high and/or multiplier_low for the belay specified by BELAY, overriding their values from the corresponding belay config section. Values set by this command will not persist across restarts.

    "},{"location":"G-Codes.html#belay_set_stepper","title":"BELAY_SET_STEPPER","text":"

    BELAY_SET_STEPPER BELAY=<config_name> STEPPER=<extruder_stepper_name>: Selects the extruder_stepper whose multiplier will be controlled by the belay specified by BELAY. The multiplier for the previous stepper will be reset back to 1 before switching to the new stepper. Stepper selections made by this command will not persist across restarts. This command is only available if extruder_type is set to 'extruder_stepper' in the corresponding belay config section.

    "},{"location":"G-Codes.html#bltouch","title":"[bltouch]","text":"

    The following command is available when a bltouch config section is enabled (also see the BL-Touch guide).

    "},{"location":"G-Codes.html#bltouch_debug","title":"BLTOUCH_DEBUG","text":"

    BLTOUCH_DEBUG COMMAND=<command>: This sends a command to the BLTouch. It may be useful for debugging. Available commands are: pin_down, touch_mode, pin_up, self_test, reset. A BL-Touch V3.0 or V3.1 may also support set_5V_output_mode, set_OD_output_mode, output_mode_store commands.

    "},{"location":"G-Codes.html#bltouch_store","title":"BLTOUCH_STORE","text":"

    BLTOUCH_STORE MODE=<output_mode>: This stores an output mode in the EEPROM of a BLTouch V3.1 Available output_modes are: 5V, OD

    "},{"location":"G-Codes.html#configfile","title":"[configfile]","text":"

    The configfile module is automatically loaded.

    "},{"location":"G-Codes.html#save_config","title":"SAVE_CONFIG","text":"

    SAVE_CONFIG [RESTART=0|1]: This command will overwrite the main printer config file and restart the host software. This command is used in conjunction with other calibration commands to store the results of calibration tests. If RESTART is set to 0, no restart will be performed !!USE WITH CAUTION!!.

    "},{"location":"G-Codes.html#delayed_gcode","title":"[delayed_gcode]","text":"

    The following command is enabled if a delayed_gcode config section has been enabled (also see the template guide).

    "},{"location":"G-Codes.html#update_delayed_gcode","title":"UPDATE_DELAYED_GCODE","text":"

    UPDATE_DELAYED_GCODE [ID=<name>] [DURATION=<seconds>]: Updates the delay duration for the identified [delayed_gcode] and starts the timer for gcode execution. A value of 0 will cancel a pending delayed gcode from executing.

    "},{"location":"G-Codes.html#delta_calibrate","title":"[delta_calibrate]","text":"

    The following commands are available when the [delta_calibrate] config section is enabled (also see the delta calibrate guide).

    "},{"location":"G-Codes.html#delta_calibrate_1","title":"DELTA_CALIBRATE","text":"

    DELTA_CALIBRATE [METHOD=manual] [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>]: This command will probe seven points on the bed and recommend updated endstop positions, tower angles, and radius. See the PROBE command for details on the optional probe parameters. If METHOD=manual is specified then the manual probing tool is activated - see the MANUAL_PROBE command above for details on the additional commands available while this tool is active. The optional HORIZONTAL_MOVE_Z value overrides the horizontal_move_z option specified in the config file.

    "},{"location":"G-Codes.html#delta_analyze","title":"DELTA_ANALYZE","text":"

    DELTA_ANALYZE: This command is used during enhanced delta calibration. See Delta Calibrate for details.

    "},{"location":"G-Codes.html#display","title":"[display]","text":"

    The following command is available when a display config section is enabled.

    "},{"location":"G-Codes.html#set_display_group","title":"SET_DISPLAY_GROUP","text":"

    SET_DISPLAY_GROUP [DISPLAY=<display>] GROUP=<group>: Set the active display group of an lcd display. This allows to define multiple display data groups in the config, e.g. [display_data <group> <elementname>] and switch between them using this extended gcode command. If DISPLAY is not specified it defaults to \"display\" (the primary display).

    "},{"location":"G-Codes.html#display_status","title":"[display_status]","text":"

    The display_status module is automatically loaded if a display config section is enabled. It provides the following standard G-Code commands:

    Also provided is the following extended G-Code command:

    "},{"location":"G-Codes.html#dockable_probe","title":"[dockable_probe]","text":"

    In addition to the normal commands available for a [probe], the following commands are available when a dockable_probe config section is enabled (also see the Dockable Probe guide):

    "},{"location":"G-Codes.html#dual_carriage","title":"[dual_carriage]","text":"

    The following command is available when the dual_carriage config section is enabled.

    "},{"location":"G-Codes.html#set_dual_carriage","title":"SET_DUAL_CARRIAGE","text":"

    SET_DUAL_CARRIAGE CARRIAGE=[0|1] [MODE=[PRIMARY|COPY|MIRROR]]: This command will change the mode of the specified carriage. If no MODE is provided it defaults to PRIMARY. Setting the mode to PRIMARY deactivates the other carriage and makes the specified carriage execute subsequent G-Code commands as-is. COPY and MIRROR modes are supported only for CARRIAGE=1. When set to either of these modes, carriage 1 will then track the subsequent moves of the carriage 0 and either copy relative movements of it (in COPY mode) or execute them in the opposite (mirror) direction (in MIRROR mode).

    "},{"location":"G-Codes.html#save_dual_carriage_state","title":"SAVE_DUAL_CARRIAGE_STATE","text":"

    SAVE_DUAL_CARRIAGE_STATE [NAME=<state_name>]: Save the current positions of the dual carriages and their modes. Saving and restoring DUAL_CARRIAGE state can be useful in scripts and macros, as well as in homing routine overrides. If NAME is provided it allows one to name the saved state to the given string. If NAME is not provided it defaults to \"default\".

    "},{"location":"G-Codes.html#restore_dual_carriage_state","title":"RESTORE_DUAL_CARRIAGE_STATE","text":"

    RESTORE_DUAL_CARRIAGE_STATE [NAME=<state_name>] [MOVE=[0|1] [MOVE_SPEED=<speed>]]: Restore the previously saved positions of the dual carriages and their modes, unless \"MOVE=0\" is specified, in which case only the saved modes will be restored, but not the positions of the carriages. If positions are being restored and \"MOVE_SPEED\" is specified, then the toolhead moves will be performed with the given speed (in mm/s); otherwise the toolhead move will use the rail homing speed. Note that the carriages restore their positions only over their own axis, which may be necessary to correctly restore COPY and MIRROR mode of the dual carraige.

    "},{"location":"G-Codes.html#endstop_phase","title":"[endstop_phase]","text":"

    The following commands are available when an endstop_phase config section is enabled (also see the endstop phase guide).

    "},{"location":"G-Codes.html#endstop_phase_calibrate","title":"ENDSTOP_PHASE_CALIBRATE","text":"

    ENDSTOP_PHASE_CALIBRATE [STEPPER=<config_name>]: If no STEPPER parameter is provided then this command will reports statistics on endstop stepper phases during past homing operations. When a STEPPER parameter is provided it arranges for the given endstop phase setting to be written to the config file (in conjunction with the SAVE_CONFIG command).

    "},{"location":"G-Codes.html#exclude_object","title":"[exclude_object]","text":"

    The following commands are available when an exclude_object config section is enabled (also see the exclude object guide):

    "},{"location":"G-Codes.html#exclude_object_1","title":"EXCLUDE_OBJECT","text":"

    EXCLUDE_OBJECT [NAME=object_name] [CURRENT=1] [RESET=1]: With no parameters, this will return a list of all currently excluded objects.

    When the NAME parameter is given, the named object will be excluded from printing.

    When the CURRENT parameter is given, the current object will be excluded from printing.

    When the RESET parameter is given, the list of excluded objects will be cleared. Additionally including NAME will only reset the named object. This can cause print failures, if layers were already skipped.

    "},{"location":"G-Codes.html#exclude_object_define","title":"EXCLUDE_OBJECT_DEFINE","text":"

    EXCLUDE_OBJECT_DEFINE [NAME=object_name [CENTER=X,Y] [POLYGON=[[x,y],...]] [RESET=1] [JSON=1]: Provides a summary of an object in the file.

    With no parameters provided, this will list the defined objects known to Kalico. Returns a list of strings, unless the JSON parameter is given, when it will return object details in json format.

    When the NAME parameter is included, this defines an object to be excluded.

    When the RESET parameter is provided, all defined objects will be cleared, and the [exclude_object] module will be reset.

    "},{"location":"G-Codes.html#exclude_object_start","title":"EXCLUDE_OBJECT_START","text":"

    EXCLUDE_OBJECT_START NAME=object_name: This command takes a NAME parameter and denotes the start of the gcode for an object on the current layer.

    "},{"location":"G-Codes.html#exclude_object_end","title":"EXCLUDE_OBJECT_END","text":"

    EXCLUDE_OBJECT_END [NAME=object_name]: Denotes the end of the object's gcode for the layer. It is paired with EXCLUDE_OBJECT_START. A NAME parameter is optional, and will only warn when the provided name does not match the current object.

    "},{"location":"G-Codes.html#extruder","title":"[extruder]","text":"

    The following commands are available if an extruder config section is enabled:

    "},{"location":"G-Codes.html#activate_extruder","title":"ACTIVATE_EXTRUDER","text":"

    ACTIVATE_EXTRUDER EXTRUDER=<config_name>: In a printer with multiple extruder config sections, this command changes the active hotend.

    "},{"location":"G-Codes.html#set_pressure_advance","title":"SET_PRESSURE_ADVANCE","text":"

    SET_PRESSURE_ADVANCE [EXTRUDER=<config_name>] [ADVANCE=<pressure_advance>] [SMOOTH_TIME=<pressure_advance_smooth_time>]: Set pressure advance parameters of an extruder stepper (as defined in an extruder or extruder_stepper config section). If EXTRUDER is not specified, it defaults to the stepper defined in the active hotend.

    "},{"location":"G-Codes.html#set_extruder_rotation_distance","title":"SET_EXTRUDER_ROTATION_DISTANCE","text":"

    SET_EXTRUDER_ROTATION_DISTANCE EXTRUDER=<config_name> [DISTANCE=<distance>]: Set a new value for the provided extruder stepper's \"rotation distance\" (as defined in an extruder or extruder_stepper config section). If the rotation distance is a negative number then the stepper motion will be inverted (relative to the stepper direction specified in the config file). Changed settings are not retained on Kalico reset. Use with caution as small changes can result in excessive pressure between extruder and hotend. Do proper calibration with filament before use. If 'DISTANCE' value is not provided then this command will return the current rotation distance.

    "},{"location":"G-Codes.html#sync_extruder_motion","title":"SYNC_EXTRUDER_MOTION","text":"

    SYNC_EXTRUDER_MOTION EXTRUDER=<name> MOTION_QUEUE=<name>: This command will cause the stepper specified by EXTRUDER (as defined in an extruder or extruder_stepper config section) to become synchronized to the movement of an extruder specified by MOTION_QUEUE (as defined in an extruder config section). If MOTION_QUEUE is an empty string then the stepper will be desynchronized from all extruder movement.

    "},{"location":"G-Codes.html#mixing_extruder","title":"[mixing_extruder]","text":"

    The following commands are available when a mixingextruder config section is enabled:

    "},{"location":"G-Codes.html#set_mixing_extruder","title":"SET_MIXING_EXTRUDER","text":"

    SET_MIXING_EXTRUDER [FACTORS=<factor1>[:<factor2>[:<factor3>...]]] [ENABLE=[0|1]]: This command activates the specified mixing extruder. Subsequent G1 commands use the mixing defined by the factors. FACTORS defines the mixing by providing a number of positive values. The number of values should correspond to the number of steppers defined in the configuration. The values are normalized internally to add up to 1 and the extrusion of the corresponding stepper is multiplied by that value. If ENABLED is omitted the current mixing state is not changed. If neither FACTORS nor ENABLE is provided the current mixing status is displayed.

    "},{"location":"G-Codes.html#set_mixing_extruder_gradient","title":"SET_MIXING_EXTRUDER_GRADIENT","text":"

    SET_MIXING_EXTRUDER_GRADIENT [START_FACTORS=<s1>[,<s2>[,<s3>...]] END_FACTORS=<e1>[,<e2>[,<e3>...]] START_HEIGHT=<start> END_HEIGHT=<end>] [ENABLE=[0|1|RESET]] [METHOD=[linear|spherical] [VECTOR=,,]]`: When START_FACTORS, END_FACTORS, START_HEIGHT, END_HEIGHT is provided then an gradient configuration is added. The START_FACTORS define the mixing below and up to the START_HEIGHT. The END_FACTORS respectively the mixing from the END_HEIGHT onward. The mixing in between is linearly interpolated. When ENABLE is either 0 or 1 or METHOD is specified the mixing gradient is turned off or on and the gradient method (METHOD) which should be used is selected. All previously added gradients are used when enabled. The optional VECTOR configures a parameter depending on the METHOD: eg. for linear VECTOR defines the up direction and for spherical it defines the origin of the spheres. When ENABLE is RESET all configured gradients are removed and the gradient handling is disabled. When no parameter is provided the current mixing gradient status is displayed."},{"location":"G-Codes.html#heated_fan","title":"[heated_fan]","text":"

    The following command is available when a heated_fan is enabled.

    "},{"location":"G-Codes.html#set_heated_fan_target","title":"SET_HEATED_FAN_TARGET","text":"

    SET_HEATED_FAN_TARGET TARGET=<temperature>: Override the heater_temp setting in the heated_fan config section until Kalico is restarted. Useful for slicers to set different heated fan temperatures at different layers.

    "},{"location":"G-Codes.html#fan_generic","title":"[fan_generic]","text":"

    The following command is available when a fan_generic config section is enabled.

    "},{"location":"G-Codes.html#set_fan_speed","title":"SET_FAN_SPEED","text":"

    SET_FAN_SPEED FAN=config_name SPEED=<speed> This command sets the speed of a fan. \"speed\" must be between 0.0 and 1.0.

    "},{"location":"G-Codes.html#filament_switch_sensor","title":"[filament_switch_sensor]","text":"

    The following command is available when a filament_switch_sensor or filament_motion_sensor config section is enabled.

    "},{"location":"G-Codes.html#query_filament_sensor","title":"QUERY_FILAMENT_SENSOR","text":"

    QUERY_FILAMENT_SENSOR SENSOR=<sensor_name>: Queries the current status of the filament sensor. The data displayed on the terminal will depend on the sensor type defined in the configuration.

    "},{"location":"G-Codes.html#set_filament_sensor","title":"SET_FILAMENT_SENSOR","text":""},{"location":"G-Codes.html#for-filament_switch_sensor","title":"For filament_switch_sensor:","text":"

    SET_FILAMENT_SENSOR SENSOR=<sensor_name> [ENABLE=0|1] [RESET=0|1] [RUNOUT_DISTANCE=<mm>] [SMART=0|1] [ALWAYS_FIRE_EVENTS=0|1] [CHECK_ON_PRINT_START=0|1]: Sets values for the filament sensor. If all parameters are omitted, the current stats will be reported. ENABLE sets the filament sensor on/off. If ENABLE is set to 0, the filament sensor will be disabled, if set to 1 it is enabled. If the state of the sensor changes, a reset will be triggered. RESET removes all pending runout_gcodes and pauses and force a reevaluation of the sensor state. RUNOUT_DISTANCE sets the runout_distance. SMART sets the smart parameter. ALWAYS_FIRE_EVENTS sets the always_fire_events parameter, if set to true, a reset of the sensor will be triggered. CHECK_ON_PRINT_START sets the check_on_print_start parameter.

    "},{"location":"G-Codes.html#for-filament_motion_sensor","title":"For filament_motion_sensor:","text":"

    SET_FILAMENT_SENSOR SENSOR=<sensor_name> [ENABLE=0|1] [RESET=0|1] [DETECTION_LENGTH=<mm>] [SMART=0|1] [ALWAYS_FIRE_EVENTS=0|1]: Sets values for the filament sensor. If all parameters are omitted, the current stats will be reported. ENABLE sets the filament sensor on/off. If ENABLE is set to 0, the filament sensor will be disabled, if set to 1 it is enabled. If the sensor was previously disabled and gets enabled, a reset will be triggered. RESET resets the state of the sensor and sets it to filament detected. DETECTION_LENGTH sets the detection_length, if the new detection length is different from the old one, a reset will be triggered. SMART sets the smart parameter. ALWAYS_FIRE_EVENTS sets the always_fire_events parameter, no reset will be triggered.

    "},{"location":"G-Codes.html#firmware_retraction","title":"[firmware_retraction]","text":"

    The following standard G-Code commands are available when the firmware_retraction config section is enabled. These commands allow utilizing the firmware retraction feature available in many slicers. Retraction is a strategy to reduce stringing during travel moves (non-extrusion) from one part of the print to another. Note that pressure advance should be properly configured before retraction parameters are tuned to ensure optimal results.

    The following additional commands are also available.

    "},{"location":"G-Codes.html#set_retraction","title":"SET_RETRACTION","text":"

    SET_RETRACTION [RETRACT_LENGTH=<mm>] [RETRACT_SPEED=<mm/s>] [UNRETRACT_EXTRA_LENGTH=<mm>] [UNRETRACT_SPEED=<mm/s>] [Z_HOP_HEIGHT=<mm>]: Adjust the parameters used by firmware retraction. RETRACT_LENGTH determines the length of filament to retract (the minimum as well as standard value is 0 mm). RETRACT_SPEED determines the speed of the filament retraction move (the minimum value is 1 mm/s, the standard value is 20 mm/s). This value is typically set relatively high (>40 mm/s), except for soft and/or oozy filaments like TPU and PETG (20 to 30 mm/s). UNRETRACT_SPEED sets the speed of the filament unretract move (the minimum value is 1 mm/s, the standard value is 10 mm/s). This parameter is not particularly critical, although often lower than RETRACT_SPEED. UNRETRACT_EXTRA_LENGTH allows to add a small amount of length to the filament unretract move to prime the nozzle or to subtract a small amount of length from the filament unretract move to reduce blobbing at seams (the minimum value is -1 mm (2.41 mm3 volume for 1.75 mm filament), the standard value is 0 mm). Z_HOP_HEIGHT determines the vertical height by which the nozzle is lifted from the print to prevent collisions with the print during travel moves (the minimum value is 0 mm, the standard value is 0 mm, which disables Z-Hop moves). If a parameter is set when retracted, the new value will be taken into account only after G11 or CLEAR_RETRACTION event. SET_RETRACTION is commonly set as part of slicer per-filament configuration, as different filaments require different parameter settings. The command can be issued at runtime.

    "},{"location":"G-Codes.html#get_retraction","title":"GET_RETRACTION","text":"

    GET_RETRACTION: Queries the current parameters used by the firmware retraction module as well as the retract state. RETRACT_LENGTH, RETRACT_SPEED, UNRETRACT_EXTRA_LENGTH, UNRETRACT_SPEED, Z_HOP_HEIGHT, RETRACT_STATE (True, if retracted), ZHOP_STATE (True, if zhop offset currently applied) are displayed on the terminal.

    "},{"location":"G-Codes.html#clear_retraction","title":"CLEAR_RETRACTION","text":"

    CLEAR_RETRACTION: Clears the current retract state without extruder or motion system movement. All flags related to the retract state are reset to False.

    NOTE: The zhop state is also reset to False when the steppers are disabled (M84, typically part of end gcode and standard behavior of OctoPrint if a print is canceled) or the printer is homed (G28, typically part of start gcode). Hence, upon ending or canceling a print as well as starting a new print via GCode streaming or virtual SD card, the toolhead will not apply z_hop_height until next G11 if filament is retracted. Nevertheless, it is recommended to add CLEAR_RETRACTION to your start and end gcode to make sure the retract state is reset before and after each print.

    "},{"location":"G-Codes.html#reset_retraction","title":"RESET_RETRACTION","text":"

    RESET_RETRACTION: All changes to retraction parameters made via previous SET_RETRACTION commands are reset to config values.

    NOTE: It is recommended to add RESET_RETRACTION to your start and end gcode (with a possible override in your filament start gcode to set filament-specific overrides of firmware retraction defaults via SET_RETRACTION).

    "},{"location":"G-Codes.html#force_move","title":"[force_move]","text":"

    The force_move module is automatically loaded, however some commands require setting enable_force_move in the printer config.

    "},{"location":"G-Codes.html#stepper_buzz","title":"STEPPER_BUZZ","text":"

    STEPPER_BUZZ STEPPER=<config_name>: Move the given stepper forward one mm and then backward one mm, repeated 10 times. This is a diagnostic tool to help verify stepper connectivity.

    "},{"location":"G-Codes.html#force_move_1","title":"FORCE_MOVE","text":"

    FORCE_MOVE STEPPER=<config_name> DISTANCE=<value> VELOCITY=<value> [ACCEL=<value>]: This command will forcibly move the given stepper the given distance (in mm) at the given constant velocity (in mm/s). If ACCEL is specified and is greater than zero, then the given acceleration (in mm/s^2) will be used; otherwise no acceleration is performed. No boundary checks are performed; no kinematic updates are made; other parallel steppers on an axis will not be moved. Use caution as an incorrect command could cause damage! Using this command will almost certainly place the low-level kinematics in an incorrect state; issue a G28 afterwards to reset the kinematics. This command is intended for low-level diagnostics and debugging.

    "},{"location":"G-Codes.html#set_kinematic_position","title":"SET_KINEMATIC_POSITION","text":"

    SET_KINEMATIC_POSITION [X=<value>] [Y=<value>] [Z=<value>]: Force the low-level kinematic code to believe the toolhead is at the given cartesian position. This is a diagnostic and debugging command; use SET_GCODE_OFFSET and/or G92 for regular axis transformations. If an axis is not specified then it will default to the position that the head was last commanded to. Setting an incorrect or invalid position may lead to internal software errors. This command may invalidate future boundary checks; issue a G28 afterwards to reset the kinematics.

    "},{"location":"G-Codes.html#gcode","title":"[gcode]","text":"

    The gcode module is automatically loaded.

    "},{"location":"G-Codes.html#restart","title":"RESTART","text":"

    RESTART: This will cause the host software to reload its config and perform an internal reset. This command will not clear error state from the micro-controller (see FIRMWARE_RESTART) nor will it load new software (see the FAQ).

    "},{"location":"G-Codes.html#firmware_restart","title":"FIRMWARE_RESTART","text":"

    FIRMWARE_RESTART: This is similar to a RESTART command, but it also clears any error state from the micro-controller.

    "},{"location":"G-Codes.html#heater_interrupt","title":"HEATER_INTERRUPT","text":"

    HEATER_INTERRUPT: Interrupts a TEMPERATURE_WAIT command.

    "},{"location":"G-Codes.html#log_rollover","title":"LOG_ROLLOVER","text":"

    LOG_ROLLOVER: Trigger a klippy.log rollover and generate a new log file.

    "},{"location":"G-Codes.html#status","title":"STATUS","text":"

    STATUS: Report the Kalico host software status.

    "},{"location":"G-Codes.html#help","title":"HELP","text":"

    HELP: Report the list of available extended G-Code commands.

    "},{"location":"G-Codes.html#gcode_arcs","title":"[gcode_arcs]","text":"

    The following standard G-Code commands are available if a gcode_arcs config section is enabled:

    "},{"location":"G-Codes.html#gcode_macro","title":"[gcode_macro]","text":"

    The following command is available when a gcode_macro config section is enabled (also see the command templates guide).

    "},{"location":"G-Codes.html#set_gcode_variable","title":"SET_GCODE_VARIABLE","text":"

    SET_GCODE_VARIABLE MACRO=<macro_name> VARIABLE=<name> VALUE=<value>: This command allows one to change the value of a gcode_macro variable at run-time. The provided VALUE is parsed as a Python literal.

    "},{"location":"G-Codes.html#reload_gcode_macros","title":"RELOAD_GCODE_MACROS","text":"

    RELOAD_GCODE_MACROS: This command reads the config files and reloads all previously loaded gcode templates. It does not load new [gcode_macro] objects or unload deleted ones. Variables modified with SET_GCODE_VARIABLE remain unaffected.

    "},{"location":"G-Codes.html#gcode_move","title":"[gcode_move]","text":"

    The gcode_move module is automatically loaded.

    "},{"location":"G-Codes.html#get_position","title":"GET_POSITION","text":"

    GET_POSITION: Return information on the current location of the toolhead. See the developer documentation of GET_POSITION output for more information.

    "},{"location":"G-Codes.html#set_gcode_offset","title":"SET_GCODE_OFFSET","text":"

    SET_GCODE_OFFSET [X=<pos>|X_ADJUST=<adjust>] [Y=<pos>|Y_ADJUST=<adjust>] [Z=<pos>|Z_ADJUST=<adjust>] [MOVE=1 [MOVE_SPEED=<speed>]]: Set a positional offset to apply to future G-Code commands. This is commonly used to virtually change the Z bed offset or to set nozzle XY offsets when switching extruders. For example, if \"SET_GCODE_OFFSET Z=0.2\" is sent, then future G-Code moves will have 0.2mm added to their Z height. If the X_ADJUST style parameters are used, then the adjustment will be added to any existing offset (eg, \"SET_GCODE_OFFSET Z=-0.2\" followed by \"SET_GCODE_OFFSET Z_ADJUST=0.3\" would result in a total Z offset of 0.1). If \"MOVE=1\" is specified then a toolhead move will be issued to apply the given offset (otherwise the offset will take effect on the next absolute G-Code move that specifies the given axis). If \"MOVE_SPEED\" is specified then the toolhead move will be performed with the given speed (in mm/s); otherwise the toolhead move will use the last specified G-Code speed.

    "},{"location":"G-Codes.html#save_gcode_state","title":"SAVE_GCODE_STATE","text":"

    SAVE_GCODE_STATE [NAME=<state_name>]: Save the current g-code coordinate parsing state. Saving and restoring the g-code state is useful in scripts and macros. This command saves the current g-code absolute coordinate mode (G90/G91), absolute extrude mode (M82/M83), origin (G92), offset (SET_GCODE_OFFSET), speed override (M220), extruder override (M221), move speed, current XYZ position, and relative extruder \"E\" position. If NAME is provided it allows one to name the saved state to the given string. If NAME is not provided it defaults to \"default\".

    "},{"location":"G-Codes.html#restore_gcode_state","title":"RESTORE_GCODE_STATE","text":"

    RESTORE_GCODE_STATE [NAME=<state_name>] [MOVE=1 [MOVE_SPEED=<speed>]]: Restore a state previously saved via SAVE_GCODE_STATE. If \"MOVE=1\" is specified then a toolhead move will be issued to move back to the previous XYZ position. If \"MOVE_SPEED\" is specified then the toolhead move will be performed with the given speed (in mm/s); otherwise the toolhead move will use the restored g-code speed.

    "},{"location":"G-Codes.html#hall_filament_width_sensor","title":"[hall_filament_width_sensor]","text":"

    The following commands are available when the tsl1401cl filament width sensor config section or hall filament width sensor config section is enabled (also see TSLl401CL Filament Width Sensor and Hall Filament Width Sensor):

    "},{"location":"G-Codes.html#query_filament_width","title":"QUERY_FILAMENT_WIDTH","text":"

    QUERY_FILAMENT_WIDTH: Return the current measured filament width.

    "},{"location":"G-Codes.html#reset_filament_width_sensor","title":"RESET_FILAMENT_WIDTH_SENSOR","text":"

    RESET_FILAMENT_WIDTH_SENSOR: Clear all sensor readings. Helpful after filament change.

    "},{"location":"G-Codes.html#disable_filament_width_sensor","title":"DISABLE_FILAMENT_WIDTH_SENSOR","text":"

    DISABLE_FILAMENT_WIDTH_SENSOR: Turn off the filament width sensor and stop using it for flow control.

    "},{"location":"G-Codes.html#enable_filament_width_sensor","title":"ENABLE_FILAMENT_WIDTH_SENSOR","text":"

    ENABLE_FILAMENT_WIDTH_SENSOR: Turn on the filament width sensor and start using it for flow control.

    "},{"location":"G-Codes.html#query_raw_filament_width","title":"QUERY_RAW_FILAMENT_WIDTH","text":"

    QUERY_RAW_FILAMENT_WIDTH: Return the current ADC channel readings and RAW sensor value for calibration points.

    "},{"location":"G-Codes.html#enable_filament_width_log","title":"ENABLE_FILAMENT_WIDTH_LOG","text":"

    ENABLE_FILAMENT_WIDTH_LOG: Turn on diameter logging.

    "},{"location":"G-Codes.html#disable_filament_width_log","title":"DISABLE_FILAMENT_WIDTH_LOG","text":"

    DISABLE_FILAMENT_WIDTH_LOG: Turn off diameter logging.

    "},{"location":"G-Codes.html#heaters","title":"[heaters]","text":"

    The heaters module is automatically loaded if a heater is defined in the config file.

    "},{"location":"G-Codes.html#turn_off_heaters","title":"TURN_OFF_HEATERS","text":"

    TURN_OFF_HEATERS: Turn off all heaters.

    "},{"location":"G-Codes.html#temperature_wait","title":"TEMPERATURE_WAIT","text":"

    TEMPERATURE_WAIT SENSOR=<config_name> [MINIMUM=<target>] [MAXIMUM=<target>]: Wait until the given temperature sensor is at or above the supplied MINIMUM and/or at or below the supplied MAXIMUM.

    "},{"location":"G-Codes.html#set_heater_temperature","title":"SET_HEATER_TEMPERATURE","text":"

    SET_HEATER_TEMPERATURE HEATER=<heater_name> [TARGET=<target_temperature>]: Sets the target temperature for a heater. If a target temperature is not supplied, the target is 0.

    "},{"location":"G-Codes.html#set_smooth_time","title":"SET_SMOOTH_TIME","text":"

    SET_SMOOTH_TIME HEATER=<heater_name> [SMOOTH_TIME=<smooth_time>] [SAVE_TO_PROFILE=0|1]: Sets the smooth_time of the specified heater. If SMOOTH_TIME is omitted, the smooth_time will be reset to the value from the config. If SAVE_TO_PROFILE is set to 1, the new value will be written to the current PID_PROFILE.

    "},{"location":"G-Codes.html#idle_timeout","title":"[idle_timeout]","text":"

    The idle_timeout module is automatically loaded.

    "},{"location":"G-Codes.html#set_idle_timeout","title":"SET_IDLE_TIMEOUT","text":"

    SET_IDLE_TIMEOUT [TIMEOUT=<timeout>]: Allows the user to set the idle timeout (in seconds).

    "},{"location":"G-Codes.html#input_shaper","title":"[input_shaper]","text":"

    The following command is enabled if an input_shaper config section has been enabled (also see the resonance compensation guide).

    "},{"location":"G-Codes.html#set_input_shaper","title":"SET_INPUT_SHAPER","text":"

    SET_INPUT_SHAPER [SHAPER_FREQ_X=<shaper_freq_x>] [SHAPER_FREQ_Y=<shaper_freq_y>] [DAMPING_RATIO_X=<damping_ratio_x>] [DAMPING_RATIO_Y=<damping_ratio_y>] [SHAPER_TYPE=<shaper>] [SHAPER_TYPE_X=<shaper_type_x>] [SHAPER_TYPE_Y=<shaper_type_y>]: Modify input shaper parameters. Note that SHAPER_TYPE parameter resets input shaper for both X and Y axes even if different shaper types have been configured in [input_shaper] section. SHAPER_TYPE cannot be used together with either of SHAPER_TYPE_X and SHAPER_TYPE_Y parameters. See config reference for more details on each of these parameters.

    "},{"location":"G-Codes.html#manual_probe","title":"[manual_probe]","text":"

    The manual_probe module is automatically loaded.

    "},{"location":"G-Codes.html#manual_probe_1","title":"MANUAL_PROBE","text":"

    MANUAL_PROBE [SPEED=<speed>]: Run a helper script useful for measuring the height of the nozzle at a given location. If SPEED is specified, it sets the speed of TESTZ commands (the default is 5mm/s). During a manual probe, the following additional commands are available:

    "},{"location":"G-Codes.html#z_endstop_calibrate","title":"Z_ENDSTOP_CALIBRATE","text":"

    Z_ENDSTOP_CALIBRATE [SPEED=<speed>]: Run a helper script useful for calibrating a Z position_endstop config setting. See the MANUAL_PROBE command for details on the parameters and the additional commands available while the tool is active.

    "},{"location":"G-Codes.html#z_offset_apply_endstop","title":"Z_OFFSET_APPLY_ENDSTOP","text":"

    Z_OFFSET_APPLY_ENDSTOP: Take the current Z Gcode offset (aka, babystepping), and subtract it from the stepper_z endstop_position. This acts to take a frequently used babystepping value, and \"make it permanent\". Requires a SAVE_CONFIG to take effect.

    "},{"location":"G-Codes.html#manual_stepper","title":"[manual_stepper]","text":"

    The following command is available when a manual_stepper config section is enabled.

    "},{"location":"G-Codes.html#manual_stepper_1","title":"MANUAL_STEPPER","text":"

    MANUAL_STEPPER STEPPER=config_name [ENABLE=[0|1]] [SET_POSITION=<pos>] [SPEED=<speed>] [ACCEL=<accel>] [MOVE=<pos> [STOP_ON_ENDSTOP=[1|2|-1|-2]] [SYNC=0]]: This command will alter the state of the stepper. Use the ENABLE parameter to enable/disable the stepper. Use the SET_POSITION parameter to force the stepper to think it is at the given position. Use the MOVE parameter to request a movement to the given position. If SPEED and/or ACCEL is specified then the given values will be used instead of the defaults specified in the config file. If an ACCEL of zero is specified then no acceleration will be performed. If STOP_ON_ENDSTOP=1 is specified then the move will end early should the endstop report as triggered (use STOP_ON_ENDSTOP=2 to complete the move without error even if the endstop does not trigger, use -1 or -2 to stop when the endstop reports not triggered). Normally future G-Code commands will be scheduled to run after the stepper move completes, however if a manual stepper move uses SYNC=0 then future G-Code movement commands may run in parallel with the stepper movement.

    "},{"location":"G-Codes.html#mcp4018","title":"[mcp4018]","text":"

    The following command is available when a mcp4018 config section is enabled.

    "},{"location":"G-Codes.html#set_digipot","title":"SET_DIGIPOT","text":"

    SET_DIGIPOT DIGIPOT=config_name WIPER=<value>: This command will change the current value of the digipot. This value should typically be between 0.0 and 1.0, unless a 'scale' is defined in the config. When 'scale' is defined, then this value should be between 0.0 and 'scale'.

    "},{"location":"G-Codes.html#led","title":"[led]","text":"

    The following command is available when any of the led config sections are enabled.

    "},{"location":"G-Codes.html#set_led","title":"SET_LED","text":"

    SET_LED LED=<config_name> RED=<value> GREEN=<value> BLUE=<value> WHITE=<value> [INDEX=<index>] [TRANSMIT=0] [SYNC=1]: This sets the LED output. Each color <value> must be between 0.0 and 1.0. The WHITE option is only valid on RGBW LEDs. If the LED supports multiple chips in a daisy-chain then one may specify INDEX to alter the color of just the given chip (1 for the first chip, 2 for the second, etc.). If INDEX is not provided then all LEDs in the daisy-chain will be set to the provided color. If TRANSMIT=0 is specified then the color change will only be made on the next SET_LED command that does not specify TRANSMIT=0; this may be useful in combination with the INDEX parameter to batch multiple updates in a daisy-chain. By default, the SET_LED command will sync it's changes with other ongoing gcode commands. This can lead to undesirable behavior if LEDs are being set while the printer is not printing as it will reset the idle timeout. If careful timing is not needed, the optional SYNC=0 parameter can be specified to apply the changes without resetting the idle timeout.

    "},{"location":"G-Codes.html#set_led_template","title":"SET_LED_TEMPLATE","text":"

    SET_LED_TEMPLATE LED=<led_name> TEMPLATE=<template_name> [<param_x>=<literal>] [INDEX=<index>]: Assign a display_template to a given LED. For example, if one defined a [display_template my_led_template] config section then one could assign TEMPLATE=my_led_template here. The display_template should produce a comma separated string containing four floating point numbers corresponding to red, green, blue, and white color settings. The template will be continuously evaluated and the LED will be automatically set to the resulting colors. One may set display_template parameters to use during template evaluation (parameters will be parsed as Python literals). If INDEX is not specified then all chips in the LED's daisy-chain will be set to the template, otherwise only the chip with the given index will be updated. If TEMPLATE is an empty string then this command will clear any previous template assigned to the LED (one can then use SET_LED commands to manage the LED's color settings).

    "},{"location":"G-Codes.html#output_pin","title":"[output_pin]","text":"

    The following command is available when an output_pin config section or pwm_tool config section is enabled.

    "},{"location":"G-Codes.html#set_pin","title":"SET_PIN","text":"

    SET_PIN PIN=config_name VALUE=<value>: Set the pin to the given output VALUE. VALUE should be 0 or 1 for \"digital\" output pins. For PWM pins, set to a value between 0.0 and 1.0, or between 0.0 and scale if a scale is configured in the output_pin config section.

    "},{"location":"G-Codes.html#palette2","title":"[palette2]","text":"

    The following commands are available when the palette2 config section is enabled.

    Palette prints work by embedding special OCodes (Omega Codes) in the GCode file:

    The following additional commands are also available.

    "},{"location":"G-Codes.html#palette_connect","title":"PALETTE_CONNECT","text":"

    PALETTE_CONNECT: This command initializes the connection with the Palette 2.

    "},{"location":"G-Codes.html#palette_disconnect","title":"PALETTE_DISCONNECT","text":"

    PALETTE_DISCONNECT: This command disconnects from the Palette 2.

    "},{"location":"G-Codes.html#palette_clear","title":"PALETTE_CLEAR","text":"

    PALETTE_CLEAR: This command instructs the Palette 2 to clear all of the input and output paths of filament.

    "},{"location":"G-Codes.html#palette_cut","title":"PALETTE_CUT","text":"

    PALETTE_CUT: This command instructs the Palette 2 to cut the filament currently loaded in the splice core.

    "},{"location":"G-Codes.html#palette_smart_load","title":"PALETTE_SMART_LOAD","text":"

    PALETTE_SMART_LOAD: This command start the smart load sequence on the Palette 2. Filament is loaded automatically by extruding it the distance calibrated on the device for the printer, and instructs the Palette 2 once the loading has been completed. This command is the same as pressing Smart Load directly on the Palette 2 screen after the filament load is complete.

    "},{"location":"G-Codes.html#pid_calibrate","title":"[pid_calibrate]","text":"

    The pid_calibrate module is automatically loaded if a heater is defined in the config file.

    "},{"location":"G-Codes.html#pid_calibrate_1","title":"PID_CALIBRATE","text":"

    PID_CALIBRATE HEATER=<config_name> TARGET=<temperature> [WRITE_FILE=1] [TOLERANCE=0.02]: Perform a PID calibration test. The specified heater will be enabled until the specified target temperature is reached, and then the heater will be turned off and on for several cycles. If the WRITE_FILE parameter is enabled, then the file /tmp/heattest.csv will be created with a log of all temperature samples taken during the test. TOLERANCE defaults to 0.02 if not passed in. The tighter the tolerance the better the calibration result will be, but how tight you can achieve depends on how clean your sensor readings are. low noise readings might allow 0.01, to be used, while noisy reading might require a value of 0.03 or higher.

    "},{"location":"G-Codes.html#set_heater_pid","title":"SET_HEATER_PID","text":"

    SET_HEATER_PID HEATER=<heater_name> KP=<kp> KI=<ki> KD=<kd>: Will allow one to manually change PID parameters of heaters without a reload of the firmware. HEATER takes the short name (so for heater_generic chamber you would only write chamber)

    "},{"location":"G-Codes.html#pid_profile","title":"[pid_profile]","text":"

    The PID_PROFILE module is automatically loaded if a heater is defined in the config file.

    HEATER generally takes the short name (so for heater_generic chamber you would only write chamber)

    "},{"location":"G-Codes.html#pid_profile_1","title":"PID_PROFILE","text":"

    PID_PROFILE LOAD=<profile_name> HEATER=<heater_name> [DEFAULT=<profile_name>] [VERBOSE=<verbosity>] [KEEP_TARGET=0|1] [LOAD_CLEAN=0|1]: Loads the given PID_PROFILE for the specified heater. If DEFAULT is specified, the Profile specified in DEFAULT will be loaded when then given Profile for LOAD can't be found (like a getOrDefault method). If VERBOSE is set to LOW, minimal info will be written in console. If set to NONE, no console outputs will be given. If KEEP_TARGET is set to 1, the heater will keep it's target temperature, if set to 0, the target temperature will be set to 0. By default the target temperature of the heater will be set to 0 so the algorithm has time to settle in. If LOAD_CLEAN is set to 1, the profile would be loaded as if the printer just started up, if set to 0, the profile will retain previous heating information. By default the information will be kept to reduce overshoot, change this value if you encounter weird behaviour while switching profiles.

    PID_PROFILE SAVE=<profile_name> HEATER=<heater_name>: Saves the currently loaded profile of the specified heater to the config under the given name.

    PID_PROFILE REMOVE=<profile_name> HEATER=<heater_name>: Removes the given profile from the profiles List for the current session and config if SAVE_CONFIG is issued afterwards.

    PID_PROFILE SET_VALUES=<profile_name> HEATER=<heater_name> TARGET=<target_temp> TOLERANCE=<tolerance> CONTROL=<control_type> KP=<kp> KI=<ki> KD=<kd> [RESET_TARGET=0|1] [LOAD_CLEAN=0|1]: Creates a new profile with the given PID values, CONTROL must either be pid or pid_v, TOLERANCE and TARGET must be specified to create a valid profile, though the values themselves don't matter. If KEEP_TARGET is set to 1, the heater will keep it's target temperature, if set to 0, the target temperature will be set to 0. By default the target temperature of the heater will be set to 0 so the algorithm has time to settle in. If LOAD_CLEAN is set to 1, the profile would be loaded as if the printer just started up, if set to 0, the profile will retain previous heating information. By default the information will be kept to reduce overshoot, change this value if you encounter weird behaviour while switching profiles.

    PID_PROFILE GET_VALUES HEATER=<heater_name>: Outputs the values of the current loaded pid_profile of the given heater to the console.

    "},{"location":"G-Codes.html#pause_resume","title":"[pause_resume]","text":"

    The following commands are available when the pause_resume config section is enabled:

    "},{"location":"G-Codes.html#pause","title":"PAUSE","text":"

    PAUSE: Pauses the current print. The current position is captured for restoration upon resume.

    "},{"location":"G-Codes.html#resume","title":"RESUME","text":"

    RESUME [VELOCITY=<value>]: Resumes the print from a pause, first restoring the previously captured position. The VELOCITY parameter determines the speed at which the tool should return to the original captured position.

    "},{"location":"G-Codes.html#clear_pause","title":"CLEAR_PAUSE","text":"

    CLEAR_PAUSE: Clears the current paused state without resuming the print. This is useful if one decides to cancel a print after a PAUSE. It is recommended to add this to your start gcode to make sure the paused state is fresh for each print.

    "},{"location":"G-Codes.html#cancel_print","title":"CANCEL_PRINT","text":"

    CANCEL_PRINT: Cancels the current print.

    "},{"location":"G-Codes.html#print_stats","title":"[print_stats]","text":"

    The print_stats module is automatically loaded.

    "},{"location":"G-Codes.html#set_print_stats_info","title":"SET_PRINT_STATS_INFO","text":"

    SET_PRINT_STATS_INFO [TOTAL_LAYER=<total_layer_count>] [CURRENT_LAYER= <current_layer>]: Pass slicer info like layer act and total to Kalico. Add SET_PRINT_STATS_INFO [TOTAL_LAYER=<total_layer_count>] to your slicer start gcode section and SET_PRINT_STATS_INFO [CURRENT_LAYER= <current_layer>] at the layer change gcode section to pass layer information from your slicer to Kalico.

    "},{"location":"G-Codes.html#probe","title":"[probe]","text":"

    The following commands are available when a probe config section or bltouch config section is enabled (also see the probe calibrate guide).

    "},{"location":"G-Codes.html#probe_1","title":"PROBE","text":"

    PROBE [PROBE_SPEED=<mm/s>] [LIFT_SPEED=<mm/s>] [SAMPLES=<count>] [SAMPLE_RETRACT_DIST=<mm>] [SAMPLES_TOLERANCE=<mm>] [SAMPLES_TOLERANCE_RETRIES=<count>] [SAMPLES_RESULT=median|average]: Move the nozzle downwards until the probe triggers. If any of the optional parameters are provided they override their equivalent setting in the probe config section.

    "},{"location":"G-Codes.html#query_probe","title":"QUERY_PROBE","text":"

    QUERY_PROBE: Report the current status of the probe (\"triggered\" or \"open\").

    "},{"location":"G-Codes.html#probe_accuracy","title":"PROBE_ACCURACY","text":"

    PROBE_ACCURACY [PROBE_SPEED=<mm/s>] [SAMPLES=<count>] [SAMPLE_RETRACT_DIST=<mm>]: Calculate the maximum, minimum, average, median, and standard deviation of multiple probe samples. By default, 10 SAMPLES are taken. Otherwise the optional parameters default to their equivalent setting in the probe config section.

    "},{"location":"G-Codes.html#probe_calibrate","title":"PROBE_CALIBRATE","text":"

    PROBE_CALIBRATE [SPEED=<speed>] [<probe_parameter>=<value>]: Run a helper script useful for calibrating the probe's z_offset. See the PROBE command for details on the optional probe parameters. See the MANUAL_PROBE command for details on the SPEED parameter and the additional commands available while the tool is active. Please note, the PROBE_CALIBRATE command uses the speed variable to move in XY direction as well as Z.

    "},{"location":"G-Codes.html#z_offset_apply_probe","title":"Z_OFFSET_APPLY_PROBE","text":"

    Z_OFFSET_APPLY_PROBE: Take the current Z Gcode offset (aka, babystepping), and subtract if from the probe's z_offset. This acts to take a frequently used babystepping value, and \"make it permanent\". Requires a SAVE_CONFIG to take effect.

    "},{"location":"G-Codes.html#probe_eddy_current","title":"[probe_eddy_current]","text":"

    The following commands are available when a probe_eddy_current config section is enabled.

    "},{"location":"G-Codes.html#probe_eddy_current_calibrate","title":"PROBE_EDDY_CURRENT_CALIBRATE","text":"

    PROBE_EDDY_CURRENT_CALIBRATE CHIP=<config_name>: This starts a tool that calibrates the sensor resonance frequencies to corresponding Z heights. The tool will take a couple of minutes to complete. After completion, use the SAVE_CONFIG command to store the results in the printer.cfg file.

    "},{"location":"G-Codes.html#ldc_calibrate_drive_current","title":"LDC_CALIBRATE_DRIVE_CURRENT","text":"

    LDC_CALIBRATE_DRIVE_CURRENT CHIP=<config_name> This tool will calibrate the ldc1612 DRIVE_CURRENT0 register. Prior to using this tool, move the sensor so that it is near the center of the bed and about 20mm above the bed surface. Run this command to determine an appropriate DRIVE_CURRENT for the sensor. After running this command use the SAVE_CONFIG command to store that new setting in the printer.cfg config file.

    "},{"location":"G-Codes.html#pwm_cycle_time","title":"[pwm_cycle_time]","text":"

    The following command is available when a pwm_cycle_time config section is enabled.

    "},{"location":"G-Codes.html#set_pin_1","title":"SET_PIN","text":"

    SET_PIN PIN=config_name VALUE=<value> [CYCLE_TIME=<cycle_time>]: This command works similarly to output_pin SET_PIN commands. The command here supports setting an explicit cycle time using the CYCLE_TIME parameter (specified in seconds). Note that the CYCLE_TIME parameter is not stored between SET_PIN commands (any SET_PIN command without an explicit CYCLE_TIME parameter will use the cycle_time specified in the pwm_cycle_time config section).

    "},{"location":"G-Codes.html#query_adc","title":"[query_adc]","text":"

    The query_adc module is automatically loaded.

    "},{"location":"G-Codes.html#query_adc_1","title":"QUERY_ADC","text":"

    QUERY_ADC [NAME=<config_name>] [PULLUP=<value>]: Report the last analog value received for a configured analog pin. If NAME is not provided, the list of available adc names are reported. If PULLUP is provided (as a value in Ohms), the raw analog value along with the equivalent resistance given that pullup is reported.

    "},{"location":"G-Codes.html#query_endstops","title":"[query_endstops]","text":"

    The query_endstops module is automatically loaded. The following standard G-Code commands are currently available, but using them is not recommended:

    "},{"location":"G-Codes.html#query_endstops_1","title":"QUERY_ENDSTOPS","text":"

    QUERY_ENDSTOPS: Probe the axis endstops and report if they are \"triggered\" or in an \"open\" state. This command is typically used to verify that an endstop is working correctly.

    "},{"location":"G-Codes.html#resonance_tester","title":"[resonance_tester]","text":"

    The following commands are available when a resonance_tester config section is enabled (also see the measuring resonances guide).

    "},{"location":"G-Codes.html#measure_axes_noise","title":"MEASURE_AXES_NOISE","text":"

    MEASURE_AXES_NOISE: Measures and outputs the noise for all axes of all enabled accelerometer chips.

    "},{"location":"G-Codes.html#test_resonances","title":"TEST_RESONANCES","text":"

    TEST_RESONANCES AXIS=<axis> OUTPUT=<resonances,raw_data> [NAME=<name>] [FREQ_START=<min_freq>] [FREQ_END=<max_freq>] [HZ_PER_SEC=<hz_per_sec>] [CHIPS=<adxl345_chip_name>] [POINT=x,y,z] [ACCEL_PER_HZ=<accel_per_hz>] [INPUT_SHAPING=[<0:1>]]: Runs the resonance test in all configured probe points for the requested \"axis\" and measures the acceleration using the accelerometer chips configured for the respective axis. \"axis\" can either be X or Y, or specify an arbitrary direction as AXIS=dx,dy, where dx and dy are floating point numbers defining a direction vector (e.g. AXIS=X, AXIS=Y, or AXIS=1,-1 to define a diagonal direction). Note that AXIS=dx,dy and AXIS=-dx,-dy is equivalent. adxl345_chip_name can be one or more configured adxl345 chip,delimited with comma, for example CHIPS=\"adxl345, adxl345 rpi\". Note that adxl345 can be omitted from named adxl345 chips. If POINT or ACCEL_PER_HZ are specified, they will override the corresponding fields configured in [resonance_tester]. If INPUT_SHAPING=0 or not set(default), disables input shaping for the resonance testing, because it is not valid to run the resonance testing with the input shaper enabled. OUTPUT parameter is a comma-separated list of which outputs will be written. If raw_data is requested, then the raw accelerometer data is written into a file or a series of files /tmp/raw_data_<axis>_[<chip_name>_][<point>_]<name>.csv with (<point>_ part of the name generated only if more than 1 probe point is configured or POINT is specified). If resonances is specified, the frequency response is calculated (across all probe points) and written into /tmp/resonances_<axis>_<name>.csv file. If unset, OUTPUT defaults to resonances, and NAME defaults to the current time in \"YYYYMMDD_HHMMSS\" format.

    "},{"location":"G-Codes.html#shaper_calibrate","title":"SHAPER_CALIBRATE","text":"

    SHAPER_CALIBRATE [AXIS=<axis>] [NAME=<name>] [FREQ_START=<min_freq>] [FREQ_END=<max_freq>] [HZ_PER_SEC=<hz_per_sec>] [CHIPS=<adxl345_chip_name>] [MAX_SMOOTHING=<max_smoothing>]: Similarly to TEST_RESONANCES, runs the resonance test as configured, and tries to find the optimal parameters for the input shaper for the requested axis (or both X and Y axes if AXIS parameter is unset). If MAX_SMOOTHING is unset, its value is taken from [resonance_tester] section, with the default being unset. See the Max smoothing of the measuring resonances guide for more information on the use of this feature. The results of the tuning are printed to the console, and the frequency responses and the different input shapers values are written to a CSV file(s) /tmp/calibration_data_<axis>_<name>.csv. Unless specified, NAME defaults to the current time in \"YYYYMMDD_HHMMSS\" format. Note that the suggested input shaper parameters can be persisted in the config by issuing SAVE_CONFIG command, and if [input_shaper] was already enabled previously, these parameters take effect immediately.

    "},{"location":"G-Codes.html#respond","title":"[respond]","text":"

    The following standard G-Code commands are available when the respond config section is enabled:

    The following additional commands are also available.

    "},{"location":"G-Codes.html#respond_1","title":"RESPOND","text":""},{"location":"G-Codes.html#save_variables","title":"[save_variables]","text":"

    The following command is enabled if a save_variables config section has been enabled.

    "},{"location":"G-Codes.html#save_variable","title":"SAVE_VARIABLE","text":"

    SAVE_VARIABLE VARIABLE=<name> VALUE=<value>: Saves the variable to disk so that it can be used across restarts. All stored variables are loaded into the printer.save_variables.variables dict at startup and can be used in gcode macros. The provided VALUE is parsed as a Python literal.

    "},{"location":"G-Codes.html#screws_tilt_adjust","title":"[screws_tilt_adjust]","text":"

    The following commands are available when the screws_tilt_adjust config section is enabled (also see the manual level guide).

    "},{"location":"G-Codes.html#screws_tilt_calculate","title":"SCREWS_TILT_CALCULATE","text":"

    SCREWS_TILT_CALCULATE [DIRECTION=CW|CCW] [MAX_DEVIATION=<value>] [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>]: This command will invoke the bed screws adjustment tool. It will command the nozzle to different locations (as defined in the config file) probing the z height and calculate the number of knob turns to adjust the bed level. If DIRECTION is specified, the knob turns will all be in the same direction, clockwise (CW) or counterclockwise (CCW). See the PROBE command for details on the optional probe parameters. IMPORTANT: You MUST always do a G28 before using this command. If MAX_DEVIATION is specified, the command will raise a gcode error if any difference in the screw height relative to the base screw height is greater than the value provided. The optional HORIZONTAL_MOVE_Z value overrides the horizontal_move_z option specified in the config file.

    "},{"location":"G-Codes.html#sdcard_loop","title":"[sdcard_loop]","text":"

    When the sdcard_loop config section is enabled, the following extended commands are available.

    "},{"location":"G-Codes.html#sdcard_loop_begin","title":"SDCARD_LOOP_BEGIN","text":"

    SDCARD_LOOP_BEGIN COUNT=<count>: Begin a looped section in the SD print. A count of 0 indicates that the section should be looped indefinitely.

    "},{"location":"G-Codes.html#sdcard_loop_end","title":"SDCARD_LOOP_END","text":"

    SDCARD_LOOP_END: End a looped section in the SD print.

    "},{"location":"G-Codes.html#sdcard_loop_desist","title":"SDCARD_LOOP_DESIST","text":"

    SDCARD_LOOP_DESIST: Complete existing loops without further iterations.

    "},{"location":"G-Codes.html#servo","title":"[servo]","text":"

    The following commands are available when a servo config section is enabled.

    "},{"location":"G-Codes.html#set_servo","title":"SET_SERVO","text":"

    SET_SERVO SERVO=config_name [ANGLE=<degrees> | WIDTH=<seconds>]: Set the servo position to the given angle (in degrees) or pulse width (in seconds). Use WIDTH=0 to disable the servo output.

    "},{"location":"G-Codes.html#skew_correction","title":"[skew_correction]","text":"

    The following commands are available when the skew_correction config section is enabled (also see the Skew Correction guide).

    "},{"location":"G-Codes.html#set_skew","title":"SET_SKEW","text":"

    SET_SKEW [XY=<ac_length,bd_length,ad_length>] [XZ=<ac,bd,ad>] [YZ=<ac,bd,ad>] [CLEAR=<0|1>]: Configures the [skew_correction] module with measurements (in mm) taken from a calibration print. One may enter measurements for any combination of planes, planes not entered will retain their current value. If CLEAR=1 is entered then all skew correction will be disabled.

    "},{"location":"G-Codes.html#get_current_skew","title":"GET_CURRENT_SKEW","text":"

    GET_CURRENT_SKEW: Reports the current printer skew for each plane in both radians and degrees. The skew is calculated based on parameters provided via the SET_SKEW gcode.

    "},{"location":"G-Codes.html#calc_measured_skew","title":"CALC_MEASURED_SKEW","text":"

    CALC_MEASURED_SKEW [AC=<ac_length>] [BD=<bd_length>] [AD=<ad_length>]: Calculates and reports the skew (in radians and degrees) based on a measured print. This can be useful for determining the printer's current skew after correction has been applied. It may also be useful before correction is applied to determine if skew correction is necessary. See Skew Correction for details on skew calibration objects and measurements.

    "},{"location":"G-Codes.html#skew_profile","title":"SKEW_PROFILE","text":"

    SKEW_PROFILE [LOAD=<name>] [SAVE=<name>] [REMOVE=<name>]: Profile management for skew_correction. LOAD will restore skew state from the profile matching the supplied name. SAVE will save the current skew state to a profile matching the supplied name. Remove will delete the profile matching the supplied name from persistent memory. Note that after SAVE or REMOVE operations have been run the SAVE_CONFIG gcode must be run to make the changes to persistent memory permanent.

    "},{"location":"G-Codes.html#smart_effector","title":"\u26a0\ufe0f [smart_effector]","text":"

    Several commands are available when a smart_effector config section is enabled. Be sure to check the official documentation for the Smart Effector on the Duet3D Wiki before changing the Smart Effector parameters. Also check the probe calibration guide.

    "},{"location":"G-Codes.html#set_smart_effector","title":"SET_SMART_EFFECTOR","text":"

    SET_SMART_EFFECTOR [SENSITIVITY=<sensitivity>] [ACCEL=<accel>] [RECOVERY_TIME=<time>]: Set the Smart Effector parameters. When SENSITIVITY is specified, the respective value is written to the SmartEffector EEPROM (requires control_pin to be provided). Acceptable <sensitivity> values are 0..255, the default is 50. Lower values require less nozzle contact force to trigger (but there is a higher risk of false triggering due to vibrations during probing), and higher values reduce false triggering (but require larger contact force to trigger). Since the sensitivity is written to EEPROM, it is preserved after the shutdown, and so it does not need to be configured on every printer startup. ACCEL and RECOVERY_TIME allow to override the corresponding parameters at run-time, see the config section of Smart Effector for more info on those parameters.

    "},{"location":"G-Codes.html#reset_smart_effector","title":"RESET_SMART_EFFECTOR","text":"

    RESET_SMART_EFFECTOR: Resets Smart Effector sensitivity to its factory settings. Requires control_pin to be provided in the config section.

    "},{"location":"G-Codes.html#stepper_enable","title":"[stepper_enable]","text":"

    The stepper_enable module is automatically loaded.

    "},{"location":"G-Codes.html#set_stepper_enable","title":"SET_STEPPER_ENABLE","text":"

    SET_STEPPER_ENABLE STEPPER=<config_name> ENABLE=[0|1]: Enable or disable only the given stepper. This is a diagnostic and debugging tool and must be used with care. Disabling an axis motor does not reset the homing information. Manually moving a disabled stepper may cause the machine to operate the motor outside of safe limits. This can lead to damage to axis components, hot ends, and print surface.

    "},{"location":"G-Codes.html#temperature_fan","title":"[temperature_fan]","text":"

    The following command is available when a temperature_fan config section is enabled.

    "},{"location":"G-Codes.html#set_temperature_fan_target","title":"SET_TEMPERATURE_FAN_TARGET","text":"

    SET_TEMPERATURE_FAN_TARGET temperature_fan=<temperature_fan_name> [target=<target_temperature>] [min_speed=<min_speed>] [max_speed=<max_speed>]: Sets the target temperature for a temperature_fan. If a target is not supplied, it is set to the specified temperature in the config file. If speeds are not supplied, no change is applied.

    "},{"location":"G-Codes.html#tmcxxxx","title":"[tmcXXXX]","text":"

    The following commands are available when any of the tmcXXXX config sections are enabled.

    "},{"location":"G-Codes.html#dump_tmc","title":"DUMP_TMC","text":"

    DUMP_TMC STEPPER=<name> [REGISTER=<name>]: This command will read all TMC driver registers and report their values. If a REGISTER is provided, only the specified register will be dumped.

    "},{"location":"G-Codes.html#init_tmc","title":"INIT_TMC","text":"

    INIT_TMC STEPPER=<name>: This command will initialize the TMC registers. Needed to re-enable the driver if power to the chip is turned off then back on.

    "},{"location":"G-Codes.html#set_tmc_current","title":"SET_TMC_CURRENT","text":"

    SET_TMC_CURRENT STEPPER=<name> CURRENT=<amps> HOLDCURRENT=<amps>: This will adjust the run and hold currents of the TMC driver. HOLDCURRENT is not applicable to tmc2660 drivers. When used on a driver which has the globalscaler field (tmc5160 and tmc2240), if StealthChop2 is used, the stepper must be held at standstill for >130ms so that the driver executes the AT#1 calibration.

    "},{"location":"G-Codes.html#set_tmc_field","title":"SET_TMC_FIELD","text":"

    SET_TMC_FIELD STEPPER=<name> FIELD=<field> VALUE=<value> VELOCITY=<value>: This will alter the value of the specified register field of the TMC driver. This command is intended for low-level diagnostics and debugging only because changing the fields during run-time can lead to undesired and potentially dangerous behavior of your printer. Permanent changes should be made using the printer configuration file instead. No sanity checks are performed for the given values. A VELOCITY can also be specified instead of a VALUE. This velocity is converted to the 20bit TSTEP based value representation. Only use the VELOCITY argument for fields that represent velocities.

    "},{"location":"G-Codes.html#toolhead","title":"[toolhead]","text":"

    The toolhead module is automatically loaded.

    "},{"location":"G-Codes.html#set_velocity_limit","title":"SET_VELOCITY_LIMIT","text":"

    SET_VELOCITY_LIMIT [VELOCITY=<value>] [ACCEL=<value>] [MINIMUM_CRUISE_RATIO=<value>] [SQUARE_CORNER_VELOCITY=<value>]: This command can alter the velocity limits that were specified in the printer config file. See the printer config section for a description of each parameter.

    "},{"location":"G-Codes.html#reset_velocity_limit","title":"RESET_VELOCITY_LIMIT","text":"

    RESET_VELOCITY_LIMIT: This command resets the velocity limits to the values specified in the printer config file. See the printer config section for a description of each parameter.

    "},{"location":"G-Codes.html#set_kinematics_limit","title":"\u26a0\ufe0f SET_KINEMATICS_LIMIT","text":"

    SET_KINEMATICS_LIMIT [<X,Y,Z>_ACCEL=<value>] [<X,Y,Z>_VELOCITY=<value>] [SCALE=<0:1>]: change the per-axis limits.

    This command is only available when kinematics is set to either limited_cartesian or limited_corexy. The velocity argument is not available on CoreXY. With no arguments, this command responds with the movement direction with the most acceleration or velocity.

    "},{"location":"G-Codes.html#tools_calibrate","title":"\u26a0\ufe0f [tools_calibrate]","text":"

    The following commands are available when the tools_calibrate config section is enabled.

    "},{"location":"G-Codes.html#tool_calibrate_query_probe","title":"TOOL_CALIBRATE_QUERY_PROBE","text":"

    TOOL_CALIBRATE_QUERY_PROBE: Query the current calibration probe state.

    "},{"location":"G-Codes.html#tool_locate_sensor","title":"TOOL_LOCATE_SENSOR","text":"

    TOOL_LOCATE_SENSOR: Locate the sensor relative to the initial tool. The initial tool is the 0 offset, which other tools are calibrated against.

    Before running TOOL_LOCATE_SENSOR, position your primary toolhead centered over the calibration probe.

    "},{"location":"G-Codes.html#tool_calibrate_tool_offset","title":"TOOL_CALIBRATE_TOOL_OFFSET","text":"

    TOOL_CALIBRATE_TOOL_OFFSET: After locating the sensor with your initial tool, position each additional tool over the sensor and run TOOL_CALIBRATE_TOOL_OFFSET to find their offsets.

    "},{"location":"G-Codes.html#tool_calibrate_save_tool_offset","title":"TOOL_CALIBRATE_SAVE_TOOL_OFFSET","text":"

    TOOL_CALIBRATE_SAVE_TOOL_OFFSET MACRO=<macro_name> VARIABLE=<variable_name> [VALUE=\"({x:0.6f}, {y:0.6f}, {z:0.6f})\"]: Save the last calibration result to a macro variable.

    TOOL_CALIBRATE_SAVE_TOOL_OFFSET SECTION= ATTRIBUTE= [VALUE=\"{x:0.6f}, {y:0.6f}, {z:0.6f}\"]: Save the last calibration result to a field in your configuration. Calibration data saved this way will not take effect until after a RESTART of your printer.

    "},{"location":"G-Codes.html#trad_rack","title":"[trad_rack]","text":"

    The following commands are available when the trad_rack config section is enabled.

    "},{"location":"G-Codes.html#tr_home","title":"TR_HOME","text":"

    TR_HOME: Homes the selector.

    "},{"location":"G-Codes.html#tr_go_to_lane","title":"TR_GO_TO_LANE","text":"

    TR_GO_TO_LANE LANE=<lane index>: Moves the selector to the specified lane.

    "},{"location":"G-Codes.html#tr_load_lane","title":"TR_LOAD_LANE","text":"

    TR_LOAD_LANE LANE=<lane index> [RESET_SPEED=<0|1>]: Ensures filament is loaded into the module for the specified lane by prompting the user to insert filament, loading filament from the module into the selector, and retracting the filament back into the module. If RESET_SPEED is 1, the bowden move speed used for the specified LANE will be reset to spool_pull_speed from the trad_rack config section (see bowden speeds for details on how the bowden speed settings are used). If not specified, RESET_SPEED defaults to 1.

    "},{"location":"G-Codes.html#tr_load_toolhead","title":"TR_LOAD_TOOLHEAD","text":"

    TR_LOAD_TOOLHEAD LANE=<lane index>|TOOL=<tool index> [MIN_TEMP=<temperature>] [EXACT_TEMP=<temperature>] [BOWDEN_LENGTH=<mm>] [EXTRUDER_LOAD_LENGTH=<mm>] [HOTEND_LOAD_LENGTH=<mm>]: Loads filament from the specified lane or tool into the toolhead*. Either LANE or TOOL must be specified. If both are specified, then LANE takes precedence. If there is already an \"active lane\" because the toolhead has been loaded beforehand, it will be unloaded before loading the new filament. If MIN_TEMP is specified and it is higher than the extruder's current temperature, then the extruder will be heated to at least MIN_TEMP before unloading/loading; the current extruder temperature target may be used instead if it is higher than MIN_TEMP, and if not then tr_last_heater_target may be used. If EXACT_TEMP is specified, the extruder will be heated to EXACT_TEMP before unloading/loading, regardless of any other temperature setting. If any of the optional length parameters are specified, they override the corresponding settings in the trad_rack config section.

    * see the Tool Mapping document for details on the difference between lanes and tools and how they relate to each other.

    "},{"location":"G-Codes.html#t0-t1-t2-etc","title":"T0, T1, T2, etc.","text":"

    T<tool index>: Equivalent to calling TR_LOAD_TOOLHEAD TOOL=<tool index>. All of the optional parameters accepted by the TR_LOAD_TOOLHEAD command can also be used with these commands.

    "},{"location":"G-Codes.html#tr_unload_toolhead","title":"TR_UNLOAD_TOOLHEAD","text":"

    TR_UNLOAD_TOOLHEAD [MIN_TEMP=<temperature>] [EXACT_TEMP=<temperature>]: Unloads filament from the toolhead and back into its module. If MIN_TEMP is specified and it is higher than the extruder's current temperature, then the extruder will be heated to at least MIN_TEMP before unloading; the current extruder temperature target may be used instead if it is higher than MIN_TEMP, and if not then tr_last_heater_target may be used. If EXACT_TEMP is specified, the extruder will be heated to EXACT_TEMP before unloading/loading, regardless of any other temperature setting.

    "},{"location":"G-Codes.html#tr_servo_down","title":"TR_SERVO_DOWN","text":"

    TR_SERVO_DOWN [FORCE=<0|1>]: Moves the servo to bring the drive gear down. The selector must be moved to a valid lane before using this command, unless FORCE is 1. If not specified, FORCE defaults to 0. The FORCE parameter is unsafe for normal use and should only be used when the servo is not attached to Trad Rack's carriage.

    "},{"location":"G-Codes.html#tr_servo_up","title":"TR_SERVO_UP","text":"

    TR_SERVO_UP: Moves the servo to bring the drive gear up.

    "},{"location":"G-Codes.html#tr_set_active_lane","title":"TR_SET_ACTIVE_LANE","text":"

    TR_SET_ACTIVE_LANE LANE=<lane index>: Tells Trad Rack to assume the toolhead has been loaded with filament from the specified lane. The selector's position will also be inferred from this lane, and the selector motor will be enabled if it isn't already.

    "},{"location":"G-Codes.html#tr_reset_active_lane","title":"TR_RESET_ACTIVE_LANE","text":"

    TR_RESET_ACTIVE_LANE: Tells Trad Rack to assume the toolhead has not been loaded.

    "},{"location":"G-Codes.html#tr_resume","title":"TR_RESUME","text":"

    TR_RESUME: Completes necessary actions for Trad Rack to recover (and/or checks that Trad Rack is ready to continue), then resumes the print if all of those actions complete successfully. For example, if the print was paused due to a failed toolchange, then this command would retry the toolchange and then resume the print if the toolchange completes successfully. You will be prompted to use this command if Trad Rack has paused the print and requires user interaction or confirmation before attempting to recover and resume.

    "},{"location":"G-Codes.html#tr_locate_selector","title":"TR_LOCATE_SELECTOR","text":"

    TR_LOCATE_SELECTOR: Ensures the position of Trad Rack's selector is known so that it is ready for a print. If the user needs to take an action, they will be prompted to do so and the print will be paused (for example if the selector sensor is triggered but no active lane is set). The user_wait_time config option from the trad_rack config section determines how long Trad Rack will wait for user action before automatically unloading the toolhead and resuming. In addition, the save_active_lane config option determines whether this command can infer the \"active lane\" from a value saved before the last restart if the selector filament sensor is triggered but no active lane is currently set. It is recommended to call this command in the print start gcode.

    "},{"location":"G-Codes.html#tr_next","title":"TR_NEXT","text":"

    TR_NEXT: You will be prompted to use this command if Trad Rack requires user confirmation before continuing an action.

    "},{"location":"G-Codes.html#tr_sync_to_extruder","title":"TR_SYNC_TO_EXTRUDER","text":"

    TR_SYNC_TO_EXTRUDER: Syncs Trad Rack's filament driver to the extruder during printing, as well as during any extrusion moves within toolhead loading or unloading that would normally involve only the extruder. See the Extruder syncing document for more details. If you want the filament driver to be synced to the extruder on every startup without having to call this command, you can set sync_to_extruder to True in the trad_rack config section.

    "},{"location":"G-Codes.html#tr_unsync_from_extruder","title":"TR_UNSYNC_FROM_EXTRUDER","text":"

    TR_UNSYNC_FROM_EXTRUDER: Unsyncs Trad Rack's filament driver from the extruder during printing, as well as during any extrusion moves within toolhead loading or unloading that normally involve only the extruder. This is the default behavior unless you have set sync_to_extruder to True in the trad_rack config section.

    "},{"location":"G-Codes.html#tr_servo_test","title":"TR_SERVO_TEST","text":"

    TR_SERVO_TEST [ANGLE=<degrees>]: Moves the servo to the specified ANGLE relative to the down position. If ANGLE is not specified, the servo will be moved to the up position defined by servo_up_angle from the trad_rack config section. This command is meant for testing different servo angles in order to find the correct value for servo_up_angle.

    "},{"location":"G-Codes.html#tr_calibrate_selector","title":"TR_CALIBRATE_SELECTOR","text":"

    TR_CALIBRATE_SELECTOR: Initiates the process of calibrating lane_spacing, as well as the min, endstop, and max positions of the selector motor. You will be guided through the selector calibration process via messages in the console.

    "},{"location":"G-Codes.html#tr_set_hotend_load_length","title":"TR_SET_HOTEND_LOAD_LENGTH","text":"

    TR_SET_HOTEND_LOAD_LENGTH VALUE=<value>|ADJUST=<adjust>: Sets the value of hotend_load_length, overriding its value from the trad_rack config section. Does not persist across restarts. If the VALUE parameter is used, hotend_load_length will be set to the value passed in. If the ADJUST parameter is used, the adjustment will be added to the current value of hotend_load_length.

    "},{"location":"G-Codes.html#tr_discard_bowden_lengths","title":"TR_DISCARD_BOWDEN_LENGTHS","text":"

    TR_DISCARD_BOWDEN_LENGTHS [MODE=[ALL|LOAD|UNLOAD]]: Discards saved values for \"bowden_load_length\" and/or \"bowden_unload_length\" (see bowden lengths for details on how these settings are used). These settings will each be reset to the value of bowden_length from the trad_rack config section, and empty dictionaries will be saved for tr_calib_bowden_load_length and tr_calib_bowden_unload_length. \"bowden_load_length\" and tr_calib_bowden_load_length will be affected if MODE=LOAD is specified, \"bowden_unload_length\" and tr_calib_bowden_unload_length will be affected if MODE=UNLOAD is specified, and all 4 will be affected if MODE=ALL is specified. If not specified, MODE defaults to ALL.

    "},{"location":"G-Codes.html#tr_assign_lane","title":"TR_ASSIGN_LANE","text":"

    TR_ASSIGN_LANE LANE=<lane index> TOOL=<tool index> [SET_DEFAULT=<0|1>]: Assigns the specified LANE to the specified TOOL. If SET_DEFAULT is 1, LANE will become the default lane for the tool. If not specified, SET_DEFAULT defaults to 0.

    "},{"location":"G-Codes.html#tr_set_default_lane","title":"TR_SET_DEFAULT_LANE","text":"

    TR_SET_DEFAULT_LANE LANE=<lane index> [TOOL=<tool index>]: If TOOL is specified, LANE will be set as the default lane for the tool. If TOOL is not specified, LANE will be set as the default lane for its currently-assigned tool.

    "},{"location":"G-Codes.html#tr_reset_tool_map","title":"TR_RESET_TOOL_MAP","text":"

    TR_RESET_TOOL_MAP: Resets lane/tool mapping. Each tool will be mapped to a lane group consisting of a single lane with the same index as the tool.

    "},{"location":"G-Codes.html#tr_print_tool_map","title":"TR_PRINT_TOOL_MAP","text":"

    TR_PRINT_TOOL_MAP: Prints a table of the lane/tool mapping to the console, with rows corresponding to tools and columns corresponding to lanes.

    "},{"location":"G-Codes.html#tr_print_tool_groups","title":"TR_PRINT_TOOL_GROUPS","text":"

    TR_PRINT_TOOL_GROUPS: Prints a list of lanes assigned to each tool to the console. If a tool has multiple lanes assigned to it, the default lane will be indicated.

    "},{"location":"G-Codes.html#tuning_tower","title":"[tuning_tower]","text":"

    The tuning_tower module is automatically loaded.

    "},{"location":"G-Codes.html#tuning_tower_1","title":"TUNING_TOWER","text":"

    TUNING_TOWER COMMAND=<command> PARAMETER=<name> START=<value> [SKIP=<value>] [FACTOR=<value> [BAND=<value>]] | [STEP_DELTA=<value> STEP_HEIGHT=<value>]: A tool for tuning a parameter on each Z height during a print. The tool will run the given COMMAND with the given PARAMETER assigned to a value that varies with Z according to a formula. Use FACTOR if you will use a ruler or calipers to measure the Z height of the optimum value, or STEP_DELTA and STEP_HEIGHT if the tuning tower model has bands of discrete values as is common with temperature towers. If SKIP=<value> is specified, the tuning process doesn't begin until Z height <value> is reached, and below that the value will be set to START; in this case, the z_height used in the formulas below is actually max(z - skip, 0). There are three possible combinations of options:

    "},{"location":"G-Codes.html#virtual_sdcard","title":"[virtual_sdcard]","text":"

    Kalico supports the following standard G-Code commands if the virtual_sdcard config section is enabled:

    In addition, the following extended commands are available when the \"virtual_sdcard\" config section is enabled.

    "},{"location":"G-Codes.html#sdcard_print_file","title":"SDCARD_PRINT_FILE","text":"

    SDCARD_PRINT_FILE FILENAME=<filename>: Load a file and start SD print.

    "},{"location":"G-Codes.html#sdcard_reset_file","title":"SDCARD_RESET_FILE","text":"

    SDCARD_RESET_FILE: Unload file and clear SD state.

    "},{"location":"G-Codes.html#z_thermal_adjust","title":"[z_thermal_adjust]","text":"

    The following commands are available when the z_thermal_adjust config section is enabled.

    "},{"location":"G-Codes.html#set_z_thermal_adjust","title":"SET_Z_THERMAL_ADJUST","text":"

    SET_Z_THERMAL_ADJUST [ENABLE=<0:1>] [TEMP_COEFF=<value>] [REF_TEMP=<value>]: Enable or disable the Z thermal adjustment with ENABLE. Disabling does not remove any adjustment already applied, but will freeze the current adjustment value - this prevents potentially unsafe downward Z movement. Re-enabling can potentially cause upward tool movement as the adjustment is updated and applied. TEMP_COEFF allows run-time tuning of the adjustment temperature coefficient (i.e. the TEMP_COEFF config parameter). TEMP_COEFF values are not saved to the config. REF_TEMP manually overrides the reference temperature typically set during homing (for use in e.g. non-standard homing routines) - will be reset automatically upon homing.

    "},{"location":"G-Codes.html#z_calibration","title":"\u26a0\ufe0f [z_calibration]","text":"

    The following commands are available when a z_calibration config section is enabled (also see the Z-Calibration guide):

    "},{"location":"G-Codes.html#z_tilt","title":"[z_tilt]","text":"

    The following commands are available when the z_tilt config section is enabled.

    "},{"location":"G-Codes.html#z_tilt_adjust","title":"Z_TILT_ADJUST","text":"

    Z_TILT_ADJUST [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>]: This command will probe the points specified in the config and then make independent adjustments to each Z stepper to compensate for tilt. See the PROBE command for details on the optional probe parameters. The optional HORIZONTAL_MOVE_Z value overrides the horizontal_move_z option specified in the config file.

    "},{"location":"G-Codes.html#z_tilt_ng","title":"[z_tilt_ng]","text":"

    The following commands are available when the z_tilt_ng config section is enabled.

    "},{"location":"G-Codes.html#z_tilt_adjust_1","title":"Z_TILT_ADJUST","text":"

    Z_TILT_ADJUST [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>] [INCREASING_THRESHOLD=<value>]: This command will probe the points specified in the config and then make independent adjustments to each Z stepper to compensate for tilt. See the PROBE command for details on the optional probe parameters. The optional HORIZONTAL_MOVE_Z value overrides the horizontal_move_z option specified in the config file. INCREASING_THRESHOLD sets the increasing_threshold parameter of z_tilt. The follwing commands are availabe when the parameter \"extra_points\" is configured in the z_tilt_ng section:

    "},{"location":"Hall_Filament_Width_Sensor.html","title":"Hall filament width sensor","text":"

    This document describes Filament Width Sensor host module. Hardware used for developing this host module is based on two Hall linear sensors (ss49e for example). Sensors in the body are located on opposite sides. Principle of operation: two hall sensors work in differential mode, temperature drift same for sensor. Special temperature compensation not needed.

    You can find designs at Thingiverse, an assembly video is also available on Youtube

    To use Hall filament width sensor, read Config Reference and G-Code documentation.

    "},{"location":"Hall_Filament_Width_Sensor.html#how-does-it-work","title":"How does it work?","text":"

    Sensor generates two analog output based on calculated filament width. Sum of output voltage always equals to detected filament width. Host module monitors voltage changes and adjusts extrusion multiplier. I use the aux2 connector on a ramps-like board with the analog11 and analog12 pins. You can use different pins and different boards.

    "},{"location":"Hall_Filament_Width_Sensor.html#template-for-menu-variables","title":"Template for menu variables","text":"
    [menu __main __filament __width_current]\ntype: command\nenable: {'hall_filament_width_sensor' in printer}\nname: Dia: {'%.2F' % printer.hall_filament_width_sensor.Diameter}\nindex: 0\n\n[menu __main __filament __raw_width_current]\ntype: command\nenable: {'hall_filament_width_sensor' in printer}\nname: Raw: {'%4.0F' % printer.hall_filament_width_sensor.Raw}\nindex: 1\n
    "},{"location":"Hall_Filament_Width_Sensor.html#calibration-procedure","title":"Calibration procedure","text":"

    To get raw sensor value you can use menu item or QUERY_RAW_FILAMENT_WIDTH command in terminal.

    1. Insert first calibration rod (1.5 mm size) get first raw sensor value

    2. Insert second calibration rod (2.0 mm size) get second raw sensor value

    3. Save raw sensor values in config parameter Raw_dia1 and Raw_dia2

    "},{"location":"Hall_Filament_Width_Sensor.html#how-to-enable-sensor","title":"How to enable sensor","text":"

    By default, the sensor is disabled at power-on.

    To enable the sensor, issue ENABLE_FILAMENT_WIDTH_SENSOR command or set the enable parameter to true.

    "},{"location":"Hall_Filament_Width_Sensor.html#logging","title":"Logging","text":"

    By default, diameter logging is disabled at power-on.

    Issue ENABLE_FILAMENT_WIDTH_LOG command to start logging and issue DISABLE_FILAMENT_WIDTH_LOG command to stop logging. To enable logging at power-on, set the logging parameter to true.

    Filament diameter is logged on every measurement interval (10 mm by default).

    "},{"location":"Installation.html","title":"Installation","text":"

    These instructions assume the software will run on a linux based host running a Kalico compatible front end. It is recommended that a SBC(Small Board Computer) such as a Raspberry Pi or Debian based Linux device be used as the host machine (see the FAQ for other options).

    For the purposes of these instructions host relates to the Linux device and mcu relates to the printboard. SBC relates to the term Small Board Computer such as the Raspberry Pi.

    "},{"location":"Installation.html#obtain-a-kalico-configuration-file","title":"Obtain a Kalico Configuration File","text":"

    Most Kalico settings are determined by a \"printer configuration file\" printer.cfg, that will be stored on the host. An appropriate configuration file can often be found by looking in the Kalico config directory for a file starting with a \"printer-\" prefix that corresponds to the target printer. The Kalico configuration file contains technical information about the printer that will be needed during the installation.

    If there isn't an appropriate printer configuration file in the Kalico config directory then try searching the printer manufacturer's website to see if they have an appropriate Kalico configuration file.

    If no configuration file for the printer can be found, but the type of printer control board is known, then look for an appropriate config file starting with a \"generic-\" prefix. These example printer board files should allow one to successfully complete the initial installation, but will require some customization to obtain full printer functionality.

    It is also possible to define a new printer configuration from scratch. However, this requires significant technical knowledge about the printer and its electronics. It is recommended that most users start with an appropriate configuration file. If creating a new custom printer configuration file, then start with the closest example config file and use the Kalico config reference for further information.

    "},{"location":"Installation.html#interacting-with-kalico","title":"Interacting with Kalico","text":"

    Kalico is a 3d printer firmware, so it needs some way for the user to interact with it.

    Currently the best choices are front ends that retrieve information through the Moonraker web API and there is also the option to use Octoprint to control Kalico.

    The choice is up to the user on what to use, but the underlying Kalico is the same in all cases. We encourage users to research the options available and make an informed decision.

    "},{"location":"Installation.html#obtaining-an-os-image-for-sbcs","title":"Obtaining an OS image for SBC's","text":"

    There are many ways to obtain an OS image for Kalico for SBC use, most depend on what front end you wish to use. Some manafactures of these SBC boards also provide their own Kalico-centric images.

    The two main Moonraker based front ends are Fluidd and Mainsail, the latter of which has a premade install image \"MainsailOS\", this has the option for Raspberry Pi and some OrangePi variants.

    Fluidd can be installed via KIAUH(Klipper Install And Update Helper), which is explained below and is a 3rd party installer for all things Kalico.

    OctoPrint can be installed via the popular OctoPi image or via KIAUH, this process is explained in OctoPrint.md

    "},{"location":"Installation.html#installing-via-kiauh","title":"Installing via KIAUH","text":"

    Normally you would start with a base image for your SBC, RPiOS Lite for example, or in the case of a x86 Linux device, Ubuntu Server. Please note that Desktop variants are not recommended due to certain helper programs that can stop some Kalico functions working and even mask access to some print boards.

    KIAUH can be used to install Kalico and its associated programs on a variety of Linux based systems that run a form of Debian. More information can be found at https://github.com/dw-0/kiauh

    "},{"location":"Installation.html#building-and-flashing-the-micro-controller","title":"Building and flashing the micro-controller","text":"

    To compile the micro-controller code, start by running these commands on your host device:

    cd ~/klipper/\nmake menuconfig\n

    The comments at the top of the printer configuration file should describe the settings that need to be set during \"make menuconfig\". Open the file in a web browser or text editor and look for these instructions near the top of the file. Once the appropriate \"menuconfig\" settings have been configured, press \"Q\" to exit, and then \"Y\" to save. Then run:

    make\n

    If the comments at the top of the printer configuration file describe custom steps for \"flashing\" the final image to the printer control board then follow those steps and then proceed to configuring OctoPrint.

    Otherwise, the following steps are often used to \"flash\" the printer control board. First, it is necessary to determine the serial port connected to the micro-controller. Run the following:

    ls /dev/serial/by-id/*\n

    It should report something similar to the following:

    /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0\n

    It's common for each printer to have its own unique serial port name. This unique name will be used when flashing the micro-controller. It's possible there may be multiple lines in the above output - if so, choose the line corresponding to the micro-controller. If many items are listed and the choice is ambiguous, unplug the board and run the command again, the missing item will be your print board(see the FAQ for more information).

    For common micro-controllers with STM32 or clone chips, LPC chips and others it is usual that these need an initial Kalico flash via SD card.

    When flashing with this method, it is important to make sure that the print board is not connected with USB to the host, due to some boards being able to feed power back to the board and stopping a flash from occuring.

    For common micro-controllers using Atmega chips, for example the 2560, the code can be flashed with something similar to:

    sudo service klipper stop\nmake flash FLASH_DEVICE=/dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0\nsudo service klipper start\n

    Be sure to update the FLASH_DEVICE with the printer's unique serial port name.

    For common micro-controllers using RP2040 chips, the code can be flashed with something similar to:

    sudo service klipper stop\nmake flash FLASH_DEVICE=first\nsudo service klipper start\n

    It is important to note that RP2040 chips may need to be put into Boot mode before this operation.

    "},{"location":"Installation.html#configuring-kalico","title":"Configuring Kalico","text":"

    The next step is to copy the printer configuration file to the host.

    Arguably the easiest way to set the Kalico configuration file is using the built in editors in Mainsail or Fluidd. These will allow the user to open the configuration examples and save them to be printer.cfg.

    Another option is to use a desktop editor that supports editing files over the \"scp\" and/or \"sftp\" protocols. There are freely available tools that support this (eg, Notepad++, WinSCP, and Cyberduck). Load the printer config file in the editor and then save it as a file named \"printer.cfg\" in the home directory of the pi user (ie, /home/pi/printer.cfg).

    Alternatively, one can also copy and edit the file directly on the host via ssh. That may look something like the following (be sure to update the command to use the appropriate printer config filename):

    cp ~/klipper/config/example-cartesian.cfg ~/printer.cfg\nnano ~/printer.cfg\n

    It's common for each printer to have its own unique name for the micro-controller. The name may change after flashing Kalico, so rerun these steps again even if they were already done when flashing. Run:

    ls /dev/serial/by-id/*\n

    It should report something similar to the following:

    /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0\n

    Then update the config file with the unique name. For example, update the [mcu] section to look something similar to:

    [mcu]\nserial: /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0\n

    After creating and editing the file it will be necessary to issue a \"restart\" command in the command console to load the config. A \"status\" command will report the printer is ready if the Kalico config file is successfully read and the micro-controller is successfully found and configured.

    When customizing the printer config file, it is not uncommon for Kalico to report a configuration error. If an error occurs, make any necessary corrections to the printer config file and issue \"restart\" until \"status\" reports the printer is ready.

    Kalico reports error messages via the command console and via pop up in Fluidd and Mainsail. The \"status\" command can be used to re-report error messages. A log is available and usually located in ~/printer_data/logs this is named klippy.log

    After Kalico reports that the printer is ready, proceed to the config check document to perform some basic checks on the definitions in the config file. See the main documentation reference for other information.

    "},{"location":"Kalico_Additions.html","title":"Kalico additions","text":""},{"location":"Kalico_Additions.html#changes-to-klipper-defaults","title":"Changes to Klipper defaults","text":""},{"location":"Kalico_Additions.html#additional-configuration-options","title":"Additional configuration options","text":""},{"location":"Kalico_Additions.html#enhanced-behavior","title":"Enhanced behavior","text":""},{"location":"Kalico_Additions.html#new-kalico-modules","title":"New Kalico Modules","text":""},{"location":"Kalico_Additions.html#sensorless-homing","title":"Sensorless Homing","text":""},{"location":"Kalico_Additions.html#probes-and-probing","title":"Probes and Probing","text":""},{"location":"Kalico_Additions.html#heaters-fans-and-pid-changes","title":"Heaters, Fans, and PID changes","text":" "},{"location":"Kalico_Additions.html#macros","title":"Macros","text":""},{"location":"Kalico_Additions.html#plugins","title":"Plugins","text":"

    Extend your Kalico installation with custom plugins.

    Your python plugins can now extend klippy/extras adding new modules to Kalico without causing updates to fail due to a \"dirty\" git tree.

    Enable [danger_options] allow_plugin_override: True to override existing extras.

    "},{"location":"Kinematics.html","title":"Kinematics","text":"

    This document provides an overview of how Kalico implements robot motion (its kinematics). The contents may be of interest to both developers interested in working on the Kalico software as well as users interested in better understanding the mechanics of their machines.

    "},{"location":"Kinematics.html#acceleration","title":"Acceleration","text":"

    Kalico implements a constant acceleration scheme whenever the print head changes velocity - the velocity is gradually changed to the new speed instead of suddenly jerking to it. Kalico always enforces acceleration between the tool head and the print. The filament leaving the extruder can be quite fragile - rapid jerks and/or extruder flow changes lead to poor quality and poor bed adhesion. Even when not extruding, if the print head is at the same level as the print then rapid jerking of the head can cause disruption of recently deposited filament. Limiting speed changes of the print head (relative to the print) reduces risks of disrupting the print.

    It is also important to limit acceleration so that the stepper motors do not skip or put excessive stress on the machine. Kalico limits the torque on each stepper by virtue of limiting the acceleration of the print head. Enforcing acceleration at the print head naturally also limits the torque of the steppers that move the print head (the inverse is not always true).

    Kalico implements constant acceleration. The key formula for constant acceleration is:

    velocity(time) = start_velocity + accel*time\n
    "},{"location":"Kinematics.html#trapezoid-generator","title":"Trapezoid generator","text":"

    Kalico uses a traditional \"trapezoid generator\" to model the motion of each move - each move has a start speed, it accelerates to a cruising speed at constant acceleration, it cruises at a constant speed, and then decelerates to the end speed using constant acceleration.

    It's called a \"trapezoid generator\" because a velocity diagram of the move looks like a trapezoid.

    The cruising speed is always greater than or equal to both the start speed and the end speed. The acceleration phase may be of zero duration (if the start speed is equal to the cruising speed), the cruising phase may be of zero duration (if the move immediately starts decelerating after acceleration), and/or the deceleration phase may be of zero duration (if the end speed is equal to the cruising speed).

    "},{"location":"Kinematics.html#look-ahead","title":"Look-ahead","text":"

    The \"look-ahead\" system is used to determine cornering speeds between moves.

    Consider the following two moves contained on an XY plane:

    In the above situation it is possible to fully decelerate after the first move and then fully accelerate at the start of the next move, but that is not ideal as all that acceleration and deceleration would greatly increase the print time and the frequent changes in extruder flow would result in poor print quality.

    To solve this, the \"look-ahead\" mechanism queues multiple incoming moves and analyzes the angles between moves to determine a reasonable speed that can be obtained during the \"junction\" between two moves. If the next move is nearly in the same direction then the head need only slow down a little (if at all).

    However, if the next move forms an acute angle (the head is going to travel in nearly a reverse direction on the next move) then only a small junction speed is permitted.

    The junction speeds are determined using \"approximated centripetal acceleration\". Best described by the author. However, in Kalico, junction speeds are configured by specifying the desired speed that a 90\u00b0 corner should have (the \"square corner velocity\"), and the junction speeds for other angles are derived from that.

    Key formula for look-ahead:

    end_velocity^2 = start_velocity^2 + 2*accel*move_distance\n
    "},{"location":"Kinematics.html#minimum-cruise-ratio","title":"Minimum cruise ratio","text":"

    Kalico also implements a mechanism for smoothing out the motions of short \"zigzag\" moves. Consider the following moves:

    In the above, the frequent changes from acceleration to deceleration can cause the machine to vibrate which causes stress on the machine and increases the noise. Kalico implements a mechanism to ensure there is always some movement at a cruising speed between acceleration and deceleration. This is done by reducing the top speed of some moves (or sequence of moves) to ensure there is a minimum distance traveled at cruising speed relative to the distance traveled during acceleration and deceleration.

    Kalico implements this feature by tracking both a regular move acceleration as well as a virtual \"acceleration to deceleration\" rate:

    Specifically, the code calculates what the velocity of each move would be if it were limited to this virtual \"acceleration to deceleration\" rate. In the above picture the dashed gray lines represent this virtual acceleration rate for the first move. If a move can not reach its full cruising speed using this virtual acceleration rate then its top speed is reduced to the maximum speed it could obtain at this virtual acceleration rate.

    For most moves the limit will be at or above the move's existing limits and no change in behavior is induced. For short zigzag moves, however, this limit reduces the top speed. Note that it does not change the actual acceleration within the move - the move continues to use the normal acceleration scheme up to its adjusted top-speed.

    "},{"location":"Kinematics.html#generating-steps","title":"Generating steps","text":"

    Once the look-ahead process completes, the print head movement for the given move is fully known (time, start position, end position, velocity at each point) and it is possible to generate the step times for the move. This process is done within \"kinematic classes\" in the Kalico code. Outside of these kinematic classes, everything is tracked in millimeters, seconds, and in cartesian coordinate space. It's the task of the kinematic classes to convert from this generic coordinate system to the hardware specifics of the particular printer.

    Kalico uses an iterative solver to generate the step times for each stepper. The code contains the formulas to calculate the ideal cartesian coordinates of the head at each moment in time, and it has the kinematic formulas to calculate the ideal stepper positions based on those cartesian coordinates. With these formulas, Kalico can determine the ideal time that the stepper should be at each step position. The given steps are then scheduled at these calculated times.

    The key formula to determine how far a move should travel under constant acceleration is:

    move_distance = (start_velocity + .5 * accel * move_time) * move_time\n

    and the key formula for movement with constant velocity is:

    move_distance = cruise_velocity * move_time\n

    The key formulas for determining the cartesian coordinate of a move given a move distance is:

    cartesian_x_position = start_x + move_distance * total_x_movement / total_movement\ncartesian_y_position = start_y + move_distance * total_y_movement / total_movement\ncartesian_z_position = start_z + move_distance * total_z_movement / total_movement\n
    "},{"location":"Kinematics.html#cartesian-robots","title":"Cartesian Robots","text":"

    Generating steps for cartesian printers is the simplest case. The movement on each axis is directly related to the movement in cartesian space.

    Key formulas:

    stepper_x_position = cartesian_x_position\nstepper_y_position = cartesian_y_position\nstepper_z_position = cartesian_z_position\n
    "},{"location":"Kinematics.html#corexy-robots","title":"CoreXY Robots","text":"

    Generating steps on a CoreXY machine is only a little more complex than basic cartesian robots. The key formulas are:

    stepper_a_position = cartesian_x_position + cartesian_y_position\nstepper_b_position = cartesian_x_position - cartesian_y_position\nstepper_z_position = cartesian_z_position\n
    "},{"location":"Kinematics.html#delta-robots","title":"Delta Robots","text":"

    Step generation on a delta robot is based on Pythagoras's theorem:

    stepper_position = (sqrt(arm_length^2\n\n                         - (cartesian_x_position - tower_x_position)^2\n                         - (cartesian_y_position - tower_y_position)^2)\n                    + cartesian_z_position)\n
    "},{"location":"Kinematics.html#stepper-motor-acceleration-limits","title":"Stepper motor acceleration limits","text":"

    With delta kinematics it is possible for a move that is accelerating in cartesian space to require an acceleration on a particular stepper motor greater than the move's acceleration. This can occur when a stepper arm is more horizontal than vertical and the line of movement passes near that stepper's tower. Although these moves could require a stepper motor acceleration greater than the printer's maximum configured move acceleration, the effective mass moved by that stepper would be smaller. Thus the higher stepper acceleration does not result in significantly higher stepper torque and it is therefore considered harmless.

    However, to avoid extreme cases, Kalico enforces a maximum ceiling on stepper acceleration of three times the printer's configured maximum move acceleration. (Similarly, the maximum velocity of the stepper is limited to three times the maximum move velocity.) In order to enforce this limit, moves at the extreme edge of the build envelope (where a stepper arm may be nearly horizontal) will have a lower maximum acceleration and velocity.

    "},{"location":"Kinematics.html#extruder-kinematics","title":"Extruder kinematics","text":"

    Kalico implements extruder motion in its own kinematic class. Since the timing and speed of each print head movement is fully known for each move, it's possible to calculate the step times for the extruder independently from the step time calculations of the print head movement.

    Basic extruder movement is simple to calculate. The step time generation uses the same formulas that cartesian robots use:

    stepper_position = requested_e_position\n
    "},{"location":"Kinematics.html#pressure-advance","title":"Pressure advance","text":"

    Experimentation has shown that it's possible to improve the modeling of the extruder beyond the basic extruder formula. In the ideal case, as an extrusion move progresses, the same volume of filament should be deposited at each point along the move and there should be no volume extruded after the move. Unfortunately, it's common to find that the basic extrusion formulas cause too little filament to exit the extruder at the start of extrusion moves and for excess filament to extrude after extrusion ends. This is often referred to as \"ooze\".

    The \"pressure advance\" system attempts to account for this by using a different model for the extruder. Instead of naively believing that each mm^3 of filament fed into the extruder will result in that amount of mm^3 immediately exiting the extruder, it uses a model based on pressure. Pressure increases when filament is pushed into the extruder (as in Hooke's law) and the pressure necessary to extrude is dominated by the flow rate through the nozzle orifice (as in Poiseuille's law). The key idea is that the relationship between filament, pressure, and flow rate can be modeled using a linear coefficient:

    pa_position = nominal_position + pressure_advance_coefficient * nominal_velocity\n

    See the pressure advance document for information on how to find this pressure advance coefficient.

    The basic pressure advance formula can cause the extruder motor to make sudden velocity changes. Kalico implements \"smoothing\" of the extruder movement to avoid this.

    The above graph shows an example of two extrusion moves with a non-zero cornering velocity between them. Note that the pressure advance system causes additional filament to be pushed into the extruder during acceleration. The higher the desired filament flow rate, the more filament must be pushed in during acceleration to account for pressure. During head deceleration the extra filament is retracted (the extruder will have a negative velocity).

    The \"smoothing\" is implemented using a weighted average of the extruder position over a small time period (as specified by the pressure_advance_smooth_time config parameter). This averaging can span multiple g-code moves. Note how the extruder motor will start moving prior to the nominal start of the first extrusion move and will continue to move after the nominal end of the last extrusion move.

    Key formula for \"smoothed pressure advance\":

    smooth_pa_position(t) =\n    ( definitive_integral(pa_position(x) * (smooth_time/2 - abs(t - x)) * dx,\n                          from=t-smooth_time/2, to=t+smooth_time/2)\n     / (smooth_time/2)^2 )\n
    "},{"location":"MCU_Commands.html","title":"MCU commands","text":"

    This document provides information on the low-level micro-controller commands that are sent from the Kalico \"host\" software and processed by the Kalico micro-controller software. This document is not an authoritative reference for these commands, nor is it an exclusive list of all available commands.

    This document may be useful for developers interested in understanding the low-level micro-controller commands.

    See the protocol document for more information on the format of commands and their transmission. The commands here are described using their \"printf\" style syntax - for those unfamiliar with that format, just note that where a '%...' sequence is seen it should be replaced with an actual integer. For example, a description with \"count=%c\" could be replaced with the text \"count=10\". Note that parameters that are considered \"enumerations\" (see the above protocol document) take a string value which is automatically converted to an integer value for the micro-controller. This is common with parameters named \"pin\" (or that have a suffix of \"_pin\").

    "},{"location":"MCU_Commands.html#startup-commands","title":"Startup Commands","text":"

    It may be necessary to take certain one-time actions to configure the micro-controller and its peripherals. This section lists common commands available for that purpose. Unlike most micro-controller commands, these commands run as soon as they are received and they do not require any particular setup.

    Common startup commands:

    "},{"location":"MCU_Commands.html#low-level-micro-controller-configuration","title":"Low-level micro-controller configuration","text":"

    Most commands in the micro-controller require an initial setup before they can be successfully invoked. This section provides an overview of the configuration process. This section and the following sections are likely only of interest to developers interested in the internal details of Kalico.

    When the host first connects to the micro-controller it always starts by obtaining a data dictionary (see protocol for more information). After the data dictionary is obtained the host will check if the micro-controller is in a \"configured\" state and configure it if not. Configuration involves the following phases:

    "},{"location":"MCU_Commands.html#common-micro-controller-objects","title":"Common micro-controller objects","text":"

    This section lists some commonly used config commands.

    "},{"location":"MCU_Commands.html#common-commands","title":"Common commands","text":"

    This section lists some commonly used run-time commands. It is likely only of interest to developers looking to gain insight into Kalico.

    "},{"location":"MCU_Commands.html#stepper-commands","title":"Stepper commands","text":" "},{"location":"MCU_Commands.html#move-queue","title":"Move queue","text":"

    Each queue_step command utilizes an entry in the micro-controller \"move queue\". This queue is allocated when it receives the \"finalize_config\" command, and it reports the number of available queue entries in \"config\" response messages.

    It is the responsibility of the host to ensure that there is available space in the queue before sending a queue_step command. The host does this by calculating when each queue_step command completes and scheduling new queue_step commands accordingly.

    "},{"location":"MCU_Commands.html#spi-commands","title":"SPI Commands","text":" "},{"location":"MPC.html","title":"Model Predictive Control","text":"

    Model Predictive Control (MPC) is an advanced temperature control method that offers an alternative to traditional PID control. MPC leverages a system model to simulate the temperature of the hotend and adjusts the heater power to align with the target temperature.

    Unlike reactive methods, MPC operates proactively, adjusting in anticipation of temperature fluctuations. It utilizes a model of the hotend, considering factors such as the thermal masses of the system, heater power, heat loss to ambient air, and fans, and heat transfer into the filament. This model allows MPC to predict the amount of heat energy that will be dissipated from the hotend over a given duration, and it compensates for this by adjusting the heater power accordingly. As a result, MPC can accurately calculate the necessary heat energy input to maintain a steady temperature or to transition to a new temperature.

    MPC offers several advantages over PID control:

    Caution

    This feature controls the portions of the 3D printer that can get very hot. All standard Kalico warnings apply. Please report all issues and bugs to GitHub or Discord.

    "},{"location":"MPC.html#basic-configuration","title":"Basic Configuration","text":"

    To use MPC as the temperature controller for the extruder use the following basic configuration block.

    [extruder]\ncontrol: mpc\nheater_power: 50  \ncooling_fan:\nfilament_diameter: 1.75\nfilament_density: 1.20\nfilament_heat_capacity: 1.8 \n
    "},{"location":"MPC.html#optional-config-parameters","title":"Optional Config Parameters","text":"

    These can be specified in the config but should not need to be changed from the default values for most users.

    "},{"location":"MPC.html#ptc-heater-power","title":"PTC Heater Power","text":"

    The heater power: for PTC style heaters is recommended to be set at the normal print temperature for the printer. Some common PTC heaters are given below for reference. If your heater is not listed the manufacturer should be able to provide a temperature and power curve.

    Heater Temp (C) Rapido 2 (W) Rapido 1 (W) Dragon Ace old (W) Dragon Ace new (W) Revo 40 (W) Revo 60 (W) 180 72 52 51 66 30 45 200 70 51 48 63 29 44 220 67 50 46 60 28 43 240 65 49 44 58 28 42 260 64 48 43 55 27 40 280 62 47 41 53 27 39 300 60 46 39 51 26 38"},{"location":"MPC.html#filament-feed-forward-configuration","title":"Filament Feed Forward Configuration","text":"

    The filament feed forward (FFF) feature allows MPC to look forward and see changes in extrusion rates which could require more or less heat input to maintain target temperature. This feature substantially improves the accuracy and responsiveness of the model during printing. It is enabled by default and can be defined is more detail with the filament_density and filament_heat_capacity config parameters. The default values are set to cover a wide range of standard materials including ABS, ASA, PLA, PETG.

    FFF parameters can be set, for the printer session, via the MPC_SET G-Code command:

    MPC_SET HEATER=<heater> FILAMENT_DENSITY=<value> FILAMENT_HEAT_CAPACITY=<value> [FILAMENT_TEMP=<sensor|ambient|<value>>]

    For example, updating the filament material properties for ASA would be: 

    MPC_SET HEATER=extruder FILAMENT_DENSITY=1.07 FILAMENT_HEAT_CAPACITY=1.7  \n
    "},{"location":"MPC.html#filament-physical-properties","title":"Filament Physical Properties","text":"

    MPC works best knowing how much energy (in Joules) it takes to heat 1mm of filament by 1\u00b0C. The material values from the tables below have been curated from popular filament manufacturers and material data references. These values are sufficient for MPC to implement the FFF feature. Advanced users could tune the filament_density and filament_heat_capacity parameters based on manufacturers datasheets.

    "},{"location":"MPC.html#common-materials","title":"Common Materials","text":"Material Density [g/cm\u00b3] Specific heat [J/g/K] PLA 1.25 1.8 - 2.2 PETG 1.27 1.7 - 2.2 PC+ABS 1.15 1.5 - 2.2 ABS 1.06 1.25 - 2.4 ASA 1.07 1.3 - 2.1 PA6 1.12 2 - 2.5 PA 1.15 2 - 2.5 PC 1.20 1.1 - 1.9 TPU 1.21 1.5 - 2 TPU-90A 1.15 1.5 - 2 TPU-95A 1.22 1.5 - 2"},{"location":"MPC.html#common-carbon-fiber-filled-materials","title":"Common Carbon Fiber Filled Materials","text":"Material Density [g/cm\u00b3] Specific heat [J/g/K] ABS-CF 1.11 ^ ASA-CF 1.11 ^ PA6-CF 1.19 ^ PC+ABS-CF 1.22 ^ PC+CF 1.36 ^ PLA-CF 1.29 ^ PETG-CF 1.30 ^

    ^ Use the specific heat from the base polymer

    "},{"location":"MPC.html#calibration","title":"Calibration","text":"

    The MPC default calibration routine takes the following steps:

    1. Cool to ambient: The calibration routine needs to know the approximate ambient temperature and waits until the hotend temperature stabilises and stops decreasing relative to ambient.
    2. Heat past 200\u00b0C: Measure the point where the temperature is increasing most rapidly, and the time and temperature at that point. Also, three temperature measurements are needed at some point after the initial latency has taken effect.
    3. Hold temperature while measuring ambient heat-loss: At this point enough is known for the MPC algorithm to engage. The calibration routine makes a best guess at the overshoot past 200\u00b0C which will occur and targets this temperature for about a minute while ambient heat-loss is measured without and with the fan engaged (if a cooling_fan is specified).
    4. The MPC calibration routine creates the appropriate model constants. At this time the model parameters are temporary and not yet saved to the printer configuration.

    The MPC calibration routine must be run for each heater, to be controlled by MPC, in order to determine the model parameters. For an MPC calibration to be successful an extruder must be able to reach 200C. Calibration is performed with the following G-code command.

    MPC_CALIBRATE HEATER=<heater> [TARGET=<temperature>] [FAN_BREAKPOINTS=<value>]

    Default calibration of the hotend with seven fan breakpoints: 

    MPC_CALIBRATE HEATER=extruder FAN_BREAKPOINTS=7\n

    Note

    Ensure that the part cooling fan is off before starting calibration.

    After successful calibration the method will generate the key model parameters into the log for future reference.

    A SAVE_CONFIG command is then required to commit these calibrated model parameters to the printer config or the user can manually update the values. The SAVE_CONFIG block should then look like: 

    #*# <----------- SAVE_CONFIG ----------->\n#*# DO NOT EDIT THIS BLOCK OR BELOW. The contents are auto-generated.\n#*# [extruder]\n#*# control = mpc\n#*# block_heat_capacity = 22.3110\n#*# sensor_responsiveness = 0.0998635\n#*# ambient_transfer = 0.155082\n#*# fan_ambient_transfer=0.155082, 0.20156, 0.216441\n

    Note

    If the [extruder] section is in a .cfg file other than printer.cfg the SAVE_CONFIG command may not be able to write the calibration parameters and klippy will provide an error.

    These model parameters are not suitable for pre-configuration or are not explicitly determinable. Advanced users could tweak these post calibration based on the following guidance: Slightly increasing these values will increase the temperature where MPC settles and slightly decreasing them will decrease the settling temperature.

    "},{"location":"MPC.html#support-macros","title":"Support Macros","text":""},{"location":"MPC.html#temperature-wait","title":"Temperature Wait","text":"

    The following macro can be used to replace M109 hotend temperature set and M190 bed temperature set G-code commands with a macro utilizing temperature_wait G-codes. This can be utilized in systems where the sensor temperature takes an extended time to converge on the set temperature.

    Note

    This behaviour occurs primarily because MPC controls the modelled block temperature and not the hotend temperature sensor. For almost all cases, when temperature sensor overshoot/undershoot occurs, the block modelled temperature will be correctly at the set temperature. However, the Kalico system performs actions based on the sensor temperature only which can lead to undesirable delays in print actions with stock M109 and M190 commands.

    [gcode_macro M109] # Wait Hotend Temp\nrename_existing: M109.1\ngcode:\n    #Parameters\n    {% set s = params.S|float %}\n\n    M104 {% for p in params %}{'%s%s' % (p, params[p])}{% endfor %}  # Set hotend temp\n    {% if s != 0 %}\n        TEMPERATURE_WAIT SENSOR=extruder MINIMUM={s-2} MAXIMUM={s+5}   # Wait for hotend temp (within n degrees)\n    {% endif %}\n\n\n[gcode_macro M190] # Wait Bed Temp\nrename_existing: M190.1\ngcode:\n    #Parameters\n    {% set s = params.S|float %}\n\n    M140 {% for p in params %}{'%s%s' % (p, params[p])}{% endfor %}   # Set bed temp\n    {% if s != 0 %}\n        TEMPERATURE_WAIT SENSOR=heater_bed MINIMUM={s-2} MAXIMUM={s+5}  # Wait for bed temp (within n degrees)\n    {% endif %}\n
    "},{"location":"MPC.html#setting-fff-parameters-from-the-slicer","title":"Setting FFF Parameters From The Slicer","text":"

    This macro will set FFF parameters automatically when the material type is passed from the slicer. 

    [gcode_macro _SET_MPC_MATERIAL]\ndescription: Set heater MPC parameters for a given material\nvariable_filament_table:\n    ## Update this table to adjust material settings\n    {\n        ## ( density, heat capacity )  # suggested heat capacity range\n        \"PLA\"       : ( 1.25, 2.20 ),  # 1.80 - 2.20\n        \"PETG\"      : ( 1.27, 2.20 ),  # 1.70 - 2.20\n        \"PC+ABS\"    : ( 1.15, 2.20 ),  # 1.50 - 2.20\n        \"ABS\"       : ( 1.06, 2.40 ),  # 1.25 - 2.40\n        \"ASA\"       : ( 1.07, 2.10 ),  # 1.30 - 2.10\n        \"PA6\"       : ( 1.12, 2.50 ),  # 2.00 - 2.50\n        \"PA\"        : ( 1.15, 2.50 ),  # 2.00 - 2.50\n        \"PC\"        : ( 1.20, 1.90 ),  # 1.10 - 1.90\n        \"TPU\"       : ( 1.21, 2.00 ),  # 1.50 - 2.00\n        \"TPU-90A\"   : ( 1.15, 2.00 ),  # 1.50 - 2.00\n        \"TPU-95A\"   : ( 1.22, 2.00 ),  # 1.50 - 2.00\n        \"ABS-CF\"    : ( 1.11, 2.40 ),  # 1.25 - 2.40\n        \"ASA-CF\"    : ( 1.11, 2.10 ),  # 1.30 - 2.10\n        \"PA6-CF\"    : ( 1.19, 2.50 ),  # 2.00 - 2.50\n        \"PC+ABS-CF\" : ( 1.22, 2.20 ),  # 1.50 - 2.20\n        \"PC+CF\"     : ( 1.36, 1.90 ),  # 1.10 - 1.90\n        \"PLA-CF\"    : ( 1.29, 2.20 ),  # 1.80 - 2.20\n        \"PETG-CF\"   : ( 1.30, 2.20 ),  # 1.70 - 2.20\n    }\ngcode:\n    {% set material = params.MATERIAL | upper %}\n    {% set heater = params.HEATER | default('extruder') %}\n    {% set extruder_config = printer.configfile.settings[heater] %}\n\n    {% if material in filament_table %}\n        {% set (density, heat_capacity) = filament_table[material] %}\n\n        RESPOND PREFIX=\ud83d\udd25 MSG=\"Configured {heater} MPC for {material}. Density: {density}, Heat Capacity: {heat_capacity}\"\n    {% else %}\n        {% set density = extruder_config.filament_density %}\n        {% set heat_capacity=extruder_config.filament_heat_capacity %}\n\n        RESPOND PREFIX=\ud83d\udd25 MSG=\"Unknown material '{material}', using default mpc parameters for {heater}\"\n    {% endif %}\n\n    MPC_SET HEATER={heater} FILAMENT_DENSITY={density} FILAMENT_HEAT_CAPACITY={heat_capacity}\n

    The slicer must be configured to pass the current material type to your PRINT_START macro. For PrusaSlicer you should add the following parameter line to print_start in the Start G-Code section:

    MATERIAL=[filament_type[initial_extruder]]\n

    The print_start line, in PrusaSlicer, would look like:

    start_print MATERIAL=[filament_type[initial_extruder]] EXTRUDER_TEMP={first_layer_temperature[initial_extruder]} BED_TEMP={first_layer_bed_temperature[initial_extruder]} CHAMBER_TEMP={chamber_temperature}\n

    Then, in your PRINT_START macro include the following macro call:

    _SET_MPC_MATERIAL MATERIAL={params.MATERIAL}\n
    "},{"location":"MPC.html#real-time-model-state","title":"Real-Time Model State","text":"

    The real-time temperatures and model states can be viewed from a browser by entering the following local address for your computer.

    https://192.168.xxx.xxx:7125/printer/objects/query?extruder\n

    "},{"location":"MPC.html#experimental-features","title":"EXPERIMENTAL FEATURES","text":""},{"location":"MPC.html#bed-heater","title":"Bed Heater","text":"

    Using MPC for bed heater control is functional but the performance is not guaranteed or currently supported. MPC for the bed can be configured simply.

    [heater_bed]\ncontrol: mpc\nheater_power: 400\n

    The bed should be able to reach at least 90C to perform calibration with the following G-code.

    MPC_CALIBRATE HEATER=<heater> [TARGET=<temperature>] [FAN_BREAKPOINTS=<value>]

    Default calibration of the hotend with five fan breakpoints: 

    MPC_CALIBRATE HEATER=heater_bed FAN_BREAKPOINTS=5\n

    These calibrated model parameters need to be saved to the SAVE_CONFIG block manually or by using the SAVE_CONFIG command.

    "},{"location":"MPC.html#updating-calibration-parameters-at-runtime","title":"Updating calibration parameters at runtime","text":"

    Similar to SET_HEATER_PID, you can update your MPC calibration profile at runtime.

    MPC_SET HEATER=<heater_name> [BLOCK_HEAT_CAPACITY=0.0] [SENSOR_RESPONSIVENESS=0.0] [AMBIENT_TRANSFER=0.0] [FAN_AMBIENT_TRANSFER=0.01,0.02,0.03]

    "},{"location":"MPC.html#background","title":"BACKGROUND","text":""},{"location":"MPC.html#mpc-algorithm","title":"MPC Algorithm","text":"

    MPC models the hotend system as four thermal masses: ambient air, the filament, the heater block and the sensor. Heater power heats the modelled heater block directly. Ambient air heats or cools the heater block. Filament cools the heater block. The heater block heats or cools the sensor.

    Every time the MPC algorithm runs it uses the following information to calculate a new temperature for the simulated hotend and sensor:

    Once this calculation is done, the simulated sensor temperature is compared to the measured temperature and a fraction of the difference is added to the modelled sensor and heater block temperatures. This drags the simulated system in the direction of the real system. Because only a fraction of the difference is applied, sensor noise is diminished and averages out to zero over time. Both the simulated and the real sensor exhibit the same (or very similar) latency. Consequently, the effects of latency are eliminated when these values are compared to each other. So, the simulated hotend is only minimally affected by sensor noise and latency.

    SMOOTHING is the factor applied to the difference between simulated and measured sensor temperature. At its maximum value of 1, the simulated sensor temperature is continually set equal to the measured sensor temperature. A lower value will result in greater stability in MPC output power but also in decreased responsiveness. A value around 0.25 seems to work quite well.

    No simulation is perfect and, anyway, real life ambient temperature changes. So MPC also maintains a best guess estimate of ambient temperature. When the simulated system is close to steady state the simulated ambient temperature is continually adjusted. Steady state is determined to be when the MPC algorithm is not driving the hotend at its limits (i.e., full or zero heater power) or when it is at its limit but temperatures are still not changing very much - which will occur at asymptotic temperature (usually when target temperature is zero and the hotend is at ambient).

    Steady_state_rate is used to recognize the asymptotic condition. Whenever the simulated hotend temperature changes at an absolute rate less than steady_state_rate between two successive runs of the algorithm, the steady state logic is applied. Since the algorithm runs frequently, even a small amount of noise can result in a fairly high instantaneous rate of change of hotend temperature. In practice 1\u00b0C/s seems to work well for steady_state_rate.

    When in steady state, the difference between real and simulated sensor temperatures is used to drive the changes to ambient temperature. However, when the temperatures are really close min_ambient_change ensures that the simulated ambient temperature converges relatively quickly. Larger values of min_ambient_change will result in faster convergence but will also cause the simulated ambient temperature to flutter somewhat chaotically around the ideal value. This is not a problem because the effect of ambient temperature is fairly small and short-term variations of even 10\u00b0C or more will not have a noticeable effect.

    It is important to note that the simulated ambient temperature will only converge on real world ambient temperature if the ambient heat transfer coefficients are exactly accurate. In practice this will not be the case and the simulated ambient temperature therefore also acts a correction to these inaccuracies.

    Finally, armed with a new set of temperatures, the MPC algorithm calculates how much power must be applied to get the heater block to target temperature in the next two seconds. This calculation takes into account the heat that is expected to be lost to ambient air and filament heating. This power value is then converted to a PWM output.

    "},{"location":"MPC.html#additional-details","title":"Additional Details","text":"

    Please refer to that the excellent Marlin MPC Documentation for information on the model derivations, tuning methods, and heat transfer coefficients used in this feature.

    "},{"location":"MPC.html#acknowledgements","title":"Acknowledgements","text":"

    This feature is a port of the Marlin MPC implementation, and all credit goes to their team and community for pioneering this feature for open source 3D printing. The Marlin MPC documentation and github pages were heavily referenced and, in some cases directly copied and edited to create this document.

    "},{"location":"Manual_Level.html","title":"Manual leveling","text":"

    This document describes tools for calibrating a Z endstop and for performing adjustments to bed leveling screws.

    "},{"location":"Manual_Level.html#calibrating-a-z-endstop","title":"Calibrating a Z endstop","text":"

    An accurate Z endstop position is critical to obtaining high quality prints.

    Note, though, the accuracy of the Z endstop switch itself can be a limiting factor. If one is using Trinamic stepper motor drivers then consider enabling endstop phase detection to improve the accuracy of the switch.

    To perform a Z endstop calibration, home the printer, command the head to move to a Z position that is at least five millimeters above the bed (if it is not already), command the head to move to an XY position near the center of the bed, then navigate to the OctoPrint terminal tab and run:

    Z_ENDSTOP_CALIBRATE\n

    Then follow the steps described at \"the paper test\" to determine the actual distance between the nozzle and bed at the given location. Once those steps are complete one can ACCEPT the position and save the results to the config file with:

    SAVE_CONFIG\n

    It's preferable to use a Z endstop switch on the opposite end of the Z axis from the bed. (Homing away from the bed is more robust as then it is generally always safe to home the Z.) However, if one must home towards the bed it is recommended to adjust the endstop so that it triggers a small distance (eg, .5mm) above the bed. Almost all endstop switches can safely be depressed a small distance beyond their trigger point. When this is done, one should find that the Z_ENDSTOP_CALIBRATE command reports a small positive value (eg, .5mm) for the Z position_endstop. Triggering the endstop while it is still some distance from the bed reduces the risk of inadvertent bed crashes.

    Some printers have the ability to manually adjust the location of the physical endstop switch. However, it's recommended to perform Z endstop positioning in software with Kalico - once the physical location of the endstop is in a convenient location, one can make any further adjustments by running Z_ENDSTOP_CALIBRATE or by manually updating the Z position_endstop in the configuration file.

    "},{"location":"Manual_Level.html#adjusting-bed-leveling-screws","title":"Adjusting bed leveling screws","text":"

    The secret to getting good bed leveling with bed leveling screws is to utilize the printer's high precision motion system during the bed leveling process itself. This is done by commanding the nozzle to a position near each bed screw and then adjusting that screw until the bed is a set distance from the nozzle. Kalico has a tool to assist with this. In order to use the tool it is necessary to specify each screw XY location.

    This is done by creating a [bed_screws] config section. For example, it might look something similar to:

    [bed_screws]\nscrew1: 100, 50\nscrew2: 100, 150\nscrew3: 150, 100\n

    If a bed screw is under the bed, then specify the XY position directly above the screw. If the screw is outside the bed then specify an XY position closest to the screw that is still within the range of the bed.

    Once the config file is ready, run RESTART to load that config, and then one can start the tool by running:

    BED_SCREWS_ADJUST\n

    This tool will move the printer's nozzle to each screw XY location and then move the nozzle to a Z=0 height. At this point one can use the \"paper test\" to adjust the bed screw directly under the nozzle. See the information described in \"the paper test\", but adjust the bed screw instead of commanding the nozzle to different heights. Adjust the bed screw until there is a small amount of friction when pushing the paper back and forth.

    Once the screw is adjusted so that a small amount of friction is felt, run either the ACCEPT or ADJUSTED command. Use the ADJUSTED command if the bed screw needed an adjustment (typically anything more than about 1/8th of a turn of the screw). Use the ACCEPT command if no significant adjustment is necessary. Both commands will cause the tool to proceed to the next screw. (When an ADJUSTED command is used, the tool will schedule an additional cycle of bed screw adjustments; the tool completes successfully when all bed screws are verified to not require any significant adjustments.) One can use the ABORT command to exit the tool early.

    This system works best when the printer has a flat printing surface (such as glass) and has straight rails. Upon successful completion of the bed leveling tool the bed should be ready for printing.

    "},{"location":"Manual_Level.html#fine-grained-bed-screw-adjustments","title":"Fine grained bed screw adjustments","text":"

    If the printer uses three bed screws and all three screws are under the bed, then it may be possible to perform a second \"high precision\" bed leveling step. This is done by commanding the nozzle to locations where the bed moves a larger distance with each bed screw adjustment.

    For example, consider a bed with screws at locations A, B, and C:

    For each adjustment made to the bed screw at location C, the bed will swing along a pendulum defined by the remaining two bed screws (shown here as a green line). In this situation, each adjustment to the bed screw at C will move the bed at position D a further amount than directly at C. It is thus possible to make an improved C screw adjustment when the nozzle is at position D.

    To enable this feature, one would determine the additional nozzle coordinates and add them to the config file. For example, it might look like:

    [bed_screws]\nscrew1: 100, 50\nscrew1_fine_adjust: 0, 0\nscrew2: 100, 150\nscrew2_fine_adjust: 300, 300\nscrew3: 150, 100\nscrew3_fine_adjust: 0, 100\n

    When this feature is enabled, the BED_SCREWS_ADJUST tool will first prompt for coarse adjustments directly above each screw position, and once those are accepted, it will prompt for fine adjustments at the additional locations. Continue to use ACCEPT and ADJUSTED at each position.

    "},{"location":"Manual_Level.html#adjusting-bed-leveling-screws-using-the-bed-probe","title":"Adjusting bed leveling screws using the bed probe","text":"

    This is another way to calibrate the bed level using the bed probe. To use it you must have a Z probe (BL Touch, Inductive sensor, etc).

    To enable this feature, one would determine the nozzle coordinates such that the Z probe is above the screws, and then add them to the config file. For example, it might look like:

    [screws_tilt_adjust]\nscrew1: -5, 30\nscrew1_name: front left screw\nscrew2: 155, 30\nscrew2_name: front right screw\nscrew3: 155, 190\nscrew3_name: rear right screw\nscrew4: -5, 190\nscrew4_name: rear left screw\nhorizontal_move_z: 10.\nspeed: 50.\nscrew_thread: CW-M3\n

    The screw1 is always the reference point for the others, so the system assumes that screw1 is at the correct height. Always run G28 first and then run SCREWS_TILT_CALCULATE - it should produce output similar to:

    Send: G28\nRecv: ok\nSend: SCREWS_TILT_CALCULATE\nRecv: // 01:20 means 1 full turn and 20 minutes, CW=clockwise, CCW=counter-clockwise\nRecv: // front left screw (base) : x=-5.0, y=30.0, z=2.48750\nRecv: // front right screw : x=155.0, y=30.0, z=2.36000 : adjust CW 01:15\nRecv: // rear right screw : y=155.0, y=190.0, z=2.71500 : adjust CCW 00:50\nRecv: // read left screw : x=-5.0, y=190.0, z=2.47250 : adjust CW 00:02\nRecv: ok\n

    This means that:

    Note that \"minutes\" refers to \"minutes of a clock face\". So, for example, 15 minutes is a quarter of a full turn.

    Repeat the process several times until you get a good level bed - normally when all adjustments are below 6 minutes.

    If using a probe that is mounted on the side of the hotend (that is, it has an X or Y offset) then note that adjusting the bed tilt will invalidate any previous probe calibration that was performed with a tilted bed. Be sure to run probe calibration after the bed screws have been adjusted.

    The MAX_DEVIATION parameter is useful when a saved bed mesh is used, to ensure that the bed level has not drifted too far from where it was when the mesh was created. For example, SCREWS_TILT_CALCULATE MAX_DEVIATION=0.01 can be added to the custom start gcode of the slicer before the mesh is loaded. It will abort the print if the configured limit is exceeded (0.01mm in this example), giving the user a chance to adjust the screws and restart the print.

    The DIRECTION parameter is useful if you can turn your bed adjustment screws in one direction only. For example, you might have screws that start tightened in their lowest (or highest) possible position, which can only be turned in a single direction, to raise (or lower) the bed. If you can only turn the screws clockwise, run SCREWS_TILT_CALCULATE DIRECTION=CW. If you can only turn them counter-clockwise, run SCREWS_TILT_CALCULATE DIRECTION=CCW. A suitable reference point will be chosen such that the bed can be leveled by turning all the screws in the given direction.

    "},{"location":"Measuring_Resonances.html","title":"Measuring Resonances","text":"

    Kalico has built-in support for the ADXL345, MPU-9250 and LIS2DW compatible accelerometers which can be used to measure resonance frequencies of the printer for different axes, and auto-tune input shapers to compensate for resonances. Note that using accelerometers requires some soldering and crimping. The ADXL345/LIS2DW can be connected to the SPI interface of a Raspberry Pi or MCU board (it needs to be reasonably fast). The MPU family can be connected to the I2C interface of a Raspberry Pi directly, or to an I2C interface of an MCU board that supports 400kbit/s fast mode in Kalico.

    When sourcing accelerometers, be aware that there are a variety of different PCB board designs and different clones of them. If it is going to be connected to a 5V printer MCU ensure it has a voltage regulator and level shifters.

    For ADXL345s/LIS2DWs, make sure that the board supports SPI mode (a small number of boards appear to be hard-configured for I2C by pulling SDO to GND).

    For MPU-9250/MPU-9255/MPU-6515/MPU-6050/MPU-6500s there are also a variety of board designs and clones with different I2C pull-up resistors which will need supplementing.

    "},{"location":"Measuring_Resonances.html#mcus-with-kalico-i2c-fast-mode-support","title":"MCUs with Kalico I2C fast-mode Support","text":"MCU Family MCU(s) Tested MCU(s) with Support Raspberry Pi 3B+, Pico 3A, 3A+, 3B, 4 AVR ATmega ATmega328p ATmega32u4, ATmega128, ATmega168, ATmega328, ATmega644p, ATmega1280, ATmega1284, ATmega2560 AVR AT90 - AT90usb646, AT90usb1286"},{"location":"Measuring_Resonances.html#installation-instructions","title":"Installation instructions","text":""},{"location":"Measuring_Resonances.html#wiring","title":"Wiring","text":"

    An ethernet cable with shielded twisted pairs (cat5e or better) is recommended for signal integrity over a long distance. If you still experience signal integrity issues (SPI/I2C errors):

    Connect ethernet cable shielding only to the MCU board/Pi ground.

    Double-check your wiring before powering up to prevent damaging your MCU/Raspberry Pi or the accelerometer.

    "},{"location":"Measuring_Resonances.html#spi-accelerometers","title":"SPI Accelerometers","text":"

    Suggested twisted pair order for three twisted pairs:

    GND+MISO\n3.3V+MOSI\nSCLK+CS\n

    Note that unlike a cable shield, GND must be connected at both ends.

    "},{"location":"Measuring_Resonances.html#adxl345","title":"ADXL345","text":""},{"location":"Measuring_Resonances.html#direct-to-raspberry-pi","title":"Direct to Raspberry Pi","text":"

    Note: Many MCUs will work with an ADXL345 in SPI mode (e.g. Pi Pico), wiring and configuration will vary according to your specific board and available pins.

    You need to connect ADXL345 to your Raspberry Pi via SPI. Note that the I2C connection, which is suggested by ADXL345 documentation, has too low throughput and will not work. The recommended connection scheme:

    ADXL345 pin RPi pin RPi pin name 3V3 (or VCC) 01 3.3V DC power GND 06 Ground CS 24 GPIO08 (SPI0_CE0_N) SDO 21 GPIO09 (SPI0_MISO) SDA 19 GPIO10 (SPI0_MOSI) SCL 23 GPIO11 (SPI0_SCLK)

    Fritzing wiring diagrams for some of the ADXL345 boards:

    "},{"location":"Measuring_Resonances.html#using-raspberry-pi-pico","title":"Using Raspberry Pi Pico","text":"

    You may connect the ADXL345 to your Raspberry Pi Pico and then connect the Pico to your Raspberry Pi via USB. This makes it easy to reuse the accelerometer on other Kalico devices, as you can connect via USB instead of GPIO. The Pico does not have much processing power, so make sure it is only running the accelerometer and not performing any other duties.

    In order to avoid damage to your RPi make sure to connect the ADXL345 to 3.3V only. Depending on the board's layout, a level shifter may be present, which makes 5V dangerous for your RPi.

    ADXL345 pin Pico pin Pico pin name 3V3 (or VCC) 36 3.3V DC power GND 38 Ground CS 2 GP1 (SPI0_CSn) SDO 1 GP0 (SPI0_RX) SDA 5 GP3 (SPI0_TX) SCL 4 GP2 (SPI0_SCK)

    Wiring diagrams for some of the ADXL345 boards:

    "},{"location":"Measuring_Resonances.html#i2c-accelerometers","title":"I2C Accelerometers","text":"

    Suggested twisted pair order for three pairs (preferred):

    3.3V+GND\nSDA+GND\nSCL+GND\n

    or for two pairs:

    3.3V+SDA\nGND+SCL\n

    Note that unlike a cable shield, any GND(s) should be connected at both ends.

    "},{"location":"Measuring_Resonances.html#mpu-9250mpu-9255mpu-6515mpu-6050mpu-6500","title":"MPU-9250/MPU-9255/MPU-6515/MPU-6050/MPU-6500","text":"

    These accelerometers have been tested to work over I2C on the RPi, RP2040 (Pico) and AVR at 400kbit/s (fast mode). Some MPU accelerometer modules include pull-ups, but some are too large at 10K and must be changed or supplemented by smaller parallel resistors.

    Recommended connection scheme for I2C on the Raspberry Pi:

    MPU-9250 pin RPi pin RPi pin name VCC 01 3.3v DC power GND 09 Ground SDA 03 GPIO02 (SDA1) SCL 05 GPIO03 (SCL1)

    The RPi has buit-in 1.8K pull-ups on both SCL and SDA.

    Recommended connection scheme for I2C (i2c0a) on the RP2040:

    MPU-9250 pin RP2040 pin RP2040 pin name VCC 36 3v3 GND 38 Ground SDA 01 GP0 (I2C0 SDA) SCL 02 GP1 (I2C0 SCL)

    The Pico does not include any built-in I2C pull-up resistors.

    "},{"location":"Measuring_Resonances.html#recommended-connection-scheme-for-i2ctwi-on-the-avr-atmega328p-arduino-nano","title":"Recommended connection scheme for I2C(TWI) on the AVR ATmega328P Arduino Nano:","text":"MPU-9250 pin Atmega328P TQFP32 pin Atmega328P pin name Arduino Nano pin VCC 39 - - GND 38 Ground GND SDA 27 SDA A4 SCL 28 SCL A5

    The Arduino Nano does not include any built-in pull-up resistors nor a 3.3V power pin.

    "},{"location":"Measuring_Resonances.html#mounting-the-accelerometer","title":"Mounting the accelerometer","text":"

    The accelerometer must be attached to the toolhead. One needs to design a proper mount that fits their own 3D printer. It is better to align the axes of the accelerometer with the printer's axes (but if it makes it more convenient, axes can be swapped - i.e. no need to align X axis with X and so forth - it should be fine even if Z axis of accelerometer is X axis of the printer, etc.).

    An example of mounting ADXL345 on the SmartEffector:

    Note that on a bed slinger printer one must design 2 mounts: one for the toolhead and one for the bed, and run the measurements twice. See the corresponding section for more details.

    Attention: make sure the accelerometer and any screws that hold it in place do not touch any metal parts of the printer. Basically, the mount must be designed such as to ensure the electrical isolation of the accelerometer from the printer frame. Failing to ensure that can create a ground loop in the system that may damage the electronics.

    "},{"location":"Measuring_Resonances.html#software-installation","title":"Software installation","text":"

    Note that resonance measurements and shaper auto-calibration require additional software dependencies not installed by default. First, run on your Raspberry Pi the following commands:

    sudo apt update\nsudo apt install python3-numpy python3-matplotlib libatlas-base-dev libopenblas-dev\n

    Next, in order to install NumPy in the Kalico environment, run the command:

    ~/klippy-env/bin/pip install -v numpy\n

    Note that, depending on the performance of the CPU, it may take a lot of time, up to 10-20 minutes. Be patient and wait for the completion of the installation. On some occasions, if the board has too little RAM the installation may fail and you will need to enable swap.

    Once installed please check that no errors show from the command:

    ~/klippy-env/bin/python -c 'import numpy;'\n

    The correct output should simply be a new line.

    "},{"location":"Measuring_Resonances.html#configure-adxl345-with-rpi","title":"Configure ADXL345 With RPi","text":"

    First, check and follow the instructions in the RPi Microcontroller document to setup the \"linux mcu\" on the Raspberry Pi. This will configure a second Kalico instance that runs on your Pi.

    Make sure the Linux SPI driver is enabled by running sudo raspi-config and enabling SPI under the \"Interfacing options\" menu.

    Add the following to the printer.cfg file:

    [mcu rpi]\nserial: /tmp/klipper_host_mcu\n\n[adxl345]\ncs_pin: rpi:None\n\n[resonance_tester]\naccel_chip: adxl345\nprobe_points:\n    100, 100, 20  # an example\n

    It is advised to start with 1 probe point, in the middle of the print bed, slightly above it.

    "},{"location":"Measuring_Resonances.html#configure-adxl345-with-pi-pico","title":"Configure ADXL345 With Pi Pico","text":""},{"location":"Measuring_Resonances.html#flash-the-pico-firmware","title":"Flash the Pico Firmware","text":"

    On your Raspberry Pi, compile the firmware for the Pico.

    cd ~/klipper\nmake clean\nmake menuconfig\n

    Now, while holding down the BOOTSEL button on the Pico, connect the Pico to the Raspberry Pi via USB. Compile and flash the firmware.

    make flash FLASH_DEVICE=first\n

    If that fails, you will be told which FLASH_DEVICE to use. In this example, that's make flash FLASH_DEVICE=2e8a:0003.

    "},{"location":"Measuring_Resonances.html#configure-the-connection","title":"Configure the Connection","text":"

    The Pico will now reboot with the new firmware and should show up as a serial device. Find the pico serial device with ls /dev/serial/by-id/*. You can now add an adxl.cfg file with the following settings:

    [mcu adxl]\n# Change <mySerial> to whatever you found above. For example,\n# usb-Klipper_rp2040_E661640843545B2E-if00\nserial: /dev/serial/by-id/usb-Klipper_rp2040_<mySerial>\n\n[adxl345]\ncs_pin: adxl:gpio1\nspi_bus: spi0a\naxes_map: x,z,y\n\n[resonance_tester]\naccel_chip: adxl345\nprobe_points:\n    # Somewhere slightly above the middle of your print bed\n    147,154, 20\n\n[output_pin power_mode] # Improve power stability\npin: adxl:gpio23\n

    If setting up the ADXL345 configuration in a separate file, as shown above, you'll also want to modify your printer.cfg file to include this:

    [include adxl.cfg] # Comment this out when you disconnect the accelerometer\n

    Restart Kalico via the RESTART command.

    "},{"location":"Measuring_Resonances.html#configure-lis2dw-series","title":"Configure LIS2DW series","text":"
    [mcu lis]\n# Change <mySerial> to whatever you found above. For example,\n# usb-Klipper_rp2040_E661640843545B2E-if00\nserial: /dev/serial/by-id/usb-Klipper_rp2040_<mySerial>\n\n[lis2dw]\ncs_pin: lis:gpio1\nspi_bus: spi0a\naxes_map: x,z,y\n\n[resonance_tester]\naccel_chip: lis2dw\nprobe_points:\n    # Somewhere slightly above the middle of your print bed\n    147,154, 20\n
    "},{"location":"Measuring_Resonances.html#configure-mpu-60009000-series-with-rpi","title":"Configure MPU-6000/9000 series With RPi","text":"

    Make sure the Linux I2C driver is enabled and the baud rate is set to 400000 (see Enabling I2C section for more details). Then, add the following to the printer.cfg:

    [mcu rpi]\nserial: /tmp/klipper_host_mcu\n\n[mpu9250]\ni2c_mcu: rpi\ni2c_bus: i2c.1\n\n[resonance_tester]\naccel_chip: mpu9250\nprobe_points:\n    100, 100, 20  # an example\n
    "},{"location":"Measuring_Resonances.html#configure-mpu-9520-compatibles-with-pico","title":"Configure MPU-9520 Compatibles With Pico","text":"

    Pico I2C is set to 400000 on default. Simply add the following to the printer.cfg:

    [mcu pico]\nserial: /dev/serial/by-id/<your Pico's serial ID>\n\n[mpu9250]\ni2c_mcu: pico\ni2c_bus: i2c0a\n\n[resonance_tester]\naccel_chip: mpu9250\nprobe_points:\n    100, 100, 20  # an example\n\n[static_digital_output pico_3V3pwm] # Improve power stability\npins: pico:gpio23\n
    "},{"location":"Measuring_Resonances.html#configure-mpu-9520-compatibles-with-avr","title":"Configure MPU-9520 Compatibles with AVR","text":"

    AVR I2C will be set to 400000 by the mpu9250 option. Simply add the following to the printer.cfg:

    [mcu nano]\nserial: /dev/serial/by-id/<your nano's serial ID>\n\n[mpu9250]\ni2c_mcu: nano\n\n[resonance_tester]\naccel_chip: mpu9250\nprobe_points:\n    100, 100, 20  # an example\n

    Restart Kalico via the RESTART command.

    "},{"location":"Measuring_Resonances.html#measuring-the-resonances","title":"Measuring the resonances","text":""},{"location":"Measuring_Resonances.html#checking-the-setup","title":"Checking the setup","text":"

    Now you can test a connection.

    You should see the current measurements from the accelerometer, including the free-fall acceleration, e.g.

    Recv: // adxl345 values (x, y, z): 470.719200, 941.438400, 9728.196800\n

    If you get an error like Invalid adxl345 id (got xx vs e5), where xx is some other ID, immediately try again. There's an issue with SPI initialization. If you still get an error, it is indicative of the connection problem with ADXL345, or the faulty sensor. Double-check the power, the wiring (that it matches the schematics, no wire is broken or loose, etc.), and soldering quality.

    If you are using a MPU-9250 compatible accelerometer and it shows up as mpu-unknown, use with caution! They are probably refurbished chips!

    Next, try running MEASURE_AXES_NOISE in Octoprint, you should get some baseline numbers for the noise of accelerometer on the axes (should be somewhere in the range of ~1-100). Too high axes noise (e.g. 1000 and more) can be indicative of the sensor issues, problems with its power, or too noisy imbalanced fans on a 3D printer.

    "},{"location":"Measuring_Resonances.html#measuring-the-resonances_1","title":"Measuring the resonances","text":"

    Now you can run some real-life tests. Run the following command:

    TEST_RESONANCES AXIS=X\n

    Note that it will create vibrations on X axis. It will also disable input shaping if it was enabled previously, as it is not valid to run the resonance testing with the input shaper enabled.

    Attention! Be sure to observe the printer for the first time, to make sure the vibrations do not become too violent (M112 command can be used to abort the test in case of emergency; hopefully it will not come to this though). If the vibrations do get too strong, you can attempt to specify a lower than the default value for accel_per_hz parameter in [resonance_tester] section, e.g.

    [resonance_tester]\naccel_chip: adxl345\naccel_per_hz: 50  # default is 75\nprobe_points: ...\n

    If it works for X axis, run for Y axis as well:

    TEST_RESONANCES AXIS=Y\n

    This will generate 2 CSV files (/tmp/resonances_x_*.csv and /tmp/resonances_y_*.csv). These files can be processed with the stand-alone script on a Raspberry Pi. This script is intended to be run with a single CSV file for each axis measured, although it can be used with multiple CSV files if you desire to average the results. Averaging results can be useful, for example, if resonance tests were done at multiple test points. Delete the extra CSV files if you do not desire to average them.

    ~/klippy-env/bin/python ~/klipper/scripts/calibrate_shaper.py /tmp/resonances_x_*.csv -o /tmp/shaper_calibrate_x.png\n~/klippy-env/bin/python ~/klipper/scripts/calibrate_shaper.py /tmp/resonances_y_*.csv -o /tmp/shaper_calibrate_y.png\n

    This script will generate the charts /tmp/shaper_calibrate_x.png and /tmp/shaper_calibrate_y.png with frequency responses. You will also get the suggested frequencies for each input shaper, as well as which input shaper is recommended for your setup. For example:

    Fitted shaper 'zv' frequency = 34.4 Hz (vibrations = 4.0%, smoothing ~= 0.132)\nTo avoid too much smoothing with 'zv', suggested max_accel <= 4500 mm/sec^2\nFitted shaper 'mzv' frequency = 34.6 Hz (vibrations = 0.0%, smoothing ~= 0.170)\nTo avoid too much smoothing with 'mzv', suggested max_accel <= 3500 mm/sec^2\nFitted shaper 'ei' frequency = 41.4 Hz (vibrations = 0.0%, smoothing ~= 0.188)\nTo avoid too much smoothing with 'ei', suggested max_accel <= 3200 mm/sec^2\nFitted shaper '2hump_ei' frequency = 51.8 Hz (vibrations = 0.0%, smoothing ~= 0.201)\nTo avoid too much smoothing with '2hump_ei', suggested max_accel <= 3000 mm/sec^2\nFitted shaper '3hump_ei' frequency = 61.8 Hz (vibrations = 0.0%, smoothing ~= 0.215)\nTo avoid too much smoothing with '3hump_ei', suggested max_accel <= 2800 mm/sec^2\nRecommended shaper is mzv @ 34.6 Hz\n

    The suggested configuration can be added to [input_shaper] section of printer.cfg, e.g.:

    [input_shaper]\nshaper_freq_x: ...\nshaper_type_x: ...\nshaper_freq_y: 34.6\nshaper_type_y: mzv\n\n[printer]\nmax_accel: 3000  # should not exceed the estimated max_accel for X and Y axes\n

    or you can choose some other configuration yourself based on the generated charts: peaks in the power spectral density on the charts correspond to the resonance frequencies of the printer.

    Note that alternatively you can run the input shaper auto-calibration from Kalico directly, which can be convenient, for example, for the input shaper re-calibration.

    "},{"location":"Measuring_Resonances.html#bed-slinger-printers","title":"Bed-slinger printers","text":"

    If your printer is a bed slinger printer, you will need to change the location of the accelerometer between the measurements for X and Y axes: measure the resonances of X axis with the accelerometer attached to the toolhead and the resonances of Y axis - to the bed (the usual bed slinger setup).

    However, you can also connect two accelerometers simultaneously, though the ADXL345 must be connected to different boards (say, to an RPi and printer MCU board), or to two different physical SPI interfaces on the same board (rarely available). Then they can be configured in the following manner:

    [adxl345 hotend]\n# Assuming `hotend` chip is connected to an RPi\ncs_pin: rpi:None\n\n[adxl345 bed]\n# Assuming `bed` chip is connected to a printer MCU board\ncs_pin: ...  # Printer board SPI chip select (CS) pin\n\n[resonance_tester]\n# Assuming the typical setup of the bed slinger printer\naccel_chip_x: adxl345 hotend\naccel_chip_y: adxl345 bed\nprobe_points: ...\n

    Two MPUs can share one I2C bus, but they cannot measure simultaneously as the 400kbit/s I2C bus is not fast enough. One must have its AD0 pin pulled-down to 0V (address 104) and the other its AD0 pin pulled-up to 3.3V (address 105):

    [mpu9250 hotend]\ni2c_mcu: rpi\ni2c_bus: i2c.1\ni2c_address: 104 # This MPU has pin AD0 pulled low\n\n[mpu9250 bed]\ni2c_mcu: rpi\ni2c_bus: i2c.1\ni2c_address: 105 # This MPU has pin AD0 pulled high\n\n[resonance_tester]\n# Assuming the typical setup of the bed slinger printer\naccel_chip_x: mpu9250 hotend\naccel_chip_y: mpu9250 bed\nprobe_points: ...\n

    [Test with each MPU individually before connecting both to the bus for easy debugging.]

    Then the commands TEST_RESONANCES AXIS=X and TEST_RESONANCES AXIS=Y will use the correct accelerometer for each axis.

    "},{"location":"Measuring_Resonances.html#max-smoothing","title":"Max smoothing","text":"

    Keep in mind that the input shaper can create some smoothing in parts. Automatic tuning of the input shaper performed by calibrate_shaper.py script or SHAPER_CALIBRATE command tries not to exacerbate the smoothing, but at the same time they try to minimize the resulting vibrations. Sometimes they can make a sub-optimal choice of the shaper frequency, or maybe you simply prefer to have less smoothing in parts at the expense of a larger remaining vibrations. In these cases, you can request to limit the maximum smoothing from the input shaper.

    Let's consider the following results from the automatic tuning:

    Fitted shaper 'zv' frequency = 57.8 Hz (vibrations = 20.3%, smoothing ~= 0.053)\nTo avoid too much smoothing with 'zv', suggested max_accel <= 13000 mm/sec^2\nFitted shaper 'mzv' frequency = 34.8 Hz (vibrations = 3.6%, smoothing ~= 0.168)\nTo avoid too much smoothing with 'mzv', suggested max_accel <= 3600 mm/sec^2\nFitted shaper 'ei' frequency = 48.8 Hz (vibrations = 4.9%, smoothing ~= 0.135)\nTo avoid too much smoothing with 'ei', suggested max_accel <= 4400 mm/sec^2\nFitted shaper '2hump_ei' frequency = 45.2 Hz (vibrations = 0.1%, smoothing ~= 0.264)\nTo avoid too much smoothing with '2hump_ei', suggested max_accel <= 2200 mm/sec^2\nFitted shaper '3hump_ei' frequency = 48.0 Hz (vibrations = 0.0%, smoothing ~= 0.356)\nTo avoid too much smoothing with '3hump_ei', suggested max_accel <= 1500 mm/sec^2\nRecommended shaper is 2hump_ei @ 45.2 Hz\n

    Note that the reported smoothing values are some abstract projected values. These values can be used to compare different configurations: the higher the value, the more smoothing a shaper will create. However, these smoothing scores do not represent any real measure of smoothing, because the actual smoothing depends on max_accel and square_corner_velocity parameters. Therefore, you should print some test prints to see how much smoothing exactly a chosen configuration creates.

    In the example above the suggested shaper parameters are not bad, but what if you want to get less smoothing on the X axis? You can try to limit the maximum shaper smoothing using the following command:

    ~/klippy-env/bin/python ~/klipper/scripts/calibrate_shaper.py /tmp/resonances_x_*.csv -o /tmp/shaper_calibrate_x.png --max_smoothing=0.2\n

    which limits the smoothing to 0.2 score. Now you can get the following result:

    Fitted shaper 'zv' frequency = 55.4 Hz (vibrations = 19.7%, smoothing ~= 0.057)\nTo avoid too much smoothing with 'zv', suggested max_accel <= 12000 mm/sec^2\nFitted shaper 'mzv' frequency = 34.6 Hz (vibrations = 3.6%, smoothing ~= 0.170)\nTo avoid too much smoothing with 'mzv', suggested max_accel <= 3500 mm/sec^2\nFitted shaper 'ei' frequency = 48.2 Hz (vibrations = 4.8%, smoothing ~= 0.139)\nTo avoid too much smoothing with 'ei', suggested max_accel <= 4300 mm/sec^2\nFitted shaper '2hump_ei' frequency = 52.0 Hz (vibrations = 2.7%, smoothing ~= 0.200)\nTo avoid too much smoothing with '2hump_ei', suggested max_accel <= 3000 mm/sec^2\nFitted shaper '3hump_ei' frequency = 72.6 Hz (vibrations = 1.4%, smoothing ~= 0.155)\nTo avoid too much smoothing with '3hump_ei', suggested max_accel <= 3900 mm/sec^2\nRecommended shaper is 3hump_ei @ 72.6 Hz\n

    If you compare to the previously suggested parameters, the vibrations are a bit larger, but the smoothing is significantly smaller than previously, allowing larger maximum acceleration.

    When deciding which max_smoothing parameter to choose, you can use a trial-and-error approach. Try a few different values and see which results you get. Note that the actual smoothing produced by the input shaper depends, primarily, on the lowest resonance frequency of the printer: the higher the frequency of the lowest resonance - the smaller the smoothing. Therefore, if you request the script to find a configuration of the input shaper with the unrealistically small smoothing, it will be at the expense of increased ringing at the lowest resonance frequencies (which are, typically, also more prominently visible in prints). So, always double-check the projected remaining vibrations reported by the script and make sure they are not too high.

    Note that if you chose a good max_smoothing value for both of your axes, you can store it in the printer.cfg as

    [resonance_tester]\naccel_chip: ...\nprobe_points: ...\nmax_smoothing: 0.25  # an example\n

    Then, if you rerun the input shaper auto-tuning using SHAPER_CALIBRATE Kalico command in the future, it will use the stored max_smoothing value as a reference.

    "},{"location":"Measuring_Resonances.html#selecting-max_accel","title":"Selecting max_accel","text":"

    Since the input shaper can create some smoothing in parts, especially at high accelerations, you will still need to choose the max_accel value that does not create too much smoothing in the printed parts. A calibration script provides an estimate for max_accel parameter that should not create too much smoothing. Note that the max_accel as displayed by the calibration script is only a theoretical maximum at which the respective shaper is still able to work without producing too much smoothing. It is by no means a recommendation to set this acceleration for printing. The maximum acceleration your printer is able to sustain depends on its mechanical properties and the maximum torque of the used stepper motors. Therefore, it is suggested to set max_accel in [printer] section that does not exceed the estimated values for X and Y axes, likely with some conservative safety margin.

    Alternatively, follow this part of the input shaper tuning guide and print the test model to choose max_accel parameter experimentally.

    The same notice applies to the input shaper auto-calibration with SHAPER_CALIBRATE command: it is still necessary to choose the right max_accel value after the auto-calibration, and the suggested acceleration limits will not be applied automatically.

    Keep in mind that the maximum acceleration without too much smoothing depends on the square_corner_velocity. The general recommendation is not to change it from its default value 5.0, and this is the value used by default by the calibrate_shaper.py script. If you did change it though, you should inform the script about it by passing --square_corner_velocity=... parameter, e.g.

    ~/klippy-env/bin/python ~/klipper/scripts/calibrate_shaper.py /tmp/resonances_x_*.csv -o /tmp/shaper_calibrate_x.png --square_corner_velocity=10.0\n

    so that it can calculate the maximum acceleration recommendations correctly. Note that the SHAPER_CALIBRATE command already takes the configured square_corner_velocity parameter into account, and there is no need to specify it explicitly.

    If you are doing a shaper re-calibration and the reported smoothing for the suggested shaper configuration is almost the same as what you got during the previous calibration, this step can be skipped.

    "},{"location":"Measuring_Resonances.html#testing-custom-axes","title":"Testing custom axes","text":"

    TEST_RESONANCES command supports custom axes. While this is not really useful for input shaper calibration, it can be used to study printer resonances in-depth and to check, for example, belt tension.

    To check the belt tension on CoreXY printers, execute

    TEST_RESONANCES AXIS=1,1 OUTPUT=raw_data\nTEST_RESONANCES AXIS=1,-1 OUTPUT=raw_data\n

    and use graph_accelerometer.py to process the generated files, e.g.

    ~/klippy-env/bin/python ~/klipper/scripts/graph_accelerometer.py -c /tmp/raw_data_axis*.csv -o /tmp/resonances.png\n

    which will generate /tmp/resonances.png comparing the resonances.

    For Delta printers with the default tower placement (tower A ~= 210 degrees, B ~= 330 degrees, and C ~= 90 degrees), execute

    TEST_RESONANCES AXIS=0,1 OUTPUT=raw_data\nTEST_RESONANCES AXIS=-0.866025404,-0.5 OUTPUT=raw_data\nTEST_RESONANCES AXIS=0.866025404,-0.5 OUTPUT=raw_data\n

    and then use the same command

    ~/klippy-env/bin/python ~/klipper/scripts/graph_accelerometer.py -c /tmp/raw_data_axis*.csv -o /tmp/resonances.png\n

    to generate /tmp/resonances.png comparing the resonances.

    "},{"location":"Measuring_Resonances.html#input-shaper-auto-calibration","title":"Input Shaper auto-calibration","text":"

    Besides manually choosing the appropriate parameters for the input shaper feature, it is also possible to run the auto-tuning for the input shaper directly from Kalico. Run the following command via Octoprint terminal:

    SHAPER_CALIBRATE\n

    This will run the full test for both axes and generate the csv output (/tmp/calibration_data_*.csv by default) for the frequency response and the suggested input shapers. You will also get the suggested frequencies for each input shaper, as well as which input shaper is recommended for your setup, on Octoprint console. For example:

    Calculating the best input shaper parameters for y axis\nFitted shaper 'zv' frequency = 39.0 Hz (vibrations = 13.2%, smoothing ~= 0.105)\nTo avoid too much smoothing with 'zv', suggested max_accel <= 5900 mm/sec^2\nFitted shaper 'mzv' frequency = 36.8 Hz (vibrations = 1.7%, smoothing ~= 0.150)\nTo avoid too much smoothing with 'mzv', suggested max_accel <= 4000 mm/sec^2\nFitted shaper 'ei' frequency = 36.6 Hz (vibrations = 2.2%, smoothing ~= 0.240)\nTo avoid too much smoothing with 'ei', suggested max_accel <= 2500 mm/sec^2\nFitted shaper '2hump_ei' frequency = 48.0 Hz (vibrations = 0.0%, smoothing ~= 0.234)\nTo avoid too much smoothing with '2hump_ei', suggested max_accel <= 2500 mm/sec^2\nFitted shaper '3hump_ei' frequency = 59.0 Hz (vibrations = 0.0%, smoothing ~= 0.235)\nTo avoid too much smoothing with '3hump_ei', suggested max_accel <= 2500 mm/sec^2\nRecommended shaper_type_y = mzv, shaper_freq_y = 36.8 Hz\n

    If you agree with the suggested parameters, you can execute SAVE_CONFIG now to save them and restart the Kalico. Note that this will not update max_accel value in [printer] section. You should update it manually following the considerations in Selecting max_accel section.

    If your printer is a bed slinger printer, you can specify which axis to test, so that you can change the accelerometer mounting point between the tests (by default the test is performed for both axes):

    SHAPER_CALIBRATE AXIS=Y\n

    You can execute SAVE_CONFIG twice - after calibrating each axis.

    However, if you connected two accelerometers simultaneously, you simply run SHAPER_CALIBRATE without specifying an axis to calibrate the input shaper for both axes in one go.

    "},{"location":"Measuring_Resonances.html#input-shaper-re-calibration","title":"Input Shaper re-calibration","text":"

    SHAPER_CALIBRATE command can be also used to re-calibrate the input shaper in the future, especially if some changes to the printer that can affect its kinematics are made. One can either re-run the full calibration using SHAPER_CALIBRATE command, or restrict the auto-calibration to a single axis by supplying AXIS= parameter, like

    SHAPER_CALIBRATE AXIS=X\n

    Warning! It is not advisable to run the shaper auto-calibration very frequently (e.g. before every print, or every day). In order to determine resonance frequencies, auto-calibration creates intensive vibrations on each of the axes. Generally, 3D printers are not designed to withstand a prolonged exposure to vibrations near the resonance frequencies. Doing so may increase wear of the printer components and reduce their lifespan. There is also an increased risk of some parts unscrewing or becoming loose. Always check that all parts of the printer (including the ones that may normally not move) are securely fixed in place after each auto-tuning.

    Also, due to some noise in measurements, it is possible that the tuning results will be slightly different from one calibration run to another one. Still, it is not expected that the noise will affect the print quality too much. However, it is still advised to double-check the suggested parameters, and print some test prints before using them to confirm they are good.

    "},{"location":"Measuring_Resonances.html#offline-processing-of-the-accelerometer-data","title":"Offline processing of the accelerometer data","text":"

    It is possible to generate the raw accelerometer data and process it offline (e.g. on a host machine), for example to find resonances. In order to do so, run the following commands via Octoprint terminal:

    SET_INPUT_SHAPER SHAPER_FREQ_X=0 SHAPER_FREQ_Y=0\nTEST_RESONANCES AXIS=X OUTPUT=raw_data\n

    ignoring any errors for SET_INPUT_SHAPER command. For TEST_RESONANCES command, specify the desired test axis. The raw data will be written into /tmp directory on the RPi.

    The raw data can also be obtained by running the command ACCELEROMETER_MEASURE command twice during some normal printer activity - first to start the measurements, and then to stop them and write the output file. Refer to G-Codes for more details.

    The data can be processed later by the following scripts: scripts/graph_accelerometer.py and scripts/calibrate_shaper.py. Both of them accept one or several raw csv files as the input depending on the mode. The graph_accelerometer.py script supports several modes of operation:

    Note that graph_accelerometer.py script supports only the raw_data*.csv files and not resonances*.csv or calibration_data*.csv files.

    For example,

    ~/klippy-env/bin/python ~/klipper/scripts/graph_accelerometer.py /tmp/raw_data_x_*.csv -o /tmp/resonances_x.png -c -a z\n

    will plot the comparison of several /tmp/raw_data_x_*.csv files for Z axis to /tmp/resonances_x.png file.

    The shaper_calibrate.py script accepts 1 or several inputs and can run automatic tuning of the input shaper and suggest the best parameters that work well for all provided inputs. It prints the suggested parameters to the console, and can additionally generate the chart if -o output.png parameter is provided, or the CSV file if -c output.csv parameter is specified.

    Providing several inputs to shaper_calibrate.py script can be useful if running some advanced tuning of the input shapers, for example:

    "},{"location":"Migrating_from_Klipper.html","title":"Migrating from Klipper","text":"

    Note

    Any add-on modules you are using will need to be reinstalled after switching to Kalico. This includes things like Beacon support, led-effect, etc.

    Any data in ~/printer_data such as printer configs and macros will be unaffected, THOUGH do back up just in case.

    "},{"location":"Migrating_from_Klipper.html#option-1-manually-clone-the-repository","title":"Option 1. Manually clone the repository","text":"

    If desired, make a backup copy of your existing Klipper installation by running:

    mv ~/klipper ~/klipper_old\n

    Then clone the Kalico repo and restart the klipper service:

    git clone https://github.com/KalicoCrew/kalico.git ~/klipper\nsudo systemctl restart klipper\n
    "},{"location":"Migrating_from_Klipper.html#option-2-using-kiauh","title":"Option 2. Using KIAUH","text":"

    For users that are not comfortable using Git directly, KIAUH v6 is able to use custom repositories.

    To do this, add the Kalico repo to KIAUH's custom repository settings with the following steps:

    From the KIAUH menu select:

    "},{"location":"Migrating_from_Klipper.html#option-3-adding-a-git-remote-to-the-existing-installation","title":"Option 3. Adding a git-remote to the existing installation","text":"

    Can switch back to mainline klipper at any time via a git checkout upstream_main

    cd ~/klipper\ngit remote add kalico https://github.com/KalicoCrew/kalico.git\ngit checkout -b upstream-main origin/master\ngit branch -D master\ngit fetch kalico main\ngit checkout -b main kalico/main\nsudo systemctl restart klipper\nsudo systemctl restart moonraker\n
    "},{"location":"Multi_MCU_Homing.html","title":"Multiple Micro-controller Homing and Probing","text":"

    Kalico supports a mechanism for homing with an endstop attached to one micro-controller while its stepper motors are on a different micro-controller. This support is referred to as \"multi-mcu homing\". This feature is also used when a Z probe is on a different micro-controller than the Z stepper motors.

    This feature can be useful to simplify wiring, as it may be more convenient to attach an endstop or probe to a closer micro-controller. However, using this feature may result in \"overshoot\" of the stepper motors during homing and probing operations.

    The overshoot occurs due to possible message transmission delays between the micro-controller monitoring the endstop and the micro-controllers moving the stepper motors. The Kalico code is designed to limit this delay to no more than 25ms. (When multi-mcu homing is activated, the micro-controllers send periodic status messages and check that corresponding status messages are received within 25ms.)

    So, for example, if homing at 10mm/s then it is possible for an overshoot of up to 0.250mm (10mm/s * .025s == 0.250mm). Care should be taken when configuring multi-mcu homing to account for this type of overshoot. Using slower homing or probing speeds can reduce the overshoot.

    Stepper motor overshoot should not adversely impact the precision of the homing and probing procedure. The Kalico code will detect the overshoot and account for it in its calculations. However, it is important that the hardware design is capable of handling overshoot without causing damage to the machine.

    In order to use this \"multi-mcu homing\" capability the hardware must have predictably low latency between the host computer and all of the micro-controllers. Typically the round-trip time must be consistently less than 10ms. High latency (even for short periods) is likely to result in homing failures.

    Should high latency result in a failure (or if some other communication issue is detected) then Kalico will raise a \"Communication timeout during homing\" error.

    Note that an axis with multiple steppers (eg, stepper_z and stepper_z1) need to be on the same micro-controller in order to use multi-mcu homing. For example, if an endstop is on a separate micro-controller from stepper_z then stepper_z1 must be on the same micro-controller as stepper_z.

    "},{"location":"OctoPrint.html","title":"Using OctoPrint","text":"

    Kalico has a few options for its front ends, Octoprint was the first and original front end for Kalico. This document will give a brief overview of installing with this option.

    "},{"location":"OctoPrint.html#install-with-octopi","title":"Install with OctoPi","text":"

    Start by installing OctoPi on the Raspberry Pi computer. Use OctoPi v0.17.0 or later - see the OctoPi releases for release information.

    One should verify that OctoPi boots and that the OctoPrint web server works. After connecting to the OctoPrint web page, follow the prompt to upgrade OctoPrint if needed.

    After installing OctoPi and upgrading OctoPrint, it will be necessary to ssh into the target machine to run a handful of system commands.

    Start by running these commands on your host device:

    If you do not have git installed, please do so with:

    sudo apt install git\n

    then proceed:

    cd ~\ngit clone https://github.com/KalicoCrew/kalico klipper\n./klipper/scripts/install-octopi.sh\n

    The above will download Kalico, install the needed system dependencies, setup Kalico to run at system startup, and start the Kalico host software. It will require an internet connection and it may take a few minutes to complete.

    "},{"location":"OctoPrint.html#installing-with-kiauh","title":"Installing with KIAUH","text":"

    KIAUH can be used to install OctoPrint on a variety of Linux based systems that run a form of Debian. More information can be found at https://github.com/dw-0/kiauh

    "},{"location":"OctoPrint.html#configuring-octoprint-to-use-kalico","title":"Configuring OctoPrint to use Kalico","text":"

    The OctoPrint web server needs to be configured to communicate with the Kalico host software. Using a web browser, login to the OctoPrint web page and then configure the following items:

    Navigate to the Settings tab (the wrench icon at the top of the page). Under \"Serial Connection\" in \"Additional serial ports\" add:

    ~/printer_data/comms/klippy.serial\n

    Then click \"Save\".

    In some older setups this address may be /tmp/printer, depending on your setup, you may need to keep this line as well

    Enter the Settings tab again and under \"Serial Connection\" change the \"Serial Port\" setting to the one added above.

    In the Settings tab, navigate to the \"Behavior\" sub-tab and select the \"Cancel any ongoing prints but stay connected to the printer\" option. Click \"Save\".

    From the main page, under the \"Connection\" section (at the top left of the page) make sure the \"Serial Port\" is set to the new additional one added and click \"Connect\". (If it is not in the available selection then try reloading the page.)

    Once connected, navigate to the \"Terminal\" tab and type \"status\" (without the quotes) into the command entry box and click \"Send\". The terminal window will likely report there is an error opening the config file - that means OctoPrint is successfully communicating with Kalico.

    Please proceed to Installation.md and the Building and flashing the micro-controller section

    "},{"location":"Overview.html","title":"Overview","text":"

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

    "},{"location":"Overview.html#overview-information","title":"Overview information","text":""},{"location":"Overview.html#installation-and-configuration","title":"Installation and Configuration","text":""},{"location":"Overview.html#developer-documentation","title":"Developer Documentation","text":""},{"location":"Overview.html#device-specific-documents","title":"Device Specific Documents","text":""},{"location":"PID.html","title":"PID","text":"

    PID control is a widely used control method in the 3D printing world. It\u2019s ubiquitous when it comes to temperature control, be it with heaters to generate heat or fans to remove heat. This document aims to provide a high-level overview of what PID is and how to use it best in Kalico.

    "},{"location":"PID.html#pid-calibration","title":"PID Calibration","text":""},{"location":"PID.html#preparing-the-calibration","title":"Preparing the Calibration","text":"

    When a calibration test is performed external influences should be minimized as much as possible:

    More important than listed above, PID how you print. If your part fans are on when printing, PID tune with them on.

    "},{"location":"PID.html#choosing-the-right-pid-algorithm","title":"Choosing the right PID Algorithm","text":"

    Kalico offers two different PID algorithms: Positional and Velocity

    Refer to the control statement in the Configuration Reference.

    "},{"location":"PID.html#running-the-pid-calibration","title":"Running the PID Calibration","text":"

    The PID calibration is invoked via the PID_CALIBRATE command. This command will heat up the respective heater and let it cool down around the target temperature in multiple cycles to determine the needed parameters.

    Such a calibration cycles looks like the following snippet:

    3:12 PM   PID_CALIBRATE HEATER=extruder TARGET=220 TOLERANCE=0.01 WRITE_FILE=1\n3:15 PM   sample:1 pwm:1.0000 asymmetry:3.7519 tolerance:n/a\n3:15 PM   sample:2 pwm:0.6229 asymmetry:0.3348 tolerance:n/a\n3:16 PM   sample:3 pwm:0.5937 asymmetry:0.0840 tolerance:n/a\n3:17 PM   sample:4 pwm:0.5866 asymmetry:0.0169 tolerance:0.4134\n3:18 PM   sample:5 pwm:0.5852 asymmetry:0.0668 tolerance:0.0377\n3:18 PM   sample:6 pwm:0.5794 asymmetry:0.0168 tolerance:0.0142\n3:19 PM   sample:7 pwm:0.5780 asymmetry:-0.1169 tolerance:0.0086\n3:19 PM   PID parameters: pid_Kp=16.538 pid_Ki=0.801 pid_Kd=85.375\n               The SAVE_CONFIG command will update the printer config file\n               with these parameters and restart the printer.\n

    Note the asymmetry information. It provides an indication if the heater's power is sufficient to ensure a symmetrical \"heat up\" versus \"cool down / heat loss\" behavior. It should start positive and converge to zero. A negative starting value indicates that the heat loss is faster than the heat up, this means the system is asymmetrical. The calibration will still be successful but reserves to counter disturbances might be low.

    "},{"location":"PID.html#advanced-manual-calibration","title":"Advanced / Manual Calibration","text":"

    Many methods exist for calculating control parameters, such as Ziegler-Nichols, Cohen-Coon, Kappa-Tau, Lambda, and many more. By default, classical Ziegler-Nichols parameters are generated. If a user wants to experiment with other flavors of Ziegler-Nichols, or Cohen-Coon parameters, they can extract the constants from the log as seen below and enter them into this spreadsheet.

    Ziegler-Nichols constants: Ku=0.103092 Tu=41.800000\nCohen-Coon constants: Km=-17.734845 Theta=6.600000 Tau=-10.182680\n

    Classic Ziegler-Nichols parameters work in all scenarios. Cohen-Coon parameters work better with systems that have a large amount of dead time/delay. For example, if a printer has a bed with a large thermal mass that\u2019s slow to heat up and stabilize, the Cohen-Coon parameters will generally do a better job at controlling it.

    "},{"location":"PID.html#further-readings","title":"Further Readings","text":""},{"location":"PID.html#history","title":"History","text":"

    The first rudimentary PID controller was developed by Elmer Sperry in 1911 to automate the control of a ship's rudder. Engineer Nicolas Minorsky published the first mathematical analysis of a PID controller in 1922. In 1942, John Ziegler & Nathaniel Nichols published their seminal paper, \"Optimum Settings for Automatic Controllers,\" which described a trial-and-error method for tuning a PID controller, now commonly referred to as the \"Ziegler-Nichols method.

    In 1984, Karl Astrom and Tore Hagglund published their paper \"Automatic Tuning of Simple Regulators with Specifications on Phase and Amplitude Margins\". In the paper they introduced an automatic tuning method commonly referred to as the \"Astrom-Hagglund method\" or the \"relay method\".

    In 2019 Brandon Taysom & Carl Sorensen published their paper \"Adaptive Relay Autotuning under Static and Non-static Disturbances with Application to Friction Stir Welding\", which laid out a method to generate more accurate results from a relay test. This is the PID calibration method currently used by Kalico.

    "},{"location":"PID.html#details-of-the-relay-test","title":"Details of the Relay Test","text":"

    As previously mentioned, Kalico uses a relay test for calibration purposes. A standard relay test is conceptually simple. You turn the heater\u2019s power on and off to get it to oscillate about the target temperature, as seen in the following graph.

    The above graph shows a common issue with a standard relay test. If the system being calibrated has too much or too little power for the chosen target temperature, it will produce biased and asymmetric results. As can be seen above, the system spends more time in the off state than on and has a larger amplitude above the target temperature than below.

    In an ideal system, both the on and off times and the amplitude above and below the target temperature would be the same. 3D printers don\u2019t actively cool the hot end or bed, so they can never reach the ideal state.

    The following graph is a relay test based on the methodology laid out by Taysom & Sorensen. After each iteration, the data is analyzed and a new maximum power setting is calculated. As can be seen, the system starts the test asymmetric but ends very symmetric.

    Asymmetry can be monitored in real time during a calibration run. It can also provide insight into how suitable the heater is for the current calibration parameters. When asymmetry starts off positive and converges to zero, the heater has more than enough power to achieve symmetry for the calibration parameters.

    3:12 PM   PID_CALIBRATE HEATER=extruder TARGET=220 TOLERANCE=0.01 WRITE_FILE=1\n3:15 PM   sample:1 pwm:1.0000 asymmetry:3.7519 tolerance:n/a\n3:15 PM   sample:2 pwm:0.6229 asymmetry:0.3348 tolerance:n/a\n3:16 PM   sample:3 pwm:0.5937 asymmetry:0.0840 tolerance:n/a\n3:17 PM   sample:4 pwm:0.5866 asymmetry:0.0169 tolerance:0.4134\n3:18 PM   sample:5 pwm:0.5852 asymmetry:0.0668 tolerance:0.0377\n3:18 PM   sample:6 pwm:0.5794 asymmetry:0.0168 tolerance:0.0142\n3:19 PM   sample:7 pwm:0.5780 asymmetry:-0.1169 tolerance:0.0086\n3:19 PM   PID parameters: pid_Kp=16.538 pid_Ki=0.801 pid_Kd=85.375\n               The SAVE_CONFIG command will update the printer config file\n               with these parameters and restart the printer.\n

    When asymmetry starts off negative, It will not converge to zero. If Kalico does not error out, the calibration run will complete and provide good PID parameters, However the heater is less likely to handle disturbances as well as a heater with power in reserve.

    3:36 PM   PID_CALIBRATE HEATER=extruder TARGET=220 TOLERANCE=0.01 WRITE_FILE=1\n3:38 PM   sample:1 pwm:1.0000 asymmetry:-2.1149 tolerance:n/a\n3:39 PM   sample:2 pwm:1.0000 asymmetry:-2.0140 tolerance:n/a\n3:39 PM   sample:3 pwm:1.0000 asymmetry:-1.8811 tolerance:n/a\n3:40 PM   sample:4 pwm:1.0000 asymmetry:-1.8978 tolerance:0.0000\n3:40 PM   PID parameters: pid_Kp=21.231 pid_Ki=1.227 pid_Kd=91.826\n               The SAVE_CONFIG command will update the printer config file\n               with these parameters and restart the printer.\n
    "},{"location":"PID.html#pid-control-algorithms","title":"Pid Control Algorithms","text":"

    Kalico currently supports two control algorithms: Positional and Velocity. The fundamental difference between the two algorithms is that the Positional algorithm calculates what the PWM value should be for the current time interval, and the Velocity algorithm calculates how much the previous PWM setting should be changed to get the PWM value for the current time interval.

    Positional is the default algorithm, as it will work in every scenario. The Velocity algorithm can provide superior results to the Positional algorithm but requires lower noise sensor readings, or a larger smoothing time setting.

    The most noticeable difference between the two algorithms is that for the same configuration parameters, velocity control will eliminate or drastically reduce overshoot, as seen in the graphs below, as it isn\u2019t susceptible to integral wind-up.

    In some scenarios Velocity control will also be better at holding the heater at its target temperature, and rejecting disturbances. The primary reason for this is that velocity control is more like a standard second order differential equation. It takes into account position, velocity, and acceleration.

    "},{"location":"Packaging.html","title":"Packaging Kalico","text":"

    Kalico is somewhat of a packaging anomaly among python programs, as it doesn't use setuptools to build and install. Some notes regarding how best to package it are as follows:

    "},{"location":"Packaging.html#c-modules","title":"C modules","text":"

    Kalico uses a C module to handle some kinematics calculations more quickly. This module needs to be compiled at packaging time to avoid introducing a runtime dependency on a compiler. To compile the C module, run python3 klippy/chelper/__init__.py.

    "},{"location":"Packaging.html#compiling-python-code","title":"Compiling python code","text":"

    Many distributions have a policy of compiling all python code before packaging to improve startup time. You can do this by running python3 -m compileall klippy.

    "},{"location":"Packaging.html#versioning","title":"Versioning","text":"

    If you are building a package of Kalico from git, it is usual practice not to ship a .git directory, so the versioning must be handled without git. To do this, use the script shipped in scripts/make_version.py which should be run as follows: python3 scripts/make_version.py YOURDISTRONAME > klippy/.version.

    "},{"location":"Packaging.html#sample-packaging-script","title":"Sample packaging script","text":"

    klipper-git is packaged for Arch Linux, and has a PKGBUILD (package build script) available at Arch User Repository.

    "},{"location":"Pressure_Advance.html","title":"Pressure advance","text":"

    This document provides information on tuning the \"pressure advance\" configuration variable for a particular nozzle and filament. The pressure advance feature can be helpful in reducing ooze. For more information on how pressure advance is implemented see the kinematics document.

    "},{"location":"Pressure_Advance.html#tuning-pressure-advance","title":"Tuning pressure advance","text":"

    Pressure advance does two useful things - it reduces ooze during non-extrude moves and it reduces blobbing during cornering. This guide uses the second feature (reducing blobbing during cornering) as a mechanism for tuning.

    In order to calibrate pressure advance the printer must be configured and operational as the tuning test involves printing and inspecting a test object. It is a good idea to read this document in full prior to running the test.

    Use a slicer to generate g-code for the large hollow square found in docs/prints/square_tower.stl. Use a high speed (eg, 100mm/s), zero infill, and a coarse layer height (the layer height should be around 75% of the nozzle diameter). Make sure any \"dynamic acceleration control\" is disabled in the slicer.

    Prepare for the test by issuing the following G-Code command:

    SET_VELOCITY_LIMIT SQUARE_CORNER_VELOCITY=1 ACCEL=500\n

    This command makes the nozzle travel slower through corners to emphasize the effects of extruder pressure. Then for printers with a direct drive extruder run the command:

    TUNING_TOWER COMMAND=SET_PRESSURE_ADVANCE PARAMETER=ADVANCE START=0 FACTOR=.005\n

    For long bowden extruders use:

    TUNING_TOWER COMMAND=SET_PRESSURE_ADVANCE PARAMETER=ADVANCE START=0 FACTOR=.020\n

    Then print the object. When fully printed the test print looks like:

    The above TUNING_TOWER command instructs Kalico to alter the pressure_advance setting on each layer of the print. Higher layers in the print will have a larger pressure advance value set. Layers below the ideal pressure_advance setting will have blobbing at the corners, and layers above the ideal setting can lead to rounded corners and poor extrusion leading up to the corner.

    One can cancel the print early if one observes that the corners are no longer printing well (and thus one can avoid printing layers that are known to be above the ideal pressure_advance value).

    Inspect the print and then use a digital calipers to find the height that has the best quality corners. When in doubt, prefer a lower height.

    The pressure_advance value can then be calculated as pressure_advance = <start> + <measured_height> * <factor>. (For example, 0 + 12.90 * .020 would be .258.)

    It is possible to choose custom settings for START and FACTOR if that helps identify the best pressure advance setting. When doing this, be sure to issue the TUNING_TOWER command at the start of each test print.

    Typical pressure advance values are between 0.050 and 1.000 (the high end usually only with bowden extruders). If there is no significant improvement with a pressure advance up to 1.000, then pressure advance is unlikely to improve the quality of prints. Return to a default configuration with pressure advance disabled.

    Although this tuning exercise directly improves the quality of corners, it's worth remembering that a good pressure advance configuration also reduces ooze throughout the print.

    At the completion of this test, set pressure_advance = <calculated_value> in the [extruder] section of the configuration file and issue a RESTART command. The RESTART command will clear the test state and return the acceleration and cornering speeds to their normal values.

    "},{"location":"Pressure_Advance.html#important-notes","title":"Important Notes","text":" "},{"location":"Probe_Calibrate.html","title":"Probe calibration","text":"

    This document describes the method for calibrating the X, Y, and Z offsets of an \"automatic z probe\" in Kalico. This is useful for users that have a [probe] or [bltouch] section in their config file.

    "},{"location":"Probe_Calibrate.html#calibrating-probe-x-and-y-offsets","title":"Calibrating probe X and Y offsets","text":"

    To calibrate the X and Y offset, navigate to the OctoPrint \"Control\" tab, home the printer, and then use the OctoPrint jogging buttons to move the head to a position near the center of the bed.

    Place a piece of blue painters tape (or similar) on the bed underneath the probe. Navigate to the OctoPrint \"Terminal\" tab and issue a PROBE command:

    PROBE\n

    Place a mark on the tape directly under where the probe is (or use a similar method to note the location on the bed).

    Issue a GET_POSITION command and record the toolhead XY location reported by that command. For example if one sees:

    Recv: // toolhead: X:46.500000 Y:27.000000 Z:15.000000 E:0.000000\n

    then one would record a probe X position of 46.5 and probe Y position of 27.

    After recording the probe position, issue a series of G1 commands until the nozzle is directly above the mark on the bed. For example, one might issue:

    G1 F300 X57 Y30 Z15\n

    to move the nozzle to an X position of 57 and Y of 30. Once one finds the position directly above the mark, use the GET_POSITION command to report that position. This is the nozzle position.

    The x_offset is then the nozzle_x_position - probe_x_position and y_offset is similarly the nozzle_y_position - probe_y_position. Update the printer.cfg file with the given values, remove the tape/marks from the bed, and then issue a RESTART command so that the new values take effect.

    "},{"location":"Probe_Calibrate.html#calibrating-probe-z-offset","title":"Calibrating probe Z offset","text":"

    Providing an accurate probe z_offset is critical to obtaining high quality prints. The z_offset is the distance between the nozzle and bed when the probe triggers. The Kalico PROBE_CALIBRATE tool can be used to obtain this value - it will run an automatic probe to measure the probe's Z trigger position and then start a manual probe to obtain the nozzle Z height. The probe z_offset will then be calculated from these measurements.

    Start by homing the printer and then move the head to a position near the center of the bed. Navigate to the OctoPrint terminal tab and run the PROBE_CALIBRATE command to start the tool.

    This tool will perform an automatic probe, then lift the head, move the nozzle over the location of the probe point, and start the manual probe tool. If the nozzle does not move to a position above the automatic probe point, then ABORT the manual probe tool and perform the XY probe offset calibration described above.

    Once the manual probe tool starts, follow the steps described at \"the paper test\" to determine the actual distance between the nozzle and bed at the given location. Once those steps are complete one can ACCEPT the position and save the results to the config file with:

    SAVE_CONFIG\n

    Note that if a change is made to the printer's motion system, hotend position, or probe location then it will invalidate the results of PROBE_CALIBRATE.

    If the probe has an X or Y offset and the bed tilt is changed (eg, by adjusting bed screws, running DELTA_CALIBRATE, running Z_TILT_ADJUST, running QUAD_GANTRY_LEVEL, or similar) then it will invalidate the results of PROBE_CALIBRATE. After making any of the above adjustments it will be necessary to run PROBE_CALIBRATE again.

    If the results of PROBE_CALIBRATE are invalidated, then any previous bed mesh results that were obtained using the probe are also invalidated - it will be necessary to rerun BED_MESH_CALIBRATE after recalibrating the probe.

    "},{"location":"Probe_Calibrate.html#repeatability-check","title":"Repeatability check","text":"

    After calibrating the probe X, Y, and Z offsets it is a good idea to verify that the probe provides repeatable results. Start by homing the printer and then move the head to a position near the center of the bed. Navigate to the OctoPrint terminal tab and run the PROBE_ACCURACY command.

    This command will run the probe ten times and produce output similar to the following:

    Recv: // probe accuracy: at X:0.000 Y:0.000 Z:10.000\nRecv: // and read 10 times with speed of 5 mm/s\nRecv: // probe at -0.003,0.005 is z=2.506948\nRecv: // probe at -0.003,0.005 is z=2.519448\nRecv: // probe at -0.003,0.005 is z=2.519448\nRecv: // probe at -0.003,0.005 is z=2.506948\nRecv: // probe at -0.003,0.005 is z=2.519448\nRecv: // probe at -0.003,0.005 is z=2.519448\nRecv: // probe at -0.003,0.005 is z=2.506948\nRecv: // probe at -0.003,0.005 is z=2.506948\nRecv: // probe at -0.003,0.005 is z=2.519448\nRecv: // probe at -0.003,0.005 is z=2.506948\nRecv: // probe accuracy results: maximum 2.519448, minimum 2.506948, range 0.012500, average 2.513198, median 2.513198, standard deviation 0.006250\n

    Ideally the tool will report an identical maximum and minimum value. (That is, ideally the probe obtains an identical result on all ten probes.) However, it's normal for the minimum and maximum values to differ by one Z \"step distance\" or up to 5 microns (.005mm). A \"step distance\" is rotation_distance/(full_steps_per_rotation*microsteps). The distance between the minimum and the maximum value is called the range. So, in the above example, since the printer uses a Z step distance of .0125, a range of 0.012500 would be considered normal.

    If the results of the test show a range value that is greater than 25 microns (.025mm) then the probe does not have sufficient accuracy for typical bed leveling procedures. It may be possible to tune the probe speed and/or probe start height to improve the repeatability of the probe. The PROBE_ACCURACY command allows one to run tests with different parameters to see their impact - see the G-Codes document for further details. If the probe generally obtains repeatable results but has an occasional outlier, then it may be possible to account for that by using multiple samples on each probe - read the description of the probe samples config parameters in the config reference for more details.

    If new probe speed, samples count, or other settings are needed, then update the printer.cfg file and issue a RESTART command. If so, it is a good idea to calibrate the z_offset again. If repeatable results can not be obtained then don't use the probe for bed leveling. Kalico has several manual probing tools that can be used instead - see the Bed Level document for further details.

    "},{"location":"Probe_Calibrate.html#location-bias-check","title":"Location Bias Check","text":"

    Some probes can have a systemic bias that corrupts the results of the probe at certain toolhead locations. For example, if the probe mount tilts slightly when moving along the Y axis then it could result in the probe reporting biased results at different Y positions.

    This is a common issue with probes on delta printers, however it can occur on all printers.

    One can check for a location bias by using the PROBE_CALIBRATE command to measuring the probe z_offset at various X and Y locations. Ideally, the probe z_offset would be a constant value at every printer location.

    For delta printers, try measuring the z_offset at a position near the A tower, at a position near the B tower, and at a position near the C tower. For cartesian, corexy, and similar printers, try measuring the z_offset at positions near the four corners of the bed.

    Before starting this test, first calibrate the probe X, Y, and Z offsets as described at the beginning of this document. Then home the printer and navigate to the first XY position. Follow the steps at calibrating probe Z offset to run the PROBE_CALIBRATE command, TESTZ commands, and ACCEPT command, but do not run SAVE_CONFIG. Note the reported z_offset found. Then navigate to the other XY positions, repeat these PROBE_CALIBRATE steps, and note the reported z_offset.

    If the difference between the minimum reported z_offset and the maximum reported z_offset is greater than 25 microns (.025mm) then the probe is not suitable for typical bed leveling procedures. See the Bed Level document for manual probe alternatives.

    "},{"location":"Probe_Calibrate.html#temperature-bias","title":"Temperature Bias","text":"

    Many probes have a systemic bias when probing at different temperatures. For example, the probe may consistently trigger at a lower height when the probe is at a higher temperature.

    It is recommended to run the bed leveling tools at a consistent temperature to account for this bias. For example, either always run the tools when the printer is at room temperature, or always run the tools after the printer has obtained a consistent print temperature. In either case, it is a good idea to wait several minutes after the desired temperature is reached, so that the printer apparatus is consistently at the desired temperature.

    To check for a temperature bias, start with the printer at room temperature and then home the printer, move the head to a position near the center of the bed, and run the PROBE_ACCURACY command. Note the results. Then, without homing or disabling the stepper motors, heat the printer nozzle and bed to printing temperature, and run the PROBE_ACCURACY command again. Ideally, the command will report identical results. As above, if the probe does have a temperature bias then be careful to always use the probe at a consistent temperature.

    "},{"location":"Protocol.html","title":"Protocol","text":"

    The Kalico messaging protocol is used for low-level communication between the Kalico host software and the Kalico micro-controller software. At a high level the protocol can be thought of as a series of command and response strings that are compressed, transmitted, and then processed at the receiving side. An example series of commands in uncompressed human-readable format might look like:

    set_digital_out pin=PA3 value=1\nset_digital_out pin=PA7 value=1\nschedule_digital_out oid=8 clock=4000000 value=0\nqueue_step oid=7 interval=7458 count=10 add=331\nqueue_step oid=7 interval=11717 count=4 add=1281\n

    See the mcu commands document for information on available commands. See the debugging document for information on how to translate a G-Code file into its corresponding human-readable micro-controller commands.

    This page provides a high-level description of the Kalico messaging protocol itself. It describes how messages are declared, encoded in binary format (the \"compression\" scheme), and transmitted.

    The goal of the protocol is to enable an error-free communication channel between the host and micro-controller that is low-latency, low-bandwidth, and low-complexity for the micro-controller.

    "},{"location":"Protocol.html#micro-controller-interface","title":"Micro-controller Interface","text":"

    The Kalico transmission protocol can be thought of as a RPC mechanism between micro-controller and host. The micro-controller software declares the commands that the host may invoke along with the response messages that it can generate. The host uses that information to command the micro-controller to perform actions and to interpret the results.

    "},{"location":"Protocol.html#declaring-commands","title":"Declaring commands","text":"

    The micro-controller software declares a \"command\" by using the DECL_COMMAND() macro in the C code. For example:

    DECL_COMMAND(command_update_digital_out, \"update_digital_out oid=%c value=%c\");\n

    The above declares a command named \"update_digital_out\". This allows the host to \"invoke\" this command which would cause the command_update_digital_out() C function to be executed in the micro-controller. The above also indicates that the command takes two integer parameters. When the command_update_digital_out() C code is executed, it will be passed an array containing these two integers - the first corresponding to the 'oid' and the second corresponding to the 'value'.

    In general, the parameters are described with printf() style syntax (eg, \"%u\"). The formatting directly corresponds to the human-readable view of commands (eg, \"update_digital_out oid=7 value=1\"). In the above example, \"value=\" is a parameter name and \"%c\" indicates the parameter is an integer. Internally, the parameter name is only used as documentation. In this example, the \"%c\" is also used as documentation to indicate the expected integer is 1 byte in size (the declared integer size does not impact the parsing or encoding).

    The micro-controller build will collect all commands declared with DECL_COMMAND(), determine their parameters, and arrange for them to be callable.

    "},{"location":"Protocol.html#declaring-responses","title":"Declaring responses","text":"

    To send information from the micro-controller to the host a \"response\" is generated. These are both declared and transmitted using the sendf() C macro. For example:

    sendf(\"status clock=%u status=%c\", sched_read_time(), sched_is_shutdown());\n

    The above transmits a \"status\" response message that contains two integer parameters (\"clock\" and \"status\"). The micro-controller build automatically finds all sendf() calls and generates encoders for them. The first parameter of the sendf() function describes the response and it is in the same format as command declarations.

    The host can arrange to register a callback function for each response. So, in effect, commands allow the host to invoke C functions in the micro-controller and responses allow the micro-controller software to invoke code in the host.

    The sendf() macro should only be invoked from command or task handlers, and it should not be invoked from interrupts or timers. The code does not need to issue a sendf() in response to a received command, it is not limited in the number of times sendf() may be invoked, and it may invoke sendf() at any time from a task handler.

    "},{"location":"Protocol.html#output-responses","title":"Output responses","text":"

    To simplify debugging, there is also an output() C function. For example:

    output(\"The value of %u is %s with size %u.\", x, buf, buf_len);\n

    The output() function is similar in usage to printf() - it is intended to generate and format arbitrary messages for human consumption.

    "},{"location":"Protocol.html#declaring-enumerations","title":"Declaring enumerations","text":"

    Enumerations allow the host code to use string identifiers for parameters that the micro-controller handles as integers. They are declared in the micro-controller code - for example:

    DECL_ENUMERATION(\"spi_bus\", \"spi\", 0);\n\nDECL_ENUMERATION_RANGE(\"pin\", \"PC0\", 16, 8);\n

    If the first example, the DECL_ENUMERATION() macro defines an enumeration for any command/response message with a parameter name of \"spi_bus\" or parameter name with a suffix of \"_spi_bus\". For those parameters the string \"spi\" is a valid value and it will be transmitted with an integer value of zero.

    It's also possible to declare an enumeration range. In the second example, a \"pin\" parameter (or any parameter with a suffix of \"_pin\") would accept PC0, PC1, PC2, ..., PC7 as valid values. The strings will be transmitted with integers 16, 17, 18, ..., 23.

    "},{"location":"Protocol.html#declaring-constants","title":"Declaring constants","text":"

    Constants can also be exported. For example, the following:

    DECL_CONSTANT(\"SERIAL_BAUD\", 250000);\n

    would export a constant named \"SERIAL_BAUD\" with a value of 250000 from the micro-controller to the host. It is also possible to declare a constant that is a string - for example:

    DECL_CONSTANT_STR(\"MCU\", \"pru\");\n
    "},{"location":"Protocol.html#low-level-message-encoding","title":"Low-level message encoding","text":"

    To accomplish the above RPC mechanism, each command and response is encoded into a binary format for transmission. This section describes the transmission system.

    "},{"location":"Protocol.html#message-blocks","title":"Message Blocks","text":"

    All data sent from host to micro-controller and vice-versa are contained in \"message blocks\". A message block has a two byte header and a three byte trailer. The format of a message block is:

    <1 byte length><1 byte sequence><n-byte content><2 byte crc><1 byte sync>\n

    The length byte contains the number of bytes in the message block including the header and trailer bytes (thus the minimum message length is 5 bytes). The maximum message block length is currently 64 bytes. The sequence byte contains a 4 bit sequence number in the low-order bits and the high-order bits always contain 0x10 (the high-order bits are reserved for future use). The content bytes contain arbitrary data and its format is described in the following section. The crc bytes contain a 16bit CCITT CRC of the message block including the header bytes but excluding the trailer bytes. The sync byte is 0x7e.

    The format of the message block is inspired by HDLC message frames. Like in HDLC, the message block may optionally contain an additional sync character at the start of the block. Unlike in HDLC, a sync character is not exclusive to the framing and may be present in the message block content.

    "},{"location":"Protocol.html#message-block-contents","title":"Message Block Contents","text":"

    Each message block sent from host to micro-controller contains a series of zero or more message commands in its contents. Each command starts with a Variable Length Quantity (VLQ) encoded integer command-id followed by zero or more VLQ parameters for the given command.

    As an example, the following four commands might be placed in a single message block:

    update_digital_out oid=6 value=1\nupdate_digital_out oid=5 value=0\nget_config\nget_clock\n

    and encoded into the following eight VLQ integers:

    <id_update_digital_out><6><1><id_update_digital_out><5><0><id_get_config><id_get_clock>\n

    In order to encode and parse the message contents, both the host and micro-controller must agree on the command ids and the number of parameters each command has. So, in the above example, both the host and micro-controller would know that \"id_update_digital_out\" is always followed by two parameters, and \"id_get_config\" and \"id_get_clock\" have zero parameters. The host and micro-controller share a \"data dictionary\" that maps the command descriptions (eg, \"update_digital_out oid=%c value=%c\") to their integer command-ids. When processing the data, the parser will know to expect a specific number of VLQ encoded parameters following a given command id.

    The message contents for blocks sent from micro-controller to host follow the same format. The identifiers in these messages are \"response ids\", but they serve the same purpose and follow the same encoding rules. In practice, message blocks sent from the micro-controller to the host never contain more than one response in the message block contents.

    "},{"location":"Protocol.html#variable-length-quantities","title":"Variable Length Quantities","text":"

    See the wikipedia article for more information on the general format of VLQ encoded integers. Kalico uses an encoding scheme that supports both positive and negative integers. Integers close to zero use less bytes to encode and positive integers typically encode using less bytes than negative integers. The following table shows the number of bytes each integer takes to encode:

    Integer Encoded size -32 .. 95 1 -4096 .. 12287 2 -524288 .. 1572863 3 -67108864 .. 201326591 4 -2147483648 .. 4294967295 5"},{"location":"Protocol.html#variable-length-strings","title":"Variable length strings","text":"

    As an exception to the above encoding rules, if a parameter to a command or response is a dynamic string then the parameter is not encoded as a simple VLQ integer. Instead it is encoded by transmitting the length as a VLQ encoded integer followed by the contents itself:

    <VLQ encoded length><n-byte contents>\n

    The command descriptions found in the data dictionary allow both the host and micro-controller to know which command parameters use simple VLQ encoding and which parameters use string encoding.

    "},{"location":"Protocol.html#data-dictionary","title":"Data Dictionary","text":"

    In order for meaningful communications to be established between micro-controller and host, both sides must agree on a \"data dictionary\". This data dictionary contains the integer identifiers for commands and responses along with their descriptions.

    The micro-controller build uses the contents of DECL_COMMAND() and sendf() macros to generate the data dictionary. The build automatically assigns unique identifiers to each command and response. This system allows both the host and micro-controller code to seamlessly use descriptive human-readable names while still using minimal bandwidth.

    The host queries the data dictionary when it first connects to the micro-controller. Once the host downloads the data dictionary from the micro-controller, it uses that data dictionary to encode all commands and to parse all responses from the micro-controller. The host must therefore handle a dynamic data dictionary. However, to keep the micro-controller software simple, the micro-controller always uses its static (compiled in) data dictionary.

    The data dictionary is queried by sending \"identify\" commands to the micro-controller. The micro-controller will respond to each identify command with an \"identify_response\" message. Since these two commands are needed prior to obtaining the data dictionary, their integer ids and parameter types are hard-coded in both the micro-controller and the host. The \"identify_response\" response id is 0, the \"identify\" command id is 1. Other than having hard-coded ids the identify command and its response are declared and transmitted the same way as other commands and responses. No other command or response is hard-coded.

    The format of the transmitted data dictionary itself is a zlib compressed JSON string. The micro-controller build process generates the string, compresses it, and stores it in the text section of the micro-controller flash. The data dictionary can be much larger than the maximum message block size - the host downloads it by sending multiple identify commands requesting progressive chunks of the data dictionary. Once all chunks are obtained the host will assemble the chunks, uncompress the data, and parse the contents.

    In addition to information on the communication protocol, the data dictionary also contains the software version, enumerations (as defined by DECL_ENUMERATION), and constants (as defined by DECL_CONSTANT).

    "},{"location":"Protocol.html#message-flow","title":"Message flow","text":"

    Message commands sent from host to micro-controller are intended to be error-free. The micro-controller will check the CRC and sequence numbers in each message block to ensure the commands are accurate and in-order. The micro-controller always processes message blocks in-order - should it receive a block out-of-order it will discard it and any other out-of-order blocks until it receives blocks with the correct sequencing.

    The low-level host code implements an automatic retransmission system for lost and corrupt message blocks sent to the micro-controller. To facilitate this, the micro-controller transmits an \"ack message block\" after each successfully received message block. The host schedules a timeout after sending each block and it will retransmit should the timeout expire without receiving a corresponding \"ack\". In addition, if the micro-controller detects a corrupt or out-of-order block it may transmit a \"nak message block\" to facilitate fast retransmission.

    An \"ack\" is a message block with empty content (ie, a 5 byte message block) and a sequence number greater than the last received host sequence number. A \"nak\" is a message block with empty content and a sequence number less than the last received host sequence number.

    The protocol facilitates a \"window\" transmission system so that the host can have many outstanding message blocks in-flight at a time. (This is in addition to the many commands that may be present in a given message block.) This allows maximum bandwidth utilization even in the event of transmission latency. The timeout, retransmit, windowing, and ack mechanism are inspired by similar mechanisms in TCP.

    In the other direction, message blocks sent from micro-controller to host are designed to be error-free, but they do not have assured transmission. (Responses should not be corrupt, but they may go missing.) This is done to keep the implementation in the micro-controller simple. There is no automatic retransmission system for responses - the high-level code is expected to be capable of handling an occasional missing response (usually by re-requesting the content or setting up a recurring schedule of response transmission). The sequence number field in message blocks sent to the host is always one greater than the last received sequence number of message blocks received from the host. It is not used to track sequences of response message blocks.

    "},{"location":"RPi_microcontroller.html","title":"RPi microcontroller","text":"

    This document describes the process of running Kalico on a RPi and use the same RPi as secondary mcu.

    "},{"location":"RPi_microcontroller.html#why-use-rpi-as-a-secondary-mcu","title":"Why use RPi as a secondary MCU?","text":"

    Often the MCUs dedicated to controlling 3D printers have a limited and pre-configured number of exposed pins to manage the main printing functions (thermal resistors, extruders, steppers ...). Using the RPi where Kalico is installed as a secondary MCU gives the possibility to directly use the GPIOs and the buses (i2c, spi) of the RPi inside Kalico without using Octoprint plugins (if used) or external programs giving the ability to control everything within the print GCODE.

    Warning: If your platform is a Beaglebone and you have correctly followed the installation steps, the linux mcu is already installed and configured for your system.

    "},{"location":"RPi_microcontroller.html#install-the-rc-script","title":"Install the rc script","text":"

    If you want to use the host as a secondary MCU the klipper_mcu process must run before the klippy process.

    After installing Kalico, install the script. run:

    cd ~/klipper/\nsudo cp ./scripts/klipper-mcu.service /etc/systemd/system/\nsudo systemctl enable klipper-mcu.service\n
    "},{"location":"RPi_microcontroller.html#building-the-micro-controller-code","title":"Building the micro-controller code","text":"

    To compile the Kalico micro-controller code, start by configuring it for the \"Linux process\":

    cd ~/klipper/\nmake menuconfig\n

    In the menu, set \"Microcontroller Architecture\" to \"Linux process,\" then save and exit.

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

    sudo service klipper stop\nmake flash\nsudo service klipper start\n

    If klippy.log reports a \"Permission denied\" error when attempting to connect to /tmp/klipper_host_mcu then you need to add your user to the tty group. The following command will add the \"pi\" user to the tty group:

    sudo usermod -a -G tty pi\n
    "},{"location":"RPi_microcontroller.html#remaining-configuration","title":"Remaining configuration","text":"

    Complete the installation by configuring Kalico secondary MCU following the instructions in RaspberryPi sample config and Multi MCU sample config.

    "},{"location":"RPi_microcontroller.html#optional-enabling-spi","title":"Optional: Enabling SPI","text":"

    Make sure the Linux SPI driver is enabled by running sudo raspi-config and enabling SPI under the \"Interfacing options\" menu.

    "},{"location":"RPi_microcontroller.html#optional-enabling-i2c","title":"Optional: Enabling I2C","text":"

    Make sure the Linux I2C driver is enabled by running sudo raspi-config and enabling I2C under the \"Interfacing options\" menu. If planning to use I2C for the MPU accelerometer, it is also required to set the baud rate to 400000 by: adding/uncommenting dtparam=i2c_arm=on,i2c_arm_baudrate=400000 in /boot/config.txt (or /boot/firmware/config.txt in some distros).

    "},{"location":"RPi_microcontroller.html#optional-identify-the-correct-gpiochip","title":"Optional: Identify the correct gpiochip","text":"

    On Raspberry Pi and on many clones the pins exposed on the GPIO belong to the first gpiochip. They can therefore be used on Kalico simply by referring them with the name gpio0..n. However, there are cases in which the exposed pins belong to gpiochips other than the first. For example in the case of some OrangePi models or if a Port Expander is used. In these cases it is useful to use the commands to access the Linux GPIO character device to verify the configuration.

    To install the Linux GPIO character device - binary on a debian based distro like octopi run:

    sudo apt-get install gpiod\n

    To check available gpiochip run:

    gpiodetect\n

    To check the pin number and the pin availability tun:

    gpioinfo\n

    The chosen pin can thus be used within the configuration as gpiochip<n>/gpio<o> where n is the chip number as seen by the gpiodetect command and o is the line number seen by thegpioinfo command.

    Warning: only gpio marked as unused can be used. It is not possible for a line to be used by multiple processes simultaneously.

    For example on a RPi 3B+ where Kalico use the GPIO20 for a switch:

    $ gpiodetect\ngpiochip0 [pinctrl-bcm2835] (54 lines)\ngpiochip1 [raspberrypi-exp-gpio] (8 lines)\n\n$ gpioinfo\ngpiochip0 - 54 lines:\n        line   0:      unnamed       unused   input  active-high\n        line   1:      unnamed       unused   input  active-high\n        line   2:      unnamed       unused   input  active-high\n        line   3:      unnamed       unused   input  active-high\n        line   4:      unnamed       unused   input  active-high\n        line   5:      unnamed       unused   input  active-high\n        line   6:      unnamed       unused   input  active-high\n        line   7:      unnamed       unused   input  active-high\n        line   8:      unnamed       unused   input  active-high\n        line   9:      unnamed       unused   input  active-high\n        line  10:      unnamed       unused   input  active-high\n        line  11:      unnamed       unused   input  active-high\n        line  12:      unnamed       unused   input  active-high\n        line  13:      unnamed       unused   input  active-high\n        line  14:      unnamed       unused   input  active-high\n        line  15:      unnamed       unused   input  active-high\n        line  16:      unnamed       unused   input  active-high\n        line  17:      unnamed       unused   input  active-high\n        line  18:      unnamed       unused   input  active-high\n        line  19:      unnamed       unused   input  active-high\n        line  20:      unnamed    \"klipper\"  output  active-high [used]\n        line  21:      unnamed       unused   input  active-high\n        line  22:      unnamed       unused   input  active-high\n        line  23:      unnamed       unused   input  active-high\n        line  24:      unnamed       unused   input  active-high\n        line  25:      unnamed       unused   input  active-high\n        line  26:      unnamed       unused   input  active-high\n        line  27:      unnamed       unused   input  active-high\n        line  28:      unnamed       unused   input  active-high\n        line  29:      unnamed       \"led0\"  output  active-high [used]\n        line  30:      unnamed       unused   input  active-high\n        line  31:      unnamed       unused   input  active-high\n        line  32:      unnamed       unused   input  active-high\n        line  33:      unnamed       unused   input  active-high\n        line  34:      unnamed       unused   input  active-high\n        line  35:      unnamed       unused   input  active-high\n        line  36:      unnamed       unused   input  active-high\n        line  37:      unnamed       unused   input  active-high\n        line  38:      unnamed       unused   input  active-high\n        line  39:      unnamed       unused   input  active-high\n        line  40:      unnamed       unused   input  active-high\n        line  41:      unnamed       unused   input  active-high\n        line  42:      unnamed       unused   input  active-high\n        line  43:      unnamed       unused   input  active-high\n        line  44:      unnamed       unused   input  active-high\n        line  45:      unnamed       unused   input  active-high\n        line  46:      unnamed       unused   input  active-high\n        line  47:      unnamed       unused   input  active-high\n        line  48:      unnamed       unused   input  active-high\n        line  49:      unnamed       unused   input  active-high\n        line  50:      unnamed       unused   input  active-high\n        line  51:      unnamed       unused   input  active-high\n        line  52:      unnamed       unused   input  active-high\n        line  53:      unnamed       unused   input  active-high\ngpiochip1 - 8 lines:\n        line   0:      unnamed       unused   input  active-high\n        line   1:      unnamed       unused   input  active-high\n        line   2:      unnamed       \"led1\"  output   active-low [used]\n        line   3:      unnamed       unused   input  active-high\n        line   4:      unnamed       unused   input  active-high\n        line   5:      unnamed       unused   input  active-high\n        line   6:      unnamed       unused   input  active-high\n        line   7:      unnamed       unused   input  active-high\n
    "},{"location":"RPi_microcontroller.html#optional-hardware-pwm","title":"Optional: Hardware PWM","text":"

    Raspberry Pi's have two PWM channels (PWM0 and PWM1) which are exposed on the header or if not, can be routed to existing gpio pins. The Linux mcu daemon uses the pwmchip sysfs interface to control hardware pwm devices on Linux hosts. The pwm sysfs interface is not exposed by default on a Raspberry and can be activated by adding a line to /boot/config.txt:

    # Enable pwmchip sysfs interface\ndtoverlay=pwm,pin=12,func=4\n

    This example enables only PWM0 and routes it to gpio12. If both PWM channels need to be enabled you can use pwm-2chan:

    # Enable pwmchip sysfs interface\ndtoverlay=pwm-2chan,pin=12,func=4,pin2=13,func2=4\n

    This example additionally enables PWM1 and routes it to gpio13.

    The overlay does not expose the pwm line on sysfs on boot and needs to be exported by echo'ing the number of the pwm channel to /sys/class/pwm/pwmchip0/export. This will create device /sys/class/pwm/pwmchip0/pwm0 in the filesystem. The easiest way to do this is by adding this to /etc/rc.local before the exit 0 line:

    # Enable pwmchip sysfs interface\necho 0 > /sys/class/pwm/pwmchip0/export\n

    When using both PWM channels, the number of the second channel needs to be echo'd as well:

    # Enable pwmchip sysfs interface\necho 0 > /sys/class/pwm/pwmchip0/export\necho 1 > /sys/class/pwm/pwmchip0/export\n

    With the sysfs in place, you can now use either the pwm channel(s) by adding the following piece of configuration to your printer.cfg:

    [output_pin caselight]\npin: host:pwmchip0/pwm0\npwm: True\nhardware_pwm: True\ncycle_time: 0.000001\n\n[output_pin beeper]\npin: host:pwmchip0/pwm1\npwm: True\nhardware_pwm: True\nvalue: 0\nshutdown_value: 0\ncycle_time: 0.0005\n

    This will add hardware pwm control to gpio12 and gpio13 on the Pi (because the overlay was configured to route pwm0 to pin=12 and pwm1 to pin=13).

    PWM0 can be routed to gpio12 and gpio18, PWM1 can be routed to gpio13 and gpio19:

    PWM gpio PIN Func 0 12 4 0 18 2 1 13 4 1 19 2"},{"location":"Resonance_Compensation.html","title":"Resonance Compensation","text":"

    Kalico supports Input Shaping - a technique that can be used to reduce ringing (also known as echoing, ghosting or rippling) in prints. Ringing is a surface printing defect when, typically, elements like edges repeat themselves on a printed surface as a subtle 'echo':

    |||

    Ringing is caused by mechanical vibrations in the printer due to quick changes of the printing direction. Note that ringing usually has mechanical origins: insufficiently rigid printer frame, non-tight or too springy belts, alignment issues of mechanical parts, heavy moving mass, etc. Those should be checked and fixed first, if possible.

    Input shaping is an open-loop control technique which creates a commanding signal that cancels its own vibrations. Input shaping requires some tuning and measurements before it can be enabled. Besides ringing, Input Shaping typically reduces the vibrations and shaking of the printer in general, and may also improve the reliability of the stealthChop mode of Trinamic stepper drivers.

    "},{"location":"Resonance_Compensation.html#tuning","title":"Tuning","text":"

    Basic tuning requires measuring the ringing frequencies of the printer by printing a test model.

    Slice the ringing test model, which can be found in docs/prints/ringing_tower.stl, in the slicer:

    "},{"location":"Resonance_Compensation.html#ringing-frequency","title":"Ringing frequency","text":"

    First, measure the ringing frequency.

    1. If square_corner_velocity parameter was changed, revert it back to 5.0. It is not advised to increase it when using input shaper because it can cause more smoothing in parts - it is better to use higher acceleration value instead.
    2. Disable the minimum_cruise_ratio feature by issuing the following command: SET_VELOCITY_LIMIT MINIMUM_CRUISE_RATIO=0
    3. Disable Pressure Advance: SET_PRESSURE_ADVANCE ADVANCE=0
    4. If you have already added [input_shaper] section to the printer.cfg, execute SET_INPUT_SHAPER SHAPER_FREQ_X=0 SHAPER_FREQ_Y=0 command. If you get \"Unknown command\" error, you can safely ignore it at this point and continue with the measurements.
    5. Execute the command: TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5 Basically, we try to make ringing more pronounced by setting different large values for acceleration. This command will increase the acceleration every 5 mm starting from 1500 mm/sec^2: 1500 mm/sec^2, 2000 mm/sec^2, 2500 mm/sec^2 and so forth up until 7000 mm/sec^2 at the last band.
    6. Print the test model sliced with the suggested parameters.
    7. You can stop the print earlier if the ringing is clearly visible and you see that acceleration gets too high for your printer (e.g. printer shakes too much or starts skipping steps).

    8. Use X and Y marks at the back of the model for reference. The measurements from the side with X mark should be used for X axis configuration, and Y mark - for Y axis configuration. Measure the distance D (in mm) between several oscillations on the part with X mark, near the notches, preferably skipping the first oscillation or two. To measure the distance between oscillations more easily, mark the oscillations first, then measure the distance between the marks with a ruler or calipers:

      |||

    9. Count how many oscillations N the measured distance D corresponds to. If you are unsure how to count the oscillations, refer to the picture above, which shows N = 6 oscillations.

    10. Compute the ringing frequency of X axis as V \u00b7 N / D (Hz), where V is the velocity for outer perimeters (mm/sec). For the example above, we marked 6 oscillations, and the test was printed at 100 mm/sec velocity, so the frequency is 100 * 6 / 12.14 \u2248 49.4 Hz.
    11. Do (8) - (10) for Y mark as well.

    Note that ringing on the test print should follow the pattern of the curved notches, as in the picture above. If it doesn't, then this defect is not really a ringing and has a different origin - either mechanical, or an extruder issue. It should be fixed first before enabling and tuning input shapers.

    If the measurements are not reliable because, say, the distance between the oscillations is not stable, it might mean that the printer has several resonance frequencies on the same axis. One may try to follow the tuning process described in Unreliable measurements of ringing frequencies section instead and still get something out of the input shaping technique.

    Ringing frequency can depend on the position of the model within the buildplate and Z height, especially on delta printers; you can check if you see the differences in frequencies at different positions along the sides of the test model and at different heights. You can calculate the average ringing frequencies over X and Y axes if that is the case.

    If the measured ringing frequency is very low (below approx 20-25 Hz), it might be a good idea to invest into stiffening the printer or decreasing the moving mass - depending on what is applicable in your case - before proceeding with further input shaping tuning, and re-measuring the frequencies afterwards. For many popular printer models there are often some solutions available already.

    Note that the ringing frequencies can change if the changes are made to the printer that affect the moving mass or change the stiffness of the system, for example:

    If such changes are made, it is a good idea to at least measure the ringing frequencies to see if they have changed.

    "},{"location":"Resonance_Compensation.html#input-shaper-configuration","title":"Input shaper configuration","text":"

    After the ringing frequencies for X and Y axes are measured, you can add the following section to your printer.cfg:

    [input_shaper]\nshaper_freq_x: ...  # frequency for the X mark of the test model\nshaper_freq_y: ...  # frequency for the Y mark of the test model\n

    For the example above, we get shaper_freq_x/y = 49.4.

    "},{"location":"Resonance_Compensation.html#choosing-input-shaper","title":"Choosing input shaper","text":"

    Kalico supports several input shapers. They differ in their sensitivity to errors determining the resonance frequency and how much smoothing they cause in the printed parts. Also, some of the shapers like 2HUMP_EI and 3HUMP_EI should usually not be used with shaper_freq = resonance frequency - they are configured from different considerations to reduce several resonances at once.

    For most of the printers, either MZV or EI shapers can be recommended. This section describes a testing process to choose between them, and figure out a few other related parameters.

    Print the ringing test model as follows:

    1. Restart the firmware: RESTART
    2. Prepare for test: SET_VELOCITY_LIMIT MINIMUM_CRUISE_RATIO=0
    3. Disable Pressure Advance: SET_PRESSURE_ADVANCE ADVANCE=0
    4. Execute: SET_INPUT_SHAPER SHAPER_TYPE=MZV
    5. Execute the command: TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5
    6. Print the test model sliced with the suggested parameters.

    If you see no ringing at this point, then MZV shaper can be recommended for use.

    If you do see some ringing, re-measure the frequencies using steps (8)-(10) described in Ringing frequency section. If the frequencies differ significantly from the values you obtained earlier, a more complex input shaper configuration is needed. You can refer to Technical details of Input shapers section. Otherwise, proceed to the next step.

    Now try EI input shaper. To try it, repeat steps (1)-(6) from above, but executing at step 4 the following command instead: SET_INPUT_SHAPER SHAPER_TYPE=EI.

    Compare two prints with MZV and EI input shaper. If EI shows noticeably better results than MZV, use EI shaper, otherwise prefer MZV. Note that EI shaper will cause more smoothing in printed parts (see the next section for further details). Add shaper_type: mzv (or ei) parameter to [input_shaper] section, e.g.:

    [input_shaper]\nshaper_freq_x: ...\nshaper_freq_y: ...\nshaper_type: mzv\n

    A few notes on shaper selection:

    "},{"location":"Resonance_Compensation.html#selecting-max_accel","title":"Selecting max_accel","text":"

    You should have a printed test for the shaper you chose from the previous step (if you don't, print the test model sliced with the suggested parameters with the pressure advance disabled SET_PRESSURE_ADVANCE ADVANCE=0 and with the tuning tower enabled as TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5). Note that at very high accelerations, depending on the resonance frequency and the input shaper you chose (e.g. EI shaper creates more smoothing than MZV), input shaping may cause too much smoothing and rounding of the parts. So, max_accel should be chosen such as to prevent that. Another parameter that can impact smoothing is square_corner_velocity, so it is not advisable to increase it above the default 5 mm/sec to prevent increased smoothing.

    In order to select a suitable max_accel value, inspect the model for the chosen input shaper. First, take a note at which acceleration ringing is still small - that you are comfortable with it.

    Next, check the smoothing. To help with that, the test model has a small gap in the wall (0.15 mm):

    As the acceleration increases, so does the smoothing, and the actual gap in the print widens:

    In this picture, the acceleration increases left to right, and the gap starts to grow starting from 3500 mm/sec^2 (5-th band from the left). So the good value for max_accel = 3000 (mm/sec^2) in this case to avoid the excessive smoothing.

    Note the acceleration when the gap is still very small in your test print. If you see bulges, but no gap in the wall at all, even at high accelerations, it may be due to disabled Pressure Advance, especially on Bowden extruders. If that is the case, you may need to repeat the print with the PA enabled. It may also be a result of a miscalibrated (too high) filament flow, so it is a good idea to check that too.

    Choose the minimum out of the two acceleration values (from ringing and smoothing), and put it as max_accel into printer.cfg.

    As a note, it may happen - especially at low ringing frequencies - that EI shaper will cause too much smoothing even at lower accelerations. In this case, MZV may be a better choice, because it may allow higher acceleration values.

    At very low ringing frequencies (~25 Hz and below) even MZV shaper may create too much smoothing. If that is the case, you can also try to repeat the steps in Choosing input shaper section with ZV shaper, by using SET_INPUT_SHAPER SHAPER_TYPE=ZV command instead. ZV shaper should show even less smoothing than MZV, but is more sensitive to errors in measuring the ringing frequencies.

    Another consideration is that if a resonance frequency is too low (below 20-25 Hz), it might be a good idea to increase the printer stiffness or reduce the moving mass. Otherwise, acceleration and printing speed may be limited due too much smoothing now instead of ringing.

    "},{"location":"Resonance_Compensation.html#fine-tuning-resonance-frequencies","title":"Fine-tuning resonance frequencies","text":"

    Note that the precision of the resonance frequencies measurements using the ringing test model is sufficient for most purposes, so further tuning is not advised. If you still want to try to double-check your results (e.g. if you still see some ringing after printing a test model with an input shaper of your choice with the same frequencies as you have measured earlier), you can follow the steps in this section. Note that if you see ringing at different frequencies after enabling [input_shaper], this section will not help with that.

    Assuming that you have sliced the ringing model with suggested parameters, complete the following steps for each of the axes X and Y:

    1. Prepare for test: SET_VELOCITY_LIMIT MINIMUM_CRUISE_RATIO=0
    2. Make sure Pressure Advance is disabled: SET_PRESSURE_ADVANCE ADVANCE=0
    3. Execute: SET_INPUT_SHAPER SHAPER_TYPE=ZV
    4. From the existing ringing test model with your chosen input shaper select the acceleration that shows ringing sufficiently well, and set it with: SET_VELOCITY_LIMIT ACCEL=...
    5. Calculate the necessary parameters for the TUNING_TOWER command to tune shaper_freq_x parameter as follows: start = shaper_freq_x * 83 / 132 and factor = shaper_freq_x / 66, where shaper_freq_x here is the current value in printer.cfg.
    6. Execute the command: TUNING_TOWER COMMAND=SET_INPUT_SHAPER PARAMETER=SHAPER_FREQ_X START=start FACTOR=factor BAND=5 using start and factor values calculated at step (5).
    7. Print the test model.
    8. Reset the original frequency value: SET_INPUT_SHAPER SHAPER_FREQ_X=....
    9. Find the band which shows ringing the least and count its number from the bottom starting at 1.
    10. Calculate the new shaper_freq_x value via old shaper_freq_x * (39 + 5 * #band-number) / 66.

    Repeat these steps for the Y axis in the same manner, replacing references to X axis with the axis Y (e.g. replace shaper_freq_x with shaper_freq_y in the formulae and in the TUNING_TOWER command).

    As an example, let's assume you have had measured the ringing frequency for one of the axis equal to 45 Hz. This gives start = 45 * 83 / 132 = 28.30 and factor = 45 / 66 = 0.6818 values for TUNING_TOWER command. Now let's assume that after printing the test model, the fourth band from the bottom gives the least ringing. This gives the updated shaper_freq_? value equal to 45 * (39 + 5 * 4) / 66 \u2248 40.23.

    After both new shaper_freq_x and shaper_freq_y parameters have been calculated, you can update [input_shaper] section in printer.cfg with the new shaper_freq_x and shaper_freq_y values.

    "},{"location":"Resonance_Compensation.html#pressure-advance","title":"Pressure Advance","text":"

    If you use Pressure Advance, it may need to be re-tuned. Follow the instructions to find the new value, if it differs from the previous one. Make sure to restart Kalico before tuning Pressure Advance.

    "},{"location":"Resonance_Compensation.html#unreliable-measurements-of-ringing-frequencies","title":"Unreliable measurements of ringing frequencies","text":"

    If you are unable to measure the ringing frequencies, e.g. if the distance between the oscillations is not stable, you may still be able to take advantage of input shaping techniques, but the results may not be as good as with proper measurements of the frequencies, and will require a bit more tuning and printing the test model. Note that another possibility is to purchase and install an accelerometer and measure the resonances with it (refer to the docs describing the required hardware and the setup process) - but this option requires some crimping and soldering.

    For tuning, add empty [input_shaper] section to your printer.cfg. Then, assuming that you have sliced the ringing model with suggested parameters, print the test model 3 times as follows. First time, prior to printing, run

    1. RESTART
    2. SET_VELOCITY_LIMIT MINIMUM_CRUISE_RATIO=0
    3. SET_PRESSURE_ADVANCE ADVANCE=0
    4. SET_INPUT_SHAPER SHAPER_TYPE=2HUMP_EI SHAPER_FREQ_X=60 SHAPER_FREQ_Y=60
    5. TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5

    and print the model. Then print the model again, but before printing run instead

    1. SET_INPUT_SHAPER SHAPER_TYPE=2HUMP_EI SHAPER_FREQ_X=50 SHAPER_FREQ_Y=50
    2. TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5

    Then print the model for the 3rd time, but now run

    1. SET_INPUT_SHAPER SHAPER_TYPE=2HUMP_EI SHAPER_FREQ_X=40 SHAPER_FREQ_Y=40
    2. TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5

    Essentially, we are printing the ringing test model with TUNING_TOWER using 2HUMP_EI shaper with shaper_freq = 60 Hz, 50 Hz, and 40 Hz.

    If none of the models demonstrate improvements in ringing, then, unfortunately, it does not look like the input shaping techniques can help with your case.

    Otherwise, it may be that all models show no ringing, or some show the ringing and some - not so much. Choose the test model with the highest frequency that still shows good improvements in ringing. For example, if 40 Hz and 50 Hz models show almost no ringing, and 60 Hz model already shows some more ringing, stick with 50 Hz.

    Now check if EI shaper would be good enough in your case. Choose EI shaper frequency based on the frequency of 2HUMP_EI shaper you chose:

    Now print the test model one more time, running

    1. SET_INPUT_SHAPER SHAPER_TYPE=EI SHAPER_FREQ_X=... SHAPER_FREQ_Y=...
    2. TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5

    providing the shaper_freq_x=... and shaper_freq_y=... as determined previously.

    If EI shaper shows very comparable good results as 2HUMP_EI shaper, stick with EI shaper and the frequency determined earlier, otherwise use 2HUMP_EI shaper with the corresponding frequency. Add the results to printer.cfg as, e.g.

    [input_shaper]\nshaper_freq_x: 50\nshaper_freq_y: 50\nshaper_type: 2hump_ei\n

    Continue the tuning with Selecting max_accel section.

    "},{"location":"Resonance_Compensation.html#troubleshooting-and-faq","title":"Troubleshooting and FAQ","text":""},{"location":"Resonance_Compensation.html#i-cannot-get-reliable-measurements-of-resonance-frequencies","title":"I cannot get reliable measurements of resonance frequencies","text":"

    First, make sure it is not some other problem with the printer instead of ringing. If the measurements are not reliable because, say, the distance between the oscillations is not stable, it might mean that the printer has several resonance frequencies on the same axis. One may try to follow the tuning process described in Unreliable measurements of ringing frequencies section and still get something out of the input shaping technique. Another possibility is to install an accelerometer, measure the resonances with it, and auto-tune the input shaper using the results of those measurements.

    "},{"location":"Resonance_Compensation.html#after-enabling-input_shaper-i-get-too-smoothed-printed-parts-and-fine-details-are-lost","title":"After enabling [input_shaper], I get too smoothed printed parts and fine details are lost","text":"

    Check the considerations in Selecting max_accel section. If the resonance frequency is low, one should not set too high max_accel or increase square_corner_velocity parameters. It might also be better to choose MZV or even ZV input shapers over EI (or 2HUMP_EI and 3HUMP_EI shapers).

    "},{"location":"Resonance_Compensation.html#after-successfully-printing-for-some-time-without-ringing-it-appears-to-come-back","title":"After successfully printing for some time without ringing, it appears to come back","text":"

    It is possible that after some time the resonance frequencies have changed. E.g. maybe the belts tension has changed (belts got more loose), etc. It is a good idea to check and re-measure the ringing frequencies as described in Ringing frequency section and update your config file if necessary.

    "},{"location":"Resonance_Compensation.html#is-dual-carriage-setup-supported-with-input-shapers","title":"Is dual carriage setup supported with input shapers?","text":"

    Yes. In this case, one should measure the resonances twice for each carriage. For example, if the second (dual) carriage is installed on X axis, it is possible to set different input shapers for X axis for the primary and dual carriages. However, the input shaper for Y axis should be the same for both carriages (as ultimately this axis is driven by one or more stepper motors each commanded to perform exactly the same steps). One possibility to configure the input shaper for such setups is to keep [input_shaper] section empty and additionally define a [delayed_gcode] section in the printer.cfg as follows:

    [input_shaper]\n# Intentionally empty\n\n[delayed_gcode init_shaper]\ninitial_duration: 0.1\ngcode:\n  SET_DUAL_CARRIAGE CARRIAGE=1\n  SET_INPUT_SHAPER SHAPER_TYPE_X=<dual_carriage_shaper> SHAPER_FREQ_X=<dual_carriage_freq> SHAPER_TYPE_Y=<y_shaper> SHAPER_FREQ_Y=<y_freq>\n  SET_DUAL_CARRIAGE CARRIAGE=0\n  SET_INPUT_SHAPER SHAPER_TYPE_X=<primary_carriage_shaper> SHAPER_FREQ_X=<primary_carriage_freq> SHAPER_TYPE_Y=<y_shaper> SHAPER_FREQ_Y=<y_freq>\n

    Note that SHAPER_TYPE_Y and SHAPER_FREQ_Y should be the same in both commands. It is also possible to put a similar snippet into the start g-code in the slicer, however then the shaper will not be enabled until any print is started.

    Note that the input shaper only needs to be configured once. Subsequent changes of the carriages or their modes via SET_DUAL_CARRIAGE command will preserve the configured input shaper parameters.

    "},{"location":"Resonance_Compensation.html#does-input_shaper-affect-print-time","title":"Does input_shaper affect print time?","text":"

    No, input_shaper feature has pretty much no impact on the print times by itself. However, the value of max_accel certainly does (tuning of this parameter described in this section).

    "},{"location":"Resonance_Compensation.html#technical-details","title":"Technical details","text":""},{"location":"Resonance_Compensation.html#input-shapers","title":"Input shapers","text":"

    Input shapers used in Kalico are rather standard, and one can find more in-depth overview in the articles describing the corresponding shapers. This section contains a brief overview of some technical aspects of the supported input shapers. The table below shows some (usually approximate) parameters of each shaper.

    Input shaper Shaper duration Vibration reduction 20x (5% vibration tolerance) Vibration reduction 10x (10% vibration tolerance) ZV 0.5 / shaper_freq N/A \u00b1 5% shaper_freq MZV 0.75 / shaper_freq \u00b1 4% shaper_freq -10%...+15% shaper_freq ZVD 1 / shaper_freq \u00b1 15% shaper_freq \u00b1 22% shaper_freq EI 1 / shaper_freq \u00b1 20% shaper_freq \u00b1 25% shaper_freq 2HUMP_EI 1.5 / shaper_freq \u00b1 35% shaper_freq \u00b1 40 shaper_freq 3HUMP_EI 2 / shaper_freq -45...+50% shaper_freq -50%...+55% shaper_freq

    A note on vibration reduction: the values in the table above are approximate. If the damping ratio of the printer is known for each axis, the shaper can be configured more precisely and it will then reduce the resonances in a bit wider range of frequencies. However, the damping ratio is usually unknown and is hard to estimate without a special equipment, so Kalico uses 0.1 value by default, which is a good all-round value. The frequency ranges in the table cover a number of different possible damping ratios around that value (approx. from 0.05 to 0.2).

    Also note that EI, 2HUMP_EI, and 3HUMP_EI are tuned to reduce vibrations to 5%, so the values for 10% vibration tolerance are provided only for the reference.

    How to use this table:

    "},{"location":"Rotation_Distance.html","title":"Rotation distance","text":"

    Stepper motor drivers on Kalico require a rotation_distance parameter in each stepper config section. The rotation_distance is the amount of distance that the axis moves with one full revolution of the stepper motor. This document describes how one can configure this value.

    "},{"location":"Rotation_Distance.html#obtaining-rotation_distance-from-steps_per_mm-or-step_distance","title":"Obtaining rotation_distance from steps_per_mm (or step_distance)","text":"

    The designers of your 3d printer originally calculated steps_per_mm from a rotation distance. If you know the steps_per_mm then it is possible to use this general formula to obtain that original rotation distance:

    rotation_distance = <full_steps_per_rotation> * <microsteps> / <steps_per_mm>\n

    Or, if you have an older Kalico configuration and know the step_distance parameter you can use this formula:

    rotation_distance = <full_steps_per_rotation> * <microsteps> * <step_distance>\n

    The <full_steps_per_rotation> setting is determined from the type of stepper motor. Most stepper motors are \"1.8 degree steppers\" and therefore have 200 full steps per rotation (360 divided by 1.8 is 200). Some stepper motors are \"0.9 degree steppers\" and thus have 400 full steps per rotation. Other stepper motors are rare. If unsure, do not set full_steps_per_rotation in the config file and use 200 in the formula above.

    The <microsteps> setting is determined by the stepper motor driver. Most drivers use 16 microsteps. If unsure, set microsteps: 16 in the config and use 16 in the formula above.

    Almost all printers should have a whole number for rotation_distance on X, Y, and Z type axes. If the above formula results in a rotation_distance that is within .01 of a whole number then round the final value to that whole_number.

    "},{"location":"Rotation_Distance.html#calibrating-rotation_distance-on-extruders","title":"Calibrating rotation_distance on extruders","text":"

    On an extruder, the rotation_distance is the amount of distance the filament travels for one full rotation of the stepper motor. The best way to get an accurate value for this setting is to use a \"measure and trim\" procedure.

    First start with an initial guess for the rotation distance. This may be obtained from steps_per_mm or by inspecting the hardware.

    Then use the following procedure to \"measure and trim\":

    1. Make sure the extruder has filament in it, the hotend is heated to an appropriate temperature, and the printer is ready to extrude.
    2. Use a marker to place a mark on the filament around 70mm from the intake of the extruder body. Then use a digital calipers to measure the actual distance of that mark as precisely as one can. Note this as <initial_mark_distance>.
    3. Extrude 50mm of filament with the following command sequence: G91 followed by G1 E50 F60. Note 50mm as <requested_extrude_distance>. Wait for the extruder to finish the move (it will take about 50 seconds). It is important to use the slow extrusion rate for this test as a faster rate can cause high pressure in the extruder which will skew the results. (Do not use the \"extrude button\" on graphical front-ends for this test as they extrude at a fast rate.)
    4. Use the digital calipers to measure the new distance between the extruder body and the mark on the filament. Note this as <subsequent_mark_distance>. Then calculate: actual_extrude_distance = <initial_mark_distance> - <subsequent_mark_distance>
    5. Calculate rotation_distance as: rotation_distance = <previous_rotation_distance> * <actual_extrude_distance> / <requested_extrude_distance> Round the new rotation_distance to three decimal places.

    If the actual_extrude_distance differs from requested_extrude_distance by more than about 2mm then it is a good idea to perform the steps above a second time.

    Note: Do not use a \"measure and trim\" type of method to calibrate x, y, or z type axes. The \"measure and trim\" method is not accurate enough for those axes and will likely lead to a worse configuration. Instead, if needed, those axes can be determined by measuring the belts, pulleys, and lead screw hardware.

    "},{"location":"Rotation_Distance.html#obtaining-rotation_distance-by-inspecting-the-hardware","title":"Obtaining rotation_distance by inspecting the hardware","text":"

    It's possible to calculate rotation_distance with knowledge of the stepper motors and printer kinematics. This may be useful if the steps_per_mm is not known or if designing a new printer.

    "},{"location":"Rotation_Distance.html#belt-driven-axes","title":"Belt driven axes","text":"

    It is easy to calculate rotation_distance for a linear axis that uses a belt and pulley.

    First determine the type of belt. Most printers use a 2mm belt pitch (that is, each tooth on the belt is 2mm apart). Then count the number of teeth on the stepper motor pulley. The rotation_distance is then calculated as:

    rotation_distance = <belt_pitch> * <number_of_teeth_on_pulley>\n

    For example, if a printer has a 2mm belt and uses a pulley with 20 teeth, then the rotation distance is 40.

    "},{"location":"Rotation_Distance.html#axes-with-a-lead-screw","title":"Axes with a lead screw","text":"

    It is easy to calculate the rotation_distance for common lead screws using the following formula:

    rotation_distance = <screw_pitch> * <number_of_separate_threads>\n

    For example, the common \"T8 leadscrew\" has a rotation distance of 8 (it has a pitch of 2mm and has 4 separate threads).

    Older printers with \"threaded rods\" have only one \"thread\" on the lead screw and thus the rotation distance is the pitch of the screw. (The screw pitch is the distance between each groove on the screw.) So, for example, an M6 metric rod has a rotation distance of 1 and an M8 rod has a rotation distance of 1.25.

    "},{"location":"Rotation_Distance.html#extruder","title":"Extruder","text":"

    It's possible to obtain an initial rotation distance for extruders by measuring the diameter of the \"hobbed bolt\" that pushes the filament and using the following formula: rotation_distance = <diameter> * 3.14

    If the extruder uses gears then it will also be necessary to determine and set the gear_ratio for the extruder.

    The actual rotation distance on an extruder will vary from printer to printer, because the grip of the \"hobbed bolt\" that engages the filament can vary. It can even vary between filament spools. After obtaining an initial rotation_distance, use the measure and trim procedure to obtain a more accurate setting.

    "},{"location":"Rotation_Distance.html#using-a-gear_ratio","title":"Using a gear_ratio","text":"

    Setting a gear_ratio can make it easier to configure the rotation_distance on steppers that have a gear box (or similar) attached to it. Most steppers do not have a gear box - if unsure then do not set gear_ratio in the config.

    When gear_ratio is set, the rotation_distance represents the distance the axis moves with one full rotation of the final gear on the gear box. If, for example, one is using a gearbox with a \"5:1\" ratio, then one could calculate the rotation_distance with knowledge of the hardware and then add gear_ratio: 5:1 to the config.

    For gearing implemented with belts and pulleys, it is possible to determine the gear_ratio by counting the teeth on the pulleys. For example, if a stepper with a 16 toothed pulley drives the next pulley with 80 teeth then one would use gear_ratio: 80:16. Indeed, one could open a common off the shelf \"gear box\" and count the teeth in it to confirm its gear ratio.

    Note that sometimes a gearbox will have a slightly different gear ratio than what it is advertised as. The common BMG extruder motor gears are an example of this - they are advertised as \"3:1\" but actually use \"50:17\" gearing. (Using teeth numbers without a common denominator may improve overall gear wear as the teeth don't always mesh the same way with each revolution.) The common \"5.18:1 planetary gearbox\", is more accurately configured with gear_ratio: 57:11.

    If several gears are used on an axis then it is possible to provide a comma separated list to gear_ratio. For example, a \"5:1\" gear box driving a 16 toothed to 80 toothed pulley could use gear_ratio: 5:1, 80:16.

    In most cases, gear_ratio should be defined with whole numbers as common gears and pulleys have a whole number of teeth on them. However, in cases where a belt drives a pulley using friction instead of teeth, it may make sense to use a floating point number in the gear ratio (eg, gear_ratio: 107.237:16).

    "},{"location":"SDCard_Updates.html","title":"SDCard updates","text":"

    Many of today's popular controller boards ship with a bootloader capable of updating firmware via SD Card. While this is convenient in many circumstances, these bootloaders typically provide no other way to update firmware. This can be a nuisance if your board is mounted in a location that is difficult to access or if you need to update firmware often. After Kalico has been initially flashed to a controller it is possible to transfer new firmware to the SD Card and initiate the flashing procedure via ssh.

    "},{"location":"SDCard_Updates.html#typical-upgrade-procedure","title":"Typical Upgrade Procedure","text":"

    The procedure for updating MCU firmware using the SD Card is similar to that of other methods. Instead of using make flash it is necessary to run a helper script, flash-sdcard.sh. Updating a BigTreeTech SKR 1.3 might look like the following:

    sudo service klipper stop\ncd ~/klipper\ngit pull\nmake clean\nmake menuconfig\nmake\n./scripts/flash-sdcard.sh /dev/ttyACM0 btt-skr-v1.3\nsudo service klipper start\n

    It is up to the user to determine the device location and board name. If a user needs to flash multiple boards, flash-sdcard.sh (or make flash if appropriate) should be run for each board prior to restarting the Klipper service.

    Supported boards can be listed with the following command:

    ./scripts/flash-sdcard.sh -l\n

    If you do not see your board listed it may be necessary to add a new board definition as described below.

    "},{"location":"SDCard_Updates.html#advanced-usage","title":"Advanced Usage","text":"

    The above commands assume that your MCU connects at the default baud rate of 250000 and the firmware is located at ~/klipper/out/klipper.bin. The flash-sdcard.sh script provides options for changing these defaults. All options can be viewed by the help screen:

    ./scripts/flash-sdcard.sh -h\nSD Card upload utility for Kalico\n\nusage: flash_sdcard.sh [-h] [-l] [-c] [-b <baud>] [-f <firmware>]\n                       <device> <board>\n\npositional arguments:\n  <device>        device serial port\n  <board>         board type\n\noptional arguments:\n  -h              show this message\n  -l              list available boards\n  -c              run flash check/verify only (skip upload)\n  -b <baud>       serial baud rate (default is 250000)\n  -f <firmware>   path to klipper.bin\n

    If your board is flashed with firmware that connects at a custom baud rate it is possible to upgrade by specifying the -b option:

    ./scripts/flash-sdcard.sh -b 115200 /dev/ttyAMA0 btt-skr-v1.3\n

    If you wish to flash a build of Kalico located somewhere other than the default location it can be done by specifying the -f option:

    ./scripts/flash-sdcard.sh -f ~/downloads/klipper.bin /dev/ttyAMA0 btt-skr-v1.3\n

    Note that when upgrading a MKS Robin E3 it is not necessary to manually run update_mks_robin.py and supply the resulting binary to flash-sdcard.sh. This procedure is automated during the upload process.

    The -c option is used to perform a check or verify-only operation to test if the board is running the specified firmware correctly. This option is primarily intended for cases where a manual power-cycle is necessary to complete the flashing procedure, such as with bootloaders that use SDIO mode instead of SPI to access their SD Cards. (See Caveats below) But, it can also be used anytime to verify if the code flashed into the board matches the version in your build folder on any supported board.

    "},{"location":"SDCard_Updates.html#caveats","title":"Caveats","text":""},{"location":"SDCard_Updates.html#board-definitions","title":"Board Definitions","text":"

    Most common boards should be available, however it is possible to add a new board definition if necessary. Board definitions are located in ~/klipper/scripts/spi_flash/board_defs.py. The definitions are stored in dictionary, for example:

    BOARD_DEFS = {\n    'generic-lpc1768': {\n        'mcu': \"lpc1768\",\n        'spi_bus': \"ssp1\",\n        \"cs_pin\": \"P0.6\"\n    },\n    ...<further definitions>\n}\n

    The following fields may be specified:

    If software SPI is required, the spi_bus field should be set to swspi and the following additional field should be specified:

    It should be exceedingly rare that Software SPI is necessary, typically only boards with design errors or boards that normally only support SDIO mode for their SD Card will require it. The btt-skr-pro board definition provides an example of the former, and the btt-octopus-f446-v1 board definition provides an example of the latter.

    Prior to creating a new board definition one should check to see if an existing board definition meets the criteria necessary for the new board. If this is the case, a BOARD_ALIAS may be specified. For example, the following alias may be added to specify my-new-board as an alias for generic-lpc1768:

    BOARD_ALIASES = {\n    ...<previous aliases>,\n    'my-new-board': BOARD_DEFS['generic-lpc1768'],\n}\n

    If you need a new board definition and you are uncomfortable with the procedure outlined above it is recommended that you request one in the Kalico Discord server.

    "},{"location":"SDCard_Updates.html#flashing-boards-that-use-sdio","title":"Flashing Boards that use SDIO","text":"

    As mentioned in the Caveats, boards whose bootloader uses SDIO mode to access their SD Card require a power-cycle of the board, and specifically the SD Card itself, in order to switch from the SPI Mode used while writing the file to the SD Card back to SDIO mode for the bootloader to flash it into the board. These board definitions will use the skip_verify flag, which tells the flashing tool to stop after writing the firmware to the SD Card so that the board can be manually power-cycled and the verification step deferred until that's complete.

    There are two scenarios -- one with the RPi Host running on a separate power supply and the other when the RPi Host is running on the same power supply as the main board being flashed. The difference is whether or not it's necessary to also shutdown the RPi and then ssh again after the flashing is complete in order to do the verification step, or if the verification can be done immediately. Here's examples of the two scenarios:

    "},{"location":"SDCard_Updates.html#sdio-programming-with-rpi-on-separate-power-supply","title":"SDIO Programming with RPi on Separate Power Supply","text":"

    A typical session with the RPi on a Separate Power Supply looks like the following. You will, of course, need to use your proper device path and board name:

    sudo service klipper stop\ncd ~/klipper\ngit pull\nmake clean\nmake menuconfig\nmake\n./scripts/flash-sdcard.sh /dev/ttyACM0 btt-octopus-f446-v1\n[[[manually power-cycle the printer board here when instructed]]]\n./scripts/flash-sdcard.sh -c /dev/ttyACM0 btt-octopus-f446-v1\nsudo service klipper start\n
    "},{"location":"SDCard_Updates.html#sdio-programming-with-rpi-on-the-same-power-supply","title":"SDIO Programming with RPi on the Same Power Supply","text":"

    A typical session with the RPi on the Same Power Supply looks like the following. You will, of course, need to use your proper device path and board name:

    sudo service klipper stop\ncd ~/klipper\ngit pull\nmake clean\nmake menuconfig\nmake\n./scripts/flash-sdcard.sh /dev/ttyACM0 btt-octopus-f446-v1\nsudo shutdown -h now\n[[[wait for the RPi to shutdown, then power-cycle and ssh again to the RPi when it restarts]]]\nsudo service klipper stop\ncd ~/klipper\n./scripts/flash-sdcard.sh -c /dev/ttyACM0 btt-octopus-f446-v1\nsudo service klipper start\n

    In this case, since the RPi Host is being restarted, which will restart the klipper service, it's necessary to stop klipper again before doing the verification step and restart it after verification is complete.

    "},{"location":"SDCard_Updates.html#sdio-to-spi-pin-mapping","title":"SDIO to SPI Pin Mapping","text":"

    If your board's schematic uses SDIO for its SD Card, you can map the pins as described in the chart below to determine the compatible Software SPI pins to assign in the board_defs.py file:

    SD Card Pin Micro SD Card Pin SDIO Pin Name SPI Pin Name 9 1 DATA2 None (PU)* 1 2 CD/DATA3 CS 2 3 CMD MOSI 4 4 +3.3V (VDD) +3.3V (VDD) 5 5 CLK SCLK 3 6 GND (VSS) GND (VSS) 7 7 DATA0 MISO 8 8 DATA1 None (PU)* N/A 9 Card Detect (CD) Card Detect (CD) 6 10 GND GND

    * None (PU) indicates an unused pin with a pull-up resistor

    "},{"location":"Skew_Correction.html","title":"Skew correction","text":"

    Software based skew correction can help resolve dimensional inaccuracies resulting from a printer assembly that is not perfectly square. Note that if your printer is significantly skewed it is strongly recommended to first use mechanical means to get your printer as square as possible prior to applying software based correction.

    "},{"location":"Skew_Correction.html#print-a-calibration-object","title":"Print a Calibration Object","text":"

    The first step in correcting skew is to print a calibration object along the plane you want to correct. There is also a calibration object that includes all planes in one model. You want the object oriented so that corner A is toward the origin of the plane.

    Make sure that no skew correction is applied during this print. You may do this by either removing the [skew_correction] module from printer.cfg or by issuing a SET_SKEW CLEAR=1 gcode.

    "},{"location":"Skew_Correction.html#take-your-measurements","title":"Take your measurements","text":"

    The [skew_correction] module requires 3 measurements for each plane you want to correct; the length from Corner A to Corner C, the length from Corner B to Corner D, and the length from Corner A to Corner D. When measuring length AD do not include the flats on the corners that some test objects provide.

    "},{"location":"Skew_Correction.html#configure-your-skew","title":"Configure your skew","text":"

    Make sure [skew_correction] is in printer.cfg. You may now use the SET_SKEW gcode to configure skew_correcton. For example, if your measured lengths along XY are as follows:

    Length AC = 140.4\nLength BD = 142.8\nLength AD = 99.8\n

    SET_SKEW can be used to configure skew correction for the XY plane.

    SET_SKEW XY=140.4,142.8,99.8\n

    You may also add measurements for XZ and YZ to the gcode:

    SET_SKEW XY=140.4,142.8,99.8 XZ=141.6,141.4,99.8 YZ=142.4,140.5,99.5\n

    The [skew_correction] module also supports profile management in a manner similar to [bed_mesh]. After setting skew using the SET_SKEW gcode, you may use the SKEW_PROFILE gcode to save it:

    SKEW_PROFILE SAVE=my_skew_profile\n

    After this command you will be prompted to issue a SAVE_CONFIG gcode to save the profile to persistent storage. If no profile is named my_skew_profile then a new profile will be created. If the named profile exists it will be overwritten.

    Once you have a saved profile, you may load it:

    SKEW_PROFILE LOAD=my_skew_profile\n

    It is also possible to remove an old or out of date profile:

    SKEW_PROFILE REMOVE=my_skew_profile\n

    After removing a profile you will be prompted to issue a SAVE_CONFIG to make this change persist.

    "},{"location":"Skew_Correction.html#verifying-your-correction","title":"Verifying your correction","text":"

    After skew_correction has been configured you may reprint the calibration part with correction enabled. Use the following gcode to check your skew on each plane. The results should be lower than those reported via GET_CURRENT_SKEW.

    CALC_MEASURED_SKEW AC=<ac_length> BD=<bd_length> AD=<ad_length>\n
    "},{"location":"Skew_Correction.html#caveats","title":"Caveats","text":"

    Due to the nature of skew correction it is recommended to configure skew in your start gcode, after homing and any kind of movement that travels near the edge of the print area such as a purge or nozzle wipe. You may use use the SET_SKEW or SKEW_PROFILE gcodes to accomplish this. It is also recommended to issue a SET_SKEW CLEAR=1 in your end gcode.

    Keep in mind that it is possible for [skew_correction] to generate a correction that moves the tool beyond the printer's boundaries on the X and/or Y axes. It is recommended to arrange parts away from the edges when using [skew_correction].

    "},{"location":"Slicers.html","title":"Slicers","text":"

    This document provides some tips for configuring a \"slicer\" application for use with Kalico. Common slicers used with Kalico are Slic3r, Cura, Simplify3D, etc.

    "},{"location":"Slicers.html#set-the-g-code-flavor-to-marlin","title":"Set the G-Code flavor to Marlin","text":"

    Many slicers have an option to configure the \"G-Code flavor\". Most modern slicers nowadays have a \"Klipper\" G-Code flavor that works best for Kalico. \"Marlin\" also should work well with Kalico if the \"Klipper\" flavor is not available. The \"Smoothieware\" setting also works well with Kalico.

    "},{"location":"Slicers.html#kalico-gcode_macro","title":"Kalico gcode_macro","text":"

    Slicers will often allow one to configure \"Start G-Code\" and \"End G-Code\" sequences. It is often convenient to define custom macros in the Kalico config file instead - such as: [gcode_macro START_PRINT] and [gcode_macro END_PRINT]. Then one can just run START_PRINT and END_PRINT in the slicer's configuration. Defining these actions in the Kalico configuration may make it easier to tweak the printer's start and end steps as changes do not require re-slicing.

    See sample-macros.cfg for example START_PRINT and END_PRINT macros.

    See the config reference for details on defining a gcode_macro.

    "},{"location":"Slicers.html#large-retraction-settings-may-require-tuning-kalico","title":"Large retraction settings may require tuning Kalico","text":"

    The maximum speed and acceleration of retraction moves are controlled in Kalico by the max_extrude_only_velocity and max_extrude_only_accel config settings. These settings have a default value that should work well on many printers. However, if one has configured a large retraction in the slicer (eg, 5mm or greater) then one may find they limit the desired speed of retractions.

    If using a large retraction, consider tuning Kalico's pressure advance instead. Otherwise, if one finds the toolhead seems to \"pause\" during retraction and priming, then consider explicitly defining max_extrude_only_velocity and max_extrude_only_accel in the Kalico config file.

    "},{"location":"Slicers.html#do-not-enable-coasting","title":"Do not enable \"coasting\"","text":"

    The \"coasting\" feature is likely to result in poor quality prints with Kalico. Consider using Kalico's pressure advance instead.

    Specifically, if the slicer dramatically changes the extrusion rate between moves then Kalico will perform deceleration and acceleration between moves. This is likely to make blobbing worse, not better.

    In contrast, it is okay (and often helpful) to use a slicer's \"retract\" setting, \"wipe\" setting, and/or \"wipe on retract\" setting.

    "},{"location":"Slicers.html#do-not-use-extra-restart-distance-on-simplify3d","title":"Do not use \"extra restart distance\" on Simplify3d","text":"

    This setting can cause dramatic changes to extrusion rates which can trigger Kalico's maximum extrusion cross-section check. Consider using Kalico's pressure advance or the regular Simplify3d retract setting instead.

    "},{"location":"Slicers.html#disable-preloadve-on-kisslicer","title":"Disable \"PreloadVE\" on KISSlicer","text":"

    If using KISSlicer slicing software then set \"PreloadVE\" to zero. Consider using Kalico's pressure advance instead.

    "},{"location":"Slicers.html#disable-any-advanced-extruder-pressure-settings","title":"Disable any \"advanced extruder pressure\" settings","text":"

    Some slicers advertise an \"advanced extruder pressure\" capability. It is recommended to keep these options disabled when using Kalico as they are likely to result in poor quality prints. Consider using Kalico's pressure advance instead.

    Specifically, these slicer settings can instruct the firmware to make wild changes to the extrusion rate in the hope that the firmware will approximate those requests and the printer will roughly obtain a desirable extruder pressure. Kalico, however, utilizes precise kinematic calculations and timing. When Kalico is commanded to make significant changes to the extrusion rate it will plan out the corresponding changes to velocity, acceleration, and extruder movement - which is not the slicer's intent. The slicer may even command excessive extrusion rates to the point that it triggers Kalico's maximum extrusion cross-section check.

    In contrast, it is okay (and often helpful) to use a slicer's \"retract\" setting, \"wipe\" setting, and/or \"wipe on retract\" setting.

    "},{"location":"Slicers.html#start_print-macros","title":"START_PRINT macros","text":"

    When using a START_PRINT macro or similar, it is useful to sometimes pass through parameters from the slicer variables to the macro.

    In Cura, to pass through temperatures, the following start gcode would be used:

    START_PRINT BED_TEMP={material_bed_temperature_layer_0} EXTRUDER_TEMP={material_print_temperature_layer_0}\n

    In slic3r derivatives such as PrusaSlicer and SuperSlicer, the following would be used:

    START_PRINT EXTRUDER_TEMP=[first_layer_temperature] BED_TEMP=[first_layer_bed_temperature]\n

    Also note that these slicers will insert their own heating codes when certain conditions are not met. In Cura, the existence of the {material_bed_temperature_layer_0} and {material_print_temperature_layer_0} variables is enough to mitigate this. In slic3r derivatives, you would use:

    M140 S0\nM104 S0\n

    before the macro call. Also note that SuperSlicer has a \"custom gcode only\" button option, which achieves the same outcome.

    An example of a START_PRINT macro using these paramaters can be found in config/sample-macros.cfg

    "},{"location":"Sponsors.html","title":"Sponsors","text":"

    Kalico is a community-driven, open-source project that is free to use (as in \"free beer\"). While we don't have official sponsors yet, we are deeply grateful for the generous support from our community. Every contribution helps us continue improving Kalico for everyone.

    If you'd like to support Kalico, donations to our Ko-Fi are more than welcome: \ud83d\udc49 https://ko-fi.com/kalicocrew

    "},{"location":"Sponsors.html#the-people-behind-kalico","title":"The People behind Kalico","text":""},{"location":"Sponsors.html#the-crew","title":"The Crew","text":"Name Alias GitHub Bea NanceBea initiated the Kalico project together with Ma\u00ebl, forking the awesome Klipper firmware originally as \"Danger-Klipper\" to add some bleeding edge spice to it. \"So I saw people wanted some community-driven features in klipper, so i was like \"ehh, i'll just fork it and give it a go\" bwnance @bwnance Ma\u00ebl KerbiriouMa\u00ebl together with Bea brought Kalico to life. piezoid @Piezoid Rogerio GoncalvesRoger chimed in early into the development of Kalico, and has since been a crucial contributor to the project. rogerlz @rogerlz Frank TackittFrank started his klipper hacking with exclude_object and just forgot to stop there frank.af @kageurufu"},{"location":"Sponsors.html#contributors","title":"Contributors","text":"Name Alias GitHub Vinzenz Hassert\"Uhh dunno... I mean I did pid profiles, filament sensors and curve control mainly. And I am best at giving Roger grey hairs cause I do huge pull requests!\" LastZeanon @LastZeanon Yancey ArringtonYancey wrote the docs for all the bleeding edge features and model predictive control, otherwise you wouldn't know about all the fancy stuff Kalico brings to the table! He also helps other community members a lot with their questions. What a great guy! Ray_Boy @YanceyA Ryan GhoshAll Ryan cares about are the TradRack and Belay modules of Kalico. How selfish! (no, in fact, that is very generous. Thanks Ryan!) RyanG @rsghosh Lasse DalegaardOur secret consultant for roasting everything. He also contributed a lot more than he is willing to admit. Silly Lasse. dalegaard @dalegaard Philipp MolitorPhil started hacking around with the docs because he does web stuff and 3D printers, and liked the Kalico Crew so much he just... stuck around.\"Hehehe... I wrote this page!\" philm0 @PhilippMolitor"},{"location":"Sponsors.html#other-kalico-contributors","title":"Other Kalico Contributors","text":"

    Kalico is a community effort, and we have a lot more people helping us! For a full list of people, have a look at the members of the GitHub Organization and our Contributors.

    "},{"location":"Sponsors.html#original-klipper-developers","title":"Original Klipper Developers","text":"

    See https://www.klipper3d.org/Sponsors.html for further information.

    "},{"location":"Sponsors.html#kevin-oconnor","title":"Kevin O'Connor","text":"

    Kevin is the original author and current maintainer of Klipper. Donate at: https://ko-fi.com/koconnor or https://www.patreon.com/koconnor

    "},{"location":"Sponsors.html#eric-callahan","title":"Eric Callahan","text":"

    Eric is the author of bed_mesh, spi_flash, and several other Klipper modules. Eric has a donations page at: https://ko-fi.com/arksine

    "},{"location":"Sponsors.html#related-kalico-projects","title":"Related Kalico Projects","text":"

    Kalico is frequently used with other Free Software. Consider using or supporting these projects.

    "},{"location":"Status_Reference.html","title":"Status reference","text":"

    This document is a reference of printer status information available in Kalico macros, display fields, and via the API Server.

    The fields in this document are subject to change - if using an attribute be sure to review the Config Changes document when upgrading the Kalico software.

    "},{"location":"Status_Reference.html#angle","title":"angle","text":"

    The following information is available in angle some_name objects:

    "},{"location":"Status_Reference.html#bed_mesh","title":"bed_mesh","text":"

    The following information is available in the bed_mesh object:

    "},{"location":"Status_Reference.html#bed_screws","title":"bed_screws","text":"

    The following information is available in the Config_Reference.md#bed_screws object:

    "},{"location":"Status_Reference.html#belay","title":"belay","text":"

    The following information is available in belay some_name objects:

    "},{"location":"Status_Reference.html#configfile","title":"configfile","text":"

    The following information is available in the configfile object (this object is always available):

    "},{"location":"Status_Reference.html#display_status","title":"display_status","text":"

    The following information is available in the display_status object (this object is automatically available if a display config section is defined):

    "},{"location":"Status_Reference.html#dockable_probe","title":"dockable_probe","text":"

    The following information is available in the dockable_probe:

    "},{"location":"Status_Reference.html#endstop_phase","title":"endstop_phase","text":"

    The following information is available in the endstop_phase object:

    "},{"location":"Status_Reference.html#exclude_object","title":"exclude_object","text":"

    The following information is available in the exclude_object object:

    [\n  {\n    \"polygon\": [\n      [ 156.25, 146.2511675 ],\n      [ 156.25, 153.7488325 ],\n      [ 163.75, 153.7488325 ],\n      [ 163.75, 146.2511675 ]\n    ],\n    \"name\": \"CYLINDER_2_STL_ID_2_COPY_0\",\n    \"center\": [ 160, 150 ]\n  },\n  {\n    \"polygon\": [\n      [ 146.25, 146.2511675 ],\n      [ 146.25, 153.7488325 ],\n      [ 153.75, 153.7488325 ],\n      [ 153.75, 146.2511675 ]\n    ],\n    \"name\": \"CYLINDER_2_STL_ID_1_COPY_0\",\n    \"center\": [ 150, 150 ]\n  }\n]\n
    "},{"location":"Status_Reference.html#extruder_stepper","title":"extruder_stepper","text":"

    The following information is available for extruder_stepper objects (as well as extruder objects):

    "},{"location":"Status_Reference.html#fan","title":"fan","text":"

    The following information is available in fan, heater_fan some_name and controller_fan some_name objects:

    "},{"location":"Status_Reference.html#filament_switch_sensor","title":"filament_switch_sensor","text":"

    The following information is available in filament_switch_sensor some_name objects:

    "},{"location":"Status_Reference.html#filament_motion_sensor","title":"filament_motion_sensor","text":"

    The following information is available in filament_motion_sensor some_name objects:

    "},{"location":"Status_Reference.html#firmware_retraction","title":"firmware_retraction","text":"

    The following information is available in the firmware_retraction object:

    "},{"location":"Status_Reference.html#gcode","title":"gcode","text":"

    The following information is available in the gcode object:

    "},{"location":"Status_Reference.html#gcode_button","title":"gcode_button","text":"

    The following information is available in gcode_button some_name objects:

    "},{"location":"Status_Reference.html#gcode_button_1","title":"gcode_button","text":"

    The following information is available in gcode_button some_name objects:

    "},{"location":"Status_Reference.html#gcode_macro","title":"gcode_macro","text":"

    The following information is available in gcode_macro some_name objects:

    "},{"location":"Status_Reference.html#gcode_move","title":"gcode_move","text":"

    The following information is available in the gcode_move object (this object is always available):

    "},{"location":"Status_Reference.html#hall_filament_width_sensor","title":"hall_filament_width_sensor","text":"

    The following information is available in the hall_filament_width_sensor object:

    "},{"location":"Status_Reference.html#heater","title":"heater","text":"

    The following information is available for heater objects such as extruder, heater_bed, and heater_generic:

    "},{"location":"Status_Reference.html#heaters","title":"heaters","text":"

    The following information is available in the heaters object (this object is available if any heater is defined):

    "},{"location":"Status_Reference.html#idle_timeout","title":"idle_timeout","text":"

    The following information is available in the idle_timeout object (this object is always available):

    "},{"location":"Status_Reference.html#led","title":"led","text":"

    The following information is available for each [led led_name], [neopixel led_name], [dotstar led_name], [pca9533 led_name], and [pca9632 led_name] config section defined in printer.cfg:

    "},{"location":"Status_Reference.html#manual_probe","title":"manual_probe","text":"

    The following information is available in the manual_probe object:

    "},{"location":"Status_Reference.html#mcu","title":"mcu","text":"

    The following information is available in mcu and mcu some_name objects:

    "},{"location":"Status_Reference.html#mixing_extruder","title":"mixing_extruder","text":"

    The following information is available in the mixing_extruder object (this object is automatically available if any stepper config section is defined):

    The following information is available in mixing_extruder objects:

    "},{"location":"Status_Reference.html#motion_report","title":"motion_report","text":"

    The following information is available in the motion_report object (this object is automatically available if any stepper config section is defined):

    "},{"location":"Status_Reference.html#output_pin","title":"output_pin","text":"

    The following information is available in output_pin some_name and pwm_tool some_name objects:

    "},{"location":"Status_Reference.html#palette2","title":"palette2","text":"

    The following information is available in the palette2 object:

    "},{"location":"Status_Reference.html#pause_resume","title":"pause_resume","text":"

    The following information is available in the pause_resume object:

    "},{"location":"Status_Reference.html#print_stats","title":"print_stats","text":"

    The following information is available in the print_stats object (this object is automatically available if a virtual_sdcard config section is defined):

    "},{"location":"Status_Reference.html#probe","title":"probe","text":"

    The following information is available in the probe object (this object is also available if a bltouch config section is defined):

    "},{"location":"Status_Reference.html#pwm_cycle_time","title":"pwm_cycle_time","text":"

    The following information is available in pwm_cycle_time some_name objects:

    "},{"location":"Status_Reference.html#quad_gantry_level","title":"quad_gantry_level","text":"

    The following information is available in the quad_gantry_level object (this object is available if quad_gantry_level is defined):

    "},{"location":"Status_Reference.html#query_endstops","title":"query_endstops","text":"

    The following information is available in the query_endstops object (this object is available if any endstop is defined):

    "},{"location":"Status_Reference.html#screws_tilt_adjust","title":"screws_tilt_adjust","text":"

    The following information is available in the screws_tilt_adjust object:

    "},{"location":"Status_Reference.html#servo","title":"servo","text":"

    The following information is available in servo some_name objects:

    "},{"location":"Status_Reference.html#stepper_enable","title":"stepper_enable","text":"

    The following information is available in the stepper_enable object (this object is available if any stepper is defined):

    "},{"location":"Status_Reference.html#system_stats","title":"system_stats","text":"

    The following information is available in the system_stats object (this object is always available):

    "},{"location":"Status_Reference.html#temperature-sensors","title":"temperature sensors","text":"

    The following information is available in

    bme280 config_section_name, htu21d config_section_name, sht3x config_section_name, lm75 config_section_name, temperature_host config_section_name and temperature_combined config_section_name objects:

    "},{"location":"Status_Reference.html#temperature_fan","title":"temperature_fan","text":"

    The following information is available in temperature_fan some_name objects:

    "},{"location":"Status_Reference.html#temperature_sensor","title":"temperature_sensor","text":"

    The following information is available in temperature_sensor some_name objects:

    "},{"location":"Status_Reference.html#tmc-drivers","title":"tmc drivers","text":"

    The following information is available in TMC stepper driver objects (eg, [tmc2208 stepper_x]):

    "},{"location":"Status_Reference.html#toolhead","title":"toolhead","text":"

    The following information is available in the toolhead object (this object is always available):

    "},{"location":"Status_Reference.html#dual_carriage","title":"dual_carriage","text":"

    The following information is available in dual_carriage on a cartesian, hybrid_corexy or hybrid_corexz robot

    "},{"location":"Status_Reference.html#tools_calibrate","title":"tools_calibrate","text":"

    The following information is available in the tools_calibrate object:

    "},{"location":"Status_Reference.html#trad_rack","title":"trad_rack","text":"

    The following informatin is available in the trad_rack object:

    "},{"location":"Status_Reference.html#virtual_sdcard","title":"virtual_sdcard","text":"

    The following information is available in the virtual_sdcard object:

    "},{"location":"Status_Reference.html#webhooks","title":"webhooks","text":"

    The following information is available in the webhooks object (this object is always available):

    "},{"location":"Status_Reference.html#z_thermal_adjust","title":"z_thermal_adjust","text":"

    The following information is available in the z_thermal_adjust object (this object is available if z_thermal_adjust is defined).

    "},{"location":"Status_Reference.html#z_tilt","title":"z_tilt","text":"

    The following information is available in the z_tilt object (this object is available if z_tilt is defined):

    "},{"location":"TMC_Drivers.html","title":"TMC drivers","text":"

    This document provides information on using Trinamic stepper motor drivers in SPI/UART mode on Kalico.

    Kalico can also use Trinamic drivers in their \"standalone mode\". However, when the drivers are in this mode, no special Kalico configuration is needed and the advanced Kalico features discussed in this document are not available.

    In addition to this document, be sure to review the TMC driver config reference.

    "},{"location":"TMC_Drivers.html#tuning-motor-current","title":"Tuning motor current","text":"

    A higher driver current increases positional accuracy and torque. However, a higher current also increases the heat produced by the stepper motor and the stepper motor driver. If the stepper motor driver gets too hot it will disable itself and Kalico will report an error. If the stepper motor gets too hot, it loses torque and positional accuracy. (If it gets very hot it may also melt plastic parts attached to it or near it.)

    As a general tuning tip, prefer higher current values as long as the stepper motor does not get too hot and the stepper motor driver does not report warnings or errors. In general, it is okay for the stepper motor to feel warm, but it should not become so hot that it is painful to touch.

    "},{"location":"TMC_Drivers.html#prefer-to-not-specify-a-hold_current","title":"Prefer to not specify a hold_current","text":"

    If one configures a hold_current then the TMC driver can reduce current to the stepper motor when it detects that the stepper is not moving. However, changing motor current may itself introduce motor movement. This may occur due to \"detent forces\" within the stepper motor (the permanent magnet in the rotor pulls towards the iron teeth in the stator) or due to external forces on the axis carriage.

    Most stepper motors will not obtain a significant benefit to reducing current during normal prints, because few printing moves will leave a stepper motor idle for sufficiently long to activate the hold_current feature. And, it is unlikely that one would want to introduce subtle print artifacts to the few printing moves that do leave a stepper idle sufficiently long.

    If one wishes to reduce current to motors during print start routines, then consider issuing SET_TMC_CURRENT commands in a START_PRINT macro to adjust the current before and after normal printing moves.

    Some printers with dedicated Z motors that are idle during normal printing moves (no bed_mesh, no bed_tilt, no Z skew_correction, no \"vase mode\" prints, etc.) may find that Z motors do run cooler with a hold_current. If implementing this then be sure to take into account this type of uncommanded Z axis movement during bed leveling, bed probing, probe calibration, and similar. The driver_TPOWERDOWN and driver_IHOLDDELAY should also be calibrated accordingly. If unsure, prefer to not specify a hold_current.

    "},{"location":"TMC_Drivers.html#setting-spreadcycle-vs-stealthchop-mode","title":"Setting \"spreadCycle\" vs \"stealthChop\" Mode","text":"

    By default, Kalico places the TMC drivers in \"spreadCycle\" mode. If the driver supports \"stealthChop\" then it can be enabled by adding stealthchop_threshold: 999999 to the TMC config section.

    In general, spreadCycle mode provides greater torque and greater positional accuracy than stealthChop mode. However, stealthChop mode may produce significantly lower audible noise on some printers.

    Tests comparing modes have shown an increased \"positional lag\" of around 75% of a full-step during constant velocity moves when using stealthChop mode (for example, on a printer with 40mm rotation_distance and 200 steps_per_rotation, position deviation of constant speed moves increased by ~0.150mm). However, this \"delay in obtaining the requested position\" may not manifest as a significant print defect and one may prefer the quieter behavior of stealthChop mode.

    It is recommended to always use \"spreadCycle\" mode (by not specifying stealthchop_threshold) or to always use \"stealthChop\" mode (by setting stealthchop_threshold to 999999). Unfortunately, the drivers often produce poor and confusing results if the mode changes while the motor is at a non-zero velocity.

    "},{"location":"TMC_Drivers.html#tmc-interpolate-setting-introduces-small-position-deviation","title":"TMC interpolate setting introduces small position deviation","text":"

    The TMC driver interpolate setting may reduce the audible noise of printer movement at the cost of introducing a small systemic positional error. This systemic positional error results from the driver's delay in executing \"steps\" that Kalico sends it. During constant velocity moves, this delay results in a positional error of nearly half a configured microstep (more precisely, the error is half a microstep distance minus a 512th of a full step distance). For example, on an axis with a 40mm rotation_distance, 200 steps_per_rotation, and 16 microsteps, the systemic error introduced during constant velocity moves is ~0.006mm.

    For best positional accuracy consider using spreadCycle mode and disable interpolation (set interpolate: False in the TMC driver config). When configured this way, one may increase the microstep setting to reduce audible noise during stepper movement. Typically, a microstep setting of 64 or 128 will have similar audible noise as interpolation, and do so without introducing a systemic positional error.

    If using stealthChop mode then the positional inaccuracy from interpolation is small relative to the positional inaccuracy introduced from stealthChop mode. Therefore tuning interpolation is not considered useful when in stealthChop mode, and one can leave interpolation in its default state.

    "},{"location":"TMC_Drivers.html#sensorless-homing","title":"Sensorless Homing","text":"

    Sensorless homing allows to home an axis without the need for a physical limit switch. Instead, the carriage on the axis is moved into the mechanical limit making the stepper motor lose steps. The stepper driver senses the lost steps and indicates this to the controlling MCU (Kalico) by toggling a pin. This information can be used by Kalico as end stop for the axis.

    This guide covers the setup of sensorless homing for the X axis of your (cartesian) printer. However, it works the same with all other axes (that require an end stop). You should configure and tune it for one axis at a time.

    "},{"location":"TMC_Drivers.html#limitations","title":"Limitations","text":"

    Be sure that your mechanical components are able to handle the load of the carriage bumping into the limit of the axis repeatedly. Especially leadscrews might generate a lot of force. Homing a Z axis by bumping the nozzle into the printing surface might not be a good idea. For best results, verify that the axis carriage will make a firm contact with the axis limit.

    Further, sensorless homing might not be accurate enough for your printer. While homing X and Y axes on a cartesian machine can work well, homing the Z axis is generally not accurate enough and may result in an inconsistent first layer height. Homing a delta printer sensorless is not advisable due to missing accuracy.

    Further, the stall detection of the stepper driver is dependent on the mechanical load on the motor, the motor current and the motor temperature (coil resistance).

    Sensorless homing works best at medium motor speeds. For very slow speeds (less than 10 RPM) the motor does not generate significant back EMF and the TMC cannot reliably detect motor stalls. Further, at very high speeds, the back EMF of the motor approaches the supply voltage of the motor, so the TMC cannot detect stalls anymore. It is advised to have a look in the datasheet of your specific TMCs. There you can also find more details on limitations of this setup.

    "},{"location":"TMC_Drivers.html#prerequisites","title":"Prerequisites","text":"

    A few prerequisites are needed to use sensorless homing:

    1. A stallGuard capable TMC stepper driver (tmc2130, tmc2209, tmc2660, tmc5160 or tmc2160).
    2. SPI / UART interface of the TMC driver wired to micro-controller (stand-alone mode does not work).
    3. The appropriate \"DIAG\" or \"SG_TST\" pin of TMC driver connected to the micro-controller.
    4. The steps in the config checks document must be run to confirm the stepper motors are configured and working properly.
    "},{"location":"TMC_Drivers.html#tuning","title":"Tuning","text":"

    The procedure described here has six major steps:

    1. Choose a homing speed.
    2. Configure the printer.cfg file to enable sensorless homing.
    3. Find the stallguard setting with highest sensitivity that successfully homes.
    4. Find the stallguard setting with lowest sensitivity that successfully homes with a single touch.
    5. Update the printer.cfg with the desired stallguard setting.
    6. Create or update printer.cfg macros to home consistently.
    "},{"location":"TMC_Drivers.html#choose-homing-speed","title":"Choose homing speed","text":"

    The homing speed is an important choice when performing sensorless homing. It's desirable to use a slow homing speed so that the carriage does not exert excessive force on the frame when making contact with the end of the rail. However, the TMC drivers can't reliably detect a stall at very slow speeds.

    A good starting point for the homing speed is for the stepper motor to make a full rotation every two seconds. For many axes this will be the rotation_distance divided by two. For example:

    [stepper_x]\nrotation_distance: 40\nhoming_speed: 20\n...\n
    "},{"location":"TMC_Drivers.html#configure-printercfg-for-sensorless-homing","title":"Configure printer.cfg for sensorless homing","text":"

    Be sure that a hold_current setting is not specified in the TMC driver section of the config. (If a hold_current is set then after contact is made, the motor stops while the carriage is pressed against the end of the rail, and reducing the current while in that position may cause the carriage to move - that results in poor performance and will confuse the tuning process.)

    It is necessary to configure the sensorless homing pins and to configure initial \"stallguard\" settings. A tmc2209 example configuration for an X axis might look like:

    [tmc2209 stepper_x]\ndiag_pin: ^PA1      # Set to MCU pin connected to TMC DIAG pin\ndriver_SGTHRS: 255  # 255 is most sensitive value, 0 is least sensitive\nhome_current: 1\n...\n\n[stepper_x]\nendstop_pin: tmc2209_stepper_x:virtual_endstop\nhoming_retract_dist: 10 # Must be greater than 0 or set use_sensorless_homing: True\n...\n

    An example tmc2130 or tmc5160 config might look like:

    [tmc2130 stepper_x]\ndiag1_pin: ^!PA1 # Pin connected to TMC DIAG1 pin (or use diag0_pin / DIAG0 pin)\ndriver_SGT: -64  # -64 is most sensitive value, 63 is least sensitive\nhome_current: 1\n...\n\n[stepper_x]\nendstop_pin: tmc2130_stepper_x:virtual_endstop\nhoming_retract_dist: 10\n...\n

    An example tmc2660 config might look like:

    [tmc2660 stepper_x]\ndriver_SGT: -64     # -64 is most sensitive value, 63 is least sensitive\nhome_current: 1\n...\n\n[stepper_x]\nendstop_pin: ^PA1   # Pin connected to TMC SG_TST pin\nuse_sensorless_homing: True # Required if endstop_pin is not a virtual_endstop\nhoming_retract_dist: 10\n...\n

    The examples above only show settings specific to sensorless homing. See the config reference for all the available options.

    "},{"location":"TMC_Drivers.html#find-highest-sensitivity-that-successfully-homes","title":"Find highest sensitivity that successfully homes","text":"

    Place the carriage near the center of the rail. Use the SET_TMC_FIELD command to set the highest sensitivity. For tmc2209:

    SET_TMC_FIELD STEPPER=stepper_x FIELD=SGTHRS VALUE=255\n

    For tmc2130, tmc5160, tmc2160, and tmc2660:

    SET_TMC_FIELD STEPPER=stepper_x FIELD=sgt VALUE=-64\n

    Then issue a G28 X0 command and verify the axis does not move at all or quickly stops moving. If the axis does not stop, then issue an M112 to halt the printer - something is not correct with the diag/sg_tst pin wiring or configuration and it must be corrected before continuing.

    Next, continually decrease the sensitivity of the VALUE setting and run the SET_TMC_FIELD G28 X0 commands again to find the highest sensitivity that results in the carriage successfully moving all the way to the endstop and halting. (For tmc2209 drivers this will be decreasing SGTHRS, for other drivers it will be increasing sgt.) Be sure to start each attempt with the carriage near the center of the rail (if needed issue M84 and then manually move the carriage to the center). It should be possible to find the highest sensitivity that homes reliably (settings with higher sensitivity result in small or no movement). Note the found value as maximum_sensitivity. (If the minimum possible sensitivity (SGTHRS=0 or sgt=63) is obtained without any carriage movement then something is not correct with the diag/sg_tst pin wiring or configuration and it must be corrected before continuing.)

    When searching for maximum_sensitivity, it may be convenient to jump to different VALUE settings (so as to bisect the VALUE parameter). If doing this then be prepared to issue an M112 command to halt the printer, as a setting with a very low sensitivity may cause the axis to repeatedly \"bang\" into the end of the rail.

    Be sure to wait a couple of seconds between each homing attempt. After the TMC driver detects a stall it may take a little time for it to clear its internal indicator and be capable of detecting another stall.

    During these tuning tests, if a G28 X0 command does not move all the way to the axis limit, then be careful with issuing any regular movement commands (eg, G1). Kalico will not have a correct understanding of the carriage position and a move command may cause undesirable and confusing results.

    "},{"location":"TMC_Drivers.html#find-lowest-sensitivity-that-homes-with-one-touch","title":"Find lowest sensitivity that homes with one touch","text":"

    When homing with the found maximum_sensitivity value, the axis should move to the end of the rail and stop with a \"single touch\" - that is, there should not be a \"clicking\" or \"banging\" sound. (If there is a banging or clicking sound at maximum_sensitivity then the homing_speed may be too low, the driver current may be too low, or sensorless homing may not be a good choice for the axis.)

    The next step is to again continually move the carriage to a position near the center of the rail, decrease the sensitivity, and run the SET_TMC_FIELD G28 X0 commands - the goal is now to find the lowest sensitivity that still results in the carriage successfully homing with a \"single touch\". That is, it does not \"bang\" or \"click\" when contacting the end of the rail. Note the found value as minimum_sensitivity.

    "},{"location":"TMC_Drivers.html#update-printercfg-with-sensitivity-value","title":"Update printer.cfg with sensitivity value","text":"

    After finding maximum_sensitivity and minimum_sensitivity, use a calculator to obtain the recommend sensitivity as minimum_sensitivity + (maximum_sensitivity - minimum_sensitivity)/3. The recommended sensitivity should be in the range between the minimum and maximum, but slightly closer to the minimum. Round the final value to the nearest integer value.

    For tmc2209 set this in the config as driver_SGTHRS, for other TMC drivers set this in the config as driver_SGT.

    If the range between maximum_sensitivity and minimum_sensitivity is small (eg, less than 5) then it may result in unstable homing. A faster homing speed may increase the range and make the operation more stable.

    Note that if any change is made to driver current, homing speed, or a notable change is made to the printer hardware, then it will be necessary to run the tuning process again.

    "},{"location":"TMC_Drivers.html#using-macros-when-homing","title":"Using Macros when Homing","text":"

    Unlike Klipper, in Kalico, you do not need macros for sensorless homing management. Homing current is handled by the TMC block, homing retract distance is used to define a minimum homing distance (which can also be manually configured) which is used for sensorless homing verification as well as post home retract. In depth guide for sensorless setup coming soon.

    "},{"location":"TMC_Drivers.html#tips-for-sensorless-homing-on-corexy","title":"Tips for sensorless homing on CoreXY","text":"

    It is possible to use sensorless homing on the X and Y carriages of a CoreXY printer. Kalico uses the [stepper_x] stepper to detect stalls when homing the X carriage and uses the [stepper_y] stepper to detect stalls when homing the Y carriage.

    Use the tuning guide described above to find the appropriate \"stall sensitivity\" for each carriage, but be aware of the following restrictions:

    1. When using sensorless homing on CoreXY, make sure there is no hold_current configured for either stepper.
    2. While tuning, make sure both the X and Y carriages are near the center of their rails before each home attempt.
    3. After tuning is complete, when homing both X and Y, use macros to ensure that one axis is homed first, then move that carriage away from the axis limit, pause for at least 2 seconds, and then start the homing of the other carriage. The move away from the axis avoids homing one axis while the other is pressed against the axis limit (which may skew the stall detection). The pause is necessary to ensure the driver's stall flag is cleared prior to homing again.

    An example CoreXY homing macro might look like:

    [gcode_macro HOME]\ngcode:\n    G90\n    # Home Z\n    G28 Z0\n    G1 Z10 F1200\n    # Home Y\n    G28 Y0\n    G1 Y5 F1200\n    # Home X\n    G4 P2000\n    G28 X0\n    G1 X5 F1200\n
    "},{"location":"TMC_Drivers.html#querying-and-diagnosing-driver-settings","title":"Querying and diagnosing driver settings","text":"

    The `DUMP_TMC command is a useful tool when configuring and diagnosing the drivers. It will report all fields configured by Kalico as well as all fields that can be queried from the driver.

    All of the reported fields are defined in the Trinamic datasheet for each driver. These datasheets can be found on the Trinamic website. Obtain and review the Trinamic datasheet for the driver to interpret the results of DUMP_TMC.

    "},{"location":"TMC_Drivers.html#configuring-driver_xxx-settings","title":"Configuring driver_XXX settings","text":"

    Kalico supports configuring many low-level driver fields using driver_XXX settings. The TMC driver config reference has the full list of fields available for each type of driver.

    In addition, almost all fields can be modified at run-time using the SET_TMC_FIELD command.

    Each of these fields is defined in the Trinamic datasheet for each driver. These datasheets can be found on the Trinamic website.

    Note that the Trinamic datasheets sometime use wording that can confuse a high-level setting (such as \"hysteresis end\") with a low-level field value (eg, \"HEND\"). In Kalico, driver_XXX and SET_TMC_FIELD always set the low-level field value that is actually written to the driver. So, for example, if the Trinamic datasheet states that a value of 3 must be written to the HEND field to obtain a \"hysteresis end\" of 0, then set driver_HEND=3 to obtain the high-level value of 0.

    "},{"location":"TMC_Drivers.html#common-questions","title":"Common Questions","text":""},{"location":"TMC_Drivers.html#can-i-use-stealthchop-mode-on-an-extruder-with-pressure-advance","title":"Can I use stealthChop mode on an extruder with pressure advance?","text":"

    Many people successfully use \"stealthChop\" mode with Kalico's pressure advance. Kalico implements smooth pressure advance which does not introduce any instantaneous velocity changes.

    However, \"stealthChop\" mode may produce lower motor torque and/or produce higher motor heat. It may or may not be an adequate mode for your particular printer.

    "},{"location":"TMC_Drivers.html#i-keep-getting-unable-to-read-tmc-uart-stepper_x-register-ifcnt-errors","title":"I keep getting \"Unable to read tmc uart 'stepper_x' register IFCNT\" errors?","text":"

    This occurs when Kalico is unable to communicate with a tmc2208 or tmc2209 driver.

    Make sure that the motor power is enabled, as the stepper motor driver generally needs motor power before it can communicate with the micro-controller.

    If this error occurs after flashing Kalico for the first time, then the stepper driver may have been previously programmed in a state that is not compatible with Kalico. To reset the state, remove all power from the printer for several seconds (physically unplug both USB and power plugs).

    Otherwise, this error is typically the result of incorrect UART pin wiring or an incorrect Kalico configuration of the UART pin settings.

    "},{"location":"TMC_Drivers.html#i-keep-getting-unable-to-write-tmc-spi-stepper_x-register-errors","title":"I keep getting \"Unable to write tmc spi 'stepper_x' register ...\" errors?","text":"

    This occurs when Kalico is unable to communicate with a tmc2130, tmc5160 or tmc2160 driver.

    Make sure that the motor power is enabled, as the stepper motor driver generally needs motor power before it can communicate with the micro-controller.

    Otherwise, this error is typically the result of incorrect SPI wiring, an incorrect Kalico configuration of the SPI settings, or an incomplete configuration of devices on an SPI bus.

    Note that if the driver is on a shared SPI bus with multiple devices then be sure to fully configure every device on that shared SPI bus in Kalico. If a device on a shared SPI bus is not configured, then it may incorrectly respond to commands not intended for it and corrupt the communication to the intended device. If there is a device on a shared SPI bus that can not be configured in Kalico, then use a static_digital_output config section to set the CS pin of the unused device high (so that it will not attempt to use the SPI bus). The board's schematic is often a useful reference for finding which devices are on an SPI bus and their associated pins.

    "},{"location":"TMC_Drivers.html#why-did-i-get-a-tmc-reports-error-error","title":"Why did I get a \"TMC reports error: ...\" error?","text":"

    This type of error indicates the TMC driver detected a problem and has disabled itself. That is, the driver stopped holding its position and ignored movement commands. If Kalico detects that an active driver has disabled itself, it will transition the printer into a \"shutdown\" state.

    It's also possible that a TMC reports error shutdown occurs due to SPI errors that prevent communication with the driver (on tmc2130, tmc5160, tmc2160, or tmc2660). If this occurs, it's common for the reported driver status to show 00000000 or ffffffff - for example: TMC reports error: DRV_STATUS: ffffffff ... OR TMC reports error: READRSP@RDSEL2: 00000000 .... Such a failure may be due to an SPI wiring problem or may be due to a self-reset or failure of the TMC driver.

    Some common errors and tips for diagnosing them:

    "},{"location":"TMC_Drivers.html#tmc-reports-error-ot1overtemperror","title":"TMC reports error: ... ot=1(OvertempError!)","text":"

    This indicates the motor driver disabled itself because it became too hot. Typical solutions are to decrease the stepper motor current, increase cooling on the stepper motor driver, and/or increase cooling on the stepper motor.

    "},{"location":"TMC_Drivers.html#tmc-reports-error-shorttognd-or-shorttosupply","title":"TMC reports error: ... ShortToGND OR ShortToSupply","text":"

    This indicates the driver has disabled itself because it detected very high current passing through the driver. This may indicate a loose or shorted wire to the stepper motor or within the stepper motor itself.

    This error may also occur if using stealthChop mode and the TMC driver is not able to accurately predict the mechanical load of the motor. (If the driver makes a poor prediction then it may send too much current through the motor and trigger its own over-current detection.) To test this, disable stealthChop mode and check if the errors continue to occur.

    "},{"location":"TMC_Drivers.html#tmc-reports-error-reset1reset-or-cs_actual0reset-or-se0reset","title":"TMC reports error: ... reset=1(Reset) OR CS_ACTUAL=0(Reset?) OR SE=0(Reset?)","text":"

    This indicates that the driver has reset itself mid-print. This may be due to voltage or wiring issues.

    "},{"location":"TMC_Drivers.html#tmc-reports-error-uv_cp1undervoltage","title":"TMC reports error: ... uv_cp=1(Undervoltage!)","text":"

    This indicates the driver has detected a low-voltage event and has disabled itself. This may be due to wiring or power supply issues.

    "},{"location":"TMC_Drivers.html#how-do-i-tune-spreadcyclecoolstepetc-mode-on-my-drivers","title":"How do I tune spreadCycle/coolStep/etc. mode on my drivers?","text":"

    The Trinamic website has guides on configuring the drivers. These guides are often technical, low-level, and may require specialized hardware. Regardless, they are the best source of information.

    "},{"location":"TSL1401CL_Filament_Width_Sensor.html","title":"TSL1401CL filament width sensor","text":"

    This document describes Filament Width Sensor host module. Hardware used for developing this host module is based on TSL1401CL linear sensor array but it can work with any sensor array that has analog output. You can find designs at Thingiverse.

    To use a sensor array as a filament width sensor, read Config Reference and G-Code documentation.

    "},{"location":"TSL1401CL_Filament_Width_Sensor.html#how-does-it-work","title":"How does it work?","text":"

    Sensor generates analog output based on calculated filament width. Output voltage always equals to detected filament width (Ex. 1.65v, 1.70v, 3.0v). Host module monitors voltage changes and adjusts extrusion multiplier.

    "},{"location":"TSL1401CL_Filament_Width_Sensor.html#note","title":"Note:","text":"

    Sensor readings done with 10 mm intervals by default. If necessary you are free to change this setting by editing MEASUREMENT_INTERVAL_MM parameter in filament_width_sensor.py file.

    "},{"location":"Using_PWM_Tools.html","title":"Using PWM tools","text":"

    This document describes how to setup a PWM-controlled laser or spindle using pwm_tool and some macros.

    "},{"location":"Using_PWM_Tools.html#how-does-it-work","title":"How does it work?","text":"

    With re-purposing the printhead's fan pwm output, you can control lasers or spindles. This is useful if you use switchable print heads, for example the E3D toolchanger or a DIY solution. Usually, cam-tools such as LaserWeb can be configured to use M3-M5 commands, which stand for spindle speed CW (M3 S[0-255]), spindle speed CCW (M4 S[0-255]) and spindle stop (M5).

    Warning: When driving a laser, keep all security precautions that you can think of! Diode lasers are usually inverted. This means, that when the MCU restarts, the laser will be fully on for the time it takes the MCU to start up again. For good measure, it is recommended to always wear appropriate laser-goggles of the right wavelength if the laser is powered; and to disconnect the laser when it is not needed. Also, you should configure a safety timeout, so that when your host or MCU encounters an error, the tool will stop.

    For an example configuration, see config/sample-pwm-tool.cfg.

    "},{"location":"Using_PWM_Tools.html#commands","title":"Commands","text":"

    M3/M4 S<value> : Set PWM duty-cycle. Values between 0 and 255. M5 : Stop PWM output to shutdown value.

    "},{"location":"Using_PWM_Tools.html#laserweb-configuration","title":"Laserweb Configuration","text":"

    If you use Laserweb, a working configuration would be:

    GCODE START:\n    M5            ; Disable Laser\n    G21           ; Set units to mm\n    G90           ; Absolute positioning\n    G0 Z0 F7000   ; Set Non-Cutting speed\n\nGCODE END:\n    M5            ; Disable Laser\n    G91           ; relative\n    G0 Z+20 F4000 ;\n    G90           ; absolute\n\nGCODE HOMING:\n    M5            ; Disable Laser\n    G28           ; Home all axis\n\nTOOL ON:\n    M3 $INTENSITY\n\nTOOL OFF:\n    M5            ; Disable Laser\n\nLASER INTENSITY:\n    S\n
    "},{"location":"Z_Calibration.html","title":"Automatic Z-Offset Calibration","text":"

    This document provides information on calibrating the nozzle's Z offset automatically. With this enabled, manual Z offset or first layer calibrations are needless. It computes always the correct offset independantly of the current temperature, used nozzle or used print bed or flex plate.

    "},{"location":"Z_Calibration.html#why-this","title":"Why This","text":"

    It is possible and this it is what this extension does!

    "},{"location":"Z_Calibration.html#requirements","title":"Requirements","text":"

    But, there are some requirements to use it:

    "},{"location":"Z_Calibration.html#what-it-does","title":"What It Does","text":"
    1. A normal homing of all axes using the Z endstop for Z (this is not part of this plugin). After that, there is a defined zero point in Z. From now on, everything is in relation to this point. So, a new homing would change everything, since the homing is not that precise.
    2. Determine the height of the nozzle by probing the tip of it on the Z endstop (like the homing in step 1. But this one can result in a slightly different value):
    3. Determine the height of the mag-probe by probing the body of the switch on the z-endstop:

    4. Calculate the offset between the tip of the nozzle and the trigger point of the mag-probe:

      nozzle switch offset = mag probe height - nozzle height + switch offset

      The trigger point of the mag-probe cannot be probed directly. This is why the body of the switch is clicked on the endstop indstead of the trigger nob. This is why a small switch offset is used here to reflect the offset between the nob and the body of the switch while it is triggerd. This offset is fixed.

    5. Determine the height of the print surface by probing one point with the mag-probe on the bed (preferably the center or the \"bed_mesh:relative_reference_index\" of a configured/used mesh).

    6. Now, the final offset is calculated like this:

      probe offset = probed height - calculated nozzle switch offset

    7. Finally, the calculated offset is applied by using the SET_GCODE_OFFSET command (a previous offset is resetted before!).

    "},{"location":"Z_Calibration.html#interference","title":"Interference","text":"

    Temperature or humindity changes are not a big deal since the switch is not affected much by them and all values are probed in a small time period and only the releations to each other are used. The nozzle height in step 2 can be determined some time later and even many Celsius higher in the printer's chamber, compared to the homing in step 1. That is why the nozzle is probed again and can vary a little to the first homing position.

    "},{"location":"Z_Calibration.html#example-output","title":"Example Output","text":"

    The output of the calibration with all determined positions looks like this (the offset is the one which is applied as GCode offset):

    Z-CALIBRATION: ENDSTOP=-0.300 NOZZLE=-0.300 SWITCH=6.208 PROBE=7.013 --> OFFSET=-0.170\n

    The endstop value is the homed Z position which is always zero or the configure \"stepper_z:position_endstop\" setting - and in this case, it's even the same as the probed nozzle hight.

    "},{"location":"Z_Calibration.html#configuration","title":"Configuration","text":"

    To activate the extension, a [z_calibration] section is needed in the printer configuration. The configuration properties are described here in details.

    "},{"location":"Z_Calibration.html#switch-offset","title":"Switch Offset","text":"

    The \"z_calibration:switch_offset\" is the already mentioned offset from the switch body (which is the probed position) to the actual trigger point above it. A starting point for this value can be taken from the datasheet like from the Omron switch (D2F-5: 0.5mm and SSG-5H: 0.7mm). It's good to start with a little less depending on the squishiness you prefer for the first layer (it's about 0.45 for the D2F-5). So, with a smaller offset value, the nozzle is more away from the bed! The value cannot be negative.

    For example, the datasheet of the D2F-5:

    And the calculation of the offset base:

    offset base = OP (Operation Position) - switch body height\n     0.5 mm = 5.5 mm - 5 mm\n
    "},{"location":"Z_Calibration.html#attaching-and-detaching-the-probe","title":"Attaching and Detaching the Probe","text":"

    The attaching and detaching of the mag-probe can be done by creating a macro for the CALIBRATE_Z command and surround it by the appropriate commands:

    [gcode_macro CALIBRATE_Z]\ndescription: Automatically calibrates the nozzles offset to the print surface and dock/undock MagProbe\nrename_existing: CALIBRATE_Z_BASE\ngcode:\n  ATTACH_PROBE     # replace with the name of your specific attach macro\n  CALIBRATE_Z_BASE\n  DETACH_PROBE     # replace with the name of your specific detach macro\n

    It is also possible to use the start_gcode and end_gcode properties to call the attach and detach commands instead:

    [z_calibration]\n...\nstart_gcode: ATTACH_PROBE  # replace with the name of your specific attach macro\nend_gcode: DETACH_PROBE    # replace with the name of your specific detach macro\n

    If there are any space restrictions and it is not possible to probe the nozzle on the endstop with the probe attached, the before_switch_gcode property can be used to attach the probe instead of the start_gcode. Then, the probe is not attached until the probe is probed on the endstop:

    [z_calibration]\n...\nbefore_switch_gcode: ATTACH_PROBE  # replace with the name of your specific attach macro\nend_gcode: DETACH_PROBE            # replace with the name of your specific detach macro\n
    "},{"location":"Z_Calibration.html#bed-mesh","title":"Bed Mesh","text":"

    If a bed mesh is used, the coordinates for probing on the print bed must be exactly the relative reference index point of the mesh since this is the point zero of the mesh! But, it is possible to omit these properties completely and the relative reference index point of the mesh will be taken automatically (for this, the \"bed_mesh:relative_reference_index\" setting is required and there is no support for round bed/mesh so far)!

    "},{"location":"Z_Calibration.html#how-to-test-it","title":"How To Test It","text":"

    Do not bother too much about absolute values of the calculated offsets. These can vary a lot. Only the real position from the nozzle to the bed counts. To test this, the result of the calibration can be queried by GET_POSITION first:

    > CALIBRATE_Z\n> Z-CALIBRATION: ENDSTOP=-0.300 NOZZLE=-0.267 SWITCH=2.370 PROBE=3.093 --> OFFSET=-0.010000\n> GET_POSITION\n> mcu: stepper_x:17085 stepper_y:15625 stepper_z:-51454 stepper_z1:-51454 stepper_z2:-51454 stepper_z3:-51454\n> stepper: stepper_x:552.500000 stepper_y:-47.500000 stepper_z:10.022500 stepper_z1:10.022500 stepper_z2:10.022500 stepper_z3:10.022500\n> kinematic: X:252.500000 Y:300.000000 Z:10.022500\n> toolhead: X:252.500000 Y:300.000000 Z:10.021472 E:0.000000\n> gcode: X:252.500000 Y:300.000000 Z:9.990000 E:0.000000\n> gcode base: X:0.000000 Y:0.000000 Z:-0.010000 E:0.000000\n> gcode homing: X:0.000000 Y:0.000000 Z:-0.010000\n

    Here, the Z position in \"gcode base\" reflects the calibrated Z offset.

    Then, the offset can be tested by moving the nozzle slowly down to zero by moving it in multiple steps. It's good to do this by using GCodes, since the offset is applied as GCode-Offset. For example like this:

    > G90\n> G0 Z5\n> G0 Z3\n> G0 Z1\n> G0 Z0.5\n> G0 Z0.3\n> G0 Z0.1\n

    Check the distance to the print surface after every step. If there is a small discrepancy (which should be smaller than the offset base from the switch's datasheet), then adapt the \"z_calibration:switch_offset\" by that value. Decreasing the \"switch_offset\" will move the nozzle more away from the bed.

    And finally, if you have double checked, that the calibrated offset is correct, you can go for fine tuning the \"z_calibration:switch_offset\" by actually printing first layer tests. This needs to be done only once!

    "},{"location":"Z_Calibration.html#how-to-use-it","title":"How To Use It","text":""},{"location":"Z_Calibration.html#command-calibrate_z","title":"Command CALIBRATE_Z","text":"

    The calibration is started by using the CALIBRATE_Z command. There are no more parameters. A clean nozzle is needed for running this command.

    It does not matter when this calibration is called (and at what temperatures). But, it is importaint to call it just before starting a print when the printer is hot. So, it is good to add the CALIBRATE_Z command to the PRINT_START macro (which is called from the slicers start gCode). The sequence of this macro can look like this:

    1. Home all axes
    2. Heat up the bed and nozzle (and chamber)
    3. Get probe, make any bed leveling if needed (like QGL, Z-Tilt), park probe
    4. Purge and clean the nozzle
    5. Get probe, CALIBRATE_Z, park probe
    6. (Adjust Z offset if needed)
    7. Print intro line if used
    8. Start printing...

    :exclamation: And remove any old Z offset adjustments here (like SET_GCODE_OFFSET)

    For textured print surfaces, it might be necessary to go closer to the bed. To adjust the offset from the slicers start GCode, the following command can be added to the PRINT_START macro after calling the Z calibration:

        # Adjust the G-Code Z offset if needed\n    SET_GCODE_OFFSET Z_ADJUST={params.Z_ADJUST|default(0.0)|float} MOVE=1\n

    Then, a Z_ADJUST=0.0 can be added to the PRINT_START command in the Slicer. This does not reset the offset to this value but adjusts it by the given amount!

    NOTE: Do not home Z again after running the Z calibration or it needs to be executed again!

    "},{"location":"Z_Calibration.html#command-probe_z_accuracy","title":"Command PROBE_Z_ACCURACY","text":"

    There is also a PROBE_Z_ACCURACY command to test the accuracy of the Z endstop (like the PROBE_ACCURACY command of the probe):

    PROBE_Z_ACCURACY [PROBE_SPEED=<mm/s>] [LIFT_SPEED=<mm/s>] [SAMPLES=<count>] [SAMPLE_RETRACT_DIST=<mm>]\n

    It calculates the maximum, minimum, average, median and standard deviation of multiple probe samles on the endstop by taking the configured nozzle position on the endstop. The optional parameters default to their equivalent setting in the z_calibration config section.

    "},{"location":"Z_Calibration.html#ooze-mitigation","title":"Ooze Mitigation","text":"

    Ooze with any nozzle probe endstop can cause inaccuracies, as the filament will continue to leak or deform over the space of multiple probes. It is highly recommended to take some measures to prevent ooze buildup before the nozzle probe portion of this plugin.

    A slow long retraction, of as much as 15mm at print end, can reduce the potential for ooze. If you do this, consider adding a comparable extrude as the last command in your print start sequence to bring the plastic back to the tip. (Retracts longer than 5mm have been linked to clogs in many hotends, especially the Rapido. This may be best considered a last resort, depending on exact hardware and filament.)

    Heating the nozzle about a minute before scrubbing - using a purge bucket - will allow all the remaining plastic time to drain from the nozzle and be cleaned away by a simple wipe. If using a purge and scrubbing bucket, do not purge filament at this stage.

    An endstop switch that requires a stronger activation force, such as sexbolt with a spring, or unklicky z, can help squash any remaining ooze and improve consistency.

    Probing can be done with a hotend temperature below the full temperature for the print. If you print at 250, you can preheat the nozzle to 180, and run this script before finishing the heat up to full temperature. This may have varying effects depending on temperatures used.

    Also consider picking up your probe prior to your nozzle wipe, to allow this script to probe the nozzle immediately after cleaning it.

    "}]} \ No newline at end of file +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"index.html","title":"Welcome to the Kalico documentation!","text":"

    Kalico is a community-maintained fork of the Klipper 3D-Printer firmware. It combines the power of a general purpose computer with one or more micro-controllers. See the features document for more information on why you should use Kalico.

    To begin using Kalico start by installing it. If you consider migrating from Klipper to Kalico, please read our dedicated migration guide.

    Kalico is Free Software. Read the documentation or view the Kalico code on GitHub.

    We depend on the generous support from our sponsors.

    "},{"location":"API_Server.html","title":"API server","text":"

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

    "},{"location":"API_Server.html#enabling-the-api-socket","title":"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\n

    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 Kalico.

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

    "},{"location":"API_Server.html#request-format","title":"Request format","text":"

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

    <json_object_1><0x03><json_object_2><0x03>...\n

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

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

    This tool can read a series of JSON commands from stdin, send them to Kalico, 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 Kalico API server does not have a newline requirement.)

    "},{"location":"API_Server.html#api-protocol","title":"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 Kalico \"endpoint\".

    The request dictionary may contain a \"params\" parameter which must be of a dictionary type. The \"params\" provide additional parameter information to the Kalico \"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 Kalico will respond to the request with a response message containing that \"id\". If \"id\" is omitted (or set to a JSON \"null\" value) then Kalico 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\"}}

    Kalico 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.

    "},{"location":"API_Server.html#subscriptions","title":"Subscriptions","text":"

    Some Kalico \"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 Kalico 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, Kalico 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 ({}).

    "},{"location":"API_Server.html#available-endpoints","title":"Available \"endpoints\"","text":"

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

    "},{"location":"API_Server.html#info","title":"info","text":"

    The \"info\" endpoint is used to obtain system and version information from Kalico. It is also used to provide the client's version information to Kalico. 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 Kalico API server.

    "},{"location":"API_Server.html#emergency_stop","title":"emergency_stop","text":"

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

    "},{"location":"API_Server.html#register_remote_method","title":"register_remote_method","text":"

    This endpoint allows clients to register methods that can be called from Kalico. 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 KliKalicopper. 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]\ngcode:\n  {action_call_remote_method(\"paneldue_beep\", frequency=300, duration=1.0)}\n

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

    "},{"location":"API_Server.html#objectslist","title":"objects/list","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\"]}}

    "},{"location":"API_Server.html#objectsquery","title":"objects/query","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.

    "},{"location":"API_Server.html#objectssubscribe","title":"objects/subscribe","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}}

    "},{"location":"API_Server.html#gcodehelp","title":"gcode/help","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\", ...}}

    "},{"location":"API_Server.html#gcodescript","title":"gcode/script","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.

    "},{"location":"API_Server.html#gcoderestart","title":"gcode/restart","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.

    "},{"location":"API_Server.html#gcodefirmware_restart","title":"gcode/firmware_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.

    "},{"location":"API_Server.html#gcodesubscribe_output","title":"gcode/subscribe_output","text":"

    This endpoint is used to subscribe to G-Code terminal messages that are generated by Kalico. 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 Kalico's state.

    "},{"location":"API_Server.html#motion_reportdump_stepper","title":"motion_report/dump_stepper","text":"

    This endpoint is used to subscribe to Kalico'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 Kalico'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.

    "},{"location":"API_Server.html#motion_reportdump_trapq","title":"motion_report/dump_trapq","text":"

    This endpoint is used to subscribe to Kalico's internal \"trapezoid motion queue\". Obtaining these low-level motion updates may be useful for diagnostic and debugging purposes. Using this endpoint may increase Kalico'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.

    "},{"location":"API_Server.html#adxl345dump_adxl345","title":"adxl345/dump_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 Kalico'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.

    "},{"location":"API_Server.html#angledump_angle","title":"angle/dump_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 Kalico'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.

    "},{"location":"API_Server.html#hx71xdump_hx71x","title":"hx71x/dump_hx71x","text":"

    This endpoint is used to subscribe to raw HX711 and HX717 ADC data. Obtaining these low-level ADC updates may be useful for diagnostic and debugging purposes. Using this endpoint may increase Kalico's system load.

    A request may look like: {\"id\": 123, \"method\":\"hx71x/dump_hx71x\", \"params\": {\"sensor\": \"load_cell\", \"response_template\": {}}} and might return: {\"id\": 123,\"result\":{\"header\":[\"time\",\"counts\",\"value\"]}} and might later produce asynchronous messages such as: {\"params\":{\"data\":[[3292.432935, 562534, 0.067059278], [3292.4394937, 5625322, 0.670590639]]}}

    "},{"location":"API_Server.html#ads1220dump_ads1220","title":"ads1220/dump_ads1220","text":"

    This endpoint is used to subscribe to raw ADS1220 ADC data. Obtaining these low-level ADC updates may be useful for diagnostic and debugging purposes. Using this endpoint may increase Kalico's system load.

    A request may look like: {\"id\": 123, \"method\":\"ads1220/dump_ads1220\", \"params\": {\"sensor\": \"load_cell\", \"response_template\": {}}} and might return: {\"id\": 123,\"result\":{\"header\":[\"time\",\"counts\",\"value\"]}} and might later produce asynchronous messages such as: {\"params\":{\"data\":[[3292.432935, 562534, 0.067059278], [3292.4394937, 5625322, 0.670590639]]}}

    "},{"location":"API_Server.html#pause_resumecancel","title":"pause_resume/cancel","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.

    "},{"location":"API_Server.html#pause_resumepause","title":"pause_resume/pause","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.

    "},{"location":"API_Server.html#pause_resumeresume","title":"pause_resume/resume","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.

    "},{"location":"API_Server.html#query_endstopsstatus","title":"query_endstops/status","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.

    "},{"location":"Axis_Twist_Compensation.html","title":"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, as the calibration could be affected by issues with probe accuracy, bed flatness, Z axis alignment, etc.

    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.

    "},{"location":"Axis_Twist_Compensation.html#overview-of-compensation-usage","title":"Overview of compensation usage","text":"

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

    "},{"location":"Axis_Twist_Compensation.html#basic-usage-x-axis-calibration","title":"Basic Usage: X-Axis Calibration","text":"
    1. After setting up the [axis_twist_compensation] module, run:
    AXIS_TWIST_COMPENSATION_CALIBRATE\n

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

    1. Adjust Your Z Offset: After completing the calibration, be sure to [adjust your Z offset] (Probe_Calibrate.md#calibrating-probe-z-offset).

    2. Perform Bed Leveling Operations: Use probe-based operations as needed, such as: - Screws Tilt Adjust - Z Tilt Adjust

    3. Finalize the Setup: - Home all axes, and perform a Bed Mesh if necessary. - Run a test print, followed by any fine-tuning if needed.

    "},{"location":"Axis_Twist_Compensation.html#for-y-axis-calibration","title":"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\n

    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.

    "},{"location":"Axis_Twist_Compensation.html#axis_twist_compensation-setup-and-commands","title":"[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

    "},{"location":"BLTouch.html","title":"BL-Touch","text":""},{"location":"BLTouch.html#connecting-bl-touch","title":"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]\nsensor_pin: ^P1.24\ncontrol_pin: P1.26\n

    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]\nhome_xy_position: 100, 100 # Change coordinates to the center of your print bed\nspeed: 50\nz_hop: 10                 # Move up 10mm\nz_hop_speed: 5\n

    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.

    "},{"location":"BLTouch.html#initial-tests","title":"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.

    "},{"location":"BLTouch.html#bl-touch-gone-bad","title":"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.

    "},{"location":"BLTouch.html#bl-touch-clones","title":"BL-Touch \"clones\"","text":"

    Many BL-Touch \"clone\" devices work correctly with Kalico 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 Kalico 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 Kalico's internal sensor verification test. On these devices, attempts to home or probe can result in Kalico 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 Kalico config file.

    A rare number of old \"clone\" devices are unable to report when they have successfully raised their probe. On these devices Kalico 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 Kalico config file.

    "},{"location":"BLTouch.html#bl-touch-v3","title":"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. Kalico 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).

    "},{"location":"BLTouch.html#multi-probing-without-stowing","title":"Multi-probing without stowing","text":"

    By default, Kalico 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. Kalico 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 Kalico 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).

    "},{"location":"BLTouch.html#calibrating-the-bl-touch-offsets","title":"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.

    "},{"location":"BLTouch.html#bl-touch-output-mode","title":"BL-Touch output mode","text":""},{"location":"Beaglebone.html","title":"Beaglebone","text":"

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

    "},{"location":"Beaglebone.html#building-an-os-image","title":"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 Kalico you need to free-up additional space. there are 3 options to do that:

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

    To remove some BeagleBone \"Demo\" resources execute these commands

    sudo apt remove bb-node-red-installer\nsudo apt remove bb-code-server\n

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

    sudo growpart /dev/mmcblk0 1\nsudo resize2fs /dev/mmcblk0p1\n

    Install Kalico by running the following commands:

    git clone https://github.com/KalicoCrew/kalico klipper\n./klipper/scripts/install-beaglebone.sh\n

    After installing Kalico 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 Kalico 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 Kalico 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 Kalico + 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.

    "},{"location":"Beaglebone.html#installing-octoprint","title":"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\ncd OctoPrint/\nvirtualenv venv\n./venv/bin/python setup.py install\n

    And setup OctoPrint to start at bootup:

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

    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\n

    Then start the Octoprint service:

    sudo systemctl start octoprint\n

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

    "},{"location":"Beaglebone.html#building-the-beaglebone-pru-micro-controller-code-pru-firmware","title":"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\n

    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]\nUBOOT: Booted Device-Tree:[am335x-boneblack-uboot-univ.dts]\nUBOOT: Loaded Overlay:[BB-ADC-00A0.bb.org-overlays]\nUBOOT: Loaded Overlay:[BB-BONE-eMMC1-01-00A0.bb.org-overlays]\nkernel:[5.10.168-ti-r71]\n/boot/uEnv.txt Settings:\nuboot_overlay_options:[enable_uboot_overlays=1]\nuboot_overlay_options:[disable_uboot_overlay_video=0]\nuboot_overlay_options:[disable_uboot_overlay_audio=1]\nuboot_overlay_options:[disable_uboot_overlay_wireless=1]\nuboot_overlay_options:[enable_uboot_cape_universal=1]\npkg:[bb-cape-overlays]:[4.14.20210821.0-0~bullseye+20210821]\npkg:[bb-customizations]:[1.20230720.1-0~bullseye+20230720]\npkg:[bb-usb-gadgets]:[1.20230414.0-0~bullseye+20230414]\npkg:[bb-wl18xx-firmware]:[1.20230414.0-0~bullseye+20230414]\n.............\n.............\n

    To compile the Kalico 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/\nmake menuconfig\n

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

    sudo service klipper stop\nmake flash\nsudo service klipper start\n

    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\n

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

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

    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.

    "},{"location":"Beaglebone.html#building-and-installing-linux-host-micro-controller-code","title":"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\n

    Then install this micro-controller code as well:

    sudo service klipper stop\nmake flash\nsudo service klipper start\n

    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.

    "},{"location":"Beaglebone.html#remaining-configuration","title":"Remaining configuration","text":"

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

    "},{"location":"Beaglebone.html#printing-on-the-beaglebone","title":"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 Kalico and disable any DEBUG or VERBOSE logging options if you did enable them.

    "},{"location":"Beaglebone.html#avr-micro-controller-code-build","title":"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\nsudo apt-get install avrdude gcc-avr binutils-avr avr-libc\n

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

    sudo apt-get remove avrdude gcc-avr binutils-avr avr-libc\nsudo apt-get install gcc-pru\n
    "},{"location":"Beaglebone.html#hardware-pin-designation","title":"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\n

    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\n

    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.

    "},{"location":"Beaglebone.html#enabling-hardware-spi","title":"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\n

    uncomment variable

    disable_uboot_overlay_audio=1\n

    next uncomment variable and define it this way

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

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

    ls /dev/spidev1.*\n

    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.

    "},{"location":"Beaglebone.html#enabling-hardware-i2c","title":"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

    "},{"location":"Beaglebone.html#enabling-hardware-uartserialcan","title":"Enabling hardware UART(Serial)/CAN","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

    "},{"location":"Bed_Level.html","title":"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 Kalico.

    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.

    "},{"location":"Bed_Level.html#choose-the-appropriate-calibration-mechanism","title":"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.

    "},{"location":"Bed_Level.html#the-paper-test","title":"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!

    Kalico 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.\nRecv: // Finish with ACCEPT or ABORT command.\nRecv: // Z position: ?????? --> 5.000 <-- ??????\n

    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\n

    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\n

    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\n

    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.

    "},{"location":"Bed_Level.html#determining-thermal-expansion","title":"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 layer 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.

    "},{"location":"Bed_Mesh.html","title":"Bed Mesh","text":"

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

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

    "},{"location":"Bed_Mesh.html#basic-configuration","title":"Basic Configuration","text":""},{"location":"Bed_Mesh.html#rectangular-beds","title":"Rectangular Beds","text":"

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

    [bed_mesh]\nspeed: 120\nhorizontal_move_z: 5\nmesh_min: 35, 6\nmesh_max: 240, 198\nprobe_count: 5, 3\n

    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).

    "},{"location":"Bed_Mesh.html#round-beds","title":"Round beds","text":"

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

    [bed_mesh]\nspeed: 120\nhorizontal_move_z: 5\nmesh_radius: 75\nmesh_origin: 0, 0\nround_probe_count: 5\n

    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.

    "},{"location":"Bed_Mesh.html#advanced-configuration","title":"Advanced Configuration","text":"

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

    "},{"location":"Bed_Mesh.html#mesh-interpolation","title":"Mesh Interpolation","text":"

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

    [bed_mesh]\nspeed: 120\nhorizontal_move_z: 5\nmesh_min: 35, 6\nmesh_max: 240, 198\nprobe_count: 5, 3\nmesh_pps: 2, 3\nalgorithm: bicubic\nbicubic_tension: 0.2\n

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

    "},{"location":"Bed_Mesh.html#move-splitting","title":"Move Splitting","text":"

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

    [bed_mesh]\nspeed: 120\nhorizontal_move_z: 5\nmesh_min: 35, 6\nmesh_max: 240, 198\nprobe_count: 5, 3\nmove_check_distance: 5\nsplit_delta_z: .025\n

    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.

    "},{"location":"Bed_Mesh.html#mesh-fade","title":"Mesh Fade","text":"

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

    [bed_mesh]\nspeed: 120\nhorizontal_move_z: 5\nmesh_min: 35, 6\nmesh_max: 240, 198\nprobe_count: 5, 3\nfade_start: 1\nfade_end: 10\nfade_target: 0\n
    "},{"location":"Bed_Mesh.html#configuring-the-zero-reference-position","title":"Configuring the zero reference position","text":"

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

    [bed_mesh]\nspeed: 120\nhorizontal_move_z: 5\nmesh_min: 35, 6\nmesh_max: 240, 198\nzero_reference_position: 125, 110\nprobe_count: 5, 3\n
    "},{"location":"Bed_Mesh.html#the-deprecated-relative_reference_index","title":"The deprecated relative_reference_index","text":"

    Existing configurations using the relative_reference_index option must be updated to use the zero_reference_position. The response to the BED_MESH_OUTPUT PGP=1 gcode command will include the (X, Y) coordinate associated with the index; this position may be used as the value for the zero_reference_position. The output will look similar to the following:

    // bed_mesh: generated points\n// Index | Tool Adjusted | Probe\n// 0 | (1.0, 1.0) | (24.0, 6.0)\n// 1 | (36.7, 1.0) | (59.7, 6.0)\n// 2 | (72.3, 1.0) | (95.3, 6.0)\n// 3 | (108.0, 1.0) | (131.0, 6.0)\n... (additional generated points)\n// bed_mesh: relative_reference_index 24 is (131.5, 108.0)\n

    Note: The above output is also printed in klippy.log during initialization.

    Using the example above we see that the relative_reference_index is printed along with its coordinate. Thus the zero_reference_position is 131.5, 108.

    "},{"location":"Bed_Mesh.html#faulty-regions","title":"Faulty Regions","text":"

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

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

    [bed_mesh]\nspeed: 120\nhorizontal_move_z: 5\nmesh_min: 35, 6\nmesh_max: 240, 198\nprobe_count: 5, 3\nfaulty_region_1_min: 130.0, 0.0\nfaulty_region_1_max: 145.0, 40.0\nfaulty_region_2_min: 225.0, 0.0\nfaulty_region_2_max: 250.0, 25.0\nfaulty_region_3_min: 165.0, 95.0\nfaulty_region_3_max: 205.0, 110.0\nfaulty_region_4_min: 30.0, 170.0\nfaulty_region_4_max: 45.0, 210.0\n

    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.

    "},{"location":"Bed_Mesh.html#adaptive-meshes","title":"Adaptive Meshes","text":"

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

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

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

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

    [bed_mesh]\nspeed: 120\nhorizontal_move_z: 5\nmesh_min: 35, 6\nmesh_max: 240, 198\nprobe_count: 5, 3\nadaptive_margin: 5\n

    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.

    "},{"location":"Bed_Mesh.html#bed-mesh-gcodes","title":"Bed Mesh Gcodes","text":""},{"location":"Bed_Mesh.html#calibration","title":"Calibration","text":"

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

    Initiates the probing procedure for Bed Mesh Calibration.

    The mesh will be saved into a profile specified by the PROFILE parameter, or default if unspecified. If METHOD=manual is selected then manual probing will occur. When switching between automatic and manual probing the generated mesh points will automatically be adjusted.

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

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

    "},{"location":"Bed_Mesh.html#profiles","title":"Profiles","text":"

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

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

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

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

    BED_MESH_PROFILE REMOVE=default

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

    "},{"location":"Bed_Mesh.html#loading-the-default-profile","title":"Loading the default profile","text":"

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

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

    [delayed_gcode bed_mesh_init]\ninitial_duration: .01\ngcode:\n  BED_MESH_PROFILE LOAD=default\n
    "},{"location":"Bed_Mesh.html#output","title":"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\n// Index | Tool Adjusted | Probe\n// 0 | (11.0, 1.0) | (35.0, 6.0)\n// 1 | (62.2, 1.0) | (86.2, 6.0)\n// 2 | (113.5, 1.0) | (137.5, 6.0)\n// 3 | (164.8, 1.0) | (188.8, 6.0)\n// 4 | (216.0, 1.0) | (240.0, 6.0)\n// 5 | (216.0, 97.0) | (240.0, 102.0)\n// 6 | (164.8, 97.0) | (188.8, 102.0)\n// 7 | (113.5, 97.0) | (137.5, 102.0)\n// 8 | (62.2, 97.0) | (86.2, 102.0)\n// 9 | (11.0, 97.0) | (35.0, 102.0)\n// 10 | (11.0, 193.0) | (35.0, 198.0)\n// 11 | (62.2, 193.0) | (86.2, 198.0)\n// 12 | (113.5, 193.0) | (137.5, 198.0)\n// 13 | (164.8, 193.0) | (188.8, 198.0)\n// 14 | (216.0, 193.0) | (240.0, 198.0)\n

    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.

    "},{"location":"Bed_Mesh.html#clear-mesh-state","title":"Clear Mesh State","text":"

    BED_MESH_CLEAR

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

    "},{"location":"Bed_Mesh.html#apply-xy-offsets","title":"Apply X/Y offsets","text":"

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

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

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

    "},{"location":"Benchmarks.html","title":"Benchmarks","text":"

    This document describes Kalico benchmarks.

    "},{"location":"Benchmarks.html#micro-controller-benchmarks","title":"Micro-controller Benchmarks","text":"

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

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

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

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

    "},{"location":"Benchmarks.html#step-rate-benchmark-test","title":"Step rate benchmark test","text":"

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

    SET start_clock {clock+freq}\nSET ticks 1000\n\nreset_step_clock oid=0 clock={start_clock}\nset_next_step_dir oid=0 dir=0\nqueue_step oid=0 interval={ticks} count=60000 add=0\nset_next_step_dir oid=0 dir=1\nqueue_step oid=0 interval=3000 count=1 add=0\n\nreset_step_clock oid=1 clock={start_clock}\nset_next_step_dir oid=1 dir=0\nqueue_step oid=1 interval={ticks} count=60000 add=0\nset_next_step_dir oid=1 dir=1\nqueue_step oid=1 interval=3000 count=1 add=0\n\nreset_step_clock oid=2 clock={start_clock}\nset_next_step_dir oid=2 dir=0\nqueue_step oid=2 interval={ticks} count=60000 add=0\nset_next_step_dir oid=2 dir=1\nqueue_step oid=2 interval=3000 count=1 add=0\n

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

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

    clear_shutdown\n

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

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

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

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

    "},{"location":"Benchmarks.html#avr-step-rate-benchmark","title":"AVR step rate benchmark","text":"

    The following configuration sequence is used on AVR chips:

    allocate_oids count=3\nconfig_stepper oid=0 step_pin=PA5 dir_pin=PA4 invert_step=0 step_pulse_ticks=32\nconfig_stepper oid=1 step_pin=PA3 dir_pin=PA2 invert_step=0 step_pulse_ticks=32\nconfig_stepper oid=2 step_pin=PC7 dir_pin=PC6 invert_step=0 step_pulse_ticks=32\nfinalize_config crc=0\n

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

    avr ticks 1 stepper 102 3 stepper 486"},{"location":"Benchmarks.html#arduino-due-step-rate-benchmark","title":"Arduino Due step rate benchmark","text":"

    The following configuration sequence is used on the Due:

    allocate_oids count=3\nconfig_stepper oid=0 step_pin=PB27 dir_pin=PA21 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=1 step_pin=PB26 dir_pin=PC30 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=2 step_pin=PA21 dir_pin=PC30 invert_step=-1 step_pulse_ticks=0\nfinalize_config crc=0\n

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

    sam3x8e ticks 1 stepper 66 3 stepper 257"},{"location":"Benchmarks.html#duet-maestro-step-rate-benchmark","title":"Duet Maestro step rate benchmark","text":"

    The following configuration sequence is used on the Duet Maestro:

    allocate_oids count=3\nconfig_stepper oid=0 step_pin=PC26 dir_pin=PC18 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=1 step_pin=PC26 dir_pin=PA8 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=2 step_pin=PC26 dir_pin=PB4 invert_step=-1 step_pulse_ticks=0\nfinalize_config crc=0\n

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

    sam4s8c ticks 1 stepper 71 3 stepper 260"},{"location":"Benchmarks.html#duet-wifi-step-rate-benchmark","title":"Duet Wifi step rate benchmark","text":"

    The following configuration sequence is used on the Duet Wifi:

    allocate_oids count=3\nconfig_stepper oid=0 step_pin=PD6 dir_pin=PD11 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=1 step_pin=PD7 dir_pin=PD12 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=2 step_pin=PD8 dir_pin=PD13 invert_step=-1 step_pulse_ticks=0\nfinalize_config crc=0\n

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

    sam4e8e ticks 1 stepper 48 3 stepper 215"},{"location":"Benchmarks.html#beaglebone-pru-step-rate-benchmark","title":"Beaglebone PRU step rate benchmark","text":"

    The following configuration sequence is used on the PRU:

    allocate_oids count=3\nconfig_stepper oid=0 step_pin=gpio0_23 dir_pin=gpio1_12 invert_step=0 step_pulse_ticks=20\nconfig_stepper oid=1 step_pin=gpio1_15 dir_pin=gpio0_26 invert_step=0 step_pulse_ticks=20\nconfig_stepper oid=2 step_pin=gpio0_22 dir_pin=gpio2_1 invert_step=0 step_pulse_ticks=20\nfinalize_config crc=0\n

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

    pru ticks 1 stepper 231 3 stepper 847"},{"location":"Benchmarks.html#stm32f042-step-rate-benchmark","title":"STM32F042 step rate benchmark","text":"

    The following configuration sequence is used on the STM32F042:

    allocate_oids count=3\nconfig_stepper oid=0 step_pin=PA1 dir_pin=PA2 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=1 step_pin=PA3 dir_pin=PA2 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=2 step_pin=PB8 dir_pin=PA2 invert_step=-1 step_pulse_ticks=0\nfinalize_config crc=0\n

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

    stm32f042 ticks 1 stepper 59 3 stepper 249"},{"location":"Benchmarks.html#stm32f103-step-rate-benchmark","title":"STM32F103 step rate benchmark","text":"

    The following configuration sequence is used on the STM32F103:

    allocate_oids count=3\nconfig_stepper oid=0 step_pin=PC13 dir_pin=PB5 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=1 step_pin=PB3 dir_pin=PB6 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=2 step_pin=PA4 dir_pin=PB7 invert_step=-1 step_pulse_ticks=0\nfinalize_config crc=0\n

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

    stm32f103 ticks 1 stepper 61 3 stepper 264"},{"location":"Benchmarks.html#stm32f4-step-rate-benchmark","title":"STM32F4 step rate benchmark","text":"

    The following configuration sequence is used on the STM32F4:

    allocate_oids count=3\nconfig_stepper oid=0 step_pin=PA5 dir_pin=PB5 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=1 step_pin=PB2 dir_pin=PB6 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=2 step_pin=PB3 dir_pin=PB7 invert_step=-1 step_pulse_ticks=0\nfinalize_config crc=0\n

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

    stm32f446 ticks 1 stepper 46 3 stepper 205 stm32f407 ticks 1 stepper 46 3 stepper 205"},{"location":"Benchmarks.html#stm32h7-step-rate-benchmark","title":"STM32H7 step rate benchmark","text":"

    The following configuration sequence is used on a STM32H743VIT6:

    allocate_oids count=3\nconfig_stepper oid=0 step_pin=PD4 dir_pin=PD3 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=1 step_pin=PA15 dir_pin=PA8 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=2 step_pin=PE2 dir_pin=PE3 invert_step=-1 step_pulse_ticks=0\nfinalize_config crc=0\n

    The test was last run on commit 00191b5c with gcc version arm-none-eabi-gcc (15:8-2019-q3-1+b1) 8.3.1 20190703 (release) [gcc-8-branch revision 273027].

    stm32h7 ticks 1 stepper 44 3 stepper 198"},{"location":"Benchmarks.html#stm32g0b1-step-rate-benchmark","title":"STM32G0B1 step rate benchmark","text":"

    The following configuration sequence is used on the STM32G0B1:

    allocate_oids count=3\nconfig_stepper oid=0 step_pin=PB13 dir_pin=PB12 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=1 step_pin=PB10 dir_pin=PB2 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=2 step_pin=PB0 dir_pin=PC5 invert_step=-1 step_pulse_ticks=0\nfinalize_config crc=0\n

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

    stm32g0b1 ticks 1 stepper 58 3 stepper 243"},{"location":"Benchmarks.html#lpc176x-step-rate-benchmark","title":"LPC176x step rate benchmark","text":"

    The following configuration sequence is used on the LPC176x:

    allocate_oids count=3\nconfig_stepper oid=0 step_pin=P1.20 dir_pin=P1.18 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=1 step_pin=P1.21 dir_pin=P1.18 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=2 step_pin=P1.23 dir_pin=P1.18 invert_step=-1 step_pulse_ticks=0\nfinalize_config crc=0\n

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

    lpc1768 ticks 1 stepper 52 3 stepper 222 lpc1769 ticks 1 stepper 51 3 stepper 222"},{"location":"Benchmarks.html#samd21-step-rate-benchmark","title":"SAMD21 step rate benchmark","text":"

    The following configuration sequence is used on the SAMD21:

    allocate_oids count=3\nconfig_stepper oid=0 step_pin=PA27 dir_pin=PA20 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=1 step_pin=PB3 dir_pin=PA21 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=2 step_pin=PA17 dir_pin=PA21 invert_step=-1 step_pulse_ticks=0\nfinalize_config crc=0\n

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

    samd21 ticks 1 stepper 70 3 stepper 306"},{"location":"Benchmarks.html#samd51-step-rate-benchmark","title":"SAMD51 step rate benchmark","text":"

    The following configuration sequence is used on the SAMD51:

    allocate_oids count=3\nconfig_stepper oid=0 step_pin=PA22 dir_pin=PA20 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=1 step_pin=PA22 dir_pin=PA21 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=2 step_pin=PA22 dir_pin=PA19 invert_step=-1 step_pulse_ticks=0\nfinalize_config crc=0\n

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

    samd51 ticks 1 stepper 39 3 stepper 191 1 stepper (200Mhz) 39 3 stepper (200Mhz) 181"},{"location":"Benchmarks.html#same70-step-rate-benchmark","title":"SAME70 step rate benchmark","text":"

    The following configuration sequence is used on the SAME70:

    allocate_oids count=3\nconfig_stepper oid=0 step_pin=PC18 dir_pin=PB5 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=1 step_pin=PC16 dir_pin=PD10 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=2 step_pin=PC28 dir_pin=PA4 invert_step=-1 step_pulse_ticks=0\nfinalize_config crc=0\n

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

    same70 ticks 1 stepper 45 3 stepper 190"},{"location":"Benchmarks.html#ar100-step-rate-benchmark","title":"AR100 step rate benchmark","text":"

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

    allocate_oids count=3\nconfig_stepper oid=0 step_pin=PL10 dir_pin=PE14 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=1 step_pin=PL11 dir_pin=PE15 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=2 step_pin=PL12 dir_pin=PE16 invert_step=-1 step_pulse_ticks=0\nfinalize_config crc=0\n

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

    AR100 R_PIO ticks 1 stepper 85 3 stepper 359"},{"location":"Benchmarks.html#rpxxxx-step-rate-benchmark","title":"RPxxxx step rate benchmark","text":"

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

    allocate_oids count=3\nconfig_stepper oid=0 step_pin=gpio25 dir_pin=gpio3 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=1 step_pin=gpio26 dir_pin=gpio4 invert_step=-1 step_pulse_ticks=0\nconfig_stepper oid=2 step_pin=gpio27 dir_pin=gpio5 invert_step=-1 step_pulse_ticks=0\nfinalize_config crc=0\n

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

    rp2040 (*) ticks 1 stepper 5 3 stepper 22 rp2350 ticks 1 stepper 36 3 stepper 169

    (*) Note that the reported rp2040 ticks are relative to a 12Mhz scheduling timer and do not correspond to its 125Mhz internal ARM processing rate. It is expected that 5 scheduling ticks corresponds to ~47 ARM core cycles and 22 scheduling ticks corresponds to ~224 ARM core cycles.

    "},{"location":"Benchmarks.html#linux-mcu-step-rate-benchmark","title":"Linux MCU step rate benchmark","text":"

    The following configuration sequence is used on a Raspberry Pi:

    allocate_oids count=3\nconfig_stepper oid=0 step_pin=gpio2 dir_pin=gpio3 invert_step=0 step_pulse_ticks=5\nconfig_stepper oid=1 step_pin=gpio4 dir_pin=gpio5 invert_step=0 step_pulse_ticks=5\nconfig_stepper oid=2 step_pin=gpio6 dir_pin=gpio17 invert_step=0 step_pulse_ticks=5\nfinalize_config crc=0\n

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

    Linux (RPi3) ticks 1 stepper 160 3 stepper 380"},{"location":"Benchmarks.html#command-dispatch-benchmark","title":"Command dispatch benchmark","text":"

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

    DELAY {clock + 2*freq} get_uptime\nFLOOD 100000 0.0 debug_nop\nget_uptime\n

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

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

    MCU Rate Build Build compiler stm32f042 (CAN) 18K c105adc8 arm-none-eabi-gcc (GNU Tools 7-2018-q3-update) 7.3.1 atmega2560 (serial) 23K b161a69e avr-gcc (GCC) 4.8.1 sam3x8e (serial) 23K b161a69e arm-none-eabi-gcc (Fedora 7.1.0-5.fc27) 7.1.0 at90usb1286 (USB) 75K 01d2183f avr-gcc (GCC) 5.4.0 ar100 (serial) 138K 08d037c6 or1k-linux-musl-gcc 9.3.0 samd21 (USB) 223K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 pru (shared memory) 260K c5968a08 pru-gcc (GCC) 8.0.0 20170530 (experimental) stm32f103 (USB) 355K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 sam3x8e (USB) 418K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 lpc1768 (USB) 534K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 lpc1769 (USB) 628K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 sam4s8c (USB) 650K 8d4a5c16 arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 samd51 (USB) 864K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 stm32f446 (USB) 870K 01d2183f arm-none-eabi-gcc (Fedora 7.4.0-1.fc30) 7.4.0 rp2040 (USB) 885K f6718291 arm-none-eabi-gcc (Fedora 14.1.0-1.fc40) 14.1.0 rp2350 (USB) 885K f6718291 arm-none-eabi-gcc (Fedora 14.1.0-1.fc40) 14.1.0"},{"location":"Benchmarks.html#host-benchmarks","title":"Host Benchmarks","text":"

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

    time ~/klippy-env/bin/python ./klippy/klippy.py config/example-cartesian.cfg -i something_complex.gcode -o /dev/null -d out/klipper.dict\n
    "},{"location":"Bleeding_Edge.html","title":"Bleeding Edge Features Documentation","text":"

    The following are experimental features found in the bleeding edge branch of Kalico and should be used at your own caution. The support for these features is limited and your experience may vary! If you do use the features and find them useful, discover bugs, or have improvements please use the Kalico Discord server to discuss your findings.

    Refer to the Bleeding Edge Configuration Reference for details on printer configurations for these features.

    "},{"location":"Bleeding_Edge.html#high-precision-stepping-and-new-stepcompress-protocol","title":"High precision stepping and new stepcompress protocol","text":"

    Reference Discussion of this feature: https://klipper.discourse.group/t/improved-stepcompress-implementation/3203

    "},{"location":"Bleeding_Edge.html#overview","title":"Overview","text":"

    The new stepcompress protocol and precision stepping feature is a proposed improvement in the control and accuracy of stepper motor movements. This feature enhances the step compression algorithm, crucial for transmitting stepper commands accurately.

    "},{"location":"Bleeding_Edge.html#existing-step-compression-mechanism","title":"Existing Step Compression Mechanism","text":""},{"location":"Bleeding_Edge.html#limitations-of-current-method","title":"Limitations of Current Method","text":""},{"location":"Bleeding_Edge.html#improved-step-compression-schema","title":"Improved Step Compression Schema","text":""},{"location":"Bleeding_Edge.html#advantages-of-new-method","title":"Advantages of New Method","text":""},{"location":"Bleeding_Edge.html#computational-considerations","title":"Computational Considerations","text":""},{"location":"Bleeding_Edge.html#real-world-testing-and-results","title":"Real-World Testing and Results","text":""},{"location":"Bleeding_Edge.html#smooth-input-shapers","title":"Smooth Input Shapers","text":"

    Reference Discussion of this feature: https://klipper.discourse.group/t/scurve-pa-branch/7621/3

    "},{"location":"Bleeding_Edge.html#overview_1","title":"Overview","text":"

    The Smooth Input Shaper feature employs polynomial smooth functions designed to cancel vibrations at certain frequencies, similar to regular input shapers. The feature aims to provide shapers that have somewhat better overall characteristics.

    "},{"location":"Bleeding_Edge.html#key-features","title":"Key Features","text":" "},{"location":"Bleeding_Edge.html#smooth-shapers-avaliable","title":"Smooth shapers avaliable","text":""},{"location":"Bleeding_Edge.html#custom-smooth-shapers","title":"Custom smooth shapers","text":""},{"location":"Bleeding_Edge.html#hardware-requirements","title":"Hardware Requirements","text":" "},{"location":"Bleeding_Edge.html#configuration-and-usage","title":"Configuration and Usage","text":" "},{"location":"Bleeding_Edge.html#extruder-pa-synchronization-with-input-shaping","title":"Extruder PA Synchronization with Input Shaping","text":"

    Reference Discussion of this feature: https://klipper.discourse.group/t/extruder-pa-synchronization-with-input-shaping/3843

    "},{"location":"Bleeding_Edge.html#overview_2","title":"Overview","text":"

    The Extruder PA Synchronization with Input Shaping feature synchronizes filament extrusion (Pressure Advance - PA) with the toolhead's motion. This synchronization aims to reduce artifacts by compensating for changes in toolhead motion, especially in scenarios where input shaping is employed to minimize vibration and ringing.

    "},{"location":"Bleeding_Edge.html#background","title":"Background","text":"

    Input shaping is a technique used to alter toolhead motion to reduce vibrations. While Klipper's existing pressure advance algorithm helps in synchronizing filament extrusion with toolhead motion, it is not fully aligned with the input shaping alterations. This misalignment can be particularly noticeable in scenarios where X and Y axes have different resonance frequencies, or the PA smooth time significantly deviates from the input shaper duration.

    "},{"location":"Bleeding_Edge.html#implementation","title":"Implementation","text":"

    The feature involves:

    1. Calculating toolhead motion across X, Y, and Z axes.
    2. Applying input shaping to the X and Y axes.
    3. Using linearization to project this motion onto the E (extruder) axis.

    If the input shaper is consistent for both X and Y axes, the synchronization is precise for XY motion. In other cases, the feature provides a linear approximation over X/Y deviations, which is an improvement over the previous state.

    "},{"location":"Bleeding_Edge.html#observations-and-improvements","title":"Observations and Improvements","text":""},{"location":"Bleeding_Edge.html#hardware-requirements_1","title":"Hardware Requirements","text":""},{"location":"Bleeding_Edge.html#testing-and-results","title":"Testing and Results","text":"

    The feature has been tested over several months, showing modest improvements in the quality of real prints. It is particularly effective for direct drive extruders with short filament paths. The impact on bowden extruders is expected to be neutral.

    "},{"location":"Bleeding_Edge.html#usage-recommendations","title":"Usage Recommendations","text":""},{"location":"Bleeding_Edge.html#ringing-tower-test-print","title":"Ringing tower test print","text":"

    Reference Discussion of this feature: https://klipper.discourse.group/t/alternative-ringing-tower-print-for-input-shaping-calibration/4517

    "},{"location":"Bleeding_Edge.html#overview_3","title":"Overview","text":"

    The new test methodology for input shaper calibration addresses a critical limitation of the existing ringing_tower test. This improvement is centered around isolating the vibrations on each axis during the calibration process, thereby providing more accurate and reliable results.

    "},{"location":"Bleeding_Edge.html#limitation-of-current-ringing-tower-test","title":"Limitation of Current Ringing Tower Test","text":""},{"location":"Bleeding_Edge.html#new-test-methodology-concept","title":"New Test Methodology Concept","text":""},{"location":"Bleeding_Edge.html#advantages","title":"Advantages","text":""},{"location":"Bleeding_Edge.html#considerations","title":"Considerations","text":""},{"location":"Bleeding_Edge.html#sample-run-command","title":"Sample run command:","text":"

    Note, it is not reccomended to run the command directly without the helper macros configured.

    RUN_RINGING_TEST NOZZLE=0.4 TARGET_TEMP=210 BED_TEMP=55.

    "},{"location":"Bleeding_Edge.html#sample-helper-macros","title":"Sample helper macros","text":"

    This sample Gcode can be included in printer.cfg or s seperate *.cfg file and #included in printer.cfg. Specific start/end printing Gcode for the printer should be added to ensure it aligned with the standard printing process such as the appropriate heating, homing and bed meshing sequences and additional functions such as enabling fan, additional purge lines, pressure advance setup, or adjusting the flow rate.

    [ringing_test]\n\n[delayed_gcode start_ringing_test]\n\ngcode:\n    {% set vars = printer[\"gcode_macro RUN_RINGING_TEST\"] %}\n    # Add your start GCode here, for example:\n    # G28\n    # M190 S{vars.bed_temp}\n    # M109 S{vars.hotend_temp}\n    # M106 S255\n    {% set flow_percent = vars.flow_rate|float * 100.0 %}\n    {% if flow_percent > 0 %}\n    M221 S{flow_percent}\n    {% endif %}\n    {% set layer_height = vars.nozzle * 0.5 %}\n    {% set first_layer_height = layer_height * 1.25 %}\n    PRINT_RINGING_TOWER {vars.rawparams} LAYER_HEIGHT={layer_height} FIRST_LAYER_HEIGHT={first_layer_height} FINAL_GCODE_ID=end_ringing_test\n\n[delayed_gcode end_ringing_test]\ngcode:\n    # Add your end GCode here, for example:\n    # M104 S0 ; turn off temperature\n    # M140 S0 ; turn off heatbed\n    # M107 ; turn off fan\n    # G91 ; relative positioning\n    # G1 Z5 ; raise Z\n    # G90 ; absolute positioning\n    # G1 X0 Y200 ; present print\n    # M84 ; disable steppers\n    RESTORE_GCODE_STATE NAME=RINGING_TEST_STATE\n\n[gcode_macro RUN_RINGING_TEST]\nvariable_bed_temp: -1\nvariable_hotend_temp: -1\nvariable_nozzle: -1\nvariable_flow_rate: -1\nvariable_rawparams: ''\ngcode:\n    # Fail early if the required parameters are not provided\n    {% if params.NOZZLE is not defined %}\n    {action_raise_error('NOZZLE= parameter must be provided')}\n    {% endif %}\n    {% if params.TARGET_TEMP is not defined %}\n    {action_raise_error('TARGET_TEMP= parameter must be provided')}\n    {% endif %}\n    SET_GCODE_VARIABLE MACRO=RUN_RINGING_TEST VARIABLE=bed_temp VALUE={params.BED_TEMP|default(60)}\n    SET_GCODE_VARIABLE MACRO=RUN_RINGING_TEST VARIABLE=hotend_temp VALUE={params.TARGET_TEMP}\n    SET_GCODE_VARIABLE MACRO=RUN_RINGING_TEST VARIABLE=nozzle VALUE={params.NOZZLE}\n    SET_GCODE_VARIABLE MACRO=RUN_RINGING_TEST VARIABLE=flow_rate VALUE={params.FLOW_RATE|default(-1)}\n    SET_GCODE_VARIABLE MACRO=RUN_RINGING_TEST VARIABLE=rawparams VALUE=\"'{rawparams}'\"\n    SAVE_GCODE_STATE NAME=RINGING_TEST_STATE\n    UPDATE_DELAYED_GCODE ID=start_ringing_test DURATION=0.01\n
    "},{"location":"Bleeding_Edge.html#pa-tower-test-print","title":"PA tower test print","text":"

    Reference Discussion of this feature: https://klipper.discourse.group/t/extruder-pa-synchronization-with-input-shaping/3843/27

    "},{"location":"Bleeding_Edge.html#overview_4","title":"Overview","text":"

    The features introduces a new module for printing a Pressure Advance (PA) calibration tower directly from the firmware. This module simplifies the process of calibrating the PA settings, enhancing the precision and ease of tuning for optimal print quality.

    "},{"location":"Bleeding_Edge.html#key-features_1","title":"Key Features","text":""},{"location":"Bleeding_Edge.html#configuration","title":"Configuration","text":""},{"location":"Bleeding_Edge.html#operation","title":"Operation","text":""},{"location":"Bleeding_Edge.html#advantages-over-other-methods","title":"Advantages Over Other Methods","text":""},{"location":"Bleeding_Edge.html#sample-run-command_1","title":"Sample run command:","text":"

    Note, it is not reccomended to run the command directly without the helper macros configured.

    RUN_PA_TEST NOZZLE=0.4 TARGET_TEMP=205 BED_TEMP=55

    "},{"location":"Bleeding_Edge.html#sample-helper-macros_1","title":"Sample helper macros","text":"

    This sample Gcode can be included in printer.cfg or s seperate *.cfg file and #included in printer.cfg. Specific start/end printing Gcode for the printer should be added to ensure it aligned with the standard printing process such as the appropriate heating, homing and bed meshing sequences and additional functions such as enabling fan, additional purge lines, pressure advance setup, or adjusting the flow rate.

    [delayed_gcode start_pa_test]\ngcode:\n    {% set vars = printer[\"gcode_macro RUN_PA_TEST\"] %}\n    # Add your start GCode here, for example:\n    # G28\n    # M190 S{vars.bed_temp}\n    # M109 S{vars.hotend_temp}\n    {% set flow_percent = vars.flow_rate|float * 100.0 %}\n    {% if flow_percent > 0 %}\n        M221 S{flow_percent}\n    {% endif %}\n    {% set height = printer.configfile.settings.pa_test.height %}  \n    {% set pavalue = vars.pa_value %}\n    ; If pa_value is 0 then we test the full pa range starting from 0\n    {% if  vars.pa_value == 0 %} \n        TUNING_TOWER COMMAND=SET_PRESSURE_ADVANCE PARAMETER=ADVANCE START=0 FACTOR=.005\n    {% else %}\n        ; make sure that delta and start can not be lower then 0\n        {% if vars.pa_value - vars.pa_range <= 0%} \n            {% set delta = vars.pa_range %}\n            {% set start = 0 %}\n        {% else %}\n            ; calculate the pa range that we want to test\n            {% set delta = (vars.pa_value + vars.pa_range)  - (vars.pa_value - vars.pa_range)  %} \n            ; calculate the pa start value\n            {% set start = vars.pa_value - vars.pa_range %} \n        {% endif %}\n        TUNING_TOWER COMMAND=SET_PRESSURE_ADVANCE PARAMETER=ADVANCE START={start} FACTOR={delta / height}\n    {% endif %}\n    ; PRINT_PA_TOWER must be the last command in the start_pa_test script:\n    ; it starts a print and then immediately returns without waiting for the print to finish\n    PRINT_PA_TOWER {vars.rawparams} FINAL_GCODE_ID=end_pa_test\n\n[delayed_gcode end_pa_test]\ngcode:\n    # Add your end GCode here, for example:\n    # M104 S0 ; turn off temperature\n    # M140 S0 ; turn off heatbed\n    # M107 ; turn off fan\n    # G91 ; relative positioning\n    # G1 Z5 ; raise Z\n    # G90 ; absolute positioning\n    # G1 X0 Y200 ; present print\n    # M84 ; disable steppers\n    RESTORE_GCODE_STATE NAME=PA_TEST_STATE\n\n[gcode_macro RUN_PA_TEST]\nvariable_bed_temp: -1\nvariable_hotend_temp: -1\nvariable_pa_value: 0             # Used for further tuning of pa value. If value is not 0 than the tested pa value will only be +/- (determined by the pa_range variable) around of the pa_value variable\nvariable_pa_range: 0.03          # Only use if pa_value is set to heigher than 0. Used to set the +/- area around pa_value that should be tested\nvariable_flow_rate: -1\nvariable_rawparams: ''\ngcode:\n    # Fail early if the required parameters are not provided\n    {% if params.NOZZLE is not defined %}\n    {action_raise_error('NOZZLE= parameter must be provided')}\n    {% endif %}\n    {% if params.TARGET_TEMP is not defined %}\n    {action_raise_error('TARGET_TEMP= parameter must be provided')}\n    {% endif %}\n    SET_GCODE_VARIABLE MACRO=RUN_PA_TEST VARIABLE=bed_temp VALUE={params.BED_TEMP|default(60)}\n    SET_GCODE_VARIABLE MACRO=RUN_PA_TEST VARIABLE=hotend_temp VALUE={params.TARGET_TEMP}\n    SET_GCODE_VARIABLE MACRO=RUN_PA_TEST VARIABLE=pa_value VALUE={params.PA_VALUE|default(0)}\n    SET_GCODE_VARIABLE MACRO=RUN_PA_TEST VARIABLE=pa_range VALUE={params.PA_RANGE|default(0.01)}\n    SET_GCODE_VARIABLE MACRO=RUN_PA_TEST VARIABLE=flow_rate VALUE={params.FLOW_RATE|default(-1)}\n    SET_GCODE_VARIABLE MACRO=RUN_PA_TEST VARIABLE=rawparams VALUE=\"'{rawparams}'\"\n    SAVE_GCODE_STATE NAME=PA_TEST_STATE\n    UPDATE_DELAYED_GCODE ID=start_pa_test DURATION=0.01\n
    "},{"location":"Bootloader_Entry.html","title":"Bootloader Entry","text":"

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

    "},{"location":"Bootloader_Entry.html#requesting-the-bootloader","title":"Requesting the bootloader","text":""},{"location":"Bootloader_Entry.html#virtual-serial","title":"Virtual Serial","text":"

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

    "},{"location":"Bootloader_Entry.html#python-with-flash_usb","title":"Python (with flash_usb)","text":"

    To enter the bootloader using python (using flash_usb):

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

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

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

    "},{"location":"Bootloader_Entry.html#picocom","title":"Picocom","text":"
    picocom -b 1200 <DEVICE>\n<Ctrl-A><Ctrl-P>\n

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

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

    "},{"location":"Bootloader_Entry.html#physical-serial","title":"Physical serial","text":"

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

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

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

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

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

    "},{"location":"Bootloader_Entry.html#shell","title":"Shell","text":"
    stty <BAUD> < /dev/<DEVICE>\necho $'~ \\x1c Request Serial Bootloader!! ~' >> /dev/<DEVICE>\n

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

    <BAUD> is the baud rate of the serial port, such as 115200.

    "},{"location":"Bootloader_Entry.html#canbus","title":"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.

    "},{"location":"Bootloader_Entry.html#katapults-flashtoolpy","title":"Katapult's flashtool.py","text":"
    python3 ./katapult/scripts/flashtool.py -i <CAN_IFACE> -u <UUID> -r\n

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

    <UUID> is the UUID of your CAN device.

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

    "},{"location":"Bootloader_Entry.html#entering-the-bootloader","title":"Entering the bootloader","text":"

    When Kalico receives one of the above bootloader requests:

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

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

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

    For details about the specific bootloaders on various platforms see Bootloaders

    "},{"location":"Bootloader_Entry.html#notes","title":"Notes","text":""},{"location":"Bootloader_Entry.html#stm32-dfu-warning","title":"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.

    "},{"location":"Bootloaders.html","title":"Bootloaders","text":"

    This document provides information on common bootloaders found on micro-controllers that Kalico 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, Kalico) 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 Kalico developers have accumulated.

    "},{"location":"Bootloaders.html#avr-micro-controllers","title":"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).

    "},{"location":"Bootloaders.html#atmega2560","title":"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'\n\navrdude -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\navrdude -cavrispv2 -patmega2560 -P/dev/ttyACM0 -b115200 -U flash:w:stk500boot_v2_mega2560.hex\navrdude -cavrispv2 -patmega2560 -P/dev/ttyACM0 -b115200 -U lock:w:0x0F:m\n

    To flash an application use something like:

    avrdude -cwiring -patmega2560 -P/dev/ttyACM0 -b115200 -D -Uflash:w:out/klipper.elf.hex:i\n
    "},{"location":"Bootloaders.html#atmega1280","title":"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'\n\navrdude -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\navrdude -cavrispv2 -patmega1280 -P/dev/ttyACM0 -b115200 -U flash:w:ATmegaBOOT_168_atmega1280.hex\navrdude -cavrispv2 -patmega1280 -P/dev/ttyACM0 -b115200 -U lock:w:0x0F:m\n

    To flash an application use something like:

    avrdude -carduino -patmega1280 -P/dev/ttyACM0 -b57600 -D -Uflash:w:out/klipper.elf.hex:i\n
    "},{"location":"Bootloaders.html#atmega1284p","title":"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'\n\navrdude -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\navrdude -cavrispv2 -patmega1284p -P/dev/ttyACM0 -b115200 -U flash:w:optiboot_atmega1284p.hex\navrdude -cavrispv2 -patmega1284p -P/dev/ttyACM0 -b115200 -U lock:w:0x0F:m\n

    To flash an application use something like:

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

    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\n
    "},{"location":"Bootloaders.html#at90usb1286","title":"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\n
    "},{"location":"Bootloaders.html#atmega168","title":"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'\n\navrdude -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\navrdude -cavrispv2 -patmega168 -P/dev/ttyACM0 -b115200 -U flash:w:optiboot_atmega168.hex\navrdude -cavrispv2 -patmega168 -P/dev/ttyACM0 -b115200 -U lock:w:0x0F:m\n

    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\n
    "},{"location":"Bootloaders.html#sam3-micro-controllers-arduino-due","title":"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\nbossac -U -p /dev/ttyACM0 -R\n
    "},{"location":"Bootloaders.html#sam4-micro-controllers-duet-wifi","title":"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\n
    "},{"location":"Bootloaders.html#samdc21-micro-controllers-duet3d-toolboard-1lc","title":"SAMDC21 micro-controllers (Duet3D Toolboard 1LC)","text":"

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

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

    SWCLK=25\nSWDIO=24\nSRST=18\n\necho \"Exporting SWCLK and SRST pins.\"\necho $SWCLK > /sys/class/gpio/export\necho $SRST > /sys/class/gpio/export\necho \"out\" > /sys/class/gpio/gpio$SWCLK/direction\necho \"out\" > /sys/class/gpio/gpio$SRST/direction\n\necho \"Setting SWCLK low and pulsing SRST.\"\necho \"0\" > /sys/class/gpio/gpio$SWCLK/value\necho \"0\" > /sys/class/gpio/gpio$SRST/value\necho \"1\" > /sys/class/gpio/gpio$SRST/value\n\necho \"Unexporting SWCLK and SRST pins.\"\necho $SWCLK > /sys/class/gpio/unexport\necho $SRST > /sys/class/gpio/unexport\n

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

    source [find target/at91samdXX.cfg]\n

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

    at91samd chip-erase\nat91samd bootloader 0\nprogram out/klipper.elf verify\n
    "},{"location":"Bootloaders.html#samd21-micro-controllers-arduino-zero","title":"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]\n

    Obtain a bootloader - for example:

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

    Flash with OpenOCD commands similar to:

    at91samd bootloader 0\nprogram samd21_sam_ba.bin verify\n

    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\n

    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\n
    "},{"location":"Bootloaders.html#samd51-micro-controllers-adafruit-metro-m4-and-similar","title":"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]\n

    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'\n

    Flash with OpenOCD commands similar to:

    at91samd bootloader 0\nprogram bootloader-itsybitsy_m4-v3.7.0.bin verify\nat91samd bootloader 16384\n

    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\n
    "},{"location":"Bootloaders.html#stm32f103-micro-controllers-blue-pill-devices","title":"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\n

    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.

    "},{"location":"Bootloaders.html#stm32f103-with-stm32duino-bootloader","title":"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'\n\nstm32flash -w generic_boot20_pc13.bin -v -g 0 /dev/ttyAMA0\n

    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\n

    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.

    "},{"location":"Bootloaders.html#stm32f103-with-hid-bootloader","title":"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]\n

    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\n

    finally, you can flash with commands similar to:

    stm32f1x mass_erase 0\nprogram hid_btt_skr_mini_e3.bin verify 0x08000000\n

    NOTES:

    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\ncd ~/klipper/lib/hidflash\nmake\n

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

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

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

    make flash FLASH_DEVICE=1209:BEBA\n

    OR if Kalico has been previously flashed:

    make flash FLASH_DEVICE=/dev/ttyACM0\n

    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.

    "},{"location":"Bootloaders.html#stm32f103stm32f072-with-msc-bootloader","title":"STM32F103/STM32F072 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\n

    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.

    "},{"location":"Bootloaders.html#stm32f103stm32f0x2-with-canboot-bootloader","title":"STM32F103/STM32F0x2 with CanBoot bootloader","text":"

    The CanBoot bootloader provides an option for uploading Kalico firmware over the CANBUS. The bootloader itself is derived from Kalico'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 Kalico 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\n

    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\n

    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 Kalico for use with CanBoot, select the 8 KiB Bootloader option.

    "},{"location":"Bootloaders.html#stm32f4-micro-controllers-skr-pro-11","title":"STM32F4 micro-controllers (SKR Pro 1.1)","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\n\nstm32flash -w hid_bootloader_SKR_PRO.bin -v -g 0 /dev/ttyAMA0\n

    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.

    "},{"location":"Bootloaders.html#lpc176x-micro-controllers-smoothieboards","title":"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.

    "},{"location":"Bootloaders.html#running-openocd-on-the-raspberry-pi","title":"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\nsudo apt-get install autoconf libtool telnet\nmkdir ~/openocd\ncd ~/openocd/\ngit clone http://openocd.zylin.com/openocd\ncd openocd\n./bootstrap\n./configure --enable-sysfsgpio --enable-bcm2835gpio --prefix=/home/pi/openocd/install\nmake\nmake install\n
    "},{"location":"Bootloaders.html#configure-openocd","title":"Configure OpenOCD","text":"

    Create an OpenOCD config file:

    nano ~/openocd/openocd.cfg\n

    Use a config similar to the following:

    # Uses RPi pins: GPIO25 for SWDCLK, GPIO24 for SWDIO, GPIO18 for nRST\nsource [find interface/raspberrypi2-native.cfg]\nbcm2835gpio_swd_nums 25 24\nbcm2835gpio_srst_num 18\ntransport select swd\n\n# Use hardware reset wire for chip resets\nreset_config srst_only\nadapter_nsrst_delay 100\nadapter_nsrst_assert_width 100\n\n# Specify the chip type\nsource [find target/atsame5x.cfg]\n\n# Set the adapter speed\nadapter_khz 40\n\n# Connect to chip\ninit\ntargets\nreset halt\n
    "},{"location":"Bootloaders.html#wire-the-raspberry-pi-to-the-target-chip","title":"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.

    "},{"location":"Bootloaders.html#run-openocd","title":"Run OpenOCD","text":"

    Run OpenOCD:

    cd ~/openocd/\nsudo ~/openocd/install/bin/openocd -f ~/openocd/openocd.cfg\n

    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\n

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

    "},{"location":"Bootloaders.html#openocd-and-gdb","title":"OpenOCD and gdb","text":"

    It is possible to use OpenOCD with gdb to debug Kalico. 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\ngdb_port 44444\n

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

    cd /path/to/klipper/\ngdb out/klipper.elf\n

    Within gdb run:

    target remote octopi:44444\n

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

    "},{"location":"CANBUS.html","title":"CANBUS","text":"

    This document describes Kalico's CAN bus support.

    "},{"location":"CANBUS.html#device-hardware","title":"Device Hardware","text":"

    Kalico 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.

    "},{"location":"CANBUS.html#host-hardware","title":"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 Kalico 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\niface can0 can static\n    bitrate 1000000\n    up ip link set $IFACE txqueuelen 128\n
    "},{"location":"CANBUS.html#terminating-resistors","title":"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.

    "},{"location":"CANBUS.html#finding-the-canbus_uuid-for-new-micro-controllers","title":"\u26a0\ufe0f 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\n

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

    Found canbus_uuid=11aa22bb33cc, Application: Klipper, Unassigned\nFound canbus_uuid=11aa22bb33cc, Application: Kalico, Assigned: 77\n

    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 Kalico (or a similar tool) configures the device then it will no longer appear in the list.

    \u26a0\ufe0f Note that only devices flashed with a Kalico firmware will respond while assigned a device node ID. Devices using a Klipper firmware will no longer appear in the list once configured

    "},{"location":"CANBUS.html#configuring-kalico","title":"Configuring Kalico","text":"

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

    [mcu my_can_mcu]\ncanbus_uuid: 11aa22bb33cc\n
    "},{"location":"CANBUS.html#usb-to-can-bus-bridge-mode","title":"USB to CAN bus bridge mode","text":"

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

    When Kalico uses this mode the micro-controller appears as a \"USB CAN bus adapter\" under Linux. The \"Kalico 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 Kalico nodes.

    Some important notes when using this mode:

    allow-hotplug can0\niface can0 can static\n    bitrate 1000000\n    up ip link set $IFACE txqueuelen 128\n
    "},{"location":"CANBUS.html#tips-for-troubleshooting","title":"Tips for troubleshooting","text":"

    See the CAN bus troubleshooting document.

    "},{"location":"CANBUS_Troubleshooting.html","title":"CANBUS Troubleshooting","text":"

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

    "},{"location":"CANBUS_Troubleshooting.html#verify-can-bus-wiring","title":"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.

    "},{"location":"CANBUS_Troubleshooting.html#check-for-incrementing-bytes_invalid-counter","title":"Check for incrementing bytes_invalid counter","text":"

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

    Incrementing bytes_invalid on a CAN bus connection is a symptom of reordered messages on the CAN bus. There are two known causes of reordered messages:

    1. Old versions of the popular candlight_firmware for USB CAN adapters had a bug that could cause reordered messages. If using a USB CAN adapter running this firmware then make sure to update to the latest firmware if incrementing bytes_invalid is observed.
    2. Some Linux kernel builds for embedded devices have been known to reorder CAN bus messages. It may be necessary to use an alternative Linux kernel or to use alternative hardware that supports mainstream Linux kernels that do not exhibit this problem.

    Reordered messages is a severe problem that must be fixed. It will result in unstable behavior and can lead to confusing errors at any part of a print.

    "},{"location":"CANBUS_Troubleshooting.html#use-an-appropriate-txqueuelen-setting","title":"Use an appropriate txqueuelen setting","text":"

    The Kalico 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 Kalico 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 Kalico log:

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

    Kalico 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 Kalico 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, Kalico'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 Kalico may utilize ~25 queue slots per MCU - typically only utilizing more slots during retransmits. (Specifically, the Kalico host may transmit up to 192 bytes to each Kalico MCU before receiving an acknowledgment from that MCU.) If a single CAN bus has 5 or more Kalico 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.

    "},{"location":"CANBUS_Troubleshooting.html#obtaining-candump-logs","title":"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\n

    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\n

    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 Kalico. Understanding the content of these messages will likely require low-level knowledge of Kalico's CANBUS protocol and Kalico's MCU commands.

    "},{"location":"CANBUS_Troubleshooting.html#parsing-kalico-messages-in-a-candump-log","title":"Parsing Kalico messages in a candump log","text":"

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

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

    This tool produces output similar to the parsedump tool. See the documentation for that tool for information on generating the Kalico 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 Kalico 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.

    "},{"location":"CANBUS_Troubleshooting.html#using-a-logic-analyzer-on-the-canbus-wiring","title":"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.

    "},{"location":"CANBUS_protocol.html","title":"CANBUS protocol","text":"

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

    "},{"location":"CANBUS_protocol.html#micro-controller-id-assignment","title":"Micro-controller id assignment","text":"

    Kalico 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 Kalico command and response traffic. Kalico command messages going from host to micro-controller use the CAN bus id of canbus_nodeid * 2 + 256, while Kalico 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.

    "},{"location":"CANBUS_protocol.html#admin-messages","title":"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\".

    "},{"location":"CANBUS_protocol.html#cmd_query_unassigned-message","title":"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>

    "},{"location":"CANBUS_protocol.html#cmd_set_klipper_nodeid-message","title":"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>

    "},{"location":"CANBUS_protocol.html#resp_need_nodeid-message","title":"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>

    "},{"location":"CANBUS_protocol.html#data-packets","title":"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 Kalico 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).

    "},{"location":"CONTRIBUTING.html","title":"Contributing to Kalico","text":"

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

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

    "},{"location":"CONTRIBUTING.html#overview-of-contribution-process","title":"Overview of Contribution Process","text":"

    Contributions to Kalico generally follow a high-level process:

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

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

    "},{"location":"CONTRIBUTING.html#what-to-expect-in-a-review","title":"What to expect in a review","text":"

    Contributions to Kalico 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 Kalico documentation.

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

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

    Common things a reviewer will look for:

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

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

      The main KalicoCrew/kalico GitHub repository might accept experimental work, but we encourage submitters should perform experimentation, debugging, and testing in their own repositories. The Kalico Discord server is a good place to raise awareness of new work and to find users interested in providing real-world feedback.

      Submissions must pass all regression test cases.

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

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

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

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

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

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

      Submissions to the main Kalico 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 Kalico's most notable features took months of discussion, rework, testing, and documentation prior to being merged into the main branch.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

      Commit messages should follow the preferred format.

      Commits must not have a merge conflict. New additions to the Kalico main 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 Kalico main branch. 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.

    Kalico implements a soft-strict \"coding style guide\" on the Python code. Modifications to existing code should follow the high-level code flow, code indentation style, and format of that existing code.

    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.

    "},{"location":"CONTRIBUTING.html#helping-with-reviews","title":"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\".

    "},{"location":"CONTRIBUTING.html#reviewers","title":"Reviewers","text":"

    The Kalico \"reviewers\" are:

    Name GitHub Id Areas of interest

    TODO

    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 Kalico \"maintainers\" are:

    Name GitHub name Bea Nance @bwnance Rogerio Goncalves @rogerlz Lasse Dalegaard @dalegaard"},{"location":"CONTRIBUTING.html#format-of-commit-messages","title":"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\n\nMore detailed explanatory text, if necessary.  Wrap it to about 75\ncharacters or so.  In some contexts, the first line is treated as the\nsubject of an email and the rest of the text as the body.  The blank\nline separating the summary from the body is critical (unless you omit\nthe body entirely); tools like rebase can get confused if you run the\ntwo together.\n\nFurther paragraphs come after blank lines..\n\nSigned-off-by: My Name <myemail@example.org>\n

    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.

    "},{"location":"Code_Overview.html","title":"Code overview","text":"

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

    "},{"location":"Code_Overview.html#directory-layout","title":"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.

    "},{"location":"Code_Overview.html#micro-controller-code-flow","title":"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.

    "},{"location":"Code_Overview.html#klippy-code-overview","title":"Klippy code overview","text":"

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

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

    There are four threads in the Klippy host code. The main thread handles incoming gcode commands. A second thread (which resides entirely in the klippy/chelper/serialqueue.c C code) handles low-level IO with the serial port. The third thread is used to process response messages from the micro-controller in the Python code (see klippy/serialhdl.py). The fourth thread writes debug messages to the log (see klippy/queuelogger.py) so that the other threads never block on log writes.

    "},{"location":"Code_Overview.html#code-flow-of-a-move-command","title":"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.

    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.

    "},{"location":"Code_Overview.html#adding-a-host-module","title":"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 Kalico.

    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:

    "},{"location":"Code_Overview.html#adding-new-kinematics","title":"Adding new kinematics","text":"

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

    Useful steps:

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

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

    Useful steps:

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

    Additional coding tips:

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

    Internally, Kalico 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 Kalico 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 Kalico has several tools to facilitate that. This can be seen by running the GET_POSITION command. For example:

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

    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.

    "},{"location":"Code_Overview.html#time","title":"Time","text":"

    Fundamental to the operation of Kalico is the handling of clocks, times, and timestamps. Kalico 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 Kalico is critical to correct operation.

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

    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:

    "},{"location":"Command_Templates.html","title":"Commands templates","text":"

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

    "},{"location":"Command_Templates.html#g-code-macro-naming","title":"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).

    "},{"location":"Command_Templates.html#formatting-of-g-code-in-the-config","title":"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]\ngcode:\n  SET_PIN PIN=my_led VALUE=1\n  G4 P2000\n  SET_PIN PIN=my_led VALUE=0\n

    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.

    "},{"location":"Command_Templates.html#add-a-description-to-your-macro","title":"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]\ndescription: Blink my_led one time\ngcode:\n  SET_PIN PIN=my_led VALUE=1\n  G4 P2000\n  SET_PIN PIN=my_led VALUE=0\n

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

    "},{"location":"Command_Templates.html#saverestore-state-for-g-code-moves","title":"Save/Restore 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]\ngcode:\n  SAVE_GCODE_STATE NAME=my_move_up_state\n  G91\n  G1 Z10 F300\n  RESTORE_GCODE_STATE NAME=my_move_up_state\n

    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.

    "},{"location":"Command_Templates.html#template-expansion","title":"Template expansion","text":"

    The gcode_macro gcode: config section is evaluated using either the Jinja2 template language or Python.

    "},{"location":"Command_Templates.html#jinja2","title":"Jinja2","text":"

    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 Jinja2 macro:

    [gcode_macro clean_nozzle]\ngcode:\n  {% set wipe_count = 8 %}\n  SAVE_GCODE_STATE NAME=clean_nozzle_state\n  G90\n  G0 Z15 F300\n  {% for wipe in range(wipe_count) %}\n    {% for coordinate in [(275, 4),(235, 4)] %}\n      G0 X{coordinate[0]} Y{coordinate[1] + 0.25 * wipe} Z9.7 F12000\n    {% endfor %}\n  {% endfor %}\n  RESTORE_GCODE_STATE NAME=clean_nozzle_state\n
    "},{"location":"Command_Templates.html#jinja2-macro-parameters","title":"Jinja2: 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]\ngcode:\n  M117 Now at { params.VALUE|float * 100 }%\n

    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]\ngcode:\n  {% set bed_temp = params.TEMPERATURE|default(40)|float %}\n  M140 S{bed_temp}\n
    "},{"location":"Command_Templates.html#jinja2-the-rawparams-variable","title":"Jinja2: 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.

    "},{"location":"Command_Templates.html#jinja2-the-printer-variable","title":"Jinja2 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]\ngcode:\n  M106 S{ printer.fan.speed * 0.9 * 255}\n

    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]\ngcode:\n    {% set sensor = printer[\"htu21d my_sensor\"] %}\n    M117 Temp:{sensor.temperature} Humidity:{sensor.humidity}\n
    "},{"location":"Command_Templates.html#python","title":"Python","text":"

    Templates can also be written in Python code. The template will automatically be interpreted as Python if lines are prefixed with !. Note: You can't mix Python and Jinja2.

    An example of a complex Python macro:

    [gcode_macro clean_nozzle]\ngcode:\n  !wipe_count = 8\n  !emit(\"G90\")\n  !emit(\"G0 Z15 F300\")\n  !for wipe in range(wipe_count):\n  !  for coordinate in [(275, 4), (235, 4)]:\n  !    emit(f\"G0 X{coordinate[0]} Y{coordinate[1] + 0.25 * wipe} Z9.7 F12000\")\n
    "},{"location":"Command_Templates.html#python-rawparams","title":"Python: Rawparams","text":"
    [gcode_macro G4]\nrename_existing: G4.1\ngcode:\n  !if rawparams and \"S\" in rawparams:\n  !  s = int(rawparams.split(\"S\")[1])\n  !  respond_info(f\"Sleeping for {s} seconds\")\n  !  emit(f\"G4.1 P{s * 1000}\")\n  !else:\n  !  p = int(rawparams.split(\"P\")[1])\n  !  respond_info(f\"Sleeping for {p/1000} seconds\")\n  !  emit(f\"G4.1 {rawparams}\")\n
    "},{"location":"Command_Templates.html#python-variables","title":"Python: Variables","text":"
    [gcode_macro POKELOOP]\nvariable_count: 10\nvariable_speed: 3\ngcode:\n  !for i in range(own_vars.count):\n  !  emit(f\"BEACON_POKE SPEED={own_vars.speed} TOP=5 BOTTOM=-0.3\")\n
    "},{"location":"Command_Templates.html#python-printer-objects","title":"Python: Printer objects","text":"
    [gcode_macro EXTRUDER_TEMP]\ngcode:\n    !ACTUAL_TEMP = printer[\"extruder\"][\"temperature\"]\n    !TARGET_TEMP = printer[\"extruder\"][\"target\"]\n    !\n    !respond_info(\"Extruder Target: %.1fC, Actual: %.1fC\" % (TARGET_TEMP, ACTUAL_TEMP))\n
    "},{"location":"Command_Templates.html#python-helpers","title":"Python: Helpers","text":""},{"location":"Command_Templates.html#actions","title":"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:

    "},{"location":"Command_Templates.html#variables","title":"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]\nvariable_bed_temp: 0\ngcode:\n  # Save target temperature to bed_temp variable\n  SET_GCODE_VARIABLE MACRO=start_probe VARIABLE=bed_temp VALUE={printer.heater_bed.target}\n  # Disable bed heater\n  M140\n  # Perform probe\n  PROBE\n  # Call finish_probe macro at completion of probe\n  finish_probe\n\n[gcode_macro finish_probe]\ngcode:\n  # Restore temperature\n  M140 S{printer[\"gcode_macro start_probe\"].bed_temp}\n

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

    "},{"location":"Command_Templates.html#delayed-gcodes","title":"Delayed Gcodes","text":"

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

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

    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]\ninitial_duration: 5.\ngcode:\n  M117 Welcome!\n

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

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

    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\n
    "},{"location":"Command_Templates.html#menu-templates","title":"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:

    The following actions are available in menu templates:

    "},{"location":"Command_Templates.html#menu-dialogs","title":"Menu Dialogs","text":"

    When a menu dialog is used, and additional read-only attribute is availabe in templates.

    [menu __main __setup __tuning __hotend_mpc_dialog] in the default set of menus can be used as reference for how to build more complex dialogs.

    "},{"location":"Command_Templates.html#save-variables-to-disk","title":"Save Variables to disk","text":"

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

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

    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]\ngcode:\n  ACTIVATE_EXTRUDER extruder=extruder1\n  SAVE_VARIABLE VARIABLE=currentextruder VALUE='\"extruder1\"'\n\n[gcode_macro T0]\ngcode:\n  ACTIVATE_EXTRUDER extruder=extruder\n  SAVE_VARIABLE VARIABLE=currentextruder VALUE='\"extruder\"'\n\n[gcode_macro START_GCODE]\ngcode:\n  {% set svv = printer.save_variables.variables %}\n  ACTIVATE_EXTRUDER extruder={svv.currentextruder}\n
    "},{"location":"Config_Changes.html","title":"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 Kalico software.

    All dates in this document are approximate.

    "},{"location":"Config_Changes.html#changes","title":"Changes","text":"

    20250107: The rref parameter for tmc2240 is now mandatory with no default value.

    20241202: The sense_resistor parameter is now mandatory with no default value.

    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.

    20241125: The off_below parameter in fans config section is deprecated. It will be removed in the near future. Use min_power instead. The printer[fan object].speed status will be replaced by printer[fan object].value and printer[fan object].power.

    20241223: The CLEAR_RETRACTION command does not reset parameters to default config values anymore, a RESET_RETRACTION command was added to achieve this. Automatic resetting behavior on events was removed.

    20240430: The adc_ignore_limits parameter in the [danger_options] config section has been renamed to temp_ignore_limits and it now covers all possible temperature sensors.

    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).

    20240128: printer.kinematics now accepts limited_cartesian and limited_cartesian and limited_corexy that enables max_{x,y}_accel and max_{x,y}_velocity (only for limited_cartesian). In the future, this functionality may be moved into the original kinematics module (as optional settings).

    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.

    20230801: The setting fan.off_bellow has been changed to fan.min_power. However, this change will not affect users who do not utilize this setting. With this update, a PWM scaling has been introduced between min_power and max_power. Fans that require a higher min_power will now have access to their full \"safe\" power curve. By properly setting min_power, any fan (such as CPAP) should engage even at M106 S1. It's recommended to review your slicer/macros to adjust your fan speeds. Your previously designated 20% fan speed may no longer represent your lowest fan setting but will now correspond to an actual 20% fan speed. If you had previously set max_power to anything below 1.0 (default), it is advisable to recalibrate min_power and kick_start_time again, with the settings min_power: 0 and max_power: 1.

    20230729: The exported status for dual_carriage is changed. Instead of exporting mode and active_carriage, the individual modes for each carriage are exported as printer.dual_carriage.carriage_0 and printer.dual_carriage.carriage_1.

    20230619: The relative_reference_index option has been deprecated and superceded by the zero_reference_position option. Refer to the Bed Mesh Documentation for details on how to update the configuration. With this deprecation the RELATIVE_REFERENCE_INDEX is no longer available as a parameter for the BED_MESH_CALIBRATE gcode command.

    20230530: The default canbus frequency in \"make menuconfig\" is now 1000000. If using canbus and using canbus with some other frequency is required, then be sure to select \"Enable extra low-level configuration options\" and specify the desired \"CAN bus speed\" in \"make menuconfig\" when compiling and flashing the micro-controller.

    20230525: SHAPER_CALIBRATE command immediately applies input shaper parameters if [input_shaper] was enabled already.

    20230407: The stalled_bytes counter in the log and in the printer.mcu.last_stats field has been renamed to upcoming_bytes.

    20230323: On tmc5160 drivers multistep_filt is now enabled by default. Set driver_MULTISTEP_FILT: False in the tmc5160 config for the previous behavior.

    20230304: The SET_TMC_CURRENT command now properly adjusts the globalscaler register for drivers that have it. This removes a limitation where on tmc5160, the currents could not be raised higher with SET_TMC_CURRENT than the run_current value set in the config file. However, this has a side effect: After running SET_TMC_CURRENT, the stepper must be held at standstill for >130ms in case StealthChop2 is used so that the AT#1 calibration gets executed by the driver.

    20230202: The format of the printer.screws_tilt_adjust status information has changed. The information is now stored as a dictionary of screws with the resulting measurements. See the status reference for details.

    20230201: The [bed_mesh] module no longer loads the default profile on startup. It is recommended that users who use the default profile add BED_MESH_PROFILE LOAD=default to their START_PRINT macro (or to their slicer's \"Start G-Code\" configuration when applicable).

    20230103: It is now possible with the flash-sdcard.sh script to flash both variants of the Bigtreetech SKR-2, STM32F407 and STM32F429. This means that the original tag of btt-skr2 now has changed to either btt-skr-2-f407 or btt-skr-2-f429.

    20221128: Klipper v0.11.0 released.

    20221122: Previously, with safe_z_home, it was possible that the z_hop after the g28 homing would go in the negative z direction. Now, a z_hop is performed after g28 only if it results in a positive hop, mirroring the behavior of the z_hop that occurs before the g28 homing.

    20220616: It was previously possible to flash an rp2040 in bootloader mode by running make flash FLASH_DEVICE=first. The equivalent command is now make flash FLASH_DEVICE=2e8a:0003.

    20220612: The rp2040 micro-controller now has a workaround for the \"rp2040-e5\" USB errata. This should make initial USB connections more reliable. However, it may result in a change in behavior for the gpio15 pin. It is unlikely the gpio15 behavior change will be noticeable.

    20220407: The temperature_fan pid_integral_max config option has been removed (it was deprecated on 20210612).

    20220407: The default color order for pca9632 LEDs is now \"RGBW\". Add an explicit color_order: RBGW setting to the pca9632 config section to obtain the previous behavior.

    20220330: The format of the printer.neopixel.color_data status information for neopixel and dotstar modules has changed. The information is now stored as a list of color lists (instead of a list of dictionaries). See the status reference for details.

    20220307: M73 will no longer set print progress to 0 if P is missing.

    20220304: There is no longer a default for the extruder parameter of extruder_stepper config sections. If desired, specify extruder: extruder explicitly to associate the stepper motor with the \"extruder\" motion queue at startup.

    20220210: The SYNC_STEPPER_TO_EXTRUDER command is deprecated; the SET_EXTRUDER_STEP_DISTANCE command is deprecated; the extruder shared_heater config option is deprecated. These features will be removed in the near future. Replace SET_EXTRUDER_STEP_DISTANCE with SET_EXTRUDER_ROTATION_DISTANCE. Replace SYNC_STEPPER_TO_EXTRUDER with SYNC_EXTRUDER_MOTION. Replace extruder config sections using shared_heater with extruder_stepper config sections and update any activation macros to use SYNC_EXTRUDER_MOTION.

    20220116: The tmc2130, tmc2208, tmc2209, and tmc2660 run_current calculation code has changed. For some run_current settings the drivers may now be configured differently. This new configuration should be more accurate, but it may invalidate previous tmc driver tuning.

    20211230: Scripts to tune input shaper (scripts/calibrate_shaper.py and scripts/graph_accelerometer.py) were migrated to use Python3 by default. As a result, users must install Python3 versions of certain packages (e.g. sudo apt install python3-numpy python3-matplotlib) to continue using these scripts. For more details, refer to Software installation. Alternatively, users can temporarily force the execution of these scripts under Python 2 by explicitly calling Python2 interpretor in the console: python2 ~/klipper/scripts/calibrate_shaper.py ...

    20211110: The \"NTC 100K beta 3950\" temperature sensor is deprecated. This sensor will be removed in the near future. Most users will find the \"Generic 3950\" temperature sensor more accurate. To continue to use the older (typically less accurate) definition, define a custom thermistor with temperature1: 25, resistance1: 100000, and beta: 3950.

    20211104: The \"step pulse duration\" option in \"make menuconfig\" has been removed. The default step duration for TMC drivers configured in UART or SPI mode is now 100ns. A new step_pulse_duration setting in the stepper config section should be set for all steppers that need a custom pulse duration.

    20211102: Several deprecated features have been removed. The stepper step_distance option has been removed (deprecated on 20201222). The rpi_temperature sensor alias has been removed (deprecated on 20210219). The mcu pin_map option has been removed (deprecated on 20210325). The gcode_macro default_parameter_<name> and macro access to command parameters other than via the params pseudo-variable has been removed (deprecated on 20210503). The heater pid_integral_max option has been removed (deprecated on 20210612).

    20210929: Klipper v0.10.0 released.

    20210903: The default smooth_time for heaters has changed to 1 second (from 2 seconds). For most printers this will result in more stable temperature control.

    20210830: The default adxl345 name is now \"adxl345\". The default CHIP parameter for the ACCELEROMETER_MEASURE and ACCELEROMETER_QUERY is now also \"adxl345\".

    20210830: The adxl345 ACCELEROMETER_MEASURE command no longer supports a RATE parameter. To alter the query rate, update the printer.cfg file and issue a RESTART command.

    20210821: Several config settings in printer.configfile.settings will now be reported as lists instead of raw strings. If the actual raw string is desired, use printer.configfile.config instead.

    20210819: In some cases, a G28 homing move may end in a position that is nominally outside the valid movement range. In rare situations this may result in confusing \"Move out of range\" errors after homing. If this occurs, change your start scripts to move the toolhead to a valid position immediately after homing.

    20210814: The analog only pseudo-pins on the atmega168 and atmega328 have been renamed from PE0/PE1 to PE2/PE3.

    20210720: A controller_fan section now monitors all stepper motors by default (not just the kinematic stepper motors). If the previous behavior is desired, see the stepper config option in the config reference.

    20210703: A samd_sercom config section must now specify the sercom bus it is configuring via the sercom option.

    20210612: The pid_integral_max config option in heater and temperature_fan sections is deprecated. The option will be removed in the near future.

    20210503: The gcode_macro default_parameter_<name> config option is deprecated. Use the params pseudo-variable to access macro parameters. Other methods for accessing macro parameters will be removed in the near future. Most users can replace a default_parameter_NAME: VALUE config option with a line like the following in the start of the macro: {% set NAME = params.NAME|default(VALUE)|float %}. See the Command Templates document for examples.

    20210430: The SET_VELOCITY_LIMIT (and M204) command may now set a velocity, acceleration, and square_corner_velocity larger than the specified values in the config file.

    20210325: Support for the pin_map config option is deprecated. Use the sample-aliases.cfg file to translate to the actual micro-controller pin names. The pin_map config option will be removed in the near future.

    20210313: Klipper's support for micro-controllers that communicate with CAN bus has changed. If using CAN bus then all micro-controllers must be reflashed and the Klipper configuration must be updated.

    20210310: The TMC2660 default for driver_SFILT has been changed from 1 to 0.

    20210227: TMC stepper motor drivers in UART or SPI mode are now queried once per second whenever they are enabled - if the driver can not be contacted or if the driver reports an error, then Klipper will transition to a shutdown state.

    20210219: The rpi_temperature module has been renamed to temperature_host. Replace any occurrences of sensor_type: rpi_temperature with sensor_type: temperature_host. The path to the temperature file may be specified in the sensor_path config variable. The rpi_temperature name is deprecated and will be removed in the near future.

    20210201: The TEST_RESONANCES command will now disable input shaping if it was previously enabled (and re-enable it after the test). In order to override this behavior and keep the input shaping enabled, one can pass an additional parameter INPUT_SHAPING=1 to the command.

    20210201: The ACCELEROMETER_MEASURE command will now append the name of the accelerometer chip to the output file name if the chip was given a name in the corresponding adxl345 section of the printer.cfg.

    20201222: The step_distance setting in the stepper config sections is deprecated. It is advised to update the config to use the rotation_distance setting. Support for step_distance will be removed in the near future.

    20201218: The endstop_phase setting in the endstop_phase module has been replaced with trigger_phase. If using the endstop phases module then it will be necessary to convert to rotation_distance and recalibrate any endstop phases by running the ENDSTOP_PHASE_CALIBRATE command.

    20201218: Rotary delta and polar printers must now specify a gear_ratio for their rotary steppers, and they may no longer specify a step_distance parameter. See the config reference for the format of the new gear_ratio paramter.

    20201213: It is not valid to specify a Z \"position_endstop\" when using \"probe:z_virtual_endstop\". An error will now be raised if a Z \"position_endstop\" is specified with \"probe:z_virtual_endstop\". Remove the Z \"position_endstop\" definition to fix the error.

    20201120: The [board_pins] config section now specifies the mcu name in an explicit mcu: parameter. If using board_pins for a secondary mcu, then the config must be updated to specify that name. See the config reference for further details.

    20201112: The time reported by print_stats.print_duration has changed. The duration prior to the first detected extrusion is now excluded.

    20201029: The neopixel color_order_GRB config option has been removed. If necessary, update the config to set the new color_order option to RGB, GRB, RGBW, or GRBW.

    20201029: The serial option in the mcu config section no longer defaults to /dev/ttyS0. In the rare situation where /dev/ttyS0 is the desired serial port, it must be specified explicitly.

    20201020: Klipper v0.9.0 released.

    20200902: The RTD resistance-to-temperature calculation for MAX31865 converters has been corrected to not read low. If you are using such a device, you should recalibrate your print temperature and PID settings.

    20200816: The gcode macro printer.gcode object has been renamed to printer.gcode_move. Several undocumented variables in printer.toolhead and printer.gcode have been removed. See docs/Command_Templates.md for a list of available template variables.

    20200816: The gcode macro \"action_\" system has changed. Replace any calls to printer.gcode.action_emergency_stop() with action_emergency_stop(), printer.gcode.action_respond_info() with action_respond_info(), and printer.gcode.action_respond_error() with action_raise_error().

    20200809: The menu system has been rewritten. If the menu has been customized then it will be necessary to update to the new configuration. See config/example-menu.cfg for configuration details and see klippy/extras/display/menu.cfg for examples.

    20200731: The behavior of the progress attribute reported by the virtual_sdcard printer object has changed. Progress is no longer reset to 0 when a print is paused. It will now always report progress based on the internal file position, or 0 if no file is currently loaded.

    20200725: The servo enable config parameter and the SET_SERVO ENABLE parameter have been removed. Update any macros to use SET_SERVO SERVO=my_servo WIDTH=0 to disable a servo.

    20200608: The LCD display support has changed the name of some internal \"glyphs\". If a custom display layout was implemented it may be necessary to update to the latest glyph names (see klippy/extras/display/display.cfg for a list of available glyphs).

    20200606: The pin names on linux mcu have changed. Pins now have names of the form gpiochip<chipid>/gpio<gpio>. For gpiochip0 you can also use a short gpio<gpio>. For example, what was previously referred to as P20 now becomes gpio20 or gpiochip0/gpio20.

    20200603: The default 16x4 LCD layout will no longer show the estimated time remaining in a print. (Only the elapsed time will be shown.) If the old behavior is desired one can customize the menu display with that information (see the description of display_data in config/example-extras.cfg for details).

    20200531: The default USB vendor/product id is now 0x1d50/0x614e. These new ids are reserved for Klipper (thanks to the openmoko project). This change should not require any config changes, but the new ids may appear in system logs.

    20200524: The default value for the tmc5160 pwm_freq field is now zero (instead of one).

    20200425: The gcode_macro command template variable printer.heater was renamed to printer.heaters.

    20200313: The default lcd layout for multi-extruder printers with a 16x4 screen has changed. The single extruder screen layout is now the default and it will show the currently active extruder. To use the previous display layout set \"display_group: _multiextruder_16x4\" in the [display] section of the printer.cfg file.

    20200308: The default __test menu item was removed. If the config file has a custom menu then be sure to remove all references to this __test menu item.

    20200308: The menu \"deck\" and \"card\" options were removed. To customize the layout of an lcd screen use the new display_data config sections (see config/example-extras.cfg for the details).

    20200109: The bed_mesh module now references the probe's location in for the mesh configuration. As such, some configuration options have been renamed to more accurately reflect their intended functionality. For rectangular beds, min_point and max_point have been renamed to mesh_min and mesh_max respectively. For round beds, bed_radius has been renamed to mesh_radius. A new mesh_origin option has also been added for round beds. Note that these changes are also incompatible with previously saved mesh profiles. If an incompatible profile is detected it will be ignored and scheduled for removal. The removal process can be completed by issuing the SAVE_CONFIG command. The user will need to re-calibrate each profile.

    20191218: The display config section no longer supports \"lcd_type: st7567\". Use the \"uc1701\" display type instead - set \"lcd_type: uc1701\" and change the \"rs_pin: some_pin\" to \"rst_pin: some_pin\". It may also be necessary to add a \"contrast: 60\" config setting.

    20191210: The builtin T0, T1, T2, ... commands have been removed. The extruder activate_gcode and deactivate_gcode config options have been removed. If these commands (and scripts) are needed then define individual [gcode_macro T0] style macros that call the ACTIVATE_EXTRUDER command. See the config/sample-idex.cfg and sample-multi-extruder.cfg files for examples.

    20191210: Support for the M206 command has been removed. Replace with calls to SET_GCODE_OFFSET. If support for M206 is needed, add a [gcode_macro M206] config section that calls SET_GCODE_OFFSET. (For example \"SET_GCODE_OFFSET Z=-{params.Z}\".)

    20191202: Support for the undocumented \"S\" parameter of the \"G4\" command has been removed. Replace any occurrences of S with the standard \"P\" parameter (the delay specified in milliseconds).

    20191126: The USB names have changed on micro-controllers with native USB support. They now use a unique chip id by default (where available). If an \"mcu\" config section uses a \"serial\" setting that starts with \"/dev/serial/by-id/\" then it may be necessary to update the config. Run \"ls /dev/serial/by-id/*\" in an ssh terminal to determine the new id.

    20191121: The pressure_advance_lookahead_time parameter has been removed. See example.cfg for alternate configuration settings.

    20191112: The tmc stepper driver virtual enable capability is now automatically enabled if the stepper does not have a dedicated stepper enable pin. Remove references to tmcXXXX:virtual_enable from the config. The ability to control multiple pins in the stepper enable_pin config has been removed. If multiple pins are needed then use a multi_pin config section.

    20191107: The primary extruder config section must be specified as \"extruder\" and may no longer be specified as \"extruder0\". Gcode command templates that query the extruder status are now accessed via \"{printer.extruder}\".

    20191021: Klipper v0.8.0 released

    20191003: The move_to_previous option in [safe_z_homing] now defaults to False. (It was effectively False prior to 20190918.)

    20190918: The zhop option in [safe_z_homing] is always re-applied after Z axis homing completed. This might need users to update custom scripts based on this module.

    20190806: The SET_NEOPIXEL command has been renamed to SET_LED.

    20190726: The mcp4728 digital-to-analog code has changed. The default i2c_address is now 0x60 and the voltage reference is now relative to the mcp4728's internal 2.048 volt reference.

    20190710: The z_hop option was removed from the [firmware_retract] config section. The z_hop support was incomplete and could cause incorrect behavior with several common slicers.

    20190710: The optional parameters of the PROBE_ACCURACY command have changed. It may be necessary to update any macros or scripts that use that command.

    20190628: All configuration options have been removed from the [skew_correction] section. Configuration for skew_correction is now done via the SET_SKEW gcode. See Skew Correction for recommended usage.

    20190607: The \"variable_X\" parameters of gcode_macro (along with the VALUE parameter of SET_GCODE_VARIABLE) are now parsed as Python literals. If a value needs to be assigned a string then wrap the value in quotes so that it is evaluated as a string.

    20190606: The \"samples\", \"samples_result\", and \"sample_retract_dist\" config options have been moved to the \"probe\" config section. These options are no longer supported in the \"delta_calibrate\", \"bed_tilt\", \"bed_mesh\", \"screws_tilt_adjust\", \"z_tilt\", or \"quad_gantry_level\" config sections.

    20190528: The magic \"status\" variable in gcode_macro template evaluation has been renamed to \"printer\".

    20190520: The SET_GCODE_OFFSET command has changed; update any g-code macros accordingly. The command will no longer apply the requested offset to the next G1 command. The old behavior may be approximated by using the new \"MOVE=1\" parameter.

    20190404: The Python host software packages were updated. Users will need to rerun the ~/klipper/scripts/install-octopi.sh script (or otherwise upgrade the python dependencies if not using a standard OctoPi installation).

    20190404: The i2c_bus and spi_bus parameters (in various config sections) now take a bus name instead of a number.

    20190404: The sx1509 config parameters have changed. The 'address' parameter is now 'i2c_address' and it must be specified as a decimal number. Where 0x3E was previously used, specify 62.

    20190328: The min_speed value in [temperature_fan] config will now be respected and the fan will always run at this speed or higher in PID mode.

    20190322: The default value for \"driver_HEND\" in [tmc2660] config sections was changed from 6 to 3. The \"driver_VSENSE\" field was removed (it is now automatically calculated from run_current).

    20190310: The [controller_fan] config section now always takes a name (such as [controller_fan my_controller_fan]).

    20190308: The \"driver_BLANK_TIME_SELECT\" field in [tmc2130] and [tmc2208] config sections has been renamed to \"driver_TBL\".

    20190308: The [tmc2660] config section has changed. A new sense_resistor config parameter must now be provided. The meaning of several of the driver_XXX parameters has changed.

    20190228: Users of SPI or I2C on SAMD21 boards must now specify the bus pins via a [samd_sercom] config section.

    20190224: The bed_shape option has been removed from bed_mesh. The radius option has been renamed to bed_radius. Users with round beds should supply the bed_radius and round_probe_count options.

    20190107: The i2c_address parameter in the mcp4451 config section changed. This is a common setting on Smoothieboards. The new value is half the old value (88 should be changed to 44, and 90 should be changed to 45).

    20181220: Klipper v0.7.0 released

    "},{"location":"Config_Reference.html","title":"Configuration reference","text":"

    This document is a reference for options available in the Kalico config file.

    Sections and options are marked with an \u26a0\ufe0f to denote configurations that are changed from stock Klipper.

    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 Kalico and choosing an initial config file.

    "},{"location":"Config_Reference.html#micro-controller-configuration","title":"Micro-controller configuration","text":""},{"location":"Config_Reference.html#format-of-micro-controller-pin-names","title":"Format of micro-controller pin names","text":"

    Many config options require the name of a micro-controller pin. Kalico 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.

    "},{"location":"Config_Reference.html#mcu","title":"[mcu]","text":"

    Configuration of the primary micro-controller.

    [mcu]\nserial:\n#   The serial port to connect to the MCU. If unsure (or if it\n#   changes) see the \"Where's my serial port?\" section of the FAQ.\n#   This parameter must be provided when using a serial port.\n#baud: 250000\n#   The baud rate to use. The default is 250000.\n#canbus_uuid:\n#   If using a device connected to a CAN bus then this sets the unique\n#   chip identifier to connect to. This value must be provided when using\n#   CAN bus for communication.\n#canbus_interface:\n#   If using a device connected to a CAN bus then this sets the CAN\n#   network interface to use. The default is 'can0'.\n#restart_method:\n#   This controls the mechanism the host will use to reset the\n#   micro-controller. The choices are 'arduino', 'cheetah', 'rpi_usb',\n#   and 'command'. The 'arduino' method (toggle DTR) is common on\n#   Arduino boards and clones. The 'cheetah' method is a special\n#   method needed for some Fysetc Cheetah boards. The 'rpi_usb' method\n#   is useful on Raspberry Pi boards with micro-controllers powered\n#   over USB - it briefly disables power to all USB ports to\n#   accomplish a micro-controller reset. The 'command' method involves\n#   sending a Kalico command to the micro-controller so that it can\n#   reset itself. The default is 'arduino' if the micro-controller\n#   communicates over a serial port, 'command' otherwise.\n#is_non_critical: False\n#   Setting this to True will allow the mcu to be disconnected and\n#   reconnected at will without errors. Helpful for USB-accelerometer boards\n#   and USB-probes\n
    "},{"location":"Config_Reference.html#mcu-my_extra_mcu","title":"[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]\n# See the \"mcu\" section for configuration parameters.\n
    "},{"location":"Config_Reference.html#danger-options","title":"\u26a0\ufe0f Danger Options","text":"

    A collection of Kalico-specific system options

    [danger_options]\n#error_on_unused_config_options: True\n#   If an unused config option or section should cause an error\n#   if False, will warn but allow Kalico to still run.\n#   The default is True.\n#allow_plugin_override: False\n#   Allows modules in `plugins` to override modules of the same name in `extras`\n#   The default is False.\n#multi_mcu_trsync_timeout: 0.025\n#   The timeout (in seconds) for MCU synchronization during the homing process when\n#   multiple MCUs are in use. The default is 0.025\n#homing_elapsed_distance_tolerance: 0.5\n#   Tolerance (in mm) for distance moved in the second homing. Ensures the\n#   second homing distance closely matches the `min_home_dist` when using\n#   sensorless homing. The default is 0.5mm.\n#temp_ignore_limits: False\n#   When set to true, this parameter ignores the min_value and max_value\n#   limits for temperature sensors. It prevents shutdowns due to\n#   'ADC out of range' and similar errors by allowing readings outside the\n#   specified range without triggering a shutdown. The default is False.\n#autosave_includes: False\n#   When set to true, SAVE_CONFIG will recursively read [include ...] blocks\n#   for conflicts to autosave data. Any configurations updated will be backed\n#   up to configs/config_backups.\n#bgflush_extra_time: 0.250\n#   This allows to set extra flush time (in seconds). Under certain conditions,\n#   a low value will result in an error if message is not get flushed, a high value\n#   (0.250) will result in homing/probing latency. The default is 0.250\n#homing_start_delay: 0.001\n#   How long to dwell before beginning a drip move for homing\n#endstop_sample_time: 0.000015\n#   How often the MCU should sample the endstop state\n#endstop_sample_count: 4\n#   How many times we should check the endstop state when homing\n#   Unless your endstop is noisy and unreliable, you should be able to lower this to 1\n\n\n# Logging options:\n\n#minimal_logging: False\n#   Set all log parameters log options to False. The default is False.\n#log_statistics: True\n#   If statistics should be logged\n#   (helpful for keeping the log clean during development)\n#   The default is True.\n#log_config_file_at_startup: True\n#   If the config file should be logged at startup\n#   The default is True.\n#log_bed_mesh_at_startup: True\n#   If the bed mesh should be logged at startup\n#   (helpful for keeping the log clean during development)\n#   The default is True.\n#log_velocity_limit_changes: True\n#   If changes to velocity limits should be logged. If False, velocity limits will only\n#   be logged at rollover. Some slicers emit very frequent SET_VELOCITY_LIMIT commands\n#   The default is True\n#log_pressure_advance_changes: True\n#   If changes to pressure advance should be logged. If false, pressure advance data\n#   will only be logged at rollover.\n#   The default is True.\n#log_shutdown_info: True\n#   If we should log detailed crash info when an exception occurs\n#   Most of it is overly-verbose and fluff and we still get a stack trace\n#   for normal exceptions, so setting to False can help save time while developing\n#   The default is True.\n#log_serial_reader_warnings: True\n#log_startup_info: True\n#log_webhook_method_register_messages: False\n
    "},{"location":"Config_Reference.html#configuration-references","title":"\u26a0\ufe0f Configuration references","text":"

    In your configuration, you can reference other values to share configuration between multiple sections. References take the form of ${option} to copy a value in the current section, or ${section.option} to look up a value elsewhere in your configuration. Note, that constants must always be lower case.

    Optionally, a [constants] section may be used specifically to store these values. Unlike the rest of your configuration, unused constants will show a warning instead of causing an error.

    [constants]\nrun_current_ab:  1.0\ni_am_not_used: True  # Will show \"Constant 'i_am_not_used' is unused\"\n\n[tmc5160 stepper_x]\nrun_current: ${constants.run_current_ab}\n\n[tmc5160 stepper_y]\nrun_current: ${tmc5160 stepper_x.run_current}\n#   Nested references work, but are not advised\n
    "},{"location":"Config_Reference.html#common-kinematic-settings","title":"Common kinematic settings","text":""},{"location":"Config_Reference.html#printer","title":"[printer]","text":"

    The printer section controls high level printer settings.

    [printer]\nkinematics:\n#   The type of printer in use. This option may be one of: cartesian,\n#   corexy, corexz, hybrid_corexy, hybrid_corexz, rotary_delta, delta,\n#   deltesian, polar, winch, or none. This parameter must be specified.\nmax_velocity:\n#   Maximum velocity (in mm/s) of the toolhead (relative to the\n#   print). This value may be changed at runtime using the\n#   SET_VELOCITY_LIMIT command. This parameter must be specified.\nmax_accel:\n#   Maximum acceleration (in mm/s^2) of the toolhead (relative to the\n#   print). Although this parameter is described as a \"maximum\"\n#   acceleration, in practice most moves that accelerate or decelerate\n#   will do so at the rate specified here. The value specified here\n#   may be changed at runtime using the SET_VELOCITY_LIMIT command.\n#   This parameter must be specified.\n#minimum_cruise_ratio: 0.5\n#   Most moves will accelerate to a cruising speed, travel at that\n#   cruising speed, and then decelerate. However, some moves that\n#   travel a short distance could nominally accelerate and then\n#   immediately decelerate. This option reduces the top speed of these\n#   moves to ensure there is always a minimum distance traveled at a\n#   cruising speed. That is, it enforces a minimum distance traveled\n#   at cruising speed relative to the total distance traveled. It is\n#   intended to reduce the top speed of short zigzag moves (and thus\n#   reduce printer vibration from these moves). For example, a\n#   minimum_cruise_ratio of 0.5 would ensure that a standalone 1.5mm\n#   move would have a minimum cruising distance of 0.75mm. Specify a\n#   ratio of 0.0 to disable this feature (there would be no minimum\n#   cruising distance enforced between acceleration and deceleration).\n#   The value specified here may be changed at runtime using the\n#   SET_VELOCITY_LIMIT command. The default is 0.5.\n#square_corner_velocity: 5.0\n#   The maximum velocity (in mm/s) that the toolhead may travel a 90\n#   degree corner at. A non-zero value can reduce changes in extruder\n#   flow rates by enabling instantaneous velocity changes of the\n#   toolhead during cornering. This value configures the internal\n#   centripetal velocity cornering algorithm; corners with angles\n#   larger than 90 degrees will have a higher cornering velocity while\n#   corners with angles less than 90 degrees will have a lower\n#   cornering velocity. If this is set to zero then the toolhead will\n#   decelerate to zero at each corner. The value specified here may be\n#   changed at runtime using the SET_VELOCITY_LIMIT command. The\n#   default is 5mm/s.\n#max_accel_to_decel:\n#   This parameter is deprecated and should no longer be used.\n
    "},{"location":"Config_Reference.html#stepper","title":"[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]\nstep_pin:\n#   Step GPIO pin (triggered high). This parameter must be provided.\ndir_pin:\n#   Direction GPIO pin (high indicates positive direction). This\n#   parameter must be provided.\nenable_pin:\n#   Enable pin (default is enable high; use ! to indicate enable\n#   low). If this parameter is not provided then the stepper motor\n#   driver must always be enabled.\nrotation_distance:\n#   Distance (in mm) that the axis travels with one full rotation of\n#   the stepper motor (or final gear if gear_ratio is specified).\n#   This parameter must be provided.\nmicrosteps:\n#   The number of microsteps the stepper motor driver uses. This\n#   parameter must be provided.\n#full_steps_per_rotation: 200\n#   The number of full steps for one rotation of the stepper motor.\n#   Set this to 200 for a 1.8 degree stepper motor or set to 400 for a\n#   0.9 degree motor. The default is 200.\n#gear_ratio:\n#   The gear ratio if the stepper motor is connected to the axis via a\n#   gearbox. For example, one may specify \"5:1\" if a 5 to 1 gearbox is\n#   in use. If the axis has multiple gearboxes one may specify a comma\n#   separated list of gear ratios (for example, \"57:11, 2:1\"). If a\n#   gear_ratio is specified then rotation_distance specifies the\n#   distance the axis travels for one full rotation of the final gear.\n#   The default is to not use a gear ratio.\n#step_pulse_duration:\n#   The minimum time between the step pulse signal edge and the\n#   following \"unstep\" signal edge. This is also used to set the\n#   minimum time between a step pulse and a direction change signal.\n#   The default is 0.000000100 (100ns) for TMC steppers that are\n#   configured in UART or SPI mode, and the default is 0.000002 (which\n#   is 2us) for all other steppers.\nendstop_pin:\n#   Endstop switch detection pin. If this endstop pin is on a\n#   different mcu than the stepper motor then it enables \"multi-mcu\n#   homing\". This parameter must be provided for the X, Y, and Z\n#   steppers on cartesian style printers.\n#position_min: 0\n#   Minimum valid distance (in mm) the user may command the stepper to\n#   move to.  The default is 0mm.\nposition_endstop:\n#   Location of the endstop (in mm). This parameter must be provided\n#   for the X, Y, and Z steppers on cartesian style printers.\nposition_max:\n#   Maximum valid distance (in mm) the user may command the stepper to\n#   move to. This parameter must be provided for the X, Y, and Z\n#   steppers on cartesian style printers.\n#homing_speed: 5.0\n#   Maximum velocity (in mm/s) of the stepper when homing. The default\n#   is 5mm/s.\n#homing_retract_dist: 5.0\n#   Distance to backoff (in mm) before homing a second time during\n#   homing. If `use_sensorless_homing` is false, this setting can be set\n#   to zero to disable the second home. If `use_sensorless_homing` is\n#   true, this setting can be > 0 to backoff after homing. The default\n#   is 5mm.\n#homing_retract_speed:\n#   Speed to use on the retract move after homing in case this should\n#   be different from the homing speed, which is the default for this\n#   parameter\n#min_home_dist:\n#   Minimum distance (in mm) for toolhead before sensorless homing. If closer\n#   than `min_home_dist` to endstop, it moves away to this distance, then homes.\n#   If further, it directly homes and retracts to `homing_retract_dist`.\n#   The default is equal to `homing_retract_dist`.\n#second_homing_speed:\n#   Velocity (in mm/s) of the stepper when performing the second home.\n#   The default is homing_speed/2.\n#homing_positive_dir:\n#   If true, homing will cause the stepper to move in a positive\n#   direction (away from zero); if false, home towards zero. It is\n#   better to use the default than to specify this parameter. The\n#   default is true if position_endstop is near position_max and false\n#   if near position_min.\n#use_sensorless_homing:\n#   If true, disables the second home action if homing_retract_dist > 0.\n#   The default is true if endstop_pin is configured to use virtual_endstop\n
    "},{"location":"Config_Reference.html#cartesian-kinematics","title":"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]\nkinematics: cartesian\nmax_z_velocity:\n#   This sets the maximum velocity (in mm/s) of movement along the z\n#   axis. This setting can be used to restrict the maximum speed of\n#   the z stepper motor. The default is to use max_velocity for\n#   max_z_velocity.\nmax_z_accel:\n#   This sets the maximum acceleration (in mm/s^2) of movement along\n#   the z axis. It limits the acceleration of the z stepper motor. The\n#   default is to use max_accel for max_z_accel.\n\n# The stepper_x section is used to describe the stepper controlling\n# the X axis in a cartesian robot.\n[stepper_x]\n\n# The stepper_y section is used to describe the stepper controlling\n# the Y axis in a cartesian robot.\n[stepper_y]\n\n# The stepper_z section is used to describe the stepper controlling\n# the Z axis in a cartesian robot.\n[stepper_z]\n
    "},{"location":"Config_Reference.html#cartesian-kinematics-with-limits-for-x-and-y-axes","title":"\u26a0\ufe0f Cartesian Kinematics with limits for X and Y axes","text":"

    Behaves exactly the as cartesian kinematics, but allows to set a velocity and acceleration limit for X and Y axis. This also makes command SET_KINEMATICS_LIMIT available to sets these limits at runtime.

    [printer]\nkinematics: limited_cartesian\nmax_x_velocity:\n#   This sets the maximum velocity (in mm/s) of movement along the x\n#   axis. This setting can be used to restrict the maximum speed of\n#   the x stepper motor. The default is to use max_velocity for\n#   max_x_velocity.\nmax_y_velocity:\n#   This sets the maximum velocity (in mm/s) of movement along the y\n#   axis. This setting can be used to restrict the maximum speed of\n#   the y stepper motor. The default is to use max_velocity for\n#   max_x_velocity.\nmax_z_velocity:\n#   See cartesian above.\nmax_velocity:\n#   In order to get maximum velocity gains on diagonals, this should be equal or\n#   greater than the hypotenuse (sqrt(x*x + y*y)) of max_x_velocity and\n#   max_y_velocity.\nmax_x_accel:\n#   This sets the maximum acceleration (in mm/s^2) of movement along\n#   the x axis. It limits the acceleration of the x stepper motor. The\n#   default is to use max_accel for max_x_accel.\nmax_y_accel:\n#   This sets the maximum acceleration (in mm/s^2) of movement along\n#   the y axis. It limits the acceleration of the y stepper motor. The\n#   default is to use max_accel for max_y_accel.\nmax_z_accel:\n# See cartesian above.\nmax_accel:\n# See cartesian above.\nscale_xy_accel: False\n#   When true, scales the XY limits by the current tool head acceleration.\n#   The factor is: slicer accel / hypot(max_x_accel, max_y_accel).\n#   See below.\n

    If scale_xy_accel is False, the acceleration set by max_accel, M204 or SET_VELOCITY_LIMIT, acts as a third limit. In that case, this module doesn't apply limitations on moves having an acceleration lower than max_x_accel`` andmax_y_accel. When scale_xy_accel isTrue,max_x_accelandmax_y_accelare scaled by the ratio of the dynamically set acceleration and the hypotenuse of max_x_accel andmax_y_accel, as reported fromSET_KINEMATICS_LIMIT`. This implies that the actual acceleration will always depend on the direction. For example, these settings:

    [printer]\nmax_x_accel: 12000\nmax_y_accel: 9000\nscale_xy_accel: true\n

    SET_KINEMATICS_LIMIT will report a maximum acceleration of 15000 mm/s^2 on 37\u00b0 diagonals. If the slicer emit M204 S3000 (3000 mm/s^2 accel). On these 37\u00b0 and 143\u00b0 diagonals, the toolhead will accelerate at 3000 mm/s^2. On the X axis, the acceleration will be 12000 * 3000 / 15000 = 2400 mm/s^2, and 18000 mm/s^2 for pure Y moves.

    [printer]\nkinematics: delta\nmax_z_velocity:\n#   For delta printers this limits the maximum velocity (in mm/s) of\n#   moves with z axis movement. This setting can be used to reduce the\n#   maximum speed of up/down moves (which require a higher step rate\n#   than other moves on a delta printer). The default is to use\n#   max_velocity for max_z_velocity.\n#max_z_accel:\n#   This sets the maximum acceleration (in mm/s^2) of movement along\n#   the z axis. Setting this may be useful if the printer can reach higher\n#   acceleration on XY moves than Z moves (eg, when using input shaper).\n#   The default is to use max_accel for max_z_accel.\n#minimum_z_position: 0\n#   The minimum Z position that the user may command the head to move\n#   to. The default is 0.\ndelta_radius:\n#   Radius (in mm) of the horizontal circle formed by the three linear\n#   axis towers. This parameter may also be calculated as:\n#    delta_radius = smooth_rod_offset - effector_offset - carriage_offset\n#   This parameter must be provided.\n#print_radius:\n#   The radius (in mm) of valid toolhead XY coordinates. One may use\n#   this setting to customize the range checking of toolhead moves. If\n#   a large value is specified here then it may be possible to command\n#   the toolhead into a collision with a tower. The default is to use\n#   delta_radius for print_radius (which would normally prevent a\n#   tower collision).\n\n# The stepper_a section describes the stepper controlling the front\n# left tower (at 210 degrees). This section also controls the homing\n# parameters (homing_speed, homing_retract_dist) for all towers.\n[stepper_a]\nposition_endstop:\n#   Distance (in mm) between the nozzle and the bed when the nozzle is\n#   in the center of the build area and the endstop triggers. This\n#   parameter must be provided for stepper_a; for stepper_b and\n#   stepper_c this parameter defaults to the value specified for\n#   stepper_a.\narm_length:\n#   Length (in mm) of the diagonal rod that connects this tower to the\n#   print head. This parameter must be provided for stepper_a; for\n#   stepper_b and stepper_c this parameter defaults to the value\n#   specified for stepper_a.\n#angle:\n#   This option specifies the angle (in degrees) that the tower is\n#   at. The default is 210 for stepper_a, 330 for stepper_b, and 90\n#   for stepper_c.\n\n# The stepper_b section describes the stepper controlling the front\n# right tower (at 330 degrees).\n[stepper_b]\n\n# The stepper_c section describes the stepper controlling the rear\n# tower (at 90 degrees).\n[stepper_c]\n\n# The delta_calibrate section enables a DELTA_CALIBRATE extended\n# g-code command that can calibrate the tower endstop positions and\n# angles.\n[delta_calibrate]\nradius:\n#   Radius (in mm) of the area that may be probed. This is the radius\n#   of nozzle coordinates to be probed; if using an automatic probe\n#   with an XY offset then choose a radius small enough so that the\n#   probe always fits over the bed. This parameter must be provided.\n#speed: 50\n#   The speed (in mm/s) of non-probing moves during the calibration.\n#   The default is 50.\n#horizontal_move_z: 5\n#   The height (in mm) that the head should be commanded to move to\n#   just prior to starting a probe operation. The default is 5.\n#use_probe_xy_offsets: False\n#   If True, apply the `[probe]` XY offsets to the probed positions. The\n#   default is False.\n
    "},{"location":"Config_Reference.html#deltesian-kinematics","title":"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]\nkinematics: deltesian\nmax_z_velocity:\n#   For deltesian printers, this limits the maximum velocity (in mm/s) of\n#   moves with z axis movement. This setting can be used to reduce the\n#   maximum speed of up/down moves (which require a higher step rate\n#   than other moves on a deltesian printer). The default is to use\n#   max_velocity for max_z_velocity.\n#max_z_accel:\n#   This sets the maximum acceleration (in mm/s^2) of movement along\n#   the z axis. Setting this may be useful if the printer can reach higher\n#   acceleration on XY moves than Z moves (eg, when using input shaper).\n#   The default is to use max_accel for max_z_accel.\n#minimum_z_position: 0\n#   The minimum Z position that the user may command the head to move\n#   to. The default is 0.\n#min_angle: 5\n#   This represents the minimum angle (in degrees) relative to horizontal\n#   that the deltesian arms are allowed to achieve. This parameter is\n#   intended to restrict the arms from becoming completely horizontal,\n#   which would risk accidental inversion of the XZ axis. The default is 5.\n#print_width:\n#   The distance (in mm) of valid toolhead X coordinates. One may use\n#   this setting to customize the range checking of toolhead moves. If\n#   a large value is specified here then it may be possible to command\n#   the toolhead into a collision with a tower. This setting usually\n#   corresponds to bed width (in mm).\n#slow_ratio: 3\n#   The ratio used to limit velocity and acceleration on moves near the\n#   extremes of the X axis. If vertical distance divided by horizontal\n#   distance exceeds the value of slow_ratio, then velocity and\n#   acceleration are limited to half their nominal values. If vertical\n#   distance divided by horizontal distance exceeds twice the value of\n#   the slow_ratio, then velocity and acceleration are limited to one\n#   quarter of their nominal values. The default is 3.\n\n# The stepper_left section is used to describe the stepper controlling\n# the left tower. This section also controls the homing parameters\n# (homing_speed, homing_retract_dist) for all towers.\n[stepper_left]\nposition_endstop:\n#   Distance (in mm) between the nozzle and the bed when the nozzle is\n#   in the center of the build area and the endstops are triggered. This\n#   parameter must be provided for stepper_left; for stepper_right this\n#   parameter defaults to the value specified for stepper_left.\narm_length:\n#   Length (in mm) of the diagonal rod that connects the tower carriage to\n#   the print head. This parameter must be provided for stepper_left; for\n#   stepper_right, this parameter defaults to the value specified for\n#   stepper_left.\narm_x_length:\n#   Horizontal distance between the print head and the tower when the\n#   printers is homed. This parameter must be provided for stepper_left;\n#   for stepper_right, this parameter defaults to the value specified for\n#   stepper_left.\n\n# The stepper_right section is used to describe the stepper controlling the\n# right tower.\n[stepper_right]\n\n# The stepper_y section is used to describe the stepper controlling\n# the Y axis in a deltesian robot.\n[stepper_y]\n
    "},{"location":"Config_Reference.html#corexy-kinematics","title":"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]\nkinematics: corexy\nmax_z_velocity:\n#   This sets the maximum velocity (in mm/s) of movement along the z\n#   axis. This setting can be used to restrict the maximum speed of\n#   the z stepper motor. The default is to use max_velocity for\n#   max_z_velocity.\nmax_z_accel:\n#   This sets the maximum acceleration (in mm/s^2) of movement along\n#   the z axis. It limits the acceleration of the z stepper motor. The\n#   default is to use max_accel for max_z_accel.\n\n# The stepper_x section is used to describe the X axis as well as the\n# stepper controlling the X+Y movement.\n[stepper_x]\n\n# The stepper_y section is used to describe the Y axis as well as the\n# stepper controlling the X-Y movement.\n[stepper_y]\n\n# The stepper_z section is used to describe the stepper controlling\n# the Z axis.\n[stepper_z]\n
    "},{"location":"Config_Reference.html#corexy-kinematics-with-limits-for-x-and-y-axes","title":"\u26a0\ufe0f CoreXY Kinematics with limits for X and Y axes","text":"

    Behaves exactly the as CoreXY kinematics, but allows to set a acceleration limit for X and Y axis.

    There is no velocity limits for X and Y, since on a CoreXY the pull-out velocity are identical on both axes.

    [printer]\nkinematics: limited_corexy\nmax_z_velocity:\n#   See CoreXY above.\nmax_x_accel:\n#   This sets the maximum acceleration (in mm/s^2) of movement along\n#   the x axis. It limits the acceleration of the x stepper motor. The\n#   default is to use max_accel for max_x_accel.\nmax_y_accel:\n#   This sets the maximum acceleration (in mm/s^2) of movement along\n#   the y axis. It limits the acceleration of the y stepper motor. The\n#   default is to use max_accel for max_y_accel.\nmax_z_accel:\n# See CoreXY above.\nmax_accel:\n# See CoreXY above..\nscale_xy_accel:\n#   When True, scales the XY limits by the current tool head acceleration.\n#   The factor is: slicer accel / max(max_x_accel, max_y_accel).\n
    "},{"location":"Config_Reference.html#corexz-kinematics","title":"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]\nkinematics: corexz\nmax_z_velocity:\n#   This sets the maximum velocity (in mm/s) of movement along the z\n#   axis. The default is to use max_velocity for max_z_velocity.\nmax_z_accel:\n#   This sets the maximum acceleration (in mm/s^2) of movement along\n#   the z axis. The default is to use max_accel for max_z_accel.\n\n# The stepper_x section is used to describe the X axis as well as the\n# stepper controlling the X+Z movement.\n[stepper_x]\n\n# The stepper_y section is used to describe the stepper controlling\n# the Y axis.\n[stepper_y]\n\n# The stepper_z section is used to describe the Z axis as well as the\n# stepper controlling the X-Z movement.\n[stepper_z]\n
    "},{"location":"Config_Reference.html#corexz-kinematics-with-limits-for-x-and-y-axes","title":"\u26a0\ufe0f CoreXZ Kinematics with limits for X and Y axes","text":"
    [printer]\nkinematics: limited_corexz\nmax_velocity: 500 # Hypotenuse of the two values bellow\nmax_x_velocity: 400\nmax_y_velocity: 300\nmax_z_velocity: 5\nmax_accel: 1500 # Default acceleration of your choice\nmax_x_accel: 12000\nmax_y_accel: 9000\nmax_z_accel: 100\nscale_xy_accel: [True/False, default False]\n

    max_velocity is usually the hypotenuses of X and Y velocity, For example: with max_x_velocity: 300 and max_y_velocity: 400, the recommended value is max_velocity: 500.

    If scale_xy_accel is False, max_accel, set by M204 or SET_VELOCITY_LIMIT, acts as a third limit. In that case, this module doesn't apply limitations to moves with an acceleration lower than max_x_accel and max_y_accel.

    When scale_xy_accel is True, max_x_accel and max_y_accel are scaled by the ratio of the dynamically set acceleration and the hypotenuse of max_x_accel and max_y_accel, as reported from SET_KINEMATICS_LIMIT. This means that the actual acceleration will always depend on the direction.

    For example with these settings:

    [printer]\nmax_x_accel: 12000\nmax_y_accel: 9000\nscale_xy_accel: True\n

    SET_KINEMATICS_LIMIT will report a maximum acceleration of 15000 mm/s^2 on 37 degrees diagonals. Thus, setting an acceleration of 3000 mm/s^2 in the slicer will make the toolhead accelerate at 3000 mm/s^2 on these 37 and 143 degrees diagonals, but only 12000 * 3000 / 15000 = 2400 mm/s^2 for moves aligned with the X axis and 18000 mm/s^2 for pure Y moves.

    "},{"location":"Config_Reference.html#hybrid-corexy-kinematics","title":"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]\nkinematics: hybrid_corexy\ninvert_kinematics: False\n# \u26a0\ufe0f Some hybrid_corexy machines with dual carriages may need to\n#   invert the kinematics if the toolheads move in reverse\nmax_z_velocity:\n#   This sets the maximum velocity (in mm/s) of movement along the z\n#   axis. The default is to use max_velocity for max_z_velocity.\nmax_z_accel:\n#   This sets the maximum acceleration (in mm/s^2) of movement along\n#   the z axis. The default is to use max_accel for max_z_accel.\n\n# The stepper_x section is used to describe the X axis as well as the\n# stepper controlling the X-Y movement.\n[stepper_x]\n\n# The stepper_y section is used to describe the stepper controlling\n# the Y axis.\n[stepper_y]\n\n# The stepper_z section is used to describe the stepper controlling\n# the Z axis.\n[stepper_z]\n
    "},{"location":"Config_Reference.html#hybrid-corexz-kinematics","title":"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]\nkinematics: hybrid_corexz\ninvert_kinematics: False\n# \u26a0\ufe0f Some hybrid_corexy machines with dual carriages may need to\n#   invert the kinematics if the toolheads move in reverse\nmax_z_velocity:\n#   This sets the maximum velocity (in mm/s) of movement along the z\n#   axis. The default is to use max_velocity for max_z_velocity.\nmax_z_accel:\n#   This sets the maximum acceleration (in mm/s^2) of movement along\n#   the z axis. The default is to use max_accel for max_z_accel.\n\n# The stepper_x section is used to describe the X axis as well as the\n# stepper controlling the X-Z movement.\n[stepper_x]\n\n# The stepper_y section is used to describe the stepper controlling\n# the Y axis.\n[stepper_y]\n\n# The stepper_z section is used to describe the stepper controlling\n# the Z axis.\n[stepper_z]\n
    "},{"location":"Config_Reference.html#polar-kinematics","title":"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]\nkinematics: polar\nmax_z_velocity:\n#   This sets the maximum velocity (in mm/s) of movement along the z\n#   axis. This setting can be used to restrict the maximum speed of\n#   the z stepper motor. The default is to use max_velocity for\n#   max_z_velocity.\nmax_z_accel:\n#   This sets the maximum acceleration (in mm/s^2) of movement along\n#   the z axis. It limits the acceleration of the z stepper motor. The\n#   default is to use max_accel for max_z_accel.\n\n# The stepper_bed section is used to describe the stepper controlling\n# the bed.\n[stepper_bed]\ngear_ratio:\n#   A gear_ratio must be specified and rotation_distance may not be\n#   specified. For example, if the bed has an 80 toothed pulley driven\n#   by a stepper with a 16 toothed pulley then one would specify a\n#   gear ratio of \"80:16\". This parameter must be provided.\n\n# The stepper_arm section is used to describe the stepper controlling\n# the carriage on the arm.\n[stepper_arm]\n\n# The stepper_z section is used to describe the stepper controlling\n# the Z axis.\n[stepper_z]\n
    "},{"location":"Config_Reference.html#rotary-delta-kinematics","title":"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]\nkinematics: rotary_delta\nmax_z_velocity:\n#   For delta printers this limits the maximum velocity (in mm/s) of\n#   moves with z axis movement. This setting can be used to reduce the\n#   maximum speed of up/down moves (which require a higher step rate\n#   than other moves on a delta printer). The default is to use\n#   max_velocity for max_z_velocity.\n#minimum_z_position: 0\n#   The minimum Z position that the user may command the head to move\n#   to.  The default is 0.\nshoulder_radius:\n#   Radius (in mm) of the horizontal circle formed by the three\n#   shoulder joints, minus the radius of the circle formed by the\n#   effector joints. This parameter may also be calculated as:\n#     shoulder_radius = (delta_f - delta_e) / sqrt(12)\n#   This parameter must be provided.\nshoulder_height:\n#   Distance (in mm) of the shoulder joints from the bed, minus the\n#   effector toolhead height. This parameter must be provided.\n\n# The stepper_a section describes the stepper controlling the rear\n# right arm (at 30 degrees). This section also controls the homing\n# parameters (homing_speed, homing_retract_dist) for all arms.\n[stepper_a]\ngear_ratio:\n#   A gear_ratio must be specified and rotation_distance may not be\n#   specified. For example, if the arm has an 80 toothed pulley driven\n#   by a pulley with 16 teeth, which is in turn connected to a 60\n#   toothed pulley driven by a stepper with a 16 toothed pulley, then\n#   one would specify a gear ratio of \"80:16, 60:16\". This parameter\n#   must be provided.\nposition_endstop:\n#   Distance (in mm) between the nozzle and the bed when the nozzle is\n#   in the center of the build area and the endstop triggers. This\n#   parameter must be provided for stepper_a; for stepper_b and\n#   stepper_c this parameter defaults to the value specified for\n#   stepper_a.\nupper_arm_length:\n#   Length (in mm) of the arm connecting the \"shoulder joint\" to the\n#   \"elbow joint\". This parameter must be provided for stepper_a; for\n#   stepper_b and stepper_c this parameter defaults to the value\n#   specified for stepper_a.\nlower_arm_length:\n#   Length (in mm) of the arm connecting the \"elbow joint\" to the\n#   \"effector joint\". This parameter must be provided for stepper_a;\n#   for stepper_b and stepper_c this parameter defaults to the value\n#   specified for stepper_a.\n#angle:\n#   This option specifies the angle (in degrees) that the arm is at.\n#   The default is 30 for stepper_a, 150 for stepper_b, and 270 for\n#   stepper_c.\n\n# The stepper_b section describes the stepper controlling the rear\n# left arm (at 150 degrees).\n[stepper_b]\n\n# The stepper_c section describes the stepper controlling the front\n# arm (at 270 degrees).\n[stepper_c]\n\n# The delta_calibrate section enables a DELTA_CALIBRATE extended\n# g-code command that can calibrate the shoulder endstop positions.\n[delta_calibrate]\nradius:\n#   Radius (in mm) of the area that may be probed. This is the radius\n#   of nozzle coordinates to be probed; if using an automatic probe\n#   with an XY offset then choose a radius small enough so that the\n#   probe always fits over the bed. This parameter must be provided.\n#speed: 50\n#   The speed (in mm/s) of non-probing moves during the calibration.\n#   The default is 50.\n#horizontal_move_z: 5\n#   The height (in mm) that the head should be commanded to move to\n#   just prior to starting a probe operation. The default is 5.\n
    "},{"location":"Config_Reference.html#cable-winch-kinematics","title":"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]\nkinematics: winch\n\n# The stepper_a section describes the stepper connected to the first\n# cable winch. A minimum of 3 and a maximum of 26 cable winches may be\n# defined (stepper_a to stepper_z) though it is common to define 4.\n[stepper_a]\nrotation_distance:\n#   The rotation_distance is the nominal distance (in mm) the toolhead\n#   moves towards the cable winch for each full rotation of the\n#   stepper motor. This parameter must be provided.\nanchor_x:\nanchor_y:\nanchor_z:\n#   The X, Y, and Z position of the cable winch in cartesian space.\n#   These parameters must be provided.\n
    "},{"location":"Config_Reference.html#none-kinematics","title":"None Kinematics","text":"

    It is possible to define a special \"none\" kinematics to disable kinematic support in Kalico. This may be useful for controlling devices that are not typical 3d-printers or for debugging purposes.

    [printer]\nkinematics: none\nmax_velocity: 1\nmax_accel: 1\n#   The max_velocity and max_accel parameters must be defined. The\n#   values are not used for \"none\" kinematics.\n
    "},{"location":"Config_Reference.html#common-extruder-and-heated-bed-support","title":"Common extruder and heated bed support","text":""},{"location":"Config_Reference.html#extruder","title":"[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. See PID or MPC for more detailed information about the control methods.

    [extruder]\nstep_pin:\ndir_pin:\nenable_pin:\nmicrosteps:\nrotation_distance:\n#full_steps_per_rotation:\n#gear_ratio:\n#   See the \"stepper\" section for a description of the above\n#   parameters. If none of the above parameters are specified then no\n#   stepper will be associated with the nozzle hotend (though a\n#   SYNC_EXTRUDER_MOTION command may associate one at run-time).\nnozzle_diameter:\n#   Diameter of the nozzle orifice (in mm). This parameter must be\n#   provided.\nfilament_diameter:\n#   The nominal diameter of the raw filament (in mm) as it enters the\n#   extruder. This parameter must be provided.\n#max_extrude_cross_section:\n#   Maximum area (in mm^2) of an extrusion cross section (eg,\n#   extrusion width multiplied by layer height). This setting prevents\n#   excessive amounts of extrusion during relatively small XY moves.\n#   If a move requests an extrusion rate that would exceed this value\n#   it will cause an error to be returned. The default is: 4.0 *\n#   nozzle_diameter^2\n#instantaneous_corner_velocity: 1.000\n#   The maximum instantaneous velocity change (in mm/s) of the\n#   extruder during the junction of two moves. The default is 1mm/s.\n#max_extrude_only_distance: 50.0\n#   Maximum length (in mm of raw filament) that a retraction or\n#   extrude-only move may have. If a retraction or extrude-only move\n#   requests a distance greater than this value it will cause an error\n#   to be returned. The default is 50mm.\n#max_extrude_only_velocity:\n#max_extrude_only_accel:\n#   Maximum velocity (in mm/s) and acceleration (in mm/s^2) of the\n#   extruder motor for retractions and extrude-only moves. These\n#   settings do not have any impact on normal printing moves. If not\n#   specified then they are calculated to match the limit an XY\n#   printing move with a cross section of 4.0*nozzle_diameter^2 would\n#   have.\n#pressure_advance: 0.0\n#   The amount of raw filament to push into the extruder during\n#   extruder acceleration. An equal amount of filament is retracted\n#   during deceleration. It is measured in millimeters per\n#   millimeter/second. The default is 0, which disables pressure\n#   advance.\n#pressure_advance_smooth_time: 0.040\n#   A time range (in seconds) to use when calculating the average\n#   extruder velocity for pressure advance. A larger value results in\n#   smoother extruder movements. This parameter may not exceed 200ms.\n#   This setting only applies if pressure_advance is non-zero. The\n#   default is 0.040 (40 milliseconds).\n#\n# The remaining variables describe the extruder heater.\nheater_pin:\n#   PWM output pin controlling the heater. This parameter must be\n#   provided.\n#max_power: 1.0\n#   The maximum power (expressed as a value from 0.0 to 1.0) that the\n#   heater_pin may be set to. The value 1.0 allows the pin to be set\n#   fully enabled for extended periods, while a value of 0.5 would\n#   allow the pin to be enabled for no more than half the time. This\n#   setting may be used to limit the total power output (over extended\n#   periods) to the heater. The default is 1.0.\nsensor_type:\n#   Type of sensor - common thermistors are \"EPCOS 100K B57560G104F\",\n#   \"ATC Semitec 104GT-2\", \"ATC Semitec 104NT-4-R025H42G\", \"Generic\n#   3950\",\"Honeywell 100K 135-104LAG-J01\", \"NTC 100K MGB18-104F39050L32\",\n#   \"SliceEngineering 450\", and \"TDK NTCG104LH104JT1\". See the\n#   \"Temperature sensors\" section for other sensors. This parameter\n#   must be provided.\nsensor_pin:\n#   Analog input pin connected to the sensor. This parameter must be\n#   provided.\n#pullup_resistor: 4700\n#   The resistance (in ohms) of the pullup attached to the thermistor.\n#   This parameter is only valid when the sensor is a thermistor. The\n#   default is 4700 ohms.\n#smooth_time: 1.0\n#   A time value (in seconds) over which temperature measurements will\n#   be smoothed to reduce the impact of measurement noise. The default\n#   is 1 seconds.\ncontrol:\n#   Control algorithm (either pid, pid_v, watermark or mpc). This parameter must\n#   be provided. pid_v should only be used on well calibrated heaters with\n#   low to moderate noise.\n#\n#   If control: pid or pid_v\n#pid_Kp:\n#pid_Ki:\n#pid_Kd:\n#   The proportional (pid_Kp), integral (pid_Ki), and derivative\n#   (pid_Kd) settings for the PID feedback control system. Kalico\n#   evaluates the PID settings with the following general formula:\n#     heater_pwm = (Kp*error + Ki*integral(error) - Kd*derivative(error)) / 255\n#   Where \"error\" is \"requested_temperature - measured_temperature\"\n#   and \"heater_pwm\" is the requested heating rate with 0.0 being full\n#   off and 1.0 being full on. Consider using the PID_CALIBRATE\n#   command to obtain these parameters. The pid_Kp, pid_Ki, and pid_Kd\n#   parameters must be provided for PID heaters.\n#\n#   If control: watermark\n#max_delta: 2.0\n#   On 'watermark' controlled heaters this is the number of degrees in\n#   Celsius above the target temperature before disabling the heater\n#   as well as the number of degrees below the target before\n#   re-enabling the heater. The default is 2 degrees Celsius.\n#\n#   If control: mpc\n#   See MPC.md for details about these parameters.\n#heater_power:\n#cooling_fan:\n#ambient_temp_sensor:\n#filament_diameter: 1.75\n#filament_density: 1.2\n#filament_heat_capacity: 1.8\n#\n#pwm_cycle_time: 0.100\n#   Time in seconds for each software PWM cycle of the heater. It is\n#   not recommended to set this unless there is an electrical\n#   requirement to switch the heater faster than 10 times a second.\n#   The default is 0.100 seconds.\n#min_extrude_temp: 170\n#   The minimum temperature (in Celsius) at which extruder move\n#   commands may be issued. The default is 170 Celsius.\nmin_temp:\nmax_temp:\n#   The maximum range of valid temperatures (in Celsius) that the\n#   heater must remain within. This controls a safety feature\n#   implemented in the micro-controller code - should the measured\n#   temperature ever fall outside this range then the micro-controller\n#   will go into a shutdown state. This check can help detect some\n#   heater and sensor hardware failures. Set this range just wide\n#   enough so that reasonable temperatures do not result in an error.\n#   These parameters must be provided.\nper_move_pressure_advance: False\n#   If true, uses pressure advance constant from trapq when processing moves\n#   This causes changes to pressure advance be taken into account immediately,\n#   for all moves in the current queue, rather than ~250ms later once the queue gets flushed\n
    "},{"location":"Config_Reference.html#heater_bed","title":"[heater_bed]","text":"

    The heater_bed section describes a heated bed. It uses the same heater settings described in the \"extruder\" section.

    [heater_bed]\nheater_pin:\nsensor_type:\nsensor_pin:\ncontrol:\nmin_temp:\nmax_temp:\n#   See the \"extruder\" section for a description of the above parameters.\n
    "},{"location":"Config_Reference.html#pid_profile","title":"[pid_profile]","text":"

    Pid Profiles specify a set of PID values that can be loaded at runtime.

    [pid_profile <heater> <profile-name>]\npid_version: 1\n# This defines the version it was saved with and is important for compatibility\n# checks, leave it at 1!\npid_target:\n# For reference only, specifies the temperature the profile was calibrated for.\n# If you create a custom profile, either enter the temperature that profile is\n# intended to be used at or leave it blank.\npid_tolerance: \n# The tolerance that was used when autocalibrating the profile. If you define\n# a custom profile, leave it empty.\ncontrol: <pid|pid_v>\n# Has to be either pid or pid_v.\n# This parameter is required.\npid_kp: \n# The P value for the PID Control.\n# This parameter is required.\npid_ki:\n# The I value for the PID Control.\n# This parameter is required.\npid_kd: \n# The D value for the PID Control.\n# This parameter is required.\n

    For more information, read up on docs/PID.md

    "},{"location":"Config_Reference.html#bed-level-support","title":"Bed level support","text":""},{"location":"Config_Reference.html#bed_mesh","title":"[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:\n             x---x---x (max_point)\n             |\n             x---x---x\n                     |\n (min_point) x---x---x\n\n round bed, round_probe_count = 5, bed_radius = r:\n                 x (0, r) end\n               /\n             x---x---x\n                       \\\n (-r, 0) x---x---x---x---x (r, 0)\n           \\\n             x---x---x\n                   /\n                 x  (0, -r) start\n
    [bed_mesh]\n#speed: 50\n#   The speed (in mm/s) of non-probing moves during the calibration.\n#   The default is 50.\n#horizontal_move_z: 5\n#   The height (in mm) that the head should be commanded to move to\n#   just prior to starting a probe operation. The default is 5.\n#mesh_radius:\n#   Defines the radius of the mesh to probe for round beds. Note that\n#   the radius is relative to the coordinate specified by the\n#   mesh_origin option. This parameter must be provided for round beds\n#   and omitted for rectangular beds.\n#mesh_origin:\n#   Defines the center X, Y coordinate of the mesh for round beds. This\n#   coordinate is relative to the probe's location. It may be useful\n#   to adjust the mesh_origin in an effort to maximize the size of the\n#   mesh radius. Default is 0, 0. This parameter must be omitted for\n#   rectangular beds.\n#mesh_min:\n#   Defines the minimum X, Y coordinate of the mesh for rectangular\n#   beds. This coordinate is relative to the probe's location. This\n#   will be the first point probed, nearest to the origin. This\n#   parameter must be provided for rectangular beds.\n#mesh_max:\n#   Defines the maximum X, Y coordinate of the mesh for rectangular\n#   beds. Adheres to the same principle as mesh_min, however this will\n#   be the furthest point probed from the bed's origin. This parameter\n#   must be provided for rectangular beds.\n#probe_count: 3, 3\n#   For rectangular beds, this is a comma separate pair of integer\n#   values X, Y defining the number of points to probe along each\n#   axis. A single value is also valid, in which case that value will\n#   be applied to both axes. Default is 3, 3.\n#round_probe_count: 5\n#   For round beds, this integer value defines the maximum number of\n#   points to probe along each axis. This value must be an odd number.\n#   Default is 5.\n#fade_start: 1.0\n#   The gcode z position in which to start phasing out z-adjustment\n#   when fade is enabled. Default is 1.0.\n#fade_end: 0.0\n#   The gcode z position in which phasing out completes. When set to a\n#   value below fade_start, fade is disabled. It should be noted that\n#   fade may add unwanted scaling along the z-axis of a print. If a\n#   user wishes to enable fade, a value of 10.0 is recommended.\n#   Default is 0.0, which disables fade.\n#fade_target:\n#   The z position in which fade should converge. When this value is\n#   set to a non-zero value it must be within the range of z-values in\n#   the mesh. Users that wish to converge to the z homing position\n#   should set this to 0. Default is the average z value of the mesh.\n#split_delta_z: .025\n#   The amount of Z difference (in mm) along a move that will trigger\n#   a split. Default is .025.\n#move_check_distance: 5.0\n#   The distance (in mm) along a move to check for split_delta_z.\n#   This is also the minimum length that a move can be split. Default\n#   is 5.0.\n#mesh_pps: 2, 2\n#   A comma separated pair of integers X, Y defining the number of\n#   points per segment to interpolate in the mesh along each axis. A\n#   \"segment\" can be defined as the space between each probed point.\n#   The user may enter a single value which will be applied to both\n#   axes. Default is 2, 2.\n#algorithm: lagrange\n#   The interpolation algorithm to use. May be either \"lagrange\" or\n#   \"bicubic\". This option will not affect 3x3 grids, which are forced\n#   to use lagrange sampling. Default is lagrange.\n#bicubic_tension: .2\n#   When using the bicubic algorithm the tension parameter above may\n#   be applied to change the amount of slope interpolated. Larger\n#   numbers will increase the amount of slope, which results in more\n#   curvature in the mesh. Default is .2.\n#zero_reference_position:\n#   An optional X,Y coordinate that specifies the location on the bed\n#   where Z = 0.  When this option is specified the mesh will be offset\n#   so that zero Z adjustment occurs at this location.  The default is\n#   no zero reference.\n#faulty_region_1_min:\n#faulty_region_1_max:\n#   Optional points that define a faulty region.  See docs/Bed_Mesh.md\n#   for details on faulty regions.  Up to 99 faulty regions may be added.\n#   By default no faulty regions are set.\n#adaptive_margin:\n#   An optional margin (in mm) to be added around the bed area used by\n#   the defined print objects when generating an adaptive mesh.\n#bed_mesh_default:\n#   Optionally provide the name of a profile you would like loaded on init.\n#   By default, no profile is loaded.\n#use_probe_xy_offsets: True\n#   If True, apply the `[probe]` XY offsets to the probed positions. The\n#   default is True.\n
    "},{"location":"Config_Reference.html#bed_tilt","title":"[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]\n#x_adjust: 0\n#   The amount to add to each move's Z height for each mm on the X\n#   axis. The default is 0.\n#y_adjust: 0\n#   The amount to add to each move's Z height for each mm on the Y\n#   axis. The default is 0.\n#z_adjust: 0\n#   The amount to add to the Z height when the nozzle is nominally at\n#   0, 0. The default is 0.\n# The remaining parameters control a BED_TILT_CALIBRATE extended\n# g-code command that may be used to calibrate appropriate x and y\n# adjustment parameters.\n#points:\n#   A list of X, Y coordinates (one per line; subsequent lines\n#   indented) that should be probed during a BED_TILT_CALIBRATE\n#   command. Specify coordinates of the nozzle and be sure the probe\n#   is above the bed at the given nozzle coordinates. The default is\n#   to not enable the command.\n#speed: 50\n#   The speed (in mm/s) of non-probing moves during the calibration.\n#   The default is 50.\n#horizontal_move_z: 5\n#   The height (in mm) that the head should be commanded to move to\n#   just prior to starting a probe operation. The default is 5.\n#use_probe_xy_offsets: False\n#   If True, apply the `[probe]` XY offsets to the probed positions. The\n#   default is False.\n
    "},{"location":"Config_Reference.html#bed_screws","title":"[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]\n#screw1:\n#   The X, Y coordinate of the first bed leveling screw. This is a\n#   position to command the nozzle to that is directly above the bed\n#   screw (or as close as possible while still being above the bed).\n#   This parameter must be provided.\n#screw1_name:\n#   An arbitrary name for the given screw. This name is displayed when\n#   the helper script runs. The default is to use a name based upon\n#   the screw XY location.\n#screw1_fine_adjust:\n#   An X, Y coordinate to command the nozzle to so that one can fine\n#   tune the bed leveling screw. The default is to not perform fine\n#   adjustments on the bed screw.\n#screw2:\n#screw2_name:\n#screw2_fine_adjust:\n#...\n#   Additional bed leveling screws. At least three screws must be\n#   defined.\n#horizontal_move_z: 5\n#   The height (in mm) that the head should be commanded to move to\n#   when moving from one screw location to the next. The default is 5.\n#probe_height: 0\n#   The height of the probe (in mm) after adjusting for the thermal\n#   expansion of bed and nozzle. The default is zero.\n#speed: 50\n#   The speed (in mm/s) of non-probing moves during the calibration.\n#   The default is 50.\n#probe_speed: 5\n#   The speed (in mm/s) when moving from a horizontal_move_z position\n#   to a probe_height position. The default is 5.\n
    "},{"location":"Config_Reference.html#screws_tilt_adjust","title":"[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]\n#screw1:\n#   The (X, Y) coordinate of the first bed leveling screw. This is a\n#   position to command the nozzle to so that the probe is directly\n#   above the bed screw (or as close as possible while still being\n#   above the bed). This is the base screw used in calculations. This\n#   parameter must be provided.\n#screw1_name:\n#   An arbitrary name for the given screw. This name is displayed when\n#   the helper script runs. The default is to use a name based upon\n#   the screw XY location.\n#screw2:\n#screw2_name:\n#...\n#   Additional bed leveling screws. At least two screws must be\n#   defined.\n#speed: 50\n#   The speed (in mm/s) of non-probing moves during the calibration.\n#   The default is 50.\n#horizontal_move_z: 5\n#   The height (in mm) that the head should be commanded to move to\n#   just prior to starting a probe operation. The default is 5.\n#screw_thread: CW-M3\n#   The type of screw used for bed leveling, M3, M4, or M5, and the\n#   rotation direction of the knob that is used to level the bed.\n#   Accepted values: CW-M3, CCW-M3, CW-M4, CCW-M4, CW-M5, CCW-M5, CW-M8, CCW-M8.\n#   Default value is CW-M3 which most printers use. A clockwise\n#   rotation of the knob decreases the gap between the nozzle and the\n#   bed. Conversely, a counter-clockwise rotation increases the gap.\n#use_probe_xy_offsets: False\n#   If True, apply the `[probe]` XY offsets to the probed positions. The\n#   default is False.\n
    "},{"location":"Config_Reference.html#z_tilt","title":"[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]\n#z_positions:\n#   A list of X, Y coordinates (one per line; subsequent lines\n#   indented) describing the location of each bed \"pivot point\". The\n#   \"pivot point\" is the point where the bed attaches to the given Z\n#   stepper. It is described using nozzle coordinates (the X, Y position\n#   of the nozzle if it could move directly above the point). The\n#   first entry corresponds to stepper_z, the second to stepper_z1,\n#   the third to stepper_z2, etc. This parameter must be provided.\n#points:\n#   A list of X, Y coordinates (one per line; subsequent lines\n#   indented) that should be probed during a Z_TILT_ADJUST command.\n#   Specify coordinates of the nozzle and be sure the probe is above\n#   the bed at the given nozzle coordinates. This parameter must be\n#   provided.\n#speed: 50\n#   The speed (in mm/s) of non-probing moves during the calibration.\n#   The default is 50.\n#horizontal_move_z: 5\n#   The height (in mm) that the head should be commanded to move to\n#   just prior to starting a probe operation. The default is 5.\n#min_horizontal_move_z: 1.0\n#   minimum value for horizontal move z\n#   (only used when adaptive_horizontal_move_z is True)\n#adaptive_horizontal_move_z: False\n#   if we should adjust horizontal move z after the first adjustment round,\n#   based on error.\n#   when set to True, initial horizontal_move_z is the config value,\n#   subsequent iterations will set horizontal_move_z to\n#   the ceil of error, or min_horizontal_move_z - whichever is greater.\n#retries: 0\n#   Number of times to retry if the probed points aren't within\n#   tolerance.\n#retry_tolerance: 0\n#   If retries are enabled then retry if largest and smallest probed\n#   points differ more than retry_tolerance. Note the smallest unit of\n#   change here would be a single step. However if you are probing\n#   more points than steppers then you will likely have a fixed\n#   minimum value for the range of probed points which you can learn\n#   by observing command output.\n#increasing_threshold: 0.0000001\n#   Sets the threshold that probe points can increase before z_tilt aborts.\n#   To disable the validation, set this parameter to a high value.\n#use_probe_xy_offsets: False\n#   If True, apply the `[probe]` XY offsets to the probed positions. The\n#   default is False.\n
    "},{"location":"Config_Reference.html#z_tilt_ng","title":"[z_tilt_ng]","text":"

    z_tilt's next generation, adding the Z_TILT_CALIBRATE and Z_TILT_AUTODETECT extended G-Code commands. Z_TILT_CALIBRATE performs multiple probing runs to calculate z_offsets, enabling accurate tilt adjustment with fewer probe points. Z_TILT_AUTODETECT automatically determines pivot positions for each Z stepper through iterative probing. When this section is present, these extended commands become available, enhancing bed leveling accuracy and calibration efficiency.

    [z_tilt_ng]\n#z_positions:\n# See [z_tilt]. This parameter must be provided,\n#   unless the parameter \"extra_points\" is provided. In that case only\n#   the command Z_TILT_AUTODETECT can be run to automatically determine\n#   the z_positions. See 'extra_points' below.\n#z_offsets:\n#   A list of Z offsets for each z_position. The z_offset is added to each\n#   probed value during Z_TILT_ADJUST to offset for unevenness of the bed.\n#   This values can also be automatically detected by running\n#   Z_TILT_CALIBRATE. See \"extra_points\" below.\n#points:\n# See [z_tilt]\n#speed: 50\n# See [z_tilt]\n#horizontal_move_z: 5\n# See [z_tilt]\n#min_horizontal_move_z: 1.0\n# See [z_tilt]\n#adaptive_horizontal_move_z: False\n# See [z_tilt]\n#retries: 0\n# See [z_tilt]\n#retry_tolerance: 0\n# See [z_tilt]\n#increasing_threshold: 0.0000001\n# See [z_tilt]\n#use_probe_xy_offsets: False\n# See [z_tilt]\n#extra_points:\n#   A list in the same format as \"points\" above. This list contains\n#   additional points to be probed during the two calibration commands\n#   Z_TILT_CALIBRATE and Z_TILT_AUTODETECT. If the bed is not perfectly\n#   level, it is possible to specify more probing points with \"points\".\n#   In that Z_TILT_ADJUST will determine the best fit via a least squares\n#   algorithm. As this comes with additional overhead on each Z_TILT_ADJUST\n#   run, it is instead possible to move the additional probing points here,\n#   and use Z_TILT_CALIBRATE to find z_offsets to use for the probing points\n#   used in Z_TILT_ADJUST.\n#   The extra points are also used during T_ZILT_AUTODETECT. This command\n#   can determine the z_positions automatically by during several probings\n#   with intentionally tilted bed. It is currently only implemented for 3\n#   z steppers.\n#   Note that for both commands to work numpy has to be installed.\n#averaging_len: 3\n#   Z_TILT_CALIBRATE and Z_TILT_AUTODETECT both run repeatedly until the\n#   result can no longer be improved. To determine this, the probed values\n#   are averaged. The number of runs to average over is configured with this\n#   parameter.\n#autodetect_delta: 1.0\n#   The amount by which Z_TILT_AUTODETECT intentionally tilts the bed. Higher\n#   values yield better results, but can also lead to situations where the\n#   bed is tilted in a way that the nozzle touched the bed before the probe.\n#   The default is conservative.\n
    "},{"location":"Config_Reference.html#quad_gantry_level","title":"[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:

     ----------------\n |Z1          Z2|\n |  ---------   |\n |  |       |   |\n |  |       |   |\n |  x--------   |\n |Z           Z3|\n ----------------\n

    Where x is the 0, 0 point on the bed

    [quad_gantry_level]\n#gantry_corners:\n#   A newline separated list of X, Y coordinates describing the two\n#   opposing corners of the gantry. The first entry corresponds to Z,\n#   the second to Z2. This parameter must be provided.\n#points:\n#   A newline separated list of four X, Y points that should be probed\n#   during a QUAD_GANTRY_LEVEL command. Order of the locations is\n#   important, and should correspond to Z, Z1, Z2, and Z3 location in\n#   order. This parameter must be provided. For maximum accuracy,\n#   ensure your probe offsets are configured.\n#speed: 50\n#   The speed (in mm/s) of non-probing moves during the calibration.\n#   The default is 50.\n#horizontal_move_z: 5\n#   The height (in mm) that the head should be commanded to move to\n#   just prior to starting a probe operation. The default is 5.\n#min_horizontal_move_z: 1.0\n#   minimum value for horizontal move z\n#   (only used when adaptive_horizontal_move_z is True)\n#adaptive_horizontal_move_z: False\n#   if we should adjust horizontal move z after the first adjustment round,\n#   based on error.\n#   when set to True, initial horizontal_move_z is the config value,\n#   subsequent iterations will set horizontal_move_z to\n#   the ceil of error, or min_horizontal_move_z - whichever is greater.\n#max_adjust: 4\n#   Safety limit if an adjustment greater than this value is requested\n#   quad_gantry_level will abort.\n#retries: 0\n#   Number of times to retry if the probed points aren't within\n#   tolerance.\n#retry_tolerance: 0\n#   If retries are enabled then retry if largest and smallest probed\n#   points differ more than retry_tolerance.\n#increasing_threshold: 0.0000001\n#   Sets the threshold that probe points can increase before qgl aborts.\n#   To disable the validation, set this parameter to a high value.\n#use_probe_xy_offsets: False\n#   If True, apply the `[probe]` XY offsets to the probed positions. The\n#   default is False.\n
    "},{"location":"Config_Reference.html#skew_correction","title":"[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]\n
    "},{"location":"Config_Reference.html#z_thermal_adjust","title":"[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]\n#temp_coeff:\n#   The temperature coefficient of expansion, in mm/degC. For example, a\n#   temp_coeff of 0.01 mm/degC will move the Z axis downwards by 0.01 mm for\n#   every degree Celsius that the temperature sensor increases. Defaults to\n#   0.0 mm/degC, which applies no adjustment.\n#smooth_time:\n#   Smoothing window applied to the temperature sensor, in seconds. Can reduce\n#   motor noise from excessive small corrections in response to sensor noise.\n#   The default is 2.0 seconds.\n#z_adjust_off_above:\n#   Disables adjustments above this Z height [mm]. The last computed correction\n#   will remain applied until the toolhead moves below the specified Z height\n#   again. The default is 99999999.0 mm (always on).\n#max_z_adjustment:\n#   Maximum absolute adjustment that can be applied to the Z axis [mm]. The\n#   default is 99999999.0 mm (unlimited).\n#sensor_type:\n#sensor_pin:\n#min_temp:\n#max_temp:\n#   Temperature sensor configuration.\n#   See the \"extruder\" section for the definition of the above\n#   parameters.\n#gcode_id:\n#   See the \"heater_generic\" section for the definition of this\n#   parameter.\n
    "},{"location":"Config_Reference.html#customized-homing","title":"Customized homing","text":""},{"location":"Config_Reference.html#safe_z_home","title":"[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]\nhome_xy_position:\n#   A X, Y coordinate (e.g. 100, 100) where the Z homing should be\n#   performed. This parameter must be provided.\n#speed: 50.0\n#   Speed at which the toolhead is moved to the safe Z home\n#   coordinate. The default is 50 mm/s\n#z_hop:\n#   Distance (in mm) to lift the Z axis prior to homing. This is\n#   applied to any homing command, even if it doesn't home the Z axis.\n#   If the Z axis is already homed and the current Z position is less\n#   than z_hop, then this will lift the head to a height of z_hop. If\n#   the Z axis is not already homed the head is lifted by z_hop.\n#   The default is to not implement Z hop.\n#z_hop_speed: 15.0\n#   Speed (in mm/s) at which the Z axis is lifted prior to homing. The\n#   default is 15 mm/s.\n#move_to_previous: False\n#   When set to True, the X and Y axes are reset to their previous\n#   positions after Z axis homing. The default is False.\n#home_y_before_x: False\n#  # If True, the Y axis will home first. The default is False.\n
    "},{"location":"Config_Reference.html#homing_override","title":"[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]\ngcode:\n#   A list of G-Code commands to execute in place of G28 commands\n#   found in the normal g-code input. See docs/Command_Templates.md\n#   for G-Code format. If a G28 is contained in this list of commands\n#   then it will invoke the normal homing procedure for the printer.\n#   The commands listed here must home all axes. This parameter must\n#   be provided.\n#axes: xyz\n#   The axes to override. For example, if this is set to \"z\" then the\n#   override script will only be run when the z axis is homed (eg, via\n#   a \"G28\" or \"G28 Z0\" command). Note, the override script should\n#   still home all axes. The default is \"xyz\" which causes the\n#   override script to be run in place of all G28 commands.\n#set_position_x:\n#set_position_y:\n#set_position_z:\n#   If specified, the printer will assume the axis is at the specified\n#   position prior to running the above g-code commands. Setting this\n#   disables homing checks for that axis. This may be useful if the\n#   head must move prior to invoking the normal G28 mechanism for an\n#   axis. The default is to not force a position for an axis.\n
    "},{"location":"Config_Reference.html#endstop_phase","title":"[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]\n#endstop_accuracy:\n#   Sets the expected accuracy (in mm) of the endstop. This represents\n#   the maximum error distance the endstop may trigger (eg, if an\n#   endstop may occasionally trigger 100um early or up to 100um late\n#   then set this to 0.200 for 200um). The default is\n#   4*rotation_distance/full_steps_per_rotation.\n#trigger_phase:\n#   This specifies the phase of the stepper motor driver to expect\n#   when hitting the endstop. It is composed of two numbers separated\n#   by a forward slash character - the phase and the total number of\n#   phases (eg, \"7/64\"). Only set this value if one is sure the\n#   stepper motor driver is reset every time the mcu is reset. If this\n#   is not set, then the stepper phase will be detected on the first\n#   home and that phase will be used on all subsequent homes.\n#endstop_align_zero: False\n#   If true then the position_endstop of the axis will effectively be\n#   modified so that the zero position for the axis occurs at a full\n#   step on the stepper motor. (If used on the Z axis and the print\n#   layer height is a multiple of a full step distance then every\n#   layer will occur on a full step.) The default is False.\n
    "},{"location":"Config_Reference.html#g-code-macros-and-events","title":"G-Code macros and events","text":""},{"location":"Config_Reference.html#gcode_macro","title":"[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]\n#gcode:\n#   A list of G-Code commands to execute in place of \"my_cmd\". See\n#   docs/Command_Templates.md for G-Code format. This parameter must\n#   be provided.\n#variable_<name>:\n#   One may specify any number of options with a \"variable_\" prefix.\n#   The given variable name will be assigned the given value (parsed\n#   as a Python literal) and will be available during macro expansion.\n#   For example, a config with \"variable_fan_speed = 75\" might have\n#   gcode commands containing \"M106 S{ fan_speed * 255 }\". Variables\n#   can be changed at run-time using the SET_GCODE_VARIABLE command\n#   (see docs/Command_Templates.md for details). Variable names may\n#   not use upper case characters.\n#rename_existing:\n#   This option will cause the macro to override an existing G-Code\n#   command and provide the previous definition of the command via the\n#   name provided here. This can be used to override builtin G-Code\n#   commands. Care should be taken when overriding commands as it can\n#   cause complex and unexpected results. The default is to not\n#   override an existing G-Code command.\n#description: G-Code macro\n#   This will add a short description used at the HELP command or while\n#   using the auto completion feature. Default \"G-Code macro\"\n
    "},{"location":"Config_Reference.html#delayed_gcode","title":"[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]\ngcode:\n#   A list of G-Code commands to execute when the delay duration has\n#   elapsed. G-Code templates are supported. This parameter must be\n#   provided.\n#initial_duration: 0.0\n#   The duration of the initial delay (in seconds). If set to a\n#   non-zero value the delayed_gcode will execute the specified number\n#   of seconds after the printer enters the \"ready\" state. This can be\n#   useful for initialization procedures or a repeating delayed_gcode.\n#   If set to 0 the delayed_gcode will not execute on startup.\n#   Default is 0.\n
    "},{"location":"Config_Reference.html#save_variables","title":"[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]\nfilename:\n#   Required - provide a filename that would be used to save the\n#   variables to disk e.g. ~/variables.cfg\n
    "},{"location":"Config_Reference.html#idle_timeout","title":"[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]\n#gcode:\n#   A list of G-Code commands to execute on an idle timeout. See\n#   docs/Command_Templates.md for G-Code format. The default is to run\n#   \"TURN_OFF_HEATERS\" and \"M84\".\n#timeout: 600\n#   Idle time (in seconds) to wait before running the above G-Code\n#   commands. Set it to 0 to disable the timeout feature.\n#   The default is 600 seconds.\n
    "},{"location":"Config_Reference.html#optional-g-code-features","title":"Optional G-Code features","text":""},{"location":"Config_Reference.html#virtual_sdcard","title":"[virtual_sdcard]","text":"

    A virtual sdcard may be useful if the host machine is not fast enough to run OctoPrint well. It allows the Kalico host software to directly print gcode files stored in a directory on the host using standard sdcard G-Code commands (eg, M24).

    [virtual_sdcard]\npath:\n#   The path of the local directory on the host machine to look for\n#   g-code files. This is a read-only directory (sdcard file writes\n#   are not supported). One may point this to OctoPrint's upload\n#   directory (generally ~/.octoprint/uploads/ ). This parameter must\n#   be provided.\n#on_error_gcode:\n#   A list of G-Code commands to execute when an error is reported.\n#   See docs/Command_Templates.md for G-Code format. The default is to\n#   run TURN_OFF_HEATERS.\n#with_subdirs: False\n#   Enable scanning of subdirectories for the menu and for the\n#   M20 and M23 commands. The default is False.\n
    "},{"location":"Config_Reference.html#sdcard_loop","title":"[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]\n
    "},{"location":"Config_Reference.html#force_move","title":"\u26a0\ufe0f [force_move]","text":"

    This module is enabled by default in Kalico!

    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]\n#enable_force_move: True\n#   Set to `True` to enable FORCE_MOVE and SET_KINEMATIC_POSITION\n#   extended G-Code commands. The default is `True`.\n
    "},{"location":"Config_Reference.html#pause_resume","title":"[pause_resume]","text":"

    Pause/Resume functionality with support of position capture and restore. See the command reference for more information.

    [pause_resume]\n#recover_velocity: 50.\n#   When capture/restore is enabled, the speed at which to return to\n#   the captured position (in mm/s). Default is 50.0 mm/s.\n
    "},{"location":"Config_Reference.html#firmware_retraction","title":"[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]\n#retract_length: 0.0\n#   The length of filament (in mm) to retract when a G10 command is\n#   executed. When a G11 command is executed, the unretract_length\n#   is the sum of the retract_length and the unretract_extra_length\n#   (see below). The minimum value and default are 0 mm, which\n#   disables firmware retraction.\n#retract_speed: 20.0\n#   The speed of filament retraction moves (in mm/s).\n#   This value is typically set relatively high (>40 mm/s),\n#   except for soft and/oozy filaments like TPU and PETG\n#   (20 to 30 mm/s). The minimum value is 1 mm/s, the default value\n#   is 20 mm/s.\n#unretract_extra_length: 0.0\n#   The *additional* length (in mm) to add or the length to subtract\n#   from the filament move when unretracting compared to the retract\n#   move length. This allows priming the nozzle (positive extra length)\n#   or delaying extrusion after unretracting (negative length). The\n#   latter may help reduce blobbing. The minimum value is -1 mm\n#   (2.41 mm3 volume for 1.75 mm filament), the default value is 0 mm.\n#unretract_speed: 10.0\n#   The speed of filament unretraction moves (in mm/s).\n#   This parameter is not particularly critical, although often lower\n#   than retract_speed. The minimum value is 1 mm/s, the default value\n#   is 10 mm/s.\n#z_hop_height: 0.0\n#   The vertical height by which the nozzle is lifted from the print to\n#   prevent collisions with the print during travel moves when retracted.\n#   The minimum value is 0 mm, the default value is 0 mm, which disables\n#   zhop moves. The value will be reduced if the zhop move reaches\n#   maximum z.\n#clear_zhop_on_z_moves: False\n#   If True, when a change in Z is sent while toolhead is retracted,\n#   z_hop is cancelled until next retraction. Otherwise,\n#   `z_hop_height` is applied as an offset to all movements.\n
    "},{"location":"Config_Reference.html#gcode_arcs","title":"[gcode_arcs]","text":"

    Support for gcode arc (G2/G3) commands.

    [gcode_arcs]\n#resolution: 1.0\n#   An arc will be split into segments. Each segment's length will\n#   equal the resolution in mm set above. Lower values will produce a\n#   finer arc, but also more work for your machine. Arcs smaller than\n#   the configured value will become straight lines. The default is\n#   1mm.\n
    "},{"location":"Config_Reference.html#respond","title":"[respond]","text":"

    This module is enabled by default in Kalico!

    Enable the \"M118\" and \"RESPOND\" extended commands.

    [respond]\n#default_type: echo\n#   Sets the default prefix of the \"M118\" and \"RESPOND\" output to one\n#   of the following:\n#       echo: \"echo: \" (This is the default)\n#       command: \"// \"\n#       error: \"!! \"\n#default_prefix: echo:\n#   Directly sets the default prefix. If present, this value will\n#   override the \"default_type\".\n#enable_respond: True\n#   Set to `True` to enable M118 and RESPOND\n#   extended G-Code commands. The default is `True`.\n
    "},{"location":"Config_Reference.html#exclude_object","title":"[exclude_object]","text":"

    This module is enabled by default in Kalico!

    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]\n#enable_exclude_object: True\n#   Set to `True` to enable `EXCLUDE_OBJECT_*` extended G-Code commands.\n#   The default is `True`.\n
    "},{"location":"Config_Reference.html#resonance-compensation","title":"Resonance compensation","text":""},{"location":"Config_Reference.html#input_shaper","title":"[input_shaper]","text":"

    Enables resonance compensation. Also see the command reference.

    [input_shaper]\n#shaper_freq_x: 0\n#   A frequency (in Hz) of the input shaper for X axis. This is\n#   usually a resonance frequency of X axis that the input shaper\n#   should suppress. For more complex shapers, like 2- and 3-hump EI\n#   input shapers, this parameter can be set from different\n#   considerations. The default value is 0, which disables input\n#   shaping for X axis.\n#shaper_freq_y: 0\n#   A frequency (in Hz) of the input shaper for Y axis. This is\n#   usually a resonance frequency of Y axis that the input shaper\n#   should suppress. For more complex shapers, like 2- and 3-hump EI\n#   input shapers, this parameter can be set from different\n#   considerations. The default value is 0, which disables input\n#   shaping for Y axis.\n#shaper_type: mzv\n#   A type of the input shaper to use for both X and Y axes. Supported\n#   shapers are zv, mzv, zvd, ei, 2hump_ei, and 3hump_ei. The default\n#   is mzv input shaper.\n#shaper_type_x:\n#shaper_type_y:\n#   If shaper_type is not set, these two parameters can be used to\n#   configure different input shapers for X and Y axes. The same\n#   values are supported as for shaper_type parameter.\n#damping_ratio_x: 0.1\n#damping_ratio_y: 0.1\n#   Damping ratios of vibrations of X and Y axes used by input shapers\n#   to improve vibration suppression. Default value is 0.1 which is a\n#   good all-round value for most printers. In most circumstances this\n#   parameter requires no tuning and should not be changed.\n
    "},{"location":"Config_Reference.html#adxl345","title":"[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]\ncs_pin:\n#   The SPI enable pin for the sensor. This parameter must be provided.\n#spi_speed: 5000000\n#   The SPI speed (in hz) to use when communicating with the chip.\n#   The default is 5000000.\n#spi_bus:\n#spi_software_sclk_pin:\n#spi_software_mosi_pin:\n#spi_software_miso_pin:\n#   See the \"common SPI settings\" section for a description of the\n#   above parameters.\n#axes_map: x, y, z\n#   The accelerometer axis for each of the printer's X, Y, and Z axes.\n#   This may be useful if the accelerometer is mounted in an\n#   orientation that does not match the printer orientation. For\n#   example, one could set this to \"y, x, z\" to swap the X and Y axes.\n#   It is also possible to negate an axis if the accelerometer\n#   direction is reversed (eg, \"x, z, -y\"). The default is \"x, y, z\".\n#rate: 3200\n#   Output data rate for ADXL345. ADXL345 supports the following data\n#   rates: 3200, 1600, 800, 400, 200, 100, 50, and 25. Note that it is\n#   not recommended to change this rate from the default 3200, and\n#   rates below 800 will considerably affect the quality of resonance\n#   measurements.\n
    "},{"location":"Config_Reference.html#lis2dw","title":"[lis2dw]","text":"

    Support for LIS2DW accelerometers.

    [lis2dw]\n#cs_pin:\n#   The SPI enable pin for the sensor. This parameter must be provided\n#   if using SPI.\n#spi_speed: 5000000\n#   The SPI speed (in hz) to use when communicating with the chip.\n#   The default is 5000000.\n#spi_bus:\n#spi_software_sclk_pin:\n#spi_software_mosi_pin:\n#spi_software_miso_pin:\n#   See the \"common SPI settings\" section for a description of the\n#   above parameters.\n#i2c_address:\n#   Default is 25 (0x19). If SA0 is high, it would be 24 (0x18) instead.\n#i2c_mcu:\n#i2c_bus:\n#i2c_software_scl_pin:\n#i2c_software_sda_pin:\n#i2c_speed: 400000\n#   See the \"common I2C settings\" section for a description of the\n#   above parameters. The default \"i2c_speed\" is 400000.\n#axes_map: x, y, z\n#   See the \"adxl345\" section for information on this parameter.\n
    "},{"location":"Config_Reference.html#lis3dh","title":"[lis3dh]","text":"

    Support for LIS3DH accelerometers.

    [lis3dh]\n#cs_pin:\n#   The SPI enable pin for the sensor. This parameter must be provided\n#   if using SPI.\n#spi_speed: 5000000\n#   The SPI speed (in hz) to use when communicating with the chip.\n#   The default is 5000000.\n#spi_bus:\n#spi_software_sclk_pin:\n#spi_software_mosi_pin:\n#spi_software_miso_pin:\n#   See the \"common SPI settings\" section for a description of the\n#   above parameters.\n#i2c_address:\n#   Default is 25 (0x19). If SA0 is high, it would be 24 (0x18) instead.\n#i2c_mcu:\n#i2c_bus:\n#i2c_software_scl_pin:\n#i2c_software_sda_pin:\n#i2c_speed: 400000\n#   See the \"common I2C settings\" section for a description of the\n#   above parameters. The default \"i2c_speed\" is 400000.\n#axes_map: x, y, z\n#   See the \"adxl345\" section for information on this parameter.\n
    "},{"location":"Config_Reference.html#mpu9250","title":"[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]\n#i2c_address:\n#   Default is 104 (0x68). If AD0 is high, it would be 0x69 instead.\n#i2c_mcu:\n#i2c_bus:\n#i2c_software_scl_pin:\n#i2c_software_sda_pin:\n#i2c_speed: 400000\n#   See the \"common I2C settings\" section for a description of the\n#   above parameters. The default \"i2c_speed\" is 400000.\n#axes_map: x, y, z\n#   See the \"adxl345\" section for information on this parameter.\n
    "},{"location":"Config_Reference.html#resonance_tester","title":"[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]\n#probe_points:\n#   A list of X, Y, Z coordinates of points (one point per line) to test\n#   resonances at. At least one point is required. Make sure that all\n#   points with some safety margin in XY plane (~a few centimeters)\n#   are reachable by the toolhead.\n#accel_chip:\n#   A name of the accelerometer chip to use for measurements. If\n#   adxl345 chip was defined without an explicit name, this parameter\n#   can simply reference it as \"accel_chip: adxl345\", otherwise an\n#   explicit name must be supplied as well, e.g. \"accel_chip: adxl345\n#   my_chip_name\". Either this, or the next two parameters must be\n#   set.\n#accel_chip_x:\n#accel_chip_y:\n#   Names of the accelerometer chips to use for measurements for each\n#   of the axis. Can be useful, for instance, on bed slinger printer,\n#   if two separate accelerometers are mounted on the bed (for Y axis)\n#   and on the toolhead (for X axis). These parameters have the same\n#   format as 'accel_chip' parameter. Only 'accel_chip' or these two\n#   parameters must be provided.\n#max_smoothing:\n#   Maximum input shaper smoothing to allow for each axis during shaper\n#   auto-calibration (with 'SHAPER_CALIBRATE' command). By default no\n#   maximum smoothing is specified. Refer to Measuring_Resonances guide\n#   for more details on using this feature.\n#move_speed: 50\n#   The speed (in mm/s) to move the toolhead to and between test points\n#   during the calibration. The default is 50.\n#min_freq: 5\n#   Minimum frequency to test for resonances. The default is 5 Hz.\n#max_freq: 133.33\n#   Maximum frequency to test for resonances. The default is 133.33 Hz.\n#accel_per_hz: 75\n#   This parameter is used to determine which acceleration to use to\n#   test a specific frequency: accel = accel_per_hz * freq. Higher the\n#   value, the higher is the energy of the oscillations. Can be set to\n#   a lower than the default value if the resonances get too strong on\n#   the printer. However, lower values make measurements of\n#   high-frequency resonances less precise. The default value is 75\n#   (mm/sec).\n#   Set it to 60 as a good baseline when using the sweeping resonance tester.\n#hz_per_sec: 1\n#   Determines the speed of the test. When testing all frequencies in\n#   range [min_freq, max_freq], each second the frequency increases by\n#   hz_per_sec. Small values make the test slow, and the large values\n#   will decrease the precision of the test. The default value is 1.0\n#   (Hz/sec == sec^-2).\n#sweeping_accel: 400\n#   An acceleration of slow sweeping moves. The default is 400 mm/sec^2.\n#sweeping_period: 0\n#   A period of slow sweeping moves. Avoid setting it to a too small\n#   non-zero value in order to not poison the measurements.\n#   To enable it, start by setting it to 1.2 sec which is a good all-round\n#   choice. Set it to 0 do disable it. The default is 0.\n
    "},{"location":"Config_Reference.html#config-file-helpers","title":"Config file helpers","text":""},{"location":"Config_Reference.html#board_pins","title":"[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]\nmcu: mcu\n#   A comma separated list of micro-controllers that may use the\n#   aliases. The default is to apply the aliases to the main \"mcu\".\naliases:\naliases_<name>:\n#   A comma separated list of \"name=value\" aliases to create for the\n#   given micro-controller. For example, \"EXP1_1=PE6\" would create an\n#   \"EXP1_1\" alias for the \"PE6\" pin. However, if \"value\" is enclosed\n#   in \"<>\" then \"name\" is created as a reserved pin (for example,\n#   \"EXP1_9=<GND>\" would reserve \"EXP1_9\"). Any number of options\n#   starting with \"aliases_\" may be specified.\n
    "},{"location":"Config_Reference.html#include","title":"[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\", or \"configs/**/*.cfg\" if using python version >=3.5).

    [include my_other_config.cfg]\n
    "},{"location":"Config_Reference.html#duplicate_pin_override","title":"[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 Kalico supports using the same pin multiple times, and using this override may cause confusing and unexpected results. One may specify an explicit name (eg, [duplicate_pin_override my_name]) to define multiple instances of it.

    [duplicate_pin_override]\npins:\n#   A comma separated list of pins that may be used multiple times in\n#   a config file without normal error checks. This parameter must be\n#   provided.\n
    "},{"location":"Config_Reference.html#bed-probing-hardware","title":"Bed probing hardware","text":""},{"location":"Config_Reference.html#probe","title":"[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]\npin:\n#   Probe detection pin. If the pin is on a different microcontroller\n#   than the Z steppers then it enables \"multi-mcu homing\". This\n#   parameter must be provided.\n#deactivate_on_each_sample: True\n#   This determines if Kalico should execute deactivation gcode\n#   between each probe attempt when performing a multiple probe\n#   sequence. The default is True.\n#x_offset: 0.0\n#   The distance (in mm) between the probe and the nozzle along the\n#   x-axis. The default is 0.\n#y_offset: 0.0\n#   The distance (in mm) between the probe and the nozzle along the\n#   y-axis. The default is 0.\nz_offset:\n#   The distance (in mm) between the bed and the nozzle when the probe\n#   triggers. This parameter must be provided.\n#speed: 5.0\n#   Speed (in mm/s) of the Z axis when probing. The default is 5mm/s.\n#samples: 1\n#   The number of times to probe each point. The probed z-values will\n#   be averaged. The default is to probe 1 time.\n#sample_retract_dist: 2.0\n#   The distance (in mm) to lift the toolhead between each sample (if\n#   sampling more than once). The default is 2mm.\n#lift_speed:\n#   Speed (in mm/s) of the Z axis when lifting the probe between\n#   samples. The default is to use the same value as the 'speed'\n#   parameter.\n#samples_result: average\n#   The calculation method when sampling more than once - either\n#   \"median\" or \"average\". The default is average.\n#samples_tolerance: 0.100\n#   The maximum Z distance (in mm) that a sample may differ from other\n#   samples. If this tolerance is exceeded then either an error is\n#   reported or the attempt is restarted (see\n#   samples_tolerance_retries). The default is 0.100mm.\n#samples_tolerance_retries: 0\n#   The number of times to retry if a sample is found that exceeds\n#   samples_tolerance. On a retry, all current samples are discarded\n#   and the probe attempt is restarted. If a valid set of samples are\n#   not obtained in the given number of retries then an error is\n#   reported. The default is zero which causes an error to be reported\n#   on the first sample that exceeds samples_tolerance.\n#activate_gcode:\n#   A list of G-Code commands to execute prior to each probe attempt.\n#   See docs/Command_Templates.md for G-Code format. This may be\n#   useful if the probe needs to be activated in some way. Do not\n#   issue any commands here that move the toolhead (eg, G1). The\n#   default is to not run any special G-Code commands on activation.\n#deactivate_gcode:\n#   A list of G-Code commands to execute after each probe attempt\n#   completes. See docs/Command_Templates.md for G-Code format. Do not\n#   issue any commands here that move the toolhead. The default is to\n#   not run any special G-Code commands on deactivation.\n#drop_first_result: False\n#   Set to `True` will probe one extra time and remove the first\n#   sample from calculation. This can improve probe accuracy for\n#   printers that have an outlier first sample.\n
    "},{"location":"Config_Reference.html#bltouch","title":"[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]\nsensor_pin:\n#   Pin connected to the BLTouch sensor pin. Most BLTouch devices\n#   require a pullup on the sensor pin (prefix the pin name with \"^\").\n#   This parameter must be provided.\ncontrol_pin:\n#   Pin connected to the BLTouch control pin. This parameter must be\n#   provided.\n#pin_move_time: 0.680\n#   The amount of time (in seconds) to wait for the BLTouch pin to\n#   move up or down. The default is 0.680 seconds.\n#stow_on_each_sample: True\n#   This determines if Kalico should command the pin to move up\n#   between each probe attempt when performing a multiple probe\n#   sequence. Read the directions in docs/BLTouch.md before setting\n#   this to False. The default is True.\n#probe_with_touch_mode: False\n#   If this is set to True then Kalico will probe with the device in\n#   \"touch_mode\". The default is False (probing in \"pin_down\" mode).\n#pin_up_reports_not_triggered: True\n#   Set if the BLTouch consistently reports the probe in a \"not\n#   triggered\" state after a successful \"pin_up\" command. This should\n#   be True for all genuine BLTouch devices. Read the directions in\n#   docs/BLTouch.md before setting this to False. The default is True.\n#pin_up_touch_mode_reports_triggered: True\n#   Set if the BLTouch consistently reports a \"triggered\" state after\n#   the commands \"pin_up\" followed by \"touch_mode\". This should be\n#   True for all genuine BLTouch devices. Read the directions in\n#   docs/BLTouch.md before setting this to False. The default is True.\n#set_output_mode:\n#   Request a specific sensor pin output mode on the BLTouch V3.0 (and\n#   later). This setting should not be used on other types of probes.\n#   Set to \"5V\" to request a sensor pin output of 5 Volts (only use if\n#   the controller board needs 5V mode and is 5V tolerant on its input\n#   signal line). Set to \"OD\" to request the sensor pin output use\n#   open drain mode. The default is to not request an output mode.\n#x_offset:\n#y_offset:\n#z_offset:\n#speed:\n#lift_speed:\n#samples:\n#sample_retract_dist:\n#samples_result:\n#samples_tolerance:\n#samples_tolerance_retries:\n#   See the \"probe\" section for information on these parameters.\n
    "},{"location":"Config_Reference.html#dockable_probe","title":"[dockable_probe]","text":"

    Certain probes are magnetically coupled to the toolhead and stowed in a dock when not in use. One should define this section instead of a probe section if the probe uses magnets to attach and a dock for storage. See Dockable Probe Guide for more detailed information regarding configuration and setup.

    [dockable_probe]\ndock_position: 0,0,0\n#   The physical position of the probe dock relative to the origin of\n#   the bed. The coordinates are specified as a comma separated X, Y, Z\n#   list of values. Certain dock designs are independent of the Z axis.\n#   If Z is specified the toolhead will move to the Z location before the X, Y\n#   coordinates.\n#   This parameter is required.\napproach_position: 0,0,0\n#   The X, Y, Z position where the toolhead needs to be prior to moving into the\n#   dock so that the probe is aligned properly for attaching or detaching.\n#   If Z is specified the toolhead will move to the Z location before the X, Y\n#   coordinates.\n#   This parameter is required.\ndetach_position: 0,0,0\n#   Similar to the approach_position, the detach_position is the coordinates\n#   where the toolhead is moved after the probe has been docked.\n#   For magnetically coupled probes, this is typically perpendicular to\n#   the approach_position in a direction that does not cause the tool to\n#   collide with the printer.\n#   If Z is specified the toolhead will move to the Z location before the X, Y\n#   coordinates.\n#   This parameter is required.\n#extract_position: 0,0,0\n#   Similar to the approach_position, the extract_position is the coordinates\n#   where the toolhead is moved to extract the probe from the dock.\n#   If Z is specified the toolhead will move to the Z location before the X, Y\n#   coordinates.\n#   The default value is approach_probe value.\n#insert_position: 0,0,0\n#   Similar to the extract_position, the insert_position is the coordinates\n#   where the toolhead is moved before inserting the probe into the dock.\n#   If Z is specified the toolhead will move to the Z location before the X, Y\n#   coordinates.\n#   The default value is extract_probe value.\n#safe_dock_distance :\n#   This setting defines a security area around dock during ATTACH/DETACH_PROBE\n#   commands. While inside the area, the toolhead move away prior to reach the\n#   approach or insert position.\n#   Default is the smallest distance to the dock of approach, detach, insert\n#   position. It could be only lower than the Default value.\n#safe_position : approach_position\n#   A safe position to ensure MOVE_AVOIDING_DOCK travel does not move the\n#   toolhead out of range.\n#z_hop: 15.0\n#   Distance (in mm) to lift the Z axis prior to attaching/detaching the probe.\n#   If the Z axis is already homed and the current Z position is less\n#   than `z_hop`, then this will lift the head to a height of `z_hop`. If\n#   the Z axis is not already homed the head is lifted by `z_hop`.\n#   The default is to not implement Z hop.\n#restore_toolhead: True\n#   While True, the position of the toolhead is restored to the position prior\n#   to the attach/detach movements.\n#   The default value is True.\n#dock_retries:\n#   The number of times to attempt to attach/dock the probe before raising\n#   an error and aborting probing.\n#   The default is 0.\n#auto_attach_detach: False\n#   Enable/Disable the automatic attaching/detaching of the probe during\n#   actions that require the probe.\n#   The default is True.\n#attach_speed:\n#detach_speed:\n#travel_speed:\n#   Optional speeds used during moves.\n#   The default is to use `speed` of `probe` or 5.0.\n#check_open_attach:\n#   The probe status should be verified prior to homing. Setting this option\n#   to true will check the probe \"endstop\" is \"open\" after attaching and\n#   will abort probing if not, also checking for \"triggered\" after docking.\n#   Conversively, setting this to false, the probe should read \"triggered\"\n#   after attaching and \"open\" after docking. If not, probing will abort.\n#probe_sense_pin:\n#   This supplemental pin can be defined to determine an attached state\n#   instead of check_open_attach.\n#dock_sense_pin:\n#   This supplemental pin can be defined to determine a docked state in\n#   addition to probe_sense_pin or check_open_attach.\n#x_offset:\n#y_offset:\n#z_offset:\n#lift_speed:\n#speed:\n#samples:\n#sample_retract_dist:\n#samples_result:\n#samples_tolerance:\n#samples_tolerance_retries:\n#activate_gcode:\n#deactivate_gcode:\n#   See the \"probe\" section for information on these parameters.\n
    "},{"location":"Config_Reference.html#smart_effector","title":"[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]\npin:\n#   Pin connected to the Smart Effector Z Probe output pin (pin 5). Note that\n#   pullup resistor on the board is generally not required. However, if the\n#   output pin is connected to the board pin with a pullup resistor, that\n#   resistor must be high value (e.g. 10K Ohm or more). Some boards have a low\n#   value pullup resistor on the Z probe input, which will likely result in an\n#   always-triggered probe state. In this case, connect the Smart Effector to\n#   a different pin on the board. This parameter is required.\n#control_pin:\n#   Pin connected to the Smart Effector control input pin (pin 7). If provided,\n#   Smart Effector sensitivity programming commands become available.\n#probe_accel:\n#   If set, limits the acceleration of the probing moves (in mm/sec^2).\n#   A sudden large acceleration at the beginning of the probing move may\n#   cause spurious probe triggering, especially if the hotend is heavy.\n#   To prevent that, it may be necessary to reduce the acceleration of\n#   the probing moves via this parameter.\n#recovery_time: 0.4\n#   A delay between the travel moves and the probing moves in seconds. A fast\n#   travel move prior to probing may result in a spurious probe triggering.\n#   This may cause 'Probe triggered prior to movement' errors if no delay\n#   is set. Value 0 disables the recovery delay.\n#   Default value is 0.4.\n#x_offset:\n#y_offset:\n#   Should be left unset (or set to 0).\nz_offset:\n#   Trigger height of the probe. Start with -0.1 (mm), and adjust later using\n#   `PROBE_CALIBRATE` command. This parameter must be provided.\n#speed:\n#   Speed (in mm/s) of the Z axis when probing. It is recommended to start\n#   with the probing speed of 20 mm/s and adjust it as necessary to improve\n#   the accuracy and repeatability of the probe triggering.\n#samples:\n#sample_retract_dist:\n#samples_result:\n#samples_tolerance:\n#samples_tolerance_retries:\n#activate_gcode:\n#deactivate_gcode:\n#deactivate_on_each_sample:\n#   See the \"probe\" section for more information on the parameters above.\n
    "},{"location":"Config_Reference.html#probe_eddy_current","title":"[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]\nsensor_type: ldc1612\n#   The sensor chip used to perform eddy current measurements. This\n#   parameter must be provided and must be set to ldc1612.\n#intb_pin:\n#   MCU gpio pin connected to the ldc1612 sensor's INTB pin (if\n#   available). The default is to not use the INTB pin.\n#z_offset:\n#   The nominal distance (in mm) between the nozzle and bed that a\n#   probing attempt should stop at. This parameter must be provided.\n#i2c_address:\n#i2c_mcu:\n#i2c_bus:\n#i2c_software_scl_pin:\n#i2c_software_sda_pin:\n#i2c_speed:\n#   The i2c settings for the sensor chip. See the \"common I2C\n#   settings\" section for a description of the above parameters.\n#x_offset:\n#y_offset:\n#speed:\n#lift_speed:\n#samples:\n#sample_retract_dist:\n#samples_result:\n#samples_tolerance:\n#samples_tolerance_retries:\n#   See the \"probe\" section for information on these parameters.\n
    "},{"location":"Config_Reference.html#axis_twist_compensation","title":"[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]\n#speed: 50\n#   The speed (in mm/s) of non-probing moves during the calibration.\n#   The default is 50.\n#horizontal_move_z: 5\n#   The height (in mm) that the head should be commanded to move to\n#   just prior to starting a probe operation. The default is 5.\ncalibrate_start_x: 20\n#   Defines the minimum X coordinate of the calibration\n#   This should be the X coordinate that positions the nozzle at the starting\n#   calibration position.\ncalibrate_end_x: 200\n#   Defines the maximum X coordinate of the calibration\n#   This should be the X coordinate that positions the nozzle at the ending\n#   calibration position.\ncalibrate_y: 112.5\n#   Defines the Y coordinate of the calibration\n#   This should be the Y coordinate that positions the nozzle during the\n#   calibration process. This parameter is recommended to\n#   be near the center of the bed\n\n# For Y-axis twist compensation, specify the following parameters:\ncalibrate_start_y: ...\n#   Defines the minimum Y coordinate of the calibration\n#   This should be the Y coordinate that positions the nozzle at the starting\n#   calibration position for the Y axis. This parameter must be provided if\n#   compensating for Y axis twist.\ncalibrate_end_y: ...\n#   Defines the maximum Y coordinate of the calibration\n#   This should be the Y coordinate that positions the nozzle at the ending\n#   calibration position for the Y axis. This parameter must be provided if\n#   compensating for Y axis twist.\ncalibrate_x: ...\n#   Defines the X coordinate of the calibration for Y axis twist compensation\n#   This should be the X coordinate that positions the nozzle during the\n#   calibration process for Y axis twist compensation. This parameter must be\n#   provided and is recommended to be near the center of the bed.\n
    "},{"location":"Config_Reference.html#z_calibration","title":"\u26a0\ufe0f [z_calibration]","text":"

    Automatic Z offset calibration. One may define this section if the printer is able to calibrate the nozzle's offset automatically. See Z-Calibration guide for further information.

    [z_calibration]\nnozzle_xy_position:\n#   A X, Y coordinate (e.g. 100,100) of the nozzle, clicking on the Z endstop.\nswitch_xy_position:\n#   A X, Y coordinate (e.g. 100,100) of the probe's switch body, clicking on\n#   the Z endstop.\nbed_xy_position: default from relative_reference_index of bed_mesh\n#   a X, Y coordinate (e.g. 100,100) where the print surface (e.g. the center\n#   point) is probed. These coordinates will be adapted by the\n#   probe's X and Y offsets. The default is the relative_reference_index\n#   of the configured bed_mesh, if configured. It's possible to change the relative\n#   reference index at runtime or use the GCode argument BED_POSITION of CALIBRATE_Z.\nswitch_offset:\n#   The trigger point offset of the used mag-probe switch.\n#   Larger values will position the nozzle closer to the bed.\n#   This needs to be find out manually. More on this later\n#   in this section..\nmax_deviation: 1.0\n#   The maximum allowed deviation of the calculated offset.\n#   If the offset exceeds this value, it will stop!\n#   The default is 1.0 mm.\nsamples: default from \"probe:samples\" section\n#   The number of times to probe each point. The probed z-values\n#   will be averaged. The default is from the probe's configuration.\nsamples_tolerance: default from \"probe:samples_tolerance\" section\n#   The maximum Z distance (in mm) that a sample may differ from other\n#   samples. The default is from the probe's configuration.\nsamples_tolerance_retries: default from \"probe:samples_tolerance_retries\" section\n#   The number of times to retry if a sample is found that exceeds\n#   samples_tolerance. The default is from the probe's configuration.\nsamples_result: default from \"probe:samples_result\" section\n#   The calculation method when sampling more than once - either\n#   \"median\" or \"average\". The default is from the probe's configuration.\nclearance: 2 * z_offset from the \"probe:z_offset\" section\n#   The distance in mm to move up before moving to the next\n#   position. The default is two times the z_offset from the probe's\n#   configuration.\nposition_min: default from \"stepper_z:position_min\" section.\n#   Minimum valid distance (in mm) used for probing move. The\n#   default is from the Z rail configuration.\nspeed: 50\n#   The moving speed in X and Y. The default is 50 mm/s.\nlift_speed: default from \"probe:lift_speed\" section\n#   Speed (in mm/s) of the Z axis when lifting the probe between\n#   samples and clearance moves. The default is from the probe's\n#   configuration.\nprobing_speed: default from \"stepper_z:homing_speed\" section.\n#   The fast probing speed (in mm/s) used, when probing_first_fast\n#   is activated. The default is from the Z rail configuration.\nprobing_second_speed: default from \"stepper_z:second_homing_speed\" section.\n#   The slower speed (in mm/s) for probing the recorded samples.\n#   The default is second_homing_speed of the Z rail configuration.\nprobing_retract_dist: default from \"stepper_z:homing_retract_dist\" section.\n#   Distance to retract (in mm) before probing the next sample.\n#   The default is homing_retract_dist from the Z rail configuration.\nprobing_first_fast: false\n#   If true, the first probing is done faster by the probing speed.\n#   This is to get faster down and the result is not recorded as a\n#   probing sample. The default is false.\nstart_gcode:\n#   A list of G-Code commands to execute prior to each calibration command.\n#   See docs/Command_Templates.md for G-Code format. This can be used to\n#   attach the probe.\nbefore_switch_gcode:\n#   A list of G-Code commands to execute prior to each probing on the\n#   mag-probe. See docs/Command_Templates.md for G-Code format. This can be\n#   used to attach the probe after probing on the nozzle and before probing\n#   on the mag-probe.\nend_gcode:\n#   A list of G-Code commands to execute after each calibration command.\n#   See docs/Command_Templates.md for G-Code format. This can be used to\n#   detach the probe afterwards.\n
    "},{"location":"Config_Reference.html#additional-stepper-motors-and-extruders","title":"Additional stepper motors and extruders","text":""},{"location":"Config_Reference.html#stepper_z1","title":"[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]\n#step_pin:\n#dir_pin:\n#enable_pin:\n#microsteps:\n#rotation_distance:\n#   See the \"stepper\" section for the definition of the above parameters.\n#endstop_pin:\n#   If an endstop_pin is defined for the additional stepper then the\n#   stepper will home until the endstop is triggered. Otherwise, the\n#   stepper will home until the endstop on the primary stepper for the\n#   axis is triggered.\n
    "},{"location":"Config_Reference.html#extruder1","title":"[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]\n#step_pin:\n#dir_pin:\n#...\n#   See the \"extruder\" section for available stepper and heater\n#   parameters.\n#shared_heater:\n#   This option is deprecated and should no longer be specified.\n
    "},{"location":"Config_Reference.html#dual_carriage","title":"[dual_carriage]","text":"

    Support for cartesian and hybrid_corexy/z printers with dual carriages on a single axis. The carriage mode can be set via the SET_DUAL_CARRIAGE extended g-code command. For example, \"SET_DUAL_CARRIAGE CARRIAGE=1\" command will activate the carriage defined in this section (CARRIAGE=0 will return activation to the primary carriage). Dual carriage support is typically combined with extra extruders - the SET_DUAL_CARRIAGE command is often called at the same time as the ACTIVATE_EXTRUDER command. Be sure to park the carriages during deactivation. Note that during G28 homing, typically the primary carriage is homed first followed by the carriage defined in the [dual_carriage] config section. However, the [dual_carriage] carriage will be homed first if both carriages home in a positive direction and the [dual_carriage] carriage has a position_endstop greater than the primary carriage, or if both carriages home in a negative direction and the [dual_carriage] carriage has a position_endstop less than the primary carriage.

    Additionally, one could use \"SET_DUAL_CARRIAGE CARRIAGE=1 MODE=COPY\" or \"SET_DUAL_CARRIAGE CARRIAGE=1 MODE=MIRROR\" commands to activate either copying or mirroring mode of the dual carriage, in which case it will follow the motion of the carriage 0 accordingly. These commands can be used to print two parts simultaneously - either two identical parts (in COPY mode) or mirrored parts (in MIRROR mode). Note that COPY and MIRROR modes also require appropriate configuration of the extruder on the dual carriage, which can typically be achieved with \"SYNC_EXTRUDER_MOTION MOTION_QUEUE=extruder EXTRUDER=\" or a similar command.

    See sample-idex.cfg for an example configuration.

    [dual_carriage]\naxis:\n#   The axis this extra carriage is on (either x or y). This parameter\n#   must be provided.\n#safe_distance:\n#   The minimum distance (in mm) to enforce between the dual and the primary\n#   carriages. If a G-Code command is executed that will bring the carriages\n#   closer than the specified limit, such a command will be rejected with an\n#   error. If safe_distance is not provided, it will be inferred from\n#   position_min and position_max for the dual and primary carriages. If set\n#   to 0 (or safe_distance is unset and position_min and position_max are\n#   identical for the primary and dual carraiges), the carriages proximity\n#   checks will be disabled.\n#step_pin:\n#dir_pin:\n#enable_pin:\n#microsteps:\n#rotation_distance:\n#endstop_pin:\n#position_endstop:\n#position_min:\n#position_max:\n#   See the \"stepper\" section for the definition of the above parameters.\n
    "},{"location":"Config_Reference.html#extruder_stepper","title":"[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]\nextruder:\n#   The extruder this stepper is synchronized to. If this is set to an\n#   empty string then the stepper will not be synchronized to an\n#   extruder. This parameter must be provided.\n#step_pin:\n#dir_pin:\n#enable_pin:\n#microsteps:\n#rotation_distance:\n#   See the \"stepper\" section for the definition of the above\n#   parameters.\n
    "},{"location":"Config_Reference.html#manual_stepper","title":"[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]\n#step_pin:\n#dir_pin:\n#enable_pin:\n#microsteps:\n#rotation_distance:\n#   See the \"stepper\" section for a description of these parameters.\n#velocity:\n#   Set the default velocity (in mm/s) for the stepper. This value\n#   will be used if a MANUAL_STEPPER command does not specify a SPEED\n#   parameter. The default is 5mm/s.\n#accel:\n#   Set the default acceleration (in mm/s^2) for the stepper. An\n#   acceleration of zero will result in no acceleration. This value\n#   will be used if a MANUAL_STEPPER command does not specify an ACCEL\n#   parameter. The default is zero.\n#endstop_pin:\n#   Endstop switch detection pin. If specified, then one may perform\n#   \"homing moves\" by adding a STOP_ON_ENDSTOP parameter to\n#   MANUAL_STEPPER movement commands.\n
    "},{"location":"Config_Reference.html#mixing_extruder","title":"[mixing_extruder]","text":"

    A mixing printhead which has in-1out mixing nozzle. When activated additional G-Code Commands are available. See G-Codes for a detailed description of the additional commands. 

    [mixing_extruder]\n#steppers:\n#   Which steppers feed into the hotend/nozzle. provide a comma\n#   separated list, eg. \"extruder,extruder1,extruder2\". Should be\n#   the names of either extruder sections or extruder_stepper sections\n#   This configuration is required.\n#extruder_name:\n#   The name of the extruder to synchronize the steppers in the steppers\n#   list to.\n#   The default is the first entry in the\n#   \"steppers\" list.\n
    "},{"location":"Config_Reference.html#custom-heaters-and-sensors","title":"Custom heaters and sensors","text":""},{"location":"Config_Reference.html#verify_heater","title":"[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]\n#max_error: 120\n#   The maximum \"cumulative temperature error\" before raising an\n#   error. Smaller values result in stricter checking and larger\n#   values allow for more time before an error is reported.\n#   Specifically, the temperature is inspected once a second and if it\n#   is close to the target temperature then an internal \"error\n#   counter\" is reset; otherwise, if the temperature is below the\n#   target range then the counter is increased by the amount the\n#   reported temperature differs from that range. Should the counter\n#   exceed this \"max_error\" then an error is raised. The default is\n#   120.\n#check_gain_time:\n#   This controls heater verification during initial heating. Smaller\n#   values result in stricter checking and larger values allow for\n#   more time before an error is reported. Specifically, during\n#   initial heating, as long as the heater increases in temperature\n#   within this time frame (specified in seconds) then the internal\n#   \"error counter\" is reset. The default is 20 seconds for extruders\n#   and 60 seconds for heater_bed.\n#hysteresis: 5\n#   The maximum temperature difference (in Celsius) to a target\n#   temperature that is considered in range of the target. This\n#   controls the max_error range check. It is rare to customize this\n#   value. The default is 5.\n#heating_gain: 2\n#   The minimum temperature (in Celsius) that the heater must increase\n#   by during the check_gain_time check. It is rare to customize this\n#   value. The default is 2.\n
    "},{"location":"Config_Reference.html#homing_heaters","title":"[homing_heaters]","text":"

    Tool to disable heaters when homing or probing an axis.

    [homing_heaters]\n#steppers:\n#   A comma separated list of steppers that should cause heaters to be\n#   disabled. The default is to disable heaters for any homing/probing\n#   move.\n#   Typical example: stepper_z\n#heaters:\n#   A comma separated list of heaters to disable during homing/probing\n#   moves. The default is to disable all heaters.\n#   Typical example: extruder, heater_bed\n
    "},{"location":"Config_Reference.html#thermistor","title":"[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]\n#temperature1:\n#resistance1:\n#temperature2:\n#resistance2:\n#temperature3:\n#resistance3:\n#   Three resistance measurements (in Ohms) at the given temperatures\n#   (in Celsius). The three measurements will be used to calculate the\n#   Steinhart-Hart coefficients for the thermistor. These parameters\n#   must be provided when using Steinhart-Hart to define the\n#   thermistor.\n#beta:\n#   Alternatively, one may define temperature1, resistance1, and beta\n#   to define the thermistor parameters. This parameter must be\n#   provided when using \"beta\" to define the thermistor.\n
    "},{"location":"Config_Reference.html#adc_temperature","title":"[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]\n#temperature1:\n#voltage1:\n#temperature2:\n#voltage2:\n#...\n#   A set of temperatures (in Celsius) and voltages (in Volts) to use\n#   as reference when converting a temperature. A heater section using\n#   this sensor may also specify adc_voltage and voltage_offset\n#   parameters to define the ADC voltage (see \"Common temperature\n#   amplifiers\" section for details). At least two measurements must\n#   be provided.\n#temperature1:\n#resistance1:\n#temperature2:\n#resistance2:\n#...\n#   Alternatively one may specify a set of temperatures (in Celsius)\n#   and resistance (in Ohms) to use as reference when converting a\n#   temperature. A heater section using this sensor may also specify a\n#   pullup_resistor parameter (see \"extruder\" section for details). At\n#   least two measurements must be provided.\n
    "},{"location":"Config_Reference.html#heater_generic","title":"[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]\n#gcode_id:\n#   The id to use when reporting the temperature in the M105 command.\n#   This parameter must be provided.\n#heater_pin:\n#max_power:\n#sensor_type:\n#sensor_pin:\n#smooth_time:\n#control:\n#pid_Kp:\n#pid_Ki:\n#pid_Kd:\n#pwm_cycle_time:\n#min_temp:\n#max_temp:\n#   See the \"extruder\" section for the definition of the above\n#   parameters.\n
    "},{"location":"Config_Reference.html#temperature_sensor","title":"[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]\n#sensor_type:\n#sensor_pin:\n#min_temp:\n#max_temp:\n#   See the \"extruder\" section for the definition of the above\n#   parameters.\n#gcode_id:\n#   See the \"heater_generic\" section for the definition of this\n#   parameter.\n
    "},{"location":"Config_Reference.html#temperature-sensors","title":"Temperature sensors","text":"

    Kalico 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).

    "},{"location":"Config_Reference.html#common-thermistors","title":"Common thermistors","text":"

    Common thermistors. The following parameters are available in heater sections that use one of these sensors.

    sensor_type:\n#   One of \"EPCOS 100K B57560G104F\", \"ATC Semitec 104GT-2\",\n#   \"ATC Semitec 104NT-4-R025H42G\", \"Generic 3950\",\n#   \"Honeywell 100K 135-104LAG-J01\", \"NTC 100K MGB18-104F39050L32\",\n#   \"SliceEngineering 450\", or \"TDK NTCG104LH104JT1\"\nsensor_pin:\n#   Analog input pin connected to the thermistor. This parameter must\n#   be provided.\n#pullup_resistor: 4700\n#   The resistance (in ohms) of the pullup attached to the thermistor.\n#   The default is 4700 ohms.\n#inline_resistor: 0\n#   The resistance (in ohms) of an extra (not heat varying) resistor\n#   that is placed inline with the thermistor. It is rare to set this.\n#   The default is 0 ohms.\n
    "},{"location":"Config_Reference.html#common-temperature-amplifiers","title":"Common temperature amplifiers","text":"

    Common temperature amplifiers. The following parameters are available in heater sections that use one of these sensors.

    sensor_type:\n#   One of \"PT100 INA826\", \"AD595\", \"AD597\", \"AD8494\", \"AD8495\",\n#   \"AD8496\", or \"AD8497\".\nsensor_pin:\n#   Analog input pin connected to the sensor. This parameter must be\n#   provided.\n#adc_voltage: 5.0\n#   The ADC comparison voltage (in Volts). The default is 5 volts.\n#voltage_offset: 0\n#   The ADC voltage offset (in Volts). The default is 0.\n
    "},{"location":"Config_Reference.html#directly-connected-pt1000-sensor","title":"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\nsensor_pin:\n#   Analog input pin connected to the sensor. This parameter must be\n#   provided.\n#pullup_resistor: 4700\n#   The resistance (in ohms) of the pullup attached to the sensor. The\n#   default is 4700 ohms.\n
    "},{"location":"Config_Reference.html#maxxxxxx-temperature-sensors","title":"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:\n#   One of \"MAX6675\", \"MAX31855\", \"MAX31856\", or \"MAX31865\".\nsensor_pin:\n#   The chip select line for the sensor chip. This parameter must be\n#   provided.\n#spi_speed: 4000000\n#   The SPI speed (in hz) to use when communicating with the chip.\n#   The default is 4000000.\n#spi_bus:\n#spi_software_sclk_pin:\n#spi_software_mosi_pin:\n#spi_software_miso_pin:\n#   See the \"common SPI settings\" section for a description of the\n#   above parameters.\n#tc_type: K\n#tc_use_50Hz_filter: False\n#tc_averaging_count: 1\n#   The above parameters control the sensor parameters of MAX31856\n#   chips. The defaults for each parameter are next to the parameter\n#   name in the above list.\n#rtd_nominal_r: 100\n#rtd_reference_r: 430\n#rtd_num_of_wires: 2\n#rtd_use_50Hz_filter: False\n#   The above parameters control the sensor parameters of MAX31865\n#   chips. The defaults for each parameter are next to the parameter\n#   name in the above list.\n
    "},{"location":"Config_Reference.html#bmp180bmp280bme280bmp388bme680-temperature-sensor","title":"BMP180/BMP280/BME280/BMP388/BME680 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\n#i2c_address:\n#   Default is 118 (0x76). The BMP180, BMP388 and some BME280 sensors\n#   have an address of 119 (0x77).\n#i2c_mcu:\n#i2c_bus:\n#i2c_software_scl_pin:\n#i2c_software_sda_pin:\n#i2c_speed:\n#   See the \"common I2C settings\" section for a description of the\n#   above parameters.\n
    "},{"location":"Config_Reference.html#aht10aht20aht21-temperature-sensor","title":"AHT10/AHT20/AHT21 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\n#   Also use AHT10 for AHT20 and AHT21 sensors.\n#i2c_address:\n#   Default is 56 (0x38). Some AHT10 sensors give the option to use\n#   57 (0x39) by moving a resistor.\n#i2c_mcu:\n#i2c_bus:\n#i2c_speed:\n#   See the \"common I2C settings\" section for a description of the\n#   above parameters.\n#aht10_report_time:\n#   Interval in seconds between readings. Default is 30, minimum is 5\n
    "},{"location":"Config_Reference.html#htu21d-sensor","title":"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:\n#   Must be \"HTU21D\" , \"SI7013\", \"SI7020\", \"SI7021\" or \"SHT21\"\n#i2c_address:\n#   Default is 64 (0x40).\n#i2c_mcu:\n#i2c_bus:\n#i2c_software_scl_pin:\n#i2c_software_sda_pin:\n#i2c_speed:\n#   See the \"common I2C settings\" section for a description of the\n#   above parameters.\n#htu21d_hold_master:\n#   If the sensor can hold the I2C buf while reading. If True no other\n#   bus communication can be performed while reading is in progress.\n#   Default is False.\n#htu21d_resolution:\n#   The resolution of temperature and humidity reading.\n#   Valid values are:\n#    'TEMP14_HUM12' -> 14bit for Temp and 12bit for humidity\n#    'TEMP13_HUM10' -> 13bit for Temp and 10bit for humidity\n#    'TEMP12_HUM08' -> 12bit for Temp and 08bit for humidity\n#    'TEMP11_HUM11' -> 11bit for Temp and 11bit for humidity\n#   Default is: \"TEMP11_HUM11\"\n#htu21d_report_time:\n#   Interval in seconds between readings. Default is 30\n
    "},{"location":"Config_Reference.html#sht3x-sensor","title":"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\n#i2c_address:\n#   Default is 68 (0x44).\n#i2c_mcu:\n#i2c_bus:\n#i2c_software_scl_pin:\n#i2c_software_sda_pin:\n#i2c_speed:\n#   See the \"common I2C settings\" section for a description of the\n#   above parameters.\n
    "},{"location":"Config_Reference.html#lm75-temperature-sensor","title":"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\n#i2c_address:\n#   Default is 72 (0x48). Normal range is 72-79 (0x48-0x4F) and the 3\n#   low bits of the address are configured via pins on the chip\n#   (usually with jumpers or hard wired).\n#i2c_mcu:\n#i2c_bus:\n#i2c_software_scl_pin:\n#i2c_software_sda_pin:\n#i2c_speed:\n#   See the \"common I2C settings\" section for a description of the\n#   above parameters.\n#lm75_report_time:\n#   Interval in seconds between readings. Default is 0.8, with minimum\n#   0.5.\n
    "},{"location":"Config_Reference.html#builtin-micro-controller-temperature-sensor","title":"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\n#sensor_mcu: mcu\n#   The micro-controller to read from. The default is \"mcu\".\n#reference_voltage:\n#   The reference voltage for the ADC of the mcu. Default is 3.3\n#sensor_temperature1:\n#sensor_adc1:\n#   Specify the above two parameters (a temperature in Celsius and an\n#   ADC value as a float between 0.0 and 1.0) to calibrate the\n#   micro-controller temperature. This may improve the reported\n#   temperature accuracy on some chips. A typical way to obtain this\n#   calibration information is to completely remove power from the\n#   printer for a few hours (to ensure it is at the ambient\n#   temperature), then power it up and use the QUERY_ADC command to\n#   obtain an ADC measurement. Use some other temperature sensor on\n#   the printer to find the corresponding ambient temperature. The\n#   default is to use the factory calibration data on the\n#   micro-controller (if applicable) or the nominal values from the\n#   micro-controller specification.\n#sensor_temperature2:\n#sensor_adc2:\n#   If sensor_temperature1/sensor_adc1 is specified then one may also\n#   specify sensor_temperature2/sensor_adc2 calibration data. Doing so\n#   may provide calibrated \"temperature slope\" information. The\n#   default is to use the factory calibration data on the\n#   micro-controller (if applicable) or the nominal values from the\n#   micro-controller specification.\n
    "},{"location":"Config_Reference.html#host-temperature-sensor","title":"Host temperature sensor","text":"

    Temperature from the machine (eg Raspberry Pi) running the host software.

    sensor_type: temperature_host\n#sensor_path:\n#   The path to temperature system file. The default is\n#   \"/sys/class/thermal/thermal_zone0/temp\" which is the temperature\n#   system file on a Raspberry Pi computer.\n
    "},{"location":"Config_Reference.html#ds18b20-temperature-sensor","title":"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\nserial_no:\n#   Each 1-wire device has a unique serial number used to identify the device,\n#   usually in the format 28-031674b175ff. This parameter must be provided.\n#   Attached 1-wire devices can be listed using the following Linux command:\n#   ls /sys/bus/w1/devices/\n#ds18_report_time:\n#   Interval in seconds between readings. Default is 3.0, with a minimum of 1.0\n#sensor_mcu:\n#   The micro-controller to read from. Must be the host_mcu\n
    "},{"location":"Config_Reference.html#combined-temperature-sensor","title":"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\n#sensor_list:\n#   Must be provided. List of sensors to combine to new \"virtual\"\n#   sensor.\n#   E.g. 'temperature_sensor sensor1,extruder,heater_bed'\n#combination_method:\n#   Must be provided. Combination method used for the sensor.\n#   Available options are 'max', 'min', 'mean'.\n#maximum_deviation:\n#   Must be provided. Maximum permissible deviation between the sensors\n#   to combine (e.g. 5 degrees). To disable it, use a large value (e.g. 999.9)\n
    "},{"location":"Config_Reference.html#fans","title":"Fans","text":""},{"location":"Config_Reference.html#fan","title":"[fan]","text":"

    Print cooling fan.

    [fan]\npin:\n#   Output pin controlling the fan. This parameter must be provided.\n#max_power: 1.0\n#   The maximum power (0.0 to 1.0) that the pin may be set to. A value\n#   of 1.0 enables the pin fully for extended periods, while 0.5 allows\n#   it for no more than half the time. Use it to limit total power output\n#   (over extended periods) to the fan. This value is combined with\n#   min_power to scale fan speed. With `min_power` at 0.3 and\n#   `max_power` at 1.0, fan speed request scales between 0.3 (min_power)\n#   and 1.0 (max_power). Requesting 10% fan speed results in a value of\n#   0.37. Default is 1.0.\n#shutdown_speed: 0\n#   The desired fan speed (expressed as a value from 0.0 to 1.0) if\n#   the micro-controller software enters an error state. The default\n#   is 0.\n#cycle_time: 0.010\n#   The amount of time (in seconds) for each PWM power cycle to the\n#   fan. It is recommended this be 10 milliseconds or greater when\n#   using software based PWM. The default is 0.010 seconds.\n#hardware_pwm: False\n#   Enable this to use hardware PWM instead of software PWM. Most fans\n#   do not work well with hardware PWM, so it is not recommended to\n#   enable this unless there is an electrical requirement to switch at\n#   very high speeds. When using hardware PWM the actual cycle time is\n#   constrained by the implementation and may be significantly\n#   different than the requested cycle_time. The default is False.\n#kick_start_time: 0.100\n#   Time (in seconds) to run the fan at full speed when either first\n#   enabling or increasing it by more than 50% (helps get the fan\n#   spinning). The default is 0.100 seconds.\n#min_power: 0.0\n#   The minimum input power which will power the fan (expressed as a\n#   value from 0.0 to 1.0). The default is 0.0.\n#\n#   To calibrate this setting, start with min_power=0 and max_power=1\n#   Gradually lower the fan speed to determine the lowest\n#   input speed which reliably drives the fan without stalls. Set\n#   min_power to the duty cycle corresponding to this value (for\n#   example, 12% -> 0.12) or slightly higher.\n#tachometer_pin:\n#   Tachometer input pin for monitoring fan speed. A pullup is generally\n#   required. This parameter is optional.\n#tachometer_ppr: 2\n#   When tachometer_pin is specified, this is the number of pulses per\n#   revolution of the tachometer signal. For a BLDC fan this is\n#   normally half the number of poles. The default is 2.\n#tachometer_poll_interval: 0.0015\n#   When tachometer_pin is specified, this is the polling period of the\n#   tachometer pin, in seconds. The default is 0.0015, which is fast\n#   enough for fans below 10000 RPM at 2 PPR. This must be smaller than\n#   30/(tachometer_ppr*rpm), with some margin, where rpm is the\n#   maximum speed (in RPM) of the fan.\n#enable_pin:\n#   Optional pin to enable power to the fan. This can be useful for fans\n#   with dedicated PWM inputs. Some of these fans stay on even at 0% PWM\n#   input. In such a case, the PWM pin can be used normally, and e.g. a\n#   ground-switched FET(standard fan pin) can be used to control power to\n#   the fan.\n#off_below:\n#   These option is deprecated and should no longer be specified.\n#   Use `min_power` instead.\n#initial_speed:\n#   Fan speed will be set to this value on startup if specified. Value\n#   is from 0.0 to 1.0.\n
    "},{"location":"Config_Reference.html#heated_fan","title":"[heated_fan]","text":"

    Heated print cooling fans. An experimental module for high-temperature printing that requires part cooling air to be closer to the printed part temperature.

    [heated_fan]\n#   See the \"fan\" section for a description for fan parameters.\n#   See the \"heater_generic\" section for a description for the heater\n#   parameters.\n#heater_temp: 50\n#   The target temperature (in Celsius) for the heater when the fan is\n#   turned on. The default is 50 Celsius.\n#min_speed: 1.0\n#   The minimum fan speed (expressed as a value from 0.0 to 1.0) that the\n#   fan will be set to when its associated heater is on (e.g.: to protect\n#   ducts from melting). If the fan is set to a speed lower than min_speed,\n#   the min_speed value is applied. The default is 1.0 (100%)\n#idle_timeout: 60\n#   A timeout in seconds for the fan to stay on when it is requested to turn\n#   off, to protect ducts from melting. The default is 60 (s).\n
    "},{"location":"Config_Reference.html#heater_fan","title":"[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]\n#pin:\n#max_power:\n#shutdown_speed:\n#cycle_time:\n#hardware_pwm:\n#kick_start_time:\n#min_power:\n#tachometer_pin:\n#tachometer_ppr:\n#tachometer_poll_interval:\n#enable_pin:\n#initial_speed:\n#   See the \"fan\" section for a description of the above parameters.\n#heater: extruder\n#   Name of the config section defining the heater that this fan is\n#   associated with. If a comma separated list of heater names is\n#   provided here, then the fan will be enabled when any of the given\n#   heaters are enabled. The default is \"extruder\".\n#heater_temp: 50.0\n#   A temperature (in Celsius) that the heater must drop below before\n#   the fan is disabled. The default is 50 Celsius.\n#fan_speed: 1.0\n#   The fan speed (expressed as a value from 0.0 to 1.0) that the fan\n#   will be set to when its associated heater is enabled. The default\n#   is 1.0\n
    "},{"location":"Config_Reference.html#controller_fan","title":"[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]\n#pin:\n#max_power:\n#shutdown_speed:\n#cycle_time:\n#hardware_pwm:\n#kick_start_time:\n#min_power:\n#tachometer_pin:\n#tachometer_ppr:\n#tachometer_poll_interval:\n#enable_pin:\n#   See the \"fan\" section for a description of the above parameters.\n#fan_speed: 1.0\n#   The fan speed (expressed as a value from 0.0 to 1.0) that the fan\n#   will be set to when a heater or stepper driver is active.\n#   The default is 1.0\n#idle_timeout:\n#   The amount of time (in seconds) after a stepper driver or heater\n#   was active and the fan should be kept running. The default\n#   is 30 seconds.\n#idle_speed:\n#   The fan speed (expressed as a value from 0.0 to 1.0) that the fan\n#   will be set to when a heater or stepper driver was active and\n#   before the idle_timeout is reached. The default is fan_speed.\n#heater:\n#stepper:\n#   Name of the config section defining the heater/stepper that this fan\n#   is associated with. If a comma separated list of heater/stepper names\n#   is provided here, then the fan will be enabled when any of the given\n#   heaters/steppers are enabled. The default heater is \"extruder\", the\n#   default stepper is all of them.\n
    "},{"location":"Config_Reference.html#temperature_fan","title":"[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]\n#pin:\n#max_power:\n#shutdown_speed:\n#cycle_time:\n#hardware_pwm:\n#kick_start_time:\n#min_power:\n#tachometer_pin:\n#tachometer_ppr:\n#tachometer_poll_interval:\n#enable_pin:\n#   See the \"fan\" section for a description of the above parameters.\n#sensor_type:\n#sensor_pin:\n#control:\n#max_delta:\n#min_temp:\n#max_temp:\n#   See the \"extruder\" section for a description of the above parameters.\n#pid_Kp:\n#pid_Ki:\n#pid_Kd:\n#   The proportional (pid_Kp), integral (pid_Ki), and derivative\n#   (pid_Kd) settings for the PID feedback control system. Kalico\n#   evaluates the PID settings with the following general formula:\n#     fan_pwm = max_power - (Kp*e + Ki*integral(e) - Kd*derivative(e)) / 255\n#   Where \"e\" is \"target_temperature - measured_temperature\" and\n#   \"fan_pwm\" is the requested fan rate with 0.0 being full off and\n#   1.0 being full on. The pid_Kp, pid_Ki, and pid_Kd parameters must\n#   be provided when the PID control algorithm is enabled.\n#pid_deriv_time: 2.0\n#   A time value (in seconds) over which temperature measurements will\n#   be smoothed when using the PID control algorithm. This may reduce\n#   the impact of measurement noise. The default is 2 seconds.\n#target_temp: 40.0\n#   A temperature (in Celsius) that will be the target temperature.\n#   The default is 40 degrees.\n#max_speed: 1.0\n#   The fan speed (expressed as a value from 0.0 to 1.0) that the fan\n#   will be set to when the sensor temperature exceeds the set value.\n#   The default is 1.0.\n#min_speed: 0.3\n#   The minimum fan speed (expressed as a value from 0.0 to 1.0) that\n#   the fan will be set to for PID temperature fans.\n#   The default is 0.3.\n#gcode_id:\n#   If set, the temperature will be reported in M105 queries using the\n#   given id. The default is to not report the temperature via M105.\n#reverse: False\n#   If true, the working mode of the fan is reversed. If the temperature\n#   is lower than the target temperature, the fan speed increases;\n#   otherwise, the fan speed decreases.\n#   The default is False.\n
    control: curve\n#points:\n#  50.0, 0.0\n#  55.0, 0.5\n#   A user might defne a list of points which consist of a temperature with\n#   it's associated fan speed (temp, fan_speed).\n#   The target_temp value defines the temperature at which the fan will run\n#   at full speed.\n#   The algorithm will use linear interpolation to get the fan speeds\n#   between two points (if one has defined 0.0 for 50\u00b0 and 1.0 for 60\u00b0 the\n#   fan would run with 0.5 at 55\u00b0)\n#cooling_hysteresis: 0.0\n#   define the temperature hysteresis for lowering the fan speed\n#   (in simple terms this setting offsets the fan curve when cooling down\n#   by the specified amount of degrees celsius. For example, if the\n#   hysteresis is set to 5\u00b0C, the fan curve will be moved by -5\u00b0C. This\n#   setting can be used to reduce the effects of quickly changing\n#   temperatures around a target temperature which would cause the fan to\n#   speed up and slow down repeatedly.)\n#heating_hysteresis: 0.0\n#   same as cooling_hysteresis but for increasing the fan speed, it is\n#   recommended to be left at 0 for safety reasons\n#smooth_readings: 10\n#   This parameter is deprecated and should no longer be used.\n
    "},{"location":"Config_Reference.html#fan_generic","title":"[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]\n#pin:\n#max_power:\n#shutdown_speed:\n#cycle_time:\n#hardware_pwm:\n#kick_start_time:\n#min_power:\n#tachometer_pin:\n#tachometer_ppr:\n#tachometer_poll_interval:\n#enable_pin:\n#   See the \"fan\" section for a description of the above parameters.\n
    "},{"location":"Config_Reference.html#leds","title":"LEDs","text":""},{"location":"Config_Reference.html#led","title":"[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]\n#red_pin:\n#green_pin:\n#blue_pin:\n#white_pin:\n#   The pin controlling the given LED color. At least one of the above\n#   parameters must be provided.\n#cycle_time: 0.010\n#   The amount of time (in seconds) per PWM cycle. It is recommended\n#   this be 10 milliseconds or greater when using software based PWM.\n#   The default is 0.010 seconds.\n#hardware_pwm: False\n#   Enable this to use hardware PWM instead of software PWM. When\n#   using hardware PWM the actual cycle time is constrained by the\n#   implementation and may be significantly different than the\n#   requested cycle_time. The default is False.\n#initial_RED: 0.0\n#initial_GREEN: 0.0\n#initial_BLUE: 0.0\n#initial_WHITE: 0.0\n#   Sets the initial LED color. Each value should be between 0.0 and\n#   1.0. The default for each color is 0.\n
    "},{"location":"Config_Reference.html#neopixel","title":"[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]\npin:\n#   The pin connected to the neopixel. This parameter must be\n#   provided.\n#chain_count:\n#   The number of Neopixel chips that are \"daisy chained\" to the\n#   provided pin. The default is 1 (which indicates only a single\n#   Neopixel is connected to the pin).\n#color_order: GRB\n#   Set the pixel order required by the LED hardware (using a string\n#   containing the letters R, G, B, W with W optional). Alternatively,\n#   this may be a comma separated list of pixel orders - one for each\n#   LED in the chain. The default is GRB.\n#initial_RED: 0.0\n#initial_GREEN: 0.0\n#initial_BLUE: 0.0\n#initial_WHITE: 0.0\n#   See the \"led\" section for information on these parameters.\n
    "},{"location":"Config_Reference.html#dotstar","title":"[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]\ndata_pin:\n#   The pin connected to the data line of the dotstar. This parameter\n#   must be provided.\nclock_pin:\n#   The pin connected to the clock line of the dotstar. This parameter\n#   must be provided.\n#chain_count:\n#   See the \"neopixel\" section for information on this parameter.\n#initial_RED: 0.0\n#initial_GREEN: 0.0\n#initial_BLUE: 0.0\n#   See the \"led\" section for information on these parameters.\n
    "},{"location":"Config_Reference.html#pca9533","title":"[pca9533]","text":"

    PCA9533 LED support. The PCA9533 is used on the mightyboard.

    [pca9533 my_pca9533]\n#i2c_address: 98\n#   The i2c address that the chip is using on the i2c bus. Use 98 for\n#   the PCA9533/1, 99 for the PCA9533/2. The default is 98.\n#i2c_mcu:\n#i2c_bus:\n#i2c_software_scl_pin:\n#i2c_software_sda_pin:\n#i2c_speed:\n#   See the \"common I2C settings\" section for a description of the\n#   above parameters.\n#initial_RED: 0.0\n#initial_GREEN: 0.0\n#initial_BLUE: 0.0\n#initial_WHITE: 0.0\n#   See the \"led\" section for information on these parameters.\n
    "},{"location":"Config_Reference.html#pca9632","title":"[pca9632]","text":"

    PCA9632 LED support. The PCA9632 is used on the FlashForge Dreamer.

    [pca9632 my_pca9632]\n#i2c_address: 98\n#   The i2c address that the chip is using on the i2c bus. This may be\n#   96, 97, 98, or 99.  The default is 98.\n#i2c_mcu:\n#i2c_bus:\n#i2c_software_scl_pin:\n#i2c_software_sda_pin:\n#i2c_speed:\n#   See the \"common I2C settings\" section for a description of the\n#   above parameters.\n#scl_pin:\n#sda_pin:\n#   Alternatively, if the pca9632 is not connected to a hardware I2C\n#   bus, then one may specify the \"clock\" (scl_pin) and \"data\"\n#   (sda_pin) pins. The default is to use hardware I2C.\n#color_order: RGBW\n#   Set the pixel order of the LED (using a string containing the\n#   letters R, G, B, W). The default is RGBW.\n#initial_RED: 0.0\n#initial_GREEN: 0.0\n#initial_BLUE: 0.0\n#initial_WHITE: 0.0\n#   See the \"led\" section for information on these parameters.\n
    "},{"location":"Config_Reference.html#additional-servos-buttons-and-other-pins","title":"Additional servos, buttons, and other pins","text":""},{"location":"Config_Reference.html#servo","title":"[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]\npin:\n#   PWM output pin controlling the servo. This parameter must be\n#   provided.\n#maximum_servo_angle: 180\n#   The maximum angle (in degrees) that this servo can be set to. The\n#   default is 180 degrees.\n#minimum_pulse_width: 0.001\n#   The minimum pulse width time (in seconds). This should correspond\n#   with an angle of 0 degrees. The default is 0.001 seconds.\n#maximum_pulse_width: 0.002\n#   The maximum pulse width time (in seconds). This should correspond\n#   with an angle of maximum_servo_angle. The default is 0.002\n#   seconds.\n#initial_angle:\n#   Initial angle (in degrees) to set the servo to. The default is to\n#   not send any signal at startup.\n#initial_pulse_width:\n#   Initial pulse width time (in seconds) to set the servo to. (This\n#   is only valid if initial_angle is not set.) The default is to not\n#   send any signal at startup.\n
    "},{"location":"Config_Reference.html#gcode_button","title":"[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]\npin:\n#   The pin on which the button is connected. This parameter must be\n#   provided.\n#analog_range:\n#   Two comma separated resistances (in Ohms) specifying the minimum\n#   and maximum resistance range for the button. If analog_range is\n#   provided then the pin must be an analog capable pin. The default\n#   is to use digital gpio for the button.\n#analog_pullup_resistor:\n#   The pullup resistance (in Ohms) when analog_range is specified.\n#   The default is 4700 ohms.\n#press_gcode:\n#   A list of G-Code commands to execute when the button is pressed.\n#   G-Code templates are supported. This parameter must be provided.\n#release_gcode:\n#   A list of G-Code commands to execute when the button is released.\n#   G-Code templates are supported. The default is to not run any\n#   commands on a button release.\n
    "},{"location":"Config_Reference.html#output_pin","title":"[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]\npin:\n#   The pin to configure as an output. This parameter must be\n#   provided.\n#pwm: False\n#   Set if the output pin should be capable of pulse-width-modulation.\n#   If this is true, the value fields should be between 0 and 1; if it\n#   is false the value fields should be either 0 or 1. The default is\n#   False.\n#value:\n#   The value to initially set the pin to during MCU configuration.\n#   The default is 0 (for low voltage).\n#shutdown_value:\n#   The value to set the pin to on an MCU shutdown event. The default\n#   is 0 (for low voltage).\n#cycle_time: 0.100\n#   The amount of time (in seconds) per PWM cycle. It is recommended\n#   this be 10 milliseconds or greater when using software based PWM.\n#   The default is 0.100 seconds for pwm pins.\n#hardware_pwm: False\n#   Enable this to use hardware PWM instead of software PWM. When\n#   using hardware PWM the actual cycle time is constrained by the\n#   implementation and may be significantly different than the\n#   requested cycle_time. The default is False.\n#scale:\n#   This parameter can be used to alter how the 'value' and\n#   'shutdown_value' parameters are interpreted for pwm pins. If\n#   provided, then the 'value' parameter should be between 0.0 and\n#   'scale'. This may be useful when configuring a PWM pin that\n#   controls a stepper voltage reference. The 'scale' can be set to\n#   the equivalent stepper amperage if the PWM were fully enabled, and\n#   then the 'value' parameter can be specified using the desired\n#   amperage for the stepper. The default is to not scale the 'value'\n#   parameter.\n#maximum_mcu_duration:\n#static_value:\n#   These options are deprecated and should no longer be specified.\n
    "},{"location":"Config_Reference.html#pwm_tool","title":"[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]\npin:\n#   The pin to configure as an output. This parameter must be provided.\n#maximum_mcu_duration:\n#   The maximum duration a non-shutdown value may be driven by the MCU\n#   without an acknowledge from the host.\n#   If host can not keep up with an update, the MCU will shutdown\n#   and set all pins to their respective shutdown values.\n#   Default: 0 (disabled)\n#   Usual values are around 5 seconds.\n#value:\n#shutdown_value:\n#cycle_time: 0.100\n#hardware_pwm: False\n#scale:\n#   See the \"output_pin\" section for the definition of these parameters.\n
    "},{"location":"Config_Reference.html#pwm_cycle_time","title":"[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]\npin:\n#value:\n#shutdown_value:\n#cycle_time: 0.100\n#scale:\n#   See the \"output_pin\" section for information on these parameters.\n
    "},{"location":"Config_Reference.html#static_digital_output","title":"[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]\npins:\n#   A comma separated list of pins to be set as GPIO output pins. The\n#   pin will be set to a high level unless the pin name is prefaced\n#   with \"!\". This parameter must be provided.\n
    "},{"location":"Config_Reference.html#multi_pin","title":"[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]\npins:\n#   A comma separated list of pins associated with this alias. This\n#   parameter must be provided.\n
    "},{"location":"Config_Reference.html#tmc-stepper-driver-configuration","title":"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.

    "},{"location":"Config_Reference.html#tmc2130","title":"[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]\ncs_pin:\n#   The pin corresponding to the TMC2130 chip select line. This pin\n#   will be set to low at the start of SPI messages and raised to high\n#   after the message completes. This parameter must be provided.\n#spi_speed:\n#spi_bus:\n#spi_software_sclk_pin:\n#spi_software_mosi_pin:\n#spi_software_miso_pin:\n#   See the \"common SPI settings\" section for a description of the\n#   above parameters.\n#chain_position:\n#chain_length:\n#   These parameters configure an SPI daisy chain. The two parameters\n#   define the stepper position in the chain and the total chain length.\n#   Position 1 corresponds to the stepper that connects to the MOSI signal.\n#   The default is to not use an SPI daisy chain.\n#interpolate: True\n#   If true, enable step interpolation (the driver will internally\n#   step at a rate of 256 micro-steps). This interpolation does\n#   introduce a small systemic positional deviation - see\n#   TMC_Drivers.md for details. The default is True.\nrun_current:\n#   The amount of current (in amps RMS) to configure the driver to use\n#   during stepper movement. This parameter must be provided.\n#hold_current:\n#   The amount of current (in amps RMS) to configure the driver to use\n#   when the stepper is not moving. Setting a hold_current is not\n#   recommended (see TMC_Drivers.md for details). The default is to\n#   not reduce the current.\n#home_current:\n#   The amount of current (in amps RMS) to configure the driver to use\n#   during homing procedures. The default is to not reduce the current.\n#current_change_dwell_time:\n#   The amount of time (in seconds) to wait after changing homing current.\n#   The default is 0.5 seconds.\nsense_resistor:\n#   The resistance (in ohms) of the driver sense resistor. This\n#   parameter must be provided.\n#stealthchop_threshold: 0\n#   The velocity (in mm/s) to set the \"stealthChop\" threshold to. When\n#   set, \"stealthChop\" mode will be enabled if the stepper motor\n#   velocity is below this value. The default is 0, which disables\n#   \"stealthChop\" mode.\n#coolstep_threshold:\n#   The velocity (in mm/s) to set the TMC driver internal \"CoolStep\"\n#   threshold to. If set, the coolstep feature will be enabled when\n#   the stepper motor velocity is near or above this value. Important\n#   - if coolstep_threshold is set and \"sensorless homing\" is used,\n#   then one must ensure that the homing speed is above the coolstep\n#   threshold! The default is to not enable the coolstep feature.\n#high_velocity_threshold:\n#   The velocity (in mm/s) to set the TMC driver internal \"high\n#   velocity\" threshold (THIGH) to. This is typically used to disable\n#   the \"CoolStep\" feature at high speeds. The default is to not set a\n#   TMC \"high velocity\" threshold.\n#driver_MSLUT0: 2863314260\n#driver_MSLUT1: 1251300522\n#driver_MSLUT2: 608774441\n#driver_MSLUT3: 269500962\n#driver_MSLUT4: 4227858431\n#driver_MSLUT5: 3048961917\n#driver_MSLUT6: 1227445590\n#driver_MSLUT7: 4211234\n#driver_W0: 2\n#driver_W1: 1\n#driver_W2: 1\n#driver_W3: 1\n#driver_X1: 128\n#driver_X2: 255\n#driver_X3: 255\n#driver_START_SIN: 0\n#driver_START_SIN90: 247\n#   These fields control the Microstep Table registers directly. The optimal\n#   wave table is specific to each motor and might vary with current. An\n#   optimal configuration will have minimal print artifacts caused by\n#   non-linear stepper movement. The values specified above are the default\n#   values used by the driver. The value must be specified as a decimal integer\n#   (hex form is not supported). In order to compute the wave table fields,\n#   see the tmc2130 \"Calculation Sheet\" from the Trinamic website.\n#driver_IHOLDDELAY: 8\n#driver_TPOWERDOWN: 0\n#driver_TBL: 1\n#driver_TOFF: 4\n#driver_HEND: 7\n#driver_HSTRT: 0\n#driver_PWM_AUTOSCALE: True\n#driver_PWM_FREQ: 1\n#driver_PWM_GRAD: 4\n#driver_PWM_AMPL: 128\n#driver_SGT: 0\n#   Set the given register during the configuration of the TMC2130\n#   chip. This may be used to set custom motor parameters. The\n#   defaults for each parameter are next to the parameter name in the\n#   above list.\n#diag0_pin:\n#diag1_pin:\n#   The micro-controller pin attached to one of the DIAG lines of the\n#   TMC2130 chip. Only a single diag pin should be specified. The pin\n#   is \"active low\" and is thus normally prefaced with \"^!\". Setting\n#   this creates a \"tmc2130_stepper_x:virtual_endstop\" virtual pin\n#   which may be used as the stepper's endstop_pin. Doing this enables\n#   \"sensorless homing\". (Be sure to also set driver_SGT to an\n#   appropriate sensitivity value.) The default is to not enable\n#   sensorless homing.\n
    "},{"location":"Config_Reference.html#tmc2208","title":"[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]\nuart_pin:\n#   The pin connected to the TMC2208 PDN_UART line. This parameter\n#   must be provided.\n#tx_pin:\n#   If using separate receive and transmit lines to communicate with\n#   the driver then set uart_pin to the receive pin and tx_pin to the\n#   transmit pin. The default is to use uart_pin for both reading and\n#   writing.\n#select_pins:\n#   A comma separated list of pins to set prior to accessing the\n#   tmc2208 UART. This may be useful for configuring an analog mux for\n#   UART communication. The default is to not configure any pins.\n#interpolate: True\n#   If true, enable step interpolation (the driver will internally\n#   step at a rate of 256 micro-steps). This interpolation does\n#   introduce a small systemic positional deviation - see\n#   TMC_Drivers.md for details. The default is True.\nrun_current:\n#   The amount of current (in amps RMS) to configure the driver to use\n#   during stepper movement. This parameter must be provided.\n#hold_current:\n#   The amount of current (in amps RMS) to configure the driver to use\n#   when the stepper is not moving. Setting a hold_current is not\n#   recommended (see TMC_Drivers.md for details). The default is to\n#   not reduce the current.\n#home_current:\n#   The amount of current (in amps RMS) to configure the driver to use\n#   during homing procedures. The default is to not reduce the current.\n#current_change_dwell_time:\n#   The amount of time (in seconds) to wait after changing homing current.\n#   The default is 0.5 seconds.\nsense_resistor:\n#   The resistance (in ohms) of the driver sense resistor. This\n#   parameter must be provided.\n#stealthchop_threshold: 0\n#   The velocity (in mm/s) to set the \"stealthChop\" threshold to. When\n#   set, \"stealthChop\" mode will be enabled if the stepper motor\n#   velocity is below this value. The default is 0, which disables\n#   \"stealthChop\" mode.\n#driver_MULTISTEP_FILT: True\n#driver_IHOLDDELAY: 8\n#driver_TPOWERDOWN: 20\n#driver_TBL: 2\n#driver_TOFF: 3\n#driver_HEND: 0\n#driver_HSTRT: 5\n#driver_PWM_AUTOGRAD: True\n#driver_PWM_AUTOSCALE: True\n#driver_PWM_LIM: 12\n#driver_PWM_REG: 8\n#driver_PWM_FREQ: 1\n#driver_PWM_GRAD: 14\n#driver_PWM_OFS: 36\n#   Set the given register during the configuration of the TMC2208\n#   chip. This may be used to set custom motor parameters. The\n#   defaults for each parameter are next to the parameter name in the\n#   above list.\n
    "},{"location":"Config_Reference.html#tmc2209","title":"[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]\nuart_pin:\n#tx_pin:\n#select_pins:\n#interpolate: True\nrun_current:\n#hold_current:\n#home_current:\n#current_change_dwell_time:\nsense_resistor:\n#stealthchop_threshold: 0\n#   See the \"tmc2208\" section for the definition of these parameters.\n#coolstep_threshold:\n#   The velocity (in mm/s) to set the TMC driver internal \"CoolStep\"\n#   threshold to. If set, the coolstep feature will be enabled when\n#   the stepper motor velocity is near or above this value. Important\n#   - if coolstep_threshold is set and \"sensorless homing\" is used,\n#   then one must ensure that the homing speed is above the coolstep\n#   threshold! The default is to not enable the coolstep feature.\n#uart_address:\n#   The address of the TMC2209 chip for UART messages (an integer\n#   between 0 and 3). This is typically used when multiple TMC2209\n#   chips are connected to the same UART pin. The default is zero.\n#driver_MULTISTEP_FILT: True\n#driver_IHOLDDELAY: 8\n#driver_TPOWERDOWN: 20\n#driver_TBL: 2\n#driver_TOFF: 3\n#driver_HEND: 0\n#driver_HSTRT: 5\n#driver_PWM_AUTOGRAD: True\n#driver_PWM_AUTOSCALE: True\n#driver_PWM_LIM: 12\n#driver_PWM_REG: 8\n#driver_PWM_FREQ: 1\n#driver_PWM_GRAD: 14\n#driver_PWM_OFS: 36\n#driver_SGTHRS: 0\n#   Set the given register during the configuration of the TMC2209\n#   chip. This may be used to set custom motor parameters. The\n#   defaults for each parameter are next to the parameter name in the\n#   above list.\n#diag_pin:\n#   The micro-controller pin attached to the DIAG line of the TMC2209\n#   chip. The pin is normally prefaced with \"^\" to enable a pullup.\n#   Setting this creates a \"tmc2209_stepper_x:virtual_endstop\" virtual\n#   pin which may be used as the stepper's endstop_pin. Doing this\n#   enables \"sensorless homing\". (Be sure to also set driver_SGTHRS to\n#   an appropriate sensitivity value.) The default is to not enable\n#   sensorless homing.\n
    "},{"location":"Config_Reference.html#tmc2660","title":"[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]\ncs_pin:\n#   The pin corresponding to the TMC2660 chip select line. This pin\n#   will be set to low at the start of SPI messages and set to high\n#   after the message transfer completes. This parameter must be\n#   provided.\n#spi_speed: 4000000\n#   SPI bus frequency used to communicate with the TMC2660 stepper\n#   driver. The default is 4000000.\n#spi_bus:\n#spi_software_sclk_pin:\n#spi_software_mosi_pin:\n#spi_software_miso_pin:\n#   See the \"common SPI settings\" section for a description of the\n#   above parameters.\n#interpolate: True\n#   If true, enable step interpolation (the driver will internally\n#   step at a rate of 256 micro-steps). This only works if microsteps\n#   is set to 16. Interpolation does introduce a small systemic\n#   positional deviation - see TMC_Drivers.md for details. The default\n#   is True.\nrun_current:\n#   The amount of current (in amps RMS) used by the driver during\n#   stepper movement. This parameter must be provided.\n#home_current:\n#   The amount of current (in amps RMS) to configure the driver to use\n#   during homing procedures. The default is to not reduce the current.\n#current_change_dwell_time:\n#   The amount of time (in seconds) to wait after changing homing current.\n#   The default is 0.5 seconds.\nsense_resistor:\n#   The resistance (in ohms) of the driver sense resistor. This\n#   parameter must be provided.\n#idle_current_percent: 100\n#   The percentage of the run_current the stepper driver will be\n#   lowered to when the idle timeout expires (you need to set up the\n#   timeout using a [idle_timeout] config section). The current will\n#   be raised again once the stepper has to move again. Make sure to\n#   set this to a high enough value such that the steppers do not lose\n#   their position. There is also small delay until the current is\n#   raised again, so take this into account when commanding fast moves\n#   while the stepper is idling. The default is 100 (no reduction).\n#driver_TBL: 2\n#driver_RNDTF: 0\n#driver_HDEC: 0\n#driver_CHM: 0\n#driver_HEND: 3\n#driver_HSTRT: 3\n#driver_TOFF: 4\n#driver_SEIMIN: 0\n#driver_SEDN: 0\n#driver_SEMAX: 0\n#driver_SEUP: 0\n#driver_SEMIN: 0\n#driver_SFILT: 0\n#driver_SGT: 0\n#driver_SLPH: 0\n#driver_SLPL: 0\n#driver_DISS2G: 0\n#driver_TS2G: 3\n#   Set the given parameter during the configuration of the TMC2660\n#   chip. This may be used to set custom driver parameters. The\n#   defaults for each parameter are next to the parameter name in the\n#   list above. See the TMC2660 datasheet about what each parameter\n#   does and what the restrictions on parameter combinations are. Be\n#   especially aware of the CHOPCONF register, where setting CHM to\n#   either zero or one will lead to layout changes (the first bit of\n#   HDEC) is interpreted as the MSB of HSTRT in this case).\n
    "},{"location":"Config_Reference.html#tmc2240","title":"[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]\ncs_pin:\n#   The pin corresponding to the TMC2240 chip select line. This pin\n#   will be set to low at the start of SPI messages and raised to high\n#   after the message completes. This parameter must be provided.\n#spi_speed:\n#spi_bus:\n#spi_software_sclk_pin:\n#spi_software_mosi_pin:\n#spi_software_miso_pin:\n#   See the \"common SPI settings\" section for a description of the\n#   above parameters.\n#uart_pin:\n#   The pin connected to the TMC2240 DIAG1/SW line. If this parameter\n#   is provided UART communication is used rather then SPI.\n#chain_position:\n#chain_length:\n#   These parameters configure an SPI daisy chain. The two parameters\n#   define the stepper position in the chain and the total chain length.\n#   Position 1 corresponds to the stepper that connects to the MOSI signal.\n#   The default is to not use an SPI daisy chain.\n#interpolate: True\n#   If true, enable step interpolation (the driver will internally\n#   step at a rate of 256 micro-steps). The default is True.\nrun_current:\n#   The amount of current (in amps RMS) to configure the driver to use\n#   during stepper movement. This parameter must be provided.\n#hold_current:\n#   The amount of current (in amps RMS) to configure the driver to use\n#   when the stepper is not moving. Setting a hold_current is not\n#   recommended (see TMC_Drivers.md for details). The default is to\n#   not reduce the current.\n#home_current:\n#   The amount of current (in amps RMS) to configure the driver to use\n#   during homing procedures. The default is to not reduce the current.\n#current_change_dwell_time:\n#   The amount of time (in seconds) to wait after changing homing current.\n#   The default is 0.5 seconds.\n#rref:\n#   The resistance (in ohms) of the resistor between IREF and GND. This\n#   parameter must be provided.\n#stealthchop_threshold: 0\n#   The velocity (in mm/s) to set the \"stealthChop\" threshold to. When\n#   set, \"stealthChop\" mode will be enabled if the stepper motor\n#   velocity is below this value. The default is 0, which disables\n#   \"stealthChop\" mode.\n#coolstep_threshold:\n#   The velocity (in mm/s) to set the TMC driver internal \"CoolStep\"\n#   threshold to. If set, the coolstep feature will be enabled when\n#   the stepper motor velocity is near or above this value. Important\n#   - if coolstep_threshold is set and \"sensorless homing\" is used,\n#   then one must ensure that the homing speed is above the coolstep\n#   threshold! The default is to not enable the coolstep feature.\n#high_velocity_threshold:\n#   The velocity (in mm/s) to set the TMC driver internal \"high\n#   velocity\" threshold (THIGH) to. This is typically used to disable\n#   the \"CoolStep\" feature at high speeds. The default is to not set a\n#   TMC \"high velocity\" threshold.\n#driver_MSLUT0: 2863314260\n#driver_MSLUT1: 1251300522\n#driver_MSLUT2: 608774441\n#driver_MSLUT3: 269500962\n#driver_MSLUT4: 4227858431\n#driver_MSLUT5: 3048961917\n#driver_MSLUT6: 1227445590\n#driver_MSLUT7: 4211234\n#driver_W0: 2\n#driver_W1: 1\n#driver_W2: 1\n#driver_W3: 1\n#driver_X1: 128\n#driver_X2: 255\n#driver_X3: 255\n#driver_START_SIN: 0\n#driver_START_SIN90: 247\n#driver_OFFSET_SIN90: 0\n#   These fields control the Microstep Table registers directly. The optimal\n#   wave table is specific to each motor and might vary with current. An\n#   optimal configuration will have minimal print artifacts caused by\n#   non-linear stepper movement. The values specified above are the default\n#   values used by the driver. The value must be specified as a decimal integer\n#   (hex form is not supported). In order to compute the wave table fields,\n#   see the tmc2130 \"Calculation Sheet\" from the Trinamic website.\n#   Additionally, this driver also has the OFFSET_SIN90 field which can be used\n#   to tune a motor with unbalanced coils. See the `Sine Wave Lookup Table`\n#   section in the datasheet for information about this field and how to tune\n#   it.\n#driver_MULTISTEP_FILT: True\n#driver_IHOLDDELAY: 6\n#driver_IRUNDELAY: 4\n#driver_TPOWERDOWN: 10\n#driver_TBL: 2\n#driver_TOFF: 3\n#driver_HEND: 2\n#driver_HSTRT: 5\n#driver_FD3: 0\n#driver_TPFD: 4\n#driver_CHM: 0\n#driver_VHIGHFS: 0\n#driver_VHIGHCHM: 0\n#driver_DISS2G: 0\n#driver_DISS2VS: 0\n#driver_PWM_AUTOSCALE: True\n#driver_PWM_AUTOGRAD: True\n#driver_PWM_FREQ: 0\n#driver_FREEWHEEL: 0\n#driver_PWM_GRAD: 0\n#driver_PWM_OFS: 29\n#driver_PWM_REG: 4\n#driver_PWM_LIM: 12\n#driver_SLOPE_CONTROL: 0\n#   The chip has a default value of 0, corresponding to 100V/\u00b5s.\n#   Setting this value to 2, corresponding to 400V/\u00b5s, approximately\n#   matches the TMC2209. This lowers the power dissipation at a 50kHz\n#   chopper frequency by around 1W.\n#driver_SGT: 0\n#driver_SEMIN: 0\n#driver_SEUP: 0\n#driver_SEMAX: 0\n#driver_SEDN: 0\n#driver_SEIMIN: 0\n#driver_SFILT: 0\n#driver_SG4_ANGLE_OFFSET: 1\n#   Set the given register during the configuration of the TMC2240\n#   chip. This may be used to set custom motor parameters. The\n#   defaults for each parameter are next to the parameter name in the\n#   above list.\n#diag0_pin:\n#diag1_pin:\n#   The micro-controller pin attached to one of the DIAG lines of the\n#   TMC2240 chip. Only a single diag pin should be specified. The pin\n#   is \"active low\" and is thus normally prefaced with \"^!\". Setting\n#   this creates a \"tmc2240_stepper_x:virtual_endstop\" virtual pin\n#   which may be used as the stepper's endstop_pin. Doing this enables\n#   \"sensorless homing\". (Be sure to also set driver_SGT to an\n#   appropriate sensitivity value.) The default is to not enable\n#   sensorless homing.\n
    "},{"location":"Config_Reference.html#tmc5160","title":"[tmc5160]","text":"

    Configure a TMC5160 or TMC2160 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]\ncs_pin:\n#   The pin corresponding to the TMC5160 or TMC2160 chip select line.\n#   This pin will be set to low at the start of SPI messages and raised\n#   to high after the message completes. This parameter must be provided.\n#spi_speed:\n#spi_bus:\n#spi_software_sclk_pin:\n#spi_software_mosi_pin:\n#spi_software_miso_pin:\n#   See the \"common SPI settings\" section for a description of the\n#   above parameters.\n#chain_position:\n#chain_length:\n#   These parameters configure an SPI daisy chain. The two parameters\n#   define the stepper position in the chain and the total chain length.\n#   Position 1 corresponds to the stepper that connects to the MOSI signal.\n#   The default is to not use an SPI daisy chain.\n#interpolate: True\n#   If true, enable step interpolation (the driver will internally\n#   step at a rate of 256 micro-steps). The default is True.\nrun_current:\n#   The amount of current (in amps RMS) to configure the driver to use\n#   during stepper movement. This parameter must be provided.\n#hold_current:\n#   The amount of current (in amps RMS) to configure the driver to use\n#   when the stepper is not moving. Setting a hold_current is not\n#   recommended (see TMC_Drivers.md for details). The default is to\n#   not reduce the current.\n#home_current:\n#   The amount of current (in amps RMS) to configure the driver to use\n#   during homing procedures. The default is to not reduce the current.\n#current_change_dwell_time:\n#   The amount of time (in seconds) to wait after changing homing current.\n#   The default is 0.5 seconds.\nsense_resistor:\n#   The resistance (in ohms) of the driver sense resistor. This\n#   parameter must be provided.\n#stealthchop_threshold: 0\n#   The velocity (in mm/s) to set the \"stealthChop\" threshold to. When\n#   set, \"stealthChop\" mode will be enabled if the stepper motor\n#   velocity is below this value. The default is 0, which disables\n#   \"stealthChop\" mode.\n#coolstep_threshold:\n#   The velocity (in mm/s) to set the TMC driver internal \"CoolStep\"\n#   threshold to. If set, the coolstep feature will be enabled when\n#   the stepper motor velocity is near or above this value. Important\n#   - if coolstep_threshold is set and \"sensorless homing\" is used,\n#   then one must ensure that the homing speed is above the coolstep\n#   threshold! The default is to not enable the coolstep feature.\n#high_velocity_threshold:\n#   The velocity (in mm/s) to set the TMC driver internal \"high\n#   velocity\" threshold (THIGH) to. This is typically used to disable\n#   the \"CoolStep\" feature at high speeds. The default is to not set a\n#   TMC \"high velocity\" threshold.\n#driver_MSLUT0: 2863314260\n#driver_MSLUT1: 1251300522\n#driver_MSLUT2: 608774441\n#driver_MSLUT3: 269500962\n#driver_MSLUT4: 4227858431\n#driver_MSLUT5: 3048961917\n#driver_MSLUT6: 1227445590\n#driver_MSLUT7: 4211234\n#driver_W0: 2\n#driver_W1: 1\n#driver_W2: 1\n#driver_W3: 1\n#driver_X1: 128\n#driver_X2: 255\n#driver_X3: 255\n#driver_START_SIN: 0\n#driver_START_SIN90: 247\n#   These fields control the Microstep Table registers directly. The optimal\n#   wave table is specific to each motor and might vary with current. An\n#   optimal configuration will have minimal print artifacts caused by\n#   non-linear stepper movement. The values specified above are the default\n#   values used by the driver. The value must be specified as a decimal integer\n#   (hex form is not supported). In order to compute the wave table fields,\n#   see the tmc2130 \"Calculation Sheet\" from the Trinamic website.\n#driver_MULTISTEP_FILT: True\n#driver_IHOLDDELAY: 6\n#driver_TPOWERDOWN: 10\n#driver_TBL: 2\n#driver_TOFF: 3\n#driver_HEND: 2\n#driver_HSTRT: 5\n#driver_FD3: 0\n#driver_TPFD: 4\n#driver_CHM: 0\n#driver_VHIGHFS: 0\n#driver_VHIGHCHM: 0\n#driver_DISS2G: 0\n#driver_DISS2VS: 0\n#driver_PWM_AUTOSCALE: True\n#driver_PWM_AUTOGRAD: True\n#driver_PWM_FREQ: 0\n#driver_FREEWHEEL: 0\n#driver_PWM_GRAD: 0\n#driver_PWM_OFS: 30\n#driver_PWM_REG: 4\n#driver_PWM_LIM: 12\n#driver_SGT: 0\n#driver_SEMIN: 0\n#driver_SEUP: 0\n#driver_SEMAX: 0\n#driver_SEDN: 0\n#driver_SEIMIN: 0\n#driver_SFILT: 0\n#driver_DRVSTRENGTH: 0\n#driver_BBMCLKS: 4\n#driver_BBMTIME: 0\n#driver_FILT_ISENSE: 0\n#   Set the given register during the configuration of the TMC5160 or\n#   TMC2160 chip. This may be used to set custom motor parameters. The\n#   defaults for each parameter are next to the parameter name in the\n#   above list.\n#\u26a0\ufe0fdriver_s2vs_level: 6   # Short to Supply tolerance, from 4 to 15\n#\u26a0\ufe0fdriver_s2g_level: 6    # Short to Ground tolerance, from 2 to 15\n#\u26a0\ufe0fdriver_shortdelay: 0   # Short trigger delay, 0=750ns, 1=1500ns\n#\u26a0\ufe0fdriver_short_filter: 1\n#   Short filtering bandwidth. 0=100ns, 1=1us (Default), 2=2us, 3=3us\n#diag0_pin:\n#diag1_pin:\n#   The micro-controller pin attached to one of the DIAG lines of the\n#   TMC5160 or TMC2160 chip. Only a single diag pin should be specified.\n#   The pin is \"active low\" and is thus normally prefaced with \"^!\".\n#   Setting this creates a \"tmc5160_stepper_x:virtual_endstop\" virtual pin\n#   which may be used as the stepper's endstop_pin. Doing this enables\n#   \"sensorless homing\". (Be sure to also set driver_SGT to an\n#   appropriate sensitivity value.) The default is to not enable\n#   sensorless homing.\n
    "},{"location":"Config_Reference.html#run-time-stepper-motor-current-configuration","title":"Run-time stepper motor current configuration","text":""},{"location":"Config_Reference.html#ad5206","title":"[ad5206]","text":"

    Statically configured AD5206 digipots connected via SPI bus (one may define any number of sections with an \"ad5206\" prefix).

    [ad5206 my_digipot]\nenable_pin:\n#   The pin corresponding to the AD5206 chip select line. This pin\n#   will be set to low at the start of SPI messages and raised to high\n#   after the message completes. This parameter must be provided.\n#spi_speed:\n#spi_bus:\n#spi_software_sclk_pin:\n#spi_software_mosi_pin:\n#spi_software_miso_pin:\n#   See the \"common SPI settings\" section for a description of the\n#   above parameters.\n#channel_1:\n#channel_2:\n#channel_3:\n#channel_4:\n#channel_5:\n#channel_6:\n#   The value to statically set the given AD5206 channel to. This is\n#   typically set to a number between 0.0 and 1.0 with 1.0 being the\n#   highest resistance and 0.0 being the lowest resistance. However,\n#   the range may be changed with the 'scale' parameter (see below).\n#   If a channel is not specified then it is left unconfigured.\n#scale:\n#   This parameter can be used to alter how the 'channel_x' parameters\n#   are interpreted. If provided, then the 'channel_x' parameters\n#   should be between 0.0 and 'scale'. This may be useful when the\n#   AD5206 is used to set stepper voltage references. The 'scale' can\n#   be set to the equivalent stepper amperage if the AD5206 were at\n#   its highest resistance, and then the 'channel_x' parameters can be\n#   specified using the desired amperage value for the stepper. The\n#   default is to not scale the 'channel_x' parameters.\n
    "},{"location":"Config_Reference.html#mcp4451","title":"[mcp4451]","text":"

    Statically configured MCP4451 digipot connected via I2C bus (one may define any number of sections with an \"mcp4451\" prefix).

    [mcp4451 my_digipot]\ni2c_address:\n#   The i2c address that the chip is using on the i2c bus. This\n#   parameter must be provided.\n#i2c_mcu:\n#i2c_bus:\n#i2c_software_scl_pin:\n#i2c_software_sda_pin:\n#i2c_speed:\n#   See the \"common I2C settings\" section for a description of the\n#   above parameters.\n#wiper_0:\n#wiper_1:\n#wiper_2:\n#wiper_3:\n#   The value to statically set the given MCP4451 \"wiper\" to. This is\n#   typically set to a number between 0.0 and 1.0 with 1.0 being the\n#   highest resistance and 0.0 being the lowest resistance. However,\n#   the range may be changed with the 'scale' parameter (see below).\n#   If a wiper is not specified then it is left unconfigured.\n#scale:\n#   This parameter can be used to alter how the 'wiper_x' parameters\n#   are interpreted. If provided, then the 'wiper_x' parameters should\n#   be between 0.0 and 'scale'. This may be useful when the MCP4451 is\n#   used to set stepper voltage references. The 'scale' can be set to\n#   the equivalent stepper amperage if the MCP4451 were at its highest\n#   resistance, and then the 'wiper_x' parameters can be specified\n#   using the desired amperage value for the stepper. The default is\n#   to not scale the 'wiper_x' parameters.\n
    "},{"location":"Config_Reference.html#mcp4728","title":"[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]\n#i2c_address: 96\n#   The i2c address that the chip is using on the i2c bus. The default\n#   is 96.\n#i2c_mcu:\n#i2c_bus:\n#i2c_software_scl_pin:\n#i2c_software_sda_pin:\n#i2c_speed:\n#   See the \"common I2C settings\" section for a description of the\n#   above parameters.\n#channel_a:\n#channel_b:\n#channel_c:\n#channel_d:\n#   The value to statically set the given MCP4728 channel to. This is\n#   typically set to a number between 0.0 and 1.0 with 1.0 being the\n#   highest voltage (2.048V) and 0.0 being the lowest voltage.\n#   However, the range may be changed with the 'scale' parameter (see\n#   below). If a channel is not specified then it is left\n#   unconfigured.\n#scale:\n#   This parameter can be used to alter how the 'channel_x' parameters\n#   are interpreted. If provided, then the 'channel_x' parameters\n#   should be between 0.0 and 'scale'. This may be useful when the\n#   MCP4728 is used to set stepper voltage references. The 'scale' can\n#   be set to the equivalent stepper amperage if the MCP4728 were at\n#   its highest voltage (2.048V), and then the 'channel_x' parameters\n#   can be specified using the desired amperage value for the\n#   stepper. The default is to not scale the 'channel_x' parameters.\n
    "},{"location":"Config_Reference.html#mcp4018","title":"[mcp4018]","text":"

    Statically configured MCP4018 digipot connected via two gpio \"bit banging\" pins (one may define any number of sections with an \"mcp4018\" prefix).

    [mcp4018 my_digipot]\nscl_pin:\n#   The SCL \"clock\" pin. This parameter must be provided.\nsda_pin:\n#   The SDA \"data\" pin. This parameter must be provided.\nwiper:\n#   The value to statically set the given MCP4018 \"wiper\" to. This is\n#   typically set to a number between 0.0 and 1.0 with 1.0 being the\n#   highest resistance and 0.0 being the lowest resistance. However,\n#   the range may be changed with the 'scale' parameter (see below).\n#   This parameter must be provided.\n#scale:\n#   This parameter can be used to alter how the 'wiper' parameter is\n#   interpreted. If provided, then the 'wiper' parameter should be\n#   between 0.0 and 'scale'. This may be useful when the MCP4018 is\n#   used to set stepper voltage references. The 'scale' can be set to\n#   the equivalent stepper amperage if the MCP4018 is at its highest\n#   resistance, and then the 'wiper' parameter can be specified using\n#   the desired amperage value for the stepper. The default is to not\n#   scale the 'wiper' parameter.\n
    "},{"location":"Config_Reference.html#display-support","title":"Display support","text":""},{"location":"Config_Reference.html#display","title":"[display]","text":"

    Support for a display attached to the micro-controller.

    [display]\nlcd_type:\n#   The type of LCD chip in use. This may be \"hd44780\", \"hd44780_spi\",\n#   \"aip31068_spi\", \"st7920\", \"emulated_st7920\", \"uc1701\", \"ssd1306\", or\n#   \"sh1106\".\n#   See the display sections below for information on each type and\n#   additional parameters they provide. This parameter must be\n#   provided.\n#display_group:\n#   The name of the display_data group to show on the display. This\n#   controls the content of the screen (see the \"display_data\" section\n#   for more information). The default is _default_20x4 for hd44780 or\n#   aip31068_spi displays and _default_16x4 for other displays.\n#menu_timeout:\n#   Timeout for menu. Being inactive this amount of seconds will\n#   trigger menu exit or return to root menu when having autorun\n#   enabled. The default is 0 seconds (disabled)\n#menu_root:\n#   Name of the main menu section to show when clicking the encoder\n#   on the home screen. The defaults is __main, and this shows the\n#   the default menus as defined in klippy/extras/display/menu.cfg\n#menu_reverse_navigation:\n#   When enabled it will reverse up and down directions for list\n#   navigation. The default is False. This parameter is optional.\n#encoder_pins:\n#   The pins connected to encoder. 2 pins must be provided when using\n#   encoder. This parameter must be provided when using menu.\n#encoder_steps_per_detent:\n#   How many steps the encoder emits per detent (\"click\"). If the\n#   encoder takes two detents to move between entries or moves two\n#   entries from one detent, try changing this. Allowed values are 2\n#   (half-stepping) or 4 (full-stepping). The default is 4.\n#click_pin:\n#   The pin connected to 'enter' button or encoder 'click'. This\n#   parameter must be provided when using menu. The presence of an\n#   'analog_range_click_pin' config parameter turns this parameter\n#   from digital to analog.\n#back_pin:\n#   The pin connected to 'back' button. This parameter is optional,\n#   menu can be used without it. The presence of an\n#   'analog_range_back_pin' config parameter turns this parameter from\n#   digital to analog.\n#up_pin:\n#   The pin connected to 'up' button. This parameter must be provided\n#   when using menu without encoder. The presence of an\n#   'analog_range_up_pin' config parameter turns this parameter from\n#   digital to analog.\n#down_pin:\n#   The pin connected to 'down' button. This parameter must be\n#   provided when using menu without encoder. The presence of an\n#   'analog_range_down_pin' config parameter turns this parameter from\n#   digital to analog.\n#kill_pin:\n#   The pin connected to 'kill' button. This button will call\n#   emergency stop. The presence of an 'analog_range_kill_pin' config\n#   parameter turns this parameter from digital to analog.\n#analog_pullup_resistor: 4700\n#   The resistance (in ohms) of the pullup attached to the analog\n#   button. The default is 4700 ohms.\n#analog_range_click_pin:\n#   The resistance range for a 'enter' button. Range minimum and\n#   maximum comma-separated values must be provided when using analog\n#   button.\n#analog_range_back_pin:\n#   The resistance range for a 'back' button. Range minimum and\n#   maximum comma-separated values must be provided when using analog\n#   button.\n#analog_range_up_pin:\n#   The resistance range for a 'up' button. Range minimum and maximum\n#   comma-separated values must be provided when using analog button.\n#analog_range_down_pin:\n#   The resistance range for a 'down' button. Range minimum and\n#   maximum comma-separated values must be provided when using analog\n#   button.\n#analog_range_kill_pin:\n#   The resistance range for a 'kill' button. Range minimum and\n#   maximum comma-separated values must be provided when using analog\n#   button.\n
    "},{"location":"Config_Reference.html#hd44780-display","title":"hd44780 display","text":"

    Information on configuring hd44780 displays (which is used in \"RepRapDiscount 2004 Smart Controller\" type displays).

    [display]\nlcd_type: hd44780\n#   Set to \"hd44780\" for hd44780 displays.\nrs_pin:\ne_pin:\nd4_pin:\nd5_pin:\nd6_pin:\nd7_pin:\n#   The pins connected to an hd44780 type lcd. These parameters must\n#   be provided.\n#hd44780_protocol_init: True\n#   Perform 8-bit/4-bit protocol initialization on an hd44780 display.\n#   This is necessary on real hd44780 devices. However, one may need\n#   to disable this on some \"clone\" devices. The default is True.\n#line_length:\n#   Set the number of characters per line for an hd44780 type lcd.\n#   Possible values are 20 (default) and 16. The number of lines is\n#   fixed to 4.\n...\n
    "},{"location":"Config_Reference.html#hd44780_spi-display","title":"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]\nlcd_type: hd44780_spi\n#   Set to \"hd44780_spi\" for hd44780_spi displays.\nlatch_pin:\nspi_software_sclk_pin:\nspi_software_mosi_pin:\nspi_software_miso_pin:\n#   The pins connected to the shift register controlling the display.\n#   The spi_software_miso_pin needs to be set to an unused pin of the\n#   printer mainboard as the shift register does not have a MISO pin,\n#   but the software spi implementation requires this pin to be\n#   configured.\n#hd44780_protocol_init: True\n#   Perform 8-bit/4-bit protocol initialization on an hd44780 display.\n#   This is necessary on real hd44780 devices. However, one may need\n#   to disable this on some \"clone\" devices. The default is True.\n#line_length:\n#   Set the number of characters per line for an hd44780 type lcd.\n#   Possible values are 20 (default) and 16. The number of lines is\n#   fixed to 4.\n...\n
    "},{"location":"Config_Reference.html#aip31068_spi-display","title":"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]\nlcd_type: aip31068_spi\nlatch_pin:\nspi_software_sclk_pin:\nspi_software_mosi_pin:\nspi_software_miso_pin:\n#   The pins connected to the shift register controlling the display.\n#   The spi_software_miso_pin needs to be set to an unused pin of the\n#   printer mainboard as the shift register does not have a MISO pin,\n#   but the software spi implementation requires this pin to be\n#   configured.\n#line_length:\n#   Set the number of characters per line for an hd44780 type lcd.\n#   Possible values are 20 (default) and 16. The number of lines is\n#   fixed to 4.\n...\n
    "},{"location":"Config_Reference.html#st7920-display","title":"st7920 display","text":"

    Information on configuring st7920 displays (which is used in \"RepRapDiscount 12864 Full Graphic Smart Controller\" type displays).

    [display]\nlcd_type: st7920\n#   Set to \"st7920\" for st7920 displays.\ncs_pin:\nsclk_pin:\nsid_pin:\n#   The pins connected to an st7920 type lcd. These parameters must be\n#   provided.\n...\n
    "},{"location":"Config_Reference.html#emulated_st7920-display","title":"emulated_st7920 display","text":"

    Information on configuring an emulated st7920 display - found in some \"2.4 inch touchscreen devices\" and similar.

    [display]\nlcd_type: emulated_st7920\n#   Set to \"emulated_st7920\" for emulated_st7920 displays.\nen_pin:\nspi_software_sclk_pin:\nspi_software_mosi_pin:\nspi_software_miso_pin:\n#   The pins connected to an emulated_st7920 type lcd. The en_pin\n#   corresponds to the cs_pin of the st7920 type lcd,\n#   spi_software_sclk_pin corresponds to sclk_pin and\n#   spi_software_mosi_pin corresponds to sid_pin. The\n#   spi_software_miso_pin needs to be set to an unused pin of the\n#   printer mainboard as the st7920 as no MISO pin but the software\n#   spi implementation requires this pin to be configured.\n...\n
    "},{"location":"Config_Reference.html#uc1701-display","title":"uc1701 display","text":"

    Information on configuring uc1701 displays (which is used in \"MKS Mini 12864\" type displays).

    [display]\nlcd_type: uc1701\n#   Set to \"uc1701\" for uc1701 displays.\ncs_pin:\na0_pin:\n#   The pins connected to a uc1701 type lcd. These parameters must be\n#   provided.\n#rst_pin:\n#   The pin connected to the \"rst\" pin on the lcd. If it is not\n#   specified then the hardware must have a pull-up on the\n#   corresponding lcd line.\n#contrast:\n#   The contrast to set. The value may range from 0 to 63 and the\n#   default is 40.\n...\n
    "},{"location":"Config_Reference.html#ssd1306-and-sh1106-displays","title":"ssd1306 and sh1106 displays","text":"

    Information on configuring ssd1306 and sh1106 displays.

    [display]\nlcd_type:\n#   Set to either \"ssd1306\" or \"sh1106\" for the given display type.\n#i2c_mcu:\n#i2c_bus:\n#i2c_software_scl_pin:\n#i2c_software_sda_pin:\n#i2c_speed:\n#   Optional parameters available for displays connected via an i2c\n#   bus. See the \"common I2C settings\" section for a description of\n#   the above parameters.\n#cs_pin:\n#dc_pin:\n#spi_speed:\n#spi_bus:\n#spi_software_sclk_pin:\n#spi_software_mosi_pin:\n#spi_software_miso_pin:\n#   The pins connected to the lcd when in \"4-wire\" spi mode. See the\n#   \"common SPI settings\" section for a description of the parameters\n#   that start with \"spi_\". The default is to use i2c mode for the\n#   display.\n#reset_pin:\n#   A reset pin may be specified on the display. If it is not\n#   specified then the hardware must have a pull-up on the\n#   corresponding lcd line.\n#contrast:\n#   The contrast to set. The value may range from 0 to 256 and the\n#   default is 239.\n#vcomh: 0\n#   Set the Vcomh value on the display. This value is associated with\n#   a \"smearing\" effect on some OLED displays. The value may range\n#   from 0 to 63. Default is 0.\n#invert: False\n#   TRUE inverts the pixels on certain OLED displays.  The default is\n#   False.\n#x_offset: 0\n#   Set the horizontal offset value on SH1106 displays. The default is\n#   0.\n...\n
    "},{"location":"Config_Reference.html#display_data","title":"[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]\nposition:\n#   Comma separated row and column of the display position that should\n#   be used to display the information. This parameter must be\n#   provided.\ntext:\n#   The text to show at the given position. This field is evaluated\n#   using command templates (see docs/Command_Templates.md). This\n#   parameter must be provided.\n
    "},{"location":"Config_Reference.html#display_template","title":"[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]\n#param_<name>:\n#   One may specify any number of options with a \"param_\" prefix. The\n#   given name will be assigned the given value (parsed as a Python\n#   literal) and will be available during macro expansion. If the\n#   parameter is passed in the call to render() then that value will\n#   be used during macro expansion. For example, a config with\n#   \"param_speed = 75\" might have a caller with\n#   \"render('my_template_name', param_speed=80)\". Parameter names may\n#   not use upper case characters.\ntext:\n#   The text to return when the this template is rendered. This field\n#   is evaluated using command templates (see\n#   docs/Command_Templates.md). This parameter must be provided.\n
    "},{"location":"Config_Reference.html#display_glyph","title":"[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]\n#data:\n#   The display data, stored as 16 lines consisting of 16 bits (1 per\n#   pixel) where '.' is a blank pixel and '*' is an on pixel (e.g.,\n#   \"****************\" to display a solid horizontal line).\n#   Alternatively, one can use '0' for a blank pixel and '1' for an on\n#   pixel. Put each display line into a separate config line. The\n#   glyph must consist of exactly 16 lines with 16 bits each. This\n#   parameter is optional.\n#hd44780_data:\n#   Glyph to use on 20x4 hd44780 displays. The glyph must consist of\n#   exactly 8 lines with 5 bits each. This parameter is optional.\n#hd44780_slot:\n#   The hd44780 hardware index (0..7) to store the glyph at. If\n#   multiple distinct images use the same slot then make sure to only\n#   use one of those images in any given screen. This parameter is\n#   required if hd44780_data is specified.\n
    "},{"location":"Config_Reference.html#display-my_extra_display","title":"[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]\n# See the \"display\" section for available parameters.\n
    "},{"location":"Config_Reference.html#menu","title":"\u26a0\ufe0f [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.\n#[menu __some_list __some_name]\n#type: disabled\n#   Permanently disabled menu element, only required attribute is 'type'.\n#   Allows you to easily disable/hide existing menu items.\n\n#[menu some_name]\n#type:\n#   One of command, input, list, text:\n#       command      - basic menu element with various script triggers\n#       input        - same like 'command' but has value changing capabilities.\n#                      Press will start/stop edit mode.\n#       list         - it allows for menu items to be grouped together in a\n#                      scrollable list.  Add to the list by creating menu\n#                      configurations using \"some_list\" as a prefix - for\n#                      example: [menu some_list some_item_in_the_list]\n#       vsdlist      - same as 'list' but will append files from virtual sdcard\n#                      (deprecated, will be removed in the future)\n#    \u26a0\ufe0f file_browser - Extended SD Card browser, supporting directories and\n#                      sorting. (replaces vsdlist)\n#    \u26a0\ufe0f dialog       - Menu Dialogs, a list of inputs with a final choice to\n#                      confirm or cancel. Used for more complex scenarios like\n#                      PID/MPC calibration where you may want to set multiple\n#                      values for a single command\n#name:\n#   Name of menu item - evaluated as a template.\n#enable:\n#   Template that evaluates to True or False.\n#index:\n#   Position where an item needs to be inserted in list. By default\n#   the item is added at the end.\n\n#[menu some_list]\n#type: list\n#name:\n#enable:\n#   See above for a description of these parameters.\n\n#[menu sdcard]\n#type: file_browser\n#name:\n#sort_by:\n#   `last_modified` (default) or `name`\n#enable:\n#   See above for a description of these parameters.\n\n#[menu some_list some_command]\n#type: command\n#name:\n#enable:\n#   See above for a description of these parameters.\n#gcode:\n#   Script to run on button click or long click. Evaluated as a\n#   template.\n\n#[menu some_list some_input]\n#type: input\n#name:\n#enable:\n#   See above for a description of these parameters.\n#input:\n#   Initial value to use when editing - evaluated as a template.\n#   Result must be float.\n#input_min:\n#   Minimum value of range - evaluated as a template. Default -99999.\n#input_max:\n#   Maximum value of range - evaluated as a template. Default 99999.\n#input_step:\n#   Editing step - Must be a positive integer or float value. It has\n#   internal fast rate step. When \"(input_max - input_min) /\n#   input_step > 100\" then fast rate step is 10 * input_step else fast\n#   rate step is same input_step.\n#realtime:\n#   This attribute accepts static boolean value. When enabled then\n#   gcode script is run after each value change. The default is False.\n#gcode:\n#   Script to run on button click, long click or value change.\n#   Evaluated as a template. The button click will trigger the edit\n#   mode start or end.\n\n#[menu neopixel]\n#type: dialog\n#name:\n#enable:\n#   See above for a description of these parameters.\n#title:\n#   An optional title to display at the top of the dialog. `name` will\n#   used if not set\n#confirm_text:\n#cancel_text\n#   Templates for the confirmation and cancel options\n#gcode:\n#   G-Code to run on confirmation. The dialog will be closed on\n#   confirmation. `{menu.exit()}` may be used to close the menu\n#   instead.\n
    "},{"location":"Config_Reference.html#filament-sensors","title":"Filament sensors","text":""},{"location":"Config_Reference.html#filament_switch_sensor","title":"[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]\n#pause_on_runout: True\n#   When set to True, a PAUSE will execute immediately after a runout\n#   is detected. Note that if pause_on_runout is False and the\n#   runout_gcode is omitted then runout detection is disabled. Default\n#   is True.\n#runout_gcode:\n#   A list of G-Code commands to execute after a filament runout is\n#   detected. See docs/Command_Templates.md for G-Code format. If\n#   pause_on_runout is set to True this G-Code will run after the\n#   PAUSE is complete. The default is not to run any G-Code commands.\n#immediate_runout_gcode:\n#   A list of G-Code commands to execute immediately after a filament\n#   runout is detected and runout_distance is greater than 0.\n#   See docs/Command_Templates.md for G-Code format.\n#insert_gcode:\n#   A list of G-Code commands to execute after a filament insert is\n#   detected. See docs/Command_Templates.md for G-Code format. The\n#   default is not to run any G-Code commands, which disables insert\n#   detection.\n#runout_distance: 0.0\n#   Defines how much filament can still be pulled after the\n#   switch sensor triggered (e.g. you have a 60cm reverse bowden between your\n#   extruder and your sensor, you would then set runout_distance to something\n#   like 590 to leave a small safety margin and now the print will not\n#   immediately pause when the sensor triggers but rather keep printing until\n#   the filament is at the extruder). The default is 0 millimeters.\n#event_delay: 3.0\n#   The minimum amount of time in seconds to delay between events.\n#   Events triggered during this time period will be silently\n#   ignored. The default is 3 seconds.\n#pause_delay: 0.5\n#   The amount of time to delay, in seconds, between the pause command\n#   dispatch and execution of the runout_gcode. It may be useful to\n#   increase this delay if OctoPrint exhibits strange pause behavior.\n#   Default is 0.5 seconds.\n#switch_pin:\n#   The pin on which the switch is connected. This parameter must be\n#   provided.\n#smart:\n#   If set to true the sensor will use the virtual_sd_card module to determine\n#   whether the printer is printing which is more reliable but will not work\n#   when streaming a print over usb or similar.\n#always_fire_events:\n#   If set to true, runout events will always fire no matter whether the sensor\n#   is enabled or disabled. Usefull for MMUs\n#check_on_print_start:\n#   If set to true, the sensor will be reevaluated when a print starts and if\n#   no filament is detected the runout_gcode will be run no matter the defined\n#   runout_distance(immediate_runout_gcode will not be run in this case)\n
    "},{"location":"Config_Reference.html#filament_motion_sensor","title":"[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]\ndetection_length: 7.0\n#   The minimum length of filament pulled through the sensor to trigger\n#   a state change on the switch_pin\n#   Default is 7 mm.\nextruder:\n#   The name of the extruder section this sensor is associated with.\n#   This parameter must be provided.\nswitch_pin:\n#pause_on_runout:\n#runout_gcode:\n#insert_gcode:\n#event_delay:\n#pause_delay:\n#smart:\n#always_fire_events:\n#   See the \"filament_switch_sensor\" section for a description of the\n#   above parameters.\n
    "},{"location":"Config_Reference.html#tsl1401cl_filament_width_sensor","title":"[tsl1401cl_filament_width_sensor]","text":"

    TSLl401CL Based Filament Width Sensor. See the guide for more information.

    [tsl1401cl_filament_width_sensor]\n#pin:\n#default_nominal_filament_diameter: 1.75 # (mm)\n#   Maximum allowed filament diameter difference as mm.\n#max_difference: 0.2\n#   The distance from sensor to the melting chamber as mm.\n#measurement_delay: 100\n
    "},{"location":"Config_Reference.html#hall_filament_width_sensor","title":"[hall_filament_width_sensor]","text":"

    Hall filament width sensor (see Hall Filament Width Sensor).

    [hall_filament_width_sensor]\nadc1:\nadc2:\n#   Analog input pins connected to the sensor. These parameters must\n#   be provided.\n#cal_dia1: 1.50\n#cal_dia2: 2.00\n#   The calibration values (in mm) for the sensors. The default is\n#   1.50 for cal_dia1 and 2.00 for cal_dia2.\n#raw_dia1: 9500\n#raw_dia2: 10500\n#   The raw calibration values for the sensors. The default is 9500\n#   for raw_dia1 and 10500 for raw_dia2.\n#default_nominal_filament_diameter: 1.75\n#   The nominal filament diameter. This parameter must be provided.\n#max_difference: 0.200\n#   Maximum allowed filament diameter difference in millimeters (mm).\n#   If difference between nominal filament diameter and sensor output\n#   is more than +- max_difference, extrusion multiplier is set back\n#   to %100. The default is 0.200.\n#measurement_delay: 70\n#   The distance from sensor to the melting chamber/hot-end in\n#   millimeters (mm). The filament between the sensor and the hot-end\n#   will be treated as the default_nominal_filament_diameter. Host\n#   module works with FIFO logic. It keeps each sensor value and\n#   position in an array and POP them back in correct position. This\n#   parameter must be provided.\n#enable: False\n#   Sensor enabled or disabled after power on. The default is to\n#   disable.\n#measurement_interval: 10\n#   The approximate distance (in mm) between sensor readings. The\n#   default is 10mm.\n#logging: False\n#   Out diameter to terminal and klippy.log can be turn on|of by\n#   command.\n#min_diameter: 1.0\n#   Minimal diameter for trigger virtual filament_switch_sensor.\n#max_diameter:\n#   Maximum diameter for triggering virtual filament_switch_sensor.\n#   The default is default_nominal_filament_diameter + max_difference.\n#use_current_dia_while_delay: False\n#   Use the current diameter instead of the nominal diameter while\n#   the measurement delay has not run through.\n#pause_on_runout:\n#immediate_runout_gcode:\n#runout_gcode:\n#insert_gcode:\n#event_delay:\n#pause_delay:\n#smart:\n#always_fire_events:\n#check_on_print_start:\n#   See the \"filament_switch_sensor\" section for a description of the\n#   above parameters.\n
    "},{"location":"Config_Reference.html#belay","title":"[belay]","text":"

    Belay extruder sync sensors (one may define any number of sections with a \"belay\" prefix).

    [belay my_belay]\nextruder_type:\n#   The type of secondary extruder. Available choices are 'trad_rack'\n#   or 'extruder_stepper'. This parameter must be specified.\nextruder_stepper_name:\n#   The name of the extruder_stepper being used as the secondary\n#   extruder. Must be specified if extruder_type is set to\n#   'extruder_stepper', but should not be specified otherwise. For\n#   example, if the config section for the secondary extruder is\n#   [extruder_stepper my_extruder_stepper], this parameter's value\n#   would be 'my_extruder_stepper'.\nsensor_pin:\n#   Input pin connected to the sensor. This parameter must be\n#   provided.\n#multiplier_high: 1.05\n#   High multiplier to set for the secondary extruder when extruding\n#   forward and Belay is compressed or when extruding backward and\n#   Belay is expanded. The default is 1.05.\n#multiplier_low: 0.95\n#   Low multiplier to set for the secondary extruder when extruding\n#   forward and Belay is expanded or when extruding backward and\n#   Belay is compressed. The default is 0.95.\n#debug_level: 0\n#   Controls messages sent to the console. If set to 0, no messages\n#   will be sent. If set to 1, multiplier resets will be reported, and\n#   the multiplier will be reported whenever it is set in response to\n#   a switch state change. If set to 2, the behavior is the same as 1\n#   but with an additional message whenever the multiplier is set in\n#   response to detecting an extrusion direction change. The default\n#   is 0.\n
    "},{"location":"Config_Reference.html#load-cells","title":"Load Cells","text":""},{"location":"Config_Reference.html#load_cell","title":"[load_cell]","text":"

    Load Cell. Uses an ADC sensor attached to a load cell to create a digital scale.

    [load_cell]\nsensor_type:\n#   This must be one of the supported sensor types, see below.\n
    "},{"location":"Config_Reference.html#hx711","title":"HX711","text":"

    This is a 24 bit low sample rate chip using \"bit-bang\" communications. It is suitable for filament scales.

    [load_cell]\nsensor_type: hx711\nsclk_pin:\n#   The pin connected to the HX711 clock line. This parameter must be provided.\ndout_pin:\n#   The pin connected to the HX711 data output line. This parameter must be\n#   provided.\n#gain: A-128\n#   Valid values for gain are: A-128, A-64, B-32. The default is A-128.\n#   'A' denotes the input channel and the number denotes the gain. Only the 3\n#   listed combinations are supported by the chip. Note that changing the gain\n#   setting also selects the channel being read.\n#sample_rate: 80\n#   Valid values for sample_rate are 80 or 10. The default value is 80.\n#   This must match the wiring of the chip. The sample rate cannot be changed\n#   in software.\n
    "},{"location":"Config_Reference.html#hx717","title":"HX717","text":"

    This is the 4x higher sample rate version of the HX711, suitable for probing.

    [load_cell]\nsensor_type: hx717\nsclk_pin:\n#   The pin connected to the HX717 clock line. This parameter must be provided.\ndout_pin:\n#   The pin connected to the HX717 data output line. This parameter must be\n#   provided.\n#gain: A-128\n#   Valid values for gain are A-128, B-64, A-64, B-8.\n#   'A' denotes the input channel and the number denotes the gain setting.\n#   Only the 4 listed combinations are supported by the chip. Note that\n#   changing the gain setting also selects the channel being read.\n#sample_rate: 320\n#   Valid values for sample_rate are: 10, 20, 80, 320. The default is 320.\n#   This must match the wiring of the chip. The sample rate cannot be changed\n#   in software.\n
    "},{"location":"Config_Reference.html#ads1220","title":"ADS1220","text":"

    The ADS1220 is a 24 bit ADC supporting up to a 2Khz sample rate configurable in software.

    [load_cell]\nsensor_type: ads1220\ncs_pin:\n#   The pin connected to the ADS1220 chip select line. This parameter must\n#   be provided.\n#spi_speed: 512000\n#   This chip supports 2 speeds: 256000 or 512000. The faster speed is only\n#   enabled when one of the Turbo sample rates is used. The correct spi_speed\n#   is selected based on the sample rate.\n#spi_bus:\n#spi_software_sclk_pin:\n#spi_software_mosi_pin:\n#spi_software_miso_pin:\n#   See the \"common SPI settings\" section for a description of the\n#   above parameters.\ndata_ready_pin:\n#   Pin connected to the ADS1220 data ready line. This parameter must be\n#   provided.\n#gain: 128\n#   Valid gain values are 128, 64, 32, 16, 8, 4, 2, 1\n#   The default is 128\n#pga_bypass: False\n#   Disable the internal Programmable Gain Amplifier. If\n#   True the PGA will be disabled for gains 1, 2, and 4. The PGA is always\n#   enabled for gain settings 8 to 128, regardless of the pga_bypass setting.\n#   If AVSS is used as an input pga_bypass is forced to True.\n#   The default is False.\n#sample_rate: 660\n#   This chip supports two ranges of sample rates, Normal and Turbo. In turbo\n#   mode the chip's internal clock runs twice as fast and the SPI communication\n#   speed is also doubled.\n#   Normal sample rates: 20, 45, 90, 175, 330, 600, 1000\n#   Turbo sample rates: 40, 90, 180, 350, 660, 1200, 2000\n#   The default is 660\n#input_mux:\n#   Input multiplexer configuration, select a pair of pins to use. The first pin\n#   is the positive, AINP, and the second pin is the negative, AINN. Valid\n#   values are: 'AIN0_AIN1', 'AIN0_AIN2', 'AIN0_AIN3', 'AIN1_AIN2', 'AIN1_AIN3',\n#   'AIN2_AIN3', 'AIN1_AIN0', 'AIN3_AIN2', 'AIN0_AVSS', 'AIN1_AVSS', 'AIN2_AVSS'\n#   and 'AIN3_AVSS'. If AVSS is used the PGA is bypassed and the pga_bypass\n#   setting will be forced to True.\n#   The default is AIN0_AIN1.\n#vref:\n#   The selected voltage reference. Valid values are: 'internal', 'REF0', 'REF1'\n#   and 'analog_supply'. Default is 'internal'.\n
    "},{"location":"Config_Reference.html#board-specific-hardware-support","title":"Board specific hardware support","text":""},{"location":"Config_Reference.html#sx1509","title":"[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]\ni2c_address:\n#   I2C address used by this expander. Depending on the hardware\n#   jumpers this is one out of the following addresses: 62 63 112\n#   113. This parameter must be provided.\n#i2c_mcu:\n#i2c_bus:\n#i2c_software_scl_pin:\n#i2c_software_sda_pin:\n#i2c_speed:\n#   See the \"common I2C settings\" section for a description of the\n#   above parameters.\n
    "},{"location":"Config_Reference.html#samd_sercom","title":"[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]\nsercom:\n#   The name of the sercom bus to configure in the micro-controller.\n#   Available names are \"sercom0\", \"sercom1\", etc.. This parameter\n#   must be provided.\ntx_pin:\n#   MOSI pin for SPI communication, or SDA (data) pin for I2C\n#   communication. The pin must have a valid pinmux configuration\n#   for the given SERCOM peripheral. This parameter must be provided.\n#rx_pin:\n#   MISO pin for SPI communication. This pin is not used for I2C\n#   communication (I2C uses tx_pin for both sending and receiving).\n#   The pin must have a valid pinmux configuration for the given\n#   SERCOM peripheral. This parameter is optional.\nclk_pin:\n#   CLK pin for SPI communication, or SCL (clock) pin for I2C\n#   communication. The pin must have a valid pinmux configuration\n#   for the given SERCOM peripheral. This parameter must be provided.\n
    "},{"location":"Config_Reference.html#adc_scaled","title":"[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]\nvref_pin:\n#   The ADC pin to use for VREF monitoring. This parameter must be\n#   provided.\nvssa_pin:\n#   The ADC pin to use for VSSA monitoring. This parameter must be\n#   provided.\n#smooth_time: 2.0\n#   A time value (in seconds) over which the vref and vssa\n#   measurements will be smoothed to reduce the impact of measurement\n#   noise. The default is 2 seconds.\n
    "},{"location":"Config_Reference.html#replicape","title":"[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\"\n# virtual stepper enable pins (for steppers X, Y, Z, E, and H) and\n# \"replicape:power_x\" PWM output pins (for hotbed, e, h, fan0, fan1,\n# fan2, and fan3) that may then be used elsewhere in the config file.\n[replicape]\nrevision:\n#   The replicape hardware revision. Currently only revision \"B3\" is\n#   supported. This parameter must be provided.\n#enable_pin: !gpio0_20\n#   The replicape global enable pin. The default is !gpio0_20 (aka\n#   P9_41).\nhost_mcu:\n#   The name of the mcu config section that communicates with the\n#   Kalico \"linux process\" mcu instance. This parameter must be\n#   provided.\n#standstill_power_down: False\n#   This parameter controls the CFG6_ENN line on all stepper\n#   motors. True sets the enable lines to \"open\". The default is\n#   False.\n#stepper_x_microstep_mode:\n#stepper_y_microstep_mode:\n#stepper_z_microstep_mode:\n#stepper_e_microstep_mode:\n#stepper_h_microstep_mode:\n#   This parameter controls the CFG1 and CFG2 pins of the given\n#   stepper motor driver. Available options are: disable, 1, 2,\n#   spread2, 4, 16, spread4, spread16, stealth4, and stealth16. The\n#   default is disable.\n#stepper_x_current:\n#stepper_y_current:\n#stepper_z_current:\n#stepper_e_current:\n#stepper_h_current:\n#   The configured maximum current (in Amps) of the stepper motor\n#   driver. This parameter must be provided if the stepper is not in a\n#   disable mode.\n#stepper_x_chopper_off_time_high:\n#stepper_y_chopper_off_time_high:\n#stepper_z_chopper_off_time_high:\n#stepper_e_chopper_off_time_high:\n#stepper_h_chopper_off_time_high:\n#   This parameter controls the CFG0 pin of the stepper motor driver\n#   (True sets CFG0 high, False sets it low). The default is False.\n#stepper_x_chopper_hysteresis_high:\n#stepper_y_chopper_hysteresis_high:\n#stepper_z_chopper_hysteresis_high:\n#stepper_e_chopper_hysteresis_high:\n#stepper_h_chopper_hysteresis_high:\n#   This parameter controls the CFG4 pin of the stepper motor driver\n#   (True sets CFG4 high, False sets it low). The default is False.\n#stepper_x_chopper_blank_time_high:\n#stepper_y_chopper_blank_time_high:\n#stepper_z_chopper_blank_time_high:\n#stepper_e_chopper_blank_time_high:\n#stepper_h_chopper_blank_time_high:\n#   This parameter controls the CFG5 pin of the stepper motor driver\n#   (True sets CFG5 high, False sets it low). The default is True.\n
    "},{"location":"Config_Reference.html#other-custom-modules","title":"Other Custom Modules","text":""},{"location":"Config_Reference.html#palette2","title":"[palette2]","text":"

    Palette 2 multimaterial support - provides a tighter integration supporting Palette 2 devices in connected mode.

    This modules also requires [virtual_sdcard] and [pause_resume] for full functionality.

    If you use this module, do not use the Palette 2 plugin for Octoprint as they will conflict, and 1 will fail to initialize properly likely aborting your print.

    If you use Octoprint and stream gcode over the serial port instead of printing from virtual_sd, then remo M1 and M0 from Pausing commands in Settings > Serial Connection > Firmware & protocol will prevent the need to start print on the Palette 2 and unpausing in Octoprint for your print to begin.

    [palette2]\nserial:\n#   The serial port to connect to the Palette 2.\n#baud: 115200\n#   The baud rate to use. The default is 115200.\n#feedrate_splice: 0.8\n#   The feedrate to use when splicing, default is 0.8\n#feedrate_normal: 1.0\n#   The feedrate to use after splicing, default is 1.0\n#auto_load_speed: 2\n#   Extrude feedrate when autoloading, default is 2 (mm/s)\n#auto_cancel_variation: 0.1\n#   Auto cancel print when ping variation is above this threshold\n
    "},{"location":"Config_Reference.html#angle","title":"[angle]","text":"

    Magnetic hall angle sensor support for reading stepper motor angle shaft measurements using a1333, as5047d, or tle5012b SPI chips. The measurements are available via the API Server and motion analysis tool. See the G-Code reference for available commands.

    [angle my_angle_sensor]\nsensor_type:\n#   The type of the magnetic hall sensor chip. Available choices are\n#   \"a1333\", \"as5047d\", and \"tle5012b\". This parameter must be\n#   specified.\n#sample_period: 0.000400\n#   The query period (in seconds) to use during measurements. The\n#   default is 0.000400 (which is 2500 samples per second).\n#stepper:\n#   The name of the stepper that the angle sensor is attached to (eg,\n#   \"stepper_x\"). Setting this value enables an angle calibration\n#   tool. To use this feature, the Python \"numpy\" package must be\n#   installed. The default is to not enable angle calibration for the\n#   angle sensor.\ncs_pin:\n#   The SPI enable pin for the sensor. This parameter must be provided.\n#spi_speed:\n#spi_bus:\n#spi_software_sclk_pin:\n#spi_software_mosi_pin:\n#spi_software_miso_pin:\n#   See the \"common SPI settings\" section for a description of the\n#   above parameters.\n
    "},{"location":"Config_Reference.html#tools_calibrate","title":"\u26a0\ufe0f [tools_calibrate]","text":"

    Multi-toolhead nozzle offset calibration, using a 3-axis nozzle contact probe such as Zruncho3D's Nudge Probe.

    [tools_calibrate]\npin:\ntravel_speed: 20\n#   X and Y travel speed in mm/sec\nspread: 5\n#spread_x:\n#spread_y:\n#   X and Y travel distance around the probe\n#initial_spread:\n#initial_spread_x:\n#initial_spread_y:\n#   X and Y travel distance for the initial probe locating moves\nlower_z: 1.0\n#   Distance to lower in Z for contact with the sides of the probe\nspeed: 2\n#   The speed (in mm/sec) to retract between probes\nlift_speed: 4\n#   Z Lift speed after probing\nfinal_lift_z: 6\n#   Z lift distance after calibration, must be greater than any\n#   height variance between tools\ntrigger_to_bottom_z: 0.25\n#   Offset from probe trigger to vertical motion bottoms out.\n#   decrease if the nozzle is too high, increase if too low.\n#samples: 1\n#   The number of times to probe each point. The probed z-values will\n#   be averaged. The default is to probe 1 time.\n#sample_retract_dist: 2.0\n#   The distance (in mm) to lift the toolhead between each sample (if\n#   sampling more than once). The default is 2mm.\n#samples_result: average\n#   The calculation method when sampling more than once - either\n#   \"median\" or \"average\". The default is average.\n#samples_tolerance: 0.100\n#   The maximum Z distance (in mm) that a sample may differ from other\n#   samples. If this tolerance is exceeded then either an error is\n#   reported or the attempt is restarted (see\n#   samples_tolerance_retries). The default is 0.100mm.\n
    "},{"location":"Config_Reference.html#trad_rack","title":"[trad_rack]","text":"

    Trad Rack multimaterial system support. See the following documents from the TradRack repo for additional information:

    [trad_rack]\nselector_max_velocity:\n#   Maximum velocity (in mm/s) of the selector.\n#   This parameter must be specified.\nselector_max_accel:\n#   Maximum acceleration (in mm/s^2) of the selector.\n#   This parameter must be specified.\n#filament_max_velocity:\n#   Maximum velocity (in mm/s) for filament movement.\n#   Defaults to buffer_pull_speed.\n#filament_max_accel: 1500.0\n#   Maximum acceleration (in mm/s^2) for filament movement.\n#   The default is 1500.0.\ntoolhead_fil_sensor_pin:\n#   The pin on which the toolhead filament sensor is connected.\n#   If a pin is not specified, no toolhead filament sensor will\n#   be used.\nlane_count:\n#   The number of filament lanes. This parameter must be specified.\nlane_spacing:\n#   Spacing (in mm) between filament lanes.\n#   This parameter must be specified.\n#lane_offset_<lane index>:\n#   Options with a \"lane_offset_\" prefix may be specified for any of\n#   the lanes (from 0 to lane_count - 1). The option will apply an\n#   offset (in mm) to the corresponding lane's position. Lane offsets\n#   do not affect the position of any lanes besides the one specified\n#   in the option name. This option is intended for fine adjustment\n#   of each lane's position to ensure that the filament paths in the\n#   lane module and selector line up with each other.\n#   The default is 0.0 for each lane.\n#lane_spacing_mod_<lane index>:\n#   Options with a \"lane_spacing_mod_\" prefix may be specified for any\n#   of the lanes (from 0 to lane_count - 1). The option will apply an\n#   offset (in mm) to the corresponding lane's position, as well as\n#   any lane with a higher index. For example, if lane_spacing_mod_2\n#   is 4.0, any lane with an index of 2 or above will have its\n#   position increased by 4.0. This option is intended to account for\n#   variations in a lane module that will affect its position as well\n#   as the positions of any subsequent modules with a higher index.\n#   The default is 0.0 for each lane.\nservo_down_angle:\n#   The angle (in degrees) for the servo's down position.\n#   This parameter must be specified.\nservo_up_angle:\n#   The angle (in degrees) for the servo's up position.\n#   This parameter must be specified.\n#servo_wait_ms: 500\n#   Time (in milliseconds) to wait for the servo to complete moves\n#   between the up and down angles. The default is 500.\nselector_unload_length:\n#   Length (in mm) to retract a piece of filament out of the selector\n#   and back into the lane module after the selector sensor has been\n#   triggered or untriggered. This parameter must be specified.\n#selector_unload_length_extra: 0.0\n#   Extra length (in mm) that is added to selector_unload_length when\n#   retracting a piece of filament out of the selector and back into\n#   the lane module. After the retraction, the filament is moved\n#   forward by this length as well (so this option's value has no\n#   effect on the final position of the filament). This option may be\n#   useful when using Trad Rack with a motorized spool rewinder that\n#   senses tension or compression in the filament between the spool\n#   and Trad Rack in order to determine when to rotate the spool. The\n#   extra forward movement of the filament after retracting is\n#   intended to force the rewinder's sensor to detect tension in the\n#   filament, causing rewinding to cease immediately so the filament\n#   tip is not moved out of position by excess spool movement. The\n#   default is 0.0.\n#eject_length: 10.0\n#   Length (in mm) to eject the filament into the lane module past the\n#   length defined by selector_unload_length. The filament is ejected\n#   whenever unloading a depleted spool after a runout to make sure\n#   that filament segment is not loaded again until it has been\n#   replaced.\nbowden_length:\n#   Length (in mm) to quickly move filament through the bowden tube\n#   between Trad Rack and the toolhead during loads and unloads.\n#   See Tuning.md for details. This parameter must be specified.\nextruder_load_length:\n#   Length (in mm) to move filament into the extruder when loading the\n#   toolhead. See Tuning.md for details.\n#   This parameter must be specified.\nhotend_load_length:\n#   Length (in mm) to move filament into the hotend when loading the\n#   toolhead. See Tuning.md for details.\n#   This parameter must be specified.\ntoolhead_unload_length:\n#   Length (in mm) to move filament out of the toolhead during an\n#   unload. See Tuning.md for details. If toolhead_fil_sensor_pin is\n#   specified, this parameter must be specified.\n#   If toolhead_fil_sensor_pin is not specified, the default is\n#   extruder_load_length + hotend_load_length.\n#selector_sense_speed: 40.0\n#   Speed (in mm/s) when moving filament until the selector\n#   sensor is triggered or untriggered. See Tuning.md for details\n#   on when this speed is applied. The default is 40.0.\n#selector_unload_speed: 60.0\n#   Speed (in mm/s) to move filament when unloading the selector.\n#   The default is 60.0.\n#eject_speed: 80.0\n#   Speed (in mm/s) to move the filament when ejecting a filament\n#   segment into the lane module.\n#spool_pull_speed: 100.0\n#   Speed (in mm/s) to move filament through the bowden tube when\n#   loading from a spool. See Tuning.md for details.\n#   The default is 100.0.\n#buffer_pull_speed:\n#   Speed (in mm/s) to move filament through the bowden tube when\n#   unloading or loading from a buffer. See Tuning.md for details.\n#   Defaults to spool_pull_speed.\n#toolhead_sense_speed:\n#   Speed (in mm/s) when moving filament until the toolhead\n#   sensor is triggered or untriggered. See Tuning.md for details on\n#   when this speed is applied. Defaults to selector_sense_speed.\n#extruder_load_speed:\n#   Speed (in mm/s) to move filament into the extruder when loading\n#   the toolhead. See Tuning.md for details. The default is 60.0.\n#hotend_load_speed:\n#   Speed (in mm/s) to move filament into the hotend when loading the\n#   toolhead. See Tuning.md for details. The default is 7.0.\n#toolhead_unload_speed:\n#   Speed (in mm/s) to move filament when unloading the toolhead.\n#   See Tuning.md for details. Defaults to extruder_load_speed.\n#load_with_toolhead_sensor: True\n#   Whether to use the toolhead sensor when loading the toolhead.\n#   See Tuning.md for details. Defaults to True but is ignored if\n#   toolhead_fil_sensor_pin is not specified.\n#unload_with_toolhead_sensor: True\n#   Whether to use the toolhead sensor when unloading the toolhead.\n#   See Tuning.md for details. Defaults to True but is ignored if\n#   toolhead_fil_sensor_pin is not specified.\n#fil_homing_retract_dist: 20.0\n#   Distance (in mm) to retract filament away from a filament sensor\n#   before moving on to the next move. This retraction occurs whenever\n#   a filament sensor is triggered early during a fast move through\n#   the bowden tube. See Tuning.md for details. The default is 20.0.\n#target_toolhead_homing_dist:\n#   Target filament travel distance (in mm) when homing to the\n#   toolhead filament sensor during a load. See Tuning.md for details.\n#   Defaults to either 10.0 or toolhead_unload_length, whichever is\n#   greater.\n#target_selector_homing_dist:\n#   Target filament travel distance (in mm) when homing to the\n#   selector filament sensor during an unload. See Tuning.md for\n#   details. The default is 10.0.\n#bowden_length_samples: 10\n#   Maximum number of samples that are averaged to set bowden lengths\n#   for loading and unloading. See Tuning.md for details. The default\n#   is 10.\n#load_lane_time: 15\n#   Approximate maximum time (in seconds) to wait for filament to\n#   reach the selector filament sensor when loading a lane with the\n#   TR_LOAD_LANE gcode command. This time starts when the user is\n#   prompted to insert filament and determines when the command will\n#   be halted early if no filament is detected. The default is 15.\n#load_selector_homing_dist:\n#   Maximum distance to try to move filament when loading from a lane\n#   module to the selector filament sensor before halting the homing\n#   move. This value is not used by the TR_LOAD_LANE command but is\n#   used in similar scenarios that do not involve user interaction.\n#   Defaults to selector_unload_length * 2.\n#bowden_load_homing_dist:\n#   Maximum distance to try to move filament near the end of a\n#   toolhead load (during the slow homing move to the toolhead sensor)\n#   before halting the homing move. Defaults to bowden_length.\n#bowden_unload_homing_dist:\n#   Maximum distance to try to move filament near the end of a\n#   toolhead unload (during the slow homing move to the selector\n#   sensor) before halting the homing move. Defaults to bowden_length.\n#unload_toolhead_homing_dist:\n#   Maximum distance to try to move filament near the beginning of a\n#   toolhead unload (during the homing move to the toolhead sensor)\n#   before halting the homing move.\n#   Defaults to (extruder_load_length + hotend_load_length) * 2.\n#sync_to_extruder: False\n#   Syncs Trad Rack's filament driver to the extruder during printing,\n#   as well as during any extrusion moves within toolhead loading or\n#   unloading that would normally involve only the extruder.\n#   The default is False.\n#user_wait_time: 15\n#   Time (in seconds) to wait for the user to take an action\n#   before continuing automatically. If set to -1, Trad Rack will wait\n#   for the user indefinitely. This value is currently used by the\n#   TR_LOCATE_SELECTOR gcode command. The default is 15.\n#register_toolchange_commands: True\n#   Whether to register gcode commands T0, T1, T2, etc. so that they\n#   can be used to initiate toolchanges with Trad Rack. If set to\n#   False, the TR_LOAD_TOOLHEAD command can still be used as a\n#   substitute to initiate toolchanges. The default is True.\n#save_active_lane: True\n#   Whether to save the active lane to disk whenever it is set using\n#   save_variables. If set to True, the TR_LOCATE_SELECTOR gcode\n#   command will infer the active lane if the selector filament sensor\n#   is triggered and an active lane was saved previously.\n#   The default is True.\n#log_bowden_lengths: False\n#   Whether to log bowden load length data and bowden unload length\n#   data (to ~/bowden_load_lengths.csv and ~/bowden_unload_lengths.csv\n#   respectively). The default is False.\n#pre_unload_gcode:\n#   Gcode command template that is run before the toolhead is\n#   unloaded. The default is to run no extra commands.\n#post_unload_gcode:\n#   Gcode command template that is run after the toolhead is\n#   unloaded. The default is to run no extra commands.\n#pre_load_gcode:\n#   Gcode command template that is run before the toolhead is\n#   loaded. The default is to run no extra commands.\n#post_load_gcode:\n#   Gcode command template that is run after the toolhead is\n#   loaded. The default is to run no extra commands.\n#pause_gcode:\n#   Gcode command template that is run whenever Trad Rack needs to\n#   pause the print (usually due to a failed load or unload). The\n#   default is to run the PAUSE gcode command.\n#resume_gcode:\n#   Gcode command template that is run whenever the TR_RESUME command\n#   needs to resume the print. The default is to run the RESUME\n#   gcode command.\n
    "},{"location":"Config_Reference.html#common-bus-parameters","title":"Common bus parameters","text":""},{"location":"Config_Reference.html#common-spi-settings","title":"Common SPI settings","text":"

    The following parameters are generally available for devices using an SPI bus.

    #spi_speed:\n#   The SPI speed (in hz) to use when communicating with the device.\n#   The default depends on the type of device.\n#spi_bus:\n#   If the micro-controller supports multiple SPI busses then one may\n#   specify the micro-controller bus name here. The default depends on\n#   the type of micro-controller.\n#spi_software_sclk_pin:\n#spi_software_mosi_pin:\n#spi_software_miso_pin:\n#   Specify the above parameters to use \"software based SPI\". This\n#   mode does not require micro-controller hardware support (typically\n#   any general purpose pins may be used). The default is to not use\n#   \"software spi\".\n
    "},{"location":"Config_Reference.html#common-i2c-settings","title":"Common I2C settings","text":"

    The following parameters are generally available for devices using an I2C bus.

    Note that Kalico's current micro-controller support for I2C is generally not tolerant to line noise. Unexpected errors on the I2C wires may result in Kalico raising a run-time error. Kalico'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 Kalico micro-controller implementations only support an i2c_speed of 100000 (standard mode, 100kbit/s). The Kalico \"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 Kalico \"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 Kalico micro-controllers use a 100000 rate and ignore the i2c_speed parameter.

    #i2c_address:\n#   The i2c address of the device. This must specified as a decimal\n#   number (not in hex). The default depends on the type of device.\n#i2c_mcu:\n#   The name of the micro-controller that the chip is connected to.\n#   The default is \"mcu\".\n#i2c_bus:\n#   If the micro-controller supports multiple I2C busses then one may\n#   specify the micro-controller bus name here. The default depends on\n#   the type of micro-controller.\n#i2c_software_scl_pin:\n#i2c_software_sda_pin:\n#   Specify these parameters to use micro-controller software based\n#   I2C \"bit-banging\" support. The two parameters should the two pins\n#   on the micro-controller to use for the scl and sda wires. The\n#   default is to use hardware based I2C support as specified by the\n#   i2c_bus parameter.\n#i2c_speed:\n#   The I2C speed (in Hz) to use when communicating with the device.\n#   The Kalico implementation on most micro-controllers is hard-coded\n#   to 100000 and changing this value has no effect. The default is\n#   100000. Linux, RP2040 and ATmega support 400000.\n
    "},{"location":"Config_Reference_Bleeding_Edge.html","title":"Configuration reference for Bleeding Edge features","text":"

    This document is a reference for options available in the Kalico config file for bleeding edge features. Refer to the Bleeding Edge Documentation for details on specific features.

    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 Kalico and choosing an initial config file.

    "},{"location":"Config_Reference_Bleeding_Edge.html#high-precision-stepping-and-new-stepcompress-protocol","title":"High precision stepping and new stepcompress protocol","text":"

    This feature is enabled during Kalico firmware compile by selecting \"High-precision stepping support\" option in menuconfig. The firmware then needs to be flashed to all MCU(s) using this feature.

    The following configuration line should be added to each stepper in printer.cfg. For example in a CoreXY system the config line would be added to [stepper_x] and [stepper_y] so that it is enabled in both steppers controlling the X-Y movement of the toolhead.

    [stepper_... ]\nhigh_precision_step_compress: True\n

    Note that enabling this feature in the config without recompiling and flashing the firmware will give an error.

    "},{"location":"Config_Reference_Bleeding_Edge.html#input-shaper","title":"Input shaper","text":""},{"location":"Config_Reference_Bleeding_Edge.html#input_shaper","title":"[input_shaper]","text":"

    Extruder PA Synchronization with Input Shaping

    [input_shaper]\nenabled_extruders: extruder\n

    Smooth Input Shapers

    [input_shaper]\nshaper_type:\n#   A type of the input shaper to use for both X and Y axes. Supported\n#   shapers are smooth_zv, smooth_mzv, smooth_ei, smooth_2hump_ei, smooth_zvd_ei,\n#   smooth_si, mzv, ei, 2hump_ei.\n#shaper_type_x:\n#shaper_type_y:\n#   If shaper_type is not set, these two parameters can be used to\n#   configure different input shapers for X and Y axes. The same\n#   values are supported as for shaper_type parameter.\nsmoother_freq_x: 0\n#  A frequency (in Hz) of the smooth input shaper for X axis.\nsmoother_freq_y: 0\n#  A frequency (in Hz) of the smooth input shaper for Y axis.\n#damping_ratio_x: 0.1\n#damping_ratio_y: 0.1\n#   Damping ratios of vibrations of X and Y axes used by input shapers\n#   to improve vibration suppression. Default value is 0.1 which is a\n#   good all-round value for most printers. In most circumstances this\n#   parameter requires no tuning and should not be changed.\n#   Note: Damping ratios are not currently supported for input smoothers.\n
    "},{"location":"Config_Reference_Bleeding_Edge.html#test-print-utilities","title":"Test print utilities","text":""},{"location":"Config_Reference_Bleeding_Edge.html#ringing_test","title":"[ringing_test]","text":"

    Ringing tower test print utility which isolates vibrations to one axis at a time.

    [ringing_test]\nsize: 100\n#   X-Y Size of tower footprint (mm)\nheight: 60\n#   Height of of tower (mm)\nband: 5\n#   Height for each ringing step (mm)\nperimeters: 2\n#   Number of perimeters to be printed for the tower\nvelocity: 80\n#   Is the velocity one must use as V in a formula V * N / D when\n#   calculating the resonance frequency. N and D are the number of\n#   oscillations and the distance between them as usual:\nbrim_velocity: 30\n#   Speed for brim printing in (mm/s)\naccel_start: 1500\n#   The acceleration of the start of the test\naccel_step: 500\n#   The increment of the acceleration every `band` (mm/s^2)\nlayer_height: 0.2\nfirst_layer_height: 0.2\nfilament_diameter: 1.75\n\n#   Parameters that are computed automatically, but may be adjusted if necessary\n\n#center_x:\n#   Center of the bed by default (if detected correctly)\n#center_y:\n#   Center of the bed by default (if detected correctly)\n#brim_width:\n#   Computed based on the model size, but may be increased\n\n#   Parameters that are better left at their default values\n\n#notch: 1\n#   Size of the notch in mm\n#notch_offset:\n#   0.275 * size by default\n#deceleration_points: 100\n
    "},{"location":"Config_Reference_Bleeding_Edge.html#pa_test","title":"[pa_test]","text":"

    Pressure advance tower test print utility

    [pa_test]\nsize_x: 100\n#    X dimension tower size  (mm)\nsize_y: 50\n#    Y dimension tower size  (mm)\nheight: 50\n#   Height of tower (mm)\norigin_x:\n#   Center of the bed in x\norigin_y:\n#   Center of the bed in y\nlayer_height: 0.2\nfirst_layer_height: 0.3\nperimeters: 2\n#   Number of perimeters to be printed for the tower\nbrim_width: 10\n#   Width of brim (mm)\nslow_velocity: 20\n#   Start velocity for PA test segment (mm/s)\nmedium_velocity: 50\n#   Medium velocity for PA test segment (mm/s)\nfast_velocity: 80\n#   End velocity for PA test segment (mm/s)\nfilament_diameter: 1.75\n
    "},{"location":"Config_checks.html","title":"Configuration checks","text":"

    This document provides a list of steps to help confirm the pin settings in the Kalico 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 Kalico 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.

    "},{"location":"Config_checks.html#verify-temperature","title":"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.

    "},{"location":"Config_checks.html#verify-m112","title":"Verify M112","text":"

    Navigate to the command console and issue an M112 command in the terminal box. This command requests Kalico 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.

    "},{"location":"Config_checks.html#verify-heaters","title":"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.

    "},{"location":"Config_checks.html#verify-stepper-motor-enable-pin","title":"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\").

    "},{"location":"Config_checks.html#verify-endstops","title":"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).

    "},{"location":"Config_checks.html#verify-stepper-motors","title":"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.

    "},{"location":"Config_checks.html#verify-extruder-motor","title":"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.

    "},{"location":"Config_checks.html#calibrate-pid-settings","title":"Calibrate PID settings","text":"

    Kalico 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

    "},{"location":"Config_checks.html#next-steps","title":"Next steps","text":"

    This guide is intended to help with basic verification of pin settings in the Kalico configuration file. Be sure to read the bed leveling guide. Also see the Slicers document for information on configuring a slicer with Kalico.

    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.

    "},{"location":"Contact.html","title":"Contact","text":"

    This document provides contact information for Kalico. Kalico a community-maintained fork of the Kalico firmware.

    "},{"location":"Contact.html#discord","title":"Discord","text":"

    Kalico has a dedicated Discord server where you can chat with the developers and users of Kalico in real-time.

    You can join the server here: kalico.gg/discord

    "},{"location":"Contact.html#i-have-a-question-about-kalico","title":"I have a question about Kalico","text":"

    Many questions we receive are already answered in the Overview. Please be sure to to read the documentation and follow the directions provided there.

    If you are interested in sharing your knowledge and experience with other Kalico users then you can join the Kalico Discord server

    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.

    "},{"location":"Contact.html#i-have-a-feature-request","title":"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 on the GitHub issues page and pull requests page

    There also are discussions between collaborators on the Kalico Discord server.

    "},{"location":"Contact.html#help-it-doesnt-work","title":"Help! It doesn't work!","text":"

    If you are experiencing problems we recommend you carefully read the Overview 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 Kalico 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.

    "},{"location":"Contact.html#i-found-a-bug-in-the-kalico-software","title":"I found a bug in the Kalico software","text":"

    Kalico is an open-source project and we appreciate when collaborators diagnose errors in the software.

    Problems should be reported on the Discord server

    There is important information that will be needed in order to fix a bug. Please follow these steps:

    1. Make sure you are running unmodified code from https://github.com/KalicoCrew/kalico. 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/KalicoCrew/kalico prior to reporting.
    2. If possible, run an M112 command immediately after the undesirable event occurs. This causes Kalico to go into a \"shutdown state\" and it will cause additional debugging information to be written to the log file.
    3. Obtain the Kalico log file from the event. The log file has been engineered to answer common questions the Kalico developers have about the software and its environment (software version, hardware type, configuration, event timing, and hundreds of other questions).
      1. Dedicated Kalico web interfaces have the ability to directly obtain the Kalico 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).
      2. Copy the log file to your desktop so that it can be attached to an issue report.
      3. 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.
      4. It is a good idea to compress the log file with zip or gzip.
    4. Open a new thread on the Discord server and provide a clear description of the problem. Other Kalico contributors will need to understand what steps were taken, what the desired outcome was, and what outcome actually occurred. The compressed Kalico log file should be attached to that topic.
    "},{"location":"Contact.html#i-am-making-changes-that-id-like-to-include-in-kalico","title":"I am making changes that I'd like to include in Kalico","text":"

    Kalico 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 on the Discord server

    "},{"location":"Debugging.html","title":"Debugging","text":"

    This document describes some of the Kalico debugging tools.

    "},{"location":"Debugging.html#running-the-regression-tests","title":"Running the regression tests","text":"

    The main Kalico 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\n

    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\n~/klippy-env/bin/python ~/klipper/scripts/test_klippy.py -d dict/ ~/klipper/test/klippy/*.test\n
    "},{"location":"Debugging.html#manually-sending-commands-to-the-micro-controller","title":"Manually sending commands to the micro-controller","text":"

    Normally, the host klippy.py process would be used to translate gcode commands to Kalico micro-controller commands. However, it's also possible to manually send these MCU commands (functions marked with the DECL_COMMAND() macro in the Kalico source code). To do so, run:

    ~/klippy-env/bin/python ./klippy/console.py /tmp/pseudoserial\n

    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

    "},{"location":"Debugging.html#translating-gcode-files-to-micro-controller-commands","title":"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\nmake\n

    Once the above is done it is possible to run Kalico 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\n

    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\n

    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.

    "},{"location":"Debugging.html#motion-analysis-and-data-logging","title":"Motion analysis and data logging","text":"

    Kalico supports logging its internal motion history, which can be later analyzed. To use this feature, Kalico 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\n

    This command will connect to the Kalico 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\nsudo apt-get install python-matplotlib\n

    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\n

    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)\"]]'\n

    The list of available datasets can be found using the -l option - for example:

    ~/klipper/scripts/motan/motan_graph.py -l\n

    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\"]]'\n

    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

    "},{"location":"Debugging.html#generating-load-graphs","title":"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\nsudo apt-get install python-matplotlib\n

    Then graphs can be produced with:

    ~/klipper/scripts/graphstats.py /tmp/klippy.log -o loadgraph.png\n

    One can then view the resulting loadgraph.png file.

    Different graphs can be produced. For more information run: ~/klipper/scripts/graphstats.py --help

    "},{"location":"Debugging.html#extracting-information-from-the-klippylog-file","title":"Extracting information from the klippy.log 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\ncd work_directory\ncp /tmp/klippy.log .\n~/klipper/scripts/logextract.py ./klippy.log\n

    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.

    "},{"location":"Debugging.html#testing-with-simulavr","title":"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\ncd simulavr\nmake python\nmake build\n

    Make sure a file like ./build/pysimulavr/_pysimulavr.*.so is present after the above compilation:

    ls ./build/pysimulavr/_pysimulavr.*.so\n

    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\nsudo apt install g++ make cmake swig rst2pdf help2man texinfo\nmake cfgclean python debian\nsudo dpkg -i build/debian/python3-simulavr*.deb\n

    To compile Kalico for use in simulavr, run:

    cd /path/to/kalico\nmake menuconfig\n

    and compile the micro-controller software for an AVR atmega644p and select SIMULAVR software emulation support. Then one can compile Kalico (run make) and then start the simulation with:

    PYTHONPATH=/path/to/simulavr/build/pysimulavr/ ./scripts/avrsim.py out/klipper.elf\n

    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\n

    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 Kalico 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\n
    "},{"location":"Debugging.html#using-simulavr-with-gtkwave","title":"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\n

    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\n
    "},{"location":"Delta_Calibrate.html","title":"Delta calibration","text":"

    This document describes Kalico'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.

    "},{"location":"Delta_Calibrate.html#automatic-vs-manual-probing","title":"Automatic vs manual probing","text":"

    Kalico 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.

    "},{"location":"Delta_Calibrate.html#basic-delta-calibration","title":"Basic delta calibration","text":"

    Kalico 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\nDELTA_CALIBRATE METHOD=manual\n

    After probing the seven points new delta parameters will be calculated. Save and apply these parameters by running:

    SAVE_CONFIG\n

    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.

    "},{"location":"Delta_Calibrate.html#enhanced-delta-calibration","title":"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 Kalico with a comma separated list of floating point numbers:

    DELTA_ANALYZE CENTER_DISTS=<a_dist>,<far_c_dist>,<b_dist>,<far_a_dist>,<c_dist>,<far_b_dist>\n

    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 Kalico:

    DELTA_ANALYZE OUTER_DISTS=<a_to_far_c>,<far_c_to_b>,<b_to_far_a>,<far_a_to_c>,<c_to_far_b>,<far_b_to_a>\n

    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 Kalico:

    DELTA_ANALYZE CENTER_PILLAR_WIDTHS=<a>,<b>,<c>\n

    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 Kalico:

    DELTA_ANALYZE OUTER_PILLAR_WIDTHS=<a>,<far_c>,<b>,<far_a>,<c>,<far_b>\n

    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\n

    (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\n

    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\n

    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.

    "},{"location":"Delta_Calibrate.html#additional-notes","title":"Additional notes","text":" "},{"location":"Delta_Calibrate.html#using-bed-mesh-on-a-delta","title":"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.

    "},{"location":"Dockable_Probe.html","title":"Dockable Probe","text":"

    Dockable probes are typically microswitches mounted to a printed body that attaches to the toolhead through some means of mechanical coupling. This coupling is commonly done with magnets though there is support for a variety of designs including servo and stepper actuated couplings.

    "},{"location":"Dockable_Probe.html#basic-configuration","title":"Basic Configuration","text":"

    To use a dockable probe the following options are required at a minimum. Some users may be transitioning from a macro based set of commands and many of the options for the [probe] config section are the same. The [dockable_probe] module is first and foremost a [probe] but with additional functionality. Most of the options that can be specified for [probe] are valid for [dockable_probe].

    [dockable_probe]\npin:\nz_offset:\nsample_retract_dist:\napproach_position:\ndock_position:\ndetach_position:\n(check_open_attach: OR probe_sense_pin:) AND/OR dock_sense_pin:\n
    "},{"location":"Dockable_Probe.html#attaching-and-detaching-positions","title":"Attaching and Detaching Positions","text":" Command Module restore_th=True restore_th=False notes ATTACH_PROBE dockable_probe.py True False Z_TILT_ADJUST probe.py True False QUAD_GANTRY_LEVEL probe.py True False PROBE probe.py True True PROBE_ACCURACY probe.py True True AXIS_TWIST_COMPENSATION probe.py True True CALIBRATE_Z z_calibration.py True False G28 Z probe.py True True only for z_virtual_endstop"},{"location":"Dockable_Probe.html#position-examples","title":"Position Examples","text":"

    Probe mounted on frame at back of print bed at a fixed Z position. To attach the probe, the toolhead will move back and then forward. To detach, the toolhead will move back, and then to the side.

    +--------+\n|   p>   |\n|   ^    |\n|        |\n+--------+\n
    approach_position: 150, 300, 5\ndock_position: 150, 330, 5\ndetach_position: 170, 330\n

    Probe mounted at side of moving gantry with fixed bed. Here the probe is attachable regardless of the Z position. To attach the probe, the toolhead will move to the side and back. To detach the toolhead will move to the side and then forward.

    +--------+\n|        |\n| p<     |\n| v      |\n+--------+\n
    approach_position: 50, 150\ndock_position: 10, 150\ndetach_position: 10, 130\n

    Probe mounted at side of fixed gantry with bed moving on Z. Probe is attachable regardless of Z but force Z hop for safety. The toolhead movement is the same as above.

    +--------+\n|        |\n| p<     |\n| v      |\n+--------+\n
    approach_position: 50, 150\ndock_position: 10, 150\ndetach_position: 10, 130\nz_hop: 15\n

    Euclid style probe that requires the attach and detach movements to happen in opposite order. Attach: approach, move to dock, extract. Detach: move to extract position, move to dock, move to approach position. The approach and detach positions are the same, as are the extract and insert positions.

    Attach:\n+--------+\n|        |\n| p<     |\n| v      |\n+--------+\nDetach:\n+--------+\n|        |\n| p>     |\n| ^      |\n+--------+\n
    approach_position: 50, 150\ndock_position: 10, 150\nextract_position: 10, 130\ndetach_position: 50, 150\nz_hop: 15\n
    "},{"location":"Dockable_Probe.html#homing","title":"Homing","text":"

    No configuration specific to the dockable probe is required. However, when using the probe as a virtual endstop, it's required to use [safe_z_home] or [homing_override].

    "},{"location":"Dockable_Probe.html#examples-for-probe-as-virtual-endstop","title":"Examples for probe as virtual endstop","text":"
    [homing_override]\naxes: xyz\nset_position_z: 0\ngcode:\n\n  G90\n  {% set home_all = 'X' not in params and 'Y' not in params and 'Z' not in params %}\n\n  {% if home_all or 'X' in params %}\n    G0 Z10\n    G28 X\n  {% endif %}\n\n  {% if home_all or 'Y' in params %}\n    G0 Z10\n    G28 Y\n  {% endif %}\n\n  {% if home_all or 'Z' in params %}\n    ATTACH_PROBE\n    MOVE_AVOIDING_DOCK X=150 Y=150 SPEED=300\n    # Probe is already attached, no need to make a return trip to the dock.\n    G28 Z  \n  {% endif %}\n
    [safe_z_home]\nhome_xy_position: 150,150\nz_hop: 10\n
    "},{"location":"Dockable_Probe.html#homing-override","title":"Homing override","text":""},{"location":"Dockable_Probe.html#safe_z_home","title":"safe_z_home","text":"While homing Z with safe_z_home, the toolhead will move to home_xy_position then will move to the dock and return back to home_xy_position."},{"location":"Dockable_Probe.html#probe-attachment-verification","title":"Probe Attachment Verification","text":"

    Given the nature of this type of probe, it is necessary to verify whether or not it has successfully attached prior to attempting a probing move. Several methods can be used to verify probe attachment states.

    "},{"location":"Dockable_Probe.html#tool-velocities","title":"Tool Velocities","text":" "},{"location":"Dockable_Probe.html#safe-dock-area","title":"Safe dock area","text":"

    A safe dock area is defined to avoid collision with the dock during probe attachment/detachment moves. see MOVE_AVOIDING_DOCK.

    "},{"location":"Dockable_Probe.html#move_avoiding_dock-description","title":"MOVE_AVOIDING_DOCK description","text":"

    The strategy described below is used by the attach and detach commands to avoid dock collision.

    Note

    The default safe_position is approach_position. To help determine the avoiding path and prevent moving out of range, it should be configured as a point next to the safe area, farthest from the \"move out of range\" zone.

    Several cases are illustrated:

    1. Moving from A to B: The requested trajectory passes over the safe dock area, so the calculated trajectory passes around the dock area, close to the safe position.
    2. Moving from A' to B: The toolhead leaves the safe dock area by the shortest path and reaches B as before.
    3. Moving from A to B': Since B' is in the safe area, the toolhead stops at B\".
    4. Moving from A' to B': The toolhead leaves the safe dock area by the shortest path.
    "},{"location":"Dockable_Probe.html#dockable-probe-gcodes","title":"Dockable Probe Gcodes","text":""},{"location":"Dockable_Probe.html#general","title":"General","text":"

    ATTACH_PROBE

    This command will move the toolhead to the dock, attach the probe, and return it to its previous position. If the probe is already attached, the command does nothing.

    This command will call MOVE_TO_APPROACH_PROBE, MOVE_TO_DOCK_PROBE, and MOVE_TO_EXTRACT_PROBE.

    DETACH_PROBE

    This command will move the toolhead to the dock, detach the probe, and return it to its previous position. If the probe is already detached, the command will do nothing.

    This command will call MOVE_TO_APPROACH_PROBE, MOVE_TO_DOCK_PROBE, and MOVE_TO_DETACH_PROBE.

    "},{"location":"Dockable_Probe.html#individual-movements","title":"Individual Movements","text":"

    These commands are useful during setup to prevent the full attach/detach sequence from crashing into the bed or damaging the probe/dock.

    If your probe has special setup/teardown steps (e.g. moving a servo), accommodating that could be accomplished by overriding these gcodes.

    MOVE_TO_APPROACH_PROBE

    This command will move the toolhead to the approach_position. It can be overridden to move a servo if that's required for attaching your probe.

    MOVE_TO_DOCK_PROBE

    This command will move the toolhead to the dock_position.

    MOVE_TO_EXTRACT_PROBE

    This command will move the toolhead to the extract_position.

    MOVE_TO_INSERT_PROBE

    This command will move the toolhead to the insert_position.

    MOVE_TO_DETACH_PROBE

    This command will move the toolhead to the detach_position. It can be overridden to move a servo if that's required for detaching your probe.

    MOVE_AVOIDING_DOCK [X=<value>] [Y=<value>] [SPEED=<value>]

    This command will move the toolhead to the absolute coordinates, avoiding the safe dock area.

    "},{"location":"Dockable_Probe.html#status","title":"Status","text":"

    QUERY_DOCKABLE_PROBE

    Responds in the gcode terminal with the current probe status. Valid states are UNKNOWN, ATTACHED, and DOCKED. This is useful during setup to confirm probe configuration is working as intended.

    SET_DOCKABLE_PROBE AUTO_ATTACH_DETACH=0|1

    Enable/Disable the automatic attaching/detaching of the probe during actions that require the probe.

    This command can be helpful in print-start macros where multiple actions will be performed with the probe and there's no need to detach the probe. For example:

    SET_DOCKABLE_PROBE AUTO_ATTACH_DETACH=0\nG28\nATTACH_PROBE                             # Explicitly attach the probe\nQUAD_GANTRY_LEVEL                        # Tram the gantry parallel to the bed\nBED_MESH_CALIBRATE                       # Create a bed mesh\nDETACH_PROBE                             # Manually detach the probe\nSET_DOCKABLE_PROBE AUTO_ATTACH_DETACH=1  # Make sure the probe is attached in future\n
    "},{"location":"Dockable_Probe.html#typical-probe-execution-flow","title":"Typical probe execution flow","text":""},{"location":"Dockable_Probe.html#probing-is-started","title":"Probing is Started:","text":" "},{"location":"Dockable_Probe.html#probing-is-finished","title":"Probing is Finished:","text":" "},{"location":"Endstop_Phase.html","title":"Endstop phase","text":"

    This document describes Kalico'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. Kalico'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 Kalico 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.)

    "},{"location":"Endstop_Phase.html#calibrating-endstop-phases","title":"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]\n

    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, Kalico 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\n

    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\n
    "},{"location":"Endstop_Phase.html#additional-notes","title":"Additional notes","text":" "},{"location":"Example_Configs.html","title":"Example configurations","text":"

    This document contains guidelines for contributing an example Kalico configuration to the Kalico 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.

    "},{"location":"Example_Configs.html#guidelines","title":"Guidelines","text":"
    1. Select the appropriate config filename prefix:
      1. The printer prefix is used for stock printers sold by a mainstream manufacturer.
      2. The generic prefix is used for a 3d printer board that may be used in many different types of printers.
      3. 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.
      4. The sample prefix is used for config \"snippets\" that one may copy-and-paste into the main config file.
      5. 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.
    2. 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.
    3. Do not use spaces or special characters in the config filename. The filename should contain only characters A-Z, a-z, 0-9, -, and ..
    4. Kalico 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.
    5. The example configuration should be for the \"stock\" configuration of the printer. (There are too many \"customized\" configurations to track in the main Kalico 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.
    6. Only specify those devices present on the given printer or board. Do not specify settings specific to your particular setup.
      1. 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.
      2. 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.
      3. 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.
      4. 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.
    7. Where possible, it is best to use the same wording, phrasing, indentation, and section ordering as the existing config files.
      1. 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\".
      2. 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.)
      3. 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.
      4. Use field: value syntax instead of field=value.
      5. 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.
      6. 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.
      7. Where possible, lines should not exceed 80 columns.
      8. 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.
    8. Do not use any deprecated features in the example config file.
    9. 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.
    10. All known boards that Kalico 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.

    "},{"location":"Exclude_Object.html","title":"Exclude Objects","text":"

    The [exclude_object] module allows Kalico 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 Kalico 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.

    "},{"location":"Exclude_Object.html#workflow-overview","title":"Workflow Overview","text":"

    A typical workflow for printing a file might look like this:

    1. 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.
    2. When printing starts, Kalico will reset the [exclude_object] status.
    3. When Kalico processes the EXCLUDE_OBJECT_DEFINE block, it will update the status with the known objects and pass it on to clients.
    4. The client may use that information to present a UI to the user so that progress can be tracked. Kalico will update the status to include the currently printing object which the client can use for display purposes.
    5. If the user requests that an object be cancelled, the client will issue an EXCLUDE_OBJECT NAME=<name> command to Kalico.
    6. When Kalico process the command, it will add the object to the list of excluded objects and update the status for the client.
    7. The client will receive the updated status from Kalico and can use that information to reflect the object's status in the UI.
    8. When printing finishes, the [exclude_object] status will continue to be available until another action resets it.
    "},{"location":"Exclude_Object.html#the-gcode-file","title":"The GCode File","text":"

    The specialized gcode processing needed to support excluding objects does not fit into Kalico's core design goals. Therefore, this module requires that the file is processed before being sent to Kalico 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 Kalico. A reference post-processing script is available both as an executable and a python library, see cancelobject-preprocessor.

    "},{"location":"Exclude_Object.html#object-definitions","title":"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

    "},{"location":"Exclude_Object.html#status-information","title":"Status Information","text":"

    The state of this module is provided to clients by the exclude_object status.

    The status is reset when:

    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 Kalico 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 Kalico looks ahead to process upcoming gcode, there may be a delay between when the command is issued and when the status is updated.

    "},{"location":"FAQ.html","title":"Frequently Asked Questions","text":""},{"location":"FAQ.html#how-can-i-donate-to-the-project","title":"How can I donate to the project?","text":"

    Thank you for your support. See the Sponsors page for information.

    "},{"location":"FAQ.html#how-do-i-calculate-the-rotation_distance-config-parameter","title":"How do I calculate the rotation_distance config parameter?","text":"

    See the rotation distance document.

    "},{"location":"FAQ.html#wheres-my-serial-port","title":"Where's 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\n

    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\nmake flash FLASH_DEVICE=/dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0\nsudo service klipper start\n

    and the updated config might look like:

    [mcu]\nserial: /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0\n

    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.

    "},{"location":"FAQ.html#when-the-micro-controller-restarts-the-device-changes-to-devttyusb1","title":"When the micro-controller restarts the device changes to /dev/ttyUSB1","text":"

    Follow the directions in the \"Where's my serial port?\" section to prevent this from occurring.

    "},{"location":"FAQ.html#the-make-flash-command-doesnt-work","title":"The \"make flash\" command doesn't 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 Kalico 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.

    "},{"location":"FAQ.html#how-do-i-change-the-serial-baud-rate","title":"How do I change the serial baud rate?","text":"

    The recommended baud rate for Kalico is 250000. This baud rate works well on all micro-controller boards that Kalico 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 Kalico printer.cfg file will also need to be updated to match that baud rate (see the config reference for details). For example:

    [mcu]\nbaud: 250000\n

    The baud rate shown on the OctoPrint web page has no impact on the internal Kalico micro-controller baud rate. Always set the OctoPrint baud rate to 250000 when using Kalico.

    The Kalico 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.

    "},{"location":"FAQ.html#can-i-run-kalico-on-something-other-than-a-raspberry-pi-3","title":"Can I run Kalico on something other than a Raspberry Pi 3?","text":"

    The recommended hardware is a Raspberry Pi 2, Raspberry Pi 3, or Raspberry Pi 4.

    Kalico will run on a Raspberry Pi 1 and on the Raspberry Pi Zero, but these boards don't have enough processing power to run OctoPrint well. It is common for print stalls to occur on these slower machines when printing directly from OctoPrint. (The printer may move faster than OctoPrint can send movement commands.) If you wish to run on one one of these slower boards anyway, consider using the \"virtual_sdcard\" feature when printing (see config reference for details).

    For running on the Beaglebone, see the Beaglebone specific installation instructions.

    Kalico has been run on other machines. The Kalico 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 Kalico 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 Kalico host software on a shared general-purpose desktop or server class machine, then note that Kalico 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 Kalico 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 Kalico to report seemingly random \"Lost communication with MCU\" errors.) If you install Kalico on one of these distributions you may need to disable that package.

    "},{"location":"FAQ.html#can-i-run-multiple-instances-of-kalico-on-the-same-host-machine","title":"Can I run multiple instances of Kalico on the same host machine?","text":"

    It is possible to run multiple instances of the Kalico host software, but doing so requires Linux admin knowledge. The Kalico 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\n

    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\n

    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.

    "},{"location":"FAQ.html#do-i-have-to-use-octoprint","title":"Do I have to use OctoPrint?","text":"

    The Kalico software is not dependent on OctoPrint. It is possible to use alternative software to send commands to Kalico, but doing so requires Linux admin knowledge.

    Kalico 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 Kalico as long as it can be configured to use \"/tmp/printer\" for the printer serial port.

    "},{"location":"FAQ.html#why-cant-i-move-the-stepper-before-homing-the-printer","title":"Why can't 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.

    "},{"location":"FAQ.html#why-is-the-z-position_endstop-set-to-05-in-the-default-configs","title":"Why is the Z position_endstop set to 0.5 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.

    "},{"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","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","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. Kalico 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.

    "},{"location":"FAQ.html#my-tmc-motor-driver-turns-off-in-the-middle-of-a-print","title":"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 Kalico. A workaround for a TMC2208 \"stealthchop\" driver problem was added to Kalico in mid-March of 2020.

    "},{"location":"FAQ.html#i-keep-getting-random-lost-communication-with-mcu-errors","title":"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:

    "},{"location":"FAQ.html#my-raspberry-pi-keeps-rebooting-during-prints","title":"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.

    "},{"location":"FAQ.html#when-i-set-restart_methodcommand-my-avr-device-just-hangs-on-a-restart","title":"When I set restart_method=command 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.

    "},{"location":"FAQ.html#will-the-heaters-be-left-on-if-the-raspberry-pi-crashes","title":"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.

    "},{"location":"FAQ.html#how-do-i-convert-a-marlin-pin-number-to-a-kalico-pin-name","title":"How do I convert a Marlin pin number to a Kalico 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 Kalico alias ar23) and the prefix \"analog\" instead of \"A\" (eg, Arduino pin A14 is Kalico alias analog14).

    Long answer: Kalico 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 Kalico code uses the standard pin names defined by the micro-controller.

    "},{"location":"FAQ.html#do-i-have-to-wire-my-device-to-a-specific-type-of-micro-controller-pin","title":"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 Kalico to use a pin that is not analog capable, Kalico will report a \"Not a valid ADC pin\" error.

    PWM pins (or Timer pins): Kalico 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, Kalico will report a \"Not a valid PWM pin\" error).

    IRQ pins (or Interrupt pins): Kalico 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.

    "},{"location":"FAQ.html#how-do-i-cancel-an-m109m190-wait-for-temperature-request","title":"How do I cancel an M109/M190 \"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 Kalico to enter into a \"shutdown\" state, and it will cause OctoPrint to disconnect from Kalico. 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 Kalico error state. After completing this sequence, the previous heating request will be canceled and a new print may be started.

    "},{"location":"FAQ.html#can-i-find-out-whether-the-printer-has-lost-steps","title":"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.)

    "},{"location":"FAQ.html#why-does-kalico-report-errors-i-lost-my-print","title":"Why does Kalico 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: Kalico 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 Kalico 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 Kalico pause the print instead? Report a warning instead? Check for errors before the print? Ignore errors in user typed commands? etc? Currently Kalico 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).

    "},{"location":"FAQ.html#how-do-i-upgrade-to-the-latest-software","title":"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\ngit pull\n~/klipper/scripts/install-octopi.sh\n

    Then one can recompile and flash the micro-controller code. For example:

    make menuconfig\nmake clean\nmake\n\nsudo service klipper stop\nmake flash FLASH_DEVICE=/dev/ttyACM0\nsudo service klipper start\n

    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\ngit pull\nsudo service klipper restart\n

    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.

    "},{"location":"FAQ.html#how-do-i-uninstall-kalico","title":"How do I uninstall Kalico?","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\nrm -rf ~/klippy-env ~/klipper\n
    "},{"location":"Features.html","title":"Features","text":"

    Kalico has several compelling features:

    "},{"location":"Features.html#additional-features","title":"Additional features","text":"

    Kalico supports many standard 3d printer features:

    To get started with Kalico, read the installation guide.

    "},{"location":"Features.html#step-benchmarks","title":"Step Benchmarks","text":"

    Below are the results of stepper performance tests. The numbers shown represent total number of steps per second on the micro-controller.

    Micro-controller 1 stepper active 3 steppers active 16Mhz AVR 157K 99K 20Mhz AVR 196K 123K SAMD21 686K 471K STM32F042 814K 578K Beaglebone PRU 866K 708K STM32G0B1 1103K 790K STM32F103 1180K 818K SAM3X8E 1273K 981K SAM4S8C 1690K 1385K LPC1768 1923K 1351K LPC1769 2353K 1622K RP2040 2400K 1636K SAM4E8E 2500K 1674K SAMD51 3077K 1885K AR100 3529K 2507K STM32F407 3652K 2459K STM32F446 3913K 2634K RP2350 4167K 2663K SAME70 6667K 4737K STM32H743 9091K 6061K

    If unsure of the micro-controller on a particular board, find the appropriate config file, and look for the micro-controller name in the comments at the top of that file.

    Further details on the benchmarks are available in the Benchmarks document.

    "},{"location":"G-Code_Shell_Command.html","title":"G-Code Shell Command Extension","text":""},{"location":"G-Code_Shell_Command.html#creator-of-this-extension-is-arksine","title":"Creator of this extension is Arksine.","text":"

    This is a brief explanation of how to use the shell command extension for Kalico, which you can install with KIAUH.

    After installing the extension you can execute linux commands or even scripts from within Kalico with custom commands defined in your printer.cfg.

    "},{"location":"G-Code_Shell_Command.html#how-to-configure-a-shell-command","title":"How to configure a shell command:","text":"
    # Runs a linux command or script from within Kalico.  Note that sudo commands\n# that require password authentication are disallowed. All executable scripts\n# should include a shebang.\n# [gcode_shell_command my_shell_cmd]\n#command:\n#  The linux shell command/script to be executed.  This parameter must be\n#  provided\n#timeout: 2.\n#  The timeout in seconds until the command is forcably terminated.  Default\n#  is 2 seconds.\n#verbose: True\n#  If enabled, the command's output will be forwarded to the terminal.  Its\n#  recommended to set this to false for commands that my run in quick\n#  succession.  Default is True.\n

    Once you have set up a shell command with the given parameters from above in your printer.cfg you can run the command as follows: RUN_SHELL_COMMAND CMD=name

    Example:

    [gcode_shell_command hello_world]\ncommand: echo hello world\ntimeout: 2.\nverbose: True\n

    Execute with: RUN_SHELL_COMMAND CMD=hello_world

    "},{"location":"G-Code_Shell_Command.html#passing-parameters","title":"Passing parameters:","text":"

    As of commit f231fa9 it is also possible to pass optional parameters to a gcode_shell_command. The following short example shows storing the extruder temperature into a variable, passing that value with a parameter to a gcode_shell_command, which then, once the gcode_macro runs and the gcode_shell_command gets called, executes the script.sh. The script then echoes a message to the console (if verbose: True) and writes the value of the parameter into a textfile called test.txt located in the home directory.

    Content of the gcode_shell_command and the gcode_macro:

    [gcode_shell_command print_to_file]\ncommand: sh /home/pi/printer_data/config/script.sh\ntimeout: 30.\nverbose: True\n\n[gcode_macro GET_TEMP]\ngcode:\n    {% set temp = printer.extruder.temperature %}\n    { action_respond_info(\"%s\" % (temp)) }\n    RUN_SHELL_COMMAND CMD=print_to_file PARAMS={temp}\n

    Content of script.sh:

    #!/bin/sh\n\necho \"temp is: $1\"\necho \"$1\" >> \"${HOME}/test.txt\"\n
    "},{"location":"G-Code_Shell_Command.html#warning","title":"Warning","text":"

    This extension may have a high potential for abuse if not used carefully! Also, depending on the command you execute, high system loads may occur and can cause system instabilities. Use this extension at your own risk and only if you know what you are doing!

    "},{"location":"G-Codes.html","title":"G-Codes","text":"

    This document describes the commands that Kalico supports. These are commands that one may enter into the OctoPrint terminal tab.

    Sections and commands marked with an \u26a0\ufe0f show commands that are new or behave differently from Klipper

    "},{"location":"G-Codes.html#g-code-commands","title":"G-Code commands","text":"

    Kalico supports the following standard G-Code commands:

    For further details on the above commands see the RepRap G-Code documentation.

    Kalico'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, Kalico 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 Kalico 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.

    "},{"location":"G-Codes.html#additional-commands","title":"Additional Commands","text":"

    Kalico 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 Kalico module name, which generally follows the section names specified in the printer configuration file. Note that some modules are automatically loaded.

    "},{"location":"G-Codes.html#adxl345","title":"[adxl345]","text":"

    The following commands are available when an adxl345 config section is enabled.

    "},{"location":"G-Codes.html#accelerometer_measure","title":"ACCELEROMETER_MEASURE","text":"

    ACCELEROMETER_MEASURE [CHIP=<config_name>] [NAME=<value>]: Starts accelerometer measurements at the requested number of samples per second. If CHIP is not specified it defaults to \"adxl345\". The command works in a start-stop mode: when executed for the first time, it starts the measurements, next execution stops them. The results of measurements are written to a file named /tmp/adxl345-<chip>-<name>.csv where <chip> is the name of the accelerometer chip (my_chip_name from [adxl345 my_chip_name]) and <name> is the optional NAME parameter. If NAME is not specified it defaults to the current time in \"YYYYMMDD_HHMMSS\" format. If the accelerometer does not have a name in its config section (simply [adxl345]) then <chip> part of the name is not generated.

    "},{"location":"G-Codes.html#accelerometer_query","title":"ACCELEROMETER_QUERY","text":"

    ACCELEROMETER_QUERY [CHIP=<config_name>] [RATE=<value>] [SAMPLES=<value>] [RETURN=<value>]: queries accelerometer for the current value. If CHIP is not specified it defaults to \"adxl345\". If RATE is not specified, the default value is used. This command is useful to test the connection to the ADXL345 accelerometer: one of the returned values should be a free-fall acceleration (+/- some noise of the chip). The SAMPLES parameter can be set to sample multiple readings from the sensor. The readings will be averaged together. The default is to collect a single sample. The RETURN parameter can take on the values vector(the default) or tilt. In vector mode, the raw free-fall acceleration vector is returned. In tilt mode, X and Y angles of a plane perpendicular to the free-fall vector are calculated and displayed.

    "},{"location":"G-Codes.html#accelerometer_debug_read","title":"ACCELEROMETER_DEBUG_READ","text":"

    ACCELEROMETER_DEBUG_READ [CHIP=<config_name>] REG=<register>: queries ADXL345 register \"register\" (e.g. 44 or 0x2C). Can be useful for debugging purposes.

    "},{"location":"G-Codes.html#accelerometer_debug_write","title":"ACCELEROMETER_DEBUG_WRITE","text":"

    ACCELEROMETER_DEBUG_WRITE [CHIP=<config_name>] REG=<register> VAL=<value>: Writes raw \"value\" into a register \"register\". Both \"value\" and \"register\" can be a decimal or a hexadecimal integer. Use with care, and refer to ADXL345 data sheet for the reference.

    "},{"location":"G-Codes.html#angle","title":"[angle]","text":"

    The following commands are available when an angle config section is enabled.

    "},{"location":"G-Codes.html#angle_calibrate","title":"ANGLE_CALIBRATE","text":"

    ANGLE_CALIBRATE CHIP=<chip_name>: Perform angle calibration on the given sensor (there must be an [angle chip_name] config section that has specified a stepper parameter). IMPORTANT - this tool will command the stepper motor to move without checking the normal kinematic boundary limits. Ideally the motor should be disconnected from any printer carriage before performing calibration. If the stepper can not be disconnected from the printer, make sure the carriage is near the center of its rail before starting calibration. (The stepper motor may move forwards or backwards two full rotations during this test.) After completing this test use the SAVE_CONFIG command to save the calibration data to the config file. In order to use this tool the Python \"numpy\" package must be installed (see the measuring resonance document for more information).

    "},{"location":"G-Codes.html#angle_debug_read","title":"ANGLE_DEBUG_READ","text":"

    ANGLE_DEBUG_READ CHIP=<config_name> REG=<register>: Queries sensor register \"register\" (e.g. 44 or 0x2C). Can be useful for debugging purposes. This is only available for tle5012b chips.

    "},{"location":"G-Codes.html#angle_debug_write","title":"ANGLE_DEBUG_WRITE","text":"

    ANGLE_DEBUG_WRITE CHIP=<config_name> REG=<register> VAL=<value>: Writes raw \"value\" into register \"register\". Both \"value\" and \"register\" can be a decimal or a hexadecimal integer. Use with care, and refer to sensor data sheet for the reference. This is only available for tle5012b chips.

    "},{"location":"G-Codes.html#axis_twist_compensation","title":"[axis_twist_compensation]","text":"

    The following commands are available when the axis_twist_compensation config section is enabled.

    "},{"location":"G-Codes.html#axis_twist_compensation_calibrate","title":"AXIS_TWIST_COMPENSATION_CALIBRATE","text":"

    AXIS_TWIST_COMPENSATION_CALIBRATE [AXIS=<X|Y>] [SAMPLE_COUNT=<value>] [<probe_parameter>=<value>]:

    Calibrates axis twist compensation by specifying the target axis or enabling automatic calibration.

    "},{"location":"G-Codes.html#bed_mesh","title":"[bed_mesh]","text":"

    The following commands are available when the bed_mesh config section is enabled (also see the bed mesh guide).

    "},{"location":"G-Codes.html#bed_mesh_calibrate","title":"BED_MESH_CALIBRATE","text":"

    BED_MESH_CALIBRATE [PROFILE=<name>] [METHOD=manual] [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>] [<mesh_parameter>=<value>] [ADAPTIVE=1] [ADAPTIVE_MARGIN=<value>]: This command probes the bed using generated points specified by the parameters in the config. After probing, a mesh is generated and z-movement is adjusted according to the mesh. The mesh will be saved into a profile specified by the PROFILE parameter, or default if unspecified. See the PROBE command for details on the optional probe parameters. If METHOD=manual is specified then the manual probing tool is activated - see the MANUAL_PROBE command above for details on the additional commands available while this tool is active. The optional HORIZONTAL_MOVE_Z value overrides the horizontal_move_z option specified in the config file. If ADAPTIVE=1 is specified then the objects defined by the Gcode file being printed will be used to define the probed area. The optional ADAPTIVE_MARGIN value overrides the adaptive_margin option specified in the config file.

    "},{"location":"G-Codes.html#bed_mesh_output","title":"BED_MESH_OUTPUT","text":"

    BED_MESH_OUTPUT PGP=[<0:1>]: This command outputs the current probed z values and current mesh values to the terminal. If PGP=1 is specified the X, Y coordinates generated by bed_mesh, along with their associated indices, will be output to the terminal.

    "},{"location":"G-Codes.html#bed_mesh_map","title":"BED_MESH_MAP","text":"

    BED_MESH_MAP: Like to BED_MESH_OUTPUT, this command prints the current state of the mesh to the terminal. Instead of printing the values in a human readable format, the state is serialized in json format. This allows octoprint plugins to easily capture the data and generate height maps approximating the bed's surface.

    "},{"location":"G-Codes.html#bed_mesh_clear","title":"BED_MESH_CLEAR","text":"

    BED_MESH_CLEAR: This command clears the mesh and removes all z adjustment. It is recommended to put this in your end-gcode.

    "},{"location":"G-Codes.html#bed_mesh_profile","title":"BED_MESH_PROFILE","text":"

    BED_MESH_PROFILE LOAD=<name> SAVE=<name> REMOVE=<name>: This command provides profile management for mesh state. LOAD will restore the mesh state from the profile matching the supplied name. SAVE will save the current mesh state to a profile matching the supplied name. Remove will delete the profile matching the supplied name from persistent memory. Note that after SAVE or REMOVE operations have been run the SAVE_CONFIG gcode must be run to make the changes to persistent memory permanent.

    "},{"location":"G-Codes.html#bed_mesh_offset","title":"BED_MESH_OFFSET","text":"

    BED_MESH_OFFSET [X=<value>] [Y=<value>] [ZFADE=<value]: Applies X, Y, and/or ZFADE offsets to the mesh lookup. This is useful for printers with independent extruders, as an offset is necessary to produce correct Z adjustment after a tool change. Note that a ZFADE offset does not apply additional z-adjustment directly, it is used to correct the fade calculation when a gcode offset has been applied to the Z axis.

    "},{"location":"G-Codes.html#bed_screws","title":"[bed_screws]","text":"

    The following commands are available when the bed_screws config section is enabled (also see the manual level guide).

    "},{"location":"G-Codes.html#bed_screws_adjust","title":"BED_SCREWS_ADJUST","text":"

    BED_SCREWS_ADJUST: This command will invoke the bed screws adjustment tool. It will command the nozzle to different locations (as defined in the config file) and allow one to make adjustments to the bed screws so that the bed is a constant distance from the nozzle.

    "},{"location":"G-Codes.html#bed_tilt","title":"[bed_tilt]","text":"

    The following commands are available when the bed_tilt config section is enabled.

    "},{"location":"G-Codes.html#bed_tilt_calibrate","title":"BED_TILT_CALIBRATE","text":"

    BED_TILT_CALIBRATE [METHOD=manual] [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>]: This command will probe the points specified in the config and then recommend updated x and y tilt adjustments. See the PROBE command for details on the optional probe parameters. If METHOD=manual is specified then the manual probing tool is activated - see the MANUAL_PROBE command above for details on the additional commands available while this tool is active. The optional HORIZONTAL_MOVE_Z value overrides the horizontal_move_z option specified in the config file.

    "},{"location":"G-Codes.html#belay","title":"[belay]","text":"

    The following commands are available when a belay config section is enabled.

    "},{"location":"G-Codes.html#query_belay","title":"QUERY_BELAY","text":"

    QUERY_BELAY BELAY=<config_name>: Queries the state of the belay specified by BELAY.

    "},{"location":"G-Codes.html#belay_set_multiplier","title":"BELAY_SET_MULTIPLIER","text":"

    BELAY_SET_MULTIPLIER BELAY=<config_name> [HIGH=<multiplier_high>] [LOW=<multiplier_low>]: Sets the values of multiplier_high and/or multiplier_low for the belay specified by BELAY, overriding their values from the corresponding belay config section. Values set by this command will not persist across restarts.

    "},{"location":"G-Codes.html#belay_set_stepper","title":"BELAY_SET_STEPPER","text":"

    BELAY_SET_STEPPER BELAY=<config_name> STEPPER=<extruder_stepper_name>: Selects the extruder_stepper whose multiplier will be controlled by the belay specified by BELAY. The multiplier for the previous stepper will be reset back to 1 before switching to the new stepper. Stepper selections made by this command will not persist across restarts. This command is only available if extruder_type is set to 'extruder_stepper' in the corresponding belay config section.

    "},{"location":"G-Codes.html#bltouch","title":"[bltouch]","text":"

    The following command is available when a bltouch config section is enabled (also see the BL-Touch guide).

    "},{"location":"G-Codes.html#bltouch_debug","title":"BLTOUCH_DEBUG","text":"

    BLTOUCH_DEBUG COMMAND=<command>: This sends a command to the BLTouch. It may be useful for debugging. Available commands are: pin_down, touch_mode, pin_up, self_test, reset. A BL-Touch V3.0 or V3.1 may also support set_5V_output_mode, set_OD_output_mode, output_mode_store commands.

    "},{"location":"G-Codes.html#bltouch_store","title":"BLTOUCH_STORE","text":"

    BLTOUCH_STORE MODE=<output_mode>: This stores an output mode in the EEPROM of a BLTouch V3.1 Available output_modes are: 5V, OD

    "},{"location":"G-Codes.html#configfile","title":"[configfile]","text":"

    The configfile module is automatically loaded.

    "},{"location":"G-Codes.html#save_config","title":"SAVE_CONFIG","text":"

    SAVE_CONFIG [RESTART=0|1]: This command will overwrite the main printer config file and restart the host software. This command is used in conjunction with other calibration commands to store the results of calibration tests. If RESTART is set to 0, no restart will be performed !!USE WITH CAUTION!!.

    "},{"location":"G-Codes.html#delayed_gcode","title":"[delayed_gcode]","text":"

    The following command is enabled if a delayed_gcode config section has been enabled (also see the template guide).

    "},{"location":"G-Codes.html#update_delayed_gcode","title":"UPDATE_DELAYED_GCODE","text":"

    UPDATE_DELAYED_GCODE [ID=<name>] [DURATION=<seconds>]: Updates the delay duration for the identified [delayed_gcode] and starts the timer for gcode execution. A value of 0 will cancel a pending delayed gcode from executing.

    "},{"location":"G-Codes.html#delta_calibrate","title":"[delta_calibrate]","text":"

    The following commands are available when the [delta_calibrate] config section is enabled (also see the delta calibrate guide).

    "},{"location":"G-Codes.html#delta_calibrate_1","title":"DELTA_CALIBRATE","text":"

    DELTA_CALIBRATE [METHOD=manual] [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>]: This command will probe seven points on the bed and recommend updated endstop positions, tower angles, and radius. See the PROBE command for details on the optional probe parameters. If METHOD=manual is specified then the manual probing tool is activated - see the MANUAL_PROBE command above for details on the additional commands available while this tool is active. The optional HORIZONTAL_MOVE_Z value overrides the horizontal_move_z option specified in the config file.

    "},{"location":"G-Codes.html#delta_analyze","title":"DELTA_ANALYZE","text":"

    DELTA_ANALYZE: This command is used during enhanced delta calibration. See Delta Calibrate for details.

    "},{"location":"G-Codes.html#display","title":"[display]","text":"

    The following command is available when a display config section is enabled.

    "},{"location":"G-Codes.html#set_display_group","title":"SET_DISPLAY_GROUP","text":"

    SET_DISPLAY_GROUP [DISPLAY=<display>] GROUP=<group>: Set the active display group of an lcd display. This allows to define multiple display data groups in the config, e.g. [display_data <group> <elementname>] and switch between them using this extended gcode command. If DISPLAY is not specified it defaults to \"display\" (the primary display).

    "},{"location":"G-Codes.html#display_status","title":"[display_status]","text":"

    The display_status module is automatically loaded if a display config section is enabled. It provides the following standard G-Code commands:

    Also provided is the following extended G-Code command:

    "},{"location":"G-Codes.html#dockable_probe","title":"[dockable_probe]","text":"

    In addition to the normal commands available for a [probe], the following commands are available when a dockable_probe config section is enabled (also see the Dockable Probe guide):

    "},{"location":"G-Codes.html#dual_carriage","title":"[dual_carriage]","text":"

    The following command is available when the dual_carriage config section is enabled.

    "},{"location":"G-Codes.html#set_dual_carriage","title":"SET_DUAL_CARRIAGE","text":"

    SET_DUAL_CARRIAGE CARRIAGE=[0|1] [MODE=[PRIMARY|COPY|MIRROR]]: This command will change the mode of the specified carriage. If no MODE is provided it defaults to PRIMARY. Setting the mode to PRIMARY deactivates the other carriage and makes the specified carriage execute subsequent G-Code commands as-is. COPY and MIRROR modes are supported only for CARRIAGE=1. When set to either of these modes, carriage 1 will then track the subsequent moves of the carriage 0 and either copy relative movements of it (in COPY mode) or execute them in the opposite (mirror) direction (in MIRROR mode).

    "},{"location":"G-Codes.html#save_dual_carriage_state","title":"SAVE_DUAL_CARRIAGE_STATE","text":"

    SAVE_DUAL_CARRIAGE_STATE [NAME=<state_name>]: Save the current positions of the dual carriages and their modes. Saving and restoring DUAL_CARRIAGE state can be useful in scripts and macros, as well as in homing routine overrides. If NAME is provided it allows one to name the saved state to the given string. If NAME is not provided it defaults to \"default\".

    "},{"location":"G-Codes.html#restore_dual_carriage_state","title":"RESTORE_DUAL_CARRIAGE_STATE","text":"

    RESTORE_DUAL_CARRIAGE_STATE [NAME=<state_name>] [MOVE=[0|1] [MOVE_SPEED=<speed>]]: Restore the previously saved positions of the dual carriages and their modes, unless \"MOVE=0\" is specified, in which case only the saved modes will be restored, but not the positions of the carriages. If positions are being restored and \"MOVE_SPEED\" is specified, then the toolhead moves will be performed with the given speed (in mm/s); otherwise the toolhead move will use the rail homing speed. Note that the carriages restore their positions only over their own axis, which may be necessary to correctly restore COPY and MIRROR mode of the dual carraige.

    "},{"location":"G-Codes.html#endstop_phase","title":"[endstop_phase]","text":"

    The following commands are available when an endstop_phase config section is enabled (also see the endstop phase guide).

    "},{"location":"G-Codes.html#endstop_phase_calibrate","title":"ENDSTOP_PHASE_CALIBRATE","text":"

    ENDSTOP_PHASE_CALIBRATE [STEPPER=<config_name>]: If no STEPPER parameter is provided then this command will reports statistics on endstop stepper phases during past homing operations. When a STEPPER parameter is provided it arranges for the given endstop phase setting to be written to the config file (in conjunction with the SAVE_CONFIG command).

    "},{"location":"G-Codes.html#exclude_object","title":"[exclude_object]","text":"

    The following commands are available when an exclude_object config section is enabled (also see the exclude object guide):

    "},{"location":"G-Codes.html#exclude_object_1","title":"EXCLUDE_OBJECT","text":"

    EXCLUDE_OBJECT [NAME=object_name] [CURRENT=1] [RESET=1]: With no parameters, this will return a list of all currently excluded objects.

    When the NAME parameter is given, the named object will be excluded from printing.

    When the CURRENT parameter is given, the current object will be excluded from printing.

    When the RESET parameter is given, the list of excluded objects will be cleared. Additionally including NAME will only reset the named object. This can cause print failures, if layers were already skipped.

    "},{"location":"G-Codes.html#exclude_object_define","title":"EXCLUDE_OBJECT_DEFINE","text":"

    EXCLUDE_OBJECT_DEFINE [NAME=object_name [CENTER=X,Y] [POLYGON=[[x,y],...]] [RESET=1] [JSON=1]: Provides a summary of an object in the file.

    With no parameters provided, this will list the defined objects known to Kalico. Returns a list of strings, unless the JSON parameter is given, when it will return object details in json format.

    When the NAME parameter is included, this defines an object to be excluded.

    When the RESET parameter is provided, all defined objects will be cleared, and the [exclude_object] module will be reset.

    "},{"location":"G-Codes.html#exclude_object_start","title":"EXCLUDE_OBJECT_START","text":"

    EXCLUDE_OBJECT_START NAME=object_name: This command takes a NAME parameter and denotes the start of the gcode for an object on the current layer.

    "},{"location":"G-Codes.html#exclude_object_end","title":"EXCLUDE_OBJECT_END","text":"

    EXCLUDE_OBJECT_END [NAME=object_name]: Denotes the end of the object's gcode for the layer. It is paired with EXCLUDE_OBJECT_START. A NAME parameter is optional, and will only warn when the provided name does not match the current object.

    "},{"location":"G-Codes.html#extruder","title":"[extruder]","text":"

    The following commands are available if an extruder config section is enabled:

    "},{"location":"G-Codes.html#activate_extruder","title":"ACTIVATE_EXTRUDER","text":"

    ACTIVATE_EXTRUDER EXTRUDER=<config_name>: In a printer with multiple extruder config sections, this command changes the active hotend.

    "},{"location":"G-Codes.html#set_pressure_advance","title":"SET_PRESSURE_ADVANCE","text":"

    SET_PRESSURE_ADVANCE [EXTRUDER=<config_name>] [ADVANCE=<pressure_advance>] [SMOOTH_TIME=<pressure_advance_smooth_time>]: Set pressure advance parameters of an extruder stepper (as defined in an extruder or extruder_stepper config section). If EXTRUDER is not specified, it defaults to the stepper defined in the active hotend.

    "},{"location":"G-Codes.html#set_extruder_rotation_distance","title":"SET_EXTRUDER_ROTATION_DISTANCE","text":"

    SET_EXTRUDER_ROTATION_DISTANCE EXTRUDER=<config_name> [DISTANCE=<distance>]: Set a new value for the provided extruder stepper's \"rotation distance\" (as defined in an extruder or extruder_stepper config section). If the rotation distance is a negative number then the stepper motion will be inverted (relative to the stepper direction specified in the config file). Changed settings are not retained on Kalico reset. Use with caution as small changes can result in excessive pressure between extruder and hotend. Do proper calibration with filament before use. If 'DISTANCE' value is not provided then this command will return the current rotation distance.

    "},{"location":"G-Codes.html#sync_extruder_motion","title":"SYNC_EXTRUDER_MOTION","text":"

    SYNC_EXTRUDER_MOTION EXTRUDER=<name> MOTION_QUEUE=<name>: This command will cause the stepper specified by EXTRUDER (as defined in an extruder or extruder_stepper config section) to become synchronized to the movement of an extruder specified by MOTION_QUEUE (as defined in an extruder config section). If MOTION_QUEUE is an empty string then the stepper will be desynchronized from all extruder movement.

    "},{"location":"G-Codes.html#mixing_extruder","title":"[mixing_extruder]","text":"

    The following commands are available when a mixingextruder config section is enabled:

    "},{"location":"G-Codes.html#set_mixing_extruder","title":"SET_MIXING_EXTRUDER","text":"

    SET_MIXING_EXTRUDER [FACTORS=<factor1>[:<factor2>[:<factor3>...]]] [ENABLE=[0|1]]: This command activates the specified mixing extruder. Subsequent G1 commands use the mixing defined by the factors. FACTORS defines the mixing by providing a number of positive values. The number of values should correspond to the number of steppers defined in the configuration. The values are normalized internally to add up to 1 and the extrusion of the corresponding stepper is multiplied by that value. If ENABLED is omitted the current mixing state is not changed. If neither FACTORS nor ENABLE is provided the current mixing status is displayed.

    "},{"location":"G-Codes.html#set_mixing_extruder_gradient","title":"SET_MIXING_EXTRUDER_GRADIENT","text":"

    SET_MIXING_EXTRUDER_GRADIENT [START_FACTORS=<s1>[,<s2>[,<s3>...]] END_FACTORS=<e1>[,<e2>[,<e3>...]] START_HEIGHT=<start> END_HEIGHT=<end>] [ENABLE=[0|1|RESET]] [METHOD=[linear|spherical] [VECTOR=,,]]`: When START_FACTORS, END_FACTORS, START_HEIGHT, END_HEIGHT is provided then an gradient configuration is added. The START_FACTORS define the mixing below and up to the START_HEIGHT. The END_FACTORS respectively the mixing from the END_HEIGHT onward. The mixing in between is linearly interpolated. When ENABLE is either 0 or 1 or METHOD is specified the mixing gradient is turned off or on and the gradient method (METHOD) which should be used is selected. All previously added gradients are used when enabled. The optional VECTOR configures a parameter depending on the METHOD: eg. for linear VECTOR defines the up direction and for spherical it defines the origin of the spheres. When ENABLE is RESET all configured gradients are removed and the gradient handling is disabled. When no parameter is provided the current mixing gradient status is displayed."},{"location":"G-Codes.html#heated_fan","title":"[heated_fan]","text":"

    The following command is available when a heated_fan is enabled.

    "},{"location":"G-Codes.html#set_heated_fan_target","title":"SET_HEATED_FAN_TARGET","text":"

    SET_HEATED_FAN_TARGET TARGET=<temperature>: Override the heater_temp setting in the heated_fan config section until Kalico is restarted. Useful for slicers to set different heated fan temperatures at different layers.

    "},{"location":"G-Codes.html#fan_generic","title":"[fan_generic]","text":"

    The following command is available when a fan_generic config section is enabled.

    "},{"location":"G-Codes.html#set_fan_speed","title":"SET_FAN_SPEED","text":"

    SET_FAN_SPEED FAN=config_name SPEED=<speed> This command sets the speed of a fan. \"speed\" must be between 0.0 and 1.0.

    "},{"location":"G-Codes.html#filament_switch_sensor","title":"[filament_switch_sensor]","text":"

    The following command is available when a filament_switch_sensor or filament_motion_sensor config section is enabled.

    "},{"location":"G-Codes.html#query_filament_sensor","title":"QUERY_FILAMENT_SENSOR","text":"

    QUERY_FILAMENT_SENSOR SENSOR=<sensor_name>: Queries the current status of the filament sensor. The data displayed on the terminal will depend on the sensor type defined in the configuration.

    "},{"location":"G-Codes.html#set_filament_sensor","title":"SET_FILAMENT_SENSOR","text":""},{"location":"G-Codes.html#for-filament_switch_sensor","title":"For filament_switch_sensor:","text":"

    SET_FILAMENT_SENSOR SENSOR=<sensor_name> [ENABLE=0|1] [RESET=0|1] [RUNOUT_DISTANCE=<mm>] [SMART=0|1] [ALWAYS_FIRE_EVENTS=0|1] [CHECK_ON_PRINT_START=0|1]: Sets values for the filament sensor. If all parameters are omitted, the current stats will be reported. ENABLE sets the filament sensor on/off. If ENABLE is set to 0, the filament sensor will be disabled, if set to 1 it is enabled. If the state of the sensor changes, a reset will be triggered. RESET removes all pending runout_gcodes and pauses and force a reevaluation of the sensor state. RUNOUT_DISTANCE sets the runout_distance. SMART sets the smart parameter. ALWAYS_FIRE_EVENTS sets the always_fire_events parameter, if set to true, a reset of the sensor will be triggered. CHECK_ON_PRINT_START sets the check_on_print_start parameter.

    "},{"location":"G-Codes.html#for-filament_motion_sensor","title":"For filament_motion_sensor:","text":"

    SET_FILAMENT_SENSOR SENSOR=<sensor_name> [ENABLE=0|1] [RESET=0|1] [DETECTION_LENGTH=<mm>] [SMART=0|1] [ALWAYS_FIRE_EVENTS=0|1]: Sets values for the filament sensor. If all parameters are omitted, the current stats will be reported. ENABLE sets the filament sensor on/off. If ENABLE is set to 0, the filament sensor will be disabled, if set to 1 it is enabled. If the sensor was previously disabled and gets enabled, a reset will be triggered. RESET resets the state of the sensor and sets it to filament detected. DETECTION_LENGTH sets the detection_length, if the new detection length is different from the old one, a reset will be triggered. SMART sets the smart parameter. ALWAYS_FIRE_EVENTS sets the always_fire_events parameter, no reset will be triggered.

    "},{"location":"G-Codes.html#firmware_retraction","title":"[firmware_retraction]","text":"

    The following standard G-Code commands are available when the firmware_retraction config section is enabled. These commands allow utilizing the firmware retraction feature available in many slicers. Retraction is a strategy to reduce stringing during travel moves (non-extrusion) from one part of the print to another. Note that pressure advance should be properly configured before retraction parameters are tuned to ensure optimal results.

    The following additional commands are also available.

    "},{"location":"G-Codes.html#set_retraction","title":"SET_RETRACTION","text":"

    SET_RETRACTION [RETRACT_LENGTH=<mm>] [RETRACT_SPEED=<mm/s>] [UNRETRACT_EXTRA_LENGTH=<mm>] [UNRETRACT_SPEED=<mm/s>] [Z_HOP_HEIGHT=<mm>]: Adjust the parameters used by firmware retraction. RETRACT_LENGTH determines the length of filament to retract (the minimum as well as standard value is 0 mm). RETRACT_SPEED determines the speed of the filament retraction move (the minimum value is 1 mm/s, the standard value is 20 mm/s). This value is typically set relatively high (>40 mm/s), except for soft and/or oozy filaments like TPU and PETG (20 to 30 mm/s). UNRETRACT_SPEED sets the speed of the filament unretract move (the minimum value is 1 mm/s, the standard value is 10 mm/s). This parameter is not particularly critical, although often lower than RETRACT_SPEED. UNRETRACT_EXTRA_LENGTH allows to add a small amount of length to the filament unretract move to prime the nozzle or to subtract a small amount of length from the filament unretract move to reduce blobbing at seams (the minimum value is -1 mm (2.41 mm3 volume for 1.75 mm filament), the standard value is 0 mm). Z_HOP_HEIGHT determines the vertical height by which the nozzle is lifted from the print to prevent collisions with the print during travel moves (the minimum value is 0 mm, the standard value is 0 mm, which disables Z-Hop moves). If a parameter is set when retracted, the new value will be taken into account only after G11 or CLEAR_RETRACTION event. SET_RETRACTION is commonly set as part of slicer per-filament configuration, as different filaments require different parameter settings. The command can be issued at runtime.

    "},{"location":"G-Codes.html#get_retraction","title":"GET_RETRACTION","text":"

    GET_RETRACTION: Queries the current parameters used by the firmware retraction module as well as the retract state. RETRACT_LENGTH, RETRACT_SPEED, UNRETRACT_EXTRA_LENGTH, UNRETRACT_SPEED, Z_HOP_HEIGHT, RETRACT_STATE (True, if retracted), ZHOP_STATE (True, if zhop offset currently applied) are displayed on the terminal.

    "},{"location":"G-Codes.html#clear_retraction","title":"CLEAR_RETRACTION","text":"

    CLEAR_RETRACTION: Clears the current retract state without extruder or motion system movement. All flags related to the retract state are reset to False.

    NOTE: The zhop state is also reset to False when the steppers are disabled (M84, typically part of end gcode and standard behavior of OctoPrint if a print is canceled) or the printer is homed (G28, typically part of start gcode). Hence, upon ending or canceling a print as well as starting a new print via GCode streaming or virtual SD card, the toolhead will not apply z_hop_height until next G11 if filament is retracted. Nevertheless, it is recommended to add CLEAR_RETRACTION to your start and end gcode to make sure the retract state is reset before and after each print.

    "},{"location":"G-Codes.html#reset_retraction","title":"RESET_RETRACTION","text":"

    RESET_RETRACTION: All changes to retraction parameters made via previous SET_RETRACTION commands are reset to config values.

    NOTE: It is recommended to add RESET_RETRACTION to your start and end gcode (with a possible override in your filament start gcode to set filament-specific overrides of firmware retraction defaults via SET_RETRACTION).

    "},{"location":"G-Codes.html#force_move","title":"[force_move]","text":"

    The force_move module is automatically loaded, however some commands require setting enable_force_move in the printer config.

    "},{"location":"G-Codes.html#stepper_buzz","title":"STEPPER_BUZZ","text":"

    STEPPER_BUZZ STEPPER=<config_name>: Move the given stepper forward one mm and then backward one mm, repeated 10 times. This is a diagnostic tool to help verify stepper connectivity.

    "},{"location":"G-Codes.html#force_move_1","title":"FORCE_MOVE","text":"

    FORCE_MOVE STEPPER=<config_name> DISTANCE=<value> VELOCITY=<value> [ACCEL=<value>]: This command will forcibly move the given stepper the given distance (in mm) at the given constant velocity (in mm/s). If ACCEL is specified and is greater than zero, then the given acceleration (in mm/s^2) will be used; otherwise no acceleration is performed. No boundary checks are performed; no kinematic updates are made; other parallel steppers on an axis will not be moved. Use caution as an incorrect command could cause damage! Using this command will almost certainly place the low-level kinematics in an incorrect state; issue a G28 afterwards to reset the kinematics. This command is intended for low-level diagnostics and debugging.

    "},{"location":"G-Codes.html#set_kinematic_position","title":"SET_KINEMATIC_POSITION","text":"

    SET_KINEMATIC_POSITION [X=<value>] [Y=<value>] [Z=<value>]: Force the low-level kinematic code to believe the toolhead is at the given cartesian position. This is a diagnostic and debugging command; use SET_GCODE_OFFSET and/or G92 for regular axis transformations. If an axis is not specified then it will default to the position that the head was last commanded to. Setting an incorrect or invalid position may lead to internal software errors. This command may invalidate future boundary checks; issue a G28 afterwards to reset the kinematics.

    "},{"location":"G-Codes.html#gcode","title":"[gcode]","text":"

    The gcode module is automatically loaded.

    "},{"location":"G-Codes.html#restart","title":"RESTART","text":"

    RESTART: This will cause the host software to reload its config and perform an internal reset. This command will not clear error state from the micro-controller (see FIRMWARE_RESTART) nor will it load new software (see the FAQ).

    "},{"location":"G-Codes.html#firmware_restart","title":"FIRMWARE_RESTART","text":"

    FIRMWARE_RESTART: This is similar to a RESTART command, but it also clears any error state from the micro-controller.

    "},{"location":"G-Codes.html#heater_interrupt","title":"HEATER_INTERRUPT","text":"

    HEATER_INTERRUPT: Interrupts a TEMPERATURE_WAIT command.

    "},{"location":"G-Codes.html#log_rollover","title":"LOG_ROLLOVER","text":"

    LOG_ROLLOVER: Trigger a klippy.log rollover and generate a new log file.

    "},{"location":"G-Codes.html#status","title":"STATUS","text":"

    STATUS: Report the Kalico host software status.

    "},{"location":"G-Codes.html#help","title":"HELP","text":"

    HELP: Report the list of available extended G-Code commands.

    "},{"location":"G-Codes.html#gcode_arcs","title":"[gcode_arcs]","text":"

    The following standard G-Code commands are available if a gcode_arcs config section is enabled:

    "},{"location":"G-Codes.html#gcode_macro","title":"[gcode_macro]","text":"

    The following command is available when a gcode_macro config section is enabled (also see the command templates guide).

    "},{"location":"G-Codes.html#set_gcode_variable","title":"SET_GCODE_VARIABLE","text":"

    SET_GCODE_VARIABLE MACRO=<macro_name> VARIABLE=<name> VALUE=<value>: This command allows one to change the value of a gcode_macro variable at run-time. The provided VALUE is parsed as a Python literal.

    "},{"location":"G-Codes.html#reload_gcode_macros","title":"RELOAD_GCODE_MACROS","text":"

    RELOAD_GCODE_MACROS: This command reads the config files and reloads all previously loaded gcode templates. It does not load new [gcode_macro] objects or unload deleted ones. Variables modified with SET_GCODE_VARIABLE remain unaffected.

    "},{"location":"G-Codes.html#gcode_move","title":"[gcode_move]","text":"

    The gcode_move module is automatically loaded.

    "},{"location":"G-Codes.html#get_position","title":"GET_POSITION","text":"

    GET_POSITION: Return information on the current location of the toolhead. See the developer documentation of GET_POSITION output for more information.

    "},{"location":"G-Codes.html#set_gcode_offset","title":"SET_GCODE_OFFSET","text":"

    SET_GCODE_OFFSET [X=<pos>|X_ADJUST=<adjust>] [Y=<pos>|Y_ADJUST=<adjust>] [Z=<pos>|Z_ADJUST=<adjust>] [MOVE=1 [MOVE_SPEED=<speed>]]: Set a positional offset to apply to future G-Code commands. This is commonly used to virtually change the Z bed offset or to set nozzle XY offsets when switching extruders. For example, if \"SET_GCODE_OFFSET Z=0.2\" is sent, then future G-Code moves will have 0.2mm added to their Z height. If the X_ADJUST style parameters are used, then the adjustment will be added to any existing offset (eg, \"SET_GCODE_OFFSET Z=-0.2\" followed by \"SET_GCODE_OFFSET Z_ADJUST=0.3\" would result in a total Z offset of 0.1). If \"MOVE=1\" is specified then a toolhead move will be issued to apply the given offset (otherwise the offset will take effect on the next absolute G-Code move that specifies the given axis). If \"MOVE_SPEED\" is specified then the toolhead move will be performed with the given speed (in mm/s); otherwise the toolhead move will use the last specified G-Code speed.

    "},{"location":"G-Codes.html#save_gcode_state","title":"SAVE_GCODE_STATE","text":"

    SAVE_GCODE_STATE [NAME=<state_name>]: Save the current g-code coordinate parsing state. Saving and restoring the g-code state is useful in scripts and macros. This command saves the current g-code absolute coordinate mode (G90/G91), absolute extrude mode (M82/M83), origin (G92), offset (SET_GCODE_OFFSET), speed override (M220), extruder override (M221), move speed, current XYZ position, and relative extruder \"E\" position. If NAME is provided it allows one to name the saved state to the given string. If NAME is not provided it defaults to \"default\".

    "},{"location":"G-Codes.html#restore_gcode_state","title":"RESTORE_GCODE_STATE","text":"

    RESTORE_GCODE_STATE [NAME=<state_name>] [MOVE=1 [MOVE_SPEED=<speed>]]: Restore a state previously saved via SAVE_GCODE_STATE. If \"MOVE=1\" is specified then a toolhead move will be issued to move back to the previous XYZ position. If \"MOVE_SPEED\" is specified then the toolhead move will be performed with the given speed (in mm/s); otherwise the toolhead move will use the restored g-code speed.

    "},{"location":"G-Codes.html#hall_filament_width_sensor","title":"[hall_filament_width_sensor]","text":"

    The following commands are available when the tsl1401cl filament width sensor config section or hall filament width sensor config section is enabled (also see TSLl401CL Filament Width Sensor and Hall Filament Width Sensor):

    "},{"location":"G-Codes.html#query_filament_width","title":"QUERY_FILAMENT_WIDTH","text":"

    QUERY_FILAMENT_WIDTH: Return the current measured filament width.

    "},{"location":"G-Codes.html#reset_filament_width_sensor","title":"RESET_FILAMENT_WIDTH_SENSOR","text":"

    RESET_FILAMENT_WIDTH_SENSOR: Clear all sensor readings. Helpful after filament change.

    "},{"location":"G-Codes.html#disable_filament_width_sensor","title":"DISABLE_FILAMENT_WIDTH_SENSOR","text":"

    DISABLE_FILAMENT_WIDTH_SENSOR: Turn off the filament width sensor and stop using it for flow control.

    "},{"location":"G-Codes.html#enable_filament_width_sensor","title":"ENABLE_FILAMENT_WIDTH_SENSOR","text":"

    ENABLE_FILAMENT_WIDTH_SENSOR: Turn on the filament width sensor and start using it for flow control.

    "},{"location":"G-Codes.html#query_raw_filament_width","title":"QUERY_RAW_FILAMENT_WIDTH","text":"

    QUERY_RAW_FILAMENT_WIDTH: Return the current ADC channel readings and RAW sensor value for calibration points.

    "},{"location":"G-Codes.html#enable_filament_width_log","title":"ENABLE_FILAMENT_WIDTH_LOG","text":"

    ENABLE_FILAMENT_WIDTH_LOG: Turn on diameter logging.

    "},{"location":"G-Codes.html#disable_filament_width_log","title":"DISABLE_FILAMENT_WIDTH_LOG","text":"

    DISABLE_FILAMENT_WIDTH_LOG: Turn off diameter logging.

    "},{"location":"G-Codes.html#heaters","title":"[heaters]","text":"

    The heaters module is automatically loaded if a heater is defined in the config file.

    "},{"location":"G-Codes.html#turn_off_heaters","title":"TURN_OFF_HEATERS","text":"

    TURN_OFF_HEATERS: Turn off all heaters.

    "},{"location":"G-Codes.html#temperature_wait","title":"TEMPERATURE_WAIT","text":"

    TEMPERATURE_WAIT SENSOR=<config_name> [MINIMUM=<target>] [MAXIMUM=<target>]: Wait until the given temperature sensor is at or above the supplied MINIMUM and/or at or below the supplied MAXIMUM.

    "},{"location":"G-Codes.html#set_heater_temperature","title":"SET_HEATER_TEMPERATURE","text":"

    SET_HEATER_TEMPERATURE HEATER=<heater_name> [TARGET=<target_temperature>]: Sets the target temperature for a heater. If a target temperature is not supplied, the target is 0.

    "},{"location":"G-Codes.html#set_smooth_time","title":"SET_SMOOTH_TIME","text":"

    SET_SMOOTH_TIME HEATER=<heater_name> [SMOOTH_TIME=<smooth_time>] [SAVE_TO_PROFILE=0|1]: Sets the smooth_time of the specified heater. If SMOOTH_TIME is omitted, the smooth_time will be reset to the value from the config. If SAVE_TO_PROFILE is set to 1, the new value will be written to the current PID_PROFILE.

    "},{"location":"G-Codes.html#idle_timeout","title":"[idle_timeout]","text":"

    The idle_timeout module is automatically loaded.

    "},{"location":"G-Codes.html#set_idle_timeout","title":"SET_IDLE_TIMEOUT","text":"

    SET_IDLE_TIMEOUT [TIMEOUT=<timeout>]: Allows the user to set the idle timeout (in seconds).

    "},{"location":"G-Codes.html#input_shaper","title":"[input_shaper]","text":"

    The following command is enabled if an input_shaper config section has been enabled (also see the resonance compensation guide).

    "},{"location":"G-Codes.html#set_input_shaper","title":"SET_INPUT_SHAPER","text":"

    SET_INPUT_SHAPER [SHAPER_FREQ_X=<shaper_freq_x>] [SHAPER_FREQ_Y=<shaper_freq_y>] [DAMPING_RATIO_X=<damping_ratio_x>] [DAMPING_RATIO_Y=<damping_ratio_y>] [SHAPER_TYPE=<shaper>] [SHAPER_TYPE_X=<shaper_type_x>] [SHAPER_TYPE_Y=<shaper_type_y>]: Modify input shaper parameters. Note that SHAPER_TYPE parameter resets input shaper for both X and Y axes even if different shaper types have been configured in [input_shaper] section. SHAPER_TYPE cannot be used together with either of SHAPER_TYPE_X and SHAPER_TYPE_Y parameters. See config reference for more details on each of these parameters.

    "},{"location":"G-Codes.html#manual_probe","title":"[manual_probe]","text":"

    The manual_probe module is automatically loaded.

    "},{"location":"G-Codes.html#manual_probe_1","title":"MANUAL_PROBE","text":"

    MANUAL_PROBE [SPEED=<speed>]: Run a helper script useful for measuring the height of the nozzle at a given location. If SPEED is specified, it sets the speed of TESTZ commands (the default is 5mm/s). During a manual probe, the following additional commands are available:

    "},{"location":"G-Codes.html#z_endstop_calibrate","title":"Z_ENDSTOP_CALIBRATE","text":"

    Z_ENDSTOP_CALIBRATE [SPEED=<speed>]: Run a helper script useful for calibrating a Z position_endstop config setting. See the MANUAL_PROBE command for details on the parameters and the additional commands available while the tool is active.

    "},{"location":"G-Codes.html#z_offset_apply_endstop","title":"Z_OFFSET_APPLY_ENDSTOP","text":"

    Z_OFFSET_APPLY_ENDSTOP: Take the current Z Gcode offset (aka, babystepping), and subtract it from the stepper_z endstop_position. This acts to take a frequently used babystepping value, and \"make it permanent\". Requires a SAVE_CONFIG to take effect.

    "},{"location":"G-Codes.html#manual_stepper","title":"[manual_stepper]","text":"

    The following command is available when a manual_stepper config section is enabled.

    "},{"location":"G-Codes.html#manual_stepper_1","title":"MANUAL_STEPPER","text":"

    MANUAL_STEPPER STEPPER=config_name [ENABLE=[0|1]] [SET_POSITION=<pos>] [SPEED=<speed>] [ACCEL=<accel>] [MOVE=<pos> [STOP_ON_ENDSTOP=[1|2|-1|-2]] [SYNC=0]]: This command will alter the state of the stepper. Use the ENABLE parameter to enable/disable the stepper. Use the SET_POSITION parameter to force the stepper to think it is at the given position. Use the MOVE parameter to request a movement to the given position. If SPEED and/or ACCEL is specified then the given values will be used instead of the defaults specified in the config file. If an ACCEL of zero is specified then no acceleration will be performed. If STOP_ON_ENDSTOP=1 is specified then the move will end early should the endstop report as triggered (use STOP_ON_ENDSTOP=2 to complete the move without error even if the endstop does not trigger, use -1 or -2 to stop when the endstop reports not triggered). Normally future G-Code commands will be scheduled to run after the stepper move completes, however if a manual stepper move uses SYNC=0 then future G-Code movement commands may run in parallel with the stepper movement.

    "},{"location":"G-Codes.html#mcp4018","title":"[mcp4018]","text":"

    The following command is available when a mcp4018 config section is enabled.

    "},{"location":"G-Codes.html#set_digipot","title":"SET_DIGIPOT","text":"

    SET_DIGIPOT DIGIPOT=config_name WIPER=<value>: This command will change the current value of the digipot. This value should typically be between 0.0 and 1.0, unless a 'scale' is defined in the config. When 'scale' is defined, then this value should be between 0.0 and 'scale'.

    "},{"location":"G-Codes.html#led","title":"[led]","text":"

    The following command is available when any of the led config sections are enabled.

    "},{"location":"G-Codes.html#set_led","title":"SET_LED","text":"

    SET_LED LED=<config_name> RED=<value> GREEN=<value> BLUE=<value> WHITE=<value> [INDEX=<index>] [TRANSMIT=0] [SYNC=1]: This sets the LED output. Each color <value> must be between 0.0 and 1.0. The WHITE option is only valid on RGBW LEDs. If the LED supports multiple chips in a daisy-chain then one may specify INDEX to alter the color of just the given chip (1 for the first chip, 2 for the second, etc.). If INDEX is not provided then all LEDs in the daisy-chain will be set to the provided color. If TRANSMIT=0 is specified then the color change will only be made on the next SET_LED command that does not specify TRANSMIT=0; this may be useful in combination with the INDEX parameter to batch multiple updates in a daisy-chain. By default, the SET_LED command will sync it's changes with other ongoing gcode commands. This can lead to undesirable behavior if LEDs are being set while the printer is not printing as it will reset the idle timeout. If careful timing is not needed, the optional SYNC=0 parameter can be specified to apply the changes without resetting the idle timeout.

    "},{"location":"G-Codes.html#set_led_template","title":"SET_LED_TEMPLATE","text":"

    SET_LED_TEMPLATE LED=<led_name> TEMPLATE=<template_name> [<param_x>=<literal>] [INDEX=<index>]: Assign a display_template to a given LED. For example, if one defined a [display_template my_led_template] config section then one could assign TEMPLATE=my_led_template here. The display_template should produce a comma separated string containing four floating point numbers corresponding to red, green, blue, and white color settings. The template will be continuously evaluated and the LED will be automatically set to the resulting colors. One may set display_template parameters to use during template evaluation (parameters will be parsed as Python literals). If INDEX is not specified then all chips in the LED's daisy-chain will be set to the template, otherwise only the chip with the given index will be updated. If TEMPLATE is an empty string then this command will clear any previous template assigned to the LED (one can then use SET_LED commands to manage the LED's color settings).

    "},{"location":"G-Codes.html#output_pin","title":"[output_pin]","text":"

    The following command is available when an output_pin config section or pwm_tool config section is enabled.

    "},{"location":"G-Codes.html#set_pin","title":"SET_PIN","text":"

    SET_PIN PIN=config_name VALUE=<value>: Set the pin to the given output VALUE. VALUE should be 0 or 1 for \"digital\" output pins. For PWM pins, set to a value between 0.0 and 1.0, or between 0.0 and scale if a scale is configured in the output_pin config section.

    "},{"location":"G-Codes.html#palette2","title":"[palette2]","text":"

    The following commands are available when the palette2 config section is enabled.

    Palette prints work by embedding special OCodes (Omega Codes) in the GCode file:

    The following additional commands are also available.

    "},{"location":"G-Codes.html#palette_connect","title":"PALETTE_CONNECT","text":"

    PALETTE_CONNECT: This command initializes the connection with the Palette 2.

    "},{"location":"G-Codes.html#palette_disconnect","title":"PALETTE_DISCONNECT","text":"

    PALETTE_DISCONNECT: This command disconnects from the Palette 2.

    "},{"location":"G-Codes.html#palette_clear","title":"PALETTE_CLEAR","text":"

    PALETTE_CLEAR: This command instructs the Palette 2 to clear all of the input and output paths of filament.

    "},{"location":"G-Codes.html#palette_cut","title":"PALETTE_CUT","text":"

    PALETTE_CUT: This command instructs the Palette 2 to cut the filament currently loaded in the splice core.

    "},{"location":"G-Codes.html#palette_smart_load","title":"PALETTE_SMART_LOAD","text":"

    PALETTE_SMART_LOAD: This command start the smart load sequence on the Palette 2. Filament is loaded automatically by extruding it the distance calibrated on the device for the printer, and instructs the Palette 2 once the loading has been completed. This command is the same as pressing Smart Load directly on the Palette 2 screen after the filament load is complete.

    "},{"location":"G-Codes.html#pid_calibrate","title":"[pid_calibrate]","text":"

    The pid_calibrate module is automatically loaded if a heater is defined in the config file.

    "},{"location":"G-Codes.html#pid_calibrate_1","title":"PID_CALIBRATE","text":"

    PID_CALIBRATE HEATER=<config_name> TARGET=<temperature> [WRITE_FILE=1] [TOLERANCE=0.02]: Perform a PID calibration test. The specified heater will be enabled until the specified target temperature is reached, and then the heater will be turned off and on for several cycles. If the WRITE_FILE parameter is enabled, then the file /tmp/heattest.csv will be created with a log of all temperature samples taken during the test. TOLERANCE defaults to 0.02 if not passed in. The tighter the tolerance the better the calibration result will be, but how tight you can achieve depends on how clean your sensor readings are. low noise readings might allow 0.01, to be used, while noisy reading might require a value of 0.03 or higher.

    "},{"location":"G-Codes.html#set_heater_pid","title":"SET_HEATER_PID","text":"

    SET_HEATER_PID HEATER=<heater_name> KP=<kp> KI=<ki> KD=<kd>: Will allow one to manually change PID parameters of heaters without a reload of the firmware. HEATER takes the short name (so for heater_generic chamber you would only write chamber)

    "},{"location":"G-Codes.html#pid_profile","title":"[pid_profile]","text":"

    The PID_PROFILE module is automatically loaded if a heater is defined in the config file.

    HEATER generally takes the short name (so for heater_generic chamber you would only write chamber)

    "},{"location":"G-Codes.html#pid_profile_1","title":"PID_PROFILE","text":"

    PID_PROFILE LOAD=<profile_name> HEATER=<heater_name> [DEFAULT=<profile_name>] [VERBOSE=<verbosity>] [KEEP_TARGET=0|1] [LOAD_CLEAN=0|1]: Loads the given PID_PROFILE for the specified heater. If DEFAULT is specified, the Profile specified in DEFAULT will be loaded when then given Profile for LOAD can't be found (like a getOrDefault method). If VERBOSE is set to LOW, minimal info will be written in console. If set to NONE, no console outputs will be given. If KEEP_TARGET is set to 1, the heater will keep it's target temperature, if set to 0, the target temperature will be set to 0. By default the target temperature of the heater will be set to 0 so the algorithm has time to settle in. If LOAD_CLEAN is set to 1, the profile would be loaded as if the printer just started up, if set to 0, the profile will retain previous heating information. By default the information will be kept to reduce overshoot, change this value if you encounter weird behaviour while switching profiles.

    PID_PROFILE SAVE=<profile_name> HEATER=<heater_name>: Saves the currently loaded profile of the specified heater to the config under the given name.

    PID_PROFILE REMOVE=<profile_name> HEATER=<heater_name>: Removes the given profile from the profiles List for the current session and config if SAVE_CONFIG is issued afterwards.

    PID_PROFILE SET_VALUES=<profile_name> HEATER=<heater_name> TARGET=<target_temp> TOLERANCE=<tolerance> CONTROL=<control_type> KP=<kp> KI=<ki> KD=<kd> [RESET_TARGET=0|1] [LOAD_CLEAN=0|1]: Creates a new profile with the given PID values, CONTROL must either be pid or pid_v, TOLERANCE and TARGET must be specified to create a valid profile, though the values themselves don't matter. If KEEP_TARGET is set to 1, the heater will keep it's target temperature, if set to 0, the target temperature will be set to 0. By default the target temperature of the heater will be set to 0 so the algorithm has time to settle in. If LOAD_CLEAN is set to 1, the profile would be loaded as if the printer just started up, if set to 0, the profile will retain previous heating information. By default the information will be kept to reduce overshoot, change this value if you encounter weird behaviour while switching profiles.

    PID_PROFILE GET_VALUES HEATER=<heater_name>: Outputs the values of the current loaded pid_profile of the given heater to the console.

    "},{"location":"G-Codes.html#pause_resume","title":"[pause_resume]","text":"

    The following commands are available when the pause_resume config section is enabled:

    "},{"location":"G-Codes.html#pause","title":"PAUSE","text":"

    PAUSE: Pauses the current print. The current position is captured for restoration upon resume.

    "},{"location":"G-Codes.html#resume","title":"RESUME","text":"

    RESUME [VELOCITY=<value>]: Resumes the print from a pause, first restoring the previously captured position. The VELOCITY parameter determines the speed at which the tool should return to the original captured position.

    "},{"location":"G-Codes.html#clear_pause","title":"CLEAR_PAUSE","text":"

    CLEAR_PAUSE: Clears the current paused state without resuming the print. This is useful if one decides to cancel a print after a PAUSE. It is recommended to add this to your start gcode to make sure the paused state is fresh for each print.

    "},{"location":"G-Codes.html#cancel_print","title":"CANCEL_PRINT","text":"

    CANCEL_PRINT: Cancels the current print.

    "},{"location":"G-Codes.html#print_stats","title":"[print_stats]","text":"

    The print_stats module is automatically loaded.

    "},{"location":"G-Codes.html#set_print_stats_info","title":"SET_PRINT_STATS_INFO","text":"

    SET_PRINT_STATS_INFO [TOTAL_LAYER=<total_layer_count>] [CURRENT_LAYER= <current_layer>]: Pass slicer info like layer act and total to Kalico. Add SET_PRINT_STATS_INFO [TOTAL_LAYER=<total_layer_count>] to your slicer start gcode section and SET_PRINT_STATS_INFO [CURRENT_LAYER= <current_layer>] at the layer change gcode section to pass layer information from your slicer to Kalico.

    "},{"location":"G-Codes.html#probe","title":"[probe]","text":"

    The following commands are available when a probe config section or bltouch config section is enabled (also see the probe calibrate guide).

    "},{"location":"G-Codes.html#probe_1","title":"PROBE","text":"

    PROBE [PROBE_SPEED=<mm/s>] [LIFT_SPEED=<mm/s>] [SAMPLES=<count>] [SAMPLE_RETRACT_DIST=<mm>] [SAMPLES_TOLERANCE=<mm>] [SAMPLES_TOLERANCE_RETRIES=<count>] [SAMPLES_RESULT=median|average]: Move the nozzle downwards until the probe triggers. If any of the optional parameters are provided they override their equivalent setting in the probe config section.

    "},{"location":"G-Codes.html#query_probe","title":"QUERY_PROBE","text":"

    QUERY_PROBE: Report the current status of the probe (\"triggered\" or \"open\").

    "},{"location":"G-Codes.html#probe_accuracy","title":"PROBE_ACCURACY","text":"

    PROBE_ACCURACY [PROBE_SPEED=<mm/s>] [SAMPLES=<count>] [SAMPLE_RETRACT_DIST=<mm>]: Calculate the maximum, minimum, average, median, and standard deviation of multiple probe samples. By default, 10 SAMPLES are taken. Otherwise the optional parameters default to their equivalent setting in the probe config section.

    "},{"location":"G-Codes.html#probe_calibrate","title":"PROBE_CALIBRATE","text":"

    PROBE_CALIBRATE [SPEED=<speed>] [<probe_parameter>=<value>]: Run a helper script useful for calibrating the probe's z_offset. See the PROBE command for details on the optional probe parameters. See the MANUAL_PROBE command for details on the SPEED parameter and the additional commands available while the tool is active. Please note, the PROBE_CALIBRATE command uses the speed variable to move in XY direction as well as Z.

    "},{"location":"G-Codes.html#z_offset_apply_probe","title":"Z_OFFSET_APPLY_PROBE","text":"

    Z_OFFSET_APPLY_PROBE: Take the current Z Gcode offset (aka, babystepping), and subtract if from the probe's z_offset. This acts to take a frequently used babystepping value, and \"make it permanent\". Requires a SAVE_CONFIG to take effect.

    "},{"location":"G-Codes.html#probe_eddy_current","title":"[probe_eddy_current]","text":"

    The following commands are available when a probe_eddy_current config section is enabled.

    "},{"location":"G-Codes.html#probe_eddy_current_calibrate","title":"PROBE_EDDY_CURRENT_CALIBRATE","text":"

    PROBE_EDDY_CURRENT_CALIBRATE CHIP=<config_name>: This starts a tool that calibrates the sensor resonance frequencies to corresponding Z heights. The tool will take a couple of minutes to complete. After completion, use the SAVE_CONFIG command to store the results in the printer.cfg file.

    "},{"location":"G-Codes.html#ldc_calibrate_drive_current","title":"LDC_CALIBRATE_DRIVE_CURRENT","text":"

    LDC_CALIBRATE_DRIVE_CURRENT CHIP=<config_name> This tool will calibrate the ldc1612 DRIVE_CURRENT0 register. Prior to using this tool, move the sensor so that it is near the center of the bed and about 20mm above the bed surface. Run this command to determine an appropriate DRIVE_CURRENT for the sensor. After running this command use the SAVE_CONFIG command to store that new setting in the printer.cfg config file.

    "},{"location":"G-Codes.html#pwm_cycle_time","title":"[pwm_cycle_time]","text":"

    The following command is available when a pwm_cycle_time config section is enabled.

    "},{"location":"G-Codes.html#set_pin_1","title":"SET_PIN","text":"

    SET_PIN PIN=config_name VALUE=<value> [CYCLE_TIME=<cycle_time>]: This command works similarly to output_pin SET_PIN commands. The command here supports setting an explicit cycle time using the CYCLE_TIME parameter (specified in seconds). Note that the CYCLE_TIME parameter is not stored between SET_PIN commands (any SET_PIN command without an explicit CYCLE_TIME parameter will use the cycle_time specified in the pwm_cycle_time config section).

    "},{"location":"G-Codes.html#query_adc","title":"[query_adc]","text":"

    The query_adc module is automatically loaded.

    "},{"location":"G-Codes.html#query_adc_1","title":"QUERY_ADC","text":"

    QUERY_ADC [NAME=<config_name>] [PULLUP=<value>]: Report the last analog value received for a configured analog pin. If NAME is not provided, the list of available adc names are reported. If PULLUP is provided (as a value in Ohms), the raw analog value along with the equivalent resistance given that pullup is reported.

    "},{"location":"G-Codes.html#query_endstops","title":"[query_endstops]","text":"

    The query_endstops module is automatically loaded. The following standard G-Code commands are currently available, but using them is not recommended:

    "},{"location":"G-Codes.html#query_endstops_1","title":"QUERY_ENDSTOPS","text":"

    QUERY_ENDSTOPS: Probe the axis endstops and report if they are \"triggered\" or in an \"open\" state. This command is typically used to verify that an endstop is working correctly.

    "},{"location":"G-Codes.html#resonance_tester","title":"[resonance_tester]","text":"

    The following commands are available when a resonance_tester config section is enabled (also see the measuring resonances guide).

    "},{"location":"G-Codes.html#measure_axes_noise","title":"MEASURE_AXES_NOISE","text":"

    MEASURE_AXES_NOISE: Measures and outputs the noise for all axes of all enabled accelerometer chips.

    "},{"location":"G-Codes.html#test_resonances","title":"TEST_RESONANCES","text":"

    TEST_RESONANCES AXIS=<axis> OUTPUT=<resonances,raw_data> [NAME=<name>] [FREQ_START=<min_freq>] [FREQ_END=<max_freq>] [HZ_PER_SEC=<hz_per_sec>] [CHIPS=<adxl345_chip_name>] [POINT=x,y,z] [ACCEL_PER_HZ=<accel_per_hz>] [INPUT_SHAPING=[<0:1>]]: Runs the resonance test in all configured probe points for the requested \"axis\" and measures the acceleration using the accelerometer chips configured for the respective axis. \"axis\" can either be X or Y, or specify an arbitrary direction as AXIS=dx,dy, where dx and dy are floating point numbers defining a direction vector (e.g. AXIS=X, AXIS=Y, or AXIS=1,-1 to define a diagonal direction). Note that AXIS=dx,dy and AXIS=-dx,-dy is equivalent. adxl345_chip_name can be one or more configured adxl345 chip,delimited with comma, for example CHIPS=\"adxl345, adxl345 rpi\". Note that adxl345 can be omitted from named adxl345 chips. If POINT or ACCEL_PER_HZ are specified, they will override the corresponding fields configured in [resonance_tester]. If INPUT_SHAPING=0 or not set(default), disables input shaping for the resonance testing, because it is not valid to run the resonance testing with the input shaper enabled. OUTPUT parameter is a comma-separated list of which outputs will be written. If raw_data is requested, then the raw accelerometer data is written into a file or a series of files /tmp/raw_data_<axis>_[<chip_name>_][<point>_]<name>.csv with (<point>_ part of the name generated only if more than 1 probe point is configured or POINT is specified). If resonances is specified, the frequency response is calculated (across all probe points) and written into /tmp/resonances_<axis>_<name>.csv file. If unset, OUTPUT defaults to resonances, and NAME defaults to the current time in \"YYYYMMDD_HHMMSS\" format.

    "},{"location":"G-Codes.html#shaper_calibrate","title":"SHAPER_CALIBRATE","text":"

    SHAPER_CALIBRATE [AXIS=<axis>] [NAME=<name>] [FREQ_START=<min_freq>] [FREQ_END=<max_freq>] [HZ_PER_SEC=<hz_per_sec>] [CHIPS=<adxl345_chip_name>] [MAX_SMOOTHING=<max_smoothing>]: Similarly to TEST_RESONANCES, runs the resonance test as configured, and tries to find the optimal parameters for the input shaper for the requested axis (or both X and Y axes if AXIS parameter is unset). If MAX_SMOOTHING is unset, its value is taken from [resonance_tester] section, with the default being unset. See the Max smoothing of the measuring resonances guide for more information on the use of this feature. The results of the tuning are printed to the console, and the frequency responses and the different input shapers values are written to a CSV file(s) /tmp/calibration_data_<axis>_<name>.csv. Unless specified, NAME defaults to the current time in \"YYYYMMDD_HHMMSS\" format. Note that the suggested input shaper parameters can be persisted in the config by issuing SAVE_CONFIG command, and if [input_shaper] was already enabled previously, these parameters take effect immediately.

    "},{"location":"G-Codes.html#respond","title":"[respond]","text":"

    The following standard G-Code commands are available when the respond config section is enabled:

    The following additional commands are also available.

    "},{"location":"G-Codes.html#respond_1","title":"RESPOND","text":""},{"location":"G-Codes.html#save_variables","title":"[save_variables]","text":"

    The following command is enabled if a save_variables config section has been enabled.

    "},{"location":"G-Codes.html#save_variable","title":"SAVE_VARIABLE","text":"

    SAVE_VARIABLE VARIABLE=<name> VALUE=<value>: Saves the variable to disk so that it can be used across restarts. All stored variables are loaded into the printer.save_variables.variables dict at startup and can be used in gcode macros. The provided VALUE is parsed as a Python literal.

    "},{"location":"G-Codes.html#screws_tilt_adjust","title":"[screws_tilt_adjust]","text":"

    The following commands are available when the screws_tilt_adjust config section is enabled (also see the manual level guide).

    "},{"location":"G-Codes.html#screws_tilt_calculate","title":"SCREWS_TILT_CALCULATE","text":"

    SCREWS_TILT_CALCULATE [DIRECTION=CW|CCW] [MAX_DEVIATION=<value>] [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>]: This command will invoke the bed screws adjustment tool. It will command the nozzle to different locations (as defined in the config file) probing the z height and calculate the number of knob turns to adjust the bed level. If DIRECTION is specified, the knob turns will all be in the same direction, clockwise (CW) or counterclockwise (CCW). See the PROBE command for details on the optional probe parameters. IMPORTANT: You MUST always do a G28 before using this command. If MAX_DEVIATION is specified, the command will raise a gcode error if any difference in the screw height relative to the base screw height is greater than the value provided. The optional HORIZONTAL_MOVE_Z value overrides the horizontal_move_z option specified in the config file.

    "},{"location":"G-Codes.html#sdcard_loop","title":"[sdcard_loop]","text":"

    When the sdcard_loop config section is enabled, the following extended commands are available.

    "},{"location":"G-Codes.html#sdcard_loop_begin","title":"SDCARD_LOOP_BEGIN","text":"

    SDCARD_LOOP_BEGIN COUNT=<count>: Begin a looped section in the SD print. A count of 0 indicates that the section should be looped indefinitely.

    "},{"location":"G-Codes.html#sdcard_loop_end","title":"SDCARD_LOOP_END","text":"

    SDCARD_LOOP_END: End a looped section in the SD print.

    "},{"location":"G-Codes.html#sdcard_loop_desist","title":"SDCARD_LOOP_DESIST","text":"

    SDCARD_LOOP_DESIST: Complete existing loops without further iterations.

    "},{"location":"G-Codes.html#servo","title":"[servo]","text":"

    The following commands are available when a servo config section is enabled.

    "},{"location":"G-Codes.html#set_servo","title":"SET_SERVO","text":"

    SET_SERVO SERVO=config_name [ANGLE=<degrees> | WIDTH=<seconds>]: Set the servo position to the given angle (in degrees) or pulse width (in seconds). Use WIDTH=0 to disable the servo output.

    "},{"location":"G-Codes.html#skew_correction","title":"[skew_correction]","text":"

    The following commands are available when the skew_correction config section is enabled (also see the Skew Correction guide).

    "},{"location":"G-Codes.html#set_skew","title":"SET_SKEW","text":"

    SET_SKEW [XY=<ac_length,bd_length,ad_length>] [XZ=<ac,bd,ad>] [YZ=<ac,bd,ad>] [CLEAR=<0|1>]: Configures the [skew_correction] module with measurements (in mm) taken from a calibration print. One may enter measurements for any combination of planes, planes not entered will retain their current value. If CLEAR=1 is entered then all skew correction will be disabled.

    "},{"location":"G-Codes.html#get_current_skew","title":"GET_CURRENT_SKEW","text":"

    GET_CURRENT_SKEW: Reports the current printer skew for each plane in both radians and degrees. The skew is calculated based on parameters provided via the SET_SKEW gcode.

    "},{"location":"G-Codes.html#calc_measured_skew","title":"CALC_MEASURED_SKEW","text":"

    CALC_MEASURED_SKEW [AC=<ac_length>] [BD=<bd_length>] [AD=<ad_length>]: Calculates and reports the skew (in radians and degrees) based on a measured print. This can be useful for determining the printer's current skew after correction has been applied. It may also be useful before correction is applied to determine if skew correction is necessary. See Skew Correction for details on skew calibration objects and measurements.

    "},{"location":"G-Codes.html#skew_profile","title":"SKEW_PROFILE","text":"

    SKEW_PROFILE [LOAD=<name>] [SAVE=<name>] [REMOVE=<name>]: Profile management for skew_correction. LOAD will restore skew state from the profile matching the supplied name. SAVE will save the current skew state to a profile matching the supplied name. Remove will delete the profile matching the supplied name from persistent memory. Note that after SAVE or REMOVE operations have been run the SAVE_CONFIG gcode must be run to make the changes to persistent memory permanent.

    "},{"location":"G-Codes.html#smart_effector","title":"\u26a0\ufe0f [smart_effector]","text":"

    Several commands are available when a smart_effector config section is enabled. Be sure to check the official documentation for the Smart Effector on the Duet3D Wiki before changing the Smart Effector parameters. Also check the probe calibration guide.

    "},{"location":"G-Codes.html#set_smart_effector","title":"SET_SMART_EFFECTOR","text":"

    SET_SMART_EFFECTOR [SENSITIVITY=<sensitivity>] [ACCEL=<accel>] [RECOVERY_TIME=<time>]: Set the Smart Effector parameters. When SENSITIVITY is specified, the respective value is written to the SmartEffector EEPROM (requires control_pin to be provided). Acceptable <sensitivity> values are 0..255, the default is 50. Lower values require less nozzle contact force to trigger (but there is a higher risk of false triggering due to vibrations during probing), and higher values reduce false triggering (but require larger contact force to trigger). Since the sensitivity is written to EEPROM, it is preserved after the shutdown, and so it does not need to be configured on every printer startup. ACCEL and RECOVERY_TIME allow to override the corresponding parameters at run-time, see the config section of Smart Effector for more info on those parameters.

    "},{"location":"G-Codes.html#reset_smart_effector","title":"RESET_SMART_EFFECTOR","text":"

    RESET_SMART_EFFECTOR: Resets Smart Effector sensitivity to its factory settings. Requires control_pin to be provided in the config section.

    "},{"location":"G-Codes.html#stepper_enable","title":"[stepper_enable]","text":"

    The stepper_enable module is automatically loaded.

    "},{"location":"G-Codes.html#set_stepper_enable","title":"SET_STEPPER_ENABLE","text":"

    SET_STEPPER_ENABLE STEPPER=<config_name> ENABLE=[0|1]: Enable or disable only the given stepper. This is a diagnostic and debugging tool and must be used with care. Disabling an axis motor does not reset the homing information. Manually moving a disabled stepper may cause the machine to operate the motor outside of safe limits. This can lead to damage to axis components, hot ends, and print surface.

    "},{"location":"G-Codes.html#temperature_fan","title":"[temperature_fan]","text":"

    The following command is available when a temperature_fan config section is enabled.

    "},{"location":"G-Codes.html#set_temperature_fan_target","title":"SET_TEMPERATURE_FAN_TARGET","text":"

    SET_TEMPERATURE_FAN_TARGET temperature_fan=<temperature_fan_name> [target=<target_temperature>] [min_speed=<min_speed>] [max_speed=<max_speed>]: Sets the target temperature for a temperature_fan. If a target is not supplied, it is set to the specified temperature in the config file. If speeds are not supplied, no change is applied.

    "},{"location":"G-Codes.html#tmcxxxx","title":"[tmcXXXX]","text":"

    The following commands are available when any of the tmcXXXX config sections are enabled.

    "},{"location":"G-Codes.html#dump_tmc","title":"DUMP_TMC","text":"

    DUMP_TMC STEPPER=<name> [REGISTER=<name>]: This command will read all TMC driver registers and report their values. If a REGISTER is provided, only the specified register will be dumped.

    "},{"location":"G-Codes.html#init_tmc","title":"INIT_TMC","text":"

    INIT_TMC STEPPER=<name>: This command will initialize the TMC registers. Needed to re-enable the driver if power to the chip is turned off then back on.

    "},{"location":"G-Codes.html#set_tmc_current","title":"SET_TMC_CURRENT","text":"

    SET_TMC_CURRENT STEPPER=<name> CURRENT=<amps> HOLDCURRENT=<amps>: This will adjust the run and hold currents of the TMC driver. HOLDCURRENT is not applicable to tmc2660 drivers. When used on a driver which has the globalscaler field (tmc5160 and tmc2240), if StealthChop2 is used, the stepper must be held at standstill for >130ms so that the driver executes the AT#1 calibration.

    "},{"location":"G-Codes.html#set_tmc_field","title":"SET_TMC_FIELD","text":"

    SET_TMC_FIELD STEPPER=<name> FIELD=<field> VALUE=<value> VELOCITY=<value>: This will alter the value of the specified register field of the TMC driver. This command is intended for low-level diagnostics and debugging only because changing the fields during run-time can lead to undesired and potentially dangerous behavior of your printer. Permanent changes should be made using the printer configuration file instead. No sanity checks are performed for the given values. A VELOCITY can also be specified instead of a VALUE. This velocity is converted to the 20bit TSTEP based value representation. Only use the VELOCITY argument for fields that represent velocities.

    "},{"location":"G-Codes.html#toolhead","title":"[toolhead]","text":"

    The toolhead module is automatically loaded.

    "},{"location":"G-Codes.html#set_velocity_limit","title":"SET_VELOCITY_LIMIT","text":"

    SET_VELOCITY_LIMIT [VELOCITY=<value>] [ACCEL=<value>] [MINIMUM_CRUISE_RATIO=<value>] [SQUARE_CORNER_VELOCITY=<value>]: This command can alter the velocity limits that were specified in the printer config file. See the printer config section for a description of each parameter.

    "},{"location":"G-Codes.html#reset_velocity_limit","title":"RESET_VELOCITY_LIMIT","text":"

    RESET_VELOCITY_LIMIT: This command resets the velocity limits to the values specified in the printer config file. See the printer config section for a description of each parameter.

    "},{"location":"G-Codes.html#set_kinematics_limit","title":"\u26a0\ufe0f SET_KINEMATICS_LIMIT","text":"

    SET_KINEMATICS_LIMIT [<X,Y,Z>_ACCEL=<value>] [<X,Y,Z>_VELOCITY=<value>] [SCALE=<0:1>]: change the per-axis limits.

    This command is only available when kinematics is set to either limited_cartesian or limited_corexy. The velocity argument is not available on CoreXY. With no arguments, this command responds with the movement direction with the most acceleration or velocity.

    "},{"location":"G-Codes.html#tools_calibrate","title":"\u26a0\ufe0f [tools_calibrate]","text":"

    The following commands are available when the tools_calibrate config section is enabled.

    "},{"location":"G-Codes.html#tool_calibrate_query_probe","title":"TOOL_CALIBRATE_QUERY_PROBE","text":"

    TOOL_CALIBRATE_QUERY_PROBE: Query the current calibration probe state.

    "},{"location":"G-Codes.html#tool_locate_sensor","title":"TOOL_LOCATE_SENSOR","text":"

    TOOL_LOCATE_SENSOR: Locate the sensor relative to the initial tool. The initial tool is the 0 offset, which other tools are calibrated against.

    Before running TOOL_LOCATE_SENSOR, position your primary toolhead centered over the calibration probe.

    "},{"location":"G-Codes.html#tool_calibrate_tool_offset","title":"TOOL_CALIBRATE_TOOL_OFFSET","text":"

    TOOL_CALIBRATE_TOOL_OFFSET: After locating the sensor with your initial tool, position each additional tool over the sensor and run TOOL_CALIBRATE_TOOL_OFFSET to find their offsets.

    "},{"location":"G-Codes.html#tool_calibrate_save_tool_offset","title":"TOOL_CALIBRATE_SAVE_TOOL_OFFSET","text":"

    TOOL_CALIBRATE_SAVE_TOOL_OFFSET MACRO=<macro_name> VARIABLE=<variable_name> [VALUE=\"({x:0.6f}, {y:0.6f}, {z:0.6f})\"]: Save the last calibration result to a macro variable.

    TOOL_CALIBRATE_SAVE_TOOL_OFFSET SECTION= ATTRIBUTE= [VALUE=\"{x:0.6f}, {y:0.6f}, {z:0.6f}\"]: Save the last calibration result to a field in your configuration. Calibration data saved this way will not take effect until after a RESTART of your printer.

    "},{"location":"G-Codes.html#trad_rack","title":"[trad_rack]","text":"

    The following commands are available when the trad_rack config section is enabled.

    "},{"location":"G-Codes.html#tr_home","title":"TR_HOME","text":"

    TR_HOME: Homes the selector.

    "},{"location":"G-Codes.html#tr_go_to_lane","title":"TR_GO_TO_LANE","text":"

    TR_GO_TO_LANE LANE=<lane index>: Moves the selector to the specified lane.

    "},{"location":"G-Codes.html#tr_load_lane","title":"TR_LOAD_LANE","text":"

    TR_LOAD_LANE LANE=<lane index> [RESET_SPEED=<0|1>]: Ensures filament is loaded into the module for the specified lane by prompting the user to insert filament, loading filament from the module into the selector, and retracting the filament back into the module. If RESET_SPEED is 1, the bowden move speed used for the specified LANE will be reset to spool_pull_speed from the trad_rack config section (see bowden speeds for details on how the bowden speed settings are used). If not specified, RESET_SPEED defaults to 1.

    "},{"location":"G-Codes.html#tr_load_toolhead","title":"TR_LOAD_TOOLHEAD","text":"

    TR_LOAD_TOOLHEAD LANE=<lane index>|TOOL=<tool index> [MIN_TEMP=<temperature>] [EXACT_TEMP=<temperature>] [BOWDEN_LENGTH=<mm>] [EXTRUDER_LOAD_LENGTH=<mm>] [HOTEND_LOAD_LENGTH=<mm>]: Loads filament from the specified lane or tool into the toolhead*. Either LANE or TOOL must be specified. If both are specified, then LANE takes precedence. If there is already an \"active lane\" because the toolhead has been loaded beforehand, it will be unloaded before loading the new filament. If MIN_TEMP is specified and it is higher than the extruder's current temperature, then the extruder will be heated to at least MIN_TEMP before unloading/loading; the current extruder temperature target may be used instead if it is higher than MIN_TEMP, and if not then tr_last_heater_target may be used. If EXACT_TEMP is specified, the extruder will be heated to EXACT_TEMP before unloading/loading, regardless of any other temperature setting. If any of the optional length parameters are specified, they override the corresponding settings in the trad_rack config section.

    * see the Tool Mapping document for details on the difference between lanes and tools and how they relate to each other.

    "},{"location":"G-Codes.html#t0-t1-t2-etc","title":"T0, T1, T2, etc.","text":"

    T<tool index>: Equivalent to calling TR_LOAD_TOOLHEAD TOOL=<tool index>. All of the optional parameters accepted by the TR_LOAD_TOOLHEAD command can also be used with these commands.

    "},{"location":"G-Codes.html#tr_unload_toolhead","title":"TR_UNLOAD_TOOLHEAD","text":"

    TR_UNLOAD_TOOLHEAD [MIN_TEMP=<temperature>] [EXACT_TEMP=<temperature>]: Unloads filament from the toolhead and back into its module. If MIN_TEMP is specified and it is higher than the extruder's current temperature, then the extruder will be heated to at least MIN_TEMP before unloading; the current extruder temperature target may be used instead if it is higher than MIN_TEMP, and if not then tr_last_heater_target may be used. If EXACT_TEMP is specified, the extruder will be heated to EXACT_TEMP before unloading/loading, regardless of any other temperature setting.

    "},{"location":"G-Codes.html#tr_servo_down","title":"TR_SERVO_DOWN","text":"

    TR_SERVO_DOWN [FORCE=<0|1>]: Moves the servo to bring the drive gear down. The selector must be moved to a valid lane before using this command, unless FORCE is 1. If not specified, FORCE defaults to 0. The FORCE parameter is unsafe for normal use and should only be used when the servo is not attached to Trad Rack's carriage.

    "},{"location":"G-Codes.html#tr_servo_up","title":"TR_SERVO_UP","text":"

    TR_SERVO_UP: Moves the servo to bring the drive gear up.

    "},{"location":"G-Codes.html#tr_set_active_lane","title":"TR_SET_ACTIVE_LANE","text":"

    TR_SET_ACTIVE_LANE LANE=<lane index>: Tells Trad Rack to assume the toolhead has been loaded with filament from the specified lane. The selector's position will also be inferred from this lane, and the selector motor will be enabled if it isn't already.

    "},{"location":"G-Codes.html#tr_reset_active_lane","title":"TR_RESET_ACTIVE_LANE","text":"

    TR_RESET_ACTIVE_LANE: Tells Trad Rack to assume the toolhead has not been loaded.

    "},{"location":"G-Codes.html#tr_resume","title":"TR_RESUME","text":"

    TR_RESUME: Completes necessary actions for Trad Rack to recover (and/or checks that Trad Rack is ready to continue), then resumes the print if all of those actions complete successfully. For example, if the print was paused due to a failed toolchange, then this command would retry the toolchange and then resume the print if the toolchange completes successfully. You will be prompted to use this command if Trad Rack has paused the print and requires user interaction or confirmation before attempting to recover and resume.

    "},{"location":"G-Codes.html#tr_locate_selector","title":"TR_LOCATE_SELECTOR","text":"

    TR_LOCATE_SELECTOR: Ensures the position of Trad Rack's selector is known so that it is ready for a print. If the user needs to take an action, they will be prompted to do so and the print will be paused (for example if the selector sensor is triggered but no active lane is set). The user_wait_time config option from the trad_rack config section determines how long Trad Rack will wait for user action before automatically unloading the toolhead and resuming. In addition, the save_active_lane config option determines whether this command can infer the \"active lane\" from a value saved before the last restart if the selector filament sensor is triggered but no active lane is currently set. It is recommended to call this command in the print start gcode.

    "},{"location":"G-Codes.html#tr_next","title":"TR_NEXT","text":"

    TR_NEXT: You will be prompted to use this command if Trad Rack requires user confirmation before continuing an action.

    "},{"location":"G-Codes.html#tr_sync_to_extruder","title":"TR_SYNC_TO_EXTRUDER","text":"

    TR_SYNC_TO_EXTRUDER: Syncs Trad Rack's filament driver to the extruder during printing, as well as during any extrusion moves within toolhead loading or unloading that would normally involve only the extruder. See the Extruder syncing document for more details. If you want the filament driver to be synced to the extruder on every startup without having to call this command, you can set sync_to_extruder to True in the trad_rack config section.

    "},{"location":"G-Codes.html#tr_unsync_from_extruder","title":"TR_UNSYNC_FROM_EXTRUDER","text":"

    TR_UNSYNC_FROM_EXTRUDER: Unsyncs Trad Rack's filament driver from the extruder during printing, as well as during any extrusion moves within toolhead loading or unloading that normally involve only the extruder. This is the default behavior unless you have set sync_to_extruder to True in the trad_rack config section.

    "},{"location":"G-Codes.html#tr_servo_test","title":"TR_SERVO_TEST","text":"

    TR_SERVO_TEST [ANGLE=<degrees>]: Moves the servo to the specified ANGLE relative to the down position. If ANGLE is not specified, the servo will be moved to the up position defined by servo_up_angle from the trad_rack config section. This command is meant for testing different servo angles in order to find the correct value for servo_up_angle.

    "},{"location":"G-Codes.html#tr_calibrate_selector","title":"TR_CALIBRATE_SELECTOR","text":"

    TR_CALIBRATE_SELECTOR: Initiates the process of calibrating lane_spacing, as well as the min, endstop, and max positions of the selector motor. You will be guided through the selector calibration process via messages in the console.

    "},{"location":"G-Codes.html#tr_set_hotend_load_length","title":"TR_SET_HOTEND_LOAD_LENGTH","text":"

    TR_SET_HOTEND_LOAD_LENGTH VALUE=<value>|ADJUST=<adjust>: Sets the value of hotend_load_length, overriding its value from the trad_rack config section. Does not persist across restarts. If the VALUE parameter is used, hotend_load_length will be set to the value passed in. If the ADJUST parameter is used, the adjustment will be added to the current value of hotend_load_length.

    "},{"location":"G-Codes.html#tr_discard_bowden_lengths","title":"TR_DISCARD_BOWDEN_LENGTHS","text":"

    TR_DISCARD_BOWDEN_LENGTHS [MODE=[ALL|LOAD|UNLOAD]]: Discards saved values for \"bowden_load_length\" and/or \"bowden_unload_length\" (see bowden lengths for details on how these settings are used). These settings will each be reset to the value of bowden_length from the trad_rack config section, and empty dictionaries will be saved for tr_calib_bowden_load_length and tr_calib_bowden_unload_length. \"bowden_load_length\" and tr_calib_bowden_load_length will be affected if MODE=LOAD is specified, \"bowden_unload_length\" and tr_calib_bowden_unload_length will be affected if MODE=UNLOAD is specified, and all 4 will be affected if MODE=ALL is specified. If not specified, MODE defaults to ALL.

    "},{"location":"G-Codes.html#tr_assign_lane","title":"TR_ASSIGN_LANE","text":"

    TR_ASSIGN_LANE LANE=<lane index> TOOL=<tool index> [SET_DEFAULT=<0|1>]: Assigns the specified LANE to the specified TOOL. If SET_DEFAULT is 1, LANE will become the default lane for the tool. If not specified, SET_DEFAULT defaults to 0.

    "},{"location":"G-Codes.html#tr_set_default_lane","title":"TR_SET_DEFAULT_LANE","text":"

    TR_SET_DEFAULT_LANE LANE=<lane index> [TOOL=<tool index>]: If TOOL is specified, LANE will be set as the default lane for the tool. If TOOL is not specified, LANE will be set as the default lane for its currently-assigned tool.

    "},{"location":"G-Codes.html#tr_reset_tool_map","title":"TR_RESET_TOOL_MAP","text":"

    TR_RESET_TOOL_MAP: Resets lane/tool mapping. Each tool will be mapped to a lane group consisting of a single lane with the same index as the tool.

    "},{"location":"G-Codes.html#tr_print_tool_map","title":"TR_PRINT_TOOL_MAP","text":"

    TR_PRINT_TOOL_MAP: Prints a table of the lane/tool mapping to the console, with rows corresponding to tools and columns corresponding to lanes.

    "},{"location":"G-Codes.html#tr_print_tool_groups","title":"TR_PRINT_TOOL_GROUPS","text":"

    TR_PRINT_TOOL_GROUPS: Prints a list of lanes assigned to each tool to the console. If a tool has multiple lanes assigned to it, the default lane will be indicated.

    "},{"location":"G-Codes.html#tuning_tower","title":"[tuning_tower]","text":"

    The tuning_tower module is automatically loaded.

    "},{"location":"G-Codes.html#tuning_tower_1","title":"TUNING_TOWER","text":"

    TUNING_TOWER COMMAND=<command> PARAMETER=<name> START=<value> [SKIP=<value>] [FACTOR=<value> [BAND=<value>]] | [STEP_DELTA=<value> STEP_HEIGHT=<value>]: A tool for tuning a parameter on each Z height during a print. The tool will run the given COMMAND with the given PARAMETER assigned to a value that varies with Z according to a formula. Use FACTOR if you will use a ruler or calipers to measure the Z height of the optimum value, or STEP_DELTA and STEP_HEIGHT if the tuning tower model has bands of discrete values as is common with temperature towers. If SKIP=<value> is specified, the tuning process doesn't begin until Z height <value> is reached, and below that the value will be set to START; in this case, the z_height used in the formulas below is actually max(z - skip, 0). There are three possible combinations of options:

    "},{"location":"G-Codes.html#virtual_sdcard","title":"[virtual_sdcard]","text":"

    Kalico supports the following standard G-Code commands if the virtual_sdcard config section is enabled:

    In addition, the following extended commands are available when the \"virtual_sdcard\" config section is enabled.

    "},{"location":"G-Codes.html#sdcard_print_file","title":"SDCARD_PRINT_FILE","text":"

    SDCARD_PRINT_FILE FILENAME=<filename>: Load a file and start SD print.

    "},{"location":"G-Codes.html#sdcard_reset_file","title":"SDCARD_RESET_FILE","text":"

    SDCARD_RESET_FILE: Unload file and clear SD state.

    "},{"location":"G-Codes.html#z_thermal_adjust","title":"[z_thermal_adjust]","text":"

    The following commands are available when the z_thermal_adjust config section is enabled.

    "},{"location":"G-Codes.html#set_z_thermal_adjust","title":"SET_Z_THERMAL_ADJUST","text":"

    SET_Z_THERMAL_ADJUST [ENABLE=<0:1>] [TEMP_COEFF=<value>] [REF_TEMP=<value>]: Enable or disable the Z thermal adjustment with ENABLE. Disabling does not remove any adjustment already applied, but will freeze the current adjustment value - this prevents potentially unsafe downward Z movement. Re-enabling can potentially cause upward tool movement as the adjustment is updated and applied. TEMP_COEFF allows run-time tuning of the adjustment temperature coefficient (i.e. the TEMP_COEFF config parameter). TEMP_COEFF values are not saved to the config. REF_TEMP manually overrides the reference temperature typically set during homing (for use in e.g. non-standard homing routines) - will be reset automatically upon homing.

    "},{"location":"G-Codes.html#z_calibration","title":"\u26a0\ufe0f [z_calibration]","text":"

    The following commands are available when a z_calibration config section is enabled (also see the Z-Calibration guide):

    "},{"location":"G-Codes.html#z_tilt","title":"[z_tilt]","text":"

    The following commands are available when the z_tilt config section is enabled.

    "},{"location":"G-Codes.html#z_tilt_adjust","title":"Z_TILT_ADJUST","text":"

    Z_TILT_ADJUST [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>]: This command will probe the points specified in the config and then make independent adjustments to each Z stepper to compensate for tilt. See the PROBE command for details on the optional probe parameters. The optional HORIZONTAL_MOVE_Z value overrides the horizontal_move_z option specified in the config file.

    "},{"location":"G-Codes.html#z_tilt_ng","title":"[z_tilt_ng]","text":"

    The following commands are available when the z_tilt_ng config section is enabled.

    "},{"location":"G-Codes.html#z_tilt_adjust_1","title":"Z_TILT_ADJUST","text":"

    Z_TILT_ADJUST [HORIZONTAL_MOVE_Z=<value>] [<probe_parameter>=<value>] [INCREASING_THRESHOLD=<value>]: This command will probe the points specified in the config and then make independent adjustments to each Z stepper to compensate for tilt. See the PROBE command for details on the optional probe parameters. The optional HORIZONTAL_MOVE_Z value overrides the horizontal_move_z option specified in the config file. INCREASING_THRESHOLD sets the increasing_threshold parameter of z_tilt. The follwing commands are availabe when the parameter \"extra_points\" is configured in the z_tilt_ng section:

    "},{"location":"Hall_Filament_Width_Sensor.html","title":"Hall filament width sensor","text":"

    This document describes Filament Width Sensor host module. Hardware used for developing this host module is based on two Hall linear sensors (ss49e for example). Sensors in the body are located on opposite sides. Principle of operation: two hall sensors work in differential mode, temperature drift same for sensor. Special temperature compensation not needed.

    You can find designs at Thingiverse, an assembly video is also available on Youtube

    To use Hall filament width sensor, read Config Reference and G-Code documentation.

    "},{"location":"Hall_Filament_Width_Sensor.html#how-does-it-work","title":"How does it work?","text":"

    Sensor generates two analog output based on calculated filament width. Sum of output voltage always equals to detected filament width. Host module monitors voltage changes and adjusts extrusion multiplier. I use the aux2 connector on a ramps-like board with the analog11 and analog12 pins. You can use different pins and different boards.

    "},{"location":"Hall_Filament_Width_Sensor.html#template-for-menu-variables","title":"Template for menu variables","text":"
    [menu __main __filament __width_current]\ntype: command\nenable: {'hall_filament_width_sensor' in printer}\nname: Dia: {'%.2F' % printer.hall_filament_width_sensor.Diameter}\nindex: 0\n\n[menu __main __filament __raw_width_current]\ntype: command\nenable: {'hall_filament_width_sensor' in printer}\nname: Raw: {'%4.0F' % printer.hall_filament_width_sensor.Raw}\nindex: 1\n
    "},{"location":"Hall_Filament_Width_Sensor.html#calibration-procedure","title":"Calibration procedure","text":"

    To get raw sensor value you can use menu item or QUERY_RAW_FILAMENT_WIDTH command in terminal.

    1. Insert first calibration rod (1.5 mm size) get first raw sensor value

    2. Insert second calibration rod (2.0 mm size) get second raw sensor value

    3. Save raw sensor values in config parameter Raw_dia1 and Raw_dia2

    "},{"location":"Hall_Filament_Width_Sensor.html#how-to-enable-sensor","title":"How to enable sensor","text":"

    By default, the sensor is disabled at power-on.

    To enable the sensor, issue ENABLE_FILAMENT_WIDTH_SENSOR command or set the enable parameter to true.

    "},{"location":"Hall_Filament_Width_Sensor.html#logging","title":"Logging","text":"

    By default, diameter logging is disabled at power-on.

    Issue ENABLE_FILAMENT_WIDTH_LOG command to start logging and issue DISABLE_FILAMENT_WIDTH_LOG command to stop logging. To enable logging at power-on, set the logging parameter to true.

    Filament diameter is logged on every measurement interval (10 mm by default).

    "},{"location":"Installation.html","title":"Installation","text":"

    These instructions assume the software will run on a linux based host running a Kalico compatible front end. It is recommended that a SBC(Small Board Computer) such as a Raspberry Pi or Debian based Linux device be used as the host machine (see the FAQ for other options).

    For the purposes of these instructions host relates to the Linux device and mcu relates to the printboard. SBC relates to the term Small Board Computer such as the Raspberry Pi.

    "},{"location":"Installation.html#obtain-a-kalico-configuration-file","title":"Obtain a Kalico Configuration File","text":"

    Most Kalico settings are determined by a \"printer configuration file\" printer.cfg, that will be stored on the host. An appropriate configuration file can often be found by looking in the Kalico config directory for a file starting with a \"printer-\" prefix that corresponds to the target printer. The Kalico configuration file contains technical information about the printer that will be needed during the installation.

    If there isn't an appropriate printer configuration file in the Kalico config directory then try searching the printer manufacturer's website to see if they have an appropriate Kalico configuration file.

    If no configuration file for the printer can be found, but the type of printer control board is known, then look for an appropriate config file starting with a \"generic-\" prefix. These example printer board files should allow one to successfully complete the initial installation, but will require some customization to obtain full printer functionality.

    It is also possible to define a new printer configuration from scratch. However, this requires significant technical knowledge about the printer and its electronics. It is recommended that most users start with an appropriate configuration file. If creating a new custom printer configuration file, then start with the closest example config file and use the Kalico config reference for further information.

    "},{"location":"Installation.html#interacting-with-kalico","title":"Interacting with Kalico","text":"

    Kalico is a 3d printer firmware, so it needs some way for the user to interact with it.

    Currently the best choices are front ends that retrieve information through the Moonraker web API and there is also the option to use Octoprint to control Kalico.

    The choice is up to the user on what to use, but the underlying Kalico is the same in all cases. We encourage users to research the options available and make an informed decision.

    "},{"location":"Installation.html#obtaining-an-os-image-for-sbcs","title":"Obtaining an OS image for SBC's","text":"

    There are many ways to obtain an OS image for Kalico for SBC use, most depend on what front end you wish to use. Some manafactures of these SBC boards also provide their own Kalico-centric images.

    The two main Moonraker based front ends are Fluidd and Mainsail, the latter of which has a premade install image \"MainsailOS\", this has the option for Raspberry Pi and some OrangePi variants.

    Fluidd can be installed via KIAUH(Klipper Install And Update Helper), which is explained below and is a 3rd party installer for all things Kalico.

    OctoPrint can be installed via the popular OctoPi image or via KIAUH, this process is explained in OctoPrint.md

    "},{"location":"Installation.html#installing-via-kiauh","title":"Installing via KIAUH","text":"

    Normally you would start with a base image for your SBC, RPiOS Lite for example, or in the case of a x86 Linux device, Ubuntu Server. Please note that Desktop variants are not recommended due to certain helper programs that can stop some Kalico functions working and even mask access to some print boards.

    KIAUH can be used to install Kalico and its associated programs on a variety of Linux based systems that run a form of Debian. More information can be found at https://github.com/dw-0/kiauh

    "},{"location":"Installation.html#building-and-flashing-the-micro-controller","title":"Building and flashing the micro-controller","text":"

    To compile the micro-controller code, start by running these commands on your host device:

    cd ~/klipper/\nmake menuconfig\n

    The comments at the top of the printer configuration file should describe the settings that need to be set during \"make menuconfig\". Open the file in a web browser or text editor and look for these instructions near the top of the file. Once the appropriate \"menuconfig\" settings have been configured, press \"Q\" to exit, and then \"Y\" to save. Then run:

    make\n

    If the comments at the top of the printer configuration file describe custom steps for \"flashing\" the final image to the printer control board then follow those steps and then proceed to configuring OctoPrint.

    Otherwise, the following steps are often used to \"flash\" the printer control board. First, it is necessary to determine the serial port connected to the micro-controller. Run the following:

    ls /dev/serial/by-id/*\n

    It should report something similar to the following:

    /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0\n

    It's common for each printer to have its own unique serial port name. This unique name will be used when flashing the micro-controller. It's possible there may be multiple lines in the above output - if so, choose the line corresponding to the micro-controller. If many items are listed and the choice is ambiguous, unplug the board and run the command again, the missing item will be your print board(see the FAQ for more information).

    For common micro-controllers with STM32 or clone chips, LPC chips and others it is usual that these need an initial Kalico flash via SD card.

    When flashing with this method, it is important to make sure that the print board is not connected with USB to the host, due to some boards being able to feed power back to the board and stopping a flash from occuring.

    For common micro-controllers using Atmega chips, for example the 2560, the code can be flashed with something similar to:

    sudo service klipper stop\nmake flash FLASH_DEVICE=/dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0\nsudo service klipper start\n

    Be sure to update the FLASH_DEVICE with the printer's unique serial port name.

    For common micro-controllers using RP2040 chips, the code can be flashed with something similar to:

    sudo service klipper stop\nmake flash FLASH_DEVICE=first\nsudo service klipper start\n

    It is important to note that RP2040 chips may need to be put into Boot mode before this operation.

    "},{"location":"Installation.html#configuring-kalico","title":"Configuring Kalico","text":"

    The next step is to copy the printer configuration file to the host.

    Arguably the easiest way to set the Kalico configuration file is using the built in editors in Mainsail or Fluidd. These will allow the user to open the configuration examples and save them to be printer.cfg.

    Another option is to use a desktop editor that supports editing files over the \"scp\" and/or \"sftp\" protocols. There are freely available tools that support this (eg, Notepad++, WinSCP, and Cyberduck). Load the printer config file in the editor and then save it as a file named \"printer.cfg\" in the home directory of the pi user (ie, /home/pi/printer.cfg).

    Alternatively, one can also copy and edit the file directly on the host via ssh. That may look something like the following (be sure to update the command to use the appropriate printer config filename):

    cp ~/klipper/config/example-cartesian.cfg ~/printer.cfg\nnano ~/printer.cfg\n

    It's common for each printer to have its own unique name for the micro-controller. The name may change after flashing Kalico, so rerun these steps again even if they were already done when flashing. Run:

    ls /dev/serial/by-id/*\n

    It should report something similar to the following:

    /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0\n

    Then update the config file with the unique name. For example, update the [mcu] section to look something similar to:

    [mcu]\nserial: /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0\n

    After creating and editing the file it will be necessary to issue a \"restart\" command in the command console to load the config. A \"status\" command will report the printer is ready if the Kalico config file is successfully read and the micro-controller is successfully found and configured.

    When customizing the printer config file, it is not uncommon for Kalico to report a configuration error. If an error occurs, make any necessary corrections to the printer config file and issue \"restart\" until \"status\" reports the printer is ready.

    Kalico reports error messages via the command console and via pop up in Fluidd and Mainsail. The \"status\" command can be used to re-report error messages. A log is available and usually located in ~/printer_data/logs this is named klippy.log

    After Kalico reports that the printer is ready, proceed to the config check document to perform some basic checks on the definitions in the config file. See the main documentation reference for other information.

    "},{"location":"Kalico_Additions.html","title":"Kalico additions","text":""},{"location":"Kalico_Additions.html#changes-to-klipper-defaults","title":"Changes to Klipper defaults","text":""},{"location":"Kalico_Additions.html#additional-configuration-options","title":"Additional configuration options","text":""},{"location":"Kalico_Additions.html#enhanced-behavior","title":"Enhanced behavior","text":""},{"location":"Kalico_Additions.html#new-kalico-modules","title":"New Kalico Modules","text":""},{"location":"Kalico_Additions.html#sensorless-homing","title":"Sensorless Homing","text":""},{"location":"Kalico_Additions.html#probes-and-probing","title":"Probes and Probing","text":""},{"location":"Kalico_Additions.html#heaters-fans-and-pid-changes","title":"Heaters, Fans, and PID changes","text":" "},{"location":"Kalico_Additions.html#macros","title":"Macros","text":""},{"location":"Kalico_Additions.html#plugins","title":"Plugins","text":"

    Extend your Kalico installation with custom plugins.

    Your python plugins can now extend klippy/extras adding new modules to Kalico without causing updates to fail due to a \"dirty\" git tree.

    Enable [danger_options] allow_plugin_override: True to override existing extras.

    "},{"location":"Kinematics.html","title":"Kinematics","text":"

    This document provides an overview of how Kalico implements robot motion (its kinematics). The contents may be of interest to both developers interested in working on the Kalico software as well as users interested in better understanding the mechanics of their machines.

    "},{"location":"Kinematics.html#acceleration","title":"Acceleration","text":"

    Kalico implements a constant acceleration scheme whenever the print head changes velocity - the velocity is gradually changed to the new speed instead of suddenly jerking to it. Kalico always enforces acceleration between the tool head and the print. The filament leaving the extruder can be quite fragile - rapid jerks and/or extruder flow changes lead to poor quality and poor bed adhesion. Even when not extruding, if the print head is at the same level as the print then rapid jerking of the head can cause disruption of recently deposited filament. Limiting speed changes of the print head (relative to the print) reduces risks of disrupting the print.

    It is also important to limit acceleration so that the stepper motors do not skip or put excessive stress on the machine. Kalico limits the torque on each stepper by virtue of limiting the acceleration of the print head. Enforcing acceleration at the print head naturally also limits the torque of the steppers that move the print head (the inverse is not always true).

    Kalico implements constant acceleration. The key formula for constant acceleration is:

    velocity(time) = start_velocity + accel*time\n
    "},{"location":"Kinematics.html#trapezoid-generator","title":"Trapezoid generator","text":"

    Kalico uses a traditional \"trapezoid generator\" to model the motion of each move - each move has a start speed, it accelerates to a cruising speed at constant acceleration, it cruises at a constant speed, and then decelerates to the end speed using constant acceleration.

    It's called a \"trapezoid generator\" because a velocity diagram of the move looks like a trapezoid.

    The cruising speed is always greater than or equal to both the start speed and the end speed. The acceleration phase may be of zero duration (if the start speed is equal to the cruising speed), the cruising phase may be of zero duration (if the move immediately starts decelerating after acceleration), and/or the deceleration phase may be of zero duration (if the end speed is equal to the cruising speed).

    "},{"location":"Kinematics.html#look-ahead","title":"Look-ahead","text":"

    The \"look-ahead\" system is used to determine cornering speeds between moves.

    Consider the following two moves contained on an XY plane:

    In the above situation it is possible to fully decelerate after the first move and then fully accelerate at the start of the next move, but that is not ideal as all that acceleration and deceleration would greatly increase the print time and the frequent changes in extruder flow would result in poor print quality.

    To solve this, the \"look-ahead\" mechanism queues multiple incoming moves and analyzes the angles between moves to determine a reasonable speed that can be obtained during the \"junction\" between two moves. If the next move is nearly in the same direction then the head need only slow down a little (if at all).

    However, if the next move forms an acute angle (the head is going to travel in nearly a reverse direction on the next move) then only a small junction speed is permitted.

    The junction speeds are determined using \"approximated centripetal acceleration\". Best described by the author. However, in Kalico, junction speeds are configured by specifying the desired speed that a 90\u00b0 corner should have (the \"square corner velocity\"), and the junction speeds for other angles are derived from that.

    Key formula for look-ahead:

    end_velocity^2 = start_velocity^2 + 2*accel*move_distance\n
    "},{"location":"Kinematics.html#minimum-cruise-ratio","title":"Minimum cruise ratio","text":"

    Kalico also implements a mechanism for smoothing out the motions of short \"zigzag\" moves. Consider the following moves:

    In the above, the frequent changes from acceleration to deceleration can cause the machine to vibrate which causes stress on the machine and increases the noise. Kalico implements a mechanism to ensure there is always some movement at a cruising speed between acceleration and deceleration. This is done by reducing the top speed of some moves (or sequence of moves) to ensure there is a minimum distance traveled at cruising speed relative to the distance traveled during acceleration and deceleration.

    Kalico implements this feature by tracking both a regular move acceleration as well as a virtual \"acceleration to deceleration\" rate:

    Specifically, the code calculates what the velocity of each move would be if it were limited to this virtual \"acceleration to deceleration\" rate. In the above picture the dashed gray lines represent this virtual acceleration rate for the first move. If a move can not reach its full cruising speed using this virtual acceleration rate then its top speed is reduced to the maximum speed it could obtain at this virtual acceleration rate.

    For most moves the limit will be at or above the move's existing limits and no change in behavior is induced. For short zigzag moves, however, this limit reduces the top speed. Note that it does not change the actual acceleration within the move - the move continues to use the normal acceleration scheme up to its adjusted top-speed.

    "},{"location":"Kinematics.html#generating-steps","title":"Generating steps","text":"

    Once the look-ahead process completes, the print head movement for the given move is fully known (time, start position, end position, velocity at each point) and it is possible to generate the step times for the move. This process is done within \"kinematic classes\" in the Kalico code. Outside of these kinematic classes, everything is tracked in millimeters, seconds, and in cartesian coordinate space. It's the task of the kinematic classes to convert from this generic coordinate system to the hardware specifics of the particular printer.

    Kalico uses an iterative solver to generate the step times for each stepper. The code contains the formulas to calculate the ideal cartesian coordinates of the head at each moment in time, and it has the kinematic formulas to calculate the ideal stepper positions based on those cartesian coordinates. With these formulas, Kalico can determine the ideal time that the stepper should be at each step position. The given steps are then scheduled at these calculated times.

    The key formula to determine how far a move should travel under constant acceleration is:

    move_distance = (start_velocity + .5 * accel * move_time) * move_time\n

    and the key formula for movement with constant velocity is:

    move_distance = cruise_velocity * move_time\n

    The key formulas for determining the cartesian coordinate of a move given a move distance is:

    cartesian_x_position = start_x + move_distance * total_x_movement / total_movement\ncartesian_y_position = start_y + move_distance * total_y_movement / total_movement\ncartesian_z_position = start_z + move_distance * total_z_movement / total_movement\n
    "},{"location":"Kinematics.html#cartesian-robots","title":"Cartesian Robots","text":"

    Generating steps for cartesian printers is the simplest case. The movement on each axis is directly related to the movement in cartesian space.

    Key formulas:

    stepper_x_position = cartesian_x_position\nstepper_y_position = cartesian_y_position\nstepper_z_position = cartesian_z_position\n
    "},{"location":"Kinematics.html#corexy-robots","title":"CoreXY Robots","text":"

    Generating steps on a CoreXY machine is only a little more complex than basic cartesian robots. The key formulas are:

    stepper_a_position = cartesian_x_position + cartesian_y_position\nstepper_b_position = cartesian_x_position - cartesian_y_position\nstepper_z_position = cartesian_z_position\n
    "},{"location":"Kinematics.html#delta-robots","title":"Delta Robots","text":"

    Step generation on a delta robot is based on Pythagoras's theorem:

    stepper_position = (sqrt(arm_length^2\n\n                         - (cartesian_x_position - tower_x_position)^2\n                         - (cartesian_y_position - tower_y_position)^2)\n                    + cartesian_z_position)\n
    "},{"location":"Kinematics.html#stepper-motor-acceleration-limits","title":"Stepper motor acceleration limits","text":"

    With delta kinematics it is possible for a move that is accelerating in cartesian space to require an acceleration on a particular stepper motor greater than the move's acceleration. This can occur when a stepper arm is more horizontal than vertical and the line of movement passes near that stepper's tower. Although these moves could require a stepper motor acceleration greater than the printer's maximum configured move acceleration, the effective mass moved by that stepper would be smaller. Thus the higher stepper acceleration does not result in significantly higher stepper torque and it is therefore considered harmless.

    However, to avoid extreme cases, Kalico enforces a maximum ceiling on stepper acceleration of three times the printer's configured maximum move acceleration. (Similarly, the maximum velocity of the stepper is limited to three times the maximum move velocity.) In order to enforce this limit, moves at the extreme edge of the build envelope (where a stepper arm may be nearly horizontal) will have a lower maximum acceleration and velocity.

    "},{"location":"Kinematics.html#extruder-kinematics","title":"Extruder kinematics","text":"

    Kalico implements extruder motion in its own kinematic class. Since the timing and speed of each print head movement is fully known for each move, it's possible to calculate the step times for the extruder independently from the step time calculations of the print head movement.

    Basic extruder movement is simple to calculate. The step time generation uses the same formulas that cartesian robots use:

    stepper_position = requested_e_position\n
    "},{"location":"Kinematics.html#pressure-advance","title":"Pressure advance","text":"

    Experimentation has shown that it's possible to improve the modeling of the extruder beyond the basic extruder formula. In the ideal case, as an extrusion move progresses, the same volume of filament should be deposited at each point along the move and there should be no volume extruded after the move. Unfortunately, it's common to find that the basic extrusion formulas cause too little filament to exit the extruder at the start of extrusion moves and for excess filament to extrude after extrusion ends. This is often referred to as \"ooze\".

    The \"pressure advance\" system attempts to account for this by using a different model for the extruder. Instead of naively believing that each mm^3 of filament fed into the extruder will result in that amount of mm^3 immediately exiting the extruder, it uses a model based on pressure. Pressure increases when filament is pushed into the extruder (as in Hooke's law) and the pressure necessary to extrude is dominated by the flow rate through the nozzle orifice (as in Poiseuille's law). The key idea is that the relationship between filament, pressure, and flow rate can be modeled using a linear coefficient:

    pa_position = nominal_position + pressure_advance_coefficient * nominal_velocity\n

    See the pressure advance document for information on how to find this pressure advance coefficient.

    The basic pressure advance formula can cause the extruder motor to make sudden velocity changes. Kalico implements \"smoothing\" of the extruder movement to avoid this.

    The above graph shows an example of two extrusion moves with a non-zero cornering velocity between them. Note that the pressure advance system causes additional filament to be pushed into the extruder during acceleration. The higher the desired filament flow rate, the more filament must be pushed in during acceleration to account for pressure. During head deceleration the extra filament is retracted (the extruder will have a negative velocity).

    The \"smoothing\" is implemented using a weighted average of the extruder position over a small time period (as specified by the pressure_advance_smooth_time config parameter). This averaging can span multiple g-code moves. Note how the extruder motor will start moving prior to the nominal start of the first extrusion move and will continue to move after the nominal end of the last extrusion move.

    Key formula for \"smoothed pressure advance\":

    smooth_pa_position(t) =\n    ( definitive_integral(pa_position(x) * (smooth_time/2 - abs(t - x)) * dx,\n                          from=t-smooth_time/2, to=t+smooth_time/2)\n     / (smooth_time/2)^2 )\n
    "},{"location":"MCU_Commands.html","title":"MCU commands","text":"

    This document provides information on the low-level micro-controller commands that are sent from the Kalico \"host\" software and processed by the Kalico micro-controller software. This document is not an authoritative reference for these commands, nor is it an exclusive list of all available commands.

    This document may be useful for developers interested in understanding the low-level micro-controller commands.

    See the protocol document for more information on the format of commands and their transmission. The commands here are described using their \"printf\" style syntax - for those unfamiliar with that format, just note that where a '%...' sequence is seen it should be replaced with an actual integer. For example, a description with \"count=%c\" could be replaced with the text \"count=10\". Note that parameters that are considered \"enumerations\" (see the above protocol document) take a string value which is automatically converted to an integer value for the micro-controller. This is common with parameters named \"pin\" (or that have a suffix of \"_pin\").

    "},{"location":"MCU_Commands.html#startup-commands","title":"Startup Commands","text":"

    It may be necessary to take certain one-time actions to configure the micro-controller and its peripherals. This section lists common commands available for that purpose. Unlike most micro-controller commands, these commands run as soon as they are received and they do not require any particular setup.

    Common startup commands:

    "},{"location":"MCU_Commands.html#low-level-micro-controller-configuration","title":"Low-level micro-controller configuration","text":"

    Most commands in the micro-controller require an initial setup before they can be successfully invoked. This section provides an overview of the configuration process. This section and the following sections are likely only of interest to developers interested in the internal details of Kalico.

    When the host first connects to the micro-controller it always starts by obtaining a data dictionary (see protocol for more information). After the data dictionary is obtained the host will check if the micro-controller is in a \"configured\" state and configure it if not. Configuration involves the following phases:

    "},{"location":"MCU_Commands.html#common-micro-controller-objects","title":"Common micro-controller objects","text":"

    This section lists some commonly used config commands.

    "},{"location":"MCU_Commands.html#common-commands","title":"Common commands","text":"

    This section lists some commonly used run-time commands. It is likely only of interest to developers looking to gain insight into Kalico.

    "},{"location":"MCU_Commands.html#stepper-commands","title":"Stepper commands","text":" "},{"location":"MCU_Commands.html#move-queue","title":"Move queue","text":"

    Each queue_step command utilizes an entry in the micro-controller \"move queue\". This queue is allocated when it receives the \"finalize_config\" command, and it reports the number of available queue entries in \"config\" response messages.

    It is the responsibility of the host to ensure that there is available space in the queue before sending a queue_step command. The host does this by calculating when each queue_step command completes and scheduling new queue_step commands accordingly.

    "},{"location":"MCU_Commands.html#spi-commands","title":"SPI Commands","text":" "},{"location":"MPC.html","title":"Model Predictive Control","text":"

    Model Predictive Control (MPC) is an advanced temperature control method that offers an alternative to traditional PID control. MPC leverages a system model to simulate the temperature of the hotend and adjusts the heater power to align with the target temperature.

    Unlike reactive methods, MPC operates proactively, adjusting in anticipation of temperature fluctuations. It utilizes a model of the hotend, considering factors such as the thermal masses of the system, heater power, heat loss to ambient air, and fans, and heat transfer into the filament. This model allows MPC to predict the amount of heat energy that will be dissipated from the hotend over a given duration, and it compensates for this by adjusting the heater power accordingly. As a result, MPC can accurately calculate the necessary heat energy input to maintain a steady temperature or to transition to a new temperature.

    MPC offers several advantages over PID control:

    Caution

    This feature controls the portions of the 3D printer that can get very hot. All standard Kalico warnings apply. Please report all issues and bugs to GitHub or Discord.

    "},{"location":"MPC.html#basic-configuration","title":"Basic Configuration","text":"

    To use MPC as the temperature controller for the extruder use the following basic configuration block.

    [extruder]\ncontrol: mpc\nheater_power: 50  \ncooling_fan:\nfilament_diameter: 1.75\nfilament_density: 1.20\nfilament_heat_capacity: 1.8 \n
    "},{"location":"MPC.html#optional-config-parameters","title":"Optional Config Parameters","text":"

    These can be specified in the config but should not need to be changed from the default values for most users.

    "},{"location":"MPC.html#ptc-heater-power","title":"PTC Heater Power","text":"

    The heater power: for PTC style heaters is recommended to be set at the normal print temperature for the printer. Some common PTC heaters are given below for reference. If your heater is not listed the manufacturer should be able to provide a temperature and power curve.

    Heater Temp (C) Rapido 2 (W) Rapido 1 (W) Dragon Ace old (W) Dragon Ace new (W) Revo 40 (W) Revo 60 (W) 180 72 52 51 66 30 45 200 70 51 48 63 29 44 220 67 50 46 60 28 43 240 65 49 44 58 28 42 260 64 48 43 55 27 40 280 62 47 41 53 27 39 300 60 46 39 51 26 38"},{"location":"MPC.html#filament-feed-forward-configuration","title":"Filament Feed Forward Configuration","text":"

    The filament feed forward (FFF) feature allows MPC to look forward and see changes in extrusion rates which could require more or less heat input to maintain target temperature. This feature substantially improves the accuracy and responsiveness of the model during printing. It is enabled by default and can be defined is more detail with the filament_density and filament_heat_capacity config parameters. The default values are set to cover a wide range of standard materials including ABS, ASA, PLA, PETG.

    FFF parameters can be set, for the printer session, via the MPC_SET G-Code command:

    MPC_SET HEATER=<heater> FILAMENT_DENSITY=<value> FILAMENT_HEAT_CAPACITY=<value> [FILAMENT_TEMP=<sensor|ambient|<value>>]

    For example, updating the filament material properties for ASA would be: 

    MPC_SET HEATER=extruder FILAMENT_DENSITY=1.07 FILAMENT_HEAT_CAPACITY=1.7  \n
    "},{"location":"MPC.html#filament-physical-properties","title":"Filament Physical Properties","text":"

    MPC works best knowing how much energy (in Joules) it takes to heat 1mm of filament by 1\u00b0C. The material values from the tables below have been curated from popular filament manufacturers and material data references. These values are sufficient for MPC to implement the FFF feature. Advanced users could tune the filament_density and filament_heat_capacity parameters based on manufacturers datasheets.

    "},{"location":"MPC.html#common-materials","title":"Common Materials","text":"Material Density [g/cm\u00b3] Specific heat [J/g/K] PLA 1.25 1.8 - 2.2 PETG 1.27 1.7 - 2.2 PC+ABS 1.15 1.5 - 2.2 ABS 1.06 1.25 - 2.4 ASA 1.07 1.3 - 2.1 PA6 1.12 2 - 2.5 PA 1.15 2 - 2.5 PC 1.20 1.1 - 1.9 TPU 1.21 1.5 - 2 TPU-90A 1.15 1.5 - 2 TPU-95A 1.22 1.5 - 2"},{"location":"MPC.html#common-carbon-fiber-filled-materials","title":"Common Carbon Fiber Filled Materials","text":"Material Density [g/cm\u00b3] Specific heat [J/g/K] ABS-CF 1.11 ^ ASA-CF 1.11 ^ PA6-CF 1.19 ^ PC+ABS-CF 1.22 ^ PC+CF 1.36 ^ PLA-CF 1.29 ^ PETG-CF 1.30 ^

    ^ Use the specific heat from the base polymer

    "},{"location":"MPC.html#calibration","title":"Calibration","text":"

    The MPC default calibration routine takes the following steps:

    1. Cool to ambient: The calibration routine needs to know the approximate ambient temperature and waits until the hotend temperature stabilises and stops decreasing relative to ambient.
    2. Heat past 200\u00b0C: Measure the point where the temperature is increasing most rapidly, and the time and temperature at that point. Also, three temperature measurements are needed at some point after the initial latency has taken effect.
    3. Hold temperature while measuring ambient heat-loss: At this point enough is known for the MPC algorithm to engage. The calibration routine makes a best guess at the overshoot past 200\u00b0C which will occur and targets this temperature for about a minute while ambient heat-loss is measured without and with the fan engaged (if a cooling_fan is specified).
    4. The MPC calibration routine creates the appropriate model constants. At this time the model parameters are temporary and not yet saved to the printer configuration.

    The MPC calibration routine must be run for each heater, to be controlled by MPC, in order to determine the model parameters. For an MPC calibration to be successful an extruder must be able to reach 200C. Calibration is performed with the following G-code command.

    MPC_CALIBRATE HEATER=<heater> [TARGET=<temperature>] [FAN_BREAKPOINTS=<value>]

    Default calibration of the hotend with seven fan breakpoints: 

    MPC_CALIBRATE HEATER=extruder FAN_BREAKPOINTS=7\n

    Note

    Ensure that the part cooling fan is off before starting calibration.

    After successful calibration the method will generate the key model parameters into the log for future reference.

    A SAVE_CONFIG command is then required to commit these calibrated model parameters to the printer config or the user can manually update the values. The SAVE_CONFIG block should then look like: 

    #*# <----------- SAVE_CONFIG ----------->\n#*# DO NOT EDIT THIS BLOCK OR BELOW. The contents are auto-generated.\n#*# [extruder]\n#*# control = mpc\n#*# block_heat_capacity = 22.3110\n#*# sensor_responsiveness = 0.0998635\n#*# ambient_transfer = 0.155082\n#*# fan_ambient_transfer=0.155082, 0.20156, 0.216441\n

    Note

    If the [extruder] section is in a .cfg file other than printer.cfg the SAVE_CONFIG command may not be able to write the calibration parameters and klippy will provide an error.

    These model parameters are not suitable for pre-configuration or are not explicitly determinable. Advanced users could tweak these post calibration based on the following guidance: Slightly increasing these values will increase the temperature where MPC settles and slightly decreasing them will decrease the settling temperature.

    "},{"location":"MPC.html#support-macros","title":"Support Macros","text":""},{"location":"MPC.html#temperature-wait","title":"Temperature Wait","text":"

    The following macro can be used to replace M109 hotend temperature set and M190 bed temperature set G-code commands with a macro utilizing temperature_wait G-codes. This can be utilized in systems where the sensor temperature takes an extended time to converge on the set temperature.

    Note

    This behaviour occurs primarily because MPC controls the modelled block temperature and not the hotend temperature sensor. For almost all cases, when temperature sensor overshoot/undershoot occurs, the block modelled temperature will be correctly at the set temperature. However, the Kalico system performs actions based on the sensor temperature only which can lead to undesirable delays in print actions with stock M109 and M190 commands.

    [gcode_macro M109] # Wait Hotend Temp\nrename_existing: M109.1\ngcode:\n    #Parameters\n    {% set s = params.S|float %}\n\n    M104 {% for p in params %}{'%s%s' % (p, params[p])}{% endfor %}  # Set hotend temp\n    {% if s != 0 %}\n        TEMPERATURE_WAIT SENSOR=extruder MINIMUM={s-2} MAXIMUM={s+5}   # Wait for hotend temp (within n degrees)\n    {% endif %}\n\n\n[gcode_macro M190] # Wait Bed Temp\nrename_existing: M190.1\ngcode:\n    #Parameters\n    {% set s = params.S|float %}\n\n    M140 {% for p in params %}{'%s%s' % (p, params[p])}{% endfor %}   # Set bed temp\n    {% if s != 0 %}\n        TEMPERATURE_WAIT SENSOR=heater_bed MINIMUM={s-2} MAXIMUM={s+5}  # Wait for bed temp (within n degrees)\n    {% endif %}\n
    "},{"location":"MPC.html#setting-fff-parameters-from-the-slicer","title":"Setting FFF Parameters From The Slicer","text":"

    This macro will set FFF parameters automatically when the material type is passed from the slicer. 

    [gcode_macro _SET_MPC_MATERIAL]\ndescription: Set heater MPC parameters for a given material\nvariable_filament_table:\n    ## Update this table to adjust material settings\n    {\n        ## ( density, heat capacity )  # suggested heat capacity range\n        \"PLA\"       : ( 1.25, 2.20 ),  # 1.80 - 2.20\n        \"PETG\"      : ( 1.27, 2.20 ),  # 1.70 - 2.20\n        \"PC+ABS\"    : ( 1.15, 2.20 ),  # 1.50 - 2.20\n        \"ABS\"       : ( 1.06, 2.40 ),  # 1.25 - 2.40\n        \"ASA\"       : ( 1.07, 2.10 ),  # 1.30 - 2.10\n        \"PA6\"       : ( 1.12, 2.50 ),  # 2.00 - 2.50\n        \"PA\"        : ( 1.15, 2.50 ),  # 2.00 - 2.50\n        \"PC\"        : ( 1.20, 1.90 ),  # 1.10 - 1.90\n        \"TPU\"       : ( 1.21, 2.00 ),  # 1.50 - 2.00\n        \"TPU-90A\"   : ( 1.15, 2.00 ),  # 1.50 - 2.00\n        \"TPU-95A\"   : ( 1.22, 2.00 ),  # 1.50 - 2.00\n        \"ABS-CF\"    : ( 1.11, 2.40 ),  # 1.25 - 2.40\n        \"ASA-CF\"    : ( 1.11, 2.10 ),  # 1.30 - 2.10\n        \"PA6-CF\"    : ( 1.19, 2.50 ),  # 2.00 - 2.50\n        \"PC+ABS-CF\" : ( 1.22, 2.20 ),  # 1.50 - 2.20\n        \"PC+CF\"     : ( 1.36, 1.90 ),  # 1.10 - 1.90\n        \"PLA-CF\"    : ( 1.29, 2.20 ),  # 1.80 - 2.20\n        \"PETG-CF\"   : ( 1.30, 2.20 ),  # 1.70 - 2.20\n    }\ngcode:\n    {% set material = params.MATERIAL | upper %}\n    {% set heater = params.HEATER | default('extruder') %}\n    {% set extruder_config = printer.configfile.settings[heater] %}\n\n    {% if material in filament_table %}\n        {% set (density, heat_capacity) = filament_table[material] %}\n\n        RESPOND PREFIX=\ud83d\udd25 MSG=\"Configured {heater} MPC for {material}. Density: {density}, Heat Capacity: {heat_capacity}\"\n    {% else %}\n        {% set density = extruder_config.filament_density %}\n        {% set heat_capacity=extruder_config.filament_heat_capacity %}\n\n        RESPOND PREFIX=\ud83d\udd25 MSG=\"Unknown material '{material}', using default mpc parameters for {heater}\"\n    {% endif %}\n\n    MPC_SET HEATER={heater} FILAMENT_DENSITY={density} FILAMENT_HEAT_CAPACITY={heat_capacity}\n

    The slicer must be configured to pass the current material type to your PRINT_START macro. For PrusaSlicer you should add the following parameter line to print_start in the Start G-Code section:

    MATERIAL=[filament_type[initial_extruder]]\n

    The print_start line, in PrusaSlicer, would look like:

    start_print MATERIAL=[filament_type[initial_extruder]] EXTRUDER_TEMP={first_layer_temperature[initial_extruder]} BED_TEMP={first_layer_bed_temperature[initial_extruder]} CHAMBER_TEMP={chamber_temperature}\n

    Then, in your PRINT_START macro include the following macro call:

    _SET_MPC_MATERIAL MATERIAL={params.MATERIAL}\n
    "},{"location":"MPC.html#real-time-model-state","title":"Real-Time Model State","text":"

    The real-time temperatures and model states can be viewed from a browser by entering the following local address for your computer.

    https://192.168.xxx.xxx:7125/printer/objects/query?extruder\n

    "},{"location":"MPC.html#experimental-features","title":"EXPERIMENTAL FEATURES","text":""},{"location":"MPC.html#bed-heater","title":"Bed Heater","text":"

    Using MPC for bed heater control is functional but the performance is not guaranteed or currently supported. MPC for the bed can be configured simply.

    [heater_bed]\ncontrol: mpc\nheater_power: 400\n

    The bed should be able to reach at least 90C to perform calibration with the following G-code.

    MPC_CALIBRATE HEATER=<heater> [TARGET=<temperature>] [FAN_BREAKPOINTS=<value>]

    Default calibration of the hotend with five fan breakpoints: 

    MPC_CALIBRATE HEATER=heater_bed FAN_BREAKPOINTS=5\n

    These calibrated model parameters need to be saved to the SAVE_CONFIG block manually or by using the SAVE_CONFIG command.

    "},{"location":"MPC.html#updating-calibration-parameters-at-runtime","title":"Updating calibration parameters at runtime","text":"

    Similar to SET_HEATER_PID, you can update your MPC calibration profile at runtime.

    MPC_SET HEATER=<heater_name> [BLOCK_HEAT_CAPACITY=0.0] [SENSOR_RESPONSIVENESS=0.0] [AMBIENT_TRANSFER=0.0] [FAN_AMBIENT_TRANSFER=0.01,0.02,0.03]

    "},{"location":"MPC.html#background","title":"BACKGROUND","text":""},{"location":"MPC.html#mpc-algorithm","title":"MPC Algorithm","text":"

    MPC models the hotend system as four thermal masses: ambient air, the filament, the heater block and the sensor. Heater power heats the modelled heater block directly. Ambient air heats or cools the heater block. Filament cools the heater block. The heater block heats or cools the sensor.

    Every time the MPC algorithm runs it uses the following information to calculate a new temperature for the simulated hotend and sensor:

    Once this calculation is done, the simulated sensor temperature is compared to the measured temperature and a fraction of the difference is added to the modelled sensor and heater block temperatures. This drags the simulated system in the direction of the real system. Because only a fraction of the difference is applied, sensor noise is diminished and averages out to zero over time. Both the simulated and the real sensor exhibit the same (or very similar) latency. Consequently, the effects of latency are eliminated when these values are compared to each other. So, the simulated hotend is only minimally affected by sensor noise and latency.

    SMOOTHING is the factor applied to the difference between simulated and measured sensor temperature. At its maximum value of 1, the simulated sensor temperature is continually set equal to the measured sensor temperature. A lower value will result in greater stability in MPC output power but also in decreased responsiveness. A value around 0.25 seems to work quite well.

    No simulation is perfect and, anyway, real life ambient temperature changes. So MPC also maintains a best guess estimate of ambient temperature. When the simulated system is close to steady state the simulated ambient temperature is continually adjusted. Steady state is determined to be when the MPC algorithm is not driving the hotend at its limits (i.e., full or zero heater power) or when it is at its limit but temperatures are still not changing very much - which will occur at asymptotic temperature (usually when target temperature is zero and the hotend is at ambient).

    Steady_state_rate is used to recognize the asymptotic condition. Whenever the simulated hotend temperature changes at an absolute rate less than steady_state_rate between two successive runs of the algorithm, the steady state logic is applied. Since the algorithm runs frequently, even a small amount of noise can result in a fairly high instantaneous rate of change of hotend temperature. In practice 1\u00b0C/s seems to work well for steady_state_rate.

    When in steady state, the difference between real and simulated sensor temperatures is used to drive the changes to ambient temperature. However, when the temperatures are really close min_ambient_change ensures that the simulated ambient temperature converges relatively quickly. Larger values of min_ambient_change will result in faster convergence but will also cause the simulated ambient temperature to flutter somewhat chaotically around the ideal value. This is not a problem because the effect of ambient temperature is fairly small and short-term variations of even 10\u00b0C or more will not have a noticeable effect.

    It is important to note that the simulated ambient temperature will only converge on real world ambient temperature if the ambient heat transfer coefficients are exactly accurate. In practice this will not be the case and the simulated ambient temperature therefore also acts a correction to these inaccuracies.

    Finally, armed with a new set of temperatures, the MPC algorithm calculates how much power must be applied to get the heater block to target temperature in the next two seconds. This calculation takes into account the heat that is expected to be lost to ambient air and filament heating. This power value is then converted to a PWM output.

    "},{"location":"MPC.html#additional-details","title":"Additional Details","text":"

    Please refer to that the excellent Marlin MPC Documentation for information on the model derivations, tuning methods, and heat transfer coefficients used in this feature.

    "},{"location":"MPC.html#acknowledgements","title":"Acknowledgements","text":"

    This feature is a port of the Marlin MPC implementation, and all credit goes to their team and community for pioneering this feature for open source 3D printing. The Marlin MPC documentation and github pages were heavily referenced and, in some cases directly copied and edited to create this document.

    "},{"location":"Manual_Level.html","title":"Manual leveling","text":"

    This document describes tools for calibrating a Z endstop and for performing adjustments to bed leveling screws.

    "},{"location":"Manual_Level.html#calibrating-a-z-endstop","title":"Calibrating a Z endstop","text":"

    An accurate Z endstop position is critical to obtaining high quality prints.

    Note, though, the accuracy of the Z endstop switch itself can be a limiting factor. If one is using Trinamic stepper motor drivers then consider enabling endstop phase detection to improve the accuracy of the switch.

    To perform a Z endstop calibration, home the printer, command the head to move to a Z position that is at least five millimeters above the bed (if it is not already), command the head to move to an XY position near the center of the bed, then navigate to the OctoPrint terminal tab and run:

    Z_ENDSTOP_CALIBRATE\n

    Then follow the steps described at \"the paper test\" to determine the actual distance between the nozzle and bed at the given location. Once those steps are complete one can ACCEPT the position and save the results to the config file with:

    SAVE_CONFIG\n

    It's preferable to use a Z endstop switch on the opposite end of the Z axis from the bed. (Homing away from the bed is more robust as then it is generally always safe to home the Z.) However, if one must home towards the bed it is recommended to adjust the endstop so that it triggers a small distance (eg, .5mm) above the bed. Almost all endstop switches can safely be depressed a small distance beyond their trigger point. When this is done, one should find that the Z_ENDSTOP_CALIBRATE command reports a small positive value (eg, .5mm) for the Z position_endstop. Triggering the endstop while it is still some distance from the bed reduces the risk of inadvertent bed crashes.

    Some printers have the ability to manually adjust the location of the physical endstop switch. However, it's recommended to perform Z endstop positioning in software with Kalico - once the physical location of the endstop is in a convenient location, one can make any further adjustments by running Z_ENDSTOP_CALIBRATE or by manually updating the Z position_endstop in the configuration file.

    "},{"location":"Manual_Level.html#adjusting-bed-leveling-screws","title":"Adjusting bed leveling screws","text":"

    The secret to getting good bed leveling with bed leveling screws is to utilize the printer's high precision motion system during the bed leveling process itself. This is done by commanding the nozzle to a position near each bed screw and then adjusting that screw until the bed is a set distance from the nozzle. Kalico has a tool to assist with this. In order to use the tool it is necessary to specify each screw XY location.

    This is done by creating a [bed_screws] config section. For example, it might look something similar to:

    [bed_screws]\nscrew1: 100, 50\nscrew2: 100, 150\nscrew3: 150, 100\n

    If a bed screw is under the bed, then specify the XY position directly above the screw. If the screw is outside the bed then specify an XY position closest to the screw that is still within the range of the bed.

    Once the config file is ready, run RESTART to load that config, and then one can start the tool by running:

    BED_SCREWS_ADJUST\n

    This tool will move the printer's nozzle to each screw XY location and then move the nozzle to a Z=0 height. At this point one can use the \"paper test\" to adjust the bed screw directly under the nozzle. See the information described in \"the paper test\", but adjust the bed screw instead of commanding the nozzle to different heights. Adjust the bed screw until there is a small amount of friction when pushing the paper back and forth.

    Once the screw is adjusted so that a small amount of friction is felt, run either the ACCEPT or ADJUSTED command. Use the ADJUSTED command if the bed screw needed an adjustment (typically anything more than about 1/8th of a turn of the screw). Use the ACCEPT command if no significant adjustment is necessary. Both commands will cause the tool to proceed to the next screw. (When an ADJUSTED command is used, the tool will schedule an additional cycle of bed screw adjustments; the tool completes successfully when all bed screws are verified to not require any significant adjustments.) One can use the ABORT command to exit the tool early.

    This system works best when the printer has a flat printing surface (such as glass) and has straight rails. Upon successful completion of the bed leveling tool the bed should be ready for printing.

    "},{"location":"Manual_Level.html#fine-grained-bed-screw-adjustments","title":"Fine grained bed screw adjustments","text":"

    If the printer uses three bed screws and all three screws are under the bed, then it may be possible to perform a second \"high precision\" bed leveling step. This is done by commanding the nozzle to locations where the bed moves a larger distance with each bed screw adjustment.

    For example, consider a bed with screws at locations A, B, and C:

    For each adjustment made to the bed screw at location C, the bed will swing along a pendulum defined by the remaining two bed screws (shown here as a green line). In this situation, each adjustment to the bed screw at C will move the bed at position D a further amount than directly at C. It is thus possible to make an improved C screw adjustment when the nozzle is at position D.

    To enable this feature, one would determine the additional nozzle coordinates and add them to the config file. For example, it might look like:

    [bed_screws]\nscrew1: 100, 50\nscrew1_fine_adjust: 0, 0\nscrew2: 100, 150\nscrew2_fine_adjust: 300, 300\nscrew3: 150, 100\nscrew3_fine_adjust: 0, 100\n

    When this feature is enabled, the BED_SCREWS_ADJUST tool will first prompt for coarse adjustments directly above each screw position, and once those are accepted, it will prompt for fine adjustments at the additional locations. Continue to use ACCEPT and ADJUSTED at each position.

    "},{"location":"Manual_Level.html#adjusting-bed-leveling-screws-using-the-bed-probe","title":"Adjusting bed leveling screws using the bed probe","text":"

    This is another way to calibrate the bed level using the bed probe. To use it you must have a Z probe (BL Touch, Inductive sensor, etc).

    To enable this feature, one would determine the nozzle coordinates such that the Z probe is above the screws, and then add them to the config file. For example, it might look like:

    [screws_tilt_adjust]\nscrew1: -5, 30\nscrew1_name: front left screw\nscrew2: 155, 30\nscrew2_name: front right screw\nscrew3: 155, 190\nscrew3_name: rear right screw\nscrew4: -5, 190\nscrew4_name: rear left screw\nhorizontal_move_z: 10.\nspeed: 50.\nscrew_thread: CW-M3\n

    The screw1 is always the reference point for the others, so the system assumes that screw1 is at the correct height. Always run G28 first and then run SCREWS_TILT_CALCULATE - it should produce output similar to:

    Send: G28\nRecv: ok\nSend: SCREWS_TILT_CALCULATE\nRecv: // 01:20 means 1 full turn and 20 minutes, CW=clockwise, CCW=counter-clockwise\nRecv: // front left screw (base) : x=-5.0, y=30.0, z=2.48750\nRecv: // front right screw : x=155.0, y=30.0, z=2.36000 : adjust CW 01:15\nRecv: // rear right screw : y=155.0, y=190.0, z=2.71500 : adjust CCW 00:50\nRecv: // read left screw : x=-5.0, y=190.0, z=2.47250 : adjust CW 00:02\nRecv: ok\n

    This means that:

    Note that \"minutes\" refers to \"minutes of a clock face\". So, for example, 15 minutes is a quarter of a full turn.

    Repeat the process several times until you get a good level bed - normally when all adjustments are below 6 minutes.

    If using a probe that is mounted on the side of the hotend (that is, it has an X or Y offset) then note that adjusting the bed tilt will invalidate any previous probe calibration that was performed with a tilted bed. Be sure to run probe calibration after the bed screws have been adjusted.

    The MAX_DEVIATION parameter is useful when a saved bed mesh is used, to ensure that the bed level has not drifted too far from where it was when the mesh was created. For example, SCREWS_TILT_CALCULATE MAX_DEVIATION=0.01 can be added to the custom start gcode of the slicer before the mesh is loaded. It will abort the print if the configured limit is exceeded (0.01mm in this example), giving the user a chance to adjust the screws and restart the print.

    The DIRECTION parameter is useful if you can turn your bed adjustment screws in one direction only. For example, you might have screws that start tightened in their lowest (or highest) possible position, which can only be turned in a single direction, to raise (or lower) the bed. If you can only turn the screws clockwise, run SCREWS_TILT_CALCULATE DIRECTION=CW. If you can only turn them counter-clockwise, run SCREWS_TILT_CALCULATE DIRECTION=CCW. A suitable reference point will be chosen such that the bed can be leveled by turning all the screws in the given direction.

    "},{"location":"Measuring_Resonances.html","title":"Measuring Resonances","text":"

    Kalico has built-in support for the ADXL345, MPU-9250 and LIS2DW compatible accelerometers which can be used to measure resonance frequencies of the printer for different axes, and auto-tune input shapers to compensate for resonances. Note that using accelerometers requires some soldering and crimping. The ADXL345/LIS2DW can be connected to the SPI interface of a Raspberry Pi or MCU board (it needs to be reasonably fast). The MPU family can be connected to the I2C interface of a Raspberry Pi directly, or to an I2C interface of an MCU board that supports 400kbit/s fast mode in Kalico.

    When sourcing accelerometers, be aware that there are a variety of different PCB board designs and different clones of them. If it is going to be connected to a 5V printer MCU ensure it has a voltage regulator and level shifters.

    For ADXL345s/LIS2DWs, make sure that the board supports SPI mode (a small number of boards appear to be hard-configured for I2C by pulling SDO to GND).

    For MPU-9250/MPU-9255/MPU-6515/MPU-6050/MPU-6500s there are also a variety of board designs and clones with different I2C pull-up resistors which will need supplementing.

    "},{"location":"Measuring_Resonances.html#mcus-with-kalico-i2c-fast-mode-support","title":"MCUs with Kalico I2C fast-mode Support","text":"MCU Family MCU(s) Tested MCU(s) with Support Raspberry Pi 3B+, Pico 3A, 3A+, 3B, 4 AVR ATmega ATmega328p ATmega32u4, ATmega128, ATmega168, ATmega328, ATmega644p, ATmega1280, ATmega1284, ATmega2560 AVR AT90 - AT90usb646, AT90usb1286"},{"location":"Measuring_Resonances.html#installation-instructions","title":"Installation instructions","text":""},{"location":"Measuring_Resonances.html#wiring","title":"Wiring","text":"

    An ethernet cable with shielded twisted pairs (cat5e or better) is recommended for signal integrity over a long distance. If you still experience signal integrity issues (SPI/I2C errors):

    Connect ethernet cable shielding only to the MCU board/Pi ground.

    Double-check your wiring before powering up to prevent damaging your MCU/Raspberry Pi or the accelerometer.

    "},{"location":"Measuring_Resonances.html#spi-accelerometers","title":"SPI Accelerometers","text":"

    Suggested twisted pair order for three twisted pairs:

    GND+MISO\n3.3V+MOSI\nSCLK+CS\n

    Note that unlike a cable shield, GND must be connected at both ends.

    "},{"location":"Measuring_Resonances.html#adxl345","title":"ADXL345","text":""},{"location":"Measuring_Resonances.html#direct-to-raspberry-pi","title":"Direct to Raspberry Pi","text":"

    Note: Many MCUs will work with an ADXL345 in SPI mode (e.g. Pi Pico), wiring and configuration will vary according to your specific board and available pins.

    You need to connect ADXL345 to your Raspberry Pi via SPI. Note that the I2C connection, which is suggested by ADXL345 documentation, has too low throughput and will not work. The recommended connection scheme:

    ADXL345 pin RPi pin RPi pin name 3V3 (or VCC) 01 3.3V DC power GND 06 Ground CS 24 GPIO08 (SPI0_CE0_N) SDO 21 GPIO09 (SPI0_MISO) SDA 19 GPIO10 (SPI0_MOSI) SCL 23 GPIO11 (SPI0_SCLK)

    Fritzing wiring diagrams for some of the ADXL345 boards:

    "},{"location":"Measuring_Resonances.html#using-raspberry-pi-pico","title":"Using Raspberry Pi Pico","text":"

    You may connect the ADXL345 to your Raspberry Pi Pico and then connect the Pico to your Raspberry Pi via USB. This makes it easy to reuse the accelerometer on other Kalico devices, as you can connect via USB instead of GPIO. The Pico does not have much processing power, so make sure it is only running the accelerometer and not performing any other duties.

    In order to avoid damage to your RPi make sure to connect the ADXL345 to 3.3V only. Depending on the board's layout, a level shifter may be present, which makes 5V dangerous for your RPi.

    ADXL345 pin Pico pin Pico pin name 3V3 (or VCC) 36 3.3V DC power GND 38 Ground CS 2 GP1 (SPI0_CSn) SDO 1 GP0 (SPI0_RX) SDA 5 GP3 (SPI0_TX) SCL 4 GP2 (SPI0_SCK)

    Wiring diagrams for some of the ADXL345 boards:

    "},{"location":"Measuring_Resonances.html#i2c-accelerometers","title":"I2C Accelerometers","text":"

    Suggested twisted pair order for three pairs (preferred):

    3.3V+GND\nSDA+GND\nSCL+GND\n

    or for two pairs:

    3.3V+SDA\nGND+SCL\n

    Note that unlike a cable shield, any GND(s) should be connected at both ends.

    "},{"location":"Measuring_Resonances.html#mpu-9250mpu-9255mpu-6515mpu-6050mpu-6500","title":"MPU-9250/MPU-9255/MPU-6515/MPU-6050/MPU-6500","text":"

    These accelerometers have been tested to work over I2C on the RPi, RP2040 (Pico) and AVR at 400kbit/s (fast mode). Some MPU accelerometer modules include pull-ups, but some are too large at 10K and must be changed or supplemented by smaller parallel resistors.

    Recommended connection scheme for I2C on the Raspberry Pi:

    MPU-9250 pin RPi pin RPi pin name VCC 01 3.3v DC power GND 09 Ground SDA 03 GPIO02 (SDA1) SCL 05 GPIO03 (SCL1)

    The RPi has buit-in 1.8K pull-ups on both SCL and SDA.

    Recommended connection scheme for I2C (i2c0a) on the RP2040:

    MPU-9250 pin RP2040 pin RP2040 pin name VCC 36 3v3 GND 38 Ground SDA 01 GP0 (I2C0 SDA) SCL 02 GP1 (I2C0 SCL)

    The Pico does not include any built-in I2C pull-up resistors.

    "},{"location":"Measuring_Resonances.html#recommended-connection-scheme-for-i2ctwi-on-the-avr-atmega328p-arduino-nano","title":"Recommended connection scheme for I2C(TWI) on the AVR ATmega328P Arduino Nano:","text":"MPU-9250 pin Atmega328P TQFP32 pin Atmega328P pin name Arduino Nano pin VCC 39 - - GND 38 Ground GND SDA 27 SDA A4 SCL 28 SCL A5

    The Arduino Nano does not include any built-in pull-up resistors nor a 3.3V power pin.

    "},{"location":"Measuring_Resonances.html#mounting-the-accelerometer","title":"Mounting the accelerometer","text":"

    The accelerometer must be attached to the toolhead. One needs to design a proper mount that fits their own 3D printer. It is better to align the axes of the accelerometer with the printer's axes (but if it makes it more convenient, axes can be swapped - i.e. no need to align X axis with X and so forth - it should be fine even if Z axis of accelerometer is X axis of the printer, etc.).

    An example of mounting ADXL345 on the SmartEffector:

    Note that on a bed slinger printer one must design 2 mounts: one for the toolhead and one for the bed, and run the measurements twice. See the corresponding section for more details.

    Attention: make sure the accelerometer and any screws that hold it in place do not touch any metal parts of the printer. Basically, the mount must be designed such as to ensure the electrical isolation of the accelerometer from the printer frame. Failing to ensure that can create a ground loop in the system that may damage the electronics.

    "},{"location":"Measuring_Resonances.html#software-installation","title":"Software installation","text":"

    Note that resonance measurements and shaper auto-calibration require additional software dependencies not installed by default. First, run on your Raspberry Pi the following commands:

    sudo apt update\nsudo apt install python3-numpy python3-matplotlib libatlas-base-dev libopenblas-dev\n

    Next, in order to install NumPy in the Kalico environment, run the command:

    ~/klippy-env/bin/pip install -v numpy\n

    Note that, depending on the performance of the CPU, it may take a lot of time, up to 10-20 minutes. Be patient and wait for the completion of the installation. On some occasions, if the board has too little RAM the installation may fail and you will need to enable swap.

    Once installed please check that no errors show from the command:

    ~/klippy-env/bin/python -c 'import numpy;'\n

    The correct output should simply be a new line.

    "},{"location":"Measuring_Resonances.html#configure-adxl345-with-rpi","title":"Configure ADXL345 With RPi","text":"

    First, check and follow the instructions in the RPi Microcontroller document to setup the \"linux mcu\" on the Raspberry Pi. This will configure a second Kalico instance that runs on your Pi.

    Make sure the Linux SPI driver is enabled by running sudo raspi-config and enabling SPI under the \"Interfacing options\" menu.

    Add the following to the printer.cfg file:

    [mcu rpi]\nserial: /tmp/klipper_host_mcu\n\n[adxl345]\ncs_pin: rpi:None\n\n[resonance_tester]\naccel_chip: adxl345\nprobe_points:\n    100, 100, 20  # an example\n

    It is advised to start with 1 probe point, in the middle of the print bed, slightly above it.

    "},{"location":"Measuring_Resonances.html#configure-adxl345-with-pi-pico","title":"Configure ADXL345 With Pi Pico","text":""},{"location":"Measuring_Resonances.html#flash-the-pico-firmware","title":"Flash the Pico Firmware","text":"

    On your Raspberry Pi, compile the firmware for the Pico.

    cd ~/klipper\nmake clean\nmake menuconfig\n

    Now, while holding down the BOOTSEL button on the Pico, connect the Pico to the Raspberry Pi via USB. Compile and flash the firmware.

    make flash FLASH_DEVICE=first\n

    If that fails, you will be told which FLASH_DEVICE to use. In this example, that's make flash FLASH_DEVICE=2e8a:0003.

    "},{"location":"Measuring_Resonances.html#configure-the-connection","title":"Configure the Connection","text":"

    The Pico will now reboot with the new firmware and should show up as a serial device. Find the pico serial device with ls /dev/serial/by-id/*. You can now add an adxl.cfg file with the following settings:

    [mcu adxl]\n# Change <mySerial> to whatever you found above. For example,\n# usb-Klipper_rp2040_E661640843545B2E-if00\nserial: /dev/serial/by-id/usb-Klipper_rp2040_<mySerial>\n\n[adxl345]\ncs_pin: adxl:gpio1\nspi_bus: spi0a\naxes_map: x,z,y\n\n[resonance_tester]\naccel_chip: adxl345\nprobe_points:\n    # Somewhere slightly above the middle of your print bed\n    147,154, 20\n\n[output_pin power_mode] # Improve power stability\npin: adxl:gpio23\n

    If setting up the ADXL345 configuration in a separate file, as shown above, you'll also want to modify your printer.cfg file to include this:

    [include adxl.cfg] # Comment this out when you disconnect the accelerometer\n

    Restart Kalico via the RESTART command.

    "},{"location":"Measuring_Resonances.html#configure-lis2dw-series","title":"Configure LIS2DW series","text":"
    [mcu lis]\n# Change <mySerial> to whatever you found above. For example,\n# usb-Klipper_rp2040_E661640843545B2E-if00\nserial: /dev/serial/by-id/usb-Klipper_rp2040_<mySerial>\n\n[lis2dw]\ncs_pin: lis:gpio1\nspi_bus: spi0a\naxes_map: x,z,y\n\n[resonance_tester]\naccel_chip: lis2dw\nprobe_points:\n    # Somewhere slightly above the middle of your print bed\n    147,154, 20\n
    "},{"location":"Measuring_Resonances.html#configure-mpu-60009000-series-with-rpi","title":"Configure MPU-6000/9000 series With RPi","text":"

    Make sure the Linux I2C driver is enabled and the baud rate is set to 400000 (see Enabling I2C section for more details). Then, add the following to the printer.cfg:

    [mcu rpi]\nserial: /tmp/klipper_host_mcu\n\n[mpu9250]\ni2c_mcu: rpi\ni2c_bus: i2c.1\n\n[resonance_tester]\naccel_chip: mpu9250\nprobe_points:\n    100, 100, 20  # an example\n
    "},{"location":"Measuring_Resonances.html#configure-mpu-9520-compatibles-with-pico","title":"Configure MPU-9520 Compatibles With Pico","text":"

    Pico I2C is set to 400000 on default. Simply add the following to the printer.cfg:

    [mcu pico]\nserial: /dev/serial/by-id/<your Pico's serial ID>\n\n[mpu9250]\ni2c_mcu: pico\ni2c_bus: i2c0a\n\n[resonance_tester]\naccel_chip: mpu9250\nprobe_points:\n    100, 100, 20  # an example\n\n[static_digital_output pico_3V3pwm] # Improve power stability\npins: pico:gpio23\n
    "},{"location":"Measuring_Resonances.html#configure-mpu-9520-compatibles-with-avr","title":"Configure MPU-9520 Compatibles with AVR","text":"

    AVR I2C will be set to 400000 by the mpu9250 option. Simply add the following to the printer.cfg:

    [mcu nano]\nserial: /dev/serial/by-id/<your nano's serial ID>\n\n[mpu9250]\ni2c_mcu: nano\n\n[resonance_tester]\naccel_chip: mpu9250\nprobe_points:\n    100, 100, 20  # an example\n

    Restart Kalico via the RESTART command.

    "},{"location":"Measuring_Resonances.html#measuring-the-resonances","title":"Measuring the resonances","text":""},{"location":"Measuring_Resonances.html#checking-the-setup","title":"Checking the setup","text":"

    Now you can test a connection.

    You should see the current measurements from the accelerometer, including the free-fall acceleration, e.g.

    Recv: // adxl345 values (x, y, z): 470.719200, 941.438400, 9728.196800\n

    If you get an error like Invalid adxl345 id (got xx vs e5), where xx is some other ID, immediately try again. There's an issue with SPI initialization. If you still get an error, it is indicative of the connection problem with ADXL345, or the faulty sensor. Double-check the power, the wiring (that it matches the schematics, no wire is broken or loose, etc.), and soldering quality.

    If you are using a MPU-9250 compatible accelerometer and it shows up as mpu-unknown, use with caution! They are probably refurbished chips!

    Next, try running MEASURE_AXES_NOISE in Octoprint, you should get some baseline numbers for the noise of accelerometer on the axes (should be somewhere in the range of ~1-100). Too high axes noise (e.g. 1000 and more) can be indicative of the sensor issues, problems with its power, or too noisy imbalanced fans on a 3D printer.

    "},{"location":"Measuring_Resonances.html#measuring-the-resonances_1","title":"Measuring the resonances","text":"

    Now you can run some real-life tests. Run the following command:

    TEST_RESONANCES AXIS=X\n

    Note that it will create vibrations on X axis. It will also disable input shaping if it was enabled previously, as it is not valid to run the resonance testing with the input shaper enabled.

    Attention! Be sure to observe the printer for the first time, to make sure the vibrations do not become too violent (M112 command can be used to abort the test in case of emergency; hopefully it will not come to this though). If the vibrations do get too strong, you can attempt to specify a lower than the default value for accel_per_hz parameter in [resonance_tester] section, e.g.

    [resonance_tester]\naccel_chip: adxl345\naccel_per_hz: 50  # default is 75\nprobe_points: ...\n

    If it works for X axis, run for Y axis as well:

    TEST_RESONANCES AXIS=Y\n

    This will generate 2 CSV files (/tmp/resonances_x_*.csv and /tmp/resonances_y_*.csv). These files can be processed with the stand-alone script on a Raspberry Pi. This script is intended to be run with a single CSV file for each axis measured, although it can be used with multiple CSV files if you desire to average the results. Averaging results can be useful, for example, if resonance tests were done at multiple test points. Delete the extra CSV files if you do not desire to average them.

    ~/klippy-env/bin/python ~/klipper/scripts/calibrate_shaper.py /tmp/resonances_x_*.csv -o /tmp/shaper_calibrate_x.png\n~/klippy-env/bin/python ~/klipper/scripts/calibrate_shaper.py /tmp/resonances_y_*.csv -o /tmp/shaper_calibrate_y.png\n

    This script will generate the charts /tmp/shaper_calibrate_x.png and /tmp/shaper_calibrate_y.png with frequency responses. You will also get the suggested frequencies for each input shaper, as well as which input shaper is recommended for your setup. For example:

    Fitted shaper 'zv' frequency = 34.4 Hz (vibrations = 4.0%, smoothing ~= 0.132)\nTo avoid too much smoothing with 'zv', suggested max_accel <= 4500 mm/sec^2\nFitted shaper 'mzv' frequency = 34.6 Hz (vibrations = 0.0%, smoothing ~= 0.170)\nTo avoid too much smoothing with 'mzv', suggested max_accel <= 3500 mm/sec^2\nFitted shaper 'ei' frequency = 41.4 Hz (vibrations = 0.0%, smoothing ~= 0.188)\nTo avoid too much smoothing with 'ei', suggested max_accel <= 3200 mm/sec^2\nFitted shaper '2hump_ei' frequency = 51.8 Hz (vibrations = 0.0%, smoothing ~= 0.201)\nTo avoid too much smoothing with '2hump_ei', suggested max_accel <= 3000 mm/sec^2\nFitted shaper '3hump_ei' frequency = 61.8 Hz (vibrations = 0.0%, smoothing ~= 0.215)\nTo avoid too much smoothing with '3hump_ei', suggested max_accel <= 2800 mm/sec^2\nRecommended shaper is mzv @ 34.6 Hz\n

    The suggested configuration can be added to [input_shaper] section of printer.cfg, e.g.:

    [input_shaper]\nshaper_freq_x: ...\nshaper_type_x: ...\nshaper_freq_y: 34.6\nshaper_type_y: mzv\n\n[printer]\nmax_accel: 3000  # should not exceed the estimated max_accel for X and Y axes\n

    or you can choose some other configuration yourself based on the generated charts: peaks in the power spectral density on the charts correspond to the resonance frequencies of the printer.

    Note that alternatively you can run the input shaper auto-calibration from Kalico directly, which can be convenient, for example, for the input shaper re-calibration.

    "},{"location":"Measuring_Resonances.html#bed-slinger-printers","title":"Bed-slinger printers","text":"

    If your printer is a bed slinger printer, you will need to change the location of the accelerometer between the measurements for X and Y axes: measure the resonances of X axis with the accelerometer attached to the toolhead and the resonances of Y axis - to the bed (the usual bed slinger setup).

    However, you can also connect two accelerometers simultaneously, though the ADXL345 must be connected to different boards (say, to an RPi and printer MCU board), or to two different physical SPI interfaces on the same board (rarely available). Then they can be configured in the following manner:

    [adxl345 hotend]\n# Assuming `hotend` chip is connected to an RPi\ncs_pin: rpi:None\n\n[adxl345 bed]\n# Assuming `bed` chip is connected to a printer MCU board\ncs_pin: ...  # Printer board SPI chip select (CS) pin\n\n[resonance_tester]\n# Assuming the typical setup of the bed slinger printer\naccel_chip_x: adxl345 hotend\naccel_chip_y: adxl345 bed\nprobe_points: ...\n

    Two MPUs can share one I2C bus, but they cannot measure simultaneously as the 400kbit/s I2C bus is not fast enough. One must have its AD0 pin pulled-down to 0V (address 104) and the other its AD0 pin pulled-up to 3.3V (address 105):

    [mpu9250 hotend]\ni2c_mcu: rpi\ni2c_bus: i2c.1\ni2c_address: 104 # This MPU has pin AD0 pulled low\n\n[mpu9250 bed]\ni2c_mcu: rpi\ni2c_bus: i2c.1\ni2c_address: 105 # This MPU has pin AD0 pulled high\n\n[resonance_tester]\n# Assuming the typical setup of the bed slinger printer\naccel_chip_x: mpu9250 hotend\naccel_chip_y: mpu9250 bed\nprobe_points: ...\n

    [Test with each MPU individually before connecting both to the bus for easy debugging.]

    Then the commands TEST_RESONANCES AXIS=X and TEST_RESONANCES AXIS=Y will use the correct accelerometer for each axis.

    "},{"location":"Measuring_Resonances.html#max-smoothing","title":"Max smoothing","text":"

    Keep in mind that the input shaper can create some smoothing in parts. Automatic tuning of the input shaper performed by calibrate_shaper.py script or SHAPER_CALIBRATE command tries not to exacerbate the smoothing, but at the same time they try to minimize the resulting vibrations. Sometimes they can make a sub-optimal choice of the shaper frequency, or maybe you simply prefer to have less smoothing in parts at the expense of a larger remaining vibrations. In these cases, you can request to limit the maximum smoothing from the input shaper.

    Let's consider the following results from the automatic tuning:

    Fitted shaper 'zv' frequency = 57.8 Hz (vibrations = 20.3%, smoothing ~= 0.053)\nTo avoid too much smoothing with 'zv', suggested max_accel <= 13000 mm/sec^2\nFitted shaper 'mzv' frequency = 34.8 Hz (vibrations = 3.6%, smoothing ~= 0.168)\nTo avoid too much smoothing with 'mzv', suggested max_accel <= 3600 mm/sec^2\nFitted shaper 'ei' frequency = 48.8 Hz (vibrations = 4.9%, smoothing ~= 0.135)\nTo avoid too much smoothing with 'ei', suggested max_accel <= 4400 mm/sec^2\nFitted shaper '2hump_ei' frequency = 45.2 Hz (vibrations = 0.1%, smoothing ~= 0.264)\nTo avoid too much smoothing with '2hump_ei', suggested max_accel <= 2200 mm/sec^2\nFitted shaper '3hump_ei' frequency = 48.0 Hz (vibrations = 0.0%, smoothing ~= 0.356)\nTo avoid too much smoothing with '3hump_ei', suggested max_accel <= 1500 mm/sec^2\nRecommended shaper is 2hump_ei @ 45.2 Hz\n

    Note that the reported smoothing values are some abstract projected values. These values can be used to compare different configurations: the higher the value, the more smoothing a shaper will create. However, these smoothing scores do not represent any real measure of smoothing, because the actual smoothing depends on max_accel and square_corner_velocity parameters. Therefore, you should print some test prints to see how much smoothing exactly a chosen configuration creates.

    In the example above the suggested shaper parameters are not bad, but what if you want to get less smoothing on the X axis? You can try to limit the maximum shaper smoothing using the following command:

    ~/klippy-env/bin/python ~/klipper/scripts/calibrate_shaper.py /tmp/resonances_x_*.csv -o /tmp/shaper_calibrate_x.png --max_smoothing=0.2\n

    which limits the smoothing to 0.2 score. Now you can get the following result:

    Fitted shaper 'zv' frequency = 55.4 Hz (vibrations = 19.7%, smoothing ~= 0.057)\nTo avoid too much smoothing with 'zv', suggested max_accel <= 12000 mm/sec^2\nFitted shaper 'mzv' frequency = 34.6 Hz (vibrations = 3.6%, smoothing ~= 0.170)\nTo avoid too much smoothing with 'mzv', suggested max_accel <= 3500 mm/sec^2\nFitted shaper 'ei' frequency = 48.2 Hz (vibrations = 4.8%, smoothing ~= 0.139)\nTo avoid too much smoothing with 'ei', suggested max_accel <= 4300 mm/sec^2\nFitted shaper '2hump_ei' frequency = 52.0 Hz (vibrations = 2.7%, smoothing ~= 0.200)\nTo avoid too much smoothing with '2hump_ei', suggested max_accel <= 3000 mm/sec^2\nFitted shaper '3hump_ei' frequency = 72.6 Hz (vibrations = 1.4%, smoothing ~= 0.155)\nTo avoid too much smoothing with '3hump_ei', suggested max_accel <= 3900 mm/sec^2\nRecommended shaper is 3hump_ei @ 72.6 Hz\n

    If you compare to the previously suggested parameters, the vibrations are a bit larger, but the smoothing is significantly smaller than previously, allowing larger maximum acceleration.

    When deciding which max_smoothing parameter to choose, you can use a trial-and-error approach. Try a few different values and see which results you get. Note that the actual smoothing produced by the input shaper depends, primarily, on the lowest resonance frequency of the printer: the higher the frequency of the lowest resonance - the smaller the smoothing. Therefore, if you request the script to find a configuration of the input shaper with the unrealistically small smoothing, it will be at the expense of increased ringing at the lowest resonance frequencies (which are, typically, also more prominently visible in prints). So, always double-check the projected remaining vibrations reported by the script and make sure they are not too high.

    Note that if you chose a good max_smoothing value for both of your axes, you can store it in the printer.cfg as

    [resonance_tester]\naccel_chip: ...\nprobe_points: ...\nmax_smoothing: 0.25  # an example\n

    Then, if you rerun the input shaper auto-tuning using SHAPER_CALIBRATE Kalico command in the future, it will use the stored max_smoothing value as a reference.

    "},{"location":"Measuring_Resonances.html#selecting-max_accel","title":"Selecting max_accel","text":"

    Since the input shaper can create some smoothing in parts, especially at high accelerations, you will still need to choose the max_accel value that does not create too much smoothing in the printed parts. A calibration script provides an estimate for max_accel parameter that should not create too much smoothing. Note that the max_accel as displayed by the calibration script is only a theoretical maximum at which the respective shaper is still able to work without producing too much smoothing. It is by no means a recommendation to set this acceleration for printing. The maximum acceleration your printer is able to sustain depends on its mechanical properties and the maximum torque of the used stepper motors. Therefore, it is suggested to set max_accel in [printer] section that does not exceed the estimated values for X and Y axes, likely with some conservative safety margin.

    Alternatively, follow this part of the input shaper tuning guide and print the test model to choose max_accel parameter experimentally.

    The same notice applies to the input shaper auto-calibration with SHAPER_CALIBRATE command: it is still necessary to choose the right max_accel value after the auto-calibration, and the suggested acceleration limits will not be applied automatically.

    Keep in mind that the maximum acceleration without too much smoothing depends on the square_corner_velocity. The general recommendation is not to change it from its default value 5.0, and this is the value used by default by the calibrate_shaper.py script. If you did change it though, you should inform the script about it by passing --square_corner_velocity=... parameter, e.g.

    ~/klippy-env/bin/python ~/klipper/scripts/calibrate_shaper.py /tmp/resonances_x_*.csv -o /tmp/shaper_calibrate_x.png --square_corner_velocity=10.0\n

    so that it can calculate the maximum acceleration recommendations correctly. Note that the SHAPER_CALIBRATE command already takes the configured square_corner_velocity parameter into account, and there is no need to specify it explicitly.

    If you are doing a shaper re-calibration and the reported smoothing for the suggested shaper configuration is almost the same as what you got during the previous calibration, this step can be skipped.

    "},{"location":"Measuring_Resonances.html#testing-custom-axes","title":"Testing custom axes","text":"

    TEST_RESONANCES command supports custom axes. While this is not really useful for input shaper calibration, it can be used to study printer resonances in-depth and to check, for example, belt tension.

    To check the belt tension on CoreXY printers, execute

    TEST_RESONANCES AXIS=1,1 OUTPUT=raw_data\nTEST_RESONANCES AXIS=1,-1 OUTPUT=raw_data\n

    and use graph_accelerometer.py to process the generated files, e.g.

    ~/klippy-env/bin/python ~/klipper/scripts/graph_accelerometer.py -c /tmp/raw_data_axis*.csv -o /tmp/resonances.png\n

    which will generate /tmp/resonances.png comparing the resonances.

    For Delta printers with the default tower placement (tower A ~= 210 degrees, B ~= 330 degrees, and C ~= 90 degrees), execute

    TEST_RESONANCES AXIS=0,1 OUTPUT=raw_data\nTEST_RESONANCES AXIS=-0.866025404,-0.5 OUTPUT=raw_data\nTEST_RESONANCES AXIS=0.866025404,-0.5 OUTPUT=raw_data\n

    and then use the same command

    ~/klippy-env/bin/python ~/klipper/scripts/graph_accelerometer.py -c /tmp/raw_data_axis*.csv -o /tmp/resonances.png\n

    to generate /tmp/resonances.png comparing the resonances.

    "},{"location":"Measuring_Resonances.html#input-shaper-auto-calibration","title":"Input Shaper auto-calibration","text":"

    Besides manually choosing the appropriate parameters for the input shaper feature, it is also possible to run the auto-tuning for the input shaper directly from Kalico. Run the following command via Octoprint terminal:

    SHAPER_CALIBRATE\n

    This will run the full test for both axes and generate the csv output (/tmp/calibration_data_*.csv by default) for the frequency response and the suggested input shapers. You will also get the suggested frequencies for each input shaper, as well as which input shaper is recommended for your setup, on Octoprint console. For example:

    Calculating the best input shaper parameters for y axis\nFitted shaper 'zv' frequency = 39.0 Hz (vibrations = 13.2%, smoothing ~= 0.105)\nTo avoid too much smoothing with 'zv', suggested max_accel <= 5900 mm/sec^2\nFitted shaper 'mzv' frequency = 36.8 Hz (vibrations = 1.7%, smoothing ~= 0.150)\nTo avoid too much smoothing with 'mzv', suggested max_accel <= 4000 mm/sec^2\nFitted shaper 'ei' frequency = 36.6 Hz (vibrations = 2.2%, smoothing ~= 0.240)\nTo avoid too much smoothing with 'ei', suggested max_accel <= 2500 mm/sec^2\nFitted shaper '2hump_ei' frequency = 48.0 Hz (vibrations = 0.0%, smoothing ~= 0.234)\nTo avoid too much smoothing with '2hump_ei', suggested max_accel <= 2500 mm/sec^2\nFitted shaper '3hump_ei' frequency = 59.0 Hz (vibrations = 0.0%, smoothing ~= 0.235)\nTo avoid too much smoothing with '3hump_ei', suggested max_accel <= 2500 mm/sec^2\nRecommended shaper_type_y = mzv, shaper_freq_y = 36.8 Hz\n

    If you agree with the suggested parameters, you can execute SAVE_CONFIG now to save them and restart the Kalico. Note that this will not update max_accel value in [printer] section. You should update it manually following the considerations in Selecting max_accel section.

    If your printer is a bed slinger printer, you can specify which axis to test, so that you can change the accelerometer mounting point between the tests (by default the test is performed for both axes):

    SHAPER_CALIBRATE AXIS=Y\n

    You can execute SAVE_CONFIG twice - after calibrating each axis.

    However, if you connected two accelerometers simultaneously, you simply run SHAPER_CALIBRATE without specifying an axis to calibrate the input shaper for both axes in one go.

    "},{"location":"Measuring_Resonances.html#input-shaper-re-calibration","title":"Input Shaper re-calibration","text":"

    SHAPER_CALIBRATE command can be also used to re-calibrate the input shaper in the future, especially if some changes to the printer that can affect its kinematics are made. One can either re-run the full calibration using SHAPER_CALIBRATE command, or restrict the auto-calibration to a single axis by supplying AXIS= parameter, like

    SHAPER_CALIBRATE AXIS=X\n

    Warning! It is not advisable to run the shaper auto-calibration very frequently (e.g. before every print, or every day). In order to determine resonance frequencies, auto-calibration creates intensive vibrations on each of the axes. Generally, 3D printers are not designed to withstand a prolonged exposure to vibrations near the resonance frequencies. Doing so may increase wear of the printer components and reduce their lifespan. There is also an increased risk of some parts unscrewing or becoming loose. Always check that all parts of the printer (including the ones that may normally not move) are securely fixed in place after each auto-tuning.

    Also, due to some noise in measurements, it is possible that the tuning results will be slightly different from one calibration run to another one. Still, it is not expected that the noise will affect the print quality too much. However, it is still advised to double-check the suggested parameters, and print some test prints before using them to confirm they are good.

    "},{"location":"Measuring_Resonances.html#offline-processing-of-the-accelerometer-data","title":"Offline processing of the accelerometer data","text":"

    It is possible to generate the raw accelerometer data and process it offline (e.g. on a host machine), for example to find resonances. In order to do so, run the following commands via Octoprint terminal:

    SET_INPUT_SHAPER SHAPER_FREQ_X=0 SHAPER_FREQ_Y=0\nTEST_RESONANCES AXIS=X OUTPUT=raw_data\n

    ignoring any errors for SET_INPUT_SHAPER command. For TEST_RESONANCES command, specify the desired test axis. The raw data will be written into /tmp directory on the RPi.

    The raw data can also be obtained by running the command ACCELEROMETER_MEASURE command twice during some normal printer activity - first to start the measurements, and then to stop them and write the output file. Refer to G-Codes for more details.

    The data can be processed later by the following scripts: scripts/graph_accelerometer.py and scripts/calibrate_shaper.py. Both of them accept one or several raw csv files as the input depending on the mode. The graph_accelerometer.py script supports several modes of operation:

    Note that graph_accelerometer.py script supports only the raw_data*.csv files and not resonances*.csv or calibration_data*.csv files.

    For example,

    ~/klippy-env/bin/python ~/klipper/scripts/graph_accelerometer.py /tmp/raw_data_x_*.csv -o /tmp/resonances_x.png -c -a z\n

    will plot the comparison of several /tmp/raw_data_x_*.csv files for Z axis to /tmp/resonances_x.png file.

    The shaper_calibrate.py script accepts 1 or several inputs and can run automatic tuning of the input shaper and suggest the best parameters that work well for all provided inputs. It prints the suggested parameters to the console, and can additionally generate the chart if -o output.png parameter is provided, or the CSV file if -c output.csv parameter is specified.

    Providing several inputs to shaper_calibrate.py script can be useful if running some advanced tuning of the input shapers, for example:

    "},{"location":"Migrating_from_Klipper.html","title":"Migrating from Klipper","text":"

    Note

    Any add-on modules you are using will need to be reinstalled after switching to Kalico. This includes things like Beacon support, led-effect, etc.

    Any data in ~/printer_data such as printer configs and macros will be unaffected, THOUGH do back up just in case.

    "},{"location":"Migrating_from_Klipper.html#option-1-manually-clone-the-repository","title":"Option 1. Manually clone the repository","text":"

    If desired, make a backup copy of your existing Klipper installation by running:

    mv ~/klipper ~/klipper_old\n

    Then clone the Kalico repo and restart the klipper service:

    git clone https://github.com/KalicoCrew/kalico.git ~/klipper\nsudo systemctl restart klipper\n
    "},{"location":"Migrating_from_Klipper.html#option-2-using-kiauh","title":"Option 2. Using KIAUH","text":"

    For users that are not comfortable using Git directly, KIAUH v6 is able to use custom repositories.

    To do this, add the Kalico repo to KIAUH's custom repository settings with the following steps:

    From the KIAUH menu select:

    "},{"location":"Migrating_from_Klipper.html#option-3-adding-a-git-remote-to-the-existing-installation","title":"Option 3. Adding a git-remote to the existing installation","text":"

    Can switch back to mainline klipper at any time via a git checkout upstream_main

    cd ~/klipper\ngit remote add kalico https://github.com/KalicoCrew/kalico.git\ngit checkout -b upstream-main origin/master\ngit branch -D master\ngit fetch kalico main\ngit checkout -b main kalico/main\nsudo systemctl restart klipper\nsudo systemctl restart moonraker\n
    "},{"location":"Multi_MCU_Homing.html","title":"Multiple Micro-controller Homing and Probing","text":"

    Kalico supports a mechanism for homing with an endstop attached to one micro-controller while its stepper motors are on a different micro-controller. This support is referred to as \"multi-mcu homing\". This feature is also used when a Z probe is on a different micro-controller than the Z stepper motors.

    This feature can be useful to simplify wiring, as it may be more convenient to attach an endstop or probe to a closer micro-controller. However, using this feature may result in \"overshoot\" of the stepper motors during homing and probing operations.

    The overshoot occurs due to possible message transmission delays between the micro-controller monitoring the endstop and the micro-controllers moving the stepper motors. The Kalico code is designed to limit this delay to no more than 25ms. (When multi-mcu homing is activated, the micro-controllers send periodic status messages and check that corresponding status messages are received within 25ms.)

    So, for example, if homing at 10mm/s then it is possible for an overshoot of up to 0.250mm (10mm/s * .025s == 0.250mm). Care should be taken when configuring multi-mcu homing to account for this type of overshoot. Using slower homing or probing speeds can reduce the overshoot.

    Stepper motor overshoot should not adversely impact the precision of the homing and probing procedure. The Kalico code will detect the overshoot and account for it in its calculations. However, it is important that the hardware design is capable of handling overshoot without causing damage to the machine.

    In order to use this \"multi-mcu homing\" capability the hardware must have predictably low latency between the host computer and all of the micro-controllers. Typically the round-trip time must be consistently less than 10ms. High latency (even for short periods) is likely to result in homing failures.

    Should high latency result in a failure (or if some other communication issue is detected) then Kalico will raise a \"Communication timeout during homing\" error.

    Note that an axis with multiple steppers (eg, stepper_z and stepper_z1) need to be on the same micro-controller in order to use multi-mcu homing. For example, if an endstop is on a separate micro-controller from stepper_z then stepper_z1 must be on the same micro-controller as stepper_z.

    "},{"location":"OctoPrint.html","title":"Using OctoPrint","text":"

    Kalico has a few options for its front ends, Octoprint was the first and original front end for Kalico. This document will give a brief overview of installing with this option.

    "},{"location":"OctoPrint.html#install-with-octopi","title":"Install with OctoPi","text":"

    Start by installing OctoPi on the Raspberry Pi computer. Use OctoPi v0.17.0 or later - see the OctoPi releases for release information.

    One should verify that OctoPi boots and that the OctoPrint web server works. After connecting to the OctoPrint web page, follow the prompt to upgrade OctoPrint if needed.

    After installing OctoPi and upgrading OctoPrint, it will be necessary to ssh into the target machine to run a handful of system commands.

    Start by running these commands on your host device:

    If you do not have git installed, please do so with:

    sudo apt install git\n

    then proceed:

    cd ~\ngit clone https://github.com/KalicoCrew/kalico klipper\n./klipper/scripts/install-octopi.sh\n

    The above will download Kalico, install the needed system dependencies, setup Kalico to run at system startup, and start the Kalico host software. It will require an internet connection and it may take a few minutes to complete.

    "},{"location":"OctoPrint.html#installing-with-kiauh","title":"Installing with KIAUH","text":"

    KIAUH can be used to install OctoPrint on a variety of Linux based systems that run a form of Debian. More information can be found at https://github.com/dw-0/kiauh

    "},{"location":"OctoPrint.html#configuring-octoprint-to-use-kalico","title":"Configuring OctoPrint to use Kalico","text":"

    The OctoPrint web server needs to be configured to communicate with the Kalico host software. Using a web browser, login to the OctoPrint web page and then configure the following items:

    Navigate to the Settings tab (the wrench icon at the top of the page). Under \"Serial Connection\" in \"Additional serial ports\" add:

    ~/printer_data/comms/klippy.serial\n

    Then click \"Save\".

    In some older setups this address may be /tmp/printer, depending on your setup, you may need to keep this line as well

    Enter the Settings tab again and under \"Serial Connection\" change the \"Serial Port\" setting to the one added above.

    In the Settings tab, navigate to the \"Behavior\" sub-tab and select the \"Cancel any ongoing prints but stay connected to the printer\" option. Click \"Save\".

    From the main page, under the \"Connection\" section (at the top left of the page) make sure the \"Serial Port\" is set to the new additional one added and click \"Connect\". (If it is not in the available selection then try reloading the page.)

    Once connected, navigate to the \"Terminal\" tab and type \"status\" (without the quotes) into the command entry box and click \"Send\". The terminal window will likely report there is an error opening the config file - that means OctoPrint is successfully communicating with Kalico.

    Please proceed to Installation.md and the Building and flashing the micro-controller section

    "},{"location":"Overview.html","title":"Overview","text":"

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

    "},{"location":"Overview.html#overview-information","title":"Overview information","text":""},{"location":"Overview.html#installation-and-configuration","title":"Installation and Configuration","text":""},{"location":"Overview.html#developer-documentation","title":"Developer Documentation","text":""},{"location":"Overview.html#device-specific-documents","title":"Device Specific Documents","text":""},{"location":"PID.html","title":"PID","text":"

    PID control is a widely used control method in the 3D printing world. It\u2019s ubiquitous when it comes to temperature control, be it with heaters to generate heat or fans to remove heat. This document aims to provide a high-level overview of what PID is and how to use it best in Kalico.

    "},{"location":"PID.html#pid-calibration","title":"PID Calibration","text":""},{"location":"PID.html#preparing-the-calibration","title":"Preparing the Calibration","text":"

    When a calibration test is performed external influences should be minimized as much as possible:

    More important than listed above, PID how you print. If your part fans are on when printing, PID tune with them on.

    "},{"location":"PID.html#choosing-the-right-pid-algorithm","title":"Choosing the right PID Algorithm","text":"

    Kalico offers two different PID algorithms: Positional and Velocity

    Refer to the control statement in the Configuration Reference.

    "},{"location":"PID.html#running-the-pid-calibration","title":"Running the PID Calibration","text":"

    The PID calibration is invoked via the PID_CALIBRATE command. This command will heat up the respective heater and let it cool down around the target temperature in multiple cycles to determine the needed parameters.

    Such a calibration cycles looks like the following snippet:

    3:12 PM   PID_CALIBRATE HEATER=extruder TARGET=220 TOLERANCE=0.01 WRITE_FILE=1\n3:15 PM   sample:1 pwm:1.0000 asymmetry:3.7519 tolerance:n/a\n3:15 PM   sample:2 pwm:0.6229 asymmetry:0.3348 tolerance:n/a\n3:16 PM   sample:3 pwm:0.5937 asymmetry:0.0840 tolerance:n/a\n3:17 PM   sample:4 pwm:0.5866 asymmetry:0.0169 tolerance:0.4134\n3:18 PM   sample:5 pwm:0.5852 asymmetry:0.0668 tolerance:0.0377\n3:18 PM   sample:6 pwm:0.5794 asymmetry:0.0168 tolerance:0.0142\n3:19 PM   sample:7 pwm:0.5780 asymmetry:-0.1169 tolerance:0.0086\n3:19 PM   PID parameters: pid_Kp=16.538 pid_Ki=0.801 pid_Kd=85.375\n               The SAVE_CONFIG command will update the printer config file\n               with these parameters and restart the printer.\n

    Note the asymmetry information. It provides an indication if the heater's power is sufficient to ensure a symmetrical \"heat up\" versus \"cool down / heat loss\" behavior. It should start positive and converge to zero. A negative starting value indicates that the heat loss is faster than the heat up, this means the system is asymmetrical. The calibration will still be successful but reserves to counter disturbances might be low.

    "},{"location":"PID.html#advanced-manual-calibration","title":"Advanced / Manual Calibration","text":"

    Many methods exist for calculating control parameters, such as Ziegler-Nichols, Cohen-Coon, Kappa-Tau, Lambda, and many more. By default, classical Ziegler-Nichols parameters are generated. If a user wants to experiment with other flavors of Ziegler-Nichols, or Cohen-Coon parameters, they can extract the constants from the log as seen below and enter them into this spreadsheet.

    Ziegler-Nichols constants: Ku=0.103092 Tu=41.800000\nCohen-Coon constants: Km=-17.734845 Theta=6.600000 Tau=-10.182680\n

    Classic Ziegler-Nichols parameters work in all scenarios. Cohen-Coon parameters work better with systems that have a large amount of dead time/delay. For example, if a printer has a bed with a large thermal mass that\u2019s slow to heat up and stabilize, the Cohen-Coon parameters will generally do a better job at controlling it.

    "},{"location":"PID.html#further-readings","title":"Further Readings","text":""},{"location":"PID.html#history","title":"History","text":"

    The first rudimentary PID controller was developed by Elmer Sperry in 1911 to automate the control of a ship's rudder. Engineer Nicolas Minorsky published the first mathematical analysis of a PID controller in 1922. In 1942, John Ziegler & Nathaniel Nichols published their seminal paper, \"Optimum Settings for Automatic Controllers,\" which described a trial-and-error method for tuning a PID controller, now commonly referred to as the \"Ziegler-Nichols method.

    In 1984, Karl Astrom and Tore Hagglund published their paper \"Automatic Tuning of Simple Regulators with Specifications on Phase and Amplitude Margins\". In the paper they introduced an automatic tuning method commonly referred to as the \"Astrom-Hagglund method\" or the \"relay method\".

    In 2019 Brandon Taysom & Carl Sorensen published their paper \"Adaptive Relay Autotuning under Static and Non-static Disturbances with Application to Friction Stir Welding\", which laid out a method to generate more accurate results from a relay test. This is the PID calibration method currently used by Kalico.

    "},{"location":"PID.html#details-of-the-relay-test","title":"Details of the Relay Test","text":"

    As previously mentioned, Kalico uses a relay test for calibration purposes. A standard relay test is conceptually simple. You turn the heater\u2019s power on and off to get it to oscillate about the target temperature, as seen in the following graph.

    The above graph shows a common issue with a standard relay test. If the system being calibrated has too much or too little power for the chosen target temperature, it will produce biased and asymmetric results. As can be seen above, the system spends more time in the off state than on and has a larger amplitude above the target temperature than below.

    In an ideal system, both the on and off times and the amplitude above and below the target temperature would be the same. 3D printers don\u2019t actively cool the hot end or bed, so they can never reach the ideal state.

    The following graph is a relay test based on the methodology laid out by Taysom & Sorensen. After each iteration, the data is analyzed and a new maximum power setting is calculated. As can be seen, the system starts the test asymmetric but ends very symmetric.

    Asymmetry can be monitored in real time during a calibration run. It can also provide insight into how suitable the heater is for the current calibration parameters. When asymmetry starts off positive and converges to zero, the heater has more than enough power to achieve symmetry for the calibration parameters.

    3:12 PM   PID_CALIBRATE HEATER=extruder TARGET=220 TOLERANCE=0.01 WRITE_FILE=1\n3:15 PM   sample:1 pwm:1.0000 asymmetry:3.7519 tolerance:n/a\n3:15 PM   sample:2 pwm:0.6229 asymmetry:0.3348 tolerance:n/a\n3:16 PM   sample:3 pwm:0.5937 asymmetry:0.0840 tolerance:n/a\n3:17 PM   sample:4 pwm:0.5866 asymmetry:0.0169 tolerance:0.4134\n3:18 PM   sample:5 pwm:0.5852 asymmetry:0.0668 tolerance:0.0377\n3:18 PM   sample:6 pwm:0.5794 asymmetry:0.0168 tolerance:0.0142\n3:19 PM   sample:7 pwm:0.5780 asymmetry:-0.1169 tolerance:0.0086\n3:19 PM   PID parameters: pid_Kp=16.538 pid_Ki=0.801 pid_Kd=85.375\n               The SAVE_CONFIG command will update the printer config file\n               with these parameters and restart the printer.\n

    When asymmetry starts off negative, It will not converge to zero. If Kalico does not error out, the calibration run will complete and provide good PID parameters, However the heater is less likely to handle disturbances as well as a heater with power in reserve.

    3:36 PM   PID_CALIBRATE HEATER=extruder TARGET=220 TOLERANCE=0.01 WRITE_FILE=1\n3:38 PM   sample:1 pwm:1.0000 asymmetry:-2.1149 tolerance:n/a\n3:39 PM   sample:2 pwm:1.0000 asymmetry:-2.0140 tolerance:n/a\n3:39 PM   sample:3 pwm:1.0000 asymmetry:-1.8811 tolerance:n/a\n3:40 PM   sample:4 pwm:1.0000 asymmetry:-1.8978 tolerance:0.0000\n3:40 PM   PID parameters: pid_Kp=21.231 pid_Ki=1.227 pid_Kd=91.826\n               The SAVE_CONFIG command will update the printer config file\n               with these parameters and restart the printer.\n
    "},{"location":"PID.html#pid-control-algorithms","title":"Pid Control Algorithms","text":"

    Kalico currently supports two control algorithms: Positional and Velocity. The fundamental difference between the two algorithms is that the Positional algorithm calculates what the PWM value should be for the current time interval, and the Velocity algorithm calculates how much the previous PWM setting should be changed to get the PWM value for the current time interval.

    Positional is the default algorithm, as it will work in every scenario. The Velocity algorithm can provide superior results to the Positional algorithm but requires lower noise sensor readings, or a larger smoothing time setting.

    The most noticeable difference between the two algorithms is that for the same configuration parameters, velocity control will eliminate or drastically reduce overshoot, as seen in the graphs below, as it isn\u2019t susceptible to integral wind-up.

    In some scenarios Velocity control will also be better at holding the heater at its target temperature, and rejecting disturbances. The primary reason for this is that velocity control is more like a standard second order differential equation. It takes into account position, velocity, and acceleration.

    "},{"location":"Packaging.html","title":"Packaging Kalico","text":"

    Kalico is somewhat of a packaging anomaly among python programs, as it doesn't use setuptools to build and install. Some notes regarding how best to package it are as follows:

    "},{"location":"Packaging.html#c-modules","title":"C modules","text":"

    Kalico uses a C module to handle some kinematics calculations more quickly. This module needs to be compiled at packaging time to avoid introducing a runtime dependency on a compiler. To compile the C module, run python3 klippy/chelper/__init__.py.

    "},{"location":"Packaging.html#compiling-python-code","title":"Compiling python code","text":"

    Many distributions have a policy of compiling all python code before packaging to improve startup time. You can do this by running python3 -m compileall klippy.

    "},{"location":"Packaging.html#versioning","title":"Versioning","text":"

    If you are building a package of Kalico from git, it is usual practice not to ship a .git directory, so the versioning must be handled without git. To do this, use the script shipped in scripts/make_version.py which should be run as follows: python3 scripts/make_version.py YOURDISTRONAME > klippy/.version.

    "},{"location":"Packaging.html#sample-packaging-script","title":"Sample packaging script","text":"

    klipper-git is packaged for Arch Linux, and has a PKGBUILD (package build script) available at Arch User Repository.

    "},{"location":"Pressure_Advance.html","title":"Pressure advance","text":"

    This document provides information on tuning the \"pressure advance\" configuration variable for a particular nozzle and filament. The pressure advance feature can be helpful in reducing ooze. For more information on how pressure advance is implemented see the kinematics document.

    "},{"location":"Pressure_Advance.html#tuning-pressure-advance","title":"Tuning pressure advance","text":"

    Pressure advance does two useful things - it reduces ooze during non-extrude moves and it reduces blobbing during cornering. This guide uses the second feature (reducing blobbing during cornering) as a mechanism for tuning.

    In order to calibrate pressure advance the printer must be configured and operational as the tuning test involves printing and inspecting a test object. It is a good idea to read this document in full prior to running the test.

    Use a slicer to generate g-code for the large hollow square found in docs/prints/square_tower.stl. Use a high speed (eg, 100mm/s), zero infill, and a coarse layer height (the layer height should be around 75% of the nozzle diameter). Make sure any \"dynamic acceleration control\" is disabled in the slicer.

    Prepare for the test by issuing the following G-Code command:

    SET_VELOCITY_LIMIT SQUARE_CORNER_VELOCITY=1 ACCEL=500\n

    This command makes the nozzle travel slower through corners to emphasize the effects of extruder pressure. Then for printers with a direct drive extruder run the command:

    TUNING_TOWER COMMAND=SET_PRESSURE_ADVANCE PARAMETER=ADVANCE START=0 FACTOR=.005\n

    For long bowden extruders use:

    TUNING_TOWER COMMAND=SET_PRESSURE_ADVANCE PARAMETER=ADVANCE START=0 FACTOR=.020\n

    Then print the object. When fully printed the test print looks like:

    The above TUNING_TOWER command instructs Kalico to alter the pressure_advance setting on each layer of the print. Higher layers in the print will have a larger pressure advance value set. Layers below the ideal pressure_advance setting will have blobbing at the corners, and layers above the ideal setting can lead to rounded corners and poor extrusion leading up to the corner.

    One can cancel the print early if one observes that the corners are no longer printing well (and thus one can avoid printing layers that are known to be above the ideal pressure_advance value).

    Inspect the print and then use a digital calipers to find the height that has the best quality corners. When in doubt, prefer a lower height.

    The pressure_advance value can then be calculated as pressure_advance = <start> + <measured_height> * <factor>. (For example, 0 + 12.90 * .020 would be .258.)

    It is possible to choose custom settings for START and FACTOR if that helps identify the best pressure advance setting. When doing this, be sure to issue the TUNING_TOWER command at the start of each test print.

    Typical pressure advance values are between 0.050 and 1.000 (the high end usually only with bowden extruders). If there is no significant improvement with a pressure advance up to 1.000, then pressure advance is unlikely to improve the quality of prints. Return to a default configuration with pressure advance disabled.

    Although this tuning exercise directly improves the quality of corners, it's worth remembering that a good pressure advance configuration also reduces ooze throughout the print.

    At the completion of this test, set pressure_advance = <calculated_value> in the [extruder] section of the configuration file and issue a RESTART command. The RESTART command will clear the test state and return the acceleration and cornering speeds to their normal values.

    "},{"location":"Pressure_Advance.html#important-notes","title":"Important Notes","text":" "},{"location":"Probe_Calibrate.html","title":"Probe calibration","text":"

    This document describes the method for calibrating the X, Y, and Z offsets of an \"automatic z probe\" in Kalico. This is useful for users that have a [probe] or [bltouch] section in their config file.

    "},{"location":"Probe_Calibrate.html#calibrating-probe-x-and-y-offsets","title":"Calibrating probe X and Y offsets","text":"

    To calibrate the X and Y offset, navigate to the OctoPrint \"Control\" tab, home the printer, and then use the OctoPrint jogging buttons to move the head to a position near the center of the bed.

    Place a piece of blue painters tape (or similar) on the bed underneath the probe. Navigate to the OctoPrint \"Terminal\" tab and issue a PROBE command:

    PROBE\n

    Place a mark on the tape directly under where the probe is (or use a similar method to note the location on the bed).

    Issue a GET_POSITION command and record the toolhead XY location reported by that command. For example if one sees:

    Recv: // toolhead: X:46.500000 Y:27.000000 Z:15.000000 E:0.000000\n

    then one would record a probe X position of 46.5 and probe Y position of 27.

    After recording the probe position, issue a series of G1 commands until the nozzle is directly above the mark on the bed. For example, one might issue:

    G1 F300 X57 Y30 Z15\n

    to move the nozzle to an X position of 57 and Y of 30. Once one finds the position directly above the mark, use the GET_POSITION command to report that position. This is the nozzle position.

    The x_offset is then the nozzle_x_position - probe_x_position and y_offset is similarly the nozzle_y_position - probe_y_position. Update the printer.cfg file with the given values, remove the tape/marks from the bed, and then issue a RESTART command so that the new values take effect.

    "},{"location":"Probe_Calibrate.html#calibrating-probe-z-offset","title":"Calibrating probe Z offset","text":"

    Providing an accurate probe z_offset is critical to obtaining high quality prints. The z_offset is the distance between the nozzle and bed when the probe triggers. The Kalico PROBE_CALIBRATE tool can be used to obtain this value - it will run an automatic probe to measure the probe's Z trigger position and then start a manual probe to obtain the nozzle Z height. The probe z_offset will then be calculated from these measurements.

    Start by homing the printer and then move the head to a position near the center of the bed. Navigate to the OctoPrint terminal tab and run the PROBE_CALIBRATE command to start the tool.

    This tool will perform an automatic probe, then lift the head, move the nozzle over the location of the probe point, and start the manual probe tool. If the nozzle does not move to a position above the automatic probe point, then ABORT the manual probe tool and perform the XY probe offset calibration described above.

    Once the manual probe tool starts, follow the steps described at \"the paper test\" to determine the actual distance between the nozzle and bed at the given location. Once those steps are complete one can ACCEPT the position and save the results to the config file with:

    SAVE_CONFIG\n

    Note that if a change is made to the printer's motion system, hotend position, or probe location then it will invalidate the results of PROBE_CALIBRATE.

    If the probe has an X or Y offset and the bed tilt is changed (eg, by adjusting bed screws, running DELTA_CALIBRATE, running Z_TILT_ADJUST, running QUAD_GANTRY_LEVEL, or similar) then it will invalidate the results of PROBE_CALIBRATE. After making any of the above adjustments it will be necessary to run PROBE_CALIBRATE again.

    If the results of PROBE_CALIBRATE are invalidated, then any previous bed mesh results that were obtained using the probe are also invalidated - it will be necessary to rerun BED_MESH_CALIBRATE after recalibrating the probe.

    "},{"location":"Probe_Calibrate.html#repeatability-check","title":"Repeatability check","text":"

    After calibrating the probe X, Y, and Z offsets it is a good idea to verify that the probe provides repeatable results. Start by homing the printer and then move the head to a position near the center of the bed. Navigate to the OctoPrint terminal tab and run the PROBE_ACCURACY command.

    This command will run the probe ten times and produce output similar to the following:

    Recv: // probe accuracy: at X:0.000 Y:0.000 Z:10.000\nRecv: // and read 10 times with speed of 5 mm/s\nRecv: // probe at -0.003,0.005 is z=2.506948\nRecv: // probe at -0.003,0.005 is z=2.519448\nRecv: // probe at -0.003,0.005 is z=2.519448\nRecv: // probe at -0.003,0.005 is z=2.506948\nRecv: // probe at -0.003,0.005 is z=2.519448\nRecv: // probe at -0.003,0.005 is z=2.519448\nRecv: // probe at -0.003,0.005 is z=2.506948\nRecv: // probe at -0.003,0.005 is z=2.506948\nRecv: // probe at -0.003,0.005 is z=2.519448\nRecv: // probe at -0.003,0.005 is z=2.506948\nRecv: // probe accuracy results: maximum 2.519448, minimum 2.506948, range 0.012500, average 2.513198, median 2.513198, standard deviation 0.006250\n

    Ideally the tool will report an identical maximum and minimum value. (That is, ideally the probe obtains an identical result on all ten probes.) However, it's normal for the minimum and maximum values to differ by one Z \"step distance\" or up to 5 microns (.005mm). A \"step distance\" is rotation_distance/(full_steps_per_rotation*microsteps). The distance between the minimum and the maximum value is called the range. So, in the above example, since the printer uses a Z step distance of .0125, a range of 0.012500 would be considered normal.

    If the results of the test show a range value that is greater than 25 microns (.025mm) then the probe does not have sufficient accuracy for typical bed leveling procedures. It may be possible to tune the probe speed and/or probe start height to improve the repeatability of the probe. The PROBE_ACCURACY command allows one to run tests with different parameters to see their impact - see the G-Codes document for further details. If the probe generally obtains repeatable results but has an occasional outlier, then it may be possible to account for that by using multiple samples on each probe - read the description of the probe samples config parameters in the config reference for more details.

    If new probe speed, samples count, or other settings are needed, then update the printer.cfg file and issue a RESTART command. If so, it is a good idea to calibrate the z_offset again. If repeatable results can not be obtained then don't use the probe for bed leveling. Kalico has several manual probing tools that can be used instead - see the Bed Level document for further details.

    "},{"location":"Probe_Calibrate.html#location-bias-check","title":"Location Bias Check","text":"

    Some probes can have a systemic bias that corrupts the results of the probe at certain toolhead locations. For example, if the probe mount tilts slightly when moving along the Y axis then it could result in the probe reporting biased results at different Y positions.

    This is a common issue with probes on delta printers, however it can occur on all printers.

    One can check for a location bias by using the PROBE_CALIBRATE command to measuring the probe z_offset at various X and Y locations. Ideally, the probe z_offset would be a constant value at every printer location.

    For delta printers, try measuring the z_offset at a position near the A tower, at a position near the B tower, and at a position near the C tower. For cartesian, corexy, and similar printers, try measuring the z_offset at positions near the four corners of the bed.

    Before starting this test, first calibrate the probe X, Y, and Z offsets as described at the beginning of this document. Then home the printer and navigate to the first XY position. Follow the steps at calibrating probe Z offset to run the PROBE_CALIBRATE command, TESTZ commands, and ACCEPT command, but do not run SAVE_CONFIG. Note the reported z_offset found. Then navigate to the other XY positions, repeat these PROBE_CALIBRATE steps, and note the reported z_offset.

    If the difference between the minimum reported z_offset and the maximum reported z_offset is greater than 25 microns (.025mm) then the probe is not suitable for typical bed leveling procedures. See the Bed Level document for manual probe alternatives.

    "},{"location":"Probe_Calibrate.html#temperature-bias","title":"Temperature Bias","text":"

    Many probes have a systemic bias when probing at different temperatures. For example, the probe may consistently trigger at a lower height when the probe is at a higher temperature.

    It is recommended to run the bed leveling tools at a consistent temperature to account for this bias. For example, either always run the tools when the printer is at room temperature, or always run the tools after the printer has obtained a consistent print temperature. In either case, it is a good idea to wait several minutes after the desired temperature is reached, so that the printer apparatus is consistently at the desired temperature.

    To check for a temperature bias, start with the printer at room temperature and then home the printer, move the head to a position near the center of the bed, and run the PROBE_ACCURACY command. Note the results. Then, without homing or disabling the stepper motors, heat the printer nozzle and bed to printing temperature, and run the PROBE_ACCURACY command again. Ideally, the command will report identical results. As above, if the probe does have a temperature bias then be careful to always use the probe at a consistent temperature.

    "},{"location":"Protocol.html","title":"Protocol","text":"

    The Kalico messaging protocol is used for low-level communication between the Kalico host software and the Kalico micro-controller software. At a high level the protocol can be thought of as a series of command and response strings that are compressed, transmitted, and then processed at the receiving side. An example series of commands in uncompressed human-readable format might look like:

    set_digital_out pin=PA3 value=1\nset_digital_out pin=PA7 value=1\nschedule_digital_out oid=8 clock=4000000 value=0\nqueue_step oid=7 interval=7458 count=10 add=331\nqueue_step oid=7 interval=11717 count=4 add=1281\n

    See the mcu commands document for information on available commands. See the debugging document for information on how to translate a G-Code file into its corresponding human-readable micro-controller commands.

    This page provides a high-level description of the Kalico messaging protocol itself. It describes how messages are declared, encoded in binary format (the \"compression\" scheme), and transmitted.

    The goal of the protocol is to enable an error-free communication channel between the host and micro-controller that is low-latency, low-bandwidth, and low-complexity for the micro-controller.

    "},{"location":"Protocol.html#micro-controller-interface","title":"Micro-controller Interface","text":"

    The Kalico transmission protocol can be thought of as a RPC mechanism between micro-controller and host. The micro-controller software declares the commands that the host may invoke along with the response messages that it can generate. The host uses that information to command the micro-controller to perform actions and to interpret the results.

    "},{"location":"Protocol.html#declaring-commands","title":"Declaring commands","text":"

    The micro-controller software declares a \"command\" by using the DECL_COMMAND() macro in the C code. For example:

    DECL_COMMAND(command_update_digital_out, \"update_digital_out oid=%c value=%c\");\n

    The above declares a command named \"update_digital_out\". This allows the host to \"invoke\" this command which would cause the command_update_digital_out() C function to be executed in the micro-controller. The above also indicates that the command takes two integer parameters. When the command_update_digital_out() C code is executed, it will be passed an array containing these two integers - the first corresponding to the 'oid' and the second corresponding to the 'value'.

    In general, the parameters are described with printf() style syntax (eg, \"%u\"). The formatting directly corresponds to the human-readable view of commands (eg, \"update_digital_out oid=7 value=1\"). In the above example, \"value=\" is a parameter name and \"%c\" indicates the parameter is an integer. Internally, the parameter name is only used as documentation. In this example, the \"%c\" is also used as documentation to indicate the expected integer is 1 byte in size (the declared integer size does not impact the parsing or encoding).

    The micro-controller build will collect all commands declared with DECL_COMMAND(), determine their parameters, and arrange for them to be callable.

    "},{"location":"Protocol.html#declaring-responses","title":"Declaring responses","text":"

    To send information from the micro-controller to the host a \"response\" is generated. These are both declared and transmitted using the sendf() C macro. For example:

    sendf(\"status clock=%u status=%c\", sched_read_time(), sched_is_shutdown());\n

    The above transmits a \"status\" response message that contains two integer parameters (\"clock\" and \"status\"). The micro-controller build automatically finds all sendf() calls and generates encoders for them. The first parameter of the sendf() function describes the response and it is in the same format as command declarations.

    The host can arrange to register a callback function for each response. So, in effect, commands allow the host to invoke C functions in the micro-controller and responses allow the micro-controller software to invoke code in the host.

    The sendf() macro should only be invoked from command or task handlers, and it should not be invoked from interrupts or timers. The code does not need to issue a sendf() in response to a received command, it is not limited in the number of times sendf() may be invoked, and it may invoke sendf() at any time from a task handler.

    "},{"location":"Protocol.html#output-responses","title":"Output responses","text":"

    To simplify debugging, there is also an output() C function. For example:

    output(\"The value of %u is %s with size %u.\", x, buf, buf_len);\n

    The output() function is similar in usage to printf() - it is intended to generate and format arbitrary messages for human consumption.

    "},{"location":"Protocol.html#declaring-enumerations","title":"Declaring enumerations","text":"

    Enumerations allow the host code to use string identifiers for parameters that the micro-controller handles as integers. They are declared in the micro-controller code - for example:

    DECL_ENUMERATION(\"spi_bus\", \"spi\", 0);\n\nDECL_ENUMERATION_RANGE(\"pin\", \"PC0\", 16, 8);\n

    If the first example, the DECL_ENUMERATION() macro defines an enumeration for any command/response message with a parameter name of \"spi_bus\" or parameter name with a suffix of \"_spi_bus\". For those parameters the string \"spi\" is a valid value and it will be transmitted with an integer value of zero.

    It's also possible to declare an enumeration range. In the second example, a \"pin\" parameter (or any parameter with a suffix of \"_pin\") would accept PC0, PC1, PC2, ..., PC7 as valid values. The strings will be transmitted with integers 16, 17, 18, ..., 23.

    "},{"location":"Protocol.html#declaring-constants","title":"Declaring constants","text":"

    Constants can also be exported. For example, the following:

    DECL_CONSTANT(\"SERIAL_BAUD\", 250000);\n

    would export a constant named \"SERIAL_BAUD\" with a value of 250000 from the micro-controller to the host. It is also possible to declare a constant that is a string - for example:

    DECL_CONSTANT_STR(\"MCU\", \"pru\");\n
    "},{"location":"Protocol.html#low-level-message-encoding","title":"Low-level message encoding","text":"

    To accomplish the above RPC mechanism, each command and response is encoded into a binary format for transmission. This section describes the transmission system.

    "},{"location":"Protocol.html#message-blocks","title":"Message Blocks","text":"

    All data sent from host to micro-controller and vice-versa are contained in \"message blocks\". A message block has a two byte header and a three byte trailer. The format of a message block is:

    <1 byte length><1 byte sequence><n-byte content><2 byte crc><1 byte sync>\n

    The length byte contains the number of bytes in the message block including the header and trailer bytes (thus the minimum message length is 5 bytes). The maximum message block length is currently 64 bytes. The sequence byte contains a 4 bit sequence number in the low-order bits and the high-order bits always contain 0x10 (the high-order bits are reserved for future use). The content bytes contain arbitrary data and its format is described in the following section. The crc bytes contain a 16bit CCITT CRC of the message block including the header bytes but excluding the trailer bytes. The sync byte is 0x7e.

    The format of the message block is inspired by HDLC message frames. Like in HDLC, the message block may optionally contain an additional sync character at the start of the block. Unlike in HDLC, a sync character is not exclusive to the framing and may be present in the message block content.

    "},{"location":"Protocol.html#message-block-contents","title":"Message Block Contents","text":"

    Each message block sent from host to micro-controller contains a series of zero or more message commands in its contents. Each command starts with a Variable Length Quantity (VLQ) encoded integer command-id followed by zero or more VLQ parameters for the given command.

    As an example, the following four commands might be placed in a single message block:

    update_digital_out oid=6 value=1\nupdate_digital_out oid=5 value=0\nget_config\nget_clock\n

    and encoded into the following eight VLQ integers:

    <id_update_digital_out><6><1><id_update_digital_out><5><0><id_get_config><id_get_clock>\n

    In order to encode and parse the message contents, both the host and micro-controller must agree on the command ids and the number of parameters each command has. So, in the above example, both the host and micro-controller would know that \"id_update_digital_out\" is always followed by two parameters, and \"id_get_config\" and \"id_get_clock\" have zero parameters. The host and micro-controller share a \"data dictionary\" that maps the command descriptions (eg, \"update_digital_out oid=%c value=%c\") to their integer command-ids. When processing the data, the parser will know to expect a specific number of VLQ encoded parameters following a given command id.

    The message contents for blocks sent from micro-controller to host follow the same format. The identifiers in these messages are \"response ids\", but they serve the same purpose and follow the same encoding rules. In practice, message blocks sent from the micro-controller to the host never contain more than one response in the message block contents.

    "},{"location":"Protocol.html#variable-length-quantities","title":"Variable Length Quantities","text":"

    See the wikipedia article for more information on the general format of VLQ encoded integers. Kalico uses an encoding scheme that supports both positive and negative integers. Integers close to zero use less bytes to encode and positive integers typically encode using less bytes than negative integers. The following table shows the number of bytes each integer takes to encode:

    Integer Encoded size -32 .. 95 1 -4096 .. 12287 2 -524288 .. 1572863 3 -67108864 .. 201326591 4 -2147483648 .. 4294967295 5"},{"location":"Protocol.html#variable-length-strings","title":"Variable length strings","text":"

    As an exception to the above encoding rules, if a parameter to a command or response is a dynamic string then the parameter is not encoded as a simple VLQ integer. Instead it is encoded by transmitting the length as a VLQ encoded integer followed by the contents itself:

    <VLQ encoded length><n-byte contents>\n

    The command descriptions found in the data dictionary allow both the host and micro-controller to know which command parameters use simple VLQ encoding and which parameters use string encoding.

    "},{"location":"Protocol.html#data-dictionary","title":"Data Dictionary","text":"

    In order for meaningful communications to be established between micro-controller and host, both sides must agree on a \"data dictionary\". This data dictionary contains the integer identifiers for commands and responses along with their descriptions.

    The micro-controller build uses the contents of DECL_COMMAND() and sendf() macros to generate the data dictionary. The build automatically assigns unique identifiers to each command and response. This system allows both the host and micro-controller code to seamlessly use descriptive human-readable names while still using minimal bandwidth.

    The host queries the data dictionary when it first connects to the micro-controller. Once the host downloads the data dictionary from the micro-controller, it uses that data dictionary to encode all commands and to parse all responses from the micro-controller. The host must therefore handle a dynamic data dictionary. However, to keep the micro-controller software simple, the micro-controller always uses its static (compiled in) data dictionary.

    The data dictionary is queried by sending \"identify\" commands to the micro-controller. The micro-controller will respond to each identify command with an \"identify_response\" message. Since these two commands are needed prior to obtaining the data dictionary, their integer ids and parameter types are hard-coded in both the micro-controller and the host. The \"identify_response\" response id is 0, the \"identify\" command id is 1. Other than having hard-coded ids the identify command and its response are declared and transmitted the same way as other commands and responses. No other command or response is hard-coded.

    The format of the transmitted data dictionary itself is a zlib compressed JSON string. The micro-controller build process generates the string, compresses it, and stores it in the text section of the micro-controller flash. The data dictionary can be much larger than the maximum message block size - the host downloads it by sending multiple identify commands requesting progressive chunks of the data dictionary. Once all chunks are obtained the host will assemble the chunks, uncompress the data, and parse the contents.

    In addition to information on the communication protocol, the data dictionary also contains the software version, enumerations (as defined by DECL_ENUMERATION), and constants (as defined by DECL_CONSTANT).

    "},{"location":"Protocol.html#message-flow","title":"Message flow","text":"

    Message commands sent from host to micro-controller are intended to be error-free. The micro-controller will check the CRC and sequence numbers in each message block to ensure the commands are accurate and in-order. The micro-controller always processes message blocks in-order - should it receive a block out-of-order it will discard it and any other out-of-order blocks until it receives blocks with the correct sequencing.

    The low-level host code implements an automatic retransmission system for lost and corrupt message blocks sent to the micro-controller. To facilitate this, the micro-controller transmits an \"ack message block\" after each successfully received message block. The host schedules a timeout after sending each block and it will retransmit should the timeout expire without receiving a corresponding \"ack\". In addition, if the micro-controller detects a corrupt or out-of-order block it may transmit a \"nak message block\" to facilitate fast retransmission.

    An \"ack\" is a message block with empty content (ie, a 5 byte message block) and a sequence number greater than the last received host sequence number. A \"nak\" is a message block with empty content and a sequence number less than the last received host sequence number.

    The protocol facilitates a \"window\" transmission system so that the host can have many outstanding message blocks in-flight at a time. (This is in addition to the many commands that may be present in a given message block.) This allows maximum bandwidth utilization even in the event of transmission latency. The timeout, retransmit, windowing, and ack mechanism are inspired by similar mechanisms in TCP.

    In the other direction, message blocks sent from micro-controller to host are designed to be error-free, but they do not have assured transmission. (Responses should not be corrupt, but they may go missing.) This is done to keep the implementation in the micro-controller simple. There is no automatic retransmission system for responses - the high-level code is expected to be capable of handling an occasional missing response (usually by re-requesting the content or setting up a recurring schedule of response transmission). The sequence number field in message blocks sent to the host is always one greater than the last received sequence number of message blocks received from the host. It is not used to track sequences of response message blocks.

    "},{"location":"RPi_microcontroller.html","title":"RPi microcontroller","text":"

    This document describes the process of running Kalico on a RPi and use the same RPi as secondary mcu.

    "},{"location":"RPi_microcontroller.html#why-use-rpi-as-a-secondary-mcu","title":"Why use RPi as a secondary MCU?","text":"

    Often the MCUs dedicated to controlling 3D printers have a limited and pre-configured number of exposed pins to manage the main printing functions (thermal resistors, extruders, steppers ...). Using the RPi where Kalico is installed as a secondary MCU gives the possibility to directly use the GPIOs and the buses (i2c, spi) of the RPi inside Kalico without using Octoprint plugins (if used) or external programs giving the ability to control everything within the print GCODE.

    Warning: If your platform is a Beaglebone and you have correctly followed the installation steps, the linux mcu is already installed and configured for your system.

    "},{"location":"RPi_microcontroller.html#install-the-rc-script","title":"Install the rc script","text":"

    If you want to use the host as a secondary MCU the klipper_mcu process must run before the klippy process.

    After installing Kalico, install the script. run:

    cd ~/klipper/\nsudo cp ./scripts/klipper-mcu.service /etc/systemd/system/\nsudo systemctl enable klipper-mcu.service\n
    "},{"location":"RPi_microcontroller.html#building-the-micro-controller-code","title":"Building the micro-controller code","text":"

    To compile the Kalico micro-controller code, start by configuring it for the \"Linux process\":

    cd ~/klipper/\nmake menuconfig\n

    In the menu, set \"Microcontroller Architecture\" to \"Linux process,\" then save and exit.

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

    sudo service klipper stop\nmake flash\nsudo service klipper start\n

    If klippy.log reports a \"Permission denied\" error when attempting to connect to /tmp/klipper_host_mcu then you need to add your user to the tty group. The following command will add the \"pi\" user to the tty group:

    sudo usermod -a -G tty pi\n
    "},{"location":"RPi_microcontroller.html#remaining-configuration","title":"Remaining configuration","text":"

    Complete the installation by configuring Kalico secondary MCU following the instructions in RaspberryPi sample config and Multi MCU sample config.

    "},{"location":"RPi_microcontroller.html#optional-enabling-spi","title":"Optional: Enabling SPI","text":"

    Make sure the Linux SPI driver is enabled by running sudo raspi-config and enabling SPI under the \"Interfacing options\" menu.

    "},{"location":"RPi_microcontroller.html#optional-enabling-i2c","title":"Optional: Enabling I2C","text":"

    Make sure the Linux I2C driver is enabled by running sudo raspi-config and enabling I2C under the \"Interfacing options\" menu. If planning to use I2C for the MPU accelerometer, it is also required to set the baud rate to 400000 by: adding/uncommenting dtparam=i2c_arm=on,i2c_arm_baudrate=400000 in /boot/config.txt (or /boot/firmware/config.txt in some distros).

    "},{"location":"RPi_microcontroller.html#optional-identify-the-correct-gpiochip","title":"Optional: Identify the correct gpiochip","text":"

    On Raspberry Pi and on many clones the pins exposed on the GPIO belong to the first gpiochip. They can therefore be used on Kalico simply by referring them with the name gpio0..n. However, there are cases in which the exposed pins belong to gpiochips other than the first. For example in the case of some OrangePi models or if a Port Expander is used. In these cases it is useful to use the commands to access the Linux GPIO character device to verify the configuration.

    To install the Linux GPIO character device - binary on a debian based distro like octopi run:

    sudo apt-get install gpiod\n

    To check available gpiochip run:

    gpiodetect\n

    To check the pin number and the pin availability tun:

    gpioinfo\n

    The chosen pin can thus be used within the configuration as gpiochip<n>/gpio<o> where n is the chip number as seen by the gpiodetect command and o is the line number seen by thegpioinfo command.

    Warning: only gpio marked as unused can be used. It is not possible for a line to be used by multiple processes simultaneously.

    For example on a RPi 3B+ where Kalico use the GPIO20 for a switch:

    $ gpiodetect\ngpiochip0 [pinctrl-bcm2835] (54 lines)\ngpiochip1 [raspberrypi-exp-gpio] (8 lines)\n\n$ gpioinfo\ngpiochip0 - 54 lines:\n        line   0:      unnamed       unused   input  active-high\n        line   1:      unnamed       unused   input  active-high\n        line   2:      unnamed       unused   input  active-high\n        line   3:      unnamed       unused   input  active-high\n        line   4:      unnamed       unused   input  active-high\n        line   5:      unnamed       unused   input  active-high\n        line   6:      unnamed       unused   input  active-high\n        line   7:      unnamed       unused   input  active-high\n        line   8:      unnamed       unused   input  active-high\n        line   9:      unnamed       unused   input  active-high\n        line  10:      unnamed       unused   input  active-high\n        line  11:      unnamed       unused   input  active-high\n        line  12:      unnamed       unused   input  active-high\n        line  13:      unnamed       unused   input  active-high\n        line  14:      unnamed       unused   input  active-high\n        line  15:      unnamed       unused   input  active-high\n        line  16:      unnamed       unused   input  active-high\n        line  17:      unnamed       unused   input  active-high\n        line  18:      unnamed       unused   input  active-high\n        line  19:      unnamed       unused   input  active-high\n        line  20:      unnamed    \"klipper\"  output  active-high [used]\n        line  21:      unnamed       unused   input  active-high\n        line  22:      unnamed       unused   input  active-high\n        line  23:      unnamed       unused   input  active-high\n        line  24:      unnamed       unused   input  active-high\n        line  25:      unnamed       unused   input  active-high\n        line  26:      unnamed       unused   input  active-high\n        line  27:      unnamed       unused   input  active-high\n        line  28:      unnamed       unused   input  active-high\n        line  29:      unnamed       \"led0\"  output  active-high [used]\n        line  30:      unnamed       unused   input  active-high\n        line  31:      unnamed       unused   input  active-high\n        line  32:      unnamed       unused   input  active-high\n        line  33:      unnamed       unused   input  active-high\n        line  34:      unnamed       unused   input  active-high\n        line  35:      unnamed       unused   input  active-high\n        line  36:      unnamed       unused   input  active-high\n        line  37:      unnamed       unused   input  active-high\n        line  38:      unnamed       unused   input  active-high\n        line  39:      unnamed       unused   input  active-high\n        line  40:      unnamed       unused   input  active-high\n        line  41:      unnamed       unused   input  active-high\n        line  42:      unnamed       unused   input  active-high\n        line  43:      unnamed       unused   input  active-high\n        line  44:      unnamed       unused   input  active-high\n        line  45:      unnamed       unused   input  active-high\n        line  46:      unnamed       unused   input  active-high\n        line  47:      unnamed       unused   input  active-high\n        line  48:      unnamed       unused   input  active-high\n        line  49:      unnamed       unused   input  active-high\n        line  50:      unnamed       unused   input  active-high\n        line  51:      unnamed       unused   input  active-high\n        line  52:      unnamed       unused   input  active-high\n        line  53:      unnamed       unused   input  active-high\ngpiochip1 - 8 lines:\n        line   0:      unnamed       unused   input  active-high\n        line   1:      unnamed       unused   input  active-high\n        line   2:      unnamed       \"led1\"  output   active-low [used]\n        line   3:      unnamed       unused   input  active-high\n        line   4:      unnamed       unused   input  active-high\n        line   5:      unnamed       unused   input  active-high\n        line   6:      unnamed       unused   input  active-high\n        line   7:      unnamed       unused   input  active-high\n
    "},{"location":"RPi_microcontroller.html#optional-hardware-pwm","title":"Optional: Hardware PWM","text":"

    Raspberry Pi's have two PWM channels (PWM0 and PWM1) which are exposed on the header or if not, can be routed to existing gpio pins. The Linux mcu daemon uses the pwmchip sysfs interface to control hardware pwm devices on Linux hosts. The pwm sysfs interface is not exposed by default on a Raspberry and can be activated by adding a line to /boot/config.txt:

    # Enable pwmchip sysfs interface\ndtoverlay=pwm,pin=12,func=4\n

    This example enables only PWM0 and routes it to gpio12. If both PWM channels need to be enabled you can use pwm-2chan:

    # Enable pwmchip sysfs interface\ndtoverlay=pwm-2chan,pin=12,func=4,pin2=13,func2=4\n

    This example additionally enables PWM1 and routes it to gpio13.

    The overlay does not expose the pwm line on sysfs on boot and needs to be exported by echo'ing the number of the pwm channel to /sys/class/pwm/pwmchip0/export. This will create device /sys/class/pwm/pwmchip0/pwm0 in the filesystem. The easiest way to do this is by adding this to /etc/rc.local before the exit 0 line:

    # Enable pwmchip sysfs interface\necho 0 > /sys/class/pwm/pwmchip0/export\n

    When using both PWM channels, the number of the second channel needs to be echo'd as well:

    # Enable pwmchip sysfs interface\necho 0 > /sys/class/pwm/pwmchip0/export\necho 1 > /sys/class/pwm/pwmchip0/export\n

    With the sysfs in place, you can now use either the pwm channel(s) by adding the following piece of configuration to your printer.cfg:

    [output_pin caselight]\npin: host:pwmchip0/pwm0\npwm: True\nhardware_pwm: True\ncycle_time: 0.000001\n\n[output_pin beeper]\npin: host:pwmchip0/pwm1\npwm: True\nhardware_pwm: True\nvalue: 0\nshutdown_value: 0\ncycle_time: 0.0005\n

    This will add hardware pwm control to gpio12 and gpio13 on the Pi (because the overlay was configured to route pwm0 to pin=12 and pwm1 to pin=13).

    PWM0 can be routed to gpio12 and gpio18, PWM1 can be routed to gpio13 and gpio19:

    PWM gpio PIN Func 0 12 4 0 18 2 1 13 4 1 19 2"},{"location":"Resonance_Compensation.html","title":"Resonance Compensation","text":"

    Kalico supports Input Shaping - a technique that can be used to reduce ringing (also known as echoing, ghosting or rippling) in prints. Ringing is a surface printing defect when, typically, elements like edges repeat themselves on a printed surface as a subtle 'echo':

    |||

    Ringing is caused by mechanical vibrations in the printer due to quick changes of the printing direction. Note that ringing usually has mechanical origins: insufficiently rigid printer frame, non-tight or too springy belts, alignment issues of mechanical parts, heavy moving mass, etc. Those should be checked and fixed first, if possible.

    Input shaping is an open-loop control technique which creates a commanding signal that cancels its own vibrations. Input shaping requires some tuning and measurements before it can be enabled. Besides ringing, Input Shaping typically reduces the vibrations and shaking of the printer in general, and may also improve the reliability of the stealthChop mode of Trinamic stepper drivers.

    "},{"location":"Resonance_Compensation.html#tuning","title":"Tuning","text":"

    Basic tuning requires measuring the ringing frequencies of the printer by printing a test model.

    Slice the ringing test model, which can be found in docs/prints/ringing_tower.stl, in the slicer:

    "},{"location":"Resonance_Compensation.html#ringing-frequency","title":"Ringing frequency","text":"

    First, measure the ringing frequency.

    1. If square_corner_velocity parameter was changed, revert it back to 5.0. It is not advised to increase it when using input shaper because it can cause more smoothing in parts - it is better to use higher acceleration value instead.
    2. Disable the minimum_cruise_ratio feature by issuing the following command: SET_VELOCITY_LIMIT MINIMUM_CRUISE_RATIO=0
    3. Disable Pressure Advance: SET_PRESSURE_ADVANCE ADVANCE=0
    4. If you have already added [input_shaper] section to the printer.cfg, execute SET_INPUT_SHAPER SHAPER_FREQ_X=0 SHAPER_FREQ_Y=0 command. If you get \"Unknown command\" error, you can safely ignore it at this point and continue with the measurements.
    5. Execute the command: TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5 Basically, we try to make ringing more pronounced by setting different large values for acceleration. This command will increase the acceleration every 5 mm starting from 1500 mm/sec^2: 1500 mm/sec^2, 2000 mm/sec^2, 2500 mm/sec^2 and so forth up until 7000 mm/sec^2 at the last band.
    6. Print the test model sliced with the suggested parameters.
    7. You can stop the print earlier if the ringing is clearly visible and you see that acceleration gets too high for your printer (e.g. printer shakes too much or starts skipping steps).

    8. Use X and Y marks at the back of the model for reference. The measurements from the side with X mark should be used for X axis configuration, and Y mark - for Y axis configuration. Measure the distance D (in mm) between several oscillations on the part with X mark, near the notches, preferably skipping the first oscillation or two. To measure the distance between oscillations more easily, mark the oscillations first, then measure the distance between the marks with a ruler or calipers:

      |||

    9. Count how many oscillations N the measured distance D corresponds to. If you are unsure how to count the oscillations, refer to the picture above, which shows N = 6 oscillations.

    10. Compute the ringing frequency of X axis as V \u00b7 N / D (Hz), where V is the velocity for outer perimeters (mm/sec). For the example above, we marked 6 oscillations, and the test was printed at 100 mm/sec velocity, so the frequency is 100 * 6 / 12.14 \u2248 49.4 Hz.
    11. Do (8) - (10) for Y mark as well.

    Note that ringing on the test print should follow the pattern of the curved notches, as in the picture above. If it doesn't, then this defect is not really a ringing and has a different origin - either mechanical, or an extruder issue. It should be fixed first before enabling and tuning input shapers.

    If the measurements are not reliable because, say, the distance between the oscillations is not stable, it might mean that the printer has several resonance frequencies on the same axis. One may try to follow the tuning process described in Unreliable measurements of ringing frequencies section instead and still get something out of the input shaping technique.

    Ringing frequency can depend on the position of the model within the buildplate and Z height, especially on delta printers; you can check if you see the differences in frequencies at different positions along the sides of the test model and at different heights. You can calculate the average ringing frequencies over X and Y axes if that is the case.

    If the measured ringing frequency is very low (below approx 20-25 Hz), it might be a good idea to invest into stiffening the printer or decreasing the moving mass - depending on what is applicable in your case - before proceeding with further input shaping tuning, and re-measuring the frequencies afterwards. For many popular printer models there are often some solutions available already.

    Note that the ringing frequencies can change if the changes are made to the printer that affect the moving mass or change the stiffness of the system, for example:

    If such changes are made, it is a good idea to at least measure the ringing frequencies to see if they have changed.

    "},{"location":"Resonance_Compensation.html#input-shaper-configuration","title":"Input shaper configuration","text":"

    After the ringing frequencies for X and Y axes are measured, you can add the following section to your printer.cfg:

    [input_shaper]\nshaper_freq_x: ...  # frequency for the X mark of the test model\nshaper_freq_y: ...  # frequency for the Y mark of the test model\n

    For the example above, we get shaper_freq_x/y = 49.4.

    "},{"location":"Resonance_Compensation.html#choosing-input-shaper","title":"Choosing input shaper","text":"

    Kalico supports several input shapers. They differ in their sensitivity to errors determining the resonance frequency and how much smoothing they cause in the printed parts. Also, some of the shapers like 2HUMP_EI and 3HUMP_EI should usually not be used with shaper_freq = resonance frequency - they are configured from different considerations to reduce several resonances at once.

    For most of the printers, either MZV or EI shapers can be recommended. This section describes a testing process to choose between them, and figure out a few other related parameters.

    Print the ringing test model as follows:

    1. Restart the firmware: RESTART
    2. Prepare for test: SET_VELOCITY_LIMIT MINIMUM_CRUISE_RATIO=0
    3. Disable Pressure Advance: SET_PRESSURE_ADVANCE ADVANCE=0
    4. Execute: SET_INPUT_SHAPER SHAPER_TYPE=MZV
    5. Execute the command: TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5
    6. Print the test model sliced with the suggested parameters.

    If you see no ringing at this point, then MZV shaper can be recommended for use.

    If you do see some ringing, re-measure the frequencies using steps (8)-(10) described in Ringing frequency section. If the frequencies differ significantly from the values you obtained earlier, a more complex input shaper configuration is needed. You can refer to Technical details of Input shapers section. Otherwise, proceed to the next step.

    Now try EI input shaper. To try it, repeat steps (1)-(6) from above, but executing at step 4 the following command instead: SET_INPUT_SHAPER SHAPER_TYPE=EI.

    Compare two prints with MZV and EI input shaper. If EI shows noticeably better results than MZV, use EI shaper, otherwise prefer MZV. Note that EI shaper will cause more smoothing in printed parts (see the next section for further details). Add shaper_type: mzv (or ei) parameter to [input_shaper] section, e.g.:

    [input_shaper]\nshaper_freq_x: ...\nshaper_freq_y: ...\nshaper_type: mzv\n

    A few notes on shaper selection:

    "},{"location":"Resonance_Compensation.html#selecting-max_accel","title":"Selecting max_accel","text":"

    You should have a printed test for the shaper you chose from the previous step (if you don't, print the test model sliced with the suggested parameters with the pressure advance disabled SET_PRESSURE_ADVANCE ADVANCE=0 and with the tuning tower enabled as TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5). Note that at very high accelerations, depending on the resonance frequency and the input shaper you chose (e.g. EI shaper creates more smoothing than MZV), input shaping may cause too much smoothing and rounding of the parts. So, max_accel should be chosen such as to prevent that. Another parameter that can impact smoothing is square_corner_velocity, so it is not advisable to increase it above the default 5 mm/sec to prevent increased smoothing.

    In order to select a suitable max_accel value, inspect the model for the chosen input shaper. First, take a note at which acceleration ringing is still small - that you are comfortable with it.

    Next, check the smoothing. To help with that, the test model has a small gap in the wall (0.15 mm):

    As the acceleration increases, so does the smoothing, and the actual gap in the print widens:

    In this picture, the acceleration increases left to right, and the gap starts to grow starting from 3500 mm/sec^2 (5-th band from the left). So the good value for max_accel = 3000 (mm/sec^2) in this case to avoid the excessive smoothing.

    Note the acceleration when the gap is still very small in your test print. If you see bulges, but no gap in the wall at all, even at high accelerations, it may be due to disabled Pressure Advance, especially on Bowden extruders. If that is the case, you may need to repeat the print with the PA enabled. It may also be a result of a miscalibrated (too high) filament flow, so it is a good idea to check that too.

    Choose the minimum out of the two acceleration values (from ringing and smoothing), and put it as max_accel into printer.cfg.

    As a note, it may happen - especially at low ringing frequencies - that EI shaper will cause too much smoothing even at lower accelerations. In this case, MZV may be a better choice, because it may allow higher acceleration values.

    At very low ringing frequencies (~25 Hz and below) even MZV shaper may create too much smoothing. If that is the case, you can also try to repeat the steps in Choosing input shaper section with ZV shaper, by using SET_INPUT_SHAPER SHAPER_TYPE=ZV command instead. ZV shaper should show even less smoothing than MZV, but is more sensitive to errors in measuring the ringing frequencies.

    Another consideration is that if a resonance frequency is too low (below 20-25 Hz), it might be a good idea to increase the printer stiffness or reduce the moving mass. Otherwise, acceleration and printing speed may be limited due too much smoothing now instead of ringing.

    "},{"location":"Resonance_Compensation.html#fine-tuning-resonance-frequencies","title":"Fine-tuning resonance frequencies","text":"

    Note that the precision of the resonance frequencies measurements using the ringing test model is sufficient for most purposes, so further tuning is not advised. If you still want to try to double-check your results (e.g. if you still see some ringing after printing a test model with an input shaper of your choice with the same frequencies as you have measured earlier), you can follow the steps in this section. Note that if you see ringing at different frequencies after enabling [input_shaper], this section will not help with that.

    Assuming that you have sliced the ringing model with suggested parameters, complete the following steps for each of the axes X and Y:

    1. Prepare for test: SET_VELOCITY_LIMIT MINIMUM_CRUISE_RATIO=0
    2. Make sure Pressure Advance is disabled: SET_PRESSURE_ADVANCE ADVANCE=0
    3. Execute: SET_INPUT_SHAPER SHAPER_TYPE=ZV
    4. From the existing ringing test model with your chosen input shaper select the acceleration that shows ringing sufficiently well, and set it with: SET_VELOCITY_LIMIT ACCEL=...
    5. Calculate the necessary parameters for the TUNING_TOWER command to tune shaper_freq_x parameter as follows: start = shaper_freq_x * 83 / 132 and factor = shaper_freq_x / 66, where shaper_freq_x here is the current value in printer.cfg.
    6. Execute the command: TUNING_TOWER COMMAND=SET_INPUT_SHAPER PARAMETER=SHAPER_FREQ_X START=start FACTOR=factor BAND=5 using start and factor values calculated at step (5).
    7. Print the test model.
    8. Reset the original frequency value: SET_INPUT_SHAPER SHAPER_FREQ_X=....
    9. Find the band which shows ringing the least and count its number from the bottom starting at 1.
    10. Calculate the new shaper_freq_x value via old shaper_freq_x * (39 + 5 * #band-number) / 66.

    Repeat these steps for the Y axis in the same manner, replacing references to X axis with the axis Y (e.g. replace shaper_freq_x with shaper_freq_y in the formulae and in the TUNING_TOWER command).

    As an example, let's assume you have had measured the ringing frequency for one of the axis equal to 45 Hz. This gives start = 45 * 83 / 132 = 28.30 and factor = 45 / 66 = 0.6818 values for TUNING_TOWER command. Now let's assume that after printing the test model, the fourth band from the bottom gives the least ringing. This gives the updated shaper_freq_? value equal to 45 * (39 + 5 * 4) / 66 \u2248 40.23.

    After both new shaper_freq_x and shaper_freq_y parameters have been calculated, you can update [input_shaper] section in printer.cfg with the new shaper_freq_x and shaper_freq_y values.

    "},{"location":"Resonance_Compensation.html#pressure-advance","title":"Pressure Advance","text":"

    If you use Pressure Advance, it may need to be re-tuned. Follow the instructions to find the new value, if it differs from the previous one. Make sure to restart Kalico before tuning Pressure Advance.

    "},{"location":"Resonance_Compensation.html#unreliable-measurements-of-ringing-frequencies","title":"Unreliable measurements of ringing frequencies","text":"

    If you are unable to measure the ringing frequencies, e.g. if the distance between the oscillations is not stable, you may still be able to take advantage of input shaping techniques, but the results may not be as good as with proper measurements of the frequencies, and will require a bit more tuning and printing the test model. Note that another possibility is to purchase and install an accelerometer and measure the resonances with it (refer to the docs describing the required hardware and the setup process) - but this option requires some crimping and soldering.

    For tuning, add empty [input_shaper] section to your printer.cfg. Then, assuming that you have sliced the ringing model with suggested parameters, print the test model 3 times as follows. First time, prior to printing, run

    1. RESTART
    2. SET_VELOCITY_LIMIT MINIMUM_CRUISE_RATIO=0
    3. SET_PRESSURE_ADVANCE ADVANCE=0
    4. SET_INPUT_SHAPER SHAPER_TYPE=2HUMP_EI SHAPER_FREQ_X=60 SHAPER_FREQ_Y=60
    5. TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5

    and print the model. Then print the model again, but before printing run instead

    1. SET_INPUT_SHAPER SHAPER_TYPE=2HUMP_EI SHAPER_FREQ_X=50 SHAPER_FREQ_Y=50
    2. TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5

    Then print the model for the 3rd time, but now run

    1. SET_INPUT_SHAPER SHAPER_TYPE=2HUMP_EI SHAPER_FREQ_X=40 SHAPER_FREQ_Y=40
    2. TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5

    Essentially, we are printing the ringing test model with TUNING_TOWER using 2HUMP_EI shaper with shaper_freq = 60 Hz, 50 Hz, and 40 Hz.

    If none of the models demonstrate improvements in ringing, then, unfortunately, it does not look like the input shaping techniques can help with your case.

    Otherwise, it may be that all models show no ringing, or some show the ringing and some - not so much. Choose the test model with the highest frequency that still shows good improvements in ringing. For example, if 40 Hz and 50 Hz models show almost no ringing, and 60 Hz model already shows some more ringing, stick with 50 Hz.

    Now check if EI shaper would be good enough in your case. Choose EI shaper frequency based on the frequency of 2HUMP_EI shaper you chose:

    Now print the test model one more time, running

    1. SET_INPUT_SHAPER SHAPER_TYPE=EI SHAPER_FREQ_X=... SHAPER_FREQ_Y=...
    2. TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1500 STEP_DELTA=500 STEP_HEIGHT=5

    providing the shaper_freq_x=... and shaper_freq_y=... as determined previously.

    If EI shaper shows very comparable good results as 2HUMP_EI shaper, stick with EI shaper and the frequency determined earlier, otherwise use 2HUMP_EI shaper with the corresponding frequency. Add the results to printer.cfg as, e.g.

    [input_shaper]\nshaper_freq_x: 50\nshaper_freq_y: 50\nshaper_type: 2hump_ei\n

    Continue the tuning with Selecting max_accel section.

    "},{"location":"Resonance_Compensation.html#troubleshooting-and-faq","title":"Troubleshooting and FAQ","text":""},{"location":"Resonance_Compensation.html#i-cannot-get-reliable-measurements-of-resonance-frequencies","title":"I cannot get reliable measurements of resonance frequencies","text":"

    First, make sure it is not some other problem with the printer instead of ringing. If the measurements are not reliable because, say, the distance between the oscillations is not stable, it might mean that the printer has several resonance frequencies on the same axis. One may try to follow the tuning process described in Unreliable measurements of ringing frequencies section and still get something out of the input shaping technique. Another possibility is to install an accelerometer, measure the resonances with it, and auto-tune the input shaper using the results of those measurements.

    "},{"location":"Resonance_Compensation.html#after-enabling-input_shaper-i-get-too-smoothed-printed-parts-and-fine-details-are-lost","title":"After enabling [input_shaper], I get too smoothed printed parts and fine details are lost","text":"

    Check the considerations in Selecting max_accel section. If the resonance frequency is low, one should not set too high max_accel or increase square_corner_velocity parameters. It might also be better to choose MZV or even ZV input shapers over EI (or 2HUMP_EI and 3HUMP_EI shapers).

    "},{"location":"Resonance_Compensation.html#after-successfully-printing-for-some-time-without-ringing-it-appears-to-come-back","title":"After successfully printing for some time without ringing, it appears to come back","text":"

    It is possible that after some time the resonance frequencies have changed. E.g. maybe the belts tension has changed (belts got more loose), etc. It is a good idea to check and re-measure the ringing frequencies as described in Ringing frequency section and update your config file if necessary.

    "},{"location":"Resonance_Compensation.html#is-dual-carriage-setup-supported-with-input-shapers","title":"Is dual carriage setup supported with input shapers?","text":"

    Yes. In this case, one should measure the resonances twice for each carriage. For example, if the second (dual) carriage is installed on X axis, it is possible to set different input shapers for X axis for the primary and dual carriages. However, the input shaper for Y axis should be the same for both carriages (as ultimately this axis is driven by one or more stepper motors each commanded to perform exactly the same steps). One possibility to configure the input shaper for such setups is to keep [input_shaper] section empty and additionally define a [delayed_gcode] section in the printer.cfg as follows:

    [input_shaper]\n# Intentionally empty\n\n[delayed_gcode init_shaper]\ninitial_duration: 0.1\ngcode:\n  SET_DUAL_CARRIAGE CARRIAGE=1\n  SET_INPUT_SHAPER SHAPER_TYPE_X=<dual_carriage_shaper> SHAPER_FREQ_X=<dual_carriage_freq> SHAPER_TYPE_Y=<y_shaper> SHAPER_FREQ_Y=<y_freq>\n  SET_DUAL_CARRIAGE CARRIAGE=0\n  SET_INPUT_SHAPER SHAPER_TYPE_X=<primary_carriage_shaper> SHAPER_FREQ_X=<primary_carriage_freq> SHAPER_TYPE_Y=<y_shaper> SHAPER_FREQ_Y=<y_freq>\n

    Note that SHAPER_TYPE_Y and SHAPER_FREQ_Y should be the same in both commands. It is also possible to put a similar snippet into the start g-code in the slicer, however then the shaper will not be enabled until any print is started.

    Note that the input shaper only needs to be configured once. Subsequent changes of the carriages or their modes via SET_DUAL_CARRIAGE command will preserve the configured input shaper parameters.

    "},{"location":"Resonance_Compensation.html#does-input_shaper-affect-print-time","title":"Does input_shaper affect print time?","text":"

    No, input_shaper feature has pretty much no impact on the print times by itself. However, the value of max_accel certainly does (tuning of this parameter described in this section).

    "},{"location":"Resonance_Compensation.html#technical-details","title":"Technical details","text":""},{"location":"Resonance_Compensation.html#input-shapers","title":"Input shapers","text":"

    Input shapers used in Kalico are rather standard, and one can find more in-depth overview in the articles describing the corresponding shapers. This section contains a brief overview of some technical aspects of the supported input shapers. The table below shows some (usually approximate) parameters of each shaper.

    Input shaper Shaper duration Vibration reduction 20x (5% vibration tolerance) Vibration reduction 10x (10% vibration tolerance) ZV 0.5 / shaper_freq N/A \u00b1 5% shaper_freq MZV 0.75 / shaper_freq \u00b1 4% shaper_freq -10%...+15% shaper_freq ZVD 1 / shaper_freq \u00b1 15% shaper_freq \u00b1 22% shaper_freq EI 1 / shaper_freq \u00b1 20% shaper_freq \u00b1 25% shaper_freq 2HUMP_EI 1.5 / shaper_freq \u00b1 35% shaper_freq \u00b1 40 shaper_freq 3HUMP_EI 2 / shaper_freq -45...+50% shaper_freq -50%...+55% shaper_freq

    A note on vibration reduction: the values in the table above are approximate. If the damping ratio of the printer is known for each axis, the shaper can be configured more precisely and it will then reduce the resonances in a bit wider range of frequencies. However, the damping ratio is usually unknown and is hard to estimate without a special equipment, so Kalico uses 0.1 value by default, which is a good all-round value. The frequency ranges in the table cover a number of different possible damping ratios around that value (approx. from 0.05 to 0.2).

    Also note that EI, 2HUMP_EI, and 3HUMP_EI are tuned to reduce vibrations to 5%, so the values for 10% vibration tolerance are provided only for the reference.

    How to use this table:

    "},{"location":"Rotation_Distance.html","title":"Rotation distance","text":"

    Stepper motor drivers on Kalico require a rotation_distance parameter in each stepper config section. The rotation_distance is the amount of distance that the axis moves with one full revolution of the stepper motor. This document describes how one can configure this value.

    "},{"location":"Rotation_Distance.html#obtaining-rotation_distance-from-steps_per_mm-or-step_distance","title":"Obtaining rotation_distance from steps_per_mm (or step_distance)","text":"

    The designers of your 3d printer originally calculated steps_per_mm from a rotation distance. If you know the steps_per_mm then it is possible to use this general formula to obtain that original rotation distance:

    rotation_distance = <full_steps_per_rotation> * <microsteps> / <steps_per_mm>\n

    Or, if you have an older Kalico configuration and know the step_distance parameter you can use this formula:

    rotation_distance = <full_steps_per_rotation> * <microsteps> * <step_distance>\n

    The <full_steps_per_rotation> setting is determined from the type of stepper motor. Most stepper motors are \"1.8 degree steppers\" and therefore have 200 full steps per rotation (360 divided by 1.8 is 200). Some stepper motors are \"0.9 degree steppers\" and thus have 400 full steps per rotation. Other stepper motors are rare. If unsure, do not set full_steps_per_rotation in the config file and use 200 in the formula above.

    The <microsteps> setting is determined by the stepper motor driver. Most drivers use 16 microsteps. If unsure, set microsteps: 16 in the config and use 16 in the formula above.

    Almost all printers should have a whole number for rotation_distance on X, Y, and Z type axes. If the above formula results in a rotation_distance that is within .01 of a whole number then round the final value to that whole_number.

    "},{"location":"Rotation_Distance.html#calibrating-rotation_distance-on-extruders","title":"Calibrating rotation_distance on extruders","text":"

    On an extruder, the rotation_distance is the amount of distance the filament travels for one full rotation of the stepper motor. The best way to get an accurate value for this setting is to use a \"measure and trim\" procedure.

    First start with an initial guess for the rotation distance. This may be obtained from steps_per_mm or by inspecting the hardware.

    Then use the following procedure to \"measure and trim\":

    1. Make sure the extruder has filament in it, the hotend is heated to an appropriate temperature, and the printer is ready to extrude.
    2. Use a marker to place a mark on the filament around 70mm from the intake of the extruder body. Then use a digital calipers to measure the actual distance of that mark as precisely as one can. Note this as <initial_mark_distance>.
    3. Extrude 50mm of filament with the following command sequence: G91 followed by G1 E50 F60. Note 50mm as <requested_extrude_distance>. Wait for the extruder to finish the move (it will take about 50 seconds). It is important to use the slow extrusion rate for this test as a faster rate can cause high pressure in the extruder which will skew the results. (Do not use the \"extrude button\" on graphical front-ends for this test as they extrude at a fast rate.)
    4. Use the digital calipers to measure the new distance between the extruder body and the mark on the filament. Note this as <subsequent_mark_distance>. Then calculate: actual_extrude_distance = <initial_mark_distance> - <subsequent_mark_distance>
    5. Calculate rotation_distance as: rotation_distance = <previous_rotation_distance> * <actual_extrude_distance> / <requested_extrude_distance> Round the new rotation_distance to three decimal places.

    If the actual_extrude_distance differs from requested_extrude_distance by more than about 2mm then it is a good idea to perform the steps above a second time.

    Note: Do not use a \"measure and trim\" type of method to calibrate x, y, or z type axes. The \"measure and trim\" method is not accurate enough for those axes and will likely lead to a worse configuration. Instead, if needed, those axes can be determined by measuring the belts, pulleys, and lead screw hardware.

    "},{"location":"Rotation_Distance.html#obtaining-rotation_distance-by-inspecting-the-hardware","title":"Obtaining rotation_distance by inspecting the hardware","text":"

    It's possible to calculate rotation_distance with knowledge of the stepper motors and printer kinematics. This may be useful if the steps_per_mm is not known or if designing a new printer.

    "},{"location":"Rotation_Distance.html#belt-driven-axes","title":"Belt driven axes","text":"

    It is easy to calculate rotation_distance for a linear axis that uses a belt and pulley.

    First determine the type of belt. Most printers use a 2mm belt pitch (that is, each tooth on the belt is 2mm apart). Then count the number of teeth on the stepper motor pulley. The rotation_distance is then calculated as:

    rotation_distance = <belt_pitch> * <number_of_teeth_on_pulley>\n

    For example, if a printer has a 2mm belt and uses a pulley with 20 teeth, then the rotation distance is 40.

    "},{"location":"Rotation_Distance.html#axes-with-a-lead-screw","title":"Axes with a lead screw","text":"

    It is easy to calculate the rotation_distance for common lead screws using the following formula:

    rotation_distance = <screw_pitch> * <number_of_separate_threads>\n

    For example, the common \"T8 leadscrew\" has a rotation distance of 8 (it has a pitch of 2mm and has 4 separate threads).

    Older printers with \"threaded rods\" have only one \"thread\" on the lead screw and thus the rotation distance is the pitch of the screw. (The screw pitch is the distance between each groove on the screw.) So, for example, an M6 metric rod has a rotation distance of 1 and an M8 rod has a rotation distance of 1.25.

    "},{"location":"Rotation_Distance.html#extruder","title":"Extruder","text":"

    It's possible to obtain an initial rotation distance for extruders by measuring the diameter of the \"hobbed bolt\" that pushes the filament and using the following formula: rotation_distance = <diameter> * 3.14

    If the extruder uses gears then it will also be necessary to determine and set the gear_ratio for the extruder.

    The actual rotation distance on an extruder will vary from printer to printer, because the grip of the \"hobbed bolt\" that engages the filament can vary. It can even vary between filament spools. After obtaining an initial rotation_distance, use the measure and trim procedure to obtain a more accurate setting.

    "},{"location":"Rotation_Distance.html#using-a-gear_ratio","title":"Using a gear_ratio","text":"

    Setting a gear_ratio can make it easier to configure the rotation_distance on steppers that have a gear box (or similar) attached to it. Most steppers do not have a gear box - if unsure then do not set gear_ratio in the config.

    When gear_ratio is set, the rotation_distance represents the distance the axis moves with one full rotation of the final gear on the gear box. If, for example, one is using a gearbox with a \"5:1\" ratio, then one could calculate the rotation_distance with knowledge of the hardware and then add gear_ratio: 5:1 to the config.

    For gearing implemented with belts and pulleys, it is possible to determine the gear_ratio by counting the teeth on the pulleys. For example, if a stepper with a 16 toothed pulley drives the next pulley with 80 teeth then one would use gear_ratio: 80:16. Indeed, one could open a common off the shelf \"gear box\" and count the teeth in it to confirm its gear ratio.

    Note that sometimes a gearbox will have a slightly different gear ratio than what it is advertised as. The common BMG extruder motor gears are an example of this - they are advertised as \"3:1\" but actually use \"50:17\" gearing. (Using teeth numbers without a common denominator may improve overall gear wear as the teeth don't always mesh the same way with each revolution.) The common \"5.18:1 planetary gearbox\", is more accurately configured with gear_ratio: 57:11.

    If several gears are used on an axis then it is possible to provide a comma separated list to gear_ratio. For example, a \"5:1\" gear box driving a 16 toothed to 80 toothed pulley could use gear_ratio: 5:1, 80:16.

    In most cases, gear_ratio should be defined with whole numbers as common gears and pulleys have a whole number of teeth on them. However, in cases where a belt drives a pulley using friction instead of teeth, it may make sense to use a floating point number in the gear ratio (eg, gear_ratio: 107.237:16).

    "},{"location":"SDCard_Updates.html","title":"SDCard updates","text":"

    Many of today's popular controller boards ship with a bootloader capable of updating firmware via SD Card. While this is convenient in many circumstances, these bootloaders typically provide no other way to update firmware. This can be a nuisance if your board is mounted in a location that is difficult to access or if you need to update firmware often. After Kalico has been initially flashed to a controller it is possible to transfer new firmware to the SD Card and initiate the flashing procedure via ssh.

    "},{"location":"SDCard_Updates.html#typical-upgrade-procedure","title":"Typical Upgrade Procedure","text":"

    The procedure for updating MCU firmware using the SD Card is similar to that of other methods. Instead of using make flash it is necessary to run a helper script, flash-sdcard.sh. Updating a BigTreeTech SKR 1.3 might look like the following:

    sudo service klipper stop\ncd ~/klipper\ngit pull\nmake clean\nmake menuconfig\nmake\n./scripts/flash-sdcard.sh /dev/ttyACM0 btt-skr-v1.3\nsudo service klipper start\n

    It is up to the user to determine the device location and board name. If a user needs to flash multiple boards, flash-sdcard.sh (or make flash if appropriate) should be run for each board prior to restarting the Klipper service.

    Supported boards can be listed with the following command:

    ./scripts/flash-sdcard.sh -l\n

    If you do not see your board listed it may be necessary to add a new board definition as described below.

    "},{"location":"SDCard_Updates.html#advanced-usage","title":"Advanced Usage","text":"

    The above commands assume that your MCU connects at the default baud rate of 250000 and the firmware is located at ~/klipper/out/klipper.bin. The flash-sdcard.sh script provides options for changing these defaults. All options can be viewed by the help screen:

    ./scripts/flash-sdcard.sh -h\nSD Card upload utility for Kalico\n\nusage: flash_sdcard.sh [-h] [-l] [-c] [-b <baud>] [-f <firmware>]\n                       <device> <board>\n\npositional arguments:\n  <device>        device serial port\n  <board>         board type\n\noptional arguments:\n  -h              show this message\n  -l              list available boards\n  -c              run flash check/verify only (skip upload)\n  -b <baud>       serial baud rate (default is 250000)\n  -f <firmware>   path to klipper.bin\n

    If your board is flashed with firmware that connects at a custom baud rate it is possible to upgrade by specifying the -b option:

    ./scripts/flash-sdcard.sh -b 115200 /dev/ttyAMA0 btt-skr-v1.3\n

    If you wish to flash a build of Kalico located somewhere other than the default location it can be done by specifying the -f option:

    ./scripts/flash-sdcard.sh -f ~/downloads/klipper.bin /dev/ttyAMA0 btt-skr-v1.3\n

    Note that when upgrading a MKS Robin E3 it is not necessary to manually run update_mks_robin.py and supply the resulting binary to flash-sdcard.sh. This procedure is automated during the upload process.

    The -c option is used to perform a check or verify-only operation to test if the board is running the specified firmware correctly. This option is primarily intended for cases where a manual power-cycle is necessary to complete the flashing procedure, such as with bootloaders that use SDIO mode instead of SPI to access their SD Cards. (See Caveats below) But, it can also be used anytime to verify if the code flashed into the board matches the version in your build folder on any supported board.

    "},{"location":"SDCard_Updates.html#caveats","title":"Caveats","text":""},{"location":"SDCard_Updates.html#board-definitions","title":"Board Definitions","text":"

    Most common boards should be available, however it is possible to add a new board definition if necessary. Board definitions are located in ~/klipper/scripts/spi_flash/board_defs.py. The definitions are stored in dictionary, for example:

    BOARD_DEFS = {\n    'generic-lpc1768': {\n        'mcu': \"lpc1768\",\n        'spi_bus': \"ssp1\",\n        \"cs_pin\": \"P0.6\"\n    },\n    ...<further definitions>\n}\n

    The following fields may be specified:

    If software SPI is required, the spi_bus field should be set to swspi and the following additional field should be specified:

    It should be exceedingly rare that Software SPI is necessary, typically only boards with design errors or boards that normally only support SDIO mode for their SD Card will require it. The btt-skr-pro board definition provides an example of the former, and the btt-octopus-f446-v1 board definition provides an example of the latter.

    Prior to creating a new board definition one should check to see if an existing board definition meets the criteria necessary for the new board. If this is the case, a BOARD_ALIAS may be specified. For example, the following alias may be added to specify my-new-board as an alias for generic-lpc1768:

    BOARD_ALIASES = {\n    ...<previous aliases>,\n    'my-new-board': BOARD_DEFS['generic-lpc1768'],\n}\n

    If you need a new board definition and you are uncomfortable with the procedure outlined above it is recommended that you request one in the Kalico Discord server.

    "},{"location":"SDCard_Updates.html#flashing-boards-that-use-sdio","title":"Flashing Boards that use SDIO","text":"

    As mentioned in the Caveats, boards whose bootloader uses SDIO mode to access their SD Card require a power-cycle of the board, and specifically the SD Card itself, in order to switch from the SPI Mode used while writing the file to the SD Card back to SDIO mode for the bootloader to flash it into the board. These board definitions will use the skip_verify flag, which tells the flashing tool to stop after writing the firmware to the SD Card so that the board can be manually power-cycled and the verification step deferred until that's complete.

    There are two scenarios -- one with the RPi Host running on a separate power supply and the other when the RPi Host is running on the same power supply as the main board being flashed. The difference is whether or not it's necessary to also shutdown the RPi and then ssh again after the flashing is complete in order to do the verification step, or if the verification can be done immediately. Here's examples of the two scenarios:

    "},{"location":"SDCard_Updates.html#sdio-programming-with-rpi-on-separate-power-supply","title":"SDIO Programming with RPi on Separate Power Supply","text":"

    A typical session with the RPi on a Separate Power Supply looks like the following. You will, of course, need to use your proper device path and board name:

    sudo service klipper stop\ncd ~/klipper\ngit pull\nmake clean\nmake menuconfig\nmake\n./scripts/flash-sdcard.sh /dev/ttyACM0 btt-octopus-f446-v1\n[[[manually power-cycle the printer board here when instructed]]]\n./scripts/flash-sdcard.sh -c /dev/ttyACM0 btt-octopus-f446-v1\nsudo service klipper start\n
    "},{"location":"SDCard_Updates.html#sdio-programming-with-rpi-on-the-same-power-supply","title":"SDIO Programming with RPi on the Same Power Supply","text":"

    A typical session with the RPi on the Same Power Supply looks like the following. You will, of course, need to use your proper device path and board name:

    sudo service klipper stop\ncd ~/klipper\ngit pull\nmake clean\nmake menuconfig\nmake\n./scripts/flash-sdcard.sh /dev/ttyACM0 btt-octopus-f446-v1\nsudo shutdown -h now\n[[[wait for the RPi to shutdown, then power-cycle and ssh again to the RPi when it restarts]]]\nsudo service klipper stop\ncd ~/klipper\n./scripts/flash-sdcard.sh -c /dev/ttyACM0 btt-octopus-f446-v1\nsudo service klipper start\n

    In this case, since the RPi Host is being restarted, which will restart the klipper service, it's necessary to stop klipper again before doing the verification step and restart it after verification is complete.

    "},{"location":"SDCard_Updates.html#sdio-to-spi-pin-mapping","title":"SDIO to SPI Pin Mapping","text":"

    If your board's schematic uses SDIO for its SD Card, you can map the pins as described in the chart below to determine the compatible Software SPI pins to assign in the board_defs.py file:

    SD Card Pin Micro SD Card Pin SDIO Pin Name SPI Pin Name 9 1 DATA2 None (PU)* 1 2 CD/DATA3 CS 2 3 CMD MOSI 4 4 +3.3V (VDD) +3.3V (VDD) 5 5 CLK SCLK 3 6 GND (VSS) GND (VSS) 7 7 DATA0 MISO 8 8 DATA1 None (PU)* N/A 9 Card Detect (CD) Card Detect (CD) 6 10 GND GND

    * None (PU) indicates an unused pin with a pull-up resistor

    "},{"location":"Skew_Correction.html","title":"Skew correction","text":"

    Software based skew correction can help resolve dimensional inaccuracies resulting from a printer assembly that is not perfectly square. Note that if your printer is significantly skewed it is strongly recommended to first use mechanical means to get your printer as square as possible prior to applying software based correction.

    "},{"location":"Skew_Correction.html#print-a-calibration-object","title":"Print a Calibration Object","text":"

    The first step in correcting skew is to print a calibration object along the plane you want to correct. There is also a calibration object that includes all planes in one model. You want the object oriented so that corner A is toward the origin of the plane.

    Make sure that no skew correction is applied during this print. You may do this by either removing the [skew_correction] module from printer.cfg or by issuing a SET_SKEW CLEAR=1 gcode.

    "},{"location":"Skew_Correction.html#take-your-measurements","title":"Take your measurements","text":"

    The [skew_correction] module requires 3 measurements for each plane you want to correct; the length from Corner A to Corner C, the length from Corner B to Corner D, and the length from Corner A to Corner D. When measuring length AD do not include the flats on the corners that some test objects provide.

    "},{"location":"Skew_Correction.html#configure-your-skew","title":"Configure your skew","text":"

    Make sure [skew_correction] is in printer.cfg. You may now use the SET_SKEW gcode to configure skew_correcton. For example, if your measured lengths along XY are as follows:

    Length AC = 140.4\nLength BD = 142.8\nLength AD = 99.8\n

    SET_SKEW can be used to configure skew correction for the XY plane.

    SET_SKEW XY=140.4,142.8,99.8\n

    You may also add measurements for XZ and YZ to the gcode:

    SET_SKEW XY=140.4,142.8,99.8 XZ=141.6,141.4,99.8 YZ=142.4,140.5,99.5\n

    The [skew_correction] module also supports profile management in a manner similar to [bed_mesh]. After setting skew using the SET_SKEW gcode, you may use the SKEW_PROFILE gcode to save it:

    SKEW_PROFILE SAVE=my_skew_profile\n

    After this command you will be prompted to issue a SAVE_CONFIG gcode to save the profile to persistent storage. If no profile is named my_skew_profile then a new profile will be created. If the named profile exists it will be overwritten.

    Once you have a saved profile, you may load it:

    SKEW_PROFILE LOAD=my_skew_profile\n

    It is also possible to remove an old or out of date profile:

    SKEW_PROFILE REMOVE=my_skew_profile\n

    After removing a profile you will be prompted to issue a SAVE_CONFIG to make this change persist.

    "},{"location":"Skew_Correction.html#verifying-your-correction","title":"Verifying your correction","text":"

    After skew_correction has been configured you may reprint the calibration part with correction enabled. Use the following gcode to check your skew on each plane. The results should be lower than those reported via GET_CURRENT_SKEW.

    CALC_MEASURED_SKEW AC=<ac_length> BD=<bd_length> AD=<ad_length>\n
    "},{"location":"Skew_Correction.html#caveats","title":"Caveats","text":"

    Due to the nature of skew correction it is recommended to configure skew in your start gcode, after homing and any kind of movement that travels near the edge of the print area such as a purge or nozzle wipe. You may use use the SET_SKEW or SKEW_PROFILE gcodes to accomplish this. It is also recommended to issue a SET_SKEW CLEAR=1 in your end gcode.

    Keep in mind that it is possible for [skew_correction] to generate a correction that moves the tool beyond the printer's boundaries on the X and/or Y axes. It is recommended to arrange parts away from the edges when using [skew_correction].

    "},{"location":"Slicers.html","title":"Slicers","text":"

    This document provides some tips for configuring a \"slicer\" application for use with Kalico. Common slicers used with Kalico are Slic3r, Cura, Simplify3D, etc.

    "},{"location":"Slicers.html#set-the-g-code-flavor-to-marlin","title":"Set the G-Code flavor to Marlin","text":"

    Many slicers have an option to configure the \"G-Code flavor\". Most modern slicers nowadays have a \"Klipper\" G-Code flavor that works best for Kalico. \"Marlin\" also should work well with Kalico if the \"Klipper\" flavor is not available. The \"Smoothieware\" setting also works well with Kalico.

    "},{"location":"Slicers.html#kalico-gcode_macro","title":"Kalico gcode_macro","text":"

    Slicers will often allow one to configure \"Start G-Code\" and \"End G-Code\" sequences. It is often convenient to define custom macros in the Kalico config file instead - such as: [gcode_macro START_PRINT] and [gcode_macro END_PRINT]. Then one can just run START_PRINT and END_PRINT in the slicer's configuration. Defining these actions in the Kalico configuration may make it easier to tweak the printer's start and end steps as changes do not require re-slicing.

    See sample-macros.cfg for example START_PRINT and END_PRINT macros.

    See the config reference for details on defining a gcode_macro.

    "},{"location":"Slicers.html#large-retraction-settings-may-require-tuning-kalico","title":"Large retraction settings may require tuning Kalico","text":"

    The maximum speed and acceleration of retraction moves are controlled in Kalico by the max_extrude_only_velocity and max_extrude_only_accel config settings. These settings have a default value that should work well on many printers. However, if one has configured a large retraction in the slicer (eg, 5mm or greater) then one may find they limit the desired speed of retractions.

    If using a large retraction, consider tuning Kalico's pressure advance instead. Otherwise, if one finds the toolhead seems to \"pause\" during retraction and priming, then consider explicitly defining max_extrude_only_velocity and max_extrude_only_accel in the Kalico config file.

    "},{"location":"Slicers.html#do-not-enable-coasting","title":"Do not enable \"coasting\"","text":"

    The \"coasting\" feature is likely to result in poor quality prints with Kalico. Consider using Kalico's pressure advance instead.

    Specifically, if the slicer dramatically changes the extrusion rate between moves then Kalico will perform deceleration and acceleration between moves. This is likely to make blobbing worse, not better.

    In contrast, it is okay (and often helpful) to use a slicer's \"retract\" setting, \"wipe\" setting, and/or \"wipe on retract\" setting.

    "},{"location":"Slicers.html#do-not-use-extra-restart-distance-on-simplify3d","title":"Do not use \"extra restart distance\" on Simplify3d","text":"

    This setting can cause dramatic changes to extrusion rates which can trigger Kalico's maximum extrusion cross-section check. Consider using Kalico's pressure advance or the regular Simplify3d retract setting instead.

    "},{"location":"Slicers.html#disable-preloadve-on-kisslicer","title":"Disable \"PreloadVE\" on KISSlicer","text":"

    If using KISSlicer slicing software then set \"PreloadVE\" to zero. Consider using Kalico's pressure advance instead.

    "},{"location":"Slicers.html#disable-any-advanced-extruder-pressure-settings","title":"Disable any \"advanced extruder pressure\" settings","text":"

    Some slicers advertise an \"advanced extruder pressure\" capability. It is recommended to keep these options disabled when using Kalico as they are likely to result in poor quality prints. Consider using Kalico's pressure advance instead.

    Specifically, these slicer settings can instruct the firmware to make wild changes to the extrusion rate in the hope that the firmware will approximate those requests and the printer will roughly obtain a desirable extruder pressure. Kalico, however, utilizes precise kinematic calculations and timing. When Kalico is commanded to make significant changes to the extrusion rate it will plan out the corresponding changes to velocity, acceleration, and extruder movement - which is not the slicer's intent. The slicer may even command excessive extrusion rates to the point that it triggers Kalico's maximum extrusion cross-section check.

    In contrast, it is okay (and often helpful) to use a slicer's \"retract\" setting, \"wipe\" setting, and/or \"wipe on retract\" setting.

    "},{"location":"Slicers.html#start_print-macros","title":"START_PRINT macros","text":"

    When using a START_PRINT macro or similar, it is useful to sometimes pass through parameters from the slicer variables to the macro.

    In Cura, to pass through temperatures, the following start gcode would be used:

    START_PRINT BED_TEMP={material_bed_temperature_layer_0} EXTRUDER_TEMP={material_print_temperature_layer_0}\n

    In slic3r derivatives such as PrusaSlicer and SuperSlicer, the following would be used:

    START_PRINT EXTRUDER_TEMP=[first_layer_temperature] BED_TEMP=[first_layer_bed_temperature]\n

    Also note that these slicers will insert their own heating codes when certain conditions are not met. In Cura, the existence of the {material_bed_temperature_layer_0} and {material_print_temperature_layer_0} variables is enough to mitigate this. In slic3r derivatives, you would use:

    M140 S0\nM104 S0\n

    before the macro call. Also note that SuperSlicer has a \"custom gcode only\" button option, which achieves the same outcome.

    An example of a START_PRINT macro using these paramaters can be found in config/sample-macros.cfg

    "},{"location":"Sponsors.html","title":"Sponsors","text":"

    Kalico is a community-driven, open-source project that is free to use (as in \"free beer\"). While we don't have official sponsors yet, we are deeply grateful for the generous support from our community. Every contribution helps us continue improving Kalico for everyone.

    If you'd like to support Kalico, donations to our Ko-Fi are more than welcome: \ud83d\udc49 https://ko-fi.com/kalicocrew

    "},{"location":"Sponsors.html#the-people-behind-kalico","title":"The People behind Kalico","text":""},{"location":"Sponsors.html#the-crew","title":"The Crew","text":"Name Alias GitHub Bea NanceBea initiated the Kalico project together with Ma\u00ebl, forking the awesome Klipper firmware originally as \"Danger-Klipper\" to add some bleeding edge spice to it. \"So I saw people wanted some community-driven features in klipper, so i was like \"ehh, i'll just fork it and give it a go\" bwnance @bwnance Ma\u00ebl KerbiriouMa\u00ebl together with Bea brought Kalico to life. piezoid @Piezoid Rogerio GoncalvesRoger chimed in early into the development of Kalico, and has since been a crucial contributor to the project. rogerlz @rogerlz Frank TackittFrank started his klipper hacking with exclude_object and just forgot to stop there frank.af @kageurufu"},{"location":"Sponsors.html#contributors","title":"Contributors","text":"Name Alias GitHub Vinzenz Hassert\"Uhh dunno... I mean I did pid profiles, filament sensors and curve control mainly. And I am best at giving Roger grey hairs cause I do huge pull requests!\" LastZeanon @LastZeanon Yancey ArringtonYancey wrote the docs for all the bleeding edge features and model predictive control, otherwise you wouldn't know about all the fancy stuff Kalico brings to the table! He also helps other community members a lot with their questions. What a great guy! Ray_Boy @YanceyA Ryan GhoshAll Ryan cares about are the TradRack and Belay modules of Kalico. How selfish! (no, in fact, that is very generous. Thanks Ryan!) RyanG @rsghosh Lasse DalegaardOur secret consultant for roasting everything. He also contributed a lot more than he is willing to admit. Silly Lasse. dalegaard @dalegaard Philipp MolitorPhil started hacking around with the docs because he does web stuff and 3D printers, and liked the Kalico Crew so much he just... stuck around.\"Hehehe... I wrote this page!\" philm0 @PhilippMolitor"},{"location":"Sponsors.html#other-kalico-contributors","title":"Other Kalico Contributors","text":"

    Kalico is a community effort, and we have a lot more people helping us! For a full list of people, have a look at the members of the GitHub Organization and our Contributors.

    "},{"location":"Sponsors.html#original-klipper-developers","title":"Original Klipper Developers","text":"

    See https://www.klipper3d.org/Sponsors.html for further information.

    "},{"location":"Sponsors.html#kevin-oconnor","title":"Kevin O'Connor","text":"

    Kevin is the original author and current maintainer of Klipper. Donate at: https://ko-fi.com/koconnor or https://www.patreon.com/koconnor

    "},{"location":"Sponsors.html#eric-callahan","title":"Eric Callahan","text":"

    Eric is the author of bed_mesh, spi_flash, and several other Klipper modules. Eric has a donations page at: https://ko-fi.com/arksine

    "},{"location":"Sponsors.html#related-kalico-projects","title":"Related Kalico Projects","text":"

    Kalico is frequently used with other Free Software. Consider using or supporting these projects.

    "},{"location":"Status_Reference.html","title":"Status reference","text":"

    This document is a reference of printer status information available in Kalico macros, display fields, and via the API Server.

    The fields in this document are subject to change - if using an attribute be sure to review the Config Changes document when upgrading the Kalico software.

    "},{"location":"Status_Reference.html#angle","title":"angle","text":"

    The following information is available in angle some_name objects:

    "},{"location":"Status_Reference.html#bed_mesh","title":"bed_mesh","text":"

    The following information is available in the bed_mesh object:

    "},{"location":"Status_Reference.html#bed_screws","title":"bed_screws","text":"

    The following information is available in the Config_Reference.md#bed_screws object:

    "},{"location":"Status_Reference.html#belay","title":"belay","text":"

    The following information is available in belay some_name objects:

    "},{"location":"Status_Reference.html#configfile","title":"configfile","text":"

    The following information is available in the configfile object (this object is always available):

    "},{"location":"Status_Reference.html#display_status","title":"display_status","text":"

    The following information is available in the display_status object (this object is automatically available if a display config section is defined):

    "},{"location":"Status_Reference.html#dockable_probe","title":"dockable_probe","text":"

    The following information is available in the dockable_probe:

    "},{"location":"Status_Reference.html#endstop_phase","title":"endstop_phase","text":"

    The following information is available in the endstop_phase object:

    "},{"location":"Status_Reference.html#exclude_object","title":"exclude_object","text":"

    The following information is available in the exclude_object object:

    [\n  {\n    \"polygon\": [\n      [ 156.25, 146.2511675 ],\n      [ 156.25, 153.7488325 ],\n      [ 163.75, 153.7488325 ],\n      [ 163.75, 146.2511675 ]\n    ],\n    \"name\": \"CYLINDER_2_STL_ID_2_COPY_0\",\n    \"center\": [ 160, 150 ]\n  },\n  {\n    \"polygon\": [\n      [ 146.25, 146.2511675 ],\n      [ 146.25, 153.7488325 ],\n      [ 153.75, 153.7488325 ],\n      [ 153.75, 146.2511675 ]\n    ],\n    \"name\": \"CYLINDER_2_STL_ID_1_COPY_0\",\n    \"center\": [ 150, 150 ]\n  }\n]\n
    "},{"location":"Status_Reference.html#extruder_stepper","title":"extruder_stepper","text":"

    The following information is available for extruder_stepper objects (as well as extruder objects):

    "},{"location":"Status_Reference.html#fan","title":"fan","text":"

    The following information is available in fan, heater_fan some_name and controller_fan some_name objects:

    "},{"location":"Status_Reference.html#filament_switch_sensor","title":"filament_switch_sensor","text":"

    The following information is available in filament_switch_sensor some_name objects:

    "},{"location":"Status_Reference.html#filament_motion_sensor","title":"filament_motion_sensor","text":"

    The following information is available in filament_motion_sensor some_name objects:

    "},{"location":"Status_Reference.html#firmware_retraction","title":"firmware_retraction","text":"

    The following information is available in the firmware_retraction object:

    "},{"location":"Status_Reference.html#gcode","title":"gcode","text":"

    The following information is available in the gcode object:

    "},{"location":"Status_Reference.html#gcode_button","title":"gcode_button","text":"

    The following information is available in gcode_button some_name objects:

    "},{"location":"Status_Reference.html#gcode_button_1","title":"gcode_button","text":"

    The following information is available in gcode_button some_name objects:

    "},{"location":"Status_Reference.html#gcode_macro","title":"gcode_macro","text":"

    The following information is available in gcode_macro some_name objects:

    "},{"location":"Status_Reference.html#gcode_move","title":"gcode_move","text":"

    The following information is available in the gcode_move object (this object is always available):

    "},{"location":"Status_Reference.html#hall_filament_width_sensor","title":"hall_filament_width_sensor","text":"

    The following information is available in the hall_filament_width_sensor object:

    "},{"location":"Status_Reference.html#heater","title":"heater","text":"

    The following information is available for heater objects such as extruder, heater_bed, and heater_generic:

    "},{"location":"Status_Reference.html#heaters","title":"heaters","text":"

    The following information is available in the heaters object (this object is available if any heater is defined):

    "},{"location":"Status_Reference.html#idle_timeout","title":"idle_timeout","text":"

    The following information is available in the idle_timeout object (this object is always available):

    "},{"location":"Status_Reference.html#led","title":"led","text":"

    The following information is available for each [led led_name], [neopixel led_name], [dotstar led_name], [pca9533 led_name], and [pca9632 led_name] config section defined in printer.cfg:

    "},{"location":"Status_Reference.html#manual_probe","title":"manual_probe","text":"

    The following information is available in the manual_probe object:

    "},{"location":"Status_Reference.html#mcu","title":"mcu","text":"

    The following information is available in mcu and mcu some_name objects:

    "},{"location":"Status_Reference.html#mixing_extruder","title":"mixing_extruder","text":"

    The following information is available in the mixing_extruder object (this object is automatically available if any stepper config section is defined):

    The following information is available in mixing_extruder objects:

    "},{"location":"Status_Reference.html#motion_report","title":"motion_report","text":"

    The following information is available in the motion_report object (this object is automatically available if any stepper config section is defined):

    "},{"location":"Status_Reference.html#output_pin","title":"output_pin","text":"

    The following information is available in output_pin some_name and pwm_tool some_name objects:

    "},{"location":"Status_Reference.html#palette2","title":"palette2","text":"

    The following information is available in the palette2 object:

    "},{"location":"Status_Reference.html#pause_resume","title":"pause_resume","text":"

    The following information is available in the pause_resume object:

    "},{"location":"Status_Reference.html#print_stats","title":"print_stats","text":"

    The following information is available in the print_stats object (this object is automatically available if a virtual_sdcard config section is defined):

    "},{"location":"Status_Reference.html#probe","title":"probe","text":"

    The following information is available in the probe object (this object is also available if a bltouch config section is defined):

    "},{"location":"Status_Reference.html#pwm_cycle_time","title":"pwm_cycle_time","text":"

    The following information is available in pwm_cycle_time some_name objects:

    "},{"location":"Status_Reference.html#quad_gantry_level","title":"quad_gantry_level","text":"

    The following information is available in the quad_gantry_level object (this object is available if quad_gantry_level is defined):

    "},{"location":"Status_Reference.html#query_endstops","title":"query_endstops","text":"

    The following information is available in the query_endstops object (this object is available if any endstop is defined):

    "},{"location":"Status_Reference.html#screws_tilt_adjust","title":"screws_tilt_adjust","text":"

    The following information is available in the screws_tilt_adjust object:

    "},{"location":"Status_Reference.html#servo","title":"servo","text":"

    The following information is available in servo some_name objects:

    "},{"location":"Status_Reference.html#stepper_enable","title":"stepper_enable","text":"

    The following information is available in the stepper_enable object (this object is available if any stepper is defined):

    "},{"location":"Status_Reference.html#system_stats","title":"system_stats","text":"

    The following information is available in the system_stats object (this object is always available):

    "},{"location":"Status_Reference.html#temperature-sensors","title":"temperature sensors","text":"

    The following information is available in

    bme280 config_section_name, htu21d config_section_name, sht3x config_section_name, lm75 config_section_name, temperature_host config_section_name and temperature_combined config_section_name objects:

    "},{"location":"Status_Reference.html#temperature_fan","title":"temperature_fan","text":"

    The following information is available in temperature_fan some_name objects:

    "},{"location":"Status_Reference.html#temperature_sensor","title":"temperature_sensor","text":"

    The following information is available in temperature_sensor some_name objects:

    "},{"location":"Status_Reference.html#tmc-drivers","title":"tmc drivers","text":"

    The following information is available in TMC stepper driver objects (eg, [tmc2208 stepper_x]):

    "},{"location":"Status_Reference.html#toolhead","title":"toolhead","text":"

    The following information is available in the toolhead object (this object is always available):

    "},{"location":"Status_Reference.html#dual_carriage","title":"dual_carriage","text":"

    The following information is available in dual_carriage on a cartesian, hybrid_corexy or hybrid_corexz robot

    "},{"location":"Status_Reference.html#tools_calibrate","title":"tools_calibrate","text":"

    The following information is available in the tools_calibrate object:

    "},{"location":"Status_Reference.html#trad_rack","title":"trad_rack","text":"

    The following informatin is available in the trad_rack object:

    "},{"location":"Status_Reference.html#virtual_sdcard","title":"virtual_sdcard","text":"

    The following information is available in the virtual_sdcard object:

    "},{"location":"Status_Reference.html#webhooks","title":"webhooks","text":"

    The following information is available in the webhooks object (this object is always available):

    "},{"location":"Status_Reference.html#z_thermal_adjust","title":"z_thermal_adjust","text":"

    The following information is available in the z_thermal_adjust object (this object is available if z_thermal_adjust is defined).

    "},{"location":"Status_Reference.html#z_tilt","title":"z_tilt","text":"

    The following information is available in the z_tilt object (this object is available if z_tilt is defined):

    "},{"location":"TMC_Drivers.html","title":"TMC drivers","text":"

    This document provides information on using Trinamic stepper motor drivers in SPI/UART mode on Kalico.

    Kalico can also use Trinamic drivers in their \"standalone mode\". However, when the drivers are in this mode, no special Kalico configuration is needed and the advanced Kalico features discussed in this document are not available.

    In addition to this document, be sure to review the TMC driver config reference.

    "},{"location":"TMC_Drivers.html#tuning-motor-current","title":"Tuning motor current","text":"

    A higher driver current increases positional accuracy and torque. However, a higher current also increases the heat produced by the stepper motor and the stepper motor driver. If the stepper motor driver gets too hot it will disable itself and Kalico will report an error. If the stepper motor gets too hot, it loses torque and positional accuracy. (If it gets very hot it may also melt plastic parts attached to it or near it.)

    As a general tuning tip, prefer higher current values as long as the stepper motor does not get too hot and the stepper motor driver does not report warnings or errors. In general, it is okay for the stepper motor to feel warm, but it should not become so hot that it is painful to touch.

    "},{"location":"TMC_Drivers.html#prefer-to-not-specify-a-hold_current","title":"Prefer to not specify a hold_current","text":"

    If one configures a hold_current then the TMC driver can reduce current to the stepper motor when it detects that the stepper is not moving. However, changing motor current may itself introduce motor movement. This may occur due to \"detent forces\" within the stepper motor (the permanent magnet in the rotor pulls towards the iron teeth in the stator) or due to external forces on the axis carriage.

    Most stepper motors will not obtain a significant benefit to reducing current during normal prints, because few printing moves will leave a stepper motor idle for sufficiently long to activate the hold_current feature. And, it is unlikely that one would want to introduce subtle print artifacts to the few printing moves that do leave a stepper idle sufficiently long.

    If one wishes to reduce current to motors during print start routines, then consider issuing SET_TMC_CURRENT commands in a START_PRINT macro to adjust the current before and after normal printing moves.

    Some printers with dedicated Z motors that are idle during normal printing moves (no bed_mesh, no bed_tilt, no Z skew_correction, no \"vase mode\" prints, etc.) may find that Z motors do run cooler with a hold_current. If implementing this then be sure to take into account this type of uncommanded Z axis movement during bed leveling, bed probing, probe calibration, and similar. The driver_TPOWERDOWN and driver_IHOLDDELAY should also be calibrated accordingly. If unsure, prefer to not specify a hold_current.

    "},{"location":"TMC_Drivers.html#setting-spreadcycle-vs-stealthchop-mode","title":"Setting \"spreadCycle\" vs \"stealthChop\" Mode","text":"

    By default, Kalico places the TMC drivers in \"spreadCycle\" mode. If the driver supports \"stealthChop\" then it can be enabled by adding stealthchop_threshold: 999999 to the TMC config section.

    In general, spreadCycle mode provides greater torque and greater positional accuracy than stealthChop mode. However, stealthChop mode may produce significantly lower audible noise on some printers.

    Tests comparing modes have shown an increased \"positional lag\" of around 75% of a full-step during constant velocity moves when using stealthChop mode (for example, on a printer with 40mm rotation_distance and 200 steps_per_rotation, position deviation of constant speed moves increased by ~0.150mm). However, this \"delay in obtaining the requested position\" may not manifest as a significant print defect and one may prefer the quieter behavior of stealthChop mode.

    It is recommended to always use \"spreadCycle\" mode (by not specifying stealthchop_threshold) or to always use \"stealthChop\" mode (by setting stealthchop_threshold to 999999). Unfortunately, the drivers often produce poor and confusing results if the mode changes while the motor is at a non-zero velocity.

    "},{"location":"TMC_Drivers.html#tmc-interpolate-setting-introduces-small-position-deviation","title":"TMC interpolate setting introduces small position deviation","text":"

    The TMC driver interpolate setting may reduce the audible noise of printer movement at the cost of introducing a small systemic positional error. This systemic positional error results from the driver's delay in executing \"steps\" that Kalico sends it. During constant velocity moves, this delay results in a positional error of nearly half a configured microstep (more precisely, the error is half a microstep distance minus a 512th of a full step distance). For example, on an axis with a 40mm rotation_distance, 200 steps_per_rotation, and 16 microsteps, the systemic error introduced during constant velocity moves is ~0.006mm.

    For best positional accuracy consider using spreadCycle mode and disable interpolation (set interpolate: False in the TMC driver config). When configured this way, one may increase the microstep setting to reduce audible noise during stepper movement. Typically, a microstep setting of 64 or 128 will have similar audible noise as interpolation, and do so without introducing a systemic positional error.

    If using stealthChop mode then the positional inaccuracy from interpolation is small relative to the positional inaccuracy introduced from stealthChop mode. Therefore tuning interpolation is not considered useful when in stealthChop mode, and one can leave interpolation in its default state.

    "},{"location":"TMC_Drivers.html#sensorless-homing","title":"Sensorless Homing","text":"

    Sensorless homing allows to home an axis without the need for a physical limit switch. Instead, the carriage on the axis is moved into the mechanical limit making the stepper motor lose steps. The stepper driver senses the lost steps and indicates this to the controlling MCU (Kalico) by toggling a pin. This information can be used by Kalico as end stop for the axis.

    This guide covers the setup of sensorless homing for the X axis of your (cartesian) printer. However, it works the same with all other axes (that require an end stop). You should configure and tune it for one axis at a time.

    "},{"location":"TMC_Drivers.html#limitations","title":"Limitations","text":"

    Be sure that your mechanical components are able to handle the load of the carriage bumping into the limit of the axis repeatedly. Especially leadscrews might generate a lot of force. Homing a Z axis by bumping the nozzle into the printing surface might not be a good idea. For best results, verify that the axis carriage will make a firm contact with the axis limit.

    Further, sensorless homing might not be accurate enough for your printer. While homing X and Y axes on a cartesian machine can work well, homing the Z axis is generally not accurate enough and may result in an inconsistent first layer height. Homing a delta printer sensorless is not advisable due to missing accuracy.

    Further, the stall detection of the stepper driver is dependent on the mechanical load on the motor, the motor current and the motor temperature (coil resistance).

    Sensorless homing works best at medium motor speeds. For very slow speeds (less than 10 RPM) the motor does not generate significant back EMF and the TMC cannot reliably detect motor stalls. Further, at very high speeds, the back EMF of the motor approaches the supply voltage of the motor, so the TMC cannot detect stalls anymore. It is advised to have a look in the datasheet of your specific TMCs. There you can also find more details on limitations of this setup.

    "},{"location":"TMC_Drivers.html#prerequisites","title":"Prerequisites","text":"

    A few prerequisites are needed to use sensorless homing:

    1. A stallGuard capable TMC stepper driver (tmc2130, tmc2209, tmc2660, tmc5160 or tmc2160).
    2. SPI / UART interface of the TMC driver wired to micro-controller (stand-alone mode does not work).
    3. The appropriate \"DIAG\" or \"SG_TST\" pin of TMC driver connected to the micro-controller.
    4. The steps in the config checks document must be run to confirm the stepper motors are configured and working properly.
    "},{"location":"TMC_Drivers.html#tuning","title":"Tuning","text":"

    The procedure described here has six major steps:

    1. Choose a homing speed.
    2. Configure the printer.cfg file to enable sensorless homing.
    3. Find the stallguard setting with highest sensitivity that successfully homes.
    4. Find the stallguard setting with lowest sensitivity that successfully homes with a single touch.
    5. Update the printer.cfg with the desired stallguard setting.
    6. Create or update printer.cfg macros to home consistently.
    "},{"location":"TMC_Drivers.html#choose-homing-speed","title":"Choose homing speed","text":"

    The homing speed is an important choice when performing sensorless homing. It's desirable to use a slow homing speed so that the carriage does not exert excessive force on the frame when making contact with the end of the rail. However, the TMC drivers can't reliably detect a stall at very slow speeds.

    A good starting point for the homing speed is for the stepper motor to make a full rotation every two seconds. For many axes this will be the rotation_distance divided by two. For example:

    [stepper_x]\nrotation_distance: 40\nhoming_speed: 20\n...\n
    "},{"location":"TMC_Drivers.html#configure-printercfg-for-sensorless-homing","title":"Configure printer.cfg for sensorless homing","text":"

    Be sure that a hold_current setting is not specified in the TMC driver section of the config. (If a hold_current is set then after contact is made, the motor stops while the carriage is pressed against the end of the rail, and reducing the current while in that position may cause the carriage to move - that results in poor performance and will confuse the tuning process.)

    It is necessary to configure the sensorless homing pins and to configure initial \"stallguard\" settings. A tmc2209 example configuration for an X axis might look like:

    [tmc2209 stepper_x]\ndiag_pin: ^PA1      # Set to MCU pin connected to TMC DIAG pin\ndriver_SGTHRS: 255  # 255 is most sensitive value, 0 is least sensitive\nhome_current: 1\n...\n\n[stepper_x]\nendstop_pin: tmc2209_stepper_x:virtual_endstop\nhoming_retract_dist: 10 # Must be greater than 0 or set use_sensorless_homing: True\n...\n

    An example tmc2130 or tmc5160 config might look like:

    [tmc2130 stepper_x]\ndiag1_pin: ^!PA1 # Pin connected to TMC DIAG1 pin (or use diag0_pin / DIAG0 pin)\ndriver_SGT: -64  # -64 is most sensitive value, 63 is least sensitive\nhome_current: 1\n...\n\n[stepper_x]\nendstop_pin: tmc2130_stepper_x:virtual_endstop\nhoming_retract_dist: 10\n...\n

    An example tmc2660 config might look like:

    [tmc2660 stepper_x]\ndriver_SGT: -64     # -64 is most sensitive value, 63 is least sensitive\nhome_current: 1\n...\n\n[stepper_x]\nendstop_pin: ^PA1   # Pin connected to TMC SG_TST pin\nuse_sensorless_homing: True # Required if endstop_pin is not a virtual_endstop\nhoming_retract_dist: 10\n...\n

    The examples above only show settings specific to sensorless homing. See the config reference for all the available options.

    "},{"location":"TMC_Drivers.html#find-highest-sensitivity-that-successfully-homes","title":"Find highest sensitivity that successfully homes","text":"

    Place the carriage near the center of the rail. Use the SET_TMC_FIELD command to set the highest sensitivity. For tmc2209:

    SET_TMC_FIELD STEPPER=stepper_x FIELD=SGTHRS VALUE=255\n

    For tmc2130, tmc5160, tmc2160, and tmc2660:

    SET_TMC_FIELD STEPPER=stepper_x FIELD=sgt VALUE=-64\n

    Then issue a G28 X0 command and verify the axis does not move at all or quickly stops moving. If the axis does not stop, then issue an M112 to halt the printer - something is not correct with the diag/sg_tst pin wiring or configuration and it must be corrected before continuing.

    Next, continually decrease the sensitivity of the VALUE setting and run the SET_TMC_FIELD G28 X0 commands again to find the highest sensitivity that results in the carriage successfully moving all the way to the endstop and halting. (For tmc2209 drivers this will be decreasing SGTHRS, for other drivers it will be increasing sgt.) Be sure to start each attempt with the carriage near the center of the rail (if needed issue M84 and then manually move the carriage to the center). It should be possible to find the highest sensitivity that homes reliably (settings with higher sensitivity result in small or no movement). Note the found value as maximum_sensitivity. (If the minimum possible sensitivity (SGTHRS=0 or sgt=63) is obtained without any carriage movement then something is not correct with the diag/sg_tst pin wiring or configuration and it must be corrected before continuing.)

    When searching for maximum_sensitivity, it may be convenient to jump to different VALUE settings (so as to bisect the VALUE parameter). If doing this then be prepared to issue an M112 command to halt the printer, as a setting with a very low sensitivity may cause the axis to repeatedly \"bang\" into the end of the rail.

    Be sure to wait a couple of seconds between each homing attempt. After the TMC driver detects a stall it may take a little time for it to clear its internal indicator and be capable of detecting another stall.

    During these tuning tests, if a G28 X0 command does not move all the way to the axis limit, then be careful with issuing any regular movement commands (eg, G1). Kalico will not have a correct understanding of the carriage position and a move command may cause undesirable and confusing results.

    "},{"location":"TMC_Drivers.html#find-lowest-sensitivity-that-homes-with-one-touch","title":"Find lowest sensitivity that homes with one touch","text":"

    When homing with the found maximum_sensitivity value, the axis should move to the end of the rail and stop with a \"single touch\" - that is, there should not be a \"clicking\" or \"banging\" sound. (If there is a banging or clicking sound at maximum_sensitivity then the homing_speed may be too low, the driver current may be too low, or sensorless homing may not be a good choice for the axis.)

    The next step is to again continually move the carriage to a position near the center of the rail, decrease the sensitivity, and run the SET_TMC_FIELD G28 X0 commands - the goal is now to find the lowest sensitivity that still results in the carriage successfully homing with a \"single touch\". That is, it does not \"bang\" or \"click\" when contacting the end of the rail. Note the found value as minimum_sensitivity.

    "},{"location":"TMC_Drivers.html#update-printercfg-with-sensitivity-value","title":"Update printer.cfg with sensitivity value","text":"

    After finding maximum_sensitivity and minimum_sensitivity, use a calculator to obtain the recommend sensitivity as minimum_sensitivity + (maximum_sensitivity - minimum_sensitivity)/3. The recommended sensitivity should be in the range between the minimum and maximum, but slightly closer to the minimum. Round the final value to the nearest integer value.

    For tmc2209 set this in the config as driver_SGTHRS, for other TMC drivers set this in the config as driver_SGT.

    If the range between maximum_sensitivity and minimum_sensitivity is small (eg, less than 5) then it may result in unstable homing. A faster homing speed may increase the range and make the operation more stable.

    Note that if any change is made to driver current, homing speed, or a notable change is made to the printer hardware, then it will be necessary to run the tuning process again.

    "},{"location":"TMC_Drivers.html#using-macros-when-homing","title":"Using Macros when Homing","text":"

    Unlike Klipper, in Kalico, you do not need macros for sensorless homing management. Homing current is handled by the TMC block, homing retract distance is used to define a minimum homing distance (which can also be manually configured) which is used for sensorless homing verification as well as post home retract. In depth guide for sensorless setup coming soon.

    "},{"location":"TMC_Drivers.html#tips-for-sensorless-homing-on-corexy","title":"Tips for sensorless homing on CoreXY","text":"

    It is possible to use sensorless homing on the X and Y carriages of a CoreXY printer. Kalico uses the [stepper_x] stepper to detect stalls when homing the X carriage and uses the [stepper_y] stepper to detect stalls when homing the Y carriage.

    Use the tuning guide described above to find the appropriate \"stall sensitivity\" for each carriage, but be aware of the following restrictions:

    1. When using sensorless homing on CoreXY, make sure there is no hold_current configured for either stepper.
    2. While tuning, make sure both the X and Y carriages are near the center of their rails before each home attempt.
    3. After tuning is complete, when homing both X and Y, use macros to ensure that one axis is homed first, then move that carriage away from the axis limit, pause for at least 2 seconds, and then start the homing of the other carriage. The move away from the axis avoids homing one axis while the other is pressed against the axis limit (which may skew the stall detection). The pause is necessary to ensure the driver's stall flag is cleared prior to homing again.

    An example CoreXY homing macro might look like:

    [gcode_macro HOME]\ngcode:\n    G90\n    # Home Z\n    G28 Z0\n    G1 Z10 F1200\n    # Home Y\n    G28 Y0\n    G1 Y5 F1200\n    # Home X\n    G4 P2000\n    G28 X0\n    G1 X5 F1200\n
    "},{"location":"TMC_Drivers.html#querying-and-diagnosing-driver-settings","title":"Querying and diagnosing driver settings","text":"

    The `DUMP_TMC command is a useful tool when configuring and diagnosing the drivers. It will report all fields configured by Kalico as well as all fields that can be queried from the driver.

    All of the reported fields are defined in the Trinamic datasheet for each driver. These datasheets can be found on the Trinamic website. Obtain and review the Trinamic datasheet for the driver to interpret the results of DUMP_TMC.

    "},{"location":"TMC_Drivers.html#configuring-driver_xxx-settings","title":"Configuring driver_XXX settings","text":"

    Kalico supports configuring many low-level driver fields using driver_XXX settings. The TMC driver config reference has the full list of fields available for each type of driver.

    In addition, almost all fields can be modified at run-time using the SET_TMC_FIELD command.

    Each of these fields is defined in the Trinamic datasheet for each driver. These datasheets can be found on the Trinamic website.

    Note that the Trinamic datasheets sometime use wording that can confuse a high-level setting (such as \"hysteresis end\") with a low-level field value (eg, \"HEND\"). In Kalico, driver_XXX and SET_TMC_FIELD always set the low-level field value that is actually written to the driver. So, for example, if the Trinamic datasheet states that a value of 3 must be written to the HEND field to obtain a \"hysteresis end\" of 0, then set driver_HEND=3 to obtain the high-level value of 0.

    "},{"location":"TMC_Drivers.html#common-questions","title":"Common Questions","text":""},{"location":"TMC_Drivers.html#can-i-use-stealthchop-mode-on-an-extruder-with-pressure-advance","title":"Can I use stealthChop mode on an extruder with pressure advance?","text":"

    Many people successfully use \"stealthChop\" mode with Kalico's pressure advance. Kalico implements smooth pressure advance which does not introduce any instantaneous velocity changes.

    However, \"stealthChop\" mode may produce lower motor torque and/or produce higher motor heat. It may or may not be an adequate mode for your particular printer.

    "},{"location":"TMC_Drivers.html#i-keep-getting-unable-to-read-tmc-uart-stepper_x-register-ifcnt-errors","title":"I keep getting \"Unable to read tmc uart 'stepper_x' register IFCNT\" errors?","text":"

    This occurs when Kalico is unable to communicate with a tmc2208 or tmc2209 driver.

    Make sure that the motor power is enabled, as the stepper motor driver generally needs motor power before it can communicate with the micro-controller.

    If this error occurs after flashing Kalico for the first time, then the stepper driver may have been previously programmed in a state that is not compatible with Kalico. To reset the state, remove all power from the printer for several seconds (physically unplug both USB and power plugs).

    Otherwise, this error is typically the result of incorrect UART pin wiring or an incorrect Kalico configuration of the UART pin settings.

    "},{"location":"TMC_Drivers.html#i-keep-getting-unable-to-write-tmc-spi-stepper_x-register-errors","title":"I keep getting \"Unable to write tmc spi 'stepper_x' register ...\" errors?","text":"

    This occurs when Kalico is unable to communicate with a tmc2130, tmc5160 or tmc2160 driver.

    Make sure that the motor power is enabled, as the stepper motor driver generally needs motor power before it can communicate with the micro-controller.

    Otherwise, this error is typically the result of incorrect SPI wiring, an incorrect Kalico configuration of the SPI settings, or an incomplete configuration of devices on an SPI bus.

    Note that if the driver is on a shared SPI bus with multiple devices then be sure to fully configure every device on that shared SPI bus in Kalico. If a device on a shared SPI bus is not configured, then it may incorrectly respond to commands not intended for it and corrupt the communication to the intended device. If there is a device on a shared SPI bus that can not be configured in Kalico, then use a static_digital_output config section to set the CS pin of the unused device high (so that it will not attempt to use the SPI bus). The board's schematic is often a useful reference for finding which devices are on an SPI bus and their associated pins.

    "},{"location":"TMC_Drivers.html#why-did-i-get-a-tmc-reports-error-error","title":"Why did I get a \"TMC reports error: ...\" error?","text":"

    This type of error indicates the TMC driver detected a problem and has disabled itself. That is, the driver stopped holding its position and ignored movement commands. If Kalico detects that an active driver has disabled itself, it will transition the printer into a \"shutdown\" state.

    It's also possible that a TMC reports error shutdown occurs due to SPI errors that prevent communication with the driver (on tmc2130, tmc5160, tmc2160, or tmc2660). If this occurs, it's common for the reported driver status to show 00000000 or ffffffff - for example: TMC reports error: DRV_STATUS: ffffffff ... OR TMC reports error: READRSP@RDSEL2: 00000000 .... Such a failure may be due to an SPI wiring problem or may be due to a self-reset or failure of the TMC driver.

    Some common errors and tips for diagnosing them:

    "},{"location":"TMC_Drivers.html#tmc-reports-error-ot1overtemperror","title":"TMC reports error: ... ot=1(OvertempError!)","text":"

    This indicates the motor driver disabled itself because it became too hot. Typical solutions are to decrease the stepper motor current, increase cooling on the stepper motor driver, and/or increase cooling on the stepper motor.

    "},{"location":"TMC_Drivers.html#tmc-reports-error-shorttognd-or-shorttosupply","title":"TMC reports error: ... ShortToGND OR ShortToSupply","text":"

    This indicates the driver has disabled itself because it detected very high current passing through the driver. This may indicate a loose or shorted wire to the stepper motor or within the stepper motor itself.

    This error may also occur if using stealthChop mode and the TMC driver is not able to accurately predict the mechanical load of the motor. (If the driver makes a poor prediction then it may send too much current through the motor and trigger its own over-current detection.) To test this, disable stealthChop mode and check if the errors continue to occur.

    "},{"location":"TMC_Drivers.html#tmc-reports-error-reset1reset-or-cs_actual0reset-or-se0reset","title":"TMC reports error: ... reset=1(Reset) OR CS_ACTUAL=0(Reset?) OR SE=0(Reset?)","text":"

    This indicates that the driver has reset itself mid-print. This may be due to voltage or wiring issues.

    "},{"location":"TMC_Drivers.html#tmc-reports-error-uv_cp1undervoltage","title":"TMC reports error: ... uv_cp=1(Undervoltage!)","text":"

    This indicates the driver has detected a low-voltage event and has disabled itself. This may be due to wiring or power supply issues.

    "},{"location":"TMC_Drivers.html#how-do-i-tune-spreadcyclecoolstepetc-mode-on-my-drivers","title":"How do I tune spreadCycle/coolStep/etc. mode on my drivers?","text":"

    The Trinamic website has guides on configuring the drivers. These guides are often technical, low-level, and may require specialized hardware. Regardless, they are the best source of information.

    "},{"location":"TSL1401CL_Filament_Width_Sensor.html","title":"TSL1401CL filament width sensor","text":"

    This document describes Filament Width Sensor host module. Hardware used for developing this host module is based on TSL1401CL linear sensor array but it can work with any sensor array that has analog output. You can find designs at Thingiverse.

    To use a sensor array as a filament width sensor, read Config Reference and G-Code documentation.

    "},{"location":"TSL1401CL_Filament_Width_Sensor.html#how-does-it-work","title":"How does it work?","text":"

    Sensor generates analog output based on calculated filament width. Output voltage always equals to detected filament width (Ex. 1.65v, 1.70v, 3.0v). Host module monitors voltage changes and adjusts extrusion multiplier.

    "},{"location":"TSL1401CL_Filament_Width_Sensor.html#note","title":"Note:","text":"

    Sensor readings done with 10 mm intervals by default. If necessary you are free to change this setting by editing MEASUREMENT_INTERVAL_MM parameter in filament_width_sensor.py file.

    "},{"location":"Using_PWM_Tools.html","title":"Using PWM tools","text":"

    This document describes how to setup a PWM-controlled laser or spindle using pwm_tool and some macros.

    "},{"location":"Using_PWM_Tools.html#how-does-it-work","title":"How does it work?","text":"

    With re-purposing the printhead's fan pwm output, you can control lasers or spindles. This is useful if you use switchable print heads, for example the E3D toolchanger or a DIY solution. Usually, cam-tools such as LaserWeb can be configured to use M3-M5 commands, which stand for spindle speed CW (M3 S[0-255]), spindle speed CCW (M4 S[0-255]) and spindle stop (M5).

    Warning: When driving a laser, keep all security precautions that you can think of! Diode lasers are usually inverted. This means, that when the MCU restarts, the laser will be fully on for the time it takes the MCU to start up again. For good measure, it is recommended to always wear appropriate laser-goggles of the right wavelength if the laser is powered; and to disconnect the laser when it is not needed. Also, you should configure a safety timeout, so that when your host or MCU encounters an error, the tool will stop.

    For an example configuration, see config/sample-pwm-tool.cfg.

    "},{"location":"Using_PWM_Tools.html#commands","title":"Commands","text":"

    M3/M4 S<value> : Set PWM duty-cycle. Values between 0 and 255. M5 : Stop PWM output to shutdown value.

    "},{"location":"Using_PWM_Tools.html#laserweb-configuration","title":"Laserweb Configuration","text":"

    If you use Laserweb, a working configuration would be:

    GCODE START:\n    M5            ; Disable Laser\n    G21           ; Set units to mm\n    G90           ; Absolute positioning\n    G0 Z0 F7000   ; Set Non-Cutting speed\n\nGCODE END:\n    M5            ; Disable Laser\n    G91           ; relative\n    G0 Z+20 F4000 ;\n    G90           ; absolute\n\nGCODE HOMING:\n    M5            ; Disable Laser\n    G28           ; Home all axis\n\nTOOL ON:\n    M3 $INTENSITY\n\nTOOL OFF:\n    M5            ; Disable Laser\n\nLASER INTENSITY:\n    S\n
    "},{"location":"Z_Calibration.html","title":"Automatic Z-Offset Calibration","text":"

    This document provides information on calibrating the nozzle's Z offset automatically. With this enabled, manual Z offset or first layer calibrations are needless. It computes always the correct offset independantly of the current temperature, used nozzle or used print bed or flex plate.

    "},{"location":"Z_Calibration.html#why-this","title":"Why This","text":"

    It is possible and this it is what this extension does!

    "},{"location":"Z_Calibration.html#requirements","title":"Requirements","text":"

    But, there are some requirements to use it:

    "},{"location":"Z_Calibration.html#what-it-does","title":"What It Does","text":"
    1. A normal homing of all axes using the Z endstop for Z (this is not part of this plugin). After that, there is a defined zero point in Z. From now on, everything is in relation to this point. So, a new homing would change everything, since the homing is not that precise.
    2. Determine the height of the nozzle by probing the tip of it on the Z endstop (like the homing in step 1. But this one can result in a slightly different value):
    3. Determine the height of the mag-probe by probing the body of the switch on the z-endstop:

    4. Calculate the offset between the tip of the nozzle and the trigger point of the mag-probe:

      nozzle switch offset = mag probe height - nozzle height + switch offset

      The trigger point of the mag-probe cannot be probed directly. This is why the body of the switch is clicked on the endstop indstead of the trigger nob. This is why a small switch offset is used here to reflect the offset between the nob and the body of the switch while it is triggerd. This offset is fixed.

    5. Determine the height of the print surface by probing one point with the mag-probe on the bed (preferably the center or the \"bed_mesh:relative_reference_index\" of a configured/used mesh).

    6. Now, the final offset is calculated like this:

      probe offset = probed height - calculated nozzle switch offset

    7. Finally, the calculated offset is applied by using the SET_GCODE_OFFSET command (a previous offset is resetted before!).

    "},{"location":"Z_Calibration.html#interference","title":"Interference","text":"

    Temperature or humindity changes are not a big deal since the switch is not affected much by them and all values are probed in a small time period and only the releations to each other are used. The nozzle height in step 2 can be determined some time later and even many Celsius higher in the printer's chamber, compared to the homing in step 1. That is why the nozzle is probed again and can vary a little to the first homing position.

    "},{"location":"Z_Calibration.html#example-output","title":"Example Output","text":"

    The output of the calibration with all determined positions looks like this (the offset is the one which is applied as GCode offset):

    Z-CALIBRATION: ENDSTOP=-0.300 NOZZLE=-0.300 SWITCH=6.208 PROBE=7.013 --> OFFSET=-0.170\n

    The endstop value is the homed Z position which is always zero or the configure \"stepper_z:position_endstop\" setting - and in this case, it's even the same as the probed nozzle hight.

    "},{"location":"Z_Calibration.html#configuration","title":"Configuration","text":"

    To activate the extension, a [z_calibration] section is needed in the printer configuration. The configuration properties are described here in details.

    "},{"location":"Z_Calibration.html#switch-offset","title":"Switch Offset","text":"

    The \"z_calibration:switch_offset\" is the already mentioned offset from the switch body (which is the probed position) to the actual trigger point above it. A starting point for this value can be taken from the datasheet like from the Omron switch (D2F-5: 0.5mm and SSG-5H: 0.7mm). It's good to start with a little less depending on the squishiness you prefer for the first layer (it's about 0.45 for the D2F-5). So, with a smaller offset value, the nozzle is more away from the bed! The value cannot be negative.

    For example, the datasheet of the D2F-5:

    And the calculation of the offset base:

    offset base = OP (Operation Position) - switch body height\n     0.5 mm = 5.5 mm - 5 mm\n
    "},{"location":"Z_Calibration.html#attaching-and-detaching-the-probe","title":"Attaching and Detaching the Probe","text":"

    The attaching and detaching of the mag-probe can be done by creating a macro for the CALIBRATE_Z command and surround it by the appropriate commands:

    [gcode_macro CALIBRATE_Z]\ndescription: Automatically calibrates the nozzles offset to the print surface and dock/undock MagProbe\nrename_existing: CALIBRATE_Z_BASE\ngcode:\n  ATTACH_PROBE     # replace with the name of your specific attach macro\n  CALIBRATE_Z_BASE\n  DETACH_PROBE     # replace with the name of your specific detach macro\n

    It is also possible to use the start_gcode and end_gcode properties to call the attach and detach commands instead:

    [z_calibration]\n...\nstart_gcode: ATTACH_PROBE  # replace with the name of your specific attach macro\nend_gcode: DETACH_PROBE    # replace with the name of your specific detach macro\n

    If there are any space restrictions and it is not possible to probe the nozzle on the endstop with the probe attached, the before_switch_gcode property can be used to attach the probe instead of the start_gcode. Then, the probe is not attached until the probe is probed on the endstop:

    [z_calibration]\n...\nbefore_switch_gcode: ATTACH_PROBE  # replace with the name of your specific attach macro\nend_gcode: DETACH_PROBE            # replace with the name of your specific detach macro\n
    "},{"location":"Z_Calibration.html#bed-mesh","title":"Bed Mesh","text":"

    If a bed mesh is used, the coordinates for probing on the print bed must be exactly the relative reference index point of the mesh since this is the point zero of the mesh! But, it is possible to omit these properties completely and the relative reference index point of the mesh will be taken automatically (for this, the \"bed_mesh:relative_reference_index\" setting is required and there is no support for round bed/mesh so far)!

    "},{"location":"Z_Calibration.html#how-to-test-it","title":"How To Test It","text":"

    Do not bother too much about absolute values of the calculated offsets. These can vary a lot. Only the real position from the nozzle to the bed counts. To test this, the result of the calibration can be queried by GET_POSITION first:

    > CALIBRATE_Z\n> Z-CALIBRATION: ENDSTOP=-0.300 NOZZLE=-0.267 SWITCH=2.370 PROBE=3.093 --> OFFSET=-0.010000\n> GET_POSITION\n> mcu: stepper_x:17085 stepper_y:15625 stepper_z:-51454 stepper_z1:-51454 stepper_z2:-51454 stepper_z3:-51454\n> stepper: stepper_x:552.500000 stepper_y:-47.500000 stepper_z:10.022500 stepper_z1:10.022500 stepper_z2:10.022500 stepper_z3:10.022500\n> kinematic: X:252.500000 Y:300.000000 Z:10.022500\n> toolhead: X:252.500000 Y:300.000000 Z:10.021472 E:0.000000\n> gcode: X:252.500000 Y:300.000000 Z:9.990000 E:0.000000\n> gcode base: X:0.000000 Y:0.000000 Z:-0.010000 E:0.000000\n> gcode homing: X:0.000000 Y:0.000000 Z:-0.010000\n

    Here, the Z position in \"gcode base\" reflects the calibrated Z offset.

    Then, the offset can be tested by moving the nozzle slowly down to zero by moving it in multiple steps. It's good to do this by using GCodes, since the offset is applied as GCode-Offset. For example like this:

    > G90\n> G0 Z5\n> G0 Z3\n> G0 Z1\n> G0 Z0.5\n> G0 Z0.3\n> G0 Z0.1\n

    Check the distance to the print surface after every step. If there is a small discrepancy (which should be smaller than the offset base from the switch's datasheet), then adapt the \"z_calibration:switch_offset\" by that value. Decreasing the \"switch_offset\" will move the nozzle more away from the bed.

    And finally, if you have double checked, that the calibrated offset is correct, you can go for fine tuning the \"z_calibration:switch_offset\" by actually printing first layer tests. This needs to be done only once!

    "},{"location":"Z_Calibration.html#how-to-use-it","title":"How To Use It","text":""},{"location":"Z_Calibration.html#command-calibrate_z","title":"Command CALIBRATE_Z","text":"

    The calibration is started by using the CALIBRATE_Z command. There are no more parameters. A clean nozzle is needed for running this command.

    It does not matter when this calibration is called (and at what temperatures). But, it is importaint to call it just before starting a print when the printer is hot. So, it is good to add the CALIBRATE_Z command to the PRINT_START macro (which is called from the slicers start gCode). The sequence of this macro can look like this:

    1. Home all axes
    2. Heat up the bed and nozzle (and chamber)
    3. Get probe, make any bed leveling if needed (like QGL, Z-Tilt), park probe
    4. Purge and clean the nozzle
    5. Get probe, CALIBRATE_Z, park probe
    6. (Adjust Z offset if needed)
    7. Print intro line if used
    8. Start printing...

    :exclamation: And remove any old Z offset adjustments here (like SET_GCODE_OFFSET)

    For textured print surfaces, it might be necessary to go closer to the bed. To adjust the offset from the slicers start GCode, the following command can be added to the PRINT_START macro after calling the Z calibration:

        # Adjust the G-Code Z offset if needed\n    SET_GCODE_OFFSET Z_ADJUST={params.Z_ADJUST|default(0.0)|float} MOVE=1\n

    Then, a Z_ADJUST=0.0 can be added to the PRINT_START command in the Slicer. This does not reset the offset to this value but adjusts it by the given amount!

    NOTE: Do not home Z again after running the Z calibration or it needs to be executed again!

    "},{"location":"Z_Calibration.html#command-probe_z_accuracy","title":"Command PROBE_Z_ACCURACY","text":"

    There is also a PROBE_Z_ACCURACY command to test the accuracy of the Z endstop (like the PROBE_ACCURACY command of the probe):

    PROBE_Z_ACCURACY [PROBE_SPEED=<mm/s>] [LIFT_SPEED=<mm/s>] [SAMPLES=<count>] [SAMPLE_RETRACT_DIST=<mm>]\n

    It calculates the maximum, minimum, average, median and standard deviation of multiple probe samles on the endstop by taking the configured nozzle position on the endstop. The optional parameters default to their equivalent setting in the z_calibration config section.

    "},{"location":"Z_Calibration.html#ooze-mitigation","title":"Ooze Mitigation","text":"

    Ooze with any nozzle probe endstop can cause inaccuracies, as the filament will continue to leak or deform over the space of multiple probes. It is highly recommended to take some measures to prevent ooze buildup before the nozzle probe portion of this plugin.

    A slow long retraction, of as much as 15mm at print end, can reduce the potential for ooze. If you do this, consider adding a comparable extrude as the last command in your print start sequence to bring the plastic back to the tip. (Retracts longer than 5mm have been linked to clogs in many hotends, especially the Rapido. This may be best considered a last resort, depending on exact hardware and filament.)

    Heating the nozzle about a minute before scrubbing - using a purge bucket - will allow all the remaining plastic time to drain from the nozzle and be cleaned away by a simple wipe. If using a purge and scrubbing bucket, do not purge filament at this stage.

    An endstop switch that requires a stronger activation force, such as sexbolt with a spring, or unklicky z, can help squash any remaining ooze and improve consistency.

    Probing can be done with a hotend temperature below the full temperature for the print. If you print at 250, you can preheat the nozzle to 180, and run this script before finishing the heat up to full temperature. This may have varying effects depending on temperatures used.

    Also consider picking up your probe prior to your nozzle wipe, to allow this script to probe the nozzle immediately after cleaning it.

    "}]} \ No newline at end of file