Componentes · 13 min de leitura

APDS9960 com Arduino: guia do sensor de gestos, proximidade e cor

Guia do APDS9960 com Arduino: ligações I2C e 3,3 V, gestos para esquerda, direita, cima e baixo, leituras de proximidade e RGB, código SparkFun e Adafruit, pino INT, ESP32 e Pico.

Projetos com APDS9960 e Arduino permitem que um único chip minúsculo faça quatro tarefas: ele detecta sua mão se movendo para a direita, esquerda, cima e baixo, mede a proximidade de um objeto e lê a luz ambiente e a cor dividida nos canais vermelho, verde e azul. Ele é parente do sensor do celular que apaga a tela quando você o aproxima do ouvido e ajusta o brilho ao ambiente. É um ponto de partida ideal para acender uma lâmpada, pular uma música ou navegar por um menu com um movimento da mão, sem tocar em nada.

Neste guia você verá o que há dentro do APDS-9960, como ele detecta gestos, por que precisa funcionar com 3,3 V e como conectá-lo a um Arduino Uno, ESP32 e Raspberry Pi Pico. Com as bibliotecas SparkFun e Adafruit, você montará um teste de gestos, um LED que fica mais brilhante conforme sua mão se aproxima, medições de cor e lux e controles de LEDs e música por gestos, além de aprender a usar o pino INT como interrupção e conhecer os limites reais de alcance.

Módulo sensor de cor, proximidade e gestos APDS-9960
Módulo APDS-9960: detecção de gestos, proximidade, cor RGB e luz ambiente em um único chip; conecta-se por I2C e precisa de 3,3 V.

O que é o APDS-9960 e como ele funciona?

O APDS-9960 é um sensor fabricado pela Broadcom (antiga Avago) que reúne um LED infravermelho (IR) e vários detectores de luz em um encapsulamento de cerca de 4 × 2,4 mm. Para medir a proximidade, o LED IR emite pulsos curtos, a luz refletida pelo objeto à frente retorna aos fotodiodos e, quanto mais forte a reflexão, mais próximo está o objeto. O resultado é um número entre 0 e 255. A medição de cor não usa o LED: a luz ambiente incide em quatro fotodiodos separados com filtros vermelho, verde, azul e sem filtro (clear), e cada um produz um número de 16 bits.

A detecção de gestos é a parte mais engenhosa. Dentro do chip há quatro fotodiodos voltados para cima (U), baixo (D), esquerda (L) e direita (R). Quando sua mão passa sobre o sensor, um diodo vê a reflexão primeiro e o oposto a vê depois. Quando o valor de proximidade ultrapassa um limiar de entrada (40 na biblioteca SparkFun), o mecanismo de gestos é ativado, grava as leituras dos quatro diodos em um buffer FIFO de 32 entradas e para quando a mão se afasta. O Arduino lê essas entradas e observa como a diferença entre U e D, e entre L e R, muda ao longo do tempo: se U é maior primeiro e D é maior depois, a mão se moveu para baixo.

CaracterísticaValor
FabricanteBroadcom (antiga Avago)
Alimentação do chip (VDD)2,4–3,6 V
Alimentação do LED IR (VL)3,0–4,5 V
InterfaceI2C, até 400 kHz
Endereço I2C0x39 (fixo, não pode ser alterado)
Proximidade8 bits (0–255)
Cor e luz4 canais (sem filtro, vermelho, verde, azul), 16 bits por canal
Gestos4 fotodiodos direcionais (U, D, L, R), FIFO de 32 entradas
LED IR950 nm, corrente ajustável de 12,5 a 100 mA
Alcance prático dos gestosCerca de 10–20 cm
Saída de interrupçãoINT, dreno aberto, passa para LOW em um evento

Pinos do módulo e a questão dos 3,3 V

As placas mais comuns são o módulo da SparkFun e seu clone roxo, o GY-9960. Ambos têm seis pinos. A maioria dos módulos tem um jumper de solda chamado PS no verso; enquanto ele está fechado, a alimentação do LED IR (VL) fica conectada diretamente ao VCC e você deixa o pino VL desconectado.

PinoFunçãoConectar a
VLEntrada de alimentação do LED IRDeixe desconectado se o jumper PS estiver fechado
GNDTerraGND
VCCAlimentação do chip3,3 V
SDALinha de dados I2CPino SDA da placa
SCLLinha de clock I2CPino SCL da placa
INTSaída de interrupção (dreno aberto)Um pino digital que aceite interrupções
O chip APDS-9960 suporta no máximo 3,6 V; conectar VCC ao pino 5V do Arduino pode destruí-lo permanentemente. Exceto nas versões especiais com regulador e conversor de nível lógico integrados, sempre alimente o módulo com 3,3 V. Alguns módulos baratos não indicam de qual tipo são; se você não tiver certeza, use 3,3 V.

