diff options
| -rw-r--r-- | docs/Installation.md | 158 | ||||
| -rw-r--r-- | docs/OctoPrint.md | 79 | ||||
| -rw-r--r-- | docs/Overview.md | 1 | ||||
| -rw-r--r-- | docs/_klipper3d/mkdocs.yml | 4 |
4 files changed, 169 insertions, 73 deletions
diff --git a/docs/Installation.md b/docs/Installation.md index 004d963a..ca64259a 100644 --- a/docs/Installation.md +++ b/docs/Installation.md @@ -1,15 +1,20 @@ # 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 (or later) be used as the host machine (see the +These instructions assume the software will run on a linux based host +running a Klipper compatible front end. It is recommended that a +SBC(Small Board Computer) such as a Raspberry Pi or Debian based Linux +device be used as the host machine (see the [FAQ](FAQ.md#can-i-run-klipper-on-something-other-than-a-raspberry-pi-3) -for other machines). +for other options). + +For the purposes of these instructions host relates to the Linux device and +mcu relates to the printboard. SBC relates to the term Small Board Computer +such as the Raspberry Pi. ## 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 +printer.cfg, that will be stored on the host. 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 @@ -35,38 +40,51 @@ 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 +## Interacting with Klipper -Start by installing [OctoPi](https://github.com/guysoft/OctoPi) on the -Raspberry Pi computer. Use OctoPi v0.17.0 or later - see the -[OctoPi releases](https://github.com/guysoft/OctoPi/releases) for -release information. One should verify that OctoPi boots and that the -OctoPrint web server works. After connecting to the OctoPrint web -page, follow the prompt to upgrade OctoPrint to v1.4.2 or later. +Klipper is a 3d printer firmware, so it needs some way for the user to +interact with it. -After installing OctoPi and upgrading OctoPrint, it will be necessary -to ssh into the target machine to run a handful of system commands. If -using a Linux or MacOS desktop, then the "ssh" software should already -be installed on the desktop. There are free ssh clients available for -other desktops (eg, -[PuTTY](https://www.chiark.greenend.org.uk/~sgtatham/putty/)). Use the -ssh utility to connect to the Raspberry Pi (`ssh pi@octopi` -- password -is "raspberry") and run the following commands: +Currently the best choices are front ends that retrieve information through +the [Moonraker web API](https://moonraker.readthedocs.io/) and there is also +the option to use [Octoprint](https://octoprint.org/) to control Klipper. -``` -git clone https://github.com/Klipper3d/klipper -./klipper/scripts/install-octopi.sh -``` +The choice is up to the user on what to use, but the underlying Klipper is the +same in all cases. We encourage users to research the options available and +make an informed decision. + +## Obtaining an OS image for SBC's + +There are many ways to obtain an OS image for Klipper for SBC use, most depend on +what front end you wish to use. Some manafactures of these SBC boards also provide +their own Klipper-centric images. + +The two main Moonraker based front ends are [Fluidd](https://docs.fluidd.xyz/) +and [Mainsail](https://docs.mainsail.xyz/), the latter of which has a premade install +image ["MainsailOS"](http://docs.mainsailOS.xyz), this has the option for Raspberry Pi +and some OrangePi varianta. -The above will download Klipper, install some system dependencies, -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. +Fluidd can be installed via KIAUH(Klipper Install And Update Helper), which +is explained below and is a 3rd party installer for all things Klipper. + +OctoPrint can be installed via the popular OctoPi image or via KIAUH, this +process is explained in [OctoPrint.md](OctoPrint.md) + +## Installing via KIAUH + +Normally you would start with a base image for your SBC, RPiOS Lite for example, +or in the case of a x86 Linux device, Ubuntu Server. Please note that Desktop +variants are not recommended due to certain helper programs that can stop some +Klipper functions working and even mask access to some print boards. + +KIAUH can be used to install Klipper and its associated programs on a variety +of Linux based systems that run a form of Debian. More information can be found +at https://github.com/dw-0/kiauh ## Building and flashing the micro-controller To compile the micro-controller code, start by running these commands -on the Raspberry Pi: +on your host device: ``` cd ~/klipper/ @@ -108,10 +126,21 @@ It should report something similar to the following: It's common for each printer to have its own unique serial port name. This unique name will be used when flashing the micro-controller. It's possible there may be multiple lines in the above output - if so, -choose the line corresponding to the micro-controller (see the +choose the line corresponding to the micro-controller. If many +items are listed and the choice is ambiguous, unplug the board and +run the command again, the missing item will be your print board(see the [FAQ](FAQ.md#wheres-my-serial-port) for more information). -For common micro-controllers, the code can be flashed with something +For common micro-controllers with STM32 or clone chips, LPC chips and +others it is usual that these need an initial Klipper flash via SD card. + +When flashing with this method, it is important to make sure that the +print board is not connected with USB to the host, due to some boards +being able to feed power back to the board and stopping a flash from +occuring. + +For common micro-controllers using Atmega chips, for example the 2560, +the code can be flashed with something similar to: ``` @@ -123,53 +152,38 @@ sudo service klipper start Be sure to update the FLASH_DEVICE with the printer's unique serial port name. -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 - -The OctoPrint web server needs to be configured to communicate with -the Klipper host software. Using a web browser, login to the OctoPrint -web page and then configure the following items: - -Navigate to the Settings tab (the wrench icon at the top of the -page). Under "Serial Connection" in "Additional serial ports" add -`/tmp/printer`. Then click "Save". - -Enter the Settings tab again and under "Serial Connection" change the -"Serial Port" setting to `/tmp/printer`. +For common micro-controllers using RP2040 chips, the code can be flashed +with something similar to: -In the Settings tab, navigate to the "Behavior" sub-tab and select the -"Cancel any ongoing prints but stay connected to the printer" -option. Click "Save". +``` +sudo service klipper stop +make flash FLASH_DEVICE=first +sudo service klipper start +``` -From the main page, under the "Connection" section (at the top left of -the page) make sure the "Serial Port" is set to `/tmp/printer` and -click "Connect". (If `/tmp/printer` is not an available selection then -try reloading the page.) +It is important to note that RP2040 chips may need to be put into Boot mode +before this operation. -Once connected, navigate to the "Terminal" tab and type "status" -(without the quotes) into the command entry box and click "Send". The -terminal window will likely report there is an error opening the -config file - that means OctoPrint is successfully communicating with -Klipper. Proceed to the next section. ## Configuring Klipper The next step is to copy the [printer configuration file](#obtain-a-klipper-configuration-file) to -the Raspberry Pi. +the host. + +Arguably the easiest way to set the Klipper configuration file is using the +built in editors in Mainsail or Fluidd. These will allow the user to open +the configuration examples and save them to be printer.cfg. -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`). +Another option is to use a desktop editor that supports editing files +over the "scp" and/or "sftp" protocols. There are freely available tools +that support this (eg, Notepad++, WinSCP, and Cyberduck). +Load the printer config file in the editor and then save it as a file +named "printer.cfg" in the home directory of the pi user +(ie, /home/pi/printer.cfg). Alternatively, one can also copy and edit the file directly on the -Raspberry Pi via ssh. That may look something like the following (be +host via ssh. That may look something like the following (be sure to update the command to use the appropriate printer config filename): @@ -201,7 +215,7 @@ serial: /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 ``` 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 +"restart" command in the command console 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. @@ -211,10 +225,10 @@ 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. +Klipper reports error messages via the command console and via pop up in +Fluidd and Mainsail. The "status" command can be used to re-report error +messages. A log is available and usually located in ~/printer_data/logs +this is named klippy.log After Klipper reports that the printer is ready, proceed to the [config check document](Config_checks.md) to perform some basic checks diff --git a/docs/OctoPrint.md b/docs/OctoPrint.md new file mode 100644 index 00000000..4fa1b021 --- /dev/null +++ b/docs/OctoPrint.md @@ -0,0 +1,79 @@ +# OctoPrint for Klipper + +Klipper has a few options for its front ends, Octoprint was the first +and original front end for Klipper. This document will give +a brief overview of installing with this option. + +## Install with OctoPi + +Start by installing [OctoPi](https://github.com/guysoft/OctoPi) on the +Raspberry Pi computer. Use OctoPi v0.17.0 or later - see the +[OctoPi releases](https://github.com/guysoft/OctoPi/releases) for +release information. + +One should verify that OctoPi boots and that the +OctoPrint web server works. After connecting to the OctoPrint web +page, follow the prompt to upgrade OctoPrint if needed. + +After installing OctoPi and upgrading OctoPrint, it will be necessary +to ssh into the target machine to run a handful of system commands. + +Start by running these commands on your host device: + +__If you do not have git installed, please do so with:__ +``` +sudo apt install git +``` +then proceed: +``` +cd ~ +git clone https://github.com/Klipper3d/klipper +./klipper/scripts/install-octopi.sh +``` + +The above will download Klipper, install the needed system dependencies, +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. + +## Installing with KIAUH + +KIAUH can be used to install OctoPrint on a variety of Linux based systems +that run a form of Debian. More information can be found +at https://github.com/dw-0/kiauh + +## 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 web page and then +configure the following items: + +Navigate to the Settings tab (the wrench icon at the top of the page). +Under "Serial Connection" in "Additional serial ports" add: + +``` +~/printer_data/comms/klippy.sock +``` +Then click "Save". + +_In some older setups this address may be `/tmp/printer`_ + + +Enter the Settings tab again and under "Serial Connection" change the "Serial Port" +setting to the one added above. + +In the Settings tab, navigate to the "Behavior" sub-tab and select the +"Cancel any ongoing prints but stay connected to the printer" option. Click "Save". + +From the main page, under the "Connection" section (at the top left of the page) +make sure the "Serial Port" is set to the new additional one added +and click "Connect". (If it is not in the available selection then +try reloading the page.) + +Once connected, navigate to the "Terminal" tab and type "status" (without the quotes) +into the command entry box and click "Send". The terminal window will likely report +there is an error opening the config file - that means OctoPrint is successfully +communicating with Klipper. + +Please proceed to [Installation.md](Installation.md) and the +_Building and flashing the micro-controller_ section diff --git a/docs/Overview.md b/docs/Overview.md index 2b9253c2..1ab94891 100644 --- a/docs/Overview.md +++ b/docs/Overview.md @@ -17,6 +17,7 @@ communication with the Klipper developers. ## Installation and Configuration - [Installation](Installation.md): Guide to installing Klipper. + - [Octoprint](OctoPrint.md): Guide to installing Octoprint with Klipper. - [Config Reference](Config_Reference.md): Description of config parameters. - [Rotation Distance](Rotation_Distance.md): Calculating the diff --git a/docs/_klipper3d/mkdocs.yml b/docs/_klipper3d/mkdocs.yml index 4bfdd169..02d32fad 100644 --- a/docs/_klipper3d/mkdocs.yml +++ b/docs/_klipper3d/mkdocs.yml @@ -88,7 +88,9 @@ nav: - Config_Changes.md - Contact.md - Installation and Configuration: - - Installation.md + - Installation: + - Installation.md + - OctoPrint.md - Configuration Reference: - Config_Reference.md - Rotation_Distance.md |