First Boot
Learn how to set up MainsailOS after flashing it to your SD card. This guide covers the first boot, accessing Mainsail, and essential configurations for your 3D printer.
Last updated
Learn how to set up MainsailOS after flashing it to your SD card. This guide covers the first boot, accessing Mainsail, and essential configurations for your 3D printer.
Last updated
After MainsailOS is successfully written to the SD card, please insert the card into your device. Connect necessary peripherals such as network cables, webcams, the USB cable to your 3D printer. Then turn on the device and let it boot up.
The first start of MainsailOS will take some time to expand your file system. The larger the SD card, the longer the first start-up process will take.
Raspberry PI: The green LED indicates SD card activity. As soon as it only flashes occasionally, the process should be completed.
This process can take up to 5 minutes to complete on slower models such as the Pi Zero 2 and Pi 3 series.
After the boot process has finished, Mainsail will be available at http://mainsailos.local or http://mainsailos. You may need to replace "mainsailos" with the hostname you have chosen while flashing the image.
If accessing Mainsail using the hostname fails, you can try to connect to the device's IP address directly. Look it up in your router if it's not known.
When you open the Update Manager for the first time, it will show invalid software packages.
This is a normal behavior because the update manager hasn't checked for updates until now. To fix this, just hit the refresh button in the top right corner.
The Update Manager now shows all available updates. Click “Update all components” to start the update and wait until the installation is complete. See the Mainsail documentation for detailed information about the Update Manager.
We recommend updating the system to the current version. Even though we regularly release new versions of the OS, we cannot guarantee that all components (System, Klipper, Moonraker, Mainsail) are up to date when you install the system.
MainsailOS is a generic image for all Klipper printers, it does not include any Klipper config file (printer.cfg). With no printer.cfg present, the following error will be reported:
Most open-source 3D printer communities provide a printer.cfg for their printers. Check the projects GitHub repository or ask at the their Discord server.
A lot of vendors add the config file for their printers to the Klipper Github repository.https://github.com/Klipper3d/klipper/tree/master/config
Look for a file matching your printers name and that start with printer-.
In case you cannot find a fitting printer.cfg file or you replaced the printer board by yourself. There a generic board templates in the Klipper repository (https://github.com/Klipper3d/klipper/tree/master/config) to help you getting started. Template's need adjustments to fit your printer setup (Axis lengths, bed size, etc). Look for files matching your board name and starting with generic-.
To upload your printer.cfg, open the Machine page in Mainsail and click on the upload button or just drag and drop the file into the config file panel. Pay attention that this file has the name printer.cfg. Only this name will be used by Klipper.
Your printer board must be flashed with Klipper (Guide: https://www.klipper3d.org/Installation.html#building-and-flashing-the-micro-controller), and the serial path to your printer board must also be adjusted in the printer.cfg (Guide: https://www.klipper3d.org/Installation.html#configuring-klipper) so that Klipper can start.
After uploading your printer.cfg and starting Klipper successfully, you will be confronted with a couple of warnings:
The Mainsail specific configuration still needs to be added to your Klipper configuration (printer.cfg). We provide this configuration as the mainsail.cfg, which is preinstalled on MainsailOS. You just have to include this file in your printer.cfg by adding the following line:
After adding this line, click SAVE & RESTART and the warning should disappear.
The mainsail.cfg is read-only. This is necessary to update it via the update manager. If you want to adjust the settings follow the instructions in this guide:https://github.com/mainsail-crew/mainsail-config#how-to-customize-your-settings
Congratulations! Mainsail is now ready to sail! Happy printing!
