Componenti · 12 min di lettura

APDS9960 Arduino: sensore di gesti, prossimità e colore

Guida APDS9960 Arduino: collegamento I2C e 3,3 V, gesti su, giù, sinistra e destra, prossimità e RGB, codice SparkFun e Adafruit, pin INT, ESP32 e Pico.

I progetti APDS9960 Arduino fanno svolgere quattro compiti a un unico chip minuscolo: rileva se la tua mano si muove a destra, a sinistra, in su o in giù, misura quanto è vicino un oggetto e legge la luce ambiente e il colore separati nei canali rosso, verde e blu. È un parente del sensore dello smartphone che spegne lo schermo quando lo avvicini all'orecchio e regola la luminosità in base alla stanza. È un punto di partenza ideale per accendere una lampada, cambiare brano o muoverti in un menu con un gesto, senza toccare nulla.

In questa guida vedrai cosa c'è dentro l'APDS-9960, come riconosce i gesti, perché deve funzionare a 3,3 V e come collegarlo ad Arduino Uno, ESP32 e Raspberry Pi Pico. Con le librerie SparkFun e Adafruit farai un test dei gesti, un LED che si illumina quando la mano si avvicina, misure di colore e lux, il controllo di LED e musica con i gesti, e imparerai a usare il pin INT come interrupt e quali sono i veri limiti di portata.

Modulo sensore di colore, prossimità e gesti APDS-9960
Modulo APDS-9960: gesti, prossimità, colore RGB e luce ambiente in un solo chip; si collega via I2C e richiede 3,3 V.

Cos'è l'APDS-9960 e come funziona?

L'APDS-9960 è un sensore prodotto da Broadcom (in passato Avago) che racchiude un LED infrarosso (IR) e diversi rivelatori di luce in un package di circa 4 × 2,4 mm. Per la prossimità il LED IR emette brevi impulsi, la luce riflessa dall'oggetto torna sui fotodiodi e più forte è il riflesso, più l'oggetto è vicino. Il risultato è un numero tra 0 e 255. La misura del colore non usa il LED: la luce ambiente cade su quattro fotodiodi con filtri rosso, verde, blu e senza filtro (clear), e ognuno produce un numero a 16 bit.

Il riconoscimento dei gesti è la parte più ingegnosa. Nel chip ci sono quattro fotodiodi rivolti verso l'alto (U), il basso (D), la sinistra (L) e la destra (R). Quando la mano passa sopra il sensore, un diodo vede il riflesso per primo e quello opposto un po' dopo. Quando il valore di prossimità supera una soglia di ingresso (40 nella libreria SparkFun), il motore dei gesti si avvia, scrive le letture dei quattro diodi in un buffer FIFO da 32 voci e si ferma quando la mano si allontana. Arduino legge queste voci e osserva come cambia nel tempo la differenza tra U e D e tra L e R: se prima è maggiore U e poi D, la mano si è mossa verso il basso.

CaratteristicaValore
ProduttoreBroadcom (in passato Avago)
Alimentazione del chip (VDD)2,4–3,6 V
Alimentazione del LED IR (VL)3,0–4,5 V
InterfacciaI2C, fino a 400 kHz
Indirizzo I2C0x39 (fisso, non modificabile)
Prossimità8 bit (0–255)
Colore e luce4 canali (clear, rosso, verde, blu), 16 bit per canale
Gesti4 fotodiodi direzionali (U, D, L, R), FIFO da 32 voci
LED IR950 nm, corrente regolabile da 12,5 a 100 mA
Portata pratica dei gestiCirca 10–20 cm
Uscita di interruptINT, open-drain, va a LOW quando c'è un evento

Pin del modulo e la questione dei 3,3 V

In commercio si trovano soprattutto la scheda SparkFun e la sua copia viola, la GY-9960. Entrambe hanno sei pin. La maggior parte dei moduli ha sul retro un ponticello a saldare chiamato PS; quando è chiuso, l'alimentazione del LED IR (VL) è collegata direttamente a VCC e lasci il pin VL scollegato.

