# syssi/esphome-yeelight-ceiling-light architecture

> Architecture diagram of the GitHub repository syssi/esphome-yeelight-ceiling-light, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/syssi/esphome-yeelight-ceiling-light
- Repository: https://github.com/syssi/esphome-yeelight-ceiling-light

## Overview

##### Project Type and Purpose
- This is a microcontroller firmware project built on top of the ESPHome framework. Its purpose is to provide custom firmware for various Yeelight ceiling-light and lamp devices by defining device behavior in YAML and supplying custom C++ components for PWM outputs, ADC sensors, BLE tracking, fan control, etc.

##### File-Structure Analysis
- Top-level:
- .github/… & .pre-commit-config.yaml / setup.cfg – CI/CD definitions (GitHub Actions), linting.
- components/… – custom C++ components (xiaomi_ble, xiaomi_ylyk01yl, yeelight_fan_controller).
- tests/validate-sdkconfig-options.yaml – CI test harness for YAML configs.
- *.yaml at root – example device configurations (one per supported Yeelight model).
- test-esp32.sh – helper script to flash an ESP32.
- images/ & logs/ – documentation assets and flash logs.
- Patterns:
- Plugin-style: every device or feature lives in its own directory under components and is registered with ESPHome’s core.
- YAML-driven configuration: each device’s behavior is declared in a root-level .yaml which the esphome CLI compiles and flashes.
- CI pipeline orchestrates linting, C++ static analysis, Python linting, YAML validation, and config tests.

##### README Insights
- Confirms it is “Esphome custom firmware for some Yeelight Ceiling Lights.”
- Lists supported models with model numbers and capabilities (PWM channels, ADC sensors, BLE, etc.).
- Outlines features per device type (e.g., CCWW light control, nightlight, RGB ambient).
- Documents GPIO pin mappings for each model and disassembly instructions.

##### Main Components
a. Build & CI Layer
- GitHub Actions workflows (ci.yaml)
- esphome CLI (Python tool)
- PlatformIO/Arduino-ESP32 toolchain
- test-esp32.sh flashing script
- tests YAML validator
b. Source Code
- YAML configuration files (device definitions)
- components/ C++ modules:
- xiaomi_ble (BLE tracker component)
- xiaomi_ylyk01yl (device-specific protocol)
- yeelight_fan_controller (fan speed control)
- Core ESPHome libraries (external)
c. Generated Firmware
- Compiled .bin for ESP32 (includes esphome core + custom components)
d. Hardware Device
- ESP32-WROOM module
- PWM outputs to WW / CW / RGB / Nightlight MOSFETs
- ADC inputs for voltage or light sensors
- UART pins for serial bootloader
- GPIO0 test point for flashing
e. Runtime Integrations
- Wi-Fi connection → Home Assistant (Native API / MQTT)
- BLE scanning (esp32_ble_tracker) → external BLE devices / sensors
- Local sensors and actuators on the light fixture

##### Relationships & Data Flows
1. Developer pushes code + YAML to GitHub → CI triggers → lint & static analysis → tests/ validate YAML
2. esphome CLI reads .yaml → includes custom components from components/ → generates C++ project → compiles via PlatformIO
3. test-esp32.sh (or esphome run) flashes .bin onto ESP32 via UART → device boots
4. Firmware initializes esphome::Application → registers all components → sets up PWM, ADC, BLE, Wi-Fi
5. At runtime:
- Control commands from Home Assistant → over Wi-Fi → esphome native API → light PWM modules
- Sensor readings (voltage, ambient light) → ADC → Home Assistant
- BLE tracker component scans BLE beacons and reports presence to Home Assistant
- Fan controller component sets fan speed via dedicated PWM channel

##### Architectural Patterns & Principles
- Modular/plugin architecture: every feature lives in its own component folder and implements esphome::Component interface.
- YAML-driven code-generation: clear separation of configuration (YAML) and behavior (C++).
- CI/CD ensures code quality, static analysis, and config validation before flashing.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "CI/CD Pipeline"
        direction TB
        GH_Actions["GitHub Actions Workflows"]:::build_tool
        Restore_Python["restore-python Action"]:::build_tool
        Precommit["Pre-commit & Lint Config"]:::build_tool
        YAML_Validator["YAML Validator Test"]:::build_tool
        GH_Actions -->|triggers| Precommit
        GH_Actions -->|runs| Restore_Python
        GH_Actions -->|validates| YAML_Validator
    end

    subgraph "Source Code" 
        direction TB
        YAML_Configs["Device Configuration YAMLs"]:::source
        subgraph "Custom C++ Components"
            direction TB
            Xiaomi_BLE["xiaomi_ble Component"]:::source
            Xiaomi_YLYK["xiaomi_ylyk01yl Component"]:::source
            subgraph "yeelight_fan_controller"
                direction TB
                Yeelight_Fan_Core["yeelight_fan_controller Core"]:::source
                Yeelight_Fan_Driver["Fan Driver Module"]:::source
            end
        end
        ESPHome_Core["ESPHome Core Libraries"]:::external
        YAML_Configs -->|includes| ESPHome_Core
        Xiaomi_BLE -->|implements| ESPHome_Core
        Xiaomi_YLYK -->|implements| ESPHome_Core
        Yeelight_Fan_Core -->|implements| ESPHome_Core
        Yeelight_Fan_Driver -->|used by| Yeelight_Fan_Core
    end

    subgraph "Build & Flash"
        direction TB
        ESPhome_CLI["esphome CLI"]:::build_tool
        PlatformIO["PlatformIO / Arduino-ESP32"]:::build_tool
        Flash_Script["test-esp32.sh"]:::build_tool
        YAML_Configs -->|read by| ESPhome_CLI
        ESPhome_CLI -->|generates| PlatformIO
        PlatformIO -->|compiles .bin| Firmware
        Flash_Script -->|flashes via UART| Firmware
    end

    Firmware["Firmware Binary (.bin)"]:::firmware

    subgraph "Hardware Device (ESP32 Runtime)"
        direction TB
        ESP32["ESP32-WROOM Module"]:::hardware
        PWM["PWM Outputs (WW/CW/RGB/Night)"]:::hardware
        ADC["ADC Inputs (Sensors)"]:::hardware
        UART["UART / GPIO0 Test Point"]:::hardware
        BLE_Hardware["BLE Radio"]:::hardware
        ESP32 --> PWM
        ESP32 --> ADC
        ESP32 --> UART
        ESP32 --> BLE_Hardware
        Firmware -->|flashes to| ESP32
    end

    subgraph "Runtime Integrations"
        direction TB
        Home_Assistant["Home Assistant"]:::external
        BLE_Devices["External BLE Devices"]:::external
        ESP32 -->|Wi-Fi Native API| Home_Assistant
        ESP32 -->|BLE scan reports| Home_Assistant
        BLE_Hardware -->|scans| BLE_Devices
        ADC -->|sensor data| Home_Assistant
        Home_Assistant -->|control commands| PWM
    end

    %% Click Events
    click GH_Actions "https://github.com/syssi/esphome-yeelight-ceiling-light/blob/main/.github/workflows/ci.yaml"
    click Restore_Python "https://github.com/syssi/esphome-yeelight-ceiling-light/blob/main/.github/actions/restore-python/action.yml"
    click Precommit "https://github.com/syssi/esphome-yeelight-ceiling-light/blob/main/.pre-commit-config.yaml"
    click YAML_Validator "https://github.com/syssi/esphome-yeelight-ceiling-light/blob/main/tests/validate-sdkconfig-options.yaml"
    click Flash_Script "https://github.com/syssi/esphome-yeelight-ceiling-light/blob/main/test-esp32.sh"
    click YAML_Configs "https://github.com/syssi/esphome-yeelight-ceiling-light/blob/main/yeelight_light_ceil26.yaml"
    click Xiaomi_BLE "https://github.com/syssi/esphome-yeelight-ceiling-light/blob/main/components/xiaomi_ble/xiaomi_ble.cpp"
    click Xiaomi_BLE "https://github.com/syssi/esphome-yeelight-ceiling-light/blob/main/components/xiaomi_ble/xiaomi_ble.h"
    click Xiaomi_YLYK "https://github.com/syssi/esphome-yeelight-ceiling-light/blob/main/components/xiaomi_ylyk01yl/xiaomi_ylyk01yl.cpp"
    click Xiaomi_YLYK "https://github.com/syssi/esphome-yeelight-ceiling-light/blob/main/components/xiaomi_ylyk01yl/xiaomi_ylyk01yl.h"
    click Yeelight_Fan_Core "https://github.com/syssi/esphome-yeelight-ceiling-light/blob/main/components/yeelight_fan_controller/yeelight_fan_controller.cpp"
    click Yeelight_Fan_Core "https://github.com/syssi/esphome-yeelight-ceiling-light/blob/main/components/yeelight_fan_controller/yeelight_fan_controller.h"
    click Yeelight_Fan_Driver "https://github.com/syssi/esphome-yeelight-ceiling-light/blob/main/components/yeelight_fan_controller/fan/yeelight_fan.cpp"
    click Yeelight_Fan_Driver "https://github.com/syssi/esphome-yeelight-ceiling-light/blob/main/components/yeelight_fan_controller/fan/yeelight_fan.h"

    %% Styles
    classDef build_tool fill:#cccccc,stroke:#333,stroke-width:1px
    classDef source fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef firmware fill:#666666,stroke:#333,stroke-width:1px,color:#fff
    classDef hardware fill:#fff2cc,stroke:#333,stroke-width:1px
    classDef external fill:#d5fed5,stroke:#333,stroke-width:1px
```
