Múltiples instancias Klipper

Una de las ventajas de la arquitectura de Klipper es que el host puede controlar varias impresoras al mismo tiempo. Cada impresora necesita su propia instancia de Klipper y Moonraker, pero todas comparten el mismo SBC, la misma red y pueden gestionarse desde una sola interfaz web.

Esta guía cubre el proceso completo: instalación, gestión de serial USB, configuración de interfaces y las preguntas más frecuentes.

Antes de empezar — consideraciones importantes

• Cuantas más instancias corran en el mismo host, más recursos consumes. Un problema de hardware (sobrecalentamiento, corte de luz, SD corrupta) afectará a todas las impresoras simultáneamente.

• El host necesita estar correctamente dimensionado. Una Raspberry Pi 3B+ puede gestionar 2 impresoras sencillas, pero 3 o más instancias activas con cámara y timelapse requieren al menos una Raspberry Pi 4 con 2 GB de RAM o superior.

• Si las impresoras son críticas o para producción, valora tener hosts separados.

Requisitos previos

• KIAUH instalado y funcionando en tu host. Si aún no lo tienes, sigue la guía de instalación.

• Punto de partida limpio: instalación recién hecha, o instalación existente completamente actualizada con todas las instancias funcionando.

• Python 3.8 o superior (KIAUH v6+ lo requiere y lo verifica automáticamente).

KIAUH v6 (lanzado en octubre 2025) es una reescritura completa del instalador en Python. Si tienes una versión anterior basada en bash, actualiza con:

cd ~/kiauh && git pull

El proceso de instalación de múltiples instancias es funcionalmente el mismo, aunque la interfaz de menús puede verse diferente a las capturas de esta guía.

Nomenclatura — nombres de instancia

Cuando KIAUH instala varias instancias, te permite elegir entre dos modos:

• Nombres por defecto (numérico): las instancias se llaman printer, printer_2, printer_3... Los directorios de datos serán ~/printer_data/, ~/printer_2_data/...

• Nombres personalizados: puedes poner nombres descriptivos como voron, ender3, artillery. Los directorios serán ~/voron_data/, ~/ender3_data/...

Recomendación: usa nombres personalizados siempre que puedas. Hace que todo sea mucho más fácil de identificar: servicios, logs, configuraciones y URLs tienen el nombre de la impresora.

Estructura de directorios

Tras instalar múltiples instancias con KIAUH, cada instancia tiene su propio directorio de datos con esta estructura:

~/voron_data/
├── config/          ← aquí van los .cfg (printer.cfg, moonraker.conf...)
├── gcodes/          ← archivos de impresión subidos
├── logs/            ← klippy.log, moonraker.log...
├── comms/           ← sockets de comunicación interna
├── database/        ← base de datos de Moonraker (historial, etc.)
└── systemd/         ← referencias a servicios systemd

~/ender3_data/
├── config/
├── gcodes/
├── logs/
├── comms/
└── database/

Cada instancia es completamente independiente en cuanto a datos, configuraciones y logs.

Puertos asignados por instancia

KIAUH asigna los puertos automáticamente según el orden de instalación:

Instancia	Moonraker API	Interfaz web (Nginx)
1ª instancia	7125	80
2ª instancia	7126	81
3ª instancia	7127	82
4ª instancia	7128	83

Para acceder a la segunda impresora desde el navegador: http://IP_DEL_HOST:81

Para ver los puertos activos en cualquier momento, desde SSH:

sudo ss -lntp | grep -E "7125|7126|7127|7128|:80|:81|:82"

O con más detalle:

sudo netstat -ltnp

Servicios systemd

Cada instancia crea sus propios servicios de sistema. Con nombres personalizados:

# Klipper
klipper-voron.service
klipper-ender3.service

# Moonraker
moonraker-voron.service
moonraker-ender3.service

Con nombres por defecto:

klipper.service          # primera instancia
klipper-2.service        # segunda instancia
moonraker.service
moonraker-2.service

Comandos útiles para gestionar instancias individualmente

# Ver estado
sudo systemctl status klipper-voron.service
sudo systemctl status moonraker-voron.service

