Repository navigation
Releases
v0.2.0
Warning
Installing this can brick your monitor, and there are no guarantees. If an image fails to boot, the only way back is a USB-TTL (3.3 V UART) adapter on the ESP32 inside the case, and getting there means taking out the glued-in screen. Use at your own risk.
New
- Bluetooth proxy for Home Assistant, advertisements only, with a runtime "Bluetooth" switch. It is passive on purpose: proxied GATT connections tripped an ESP32 Bluetooth controller assert after about 2 h of retries to a device that kept failing.
- Measured heat model (
cgdn1_tcomp, select "Heat model"): a two-stage display heat model scaled by brightness, plus a Bluetooth heat term, instead of stock's −1 °C display ramp. Every constant is a Home Assistant config number, with "Display heat estimate" / "Bluetooth heat estimate" sensors so you can tune it while watching graphs. "Stock" keeps the exact stock behaviour. - Humidity at constant vapour pressure in the Measured model (Magnus 17.62 / 243.12). Stock's transfer reads about 4–6 %RH high at the usual self-heat.
- PM1.0 page and an info page in the page ring: PM1.0 → PM2.5 → PM10 → CO2 → T → RH → info. The info page shows version, build, MAC, WiFi and signal, IP, fallback AP, Bluetooth and uptime, then moves on after 10 s.
- Screen messages over MQTT (optional, off by default): notifications and questions on
<name>/notify, answered by a tap or swipe and reported on<name>/notify/response. Build withesphome -s mqtt_messages true compile cgdn1.yamland fill in themqtt_*secrets. The README has a Home Assistant automation example. - README brick warning.
docs/install.md: pass the same-soptions toesphome logsas to the build.
Upgrading from v0.1.0
- With ESPHome's own OTA (trial mode off), build and install as usual.
- In trial mode, return to stock first, then push with
tools/cgdn1_ota_push.pyas in docs/install.md. ESPHome's own OTA would overwrite stock. - New secrets only if you turn on MQTT messages (
mqtt_broker,mqtt_username,mqtt_password).
No prebuilt binary: the image embeds your WiFi credentials and API key, so build it yourself with ESPHome 2026.9.1.
Known limitations
- Tested on one unit: stock 4.8.5, display panel variant B. This release was installed with
tools/cgdn1_ota_push.pyin trial mode; the trial mark and every feature above work on that unit. - Not yet tested on hardware: pushing straight from unmodified stock, the first boot with trial mode off, the "Boot other firmware slot" button, panel variant A.
- The heat model defaults come from one unit; yours may differ, so tune from Home Assistant.
v0.1.0
First release of ESPHome for the Qingping Air Monitor Lite (CGDN1).
Features
- CO2 (SCD40), PM1.0/2.5/10 (PMSA003I), temperature/humidity (SHT4x) with the stock self-heating compensation and adjustable offsets
- Battery voltage and level (stock percent table), charge current, charging state
- OLED with the stock pages and digits, slide on touch, burn-in drift, brightness, night mode
- ATtiny814 touch slider gestures as Home Assistant events
- RGB status LED with the stock level colours (PM standard selectable)
- Back button: click toggles the display, long press powers off (on battery)
Installing
Installed over the air from the stock firmware through its local-MQTT OTA (tools/cgdn1_ota_push.py). No need to open the case: the UART is only reachable inside it, behind a glued-in screen. Start with trial mode (esphome -s trial_mode true compile cgdn1.yaml): every reboot returns to stock. Then install for good. Read docs/install.md first.
Using the components in your own configuration (external_components: github://nemethhh/esphome-qingping-cgdn1@v0.1.0): always include cgdn1_boot. It holds the power latch and supplies the stock partition table, so don't set esp32: partitions:.
No prebuilt binary: the image embeds your WiFi credentials and API key, so build it yourself with ESPHome 2026.9.1.
Known limitations
- Tested on one unit: stock firmware 4.8.5, display panel variant B.
- Not yet tested on hardware: pushing straight from unmodified stock, the first boot with trial mode off, the "Boot other firmware slot" button, panel variant A.
- An image that is well formed but crashes before WiFi comes up can only be recovered over the UART, which means opening the case (the screen is glued in).