`apds9960` — driver per sensore di prossimità, gesti e colore¶

Questo modulo fornisce un driver per il sensore digitale di prossimità, luce ambientale, colore RGB e gesti APDS9960 di Broadcom/Avago tramite I2C. Il driver espone controlli di abilitazione/disabilitazione per funzione, letture grezze dei canali (clear, R, G, B, prossimità) e una macchina a stati software per la decodifica dei gesti che classifica gli scorrimenti verso l’alto/basso/sinistra/destra e i gesti di avvicinamento/allontanamento a partire dalla FIFO a 4 fotodiodi integrata nel chip.

Esempio d’uso:

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)

Classi¶

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

Costruisce un’istanza del driver APDS9960.

bus è un oggetto bus I2C configurato usato per comunicare con il sensore. La classe base emette chiamate in stile SMBus read_byte_data, write_byte_data e read_i2c_block_data; per machine.I2C di MicroPython usa invece uAPDS9960.
address è l’indirizzo I2C a 7 bit del dispositivo. Il valore predefinito è APDS9960_I2C_ADDR (0x39).
valid_id è un elenco di valori accettabili restituiti dal registro ID del chip. Il valore predefinito è APDS9960_DEV_ID.

Il costruttore legge l’ID del dispositivo e solleva ADPS9960InvalidDevId se non è presente in valid_id. Quindi disabilita ogni funzione, programma i valori ATIME/WTIME/PPULSE predefiniti e applica la configurazione predefinita di LED drive, guadagno di prossimità, guadagno ALS, soglie di prossimità, soglie di luce ambientale, persistenza e del motore dei gesti (soglie di ingresso/uscita, GCONF1, guadagno dei gesti, LED drive dei gesti, tempo di attesa dei gesti, offset dei gesti, GPULSE, GCONF3 e abilitazione dell’interrupt dei gesti).

Controllo di modalità e alimentazione¶

getMode() → int¶: Restituisce il valore grezzo del registro ENABLE, che codifica quali funzioni sono attualmente abilitate (alimentazione, ALS, prossimità, attesa, interrupt ALS, interrupt di prossimità, gesti).

setMode(mode: int, enable: bool = True) → None¶: Abilita o disabilita una singola funzione nel registro ENABLE. mode deve essere uno dei valori APDS9960_MODE_* (APDS9960_MODE_POWER ..\ APDS9960_MODE_ALL). Quando mode è APDS9960_MODE_ALL, tutti i bit vengono attivati o disattivati contemporaneamente. Solleva ADPS9960InvalidMode per valori fuori intervallo.

enablePower() → None¶: Accende l’APDS9960 (imposta il bit PON in ENABLE).

disablePower() → None¶: Spegne l’APDS9960 (azzera il bit PON in ENABLE).

Sensore di luce ambientale / RGB¶

enableLightSensor(interrupts: bool = True) → None¶: Ripristina il guadagno ALS predefinito, configura il bit di abilitazione dell’interrupt ALS, accende il dispositivo e abilita il motore di luce ambientale/colore.

disableLightSensor() → None¶: Disabilita l’interrupt ALS e arresta il motore di luce ambientale/colore.

readAmbientLight() → int¶: Legge il livello di luce ambientale del canale clear come valore a 16 bit senza segno.

readRedLight() → int¶: Legge il livello del canale rosso come valore a 16 bit senza segno.

readGreenLight() → int¶: Legge il livello del canale verde come valore a 16 bit senza segno.

readBlueLight() → int¶: Legge il livello del canale blu come valore a 16 bit senza segno.

Sensore di prossimità¶

enableProximitySensor(interrupts: bool = True) → None¶: Ripristina il guadagno di prossimità e il LED drive predefiniti, configura il bit di abilitazione dell’interrupt di prossimità, accende il dispositivo e abilita il motore di prossimità.

disableProximitySensor() → None¶: Disabilita l’interrupt di prossimità e arresta il motore di prossimità.

readProximity() → int¶: Legge il livello di prossimità come valore a 8 bit senza segno.

