MQTT/HomeAssistant Integration

Implementation details and lessons learned for tri-modal Webasto control: LoRa (primary), MQTT (WiFi), and local button.

Overview

The receiver supports tri-modal control:

1. •LoRa control (primary): Sender device → Receiver via 433MHz LoRa
2. •Local button control: GPIO0 menu on receiver
3. •MQTT/HomeAssistant control: WiFi-based remote control (when available)

Critical constraint: MQTT is supplementary. WiFi/MQTT operations must NEVER block LoRa reception or W-BUS control.

Power Management & Sleep Behavior

Normal Operation (DISABLE_SLEEP=0)

The receiver implements aggressive power management when running on battery:

1. Startup Sequence

• •Initialize LoRa, W-BUS, WiFi, MQTT concurrently
• •WiFi attempts connection for up to 10s (non-blocking)
• •LoRa RX is active immediately regardless of WiFi state
• •System ready within 2-3s, WiFi may still be connecting

2. Heater OFF (Idle Mode)

• •Sleep cycle: Wake every 4s, listen for 400ms, then deep sleep
• •OLED powered off to save energy
• •WiFi/MQTT connection attempts continue in background (non-blocking)
• •W-BUS polling minimized during sleep to reduce wake time
• •Power consumption: ~10mA average (vs ~150mA when fully awake)

3. Command Received

• •Any command (LoRa, MQTT, or button) wakes receiver fully
• •If command starts heater: transition to Running mode
• •If command received but heater stays OFF: stay awake for RX window

4. Heater RUNNING

• •Stay fully awake (no deep sleep)
• •OLED stays on per requirement
• •LoRa RX continuous for low-latency status updates
• •WiFi/MQTT maintain connection for real-time monitoring
• •W-BUS polled every 2s for status updates
• •Power consumption: ~150-200mA

5. Heater Turns OFF → Extended Wake

• •Stay awake for 60s after heater shuts down
• •Allows final status updates to reach sender/MQTT
• •Ensures clean shutdown communication
• •W-BUS continues polling during extended wake
• •After 60s: return to sleep cycle if no new commands

6. W-BUS Polling Behavior (Power Management)

• •CRITICAL: W-BUS polling wakes the Webasto heater, drawing unnecessary power
• •Solution: Only poll W-BUS when absolutely necessary:
  • •✅ Heater is RUNNING (continuous monitoring required)
  • •✅ In extended wake period (final status updates)
  • •✅ Explicit QueryStatus command received (on-demand polling)
  • •❌ NOT during idle wake windows (would wake Webasto unnecessarily)
• •Use QueryStatus command to poll status on-demand without starting heater
• •Available via LoRa, MQTT, or button menu

7. QueryStatus Command

• •Purpose: Poll W-BUS for current status without starting the heater
• •Use case: Check heater temperature/voltage while sleeping to avoid waking it continuously
• •Availability:
  • •LoRa: Sender transmits CommandKind::QueryStatus
  • •MQTT: Publish to webasto/receiver/query topic
  • •Button: Select "STATUS?" from menu
• •Behavior: Sets flag → polls W-BUS on next 2s interval → sends status back
• •Power impact: Single W-BUS query (~250ms) instead of continuous 2s polling

8. Testing Mode (DISABLE_SLEEP=1)

• •Fully awake at all times
• •W-BUS polls continuously every 2s (as heater always considered "running")
• •Useful for serial debugging and development
• •Set in platformio.ini: -D DISABLE_SLEEP=1

Configuration

// project_config.h
#define RX_IDLE_LISTEN_WINDOW_MS 400   // LoRa RX window when waking
#define RX_IDLE_SLEEP_MS 4000          // Sleep interval when heater OFF
#define RX_OFF_EXTENDED_WAKE_MS 60000  // Stay awake 60s after heater stops

Tuning notes:

• •Shorter RX_IDLE_SLEEP_MS = faster command response, higher power draw
• •Longer RX_IDLE_LISTEN_WINDOW_MS = higher command catch rate, more wake power
• •Extended wake ensures WiFi has time to publish final status before sleeping

