Implement HTTP API for Fichero D11s printer with status and print endpoints

2026-03-07 11:39:20 +01:00
parent f945a87c43
commit 43495714e6
3 changed files with 438 additions and 0 deletions
--- a/docs/PROTOCOL.md
+++ b/docs/PROTOCOL.md
@@ -189,3 +189,144 @@ Fichero-branded printers:
 4. Traced the device class hierarchy: D11s -> AiYinNormalDevice -> BaseNormalDevice
 5. Found the AiYin-specific enable/stop commands that were different from the base class
 6. Tested every discovered command against the actual hardware and documented which ones work
+
+---
+
+## HTTP API (`fichero/api.py`)
+
+A FastAPI-based REST server that wraps the printer logic.
+
+### Installation
+
+```bash
+pip install 'fichero-printer[api]'
+```
+
+### Starting the server
+
+```bash
+fichero-server [--host HOST] [--port PORT] [--address BLE_ADDR] [--classic] [--channel N]
+```
+
+Default: `http://127.0.0.1:8765`.  
+The BLE address can also be set via the `FICHERO_ADDR` environment variable.  
+Interactive docs available at `http://127.0.0.1:8765/docs`.
+
+---
+
+### `GET /status`
+
+Returns the real-time printer status.
+
+**Query parameters** (all optional):
+
+| Parameter | Type    | Default          | Description                         |
+|-----------|---------|------------------|-------------------------------------|
+| `address` | string  | `FICHERO_ADDR`   | BLE address (skips scanning)        |
+| `classic` | boolean | `false`          | Use Classic Bluetooth RFCOMM        |
+| `channel` | integer | `1`              | RFCOMM channel                      |
+
+**Response `200`:**
+```json
+{
+  "ok": true,
+  "printing": false,
+  "cover_open": false,
+  "no_paper": false,
+  "low_battery": false,
+  "overheated": false,
+  "charging": false,
+  "raw": 0
+}
+```
+
+---
+
+### `GET /info`
+
+Returns static and dynamic printer information (model, firmware, serial, battery, …).
+
+Same query parameters as `/status`.
+
+**Response `200`:** JSON object with all info keys returned by the printer.
+
+---
+
+### `POST /print/text`
+
+Print a plain-text label. Sends `multipart/form-data`.
+
+**Form fields:**
+
+| Field          | Type    | Default | Required | Description                                      |
+|----------------|---------|---------|----------|--------------------------------------------------|
+| `text`         | string  | —       | ✓        | Text to print                                    |
+| `density`      | integer | `2`     |          | Print density: 0=light, 1=medium, 2=dark         |
+| `paper`        | string  | `gap`   |          | Paper type: `gap`, `black`, `continuous` (0-2)   |
+| `copies`       | integer | `1`     |          | Number of copies (1–99)                          |
+| `font_size`    | integer | `30`    |          | Font size in points                              |
+| `label_length` | integer | —       |          | Label length in mm (overrides `label_height`)    |
+| `label_height` | integer | `240`   |          | Label height in pixels                           |
+| `address`      | string  | —       |          | BLE address override                             |
+| `classic`      | boolean | —       |          | Use Classic Bluetooth RFCOMM                     |
+| `channel`      | integer | —       |          | RFCOMM channel                                   |
+
+**Response `200`:**
+```json
+{ "ok": true, "copies": 1, "text": "Hello World" }
+```
+
+**Example (`curl`):**
+```bash
+curl -X POST http://127.0.0.1:8765/print/text \
+  -F text="Hello World" \
+  -F density=2 \
+  -F paper=gap \
+  -F label_length=30
+```
+
+---
+
+### `POST /print/image`
+
+Print an image file. Sends `multipart/form-data`.
+
+**Form fields:**
+
+| Field          | Type    | Default | Required | Description                                      |
+|----------------|---------|---------|----------|--------------------------------------------------|
+| `file`         | file    | —       | ✓        | Image file (PNG, JPEG, BMP, GIF, TIFF, WEBP)     |
+| `density`      | integer | `2`     |          | Print density: 0=light, 1=medium, 2=dark         |
+| `paper`        | string  | `gap`   |          | Paper type: `gap`, `black`, `continuous` (0-2)   |
+| `copies`       | integer | `1`     |          | Number of copies (1–99)                          |
+| `dither`       | boolean | `true`  |          | Apply Floyd-Steinberg dithering                  |
+| `label_length` | integer | —       |          | Max label length in mm (overrides `label_height`)|
+| `label_height` | integer | `240`   |          | Max label height in pixels                       |
+| `address`      | string  | —       |          | BLE address override                             |
+| `classic`      | boolean | —       |          | Use Classic Bluetooth RFCOMM                     |
+| `channel`      | integer | —       |          | RFCOMM channel                                   |
+
+**Response `200`:**
+```json
+{ "ok": true, "copies": 1, "filename": "label.png" }
+```
+
+**Example (`curl`):**
+```bash
+curl -X POST http://127.0.0.1:8765/print/image \
+  -F file=@label.png \
+  -F density=2 \
+  -F dither=true \
+  -F label_length=40
+```
+
+---
+
+### Error responses
+
+| Status | Meaning                                                 |
+|--------|---------------------------------------------------------|
+| `404`  | Printer not found (BLE scan failed or address invalid)  |
+| `422`  | Validation error (bad parameter value or empty file)    |
+| `502`  | Printer communication error                             |
+| `504`  | Printer timed out                                       |