Fichero/fichero_printer/DOCS.md

Fichero Printer – Home Assistant Add-on

Ein HTTP-REST-API-Server für den Fichero D11s (auch bekannt als AiYin D11s) Thermodrucker. Das Add-on ermöglicht das Drucken von Textetiketten und Bildern direkt aus Home Assistant-Automationen, Skripten oder externen Anwendungen.

Herkunft / Credits

• Originalentwickler / Ursprungsprojekt: https://github.com/0xMH/fichero-printer
• Diese Variante wurde zusätzlich mit AI-unterstützten Erweiterungen ergänzt.

Voraussetzungen

• Fichero D11s / AiYin D11s Drucker
• Ein Bluetooth-Adapter, der vom Home Assistant OS erkannt wird
• Der Drucker muss eingeschaltet und in Reichweite sein

Konfiguration

Option	Standard	Beschreibung
port	8765	Port des REST-API-Servers (auch im „Port-Mapping" oben anpassen)
ble_address	(leer)	Feste BLE-Adresse des Druckers (z.B. AA:BB:CC:DD:EE:FF). Leer lassen für automatischen Scan.
transport	ble	Verbindungsart: ble (Bluetooth Low Energy) oder classic (RFCOMM)
channel	1	RFCOMM-Kanal – nur relevant bei transport: classic (bei Fehlern werden zusätzlich typische Kanäle getestet)

Verwendung

Das Add-on ist nach dem Start auf zwei Arten erreichbar:

1. Home Assistant UI (Ingress): In der Add-on-Seite auf "Öffnen" klicken. Dort erscheint direkt das Webinterface zum Abrufen von Status/Info sowie zum Drucken von Text und Bildern.
2. Direkt per Port im Netzwerk: http://<HA-IP>:<port> (z.B. http://homeassistant.local:8765).

Hinweis: Die API-Dokumentation bleibt unter /docs erreichbar.

Endpunkte

GET /status

Gibt den aktuellen Druckerstatus zurück.

curl http://homeassistant.local:8765/status

Antwort:

{
  "ok": true,
  "printing": false,
  "cover_open": false,
  "no_paper": false,
  "low_battery": false,
  "overheated": false,
  "charging": false,
  "raw": 0
}

GET /info

Gibt Geräteinformationen zurück (Modell, Firmware, Seriennummer, Akkustand).

curl http://homeassistant.local:8765/info

POST /print/text

Druckt ein Textetikett.

curl -X POST http://homeassistant.local:8765/print/text \
  -F text="Hallo Welt" \
  -F density=2 \
  -F paper=gap \
  -F label_length=30

Feld	Standard	Beschreibung
text	–	Pflichtfeld. Zu druckender Text
density	2	Druckdichte: 0=hell, 1=mittel, 2=dunkel
paper	gap	Papierart: gap, black, continuous
copies	1	Anzahl der Kopien (1–99)
font_size	30	Schriftgröße in Punkt
label_length	–	Etikettenlänge in mm (überschreibt label_height)
label_height	240	Etikettenhöhe in Pixel

POST /print/image

Druckt eine Bilddatei (PNG, JPEG, BMP, GIF, TIFF, WEBP).

curl -X POST http://homeassistant.local:8765/print/image \
  -F file=@etikett.png \
  -F density=2 \
  -F dither=true \
  -F label_length=40

Feld	Standard	Beschreibung
file	–	Pflichtfeld. Bilddatei
density	2	Druckdichte: 0=hell, 1=mittel, 2=dunkel
paper	gap	Papierart: gap, black, continuous
copies	1	Anzahl der Kopien (1–99)
dither	true	Floyd-Steinberg-Dithering aktivieren
label_length	–	Max. Etikettenlänge in mm
label_height	240	Max. Etikettenhöhe in Pixel

Fehlercodes

Status	Bedeutung
404	Drucker nicht gefunden (BLE-Scan fehlgeschlagen oder Adresse ungültig)
422	Ungültige Parameter oder leere Datei
502	Kommunikationsfehler mit dem Drucker
504	Drucker hat nicht rechtzeitig geantwortet

Home Assistant Automation – Beispiel

alias: Etikett drucken
trigger:
  - platform: state
    entity_id: input_text.etikett_text
action:
  - service: rest_command.fichero_print_text
    data:
      text: "{{ states('input_text.etikett_text') }}"

In configuration.yaml:

rest_command:
  fichero_print_text:
    url: "http://localhost:8765/print/text"
    method: POST
    content_type: "application/x-www-form-urlencoded"
    payload: "text={{ text }}&density=2&label_length=30"

Hinweise zur Bluetooth-Verbindung

• BLE (Standard): Das Add-on benötigt Zugriff auf BlueZ über D-Bus (host_dbus: true). Home Assistant OS stellt BlueZ automatisch bereit.
• Classic Bluetooth (RFCOMM): Nur unter Linux verfügbar. Erfordert die direkte Bluetooth-Adresse (kein automatischer Scan möglich) und Container- Rechte für Bluetooth-Sockets (NET_ADMIN + NET_RAW).
• Das Add-on läuft dafür mit full_access, weil einige Home-Assistant-Hosts RFCOMM trotz gesetzter Capabilities sonst weiterhin blockieren.
• Wenn die BLE-Adresse bekannt ist, diese in der Konfiguration eintragen – das beschleunigt den Verbindungsaufbau erheblich (kein Scan nötig).
• Der Drucker muss eingeschaltet sein, bevor eine Anfrage gestellt wird. Es gibt keine persistente Verbindung – jede Anfrage verbindet sich neu.