# 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 screen's own ESPHome YAML, the one ESP Screens wrote when it was installed, and add your own `calibration.yaml` to its `packages:` (it starts as identity). Don't carry over another panel's correction. ```yaml packages: display: ... # what ESP Screens put there local_overrides: !include kitchen.local.yaml # idem calibration: !include calibration.yaml ``` 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 .yaml --device ``` 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 --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, which the screen's YAML imports 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 .yaml --device ``` Close the log reader with Ctrl+C and collect **new taps**: ```sh python tools/calibrate.py capture --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 .yaml --device ``` No `-s CALIBRATION_ON_BOOT true` is given here; the profile keeps it `false`. Then check the real thing: the tiles, the navigation and a few taps in the corners. Most screens never need this. A CYD shows its calibration on the screen itself when it first starts, and its **Calibrate touch** button in Home Assistant (on the screen's ESPHome device) starts it again. This USB route is for a panel that stays off after that, or for a measurement report. 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.