Ligações: Arduino Uno, ESP32 e Raspberry Pi Pico

APDS-9960Arduino UnoESP32Raspberry Pi Pico
VCC3.3V3V33V3 (OUT)
GNDGNDGNDGND
SDAA4 (por um conversor de nível lógico)GPIO 21GP4
SCLA5 (por um conversor de nível lógico)GPIO 22GP5
INTD2GPIO 4GP15
VLDesconectado (PS fechado)Desconectado (PS fechado)Desconectado (PS fechado)

O ESP32 e o Pico já têm pinos de 3,3 V, então a conexão é direta. No Uno, a situação é um pouco mais complicada: a biblioteca Wire do Uno ativa resistores de pull-up internos em SDA e SCL e puxa as linhas para 5 V, enquanto os resistores do próprio módulo as puxam para 3,3 V. Isso costuma funcionar na prática, mas força os limites do chip. A opção mais segura é um conversor de nível lógico I2C bidirecional entre o Uno e o módulo. Como o pino INT é de dreno aberto, o resistor de pull-up do módulo o mantém em 3,3 V; o Uno lê essa tensão como HIGH, então você não precisa do pull-up interno para INT no Uno. Explicamos como o I2C funciona no guia O que é I2C.

SparkFun ou Adafruit? Como escolher uma biblioteca

CaracterísticaSparkFun APDS9960Adafruit APDS9960
Direções dos gestosCima, baixo, esquerda, direita, além de perto e longeCima, baixo, esquerda, direita
Leitura de proximidadereadProximity(variable)Valor de retorno de readProximity()
Leitura de corFunções separadas, como readRedLight()Tudo de uma vez com getColorData(), além de lux e temperatura de cor
Configurações de interrupçãoInterrupções de gestos, proximidade e luzInterrupções de proximidade e cor, configuração de limiar
ID do chip aceito0xAB e 0x9CSomente 0xAB
Dependência extraNenhuma (somente Wire)Adafruit BusIO

As duas bibliotecas estão no Gerenciador de Bibliotecas: busque SparkFun APDS9960 RGB and Gesture Sensor e Adafruit APDS9960 Library. Para gestos, o algoritmo da SparkFun é um pouco mais estável e também reconhece movimentos de aproximação e afastamento; para cor, as funções de lux e temperatura de cor da Adafruit facilitam o trabalho. Usaremos as duas neste guia. Se esta é sua primeira instalação de uma biblioteca, veja o guia Como instalar uma biblioteca no Arduino.

Passo a passo: seu primeiro teste de gestos (com o pino INT)

  1. Conecte o módulo de acordo com a tabela acima: VCC a 3.3V, SDA a A4, SCL a A5, INT a D2.
  2. Instale a biblioteca SparkFun e carregue o sketch abaixo no Uno.
  3. Abra o Monitor Serial em 9.600 baud e procure a mensagem “Jest sensoru hazir” (sensor de gestos pronto).
  4. Passe a mão de uma borda à outra, 5–10 cm acima do sensor, em um movimento que dure cerca de meio segundo.
  5. Você deve ver YUKARI (cima), ASAGI (baixo), SOL (esquerda) ou SAG (direita); se as direções estiverem invertidas, gire o sensor em 90 ou 180 graus ou troque os casos no código.
