diff --git a/docs/_config.yml b/docs/_config.yml index bfd9dd91a..44e541c4b 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -11,7 +11,6 @@ aux_links: - "//github.com/meteyou/mainsail" aux_links_new_tab: true - defaults: - scope: diff --git a/docs/assets/img/setup/balena-etcher-boot-partition.png b/docs/assets/img/setup/balena-etcher-boot-partition.png new file mode 100644 index 000000000..007a89816 Binary files /dev/null and b/docs/assets/img/setup/balena-etcher-boot-partition.png differ diff --git a/docs/assets/img/setup/balena-etcher-finished.png b/docs/assets/img/setup/balena-etcher-finished.png new file mode 100644 index 000000000..f0d12b126 Binary files /dev/null and b/docs/assets/img/setup/balena-etcher-finished.png differ diff --git a/docs/assets/img/setup/balena-etcher-flash.png b/docs/assets/img/setup/balena-etcher-flash.png new file mode 100644 index 000000000..05e888a77 Binary files /dev/null and b/docs/assets/img/setup/balena-etcher-flash.png differ diff --git a/docs/assets/img/setup/balena-etcher-validating.png b/docs/assets/img/setup/balena-etcher-validating.png new file mode 100644 index 000000000..566f9f873 Binary files /dev/null and b/docs/assets/img/setup/balena-etcher-validating.png differ diff --git a/docs/assets/img/setup/balena-flashing.png b/docs/assets/img/setup/balena-flashing.png new file mode 100644 index 000000000..806c9173b Binary files /dev/null and b/docs/assets/img/setup/balena-flashing.png differ diff --git a/docs/assets/img/setup/balena-main-screen.png b/docs/assets/img/setup/balena-main-screen.png new file mode 100644 index 000000000..df66ba6a9 Binary files /dev/null and b/docs/assets/img/setup/balena-main-screen.png differ diff --git a/docs/assets/img/setup/balena-select-os.png b/docs/assets/img/setup/balena-select-os.png new file mode 100644 index 000000000..e09aad7e9 Binary files /dev/null and b/docs/assets/img/setup/balena-select-os.png differ diff --git a/docs/assets/img/setup/balena-select-sd-card-choice.png b/docs/assets/img/setup/balena-select-sd-card-choice.png new file mode 100644 index 000000000..3c446d01d Binary files /dev/null and b/docs/assets/img/setup/balena-select-sd-card-choice.png differ diff --git a/docs/assets/img/setup/balena-select-sd-card.png b/docs/assets/img/setup/balena-select-sd-card.png new file mode 100644 index 000000000..52161525d Binary files /dev/null and b/docs/assets/img/setup/balena-select-sd-card.png differ diff --git a/docs/assets/img/setup/balena-unzipping.png b/docs/assets/img/setup/balena-unzipping.png new file mode 100644 index 000000000..1449e3ea5 Binary files /dev/null and b/docs/assets/img/setup/balena-unzipping.png differ diff --git a/docs/assets/img/setup/screenshot-printercfg-include-mainsail.png b/docs/assets/img/setup/screenshot-printercfg-include-mainsail.png new file mode 100644 index 000000000..4993b9539 Binary files /dev/null and b/docs/assets/img/setup/screenshot-printercfg-include-mainsail.png differ diff --git a/docs/assets/img/setup/screenshot-web-editor-printer.png b/docs/assets/img/setup/screenshot-web-editor-printer.png new file mode 100644 index 000000000..ef4e9da8f Binary files /dev/null and b/docs/assets/img/setup/screenshot-web-editor-printer.png differ diff --git a/docs/assets/img/update/screenshot-update-manager-button-rounded.png b/docs/assets/img/update/screenshot-update-manager-button-rounded.png new file mode 100644 index 000000000..08818cedf Binary files /dev/null and b/docs/assets/img/update/screenshot-update-manager-button-rounded.png differ diff --git a/docs/assets/img/update/screenshot-update-manager-button.png b/docs/assets/img/update/screenshot-update-manager-button.png new file mode 100644 index 000000000..08818cedf Binary files /dev/null and b/docs/assets/img/update/screenshot-update-manager-button.png differ diff --git a/docs/assets/img/update/screenshot-update-manager-example-not-up-to-date.png b/docs/assets/img/update/screenshot-update-manager-example-not-up-to-date.png new file mode 100644 index 000000000..09256b274 Binary files /dev/null and b/docs/assets/img/update/screenshot-update-manager-example-not-up-to-date.png differ diff --git a/docs/assets/img/update/screenshot-update-manager-example.png b/docs/assets/img/update/screenshot-update-manager-example.png new file mode 100644 index 000000000..0d0aff802 Binary files /dev/null and b/docs/assets/img/update/screenshot-update-manager-example.png differ diff --git a/docs/configurations/necessary-cfg.md b/docs/configurations/necessary-cfg.md new file mode 100644 index 000000000..a8ad0a886 --- /dev/null +++ b/docs/configurations/necessary-cfg.md @@ -0,0 +1,140 @@ +--- +layout: default +title: Configuration +nav_order: 5 +has_children: false +permalink: /configuration +--- + +# Required configuration + +**Mainsail requires a minimum configuration to function properly and will display a warning at startup if the required parts are not found in your configuration file(s).** +{: .warning} + +The following configuration elements are mandatory and must be configured for Mainsail to operate: + +* [Virtual SD Card](configuration#virtual_sdcard) +* [Display Status](configuration#display_status) +* [Pause / Resume](configuration#pause_resume) +* [GCode Macros](configuration#pause--resume--cancel) + +The following configuration elements are optional, including making tweaks and alterations to Klipper's default commands: +* [Custom Commands](configuration#customisation) + +## Virtual SD Card +This allows gcode file uploads. +```yaml +[virtual_sdcard] +path: ~/gcode_files +``` + +## Display Status +This is required for messages in your status panel, if you don't have a `[display]` in your configuration. +```yaml +[display_status] +``` + +## Pause, Resume, Cancel +This enables pause / resume in mainsail. + +```yaml +[pause_resume] +``` + +# Macros +## for pause / resume / cancel functionality +These should be modified to your own needs. +{% raw %} +```yaml +[gcode_macro PAUSE] +description: Pause the actual running print +rename_existing: PAUSE_BASE +gcode: + ##### set defaults ##### + {% set x = params.X|default(230) %} #edit to your park position + {% set y = params.Y|default(230) %} #edit to your park position + {% set z = params.Z|default(10)|float %} #edit to your park position + {% set e = params.E|default(1) %} #edit to your retract length + ##### calculate save lift position ##### + {% set max_z = printer.toolhead.axis_maximum.z|float %} + {% set act_z = printer.toolhead.position.z|float %} + {% set lift_z = z|abs %} + {% if act_z < (max_z - lift_z) %} + {% set z_safe = lift_z %} + {% else %} + {% set z_safe = max_z - act_z %} + {% endif %} + ##### end of definitions ##### + PAUSE_BASE + G91 + {% if printer.extruder.can_extrude|lower == 'true' %} + G1 E-{e} F2100 + {% else %} + {action_respond_info("Extruder not hot enough")} + {% endif %} + {% if "xyz" in printer.toolhead.homed_axes %} + G1 Z{z_safe} + G90 + G1 X{x} Y{y} F6000 + {% else %} + {action_respond_info("Printer not homed")} + {% endif %} +``` + +```yaml +[gcode_macro RESUME] +description: Resume the actual running print +rename_existing: RESUME_BASE +gcode: + ##### set defaults ##### + {% set e = params.E|default(1) %} #edit to your retract length + #### get VELOCITY parameter if specified #### + {% if 'VELOCITY' in params|upper %} + {% set get_params = ('VELOCITY=' + params.VELOCITY) %} + {%else %} + {% set get_params = "" %} + {% endif %} + ##### end of definitions ##### + G91 + {% if printer.extruder.can_extrude|lower == 'true' %} + G1 E{e} F2100 + {% else %} + {action_respond_info("Extruder not hot enough")} + {% endif %} + RESUME_BASE {get_params} +``` + + +```yaml +[gcode_macro CANCEL_PRINT] +description: Cancel the actual running print +rename_existing: CANCEL_PRINT_BASE +gcode: + TURN_OFF_HEATERS + CANCEL_PRINT_BASE +``` +{% endraw %} + +# Optional + +## Customisation +Klipper has many canned/preset commands that are themselves just macros. + +The default configuration of these may not suit your needs or preferences, (though they are usually a good place to start). It's possible to adjust these by including them in your config, along with whatever code you would like to run. + +## Example +Adjusting the `BED_MESH_CALIBRATE` command (which can be run from the Sidebar > Heightmap > Calibrate. +{% raw %} +```yaml +[gcode_macro BED_MESH_CALIBRATE] +rename_existing: BASE_BED_MESH_CALIBRATE +gcode: + #before the original gcode + BED_MESH_CLEAR + QUAD_GANTRY_LEVEL + G1 X125 Y125 Z5 F6000 + #the original gcode + BASE_BED_MESH_CALIBRATE + #after the original gcode +``` +{% endraw %} diff --git a/docs/credits.md b/docs/credits.md index e2c1d082b..98131b645 100644 --- a/docs/credits.md +++ b/docs/credits.md @@ -13,15 +13,15 @@ description: >- -We would like to say "thank you" to all the +We would like acknowledge the valuable contributions that many people and projects have made to Mainsail, particularly the: - contributors, who help make Mainsail better - testers, who help find bugs in Mainsail, so they can be quickly fixed - supporters via patreon/ko-fi -and of course the projects Mainsail is built on, especially [Klipper](https://github.com/KevinOConnor/klipper){:target="_blank"}, [Moonraker](https://github.com/Arksine/moonraker){:target="_blank"} and [MainsailOS](https://github.com/raymondh2/MainsailOS/){:target="_blank"}. +..and of course the projects Mainsail is built on, especially [Klipper](https://github.com/KevinOConnor/klipper){:target="_blank"}, [Moonraker](https://github.com/Arksine/moonraker){:target="_blank"} and [MainsailOS](https://github.com/raymondh2/MainsailOS/){:target="_blank"}. -**THANK YOU for YOUR support. ❤️** +**THANK YOU for your continued support.** - TOC {:toc} @@ -38,4 +38,4 @@ and of course the projects Mainsail is built on, especially [Klipper](https://gi | project | license | link | |:--------|:-------:|:-----| {% for deps in site.data.licenses %}| **{{ deps[0] }}**
{{ deps[1].description }} | [{{ deps[1].licenses }}]({{ deps[1].licenseUrl }}){:target="_blank"} | [{{ deps[1].repository }}]({{ deps[1].repository }}){:target="_blank"} | -{% endfor %} \ No newline at end of file +{% endfor %} diff --git a/docs/data-privacy.md b/docs/data-privacy.md new file mode 100644 index 000000000..ffd0d9070 --- /dev/null +++ b/docs/data-privacy.md @@ -0,0 +1,41 @@ +--- +layout: default +title: Data Privacy +nav_order: 99 +has_children: false +permalink: /data-privacy +has_toc: false +--- + +# Data Privacy + +We understand the need for data privacy and have designed Mainsail to operate in your browser’s cache locally. + +The following table applies to Mainsail when installed locallaly, or accessed via [my.mainsail.xyz](http://my.mainsail.xyz). + +| YES | NO | +| :--------------: | :---------------: | +| Store static files in browser storage (.html, .js, .css) | ‘Phone home’ | +| Communicate directly with your printer via the Moonraker API | Send/transfer any data externally | + +## Will my data be safe if I use the hosted version? +Accessing [my.mainsail.xyz](http://my.mainsail.xyz) stores the .html, .js and .css files for Mainsail locally in the brower's storage in exactly the same way that an instance running on your local hardware would do. In reality, there is no functional difference (or concern) between accessing Mainsail from a privately or publicly hosted instance. + + +Parallel operation is also possible. + +# Third party software + +We do not modify third party packages or software, nor control their attitude to Data Privacy. + +If you are concerned, please consider the privacy policies (or contacting the developer) of: + +* [RaspberryOS](https://www.raspberrypi.org/privacy/) +* Klipper +* Moonraker + + +It is worth noting that Klipper, Moonraker and RaspberryOS are open source software and ( whilst this brings no guarantee of privacy and security) the source is available and open to peer review. +{: .info} +The Raspberry Foundation is a registered charity in the United Kingdom, with extensive Privacy and Safeguarding policies. +{: .info} diff --git a/docs/index.md b/docs/index.md index 48960bc84..11efed03b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -6,7 +6,7 @@ has_children: false --- # Welcome to Mainsail! -Mainsail is a lightweight & responsive web interface for Klipper, the 3D printer firmware. It focuses especially on an intuitive and consistent interface. +Mainsail aims to make Klipper more accessible to end users through a lightweight, responsive web ui, centred around an intuitive and consistent design philsophy. {: .fs-5 } [Getting Started](/setup){: .btn .btn-primary } @@ -43,4 +43,4 @@ The project is primarily developed and maintained by meteyou. To keep the projec - [Ko-Fi (one-time)](https://ko-fi.com/mainsail){:target="_blank"} However, we would also like to ask you to support the regular contributors. -{: .info} \ No newline at end of file +{: .info} diff --git a/docs/setup-guide/index.md b/docs/setup-guide/index.md index 9650ec94c..9780821be 100644 --- a/docs/setup-guide/index.md +++ b/docs/setup-guide/index.md @@ -8,7 +8,8 @@ has_toc: false --- # Setup Guides -To get started, you first have to decide which route you want to follow for the installation. There are several ways to install Mainsail on a Raspberry Pi. +## Local installation +Decide which route you want to follow for the installation. There are several ways to install Mainsail on a Raspberry Pi: - [MainsailOS](mainsail-os.md) recommended A prebuilt image for your Raspberry Pi. Flash it and you are almost ready to go. @@ -17,17 +18,9 @@ To get started, you first have to decide which route you want to follow for the - [Manual Setup](manual-setup/index.md) The rocky road. If you want to know how everything is set up by hand, you will get all the information here. -## my.mainsail.xyz -In addition to these guides, there is [my.mainsail.xyz](http://my.mainsail.xyz){: target="_blank"}. The latest Mainsail version is always hosted there. This obviates the need to set up a web server for Mainsail on your hardware. +## Hosted -To use [my.mainsail.xyz](http://my.mainsail.xyz){: target="_blank"}, the following requirements must be met: -- Klipper must be installed. -- Moonraker must be installed. -- my.mainsail.xyz must be configured as a CORS domain in moonraker.conf. - -**MainsailOS & KIAUH already fulfill these requirements.** - -_Note_, only the static .html, .js and .css files are loaded into your browser storage. No further information is transferred to the server. The communication to your printer is then done locally directly between your browser and your Moonraker installation. -If you have any concerns, you can of course still install Mainsail on your hardware locally. Parallel operation is also possible. +Setup [remote access](../quicktips/remote-access) without installing/configuring a web server! {: .info} +A hosted instance of Mainsail can be found and used at [my.mainsail.xyz](http://my.mainsail.xyz), check out the [documentation](mainsail-hosted) for usage and configuration. diff --git a/docs/setup-guide/mainsail-hosted.md b/docs/setup-guide/mainsail-hosted.md new file mode 100644 index 000000000..beaa5cfae --- /dev/null +++ b/docs/setup-guide/mainsail-hosted.md @@ -0,0 +1,51 @@ +--- +layout: default +title: my.mainsail.xyz +parent: Setup Guides +nav_order: 4 +has_children: false +has_toc: false +permalink: /setup/mainsail-hosted +--- + +# my.mainsail.xyz + +Mainsail and MainsailOS respect [Data Privacy](../data-privacy). +{: .info} + +The hosted version of mainsail can be used: + +* On the same (local) network as your printer. +* On a remote (different) network to your printer (requires the configuration of [remote access](../quicktips/remote-access)). + +## Requirements + +- MainsailOS and KIAUH are preconfigured to meet the requirements for the hosted service to work. +- If you have a manual installation, then the following requirements must be met: + * Klipper must be installed. + * Moonraker must be installed. + * my.mainsail.xyz must be configured as a CORS domain in moonraker.conf. + +## Editing moonraker.conf + +Further information can be found in the Moonraker [documentation](https://moonraker.readthedocs.io/en/latest/configuration/#authorization) +{: .info} + +To allow [my.mainsail.xyz](http://my.mainsail.xyz) to access your local installation, navigate to moonraker.conf open it and add the following code: + +```yml +[authorization] +cors_domains: + https://my.mainsail.xyz + http://my.mainsail.xyz + http://*.local +trusted_clients: + 10.0.0.0/8 + 127.0.0.0/8 + 169.254.0.0/16 + 172.16.0.0/12 + 192.168.0.0/16 + FE80::/10 + ::1/128 + +``` diff --git a/docs/setup-guide/mainsail-os.md b/docs/setup-guide/mainsail-os.md index 8ce9e3858..39804e2fd 100644 --- a/docs/setup-guide/mainsail-os.md +++ b/docs/setup-guide/mainsail-os.md @@ -3,100 +3,20 @@ layout: default title: MainsailOS parent: Setup Guides nav_order: 1 -has_children: false +has_children: true +has_toc: false permalink: /setup/mainsail-os --- -# Installing Mainsail with MainsailOS +# Installing MainsailOS -Our recommended way to install Mainsail on a Raspberry Pi is to use [MainsailOS](https://github.com/raymondh2/MainsailOS), -as pre-packaged disk image. If you are building a custom configuration, you may need to skip -these instructions and install Mainsail [manually](manual-setup/index.md). +MainsailOS builds upon RaspberryOS-Lite by incorporating Klipper, Moonraker and Mainsail into one disc image, making them more accessible and quicker to setup than before. -**Note: To avoid confusion, the described way is available for Windows, Linux and MacOS because RPI Imager is a Multiplatform Tool!** -{: .info} +Complex/custom configurations may be better suited to a [manual](manual-setup/index.md) installation of Mainsail. -_Note: It is a good idea to use a premium SDcard from a reputable manufacturer such as Sandisk, Kingston or Samsung. Perfomancewise you should consider using a "A1" or better, marked SDCard. Low end cards will often fail quickly when used in this application -**PLEASE OBEY THAT THIS WILL DESTROY ALL DATA ON YOUR CARD**_ -{: .alert} +If you are familiar with the flashing process, then please use your preferred method as you normally would. -1. Download the latest [mainsailOS Release](https://github.com/raymondh2/MainsailOS/releases). -2. Download the latest [Raspberry Pi Imager](https://www.raspberrypi.org/software/), henceforth rpi-imager. -3. Install and Open rpi-imager. Now you should see a Window like this. +If however you are unfamiliar with the flashing process then we have documented two methods to flash MainsailOS to your SD card: - ![](../assets/img/setup/rpi-imager-launched.png) - - _Window Appereance depends on OS, in this case Linux with XFCE was used._ - {: .info} - -4. Now click on "CHOOSE OS", this will open a popup as shown below. -Click on "Use Custom" - - ![](../assets/img/setup/rpi-os-popup.png) - - This will open a Popup Window to browse your local files. Please navigate to your recently downloaded MainsailOS Zip Archive - - _**DO NOT UNPACK THE ZIP FILE!**_ - {: .alert} - - After you've done that, it should look like this - - ![](../assets/img/setup/rpi-choosen-os.png) - -5. Click on "Storage" and select your desired SDCard. - - ![](../assets/img/setup/rpi-sdcard.png) - _As an Example..._ - -6. Now it's time to setup things like Hostname, Wifi, Language and more. -It depends on your needs what you setup, but it has to be WIFI and SSH at least! -Grab your keyboard and hit: - - - CTRL+SHIFT+X - - This opens up a Setup Page - - ![](../assets/img/setup/rpi-setup-1.png) - - ![](../assets/img/setup/rpi-setup-2.png) - -7. As the last Step click on "Write", rpi-imager will give you a Warning. Click "YES" to continue... - - ![](../assets/img/setup/rpi-warning.png) - -8. Watch the Progressbar and wait until you see: - - ![](../assets/img/setup/rpi-finished.png) - Hit the "Continue" Button and safely remove your SDCard. ( eg. unmount on Linux ) - -9. Insert the SDcard into your Pi, and power on the Pi. - - _Note: Please give the PI some time, during the first boot MainsailOS (like every PI Image) will expand your "root" filesystem accordingly to your SDCard Size! The greater your SDCard is, it will take longer time! Watch out for the little green LED if it turn off or blink from time to time it has finished the resizing._ - {: .warning} - _**Make sure that your MCU(s) is connected to your pi, If you will be using wired networking, also make sure your ethernet cable is connected.**_ - {: .alert} - - -10. Find your pi on the network, open up your preferred Browser and type either your IP or Hostname (Depends on your Network configuration) - -- If your network supports bonjour, the pi should show up as `mainsailos.local` or the given Hostname in the Setup Section. -- If your network automatically assigns DNS hostnames, it may simply show up as `mainsailos` or accordingly given Hostname. -- Failing these two options, you may need to check your router's DHCP server, and find out what IP address has been assigned to the device. - -_**After you're able to get to the Mainsail Webinterface you should consider updating the System to get the latest features. Mainsail, Klipper and Moonraker got a relatively fast Development Cycle. We can't provide MainsailOS Image with all the latest and greatest. So we encourage you to Update on first Login**_ -{: .info} - -_If you decide to update, you should update in following order:_ - -1. System Update (Bring latest RaspberryOS Updates to the System) -2. Klipper Update ( To get latest Firmware, often flashing the MCU can wear out his memory ) -3. Moonraker ( Having latest Version, could lead to more Features in Frontend ) -4. Update Mainsail ( The most important! :P ) - -5. **Important:** Include the mainsail.cfg into your printer.cfg - This could be done by: - - [include mainsail.cfg] - -6. Enjoy Mainsail! +* [Raspberry Pi Imager](mainsailos/pi-imager) (cross-platform, easiest) recommended +* [Balena Etcher](mainsailos/balena-etcher) (requires manual setup) diff --git a/docs/setup-guide/mainsailos/balenaetcher.md b/docs/setup-guide/mainsailos/balenaetcher.md new file mode 100644 index 000000000..29f6287c7 --- /dev/null +++ b/docs/setup-guide/mainsailos/balenaetcher.md @@ -0,0 +1,125 @@ +--- +layout: default +title: balenaEtcher +parent: MainsailOS +grand_parent: Setup Guides +nav_order: 2 +has_children: false +permalink: /setup/mainsailos/balena-etcher +--- + +This method requires manual setup for SSH and Wi-Fi. +{: .info} +This method is cross-platform and works with Windows, Linux and MacOS. +{: .info} + +We **strongly** recommend you use a premium SD card from a reputable manufacturer such as Sandisk, Kingston or Samsung, using an "A1" (or better) grade SD card. \ +\ +Low end cards will often fail quickly when used in this application. +{: .warning} + +**FLASHING WILL DESTROY ALL DATA ON YOUR SD CARD AND CANNOT BE REVERSED** +{: .alert} + +____ + +# Preparation + +Whilst this guide makes specific use of balenaEtcher it is entirely possible to use any flashing software of your choice and then follow the manual steps to enable SSH / network after. + +* [Download](https://github.com/raymondh2/MainsailOS/releases) the latest MainsailOS release (don't unpack the zip; you don't need to). +* [Download](https://www.balena.io/etcher/) and install the latest balenaEtcher. + +# Flashing MainsailOS + +balenaEtcher appearance may vary depending on the host OS. +{: .info} + + +* When opening balenaEtcher you will be presented with the following: +![screenshot-balena-launched](../../assets/img/setup/balena-main-screen.png) + +* Select the 'Flash from file' button ('Select image' on Windows) and navigate to the downloaded MainsailOS zip. +![screenshot-balena-select-os](../../assets/img/setup/balena-select-os.png) + +* Select the 'Select target' button and choose the SD card you want to flash. +![screenshot-balena-select-sd-card](../../assets/img/setup/balena-select-sd-card.png) +![screenshot-balena-select-sd-card-choice](../../assets/img/setup/balena-select-sd-card-choice.png) + +* Return the the main screen, and select 'Flash'. Accept any warnings to continue. +**FLASHING WILL DESTROY ALL DATA ON YOUR SD CARD AND CANNOT BE REVERSED** +{: .alert} + +![screenshot-balena-flash](../../assets/img/setup/balena-etcher-flash.png) + +* balenaEtcher will now decompress (unzip) the MainsailOS archive, write the disc image to the card and verify the flash. +![screenshot-balena-unzip](../../assets/img/setup/balena-unzipping.png) +![screenshot-balena-flash](../../assets/img/setup/balena-flashing.png) +![screenshot-balena-verify](../../assets/img/setup/balena-etcher-validating.png) + +* balenaEtcher will confirm the flash is complete. +![screenshot-balena-finished](../../assets/img/setup/balena-etcher-finished.png) + +# Enabling SSH +You may need to safely remove (eject) the SD card and reinsert it for the /boot partition to show. +{: .info} + +Before you move on, it is important to check SSH is enabled. + +This is done by creating an empty file with no extension named 'SSH', or 'SSH.txt' in the /boot partition of the SD card. MainsailOS includes this file. + +![screenshot-balena-boot-partition](../../assets/img/setup/balena-etcher-boot-partition.png) + +If for some reason the file is not present, then on linux it can be created by navigating to the /boot partition and opening a terminal: + +```bash +sudo touch SSH +sudo touch SSH.txt +``` + + RaspberryOS will check if /boot/SSH(.txt) is present at first boot. If the file is present then SSH will be enabled. + + +# Setting up Wi-Fi / Network + +SSID's are case-sensitive! +{: .info} +Don't forget to set the country! +{: .warning} + + +To setup Wi-Fi for a headless Pi install the network SSID and password must be entered into mainsailos-wpa-supplicant.txt + +With the SD card inserted into the computer, navigate to the SD card's /boot partition and open mainsail-wpa-supplicant.txt. + +Locate the relevant section to your network, remove the comment marks (#) and enter the SSID and password. WPA/WPA2 is the most common. + +```yml +Original: +## WPA/WPA2 secured +#network={ +# ssid="put SSID here" +# psk="put password here" +#} + +Filled out: +## WPA/WPA2 secured +network={ + ssid="CaseSensitive_WIFI" + psk="SuperSecrets" +} + +... + +# Uncomment the country your Pi is in to activate Wifi in RaspberryPi 3 B+ and above +# For full list see: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 +country=GB # United Kingdom + +``` +Save and exit the mainsailos-wpa-supplicant.txt file. + +You are now ready to move on to the [first boot](first-boot) of MainsailOS. + + +--- +[< tool selection](../mainsail-os.md){: .btn } [next step >](first-boot){: .btn } diff --git a/docs/setup-guide/mainsailos/first-boot.md b/docs/setup-guide/mainsailos/first-boot.md new file mode 100644 index 000000000..392811ec0 --- /dev/null +++ b/docs/setup-guide/mainsailos/first-boot.md @@ -0,0 +1,73 @@ +--- +layout: default +title: First boot +parent: MainsailOS +grand_parent: Setup Guides +nav_order: 3 +has_children: false +permalink: /setup/mainsailos/first-boot +--- + + +# First boot + +Insert the flashed SD card into your Pi and connect other desired/necessary hardware (ethernet, USB to 3D printer, webcam). + +Power on the Pi and leave it to boot. + +**The initial boot of MainsailOS may take some time to expand your "root" filesystem. The larger the SD card, the longer the first boot will take.** +{: .warning} + +Initially the green LED on the Pi will be extremely active. After some time it will only intermittently flicker, indicating it has likely completed the boot sequence. + +## Mainsail.cfg + + **Important:** Include the mainsail.cfg into your printer.cfg +{: .warning} + +Mainsail will not work unless Klipper is told to include its configuration. This can be achieved either by placing the contents of mainsail.cfg into your printer.cfg fi> + +To do this, open the default printer.cfg in the Mainsail web GUI: + +![screenshot-web-editor](../../../assets/img/setup/screenshot-web-editor-printer.png) + +![screenshot-web-editor-printercfg](../../../assets/img/setup/screenshot-printercfg-include-mainsail.png) + +Add the following line: + +```yml +[include mainsail.cfg] +``` +Save the file (ctrl+s) and exit nano (ctrl+x). + +Reboot the Pi, or restart the klipper service for it to take affect. + +```bash +sudo reboot +or +sudo systemctl restart klipper +``` + +The web ui should now be ready to access on your local network: + +``` +http://mainsailos.local +http:// +``` + +## Updates + +Once you've successfully navigated to the Mainsail web ui we _thoroughly_ recommend that you run updates. + +Klipper, Moonraker and Mainsail have fast development cycles and whilst we do our best to ensure MainsailOS ships as close to the bleeding edge as we can, there will always be a short delay before releases make it into the image. + +We recommend that you enable and use the [built in update-manager](../../update/update-manager) to perform a system update, then update the stack components (Klipper, Moonraker, Mainsail) + +![screenshot-update-manager](../../../assets/img/update/screenshot-update-manager-example-not-up-to-date.png) + + +MainsailOS is now configured, and we can get Klipper's [printer.cfg](klipper-setup) setup. + +--- +[< tool selection](../mainsail-os.md){: .btn } [next step >](klipper-setup){: .btn } + diff --git a/docs/setup-guide/mainsailos/klipper-setup.md b/docs/setup-guide/mainsailos/klipper-setup.md new file mode 100644 index 000000000..bc958c5e4 --- /dev/null +++ b/docs/setup-guide/mainsailos/klipper-setup.md @@ -0,0 +1,45 @@ +--- +layout: default +title: Klipper +parent: MainsailOS +grand_parent: Setup Guides +nav_order: 4 +has_children: false +permalink: /setup/mainsailos/klipper-setup +--- + +# Klipper setup + +Please read and follow the [Klipper documentation](https://klipper3d.org) in order to setup your machine. +{: .info} +You do not need to follow instructions pertaining to Octopi or Octoprint found in the Klipper documentation. +{: .info} + +Klipper is a highly versatile piece of software and can run with almost any machine. Due to the plethora of stock and custom hardware options available, it is impossible to ship MainsailOS / Klipper with a default configuration that would work for everyone. + +## Modifying/constructing printer.cfg + +**You must enter parts of this configuration manually, as it is specific to your printer and MCU hardware** +{: .warning} + +To customise your printer.cfg you will need to SSH to your Pi and: + +```yml +cd ~/klipper_config +sudo nano printer.cfg +``` +Then follow the [Klipper documentation](https://klipper3d.org) to construct your printer.cfg file. + +--- + +Before progressing to the next step, ensure that you have: + +* Correctly built the firmware and [flashed the MCU](https://www.klipper3d.org/Installation.html#building-and-flashing-the-micro-controller) +* Correctly written/customised your printer.cfg file using the [Klipper configuration reference](https://www.klipper3d.org/Config_Reference.html). +* Checked and then [verified your printer.cfg](https://www.klipper3d.org/Config_checks.html). + + +--- +[< first boot](first-boot){: .btn } [next step >](pre-flight){: .btn } + + diff --git a/docs/setup-guide/mainsailos/pi-imager.md b/docs/setup-guide/mainsailos/pi-imager.md new file mode 100644 index 000000000..6cabcecf3 --- /dev/null +++ b/docs/setup-guide/mainsailos/pi-imager.md @@ -0,0 +1,75 @@ +--- +layout: default +title: Raspberry Pi Imager +parent: MainsailOS +grand_parent: Setup Guides +nav_order: 1 +has_children: false +permalink: /setup/mainsailos/pi-imager +--- + +This method is cross-platform and works with Windows, Linux and MacOS +{: .info} + +We **strongly** recommend you use a premium SD card from a reputable manufacturer such as Sandisk, Kingston or Samsung, using an "A1" (or better) grade SD card. \ +\ +Low end cards will often fail quickly when used in this application. +{: .warning} + +**FLASHING WILL DESTROY ALL DATA ON YOUR SD CARD AND CANNOT BE REVERSED** +{: .alert} + +____ + +# Preparation + +* [Download](https://github.com/raymondh2/MainsailOS/releases) the latest MainsailOS release (don't unpack the zip; you don't need to). +* [Download](https://www.raspberrypi.org/software/) and install the latest Raspberry Pi Imager (aka. rpi-imager). + +# Flashing MainsailOS + +Raspberry Pi Imager appearance may vary depending on the host OS. +{: .info} + + +* When opening rpi-imager you will be presented with the following: + +![screenshot-imager-launched](../../assets/img/setup/rpi-imager-launched.png) + +* Select "CHOOSE OS", and a popup will open as illustrated below. Select "Use custom" and navigate to the MainsailOS zip you downloaded. + +![screenshot-imager-popup](../../assets/img/setup/rpi-os-popup.png) +![screenshot-imager-os-selected](../../assets/img/setup/rpi-choosen-os.png) + +* Click on "STORAGE" and select your desired SD card. + +![screenshot-imager-sd-card-selection](../../assets/img/setup/rpi-sdcard.png) + +* Hostname, wi-fi, language and numerous other settings can now be scrolled through and pre-configured in a hidden setup menu, opened by pressing: + +```bash +CTRL+SHIFT+X +``` +As a bare minimumm setup SSH and a network connection (unless wired) at this point, especially if performing a 'headless' installation. +{: .info} + +![screenshot-imager-rpi-preconfig1](../../assets/img/setup/rpi-setup-1.png) + +![screenshot-imager-rpi-preconfig2](../../assets/img/setup/rpi-setup-2.png) + +* With all desired options preconfigured, click on "WRITE" and accept the warning. + +![screenshot-imager-warning](../../assets/img/setup/rpi-warning.png) + +* Imager will take some time to write the disc image to the SD card. When it's finished, click continue. + +![screenshot-imager-write-finished](../../assets/img/setup/rpi-finished.png) + +Select the "CONTINUE" button and unmount (safely remove) your newly flashed MainsailOS SD card. + +You are now ready to move on to the [first boot](first-boot) of MainsailOS. + + +--- +[< tool selection](../mainsail-os.md){: .btn } [next step >](first-boot){: .btn } + diff --git a/docs/setup-guide/manual-setup/operating-system.md b/docs/setup-guide/manual-setup/operating-system.md index b523fb368..b0cd99a02 100644 --- a/docs/setup-guide/manual-setup/operating-system.md +++ b/docs/setup-guide/manual-setup/operating-system.md @@ -12,25 +12,32 @@ description: >- # {{ page.title }} {{ page.description }} -**Please don't use an OctoPi image!** -It can cause unforeseeable events, like rips in the space-time continuum. So be aware! -No seriously. Experiences have shown that it is advisable not to use an OctoPi image (especially for beginners). +Do **not** use an OctoPi image as it can cause unforeseen (avoidable) problems. {: .warning } +Don't forget to enable SSH and configure a network if using Wi-Fi. +{: .info} -It is recommended to use a clean Raspberry Pi OS 32-bit Lite image (previously called Raspbian). You can download it [here](https://downloads.raspberrypi.org/raspios_lite_armhf_latest){:target="_blank"}. -For more information about installing Raspberry Pi OS click [here](https://www.raspberrypi.org/documentation/installation/installing-images/){:target="_blank"}. Don't forget to enable ssh. +It is recommended to use a clean [Raspberry Pi OS 32-bit Lite](https://downloads.raspberrypi.org/raspios_lite_armhf_latest){:target="_blank"} image (previously called Raspbian). -Once you have finished the installation and are connected via ssh, you can continue. +We recommend you follow the RaspberryOS official [documentation](https://www.raspberrypi.org/documentation/installation/installing-images/){:target="_blank"} to flash and install the operating system to your SD card. + +Once you have finished the installation and are connected via SSH, you can continue. ## Requirements + +Install the required packages and update the system: + ```bash sudo apt update && sudo apt upgrade sudo apt install git dfu-util unzip ``` -**Moonraker requires Python 3.7 or greater,** verify that your distribution's Python 3 packages meet this requirement. +**Verify that your distribution's Python 3 package(s) are version 3.7 or newer.** {: .alert } +Moonraker requires Python 3.7 and will not operate without it. + +You can check the current Python version installed to your operating system with the following terminal command: ``` python3 --version ``` diff --git a/docs/setup-guide/pre-flight.md b/docs/setup-guide/pre-flight.md new file mode 100644 index 000000000..7095dcc7a --- /dev/null +++ b/docs/setup-guide/pre-flight.md @@ -0,0 +1,23 @@ +-- +layout: default +title: Pre-flight +parent: Setup Guides +nav_order: 5 +has_children: false +has_toc: false +permalink: /setup/mainsailos/pre-flight +--- + +# Preflight Checklist + +A quick run-through to check no important steps have been missed during installation and configuration. + +| Installed software components: | Configured: | Performed: | +| :-- | :-- | :-- | +| ✅ MainsailOS
**OR**
✅ Klipper
✅ Moonraker
✅ Mainsail
| ✅ Network
✅ [Configured printer.cfg](k> + +# Time to print + +If you've covered all the steps, you should now have a complete software stack ready to perform calibration prints! + +**Thank you for choosing Mainsail** \ No newline at end of file diff --git a/docs/update-guide/index.md b/docs/update-guide/index.md index 43df274e3..b230b1844 100644 --- a/docs/update-guide/index.md +++ b/docs/update-guide/index.md @@ -1,9 +1,15 @@ --- layout: default -title: Update Guide +title: Update Guides nav_order: 3 has_children: true permalink: /update/ +has_toc: false --- -This is a guide to update up Klipper, Moonraker & Mainsail on your Raspberry Pi. \ No newline at end of file +There are currently two methods to update either via the web interface, or manually. + +- [Update Manager](update-manager) recommended + A built in update utility found in the web ui, under the machine tab. +- [Manual Update](manual-update) + Guides on manual update methods for each component; Klipper, Moonraker and Mainsail. diff --git a/docs/update-guide/manual-update/index.md b/docs/update-guide/manual-update/index.md new file mode 100644 index 000000000..0ddf0143e --- /dev/null +++ b/docs/update-guide/manual-update/index.md @@ -0,0 +1,13 @@ +--- +layout: default +title: Manual Update +parent: Update Guides +nav_order: 3 +has_children: true +permalink: /update/manual-update +has_toc: true +--- + +# Updating Mainsail the manual way + +This section covers the individual methods for updating each component of the stack manually. diff --git a/docs/update-guide/manual-update/klipper.md b/docs/update-guide/manual-update/klipper.md new file mode 100644 index 000000000..4281433a3 --- /dev/null +++ b/docs/update-guide/manual-update/klipper.md @@ -0,0 +1,24 @@ +--- +layout: default +title: Klipper +parent: Manual Update +grand_parent: Update Guides +nav_order: 2 +permalink: /update/manual-update/klipper +--- + +## Klipper +### Update from Repository +```bash +cd ~/klipper +git pull +``` + +Restart Klipper (`sudo service klipper restart`) and check the `klippy.log`, if Klipper starts +correctly and then continue the guide. + +### Klipper config changes +If you have issues after update your Klipper instance, you can check config changes [here](https://github.com/KevinOConnor/klipper/blob/master/docs/Config_Changes.md). + +--- +[< table of contents](index.md){: .btn } [next step >](moonraker.md){: .btn} diff --git a/docs/update-guide/manual-update/mainsail.md b/docs/update-guide/manual-update/mainsail.md new file mode 100644 index 000000000..f0714bc40 --- /dev/null +++ b/docs/update-guide/manual-update/mainsail.md @@ -0,0 +1,26 @@ +--- +layout: default +title: Mainsail +parent: Manual Update +grand_parent: Update Guides +nav_order: 4 +permalink: /update/manual-update/mainsail +--- + +## Mainsail +```bash +cd ~/mainsail +rm -R ./* +wget -q -O mainsail.zip https://github.com/meteyou/mainsail/releases/latest/download/mainsail.zip && unzip mainsail.zip && rm mainsail.zip +``` + +### Move gui.json from gcodes to klipper_config +This is only necessary if you update from 0.2.2 to 0.2.3 or higher. If you use MainsailOS, the virtual_sdcard directory is `gcode_files` instead of `sdcard`. +``` +mv ~/sdcard/gui.json ~/klipper_config/ +``` + +Now it should be possible to open the interface: `http:///`. + +--- +[< previous step](moonraker.md){: .btn } diff --git a/docs/update-guide/manual-update/moonraker.md b/docs/update-guide/manual-update/moonraker.md new file mode 100644 index 000000000..54aabb24a --- /dev/null +++ b/docs/update-guide/manual-update/moonraker.md @@ -0,0 +1,40 @@ +--- +layout: default +title: Moonraker +parent: Manual Update +grand_parent: Update Guides +nav_order: 3 +permalink: /update/manual-update/moonraker +--- + +## Moonraker +```bash +cd ~/moonraker +git pull +``` + +Restart Moonraker (`sudo service moonraker restart`) and open the url `http://:7125/printer/info` in your browser. + +If you see a content like this +``` +{"result": {"hostname": "voron250", "error_detected": false, "version": "v0.8.0-643-g528f9f25", "is_ready": true, "message": "Printer is ready", "cpu": "4 core ARMv7 Processor rev 4 (v7l)"}} +``` + +### Change Moonraker to systemd service (December 6th 2020) +Moonraker is now installed as a systemd service. If `moonraker.conf` is not located in the home directory, the command will looks something like the following: +```bash +~/moonraker/scripts/install-moonraker.sh -f -c /home/pi/klipper_config/moonraker.conf +``` +This allows logging to stdout which can be viewed with the `journalctl -u moonraker command`. + +### Update Moonraker dependence +This is only nessasary, if you see missing modules in the moonraker log. +```bash +~/moonraker/scripts/install-moonraker.sh -r +``` + +### Moonraker config changes +If you have issues after update your Moonraker instance, you can check config changes [here](https://github.com/Arksine/moonraker/blob/master/docs/user_changes.md). + +--- +[< previous step](klipper.md){: .btn } [next step >](mainsail.md){: .btn } diff --git a/docs/update-guide/update-manager.md b/docs/update-guide/update-manager.md new file mode 100644 index 000000000..5acb9f010 --- /dev/null +++ b/docs/update-guide/update-manager.md @@ -0,0 +1,53 @@ +--- +layout: default +title: Update Manager +parent: Update Guides +nav_order: 1 +has_children: false +permalink: /update/update-manager +--- + +# Update Manager + +You can find further information on this topic by checking out the [Moonraker documentation](https://github.com/Arksine/moonraker/blob/master/docs/configuration.md#update_manager){:target="_blank"}. +{: .info} + +## Enabling the feature + +To use the built in Update Manager it must first be enabled by editing the moonraker.conf file: + +```bash +cd ~/klipper_config +sudo nano moonraker.conf +``` +Add the following section to your printers moonraker.conf: + +```yaml +[update_manager] + +[update_manager client mainsail] +type: web +repo: meteyou/mainsail +path: ~/mainsail +``` + +Restart Moonraker: +```bash +sudo systemctl restart moonraker +``` + +## Using the Web UI + +With the manager enabled reload the web ui and select the 'machine' tab from the sidebar. You should now see the Update Manager panel. + +Holding shift whilst clicking the browser's refresh button (or pressing ctrl+f5) will force it to reload the page fully (without the cache). +{: .info} + +Typically the update order is top to bottom. + +![screenshot-updates-required](../assets/img/update/screenshot-update-manager-example-not-up-to-date.png) + +To update a component, click the ![screenshot-update-button](../assets/img/update/screenshot-update-manager-button-rounded.png) button. + +A new window will launch and the component will be updated. When the update is finished, the window can be closed. +