Installare Klipper su Raspberry Pi: firmware, printer.cfg e Mainsail

Klipper è un firmware per stampanti 3D che divide il lavoro in due. Un piccolo computer Linux, di solito un Raspberry Pi, fa i calcoli: è l’host. La scheda elettronica della stampante, la mcu, esegue i movimenti. Questa guida è per chi ha una stampante con il firmware originale e vuole passare a Klipper. Alla fine avrete il firmware compilato e caricato sulla scheda, un file printer.cfg che descrive la macchina e un’interfaccia web da cui controllare che la stampante sia pronta.

I comandi sono quelli della documentazione ufficiale di Klipper, elencata in fondo.

Che cos’è Klipper e come si usa

Secondo la guida all’installazione di Klipper, quasi tutte le impostazioni stanno in un unico file, printer.cfg, salvato sull’host. La scheda della stampante riceve un firmware compilato su misura, mentre i calcoli restano al Raspberry Pi.

Per usare Klipper serve un front end. Le scelte migliori sono le interfacce che dialogano con l’API web di Moonraker, cioè Fluidd e Mainsail, ma si può usare anche OctoPrint. Sotto c’è sempre lo stesso Klipper. Questa guida segue la strada di Mainsail e Fluidd.

Cosa serve

• Un Raspberry Pi adatto. Le FAQ di Klipper consigliano Raspberry Pi Zero 2 W, Raspberry Pi 3, 4 o 5. Raspberry Pi 1, 2 e Zero di prima generazione sono sconsigliati: hanno poca potenza e durante la stampa possono verificarsi blocchi.
• In alternativa, un altro computer Linux, cioè un altro SBC o una macchina x86. Servono Python su Linux e almeno il supporto hardware ai calcoli in virgola mobile a doppia precisione. Fuori dal Raspberry Pi servono competenze da amministratore Linux.
• Una microSD per il sistema del Raspberry Pi.
• La scheda della stampante, collegata al Raspberry Pi con un cavo USB di buona qualità.
• Un buon alimentatore per il Raspberry Pi, una delle prime difese contro gli errori di comunicazione.
• Il file di configurazione della stampante, da cercare nella cartella config di Klipper o sul sito del produttore.

Scegliere il file di configurazione giusto

Conviene farlo per primo, perché i commenti in cima al file spiegano come compilare il firmware. Nella cartella config di Klipper cercate un file che inizia con printer- e corrisponde al vostro modello. Se non c’è, provate sul sito del produttore.

Se conoscete solo la scheda elettronica, cercate un file che inizia con generic-. Basta per completare l’installazione, ma poi andrà personalizzato. Scrivere una configurazione da zero richiede una conoscenza approfondita della stampante e della sua elettronica.

Preparare il Raspberry Pi con MainsailOS e collegarsi in SSH

La strada più diretta è MainsailOS, l’immagine già pronta di Mainsail per Raspberry Pi e per alcuni modelli OrangePi. In alternativa si parte da un sistema base come Raspberry Pi OS Lite e si installano Klipper e l’interfaccia con KIAUH (Klipper Install And Update Helper), un installer di terze parti. Le versioni desktop del sistema sono sconsigliate: alcuni programmi di supporto possono bloccare funzioni di Klipper e rendere invisibili certe schede.

Per scrivere MainsailOS sulla microSD seguite la guida per Raspberry Pi nella documentazione di Mainsail (docs.mainsail.xyz).

Attenzione: la scrittura dell’immagine cancella tutti i dati sul supporto selezionato. Salvate prima i file che vi servono e, nell’elenco dei dispositivi, controllate di aver scelto la microSD e non un altro disco collegato al computer.

Inserite la microSD nel Raspberry Pi e accendetelo. I comandi dei passaggi successivi si danno da un terminale SSH sul Raspberry Pi. Se non avete ancora configurato l’accesso remoto, trovate le istruzioni nella nostra guida su Raspberry Pi Connect e SSH.

Compilare il firmware per la scheda della stampante

Il firmware si compila sul Raspberry Pi, con le impostazioni del microcontrollore della vostra scheda. Entrate nella cartella di Klipper:

cd ~/klipper/

Aprite il menu di configurazione:

make menuconfig

Le voci da impostare sono descritte nei commenti in cima al file di configurazione che avete scelto: apritelo in un browser o in un editor. Quando avete finito, premete Q per uscire e Y per salvare. Poi compilate:

make

