`apds9960` — Driver para Sensor de Proximidade, Gestos e Cor¶

Este módulo fornece um driver para o sensor digital de proximidade, luz ambiente, cor RGB e gestos Broadcom/Avago APDS9960 via I2C. O driver expõe controlos de ativação/desativação por funcionalidade, leituras de canais em bruto (clear, R, G, B, proximidade) e uma máquina de estados de deteção de gestos por software que classifica gestos de deslize cima/baixo/esquerda/direita e perto/longe a partir do FIFO de 4 fotodíodos do chip.

Exemplo de utilização:

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)

Classes¶

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

Constrói uma instância do driver APDS9960.

bus é um objeto de barramento I2C configurado usado para comunicar com o sensor. A classe base emite chamadas SMBus-style read_byte_data, write_byte_data e read_i2c_block_data; para o machine.I2C do MicroPython use uAPDS9960 em alternativa.
address é o endereço I2C de 7 bits do dispositivo. Por omissão é APDS9960_I2C_ADDR (0x39).
valid_id é uma lista de valores aceitáveis devolvidos pelo registo de ID do chip. Por omissão é APDS9960_DEV_ID.

O construtor lê o ID do dispositivo e gera ADPS9960InvalidDevId se este não estiver em valid_id. Em seguida, desativa todas as funcionalidades, programa os valores predefinidos de ATIME/WTIME/PPULSE e aplica as configurações predefinidas de corrente LED, ganho de proximidade, ganho ALS, limiares de proximidade, limiares de luz ambiente, persistência e configuração do motor de gestos (limiares de entrada/saída, GCONF1, ganho de gesto, corrente LED de gesto, tempo de espera de gesto, desvios de gesto, GPULSE, GCONF3 e ativação de interrupção de gesto).

Controlo de modo e de energia¶

getMode() → int¶: Devolve o valor em bruto do registo ENABLE, codificando as funcionalidades atualmente ativas (energia, ALS, proximidade, espera, interrupção ALS, interrupção de proximidade, gestos).

setMode(mode: int, enable: bool = True) → None¶: Ativa ou desativa uma funcionalidade individual no registo ENABLE. mode deve ser um dos valores APDS9960_MODE_* (APDS9960_MODE_POWER ..\ APDS9960_MODE_ALL). Quando mode é APDS9960_MODE_ALL, todos os bits são ativados ou desativados de uma vez. Gera ADPS9960InvalidMode para valores fora do intervalo.

enablePower() → None¶: Liga o APDS9960 (define o bit PON em ENABLE).

disablePower() → None¶: Desliga o APDS9960 (limpa o bit PON em ENABLE).

Sensor de luz ambiente / RGB¶

enableLightSensor(interrupts: bool = True) → None¶: Restaura o ganho ALS predefinido, configura o bit de ativação de interrupção ALS, liga o dispositivo e ativa o motor de luz ambiente/cor.

disableLightSensor() → None¶: Desativa a interrupção ALS e para o motor de luz ambiente/cor.

readAmbientLight() → int¶: Lê o nível de luz ambiente do canal clear como um valor não sinalizado de 16 bits.

readRedLight() → int¶: Lê o nível do canal vermelho como um valor não sinalizado de 16 bits.

readGreenLight() → int¶: Lê o nível do canal verde como um valor não sinalizado de 16 bits.

readBlueLight() → int¶: Lê o nível do canal azul como um valor não sinalizado de 16 bits.

Sensor de proximidade¶

enableProximitySensor(interrupts: bool = True) → None¶: Restaura o ganho de proximidade e a corrente LED predefinidos, configura o bit de ativação de interrupção de proximidade, liga o dispositivo e ativa o motor de proximidade.

disableProximitySensor() → None¶: Desativa a interrupção de proximidade e para o motor de proximidade.

readProximity() → int¶: Lê o nível de proximidade como um valor não sinalizado de 8 bits.

Motor de gestos¶

enableGestureSensor(interrupts: bool = True) → None¶: Reinicia o estado de gestos, define WTIME e a contagem de pulsos de gesto, aumenta o LED para 300%, configura o bit de ativação de interrupção de gestos, entra na máquina de estados de gestos, liga o dispositivo e ativa os modos de espera, proximidade e gestos.

disableGestureSensor() → None¶: Reinicia o estado de gestos, desativa a interrupção de gestos e a máquina de estados, e para o motor de gestos.

isGestureAvailable() → bool¶: Devolve True se o bit GVALID do registo de estado de gestos estiver definido, indicando que os dados FIFO de gestos estão prontos para ser lidos.

