v0.1.36: Enhanced BLE troubleshooting with specific br-connection-not-supported guidance\n\n- Added detailed step-by-step instructions for fixing br-connection-not-supported error\n- Improved API error messages with Home Assistant-specific guidance\n- Added visible troubleshooting section in web UI for common BLE issues\n- Enhanced error handling to distinguish between different BLE connection problems\n\nGenerated by Mistral Vibe.\nCo-Authored-By: Mistral Vibe <vibe@mistral.ai>

fichero_printer/fichero/api.py

@@ -284,7 +284,26 @@ async def get_status(
     except PrinterError as 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):
+        if not classic and "br-connection-not-supported" in error_str:
+            detail += "\n\n🔧 HOME ASSISTANT BLE PERMISSION FIX:\n"
+            detail += "This error occurs when Home Assistant doesn't have proper Bluetooth permissions.\n\n"
+            detail += "📋 STEP-BY-STEP SOLUTION:\n"
+            detail += "1. Edit your add-on configuration in Home Assistant\n"
+            detail += "2. Add this line to the configuration:\n"
+            detail += "   host_dbus: true\n"
+            detail += "3. Save the configuration\n"
+            detail += "4. Restart the Fichero add-on\n"
+            detail += "5. Try connecting again\n\n"
+            detail += "💡 If you're using the Home Assistant OS:\n"
+            detail += "- Go to Settings > Add-ons > Fichero Printer > Configuration\n"
+            detail += "- Add 'host_dbus: true' under the 'host_dbus' section\n"
+            detail += "- This gives the add-on access to the system Bluetooth stack\n\n"
+            detail += "🔄 ALTERNATIVE SOLUTION:\n"
+            detail += "If BLE still doesn't work after adding host_dbus, try Classic Bluetooth:\n"
+            detail += "1. Set 'classic=true' in your API calls\n"
+            detail += "2. Use channel=1 (most common for Fichero printers)\n"
+            detail += "3. Use the 'Pair Device' button in the web UI first"
+        elif not classic and "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"

fichero_printer/fichero/index.html

@@ -481,6 +481,22 @@
           </div>
         </div>
 
+        <div class="ble-troubleshooting" style="margin-top: 1rem; padding: 1rem; background-color: rgba(59, 130, 246, 0.1); border-radius: var(--radius-sm); border-left: 4px solid var(--accent);">
+          <h3 style="color: var(--accent); margin-bottom: 0.5rem;">🔧 BLE Connection Issues?</h3>
+          <p style="font-size: 0.9rem; margin-bottom: 0.5rem;">
+            If you see <strong>"br-connection-not-supported"</strong> error:
+          </p>
+          <ol style="font-size: 0.85rem; line-height: 1.4; padding-left: 1.2rem;">
+            <li>Edit your Home Assistant add-on configuration</li>
+            <li>Add: <code style="background: var(--bg-secondary); padding: 0.1rem 0.3rem; border-radius: 0.2rem;">host_dbus: true</code></li>
+            <li>Save and restart the add-on</li>
+            <li>Try connecting again</li>
+          </ol>
+          <p style="font-size: 0.85rem; margin-top: 0.5rem; color: var(--text-secondary);">
+            Still issues? Try Classic Bluetooth with channel 1 and use the "Pair Device" button.
+          </p>
+        </div>
+
         <div class="actions">
           <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')" title="Only needed for Classic Bluetooth. BLE does not require pairing.">Unpair Device</button>