Add driver_53xc.py — image capture for 27c6:533c (GF5288_GM168SEC) - #75

Nice work -- this is a much cleaner solution than what I independently arrived at for the same device (I'd opened #76 with a driver built around shelling out to openssl s_server and reading its stdout, plus local per-driver ACK-order workarounds instead of #72's library-level fix; closing it in favor of this stack). A couple of things from my side that might still be useful, from static analysis of the closed .so plus a live capture of the vendor driver's own traffic against a second, different physical 533c unit:

Independent cross-validation on different hardware: all-zero PSK already provisioned and 108x88 sensor size both confirmed on my unit too (not an XPS 13 9310) -- for the PSK that's from a live vendor-driver USB capture that never calls COMMAND_PRESET_PSK_WRITE_R at all, and for the dimensions it's from reshaping decoded pixel data at each plausible width and observing which one produces a coherent 2D shape rather than pure banding. Good sign this isn't specific to one laptop model.

PSK-write ACK convention, in case it's ever needed: this chip's COMMAND_PRESET_PSK_WRITE_R response uses the opposite success convention from every other model goodix.py was written against -- message[0] == 0x01 means success here, not the 0x00 that Device.preset_psk_write() checks for. I only found this because an early write attempt that goodix.py logged as "failed" had actually succeeded (confirmed via a live vendor capture showing the device already held the PSK it was supposedly failing to write). Your driver's design of refusing to run rather than provisioning sidesteps needing this, but it'd bite anyone who reuses preset_psk_write()'s return value directly against this PID.

DEVICE_CONFIG template locations, as a fallback for machines without a working vendor driver to sniff: the closed .so (libfprint-tod-goodix-53xc-0.0.4.so) has six named config templates in .rodata, keyed by what look like project codenames -- MilanF, MilanG, MilanH, MilanL, MilanFn, ChicagoHS -- at fixed offsets. MilanFn (offset 0x103380) is what got accepted (post-checksum-fix, per the shared fix_config_checksum algorithm) on my 0x533c unit, though without live vendor traffic to compare against I can't tell whether it happened to already carry usable per-unit calibration or whether the resulting image would need driver_53x5.py-style OTP splicing to look as good as what you're getting from a live-captured config. Might be a useful bootstrap for 530c/538c owners who don't have easy access to a live vendor-driver capture setup. Full details (including which offset maps to which candidate) at https://github.com/daemonhorn/goodix-533c-re/blob/main/findings/device-config.md if useful -- happy to dig further into any of it if it'd help.

Ran your full stack (#72/#73/#75) against my own 533c unit, not just diffed it -- correction and cross-validation from that:

Correction to my last comment: I speculated the six static DEVICE_CONFIG templates might be a fallback "for owners without a live vendor capture to sniff," on the assumption DEVICE_CONFIG was per-unit-calibrated. That's wrong -- your DEVICE_CONFIG, captured on your XPS 13 9310, was accepted verbatim by upload_config_mcu() on my (different) unit, and produced identical results downstream. So it's not per-machine after all, which also means your PR description's "other 533c machines may need their own" caveat is probably overcautious -- worth softening once someone else confirms.

Further cross-validation, same unit:

• nop()/firmware_version()/reset() all ran clean through _expect_ack() -- no hang, no exception. Whatever ordering quirk I hit while building my own driver, your fix in Tolerate sensors that do not ACK every command #72 handles it fine here too (or my unit just doesn't exhibit it; either way, no bug to report).
• Chip ID 0x220ca1, and both capture byte counts (14334 B encrypted -> 14260 B plain) match your log exactly.
• Finger detection genuinely works: mcu_switch_to_fdt_down fired on a real touch, and reference-vs-live frame correlation was 0.88 with the mean shifting from 3600 to 3996 (0-4095 range) -- real capacitive signal, not a stale/cached frame.
• What I couldn't reproduce: the resulting fingerprint.pgm didn't show clearly visible ridge flow for me the way your writeup describes, even after contrast stretching / per-row detrending. Given the 0.88 correlation (not ~1.0, so there's real differential signal; not the 0.5-ish you'd expect from mostly-noise), my best guess is the single global linear a*reference+b fit in flat_field() doesn't fully compensate between gain 0xc2 (reference) and 0x86 (live) if that gain change isn't perfectly linear on this unit -- but I haven't isolated it further, and it might just be my finger contact technique. Not confident enough to call this a bug -- flagging as a "didn't fully reproduce visually, protocol-level data all checks out" data point rather than a report against your driver.

(Also, independent of your PR: tool.write_pgm() emits {height} {width} where the PGM spec wants width first, so every .pgm this repo writes reads transposed in a standards-compliant viewer, and flat_field()'s output contains negative values that most PGM readers reject outright. Pre-existing repo issue, not something your PR introduced -- just flagging since it tripped me up rendering the output.)

Net: the protocol/config/geometry side of this is now confirmed across two different physical units, which is about as solid as this gets without a third tester. Nice work.

Follow-up to my earlier comment (correlation r=0.88, no visible ridges): found it. Ran a gain sweep with a finger held down through all captures (0x40, 0x50, 0x60, 0x70, 0x86, 0xa0, 0xc2), logging min/max/mean/clipped-pixel-count per gain:

gain 0x40: mean=4094.7 clipped=9501/9504 (fully saturated)
gain 0x50: mean=4092.7 clipped=9393/9504
gain 0x60: mean=4069.7 clipped=9116/9504
gain 0x70: mean=4040.9 clipped=9114/9504
gain 0x86: mean=3909.0 clipped=4462/9504 <- your hardcoded live gain
gain 0xa0: mean=2872.2 clipped=0/9504
gain 0xc2: mean=1446.6 clipped=0/9504 <- your hardcoded *reference* gain

On my unit, 0x86 (the live-capture gain in run_driver()) saturates nearly half the frame with a finger present -- ridge contrast was being clipped off the top of the 12-bit range. 0xc2, which your driver uses for the reference frame, turns out to be the only fully headroom-safe gain for the live frame on my hardware. Re-running flat_field() with the live capture at 0xc2 instead of 0x86 (reference still at 0xc2 too, so no gain mismatch to compensate for) produces a clearly ridge-structured image -- curved, branching bands, not the flat banding I was getting before. Attached for reference (contrast-stretched + median-filtered).

So: the protocol/config were never the problem (as established), and this wasn't a flat_field linearity issue either -- it was gain calibration, and the values you hardcoded for your XPS 13 9310 saturate on mine. Given this varies by unit, might be worth either making the live-capture gain configurable/auto-detected (e.g. a quick pre-sweep checking for clipping before committing to a capture gain), or at minimum noting in the driver that 0x86 is XPS-13-9310-specific and other units may need to sweep for a headroom-safe value.

Planning to build a native (non-TOD) libfprint driver from this next, using goodix-fp-linux-dev/libfprint's goodixtls/goodix5xx.c base class (confirmed it builds cleanly against current libfprint) -- will report back if anything else generalizable turns up.