Architecture

Component Stack

HomeAssistant Dashboard
         ↓ (MQTT commands)
    MQTT Broker (Mosquitto)
         ↓
WiFiManager (WPA2 Enterprise) ───→ MQTTClient (PubSubClient wrapper)
         │                              ↓
         │                         Command Handler
         │                              ↓
         └─────────────→ W-BUS Controller → Webasto Heater
                             ↑
                        (Status polling)

Non-Blocking Design

• •WiFi connection: 10s timeout, non-blocking state machine
• •MQTT reconnect: 5s retry interval, async
• •Main loop overhead: <10ms per iteration
• •Graceful degradation: LoRa/W-BUS continue working when WiFi unavailable

WiFi Manager (Phase 1)

Files: lib/common/wifi_manager.{h,cpp}

WPA2 Enterprise PEAP

Uses ESP32's esp_wpa2 API for enterprise authentication:

#include <esp_wpa2.h>
esp_wifi_sta_wpa2_ent_set_username((uint8_t*)username, strlen(username));
esp_wifi_sta_wpa2_ent_set_password((uint8_t*)password, strlen(password));
esp_wifi_sta_wpa2_ent_enable();
WiFi.begin(ssid);

Fast Reconnect

• •Caches BSSID and channel on first successful connection
• •Uses WiFi.begin(ssid, pass, channel, bssid) for 1-2s reconnect (vs 5s full scan)

State Machine

• •DISCONNECTED → CONNECTING (10s max) → CONNECTED
• •FAILED → retry after 60s
• •update() is non-blocking, checks status without delays

MQTT Client (Phase 2)

Files: lib/common/mqtt_client.{h,cpp}

Library Choice

Uses PubSubClient v2.8 (~15KB flash):

• •Proven, lightweight, Arduino-compatible
• •Non-blocking loop() for message processing
• •Supports QoS 0/1, retained messages, LWT

Command Structure

struct MQTTCommand {
  enum Type { STOP, START, RUN_MINUTES };
  Type type;
  uint8_t minutes;
  uint32_t timestampSec;  // Unix epoch for freshness check
};

Stale Command Protection

• •Commands older than 1 hour rejected: current_time - cmd_timestamp > 3600s
• •Uses NTP time sync: configTime(0, 0, "pool.ntp.org")
• •Prevents executing outdated commands after WiFi reconnection

Topic Structure

webasto/receiver/mode/set          (command: "off" or "heat")
webasto/receiver/minutes/set       (command: integer 10-90)
webasto/receiver/mode/state        (status: current mode)
webasto/receiver/temperature/state (status: heater temp °C)
webasto/receiver/voltage/state     (status: battery voltage V)
webasto/receiver/power/state       (status: heater power W)
webasto/receiver/availability      (LWT: "online" or "offline")

HomeAssistant Autodiscovery (Phase 3)

Discovery Payload

Published to: homeassistant/climate/webasto_receiver/config

Key fields:

• •Device info: identifiers, manufacturer, model, sw_version
• •Climate entity: modes ["off", "heat"], temperature as runtime minutes
• •Command topics: mode/set, minutes/set
• •State topics: mode/state, temperature/state, voltage/state, power/state
• •Availability: LWT topic for online/offline status

Discovery message is retained and republished on MQTT reconnect.

Climate Entity Mapping

• •Mode "off" → W-BUS stop() command
• •Mode "heat" → W-BUS startParkingHeater(minutes) command
• •"Temperature" control → Repurposed as runtime minutes (10-90 in steps of 10)
• •Current temperature sensor → Actual heater temperature from W-BUS page 0x05

Integration (Phase 4)

Main Loop Structure

void loop() {
  // 1. Primary functions (highest priority, always run)
  menu.update();
  loraLink.recv(...);
  wbus.readOperatingState(...);
  
  // 2. MQTT (lowest priority, non-blocking)
  #ifdef ENABLE_MQTT_CONTROL
    wifiMgr.update();  // ~1-2ms
    if (wifiMgr.isConnected()) {
      mqttClient.update();  // ~2-5ms
      
      // Publish status every 30s
      if (millis() - lastPublish > 30000) {
        mqttClient.publishStatus(gStatus);
        lastPublish = millis();
      }
    }
  #endif
  
  // 3. OLED refresh
  ui.render();
}