readGesture() → int¶: Esvazia o FIFO de gestos, executa o descodificador de gestos integrado e devolve uma das constantes de direção APDS9960_DIR_*. Devolve APDS9960_DIR_NONE se o motor não estiver em execução, não houver dados válidos disponíveis ou os dados não resolverem para um gesto reconhecido.

resetGestureParameters() → None¶: Limpa o buffer interno FIFO de gestos, deltas, contadores, contadores perto/longe, estado e último movimento descodificado.

processGestureData() → bool¶: Processa as amostras FIFO U/D/L/R atualmente em buffer para atualizar os deltas U/D e L/R e os contadores perto/longe. Devolve True se um evento próximo ou distante foi detetado, False caso contrário.

decodeGesture() → bool¶: Converte as contagens U/D e L/R atuais e os deltas acumulados numa direção armazenada no campo interno gesture_motion_. Devolve True quando uma direção é reconhecida, False caso contrário.

Limiares de proximidade¶

getProxIntLowThresh() → int¶: Devolve o limiar baixo de interrupção de proximidade (registo PILT).

setProxIntLowThresh(threshold: int) → None¶: Define o limiar baixo de interrupção de proximidade.

getProxIntHighThresh() → int¶: Devolve o limiar alto de interrupção de proximidade (registo PIHT).

setProxIntHighThresh(threshold: int) → None¶: Define o limiar alto de interrupção de proximidade.

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

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

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

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

Corrente LED, ganho e amplificação¶

getLEDDrive() → int¶: Devolve a intensidade de corrente LED usada para proximidade e ALS. Codificada como um dos valores APDS9960_LED_DRIVE_* (0 = 100 mA, 1 = 50 mA, 2 = 25 mA, 3 = 12,5 mA).

setLEDDrive(drive: int) → None¶: Define a intensidade de corrente LED usada para proximidade e ALS. drive é um dos valores APDS9960_LED_DRIVE_*.

getProximityGain() → int¶: Devolve o ganho do recetor de proximidade. Codificado como um dos valores APDS9960_PGAIN_* (0 = 1x, 1 = 2x, 2 = 4x, 3 = 8x).

setProximityGain(drive: int) → None¶: Define o ganho do recetor de proximidade. drive é um dos valores APDS9960_PGAIN_*.

getAmbientLightGain() → int¶: Devolve o ganho do sensor de luz ambiente. Codificado como um dos valores APDS9960_AGAIN_* (0 = 1x, 1 = 4x, 2 = 16x, 3 = 64x).

setAmbientLightGain(drive: int) → None¶: Define o ganho do sensor de luz ambiente. drive é um dos valores APDS9960_AGAIN_*.

getLEDBoost() → int¶: Devolve a amplificação da corrente LED. Codificada como um dos valores APDS9960_LED_BOOST_* (0 = 100%, 1 = 150%, 2 = 200%, 3 = 300%).

setLEDBoost(boost: int) → None¶: Define a amplificação da corrente LED. boost é um dos valores APDS9960_LED_BOOST_*.

Compensação de ganho de proximidade e máscara de fotodíodos¶

getProxGainCompEnable() → bool¶: Devolve True se a compensação de ganho de proximidade estiver ativada.

setProxGainCompEnable(enable: bool) → None¶: Ativa ou desativa a compensação de ganho de proximidade.

getProxPhotoMask() → int¶: Devolve a máscara de 4 bits dos fotodíodos de proximidade desativados. Os bits mapeiam como 3=UP, 2=DOWN, 1=LEFT, 0=RIGHT; 1 desativa um fotodíodo e 0 ativa-o.

setProxPhotoMask(mask: int) → None¶: Define a máscara de 4 bits dos fotodíodos de proximidade desativados (veja a codificação acima).

Configuração de gestos¶

getGestureEnterThresh() → int¶: Devolve o limiar de proximidade necessário para entrar no modo de gestos.

setGestureEnterThresh(threshold: int) → None¶: Define o limiar de proximidade necessário para entrar no modo de gestos.

getGestureExitThresh() → int¶: Devolve o limiar de proximidade necessário para sair do modo de gestos.

setGestureExitThresh(threshold: int) → None¶: Define o limiar de proximidade necessário para sair do modo de gestos.

getGestureGain() → int¶: Devolve o ganho de fotodíodo usado durante o modo de gestos. Codificado como um dos valores APDS9960_GGAIN_* (0 = 1x, 1 = 2x, 2 = 4x, 3 = 8x).

setGestureGain(gain: int) → None¶: Define o ganho de fotodíodo usado durante o modo de gestos.

