MalDruck — Ausmalbilder-Drucker

Ein self-hosted Ausmalbilder-Manager mit Web-Galerie, Druckfunktion und Home Assistant Integration. Perfekt für Kinder, die selbstständig Ausmalbilder drucken wollen.

Home Assistant Integration: homeassistant-maldruck — HACS-installierbar, keine YAML-Konfiguration nötig.

Features

• Galerie — Thumbnail-Vorschau aller PDFs, Suche, Kategoriefilter
• Zufallsdruck — Smart Random mit Wiederholungsvermeidung
• Netzwerkdrucker — CUPS-Integration, automatische Druckererkennung, Schlafmodus-Wecken via TCP
• Job-Tracking — Live-Status des Druckauftrags direkt in der UI
• Drucker-Diagnose — Port-Erreichbarkeit, CUPS-Status und Fehlerlog auf einen Blick
• Upload — PDFs per Drag & Drop oder Datei-Dialog hochladen
• Favoriten — Lieblingsbilder markieren und schnell wiederfinden
• Multi-Auswahl — Mehrere Bilder auf einmal drucken oder verwalten
• Umbenennen / Verstecken — Eigene Anzeigenamen, unerwünschte Bilder ausblenden
• Tageslimit — Konfigurierbares Maximum an Ausdrucken pro Tag
• Statistiken — Heatmap, Leaderboard, Druckverlauf
• Home Assistant — REST-API, Webhooks mit TTS-Feedback, Voice Commands, Smart Buttons
• PWA — Auf dem Homescreen installierbar, offline-fähig
• Kategorien — Automatisch aus Ordnerstruktur (Tiere/, Prinzessinnen/, ...)

Schnellstart

1. Ordnerstruktur vorbereiten

Lege deine Ausmalbilder als PDFs ab:

/mnt/nfs/ausmalbilder/
├── Tiere/
│   ├── katze.pdf
│   └── hund.pdf
├── Prinzessinnen/
│   └── schloss.pdf
└── mandala.pdf          ← landet in "Allgemein"

2. docker-compose.yml anpassen

Wichtige Einstellungen:

environment:
  - API_TOKEN=dein-sicheres-token-hier   # ÄNDERN!
  - PRINTER_URI=ipp://192.168.1.XXX:631/ipp/print
  - PRINTER_NAME=HP_P1606dn
  - DAILY_LIMIT=10

volumes:
  - /mnt/nfs/ausmalbilder:/data/coloring-pages:ro

3. Starten

docker compose up -d

• Web-UI: http://server-ip/
• CUPS Admin: http://server-ip:6310 (optionales Drucker-Setup)

4. Drucker prüfen

Öffne die Web-UI → ⚙️ Einstellungen → Drucker Diagnose → "Diagnose starten"

Dort siehst du sofort ob der Drucker erreichbar ist, CUPS-Status und eventuelle Fehlermeldungen.

Home Assistant Integration

REST Command

# configuration.yaml
rest_command:
  maldruck_print_random:
    url: "http://server-ip/api/print/random"
    method: POST
    headers:
      X-API-Token: "dein-token"

  maldruck_print_category:
    url: "http://server-ip/api/print/random?category={{ category }}"
    method: POST
    headers:
      X-API-Token: "dein-token"

Smart Button (Beispiel IKEA TRADFRI)

automation:
  - alias: "Ausmalbild-Button"
    trigger:
      - platform: device
        device_id: "BUTTON_ID"
        domain: zha
        type: remote_button_short_press
        subtype: button_1
    action:
      - action: rest_command.maldruck_print_random

Voice Commands (HA Assist)

Kopiere homeassistant/custom_sentences/de/maldruck.yaml nach:

config/custom_sentences/de/maldruck.yaml

Beispielbefehle:

• "Drucke ein Ausmalbild"
• "Ich will ein Tier ausmalen"
• "Drucke ein Prinzessinnenbild"
• "Wie viele Ausmalbilder gibt es?"

Webhook / TTS-Feedback

Nach jedem Druck sendet MalDruck optional einen POST-Request an Home Assistant:

{
  "page_name": "Katze mit Hut",
  "category": "Tiere",
  "prints_today": 3,
  "message_tts": "Ich drucke dir jetzt ein Ausmalbild! Viel Spaß beim Ausmalen!"
}

Konfiguration in docker-compose.yml:

- HA_WEBHOOK_URL=http://homeassistant.local:8123/api/webhook/maldruck-print

Vollständiges HA-Beispiel mit TTS und Limit-Ansage: homeassistant/maldruck.yaml

API Reference

Endpoint	Methode	Beschreibung
/api/pages	GET	Alle Ausmalbilder auflisten
/api/pages?category=Tiere	GET	Nach Kategorie filtern
/api/pages?search=katze	GET	Volltextsuche
/api/pages/{id}/preview	GET	Thumbnail als JPEG
/api/pages/{id}/pdf	GET	PDF herunterladen
/api/print/random	POST	Zufälliges Bild drucken
/api/print/random?category=X	POST	Zufällig aus Kategorie
/api/print/{id}	POST	Bestimmtes Bild drucken
/api/print/batch	POST	Mehrere Bilder drucken
/api/print/job/{job_id}	GET	Druckauftrag-Status abfragen
/api/printer/diagnostics	GET	Drucker-Diagnose (Ports, CUPS, Fehlerlog)
/api/printers	GET	Drucker auflisten
/api/printers/default	PUT	Standarddrucker setzen
/api/stats	GET	Statistiken
/api/heatmap	GET	Druckdaten für Kalender-Heatmap
/api/leaderboard	GET	Meistgedruckte Bilder
/api/history	GET	Druckverlauf
/api/health	GET	Health-Check
/api/config	GET/PUT	Konfiguration lesen/schreiben
/api/rescan	POST	Bilder neu scannen
/api/categories	GET	Kategorien auflisten
/api/upload	POST	PDF hochladen
/api/backup	GET	Konfiguration als JSON exportieren

Auth: Alle schreibenden Endpoints erwarten den Header X-API-Token.

Umgebungsvariablen

Variable	Default	Beschreibung
API_TOKEN	—	API-Authentifizierung (unbedingt setzen!)
DAILY_LIMIT	10	Max. Drucke pro Tag (0 = unlimitiert)
PRINTER_URI	—	IPP-URI des Druckers, z.B. ipp://10.0.0.41:631/ipp/print
PRINTER_NAME	HP_P1606dn	Druckername in CUPS
CUPS_PASSWORD	maldruck-cups	Passwort für CUPS Web-Interface (user: root)
LOG_LEVEL	INFO	Log-Verbosity: DEBUG, INFO, WARNING, ERROR
HA_WEBHOOK_URL	—	Home Assistant Webhook nach jedem Druck (optional)

Troubleshooting

Drucker druckt nicht:

Öffne die Drucker-Diagnose in der Web-UI (Einstellungen → Drucker Diagnose). Oder direkt im Container:

docker exec maldruck lpstat -p -d
docker exec maldruck cancel -a HP_P1606dn   # Stuck jobs löschen

Thumbnails fehlen:

docker exec maldruck pdftoppm -jpeg -f 1 -l 1 /data/coloring-pages/test.pdf /tmp/test

NFS-Mount nicht erreichbar:

ls /mnt/nfs/ausmalbilder/
docker exec maldruck ls /data/coloring-pages/

CUPS Web-Interface: http://server-ip:6310 — Benutzer: root, Passwort: Wert von CUPS_PASSWORD.

Kein Speicherplatz beim Docker-Build:

docker system prune -af

Lizenz

MIT — Viel Spaß beim Ausmalen!