# echavet/mitsubishicn105esphome architecture

> Architecture diagram of the GitHub repository echavet/mitsubishicn105esphome, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/echavet/mitsubishicn105esphome
- Repository: https://github.com/echavet/mitsubishicn105esphome

## Overview

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”.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Hardware Layer
    subgraph "Hardware Layer"
        Board["ESP32 Microcontroller"]:::hardware
        BoardConfig["Board Config"]:::hardware
        CN105["CN105 Connector Interface"]:::hardware
        HeatPump["Mitsubishi Heat Pump"]:::hardware
        Display["Display Module"]:::hardware
        BTProxy["BT Proxy Module"]:::hardware
        ExtraHW["Extra Hardware Example"]:::hardware
    end

    %% Firmware/Software Layer
    subgraph "Firmware/Software Layer"
        ESPHOME["ESPHome Core Firmware (OTA, WiFi, API, Web Server)"]:::firmware
        Configuration["Configuration/Includes"]:::firmware
        CustomClimate["Custom CN105 Climate Component"]:::firmware
        UARTComm["UART Communication Subsystem"]:::firmware
        Sensors["Sensors & Logging Modules"]:::firmware
    end

    %% Integration Layer
    subgraph "Integration Layer"
        HA["HomeAssistant API Integration"]:::integration
        MQTT["MQTT Integration"]:::integration
        OTA["OTA & Web Server Channel"]:::integration
    end

    %% Connections between Integration and Firmware
    HA -->|"commands"| ESPHOME
    MQTT -->|"commands"| ESPHOME
    ESPHOME -->|"manages"| CustomClimate
    ESPHOME -->|"configures"| Configuration
    ESPHOME -->|"controls"| Board

    %% Connections within Firmware
    CustomClimate -->|"processes"| UARTComm
    UARTComm -->|"controls via UART"| CN105
    CN105 -->|"sends_data"| Sensors

    %% Connections from Firmware to Hardware
    BoardConfig -->|"configures"| Board
    Board -->|"connects to"| CN105
    CN105 -->|"communicates with"| HeatPump

    %% Additional Hardware Modules connections
    Board -->|"interfaces with"| Display
    Board -->|"interfaces with"| BTProxy
    Board -->|"interfaces with"| ExtraHW

    %% Integration Layer receiving sensor data
    Sensors -->|"reports"| HA

    %% ESPHOME providing OTA/Web services
    ESPHOME -->|"provides"| OTA

    %% Click Events
    click CustomClimate "https://github.com/echavet/mitsubishicn105esphome/tree/main/components/cn105"
    click UARTComm "https://github.com/echavet/mitsubishicn105esphome/tree/main/components/cn105"
    click ESPHOME "https://github.com/echavet/mitsubishicn105esphome/tree/main/atoms3/includes"
    click Configuration "https://github.com/echavet/mitsubishicn105esphome/tree/main/atoms3/includes"
    click MQTT "https://github.com/echavet/mitsubishicn105esphome/blob/main/atoms3/includes/mqtt-config.yaml"
    click HA "https://github.com/echavet/mitsubishicn105esphome/blob/main/atoms3/includes/ha-integration-config.yaml"
    click Sensors "https://github.com/echavet/mitsubishicn105esphome/blob/main/atoms3/includes/sensor-config.yaml"
    click Display "https://github.com/echavet/mitsubishicn105esphome/blob/main/atoms3/includes/display_config.yaml"
    click BTProxy "https://github.com/echavet/mitsubishicn105esphome/blob/main/atoms3/includes/bt-proxy-config.yaml"
    click ExtraHW "https://github.com/echavet/mitsubishicn105esphome/tree/main/example-XiaoESP32S3"
    click BoardConfig "https://github.com/echavet/mitsubishicn105esphome/blob/main/esp32-test.yaml"

    %% Styles
    classDef hardware fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef firmware fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef integration fill:#FFD700,stroke:#000,stroke-width:2px;
```
