Backup Klipper
Siempre es aconsejable disponer de una copia de seguridad de nuestro sistema o ficheros de configuración para, en caso de desastre, poder restaurarlo rápidamente.
La mayoría de los usuarios no piensan en el backup hasta que algo sale mal: la SD se corrompe, una actualización rompe algo, o se borra sin querer el printer.cfg tras semanas de calibración. En ese momento, tener (o no tener) un backup marca la diferencia entre recuperarse en minutos o empezar desde cero.
Esta guía cubre dos estrategias complementarias:
Imagen completa de SD
Todo el sistema operativo + Klipper + configuraciones
Antes de actualizaciones importantes, cuando el sistema funciona perfectamente
Backup de configuración en GitHub
Solo los ficheros .cfg y scripts
Antes de cualquier cambio de configuración, de forma automatizada
Recomendación: usa ambos métodos. La imagen SD te salva si el hardware falla. El backup en GitHub te salva en el día a día cuando tocas algo que no deberías.
¿Qué ficheros son críticos?
Antes de hablar de herramientas, es importante saber qué necesitas guardar realmente:
~/printer_data/config/printer.cfg
Crítico
Configuración principal de la impresora
~/printer_data/config/moonraker.conf
Crítico
Configuración de la API Moonraker
~/printer_data/config/*.cfg
Crítico
Todos los includes, macros, configuraciones adicionales
~/printer_data/config/variables.cfg
Importante
Variables persistentes de macros (z-offset guardado, etc.)
~/klipper/
Opcional
El código fuente de Klipper — recuperable con git pull
~/moonraker/
Opcional
Código de Moonraker — recuperable
~/printer_data/database/
Opcional
Historial de impresiones, spoolman, estadísticas
El directorio ~/printer_data/gcodes/ (archivos de impresión) y los timelapse no se incluyen en el backup de configuración. Si los necesitas, inclúyelos manualmente o usa una solución de backup diferente.
Cuándo hacer backup
Siempre antes de actualizar Klipper, Moonraker o cualquier componente del sistema
Antes de tocar el
printer.cfgsi vas a hacer cambios importantesTras finalizar una calibración que te costó tiempo (Input Shaper, Pressure Advance, z-offset)
Cuando la impresora funciona perfectamente — ese es el momento ideal, no cuando ya hay problemas
Método 1 — Imagen completa de la SD
Una imagen de la SD es una copia bit a bit de todo el sistema: sistema operativo, Klipper, Moonraker, interfaces web, configuraciones y todo lo demás. Si restauras esta imagen en una SD nueva, recuperas exactamente el estado que tenías.
Aunque está enfocado a hosts con SD (Raspberry Pi), la lógica aplica a cualquier host Linux con almacenamiento extraíble.
Crear imagen — Windows (Win32DiskImager)
Apaga el host correctamente antes de extraer la SD:
O desde la interfaz web de Mainsail/Fluidd → botón de apagado del host.
Extrae la SD e insértala en el PC con Windows
Descarga e instala Win32DiskImager
Selecciona el Device correcto (tu SD) y elige la ruta de destino con extensión
.img

Pulsa Read y espera a que finalice

Crear imagen — macOS (Disk Utility)
Inserta la SD en el Mac
Abre Disk Utility (Cmd+Space → "Disk Utility")
En el menú File → New Image → Image from... selecciona tu SD

Elige destino y nombre, asegúrate de no marcar encriptación, y pulsa Save
Crear imagen — desde la propia Raspberry Pi
Puedes crear la imagen directamente desde el host sin extraer la SD. Necesitas un pendrive USB con espacio suficiente.
Conecta el pendrive y comprueba dónde se montó:
Anota el punto de montaje (ejemplo: /media/pi/MYBACKUP).
Instala el script de backup:
Lanza el backup:
Comprimir la imagen con PiShrink
Las imágenes de SD suelen ocupar más de lo necesario. PiShrink las comprime significativamente y facilita restaurarlas en SDs más pequeñas:
La opción -z crea un archivo .gz comprimido. Para restaurarlo, los programas de flasheo lo admiten directamente.
Automatizar con cron:
Añade una de estas líneas según tu preferencia:
Restaurar la imagen SD
La opción más sencilla. Descárgalo desde raspberrypi.com/software.
Selecciona Use Custom como sistema operativo

Selecciona tu imagen
.imgy la SD nueva como destino

Pulsa Write y espera

Descarga balenaEtcher.
Selecciona Flash from file y elige tu imagen
Selecciona la SD nueva como destino

Pulsa Flash y acepta los avisos de seguridad que aparezcan
Abre Win32DiskImager con la nueva SD ya insertada
Selecciona la imagen previamente creada y la SD como destino
Pulsa Write (en lugar de Read)

Método 2 — Backup de configuración en GitHub
Este método guarda solo los ficheros de configuración (.cfg, scripts, etc.) en un repositorio GitHub privado con historial de versiones. Es el complemento perfecto al método anterior: más rápido, siempre accesible online y con control de cambios.
Ventajas respecto a la imagen de SD:
Se lanza con una macro desde Mainsail/Fluidd en segundos
Puedes ver qué cambió entre versiones y revertir a un punto concreto
Accesible desde cualquier ordenador sin extraer la SD
No necesitas hardware adicional
Paso 1 — Crear el repositorio en GitHub
Si no tienes cuenta en GitHub, créala en github.com/signup (cuenta gratuita).
Haz login y crea un nuevo repositorio pulsando New

Dale un nombre descriptivo (ej:
voron24_klipper_config) y elige si quieres que sea Private (recomendado — tus configs pueden contener datos de red)

Anota la URL del repositorio — la necesitarás más adelante:

Paso 2 — Crear el token de acceso
El script de backup necesita un token para autenticarse con GitHub desde el host.
Pulsa Generate new token (classic)

Dale un nombre descriptivo (ej:
klipper-backup-voron)Expiration: puedes usar No expiration o una fecha larga — si el token expira, el backup dejará de funcionar silenciosamente
Permisos necesarios: marca
repo(acceso completo al repositorio)

Pulsa Generate token y copia el token inmediatamente — solo se muestra una vez. Guárdalo en un lugar seguro.

Paso 3 — Instalar la extensión G-Code Shell Command
El backup se lanza mediante una macro de Klipper que ejecuta un script shell. Para eso necesitas la extensión gcode_shell_command.
Instalación desde KIAUH (recomendada):

Instalación manual:
Paso 4 — Descargar y configurar el script de backup
Edita el script para adaptarlo a tu instalación:
Ajusta estas variables al principio del fichero:
Guarda con Ctrl+X → Y → Enter y dale permisos de ejecución:
Si editas el script desde Mainsail o Fluidd (editor web), los permisos de ejecución se pierden. Tendrás que volver a ejecutar chmod +x desde SSH.
Paso 5 — Configurar el repositorio git local

Haz el primer commit y push:

Paso 6 — Crear la macro de Klipper
Añade esto a tu printer.cfg o a un fichero de macros:
Ajusta la ruta en command: al path real de tu script. Si tu usuario no es pi (es el caso en sistemas más nuevos), el path será diferente — usa echo $HOME en SSH para comprobarlo.
El timeout de 30 segundos puede quedarse corto si el repositorio tiene muchos ficheros o la conexión es lenta. Sube a 60 si experimentas timeouts.
Ahora puedes lanzar el backup desde la sección de Macros de Mainsail o Fluidd:

En la consola verás el progreso:

Y en GitHub tendrás el historial completo de cambios:

Automatizar el backup al final de cada impresión
La mejor estrategia es lanzar el backup automáticamente cuando termina una impresión. Añade la llamada a tu macro PRINT_END (o donde finalices tus impresiones):
Así cada vez que acaba una impresión tienes una copia actualizada en GitHub sin tener que recordarlo.
Método 3 — KGB (Klipper Git Backup)
KGB es una alternativa al script anterior creada por la comunidad, con un asistente de configuración propio y arranque automático con el sistema.
Si ya tienes configurado el método anterior (script 3dwork-autocommit), no necesitas KGB. Elige uno de los dos.
Instalación:
El asistente te guiará por la configuración:

Como mínimo configura la opción 1) Configure con tu usuario de GitHub, email, URL del repositorio y directorio de configuración.
Clave SSH requerida por KGB
Durante la configuración, KGB genera una clave SSH pública que debes añadir a tu cuenta de GitHub:
GitHub → Settings → SSH and GPG keys → New SSH key
Pega la clave pública que te mostró KGB.
KGB se ejecuta automáticamente al arrancar el host y hace push a GitHub cuando hay conexión disponible.
Restaurar la configuración desde GitHub
Este es el paso más importante — el que necesitarás cuando algo salga mal.
Restauración rápida (sobreescribir con lo que hay en GitHub)
git reset --hard borra todo lo que tengas en el directorio config que no esté en GitHub. Antes de ejecutarlo, asegúrate de que tienes el estado correcto en el repositorio remoto.
Restauración en instalación nueva
Si la SD murió y estás empezando desde cero con MainsailOS:
Recuperar una versión anterior de un fichero concreto
Una de las ventajas del control de versiones es poder recuperar un fichero concreto de un momento específico sin afectar al resto:
Esto es especialmente útil cuando haces un cambio en la configuración y rompes algo — puedes recuperar exactamente cómo estaba antes sin restaurar todo.
Checklist de backup
Antes de hacer cualquier cambio importante en tu impresora, verifica:
Última actualización