C++ (Arduino IDE)
1#include <Wire.h>
2#include <SparkFun_APDS9960.h>
3
4const int APDS_INT = 2;                 // kesme pini (Uno'da 2 ya da 3) / interrupt pin (2 or 3 on Uno)
5SparkFun_APDS9960 apds;
6volatile bool gestureFlag = false;
7
8void onGesture() {                      // INT LOW'a düşünce çalışır / runs when INT goes LOW
9  gestureFlag = true;
10}
11
12void handleGesture() {
13  if (!apds.isGestureAvailable()) return;
14  switch (apds.readGesture()) {
15    case DIR_UP:    Serial.println("YUKARI / UP");    break;
16    case DIR_DOWN:  Serial.println("ASAGI / DOWN");   break;
17    case DIR_LEFT:  Serial.println("SOL / LEFT");     break;
18    case DIR_RIGHT: Serial.println("SAG / RIGHT");    break;
19    case DIR_NEAR:  Serial.println("YAKIN / NEAR");   break;
20    case DIR_FAR:   Serial.println("UZAK / FAR");     break;
21    default:        Serial.println("BELIRSIZ / NONE");
22  }
23}
24
25void setup() {
26  Serial.begin(9600);
27  pinMode(APDS_INT, INPUT);             // modüldeki pull-up 3,3 V'a çeker / module pull-up to 3.3 V
28  attachInterrupt(digitalPinToInterrupt(APDS_INT), onGesture, FALLING);
29
30  if (!apds.init()) {                   // Wire.begin() kütüphanenin içinde / Wire.begin() is inside
31    Serial.println("APDS-9960 bulunamadi / not found");
32    while (true);
33  }
34  if (apds.enableGestureSensor(true)) { // true = jest olunca INT LOW / true = INT goes LOW on a gesture
35    Serial.println("Jest sensoru hazir / gesture sensor ready");
36  }
37}
38
39void loop() {
40  if (gestureFlag) {
41    detachInterrupt(digitalPinToInterrupt(APDS_INT));   // okurken yeni kesme gelmesin / no new IRQ while reading
42    handleGesture();
43    gestureFlag = false;
44    attachInterrupt(digitalPinToInterrupt(APDS_INT), onGesture, FALLING);
45  }
46}

Quando um gesto está pronto, o APDS-9960 coloca o pino INT em LOW, o que dispara a interrupção no pino D2 do Uno. A função de interrupção apenas ativa uma flag; a leitura propriamente dita acontece em loop(), porque readGesture() lê dezenas de bytes por I2C e usar I2C dentro de uma interrupção causa travamentos. Desativar temporariamente a interrupção durante a leitura também impede que o mesmo gesto seja processado duas vezes. Você encontra a lógica das interrupções em detalhes no guia de interrupções no Arduino.

Para obter os melhores resultados, mantenha a mão aberta e estendida e passe-a 5–10 cm acima do sensor em meio segundo. Se você se mover devagar demais, o mecanismo de gestos desliga antes de o movimento terminar; rápido demais, e não se acumulam dados suficientes no FIFO. Se você abaixar a mão bem sobre o sensor e mantê-la parada por um instante, o gesto será detectado como NEAR; se mantiver a mão parada e depois levantá-la devagar, será detectado como FAR. Esses dois movimentos são menos confiáveis que as quatro direções.

Detecção de proximidade: um LED que fica mais brilhante quando sua mão se aproxima

Medir apenas a proximidade, em vez de gestos, é muito mais simples e estável. O sketch abaixo envia o valor de proximidade diretamente a um LED por PWM: quanto mais perto sua mão estiver, mais brilhante fica o LED, e ele vai diminuindo o brilho conforme você a afasta. Conecte o LED a D9 por um resistor de 220 Ω; você pode encontrar o valor adequado com a calculadora Resistor para LED.

C++ (Arduino IDE)
1#include <Wire.h>
2#include <SparkFun_APDS9960.h>
3
4SparkFun_APDS9960 apds;
5const int LED_PIN = 9;                  // PWM pini / PWM pin
6
7void setup() {
8  Serial.begin(9600);
9  pinMode(LED_PIN, OUTPUT);
10  if (!apds.init()) {
11    Serial.println("APDS-9960 bulunamadi / not found");
12    while (true);
13  }
14  apds.setProximityGain(PGAIN_2X);      // kazanç: 1X, 2X, 4X, 8X / gain
15  apds.enableProximitySensor(false);    // false = kesme yok / no interrupt
16}
17
18void loop() {
19  uint8_t prox = 0;                     // 0 = uzak, 255 = çok yakın / 0 far, 255 very close
20  if (apds.readProximity(prox)) {
21    analogWrite(LED_PIN, prox);         // el yaklaştıkça LED parlar / LED gets brighter as the hand comes closer
22    Serial.println(prox);
23  }
24  delay(50);
25}

O valor de proximidade não é uma medida em centímetros; ele representa a intensidade da luz refletida. Uma folha de papel branco pode indicar 40 a 15 cm, enquanto um tecido preto à mesma distância fica abaixo de 10. Por isso, use o APDS-9960 para responder “algo se aproximou?”, e não como medidor de distância. Se você precisa de uma distância exata, o sensor ultrassônico HC-SR04 é uma opção mais precisa. Se os valores forem muito baixos, ajuste o ganho para PGAIN_4X ou PGAIN_8X; se ficarem em 255 o tempo todo, reduza para PGAIN_1X.

Medição de cor RGB e luz ambiente