getGestureLEDDrive() → int¶: Devolve a corrente LED usada durante o modo de gestos. Codificada como um dos valores APDS9960_LED_DRIVE_*.

setGestureLEDDrive(drive: int) → None¶: Define a corrente LED usada durante o modo de gestos.

getGestureWaitTime() → int¶: Devolve o tempo de espera de baixo consumo entre deteções de gestos. Codificado como um dos valores APDS9960_GWTIME_* (0 = 0 ms .. 7 = 39,2 ms).

setGestureWaitTime(time: int) → None¶: Define o tempo de espera de baixo consumo entre deteções de gestos.

getGestureMode() → bool¶: Devolve True se a máquina de estados de gestos estiver atualmente em execução.

setGestureMode(enable: bool) → None¶: Entra ou sai da máquina de estados de gestos.

Limiares de interrupção de luz ambiente¶

getLightIntLowThreshold() → int¶: Devolve o limiar baixo de 16 bits usado para a interrupção de luz ambiente.

setLightIntLowThreshold(threshold: int) → None¶: Define o limiar baixo de 16 bits usado para a interrupção de luz ambiente.

getLightIntHighThreshold() → int¶: Devolve o limiar alto de 16 bits usado para a interrupção de luz ambiente.

setLightIntHighThreshold(threshold: int) → None¶: Define o limiar alto de 16 bits usado para a interrupção de luz ambiente.

Ativação e limpeza de interrupções¶

getAmbientLightIntEnable() → bool¶: Devolve True se as interrupções de luz ambiente estiverem ativadas.

setAmbientLightIntEnable(enable: bool) → None¶: Ativa ou desativa as interrupções de luz ambiente.

getProximityIntEnable() → bool¶: Devolve True se as interrupções de proximidade estiverem ativadas.

setProximityIntEnable(enable: bool) → None¶: Ativa ou desativa as interrupções de proximidade.

getGestureIntEnable() → bool¶: Devolve True se as interrupções de gestos estiverem ativadas.

setGestureIntEnable(enable: bool) → None¶: Ativa ou desativa as interrupções de gestos.

clearAmbientLightInt() → None¶: Limpa uma interrupção de luz ambiente pendente.

clearProximityInt() → None¶: Limpa uma interrupção de proximidade pendente.

class apds9960.uAPDS9960(bus: machine.I2C, address: int = 0x39, valid_id: list = [0xAB, 0x9C, 0xA8, -0x55])¶: Subclasse MicroPython de APDS9960. API pública idêntica, mas o acesso a registos subjacente usa chamadas machine.I2C-style readfrom_mem e writeto_mem em vez de métodos SMBus-style. Esta é a classe a usar em alvos OpenMV / MicroPython.

Exceções¶

exception apds9960.ADPS9960InvalidDevId(id: int, valid_ids: list)¶: Subclasse de ValueError. Gerada pelo construtor de APDS9960 quando o valor lido do registo de ID do chip não está presente na lista valid_id.

exception apds9960.ADPS9960InvalidMode(mode: int)¶: Subclasse de ValueError. Gerada por APDS9960.setMode() quando o argumento mode está fora do intervalo APDS9960_MODE_POWER..\ APDS9960_MODE_ALL.

Constantes¶

Endereço I2C e IDs de dispositivo¶

apds9960.APDS9960_I2C_ADDR: int¶: Endereço I2C padrão de 7 bits do APDS9960 (0x39).

apds9960.APDS9960_DEV_ID: list¶: Lista predefinida de valores válidos do registo de ID do dispositivo ([0xAB, 0x9C, 0xA8, -0x55]).

Ajuste de gestos¶

apds9960.APDS9960_GESTURE_THRESHOLD_OUT: int¶: Magnitude mínima de amostra (por fotodíodo) usada pelo descodificador de gestos ao procurar as primeiras/últimas amostras FIFO dentro do intervalo.

apds9960.APDS9960_GESTURE_SENSITIVITY_1: int¶: Limiar nos deltas acumulados U/D e L/R acima do qual o descodificador compromete-se a uma direção de deslize.

apds9960.APDS9960_GESTURE_SENSITIVITY_2: int¶: Limiar nos deltas U/D e L/R por passo abaixo do qual o descodificador considera que uma amostra é candidata a perto/longe em vez de deslize.

apds9960.APDS9960_TIME_FIFO_PAUSE: int¶: Milissegundos que o ciclo de gestos aguarda entre esvaziamentos do FIFO.

Modos de funcionalidade¶

Estes valores são passados a APDS9960.setMode().

apds9960.APDS9960_MODE_POWER: int¶: Bit de ligação (0).