Motore dei gesti¶

enableGestureSensor(interrupts: bool = True) → None¶: Reimposta lo stato dei gesti, imposta WTIME e il conteggio degli impulsi dei gesti, aumenta il LED al 300%, configura il bit di abilitazione dell’interrupt dei gesti, entra nella macchina a stati dei gesti, accende il dispositivo e abilita le modalità di attesa, prossimità e gesti.

disableGestureSensor() → None¶: Reimposta lo stato dei gesti, disabilita l’interrupt e la macchina a stati dei gesti e arresta il motore dei gesti.

isGestureAvailable() → bool¶: Restituisce True se il bit GVALID del registro di stato dei gesti è impostato, indicando che i dati della FIFO dei gesti sono pronti per essere letti.

readGesture() → int¶: Svuota la FIFO dei gesti, esegue il decodificatore di gesti integrato e restituisce una delle costanti di direzione APDS9960_DIR_*. Restituisce APDS9960_DIR_NONE se il motore non è in esecuzione, se non sono disponibili dati validi o se i dati non si sono risolti in un gesto riconosciuto.

resetGestureParameters() → None¶: Azzera il buffer FIFO interno dei gesti, i delta, i conteggi, i contatori di avvicinamento/allontanamento, lo stato e l’ultimo movimento decodificato.

processGestureData() → bool¶: Elabora i campioni grezzi U/D/L/R della FIFO attualmente bufferizzati per aggiornare i delta U/D e L/R e i contatori di avvicinamento/allontanamento. Restituisce True se è stato rilevato un evento di avvicinamento o allontanamento, False altrimenti.

decodeGesture() → bool¶: Converte gli attuali conteggi U/D e L/R e i delta accumulati in una direzione memorizzata nel campo interno gesture_motion_. Restituisce True quando una direzione viene riconosciuta, False altrimenti.

Soglie di prossimità¶

getProxIntLowThresh() → int¶: Restituisce la soglia bassa dell’interrupt di prossimità (registro PILT).

setProxIntLowThresh(threshold: int) → None¶: Imposta la soglia bassa dell’interrupt di prossimità.

getProxIntHighThresh() → int¶: Restituisce la soglia alta dell’interrupt di prossimità (registro PIHT).

setProxIntHighThresh(threshold: int) → None¶: Imposta la soglia alta dell’interrupt di prossimità.

getProximityIntLowThreshold() → int¶: Alias di getProxIntLowThresh().

setProximityIntLowThreshold(threshold: int) → None¶: Alias di setProxIntLowThresh().

getProximityIntHighThreshold() → int¶: Alias di getProxIntHighThresh().

setProximityIntHighThreshold(threshold: int) → None¶: Alias di setProxIntHighThresh().

LED drive, guadagno e boost¶

getLEDDrive() → int¶: Restituisce l’intensità del LED drive usata per prossimità e ALS. Codificata come uno dei valori APDS9960_LED_DRIVE_* (0 = 100 mA, 1 = 50 mA, 2 = 25 mA, 3 = 12.5 mA).

setLEDDrive(drive: int) → None¶: Imposta l’intensità del LED drive usata per prossimità e ALS. drive è uno dei valori APDS9960_LED_DRIVE_*.

getProximityGain() → int¶: Restituisce il guadagno del ricevitore di prossimità. Codificato come uno dei valori APDS9960_PGAIN_* (0 = 1x, 1 = 2x, 2 = 4x, 3 = 8x).

setProximityGain(drive: int) → None¶: Imposta il guadagno del ricevitore di prossimità. drive è uno dei valori APDS9960_PGAIN_*.

getAmbientLightGain() → int¶: Restituisce il guadagno del sensore di luce ambientale. Codificato come uno dei valori APDS9960_AGAIN_* (0 = 1x, 1 = 4x, 2 = 16x, 3 = 64x).

setAmbientLightGain(drive: int) → None¶: Imposta il guadagno del sensore di luce ambientale. drive è uno dei valori APDS9960_AGAIN_*.