Command Callback

MQTT commands execute W-BUS commands via callback:

mqttClient.setCommandCallback([](const MQTTCommand& cmd) {
  switch (cmd.type) {
    case MQTTCommand::STOP:
      wbus.stop();
      gStatus.state = HeaterState::Off;
      break;
    case MQTTCommand::START:
      wbus.startParkingHeater(cmd.minutes);
      gStatus.state = HeaterState::Running;
      break;
    // ...
  }
  mqttClient.publishStatus(gStatus);  // Immediate ACK
});

Phase 6: Diagnostic Sensors ✅

Files: Extended mqtt_client.{h,cpp}, modified main.cpp

Additional Sensors

1. •LoRa RSSI (dBm): Signal strength from last received LoRa command
2. •LoRa SNR (dB): Signal-to-noise ratio for link quality monitoring
3. •Last Command Source: "lora", "mqtt", or "button" (tracks control method)
4. •W-BUS Health: {"status": "healthy|unhealthy", "details": "..."} (JSON payload)

Autodiscovery

Each sensor gets discovery message published to:

• •homeassistant/sensor/webasto_receiver_lora_rssi/config
• •homeassistant/sensor/webasto_receiver_lora_snr/config
• •homeassistant/sensor/webasto_receiver_last_cmd_source/config
• •homeassistant/sensor/webasto_receiver_wbus_health/config

Publishing Interval

• •Status sensors (temp/voltage/power): Every 30s
• •Diagnostic sensors: Every 60s (configurable via MQTT_DIAGNOSTIC_INTERVAL_MS)

Command Source Tracking

// In LoRa command handler
gLastCommandSource = "lora";

// In MQTT command callback
gLastCommandSource = "mqtt";

// In menu button handler
gLastCommandSource = "button";

Phase 7: OTA Updates ✅

Files: lib/common/ota_updater.{h,cpp}, extended mqtt_client.cpp and main.cpp

OTA Trigger

MQTT topic: webasto/receiver/ota/update Payload:

{
  "url": "http://192.168.1.100:8080/firmware.bin",
  "username": "optional_http_basic_auth",
  "password": "optional_password"
}

Safety Checks

1. •Heater running check: OTA BLOCKED if heater is running
2. •WiFi requirement: OTA only when WiFi connected
3. •Error recovery: ESP32 rollback protection prevents bricking

OTA Status Publishing

Topic: webasto/receiver/ota/status Statuses:

• •"requested" - OTA command received
• •"starting" - Beginning firmware download
• •"success" - Update successful (device will reboot)
• •"failed" - Update failed (error message included)
• •"deferred" - Cannot update now (heater running)
• •"error" - Error occurred

OTA Progress Reporting

otaUpdater.setProgressCallback([](size_t current, size_t total) {
  uint8_t percent = (current * 100) / total;
  ui.setLine(0, "OTA Update");
  ui.setLine(1, String(percent) + "% complete");
  ui.render();
});

Implementation Details

Uses ESP32's Update.h library:

HTTPClient http;
http.begin(url);
int httpCode = http.GET();
int contentLength = http.getSize();
Update.begin(contentLength);
WiFiClient* stream = http.getStreamPtr();
size_t written = Update.writeStream(*stream);
Update.end();
ESP.restart();  // Reboot with new firmware

Credential Management (Production)

Pattern: Template-based credentials (never commit real credentials to git)

Files

• •include/credentials.h.template - Template with placeholders (commit to git)
• •include/credentials.h - Real credentials (in .gitignore, never commit)
• •.gitignore - Contains include/credentials.h

Setup Process

cp include/credentials.h.template include/credentials.h
# Edit credentials.h with real values
# Build firmware

Template Structure

// WiFi WPA2 Enterprise
#define MQTT_WIFI_SSID "your-ssid-here"
#define MQTT_WIFI_USERNAME "your-username@domain.edu"
#define MQTT_WIFI_PASSWORD "your-password-here"
#define MQTT_WIFI_ANONYMOUS_ID ""