PinFunzioneCollegamento
VLIngresso di alimentazione del LED IRScollegato se il ponticello PS è chiuso
GNDMassaGND
VCCAlimentazione del chip3,3 V
SDALinea dati I2CPin SDA della scheda
SCLLinea di clock I2CPin SCL della scheda
INTUscita di interrupt (open-drain)Un pin digitale con interrupt
Il chip APDS-9960 accetta al massimo 3,6 V; collegare VCC al pin 5V di Arduino può danneggiarlo in modo permanente. A parte versioni speciali con regolatore e convertitore di livello sulla scheda, alimenta sempre il modulo a 3,3 V. Alcuni moduli economici non lo indicano; nel dubbio usa 3,3 V.

Collegamento: Arduino Uno, ESP32 e Raspberry Pi Pico

APDS-9960Arduino UnoESP32Raspberry Pi Pico
VCC3.3V3V33V3 (OUT)
GNDGNDGNDGND
SDAA4 (con convertitore di livello)GPIO 21GP4
SCLA5 (con convertitore di livello)GPIO 22GP5
INTD2GPIO 4GP15
VLScollegato (PS chiuso)Scollegato (PS chiuso)Scollegato (PS chiuso)

ESP32 e Pico lavorano già a 3,3 V e si collegano direttamente. Con la Uno la situazione è un po' più complicata: la libreria Wire della Uno attiva le resistenze di pull-up interne su SDA e SCL e porta le linee verso 5 V, mentre le resistenze del modulo le portano a 3,3 V. In pratica di solito funziona, ma mette il chip al limite. La soluzione più sana è un convertitore di livello I2C bidirezionale tra Uno e modulo. Dato che il pin INT è open-drain, la resistenza di pull-up del modulo lo mantiene a 3,3 V; la Uno legge questa tensione come HIGH, quindi per INT non serve il pull-up interno. Spieghiamo come funziona l'I2C nella guida cos'è l'I2C.

SparkFun o Adafruit? Scegliere la libreria

CaratteristicaSparkFun APDS9960Adafruit APDS9960
Direzioni dei gestiSu, giù, sinistra, destra più vicino e lontanoSu, giù, sinistra, destra
Lettura della prossimitàreadProximity(variabile)Valore restituito da readProximity()
Lettura del coloreFunzioni separate come readRedLight()Tutto insieme con getColorData(), più lux e temperatura di colore
InterruptGesti, prossimità e luceProssimità e colore, con soglia regolabile
ID del chip accettato0xAB e 0x9CSolo 0xAB
Dipendenza aggiuntivaNessuna (solo Wire)Adafruit BusIO

Entrambe le librerie sono nel Gestore librerie: cerca SparkFun APDS9960 RGB and Gesture Sensor e Adafruit APDS9960 Library. Per i gesti l'algoritmo di SparkFun è un po' più stabile e riconosce anche i movimenti di avvicinamento e allontanamento; per il colore le funzioni di lux e temperatura di colore di Adafruit semplificano il lavoro. In questa guida le useremo entrambe. Se è la prima volta che installi una libreria, dai un'occhiata alla guida aggiungere una libreria Arduino.

Passo dopo passo: il primo test dei gesti (con il pin INT)

  1. Collega il modulo secondo la tabella qui sopra: VCC a 3.3V, SDA ad A4, SCL ad A5, INT a D2.
  2. Installa la libreria SparkFun e carica sulla Uno lo sketch qui sotto.
  3. Apri il Monitor seriale a 9600 baud e attendi il messaggio "Jest sensoru hazir" (sensore di gesti pronto).
  4. Passa la mano a 5–10 cm sopra il sensore da un bordo all'altro, con una velocità che richieda circa mezzo secondo.
  5. Vedrai YUKARI (su), ASAGI (giù), SOL (sinistra) o SAG (destra); se le direzioni sono invertite, ruota il sensore di 90 o 180 gradi oppure scambia i casi nel codice.
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 un gesto è pronto, l'APDS-9960 porta il pin INT a LOW e questo fa scattare l'interrupt sul pin D2 della Uno. La funzione di interrupt si limita ad alzare un flag; la lettura vera avviene nel loop(), perché readGesture() legge decine di byte via I2C e usare l'I2C dentro un interrupt provoca blocchi. Disattivare per un attimo l'interrupt durante la lettura evita anche che lo stesso gesto venga gestito due volte. Trovi la logica degli interrupt nel dettaglio nella guida interrupt di Arduino.