getLEDBoost() → int¶: Restituisce il boost di corrente del LED. Codificato come uno dei valori APDS9960_LED_BOOST_* (0 = 100%, 1 = 150%, 2 = 200%, 3 = 300%).

setLEDBoost(boost: int) → None¶: Imposta il boost di corrente del LED. boost è uno dei valori APDS9960_LED_BOOST_*.

Compensazione del guadagno di prossimità e maschera dei fotodiodi¶

getProxGainCompEnable() → bool¶: Restituisce True se la compensazione del guadagno di prossimità è abilitata.

setProxGainCompEnable(enable: bool) → None¶: Abilita o disabilita la compensazione del guadagno di prossimità.

getProxPhotoMask() → int¶: Restituisce la maschera a 4 bit dei fotodiodi di prossimità disabilitati. I bit sono mappati come 3=UP, 2=DOWN, 1=LEFT, 0=RIGHT; 1 disabilita un fotodiodo e 0 lo abilita.

setProxPhotoMask(mask: int) → None¶: Imposta la maschera a 4 bit dei fotodiodi di prossimità disabilitati (vedi la codifica sopra).

Configurazione dei gesti¶

getGestureEnterThresh() → int¶: Restituisce la soglia di prossimità richiesta per entrare in modalità gesti.

setGestureEnterThresh(threshold: int) → None¶: Imposta la soglia di prossimità richiesta per entrare in modalità gesti.

getGestureExitThresh() → int¶: Restituisce la soglia di prossimità richiesta per uscire dalla modalità gesti.

setGestureExitThresh(threshold: int) → None¶: Imposta la soglia di prossimità richiesta per uscire dalla modalità gesti.

getGestureGain() → int¶: Restituisce il guadagno dei fotodiodi usato durante la modalità gesti. Codificato come uno dei valori APDS9960_GGAIN_* (0 = 1x, 1 = 2x, 2 = 4x, 3 = 8x).

setGestureGain(gain: int) → None¶: Imposta il guadagno dei fotodiodi usato durante la modalità gesti.

getGestureLEDDrive() → int¶: Restituisce la corrente del LED drive usata durante la modalità gesti. Codificata come uno dei valori APDS9960_LED_DRIVE_*.

setGestureLEDDrive(drive: int) → None¶: Imposta la corrente del LED drive usata durante la modalità gesti.

getGestureWaitTime() → int¶: Restituisce il tempo di attesa a basso consumo tra i rilevamenti dei gesti. Codificato come uno dei valori APDS9960_GWTIME_* (0 = 0 ms .. 7 = 39.2 ms).

setGestureWaitTime(time: int) → None¶: Imposta il tempo di attesa a basso consumo tra i rilevamenti dei gesti.

getGestureMode() → bool¶: Restituisce True se la macchina a stati dei gesti è attualmente in esecuzione.

setGestureMode(enable: bool) → None¶: Entra o esce dalla macchina a stati dei gesti.

Soglie dell’interrupt di luce ambientale¶

getLightIntLowThreshold() → int¶: Restituisce la soglia bassa a 16 bit usata per l’interrupt di luce ambientale.

setLightIntLowThreshold(threshold: int) → None¶: Imposta la soglia bassa a 16 bit usata per l’interrupt di luce ambientale.

getLightIntHighThreshold() → int¶: Restituisce la soglia alta a 16 bit usata per l’interrupt di luce ambientale.

setLightIntHighThreshold(threshold: int) → None¶: Imposta la soglia alta a 16 bit usata per l’interrupt di luce ambientale.

Abilitazioni e azzeramenti degli interrupt¶

getAmbientLightIntEnable() → bool¶: Restituisce True se gli interrupt di luce ambientale sono abilitati.

setAmbientLightIntEnable(enable: bool) → None¶: Abilita o disabilita gli interrupt di luce ambientale.

getProximityIntEnable() → bool¶: Restituisce True se gli interrupt di prossimità sono abilitati.

setProximityIntEnable(enable: bool) → None¶: Abilita o disabilita gli interrupt di prossimità.

