Quick Start & Workflows

This guide will walk you through the physical construction of your optical hardware adapter and help you choose the right software deployment strategy based on your end goals.

1. Hardware Adapter Setup

The proprietary diagnostic port on your appliance relies on bidirectional infrared communication. You must build a custom optical transceiver to interface with it.

Required Components

  • Microcontroller: An ESP32-C3 or ESP32-C6 development board.
  • Optical Transceiver: An OSRAM Multi TOPLED SFH 7250 (or equivalent combined infrared emitter and phototransistor).
  • Pull-up Resistor ($R_P$): A resistor to pull the RX line high. The value of $R_P$ dictates the phototransistor's sensitivity to incoming infrared light. A value of approximately $47\,\text{k}\Omega$ is recommended for most setups. Lower values decrease sensitivity (requiring stronger light), while higher values increase sensitivity but may introduce noise from ambient light.

Wiring Definitions

The firmware defaults to using the UART1 peripheral for optical communication. Wire your components as follows:

  • Pin 0: RX (Optical Receiver / Phototransistor Collector). Attach the $47\,\text{k}\Omega$ pull-up resistor between this pin and 3.3V.
  • Pin 1: TX (Optical Emitter / IR LED Anode). Remember to include an appropriate current-limiting resistor in series to prevent burning out the LED or the ESP32 GPIO pin.
  • Pin 10: Status LED (Active-low). Provides visual feedback of system status and MQTT connectivity.

Best Practice: If you are designing a custom PCB or need to route traces differently, you can override these default pin assignments in the home/.cargo/config.toml file before compiling the firmware.

2. Choose Your Workflow

Once your adapter is soldered and assembled, choose the workflow that matches your objectives:

Use Case A: Device Diagnostics and Testing (Right to Repair)

Goal: View fault codes, test pumps, or read live sensor data directly from your laptop.

  1. Flash the Home Firmware in bridge mode onto your communication adapter.
  2. Apply electrical tape or a 3D-printed shroud over the adapter to block out ambient room light.
  3. Tape or hold the adapter securely over the diagnostic optical port on your appliance's front panel.
  4. Run the TUI Application on your desktop computer, pointing it to the USB serial port of your adapter (e.g., freemdu-tui /dev/ttyACM0).

Use Case B: Home Automation Integration (Smart Home)

Goal: Persistently connect your appliance to Home Assistant to trigger automations (e.g., "Notify my phone when the washing machine is done").

  1. Open home/.cargo/config.toml and configure your local Wi-Fi SSID, password, and MQTT broker credentials.
  2. Flash the Home Firmware in standalone mode.
  3. Securely mount the adapter to the appliance. Upon booting, the ESP32 will connect to your network, negotiate the optical protocol with the appliance, and use MQTT Auto-Discovery to seamlessly expose sensors and entities in Home Assistant.

Use Case C: Building Custom Tools

Goal: Write custom scripts to automate specific testing routines or reverse-engineer unknown memory addresses.

  1. Flash the adapter in bridge mode.
  2. Add the FreeMDU Protocol Library (freemdu crate) as a dependency to your own Rust project.
  3. Utilize the library's high-level abstractions or low-level memory access APIs to implement your custom logic.

Troubleshooting Hardware Issues

  • No Response / Connection Timeouts: The optical interface is highly susceptible to ambient light. If the TUI fails to connect, ensure the transceiver is completely shielded from overhead room lighting or sunlight.
  • Reversed Polarity: Ensure the TX and RX lines are correctly oriented against the appliance interface. The appliance's LED must align with your phototransistor, and your LED must align with the appliance's photodiode. If communication fails, try rotating the adapter 180 degrees.