# Reiniciar una instancia específica
sudo systemctl restart klipper-voron.service
sudo systemctl restart moonraker-voron.service

# Parar una instancia (sin afectar a las demás)
sudo systemctl stop klipper-ender3.service

# Ver logs en tiempo real de una instancia
journalctl -fu klipper-voron.service
journalctl -fu moonraker-ender3.service

---

Instalación paso a paso con KIAUH

Paso 1 — Instalar varias instancias de Klipper

Lanza KIAUH desde SSH:

./kiauh/kiauh.sh

En el menú inicial, KIAUH muestra el número de instancias instaladas y la versión de cada componente.

• Selecciona #1 Install

• Selecciona #1 Klipper

  • Elige la versión de Python (selecciona Python 3, que es la única opción válida actualmente)

  • Indica el número de instancias que quieres instalar

  • KIAUH te preguntará si quieres personalizar los nombres — di que sí y pon nombres descriptivos

Klipper se descarga e instala para cada instancia. Al terminar vuelves al menú principal.

Paso 2 — Instalar varias instancias de Moonraker

• Selecciona de nuevo #1 Install

• Selecciona #2 Moonraker

  • KIAUH te preguntará el número de instancias. Debe coincidir con el de Klipper (el menú ya te muestra las instancias existentes como referencia).

Al terminar, KIAUH muestra las IPs y puertos asignados a cada instancia de Moonraker:

Anota estos datos — los necesitarás para configurar las interfaces web.

Paso 3 — Instalar la interfaz web

Tienes dos opciones:

Opción A — Una interfaz compartida (recomendada)

Instala Mainsail o Fluidd una sola vez. Desde esa interfaz puedes gestionar todas las impresoras añadiéndolas como impresoras adicionales (ver sección de gestión más abajo). Es la opción más limpia y consume menos recursos.

Opción B — Una interfaz por instancia

Instala Mainsail o Fluidd tantas veces como instancias, cada una en su propio puerto. Útil si diferentes personas deben controlar impresoras distintas de forma independiente.

Para instalar una segunda interfaz: selecciona #1 Install → #3 Mainsail (o Fluidd) y repite el proceso.

---

El problema del serial USB con electrónicas idénticas

Esta es la pregunta más frecuente cuando se configuran múltiples instancias: si tengo dos impresoras con la misma placa (por ejemplo, dos Ender 3 con placa Creality original), ¿cómo las diferencio?

El problema está en el chip USB. Muchas placas económicas usan chips CH340 que no tienen un número de serie único grabado. Cuando Klipper busca la MCU por by-id, ambas placas tienen el mismo identificador y no sabe a cuál conectarse.

Tienes tres soluciones:

Solución 1 — Serial by-path (más sencilla)

En lugar de usar el ID del dispositivo, usas el puerto USB físico del host. El sistema operativo asigna un path diferente a cada puerto, independientemente del dispositivo conectado.