apds9960.APDS9960_MODE_AMBIENT_LIGHT: int¶: Bit de ativação do motor de luz ambiente/cor (1).

apds9960.APDS9960_MODE_PROXIMITY: int¶: Bit de ativação do motor de proximidade (2).

apds9960.APDS9960_MODE_WAIT: int¶: Bit de ativação do estado de espera (3).

apds9960.APDS9960_MODE_AMBIENT_LIGHT_INT: int¶: Bit de ativação de interrupção de luz ambiente (4).

apds9960.APDS9960_MODE_PROXIMITY_INT: int¶: Bit de ativação de interrupção de proximidade (5).

apds9960.APDS9960_MODE_GESTURE: int¶: Bit de ativação do motor de gestos (6).

apds9960.APDS9960_MODE_ALL: int¶: Valor sentinela (7) que indica a APDS9960.setMode() para ativar ou desativar todos os bits do registo ENABLE de uma vez.

Correntes LED de acionamento¶

apds9960.APDS9960_LED_DRIVE_100MA: int¶: Corrente LED de 100 mA (0).

apds9960.APDS9960_LED_DRIVE_50MA: int¶: Corrente LED de 50 mA (1).

apds9960.APDS9960_LED_DRIVE_25MA: int¶: Corrente LED de 25 mA (2).

apds9960.APDS9960_LED_DRIVE_12_5MA: int¶: Corrente LED de 12,5 mA (3).

Ganho de proximidade (PGAIN)¶

apds9960.APDS9960_PGAIN_1X: int¶: Ganho de proximidade 1x (0).

apds9960.APDS9960_PGAIN_2X: int¶: Ganho de proximidade 2x (1).

apds9960.APDS9960_PGAIN_4X: int¶: Ganho de proximidade 4x (2). Predefinição aplicada pelo construtor.

apds9960.APDS9960_PGAIN_8X: int¶: Ganho de proximidade 8x (3).

Ganho de luz ambiente (AGAIN)¶

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

apds9960.APDS9960_AGAIN_4X: int¶: Ganho ALS 4x (1). Predefinição aplicada pelo construtor.

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

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

Ganho de gestos (GGAIN)¶

apds9960.APDS9960_GGAIN_1X: int¶: Ganho de gesto 1x (0).

apds9960.APDS9960_GGAIN_2X: int¶: Ganho de gesto 2x (1).

apds9960.APDS9960_GGAIN_4X: int¶: Ganho de gesto 4x (2). Predefinição aplicada pelo construtor.

apds9960.APDS9960_GGAIN_8X: int¶: Ganho de gesto 8x (3).

Amplificação LED¶

apds9960.APDS9960_LED_BOOST_100: int¶: Amplificação LED de 100% (0).

apds9960.APDS9960_LED_BOOST_150: int¶: Amplificação LED de 150% (1).

apds9960.APDS9960_LED_BOOST_200: int¶: Amplificação LED de 200% (2).

apds9960.APDS9960_LED_BOOST_300: int¶: Amplificação LED de 300% (3). Aplicada automaticamente por APDS9960.enableGestureSensor().

Tempos de espera de gestos¶

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

apds9960.APDS9960_GWTIME_2_8MS: int¶: 2,8 ms (1). Predefinição aplicada pelo construtor.

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

Direções de gestos¶

Estes valores são devolvidos por APDS9960.readGesture().

apds9960.APDS9960_DIR_NONE: int¶: Nenhum gesto detetado (0).

apds9960.APDS9960_DIR_LEFT: int¶: Deslize para a esquerda (1).

apds9960.APDS9960_DIR_RIGHT: int¶: Deslize para a direita (2).

apds9960.APDS9960_DIR_UP: int¶: Deslize para cima (3).

apds9960.APDS9960_DIR_DOWN: int¶: Deslize para baixo (4).

apds9960.APDS9960_DIR_NEAR: int¶: Evento perto (5).

apds9960.APDS9960_DIR_FAR: int¶: Evento longe (6).

apds9960.APDS9960_DIR_ALL: int¶: Valor sentinela (7) usado internamente para representar «qualquer direção».

Estados de gestos¶

Valores de estado interno reportados pela máquina de estados de gestos.

apds9960.APDS9960_STATE_NA: int¶: Sem estado (0).

apds9960.APDS9960_STATE_NEAR: int¶: Estado próximo detetado (1).

apds9960.APDS9960_STATE_FAR: int¶: Estado distante detetado (2).

apds9960.APDS9960_STATE_ALL: int¶: Valor sentinela (3) usado internamente para representar «qualquer estado».

apds9960 — Driver para Sensor de Proximidade, Gestos e Cor¶