Installation & Setup

This guide covers the necessary steps to set up your environment, compile the FreeMDU desktop applications, and flash the hardware communication adapter.

Because FreeMDU is a modern, performance-focused project, all core components are written in Rust. Before using any FreeMDU software, ensure you have the Rust toolchain installed via rustup.

Prerequisites & System Requirements

  • Operating System: Linux, macOS, or Windows. (Linux is highly recommended for optimal serial port handling).
  • Rust Toolchain: Version 1.70.0 or higher.
  • Hardware: An ESP32-C3 or ESP32-C6 development board (for the optical adapter).

1. Terminal UI (TUI) Installation

If your goal is to repair or test your appliance directly from a laptop or desktop computer, you will need the FreeMDU Terminal UI (TUI).

Clone the repository and build the crate from source using Cargo:

git clone https://github.com/medusalix/FreeMDU.git
cd FreeMDU/tui
cargo build --release

Once compiled, the executable binary will be located at target/release/freemdu-tui. You can move this binary to your $PATH (e.g., /usr/local/bin/) for easier access globally.

Linux Serial Port Permissions

Common Pitfall: On Linux systems, accessing serial ports (like /dev/ttyACM0 or /dev/ttyUSB0) usually requires elevated privileges. Rather than running the TUI as root using sudo, add your user to the dialout or uucp group:

sudo usermod -aG dialout $USER
# You will need to log out and log back in for this to take effect.

2. Home Firmware (Communication Adapter)

To physically interface with your appliance, you must build an optical communication adapter and flash it with the freemdu-home firmware. The FreeMDU firmware currently supports modern Espressif RISC-V microcontrollers, specifically the ESP32-C3 and ESP32-C6.

Installing ESP Flashing Tools

To flash the compiled firmware over USB to your microcontroller, install the official espflash utility:

cargo install espflash --locked

Building and Flashing the Firmware

Navigate to the home directory. The build command relies on specific Cargo target flags depending on your ESP32 model.

For ESP32-C6 (Default / Recommended): 

cd home
cargo run --features esp32c6 --target riscv32imac-unknown-none-elf --release --bin <MODE>

For ESP32-C3: 

cd home
cargo run --features esp32c3 --target riscv32imc-unknown-none-elf --release --bin <MODE>

Selecting a Firmware Mode

When running the flash command, you must replace <MODE> with one of two specific binaries:

  • bridge: Configures the ESP32 to act as a transparent USB-to-Optical serial bridge. Use this if you want to run the TUI on your laptop.
  • standalone: Configures the ESP32 to connect to your Wi-Fi network and publish appliance data directly to Home Assistant via MQTT.

For an in-depth breakdown of these modes and help building the physical hardware, proceed to the Quick Start guide.