Na medição de cor, o APDS-9960 lê quatro canais: vermelho (R), verde (G), azul (B) e luz total sem filtro (C). A biblioteca Adafruit também calcula um valor aproximado em lux e a temperatura de cor da luz (em Kelvin) a partir desses valores brutos. O sketch abaixo imprime os quatro canais e os valores de lux e Kelvin a cada meio segundo e informa qual cor predomina.

C++ (Arduino IDE)
1#include <Adafruit_APDS9960.h>
2
3Adafruit_APDS9960 apds;
4
5void setup() {
6  Serial.begin(9600);
7  if (!apds.begin()) {                  // kimlik 0xAB değilse false / false if the ID is not 0xAB
8    Serial.println("APDS-9960 bulunamadi / not found");
9    while (true);
10  }
11  apds.setADCIntegrationTime(100);      // 100 ms ölçüm: daha hassas / 100 ms integration: more sensitive
12  apds.enableColor(true);               // renk + ortam ışığı / colour + ambient light
13}
14
15void loop() {
16  uint16_t r, g, b, c;
17  while (!apds.colorDataReady()) delay(5);              // ölçüm bitene kadar bekle / wait for a reading
18  apds.getColorData(&r, &g, &b, &c);
19  uint16_t lux = apds.calculateLux(r, g, b);            // yaklaşık lüks / approximate lux
20  uint16_t cct = apds.calculateColorTemperature(r, g, b); // renk sıcaklığı (K) / colour temperature (K)
21
22  Serial.print("R:");  Serial.print(r);
23  Serial.print(" G:"); Serial.print(g);
24  Serial.print(" B:"); Serial.print(b);
25  Serial.print(" C:"); Serial.print(c);
26  Serial.print("  lux:"); Serial.print(lux);
27  Serial.print("  K:");   Serial.println(cct);
28
29  if (c > 100) {                        // yeterli ışık varsa baskın rengi söyle / name the dominant colour
30    if (r > g && r > b)      Serial.println("Kirmizi / red");
31    else if (g > r && g > b) Serial.println("Yesil / green");
32    else                     Serial.println("Mavi / blue");
33  }
34  delay(500);
35}

Os valores brutos não são cores absolutas, mas quantidades de luz; o mesmo cartão vermelho fornece números muito diferentes em uma sala pouco iluminada e sob a luz do sol. Por isso, compare proporções ao comparar cores: a razão entre R e C permanece mais estável mesmo quando a luz muda. Se quiser ler a cor de um objeto, mantenha-o a 1–2 cm do sensor e bloqueie a luz externa com a mão ou um tubo. O valor em lux é uma aproximação; não substitui um luxímetro, mas é mais que suficiente para saber “o ambiente ficou escuro?”. Para projetos que precisam distinguir cores com mais precisão, considere sensores dedicados apenas a cores, como o sensor de cor TCS3200 ou o TCS34725.

Controle de um LED por gestos (sem o pino INT)

Você não precisa conectar o pino INT. A biblioteca também pode descobrir se há um novo gesto consultando continuamente o registrador de status do mecanismo de gestos por I2C. Isso economiza um pino e mantém o código simples; em contrapartida, loop() gera tráfego I2C constante. No sketch abaixo, um gesto para cima acende o LED com brilho máximo, um gesto para baixo o apaga e os gestos para a direita e para a esquerda aumentam e diminuem o brilho em passos de um quarto.

C++ (Arduino IDE)
1#include <Wire.h>
2#include <SparkFun_APDS9960.h>
3
4SparkFun_APDS9960 apds;
5const int LED_PIN = 9;                  // PWM pini / PWM pin
6int level = 0;                          // parlaklık 0-255 / brightness 0-255
7
8void setup() {
9  Serial.begin(9600);
10  pinMode(LED_PIN, OUTPUT);
11  if (!apds.init()) {
12    Serial.println("APDS-9960 bulunamadi / not found");
13    while (true);
14  }
15  apds.enableGestureSensor(false);      // INT olmadan, sorgulayarak / polling, no INT pin
16}
17
18void loop() {
19  if (apds.isGestureAvailable()) {
20    switch (apds.readGesture()) {
21      case DIR_UP:    level = 255; break;                   // tam aç / fully on
22      case DIR_DOWN:  level = 0;   break;                   // kapat / off
23      case DIR_RIGHT: level = min(level + 64, 255); break;  // daha parlak / brighter
24      case DIR_LEFT:  level = max(level - 64, 0);   break;  // daha sönük / dimmer
25      default: break;
26    }
27    analogWrite(LED_PIN, level);
28    Serial.print("Parlaklik / brightness: ");
29    Serial.println(level);
30  }
31}

