apds9960 --- 接近、手势和颜色传感器驱动

本模块通过 I2C 为 Broadcom/Avago APDS9960 数字接近、环境光、RGB 颜色和手势传感器提供了驱动。该驱动暴露了逐功能的启用/禁用控制、原始通道读取（clear、R、G、B、接近），以及一个软件手势解码状态机，可从片上的 4 光电二极管 FIFO 中识别上/下/左/右滑动以及靠近/远离手势。

用法示例:

import time
from machine import I2C, Pin
from apds9960 import uAPDS9960 as APDS9960

bus = I2C(1, scl=Pin("P15"), sda=Pin("P14"))
sensor = APDS9960(bus)

sensor.enableLightSensor()
sensor.enableProximitySensor()

while True:
    r = sensor.readRedLight()
    g = sensor.readGreenLight()
    b = sensor.readBlueLight()
    c = sensor.readAmbientLight()
    p = sensor.readProximity()
    print(r, g, b, c, p)
    time.sleep_ms(100)

类

class apds9960.APDS9960(bus: machine.I2C, address: int = 0x39, valid_id: list = [0xAB, 0x9C, 0xA8, -0x55])

构造一个 APDS9960 驱动实例。

• bus 是一个用于与传感器通信的已配置 I2C 总线对象。基类发出 SMBus 风格的 read_byte_data、write_byte_data 和 read_i2c_block_data 调用；对于 MicroPython 的 machine.I2C，请改用 uAPDS9960。

• address 是设备的 7 位 I2C 地址。默认为 APDS9960_I2C_ADDR（0x39）。

• valid_id 是芯片 ID 寄存器所返回的可接受值列表。默认为 APDS9960_DEV_ID。

构造函数读取设备 ID，如果它不在 valid_id 中则引发 ADPS9960InvalidDevId。随后它会禁用每个功能，写入默认的 ATIME/WTIME/PPULSE 值，并应用默认的 LED 驱动、接近增益、ALS 增益、接近阈值、环境光阈值、持续性以及手势引擎配置（进入/退出阈值、GCONF1、手势增益、手势 LED 驱动、手势等待时间、手势偏移、GPULSE、GCONF3 以及手势中断使能）。

模式与电源控制

getMode() → int

返回 ENABLE 寄存器的原始值，其编码了当前启用的功能（电源、ALS、接近、等待、ALS 中断、接近中断、手势）。

setMode(mode: int, enable: bool = True) → None

在 ENABLE 寄存器中启用或禁用某个单独的功能。mode 必须是 APDS9960_MODE_* 值之一（APDS9960_MODE_POWER ..\ APDS9960_MODE_ALL）。当 mode 为 APDS9960_MODE_ALL 时，所有位会被一次性开启或关闭。对于超出范围的值会引发 ADPS9960InvalidMode。

enablePower() → None

为 APDS9960 上电（设置 ENABLE 中的 PON 位）。

disablePower() → None

为 APDS9960 断电（清除 ENABLE 中的 PON 位）。

环境光 / RGB 传感器

enableLightSensor(interrupts: bool = True) → None

恢复默认的 ALS 增益，配置 ALS 中断使能位，为设备上电，并启用环境光/颜色引擎。

disableLightSensor() → None

禁用 ALS 中断并停止环境光/颜色引擎。

readAmbientLight() → int

以 16 位无符号值读取 clear 通道的环境光强度。

readRedLight() → int

以 16 位无符号值读取红色通道的强度。

readGreenLight() → int

以 16 位无符号值读取绿色通道的强度。

readBlueLight() → int

以 16 位无符号值读取蓝色通道的强度。

接近传感器

enableProximitySensor(interrupts: bool = True) → None

恢复默认的接近增益和 LED 驱动，配置接近中断使能位，为设备上电，并启用接近引擎。

disableProximitySensor() → None

禁用接近中断并停止接近引擎。

readProximity() → int

以 8 位无符号值读取接近强度。

手势引擎

enableGestureSensor(interrupts: bool = True) → None

重置手势状态，设置 WTIME 和手势脉冲计数，将 LED 提升至 300%，配置手势中断使能位，进入手势状态机，为设备上电，并启用等待、接近和手势模式。

disableGestureSensor() → None

重置手势状态，禁用手势中断和状态机，并停止手势引擎。

isGestureAvailable() → bool

