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>
This commit is contained in:
Max Gramser
@@ -0,0 +1,127 @@
|
||||
# Calibrating a new panel
|
||||
|
||||
This protocol is for **320×240, LVGL rotation 90°, swap_xy=false,
|
||||
mirror_x=true, mirror_y=false**. Other orientations, GT911 touch, and other
|
||||
controllers require a separate profile. Don't change rotation or mirroring
|
||||
partway through the measurement.
|
||||
|
||||
The filter in this repo stabilizes the XPT2046 measurements. Calibration then
|
||||
corrects offset, scale, and skew. Calibration does not fix a defective
|
||||
panel, a loose connection, unstable power, or random outliers.
|
||||
|
||||
## Preparing
|
||||
|
||||
1. Use the `device.yaml` from `tools/new_device.py`, with your own
|
||||
`calibration.yaml` that starts as identity. Don't carry over the personal
|
||||
correction from the historical base profile.
|
||||
2. Check the data cable and the USB port with `python -m serial.tools.list_ports`.
|
||||
3. Flash from the repo root:
|
||||
|
||||
```sh
|
||||
python -m esphome -s CALIBRATION_ON_BOOT true run device.yaml --device <USB_PORT>
|
||||
```
|
||||
|
||||
4. Physically check for the **dark screen with five white + marks**.
|
||||
It stays on, and tile actions aren't accessible here.
|
||||
5. Stop the ESPHome log reader with Ctrl+C. Leave the board and USB cable connected.
|
||||
Only one program may use the serial port at a time.
|
||||
|
||||
Wi-Fi/HA aren't needed for this USB route. If the board is already on Wi-Fi,
|
||||
the screen can also be opened via the encrypted API:
|
||||
|
||||
```sh
|
||||
python diagnostics/control_ui.py touch_diagnostics --host display-kitchen.local --name display-kitchen
|
||||
```
|
||||
|
||||
That doesn't change the boot mode. For a new installation, use the
|
||||
USB route above, so calibration mode also stays active after a reset.
|
||||
|
||||
## Measurement A: collecting data
|
||||
|
||||
```sh
|
||||
python tools/calibrate.py capture --port <USB_PORT> --device-name display-kitchen --output measurements-before.json
|
||||
```
|
||||
|
||||
The wizard guides you through **one target at a time**:
|
||||
|
||||
1. Read in the terminal which crosshair is up next.
|
||||
2. Press Enter, then tap only that crosshair **three times**.
|
||||
3. Hold each tap for about half a second and release fully in between.
|
||||
4. Wait for the next terminal prompt. Don't move on to another corner yourself.
|
||||
|
||||
Order: top-left, top-right, bottom-right, bottom-left, center.
|
||||
Use a suitably blunt stylus or a small, deliberate fingertip tap; no
|
||||
sharp point. The targets are at `(20,20)`, `(299,20)`, `(299,219)`, `(20,219)`,
|
||||
and `(160,120)`.
|
||||
|
||||
The wizard only reads touch logs with `calibration=1`. It doesn't flash anything, make
|
||||
any network connection, or send any HA actions. An incomplete measurement is
|
||||
not saved as a valid file. On a mistaken tap: Ctrl+C and start
|
||||
over. Use a new filename if a measurement already exists.
|
||||
|
||||
## Calculating a correction
|
||||
|
||||
```sh
|
||||
python tools/calibrate.py fit measurements-before.json --output calibration.yaml --replace
|
||||
```
|
||||
|
||||
The script:
|
||||
|
||||
- takes the median of the three raw ADC measurements per corner;
|
||||
- determines an affine correction from the four corners;
|
||||
- checks the **center point, which is not used for the fit**;
|
||||
- rejects errors that are too large (>12 px), spread (>18 px), and unusable measurement geometry;
|
||||
- saves the existing `calibration.yaml` as a dated `.bak` before
|
||||
placing a new, complete version.
|
||||
|
||||
The output contains only the four base bounds and six affine coefficients in
|
||||
an ESPHome substitutions map. `device.yaml` imports this as the calibration
|
||||
package. Don't change the coefficients by feel, and don't add a second correction
|
||||
in the driver. The `raw=` logs contain the filtered **physical ADC values**,
|
||||
even once a correction is already set; recalibrating therefore doesn't stack twice.
|
||||
|
||||
A successful fit on existing data is not yet a successful physical test.
|
||||
|
||||
## Measurement B: independently testing the flashed result
|
||||
|
||||
Flash the correction, still with the measurement screen:
|
||||
|
||||
```sh
|
||||
python -m esphome -s CALIBRATION_ON_BOOT true run device.yaml --device <USB_PORT>
|
||||
```
|
||||
|
||||
Close the log reader with Ctrl+C and collect **new taps**:
|
||||
|
||||
```sh
|
||||
python tools/calibrate.py capture --port <USB_PORT> --device-name display-kitchen --output measurements-after.json
|
||||
python tools/calibrate.py verify measurements-after.json
|
||||
```
|
||||
|
||||
`verify` uses the firmware's real `native=` coordinates, rotates them
|
||||
to screen coordinates, and compares them with the targets. It does **not
|
||||
run a new fit**. All five points must pass. Don't accidentally
|
||||
use the pre-flash file for this check.
|
||||
|
||||
Doesn't work? Check which point fails, check the order/pressure, measure again,
|
||||
and read [TROUBLESHOOTING.md](TROUBLESHOOTING.md). Don't just raise the tolerance to get the
|
||||
test to pass. Report any remaining hardware deviation honestly.
|
||||
|
||||
## Back to normal operation
|
||||
|
||||
```sh
|
||||
python -m esphome run device.yaml --device <USB_PORT>
|
||||
```
|
||||
|
||||
No `-s CALIBRATION_ON_BOOT true` is given here. In `device.yaml`, the
|
||||
setting stays `false`. Check the actual tiles and navigation per
|
||||
[ACCEPTANCE.md](ACCEPTANCE.md).
|
||||
|
||||
If calibration mode was opened only via the API, you can close it:
|
||||
|
||||
```sh
|
||||
python diagnostics/control_ui.py end_touch_diagnostics --host display-kitchen.local --name display-kitchen
|
||||
```
|
||||
|
||||
Keep both measurement files and `calibration.yaml` with this physical screen.
|
||||
Start over after replacing the panel; give only the neutral
|
||||
starter files to a next owner.
|
||||
Reference in New Issue
Block a user