Per i risultati migliori tieni la mano piatta e aperta e passala a 5–10 cm dal sensore in mezzo secondo. Se vai troppo piano il motore dei gesti si spegne prima che il movimento finisca; se vai troppo veloce nella FIFO non si accumulano abbastanza dati. Se abbassi la mano proprio sopra il sensore e la tieni ferma per un momento viene riconosciuto NEAR; se la tieni ferma e poi la sollevi lentamente, FAR. Questi due movimenti sono meno affidabili delle quattro direzioni.

Rilevare la prossimità: un LED che si illumina avvicinando la mano

Misurare solo la prossimità, invece dei gesti, è molto più semplice e stabile. Lo sketch qui sotto invia il valore di prossimità direttamente a un LED in PWM: più la mano è vicina, più il LED si illumina, e si spegne quando la allontani. Collega il LED a D9 con una resistenza da 220 Ω; puoi trovare il valore giusto con il calcolatore della resistenza per 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}

Il valore di prossimità non è in centimetri, ma è l'intensità della luce riflessa. Un foglio bianco può dare 40 a 15 cm, mentre un tessuto nero alla stessa distanza resta sotto 10. Per questo conviene usare l'APDS-9960 non come misuratore di distanza, ma come risposta alla domanda "si è avvicinato qualcosa?". Se ti serve una distanza precisa, il sensore a ultrasuoni HC-SR04 è una scelta più accurata. Se i valori sono molto bassi porta il guadagno a PGAIN_4X o PGAIN_8X; se restano sempre a 255 scendi a PGAIN_1X.

Misurare il colore RGB e la luce ambiente

Per il colore l'APDS-9960 legge quattro canali: rosso (R), verde (G), blu (B) e luce totale senza filtro (C). La libreria Adafruit calcola anche, partendo da questi valori grezzi, un valore approssimativo in lux e la temperatura di colore della luce in kelvin. Lo sketch qui sotto stampa ogni mezzo secondo i quattro canali, i lux e i kelvin e indica quale colore prevale.

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}

I valori grezzi non sono colori assoluti ma quantità di luce; la stessa carta rossa dà numeri molto diversi in una stanza buia e al sole. Per confrontare i colori guarda quindi i rapporti: il rapporto tra R e C resta più stabile anche quando la luce cambia. Se vuoi leggere il colore di un oggetto, avvicinalo a 1–2 cm dal sensore e copri la luce esterna con la mano o con un tubo. Il valore in lux è un'approssimazione; non sostituisce un luxmetro, ma basta e avanza per capire se la stanza è diventata buia. Per progetti che richiedono una distinzione dei colori più fine, valuta sensori dedicati solo al colore come il sensore di colore TCS3200 o il TCS34725.

Controllare un LED con i gesti (senza il pin INT)

Non sei obbligato a collegare il pin INT. La libreria può capire se c'è un nuovo gesto anche interrogando via I2C il registro di stato del motore dei gesti. Così risparmi un pin e il codice resta semplice; il prezzo è un traffico I2C continuo nel loop(). Nello sketch qui sotto un gesto verso l'alto accende il LED al massimo, uno verso il basso lo spegne, e i gesti a destra e a sinistra aumentano e riducono la luminosità a passi di un 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}

Controllare la musica con i gesti: con il DFPlayer Mini

Modulo lettore MP3 DFPlayer Mini
DFPlayer Mini: riproduce i file MP3 da una scheda SD e riceve i comandi tramite una linea seriale.

L'uso più divertente di un sensore di gesti è un lettore musicale senza contatto. Collega il pin RX del DFPlayer Mini al D11 della Uno tramite una resistenza da 1 kΩ e il pin TX al D10; collega l'altoparlante a SPK_1 e SPK_2 e alimenta il modulo dai 5V. Copia i brani sulla scheda SD con i nomi 0001.mp3, 0002.mp3 e così via. I dettagli del modulo sono nella guida DFPlayer Mini. Un gesto a destra passa al brano successivo e uno a sinistra al precedente; i gesti su e giù alzano e abbassano il volume, e tenere la mano ferma sopra il sensore mette in pausa e riprende la riproduzione.

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}

