Tobias/Fichero
1
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update to 0.1.28
Some checks failed
Deploy to GitHub Pages / build (push) Has been cancelled
Details
Deploy to GitHub Pages / deploy (push) Has been cancelled
Details

Browse Source
This commit is contained in:
paul2212
2026-03-16 15:18:57 +01:00
parent c3425a2b92
commit 2a7915a707
7 changed files with 125 additions and 208 deletions
Download Patch File Download Diff File Expand all files Collapse all files

156
CHANGELOG.md
View File

@@ -1,156 +0,0 @@
# Changelog
All notable changes to this project are documented in this file.
The format is based on Keep a Changelog and this project uses Semantic Versioning.
## [0.1.27] - 2026-03-16
### Changed
- **Project Structure**: Moved the `fichero` library into `fichero_printer/` to make the add-on self-contained. This simplifies the build process and removes the need for synchronization scripts.
- Fixed invalid duplicate `version` keys in `pyproject.toml` and `config.yaml`.
## [0.1.26] - 2026-03-16
### Fixed
- **Build Process**: Fixed `too many links` Docker build error by removing the symlink-based approach. Introduced a `sync_addon.sh` script to automate copying the library into the add-on directory, which is required for the Home Assistant build system.
## [0.1.25] - 2026-03-08
### Changed
- **Build Process**: Replaced the manually copied `fichero` directory inside the Home Assistant add-on with a symbolic link. This eliminates code duplication and automates synchronization, simplifying the build process.
## [0.1.24] - 2026-03-08
### Fixed
- **Home Assistant Build**: Reverted the add-on's `Dockerfile` to a vendored code approach to resolve build failures caused by the Home Assistant build system's inability to access files outside the add-on directory. The add-on is now self-contained again.
## [0.1.23] - 2026-03-08
### Changed
- Updated the Home Assistant add-on's `Dockerfile` to install the main library as a package, completing the project structure refactoring.
- Added `python-multipart` as an explicit dependency for the API server.
## [0.1.22] - 2026-03-08
### Changed
- **Refactored Project Structure**: Eliminated duplicated code by converting the project into an installable Python package. The Home Assistant add-on now installs the main library as a dependency instead of using a vendored copy, improving maintainability and preventing sync issues.
## [0.1.21] - 2026-03-08
### Fixed
- Synchronized the Home Assistant add-on's source code (`fichero_printer/fichero/`) with the main library to fix stale code and version mismatch issues.
## [0.1.20] - 2026-03-08
### Changed
- Refactored the embedded web UI in the API server to be loaded from a separate `index.html` file instead of a large inline string, improving maintainability.
## [0.1.19] - 2026-03-08
### Added
- Added `POST /unpair` endpoint and "Unpair Device" button in the web UI to remove a Bluetooth device from the host's paired devices.
## [0.1.18] - 2026-03-08
### Added
- Added `POST /pair` endpoint and "Pair Device" button in the web UI to easily pair/trust the printer via `bluetoothctl` for Classic Bluetooth connections.
## [0.1.17] - 2026-03-08
### Added
- Added automatic fallback to BLE connection if Classic Bluetooth (RFCOMM) fails with `[Errno 12] Out of memory`, a common issue on Linux with stale device states.
## [0.1.16] - 2026-03-08
### Fixed
- Corrected typos in the Code128B bit pattern table for characters '$' (ASCII 36) and ')' (ASCII 41), which caused incorrect barcodes to be generated.
## [0.1.15] - 2026-03-07
### Fixed
- Added BLE recovery path for `br-connection-not-supported`: the connector now forces a fresh LE scan target resolution and retries before returning an error.
## [0.1.14] - 2026-03-07
### Fixed
- Removed BLE fallback to raw MAC string when device resolution fails. The connector now requires a discovered LE device object, avoiding BlueZ BR/EDR misclassification that can cause `br-connection-not-supported`.
## [0.1.13] - 2026-03-07
### Fixed
- Treated BLE service-discovery disconnects (`failed to discover services, device disconnected`) as retryable transient errors in the BLE connect loop.
## [0.1.12] - 2026-03-07
### Fixed
- BLE target resolution now prefers discovered Bleak device objects (instead of raw address strings), improving BlueZ LE connection handling on hosts that previously returned `br-connection-not-supported`.
## [0.1.11] - 2026-03-07
### Fixed
- Handled `asyncio.TimeoutError` from BLE connect path so connection timeouts now return mapped API errors (502) instead of unhandled 500 exceptions.
## [0.1.10] - 2026-03-07
### Changed
- Added automatic BLE reconnect retry with linear backoff for transient timeout errors (including `br-connection-timeout`) before returning a failure.
## [0.1.9] - 2026-03-07
### Added
- Added add-on-local changelog at `fichero_printer/CHANGELOG.md` so Home Assistant can display release notes in the add-on UI.
### Changed
- Improved Classic Bluetooth connect logic by trying fallback RFCOMM channels (1-3 plus configured channel) before failing.
## [0.1.8] - 2026-03-07
### Added
- Root URL now serves a built-in printer web interface for Home Assistant with status, info, text printing, and image upload printing.
### Changed
- Swagger docs remain available under `/docs` while the Home Assistant "Open" action now lands on the print UI.
## [0.1.7] - 2026-03-07
### Fixed
- Home Assistant ingress docs now use a custom Swagger UI route with a relative `openapi.json` URL, avoiding `404 /openapi.json` behind ingress prefixes.
### Changed
- Home Assistant add-on now requests `full_access: true` in addition to Bluetooth capabilities to unblock Classic RFCOMM socket access on stricter hosts.
## [0.1.6] - 2026-03-07
### Added
- Added this `CHANGELOG.md` and established a release policy to update version and changelog for every change.
## [0.1.5] - 2026-03-07
### Changed
- Home Assistant add-on now requests `NET_RAW` in addition to `NET_ADMIN` for Classic Bluetooth RFCOMM sockets.
- Add-on documentation updated with Classic permission requirements.
## [0.1.4] - 2026-03-07
### Fixed
- RFCOMM connection under `uvloop` now uses direct Bluetooth socket connect in a worker thread, avoiding address-family resolution issues.
- Classic Bluetooth socket errors are mapped to API-safe printer errors instead of unhandled 500s.
## [0.1.3] - 2026-03-07
### Changed
- Home Assistant add-on metadata updated for ingress/web UI access.
- API root endpoint now redirects to docs in an ingress-compatible way.
- Added attribution for original upstream project and AI-assisted extension note.

