APDS-9960接Arduino:手势接近光照四合一教程

2026-11-18 13:21:27 26阅读

隔空挥手控制设备,听起来像科幻片,实际成本比想象中低。官方教程开头举的例子相当直白:有厂商拿这类技术做了个无接触马桶,手在上方一挥就冲水。一颗 APDS-9960 芯片把四套测量塞进了不到一平方厘米的封装:环境光、红绿蓝加透明通道的颜色读数、接近检测、手势识别,全部走 I2C 总线。SparkFun 给它做了块红色扩展板(货号 SEN-12787),把六个引脚引出来,接 Arduino 就能跑通。官方这条 hookup guide 写得很扎实,下面按它的路子把整条链路走一遍。

先说结论:这块板最要命的不是代码,是电压。3.3V,不是 5V,这一条记不住后面全白搭。

APDS-9960手势传感器扩展板

六个引脚和两根跳线,先认全再动手

扩展板把芯片的六个引脚全部引出,官方页面对每个引脚的用途和电压范围都有明确说明:

引脚用途电压要求
VL给红外 LED 供电的可选引脚,PS 跳线断开时才需要接3.0-4.5V
GND接地无
VCC传感器主供电2.4-3.6V
SDAI2C 数据线无
SCLI2C 时钟线无
INT外部中断输出,中断事件发生时拉低无

板子正面还有两个锡焊跳线。PS 跳线默认闭合,把传感器和红外 LED 的供电连在一起,只给 VCC 供电就能同时喂饱两者;只有把它焊开,VL 引脚才派上用场。I2C PU 是三段式跳线,默认闭合,SDA 和 SCL 上已经挂了板载上拉电阻。如果总线上别处已经有上拉,用吸锡线把这个跳线焊开,两个上拉并联会让 I2C 波形变差。

接线:3.3V 是死规矩

官方教程用 3.3V 的 Arduino Pro 做演示,接线一共五根,VL 悬空不接:

APDS-9960 扩展板Arduino Pro 3.3V
VCCVCC(3.3V)
GNDGND
SDAA4
SCLA5
INTD2

还有个前置步骤别漏了:Arduino Pro 本身不带 USB 口,烧程序要用 3.3V 的 FTDI 扩展板,USB mini 线连电脑,第一次用还得装 FTDI 驱动。接线时留意板上 3.3V/5V 选择开关的位置,务必拨在 3.3V 挡。

官方文档的原话是:5V 供电或 5V 电平的 I2C 通信都可能直接损坏芯片。手上只有 Uno、RedBoard 这类 5V 板也不是不能玩,但必须加双向电平转换器,VCC、SDA、SCL 一起转。板子出厂不带排针,先焊一排公排针,面包板上插着接最省事。

APDS-9960与Arduino Pro接线图

装库、跑官方手势示例

官方还建议开工前把 I2C 和面包板这两块基础过一遍,APDS-9960 的通信协议和接线根基都是它们,不熟的话后面排查问题会抓瞎。代码不用自己写。SparkFun 把库放在 GitHub 的 APDS-9960_RGB_and_Gesture_Sensor 仓库里,下载整个项目压缩包,解压后进 Libraries 目录,把 SparkFun_APDS9960 文件夹按 Arduino 标准装库流程放进 libraries 目录,重启 IDE 即可。

APDS-9960库解压目录

然后 File → Examples → SparkFun_APDS9960 → GestureTest,打开官方手势示例。烧录前确认串口和板型都选对,官方教程用的板型是 Arduino Pro or Pro Mini (3.3V, 8MHz) w/ ATmega328。GestureTest 完整代码如下,逐字符照抄或直接复制:

/****************************************************************
GestureTest.ino
APDS-9960 RGB and Gesture Sensor
Shawn Hymel @ SparkFun Electronics
May 30, 2014
https://github.com/sparkfun/APDS-9960_RGB_and_Gesture_Sensor

Tests the gesture sensing abilities of the APDS-9960. Configures
APDS-9960 over I2C and waits for gesture events. Calculates the
direction of the swipe (up, down, left, right) and displays it
on a serial console. 

To perform a NEAR gesture, hold your hand
far above the sensor and move it close to the sensor (within 2
inches). Hold your hand there for at least 1 second and move it
away.

To perform a FAR gesture, hold your hand within 2 inches of the
sensor for at least 1 second and then move it above (out of
range) of the sensor.

Hardware Connections:

IMPORTANT: The APDS-9960 can only accept 3.3V!

 Arduino Pin  APDS-9960 Board  Function

 3.3V         VCC              Power
 GND          GND              Ground
 A4           SDA              I2C Data
 A5           SCL              I2C Clock
 2            INT              Interrupt

Resources:
Include Wire.h and SparkFun_APDS-9960.h

Development environment specifics:
Written in Arduino 1.0.5
Tested with SparkFun Arduino Pro Mini 3.3V

This code is beerware; if you see me (or any other SparkFun 
employee) at the local, and you've found our code helpful, please
buy us a round!

Distributed as-is; no warranty is given.
****************************************************************/

#include "Wire.h"
#include "SparkFun_APDS9960.h"

// Pins
#define APDS9960_INT    2 // Needs to be an interrupt pin

// Constants

// Global Variables
SparkFun_APDS9960 apds = SparkFun_APDS9960();
int isr_flag = 0;