Controle de música por gestos: com o DFPlayer Mini

Módulo reprodutor de MP3 DFPlayer Mini
DFPlayer Mini: reproduz arquivos MP3 de um cartão SD e recebe comandos por uma linha serial.

O uso mais divertido de um sensor de gestos é um reprodutor de música sem toque. Conecte o pino RX do DFPlayer Mini a D11 do Uno por um resistor de 1 kΩ e o pino TX a D10; conecte o alto-falante a SPK_1 e SPK_2 e alimente o módulo por 5V. Copie suas músicas para o cartão SD com os nomes 0001.mp3, 0002.mp3 e assim por diante. Os detalhes do módulo estão no guia do DFPlayer Mini. Um gesto para a direita pula para a próxima música, e um para a esquerda volta à anterior; gestos para cima e para baixo aumentam e diminuem o volume, e manter a mão parada sobre o sensor pausa e retoma a reprodução.

C++ (Arduino IDE)
1#include <Wire.h>
2#include <SoftwareSerial.h>
3#include <SparkFun_APDS9960.h>
4#include <DFRobotDFPlayerMini.h>
5
6SoftwareSerial mp3Serial(10, 11);       // RX, TX (TX hattına 1 kΩ / 1 kΩ on the TX line)
7DFRobotDFPlayerMini player;
8SparkFun_APDS9960 apds;
9bool playing = true;
10int volume = 18;                        // ses 0-30 / volume 0-30
11
12void setup() {
13  Serial.begin(9600);
14  mp3Serial.begin(9600);
15  if (!player.begin(mp3Serial)) { Serial.println("DFPlayer yok / not found"); while (true); }
16  if (!apds.init())             { Serial.println("APDS-9960 yok / not found"); while (true); }
17  apds.enableGestureSensor(false);
18  player.volume(volume);
19  player.play(1);                       // SD karttaki 0001.mp3 / 0001.mp3 on the SD card
20}
21
22void loop() {
23  if (!apds.isGestureAvailable()) return;
24  switch (apds.readGesture()) {
25    case DIR_RIGHT: player.next();     Serial.println("Sonraki / next");       break;
26    case DIR_LEFT:  player.previous(); Serial.println("Onceki / previous");    break;
27    case DIR_UP:    volume = min(volume + 3, 30); player.volume(volume);      break;
28    case DIR_DOWN:  volume = max(volume - 3, 0);  player.volume(volume);      break;
29    case DIR_NEAR:                      // eli sensör üzerinde sabit tut / hold the hand still
30      if (playing) player.pause(); else player.start();
31      playing = !playing;
32      break;
33    default: break;
34  }
35}

Há um detalhe que você precisa saber aqui: readGesture() só retorna quando o gesto termina e espera 30 ms entre as leituras do FIFO. Enquanto sua mão permanece sobre o sensor, o Arduino não faz mais nada. Isso não é um problema para um reprodutor de música, mas, se o mesmo sketch tiver um motor ou uma animação no display que precise de resposta rápida, você terá que planejá-los levando em conta a leitura de gestos.

O pino INT e o ESP32: detecção de proximidade por interrupção

O pino INT não serve apenas para gestos; ele também pode ser usado para limiares de proximidade e luz. Você define um limiar; quando uma leitura o ultrapassa, o APDS-9960 coloca INT em LOW e o mantém assim até você limpar a interrupção. Dessa forma, o microcontrolador não precisa consultar o sensor continuamente. O sketch para ESP32 abaixo usa a biblioteca Adafruit para acionar INT quando a proximidade passa de 150 e alterna o estado do LED integrado a cada aproximação de uma mão, como um interruptor de luz sem toque.

