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:

Tipo	Qué cubre	Cuándo usarlo
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:

Fichero / Directorio	Importancia	Descripción
~/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.cfg si vas a hacer cambios importantes

• Tras 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:

sudo shutdown now

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ó:

# Lanza antes de y después de insertar el pendrive para ver qué apareció nuevo
df -h

Anota el punto de montaje (ejemplo: /media/pi/MYBACKUP).

Instala el script de backup:

cd ~
git clone https://github.com/lzkelley/bkup_rpimage.git

Lanza el backup:

sudo sh ~/bkup_rpimage/bkup_rpimage.sh start -c /media/pi/MYBACKUP/klipper_backup.img

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:

wget https://raw.githubusercontent.com/Drewsif/PiShrink/master/pishrink.sh
sudo chmod +x pishrink.sh
sudo mv pishrink.sh /usr/local/bin

# Comprimir la imagen recién creada
sudo pishrink.sh -z /media/pi/MYBACKUP/klipper_backup.img

La opción -z crea un archivo .gz comprimido. Para restaurarlo, los programas de flasheo lo admiten directamente.

Automatizar con cron:

sudo crontab -e

Añade una de estas líneas según tu preferencia:

# Backup incremental (sobreescribe siempre el mismo fichero) — cada noche a las 2:00
0 2 * * * sudo sh /home/pi/bkup_rpimage/bkup_rpimage.sh start -c /media/pi/MYBACKUP/klipper_backup.img

# Backup con fecha en el nombre — un fichero diferente cada día
0 2 * * * sudo sh /home/pi/bkup_rpimage/bkup_rpimage.sh start -c /media/pi/MYBACKUP/klipper_$(date +%Y-%m-%d).img

Restaurar la imagen SD

Raspberry Pi Imager (Win/macOS)

La opción más sencilla. Descárgalo desde raspberrypi.com/software.

• Selecciona Use Custom como sistema operativo

• Selecciona tu imagen .img y la SD nueva como destino

• Pulsa Write y espera

balenaEtcher (Win/macOS/Linux)

Win32DiskImager (Windows)

---

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.

• Ve a GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)

• 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):

Menú principal → 4) Advanced → 9) Shell Command Extension

Instalación manual:

# Descarga el plugin desde el repositorio de KIAUH
wget -O ~/klipper/klippy/extras/gcode_shell_command.py   https://raw.githubusercontent.com/dw-0/kiauh/master/kiauh/resources/gcode_shell_command.py

# Reinicia Klipper para que cargue la extensión
sudo systemctl restart klipper

Paso 4 — Descargar y configurar el script de backup

cd ~/printer_data/config

# Descarga el script
wget -O 3dwork-autocommit.sh   https://raw.githubusercontent.com/3dwork-io/3dwork-klipper/master/scripts/3dwork-autocommit.sh

Edita el script para adaptarlo a tu instalación:

nano ~/printer_data/config/3dwork-autocommit.sh

Ajusta estas variables al principio del fichero:

### Directorio de configuración de Klipper (obligatorio)
config_folder=~/printer_data/config

### Directorio de Klipper (opcional, descomenta si quieres incluirlo)
klipper_folder=~/klipper

### Directorio de Moonraker (opcional)
moonraker_folder=~/moonraker

### Interfaz web — descomenta solo la que uses
mainsail_folder=~/mainsail
#fluidd_folder=~/fluidd

### Rama del repositorio (normalmente main o master — verifica en tu repo)
branch=main

Guarda con Ctrl+X → Y → Enter y dale permisos de ejecución:

chmod +x ~/printer_data/config/3dwork-autocommit.sh

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

# Instala git si no está disponible
sudo apt-get install git -y

# Ve al directorio de configuración
cd ~/printer_data/config

# Inicializa el repositorio local
git init

# Configura tu identidad (git lo requiere para los commits)
git config --global user.email "[email protected]"
git config --global user.name "Tu Nombre"

# Añade el repositorio remoto de GitHub
# Sustituye TU_TOKEN y la URL por los tuyos
git remote add origin https://[email protected]/tu-usuario/tu-repo.git

# Verifica que se añadió correctamente
git remote -v

Haz el primer commit y push:

git branch -M main          # Asegura que la rama se llama main
git add .                   # Añade todos los ficheros al commit
git commit -m "Primer backup"
git push -u origin main     # Sube al repositorio remoto

# Prueba el script para verificar que funciona
sh ~/printer_data/config/3dwork-autocommit.sh

Paso 6 — Crear la macro de Klipper

Añade esto a tu printer.cfg o a un fichero de macros:

[gcode_shell_command backup_cfg_github]
command: sh /home/pi/printer_data/config/3dwork-autocommit.sh
timeout: 30.
verbose: True

[gcode_macro BACKUP_CFG_GITHUB]
description: Sube los ficheros de configuración a GitHub
gcode:
    RUN_SHELL_COMMAND CMD=backup_cfg_github

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:

Ejemplo de consola durante el backup

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):

[gcode_macro PRINT_END]
gcode:
    # ... tu código de fin de impresión ...
    M84                          # Desactiva motores
    BACKUP_CFG_GITHUB            # Backup automático al terminar

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:

sudo apt-get install git -y
cd ~ && git clone https://github.com/Low-Frequency/Klipper-Git-Backup.git
chmod +x ~/Klipper-Git-Backup/*.sh
./Klipper-Git-Backup/kgb.sh

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)

cd ~/printer_data/config
git fetch --all

# Sobreescribe todo el directorio config con el contenido de GitHub
# CUIDADO: esto borra los cambios locales no subidos
git reset --hard origin/main

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:

# 1. Instala las dependencias básicas
sudo apt-get install git -y

# 2. Clona directamente tu repositorio en el directorio de config
# (si el directorio ya existe, hazlo en uno temporal y luego mueve los ficheros)
cd ~
git clone https://github.com/tu-usuario/tu-repo.git printer_data/config

# 3. Reinicia Klipper para que cargue la configuración
sudo systemctl restart klipper
sudo systemctl restart moonraker

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:

cd ~/printer_data/config

# Ver el historial de commits
git log --oneline

# Recuperar printer.cfg de un commit específico (sustituye HASH por el id del commit)
git checkout HASH -- printer.cfg

# O recuperar el fichero tal como estaba hace 3 commits
git checkout HEAD~3 -- printer.cfg

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:

• ¿Tienes una imagen SD reciente del sistema funcionando?

• ¿Está el repositorio GitHub actualizado con el estado actual?

• ¿Está el variables.cfg (z-offset, PA, etc.) incluido en el backup?

• ¿Sabes dónde está guardado el token de GitHub (por si expira)?

• ¿Probaste alguna vez restaurar desde el backup? (hazlo antes de necesitarlo de verdad)