Zum Inhalt

Druckserver

Andere Programme und KI-Assistenten können über Tavletta Etiketten drucken, ohne das Fenster zu öffnen: tavletta serve bietet eine Web-Schnittstelle für Programme (REST API), tavletta mcp verbindet KI-Assistenten wie Claude.

Starten

tavletta serve --labels-dir ~/Labels
  • Der Server lauscht auf http://127.0.0.1:8790, nur auf diesem Computer.
  • Nur Etikettendateien im Etikettenordner (und seinen Unterordnern) können verwendet werden, mit ihren Datendateien. Ohne --labels-dir: ~/.local/share/tavletta/labels.
  • Druckeradresse, Sicherheitsabstand und Druckeinstellungen sind die in der App eingestellten.
  • --mcp fügt die Verbindung für KI-Assistenten unter /mcp hinzu.
  • Beenden mit Ctrl+C: Wartende Aufträge werden abgebrochen, ein Etikett, das gerade gedruckt wird, wird fertig gedruckt und der Zähler gespeichert.

Drucker

  • Die Drucker in einer Datei printers.toml benennen und den Server mit --printers printers.toml starten. Programme wählen einen Drucker dann über seinen Namen; andere Drucker lassen sich nicht verwenden.
[printers.shipping]
backend = "cab"
host = "cab-shipping.example.com"
description = "Shipping labels"
location = "Warehouse, gate 2"
default = true
max_copies = 200
  • backend ist das Druckermodell, host die Adresse des Druckers.
  • Die Einstellungen des Druckers, wie in den Druckereinstellungen der App, kommen in eine eigene Tabelle; nur die, die das Modell hat:
[printers.inventory]
backend = "cab"
host = "cab-it.example.com"

[printers.inventory.settings]
method = "transfer"
upside_down = true
  • method ist die Druckverfahren (printer, transfer, direct), upside_down Kopfüber drucken; weitere sind quality, chain, high_res, feed_mm, darkness, media und outlines, siehe docs/server.md.
  • Fehler in der Datei werden beim Start des Servers genannt.
  • Die Druckerliste zeigt jeden Drucker mit seinem Zustand.
  • Der Server sucht nur dann im Netzwerk nach Druckern, wenn er mit --discover gestartet wird.

Zugangstoken

  • Ein Token erstellen und geheim halten:
mkdir -p ~/.config/tavletta
openssl rand -hex 32 > ~/.config/tavletta/token
chmod 600 ~/.config/tavletta/token
tavletta serve --token-file ~/.config/tavletta/token
  • Jede Anfrage braucht dann den Header Authorization: Bearer <token>.
  • Um auf einer anderen Adresse zu lauschen (--host 0.0.0.0), ist ein Token nötig. Für andere Computer einen Reverse Proxy mit HTTPS davorschalten.
  • --allow-printer beschränkt die Druckeradressen, zum Beispiel --allow-printer '*.local'.

Zugang pro Gerät

  • Mehrere Geräte oder Personen bekommen je ein Token mit einer Rolle:
tavletta token new shipping-pc --role print --tokens ~/.config/tavletta/tokens.toml
tavletta serve --printers printers.toml --tokens ~/.config/tavletta/tokens.toml
  • Das Token wird nur einmal gezeigt; die Datei speichert nur einen Fingerabdruck (Hash) davon.
  • preview listet nur auf und zeigt Vorschauen, print druckt auch und verfolgt seine eigenen Aufträge, admin sieht alle Aufträge und kann sie abbrechen.
  • --printer shipping beschränkt ein Token auf diesen Drucker, --expires 2027-12-31 auf ein Datum.
  • Um ein Token zurückzuziehen, seinen Eintrag in tokens.toml löschen. Der Server bemerkt das sofort.

Programme (REST API)

  • Die Beschreibung aller Anfragen: die API-Referenz, und für Programme http://127.0.0.1:8790/api/v1/openapi.json (OpenAPI 3.1, mit jedem gültigen Token).
  • GET /api/v1/labels listet die Etiketten auf, GET /api/v1/labels/<name> zeigt, was sich ausfüllen lässt: Elementnamen, Variablen und Spalten.
  • POST /api/v1/preview gibt das Etikett als PNG-Bild zurück.
  • POST /api/v1/print stellt einen Druckauftrag in die Warteschlange; GET /api/v1/jobs/<id> zeigt seinen Stand, DELETE bricht ihn zwischen zwei Etiketten ab.
  • Jeder Drucker druckt einen Auftrag nach dem anderen.
  • Meldungen kommen in der Sprache des Headers Accept-Language.
  • Ohne Zugangstoken brauchen Anfragen, die Drucker abfragen, den Header X-Tavletta-Request: 1, damit keine Webseite sie senden kann.