C++ (Arduino IDE)
1#include <Wire.h>
2#include <Adafruit_APDS9960.h>
3
4const int INT_PIN = 4;                  // APDS INT -> GPIO 4
5const int LED_PIN = 2;                  // karttaki LED / on-board LED
6Adafruit_APDS9960 apds;
7bool ledOn = false;
8
9void setup() {
10  Serial.begin(115200);
11  pinMode(INT_PIN, INPUT_PULLUP);       // 3,3 V'a çekmek güvenli / pulling up to 3.3 V is safe
12  pinMode(LED_PIN, OUTPUT);
13  Wire.begin(21, 22);                   // SDA, SCL
14  if (!apds.begin()) {
15    Serial.println("APDS-9960 bulunamadi / not found");
16    while (true) delay(10);
17  }
18  apds.enableProximity(true);
19  apds.setProximityInterruptThreshold(0, 150);  // 150'yi aşınca INT LOW / INT goes LOW above 150
20  apds.enableProximityInterrupt();
21}
22
23void loop() {
24  if (digitalRead(INT_PIN) == LOW) {    // el yaklaştı / a hand came close
25    uint8_t p = apds.readProximity();
26    ledOn = !ledOn;                     // her yaklaşmada aç-kapa / toggle on every approach
27    digitalWrite(LED_PIN, ledOn);
28    Serial.printf("Yakinlik / proximity: %u  LED: %s\n", p, ledOn ? "ON" : "OFF");
29    while (apds.readProximity() > 100) delay(20);  // el çekilene kadar bekle / wait for the hand to leave
30    apds.clearInterrupt();              // INT'i serbest bırak / release INT
31  }
32}

O terceiro parâmetro de setProximityInterruptThreshold() (4 por padrão) é a persistência: ele indica quantas leituras consecutivas precisam ultrapassar o limiar antes de a interrupção ser disparada, o que filtra ruídos momentâneos. Se você não chamar clearInterrupt(), INT permanece em LOW e a próxima aproximação não será detectada. Essa configuração é muito útil em projetos alimentados por bateria: coloque o ESP32 em deep sleep e desperte-o pelo pino INT com esp_sleep_enable_ext0_wakeup(GPIO_NUM_4, 0), e a placa só acordará quando alguém aproximar a mão. GPIO 4 é um pino RTC, portanto é adequado para isso.

APDS-9960 com o Raspberry Pi Pico (MicroPython)

No Raspberry Pi Pico, você pode usar o APDS-9960 em MicroPython sem nenhuma biblioteca, escrevendo diretamente nos registradores. O código abaixo lê o ID do chip, ativa a medição de cor e proximidade e imprime os quatro canais de cor e o valor de proximidade a cada 200 ms. A ligação usa o barramento I2C0: SDA em GP4, SCL em GP5 e VCC no pino 3V3(OUT).

MicroPython
1from machine import Pin, I2C
2import time
3
4ADDR = 0x39                              # APDS-9960 sabit adresi / fixed address
5i2c = I2C(0, sda=Pin(4), scl=Pin(5), freq=400000)
6
7def write(reg, val):
8    i2c.writeto_mem(ADDR, reg, bytes([val]))
9
10def read(reg, n=1):
11    return i2c.readfrom_mem(ADDR, reg, n)
12
13print("ID:", hex(read(0x92)[0]))         # orijinalde 0xAB / 0xAB on a genuine chip
14
15write(0x80, 0x00)                        # ENABLE: her şeyi kapat / everything off
16write(0x81, 0xDB)                        # ATIME: 37 döngü, ~103 ms / 37 cycles, ~103 ms
17write(0x8E, 0x87)                        # PPULSE: 16 us, 8 darbe / 16 us, 8 pulses
18write(0x8F, 0x09)                        # CONTROL: LED 100 mA, PGAIN 4x, AGAIN 4x
19write(0x80, 0x07)                        # ENABLE: PON + AEN (renk/colour) + PEN (yakınlık/proximity)
20time.sleep_ms(150)
21
22while True:
23    if read(0x93)[0] & 0x01:             # STATUS.AVALID: renk verisi hazır / colour data ready
24        d = read(0x94, 8)                # C, R, G, B: ikişer bayt / two bytes each
25        c = d[0] | d[1] << 8
26        r = d[2] | d[3] << 8
27        g = d[4] | d[5] << 8
28        b = d[6] | d[7] << 8
29        prox = read(0x9C)[0]             # PDATA: 0-255
30        print("C", c, "R", r, "G", g, "B", b, "yakinlik/prox", prox)
31    time.sleep_ms(200)

Veja o que fazem os registradores no código: 0x80 (ENABLE) seleciona quais blocos estão ligados, 0x81 (ATIME) define o tempo de integração da cor (2,78 ms por passo), 0x8F (CONTROL) define a corrente do LED IR e os ganhos, 0x93 (STATUS) informa se os dados estão prontos, 0x94–0x9B armazenam os canais de cor e 0x9C armazena o valor de proximidade. Para gestos, você teria que ler o FIFO e escrever um algoritmo de direção como o da SparkFun, o que dá mais trabalho. Se preferir o Arduino IDE, instale o core arduino-pico no Pico e use a biblioteca SparkFun sem alterações; os pinos I2C padrão são novamente GP4 e GP5.

Limites de alcance e uso correto