C'è un dettaglio da conoscere: readGesture() non restituisce il controllo finché il gesto non è finito e aspetta 30 ms tra una lettura della FIFO e l'altra. Finché la tua mano resta sopra il sensore, Arduino non fa nient'altro. Per un lettore musicale non è un problema, ma se lo stesso sketch gestisce un motore o un'animazione sul display che devono reagire in fretta, dovrai organizzarli attorno alla lettura dei gesti.

Il pin INT e l'ESP32: rilevare la prossimità con un interrupt

Il pin INT non serve solo per i gesti; si può usare anche con soglie di prossimità e di luce. Imposti una soglia e, quando una lettura la supera, l'APDS-9960 porta INT a LOW e ce lo tiene finché non lo azzeri. Così il microcontrollore non deve interrogare il sensore di continuo. Lo sketch per ESP32 qui sotto usa la libreria Adafruit per far scattare INT quando la prossimità supera 150 e commuta il LED della scheda ogni volta che si avvicina una mano, come un interruttore della luce senza contatto.

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}

Il terzo parametro di setProximityInterruptThreshold() (4 di default) è la persistenza: indica quante letture consecutive devono superare la soglia prima che scatti l'interrupt e così filtra i disturbi momentanei. Se non chiami clearInterrupt(), INT resta a LOW e perdi l'avvicinamento successivo. Questa struttura è utilissima nei progetti a batteria: metti l'ESP32 in deep sleep e sveglialo dal pin INT con esp_sleep_enable_ext0_wakeup(GPIO_NUM_4, 0); la scheda si sveglia solo quando qualcuno avvicina la mano. GPIO 4 è un pin RTC, quindi è adatto a questo scopo.

APDS-9960 con il Raspberry Pi Pico (MicroPython)

Sul Raspberry Pi Pico puoi far funzionare l'APDS-9960 in MicroPython senza nessuna libreria, scrivendo direttamente nei suoi registri. Il codice qui sotto legge l'ID del chip, attiva la misura di colore e prossimità e stampa ogni 200 ms i quattro canali di colore e il valore di prossimità. Il collegamento usa il bus I2C0: SDA a GP4, SCL a GP5 e VCC al pin 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)

Ecco cosa fanno i registri del codice: 0x80 (ENABLE) sceglie quali blocchi sono attivi, 0x81 (ATIME) imposta il tempo di integrazione del colore (2,78 ms per passo), 0x8F (CONTROL) definisce la corrente del LED IR e i guadagni, 0x93 (STATUS) dice se i dati sono pronti, 0x94–0x9B contengono i canali di colore e 0x9C il valore di prossimità. Per i gesti dovresti leggere la FIFO e scrivere un algoritmo di direzione come quello di SparkFun, che è un lavoro più lungo. Se preferisci l'Arduino IDE, installa sul Pico il core arduino-pico e usa la libreria SparkFun così com'è; i pin I2C predefiniti sono anche lì GP4 e GP5.

Limiti di portata e uso corretto

L'APDS-9960 è nato come sensore per telefoni e la sua portata è breve. In pratica i gesti sono affidabili tra 5 e 15 cm e arrivano al massimo a 20 cm. La prossimità dà valori utili fino a una distanza simile. A fissare questo limite sono la potenza del LED IR e quanta luce riflette la tua mano; portare la corrente del LED a 100 mA e il guadagno al massimo aggiunge un po' di portata, ma anche più rumore.

FattoreEffettoCosa fare
DistanzaOltre 15 cm i gesti scompaionoPassa la mano a 5–10 cm
Velocità del movimentoI passaggi molto lenti o molto veloci non vengono rilevatiUn movimento fluido di mezzo secondo
Luce del soleL'IR del sole satura i fotodiodiUsalo all'ombra o al chiuso
Vetro o coperchio trasparenteIl coperchio rimanda indietro l'IR e la prossimità risulta sempre altaTogli il coperchio o usa un materiale sottile che lasci passare l'IR
Colore della superficieUn guanto nero riflette menoAumenta il guadagno
Orientamento del sensoreLe direzioni ruotanoScambia i casi delle direzioni nel codice

