Home Firmware

The FreeMDU Home Firmware is a specialized Rust application designed specifically for Espressif RISC-V microcontrollers (ESP32-C3 and ESP32-C6). It powers the physical optical adapter and provides dual operational capabilities, serving either as a transparent debugging tool or as a fully autonomous smart home integration.

Environment Configuration

Before compiling the firmware, you must statically configure your hardware environment. All settings are defined in the Cargo configuration file.

Open home/.cargo/config.toml and update the environment variables to match your specific hardware build and network layout:

[env]
# --- Hardware Pin Assignments ---
# Define which GPIO pins connect to your optical transceiver
PIN_LED_STATUS = "10"   # Active-low status LED
PIN_OPTICAL_RX = "0"    # Connected to Phototransistor (RX)
PIN_OPTICAL_TX = "1"    # Connected to IR LED (TX)

# --- Network Credentials (Required for Standalone Mode) ---
WIFI_SSID = "Your_IoT_Network"
WIFI_PASSWORD = "Your_Secure_Password"

# --- MQTT Broker Details (Required for Standalone Mode) ---
MQTT_HOSTNAME = "192.168.1.100"
MQTT_USERNAME = "homeassistant"
MQTT_PASSWORD = "mqtt_secret_token"

# --- Operational Settings ---
# Polling interval (in seconds) for querying the appliance and publishing to MQTT
DEVICE_PUBLISH_INTERVAL = "60"

Mode 1: Bridge Mode

In bridge mode, the ESP32 acts as a dumb, transparent USB-to-UART pass-through device. It bi-directionally forwards raw bytes between your computer's USB port and the physical infrared transceiver. The ESP32 does not process or understand the Miele protocol in this mode.

When to use this: Use bridge mode exclusively when running desktop-based diagnostic tools, such as the FreeMDU TUI, or when executing custom freemdu scripts from your PC.

Build Command: 

cargo run --features esp32c6 --target riscv32imac-unknown-none-elf --release --bin bridge

Mode 2: Standalone Mode (Smart Home Integration)

In standalone mode, the ESP32 operates autonomously. It embeds the entire freemdu protocol library internally, handles the appliance handshake, negotiates the 3-second security lock, and connects to your local Wi-Fi network as an MQTT client.

Build Command: 

cargo run --features esp32c6 --target riscv32imac-unknown-none-elf --release --bin standalone

Home Assistant MQTT Auto-Discovery

The standalone firmware deeply integrates with Home Assistant via MQTT Discovery. When the adapter boots up and successfully handshakes with the appliance, it automatically registers the device and its capabilities in Home Assistant—no manual configuration.yaml editing is required.

Receiving Sensor Data: The adapter periodically polls the appliance (based on DEVICE_PUBLISH_INTERVAL) and publishes the properties to specific MQTT topics.

  • Format: freemdu_home/<HARDWARE_MAC_ADDRESS>/<PROPERTY_ID>/value
  • Example: freemdu_home/b43a45abcdef/program_phase/value

Triggering Remote Actions: You can remotely command the appliance by publishing payloads to action topics.

  • Format: freemdu_home/<HARDWARE_MAC_ADDRESS>/<ACTION_ID>/trigger
  • Example: freemdu_home/b43a45abcdef/start_drain_pump/trigger

If a specific action requires a parameter (e.g., setting a temperature), the string payload attached to the MQTT publish message will be parsed as the argument. Actions that do not require parameters will ignore the payload entirely.

Limitation Note: Due to architectural limitations in Home Assistant's native MQTT Button platform, actions that require parameters cannot be automatically generated as simple UI buttons in the dashboard. You must trigger them via custom scripts, automations, or direct MQTT publish service calls.

Troubleshooting Connectivity

  • Wi-Fi Failures: If the status LED continuously blinks rapidly, the adapter cannot connect to the Wi-Fi network. Double-check the 2.4GHz SSID and password in config.toml.
  • MQTT Connection Drops: Ensure your MQTT broker allows connections from the IP range the ESP32 is operating on.
  • No Entities in Home Assistant: Ensure your Home Assistant MQTT integration has "Enable discovery" turned on. You can also use tools like MQTT Explorer to verify that the ESP32 is actually publishing to the homeassistant/sensor/freemdu_home_... discovery topics.