getGestureIntEnable() → bool¶: Restituisce True se gli interrupt dei gesti sono abilitati.

setGestureIntEnable(enable: bool) → None¶: Abilita o disabilita gli interrupt dei gesti.

clearAmbientLightInt() → None¶: Azzera un interrupt di luce ambientale in sospeso.

clearProximityInt() → None¶: Azzera un interrupt di prossimità in sospeso.

class apds9960.uAPDS9960(bus: machine.I2C, address: int = 0x39, valid_id: list = [0xAB, 0x9C, 0xA8, -0x55])¶: Sottoclasse MicroPython di APDS9960. API pubblica identica, ma l’accesso ai registri sottostante usa chiamate in stile machine.I2C readfrom_mem e writeto_mem anziché metodi in stile SMBus. Questa è la classe da usare su target OpenMV / MicroPython.

Eccezioni¶

exception apds9960.ADPS9960InvalidDevId(id: int, valid_ids: list)¶: Sottoclasse di ValueError. Sollevata dal costruttore di APDS9960 quando il valore letto dal registro ID del chip non è presente nell’elenco valid_id.

exception apds9960.ADPS9960InvalidMode(mode: int)¶: Sottoclasse di ValueError. Sollevata da APDS9960.setMode() quando l’argomento mode è al di fuori dell’intervallo APDS9960_MODE_POWER..\ APDS9960_MODE_ALL.

Costanti¶

Indirizzo I2C e ID dei dispositivi¶

apds9960.APDS9960_I2C_ADDR: int¶: Indirizzo I2C a 7 bit predefinito dell’APDS9960 (0x39).

apds9960.APDS9960_DEV_ID: list¶: Elenco predefinito dei valori validi del registro ID del dispositivo ([0xAB, 0x9C, 0xA8, -0x55]).

Regolazione dei gesti¶

apds9960.APDS9960_GESTURE_THRESHOLD_OUT: int¶: Magnitudine minima del campione (per fotodiodo) usata dal decodificatore di gesti durante la ricerca dei primi/ultimi campioni FIFO entro il range.

apds9960.APDS9960_GESTURE_SENSITIVITY_1: int¶: Soglia sui delta U/D e L/R accumulati oltre la quale il decodificatore conferma una direzione di scorrimento.

apds9960.APDS9960_GESTURE_SENSITIVITY_2: int¶: Soglia sui delta U/D e L/R per passo al di sotto della quale il decodificatore considera un campione un candidato di avvicinamento/allontanamento anziché uno scorrimento.

apds9960.APDS9960_TIME_FIFO_PAUSE: int¶: Millisecondi per cui il ciclo dei gesti rimane in pausa tra gli svuotamenti della FIFO.

Modalità delle funzioni¶

Questi valori vengono passati a APDS9960.setMode().

apds9960.APDS9960_MODE_POWER: int¶: Bit di accensione (0).

apds9960.APDS9960_MODE_AMBIENT_LIGHT: int¶: Bit di abilitazione del motore di luce ambientale/colore (1).

apds9960.APDS9960_MODE_PROXIMITY: int¶: Bit di abilitazione del motore di prossimità (2).

apds9960.APDS9960_MODE_WAIT: int¶: Bit di abilitazione dello stato di attesa (3).

apds9960.APDS9960_MODE_AMBIENT_LIGHT_INT: int¶: Bit di abilitazione dell’interrupt di luce ambientale (4).

apds9960.APDS9960_MODE_PROXIMITY_INT: int¶: Bit di abilitazione dell’interrupt di prossimità (5).

apds9960.APDS9960_MODE_GESTURE: int¶: Bit di abilitazione del motore dei gesti (6).

apds9960.APDS9960_MODE_ALL: int¶: Valore sentinella (7) che indica a APDS9960.setMode() di abilitare o disabilitare contemporaneamente ogni bit del registro ENABLE.

Correnti del LED drive¶

apds9960.APDS9960_LED_DRIVE_100MA: int¶: LED drive a 100 mA (0).

