docs: expand Home Assistant MQTT integration section

README.md

@@ -354,9 +354,89 @@ Reads sensor data and publishes each measurement to the configured MQTT broker.
 
 ## 🏠 Home Assistant Integration
 
-### Manual MQTT sensors
+### How it works
+
+```
+BME280 sensor
+    │  I²C
+    ▼
+bme280.py (driver)
+    │  temperature / pressure / humidity
+    ▼
+sensor_api.py (Flask)
+    │  GET /bme280/publish
+    ▼
+MQTT broker (Mosquitto)           ◄── Home Assistant polls topics
+    │
+    ├── sensor/bme280_temperature  →  21.55
+    ├── sensor/bme280_humidity     →  44.57
+    └── sensor/bme280_pressure     →  1005.16
+                                        │
+                                        ▼
+                               Home Assistant dashboard
+```
+
+Every call to `/bme280/publish` (manually or via cron) pushes the three values to the broker. Home Assistant reads them in real time and updates the entity states.
 
-Add to your `configuration.yaml`:
+---
+
+### Prerequisites
+
+#### 1. Install Mosquitto in Home Assistant
+
+In HA: **Settings → Add-ons → Mosquitto broker** → Install → Start.
+
+> 💡 Enable "Start on boot" to survive reboots.
+
+#### 2. Create a dedicated MQTT user
+
+**Settings → People → Users** → Add user (e.g. `rpi-bme280`). This user will be used by the Raspberry Pi to publish.
+
+#### 3. Enable the MQTT integration
+
+**Settings → Devices & Services → Add integration → MQTT** → point to `localhost:1883` with the user created above.
+
+#### 4. Get your credentials
+
+Fill your `.env` on the Pi with the values from the steps above:
+
+```ini
+MQTT_BROKER_HOST=192.168.1.10   # HA host IP
+MQTT_USERNAME=rpi-bme280
+MQTT_PASSWORD=your_password
+```
+
+> 🔒 Never commit `.env` — it is listed in `.gitignore`.
+
+---
+
+### Option A — MQTT auto-discovery (recommended)
+
+Home Assistant supports [MQTT discovery][ha-mqtt-discovery]: publish a JSON config payload once and the entity appears automatically in the UI — no `configuration.yaml` edit needed.
+
+Run this once from the Pi (replace `<broker>` and credentials):
+
+```bash
+mosquitto_pub -h <broker> -u rpi-bme280 -P <password> \
+  -t "homeassistant/sensor/bme280_temperature/config" \
+  -m '{"name":"BME280 Temperature","state_topic":"sensor/bme280_temperature","unit_of_measurement":"°C","device_class":"temperature","state_class":"measurement","unique_id":"bme280_temperature"}'
+
+mosquitto_pub -h <broker> -u rpi-bme280 -P <password> \
+  -t "homeassistant/sensor/bme280_humidity/config" \
+  -m '{"name":"BME280 Humidity","state_topic":"sensor/bme280_humidity","unit_of_measurement":"%","device_class":"humidity","state_class":"measurement","unique_id":"bme280_humidity"}'
+
+mosquitto_pub -h <broker> -u rpi-bme280 -P <password> \
+  -t "homeassistant/sensor/bme280_pressure/config" \
+  -m '{"name":"BME280 Pressure","state_topic":"sensor/bme280_pressure","unit_of_measurement":"hPa","device_class":"atmospheric_pressure","state_class":"measurement","unique_id":"bme280_pressure"}'
+```
+
+The three entities appear under **Settings → Devices & Services → MQTT** within seconds.
+
+---
+
+### Option B — Manual MQTT sensors
+
+If you prefer explicit config, add to your `configuration.yaml`:
 
 ```yaml
 mqtt:
@@ -380,6 +460,10 @@ mqtt:
       state_class: measurement
 ```
 
+Then: **Developer Tools → YAML → Check configuration → Restart**.
+
+---
+
 ### Automation example
 
 Trigger an alert when humidity exceeds 70%:
@@ -399,6 +483,17 @@ automation:
 
 ---
 
+### Troubleshooting
+
+| Symptom | Check |
+|---------|-------|
+| Entity stuck at `unavailable` | Verify cron is running: `crontab -l` |
+| `502` on `/bme280/publish` | Broker unreachable — check `MQTT_BROKER_HOST` and broker is up |
+| No entity in HA after discovery | Check discovery is enabled in MQTT integration settings |
+| Wrong values | Confirm `BME280_I2C_ADDRESS` matches your wiring (`0x76` vs `0x77`) |
+
+---
+
 ## 🛠️ Development
 
 ### Install dev dependencies
@@ -492,3 +587,4 @@ bme280/
 *Bosch BME280 datasheet: [BST-BME280-DS002][bme280-datasheet]*
 
 [bme280-datasheet]: https://www.bosch-sensortec.com/media/boschsensortec/downloads/datasheets/bst-bme280-ds002.pdf
+[ha-mqtt-discovery]: https://www.home-assistant.io/integrations/mqtt/#mqtt-discovery