OEPL JSON Preview

Standalone preview tool for OpenEPaperLink JSON templates. Renders templates locally using VLW bitmap fonts (same format as ESP32/TFT_eSPI).

Die Oberfläche liegt als statische Dateien unter static/ (kein Build-Step) und wird vom selben Server ausgeliefert. Die alte eingebettete Oberfläche ist weiterhin unter /legacy erreichbar. Das JSON bleibt Speicherformat; im Editor wird es normalerweise über Ebenenliste/Bühne bearbeitet (JSON-Drawer = Experten-Ansicht).

Features

• Web Editor: Interactive browser-based editor with live preview
• Font Browser: Click any font to see all its characters/symbols
• Command Line: Pipe JSON or read from files
• Uses actual VLW bitmap fonts from OpenEPaperLink
• Supports text alignment (left, center, right)
• Supports colors (black, white, red, yellow)
• Works with any VLW fonts in fonts/ (fonts are not part of the source: their licenses vary)

Requirements

pip install Pillow numpy cairosvg

Container (Podman/Docker)

# Build
podman build -t oepl-manager .

# Run
podman run -p 5000:5000 \
  -v ./fonts_ttf:/app/fonts_ttf \
  -v ./data:/app/data \
  -v ./output:/app/output \
  -v ./icons:/app/icons \
  oepl-manager

Then open http://localhost:5000 in your browser.

Local Usage

Start the web editor directly:

python3 oepl_manager.py

Options:

python3 oepl_manager.py --port 8080        # Custom port
python3 oepl_manager.py --fonts /my/fonts  # Custom fonts directory
python3 oepl_manager.py --icons /my/icons  # Custom icons directory
python3 oepl_manager.py --output /my/out   # Custom output directory

Command Line Usage

# Pipe from a template script
./my-template.sh | python3 json_preview.py

# From JSON file
python3 json_preview.py template.json

# Direct JSON input
python3 json_preview.py --json '[{"text": [10, 10, "Hello", "fonts/bahnschrift20", 1]}]'

# Save to file
./my-template.sh | python3 json_preview.py -o preview.png

# Custom dimensions
python3 json_preview.py -W 296 -H 128 template.json

# List available fonts
python3 json_preview.py --list-fonts

Ausgaben & Zeitplan

Der Zeitplan entscheidet, welche Vorlage an einem Tag gilt (Priorität: konkretes Datum JJJJ-MM-TT > Wochentag+Monat > Wochentag > default). Der Schalter „Vorschau" blendet unter jeder Zuweisung ein kleines Vorschaubild der Vorlage ein (Standard: aus; Klick aufs Bild öffnet die Vorlage im Editor). Die Ausgaben (Tab „Ausgaben") entscheiden, wann und wohin gerendert wird — je Ausgabe eine eigene Bilddatei, also ein eigenes Display. So bleibt die tägliche Standard-Ausgabe (Tag + Datum) unberührt, während weitere Displays unabhängig bespielt werden. Auch hier gibt es einen Schalter „Vorschau" (Standard: aus): Er zeigt je Ausgabe, welche Vorlage heute gerendert würde — Sonder-Regeln und Zeitplan werden dabei genauso aufgelöst wie beim echten Rendern (Einzeltag → Zeitraum → Quelle). Klick aufs Bild öffnet die Vorlage im Editor.

Auslösung (wann erzeugt wird)

• Täglich – eine Uhrzeit pro Tag.
• Mehrere Uhrzeiten – z.B. 06:00, 12:00, 18:00.
• Pro Wochentag (Sonderzeiten) – eigene Uhrzeit(en) je Wochentag; ein Tag ohne Zeiten bleibt aus. Beispiel Wochenend-Display: Fr 17:00, Sa 00:00, So 00:00.
• Intervall – alle n Minuten.
• Wochentags-Filter (bei Täglich/Mehrere/Intervall): Chips Mo–So schränken auf bestimmte Tage ein; keine Auswahl = jeden Tag.

Sonder-Regeln (welche Vorlage — datumsabhängig)

Optional pro Ausgabe. Weisen an bestimmten Tagen eine andere Vorlage zu, in dieser Priorität: Einzeltag → Zeitraum → Quelle.

• Einzeltage (Feiertage) – ein Datum + Vorlage.
• Zeiträume (Ferien) – von–bis + Vorlage.
• Quelle – Standardinhalt: „Zeitplan (heutige Vorlage)", eine feste Vorlage oder „— nichts". Bei „nichts" und keiner passenden Regel wird nichts erzeugt — nützlich, wenn der Normalinhalt (z.B. ein Stundenplan) von einem anderen Programm geschrieben wird und nur an Sonder-Tagen überschrieben werden soll.

Alle Felder sind additiv; bestehende Ausgaben ohne diese Angaben verhalten sich unverändert.

Verbund (zwei gestapelte Displays als eine Fläche)