Idee di progetti con l'APDS-9960

  • Lampada senza contatto: Accendi e spegni un modulo relè con l'interrupt di prossimità; comodissimo in cucina quando hai le mani sporche.
  • Lampada colorata a gesti: Scorri i colori di un LED RGB o di una striscia WS2812B con i gesti a destra e a sinistra.
  • Menu a mezz'aria: Scegli le voci di un menu su un display OLED con i gesti su e giù e conferma con NEAR.
  • Coperchio con servo a gesti: Apri il coperchio di una scatola con un gesto e un servomotore.
  • Luminosità automatica del display: Adatta uno schermo o una striscia LED alla luce ambiente; rispetto a un LDR ottieni una lettura più stabile e con l'informazione del colore.
  • Selezionatrice di colori: Separa caramelle o mattoncini colorati che scendono da uno scivolo in base ai canali di colore.

Errori comuni e soluzioni

SintomoCausa probabileSoluzione
"APDS-9960 bulunamadi" (non trovato)Errore di cablaggio, niente 3,3 V o ID del chip diversoCerca 0x39 con uno scanner I2C, leggi l'ID
Modulo trovato ma init fallisceChip clone con un ID diverso come 0xA8Aggiungi quel valore al controllo dell'ID nella libreria
Nessun gesto rilevatoMano troppo lontana o troppo lenta, VL non alimentatoPassa a 5–10 cm in mezzo secondo, controlla il ponticello PS
Direzioni invertite o confuseOrientamento di montaggio del sensoreScambia i casi DIR nel codice
Prossimità sempre altaVetro, coperchio o una superficie vicina davantiTogli il coperchio, abbassa il guadagno
Non funziona all'apertoLa luce del sole copre l'IRUsalo all'ombra
Blocchi casuali sulla UnoIncompatibilità I2C tra 5 V e 3,3 V, cavi lunghiConvertitore di livello e cavi corti
INT resta a LOWInterrupt non azzeratoChiama clearInterrupt() dopo la lettura
Se hai problemi, controlla prima con uno sketch scanner I2C che compaia l'indirizzo 0x39, poi esegui il codice semplice che legge solo la prossimità. Se il valore sale da 0 a oltre 200 avvicinando la mano, l'hardware è a posto e il problema sta nelle impostazioni dei gesti o nel movimento della mano.

Con un solo piccolo modulo, l'APDS-9960 aggiunge al tuo progetto controllo senza contatto, rilevamento di prossimità e misura del colore. Se tieni a mente la portata breve e la regola dei 3,3 V, diventa un elemento di interfaccia affidabile. Nell'app BlueGrays trovi progetti con LED RGB, misura della luce con LDR, sensore di movimento e misura della distanza, con schema elettrico e codice passo dopo passo, a cui puoi aggiungere l'APDS-9960 per crearne versioni senza contatto.

Domande frequenti

L'APDS-9960 funziona a 5 V?

No, il chip APDS-9960 lavora tra 2,4 e 3,6 V e i 5 V possono danneggiarlo. Alimenta il modulo dal pin 3.3V di Arduino Uno e, se puoi, metti un convertitore di livello sulle linee SDA e SCL. Solo le versioni speciali che dichiarano chiaramente regolatore e convertitore di livello integrati possono essere usate a 5 V.

Qual è l'indirizzo I2C dell'APDS-9960?

L'indirizzo I2C dell'APDS-9960 è 0x39 e non si può cambiare. Per questo non puoi collegare due APDS-9960 allo stesso bus I2C; se ti servono due sensori, usa un multiplexer I2C come il TCA9548A oppure il secondo bus I2C di ESP32 o Pico.

Da quanti centimetri l'APDS-9960 rileva i gesti?

In pratica i gesti vengono rilevati in modo affidabile tra 5 e 15 cm e in buone condizioni fino a 20 cm. La portata dipende da quanta luce riflette la mano, dalla corrente del LED IR e dal guadagno. La luce del sole e un vetro davanti al sensore riducono sensibilmente la portata.

Il pin INT dell'APDS-9960 va collegato per forza?

