diff --git a/docs/API_Server.md b/docs/API_Server.md index 6e43ce3e..1ccb6d91 100644 --- a/docs/API_Server.md +++ b/docs/API_Server.md @@ -1,9 +1,11 @@ +# API server + This document describes Klipper's Application Programmer Interface (API). This interface enables external applications to query and control the Klipper host software. Enabling the API socket -======================= +----------------------- In order to use the API server, the klippy.py host software must be started with the `-a` parameter. For example: @@ -16,7 +18,7 @@ can then open a connection on that socket and send commands to Klipper. Request format -============== +-------------- Messages sent and received on the socket are JSON encoded strings terminated by an ASCII 0x03 character: @@ -37,7 +39,7 @@ terminator when transmitting a request. (The Klipper API server does not have a newline requirement.) API Protocol -============ +------------ The command protocol used on the communication socket is inspired by [json-rpc](https://www.jsonrpc.org/). @@ -91,7 +93,7 @@ respect to responses from other requests. A JSON request will never pause the processing of future JSON requests. Subscriptions -============= +------------- Some Klipper "endpoint" requests allow one to "subscribe" to future asynchronous update messages. @@ -119,7 +121,7 @@ send that template. If a "response_template" field is not provided then it defaults to an empty dictionary (`{}`). Available "endpoints" -===================== +--------------------- By convention, Klipper "endpoints" are of the form `/`. When making a request to an "endpoint", diff --git a/docs/BLTouch.md b/docs/BLTouch.md index 0f97bc91..6fad76c5 100644 --- a/docs/BLTouch.md +++ b/docs/BLTouch.md @@ -1,5 +1,7 @@ +# BL-Touch + Connecting BL-Touch -=================== +------------------- A **warning** before you start: Avoid touching the BL-Touch pin with your bare fingers, since it is quite sensitive to finger grease. And @@ -38,7 +40,7 @@ that the probe doesn't hit anything even if the probe pin happens to be in its lowest state. Initial tests -============= +------------- 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 @@ -82,7 +84,7 @@ If that was successful, do another `G28` (or `PROBE`) but this time let it touch the bed as it should. BL-Touch gone bad -================= +----------------- Once the BL-Touch is in inconsistent state, it starts blinking red. You can force it to leave that state by issuing: @@ -105,7 +107,7 @@ light turns on and of. Use the `reset`, `pin_up` and `pin_down` commands to achieve this. BL-Touch "clones" -================= +----------------- Many BL-Touch "clone" devices work correctly with Klipper using the default configuration. However, some "clone" devices may require @@ -143,7 +145,7 @@ the second query reports "probe: TRIGGERED" then it indicates that config file. BL-Touch v3 -=========== +----------- Some BL-Touch v3.0 and BL-Touch 3.1 devices may require configuring `probe_with_touch_mode` in the printer config file. @@ -171,7 +173,7 @@ device, be sure to test the probe accuracy before and after setting this value (use the `PROBE_ACCURACY` command to test). Multi-probing without stowing -============================= +----------------------------- By default, Klipper will deploy the probe at the start of each probe attempt and then stow the probe afterwards. This repetitive deploying @@ -202,7 +204,7 @@ before and after setting `probe_with_touch_mode` (use the `PROBE_ACCURACY` command to test). Calibrating the BL-Touch offsets -================================ +-------------------------------- Follow the directions in the [Probe Calibrate](Probe_Calibrate.md) guide to set the x_offset, y_offset, and z_offset config parameters. @@ -217,7 +219,7 @@ If an adjustment is made to the probe position, then rerun the probe calibration steps. BL-Touch output mode -==================== +-------------------- * A BL-Touch V3.0 supports setting a 5V or OPEN-DRAIN output mode, a BL-Touch V3.1 supports this too, but can also store this in its diff --git a/docs/Bed_Level.md b/docs/Bed_Level.md index 03883fe8..2f02361a 100644 --- a/docs/Bed_Level.md +++ b/docs/Bed_Level.md @@ -1,3 +1,5 @@ +# Bed leveling + Bed leveling (sometimes also referred to as "bed tramming") is critical to getting high quality prints. If a bed is not properly "leveled" it can lead to poor bed adhesion, "warping", and subtle @@ -20,7 +22,7 @@ The secret to getting high accuracy is to use a repeatable process and to use a leveling method that leverages the high accuracy of the printer's own motion system. -# Choose the appropriate calibration mechanism +## Choose the appropriate calibration mechanism Different types of printers use different methods for performing bed leveling. All of them ultimately depend on the "paper test" (described @@ -46,7 +48,7 @@ routines. Setting a negative number allows the printer to move below the nominal position of the bed, which may help when trying to determine the actual bed position. -# The "paper test" +## The "paper test" The primary bed calibration mechanism is the "paper test". It involves placing a regular piece of "copy machine paper" between the printer's @@ -174,7 +176,7 @@ to obtain the same amount of friction each time one runs the test. If something goes wrong during the test, one can use the `ABORT` command to exit the calibration tool. -# Determining Thermal Expansion +## Determining Thermal Expansion After successfully performing bed leveling, one may go on to calculate a more precise value for the combined impact of "thermal expansion", diff --git a/docs/Bed_Mesh.md b/docs/Bed_Mesh.md index bdc1aa6c..a13482fa 100644 --- a/docs/Bed_Mesh.md +++ b/docs/Bed_Mesh.md @@ -1,3 +1,5 @@ +# Bed Mesh + The Bed Mesh module may be used to compensate for bed surface irregularties 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 diff --git a/docs/Benchmarks.md b/docs/Benchmarks.md index 5514f7df..7ed16312 100644 --- a/docs/Benchmarks.md +++ b/docs/Benchmarks.md @@ -1,7 +1,9 @@ +# Benchmarks + This document describes Klipper benchmarks. Micro-controller Benchmarks -=========================== +--------------------------- This section describes the mechanism used to generate the Klipper micro-controller step rate benchmarks. @@ -23,7 +25,7 @@ or other innocuous pins. **Always verify that it is safe to drive the configured pins prior to running a benchmark.** It is not recommended to drive an actual stepper during a benchmark. -## Step rate benchmark test ## +### Step rate benchmark test ### The test is performed using the console.py tool (described in [Debugging.md](Debugging.md)). The micro-controller is configured for @@ -449,7 +451,7 @@ hub. | rp2040 (USB) | 873K | c5667193 | arm-none-eabi-gcc (Fedora 10.2.0-4.fc34) 10.2.0 | Host Benchmarks -=============== +--------------- It is possible to run timing tests on the host software using the "batch mode" processing mechanism (described in diff --git a/docs/Bootloaders.md b/docs/Bootloaders.md index bf52794b..bb070a70 100644 --- a/docs/Bootloaders.md +++ b/docs/Bootloaders.md @@ -1,3 +1,5 @@ +# Bootloaders + This document provides information on common bootloaders found on micro-controllers that Klipper supports. @@ -23,8 +25,8 @@ application. This document is not an authoritative reference; it is intended as a collection of useful information that the Klipper developers have accumulated. -AVR micro-controllers -===================== +## AVR micro-controllers ## + In general, the Arduino project is a good reference for bootloaders and flashing procedures on the 8-bit Atmel Atmega micro-controllers. @@ -44,7 +46,7 @@ use. The "avrdude" program is the most common tool used to flash atmega chips (both bootloader flashing and application flashing). -## Atmega2560 ## +### Atmega2560 ### This chip is typically found in the "Arduino Mega" and is very common in 3d printer boards. @@ -63,7 +65,7 @@ To flash an application use something like: avrdude -cwiring -patmega2560 -P/dev/ttyACM0 -b115200 -D -Uflash:w:out/klipper.elf.hex:i ``` -## Atmega1280 ## +### Atmega1280 ### This chip is typically found in earlier versions of the "Arduino Mega". @@ -82,7 +84,7 @@ To flash an application use something like: avrdude -carduino -patmega1280 -P/dev/ttyACM0 -b57600 -D -Uflash:w:out/klipper.elf.hex:i ``` -## Atmega1284p ## +### Atmega1284p ### This chip is commonly found in "Melzi" style 3d printer boards. @@ -107,7 +109,7 @@ application use something like this instead: avrdude -carduino -patmega1284p -P/dev/ttyACM0 -b57600 -D -Uflash:w:out/klipper.elf.hex:i ``` -## At90usb1286 ## +### At90usb1286 ### This document does not cover the method to flash a bootloader to the At90usb1286 nor does it cover general application flashing to this @@ -122,7 +124,7 @@ One can flash an application with it using something like: teensy_loader_cli --mcu=at90usb1286 out/klipper.elf.hex -v ``` -## Atmega168 ## +### Atmega168 ### The atmega168 has limited flash space. If using a bootloader, it is recommended to use the Optiboot bootloader. To flash that bootloader @@ -142,7 +144,7 @@ avrdude -carduino -patmega168 -P/dev/ttyACM0 -b115200 -D -Uflash:w:out/klipper.e ``` SAM3 micro-controllers (Arduino Due) -==================================== +------------------------------------ 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 @@ -166,7 +168,7 @@ bossac -U -p /dev/ttyACM0 -R ``` SAM4 micro-controllers (Duet Wifi) -==================================== +---------------------------------- 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 @@ -186,7 +188,7 @@ bossac --port=/dev/ttyACM0 -b -U -e -w -v -R out/klipper.bin ``` SAMD21 micro-controllers (Arduino Zero) -======================================= +--------------------------------------- The SAMD21 bootloader is flashed via the ARM Serial Wire Debug (SWD) interface. This is commonly done with a dedicated SWD hardware dongle. @@ -225,7 +227,7 @@ avrdude -c stk500v2 -p atmega2560 -P /dev/ttyACM0 -u -Uflash:w:out/klipper.elf.h ``` SAMD51 micro-controllers (Adafruit Metro-M4 and similar) -======================================================== +-------------------------------------------------------- Like the SAMD21, the SAMD51 bootloader is flashed via the ARM Serial Wire Debug (SWD) interface. To flash a bootloader with @@ -254,7 +256,7 @@ bossac -U -p /dev/ttyACM0 --offset=0x4000 -w out/klipper.bin -v -b -R ``` STM32F103 micro-controllers (Blue Pill devices) -=============================================== +----------------------------------------------- The STM32F103 devices have a ROM that can flash a bootloader or application via 3.3V serial. To access this ROM, one should connect @@ -274,7 +276,7 @@ for details on enabling the full uart on the Raspberry Pi GPIO pins. After flashing, set both "boot 0" and "boot 1" back to low so that future resets boot from flash. -## STM32F103 with stm32duino bootloader ## +### STM32F103 with stm32duino bootloader ### The "stm32duino" project has a USB capable bootloader - see: [https://github.com/rogerclarkmelbourne/STM32duino-bootloader](https://github.com/rogerclarkmelbourne/STM32duino-bootloader) @@ -299,7 +301,7 @@ bootloader is still active (the bootloader will flash a board led while it is running). Alternatively, set the "boot 0" pin to low and "boot 1" pin to high to stay in the bootloader after a reset. -## STM32F103 with HID bootloader ## +### STM32F103 with HID bootloader ### The [HID bootloader](https://github.com/Serasidis/STM32_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]( @@ -422,7 +424,7 @@ programming is complete unplug the device and set "boot 1" back to low so the application will be loaded. LPC176x micro-controllers (Smoothieboards) -========================================== +------------------------------------------ This document does not describe the method to flash a bootloader itself - see: @@ -438,7 +440,7 @@ this bootloader is to copy the application file (eg, then to reboot the micro-controller with that SD card. Running OpenOCD on the Raspberry PI -=================================== +----------------------------------- 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 @@ -464,7 +466,7 @@ make make install ``` -## Configure OpenOCD +### Configure OpenOCD Create an OpenOCD config file: @@ -498,7 +500,7 @@ targets reset halt ``` -## Wire the Raspberry Pi to the target chip +### Wire the Raspberry Pi to the target chip 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 @@ -509,7 +511,7 @@ GPIO24, and GPIO18 respectively on the Raspberry Pi. Then power up the Raspberry Pi and provide power to the target chip. -## Run OpenOCD +### Run OpenOCD Run OpenOCD: @@ -533,7 +535,7 @@ telnet 127.0.0.1 4444 (One can exit telnet by pressing ctrl+] and then running the "quit" command.) -## OpenOCD and gdb +### OpenOCD and gdb It is possible to use OpenOCD with gdb to debug Klipper. The following commands assume one is running gdb on a desktop class machine. diff --git a/docs/CANBUS.md b/docs/CANBUS.md index de652cee..5d5b2a08 100644 --- a/docs/CANBUS.md +++ b/docs/CANBUS.md @@ -1,6 +1,8 @@ +# CANBUS + This document describes Klipper's CAN bus support. -# Device Hardware +## Device Hardware Klipper currently only supports CAN on stm32 chips. In addition, the micro-controller chip must support CAN and it must be on a board that @@ -10,7 +12,7 @@ To compile for CAN, run "make menuconfig" and select "CAN bus" as the communication interface. Finally, compile the micro-controller code and flash it to the target board. -# Host Hardware +## Host Hardware In order to use a CAN bus, it is necessary to have a host adapter. There are currently two common options: @@ -40,7 +42,7 @@ iface can0 can static Note that the "Raspberry Pi CAN hat" also requires [changes to config.txt](https://www.waveshare.com/wiki/RS485_CAN_HAT). -# Terminating Resistors +## Terminating Resistors 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. @@ -58,7 +60,7 @@ printer and use a multi-meter to check the resistance between the CANH and CANL wires - it should report ~60 ohms on a correctly wired CAN bus. -# Finding the canbus_uuid for new micro-controllers +## Finding the canbus_uuid for new micro-controllers Each micro-controller on the CAN bus is assigned a unique id based on the factory chip identifier encoded into each micro-controller. To @@ -81,7 +83,7 @@ Note that the `canbus_query.py` tool will only report uninitialized devices - if Klipper (or a similar tool) configures the device then it will no longer appear in the list. -# Configuring Klipper +## Configuring Klipper Update the Klipper [mcu configuration](Config_Reference.md#mcu) to use the CAN bus to communicate with the device - for example: diff --git a/docs/CANBUS_protocol.md b/docs/CANBUS_protocol.md index 3fa2bf2d..e1561eb5 100644 --- a/docs/CANBUS_protocol.md +++ b/docs/CANBUS_protocol.md @@ -1,9 +1,11 @@ +# CANBUS protocol + This document describes the protocol Klipper uses to communicate over [CAN bus](https://en.wikipedia.org/wiki/CAN_bus). See [CANBUS.md](CANBUS.md) for information on configuring Klipper with CAN bus. -# Micro-controller id assignment +## Micro-controller id assignment Klipper uses only CAN 2.0A standard size CAN bus packets, which are limited to 8 data bytes and an 11-bit CAN bus identifier. In order to @@ -19,7 +21,7 @@ that is used during id assignment. This identifier can exceed the length of one CAN packet, so a hash function is used to generate a unique 6-byte id (`canbus_uuid`) from the factory id. -# Admin messages +## Admin messages Admin messages are used for id assignment. Admin messages sent from host to micro-controller use the CAN bus id `0x3f0` and messages sent @@ -27,7 +29,7 @@ from micro-controller to host use the CAN bus id `0x3f1`. All micro-controllers listen to messages on id `0x3f0`; that id can be thought of as a "broadcast address". -## CMD_QUERY_UNASSIGNED message +### CMD_QUERY_UNASSIGNED message This command queries all micro-controllers that have not yet been assigned a `canbus_nodeid`. Unassigned micro-controllers will respond @@ -36,7 +38,7 @@ with a RESP_NEED_NODEID response message. The CMD_QUERY_UNASSIGNED message format is: `<1-byte message_id = 0x00>` -## CMD_SET_NODEID message +### CMD_SET_NODEID message This command assigns a `canbus_nodeid` to the micro-controller with a given `canbus_uuid`. @@ -44,12 +46,12 @@ given `canbus_uuid`. The CMD_SET_NODEID message format is: `<1-byte message_id = 0x01><6-byte canbus_uuid><1-byte canbus_nodeid>` -## RESP_NEED_NODEID message +### RESP_NEED_NODEID message The RESP_NEED_NODEID message format is: `<1-byte message_id = 0x20><6-byte canbus_uuid>` -# Data Packets +## Data Packets A micro-controller that has been assigned a nodeid via the CMD_SET_NODEID command can send and receive data packets. diff --git a/docs/Code_Overview.md b/docs/Code_Overview.md index 2b35688f..fff6d7c9 100644 --- a/docs/Code_Overview.md +++ b/docs/Code_Overview.md @@ -1,8 +1,10 @@ +# Code overview + This document describes the overall code layout and major code flow of Klipper. Directory Layout -================ +---------------- The **src/** directory contains the C source for the micro-controller code. The **src/atsam/**, **src/atsamd/**, **src/avr/**, @@ -39,7 +41,7 @@ object that is built is **out/klipper.elf.hex** on AVR and **out/klipper.bin** on ARM. Micro-controller code flow -========================== +-------------------------- Execution of the micro-controller code starts in architecture specific code (eg, **src/avr/main.c**) which ultimately calls sched_main() @@ -90,7 +92,7 @@ gpio functions are inlined into their callers, and there is no run-time cost to using them. Klippy code overview -==================== +-------------------- 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 @@ -116,7 +118,7 @@ the log (see **klippy/queuelogger.py**) so that the other threads never block on log writes. Code flow of a move command -=========================== +--------------------------- A typical printer movement starts when a "G1" command is sent to the Klippy host and it completes when the corresponding step pulses are @@ -228,7 +230,7 @@ movements and their timings. The remaining parts of the processing is mostly just communication and plumbing. Adding a host module -==================== +-------------------- The Klippy host code has a dynamic module loading capability. If a config section named "[my_module]" is found in the printer config file @@ -308,7 +310,7 @@ The following may also be useful: existing modules for the preferred format. Adding new kinematics -===================== +--------------------- This section provides some tips on adding support to Klipper for additional types of printer kinematics. This type of activity requires @@ -348,7 +350,7 @@ Useful steps: cases and to check for regressions. Porting to a new micro-controller -================================= +--------------------------------- This section provides some tips on porting Klipper's micro-controller code to a new architecture. This type of activity requires good @@ -401,7 +403,7 @@ Useful steps: 9. Consider adding build test cases in the test/ directory. Coordinate Systems -================== +------------------ Internally, Klipper primarily tracks the position of the toolhead in cartesian coordinates that are relative to the coordinate system @@ -487,7 +489,7 @@ the config file) after a `G28` home command. The `SET_GCODE_OFFSET` command can alter this value. Time -==== +---- Fundamental to the operation of Klipper is the handling of clocks, times, and timestamps. Klipper executes actions on the printer by diff --git a/docs/Command_Templates.md b/docs/Command_Templates.md index 0d45b7b3..02b92f11 100644 --- a/docs/Command_Templates.md +++ b/docs/Command_Templates.md @@ -1,7 +1,9 @@ +# Commands templates + This document provides information on implementing G-Code command sequences in gcode_macro (and similar) config sections. -### G-Code Macro Naming +## G-Code Macro Naming 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 @@ -9,7 +11,7 @@ lower case. If any numbers are used in the macro name then they must all be at the end of the name (eg, TEST_MACRO25 is valid, but MACRO25_TEST3 is not). -### Formatting of G-Code in the config +## Formatting of G-Code in the config 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 @@ -27,7 +29,7 @@ Note how the `gcode:` config option always starts at the beginning of the line and subsequent lines in the G-Code macro never start at the beginning. -### Add a description to your macro +## Add a description to your macro To help identify the functionality a short description can be added. Add `description:` with a short text to describe the functionality. @@ -46,7 +48,7 @@ gcode: This will be showing is you use the `HELP` command or use the autocomplete function. -### Save/Restore state for G-Code moves +## Save/Restore state for G-Code moves Unfortunately, the G-Code command language can be challenging to use. The standard mechanism to move the toolhead is via the `G1` command @@ -75,7 +77,7 @@ mode" and the `RESTORE_GCODE_STATE` command restores the state to what it was prior to entering the macro. Be sure to specify an explicit speed (via the `F` parameter) on the first `G1` command. -### Template expansion +## Template expansion The gcode_macro `gcode:` config section is evaluated using the Jinja2 @@ -101,7 +103,7 @@ gcode: RESTORE_GCODE_STATE NAME=clean_nozzle_state ``` -#### Macro parameters +### Macro parameters It is often useful to inspect parameters passed to the macro when it is called. These parameters are available via the `params` @@ -128,7 +130,7 @@ gcode: M140 S{bed_temp} ``` -#### The "printer" Variable +### The "printer" Variable It is possible to inspect (and alter) the current state of the printer via the `printer` pseudo-variable. For example: @@ -169,7 +171,7 @@ gcode: ``` -### Actions +## Actions There are some commands available that can alter the state of the printer. For example, `{ action_emergency_stop() }` would cause the @@ -193,7 +195,7 @@ Available "action" commands: be provided via keyword arguments, ie: `action_call_remote_method("print_stuff", my_arg="hello_world")` -### Variables +## Variables The SET_GCODE_VARIABLE command may be useful for saving state between macro calls. Variable names may not contain any upper case characters. @@ -221,7 +223,7 @@ gcode: Be sure to take the timing of macro evaluation and command execution into account when using SET_GCODE_VARIABLE. -### Delayed Gcodes +## Delayed Gcodes The [delayed_gcode] configuration option can be used to execute a delayed gcode sequence: @@ -279,7 +281,7 @@ gcode: UPDATE_DELAYED_GCODE ID=report_temp DURATION=0 ``` -### Menu templates +## Menu templates If a [display config section](Config_Reference.md#display) is enabled, then it is possible to customize the menu with @@ -303,7 +305,7 @@ The following actions are available in menu templates: * When `` is set True then it will also stop editing. Default value is False. -### Save Variables to disk +## Save Variables to disk If a diff --git a/docs/Config_Changes.md b/docs/Config_Changes.md index f523547e..9aa9cbf5 100644 --- a/docs/Config_Changes.md +++ b/docs/Config_Changes.md @@ -1,10 +1,12 @@ +# Configuration changes + This document covers recent software changes to the config file that are not backwards compatible. It is a good idea to review this document when upgrading the Klipper software. All dates in this document are approximate. -# Changes +## Changes 20210720: A controller_fan section now monitors all stepper motors by default (not just the kinematic stepper motors). If the previous diff --git a/docs/Config_Reference.md b/docs/Config_Reference.md index e876add7..5c26a6a5 100644 --- a/docs/Config_Reference.md +++ b/docs/Config_Reference.md @@ -1,3 +1,5 @@ +# Configuration reference + This document is a reference for options available in the Klipper config file. @@ -6,9 +8,9 @@ to cut-and-paste them into a printer config file. See the [installation document](Installation.md) for information on setting up Klipper and choosing an initial config file. -# Micro-controller configuration +## Micro-controller configuration -## Format of micro-controller pin names +### Format of micro-controller pin names Many config options require the name of a micro-controller pin. Klipper uses the hardware names for these pins - for example `PA4`. @@ -25,7 +27,7 @@ Note, some config sections may "create" additional pins. Where this occurs, the config section defining the pins must be listed in the config file before any sections using those pins. -## [mcu] +### [mcu] Configuration of the primary micro-controller. @@ -58,7 +60,7 @@ serial: # communicates over a serial port, 'command' otherwise. ``` -## [mcu my_extra_mcu] +### [mcu my_extra_mcu] Additional micro-controllers (one may define any number of sections with an "mcu" prefix). Additional micro-controllers introduce @@ -72,9 +74,9 @@ pins such as "extra_mcu:ar9" may then be used elsewhere in the config # See the "mcu" section for configuration parameters. ``` -# Common kinematic settings +## Common kinematic settings -## [printer] +### [printer] The printer section controls high level printer settings. @@ -109,7 +111,7 @@ max_accel: # decelerate to zero at each corner. The default is 5mm/s. ``` -## [stepper] +### [stepper] Stepper motor definitions. Different printer types (as specified by the "kinematics" option in the [printer] config section) require @@ -184,7 +186,7 @@ position_max: # if near position_min. ``` -## Cartesian Kinematics +### Cartesian Kinematics See [example-cartesian.cfg](../config/example-cartesian.cfg) for an example cartesian kinematics config file. @@ -219,7 +221,7 @@ max_z_accel: [stepper_z] ``` -## Linear Delta Kinematics +### Linear Delta Kinematics See [example-delta.cfg](../config/example-delta.cfg) for an example linear delta kinematics config file. See the @@ -300,7 +302,7 @@ radius: # just prior to starting a probe operation. The default is 5. ``` -## CoreXY Kinematics +### CoreXY Kinematics See [example-corexy.cfg](../config/example-corexy.cfg) for an example corexy (and h-bot) kinematics file. @@ -335,7 +337,7 @@ max_z_accel: [stepper_z] ``` -## CoreXZ Kinematics +### CoreXZ Kinematics See [example-corexz.cfg](../config/example-corexz.cfg) for an example corexz kinematics config file. @@ -367,7 +369,7 @@ max_z_accel: [stepper_z] ``` -## Hybrid-CoreXY Kinematics +### Hybrid-CoreXY Kinematics See [example-hybrid-corexy.cfg](../config/example-hybrid-corexy.cfg) for an example hybrid corexy kinematics config file. @@ -401,7 +403,7 @@ max_z_accel: [stepper_z] ``` -## Hybrid-CoreXZ Kinematics +### Hybrid-CoreXZ Kinematics See [example-hybrid-corexz.cfg](../config/example-hybrid-corexz.cfg) for an example hybrid corexz kinematics config file. @@ -435,7 +437,7 @@ max_z_accel: [stepper_z] ``` -## Polar Kinematics +### Polar Kinematics See [example-polar.cfg](../config/example-polar.cfg) for an example polar kinematics config file. @@ -478,7 +480,7 @@ max_z_accel: [stepper_z] ``` -## Rotary delta Kinematics +### Rotary delta Kinematics See [example-rotary-delta.cfg](../config/example-rotary-delta.cfg) for an example rotary delta kinematics config file. @@ -568,7 +570,7 @@ radius: # just prior to starting a probe operation. The default is 5. ``` -## Cable winch Kinematics +### Cable winch Kinematics See the [example-winch.cfg](../config/example-winch.cfg) for an example cable winch kinematics config file. @@ -601,7 +603,7 @@ anchor_z: # These parameters must be provided. ``` -## None Kinematics +### None Kinematics It is possible to define a special "none" kinematics to disable kinematic support in Klipper. This may be useful for controlling @@ -616,9 +618,9 @@ max_accel: 1 # values are not used for "none" kinematics. ``` -# Common extruder and heated bed support +## Common extruder and heated bed support -## [extruder] +### [extruder] The extruder section is used to describe both the stepper controlling the printer extruder and the heater parameters for the nozzle. See the @@ -740,7 +742,7 @@ max_temp: # These parameters must be provided. ``` -## [heater_bed] +### [heater_bed] The heater_bed section describes a heated bed. It uses the same heater settings described in the "extruder" section. @@ -756,9 +758,9 @@ max_temp: # See the "extruder" section for a description of the above parameters. ``` -# Bed level support +## Bed level support -## [bed_mesh] +### [bed_mesh] 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 @@ -876,7 +878,7 @@ Visual Examples: # By default no faulty regions are set. ``` -## [bed_tilt] +### [bed_tilt] Bed tilt compensation. One may define a bed_tilt config section to enable move transformations that account for a tilted bed. Note that @@ -913,7 +915,7 @@ information. # just prior to starting a probe operation. The default is 5. ``` -## [bed_screws] +### [bed_screws] Tool to help adjust bed leveling screws. One may define a [bed_screws] config section to enable a BED_SCREWS_ADJUST g-code command. @@ -958,7 +960,7 @@ information. # to a probe_height position. The default is 5. ``` -## [screws_tilt_adjust] +### [screws_tilt_adjust] 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 @@ -1001,7 +1003,7 @@ additional information. # turning the knob clockwise decrease distance. ``` -## [z_tilt] +### [z_tilt] Multiple Z stepper tilt adjustment. This feature enables independent adjustment of multiple z steppers (see the "stepper_z1" section) to @@ -1042,7 +1044,7 @@ extended [G-Code command](G-Codes.md#z-tilt) becomes available. # by observing command output. ``` -## [quad_gantry_level] +### [quad_gantry_level] Moving gantry leveling using 4 independently controlled Z motors. Corrects hyperbolic parabola effects (potato chip) on moving gantry @@ -1092,7 +1094,7 @@ Where x is the (0,0) point on the bed # points differ more than retry_tolerance. ``` -## [skew_correction] +### [skew_correction] 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 @@ -1105,9 +1107,9 @@ the nature of skew correction these lengths are set via gcode. See [skew_correction] ``` -# Customized homing +## Customized homing -## [safe_z_home] +### [safe_z_home] Safe Z homing. One may use this mechanism to home the Z axis at a specific XY coordinate. This is useful if the toolhead, for example @@ -1136,7 +1138,7 @@ home_xy_position: # homing. The default is False. ``` -## [homing_override] +### [homing_override] 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 @@ -1168,7 +1170,7 @@ gcode: # axis. The default is to not force a position for an axis. ``` -## [endstop_phase] +### [endstop_phase] Stepper phase adjusted endstops. To use this feature, define a config section with an "endstop_phase" prefix followed by the name of the @@ -1205,9 +1207,9 @@ for additional information. # layer will occur on a full step.) The default is False. ``` -# G-Code macros and events +## G-Code macros and events -## [gcode_macro] +### [gcode_macro] G-Code macros (one may define any number of sections with a "gcode_macro" prefix). See the @@ -1240,7 +1242,7 @@ G-Code macros (one may define any number of sections with a # using the auto completion feature. Default "G-Code macro" ``` -## [delayed_gcode] +### [delayed_gcode] Execute a gcode on a set delay. See the [command template guide](Command_Templates.md#delayed-gcodes) and @@ -1261,7 +1263,7 @@ gcode: # Default is 0. ``` -## [save_variables] +### [save_variables] Support saving variables to disk so that they are retained across restarts. See @@ -1275,7 +1277,7 @@ filename: # variables to disk e.g. ~/variables.cfg ``` -## [idle_timeout] +### [idle_timeout] Idle timeout. An idle timeout is automatically enabled - add an explicit idle_timeout config section to change the default settings. @@ -1291,9 +1293,9 @@ explicit idle_timeout config section to change the default settings. # commands. The default is 600 seconds. ``` -# Optional G-Code features +## Optional G-Code features -## [virtual_sdcard] +### [virtual_sdcard] A virtual sdcard may be useful if the host machine is not fast enough to run OctoPrint well. It allows the Klipper host software to directly @@ -1310,7 +1312,7 @@ path: # be provided. ``` -## [sdcard_loop] +### [sdcard_loop] 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. @@ -1325,7 +1327,7 @@ file for a Marlin compatible M808 G-Code macro. [sdcard_loop] ``` -## [force_move] +### [force_move] Support manually moving stepper motors for diagnostic purposes. Note, using this feature may place the printer in an invalid state - see the @@ -1338,7 +1340,7 @@ using this feature may place the printer in an invalid state - see the # extended G-Code commands. The default is false. ``` -## [pause_resume] +### [pause_resume] Pause/Resume functionality with support of position capture and restore. See the [command reference](G-Codes.md#pause-resume) for more @@ -1351,7 +1353,7 @@ information. # the captured position (in mm/s). Default is 50.0 mm/s. ``` -## [firmware_retraction] +### [firmware_retraction] Firmware filament retraction. This enables G10 (retract) and G11 (unretract) GCODE commands issued by many slicers. The parameters @@ -1374,7 +1376,7 @@ allowing per-filament settings and runtime tuning. # The speed of unretraction, in mm/s. The default is 10 mm/s. ``` -## [gcode_arcs] +### [gcode_arcs] Support for gcode arc (G2/G3) commands. @@ -1388,7 +1390,7 @@ Support for gcode arc (G2/G3) commands. # 1mm. ``` -## [respond] +### [respond] Enable the "M118" and "RESPOND" extended [commands](G-Codes.md#send-message-respond-to-host). @@ -1406,9 +1408,9 @@ Enable the "M118" and "RESPOND" extended # override the "default_type". ``` -# Resonance compensation +## Resonance compensation -## [input_shaper] +### [input_shaper] Enables [resonance compensation](Resonance_Compensation.md). Also see the [command reference](G-Codes.md#resonance-compensation). @@ -1446,7 +1448,7 @@ the [command reference](G-Codes.md#resonance-compensation). # parameter requires no tuning and should not be changed. ``` -## [adxl345] +### [adxl345] Support for ADXL345 accelerometers. This support allows one to query accelerometer measurements from the sensor. This enables an @@ -1483,7 +1485,7 @@ cs_pin: # measurements. ``` -## [resonance_tester] +### [resonance_tester] Support for resonance testing and automatic input shaper calibration. In order to use most of the functionality of this module, additional @@ -1541,9 +1543,9 @@ section of the measuring resonances guide for more information on # (Hz/sec == sec^-2). ``` -# Config file helpers +## Config file helpers -## [board_pins] +### [board_pins] 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 @@ -1564,7 +1566,7 @@ aliases_: # starting with "aliases_" may be specified. ``` -## [include] +### [include] Include file support. One may include additional config file from the main printer config file. Wildcards may also be used (eg, @@ -1574,7 +1576,7 @@ main printer config file. Wildcards may also be used (eg, [include my_other_config.cfg] ``` -## [duplicate_pin_override] +### [duplicate_pin_override] This tool allows a single micro-controller pin to be defined multiple times in a config file without normal error checking. This is intended @@ -1590,9 +1592,9 @@ pins: # provided. ``` -# Bed probing hardware +## Bed probing hardware -## [probe] +### [probe] Z height probe. One may define this section to enable Z height probing hardware. When this section is enabled, PROBE and QUERY_PROBE extended @@ -1661,7 +1663,7 @@ z_offset: # not run any special G-Code commands on deactivation. ``` -## [bltouch] +### [bltouch] BLTouch probe. One may define this section (instead of a probe section) to enable a BLTouch probe. See [BL-Touch guide](BLTouch.md) @@ -1718,9 +1720,9 @@ control_pin: # See the "probe" section for information on these parameters. ``` -# Additional stepper motors and extruders +## Additional stepper motors and extruders -## [stepper_z1] +### [stepper_z1] Multi-stepper axes. On a cartesian style printer, the stepper controlling a given axis may have additional config blocks defining @@ -1743,7 +1745,7 @@ at 1 (for example, "stepper_z1", "stepper_z2", etc.). # axis is triggered. ``` -## [extruder1] +### [extruder1] In a multi-extruder printer add an additional extruder section for each additional extruder. The additional extruder sections should be @@ -1769,7 +1771,7 @@ for an example configuration. # reuse an existing heater. ``` -## [dual_carriage] +### [dual_carriage] Support for cartesian printers with dual carriages on a single axis. The active carriage is set via the SET_DUAL_CARRIAGE extended @@ -1800,7 +1802,7 @@ axis: # See the "stepper" section for the definition of the above parameters. ``` -## [extruder_stepper] +### [extruder_stepper] Support for additional steppers synchronized to the movement of an extruder (one may define any number of sections with an @@ -1823,7 +1825,7 @@ more information. # parameters. ``` -## [manual_stepper] +### [manual_stepper] Manual steppers (one may define any number of sections with a "manual_stepper" prefix). These are steppers that are controlled by @@ -1856,9 +1858,9 @@ normal printer kinematics. # MANUAL_STEPPER movement commands. ``` -# Custom heaters and sensors +## Custom heaters and sensors -## [verify_heater] +### [verify_heater] Heater and temperature sensor verification. Heater verification is automatically enabled for each heater that is configured on the @@ -1896,7 +1898,7 @@ printer. Use verify_heater sections to change the default settings. # value. The default is 2. ``` -## [homing_heaters] +### [homing_heaters] Tool to disable heaters when homing or probing an axis. @@ -1913,7 +1915,7 @@ Tool to disable heaters when homing or probing an axis. # Typical example: extruder, heater_bed ``` -## [thermistor] +### [thermistor] Custom thermistors (one may define any number of sections with a "thermistor" prefix). A custom thermistor may be used in the @@ -1942,7 +1944,7 @@ heater section. # provided when using "beta" to define the thermistor. ``` -## [adc_temperature] +### [adc_temperature] Custom ADC temperature sensors (one may define any number of sections with an "adc_temperature" prefix). This allows one to define a custom @@ -1981,7 +1983,7 @@ section. # least two measurements must be provided. ``` -## [heater_generic] +### [heater_generic] Generic heaters (one may define any number of sections with a "heater_generic" prefix). These heaters behave similarly to standard @@ -2010,7 +2012,7 @@ temperature. # parameters. ``` -## [temperature_sensor] +### [temperature_sensor] Generic temperature sensors. One can define any number of additional temperature sensors that are reported via the M105 command. @@ -2028,14 +2030,14 @@ temperature sensors that are reported via the M105 command. # parameter. ``` -# Temperature sensors +## Temperature sensors Klipper includes definitions for many types of temperature sensors. These sensors may be used in any config section that requires a temperature sensor (such as an `[extruder]` or `[heated_bed]` section). -## Common thermistors +### Common thermistors Common thermistors. The following parameters are available in heater sections that use one of these sensors. @@ -2058,7 +2060,7 @@ sensor_pin: # The default is 0 ohms. ``` -## Common temperature amplifiers +### Common temperature amplifiers Common temperature amplifiers. The following parameters are available in heater sections that use one of these sensors. @@ -2076,7 +2078,7 @@ sensor_pin: # The ADC voltage offset (in Volts). The default is 0. ``` -## Directly connected PT1000 sensor +### Directly connected PT1000 sensor Directly connected PT1000 sensor. The following parameters are available in heater sections that use one of these sensors. @@ -2091,7 +2093,7 @@ sensor_pin: # default is 4700 ohms. ``` -## MAXxxxxx temperature sensors +### MAXxxxxx temperature sensors MAXxxxxx serial peripheral interface (SPI) temperature based sensors. The following parameters are available in heater sections @@ -2127,7 +2129,7 @@ sensor_pin: # name in the above list. ``` -## BMP280/BME280/BME680 temperature sensor +### BMP280/BME280/BME680 temperature sensor BMP280/BME280/BME680 two wire interface (I2C) environmental sensors. Note that thoose sensors aee not intended for use with extruders and @@ -2149,7 +2151,7 @@ sensor_type: BME280 # above parameters. ``` -## HTU21D sensor +### HTU21D sensor HTU21D family two wire interface (I2C) environmental sensor. Note that this sensor is not intended for use with extruders and heater beds, @@ -2184,7 +2186,7 @@ sensor_type: # Interval in seconds between readings. Default is 30 ``` -## LM75 temperature sensor +### LM75 temperature sensor LM75/LM75A two wire (I2C) connected temperature sensors. These sensors have range up to 125 C, so are usable for e.g. chamber temperature @@ -2206,7 +2208,7 @@ sensor_type: lm75 # 0.5. ``` -## Builtin micro-controller temperature sensor +### Builtin micro-controller temperature sensor The atsam, atsamd, and stm32 micro-controllers contain an internal temperature sensor. One can use the "temperature_mcu" sensor to @@ -2240,7 +2242,7 @@ sensor_type: temperature_mcu # micro-controller specification. ``` -## Host temperature sensor +### Host temperature sensor Temperature from the machine (eg Raspberry Pi) running the host software. @@ -2252,7 +2254,7 @@ sensor_type: temperature_host # system file on a Raspberry Pi computer. ``` -## DS18B20 temperature sensor +### DS18B20 temperature sensor 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. @@ -2269,9 +2271,9 @@ serial_no: # The micro-controller to read from. Must be the host_mcu ``` -# Fans +## Fans -## [fan] +### [fan] Print cooling fan. @@ -2336,7 +2338,7 @@ pin: # maximum speed (in RPM) of the fan. ``` -## [heater_fan] +### [heater_fan] 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 @@ -2370,7 +2372,7 @@ a shutdown_speed equal to max_power. # is 1.0 ``` -## [controller_fan] +### [controller_fan] Controller cooling fan (one may define any number of sections with a "controller_fan" prefix). A "controller fan" is a fan that will be @@ -2413,7 +2415,7 @@ watched component. # default stepper is all of them. ``` -## [temperature_fan] +### [temperature_fan] Temperature-triggered cooling fans (one may define any number of sections with a "temperature_fan" prefix). A "temperature fan" is a @@ -2464,7 +2466,7 @@ additional information. # given id. The default is to not report the temperature via M105. ``` -## [fan_generic] +### [fan_generic] Manually controlled fan (one may define any number of sections with a "fan_generic" prefix). The speed of a manually controlled fan is set @@ -2486,9 +2488,9 @@ with the SET_FAN_SPEED # See the "fan" section for a description of the above parameters. ``` -# Additional servos, LEDs, buttons, and other pins +## Additional servos, LEDs, buttons, and other pins -## [servo] +### [servo] Servos (one may define any number of sections with a "servo" prefix). The servos may be controlled using the SET_SERVO @@ -2519,7 +2521,7 @@ pin: # send any signal at startup. ``` -## [neopixel] +### [neopixel] Neopixel (aka WS2812) LED support (one may define any number of sections with a "neopixel" prefix). One may set the LED color via @@ -2547,7 +2549,7 @@ pin: # LEDs. The default for each color is 0. ``` -## [dotstar] +### [dotstar] Dotstar (aka APA102) LED support (one may define any number of sections with a "dotstar" prefix). One may set the LED color via @@ -2569,7 +2571,7 @@ clock_pin: # See the "neopixel" section for information on these parameters. ``` -## [PCA9533] +### [PCA9533] PCA9533 LED support. The PCA9533 is used on the mightyboard. @@ -2593,7 +2595,7 @@ PCA9533 LED support. The PCA9533 is used on the mightyboard. # set_led led=my_pca9533 red=1 green=1 blue=1 ``` -## [gcode_button] +### [gcode_button] 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 @@ -2621,7 +2623,7 @@ pin: # commands on a button release. ``` -## [output_pin] +### [output_pin] Run-time configurable output pins (one may define any number of sections with an "output_pin" prefix). Pins configured here will be @@ -2678,7 +2680,7 @@ pin: # parameter. ``` -## [static_digital_output] +### [static_digital_output] Statically configured digital output pins (one may define any number of sections with a "static_digital_output" prefix). Pins configured @@ -2693,7 +2695,7 @@ pins: # with "!". This parameter must be provided. ``` -## [multi_pin] +### [multi_pin] Multiple pin outputs (one may define any number of sections with a "multi_pin" prefix). A multi_pin output creates an internal pin alias @@ -2710,13 +2712,13 @@ pins: # parameter must be provided. ``` -# TMC stepper driver configuration +## TMC stepper driver configuration Configuration of Trinamic stepper motor drivers in UART/SPI mode. Additional information is in the [TMC Drivers guide](TMC_Drivers.md) and in the [command reference](G-Codes.md#tmc-stepper-drivers). -## [tmc2130] +### [tmc2130] Configure a TMC2130 stepper motor driver via SPI bus. To use this feature, define a config section with a "tmc2130" prefix followed by @@ -2787,7 +2789,7 @@ run_current: # sensorless homing. ``` -## [tmc2208] +### [tmc2208] Configure a TMC2208 (or TMC2224) stepper motor driver via single wire UART. To use this feature, define a config section with a "tmc2208" @@ -2845,7 +2847,7 @@ run_current: # above list. ``` -## [tmc2209] +### [tmc2209] Configure a TMC2209 stepper motor driver via single wire UART. To use this feature, define a config section with a "tmc2209" prefix followed @@ -2895,7 +2897,7 @@ run_current: # sensorless homing. ``` -## [tmc2660] +### [tmc2660] Configure a TMC2660 stepper motor driver via SPI bus. To use this feature, define a config section with a tmc2660 prefix followed by the @@ -2965,7 +2967,7 @@ run_current: # HDEC) is interpreted as the MSB of HSTRT in this case). ``` -## [tmc5160] +### [tmc5160] Configure a TMC5160 stepper motor driver via SPI bus. To use this feature, define a config section with a "tmc5160" prefix followed by @@ -3054,9 +3056,9 @@ run_current: # sensorless homing. ``` -# Run-time stepper motor current configuration +## Run-time stepper motor current configuration -## [ad5206] +### [ad5206] Statically configured AD5206 digipots connected via SPI bus (one may define any number of sections with an "ad5206" prefix). @@ -3096,7 +3098,7 @@ enable_pin: # default is to not scale the 'channel_x' parameters. ``` -## [mcp4451] +### [mcp4451] Statically configured MCP4451 digipot connected via I2C bus (one may define any number of sections with an "mcp4451" prefix). @@ -3131,7 +3133,7 @@ i2c_address: # to not scale the 'wiper_x' parameters. ``` -## [mcp4728] +### [mcp4728] Statically configured MCP4728 digital-to-analog converter connected via I2C bus (one may define any number of sections with an "mcp4728" @@ -3168,7 +3170,7 @@ prefix). # stepper. The default is to not scale the 'channel_x' parameters. ``` -## [mcp4018] +### [mcp4018] Statically configured MCP4018 digipot connected via two gpio "bit banging" pins (one may define any number of sections with an "mcp4018" @@ -3197,9 +3199,9 @@ wiper: # scale the 'wiper' parameter. ``` -# Display support +## Display support -## [display] +### [display] Support for a display attached to the micro-controller. @@ -3619,9 +3621,9 @@ information on menu attributes available during template rendering. # mode start or end. ``` -# Filament sensors +## Filament sensors -## [filament_switch_sensor] +### [filament_switch_sensor] Filament Switch Sensor. Support for filament insert and runout detection using a switch sensor, such as an endstop switch. @@ -3660,7 +3662,7 @@ information. # provided. ``` -## [filament_motion_sensor] +### [filament_motion_sensor] Filament Motion Sensor. Support for filament insert and runout detection using an encoder that toggles the output pin during filament @@ -3688,7 +3690,7 @@ switch_pin: # above parameters. ``` -## [tsl1401cl_filament_width_sensor] +### [tsl1401cl_filament_width_sensor] TSLl401CL Based Filament Width Sensor. See the [guide](TSL1401CL_Filament_Width_Sensor.md) for more information. @@ -3703,7 +3705,7 @@ TSLl401CL Based Filament Width Sensor. See the #measurement_delay: 100 ``` -## [hall_filament_width_sensor] +### [hall_filament_width_sensor] Hall filament width sensor (see [Hall Filament Width Sensor](HallFilamentWidthSensor.md)). @@ -3759,9 +3761,9 @@ adc2: # above parameters. ``` -# Board specific hardware support +## Board specific hardware support -## [sx1509] +### [sx1509] Configure an SX1509 I2C to GPIO expander. Due to the delay incurred by I2C communication you should NOT use SX1509 pins as stepper enable, @@ -3792,7 +3794,7 @@ i2c_address: # default is to use the default micro-controller i2c bus. ``` -## [samd_sercom] +### [samd_sercom] SAMD SERCOM configuration to specify which pins to use on a given SERCOM. One may define any number of sections with a "samd_sercom" @@ -3821,7 +3823,7 @@ clk_pin: # for the given SERCOM peripheral. This parameter must be provided. ``` -## [adc_scaled] +### [adc_scaled] Duet2 Maestro analog scaling by vref and vssa readings. Defining an adc_scaled section enables virtual adc pins (such as "my_name:PB0") @@ -3847,7 +3849,7 @@ vssa_pin: # noise. The default is 2 seconds. ``` -## [replicape] +### [replicape] Replicape support - see the [beaglebone guide](beaglebone.md) and the [generic-replicape.cfg](../config/generic-replicape.cfg) file for an @@ -3913,9 +3915,9 @@ host_mcu: # (True sets CFG5 high, False sets it low). The default is True. ``` -# Other Custom Modules +## Other Custom Modules -## [palette2] +### [palette2] Palette 2 multimaterial support - provides a tighter integration supporting Palette 2 devices in connected mode. @@ -3949,9 +3951,9 @@ serial: # Auto cancel print when ping varation is above this threshold ``` -# Common bus parameters +## Common bus parameters -## Common SPI settings +### Common SPI settings The following parameters are generally available for devices using an SPI bus. @@ -3973,7 +3975,7 @@ SPI bus. # "software spi". ``` -## Common I2C settings +### Common I2C settings The following parameters are generally available for devices using an I2C bus. diff --git a/docs/Config_checks.md b/docs/Config_checks.md index 8065dd3d..1707be74 100644 --- a/docs/Config_checks.md +++ b/docs/Config_checks.md @@ -1,3 +1,5 @@ +# Configuration checks + This document provides a list of steps to help confirm the pin settings in the Klipper printer.cfg file. It is a good idea to run through these steps after following the steps in the @@ -10,7 +12,7 @@ in the Octoprint terminal tab and then click "Send"). It's also a good idea to issue a STATUS command after every RESTART to verify that the config file is successfully loaded. -### Verify temperature +## Verify temperature Start by verifying that temperatures are being properly reported. Navigate to the Octoprint temperature tab. @@ -22,7 +24,7 @@ present and not increasing. If it is increasing, remove power from the printer. If the temperatures are not accurate, review the "sensor_type" and "sensor_pin" settings for the nozzle and/or bed. -### Verify M112 +## Verify M112 Navigate to the Octoprint terminal tab and issue an M112 command in the terminal box. This command requests Klipper to go into a @@ -37,7 +39,7 @@ The M112 command causes Klipper to go into a "shutdown" state. To clear this state, issue a FIRMWARE_RESTART command in the Octoprint terminal tab. -### Verify heaters +## Verify heaters Navigate to the Octoprint temperature tab and type in 50 followed by enter in the "Tool" temperature box. The extruder temperature in the @@ -50,7 +52,7 @@ verify the "heater_pin" setting in the config. If the printer has a heated bed then perform the above test again with the bed. -### Verify stepper motor enable pin +## Verify stepper motor enable pin Verify that all of the printer axes can manually move freely (the stepper motors are disabled). If not, issue an M84 command to disable @@ -60,7 +62,7 @@ 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: !ar38"). -### Verify endstops +## Verify endstops Manually move all the printer axes so that none of them are in contact with an endstop. Send a QUERY_ENDSTOPS command via the Octoprint @@ -81,7 +83,7 @@ require a change to the pullup setting of the pin (the '^' at the start of the endstop_pin name - most printers will use a pullup resistor and the '^' should be present). -### Verify stepper motors +## Verify stepper motors Use the STEPPER_BUZZ command to verify the connectivity of each stepper motor. Start by manually positioning the given axis to a @@ -114,7 +116,7 @@ homing mechanism should be tested. Issue a G28 command to home all axes. Remove power from the printer if it does not home properly. Rerun the endstop and stepper motor verification steps if necessary. -### Verify extruder motor +## Verify extruder motor To test the extruder motor it will be necessary to heat the extruder to a printing temperature. Navigate to the Octoprint temperature tab @@ -126,7 +128,7 @@ turns in the correct direction. If it does not, see the troubleshooting tips in the previous section to confirm the "enable_pin", "step_pin", and "dir_pin" settings for the extruder. -### Calibrate PID settings +## Calibrate PID settings Klipper supports [PID control](https://en.wikipedia.org/wiki/PID_controller) for the @@ -149,7 +151,7 @@ may turn on and off ten times a second, which may not be suitable for heaters using a mechanical switch.) A typical bed PID calibration command is: `PID_CALIBRATE HEATER=heater_bed TARGET=60` -### Next steps +## Next steps This guide is intended to help with basic verification of pin settings in the Klipper configuration file. Be sure to read the diff --git a/docs/Contact.md b/docs/Contact.md index a140b7a4..379bd01c 100644 --- a/docs/Contact.md +++ b/docs/Contact.md @@ -1,3 +1,5 @@ +# Contact + This document provides contact information for Klipper. 1. [Community Forum](#community-forum) @@ -8,13 +10,13 @@ This document provides contact information for Klipper. 6. [I have diagnosed a defect in the Klipper software](#i-have-diagnosed-a-defect-in-the-klipper-software) 7. [I am making changes that I'd like to include in Klipper](#i-am-making-changes-that-id-like-to-include-in-klipper) -# Community Forum +## Community Forum There is a [Klipper Community Discourse server](https://community.klipper3d.org) for discussions on Klipper. -# Discord Chat +## Discord Chat There is a Discord server dedicated to Klipper at: [https://discord.klipper3d.org](https://discord.klipper3d.org). @@ -23,7 +25,7 @@ This server is run by a community of Klipper enthusiasts dedicated to discussions on Klipper. It allows users to chat with other users in real-time. -# I have a question about Klipper +## I have a question about Klipper Many questions we receive are already answered in the [Klipper documentation](Overview.md). Please be sure to to read the @@ -46,7 +48,7 @@ dedicated to your printer hardware. Do not open a Klipper github issue to ask a question. -# I have a feature request +## I have a feature request All new features require someone interested and able to implement that feature. If you are interested in helping to implement or test a new @@ -57,7 +59,7 @@ collaborators. Do not open a Klipper github issue to request a feature. -# Help! It doesn't work! +## Help! It doesn't work! Unfortunately, we receive many more requests for help than we could possibly answer. Most problem reports we see are eventually tracked @@ -88,7 +90,7 @@ Klipper users can discuss Klipper with other users. Do not open a Klipper github issue to request help. -# I have diagnosed a defect in the Klipper software +## I have diagnosed a defect in the Klipper software Klipper is an open-source project and we appreciate when collaborators diagnose errors in the software. @@ -145,7 +147,7 @@ bug. Please follow these steps: ![attach-issue](img/attach-issue.png) -# I am making changes that I'd like to include in Klipper +## I am making changes that I'd like to include in Klipper Klipper is open-source software and we appreciate new contributions. diff --git a/docs/Debugging.md b/docs/Debugging.md index 6c19ce54..97c24257 100644 --- a/docs/Debugging.md +++ b/docs/Debugging.md @@ -1,7 +1,8 @@ +# Debugging + This document describes some of the Klipper debugging tools. -Translating gcode files to micro-controller commands -==================================================== +## Translating gcode files to micro-controller commands The Klippy host code can run in a batch mode to produce the low-level micro-controller commands associated with a gcode file. Inspecting @@ -43,8 +44,7 @@ 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. -Testing with simulavr -===================== +## Testing with simulavr The [simulavr](http://www.nongnu.org/simulavr/) tool enables one to simulate an Atmel ATmega micro-controller. This section describes how @@ -94,8 +94,8 @@ python virtual environment): ~/klippy-env/bin/python ./klippy/klippy.py config/generic-simulavr.cfg -i test.gcode -v ``` -Using simulavr with gtkwave ---------------------------- +### Using simulavr with gtkwave + One useful feature of simulavr is its ability to create signal wave generation files with the exact timing of events. To do this, follow @@ -114,8 +114,8 @@ using gtkwave with: gtkwave avrsim.vcd ``` -Manually sending commands to the micro-controller -================================================= +## Manually sending commands to the micro-controller + Normally, the host klippy.py process would be used to translate gcode commands to Klipper micro-controller commands. However, it's also @@ -132,8 +132,7 @@ functionality. Some command-line options are available. For more information run: `~/klippy-env/bin/python ./klippy/console.py --help` -Generating load graphs -====================== +## Generating load graphs The Klippy log file (/tmp/klippy.log) stores statistics on bandwidth, micro-controller load, and host buffer load. It can be useful to graph @@ -158,8 +157,7 @@ One can then view the resulting **loadgraph.png** file. Different graphs can be produced. For more information run: `~/klipper/scripts/graphstats.py --help` -Extracting information from the klippy.log file -=============================================== +## Extracting information from the klippy.log file The Klippy log file (/tmp/klippy.log) also contains debugging information. There is a logextract.py script that may be useful when @@ -178,8 +176,7 @@ shutdown information. The information dumps from an MCU shutdown (if present) will be reordered by timestamp to assist in diagnosing cause and effect scenarios. -Running the regression tests -============================ +## Running the regression tests The main Klipper GitHub repository uses "github actions" to run a series of regression tests. It can be useful to run some of these diff --git a/docs/Delta_Calibrate.md b/docs/Delta_Calibrate.md index 023e6865..648eab13 100644 --- a/docs/Delta_Calibrate.md +++ b/docs/Delta_Calibrate.md @@ -1,3 +1,5 @@ +# Delta calibration + This document describes Klipper's automatic calibration system for "delta" style printers. @@ -14,8 +16,7 @@ tower endstop switches. If one is using Trinamic stepper motor drivers then consider enabling [endstop phase](Endstop_Phase.md) detection to improve the accuracy of those switches. -Automatic vs manual probing -=========================== +## Automatic vs manual probing Klipper supports calibrating the delta parameters via a manual probing method or via an automatic Z probe. @@ -37,8 +38,7 @@ probes are rarely suitable for use on a delta (because minor effector tilt will result in a probe location bias). If using the probe anyway, then be sure to rerun probe calibration after any delta calibration. -Basic delta calibration -======================= +## Basic delta calibration Klipper has a DELTA_CALIBRATE command that can perform basic delta calibration. This command probes seven different points on the bed and @@ -84,8 +84,7 @@ accurate enough for basic printing. If this is a new printer, this is a good time to print some basic objects and verify general functionality. -Enhanced delta calibration -========================== +## Enhanced delta calibration The basic delta calibration generally does a good job of calculating delta parameters such that the nozzle is the correct distance from the @@ -215,8 +214,7 @@ to reenter the raw distance measurements after running SAVE_CONFIG, as this command changes the printer configuration and the raw measurements no longer apply. -Additional notes ----------------- +### Additional notes * If the delta printer has good dimensional accuracy then the distance between any two pillars should be around 74mm and the width of every @@ -236,8 +234,7 @@ Additional notes arm length may result in a tilt to the effector and some of that tilt may be accounted for by adjusting the arm length parameters. -Using Bed Mesh on a Delta -========================= +## Using Bed Mesh on a Delta It is possible to use [bed mesh](Bed_Mesh.md) on a delta. However, it is important to obtain good delta calibration prior to enabling a bed diff --git a/docs/Endstop_Phase.md b/docs/Endstop_Phase.md index fe0138d3..1921b283 100644 --- a/docs/Endstop_Phase.md +++ b/docs/Endstop_Phase.md @@ -1,3 +1,5 @@ +# Endstop phase + This document describes Klipper's stepper phase adjusted endstop system. This functionality can improve the accuracy of traditional endstop switches. It is most useful when using a Trinamic stepper @@ -32,8 +34,7 @@ phase from the driver. (It is also possible to use this system on traditional stepper drivers if one can reliably reset the stepper drivers - see below for details.) -Calibrating endstop phases -========================== +## Calibrating endstop phases If using Trinamic stepper motor drivers with run-time configuration then one can calibrate the endstop phases using the @@ -70,8 +71,7 @@ the following to update the configuration file with the data: SAVE_CONFIG ``` -Additional notes ----------------- +### Additional notes * This feature is most useful on delta printers and on the Z endstop of cartesian/corexy printers. It is possible to use this feature on diff --git a/docs/Example_Configs.md b/docs/Example_Configs.md index e5d6cc19..c53c7f2b 100644 --- a/docs/Example_Configs.md +++ b/docs/Example_Configs.md @@ -1,3 +1,5 @@ +# Example configurations + This document contains guidelines for contributing an example Klipper configuration to the Klipper github repository (located in the [config directory](../config/)). @@ -6,7 +8,7 @@ Note that the [Klipper Community Discourse server](https://community.klipper3d.org) is also a useful resource for finding and sharing config files. -# Guidelines +## Guidelines 1. Select the appropriate config filename prefix. 1. The `printer` prefix is used for stock printers sold by a diff --git a/docs/FAQ.md b/docs/FAQ.md index a65072ed..a68bbd06 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -1,5 +1,4 @@ -Frequently asked questions -========================== +# Frequently asked questions 1. [How can I donate to the project?](#how-can-i-donate-to-the-project) 2. [How do I calculate the rotation_distance config parameter?](#how-do-i-calculate-the-rotation_distance-config-parameter) @@ -26,16 +25,16 @@ Frequently asked questions 23. [How do I upgrade to the latest software?](#how-do-i-upgrade-to-the-latest-software) 24. [How do I uninstall klipper?](#how-do-i-uninstall-klipper) -### How can I donate to the project? +## How can I donate to the project? Thanks. Kevin has a Patreon page at: [https://www.patreon.com/koconnor](https://www.patreon.com/koconnor) -### How do I calculate the rotation_distance config parameter? +## How do I calculate the rotation_distance config parameter? See the [rotation distance document](Rotation_Distance.md). -### Where's my serial port? +## Where's my serial port? 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 @@ -65,13 +64,13 @@ If you are using multiple micro-controllers and they do not have unique ids (common on boards with a CH340 USB chip) then follow the directions above using the command `ls /dev/serial/by-path/*` instead. -### When the micro-controller restarts the device changes to /dev/ttyUSB1 +## When the micro-controller restarts the device changes to /dev/ttyUSB1 Follow the directions in the "[Where's my serial port?](#wheres-my-serial-port)" section to prevent this from occurring. -### The "make flash" command doesn't work +## The "make flash" command doesn't work The code attempts to flash the device using the most common method for each platform. Unfortunately, there is a lot of variance in flashing @@ -94,7 +93,7 @@ to manually flash the device using tools such as "avrdude" or "bossac" - see the [bootloader document](Bootloaders.md) for additional information. -### How do I change the serial baud rate? +## How do I change the serial baud rate? The recommended baud rate for Klipper is 250000. This baud rate works well on all micro-controller boards that Klipper supports. If you've @@ -122,7 +121,7 @@ of the micro-controller's bootloader. See the [bootloader document](Bootloaders.md) for additional information on bootloaders. -### Can I run Klipper on something other than a Raspberry Pi 3? +## Can I run Klipper on something other than a Raspberry Pi 3? The recommended hardware is a Raspberry Pi 2, Raspberry Pi 3, or Raspberry Pi 4. @@ -165,7 +164,7 @@ seemingly random "Lost communication with MCU" errors.) If you install Klipper on one of these distributions you may need to disable that package. -### Can I run multiple instances of Klipper on the same host machine? +## Can I run multiple instances of Klipper on the same host machine? It is possible to run multiple instances of the Klipper host software, but doing so requires Linux admin knowledge. The Klipper installation @@ -186,7 +185,7 @@ start, stop, and installation scripts (if any). The [klipper-start.sh](../scripts/klipper-start.sh) script may be useful as examples. -### Do I have to use OctoPrint? +## Do I have to use OctoPrint? The Klipper software is not dependent on OctoPrint. It is possible to use alternative software to send commands to Klipper, but doing so @@ -197,7 +196,7 @@ and it emulates a classic 3d-printer serial interface via that file. In general, alternative software may work with Klipper as long as it can be configured to use "/tmp/printer" for the printer serial port. -### Why can't I move the stepper before homing the printer? +## Why can't I move the stepper before homing the printer? 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 @@ -222,7 +221,7 @@ purposes then consider adding a force_move section to the config file. See [config reference](Config_Reference.md#customized_homing) for further details on these options. -### Why is the Z position_endstop set to 0.5 in the default configs? +## Why is the Z position_endstop set to 0.5 in the default configs? For cartesian style printers the Z position_endstop specifies how far the nozzle is from the bed when the endstop triggers. If possible, it @@ -234,7 +233,7 @@ bed. This way, when homing the axis, it will stop before the nozzle touches the bed. See the [bed level document](Bed_Level.md) for more information. -### I converted my config from Marlin and the X/Y axes work fine, but I just get a screeching noise when homing the Z axis +## 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 Short answer: First, make sure you have verified the stepper configuration as described in the @@ -250,7 +249,7 @@ a higher speed. So, for a Z axis with a high gearing ratio or high microsteps setting the actual obtainable max_z_velocity may be smaller than what is configured in Marlin. -### My TMC motor driver turns off in the middle of a print +## My TMC motor driver turns off in the middle of a print If using the TMC2208 (or TMC2224) driver in "standalone mode" then make sure to use the @@ -258,7 +257,7 @@ make sure to use the workaround for a TMC2208 "stealthchop" driver problem was added to Klipper in mid-March of 2020. -### I keep getting random "Lost communication with MCU" errors +## I keep getting random "Lost communication with MCU" errors This is commonly caused by hardware errors on the USB connection between the host machine and the micro-controller. Things to look for: @@ -287,14 +286,14 @@ between the host machine and the micro-controller. Things to look for: one may modify a USB cable so that it does not carry 5V power between the host and micro-controller.) -### My Raspberry Pi keeps rebooting during prints +## My Raspberry Pi keeps rebooting during prints This is most likely do to voltage fluctuations. Follow the same troubleshooting steps for a ["Lost communication with MCU"](#i-keep-getting-random-lost-communication-with-mcu-errors) error. -### When I set "restart_method=command" my AVR device just hangs on a restart +## When I set "restart_method=command" my AVR device just hangs on a restart Some old versions of the AVR bootloader have a known bug in watchdog event handling. This typically manifests when the printer.cfg file has @@ -308,7 +307,7 @@ 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](Bootloaders.md) for further details. -### Will the heaters be left on if the Raspberry Pi crashes? +## Will the heaters be left on if the Raspberry Pi crashes? The software has been designed to prevent that. Once the host enables a heater, the host software needs to confirm that enablement every 5 @@ -331,7 +330,7 @@ heaters and temperature sensors are functioning correctly. See the [config reference](Config_Reference.md#verify_heater) for further details. -### How do I convert a Marlin pin number to a Klipper pin name? +## How do I convert a Marlin pin number to a Klipper pin name? Short answer: A mapping is available in the [sample-aliases.cfg](../config/sample-aliases.cfg) file. Use that file @@ -360,7 +359,7 @@ Arduino board, but is `PC7` on another common Arduino board. To avoid this confusion, the core Klipper code uses the standard pin names defined by the micro-controller. -### Do I have to wire my device to a specific type of micro-controller pin? +## Do I have to wire my device to a specific type of micro-controller pin? It depends on the type of device and type of pin: @@ -394,7 +393,7 @@ steppers, heaters, fans, Z probes, servos, LEDs, common hd44780/st7920 LCD displays, the Trinamic UART control line may be wired to any general purpose IO pin. -### How do I cancel an M109/M190 "wait for temperature" request? +## How do I cancel an M109/M190 "wait for temperature" request? Navigate to the OctoPrint terminal tab and issue an M112 command in the terminal box. The M112 command will cause Klipper to enter into a @@ -405,7 +404,7 @@ terminal tab and issue a FIRMWARE_RESTART command to clear the Klipper error state. After completing this sequence, the previous heating request will be canceled and a new print may be started. -### Can I find out whether the printer has lost steps? +## Can I find out whether the printer has lost steps? In a way, yes. Home the printer, issue a `GET_POSITION` command, run your print, home again and issue another `GET_POSITION`. Then compare @@ -423,7 +422,7 @@ only lose steps in increments of 4 full steps. (So, if one is using 16 microsteps, then a lost step on the stepper would result in the "mcu:" step counter being off by a multiple of 64 microsteps.) -### Why does Klipper report errors? I lost my print! +## Why does Klipper report errors? I lost my print! 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 @@ -453,7 +452,7 @@ experience during abnormal events, but it is expected that will require notable infrastructure work (including a shift away from G-Code). -### How do I upgrade to the latest software? +## How do I upgrade to the latest software? The first step to upgrading the software is to review the latest [config changes](Config_Changes.md) document. On occasion, changes are @@ -504,7 +503,7 @@ Note that the RESTART and FIRMWARE_RESTART g-code commands do not load new software - the above "sudo service klipper restart" and "make flash" commands are needed for a software change to take effect. -### How do I uninstall Klipper? +## How do I uninstall Klipper? On the firmware end, nothing special needs to happen. Just follow the flashing directions for the new firmware. diff --git a/docs/Features.md b/docs/Features.md index b32cb7cf..e9a5adeb 100644 --- a/docs/Features.md +++ b/docs/Features.md @@ -1,3 +1,5 @@ +# Features + Klipper has several compelling features: * High precision stepper movement. Klipper utilizes an application @@ -72,8 +74,7 @@ Klipper has several compelling features: enables programmers to build external applications with detailed control of the printer. -Additional features -=================== +## Additional features Klipper supports many standard 3d printer features: @@ -145,8 +146,7 @@ Klipper supports many standard 3d printer features: To get started with Klipper, read the [installation](Installation.md) guide. -Step Benchmarks -=============== +## Step Benchmarks Below are the results of stepper performance tests. The numbers shown represent total number of steps per second on the micro-controller. diff --git a/docs/G-Codes.md b/docs/G-Codes.md index 34250df6..6554d695 100644 --- a/docs/G-Codes.md +++ b/docs/G-Codes.md @@ -1,7 +1,9 @@ +# G-Codes + This document describes the commands that Klipper supports. These are commands that one may enter into the OctoPrint terminal tab. -# G-Code commands +## G-Code commands Klipper supports the following standard G-Code commands: - Move (G0 or G1): `G1 [X] [Y] [Z] [E] [F]` @@ -48,7 +50,7 @@ to implement it with a custom example, one might use this to implement: `G12`, `G29`, `G30`, `G31`, `M42`, `M80`, `M81`, `T1`, etc. -## G-Code SD card commands +### G-Code SD card commands Klipper also supports the following standard G-Code commands if the [virtual_sdcard config section](Config_Reference.md#virtual_sdcard) is @@ -66,7 +68,7 @@ In addition, the following extended commands are availble when the - Load a file and start SD print: `SDCARD_PRINT_FILE FILENAME=` - Unload file and clear SD state: `SDCARD_RESET_FILE` -## G-Code arcs +### G-Code arcs The following standard G-Code commands are available if a [gcode_arcs config section](Config_Reference.md#gcode_arcs) is @@ -74,7 +76,7 @@ enabled: - Controlled Arc Move (G2 or G3): `G2 [X] [Y] [Z] [E] [F] I J` -## G-Code firmware retraction +### G-Code firmware retraction The following standard G-Code commands are available if a [firmware_retraction config section](Config_Reference.md#firmware_retraction) @@ -82,20 +84,20 @@ is enabled: - Retract: `G10` - Unretract: `G11` -## G-Code display commands +### G-Code display commands The following standard G-Code commands are available if a [display config section](Config_Reference.md#display) is enabled: - Display Message: `M117 ` - Set build percentage: `M73 P` -## Other available G-Code commands +### Other available G-Code commands The following standard G-Code commands are currently available, but using them is not recommended: - Get Endstop Status: `M119` (Use QUERY_ENDSTOPS instead.) -# Extended G-Code Commands +## Extended G-Code Commands Klipper uses "extended" G-Code commands for general configuration and status. These extended commands all follow a similar format - they @@ -240,7 +242,7 @@ The following standard commands are supported: - `STATUS`: Report the Klipper host software status. - `HELP`: Report the list of available extended G-Code commands. -## G-Code Macro Commands +### G-Code Macro Commands The following command is available when a [gcode_macro config section](Config_Reference.md#gcode_macro) is @@ -251,7 +253,7 @@ enabled (also see the gcode_macro variable at run-time. The provided VALUE is parsed as a Python literal. -## Custom Pin Commands +### Custom Pin Commands The following command is available when an [output_pin config section](Config_Reference.md#output_pin) is @@ -261,7 +263,7 @@ enabled: Note: Hardware PWM does not currently support the CYCLE_TIME parameter and will use the cycle time defined in the config. -## Manually Controlled Fans Commands +### Manually Controlled Fans Commands The following command is available when a [fan_generic config section](Config_Reference.md#fan_generic) is @@ -269,7 +271,7 @@ enabled: - `SET_FAN_SPEED FAN=config_name SPEED=` This command sets the speed of a fan. must be between 0.0 and 1.0. -## Neopixel and Dotstar Commands +### Neopixel and Dotstar Commands The following command is available when a [neopixel config section](Config_Reference.md#neopixel) or @@ -291,7 +293,7 @@ The following command is available when a timing is not needed, the optional SYNC=0 parameter can be specified to apply the changes instantly and not reset the idle timeout. -## Servo Commands +### Servo Commands The following commands are available when a [servo config section](Config_Reference.md#servo) is enabled: @@ -299,7 +301,7 @@ The following commands are available when a Set the servo position to the given angle (in degrees) or pulse width (in seconds). Use `WIDTH=0` to disable the servo output. -## Manual stepper Commands +### Manual stepper Commands The following command is available when a [manual_stepper config section](Config_Reference.md#manual_stepper) is @@ -323,7 +325,7 @@ enabled: future G-Code movement commands may run in parallel with the stepper movement. -## Extruder stepper Commands +### Extruder stepper Commands The following command is available when an [extruder_stepper config section](Config_Reference.md#extruder_stepper) @@ -333,7 +335,7 @@ is enabled: STEPPER to become synchronized to the given EXTRUDER, overriding the extruder defined in the "extruder_stepper" config section. -## Probe +### Probe The following commands are available when a [probe config section](Config_Reference.md#probe) is enabled (also see @@ -363,7 +365,7 @@ the [probe calibrate guide](Probe_Calibrate.md)): This acts to take a frequently used babystepping value, and "make it permanent". Requires a `SAVE_CONFIG` to take effect. -## BLTouch +### BLTouch The following command is available when a [bltouch config section](Config_Reference.md#bltouch) is enabled (also @@ -379,7 +381,7 @@ see the [BL-Touch guide](BLTouch.md)): - `BLTOUCH_STORE MODE=`: This stores an output mode in the EEPROM of a BLTouch V3.1 Available output_modes are: `5V`, `OD` -## Delta Calibration +### Delta Calibration The following commands are available when the [delta_calibrate config section](Config_Reference.md#linear-delta-kinematics) @@ -394,7 +396,7 @@ is enabled (also see the [delta calibrate guide](Delta_Calibrate.md)): - `DELTA_ANALYZE`: This command is used during enhanced delta calibration. See [Delta Calibrate](Delta_Calibrate.md) for details. -## Bed Tilt +### Bed Tilt The following commands are available when the [bed_tilt config section](Config_Reference.md#bed_tilt) is enabled: @@ -406,7 +408,7 @@ The following commands are available when the MANUAL_PROBE command above for details on the additional commands available while this tool is active. -## Mesh Bed Leveling +### Mesh Bed Leveling The following commands are available when the [bed_mesh config section](Config_Reference.md#bed_mesh) is enabled @@ -444,7 +446,7 @@ The following commands are available when the independent extruders, as an offset is necessary to produce correct Z adjustment after a tool change. -## Bed Screws Helper +### Bed Screws Helper The following commands are available when the [bed_screws config section](Config_Reference.md#bed_screws) is enabled @@ -456,7 +458,7 @@ The following commands are available when the the bed screws so that the bed is a constant distance from the nozzle. -## Bed Screws Tilt Adjust Helper +### Bed Screws Tilt Adjust Helper The following commands are available when the [screws_tilt_adjust config section](Config_Reference.md#screws_tilt_adjust) @@ -471,7 +473,7 @@ is enabled (also see the See the PROBE command for details on the optional probe parameters. IMPORTANT: You MUST always do a G28 before using this command. -## Z Tilt +### Z Tilt The following commands are available when the [z_tilt config section](Config_Reference.md#z_tilt) is enabled: @@ -480,7 +482,7 @@ The following commands are available when the adjustments to each Z stepper to compensate for tilt. See the PROBE command for details on the optional probe parameters. -## Dual Carriages +### Dual Carriages The following command is available when the [dual_carriage config section](Config_Reference.md#dual_carriage) is @@ -489,7 +491,7 @@ enabled: carriage. It is typically invoked from the activate_gcode and deactivate_gcode fields in a multiple extruder configuration. -## TMC stepper drivers +### TMC stepper drivers The following commands are available when any of the [tmcXXXX config sections](Config_Reference.md#tmc-stepper-driver-configuration) @@ -510,7 +512,7 @@ are enabled: Permanent changes should be made using the printer configuration file instead. No sanity checks are performed for the given values. -## Endstop adjustments by stepper phase +### Endstop adjustments by stepper phase The following commands are available when an [endstop_phase config section](Config_Reference.md#endstop_phase) is @@ -522,7 +524,7 @@ enabled (also see the [endstop phase guide](Endstop_Phase.md)): setting to be written to the config file (in conjunction with the SAVE_CONFIG command). -## Force movement +### Force movement The following commands are available when the [force_move config section](Config_Reference.md#force_move) is @@ -549,7 +551,7 @@ enabled: future boundary checks; issue a G28 afterwards to reset the kinematics. -## SDcard loop +### SDcard loop When the [sdcard_loop config section](Config_Reference.md#sdcard_loop) is enabled, the following extended commands are available: @@ -560,7 +562,7 @@ is enabled, the following extended commands are available: - `SDCARD_LOOP_DESIST`: Complete existing loops without further iterations. -## Send message (respond) to host +### Send message (respond) to host The following commands are availabe when the [respond config section](Config_Reference.md#respond) is enabled. @@ -579,7 +581,7 @@ The following commands are availabe when the prepended with ``. (The `PREFIX` parameter will take priority over the `TYPE` parameter) -## Pause Resume +### Pause Resume The following commands are available when the [pause_resume config section](Config_Reference.md#pause_resume) is @@ -596,7 +598,7 @@ enabled: sure the paused state is fresh for each print. - `CANCEL_PRINT`: Cancels the current print. -## Filament Sensor +### Filament Sensor The following command is available when the [filament_switch_sensor or filament_motion_sensor config section](Config_Reference.md#filament_switch_sensor) @@ -608,7 +610,7 @@ is enabled. filament sensor on/off. If ENABLE is set to 0, the filament sensor will be disabled, if set to 1 it is enabled. -## Firmware Retraction +### Firmware Retraction The following commands are available when the [firmware_retraction config section](Config_Reference.md#firmware_retraction) @@ -636,7 +638,7 @@ retraction required. - `G11`: Unretracts the extruder using the currently configured parameters. -## Skew Correction +### Skew Correction The following commands are available when the [skew_correction config section](Config_Reference.md#skew_correction) @@ -666,7 +668,7 @@ is enabled (also see the [skew correction guide](skew_correction.md)): SAVE_CONFIG gcode must be run to make the changes to peristent memory permanent. -## Delayed GCode +### Delayed GCode The following command is enabled if a [delayed_gcode config section](Config_Reference.md#delayed_gcode) has @@ -677,7 +679,7 @@ been enabled (also see the for gcode execution. A value of 0 will cancel a pending delayed gcode from executing. -## Save Variables +### Save Variables The following command is enabled if a [save_variables config section](Config_Reference.md#save_variables) @@ -688,7 +690,7 @@ has been enabled: startup and can be used in gcode macros. The provided VALUE is parsed as a Python literal. -## Resonance compensation +### Resonance compensation The following command is enabled if an [input_shaper config section](Config_Reference.md#input_shaper) has @@ -707,7 +709,7 @@ been enabled (also see the [config reference](Config_Reference.md#input_shaper) for more details on each of these parameters. -## Temperature Fan Commands +### Temperature Fan Commands The following command is available when a [temperature_fan config section](Config_Reference.md#temperature_fan) @@ -717,7 +719,7 @@ is enabled: 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. -## Adxl345 Accelerometer Commands +### Adxl345 Accelerometer Commands The following commands are available when an [adxl345 config section](Config_Reference.md#adxl345) is enabled: @@ -750,7 +752,7 @@ The following commands are available when an can be a decimal or a hexadecimal integer. Use with care, and refer to ADXL345 data sheet for the reference. -## Resonance Testing Commands +### Resonance Testing Commands The following commands are available when a [resonance_tester config section](Config_Reference.md#resonance_tester) @@ -797,7 +799,7 @@ is enabled (also see the the suggested input shaper parameters can be persisted in the config by issuing `SAVE_CONFIG` command. -## Palette 2 Commands +### Palette 2 Commands The following command is available when the [palette2 config section](Config_Reference.md#palette2) diff --git a/docs/HallFilamentWidthSensor.md b/docs/HallFilamentWidthSensor.md index 85f47c2c..19a7d58a 100644 --- a/docs/HallFilamentWidthSensor.md +++ b/docs/HallFilamentWidthSensor.md @@ -1,3 +1,5 @@ +# Hall filament width sensor + This document describes Filament Width Sensor host module. Hardware used for developing this host module is based on Two Hall liniar sensors (ss49e for example). Sensors in the body are located 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.com](https://www.thingiverse.com/thing:4138933) [Hall based filament width sensor assembly video](https://www.youtube.com/watch?v=TDO9tME8vp4) diff --git a/docs/Installation.md b/docs/Installation.md index b04bef80..faf4d71c 100644 --- a/docs/Installation.md +++ b/docs/Installation.md @@ -1,3 +1,5 @@ +# Installation + These instructions assume the software will run on a Raspberry Pi computer in conjunction with OctoPrint. It is recommended that a Raspberry Pi 2, 3, or 4 computer be used as the host machine (see the @@ -9,8 +11,7 @@ micro-controllers, [ARM based micro-controllers](Features.md#step-benchmarks), and [Beaglebone PRU](beaglebone.md) based printers. -Prepping an OS image -==================== +## Prepping an OS image Start by installing [OctoPi](https://github.com/guysoft/OctoPi) on the Raspberry Pi computer. Use OctoPi v0.17.0 or later - see the @@ -38,8 +39,7 @@ setup Klipper to run at system startup, and start the Klipper host software. It will require an internet connection and it may take a few minutes to complete. -Building and flashing the micro-controller -========================================== +## Building and flashing the micro-controller To compile the micro-controller code, start by running these commands on the Raspberry Pi: @@ -92,8 +92,7 @@ When flashing for the first time, make sure that OctoPrint is not connected directly to the printer (from the OctoPrint web page, under the "Connection" section, click "Disconnect"). -Configuring OctoPrint to use Klipper -==================================== +## Configuring OctoPrint to use Klipper The OctoPrint web server needs to be configured to communicate with the Klipper host software. Using a web browser, login to the OctoPrint @@ -121,8 +120,7 @@ terminal window will likely report there is an error opening the config file - that means OctoPrint is successfully communicating with Klipper. Proceed to the next section. -Configuring Klipper -=================== +## Configuring Klipper The Klipper configuration is stored in a text file on the Raspberry Pi. Take a look at the example config files in the @@ -182,8 +180,7 @@ After Klipper reports that the printer is ready go on to the [config check document](Config_checks.md) to perform some basic checks on the pin definitions in the config file. -Contacting the developers -========================= +## Contacting the developers Be sure to see the [FAQ](FAQ.md) for answers to some common questions. See the [contact page](Contact.md) to report a bug or to contact the diff --git a/docs/Kinematics.md b/docs/Kinematics.md index ee501dff..fff02dba 100644 --- a/docs/Kinematics.md +++ b/docs/Kinematics.md @@ -1,11 +1,12 @@ +# Kinematics + This document provides an overview of how Klipper implements robot motion (its [kinematics](https://en.wikipedia.org/wiki/Kinematics)). The contents may be of interest to both developers interested in working on the Klipper software as well as users interested in better understanding the mechanics of their machines. -Acceleration -============ +## Acceleration Klipper implements a constant acceleration scheme whenever the print head changes velocity - the velocity is gradually changed to the new @@ -31,8 +32,7 @@ acceleration is: velocity(time) = start_velocity + accel*time ``` -Trapezoid generator -=================== +## Trapezoid generator Klipper uses a traditional "trapezoid generator" to model the motion of each move - each move has a start speed, it accelerates to a @@ -54,8 +54,7 @@ of zero duration (if the end speed is equal to the cruising speed). ![trapezoids](img/trapezoids.svg.png) -Look-ahead -========== +## Look-ahead The "look-ahead" system is used to determine cornering speeds between moves. @@ -97,8 +96,7 @@ Key formula for look-ahead: end_velocity^2 = start_velocity^2 + 2*accel*move_distance ``` -Smoothed look-ahead -------------------- +### Smoothed look-ahead Klipper also implements a mechanism for smoothing out the motions of short "zigzag" moves. Consider the following moves: @@ -127,8 +125,7 @@ however, this limit reduces the top speed. Note that it does not change the actual acceleration within the move - the move continues to use the normal acceleration scheme up to its adjusted top-speed. -Generating steps -================ +## Generating steps Once the look-ahead process completes, the print head movement for the given move is fully known (time, start position, end position, @@ -167,8 +164,7 @@ cartesian_y_position = start_y + move_distance * total_y_movement / total_moveme cartesian_z_position = start_z + move_distance * total_z_movement / total_movement ``` -Cartesian Robots ----------------- +### Cartesian Robots Generating steps for cartesian printers is the simplest case. The movement on each axis is directly related to the movement in cartesian @@ -181,8 +177,7 @@ stepper_y_position = cartesian_y_position stepper_z_position = cartesian_z_position ``` -CoreXY Robots ----------------- +### CoreXY Robots Generating steps on a CoreXY machine is only a little more complex than basic cartesian robots. The key formulas are: @@ -192,8 +187,7 @@ stepper_b_position = cartesian_x_position - cartesian_y_position stepper_z_position = cartesian_z_position ``` -Delta Robots ------------- +### Delta Robots Step generation on a delta robot is based on Pythagoras's theorem: ``` @@ -224,8 +218,7 @@ this limit, moves at the extreme edge of the build envelope (where a stepper arm may be nearly horizontal) will have a lower maximum acceleration and velocity. -Extruder kinematics -------------------- +### Extruder kinematics ### Klipper implements extruder motion in its own kinematic class. Since the timing and speed of each print head movement is fully known for diff --git a/docs/MCU_Commands.md b/docs/MCU_Commands.md index 1859f33a..12e3f65c 100644 --- a/docs/MCU_Commands.md +++ b/docs/MCU_Commands.md @@ -1,3 +1,5 @@ +# MCU commands + This document provides information on the low-level micro-controller commands that are sent from the Klipper "host" software and processed by the Klipper micro-controller software. This document is not an @@ -18,8 +20,7 @@ document) take a string value which is automatically converted to an integer value for the micro-controller. This is common with parameters named "pin" (or that have a suffix of "_pin"). -Startup Commands -================ +## Startup Commands It may be necessary to take certain one-time actions to configure the micro-controller and its peripherals. This section lists common @@ -45,8 +46,7 @@ Common startup commands: and 255 indicating a full on state. This command may be useful for enabling CPU and nozzle cooling fans. -Low-level micro-controller configuration -======================================== +## Low-level micro-controller configuration Most commands in the micro-controller require an initial setup before they can be successfully invoked. This section provides an overview of @@ -102,8 +102,7 @@ it if not. Configuration involves the following phases: micro-controller has not been configured in the state desired by the host. -Common micro-controller objects -------------------------------- +### Common micro-controller objects This section lists some commonly used config commands. @@ -171,8 +170,7 @@ This section lists some commonly used config commands. without a CS pin definition. It is useful for SPI devices that do not have a chip select line. -Common commands -=============== +## Common commands This section lists some commonly used run-time commands. It is likely only of interest to developers looking to gain insight into Klipper. @@ -218,8 +216,7 @@ only of interest to developers looking to gain insight into Klipper. the drift between host and micro-controller clocks. It enables the host to accurately estimate the micro-controller clock. -Stepper commands ----------------- +### Stepper commands * `queue_step oid=%c interval=%u count=%hu add=%hi` : This command schedules 'count' number of steps for the given stepper, with @@ -279,8 +276,7 @@ space in the queue before sending a queue_step command. The host does this by calculating when each queue_step command completes and scheduling new queue_step commands accordingly. -SPI Commands ------------- +### SPI Commands * `spi_transfer oid=%c data=%*s` : This command causes the micro-controller to send 'data' to the spi device specified by 'oid' diff --git a/docs/Manual_Level.md b/docs/Manual_Level.md index ac75a868..ada31b4d 100644 --- a/docs/Manual_Level.md +++ b/docs/Manual_Level.md @@ -1,7 +1,9 @@ +# Manual leveling + This document describes tools for calibrating a Z endstop and for performing adjustments to bed leveling screws. -# Calibrating a Z endstop +## Calibrating a Z endstop An accurate Z endstop position is critical to obtaining high quality prints. @@ -47,7 +49,7 @@ location of the endstop is in a convenient location, one can make any further adjustments by running Z_ENDSTOP_CALIBRATE or by manually updating the Z position_endstop in the configuration file. -# Adjusting bed leveling screws +## Adjusting bed leveling screws The secret to getting good bed leveling with bed leveling screws is to utilize the printer's high precision motion system during the bed @@ -101,7 +103,7 @@ This system works best when the printer has a flat printing surface (such as glass) and has straight rails. Upon successful completion of the bed leveling tool the bed should be ready for printing. -## Fine grained bed screw adjustments +### Fine grained bed screw adjustments 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" @@ -138,7 +140,7 @@ once those are accepted, it will prompt for fine adjustments at the additional locations. Continue to use `ACCEPT` and `ADJUSTED` at each position. -# Adjusting bed leveling screws using the bed probe +## Adjusting bed leveling screws using the bed probe 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). diff --git a/docs/Measuring_Resonances.md b/docs/Measuring_Resonances.md index 8b7fed0f..c4051976 100644 --- a/docs/Measuring_Resonances.md +++ b/docs/Measuring_Resonances.md @@ -15,10 +15,9 @@ pulling SDO to GND), and, if it is going to be connected to a 5V printer MCU, that it has a voltage regulator and a level shifter. -Installation instructions -=========================== +## Installation instructions -## Wiring +### Wiring 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 @@ -41,7 +40,7 @@ Fritzing wiring diagrams for some of the ADXL345 boards: Double-check your wiring before powering up the Raspberry Pi to prevent damaging it or the accelerometer. -## Mounting the accelerometer +### Mounting the accelerometer 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 @@ -63,7 +62,7 @@ be designed such as to ensure the electrical isolation of the accelerometer from the printer frame. Failing to ensure that can create a ground loop in the system that may damage the electronics. -## Software installation +### Software installation Note that resonance measurements and shaper auto-calibration require additional software dependencies not installed by default. First, you will have to run on @@ -107,10 +106,9 @@ slightly above it. Restart Klipper via the `RESTART` command. -Measuring the resonances -=========================== +## Measuring the resonances -## Checking the setup +### Checking the setup Now you can test a connection. @@ -138,7 +136,7 @@ somewhere in the range of ~1-100). Too high axes noise (e.g. 1000 and more) can be indicative of the sensor issues, problems with its power, or too noisy imbalanced fans on a 3D printer. -## Measuring the resonances +### Measuring the resonances Now you can run some real-life tests. Run the following command: ``` @@ -212,7 +210,7 @@ from Klipper [directly](#input-shaper-auto-calibration), which can be convenient, for example, for the input shaper [re-calibration](#input-shaper-re-calibration). -## Bed-slinger printers +### Bed-slinger printers 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 @@ -242,7 +240,7 @@ probe_points: ... Then the commands `TEST_RESONANCES AXIS=X` and `TEST_RESONANCES AXIS=Y` will use the correct accelerometer for each axis. -## Max smoothing +### Max smoothing Keep in mind that the input shaper can create some smoothing in parts. Automatic tuning of the input shaper performed by `calibrate_shaper.py` @@ -327,7 +325,7 @@ Then, if you [rerun](#input-shaper-re-calibration) the input shaper auto-tuning using `SHAPER_CALIBRATE` Klipper command in the future, it will use the stored `max_smoothing` value as a reference. -## Selecting max_accel +### Selecting max_accel 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 @@ -357,7 +355,7 @@ If you are doing a shaper re-calibration and the reported smoothing for the suggested shaper configuration is almost the same as what you got during the previous calibration, this step can be skipped. -## Testing custom axes +### Testing custom axes `TEST_RESONANCES` command supports custom axes. While this is not really useful for input shaper calibration, it can be used to study printer @@ -387,7 +385,7 @@ and then use the same command ``` to generate `/tmp/resonances.png` comparing the resonances. -# Input Shaper auto-calibration +## Input Shaper auto-calibration Besides manually choosing the appropriate parameters for the input shaper feature, it is also possible to run the auto-tuning for the input shaper @@ -436,7 +434,7 @@ However, if you connected two accelerometers simultaneously, you simply run `SHAPER_CALIBRATE` without specifying an axis to calibrate the input shaper for both axes in one go. -## Input Shaper re-calibration +### Input Shaper re-calibration `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 @@ -463,7 +461,7 @@ is not expected that the noise will affect the print quality too much. However, it is still advised to double-check the suggested parameters, and print some test prints before using them to confirm they are good. -# Offline processing of the accelerometer data +## Offline processing of the accelerometer data 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, diff --git a/docs/Overview.md b/docs/Overview.md index 21daffe3..7d712433 100644 --- a/docs/Overview.md +++ b/docs/Overview.md @@ -1,8 +1,10 @@ +# Overview + Welcome to the Klipper documentation. If new to Klipper, start with the [features](Features.md) and [installation](Installation.md) documents. -# Overview information +## Overview information - [Features](Features.md): A high-level list of features in Klipper. - [FAQ](FAQ.md): Frequently asked questions. @@ -12,7 +14,7 @@ may require users to update their printer config file. - [Contact](Contact.md): Information on bug reporting and general communication with the Klipper developers. -# Configuration and Tuning Guides +## Configuration and Tuning Guides - [Installation](Installation.md): Guide to installing Klipper. - [Config Reference](Config_Reference.md): Description of config @@ -52,7 +54,7 @@ communication with the Klipper developers. tools such as lasers or spindles. - [G-Codes](G-Codes.md): Information on commands supported by Klipper. -# Developer Documentation +## Developer Documentation - [Code overview](Code_Overview.md): Developers should read this first. @@ -74,7 +76,7 @@ communication with the Klipper developers. improvements to Klipper. - [Packaging](Packaging.md): Information on building OS packages. -# Device Specific Documents +## Device Specific Documents - [Example configs](Example_Configs.md): Information on adding an example config file to Klipper. diff --git a/docs/Pressure_Advance.md b/docs/Pressure_Advance.md index 5a09c895..2f3601ca 100644 --- a/docs/Pressure_Advance.md +++ b/docs/Pressure_Advance.md @@ -1,11 +1,12 @@ +# Pressure advance + 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](Kinematics.md) document. -Tuning pressure advance -======================= +## Tuning pressure advance Pressure advance does two useful things - it reduces ooze during non-extrude moves and it reduces blobbing during cornering. This guide @@ -83,8 +84,7 @@ the configuration file and issue a RESTART command. The RESTART command will clear the test state and return the acceleration and cornering speeds to their normal values. -Important Notes -=============== +## Important Notes * The pressure advance value is dependent on the extruder, the nozzle, and the filament. It is common for filament from different diff --git a/docs/Probe_Calibrate.md b/docs/Probe_Calibrate.md index 48216174..3531d13c 100644 --- a/docs/Probe_Calibrate.md +++ b/docs/Probe_Calibrate.md @@ -1,8 +1,10 @@ +# Probe calibration + This document describes the method for calibrating the x, y, and z offsets of an "automatic z probe" in Klipper. This is useful for users that have a `[probe]` or `[bltouch]` section in their config file. -# Calibrating probe X and Y offsets +## Calibrating probe X and Y offsets To calibrate the X and Y offset, navigate to the OctoPrint "Control" tab, home the printer, and then use the OctoPrint jogging buttons to @@ -41,7 +43,7 @@ Update the printer.cfg file with the given values, remove the tape/marks from the bed, and then issue a `RESTART` command so that the new values take effect. -# Calibrating probe Z offset +## Calibrating probe Z offset Providing an accurate probe z_offset is critical to obtaining high quality prints. The z_offset is the distance between the nozzle and @@ -85,7 +87,7 @@ If the results of PROBE_CALIBRATE are invalidated, then any previous also invalidated - it will be necessary to rerun BED_MESH_CALIBRATE after recalibrating the probe. -# Repeatability check +## Repeatability check 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 @@ -143,7 +145,7 @@ bed leveling. Klipper has several manual probing tools that can be used instead - see the [Bed Level document](Bed_Level.md) for further details. -# Location Bias Check +## Location Bias Check Some probes can have a systemic bias that corrupts the results of the probe at certain toolhead locations. For example, if the probe mount @@ -177,7 +179,7 @@ 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](Bed_Level.md) for manual probe alternatives. -# Temperature Bias +## Temperature Bias Many probes have a systemic bias when probing at different temperatures. For example, the probe may consistently trigger at a diff --git a/docs/Protocol.md b/docs/Protocol.md index 92ffcf27..ce5719e1 100644 --- a/docs/Protocol.md +++ b/docs/Protocol.md @@ -1,3 +1,5 @@ +# Protocol + The Klipper messaging protocol is used for low-level communication between the Klipper host software and the Klipper micro-controller software. At a high level the protocol can be thought of as a series @@ -26,8 +28,7 @@ The goal of the protocol is to enable an error-free communication channel between the host and micro-controller that is low-latency, low-bandwidth, and low-complexity for the micro-controller. -Micro-controller Interface -========================== +## Micro-controller Interface The Klipper transmission protocol can be thought of as a [RPC](https://en.wikipedia.org/wiki/Remote_procedure_call) mechanism @@ -37,8 +38,7 @@ messages that it can generate. The host uses that information to command the micro-controller to perform actions and to interpret the results. -Declaring commands ------------------- +### Declaring commands The micro-controller software declares a "command" by using the DECL_COMMAND() macro in the C code. For example: @@ -69,8 +69,7 @@ The micro-controller build will collect all commands declared with DECL_COMMAND(), determine their parameters, and arrange for them to be callable. -Declaring responses -------------------- +### Declaring responses To send information from the micro-controller to the host a "response" is generated. These are both declared and transmitted using the @@ -97,7 +96,7 @@ code does not need to issue a sendf() in response to a received command, it is not limited in the number of times sendf() may be invoked, and it may invoke sendf() at any time from a task handler. -### Output responses +#### Output responses To simplify debugging, there is also an output() C function. For example: @@ -109,8 +108,7 @@ output("The value of %u is %s with size %u.", x, buf, buf_len); The output() function is similar in usage to printf() - it is intended to generate and format arbitrary messages for human consumption. -Declaring enumerations ----------------------- +### Declaring enumerations Enumerations allow the host code to use string identifiers for parameters that the micro-controller handles as integers. They are @@ -133,8 +131,7 @@ example, a "pin" parameter (or any parameter with a suffix of "_pin") would accept PC0, PC1, PC2, ..., PC7 as valid values. The strings will be transmitted with integers 16, 17, 18, ..., 23. -Declaring constants -------------------- +### Declaring constants Constants can also be exported. For example, the following: @@ -150,15 +147,13 @@ a constant that is a string - for example: DECL_CONSTANT_STR("MCU", "pru"); ``` -Low-level message encoding -========================== +## Low-level message encoding To accomplish the above RPC mechanism, each command and response is encoded into a binary format for transmission. This section describes the transmission system. -Message Blocks --------------- +### Message Blocks All data sent from host to micro-controller and vice-versa are contained in "message blocks". A message block has a two byte header @@ -187,8 +182,7 @@ an additional sync character at the start of the block. Unlike in HDLC, a sync character is not exclusive to the framing and may be present in the message block content. -Message Block Contents ----------------------- +### Message Block Contents Each message block sent from host to micro-controller contains a series of zero or more message commands in its contents. Each command @@ -231,7 +225,7 @@ encoding rules. In practice, message blocks sent from the micro-controller to the host never contain more than one response in the message block contents. -### Variable Length Quantities +#### Variable Length Quantities See the [wikipedia article](https://en.wikipedia.org/wiki/Variable-length_quantity) for more information on the general format of VLQ encoded @@ -249,7 +243,7 @@ takes to encode: | -67108864 .. 201326591 | 4 | | -2147483648 .. 4294967295 | 5 | -### Variable length strings +#### Variable length strings 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 @@ -264,8 +258,7 @@ The command descriptions found in the data dictionary allow both the host and micro-controller to know which command parameters use simple VLQ encoding and which parameters use string encoding. -Data Dictionary -=============== +## Data Dictionary In order for meaningful communications to be established between micro-controller and host, both sides must agree on a "data @@ -311,8 +304,7 @@ dictionary also contains the software version, enumerations (as defined by DECL_ENUMERATION), and constants (as defined by DECL_CONSTANT). -Message flow -============ +## Message flow Message commands sent from host to micro-controller are intended to be error-free. The micro-controller will check the CRC and sequence diff --git a/docs/RPi_microcontroller.md b/docs/RPi_microcontroller.md index 92e59560..4a24b517 100644 --- a/docs/RPi_microcontroller.md +++ b/docs/RPi_microcontroller.md @@ -1,8 +1,10 @@ +# RPi microcontroller + This document describes the process of running Klipper on a RPi and use the same RPi as secondary mcu. -Why use RPi as a secondary MCU? -=============================== +## Why use RPi as a secondary MCU? + 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 ...). @@ -13,8 +15,7 @@ programs giving the ability to control everything within the print GCODE. **Warning**: If your platform is a _Beaglebone_ and you have correctly followed the installation steps, the linux mcu is already installed and configured for your system. -Install the rc script -===================== +## Install the rc script If you want to use the host as a secondary MCU the klipper_mcu process must run before the klippy process. @@ -25,12 +26,11 @@ sudo cp "./scripts/klipper-mcu-start.sh" /etc/init.d/klipper_mcu sudo update-rc.d klipper_mcu defaults ``` -Enabling SPI -============ +## Enabling SPI + Make sure the Linux SPI driver is enabled by running sudo raspi-config and enabling SPI under the "Interfacing options" menu. -Building the micro-controller code -================================== +## Building the micro-controller code To compile the Klipper micro-controller code, start by configuring it for the "Linux process": @@ -54,16 +54,15 @@ The following command will add the "pi" user to the tty group: sudo usermod -a -G tty pi ``` -Remaining configuration -======================= +## Remaining configuration Complete the installation by configuring Klipper secondary MCU following the instructions in [RaspberryPi sample config](../config/sample-raspberry-pi.cfg) and [Multi MCU sample config](../config/sample-multi-mcu.cfg). -Optional: Identify the correct gpiochip -======================================= +## Optional: Identify the correct gpiochip + On Rasperry and on many clones the pins exposed on the GPIO belong to the first gpiochip. They can therefore be used on klipper simply by referring them with the name `gpio0..n`. However, there are cases in which the exposed pins belong to gpiochips other than the first. For example in the case of some OrangePi models or if a Port Expander is used. In these cases it is useful to use the commands to access the _Linux GPIO character device_ to verify the configuration. @@ -159,8 +158,8 @@ gpiochip1 - 8 lines: line 7: unnamed unused input active-high ``` -Optional: Hardware PWM -======================================= +## Optional: Hardware PWM + 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```: diff --git a/docs/Releases.md b/docs/Releases.md index 704a9ec3..f5a93a91 100644 --- a/docs/Releases.md +++ b/docs/Releases.md @@ -1,8 +1,9 @@ +# Releases + History of Klipper releases. Please see [installation](Installation.md) for information on installing Klipper. -Klipper 0.9.0 -============= +## Klipper 0.9.0 Available on 20201020. Major changes in this release: * Support for "Input Shaping" - a mechanism to counteract printer @@ -35,13 +36,11 @@ Available on 20201020. Major changes in this release: graph_temp_sensor, whconsole * Several bug fixes and code cleanups. -Klipper 0.9.1 --------------- +### Klipper 0.9.1 Available on 20201028. Release containing only bug fixes. -Klipper 0.8.0 -============= +## Klipper 0.8.0 Available on 20191021. Major changes in this release: * New G-Code command template support. G-Code in the config file is @@ -81,8 +80,7 @@ Available on 20191021. Major changes in this release: SET_IDLE_TIMEOUT, SET_TEMPERATURE_FAN_TARGET * Several bug fixes and code cleanups. -Klipper 0.7.0 -============= +## Klipper 0.7.0 Available on 20181220. Major changes in this release: * Klipper now supports "mesh" bed leveling @@ -115,8 +113,7 @@ Available on 20181220. Major changes in this release: settings, packaging, and more * Several bug fixes and code cleanups -Klipper 0.6.0 -============= +## Klipper 0.6.0 Available on 20180331. Major changes in this release: * Enhanced heater and thermistor hardware failure checks @@ -146,8 +143,7 @@ Available on 20180331. Major changes in this release: * Initial support for continuous integration testing on all github commits * Several bug fixes and code cleanups -Klipper 0.5.0 -============= +## Klipper 0.5.0 Available on 20171025. Major changes in this release: @@ -166,8 +162,7 @@ Available on 20171025. Major changes in this release: cooling fans. * Several bug fixes and code cleanups -Klipper 0.4.0 -============= +## Klipper 0.4.0 Available on 20170503. Major changes in this release: @@ -186,8 +181,7 @@ Available on 20170503. Major changes in this release: * Support for AD595 sensors * Several bug fixes and code cleanups -Klipper 0.3.0 -============= +## Klipper 0.3.0 Available on 20161223. Major changes in this release: @@ -209,8 +203,7 @@ Available on 20161223. Major changes in this release: along with help on how to resolve. * Several bug fixes and code cleanups -Klipper 0.2.0 -============= +## Klipper 0.2.0 Initial release of Klipper. Available on 20160525. Major features available in the initial release include: diff --git a/docs/Resonance_Compensation.md b/docs/Resonance_Compensation.md index f9d3fb0a..5707d51b 100644 --- a/docs/Resonance_Compensation.md +++ b/docs/Resonance_Compensation.md @@ -22,9 +22,7 @@ can be enabled. Besides ringing, Input Shaping typically reduces the vibrations and shaking of the printer in general, and may also improve the reliability of the stealthChop mode of Trinamic stepper drivers. - -Tuning -=========================== +## Tuning Basic tuning requires measuring the ringing frequencies of the printer and adding a few parameters to `printer.cfg` file. @@ -44,7 +42,7 @@ Slice the ringing test model, which can be found in not a mistake. The marks can be used later in the tuning process as a reference, because they show which axis the measurements correspond to. -## Ringing frequency +### Ringing frequency First, measure the **ringing frequency**. @@ -129,7 +127,7 @@ 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. -## Input shaper configuration +### Input shaper configuration After the ringing frequencies for X and Y axes are measured, you can add the following section to your `printer.cfg`: @@ -141,7 +139,7 @@ shaper_freq_y: ... # frequency for the Y mark of the test model For the example above, we get shaper_freq_x/y = 49.4. -## Choosing input shaper +### Choosing input shaper Klipper supports several input shapers. They differ in their sensitivity to errors determining the resonance frequency and how much smoothing they cause @@ -204,7 +202,7 @@ A few notes on shaper selection: `SET_INPUT_SHAPER SHAPER_TYPE=2HUMP_EI`), but check the considerations in the [section below](#selecting-max_accel) before enabling it. -## Selecting max_accel +### Selecting max_accel 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 @@ -266,7 +264,7 @@ moving mass. Otherwise, acceleration and printing speed may be limited due too much smoothing now instead of ringing. -## Fine-tuning resonance frequencies +### Fine-tuning resonance frequencies Note that the precision of the resonance frequencies measurements using the ringing test model is sufficient for most purposes, so further tuning is not @@ -318,7 +316,7 @@ new `shaper_freq_x` and `shaper_freq_y` values. Do not forget to revert the changes to `max_accel` and `max_accel_to_decel` parameters in the `printer.cfg` after finishing this section. -## Pressure Advance +### Pressure Advance If you use Pressure Advance, it may need to be re-tuned. Follow the [instructions](Pressure_Advance.md#tuning-pressure-advance) to find the @@ -326,7 +324,7 @@ new value, if it differs from the previous one. Make sure to restore the original values of `max_accel` and `max_accel_to_decel` parameters in the `printer.cfg` and restart Klipper before tuning Pressure Advance. -## Unreliable measurements of ringing frequencies +### Unreliable measurements of ringing frequencies 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 @@ -398,8 +396,7 @@ shaper_type: 2hump_ei Continue the tuning with [Selecting max_accel](#selecting-max_accel) section. -Troubleshooting and FAQ -======================= +## Troubleshooting and FAQ ### I cannot get reliable measurements of resonance frequencies @@ -452,10 +449,9 @@ itself. However, the value of `max_accel` certainly does (tuning of this parameter described in [this section](#selecting-max_accel)). -Technical details -================= +## Technical details -## Input shapers +### Input shapers Input shapers used in Klipper are rather standard, and one can find more in-depth overview in the articles describing the corresponding shapers. diff --git a/docs/Rotation_Distance.md b/docs/Rotation_Distance.md index a2b9673b..0d7c6c9b 100644 --- a/docs/Rotation_Distance.md +++ b/docs/Rotation_Distance.md @@ -1,3 +1,5 @@ +# Rotation distance + Stepper motor drivers on Klipper require a `rotation_distance` parameter in each [stepper config section](Config_Reference.md#stepper). The @@ -5,7 +7,7 @@ parameter in each one full revolution of the stepper motor. This document describes how one can configure this value. -# Obtaining rotation_distance from steps_per_mm (or step_distance) +## Obtaining rotation_distance from steps_per_mm (or step_distance) 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 @@ -38,7 +40,7 @@ on x, y, and z type axes. If the above formula results in a rotation_distance that is within .01 of a whole number then round the final value to that whole_number. -# Calibrating rotation_distance on extruders +## Calibrating rotation_distance on extruders On an extruder, the `rotation_distance` is the amount of distance the filament travels for one full rotation of the stepper motor. The best @@ -79,13 +81,13 @@ enough for those axes and will likely lead to a worse configuration. Instead, if needed, those axes can be determined by [measuring the belts, pulleys, and lead screw hardware](#obtaining-rotation_distance-by-inspecting-the-hardware). -# Obtaining rotation_distance by inspecting the hardware +## Obtaining rotation_distance by inspecting the hardware It's possible to calculate rotation_distance with knowledge of the stepper motors and printer kinematics. This may be useful if the steps_per_mm is not known or if designing a new printer. -## Belt driven axes +### Belt driven axes It is easy to calculate rotation_distance for a linear axis that uses a belt and pulley. @@ -101,7 +103,7 @@ rotation_distance = * For example, if a printer has a 2mm belt and uses a pulley with 20 teeth, then the rotation distance is 40. -## Axes with a lead screw +### Axes with a lead screw It is easy to calculate the rotation_distance for common lead screws using the following formula: @@ -118,7 +120,7 @@ screw pitch is the distance between each groove on the screw.) So, for example, an M6 metric rod has a rotation distance of 1 and an M8 rod has a rotation distance of 1.25. -## Extruder +### Extruder It's possible to obtain an initial rotation distance for extruders by measuring the diameter of the "hobbed bolt" that pushes the filament @@ -135,7 +137,7 @@ obtaining an initial rotation_distance, use the [measure and trim procedure](#calibrating-rotation_distance-on-extruders) to obtain a more accurate setting. -# Using a gear_ratio +## Using a gear_ratio Setting a `gear_ratio` can make it easier to configure the `rotation_distance` on steppers that have a gear box (or similar) diff --git a/docs/SDCard_Updates.md b/docs/SDCard_Updates.md index b7994512..09307715 100644 --- a/docs/SDCard_Updates.md +++ b/docs/SDCard_Updates.md @@ -1,3 +1,5 @@ +# SDCard updates + 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 @@ -7,8 +9,7 @@ After Klipper has been initially flashed to a controller it is possible to transfer new firmware to the SD Card and initiate the flashing procedure via ssh. -Typical Upgrade Procedure -========================= +## Typical Upgrade Procedure 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 @@ -37,8 +38,7 @@ Supported boards can be listed with the following command: If you do not see your board listed it may be necessary to add a new board definition as [described below](#board-definitions). -Advanced Usage -============== +## Advanced Usage 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 @@ -78,8 +78,7 @@ 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. -Caveats -======= +## Caveats - As mentioned in the introduction, this method only works for upgrading firmware. The initial flashing procedure must be done manually per the @@ -92,8 +91,7 @@ Caveats Boards that use SDIO, such as the Flymaker Flyboard and MKS Robin Nano V1/V2, will not work. -Board Definitions -================= +## Board Definitions Most common boards should be available, however it is possible to add a new board definition if necessary. Board definitions are located in diff --git a/docs/Slicers.md b/docs/Slicers.md index 6a8c5707..5cc678ec 100644 --- a/docs/Slicers.md +++ b/docs/Slicers.md @@ -1,14 +1,16 @@ +# Slicers + This document provides some tips for configuring a "slicer" application for use with Klipper. Common slicers used with Klipper are Slic3r, Cura, Simplify3D, etc. -# Set the G-Code flavor to Marlin +## Set the G-Code flavor to Marlin Many slicers have an option to configure the "G-Code flavor". The default is frequently "Marlin" and that works well with Klipper. The "Smoothieware" setting also works well with Klipper. -# Klipper gcode_macro +## Klipper gcode_macro Slicers will often allow one to configure "Start G-Code" and "End G-Code" sequences. It is often convenient to define custom macros in @@ -24,7 +26,7 @@ START_PRINT and END_PRINT macros. See the [config reference](Config_Reference.md#gcode_macro) for details on defining a gcode_macro. -# Large retraction settings may require tuning Klipper +## Large retraction settings may require tuning Klipper The maximum speed and acceleration of retraction moves are controlled in Klipper by the `max_extrude_only_velocity` and @@ -39,7 +41,7 @@ finds the toolhead seems to "pause" during retraction and priming, then consider explicitly defining `max_extrude_only_velocity` and `max_extrude_only_accel` in the Klipper config file. -# Do not enable "coasting" +## Do not enable "coasting" The "coasting" feature is likely to result in poor quality prints with Klipper. Consider using Klipper's @@ -52,20 +54,20 @@ between moves. This is likely to make blobbing worse, not better. In contrast, it is okay (and often helpful) to use a slicer's "retract" setting, "wipe" setting, and/or "wipe on retract" setting. -# Do not use "extra restart distance" on Simplify3d +## Do not use "extra restart distance" on Simplify3d This setting can cause dramatic changes to extrusion rates which can trigger Klipper's maximum extrusion cross-section check. Consider using Klipper's [pressure advance](Pressure_Advance.md) or the regular Simplify3d retract setting instead. -# Disable "PreloadVE" on KISSlicer +## Disable "PreloadVE" on KISSlicer If using KISSlicer slicing software then set "PreloadVE" to zero. Consider using Klipper's [pressure advance](Pressure_Advance.md) instead. -# Disable any "advanced extruder pressure" settings +## Disable any "advanced extruder pressure" settings Some slicers advertise an "advanced extruder pressure" capability. It is recommended to keep these options disabled when using Klipper as diff --git a/docs/Status_Reference.md b/docs/Status_Reference.md index e0da69e3..a15720fa 100644 --- a/docs/Status_Reference.md +++ b/docs/Status_Reference.md @@ -1,3 +1,5 @@ +# Status reference + This document is a reference of printer status information available in Klipper [macros](Command_Templates.md), [display fields](Config_Reference.md#display), and via the @@ -8,14 +10,14 @@ attribute be sure to review the [Config Changes document](Config_Changes.md) when upgrading the Klipper software. -# bed_mesh +## bed_mesh The following information is available in the [bed_mesh](Config_Reference.md#bed_mesh) object: - `profile_name`, `mesh_min`, `mesh_max`, `probed_matrix`, `mesh_matrix`: Information on the currently active bed_mesh. -# configfile +## configfile The following information is available in the `configfile` object (this object is always available): @@ -27,7 +29,7 @@ The following information is available in the `configfile` object restart. (Any settings changed at run-time will not be reflected here.) All values are returned as strings. -# display_status +## display_status The following information is available in the `display_status` object (this object is automatically available if a @@ -36,7 +38,7 @@ The following information is available in the `display_status` object `virtual_sdcard.progress` if no recent `M73` received). - `message`: The message contained in the last `M117` G-Code command. -# endstop_phase +## endstop_phase The following information is available in the [endstop_phase](Config_Reference.md#endstop_phase) object: @@ -50,7 +52,7 @@ The following information is available in the forward direction minus the total number of steps taken in the reverse direction since the micro-controller was last restarted. -# fan +## fan The following information is available in [fan](Config_Reference.md#fan), @@ -61,7 +63,7 @@ objects: - `rpm`: The measured fan speed in rotations per minute if the fan has a tachometer_pin defined. -# filament_switch_sensor +## filament_switch_sensor The following information is available in [filament_switch_sensor some_name](Config_Reference.md#filament_switch_sensor) @@ -70,7 +72,7 @@ objects: - `filament_detected`: Returns True if the sensor is in a triggered state. -# filament_motion_sensor +## filament_motion_sensor The following information is available in [filament_motion_sensor some_name](Config_Reference.md#filament_motion_sensor) @@ -79,7 +81,7 @@ objects: - `filament_detected`: Returns True if the sensor is in a triggered state. -# firmware_retraction +## firmware_retraction The following information is available in the [firmware_retraction](Config_Reference.md#firmware_retraction) object: @@ -88,14 +90,14 @@ The following information is available in the module. These settings may differ from the config file if a `SET_RETRACTION` command alters them. -# gcode_macro +## gcode_macro The following information is available in [gcode_macro some_name](Config_Reference.md#gcode_macro) objects: - ``: The current value of a [gcode_macro variable](Command_Templates.md#variables). -# gcode_move +## gcode_move The following information is available in the `gcode_move` object (this object is always available): @@ -124,7 +126,7 @@ The following information is available in the `gcode_move` object - `absolute_extrude`: This returns True if in `M82` absolute extrude mode or False if in `M83` relative mode. -# hall_filament_width_sensor +## hall_filament_width_sensor The following information is available in the [hall_filament_width_sensor](Config_Reference.md#hall_filament_width_sensor) @@ -132,7 +134,7 @@ object: - `is_active`: Returns True if the sensor is currently active. - `Diameter`, `Raw`: The last read values from the sensor. -# heater +## heater The following information is available for heater objects such as [extruder](Config_Reference.md#extruder), @@ -147,7 +149,7 @@ The following information is available for heater objects such as - `can_extrude`: If extruder can extrude (defined by `min_extrude_temp`), available only for [extruder](Config_Reference.md#extruder) -# heaters +## heaters The following information is available in the `heaters` object (this object is available if any heater is defined): @@ -159,7 +161,7 @@ object is available if any heater is defined): e.g. `["extruder", "heater_bed", "heater_generic my_custom_heater", "temperature_sensor electronics_temp"]`. -# idle_timeout +## idle_timeout The following information is available in the [idle_timeout](Config_Reference.md#idle_timeout) object (this object @@ -171,7 +173,7 @@ is always available): been in the "Printing" state (as tracked by the idle_timeout module). -# mcu +## mcu The following information is available in [mcu](Config_Reference.md#mcu) and @@ -187,13 +189,13 @@ The following information is available in - `last_stats.`: Statistics information on the micro-controller connection. -# output_pin +## output_pin The following information is available in [output_pin some_name](Config_Reference.md#output_pin) objects: - `value`: The "value" of the pin, as set by a `SET_PIN` command. -# palette2 +## palette2 The following information is available in the [palette2](Config_Reference.md#palette2) object: @@ -202,14 +204,14 @@ The following information is available in the be the amount of filament to load into the extruder. - `is_splicing`: True when the Palette 2 is splicing filament. -# pause_resume +## pause_resume The following information is available in the [pause_resume](Config_Reference.md#pause_resume) object: - `is_paused`: Returns true if a PAUSE command has been executed without a corresponding RESUME. -# print_stats +## print_stats The following information is available in the `print_stats` object (this object is automatically available if a @@ -219,7 +221,7 @@ defined): `state`, `message`: Estimated information about the current print when a virtual_sdcard print is active. -# probe +## probe The following information is available in the [probe](Config_Reference.md#probe) object (this object is also @@ -234,14 +236,14 @@ is defined): template expansion, the PROBE (or similar) command must be run prior to the macro containing this reference. -# quad_gantry_level +## quad_gantry_level The following information is available in the `quad_gantry_level` object (this object is available if quad_gantry_level is defined): - `applied`: True if the gantry leveling process has been run and completed successfully. -# query_endstops +## query_endstops The following information is available in the `query_endstops` object (this object is available if any endstop is defined): @@ -251,21 +253,21 @@ The following information is available in the `query_endstops` object the QUERY_ENDSTOP command must be run prior to the macro containing this reference. -# servo +## servo The following information is available in [servo some_name](Config_Reference.md#servo) objects: - `printer["servo "].value`: The last setting of the PWM pin (a value between 0.0 and 1.0) associated with the servo. -# system_stats +## system_stats The following information is available in the `system_stats` object (this object is always available): - `sysload`, `cputime`, `memavail`: Information on the host operating system and process load. -# temperature sensors +## temperature sensors The following information is available in @@ -279,7 +281,7 @@ objects: - `humidity`, `pressure`, `gas`: The last read values from the sensor (only on bme280, htu21d, and lm75 sensors). -# temperature_fan +## temperature_fan The following information is available in [temperature_fan some_name](Config_Reference.md#temperature_fan) @@ -287,7 +289,7 @@ objects: - `temperature`: The last read temperature from the sensor. - `target`: The target temperature for the fan. -# temperature_sensor +## temperature_sensor The following information is available in [temperature_sensor some_name](Config_Reference.md#temperature_sensor) @@ -297,7 +299,7 @@ objects: temperature seen by the sensor since the Klipper host software was last restarted. -# toolhead +## toolhead The following information is available in the `toolhead` object (this object is always available): @@ -322,7 +324,7 @@ The following information is available in the `toolhead` object the printer had to be paused because the toolhead moved faster than moves could be read from the G-Code input. -# dual_carriage +## dual_carriage The following information is available in [dual_carriage](Config_Reference.md#dual_carriage) @@ -331,7 +333,7 @@ on a hybrid_corexy or hybrid_corexz robot - `active_carriage`: The current active carriage. Possible values are: "CARRIAGE_0", "CARRIAGE_1" -# virtual_sdcard +## virtual_sdcard The following information is available in the [virtual_sdcard](Config_Reference.md#virtual_sdcard) object: @@ -342,7 +344,7 @@ The following information is available in the - `file_position`: The current position (in bytes) of an active print. - `file_size`: The file size (in bytes) of currently loaded file. -# webhooks +## webhooks The following information is available in the `webhooks` object (this object is always available): @@ -351,14 +353,14 @@ object is always available): - `state_message`: A human readable string giving additional context on the current Klipper state. -# z_tilt +## z_tilt The following information is available in the `z_tilt` object (this object is available if z_tilt is defined): - `applied`: True if the z-tilt leveling process has been run and completed successfully. -# neopixel / dotstar +## neopixel / dotstar The following information is available for each `[neopixel led_name]` and `[dotstar led_name]` defined in printer.cfg: - `color_data`: An array of objects, with each object containing the RGBW diff --git a/docs/TMC_Drivers.md b/docs/TMC_Drivers.md index fd082bde..349b9d1e 100644 --- a/docs/TMC_Drivers.md +++ b/docs/TMC_Drivers.md @@ -1,3 +1,5 @@ +# TMC drivers + This document provides information on using Trinamic stepper motor drivers in SPI/UART mode on Klipper. @@ -9,7 +11,7 @@ this document are not available. In addition to this document, be sure to review the [TMC driver config reference](Config_Reference.md#tmc-stepper-driver-configuration). -# Enabling "Stealthchop" mode +## Enabling "Stealthchop" mode By default, Klipper places the TMC drivers in "spreadcycle" mode. If the driver supports "stealthchop" then it can be enabled by adding @@ -21,7 +23,7 @@ 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. -# Sensorless Homing +## Sensorless Homing Sensorless homing allows to home an axis without the need for a physical limit switch. Instead, the carriage on the axis is moved into @@ -35,7 +37,7 @@ your (cartesian) printer. However, it works the same with all other axes (that require an end stop). You should configure and tune it for one axis at a time. -## Limitations +### Limitations Be sure that your mechanical components are able to handle the load of the carriage bumping into the limit of the axis repeatedly. Especially @@ -62,7 +64,7 @@ of the motor, so the TMC cannot detect stalls anymore. It is advised to have a look in the datasheet of your specific TMCs. There you can also find more details on limitations of this setup. -## Prerequisites +### Prerequisites A few prerequisites are needed to use sensorless homing: @@ -76,7 +78,7 @@ A few prerequisites are needed to use sensorless homing: run to confirm the stepper motors are configured and working properly. -## Tuning +### Tuning The procedure described here has six major steps: 1. Choose a homing speed. @@ -88,7 +90,7 @@ The procedure described here has six major steps: 5. Update the `printer.cfg` with the desired stallguard setting. 6. Create or update `printer.cfg` macros to home consistently. -### Choose homing speed +#### Choose homing speed The homing speed is an important choice when performing sensorless homing. It's desirable to use a slow homing speed so that the carriage @@ -106,7 +108,7 @@ homing_speed: 20 ... ``` -### Configure printer.cfg for sensorless homing +#### Configure printer.cfg for sensorless homing The `homing_retract_dist` setting must be set to zero in the `stepper_x` config section to disable the second homing move. The @@ -214,7 +216,7 @@ movement commands (eg, `G1`). Klipper will not have a correct understanding of the carriage position and a move command may cause undesirable and confusing results. -### Find lowest sensitivity that homes with one touch +#### Find lowest sensitivity that homes with one touch When homing with the found *maximum_sensitivity* value, the axis should move to the end of the rail and stop with a "single touch" - @@ -231,7 +233,7 @@ with a "single touch". That is, it does not "bang" or "click" when contacting the end of the rail. Note the found value as *minimum_sensitivity*. -### Update printer.cfg with sensitivity value +#### Update printer.cfg with sensitivity value After finding *maximum_sensitivity* and *minimum_sensitivity*, use a calculator to obtain the recommend sensitivity as @@ -252,7 +254,7 @@ Note that if any change is made to driver current, homing speed, or a notable change is made to the printer hardware, then it will be necessary to run the tuning process again. -### Using Macros when Homing +#### Using Macros when Homing After sensorless homing completes the carriage will be pressed against the end of the rail and the stepper will exert a force on the frame @@ -301,7 +303,7 @@ or from a [START_PRINT macro](Slicers.md#klipper-gcode_macro). Note that if the driver current during homing is changed, then the tuning process should be run again. -## Tips for sensorless homing on CoreXY +### Tips for sensorless homing on CoreXY It is possible to use sensorless homing on the X and Y carriages of a CoreXY printer. Klipper uses the `[stepper_x]` stepper to detect @@ -323,7 +325,7 @@ restrictions: limit (which may skew the stall detection). The pause is necessary to ensure the driver's stall flag is cleared prior to homing again. -# Querying and diagnosing driver settings +## Querying and diagnosing driver settings The `[DUMP_TMC command](G-Codes.md#tmc-stepper-drivers) is a useful tool when configuring and diagnosing the drivers. It will report all @@ -336,7 +338,7 @@ each driver. These datasheets can be found on the Trinamic datasheet for the driver to interpret the results of DUMP_TMC. -# Configuring driver_XXX settings +## Configuring driver_XXX settings Klipper supports configuring many low-level driver fields using `driver_XXX` settings. The @@ -359,9 +361,9 @@ states that a value of 3 must be written to the HEND field to obtain a "hysteresis end" of 0, then set `driver_HEND=3` to obtain the high-level value of 0. -# Common Questions +## Common Questions -## Can I use stealthchop mode on an extruder with pressure advance? +### Can I use stealthchop mode on an extruder with pressure advance? Many people successfully use "stealthchop" mode with Klipper's pressure advance. Klipper implements @@ -372,7 +374,7 @@ However, "stealthchop" mode may produce lower motor torque and/or produce higher motor heat. It may or may not be an adequate mode for your particular printer. -## I keep getting "Unable to read tmc uart 'stepper_x' register IFCNT" errors? +### I keep getting "Unable to read tmc uart 'stepper_x' register IFCNT" errors? This occurs when Klipper is unable to communicate with a tmc2208 or tmc2209 driver. @@ -390,7 +392,7 @@ power plugs). Otherwise, this error is typically the result of incorrect UART pin wiring or an incorrect Klipper configuration of the UART pin settings. -## I keep getting "Unable to write tmc spi 'stepper_x' register ..." errors? +### I keep getting "Unable to write tmc spi 'stepper_x' register ..." errors? This occurs when Klipper is unable to communicate with a tmc2130 or tmc5160 driver. @@ -415,7 +417,7 @@ attempt to use the SPI bus). The board's schematic is often a useful reference for finding which devices are on an SPI bus and their associated pins. -## Why did I get a "TMC reports error: ..." error? +### Why did I get a "TMC reports error: ..." error? This type of error indicates the TMC driver detected a problem and has disabled itself. That is, the driver stopped holding its position and @@ -460,7 +462,7 @@ 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. -## How do I tune spreadcycle/coolstep/etc. mode on my drivers? +### How do I tune spreadcycle/coolstep/etc. mode on my drivers? The [Trinamic website](https://www.trinamic.com/) has guides on configuring the drivers. These guides are often technical, low-level, diff --git a/docs/TSL1401CL_Filament_Width_Sensor.md b/docs/TSL1401CL_Filament_Width_Sensor.md index 98f7ff24..f465bdaf 100644 --- a/docs/TSL1401CL_Filament_Width_Sensor.md +++ b/docs/TSL1401CL_Filament_Width_Sensor.md @@ -1,3 +1,5 @@ +# TSL1401CL filament width sensor + 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.com](https://www.thingiverse.com/search?q=filament%20width%20sensor) ## How does it work? diff --git a/docs/Using_PWM_Tools.md b/docs/Using_PWM_Tools.md index 3947e183..351168ea 100644 --- a/docs/Using_PWM_Tools.md +++ b/docs/Using_PWM_Tools.md @@ -1,3 +1,5 @@ +# Using PWM tools + This document describes how to setup a PWM-controlled laser or spindle using `output_pin` and some macros. diff --git a/docs/beaglebone.md b/docs/beaglebone.md index 3c6c8e0c..322db01e 100644 --- a/docs/beaglebone.md +++ b/docs/beaglebone.md @@ -1,8 +1,10 @@ +# Beaglebone + This document describes the process of running Klipper on a Beaglebone PRU. Building an OS image -==================== +-------------------- Start by installing the [Debian 9.9 2019-08-03 4GB SD IoT](https://beagleboard.org/latest-images) @@ -19,7 +21,7 @@ git clone https://github.com/KevinOConnor/klipper ``` Install Octoprint -================= +----------------- One may then install Octoprint: ``` @@ -55,7 +57,7 @@ Make sure the octoprint web server is accessible - it should be at: [http://beaglebone:5000/](http://beaglebone:5000/) Building the micro-controller code -================================== +---------------------------------- To compile the Klipper micro-controller code, start by configuring it for the "Beaglebone PRU": @@ -86,14 +88,14 @@ sudo service klipper start ``` Remaining configuration -======================= +----------------------- Complete the installation by configuring Klipper and Octoprint following the instructions in [the main installation document](Installation.md#configuring-klipper). Printing on the Beaglebone -========================== +-------------------------- Unfortunately, the Beaglebone processor can sometimes struggle to run OctoPrint well. Print stalls have been known to occur on complex diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..4e221914 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,18 @@ +--- +hide: + - navigation + - toc +title: Welcome +--- + +![](img/klipper-logo.png){ .center-image } + +Klipper is a 3d-Printer firmware. It combines the power of a general +purpose computer with one or more micro-controllers. See the +[features](Features.md) document for more information on why you +should use Klipper. + +To begin using Klipper start by [installing](Installation.md) it. + +Klipper is Free Software. Read the [documentation](Overview.md) or +view [the Klipper code on github](https://github.com/KevinOConnor/klipper). diff --git a/docs/skew_correction.md b/docs/skew_correction.md index a787c9ed..ed022f62 100644 --- a/docs/skew_correction.md +++ b/docs/skew_correction.md @@ -1,10 +1,12 @@ +# Skew correction + Software based skew correction can help resolve dimensional inaccuracies resulting from a printer assembly that is not perfectly square. Note that if your printer is significantly skewed it is strongly recommended to first use mechanical means to get your printer as square as possible prior to applying software based correction. -# Print a Calibration Object +## Print a Calibration Object The first step in correcting skew is to print a [calibration object](https://www.thingiverse.com/thing:2563185/files) along the plane you want to correct. There is also a @@ -16,7 +18,7 @@ Make sure that no skew correction is applied during this print. You may do this by either removing the [skew_correction] module from printer.cfg or by issuing a `SET_SKEW CLEAR=1` gcode. -# Take your measurements +## Take your measurements The [skew_correcton] module requires 3 measurements for each plane you want to correct; the length from Corner A to Corner C, the length from Corner B to Corner D, and the length from corner A to corner D. When measuring length @@ -24,7 +26,7 @@ AD do not include the flats on the corners that some test objects provide. ![skew_lengths](img/skew_lengths.png) -# Configure your skew +## Configure your skew 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: @@ -69,7 +71,7 @@ SKEW_PROFILE REMOVE=my_skew_profile After removing a profile you will be prompted to issue a `SAVE_CONFIG` to make this change persist. -# Verifying your correction +## Verifying your correction 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 @@ -79,7 +81,7 @@ skew on each plane. The results should be lower than those reported via CALC_MEASURED_SKEW AC= BD= AD= ``` -# Caveats +## Caveats 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