# Ver los paths disponibles
ls /dev/serial/by-path/*

Ejemplo de resultado:

/dev/serial/by-path/platform-fd500000.pcie-pci-0000:01:00.0-usb-0:1.1:1.0-port0
/dev/serial/by-path/platform-fd500000.pcie-pci-0000:01:00.0-usb-0:1.2:1.0-port0

En el printer.cfg de cada impresora:

# printer.cfg — impresora 1 (conectada al puerto USB físico 1)
[mcu]
serial: /dev/serial/by-path/platform-fd500000.pcie-pci-0000:01:00.0-usb-0:1.1:1.0-port0

# printer.cfg — impresora 2 (conectada al puerto USB físico 2)
[mcu]
serial: /dev/serial/by-path/platform-fd500000.pcie-pci-0000:01:00.0-usb-0:1.2:1.0-port0

Importante con by-path: cada impresora debe estar siempre conectada al mismo puerto USB físico del host. Si cambias el cable a otro puerto, el path cambia y Klipper no encontrará la MCU. Márcalos con cinta adhesiva o etiquetas para no confundirlos.

Solución 2 — ID USB personalizado en el firmware (más robusta)

Cuando compilas el firmware Klipper para tu MCU, puedes establecer un número de serie USB único para cada placa. Así aunque ambas tengan el mismo chip CH340, Klipper las distingue por el ID personalizado.

En el proceso de compilación del firmware (make menuconfig), busca la sección USB ids y establece un valor único por impresora:

Tras flashear cada MCU con su firmware personalizado, ls /dev/serial/by-id/* mostrará identificadores diferentes y podrás usar by-id con normalidad.

Debes repetir este paso cada vez que recompiles el firmware de la MCU. Si compartes el mismo binario entre dos placas idénticas, volverán a tener el mismo ID.

---

Gestión desde las interfaces web

Mainsail — gestionar múltiples impresoras

Mainsail puede gestionar todas las instancias desde una sola ventana del navegador. Añade cada impresora así:

• Ve a Configuración (icono de engranajes) → Printers

• Pulsa ADD PRINTER e introduce la IP y puerto de Moonraker de cada instancia:

Instancia	Host	Puerto
Impresora 1	IP_HOST	7125
Impresora 2	IP_HOST	7126
Impresora 3	IP_HOST	7127

Una vez añadidas, puedes cambiar entre impresoras desde la barra superior de Mainsail sin cambiar de URL. También puedes acceder a cada una directamente desde http://IP_HOST:80, http://IP_HOST:81, etc.

Fluidd — gestionar múltiples impresoras

Fluidd funciona de forma similar a Mainsail. Ve a Configuración → Impresoras y añade cada instancia con su IP y puerto de Moonraker.

También puedes acceder a cada instancia directamente por su puerto Nginx (http://IP_HOST:80, :81, :82...).

KlipperScreen — múltiples impresoras en pantalla táctil

KlipperScreen puede mostrar y gestionar varias impresoras desde una única pantalla. Edita el fichero KlipperScreen.conf y añade una sección [printer ...] por cada impresora:

# KlipperScreen.conf

[printer Voron 2.4]
moonraker_host: 127.0.0.1
moonraker_port: 7125
# moonraker_api_key: False   # Solo si usas API key

[printer Ender 3]
moonraker_host: 127.0.0.1
moonraker_port: 7126

[printer Artillery Sidewinder]
moonraker_host: 127.0.0.1
moonraker_port: 7127

Si las impresoras están en hosts diferentes, pon la IP correspondiente en moonraker_host.

En KlipperScreen aparecerá un selector en la pantalla de inicio para elegir con qué impresora operar.

---

Configuración de printer.cfg y moonraker.conf

printer.cfg

Cada instancia tiene su propio printer.cfg en ~/NOMBRE_data/config/printer.cfg. No hay nada especial respecto a una instalación única — simplemente configura cada uno para su impresora.

Para impresoras idénticas (misma electrónica, mismo hardware), puedes usar includes compartidos para la configuración común y sobreescribir solo lo que cambia (serial USB, offsets, nombre):

# ~/voron_data/config/printer.cfg
[include ../shared/voron_base.cfg]   # Configuración común
[mcu]
serial: /dev/serial/by-path/...      # Serial específico de esta unidad

Pon los ficheros compartidos en un directorio accesible por ambas instancias, por ejemplo ~/shared_configs/.

moonraker.conf

El fichero moonraker.conf de cada instancia es generado automáticamente por KIAUH con el puerto correcto. Raramente necesitas editarlo, pero es útil entender los parámetros clave:

# ~/voron_data/config/moonraker.conf

[server]
host: 0.0.0.0
port: 7125          # Puerto de esta instancia (7126 para la segunda, etc.)
klippy_uds_address: ~/voron_data/comms/klippy.sock

[authorization]
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
    ::1/128
    FE80::/10
    ::1

cors_domains:
    *.local
    *.lan
    *://app.fluidd.xyz
    *://my.mainsail.xyz

El parámetro klippy_uds_address es el socket Unix que conecta Moonraker con Klipper. Cada instancia tiene el suyo propio en su directorio comms/. KIAUH lo configura correctamente de forma automática — no lo cambies.

Update Manager en Moonraker

Para que Mainsail/Fluidd muestre las actualizaciones disponibles de cada instancia correctamente, el moonraker.conf de cada instancia debe tener su propia sección [update_manager]:

# moonraker.conf — sección de actualizaciones

[update_manager]
# Para Klipper
[update_manager klipper]
type: git_repo
path: ~/klipper
origin: https://github.com/Klipper3d/klipper.git
managed_services: klipper-voron   # Nombre del servicio de esta instancia

# Para Moonraker
[update_manager moonraker]
type: git_repo
path: ~/moonraker
origin: https://github.com/Arksine/moonraker.git
managed_services: moonraker-voron

# Para Mainsail
[update_manager mainsail]
type: web
channel: stable
repo: mainsail-crew/mainsail
path: ~/mainsail

Adapta managed_services al nombre real de tu servicio systemd. Si tus instancias se llaman voron y ender3, los servicios serán klipper-voron y klipper-ender3. Si usas nombres por defecto, será klipper y klipper-2.

Comprueba los nombres exactos con:

sudo systemctl list-units | grep klipper
sudo systemctl list-units | grep moonraker

---

Añadir una instancia adicional a una instalación existente

Si ya tienes una instancia funcionando y quieres añadir una segunda sin reinstalar todo:

• Lanza KIAUH y selecciona #1 Install → #1 Klipper

• KIAUH detecta que ya tienes instancias instaladas y te ofrece añadir una nueva sin tocar las existentes

• Indica el número total de instancias que quieres tener (existentes + nuevas)

• Repite el proceso para Moonraker

KIAUH v6 gestiona esto de forma muy cómoda: detecta automáticamente las instancias existentes y solo instala lo que falta, manteniendo las configuraciones actuales intactas.

---

Cámaras con Crowsnest

Crowsnest gestiona las cámaras USB y las expone como streams MJPEG o HLS accesibles desde Mainsail/Fluidd.

Recomendación para múltiples impresoras: usa una sola instancia de Crowsnest gestionando todas las cámaras. Es más sencillo de mantener y Crowsnest puede manejar varias cámaras sin problema.

En tu crowsnest.conf (en ~/printer_data/config/crowsnest.conf de la primera instancia):

[crowsnest]
log_path: ~/printer_data/logs/crowsnest.log
log_level: verbose

# Cámara para impresora 1
[cam voron]
mode: camera-streamer
enable_rtsp: false
rtsp_port: 8554
port: 8080                              # Puerto del stream de esta cámara
device: /dev/video0
resolution: 1280x720
max_fps: 30

# Cámara para impresora 2
[cam ender3]
mode: camera-streamer
enable_rtsp: false
rtsp_port: 8555
port: 8081                              # Puerto diferente para la segunda cámara
device: /dev/video2
resolution: 1280x720
max_fps: 30

En el moonraker.conf de cada instancia, referencia el stream correcto:

# moonraker.conf de la instancia Voron
[webcam voron_cam]
stream_url: http://127.0.0.1:8080/?action=stream
snapshot_url: http://127.0.0.1:8080/?action=snapshot

# moonraker.conf de la instancia Ender3
[webcam ender3_cam]
stream_url: http://127.0.0.1:8081/?action=stream
snapshot_url: http://127.0.0.1:8081/?action=snapshot

Si necesitas instancias separadas de Crowsnest

Si prefieres instancias independientes (por ejemplo, para que el fallo de una no afecte a las demás), el proceso es manual ya que Crowsnest no tiene soporte nativo multi-instancia en su instalador:

cd ~/crowsnest
make config

El asistente te preguntará el directorio de datos para esta instancia. Repite tantas veces como necesites, luego:

sudo make install

Reinicia el host al terminar y añade la entrada de Update Manager en el moonraker.conf correspondiente.

---

Dimensionamiento del host

Una guía orientativa para no quedarse corto:

Número de instancias	Hardware mínimo	Hardware recomendado
2 impresoras	Raspberry Pi 3B+, 1 GB RAM	Raspberry Pi 4, 2 GB RAM
3-4 impresoras	Raspberry Pi 4, 2 GB RAM	Raspberry Pi 4, 4 GB RAM
5+ impresoras	Raspberry Pi 4/5, 4 GB RAM	Raspberry Pi 5, 8 GB RAM

Estos valores asumen impresoras en operación normal. Si añades cámaras con timelapse, Input Shaper en curso o compilación de firmware simultánea, multiplica los requisitos.

Puedes monitorizar la carga del sistema con:

# Carga de CPU y memoria en tiempo real
htop

# Carga de CPU promedio
uptime

# Uso de memoria
free -h

# Temperatura (en Raspberry Pi)
vcgencmd measure_temp

Si el host supera el 80% de CPU de forma sostenida durante una impresión, aumentas el riesgo de que Klipper pierda el timing de pasos y la impresión falle o se descalibre. Monitoriza antes de poner impresoras en producción.

---

Acceso remoto con múltiples instancias

Si usas OctoEverywhere o Obico para acceso remoto, cada instancia de Moonraker requiere su propio registro. El proceso es el mismo que con una sola instancia, pero repitiendo el emparejamiento para cada puerto.

Para OctoEverywhere:

• Ve a http://IP_HOST:80 (instancia 1) y sigue el proceso de enlace

• Ve a http://IP_HOST:81 (instancia 2) y repite

Cada instancia tendrá su propio enlace de acceso remoto independiente.

---

Troubleshooting — Problemas frecuentes

Klipper no arranca en una instancia

# Ver el log de errores de la instancia
journalctl -fu klipper-voron.service
# o directamente
tail -f ~/voron_data/logs/klippy.log

Los errores más comunes son:

• Serial no encontrado: el cable USB no está conectado, el path by-path cambió porque se conectó a otro puerto, o el ID by-id es incorrecto.

• Error de configuración: algún parámetro de printer.cfg tiene un error de sintaxis. El log lo indica con el fichero y la línea exacta.

• Puerto ocupado: otro proceso ya usa el socket de comunicación. Reinicia ambos servicios (klipper y moonraker) de esa instancia.

Confundo qué serial pertenece a qué impresora

Con by-path, identifica cada puerto físico USB del host y etiquétalo. Para by-id con firmware personalizado, documenta qué ID pusiste en cada placa.

Un truco: desconecta todas las placas excepto una y lanza ls /dev/serial/by-id/* — solo aparecerá la que dejaste conectada. Repite para cada una.

Moonraker no conecta con Klipper en una instancia

Verifica que el socket klippy_uds_address en moonraker.conf apunta al directorio correcto de esa instancia:

# Debe existir este fichero cuando Klipper está corriendo
ls ~/voron_data/comms/klippy.sock

Si no existe pero Klipper está corriendo, hay un problema en la ruta configurada. Revisa moonraker.conf de esa instancia.

Una interfaz web muestra la impresora equivocada

Comprueba a qué puerto Moonraker estás conectando. La instancia 1 usa 7125, la 2 usa 7126. En Mainsail/Fluidd, ve a la configuración de impresoras y verifica que cada entrada apunta al puerto correcto.

Tras actualizar Klipper, solo se actualiza una instancia

Verifica que el managed_services en la sección [update_manager] de cada moonraker.conf tiene el nombre correcto del servicio systemd de esa instancia.

Los logs crecen mucho con varias instancias

Moonraker gestiona la rotación de logs automáticamente. Si los logs son excesivamente grandes, puedes reducir el nivel de verbosidad en el moonraker.conf:

[server]
log_level: warning   # en lugar de info o debug

---

Checklist de verificación final

Antes de dar por buena la instalación múltiple, verifica:

• Cada instancia de Klipper tiene su propio servicio systemd activo (sudo systemctl status klipper-NOMBRE.service)

• Cada instancia de Moonraker está corriendo en su puerto correcto (sudo ss -lntp | grep 712)

• Cada printer.cfg usa el serial correcto para su MCU (verificado con QUERY_ENDSTOPS o M115)

• La interfaz web puede acceder a cada instancia por separado

• Las cámaras muestran la imagen de la impresora correcta

• El Update Manager en Moonraker lista correctamente los componentes de cada instancia

• Has probado un print de prueba corto en cada impresora antes de poner en producción