如果手势状态寄存器的 GVALID 位被置位，则返回 True，表示手势 FIFO 数据已就绪可供读取。

readGesture() → int

排空手势 FIFO，运行板载手势解码器，并返回 APDS9960_DIR_* 方向常量之一。如果引擎未运行、无可用的有效数据，或数据未解析为可识别的手势，则返回 APDS9960_DIR_NONE。

resetGestureParameters() → None

清除内部手势 FIFO 缓冲区、增量、计数、靠近/远离计数器、状态以及上次解码的运动。

processGestureData() → bool

处理当前缓冲的原始 U/D/L/R FIFO 样本，以更新 U/D 和 L/R 增量以及靠近/远离计数器。如果检测到靠近或远离事件则返回 True，否则返回 False。

decodeGesture() → bool

将当前的 U/D 和 L/R 计数以及累积的增量转换为一个方向，存储在内部的 gesture_motion_ 字段中。当识别出方向时返回 True，否则返回 False。

接近阈值

getProxIntLowThresh() → int

返回低接近中断阈值（PILT 寄存器）。

setProxIntLowThresh(threshold: int) → None

设置低接近中断阈值。

getProxIntHighThresh() → int

返回高接近中断阈值（PIHT 寄存器）。

setProxIntHighThresh(threshold: int) → None

设置高接近中断阈值。

getProximityIntLowThreshold() → int

getProxIntLowThresh() 的别名。

setProximityIntLowThreshold(threshold: int) → None

setProxIntLowThresh() 的别名。

getProximityIntHighThreshold() → int

getProxIntHighThresh() 的别名。

setProximityIntHighThreshold(threshold: int) → None

setProxIntHighThresh() 的别名。

LED 驱动、增益与提升

getLEDDrive() → int

返回用于接近和 ALS 的 LED 驱动强度。编码为 APDS9960_LED_DRIVE_* 值之一（0 = 100 mA，1 = 50 mA，2 = 25 mA，3 = 12.5 mA）。

setLEDDrive(drive: int) → None

设置用于接近和 ALS 的 LED 驱动强度。drive 是 APDS9960_LED_DRIVE_* 值之一。

getProximityGain() → int

返回接近接收器增益。编码为 APDS9960_PGAIN_* 值之一（0 = 1x，1 = 2x，2 = 4x，3 = 8x）。

setProximityGain(drive: int) → None

设置接近接收器增益。drive 是 APDS9960_PGAIN_* 值之一。

getAmbientLightGain() → int

返回环境光传感器增益。编码为 APDS9960_AGAIN_* 值之一（0 = 1x，1 = 4x，2 = 16x，3 = 64x）。

setAmbientLightGain(drive: int) → None

设置环境光传感器增益。drive 是 APDS9960_AGAIN_* 值之一。

getLEDBoost() → int

返回 LED 电流提升。编码为 APDS9960_LED_BOOST_* 值之一（0 = 100%，1 = 150%，2 = 200%，3 = 300%）。

setLEDBoost(boost: int) → None

设置 LED 电流提升。boost 是 APDS9960_LED_BOOST_* 值之一。

接近增益补偿与光电二极管掩码

getProxGainCompEnable() → bool

如果接近增益补偿已启用，则返回 True。

setProxGainCompEnable(enable: bool) → None

启用或禁用接近增益补偿。

getProxPhotoMask() → int

返回被禁用接近光电二极管的 4 位掩码。各位映射为 3=UP、2=DOWN、1=LEFT、0=RIGHT；1 禁用某个光电二极管，0 则启用它。

setProxPhotoMask(mask: int) → None

设置被禁用接近光电二极管的 4 位掩码（参见上面的编码）。

手势配置

getGestureEnterThresh() → int

返回进入手势模式所需的接近阈值。

setGestureEnterThresh(threshold: int) → None

设置进入手势模式所需的接近阈值。

getGestureExitThresh() → int

返回退出手势模式所需的接近阈值。

setGestureExitThresh(threshold: int) → None

设置退出手势模式所需的接近阈值。

getGestureGain() → int

返回手势模式期间使用的光电二极管增益。编码为 APDS9960_GGAIN_* 值之一（0 = 1x，1 = 2x，2 = 4x，3 = 8x）。

setGestureGain(gain: int) → None

设置手势模式期间使用的光电二极管增益。