// MQTT Broker
#define MQTT_BROKER "192.168.1.100"
#define MQTT_PORT 1883
#define MQTT_CLIENT_ID "webasto_receiver"
#define MQTT_USERNAME ""
#define MQTT_PASSWORD ""

// OTA Updates
#define OTA_UPDATE_URL ""
#define OTA_UPDATE_USERNAME ""
#define OTA_UPDATE_PASSWORD ""

Configuration Options

All in include/project_config.h:

// Feature flags
#define ENABLE_MQTT_CONTROL           // Master switch (comment out to disable all MQTT)
#define MQTT_ENABLE_DIAGNOSTIC_SENSORS // Phase 6
#define MQTT_ENABLE_OTA                // Phase 7

// WiFi parameters
#define MQTT_WIFI_TIMEOUT_MS 10000         // Connection timeout
#define MQTT_WIFI_RETRY_INTERVAL_MS 60000  // Retry interval on failure

// MQTT parameters
#define MQTT_TOPIC_BASE "webasto/receiver"
#define MQTT_DISCOVERY_PREFIX "homeassistant"
#define MQTT_CMD_MAX_AGE_SEC 3600          // Stale command threshold
#define MQTT_STATUS_INTERVAL_MS 30000      // Status publish interval
#define MQTT_DIAGNOSTIC_INTERVAL_MS 60000  // Diagnostic publish interval

// OTA parameters
#define OTA_CHECK_INTERVAL_MS 21600000     // 6 hours
#define OTA_UPDATE_TOPIC "webasto/receiver/ota/update"
#define OTA_STATUS_TOPIC "webasto/receiver/ota/status"

Resource Usage

Flash (Program Memory)

