Simple test

Ensure your device works with this simple test.

examples/apds9999_simpletest.py

# SPDX-FileCopyrightText: Copyright (c) 2026 Tim Cocks for Adafruit Industries
#
# SPDX-License-Identifier: MIT
import time

import board

from adafruit_apds9999 import APDS9999

"""
Demonstrate the setup and basic RGB/IR and proximity
 sensing functionality of the APDS9999
"""

apds_sensor = APDS9999(board.I2C())

apds_sensor.light_sensor_enabled = True
apds_sensor.proximity_sensor_enabled = True
apds_sensor.rgb_mode = True

while True:
    time.sleep(1)
    r, g, b, ir = apds_sensor.rgb_ir

    print(
        f"r: {r}, g: {g}, b: {b}, ir: {ir} "
        f"lux: {apds_sensor.calculate_lux(g)} proximity: {apds_sensor.proximity}"
    )

Manual interrupt test

See how the proximity and light interrupt features work

examples/apds9999_manual_interrupt_test.py

# SPDX-FileCopyrightText: Copyright (c) 2026 Tim Cocks for Adafruit Industries
#
# SPDX-License-Identifier: MIT
"""
APDS9999 Threshold Interrupt Demo

Demonstrates proximity and light sensor threshold interrupts.

Hardware: Connect the sensor INT pin to board.D8.

- Wave a hand near the sensor to trigger a proximity interrupt.
- Cover/uncover or shine a light on the sensor to trigger a light interrupt.
"""

import time

import board
import busio
from digitalio import DigitalInOut, Direction, Pull

from adafruit_apds9999 import APDS9999, LightInterruptChannel

# The APDS-9999 INT pin is active-low (open-drain), so use a pull-up.
interrupt_pin = DigitalInOut(board.D8)
interrupt_pin.direction = Direction.INPUT
interrupt_pin.pull = Pull.UP

# --- Sensor setup ---
i2c = busio.I2C(board.SCL, board.SDA)
sensor = APDS9999(i2c)

# Enable both sensors and select RGB (vs ALS) mode
sensor.proximity_sensor_enabled = True
sensor.light_sensor_enabled = True
sensor.rgb_mode = True

# --- Proximity Threshold Setup ---
sensor.proximity_threshold_low = 50  # Interrupt when prox < 50  (object far)
sensor.proximity_threshold_high = 200  # Interrupt when prox > 200 (object close)
sensor.proximity_persistence = 2  # Require 3 consecutive out-of-range readings
sensor.proximity_interrupt_enabled = True

print("Proximity thresholds: low=50, high=200, persistence=3")

# --- Light Threshold Setup ---
sensor.light_threshold_low = 1000  # Interrupt when light < 1000
sensor.light_threshold_high = 50000  # Interrupt when light > 50000
sensor.light_interrupt_channel = LightInterruptChannel.GREEN  # Compare green channel
sensor.light_persistence = 2  # Require 3 consecutive out-of-range readings
sensor.light_interrupt_enabled = True

print("Light thresholds: low=1000, high=50000 (green channel)")
print()
print("Waiting for interrupts...")
print("- Wave hand near sensor for proximity interrupt")
print("- Cover/uncover sensor for light interrupt")
print()

last_print = time.monotonic()

while True:
    # The INT pin is active-low: it goes False when an interrupt has fired.
    if not interrupt_pin.value:
        # Read main_status once — this clears all interrupt flags on the device.
        # Returns: (prox_data_ready, prox_interrupt, prox_logic,
        #           light_data_ready, light_interrupt, power_on_reset)
        status = sensor.main_status

        if status[1]:  # proximity_interrupt
            prox = sensor.proximity
            print(f">>> PROXIMITY INTERRUPT! Value: {prox}")

        if status[4]:  # light_interrupt
            r, g, b, ir = sensor.rgb_ir
            print(f">>> LIGHT INTERRUPT! Green: {g}")

    # Periodic sensor readings every 500 ms
    now = time.monotonic()
    if now - last_print >= 0.5:
        last_print = now
        prox = sensor.proximity
        r, g, b, ir = sensor.rgb_ir
        print(f"Prox: {prox}\tGreen: {g}")