getGestureLEDDrive() → int

返回手势模式期间使用的 LED 驱动电流。编码为 APDS9960_LED_DRIVE_* 值之一。

setGestureLEDDrive(drive: int) → None

设置手势模式期间使用的 LED 驱动电流。

getGestureWaitTime() → int

返回手势检测之间的低功耗等待时间。编码为 APDS9960_GWTIME_* 值之一（0 = 0 ms .. 7 = 39.2 ms）。

setGestureWaitTime(time: int) → None

设置手势检测之间的低功耗等待时间。

getGestureMode() → bool

如果手势状态机当前正在运行，则返回 True。

setGestureMode(enable: bool) → None

进入或离开手势状态机。

环境光中断阈值

getLightIntLowThreshold() → int

返回用于环境光中断的 16 位低阈值。

setLightIntLowThreshold(threshold: int) → None

设置用于环境光中断的 16 位低阈值。

getLightIntHighThreshold() → int

返回用于环境光中断的 16 位高阈值。

setLightIntHighThreshold(threshold: int) → None

设置用于环境光中断的 16 位高阈值。

中断使能与清除

getAmbientLightIntEnable() → bool

如果环境光中断已启用，则返回 True。

setAmbientLightIntEnable(enable: bool) → None

启用或禁用环境光中断。

getProximityIntEnable() → bool

如果接近中断已启用，则返回 True。

setProximityIntEnable(enable: bool) → None

启用或禁用接近中断。

getGestureIntEnable() → bool

如果手势中断已启用，则返回 True。

setGestureIntEnable(enable: bool) → None

启用或禁用手势中断。

clearAmbientLightInt() → None

清除一个待处理的环境光中断。

clearProximityInt() → None

清除一个待处理的接近中断。

class apds9960.uAPDS9960(bus: machine.I2C, address: int = 0x39, valid_id: list = [0xAB, 0x9C, 0xA8, -0x55])

APDS9960 的 MicroPython 子类。公共 API 完全相同，但底层寄存器访问使用 machine.I2C 风格的 readfrom_mem 和 writeto_mem 调用，而非 SMBus 风格的方法。这是在 OpenMV / MicroPython 目标上应使用的类。

异常

exception apds9960.ADPS9960InvalidDevId(id: int, valid_ids: list)

ValueError 的子类。当从芯片 ID 寄存器读取的值不在 valid_id 列表中时，由 APDS9960 构造函数引发。

exception apds9960.ADPS9960InvalidMode(mode: int)

ValueError 的子类。当 mode 参数超出 APDS9960_MODE_POWER..\ APDS9960_MODE_ALL 范围时，由 APDS9960.setMode() 引发。

常量

I2C 地址与设备 ID

apds9960.APDS9960_I2C_ADDR: int

APDS9960 的默认 7 位 I2C 地址（0x39）。

apds9960.APDS9960_DEV_ID: list

有效设备 ID 寄存器值的默认列表（[0xAB, 0x9C, 0xA8, -0x55]）。

手势调优

apds9960.APDS9960_GESTURE_THRESHOLD_OUT: int

手势解码器在搜索首个/末个在量程内的 FIFO 样本时使用的最小样本幅度（每个光电二极管）。

apds9960.APDS9960_GESTURE_SENSITIVITY_1: int

累积 U/D 和 L/R 增量的阈值，超过该值解码器即确定为某个滑动方向。

apds9960.APDS9960_GESTURE_SENSITIVITY_2: int

逐步 U/D 和 L/R 增量的阈值，低于该值解码器会将样本视为靠近/远离候选而非滑动。

apds9960.APDS9960_TIME_FIFO_PAUSE: int

手势循环在两次 FIFO 排空之间休眠的毫秒数。

功能模式

这些值会传递给 APDS9960.setMode()。

apds9960.APDS9960_MODE_POWER: int

上电位（0）。

apds9960.APDS9960_MODE_AMBIENT_LIGHT: int

环境光/颜色引擎使能位（1）。

apds9960.APDS9960_MODE_PROXIMITY: int

接近引擎使能位（2）。

apds9960.APDS9960_MODE_WAIT: int

等待状态使能位（3）。

apds9960.APDS9960_MODE_AMBIENT_LIGHT_INT: int

环境光中断使能位（4）。

apds9960.APDS9960_MODE_PROXIMITY_INT: int

