docs: Updates to Installation.md documentwork-install-20220510

Recommend users obtain an example config file prior to starting the
installation.

Signed-off-by: Kevin O'Connor <kevin@koconnor.net>

1 files changed, 79 insertions, 44 deletions

diff --git a/docs/Installation.md b/docs/Installation.md
index a8f5373d0..5e97436fe 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.