Max Gramser
08197c4ae1
The CYD restarted under load: a slider fill rounded less than its track made LVGL draw the fill into a buffer of its own size on every redraw (15-20 KB), and when that allocation failed the refresh retried until the task watchdog fired. Track and fill now share one radius, and tests/test_layer_free.py keeps every layer-making style out of the profiles, the packages and the firmware headers. A tile keeps only the fields every card uses; climate modes, select options, weather, sun and timer times, the media title and the vacuum rows moved to an Extra block that exists only while a state needs one, and the state copy became a fingerprint. runtime_tiles::model went from 24,296 to 8,216 bytes. The manual profile that bound tiles to fixed entities in the YAML is gone: 331 TILE* substitutions, DYNAMIC_TILES/TILE_COUNT/DIRECT_ACTIONS, the 80 Home Assistant subscriptions, its tap handlers and scripts, its own vacuum card, its guides and helper scripts, and the five stale header copies in the repository root that two C++ tests were compiling instead of the components. esphome config of both Easy profiles is unchanged by that cleanup. tile_scroll and the wake overlay no longer light up on a tap, and the debug sensor min_free reports the lowest free heap since boot. On the bench CYD static RAM went from 32.0% to 22.8% and free heap from 64-77 KB to about 101 KB, with 78 KB as the lowest point over thirteen hours without a restart. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
79 lines
4.8 KiB
Markdown
79 lines
4.8 KiB
Markdown
## Easy Setup and releases
|
||
|
||
The preferred route for new users is docs/EASY_SETUP.md: ESP Screen Manager
|
||
plus remote ESPHome packages. No token or blueprint needed. Tiles live in the
|
||
persistent add-on data; Wi-Fi/API/OTA stay in the device's own ESPHome YAML. Read
|
||
docs/RELEASING.md before publishing updates. Main distributes both boards.
|
||
Every push to GitHub is a release: always also bump the add-on version in
|
||
screen_manager/config.yaml (with a CHANGELOG line), otherwise HA won't see an update.
|
||
Generate packages with tools/generate_packages.py; don't edit them by hand.
|
||
A screen gets its tiles from the add-on while it runs: every card works in all
|
||
twenty positions, and no Home Assistant entity belongs in a board profile.
|
||
Preserve the data schema, protocol compatibility, unique keys, and CYD preferences.
|
||
Test updates against existing data. Don't publish an unknown storage version without
|
||
a migration. Production Ingress needs no long-lived token or public port.
|
||
|
||
## Guition board
|
||
|
||
The Guition 4848S040 has a separate profile `guition-4848s040.yaml` with
|
||
480×480, ST7701S RGB, and GT911. Read docs/GUITION.md. Don't carry over the CYD
|
||
layout or the XPT2046 calibration.
|
||
Verify touch with tools/verify_gt911.py and keep the CYD regressions green.
|
||
Don't configure wallbox relays as part of display support.
|
||
|
||
# Working instructions for LLMs and developers
|
||
|
||
This project drives an ESP32-2432S028 with ILI9341 + XPT2046 (320×240,
|
||
LVGL 90°). Read README.md and docs/ before installing. The owner can
|
||
physically tap; an agent cannot replace that with software coordinates.
|
||
|
||
## Installing a new screen
|
||
|
||
1. Install it from ESP Screens (docs/EASY_SETUP.md): the add-on writes the screen's
|
||
own ESPHome YAML with its name, Wi-Fi reference and unique keys, and flashes it
|
||
over USB. Identify the USB port and board variant first, and check whether a
|
||
profile for this screen already exists; never overwrite a working one.
|
||
Use ESPHome 2026.6.2 with Python 3.11-3.14. Don't show keys in logs or chat.
|
||
2. CYD: the screen shows its calibration on first boot; the owner taps the
|
||
crosshairs. `tools/calibrate.py` with docs/CALIBRATING.md is the USB route for a
|
||
panel that needs measuring; ask for physical taps per target, and wait for
|
||
confirmation that the measurement screen is visible. A successful build is not a flash.
|
||
Guition: GT911 reports pixels; verify with tools/verify_gt911.py, no ADC calibration.
|
||
3. Pair with the owner's own Home Assistant through the ESPHome integration.
|
||
Read real entity IDs and supported attributes; don't make up entities.
|
||
4. Choose the tiles in ESP Screens. Don't test real device actions without the
|
||
owner's permission, and report which checks were actually carried out,
|
||
the limitations, and how long the screen stayed up.
|
||
|
||
## Code and regressions
|
||
|
||
- Keep base hardware and UI in `home-like-2432s028.yaml`; personal data belongs
|
||
in the gitignored local profiles.
|
||
- Preserve fixed pages, hidden navigation at six tiles or fewer, and a
|
||
minimum default standby of 600 seconds. Don't reintroduce free scrolling
|
||
without physically testing for touch/navigation regressions.
|
||
- Preserve the touch filter and event guard before actions; calibration processes
|
||
filtered physical ADC values. Don't apply the affine correction twice, in both the driver and the UI.
|
||
- The calibration wizard assumes swap_xy=false, mirror_x=true, mirror_y=false,
|
||
and LVGL 90°. A changed orientation also requires a new projection/tests.
|
||
- Run the Python tests, both C++ test suites, and ESPHome validation/build on code changes.
|
||
Firmware tests and hardware acceptance are different checks.
|
||
- `diagnostics/run_ui_test.py` renders without HA actions; don't touch the screen
|
||
during that test. Use `--name` for the expected device identity.
|
||
`diagnostics/send_layout.py` pushes a demo layout with every card type to a
|
||
screen via the API inbox (no HA actions); the manager restores the real
|
||
layout within ~25 s. Guition: `capture_ui.py` saves the LVGL render as a PNG.
|
||
Without a screen: `tools/render_topbar.py` renders the real top-bar code for both
|
||
boards via the ESPHome host + SDL2 to `.esphome/render-topbar/out/sheet.png`.
|
||
- Share through Git. Don't stage secrets, measurements, binaries, logs, build
|
||
caches, or local device profiles.
|
||
- No automatic firmware upload to an arbitrary connected port.
|
||
With multiple boards, first determine the intended port.
|
||
- Profiles with the same `DEVICE_NAME` share `.esphome/build/<name>`.
|
||
Never compile or upload them concurrently; check
|
||
the `firmware.bin` path in the upload log, and then the compile time via
|
||
`device_info`. A wrong profile knocks the screen out of ESP Screen Manager.
|
||
|
||
Historical diagnostics are background context, not proof that a new panel
|
||
works correctly. During onboarding, don't make claims about physical tests that weren't actually performed.
|