apds9960.APDS9960_LED_DRIVE_50MA: int¶: LED drive a 50 mA (1).

apds9960.APDS9960_LED_DRIVE_25MA: int¶: LED drive a 25 mA (2).

apds9960.APDS9960_LED_DRIVE_12_5MA: int¶: LED drive a 12.5 mA (3).

Guadagno di prossimità (PGAIN)¶

apds9960.APDS9960_PGAIN_1X: int¶: Guadagno di prossimità 1x (0).

apds9960.APDS9960_PGAIN_2X: int¶: Guadagno di prossimità 2x (1).

apds9960.APDS9960_PGAIN_4X: int¶: Guadagno di prossimità 4x (2). Predefinito applicato dal costruttore.

apds9960.APDS9960_PGAIN_8X: int¶: Guadagno di prossimità 8x (3).

Guadagno di luce ambientale (AGAIN)¶

apds9960.APDS9960_AGAIN_1X: int¶: Guadagno ALS 1x (0).

apds9960.APDS9960_AGAIN_4X: int¶: Guadagno ALS 4x (1). Predefinito applicato dal costruttore.

apds9960.APDS9960_AGAIN_16X: int¶: Guadagno ALS 16x (2).

apds9960.APDS9960_AGAIN_64X: int¶: Guadagno ALS 64x (3).

Guadagno dei gesti (GGAIN)¶

apds9960.APDS9960_GGAIN_1X: int¶: Guadagno dei gesti 1x (0).

apds9960.APDS9960_GGAIN_2X: int¶: Guadagno dei gesti 2x (1).

apds9960.APDS9960_GGAIN_4X: int¶: Guadagno dei gesti 4x (2). Predefinito applicato dal costruttore.

apds9960.APDS9960_GGAIN_8X: int¶: Guadagno dei gesti 8x (3).

Boost del LED¶

apds9960.APDS9960_LED_BOOST_100: int¶: Boost del LED 100% (0).

apds9960.APDS9960_LED_BOOST_150: int¶: Boost del LED 150% (1).

apds9960.APDS9960_LED_BOOST_200: int¶: Boost del LED 200% (2).

apds9960.APDS9960_LED_BOOST_300: int¶: Boost del LED 300% (3). Applicato automaticamente da APDS9960.enableGestureSensor().

Tempi di attesa dei gesti¶

apds9960.APDS9960_GWTIME_0MS: int¶: 0 ms (0).

apds9960.APDS9960_GWTIME_2_8MS: int¶: 2.8 ms (1). Predefinito applicato dal costruttore.

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).

Direzioni dei gesti¶

Questi valori vengono restituiti da APDS9960.readGesture().

apds9960.APDS9960_DIR_NONE: int¶: Nessun gesto rilevato (0).

apds9960.APDS9960_DIR_LEFT: int¶: Scorrimento a sinistra (1).

apds9960.APDS9960_DIR_RIGHT: int¶: Scorrimento a destra (2).

apds9960.APDS9960_DIR_UP: int¶: Scorrimento verso l’alto (3).

apds9960.APDS9960_DIR_DOWN: int¶: Scorrimento verso il basso (4).

apds9960.APDS9960_DIR_NEAR: int¶: Evento di avvicinamento (5).

apds9960.APDS9960_DIR_FAR: int¶: Evento di allontanamento (6).

apds9960.APDS9960_DIR_ALL: int¶: Valore sentinella (7) usato internamente per rappresentare «qualsiasi direzione».

Stati dei gesti¶

Valori di stato interni riportati tramite la macchina a stati dei gesti.

apds9960.APDS9960_STATE_NA: int¶: Nessuno stato (0).

apds9960.APDS9960_STATE_NEAR: int¶: Stato di avvicinamento rilevato (1).

apds9960.APDS9960_STATE_FAR: int¶: Stato di allontanamento rilevato (2).

apds9960.APDS9960_STATE_ALL: int¶: Valore sentinella (3) usato internamente per rappresentare «qualsiasi stato».

apds9960 — driver per sensore di prossimità, gesti e colore¶