new version

fichero_printer/CHANGELOG.md

@@ -7,15 +7,6 @@ The format is based on Keep a Changelog and this project uses Semantic Versionin
 
 ## [0.1.35] - 2026-03-18
 
-### Fixed
-- **Web UI**: Fixed "body stream already read" error by reading response body only once.
-- **Web UI**: Improved response handling to avoid double-reading response stream.
-- **Web UI**: Better error messages for server-side 500 errors from scan endpoint.
-
-### Changed
-- **Web UI**: Refactored response handling to use single response.read() call.
-- **Web UI**: Enhanced error display for server-side scan failures.
-
 ## [0.1.34] - 2026-03-18
 
 ### Fixed

fichero_printer/fichero/api.py

@@ -47,6 +47,8 @@ from fichero.printer import (
 # ---------------------------------------------------------------------------
 
 _DEFAULT_ADDRESS: str | None = os.environ.get("FICHERO_ADDR")
+# Default to BLE transport (most reliable for Fichero/D11s printers)
+# Set FICHERO_TRANSPORT=classic to force Classic Bluetooth (RFCOMM)
 _DEFAULT_CLASSIC: bool = os.environ.get("FICHERO_TRANSPORT", "").lower() == "classic"
 _DEFAULT_CHANNEL: int = int(os.environ.get("FICHERO_CHANNEL", "1"))
 
@@ -255,11 +257,36 @@ async def get_status(
         async with connect(_address(address), classic=classic, channel=channel) as pc:
             status = await pc.get_status()
     except PrinterNotFound as exc:
-        raise HTTPException(status_code=404, detail=str(exc)) from exc
+        detail = str(exc)
+        if "BLE" in detail or "BLE" in str(classic):
+            detail += "\n\nBLE Troubleshooting:\n" 
+            detail += "- Ensure Home Assistant has Bluetooth permissions (host_dbus: true)\n"
+            detail += "- Make sure the printer is powered on and discoverable\n"
+            detail += "- Try restarting the printer\n"
+            detail += "- Check that no other device is connected to the printer"
+        raise HTTPException(status_code=404, detail=detail) from exc
     except PrinterTimeout as exc:
-        raise HTTPException(status_code=504, detail=str(exc)) from exc
+        detail = str(exc)
+        if not classic:  # BLE timeout
+            detail += "\n\nBLE Connection Tips:\n"
+            detail += "- Bring the printer closer to the Home Assistant host\n"
+            detail += "- Ensure no Bluetooth interference (WiFi, USB 3.0, microwaves)\n"
+            detail += "- Try restarting the Bluetooth service on your host"
+        raise HTTPException(status_code=504, detail=detail) from exc
     except PrinterError as exc:
-        raise HTTPException(status_code=502, detail=str(exc)) from exc
+        detail = str(exc)
+        error_str = str(exc).lower()
+        if not classic and ("br-connection-not-supported" in error_str or "dbus" in error_str):
+            detail += "\n\nBLE Permission Fix:\n"
+            detail += "1. Add 'host_dbus: true' to your add-on configuration\n"
+            detail += "2. Restart the add-on\n"
+            detail += "3. If using Classic Bluetooth, try: classic=true with channel=1"
+        elif not classic and "connection" in error_str:
+            detail += "\n\nBLE Connection Help:\n"
+            detail += "- Verify the BLE address is correct (not Classic Bluetooth address)\n"
+            detail += "- Ensure no other device is paired/connected to the printer\n"
+            detail += "- Try power cycling the printer"
+        raise HTTPException(status_code=502, detail=detail) from exc
 
     return {
         "ok": status.ok,
@@ -320,15 +347,23 @@ async def scan_devices():
 
 @app.post(
     "/pair",
-    summary="Pair and trust a Bluetooth device",
+    summary="Pair and trust a Classic Bluetooth device",
     status_code=200,
+    description="⚠️ ONLY for Classic Bluetooth (RFCOMM). BLE does not require pairing!",
 )
 async def pair_device(
     address: Annotated[str | None, Form(description="Device address (optional, overrides FICHERO_ADDR)")] = None,
 ):
     """
     Attempt to pair and trust the device using `bluetoothctl`.
-    This is intended for setting up Classic Bluetooth connections.
+    
+    ⚠️ IMPORTANT: This is ONLY for Classic Bluetooth (RFCOMM) connections.
+    BLE connections do NOT require pairing and will NOT work with this endpoint.
+    
+    For BLE issues, ensure:
+    - The printer is powered on and discoverable
+    - Home Assistant has proper Bluetooth permissions (host_dbus: true)
+    - You're using the correct BLE address (not Classic Bluetooth address)
     """
     addr = _address(address)
     if not addr:

fichero_printer/fichero/index.html

@@ -374,9 +374,9 @@
         <div class="row">
           <div>
             <label for="transport">Transport</label>
-            <select id="transport">
+            <select id="transport" title="BLE is recommended for most users. Classic Bluetooth requires pairing and specific permissions.">
-              <option value="ble"{ble_selected}>BLE</option>
+              <option value="ble"{ble_selected}>BLE (Recommended)</option>
-              <option value="classic"{classic_selected}>Classic</option>
+              <option value="classic"{classic_selected}>Classic Bluetooth</option>
             </select>
           </div>
           <div>
@@ -386,8 +386,8 @@
         </div>
 
         <div class="actions">
-          <button type="button" class="alt" onclick="runPost('pair')">Pair Device</button>
+          <button type="button" class="alt" onclick="runPost('pair')" title="Only needed for Classic Bluetooth. BLE does not require pairing.">Pair Device</button>
-          <button type="button" class="alt" onclick="runPost('unpair')">Unpair Device</button>
+          <button type="button" class="alt" onclick="runPost('unpair')" title="Only needed for Classic Bluetooth. BLE does not require pairing.">Unpair Device</button>
           <button type="button" class="alt" onclick="runGet('status')">Get Status</button>
           <button type="button" class="alt" onclick="runGet('info')">Get Info</button>
         </div>