No. Le librerie possono leggere gesti e prossimità anche interrogando il sensore via I2C; in SparkFun lo fa enableGestureSensor(false). Il pin INT però segnala l'evento subito, senza interrogazioni continue, alleggerisce il processore e può svegliare un ESP32 dal deep sleep.

Quanto è preciso l'APDS-9960 nel misurare i colori?

L'APDS-9960 misura i canali di colore con una risoluzione di 16 bit, ma fornisce valori grezzi che dipendono dalla luce ambiente invece di colori assoluti. Se avvicini l'oggetto e copri la luce esterna, distingue senza problemi carte rosse, verdi e blu. Per una distinzione più fine sono più adatti i sensori dedicati al colore come il TCS34725 o il TCS3200.

Perché l'APDS-9960 dà l'errore init failed?

Questo errore indica che la libreria non è riuscita a leggere l'ID del sensore o non ha trovato il valore atteso. Controlla il cablaggio, l'alimentazione a 3,3 V e che SDA e SCL non siano invertiti, poi cerca l'indirizzo 0x39 con uno scanner I2C. Se l'indirizzo compare, il chip potrebbe essere un clone; leggi il valore nel registro ID e aggiungilo all'elenco accettato dalla libreria.

Vedi tutti i progetti
Misurare l'intensità luminosa con LDR
AR-11Principiante

Misurare l'intensità luminosa con LDR

Vuoi vedere quanto è luminosa la tua stanza sotto forma di numero? L'LDR, un piccolo componente sensibile alla luce, misura la luce ambiente e l'Arduino scrive il valore sullo schermo del computer…

4.6(83)
143
Utilizzo dei LED RGB
AR-39Principiante
Premium

Utilizzo dei LED RGB

Dentro un solo LED si nascondono tre colori: il LED RGB si accende rosso, poi verde, poi blu, ogni colore acceso per mezzo secondo e spento per mezzo secondo, e poi il giro ricomincia.

4.9(73)
100
Transizione cromatica omogenea con LED RGB
AR-40Principiante
Premium

Transizione cromatica omogenea con LED RGB

Un solo LED RGB passa lentamente dal rosso al verde, dal verde al blu e torna al rosso, in un giro di arcobaleno che non si ferma mai.

4.8(58)
78
Rilevatore di movimento con sensore di movimento
AR-24Principiante
Premium

Rilevatore di movimento con sensore di movimento

Un semplice guardiano che ti avvisa quando qualcuno entra nella stanza. Il sensore di movimento percepisce il calore emesso dal corpo umano, e l'Arduino tiene acceso il LED finché c'è movimento e lo…

4.6(47)
67
Campanello e luce con sensore di movimento
AR-25Intermedio
Premium

Campanello e luce con sensore di movimento

Quando qualcuno si avvicina alla tua porta, lo sai prima ancora che suoni. Appena il sensore di movimento rileva qualcuno, il LED si accende e il buzzer suona un campanello di tre note, dalla più…

4.7(54)
72
Lettura della riflessione (prossimità) con TCRT5000
AR-77Intermedio
Premium

Lettura della riflessione (prossimità) con TCRT5000

Con un piccolo sensore che manda luce invisibile e misura quanta ne torna indietro, rilevi la superficie che ha davanti.

4.6(33)
43
Controllo LED RGB ESP32
ES-9Principiante

Controllo LED RGB ESP32

Generazione illimitata di colori con un singolo LED RGB invece di 3 LED separati. La transizione arcobaleno avviene impostando i valori R/G/B con analogWrite() come in Arduino. La teoria dei colori (come rosso+verde=giallo) viene vista in pratica.

4.6(29)
52
Illuminazione Intelligente ESP32 (PIR + LDR + Relè + OLED)
ES-37Avanzato
Premium

Illuminazione Intelligente ESP32 (PIR + LDR + Relè + OLED)

Con un ESP32, un sensore di movimento PIR, un sensore di luce LDR e un modulo relè trasformiamo il corridoio, il bagno o la dispensa di casa in un'illuminazione smart. Se l'ambiente è già luminoso, la luce non si accende nemmeno con il movimento, così di giorno non spreca energia. La luce resta accesa 30 secondi e il tempo si allunga in automatico finché il movimento continua.

4.3(6)
11