O APDS-9960 foi projetado como sensor de celular e seu alcance é curto. Na prática, os gestos são confiáveis entre 5 e 15 cm e chegam a 20 cm no melhor dos casos. As leituras de proximidade são úteis até uma distância semelhante. O que define esse limite é a potência do LED IR e a quantidade de luz refletida pela sua mão; aumentar a corrente do LED para 100 mA e o ganho para o máximo acrescenta um pouco de alcance, mas também mais ruído.

FatorEfeitoO que fazer
DistânciaOs gestos deixam de ser detectados além de 15 cmPasse a mão a 5–10 cm
Velocidade do movimentoMovimentos muito lentos ou muito rápidos não são detectadosUm movimento suave de meio segundo
Luz solarO IR da luz solar satura os fotodiodosUse na sombra ou em ambientes internos
Vidro ou cobertura transparenteA cobertura reflete o IR de volta, então a leitura de proximidade fica sempre altaRemova a cobertura ou use um material fino transparente ao IR
Cor da superfícieUma luva preta reflete menosAumente o ganho
Orientação do sensorAs direções giramTroque os casos de direção no código

Ideias de projetos com APDS-9960

  • Luminária sem toque: Alterne o estado de um módulo relé com a interrupção de proximidade; muito útil na cozinha quando suas mãos estão sujas.
  • Luminária colorida por gestos: Use gestos para a direita e para a esquerda para percorrer as cores de um LED RGB ou de uma fita WS2812B.
  • Menu no ar: Escolha itens de menu em um display OLED com gestos para cima e para baixo e confirme com NEAR.
  • Tampa com servo por gestos: Abra a tampa de uma caixa com um gesto e um servo motor.
  • Brilho automático do display: Ajuste uma tela ou fita LED à luz ambiente; em comparação com um LDR, você obtém uma leitura mais estável com informações de cor.
  • Separador de cores: Separe doces ou blocos coloridos que descem por uma calha de acordo com seus canais de cor.

Erros comuns e soluções

SintomaCausa provávelSolução
“APDS-9960 bulunamadi” (não encontrado)Erro de ligação, falta de 3,3 V ou ID do chip diferenteProcure 0x39 com um scanner I2C e leia o ID
Módulo encontrado, mas init falhaUm chip clone com ID diferente, como 0xA8Adicione esse valor à verificação de ID da biblioteca
Nenhum gesto detectadoMão muito distante ou movimento muito lento, VL sem alimentaçãoPasse a mão a 5–10 cm em meio segundo e verifique o jumper PS
Direções invertidas ou trocadasOrientação de montagem do sensorTroque os casos DIR no código
Proximidade sempre altaVidro, cobertura ou superfície próxima à frenteRemova a cobertura e reduza o ganho
Não funciona ao ar livreA luz solar encobre o IRUse na sombra
Travamentos aleatórios no UnoIncompatibilidade entre I2C de 5 V e 3,3 V, fios longosConversor de nível lógico e fios curtos
INT permanece em LOWInterrupção não limpaChame clearInterrupt() após a leitura
Se tiver problemas, primeiro confirme que o endereço 0x39 aparece com um sketch scanner I2C e depois execute o código simples que mede apenas proximidade. Se o valor de proximidade subir de 0 para mais de 200 quando você aproximar a mão, o hardware está funcionando e o problema está nas configurações de gestos ou no movimento da sua mão.

Com um pequeno módulo, o APDS-9960 acrescenta controle sem toque, detecção de proximidade e medição de cor ao seu projeto. Lembre-se do alcance curto e da regra dos 3,3 V, e ele se torna um elemento de interface confiável. No app BlueGrays, você encontra projetos de LED RGB, medição de luz com LDR, sensor de movimento e medição de distância com esquemas do circuito e códigos passo a passo, e pode adicionar o APDS-9960 a eles para criar versões sem toque.

Perguntas frequentes

O APDS-9960 funciona com 5 V?

Não, o chip APDS-9960 funciona com 2,4–3,6 V, e 5 V podem danificá-lo. Alimente o módulo pelo pino 3.3V do Arduino Uno e, se possível, coloque um conversor de nível lógico nas linhas SDA e SCL. Somente versões especiais que indiquem claramente ter regulador e conversor de nível lógico integrados podem ser usadas com 5 V.

Qual é o endereço I2C do APDS-9960?

O endereço I2C do APDS-9960 é 0x39 e não pode ser alterado. Por isso, você não pode colocar dois APDS-9960 no mesmo barramento I2C; se precisar de dois sensores, use um multiplexador I2C como o TCA9548A ou o segundo barramento I2C do ESP32 ou do Pico.