4
README.md
View File

@@ -7,9 +7,9 @@ Web GUI, Python CLI, and protocol documentation for the Fichero D11s thermal lab
- Original developer/project: [0xMH/fichero-printer](https://github.com/0xMH/fichero-printer) - Original developer/project: [0xMH/fichero-printer](https://github.com/0xMH/fichero-printer)
- This repository version was additionally extended with AI-assisted changes. - This repository version was additionally extended with AI-assisted changes.
## Release Policy ## Development
- Maintain `CHANGELOG.md` for every user-visible change. - The main changelog is located at `fichero_printer/CHANGELOG.md`.
- Bump the project/add-on version with every merged change. - Bump the project/add-on version with every merged change.
Blog post: [Reverse Engineering Action's Cheap Fichero Labelprinter](https://blog.dbuglife.com/reverse-engineering-fichero-label-printer/) Blog post: [Reverse Engineering Action's Cheap Fichero Labelprinter](https://blog.dbuglife.com/reverse-engineering-fichero-label-printer/)

164
fichero_printer/CHANGELOG.md
View File

@@ -1,90 +1,162 @@
# Changelog # Changelog
## 0.1.27 All notable changes to this project are documented in this file.
- The `fichero` library is now part of the add-on directory, simplifying the build process and removing the need for synchronization scripts.
## 0.1.24 The format is based on Keep a Changelog and this project uses Semantic Versioning.
- Fixed Docker build failures by reverting to a vendored code approach. The add-on now expects the `fichero` library to be present within its directory during the build. ## [0.1.28] - 2026-03-16
## 0.1.23 ### Fixed
- **Pairing**: Added the `bluez` package to the Docker image, which provides the `bluetoothctl` command. This fixes the "not found" error when using the "Pair Device" and "Unpair Device" features.
- **Changelog**: Consolidated the project's changelogs into a single, consistent file within the add-on, resolving inconsistencies from previous refactoring.
- Updated `Dockerfile` to install the main library via `pip` instead of copying source files, completing the refactoring to eliminate duplicated code. ## [0.1.27] - 2026-03-16
## 0.1.22 ### Changed
- Refactored build process to install the main `fichero-printer` library as a package instead of using duplicated source files. This resolves issues with stale code. - **Project Structure**: Moved the `fichero` library into `fichero_printer/` to make the add-on self-contained. This simplifies the build process and removes the need for synchronization scripts.
- Fixed invalid duplicate `version` keys in `pyproject.toml` and `config.yaml`.
## 0.1.21 ## [0.1.26] - 2026-03-16
- Fixed stale source code issue by synchronizing the add-on's internal `fichero` package with the latest library version. ### Fixed
## 0.1.20 - **Build Process**: Fixed `too many links` Docker build error by removing the symlink-based approach. Introduced a `sync_addon.sh` script to automate copying the library into the add-on directory, which is required for the Home Assistant build system.
- Refactored the embedded web UI to be loaded from an external `index.html` file. ## [0.1.25] - 2026-03-08
## 0.1.19 ### Changed
- Added "Unpair Device" button to the web UI. - **Build Process**: Replaced the manually copied `fichero` directory inside the Home Assistant add-on with a symbolic link. This eliminates code duplication and automates synchronization, simplifying the build process.
## 0.1.18 ## [0.1.24] - 2026-03-08
- Added "Pair Device" button to the web UI. ### Fixed
## 0.1.16 - **Home Assistant Build**: Reverted the add-on's `Dockerfile` to a vendored code approach to resolve build failures caused by the Home Assistant build system's inability to access files outside the add-on directory. The add-on is now self-contained again.
- Added automatic fallback to BLE if Classic Bluetooth fails with `[Errno 12] Out of memory`. ## [0.1.23] - 2026-03-08
## 0.1.15 ### Changed
- Added a BLE recovery retry for `br-connection-not-supported` that forces fresh LE target resolution from scan results before failing. - Updated the Home Assistant add-on's `Dockerfile` to install the main library as a package, completing the project structure refactoring.
- Added `python-multipart` as an explicit dependency for the API server.
## 0.1.14 ## [0.1.22] - 2026-03-08
- Prevented BLE fallback to raw MAC connects and now require discovered LE device resolution, reducing `br-connection-not-supported` regressions on some BlueZ hosts. ### Changed
## 0.1.13 - **Refactored Project Structure**: Eliminated duplicated code by converting the project into an installable Python package. The Home Assistant add-on now installs the main library as a dependency instead of using a vendored copy, improving maintainability and preventing sync issues.
- Marked BLE service-discovery disconnect errors as retryable (`failed to discover services, device disconnected`), so the add-on retries automatically. ## [0.1.21] - 2026-03-08
## 0.1.12 ### Fixed
- Synchronized the Home Assistant add-on's source code (`fichero_printer/fichero/`) with the main library to fix stale code and version mismatch issues.
- Improved BLE connection target resolution by preferring discovered BLE device objects over raw MAC strings to avoid BlueZ `br-connection-not-supported` on some hosts. ## [0.1.20] - 2026-03-08
## 0.1.11 ### Changed
- Fixed unhandled BLE connect timeout (`asyncio.TimeoutError`) that previously caused HTTP 500 responses. - Refactored the embedded web UI in the API server to be loaded from a separate `index.html` file instead of a large inline string, improving maintainability.
## 0.1.10 ## [0.1.19] - 2026-03-08
- Added automatic BLE reconnect retry with backoff for transient timeout errors (`br-connection-timeout`). ### Added
## 0.1.9 - Added `POST /unpair` endpoint and "Unpair Device" button in the web UI to remove a Bluetooth device from the host's paired devices.
- Added add-on local changelog file so Home Assistant can display release notes. ## [0.1.18] - 2026-03-08
- Improved Classic Bluetooth RFCOMM connection robustness by trying fallback channels (1-3 plus configured channel).
## 0.1.8 ### Added
- Added Home Assistant web print interface on `/` with status/info/text/image actions. - Added `POST /pair` endpoint and "Pair Device" button in the web UI to easily pair/trust the printer via `bluetoothctl` for Classic Bluetooth connections.
## 0.1.7 ## [0.1.17] - 2026-03-08
- Fixed ingress Swagger OpenAPI loading behind Home Assistant. ### Added
- Enabled `full_access` for stricter hosts blocking RFCOMM sockets.
## 0.1.6 - Added automatic fallback to BLE connection if Classic Bluetooth (RFCOMM) fails with `[Errno 12] Out of memory`, a common issue on Linux with stale device states.
- Added root changelog and release policy. ## [0.1.16] - 2026-03-08
## 0.1.5 ### Fixed
- Added `NET_RAW` capability for Classic Bluetooth sockets. - Corrected typos in the Code128B bit pattern table for characters '$' (ASCII 36) and ')' (ASCII 41), which caused incorrect barcodes to be generated.
## 0.1.4 ## [0.1.15] - 2026-03-07
- Fixed RFCOMM connect path under uvloop. ### Fixed
- Added BLE recovery path for `br-connection-not-supported`: the connector now forces a fresh LE scan target resolution and retries before returning an error.
## 0.1.3 ## [0.1.14] - 2026-03-07
- Added ingress/webui metadata updates. ### Fixed
- Removed BLE fallback to raw MAC string when device resolution fails. The connector now requires a discovered LE device object, avoiding BlueZ BR/EDR misclassification that can cause `br-connection-not-supported`.
## [0.1.13] - 2026-03-07
### Fixed
- Treated BLE service-discovery disconnects (`failed to discover services, device disconnected`) as retryable transient errors in the BLE connect loop.
## [0.al.12] - 2026-03-07
### Fixed
- BLE target resolution now prefers discovered Bleak device objects (instead of raw address strings), improving BlueZ LE connection handling on hosts that previously returned `br-connection-not-supported`.
## [0.1.11] - 2026-03-07
### Fixed
- Handled `asyncio.TimeoutError` from BLE connect path so connection timeouts now return mapped API errors (502) instead of unhandled 500 exceptions.
## [0.1.10] - 2026-03-07
### Changed
- Added automatic BLE reconnect retry with linear backoff for transient timeout errors (including `br-connection-timeout`) before returning a failure.
## [0.1.9] - 2026-03-07
### Added
- Added add-on-local changelog at `fichero_printer/CHANGELOG.md` so Home Assistant can display release notes in the add-on UI.
### Changed
- Improved Classic Bluetooth connect logic by trying fallback RFCOMM channels (1-3 plus configured channel) before failing.
## [0.1.8] - 2026-03-07
### Added
- Root URL now serves a built-in printer web interface for Home Assistant with status, info, text printing, and image upload printing.
### Changed
- Swagger docs remain available under `/docs` while the Home Assistant "Open" action now lands on the print UI.
## [0.1.7] - 2026-03-07
### Fixed
- Home Assistant ingress docs now use a custom Swagger UI route with a relative `openapi.json` URL, avoiding `404 /openapi.json` behind ingress prefixes.
### Changed
- Home Assistant add-on now requests `full_access: true` in addition to Bluetooth capabilities to unblock Classic RFCOMM socket access on stricter hosts.
## [0.1.6] - 2026-03-07
### Added
- Added this `CHANGELOG.md` and established a release policy to update version and changelog for every change.
## [0.1.5] - 2026-03-07
### Changed
- Home Assistant add-on now requests `NET_RAW` in addition to `NET_ADMIN` for Classic Bluetooth RFCOMM sockets.
- Add-on documentation updated with Classic permission requirements.
## [0.1.4] - 2026-03-07
### Fixed
- RFCOMM connection under `uvloop` now uses direct Bluetooth socket connect in a worker thread, avoiding address-family resolution issues.
- Classic Bluetooth socket errors are mapped to API-safe printer errors instead of unhandled 500s.
## [0.1.3] - 2026-03-07
### Changed
- Home Assistant add-on metadata updated for ingress/web UI access.
- API root endpoint now redirects to docs in an ingress-compatible way.
- Added attribution for original upstream project and AI-assisted extension note.

3
fichero_printer/Dockerfile
View File

@@ -10,7 +10,8 @@ RUN apk add --no-cache \
python3 \ python3 \
py3-pip \ py3-pip \
dbus-dev \ dbus-dev \
build-base build-base \
bluez
# Install Python dependencies from pip. # Install Python dependencies from pip.
# We cannot use `pip install .` from pyproject.toml as it's outside the build context. # We cannot use `pip install .` from pyproject.toml as it's outside the build context.

2
fichero_printer/config.yaml
View File

@@ -1,5 +1,5 @@
name: "Fichero Printer" name: "Fichero Printer"
version: "0.1.27" version: "0.1.28"
slug: "fichero_printer" slug: "fichero_printer"
description: "REST API for the Fichero D11s (AiYin) thermal label printer over Bluetooth" description: "REST API for the Fichero D11s (AiYin) thermal label printer over Bluetooth"
url: "https://git.leuschner.dev/Tobias/Fichero" url: "https://git.leuschner.dev/Tobias/Fichero"

2
fichero_printer/fichero/api.py
View File

@@ -75,7 +75,7 @@ async def lifespan(app: FastAPI): # noqa: ARG001
app = FastAPI( app = FastAPI(
title="Fichero Printer API", title="Fichero Printer API",
description="REST API for the Fichero D11s (AiYin) thermal label printer.", description="REST API for the Fichero D11s (AiYin) thermal label printer.",
version="0.1.26", version="0.1.28",
lifespan=lifespan, lifespan=lifespan,
docs_url=None, docs_url=None,
redoc_url=None, redoc_url=None,

2
pyproject.toml
View File

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
[project] [project]
name = "fichero-printer" name = "fichero-printer"
version = "0.1.27" version = "0.1.28"
description = "Web GUI, Python CLI, and protocol documentation for the Fichero D11s thermal label printer." description = "Web GUI, Python CLI, and protocol documentation for the Fichero D11s thermal label printer."
readme = "README.md" readme = "README.md"
requires-python = ">=3.10" requires-python = ">=3.10"