157 lines
4.9 KiB
Markdown
157 lines
4.9 KiB
Markdown
# 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.
|
||
|
||
```bash
|
||
curl http://homeassistant.local:8765/status
|
||
```
|
||
|
||
Antwort:
|
||
```json
|
||
{
|
||
"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).
|
||
|
||
```bash
|
||
curl http://homeassistant.local:8765/info
|
||
```
|
||
|
||
#### `POST /print/text`
|
||
|
||
Druckt ein Textetikett.
|
||
|
||
```bash
|
||
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).
|
||
|
||
```bash
|
||
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
|
||
|
||
```yaml
|
||
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`:
|
||
```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.
|