From 95676343db8c040e840eabeff88f819d1c02f4a3 Mon Sep 17 00:00:00 2001 From: Kevin O'Connor Date: Tue, 10 May 2022 09:36:03 -0400 Subject: [PATCH] docs: Updates to Installation.md document Recommend users obtain an example config file prior to starting the installation. Signed-off-by: Kevin O'Connor --- docs/Installation.md | 123 +++++++++++++++++++++++++++---------------- 1 file changed, 79 insertions(+), 44 deletions(-) diff --git a/docs/Installation.md b/docs/Installation.md index a8f5373d..5e97436f 100644 --- a/docs/Installation.md +++ b/docs/Installation.md @@ -6,10 +6,34 @@ Raspberry Pi 2, 3, or 4 computer be used as the host machine (see the [FAQ](FAQ.md#can-i-run-klipper-on-something-other-than-a-raspberry-pi-3) for other machines). -Klipper currently supports a number of Atmel ATmega based -micro-controllers, -[ARM based micro-controllers](Features.md#step-benchmarks), and -[Beaglebone PRU](Beaglebone.md) based printers. +## Obtain a Klipper Configuration File + +Most Klipper settings are determined by a "printer configuration file" +that will be stored on the Raspberry Pi. An appropriate configuration +file can often be found by looking in the Klipper +[config directory](../config/) for a file starting with a "printer-" +prefix that corresponds to the target printer. The Klipper +configuration file contains technical information about the printer +that will be needed during the installation. + +If there isn't an appropriate printer configuration file in the +Klipper config directory then try searching the printer manufacturer's +website to see if they have an appropriate Klipper configuration file. + +If no configuration file for the printer can be found, but the type of +printer control board is known, then look for an appropriate +[config file](../config/) starting with a "generic-" prefix. These +example printer board files should allow one to successfully complete +the initial installation, but will require some customization to +obtain full printer functionality. + +It is also possible to define a new printer configuration from +scratch. However, this requires significant technical knowledge about +the printer and its electronics. It is recommended that most users +start with an appropriate configuration file. If creating a new custom +printer configuration file, then start with the closest example +[config file](../config/) and use the Klipper +[config reference](Config_Reference.md) for further information. ## Prepping an OS image @@ -49,16 +73,27 @@ cd ~/klipper/ make menuconfig ``` -Select the appropriate micro-controller and review any other options -provided. Once configured, run: +The comments at the top of the +[printer configuration file](#obtain-a-klipper-configuration-file) +should describe the settings that need to be set during "make +menuconfig". Open the file in a web browser or text editor and look +for these instructions near the top of the file. Once the appropriate +"menuconfig" settings have been configured, press "Q" to exit, and +then "Y" to save. Then run: ``` make ``` -It is necessary to determine the serial port connected to the -micro-controller. For micro-controllers that connect via USB, run the -following: +If the comments at the top of the +[printer configuration file](#obtain-a-klipper-configuration-file) +describe custom steps for "flashing" the final image to the printer +control board then follow those steps and then proceed to +[configuring OctoPrint](#configuring-octoprint-to-use-klipper). + +Otherwise, the following steps are often used to "flash" the printer +control board. First, it is necessary to determine the serial port +connected to the micro-controller. Run the following: ``` ls /dev/serial/by-id/* @@ -122,36 +157,43 @@ Klipper. Proceed to the next section. ## 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 -[config directory](../config/). The -[Config Reference](Config_Reference.md) contains documentation on -config parameters. +The next step is to copy the +[printer configuration file](#obtain-a-klipper-configuration-file) to +the Raspberry Pi. -Arguably the easiest way to update the Klipper configuration file is -to use a desktop editor that supports editing files over the "scp" -and/or "sftp" protocols. There are freely available tools that support -this (eg, Notepad++, WinSCP, and Cyberduck). Use one of the example -config files as a starting point and save it as a file named -"printer.cfg" in the home directory of the pi user (ie, -/home/pi/printer.cfg). +Arguably the easiest way to set the Klipper configuration file is to +use a desktop editor that supports editing files over the "scp" and/or +"sftp" protocols. There are freely available tools that support this +(eg, Notepad++, WinSCP, and Cyberduck). Load the printer config file +in the editor and then save it as a file named "printer.cfg" in the +home directory of the pi user (ie, /home/pi/printer.cfg). Alternatively, one can also copy and edit the file directly on the -Raspberry Pi via ssh - for example: +Raspberry Pi via ssh. That may look something like the following (be +sure to update the command to use the appropriate printer config +filename): ``` cp ~/klipper/config/example-cartesian.cfg ~/printer.cfg nano ~/printer.cfg ``` -Make sure to review and update each setting that is appropriate for -the hardware. - It's common for each printer to have its own unique name for the micro-controller. The name may change after flashing Klipper, so rerun -the `ls /dev/serial/by-id/*` command and then update the config file -with the unique name. For example, update the `[mcu]` section to look -something similar to: +these steps again even if they were already done when flashing. Run: + +``` +ls /dev/serial/by-id/* +``` + +It should report something similar to the following: + +``` +/dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 +``` + +Then update the config file with the unique name. For example, update +the `[mcu]` section to look something similar to: ``` [mcu] @@ -162,26 +204,19 @@ After creating and editing the file it will be necessary to issue a "restart" command in the OctoPrint web terminal to load the config. A "status" command will report the printer is ready if the Klipper config file is successfully read and the micro-controller is -successfully found and configured. It is not unusual to have -configuration errors during the initial setup - update the printer -config file and issue "restart" until "status" reports the printer is -ready. +successfully found and configured. + +When customizing the printer config file, it is not uncommon for +Klipper to report a configuration error. If an error occurs, make any +necessary corrections to the printer config file and issue "restart" +until "status" reports the printer is ready. Klipper reports error messages via the OctoPrint terminal tab. The "status" command can be used to re-report error messages. The default Klipper startup script also places a log in **/tmp/klippy.log** which provides more detailed information. -In addition to common g-code commands, Klipper supports a few extended -commands - "status" and "restart" are examples of these commands. Use -the "help" command to get a list of other extended commands. - -After Klipper reports that the printer is ready go on to the +After Klipper reports that the printer is ready, proceed to the [config check document](Config_checks.md) to perform some basic checks -on the pin definitions in the config file. - -## 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 -developers. +on the definitions in the config file. See the main +[documentation reference](Overview.md) for other information.