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.

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

Verwendung

Nach dem Start ist die API unter http://<HA-IP>:<port> erreichbar. Die interaktive Swagger-Dokumentation ist unter http://<HA-IP>:<port>/docs verfügbar.

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).
• 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.