feat: Add Fichero D11s thermal label printer support with REST API and CLI

- Implemented a new module for the Fichero D11s thermal label printer, including BLE and Classic Bluetooth interfaces.
- Created a REST API using FastAPI to manage printer status, info, and printing tasks (text and images).
- Developed a CLI for direct printer interaction, allowing users to print text and images, check status, and modify settings.
- Added image processing capabilities for converting text and images to the required format for printing.
- Introduced error handling for printer operations and connection management.
- Included a shell script for running the API server with configurable parameters.
- Added English translations for configuration options.
- Created a repository metadata file for project management.

fichero_printer/DOCS.md

@@ -0,0 +1,144 @@
+# 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.