Automatic interrupt test

Automated test that uses NeoPixels to verify light threshold interrupt behavior

examples/apds9999_automatic_interrupt_threshold_test.py

# SPDX-FileCopyrightText: Copyright (c) 2026 Tim Cocks for Adafruit Industries
#
# SPDX-License-Identifier: MIT
"""
APDS-9999 Light Threshold Interrupt Automated Test
===================================================

Uses on-board NeoPixels to ramp brightness from off to full white, verifying
that the APDS-9999 light threshold interrupt pin behaves correctly across
three regions:

  1. BELOW low threshold  – INT pin should be asserted (active-low → False)
  2. BETWEEN thresholds   – INT pin should be de-asserted (True)
  3. ABOVE high threshold – INT pin should be asserted (active-low → False)

Hardware
--------
* APDS-9999 INT pin → board.D8  (active-low, open-drain; pull-up enabled)
* APDS-9999 wired to board I2C (SDA/SCL)
* On-board NeoPixels at board.NEOPIXEL (5 pixels assumed)

The sensor should be placed face-down on (or very close to) the NeoPixel
strip so the NeoPixel is the dominant light source.
"""

import time

import board
import busio
import neopixel
from digitalio import DigitalInOut, Direction, Pull

from adafruit_apds9999 import (
    APDS9999,
    LightGain,
    LightInterruptChannel,
    LightMeasurementRate,
    LightResolution,
)

# ---------------------------------------------------------------------------
# Configuration
# ---------------------------------------------------------------------------

# Number of NeoPixels on the board / strip.
NUM_PIXELS = 5

# Settle time (seconds) after changing NeoPixel brightness before reading.
SETTLE_TIME = 0.6

# Number of sensor samples to average per reading.
NUM_SAMPLES = 5

# Light interrupt thresholds (green channel counts).
# These are chosen to sit comfortably within the brightness ramp so that we
# can clearly demonstrate all three regions.
LIGHT_THRESHOLD_LOW = 30_000  # Below this → interrupt fires (too dark)
LIGHT_THRESHOLD_HIGH = 100_000  # Above this → interrupt fires (too bright)

# Persistence: require this many consecutive out-of-range readings before
# asserting the interrupt.  Keep at 1 so every out-of-range reading fires.
LIGHT_PERSISTENCE = 1

# Brightness steps used for the ramp.  Each entry is a 0.0–1.0 value.
# We want points clearly below, inside, and above the thresholds.
BRIGHTNESS_STEPS = [0.0, 0.05, 0.1, 0.2, 0.3, 0.5, 0.7, 0.85, 1.0]

# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------


def average_green(sensor, n=NUM_SAMPLES, delay=0.15):
    """Return the average green-channel reading over *n* samples."""
    total = 0
    for _ in range(n):
        _, g, _, _ = sensor.rgb_ir
        total += g
        time.sleep(delay)
    return total // n


def read_interrupt(pin):
    """Return True if the INT pin is currently asserted (active-low → pin False)."""
    return not pin.value


def print_result(label, passed, detail=""):
    status = "PASS" if passed else "FAIL"
    msg = f"  [{status}] {label}"
    if detail:
        msg += f" – {detail}"
    print(msg)
    return passed


def clear_interrupt(sensor):
    """Read main_status to clear any pending interrupt flags on the device."""
    _ = sensor.main_status


# ---------------------------------------------------------------------------
# Hardware setup
# ---------------------------------------------------------------------------

print("=" * 56)
print("APDS9999 Light Threshold Interrupt Test")
print("=" * 56)

# Interrupt pin: active-low, open-drain → use internal pull-up.
interrupt_pin = DigitalInOut(board.D8)
interrupt_pin.direction = Direction.INPUT
interrupt_pin.pull = Pull.UP

# NeoPixels – start off.
pixels = neopixel.NeoPixel(board.NEOPIXEL, NUM_PIXELS, brightness=0.0, auto_write=True)
pixels.fill((255, 255, 255))  # white; brightness controls intensity