Qual é o alcance de detecção de gestos do APDS-9960?

Na prática, os gestos são detectados de forma confiável entre 5 e 15 cm e podem alcançar 20 cm em boas condições. O alcance depende da quantidade de luz refletida pela sua mão, da corrente do LED IR e do ajuste de ganho. A luz solar e um vidro à frente do sensor reduzem bastante o alcance.

Preciso conectar o pino INT do APDS-9960?

Não. As bibliotecas também podem ler gestos e proximidade por polling via I2C; na biblioteca SparkFun, enableGestureSensor(false) faz isso. O pino INT informa um evento imediatamente, sem consultas constantes, o que reduz a carga do processador e pode despertar um ESP32 do deep sleep.

Qual é a precisão do sensor de cor APDS-9960?

O APDS-9960 mede seus canais de cor com resolução de 16 bits, mas fornece valores brutos que dependem da luz ambiente, em vez de cores absolutas. Se você mantiver um objeto próximo e bloquear a luz externa, ele distingue facilmente cartões vermelhos, verdes e azuis. Para distinguir cores com mais precisão, sensores dedicados apenas a cores, como o TCS34725 ou o TCS3200, são uma opção melhor.

Por que recebo o erro APDS-9960 init failed?

Esse erro significa que a biblioteca não conseguiu ler o ID do sensor ou não encontrou o valor esperado. Verifique as ligações, a alimentação de 3,3 V e se SDA e SCL não estão trocados; depois, procure o endereço 0x39 com um scanner I2C. Se o endereço aparecer, o chip pode ser um clone; leia o valor no registrador de ID e adicione-o à lista aceita pela biblioteca.

Ver todos os projetos
Medição da intensidade da luz com LDR
AR-11Iniciante

Medição da intensidade da luz com LDR

Quer ver a luminosidade do seu quarto em números? O LDR, um pequeno componente sensível à luz, mede a luz ambiente, e o Arduino exibe o valor na tela do computador a cada meio segundo.

4.6(83)
143
Uso de LED RGB
AR-39Iniciante
Premium

Uso de LED RGB

Três cores se escondem em um único LED: o LED RGB acende primeiro em vermelho, depois em verde e, por fim, em azul.

4.9(73)
100
Transição suave de cores com LED RGB
AR-40Iniciante
Premium

Transição suave de cores com LED RGB

Um único LED RGB muda lentamente do vermelho para o verde, do verde para o azul e de volta para o vermelho, repetindo esse ciclo de arco-íris sem parar.

4.8(58)
78
Detector de movimento com sensor de movimento
AR-24Iniciante
Premium

Detector de movimento com sensor de movimento

Um vigia simples que avisa quando alguém entra no cômodo. O sensor de movimento detecta o calor emitido pelo corpo humano, e o Arduino mantém o LED aceso enquanto há movimento e o apaga quando ele…

4.6(47)
67
Campainha e luz com sensor de movimento
AR-25Intermediário
Premium

Campainha e luz com sensor de movimento

Quando alguém se aproxima da sua porta, você fica sabendo antes mesmo de a pessoa tocar a campainha.

4.7(54)
72
Leitura de reflexão (proximidade) com TCRT5000
AR-77Intermediário
Premium

Leitura de reflexão (proximidade) com TCRT5000

Com um pequeno sensor que emite luz invisível e mede quanto dela é refletido, você detecta a superfície à frente dele.

4.6(33)
43
Controle de LED RGB com ESP32
ES-9Iniciante

Controle de LED RGB com ESP32

Gere inúmeras cores com um único LED RGB em vez de 3 LEDs separados. Como no Arduino, ajustamos os valores R/G/B com analogWrite() para criar uma transição de arco-íris. Você vê a teoria das cores na prática, como vermelho + verde = amarelo.

4.6(29)
52
Iluminação inteligente com ESP32 (PIR + LDR + relé + OLED)
ES-37Avançado
Premium

Iluminação inteligente com ESP32 (PIR + LDR + relé + OLED)

Transforme a iluminação do corredor, banheiro ou despensa em iluminação inteligente com ESP32! Com um sensor de movimento PIR, um sensor de luz LDR e um módulo relé, montamos o cenário clássico de "acender a luz ao detectar movimento no escuro" — se o ambiente já estiver claro, o movimento NÃO aciona a luz, economizando energia durante o dia. A luz fica acesa por 30 segundos; se o movimento continuar, o temporizador reinicia e a luz permanece acesa por mais tempo.

4.3(6)
11