How echavet/mitsubishicn105esphome works
Based on our analysis of both the file tree and the README, this project is clearly an embedded firmware for ESP32 (and optionally ESP8266) devices that integrates with ESPHome. Its main purpose is to control a Mitsubishi heat pump via the specialized CN105 connector using UART communication. The firmware not only talks directly to the heat pump hardware (using an adapted version of the SwiCago library) but also integrates with Home Assistant and supports MQTT as well as a built-in web interface.
Main Components
• Hardware Layer:
• ESP32/ESP8266 microcontroller board with WiFi capability.
• The CN105 connector interface that physically links the microcontroller board to the Mitsubishi heat pump.
• (Optional) Additional hardware modules (display, sensors, etc.) as indicated by configuration files like “atoms3”, “example-XiaoESP32S3”, etc.
• Firmware/Software Layer:
• ESPHome framework integration that handles OTA updates, WiFi, API and web server functions.
• The custom “climate” component (found in components/cn105) that implements the communication protocol with the Mitsubishi heat pump.
• A set of supporting modules/features: UART communication handling, logging, sensor data acquisition (sensors for remote temperature, compressor frequency, stage sensor, etc.).
• External components and YAML configuration includes (found in atoms3/includes) that hold configuration parameters such as API, sensor, MQTT, binary sensor, display, and WiFi configurations.
• Integration and Communication Layer:
• HomeAssistant API components and integrations: climate control entities, logging, and diagnostic sensors.
• MQTT service compatibility (for external MQTT clients).
• Web server / OTA update channel.
Relationships and Data Flows
• The ESP microcontroller (hardware) runs the custom firmware based on ESPHome, which in turn hosts the climate component for controlling the heat pump.
• The custom climate component communicates over UART to perform bi-directional data exchange with the Mitsubishi heat pump.
• The firmware receives temperature readings, command setpoints, and control instructions from HomeAssistant via the API (and sometimes MQTT). This data is forwarded to the climate component to adjust heating/cooling operations.
• Diagnostic sensors (like uptime, WiFi signal, and various “dg_…” sensors) provide status and logging information that flows up to HomeAssistant and are viewable via the integrated web server.
• OTA updates and build configuration files ensure that the device firmware is updated as needed and integrated with ESPHome’s build system.
Architectural Patterns and Design Principles
• Modularity: The code is divided into multiple clearly separated components and configuration “includes” – for example, separate directories for custom components and configuration definitions (e.g., atoms3/includes, components/cn105); this signals a modular design pattern.
• Inversion of Control: The integration with ESPHome’s component system relies on lifecycle methods like loop() where the climate component performs scheduled interactions with the heat pump.
• Non-blocking I/O: The UART reads/writes are implemented to maximize responsiveness by accumulating data byte-by-byte.
Specific Technologies, Frameworks, and Libraries
• ESPHome framework (with details like ESP-IDF for ESP32 or Arduino framework).
• MQTT and HomeAssistant API integrations.
• SwiCago/HeatPump library (embedded adapter code further integrated inside the “cn105” component).
• YAML configurations (which drive the component behavior).
Essential Architectural Elements in Detail
• Don’t shy away from sub-dividing the climate component further, for instance, separating “Command Processing”, “UART Communication”, and “Diagnostic Logging”.