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），內部用於表示「任意狀態」。