curl -H "Authorization: Bearer $(cat ~/.config/tavletta/token)" \
     -H 'Content-Type: application/json' \
     -d '{"label": "serial", "data_rows": [{"Code": "B-07-1", "Name": "Tea", "Shelf": "B-07", "Box": "1"}], "copies": 2}' \
     http://127.0.0.1:8790/api/v1/print
  • set füllt Elemente über ihren Namen und Variablen wie {=lot} aus, wie auf der Kommandozeile.
  • Serienetiketten: "data_rows", ein Objekt pro Etikett mit jeder Spalte, die das Etikett verwendet ([{"Name": "Tea", …}, {"Name": "Rice", …}]), oder "data_file" mit einer Tabelle im Etikettenordner.
  • Ein Etikett aus einem anderen Programm, zum Beispiel einem Inventar: die Felder als eine Datenzeile, der Drucker mit seinem Namen.
curl -H "Authorization: Bearer $(cat ~/.config/tavletta/token)" \
     -H 'Content-Type: application/json' \
     -d '{"label": "asset-tag", "printer": "it-cab", "copies": 1,
          "data_rows": [{"AssetNumber": "100001"}]}' \
     http://127.0.0.1:8790/api/v1/print

  • Die ganze Anleitung, mit Serien, Wiederholungen und Code in Python und C#: Ein Inventarprogramm anbinden.

  • {=counter}: Der Server speichert die nächste Nummer in der Etikettendatei. Ein Programm, das seine eigenen Nummern führt, schickt die Nummer in der Datenzeile oder als "counter_start" mit "no_save_counter": true.

KI-Assistenten (MCP)

Der Assistent kann die Etiketten und Drucker auflisten, eine Vorschau zeigen, drucken und Druckaufträge verfolgen oder abbrechen. Je nach seinen Einstellungen fragt er, bevor er ein Werkzeug verwendet.

Claude Code:

claude mcp add tavletta -- tavletta mcp --labels-dir ~/Labels

Claude Desktop, in claude_desktop_config.json:

{
  "mcpServers": {
    "tavletta": {
      "command": "tavletta",
      "args": ["mcp", "--labels-dir", "/home/me/Labels"]
    }
  }
}
  • Über das Netzwerk: tavletta serve --mcp und die Adresse http://127.0.0.1:8790/mcp mit dem Zugangstoken als Header Authorization: Bearer.
  • Drucken verbraucht echte Etiketten: zuerst nach einer Vorschau fragen.

Server und Container

  • Auf einem Server für eine Firma: Serverinstallation, mit Docker Compose (packaging/docker/compose.yaml) oder als Systemdienst (packaging/systemd/tavletta-server.service).
  • Als Dienst Ihres Benutzers auf einem Desktop: packaging/systemd/tavletta.service (Anleitung in der Datei).
  • Technische Details und Sicherheit: docs/server.md.

Container-Image

Der Druckserver wird als Container-Image für amd64 und arm64 veröffentlicht (auch für einen Raspberry Pi mit 64-Bit-System):

docker pull ghcr.io/joshii-h/tavletta:1.1.0
  • 1.1.0 ist eine Version, 1.1 die neueste Fehlerbehebungsversion von 1.1, latest die neueste Version. edge ist der Stand der Entwicklung, keine Version.
  • packaging/docker/compose.yaml verwendet das veröffentlichte Image: docker compose pull, dann docker compose up -d.
  • Um das Image stattdessen selbst zu bauen, compose.build.yaml hinzufügen: docker compose -f compose.yaml -f compose.build.yaml up -d --build.
  • Das Image läuft ohne Root-Rechte und meldet Docker seinen Zustand (HEALTHCHECK).
  • Prüfen, dass ein Image aus dem Repository von Tavletta gebaut wurde, mit der GitHub CLI oder cosign:
gh attestation verify oci://ghcr.io/joshii-h/tavletta:1.1.0 --repo joshii-h/tavletta
cosign verify ghcr.io/joshii-h/tavletta:1.1.0 \
    --certificate-oidc-issuer https://token.actions.githubusercontent.com \
    --certificate-identity-regexp '^https://github\.com/joshii-h/tavletta/\.github/workflows/docker\.yml@refs/tags/v'