# I2C + sensor.
i2c = board.I2C()
sensor = APDS9999(i2c)

# Light sensor only – no proximity.
sensor.proximity_sensor_enabled = False
sensor.light_sensor_enabled = True
sensor.rgb_mode = True

# Use 18-bit resolution
sensor.light_resolution = LightResolution.RES_18BIT
sensor.light_measurement_rate = LightMeasurementRate.RATE_200MS
sensor.light_gain = LightGain.GAIN_9X

# Configure light interrupt thresholds.
sensor.light_threshold_low = LIGHT_THRESHOLD_LOW
sensor.light_threshold_high = LIGHT_THRESHOLD_HIGH
sensor.light_interrupt_channel = LightInterruptChannel.GREEN
sensor.light_persistence = LIGHT_PERSISTENCE
sensor.light_interrupt_enabled = True

# Clear any stale interrupt state before starting.
clear_interrupt(sensor)
time.sleep(0.5)

print(f"\nLight interrupt channel : GREEN")
print(f"Low  threshold          : {LIGHT_THRESHOLD_LOW:,} counts")
print(f"High threshold          : {LIGHT_THRESHOLD_HIGH:,} counts")
print(f"Persistence             : {LIGHT_PERSISTENCE} reading(s)")
print()

# ---------------------------------------------------------------------------
# Brightness ramp + interrupt verification
# ---------------------------------------------------------------------------

all_passed = True

# Collect (brightness, green_counts, int_asserted) for every step.
ramp_data = []

print("Running brightness ramp...")
print(f"  {'Brightness':>10}  {'Green':>8}  {'INT Pin':>8}  {'Region':>18}  {'Check':>6}")
print("  " + "-" * 58)

for brightness in BRIGHTNESS_STEPS:
    pixels.brightness = brightness
    time.sleep(SETTLE_TIME)

    # Clear any previous interrupt so we get a fresh reading for this level.
    clear_interrupt(sensor)
    time.sleep(SETTLE_TIME)

    green = average_green(sensor)
    int_asserted = read_interrupt(interrupt_pin)

    if green < LIGHT_THRESHOLD_LOW:
        region = "BELOW LOW"
    elif green > LIGHT_THRESHOLD_HIGH:
        region = "ABOVE HIGH"
    else:
        region = "IN RANGE"

    ramp_data.append((brightness, green, int_asserted, region))

    print(f"  {brightness:>10.2f}  {green:>8,}  {str(int_asserted):>8}  {region:>18}")

# ---------------------------------------------------------------------------
# Automated checks
# ---------------------------------------------------------------------------

print()
print("Automated checks")
print("-" * 56)

# Check 1 – At least one step landed below, inside, and above the threshold range.
below_steps = [(b, g, ia) for b, g, ia, r in ramp_data if r == "BELOW LOW"]
in_range_steps = [(b, g, ia) for b, g, ia, r in ramp_data if r == "IN RANGE"]
above_steps = [(b, g, ia) for b, g, ia, r in ramp_data if r == "ABOVE HIGH"]

coverage_below = len(below_steps) > 0
coverage_in = len(in_range_steps) > 0
coverage_above = len(above_steps) > 0

all_passed = (
    print_result(
        "Ramp covers BELOW LOW region",
        coverage_below,
        f"{len(below_steps)} step(s) below {LIGHT_THRESHOLD_LOW:,}",
    )
    and all_passed
)

all_passed = (
    print_result(
        "Ramp covers IN RANGE region",
        coverage_in,
        f"{len(in_range_steps)} step(s) between thresholds",
    )
    and all_passed
)

all_passed = (
    print_result(
        "Ramp covers ABOVE HIGH region",
        coverage_above,
        f"{len(above_steps)} step(s) above {LIGHT_THRESHOLD_HIGH:,}",
    )
    and all_passed
)

