# 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.

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