• •WiFi Manager: ~8 KB
• •PubSubClient library: ~15 KB
• •MQTT wrapper + autodiscovery: ~5 KB
• •Phase 6 (diagnostics): ~5 KB
• •Phase 7 (OTA): ~8 KB
• •Total: ~41 KB (acceptable for ESP32's 4MB flash)

RAM (Runtime Memory)

• •WiFi state: ~1 KB
• •MQTT client buffers: ~2 KB
• •JSON parsing buffer: ~512 bytes
• •Phase 6 state: ~1 KB
• •Phase 7 state: ~2 KB
• •Total: ~6.5 KB (acceptable for ESP32's 520KB SRAM)

Performance

• •WiFi manager update: ~1-2ms per loop
• •MQTT client update: ~2-5ms per loop
• •Status publishing: ~10-20ms every 30s
• •Loop overhead: <10ms (negligible impact on LoRa reception)

Troubleshooting

WiFi Not Connecting

1. •Check SSID/username/password in credentials.h
2. •Monitor serial output: [WiFi] Connecting... → [WiFi] Connected!
3. •For WPA2 Enterprise: Verify anonymous_id requirement with network admin
4. •Check router DHCP availability
5. •Verify ESP32 can reach the network (try simple WiFi.begin() test)

MQTT Not Connecting

1. •Verify broker IP/port in credentials.h
2. •Check broker is running: mosquitto -v or check HA add-on status
3. •Test broker with mosquitto_pub/sub: mosquitto_sub -h BROKER_IP -t '#' -v
4. •Check firewall allows port 1883
5. •Serial output shows: [MQTT] Connection failed, rc=X (see PubSubClient error codes)

HomeAssistant Not Discovering

1. •Check MQTT integration is enabled in HA
2. •Verify discovery prefix matches HA config (default: homeassistant)
3. •Check retained messages in broker: mosquitto_sub -h BROKER_IP -t 'homeassistant/#' -v
4. •Force rediscovery: Disconnect/reconnect WiFi on receiver
5. •Check HA logs for MQTT discovery errors

Stale Command Rejection

1. •Verify NTP sync working: configTime(0, 0, "pool.ntp.org")
2. •Check system time: time(nullptr) should return current epoch
3. •Serial shows: [MQTT-CMD] Command too old: X seconds
4. •Ensure HomeAssistant and receiver clocks are synchronized

OTA Update Issues

1. •"Heater must be OFF for OTA": Stop heater first, then retry
2. •"WiFi required for OTA": Ensure WiFi connected before triggering OTA
3. •Download failed: Check firmware server is running and accessible
4. •Write failed: Verify firmware file is valid .bin for ESP32
5. •Update loop: Check firmware boots successfully (serial output on boot)

Testing Checklist

Basic MQTT Control

• • WiFi connects successfully
• • MQTT broker connection established
• • HomeAssistant discovers device automatically
• • Send "heat" mode from HA → heater starts
• • Send "off" mode from HA → heater stops
• • Status updates appear in HA sensors

Command Source Tracking (Phase 6)

• • Send LoRa command → sensor shows "lora"
• • Send MQTT command → sensor shows "mqtt"
• • Send button command → sensor shows "button"

Diagnostic Monitoring (Phase 6)

• • LoRa RSSI/SNR update when LoRa command received
• • W-BUS health shows "healthy" during normal operation
• • W-BUS health shows "unhealthy" when communication errors occur

OTA Updates (Phase 7)

• • OTA deferred when heater running (safety check)
• • OTA proceeds when heater OFF + WiFi connected
• • Progress displayed on OLED (0% → 100%)
• • Device reboots with new firmware
• • Status published to MQTT during OTA process

Edge Cases

• • WiFi drops mid-operation → MQTT disconnects gracefully, LoRa continues
• • MQTT command while heater running → executes correctly
• • Stale command (>1h old) → rejected with log message
• • Multiple control sources (LoRa + MQTT) → state syncs correctly
• • Deep sleep wake → WiFi reconnects, MQTT resumes

Lessons Learned

WiFi Manager

• •BSSID caching: Reduces reconnect time from 5s to 1-2s (significant for car use)
• •Timeout enforcement: Critical to prevent blocking main loop
• •Event callbacks: Use WiFi events instead of polling WiFi.status() for efficiency

MQTT Client

• •Callback-based commands: Cleaner than polling topics in main loop
• •Retained messages: Essential for state persistence across reboots
• •LWT (Last Will): Provides availability status without polling

HomeAssistant Integration

• •Climate entity mapping: "Temperature" control repurposed as runtime minutes (creative but works)
• •Autodiscovery timing: Publish on boot + reconnect ensures HA always has current config
• •Sensor attributes: JSON payloads allow rich diagnostic data (e.g., W-BUS health details)

OTA Updates

• •Safety first: Never update while heater running (could leave heater on)
• •Progress reporting: User feedback critical for 1-2 minute update process
• •HTTP server: Simple Python HTTP server sufficient for local testing: python3 -m http.server 8080
• •Rollback protection: ESP32 Update library handles corrupted firmware gracefully

Credential Management

• •Template pattern: Industry standard for open-source projects
• •Git safety: .gitignore prevents accidental credential commits
• •Build-time inclusion: No runtime parsing overhead

Future Enhancements

Potential Improvements

• •NVS credential storage: Web-based credential config (avoid recompilation)
• •MQTT TLS/SSL: Encrypted MQTT connection (port 8883)
• •Certificate-based WPA2: Use client certificates instead of username/password
• •Scheduled operations: Cron-style heater scheduling via MQTT
• •Geofencing: Auto-disable WiFi when car moves (GPS integration)
• •Battery protection: Disable WiFi when battery voltage < threshold
• •A/B partition OTA: Use ESP32's dual-partition feature for safer updates
• •Firmware version tracking: Publish current version to MQTT
• •Remote diagnostics: Detailed error reporting to HomeAssistant
• •Multi-language OLED: Internationalization for status messages

References

• •PubSubClient docs: https://pubsubclient.knolleary.net/
• •ESP32 WPA2 Enterprise: https://github.com/martinius96/ESP32-eduroam
• •HomeAssistant MQTT discovery: https://www.home-assistant.io/integrations/mqtt/#mqtt-discovery
• •ESP32 OTA updates: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/ota.html