An APDS9960 gesture interrupt is a request to consume gesture data, not proof that one complete swipe is ready. Firmware should read gesture status, drain all valid FIFO datasets and check overflow before it treats the event as finished. Clearing or ignoring the event while data remains can produce repeated interrupts or stale direction decisions.
The APDS-9960 datasheet describes a gesture engine built around four photodiodes—up, down, left and right—and a FIFO that stores their sampled values. The interrupt handler should preserve that grouping.
Start with GVALID and the FIFO level
The device uses I²C address 0x39. In gesture mode, the GVALID status bit indicates that one or more datasets are available in the gesture FIFO. GFLVL reports the number of datasets, while GFIFO_U, GFIFO_D, GFIFO_L and GFIFO_R return the four directional values.
Read the values as a set. Pulling only one directional byte or assuming that one interrupt equals one four-byte sample breaks the relationship used by the direction algorithm. Continue until the valid data is consumed; then re-read status instead of relying on the first level value.
Overflow invalidates the oldest context
The gesture FIFO can hold 32 datasets. If firmware services it too slowly, the overflow flag indicates that the sequence no longer contains a clean beginning-to-end record. Decoding a direction from that truncated history may produce an apparently valid but wrong swipe.
On overflow, discard the affected sequence, drain or reset the gesture path as specified by the driver, and wait for a new entry. Raising I²C clock speed may shorten service time, but it does not fix a handler blocked by long prints, display refreshes or other work performed inside the interrupt path.
Keep INT short and decode outside the handler
A robust microcontroller pattern is to let the hardware interrupt set a flag, then perform I²C transactions in the main loop or a task. That avoids library calls and bus waits inside an interrupt service routine. The task can timestamp the event, read status, drain complete datasets and pass the sequence to the direction decoder.
Gesture acquisition also has tunable entry and exit thresholds, persistence, pulse count, gain and LED drive. Adjust one layer at a time. If GVALID never asserts, inspect gesture enable state and optical thresholds. If it asserts but the FIFO stays empty or overflows, inspect service timing. If clean datasets arrive but direction is unstable, then tune geometry, ambient-light rejection and the decoder.
Gesture, proximity and color are separate interrupt sources
The APDS9960 also supports proximity and ambient-light/color threshold interrupts. A shared physical INT line therefore needs a status read that identifies the active engine; clearing the wrong source can leave the line asserted. Adafruit’s breakout adds a 3.3 V regulator and level shifting for 3.3 V or 5 V microcontrollers, but that board-level convenience does not change the internal event sequence.
The decisive check is data ownership: after each gesture event, every accepted four-direction dataset should be consumed exactly once, overflowed sequences should be rejected, and the task should confirm that the engine no longer reports valid unread gesture data.