接近中断使能位（5）。

apds9960.APDS9960_MODE_GESTURE: int

手势引擎使能位（6）。

apds9960.APDS9960_MODE_ALL: int

哨兵值（7），告知 APDS9960.setMode() 一次性启用或禁用 ENABLE 寄存器中的每一位。

LED 驱动电流

apds9960.APDS9960_LED_DRIVE_100MA: int

100 mA LED 驱动（0）。

apds9960.APDS9960_LED_DRIVE_50MA: int

50 mA LED 驱动（1）。

apds9960.APDS9960_LED_DRIVE_25MA: int

25 mA LED 驱动（2）。

apds9960.APDS9960_LED_DRIVE_12_5MA: int

12.5 mA LED 驱动（3）。

接近增益（PGAIN）

apds9960.APDS9960_PGAIN_1X: int

1x 接近增益（0）。

apds9960.APDS9960_PGAIN_2X: int

2x 接近增益（1）。

apds9960.APDS9960_PGAIN_4X: int

4x 接近增益（2）。由构造函数应用的默认值。

apds9960.APDS9960_PGAIN_8X: int

8x 接近增益（3）。

环境光增益（AGAIN）

apds9960.APDS9960_AGAIN_1X: int

1x ALS 增益（0）。

apds9960.APDS9960_AGAIN_4X: int

4x ALS 增益（1）。由构造函数应用的默认值。

apds9960.APDS9960_AGAIN_16X: int

16x ALS 增益（2）。

apds9960.APDS9960_AGAIN_64X: int

64x ALS 增益（3）。

手势增益（GGAIN）

apds9960.APDS9960_GGAIN_1X: int

1x 手势增益（0）。

apds9960.APDS9960_GGAIN_2X: int

2x 手势增益（1）。

apds9960.APDS9960_GGAIN_4X: int

4x 手势增益（2）。由构造函数应用的默认值。

apds9960.APDS9960_GGAIN_8X: int

8x 手势增益（3）。

LED 提升

apds9960.APDS9960_LED_BOOST_100: int

100% LED 提升（0）。

apds9960.APDS9960_LED_BOOST_150: int

150% LED 提升（1）。

apds9960.APDS9960_LED_BOOST_200: int

200% LED 提升（2）。

apds9960.APDS9960_LED_BOOST_300: int

300% LED 提升（3）。由 APDS9960.enableGestureSensor() 自动应用。

手势等待时间

apds9960.APDS9960_GWTIME_0MS: int

0 ms（0）。

apds9960.APDS9960_GWTIME_2_8MS: int

2.8 ms（1）。由构造函数应用的默认值。

apds9960.APDS9960_GWTIME_5_6MS: int

5.6 ms（2）。

apds9960.APDS9960_GWTIME_8_4MS: int

8.4 ms（3）。

apds9960.APDS9960_GWTIME_14_0MS: int

14.0 ms（4）。

apds9960.APDS9960_GWTIME_22_4MS: int

22.4 ms（5）。

apds9960.APDS9960_GWTIME_30_8MS: int

30.8 ms（6）。

apds9960.APDS9960_GWTIME_39_2MS: int

39.2 ms（7）。

手势方向

这些值由 APDS9960.readGesture() 返回。

apds9960.APDS9960_DIR_NONE: int

未检测到手势（0）。

apds9960.APDS9960_DIR_LEFT: int

向左滑动（1）。

apds9960.APDS9960_DIR_RIGHT: int

向右滑动（2）。

apds9960.APDS9960_DIR_UP: int

向上滑动（3）。

apds9960.APDS9960_DIR_DOWN: int

向下滑动（4）。

apds9960.APDS9960_DIR_NEAR: int

靠近事件（5）。

apds9960.APDS9960_DIR_FAR: int

远离事件（6）。

apds9960.APDS9960_DIR_ALL: int

哨兵值（7），内部用于表示“任意方向”。

手势状态

通过手势状态机报告的内部状态值。

apds9960.APDS9960_STATE_NA: int

无状态（0）。

apds9960.APDS9960_STATE_NEAR: int

检测到靠近状态（1）。

apds9960.APDS9960_STATE_FAR: int

检测到远离状态（2）。

apds9960.APDS9960_STATE_ALL: int

哨兵值（3），内部用于表示“任意状态”。