Hängen zwei Displays direkt übereinander, lassen sie sich im Tab „Verbund" als eine Fläche gestalten: Eine Verbund-Vorlage wird auf einer hohen Leinwand entworfen (oberes Panel + Lücke + unteres Panel, Standard 522×152 + 80 + 152), Elemente dürfen frei über die Displaykante ragen. Der Editor zeigt die Kante als schraffierten Streifen — was dort liegt, ist auf keinem Display sichtbar.

• Lücke = Abstand der beiden sichtbaren Flächen in Display-Pixeln (Rahmen + Montageabstand). Pro Vorlage einstellbar; per Sichtprobe nachjustieren, bis durchlaufende Linien fluchten.
• Ausgabe: Eine Verbund-Ausgabe (Button „Als Ausgabe einrichten") rendert die Vorlage einmal in voller Höhe und schreibt zwei Dateien (oben/unten); die Lücken-Zeilen entfallen. Auslösung/Wochentage/Sonder-Regeln wie bei normalen Ausgaben.
• Variablen ({{TAG}} …) funktionieren unverändert — ein Datum im oberen Bereich bleibt also täglich aktuell.
• Vorlage übernehmen: Bei offener Verbund-Vorlage zeigt der Editor eine zweite Werkzeugzeile, mit der sich gespeicherte (normale) Vorlagen ins obere oder untere Panel kopieren lassen — z. B. ein bestehendes Datums-Template nach oben. Die Elemente werden mit passendem Y-Versatz eingefügt und sind danach frei bearbeitbar. „Panel vorher leeren" (Standard an) entfernt dabei die vorhandenen Elemente im Ziel-Panel; Leeren + Einfügen sind ein Undo-Schritt (Strg+Z).
• Panel als Vorlage speichern: Der umgekehrte Weg — dieselbe Werkzeugzeile speichert die Elemente des oberen oder unteren Panels als eigenständige Einzeldisplay-Vorlage (beim unteren Panel wird der Y-Versatz zurückgerechnet). Mitgenommen wird alles, was sichtbar ins Panel hineinragt — auch ein Hintergrundbild, das über beide Panels läuft, landet also in beiden Panel-Vorlagen und zeigt dort jeweils den richtigen Ausschnitt. Die Panel-Vorlage merkt sich ihre Herkunft: Wird der Verbund später geändert und gespeichert, werden daraus abgeleitete Panel-Vorlagen automatisch mit aktualisiert (die Statusmeldung zählt sie auf). Zeitplan-Zuordnung und Wochentag/Monats-Attribute der Panel-Vorlage bleiben dabei erhalten. Die entstandene Vorlage ist eine ganz normale Vorlage: Sie lässt sich im Zeitplan zuordnen und von einer Ausgabe mit eigenem Dateinamen schreiben. Beim Überschreiben einer bestehenden Vorlage bleiben deren Wochentag/Monats-Attribute (und damit die Zeitplan-Zuordnung) erhalten.
• „Ausgeben" im Editor: Bei offener Verbund-Vorlage schreibt der Button zwei Panel-Dateien statt einer. Existiert bereits eine Verbund-Ausgabe für die Vorlage, werden deren Dateinamen und Zielordner übernommen, sonst verbund_oben.jpg/verbund_unten.jpg im Standard-Ausgabeordner.
• Verbund verlassen: „Neu" oder das Laden einer normalen Vorlage beendet den Verbund-Modus — die Leinwand springt automatisch aufs Einzeldisplay zurück (Standard 522×152). Eigene Sondermaße bleiben dabei erhalten.

Technisch ist eine Verbund-Vorlage eine normale Vorlage mit Zusatzfeld verbund: {width, top, bottom, gap}; ein Verbund-Job hat verbund: true und output_filename (oben) + output_filename_bottom (unten).

AP-Betrieb & Troubleshooting

Wie die gerenderten Bilder tatsächlich auf die Displays kommen (Yellow AP, Latenz, Sofort-Update per tag_cmd, hängende Übertragungen neu starten, Status prüfen): siehe AP-BETRIEB.md.

Dazu gehört oepl_ap.py — ein CLI-Tool ohne Abhängigkeiten für einen Rechner im AP-LAN: status (Batterie, letztes Bild, Warnungen), refresh, watch, restart, heal. Details im Betriebshandbuch.

JSON Template Format

[
  {"text": [x, y, "content", "fonts/fontname", color, align]},
  {"box": [x, y, width, height, color]},
  {"line": [x1, y1, x2, y2, color]}
]

Colors: 0=white, 1=black, 2=red, 3=yellow

Alignment: 0=top-left, 1=top-center, 2=top-right

Template scripts

Any script that prints a JSON template can feed the preview, e.g. one that builds a daily date tag with weekday, date and an icon.

VLW Font Format

VLW is Processing's bitmap font format, used by TFT_eSPI on ESP32:

• Header: 24 bytes (glyph count, version, height, ascent, descent)
• Glyph data: 28 bytes each (unicode, dimensions, offsets)
• Bitmap: 1 byte per pixel (alpha value)

Credits

• Based on OpenEPaperLink
• VLW fonts created with Processing
• TFT_eSPI library by Bodmer

License

GPL-3.0-or-later (see LICENSE)