Max Gramser
3e959b3df9
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>
128 lines
5.0 KiB
Markdown
128 lines
5.0 KiB
Markdown
# 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.
|