apds9960 --- 近接・ジェスチャー・カラーセンサードライバー

このモジュールは、Broadcom/Avago APDS9960 デジタル近接・周囲光・RGB カラー・ジェスチャーセンサーを I2C 経由で扱うドライバーを提供します。ドライバーは、機能ごとの有効化/無効化制御、生のチャンネル読み取り（クリア、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 ビット符号なし値として読み取ります。

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 は同一ですが、基盤となるレジスタアクセスには SMBus 形式のメソッドではなく machine.I2C 形式の readfrom_mem および writeto_mem 呼び出しを使用します。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

APDS9960.setMode() に対して ENABLE レジスタ内のすべてのビットを一度に有効または無効にするよう指示するセンチネル値（7）。

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）。