new version

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: