How syssi/esphome-yeelight-ceiling-light works
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.