void setup() {

  // Initialize Serial port
  Serial.begin(9600);
  Serial.println();
  Serial.println(F("--------------------------------"));
  Serial.println(F("SparkFun APDS-9960 - GestureTest"));
  Serial.println(F("--------------------------------"));

  // Initialize interrupt service routine
  attachInterrupt(0, interruptRoutine, FALLING);

  // Initialize APDS-9960 (configure I2C and initial values)
  if ( apds.init() ) {
    Serial.println(F("APDS-9960 initialization complete"));
  } else {
    Serial.println(F("Something went wrong during APDS-9960 init!"));
  }

  // Start running the APDS-9960 gesture sensor engine
  if ( apds.enableGestureSensor(true) ) {
    Serial.println(F("Gesture sensor is now running"));
  } else {
    Serial.println(F("Something went wrong during gesture sensor init!"));
  }
}

void loop() {
  if( isr_flag == 1 ) {
    detachInterrupt(0);
    handleGesture();
    isr_flag = 0;
    attachInterrupt(0, interruptRoutine, FALLING);
  }
}

void interruptRoutine() {
  isr_flag = 1;
}

void handleGesture() {
    if ( apds.isGestureAvailable() ) {
    switch ( apds.readGesture() ) {
      case DIR_UP:
        Serial.println("UP");
        break;
      case DIR_DOWN:
        Serial.println("DOWN");
        break;
      case DIR_LEFT:
        Serial.println("LEFT");
        break;
      case DIR_RIGHT:
        Serial.println("RIGHT");
        break;
      case DIR_NEAR:
        Serial.println("NEAR");
        break;
      case DIR_FAR:
        Serial.println("FAR");
        break;
      default:
        Serial.println("NONE");
    }
  }
}

上传前在 Tools 菜单里选好串口,点 Upload 等烧录完成,再打开 Tools → Serial Monitor。波特率不用手改,示例里已经写死 9600。

setup 里初始化串口(9600),把 INT 配成下降沿中断,再调 apds.init() 和 enableGestureSensor(true);loop 里靠 isr_flag 标志位响应中断,有手势事件就进 handleGesture() 读方向。初始化成功时串口监视器会打出两行字:APDS-9960 initialization complete 和 Gesture sensor is now running。看不到这两行就先别急着挥手,回头查接线和电压。

手势怎么挥才认得出来

官方对挥法有明确要求:手保持在传感器上方 10 到 20 厘米,从侧面滑入、划过、再滑出,起始和结束都要在感应范围之外,滑动过程保持同一高度。滑太快识别不到,手一直停在感应区里也不行。方向对应关系如下表:

手势动作
UP从板子下方向上方滑出感应范围,收尾时手腕别留在感应区
DOWN从板子上方向下方滑出感应范围
LEFT从板子右侧向左侧滑出感应范围
RIGHT从板子左侧向右侧滑出感应范围

APDS-9960手势滑动方向示意

除了四个方向,还有 NEAR 和 FAR 两个动作。NEAR 是手从远处(25 厘米以上)慢慢移近到传感器正上方约 5 厘米处,悬停至少 1 秒再拿开;FAR 反过来,先在 5 厘米处悬停至少 1 秒,再往上移出感应范围。识别失败统一打印 NONE。

APDS-9960手势NEAR与FAR判定示意

手势之外:光照与接近读数,加一份踩坑清单

库里另外四个示例把剩下几套功能全覆盖了:AmbientLightInterrupt 演示环境光低于设定阈值时触发 Arduino 中断,把判断反过来改成变亮报警也行;ColorSensor 读环境光加红、绿、蓝四个通道的数值;ProximitySensor 不走中断,按固定间隔轮询接近数据,手靠近就能看到数值变化;ProximityInterrupt 在物体进入或离开设定距离范围时触发中断。这四个示例都在 File → Examples → SparkFun_APDS9960 菜单里,改改阈值就能当光控开关或者接近唤醒用。

最后把容易翻车的点集中列一遍:

  • 电压是第一坑,5V 板直连轻则读数异常重则烧芯片,要么用 3.3V 板,要么上电平转换。
  • INT 必须接,中断必须配。示例用的是数字脚 2 的下降沿,换引脚要把 attachInterrupt 一起改。
  • 挥太快、手停在场里、划入划出没离开感应范围,结果都是 NONE。手势的定义是进范围、划过、出范围。
  • I2C 总线上已经有上拉电阻时记得焊开 I2C PU 跳线,别让两组上拉并联。
  • 串口监视器里看不到初始化成功的两行提示,先查 FTDI 驱动和串口选择,再查供电电压,最后才是挥手姿势。

这块板在 SparkFun 商城里已经标了 Retired(2026 年 11 月查),但 APDS-9960 芯片本身在各创客店都能买到,兼容扩展板的引脚定义和这套库通用。四合一路线对做非接触开关、简易手势遥控这类项目依然够用:一颗芯片包办感知,主控专心干活。


作者:野生极客一枚
链接:https://www.aiddithome.com/p/aeeedf8162519.html
本作版权归作者所有,未经允许请勿转载。若存在违规行为,您可以点击 “举报”。


登录 后发表评论
4条评论
胶佬憨憨
1楼 · 2026-11-18 13:21:50

I2C PU 那个跳线提醒很到位,我上拉并联吃过亏,波形直接梯形了。

只看不说话
2楼 · 2026-11-18 13:21:50

Retired 还能买兼容板就行,库通用这点最省心。

线比代码多
3楼 · 2026-11-18 13:21:50

NEAR 和 FAR 的判定居然要悬停一秒,怪不得我以前乱挥全是 NONE,原来是姿势不对。

老张装机
4楼 · 2026-11-18 13:21:49

这块板我前年买过一块,就是这个 3.3V 的坑:当时手边只有 Uno,嫌麻烦直接怼上去,结果传感器发热读数乱跳,幸亏断电快。后来老老实实加了双向电平转换才正常。补充一个小经验:环境温度低的时候红外 LED 的手势识别距离会缩水,冬天手别贴太远挥,10 到 20 厘米这个官方范围其实已经比较极限了,新手建议先从 8 厘米左右练起。