Se i commenti del file descrivono una procedura di flash specifica per la vostra scheda, seguite quella al posto delle istruzioni generali qui sotto.

Trovare la porta seriale della scheda

Il nome della porta seriale serve sia per il flash sia per la configurazione. Con la scheda collegata via USB, eseguite:

ls /dev/serial/by-id/*

Dovreste vedere una riga simile a questa:

/dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0

Il nome cambia da una stampante all’altra, ma per la stessa scheda non cambia: copiatelo dall’output e incollatelo dove serve. Se compaiono più righe e non capite qual è la vostra, scollegate la scheda e ripetete il comando: è quella che sparisce.

Se usate più microcontrollori senza un identificativo unico, cosa comune con il chip USB CH340, le FAQ indicano invece:

ls /dev/serial/by-path/*

Avvisi e flash del firmware sulla scheda della stampante

Attenzione: il flash sostituisce il firmware presente sulla scheda, che da quel momento funzionerà con Klipper. Prima verificate con ls /dev/serial/by-id/* che il dispositivo indicato sia la scheda della stampante: se la scollegate, la sua riga deve sparire. Con il dispositivo sbagliato il firmware finisce su un altro apparecchio. Se pensate di tornare al firmware originale, procuratevi prima le istruzioni del produttore.

Il metodo dipende dal chip:

• STM32 (e cloni), LPC e simili: di solito il primo flash si fa con la scheda SD. La scheda della stampante non deve essere collegata al Raspberry Pi via USB: alcune schede si alimentano dall’USB e il flash non va a buon fine.
• Atmega (per esempio il 2560) e RP2040: si usa make flash.

Con il flash da SD, molte schede hanno una protezione contro i flash ripetuti. Le schede originali di solito vogliono un nome di file diverso ogni volta (firmware1.bin, poi firmware2.bin) e possono ignorare un file con lo stesso nome. Molte schede aftermarket accettano sempre firmware.bin e dopo il flash lo rinominano firmware.cur. Prima di iniziare, controllate come si comporta la vostra.

Durante make flash Klipper deve essere fermo. Le schede RP2040 potrebbero dover essere messe prima in modalità Boot. Fermate il servizio:

sudo service klipper stop

Per le schede Atmega, sostituite la porta dell’esempio con la vostra:

make flash FLASH_DEVICE=/dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0

Per le schede RP2040:

make flash FLASH_DEVICE=first

In entrambi i casi, alla fine riavviate il servizio:

sudo service klipper start

Creare e modificare printer.cfg

Secondo la guida all’installazione, con Mainsail o Fluidd la strada più semplice è l’editor integrato: aprite l’esempio adatto nell’editor web e salvatelo come printer.cfg.

Il file di esempio di Klipper descrive la stampante, ma non contiene le sezioni che servono all’interfaccia. Senza [virtual_sdcard], per esempio, non potete gestire i file G-code da stampare. MainsailOS raccoglie queste sezioni in un file già pronto, mainsail.cfg. Verificate che sia presente nella cartella di configurazione e aggiungete all’inizio di printer.cfg la riga [include mainsail.cfg], poi premete SAVE & RESTART. La procedura è descritta nella documentazione di Mainsail, alla pagina dedicata a mainsail.cfg.

In alternativa potete usare un editor desktop che lavora via scp o sftp (Notepad++, WinSCP, Cyberduck) oppure il terminale SSH. L’esempio della documentazione salva il file nella home dell’utente pi, cioè /home/pi/printer.cfg. I comandi seguenti vanno bene solo se la vostra installazione legge il file da ~/printer.cfg. Con MainsailOS la posizione può essere diversa: nel dubbio usate l’editor web. Copiate l’esempio, sostituendo example-cartesian.cfg con il file della vostra stampante:

cp ~/klipper/config/example-cartesian.cfg ~/printer.cfg

Poi apritelo:

nano ~/printer.cfg

Dopo il flash il nome della porta può cambiare. Rilanciate ls /dev/serial/by-id/* e scrivete il nome nella sezione [mcu], alla voce serial:. Il riferimento della configurazione indica che il parametro è obbligatorio quando si usa una porta seriale. Il valore predefinito di baud è 250000, quello consigliato per tutte le schede supportate.

Interfaccia web e prima verifica dalla console

Aprite Mainsail o Fluidd nel browser e usate la console dei comandi dell’interfaccia, non il terminale SSH. Per caricare la configurazione:

restart

Poi controllate lo stato:

status

Se Klipper ha letto il file e ha trovato e configurato il microcontrollore, status risponde che la stampante è pronta. Se c’è un errore di configurazione, correggete printer.cfg e ripetete restart finché la stampante non risulta pronta. Gli errori compaiono nella console e negli avvisi dell’interfaccia. Il log di solito si trova in ~/printer_data/logs/klippy.log. Poi passate ai controlli di base della pagina «Configuration checks» della documentazione di Klipper.

Aggiornare Klipper

Con MainsailOS la via prevista è l’Update Manager, nella pagina Machine dell’interfaccia. Prima di aggiornare conviene leggere la pagina «Configuration Changes» della documentazione di Klipper, per sapere se printer.cfg va modificato.

Da terminale, le FAQ descrivono una scorciatoia per i casi in cui cambia solo il software dell’host. Entrate nella cartella:

cd ~/klipper

Scaricate la versione più recente:

git pull

Riavviate il servizio:

sudo service klipper restart

Se viene richiesto di aggiornare anche il microcontrollore, il firmware va ricompilato e caricato di nuovo, con la procedura adatta alla vostra scheda. Nella procedura completa le FAQ citano anche lo script install-octopi.sh, che però è pensato per le installazioni OctoPi: su MainsailOS non va lanciato. Ripulite i file della compilazione precedente:

make clean

Ripetete make menuconfig e make, poi fermate il servizio con sudo service klipper stop. Se la vostra scheda si aggiorna da SD, seguite quel metodo. Altrimenti fate il flash: l’esempio delle FAQ usa /dev/ttyACM0, da sostituire con la porta della vostra scheda, verificata come nel passaggio sul flash.

make flash FLASH_DEVICE=/dev/ttyACM0

Infine rimettete in funzione Klipper:

sudo service klipper start

Disinstallare Klipper e tornare a un altro firmware

Per rimuovere Klipper dal Raspberry Pi c’è uno script apposito:

sudo ~/klipper/scripts/klipper-uninstall.sh

Attenzione: il comando seguente cancella senza chiedere conferma le cartelle ~/klippy-env e ~/klipper con tutto il loro contenuto. Se dentro ~/klipper avete file vostri, spostateli prima.

rm -rf ~/klippy-env ~/klipper

Questi comandi agiscono solo sul Raspberry Pi. La scheda della stampante resta con Klipper finché non ci caricate un altro firmware, seguendo le istruzioni di quel firmware o del produttore.

Se qualcosa va storto

• make flash non funziona. Controllate che Klipper sia fermo e che FLASH_DEVICE sia corretto. Se usate OctoPrint, verificate che non sia collegato alla porta (scheda Connection, pulsante Disconnect). Se la scheda non accetta make flash, il flash va fatto a mano: cercate le istruzioni nel file di configurazione o presso il produttore, oppure usate strumenti come avrdude o bossac.
• Dopo un riavvio del microcontrollore la porta diventa /dev/ttyUSB1. In printer.cfg usate il percorso stabile che trovate in /dev/serial/by-id/.
• Errori casuali «Lost communication with MCU». Di solito la causa è il collegamento USB. Controllate che il cavo sia di buona qualità e ben inserito, che il Raspberry Pi abbia un alimentatore di qualità, che l’alimentatore della stampante non sia sovraccarico e che i cavi di motori e riscaldatori siano integri. Se non usate OctoPi, ModemManager o pacchetti simili possono disturbare la comunicazione seriale e potrebbe essere necessario disattivarli.
• Il Raspberry Pi si riavvia durante la stampa. Probabilmente ci sono sbalzi di tensione: fate gli stessi controlli del punto precedente.

Documentazione di riferimento

Pagine consultate il 30 settembre 2026. La documentazione di Klipper si riferisce in generale a un host Linux e consiglia un Raspberry Pi o un dispositivo basato su Debian, senza indicare un sistema operativo preciso. Le indicazioni su mainsail.cfg e sull’Update Manager vengono dalla documentazione di Mainsail (docs.mainsail.xyz).

• Documentazione di Klipper: Installation
• Documentazione di Klipper: Frequently Asked Questions
• Documentazione di Klipper: Configuration reference

Leggi anche

• OrcaSlicer: come installarlo e preparare il primo progetto di stampa
• PrusaSlicer: come installarlo e configurarlo per la prima stampa 3D
• OctoPi su Raspberry Pi: installarlo e stampare in 3D da remoto