3diy
/
klipper
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs : make modifications to all md files to make them compatible with mkdocs 

all markdown files must have a single H1 heading at the top.

Signed-off-by: Damien Martin <damlobster@gmail.com>

Update CNAME
This commit is contained in:
Damien 2021-07-22 00:40:40 +02:00 committed by KevinOConnor
parent 7e88f9220c
commit cff61605fb
44 changed files with 565 additions and 536 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
docs/API_Server.md
View File

@ -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
`<module_name>/<some_name>`. When making a request to an "endpoint",

18
docs/BLTouch.md
View File

@ -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

8
docs/Bed_Level.md
View File

@ -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",

2
docs/Bed_Mesh.md
View File

@ -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

8
docs/Benchmarks.md
View File

@ -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

42
docs/Bootloaders.md
View File

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

12
docs/CANBUS.md
View File

@ -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:

14
docs/CANBUS_protocol.md
View File

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

20
docs/Code_Overview.md
View File

@ -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

26
docs/Command_Templates.md
View File

@ -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
<!-- {% raw %} -->
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:
```
<!-- {% endraw %} -->
### 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 `<force>` is set True then it will also stop editing. Default
value is False.
### Save Variables to disk
## Save Variables to disk
<!-- {% raw %} -->
If a

4
docs/Config_Changes.md
View File

@ -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

248
docs/Config_Reference.md
View File

@ -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_<name>:
# 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.

20
docs/Config_checks.md
View File

@ -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

16
docs/Contact.md
View File

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

25
docs/Debugging.md
View File

@ -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

17
docs/Delta_Calibrate.md
View File

@ -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

8
docs/Endstop_Phase.md
View File

@ -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

4
docs/Example_Configs.md
View File

@ -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

51
docs/FAQ.md
View File

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

8
docs/Features.md
View File

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

80
docs/G-Codes.md
View File

@ -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<pos>] [Y<pos>] [Z<pos>] [E<pos>] [F<speed>]`
@ -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=<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<pos>] [Y<pos>] [Z<pos>]
[E<pos>] [F<speed>] I<value> J<value>`
## 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 <message>`
- Set build percentage: `M73 P<percent>`
## 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=<speed>` This command sets
the speed of a fan. <speed> 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=<output_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 `<prefix>`. (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
<register> 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)

2
docs/HallFilamentWidthSensor.md
View File

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

17
docs/Installation.md
View File

@ -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

29
docs/Kinematics.md
View File

@ -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

20
docs/MCU_Commands.md
View File

@ -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'

10
docs/Manual_Level.md
View File

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

30
docs/Measuring_Resonances.md
View File

@ -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,

10
docs/Overview.md
View File

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

8
docs/Pressure_Advance.md
View File

@ -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

12
docs/Probe_Calibrate.md
View File

@ -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

38
docs/Protocol.md
View File

@ -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

27
docs/RPi_microcontroller.md
View File

@ -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```:

29
docs/Releases.md
View File

@ -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:

26
docs/Resonance_Compensation.md
View File

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

16
docs/Rotation_Distance.md
View File

@ -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 = <belt_pitch> * <number_of_teeth_on_pulley>
For example, if a printer has a 2mm belt and uses a pulley with 20
teeth, then the rotation distance is 40.
## Axes with a lead screw
### 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)

14
docs/SDCard_Updates.md
View File

@ -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

16
docs/Slicers.md
View File

@ -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

68
docs/Status_Reference.md
View File

@ -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:
- `<variable>`: 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_name>`: 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 <config_name>"].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

40
docs/TMC_Drivers.md
View File

@ -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,

2
docs/TSL1401CL_Filament_Width_Sensor.md
View File

@ -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?

2
docs/Using_PWM_Tools.md
View File

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

12
docs/beaglebone.md
View File

@ -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

18
docs/index.md Normal file
View File

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

12
docs/skew_correction.md
View File

@ -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=<ac_length> BD=<bd_length> AD=<ad_length>
```
# 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