homeassistant_espscreen/docs/CALIBRATING.md

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:

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:

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

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

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:

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:

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. Don't just raise the tolerance to get the test to pass. Report any remaining hardware deviation honestly.

Back to normal operation

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.

If calibration mode was opened only via the API, you can close it:

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.