# Check 2 – INT asserted for every BELOW LOW step.
if below_steps:
    below_int_ok = all(ia for _, _, ia in below_steps)
    all_passed = (
        print_result(
            "INT asserted for all BELOW LOW steps",
            below_int_ok,
            f"{sum(ia for _, _, ia in below_steps)}/{len(below_steps)} asserted",
        )
        and all_passed
    )
else:
    print("  [SKIP] INT check for BELOW LOW – no steps in that region")

# Check 3 – INT NOT asserted for every IN RANGE step.
if in_range_steps:
    in_range_int_ok = all(not ia for _, _, ia in in_range_steps)
    all_passed = (
        print_result(
            "INT de-asserted for all IN RANGE steps",
            in_range_int_ok,
            f"{sum(not ia for _, _, ia in in_range_steps)}/{len(in_range_steps)} de-asserted",
        )
        and all_passed
    )
else:
    print("  [SKIP] INT check for IN RANGE – no steps in that region")

# Check 4 – INT asserted for every ABOVE HIGH step.
if above_steps:
    above_int_ok = all(ia for _, _, ia in above_steps)
    all_passed = (
        print_result(
            "INT asserted for all ABOVE HIGH steps",
            above_int_ok,
            f"{sum(ia for _, _, ia in above_steps)}/{len(above_steps)} asserted",
        )
        and all_passed
    )
else:
    print("  [SKIP] INT check for ABOVE HIGH – no steps in that region")

# Check 5 – Green counts increase monotonically with brightness.
greens = [g for _, g, _, _ in ramp_data]
monotonic = all(greens[i] <= greens[i + 1] for i in range(len(greens) - 1))
all_passed = (
    print_result(
        "Green counts increase monotonically with brightness",
        monotonic,
        f"counts: {greens}",
    )
    and all_passed
)

# ---------------------------------------------------------------------------
# Teardown
# ---------------------------------------------------------------------------

pixels.fill((0, 0, 0))
pixels.brightness = 0.0
sensor.light_interrupt_enabled = False
clear_interrupt(sensor)

print()
print("=" * 56)
if all_passed:
    print("Overall result: ALL TESTS PASSED")
else:
    print("Overall result: ONE OR MORE TESTS FAILED")
print("=" * 56)

Automatic RGB test

Automated test that uses NeoPixels to verify RGB light sensing functionality

examples/apds9999_automatic_rgb_test.py

# SPDX-FileCopyrightText: Copyright (c) 2026 Tim Cocks for Adafruit Industries
#
# SPDX-License-Identifier: MIT
"""
APDS9999 NeoPixel Color & Light Sensing Verification Test
==========================================================

This script verifies that the APDS9999 driver's color and light sensing
capabilities are working correctly by using on-board NeoPixels as a
controlled light source and then checking that the sensor readings match
the expected dominant color channel.

Test sequence
-------------
1. **RED**   – NeoPixel set to pure red.   Red channel must dominate.
2. **GREEN** – NeoPixel set to pure green. Green channel must dominate.
3. **BLUE**  – NeoPixel set to pure blue.  Blue channel must dominate.
4. **WHITE** – NeoPixel set to white.      All channels (R, G, B) must be high.
5. **DARK**  – NeoPixel off.               All channels must drop significantly
               compared to the white reading.

Hardware
--------
* Any CircuitPython board with on-board NeoPixels and I2C port.
* APDS9999 sensor wired to the board's I2C bus (SDA/SCL).

The sensor should be placed **very close** (ideally face-down on top of) the
NeoPixel so that the emitted light is the dominant light source being sensed.
Ambient light should be minimised where possible.
"""

import time

import board
import neopixel

from adafruit_apds9999 import APDS9999, LightGain, LightMeasurementRate, LightResolution

# ---------------------------------------------------------------------------
# Configuration
# ---------------------------------------------------------------------------

# NeoPixel brightness (0.0–1.0).  Keep this moderate so the sensor is not
# saturated but still well above the noise floor.
NEOPIXEL_BRIGHTNESS = 0.3

# How long (seconds) to let the sensor settle after changing the NeoPixel
# colour before taking a reading.
SETTLE_TIME = 0.5

# How many readings to average for each colour test.
NUM_SAMPLES = 5

