Files

T

Max Gramser 3e959b3df9 Put ESP Screens in English and keep layouts when entity IDs change (0.2.40)

Everything a user sees or reads is now English: both boards' labels,
status replies and logs, the ESP Screens editor and Alerts cheatsheet,
and the README and guides (docs/TILES.md, CALIBRATING.md, ACCEPTANCE.md
and TROUBLESHOOTING.md replace the Dutch file names). Labels follow
Home Assistant's own English names (Heat/Cool modes, Heating/Cooling
actions, Away, Returning to dock, weather conditions), dates use English
abbreviations and the top bar writes numbers the English way. Docs use
HA 2026.9's menu names (Settings -> Apps, App store, Settings -> Tools).
Unused legacy files (home-like.yaml, buttons.yaml, a.out) are removed.

Firmware 0.2.34 names its entities in English. Home Assistant registers
a renamed ESPHome entity under a new entity ID, so the inbox
text.<screen>_tegelinstellingen becomes text.<screen>_tile_settings and
the layout stored under the old ID would be lost. The manager now
recognises the screen by its device, during a run or after a restart,
and moves its layout and update history along; the Update button and
the nightly round follow the screen through the rename. Screens that
still run 0.2.33 or older keep working: both languages are matched.

Main is the only release branch from now on.

Tested on a Home Assistant Yellow (HA 2026.9.1) with both bench boards:
see docs/TEST_RESULTS_0240.md.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-09-15 02:08:43 +02:00

4.9 KiB

Raw Blame History

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. Runtime mode supports all cards in all twenty positions. The position constraints below apply only to the old manual profiles. 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. Use its own local guition-device.yaml; don't carry over the CYD layout or 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

Identify the USB port and board variant. Use ESPHome 2026.6.2 with Python 3.11–3.14. First check whether local configuration already exists.
In a fresh copy, use tools/new_device.py to create your own device.yaml, calibration.yaml, secrets.yaml. Never overwrite a working profile. Let the owner fill in Wi-Fi locally. Don't show keys in logs/chat.
Flash device.yaml with the CLI substitution CALIBRATION_ON_BOOT=true. The isolated screen shows five crosshairs and works without HA.
Follow docs/CALIBRATING.md: guided USB capture, fit, flash, new capture, independent verification. Ask for physical taps per target. Wait for confirmation that the measurement screen is actually visible; a successful build is not a flash.
Flash without that override. Pair with the owner's own HA via the ESPHome integration. Read real entity IDs and supported attributes; don't make up entities.
Configure every tile you use according to docs/TILES.md. The vacuum card sits at position 6. Positions 8/10 don't have a full slider/climate binding. Don't test real device actions without the owner's permission.
Go through docs/ACCEPTANCE.md and report the tests actually carried out, limitations, and the observed stability duration.

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 via tools/export_bundle.py or 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 (Easy Setup and manual) 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.