# Dominance factor: the winning channel must be at least this many times
# larger than each of the other colour channels to pass.
DOMINANCE_FACTOR = 1.5

# For the WHITE test, all three colour channels must be at least this fraction
# of the maximum channel value.
WHITE_BALANCE_FRACTION = 0.4

# For the DARK test, all channels must be at most this fraction of the
# corresponding WHITE reading.
DARK_FRACTION = 0.25

# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------


def average_readings(sensor, n=NUM_SAMPLES, delay=0.15):
    """Return averaged (r, g, b, ir) from *n* consecutive sensor reads."""
    totals = [0, 0, 0, 0]
    for _ in range(n):
        r, g, b, ir = sensor.rgb_ir
        totals[0] += r
        totals[1] += g
        totals[2] += b
        totals[3] += ir
        time.sleep(delay)
    return tuple(v // n for v in totals)


def print_result(name, passed, detail=""):
    status = "PASS" if passed else "FAIL"
    msg = f"  [{status}] {name}"
    if detail:
        msg += f" – {detail}"
    print(msg)
    return passed


# ---------------------------------------------------------------------------
# Setup
# ---------------------------------------------------------------------------

print("=" * 50)
print("APDS9999 NeoPixel Verification Test")
print("=" * 50)

# Initialise NeoPixel
pixels = neopixel.NeoPixel(board.NEOPIXEL, 5, brightness=NEOPIXEL_BRIGHTNESS, auto_write=True)
pixels.fill((0, 0, 0))  # Start with NeoPixel off

# Initialise the APDS9999 sensor.
i2c = board.I2C()
sensor = APDS9999(i2c)

# Enable the light sensor in RGB mode.
sensor.light_sensor_enabled = True
sensor.rgb_mode = True

# Use 18-bit resolution (100 ms conversion) with a 200 ms measurement rate.
sensor.light_resolution = LightResolution.RES_18BIT
sensor.light_measurement_rate = LightMeasurementRate.RATE_200MS

# 9x gain
sensor.light_gain = LightGain.GAIN_9X

# Allow the sensor to perform its first measurement after being enabled.
time.sleep(0.5)

print(f"\nSensor initialised – PART_ID check passed")
print(
    f"Settings: resolution=18-bit, rate=200ms, gain=9x, neopixel brightness={NEOPIXEL_BRIGHTNESS}\n"
)

# ---------------------------------------------------------------------------
# Test cases
# ---------------------------------------------------------------------------

all_passed = True
results = {}

# ---- 1. RED ----------------------------------------------------------------
print("Test 1: RED")
pixels.fill((255, 0, 0))
time.sleep(SETTLE_TIME)
r, g, b, ir = average_readings(sensor)
print(f"  Readings  r={r:>7}  g={g:>7}  b={b:>7}  ir={ir:>7}")

red_dominates = (r > g * DOMINANCE_FACTOR) and (r > b * DOMINANCE_FACTOR) and r > 0
passed = print_result(
    "Red channel dominates",
    red_dominates,
    f"r={r} vs g={g}, b={b} (factor {DOMINANCE_FACTOR}x)",
)
all_passed = all_passed and passed
results["red"] = (r, g, b, ir)

# ---- 2. GREEN --------------------------------------------------------------
print("\nTest 2: GREEN")
pixels.fill((0, 255, 0))
time.sleep(SETTLE_TIME)
r, g, b, ir = average_readings(sensor)
print(f"  Readings  r={r:>7}  g={g:>7}  b={b:>7}  ir={ir:>7}")

green_dominates = (g > r * DOMINANCE_FACTOR) and (g > b * DOMINANCE_FACTOR) and g > 0
passed = print_result(
    "Green channel dominates",
    green_dominates,
    f"g={g} vs r={r}, b={b} (factor {DOMINANCE_FACTOR}x)",
)
all_passed = all_passed and passed
results["green"] = (r, g, b, ir)

# ---- 3. BLUE ---------------------------------------------------------------
print("\nTest 3: BLUE")
pixels.fill((0, 0, 255))
time.sleep(SETTLE_TIME)
r, g, b, ir = average_readings(sensor)
print(f"  Readings  r={r:>7}  g={g:>7}  b={b:>7}  ir={ir:>7}")

blue_dominates = (b > r * DOMINANCE_FACTOR) and (b > g * DOMINANCE_FACTOR) and b > 0
passed = print_result(
    "Blue channel dominates",
    blue_dominates,
    f"b={b} vs r={r}, g={g} (factor {DOMINANCE_FACTOR}x)",
)
all_passed = all_passed and passed
results["blue"] = (r, g, b, ir)

# ---- 4. WHITE --------------------------------------------------------------
print("\nTest 4: WHITE")
pixels.fill((255, 255, 255))
time.sleep(SETTLE_TIME)
r, g, b, ir = average_readings(sensor)
print(f"  Readings  r={r:>7}  g={g:>7}  b={b:>7}  ir={ir:>7}")

white_max = max(r, g, b)
threshold = int(white_max * WHITE_BALANCE_FRACTION)
white_balanced = white_max > 0 and r >= threshold and g >= threshold and b >= threshold
passed = print_result(
    "All colour channels active (white balance)",
    white_balanced,
    f"r={r}, g={g}, b={b}, "
    f"min threshold={threshold} ({int(WHITE_BALANCE_FRACTION * 100)}% of max={white_max})",
)
all_passed = all_passed and passed
results["white"] = (r, g, b, ir)

# Also verify lux is a positive, plausible number.
lux = sensor.calculate_lux(g)
lux_ok = lux > 0
passed2 = print_result(
    "Lux value is positive",
    lux_ok,
    f"lux={lux:.2f}",
)
all_passed = all_passed and passed2

# ---- 5. DARK ---------------------------------------------------------------
print("\nTest 5: DARK (NeoPixel OFF)")
pixels.fill((0, 0, 0))
time.sleep(SETTLE_TIME)
r_dark, g_dark, b_dark, ir_dark = average_readings(sensor)
print(f"  Readings  r={r_dark:>7}  g={g_dark:>7}  b={b_dark:>7}  ir={ir_dark:>7}")

wr, wg, wb, _ = results["white"]
dark_r_ok = wr == 0 or r_dark <= wr * DARK_FRACTION
dark_g_ok = wg == 0 or g_dark <= wg * DARK_FRACTION
dark_b_ok = wb == 0 or b_dark <= wb * DARK_FRACTION
dark_ok = dark_r_ok and dark_g_ok and dark_b_ok
passed = print_result(
    "All channels drop in darkness",
    dark_ok,
    f"dark r={r_dark} (white={wr}), g={g_dark} (white={wg}), b={b_dark} (white={wb})",
)
all_passed = all_passed and passed
results["dark"] = (r_dark, g_dark, b_dark, ir_dark)

# ---- 6. main_status sanity check -------------------------------------------
print("\nTest 6: main_status data-ready flags")
pixels.fill((255, 255, 255))
time.sleep(0.4)  # Let sensor complete one measurement cycle
ps_ready, ps_int, ps_logic, ls_ready, ls_int, por = sensor.main_status
# After a measurement cycle, light_data_ready should have been True at some
# point.  We re-enable sensors and wait to catch it reliably.
sensor.light_sensor_enabled = False
time.sleep(0.05)
sensor.light_sensor_enabled = True
sensor.rgb_mode = True
time.sleep(0.4)
_, _, _, ls_ready2, _, _ = sensor.main_status
passed = print_result(
    "Light data-ready flag observed",
    ls_ready2,
    f"light_data_ready={ls_ready2}",
)
all_passed = all_passed and passed

# ---------------------------------------------------------------------------
# Summary
# ---------------------------------------------------------------------------
pixels.fill((0, 0, 0))  # Turn off NeoPixel at end of test.

print("\n" + "=" * 50)
if all_passed:
    print("Overall result: ALL TESTS PASSED")
else:
    print("Overall result: ONE OR MORE TESTS FAILED")
print("=" * 50)