简介：这份代码是 STK3310 距离传感器的完整可移植驱动，基于 MTK 平台实测可用，通过 GPIO 模拟 I2C 与传感器通信，面向嵌入式驱动工程师、移动设备 BSP 开发者，以及想掌握 I2C 时序和传感器驱动框架的读者。资源共包含 4 个文件，由 2 个 C 源文件和 2 个头文件组成，压缩包仅 6KB，典型的核心驱动骨架，可直接加入内核或用户态驱动框架中使用。驱动实现覆盖 GPIO 引脚电平模拟 I2C 协议、传感器 ID 识别、寄存器配置、接近距离读取、错误处理与上层 API 封装，附加设备树或板级配置思路可作为参考。代码量精简但结构清晰，适合在手机/平板等移动设备上实现屏幕自动亮度、通话自动熄屏等接近检测功能，也能帮助理解传感器驱动在嵌入式 Linux 下的完整工作流程。已有 1247 人学习下载，对于需要快速移植或学习 STK3310 驱动的开发者来说，是一份可靠的实战参考资料。
1. 距离传感器 STK3310 的驱动开发，从一块很小的芯片说起
手机贴近耳朵时屏幕会熄灭，这个动作背后就是距离传感器的功劳。STK3310 就是这样一颗集成了接近检测和环境光感应的芯片，封装小、功耗低、走 I2C 接口，在很多便携设备和 IoT 项目里都能看到它的身影。但芯片本身只是硬件，真正让它“听话”的是驱动——初始化寄存器、配置中断、读取数据、上报给系统，每一步都是实打实的代码活儿。这篇笔记我会从芯片工作原理讲起，给出一套可复现的 Linux 驱动骨架，再重点拆解阈值标定、中断配置和调试过程中最容易翻车的几个环节。适合正在写外设驱动的嵌入式开发者，也适合做低功耗设备但被传感器折腾过的硬件转软工程师。
2. STK3310 的驱动对象：I2C 时序、寄存器映射与中断链路
2.1 接近检测的工作原理：红外反射不是玄学
STK3310 内部有一颗红外 LED 和一个光敏接收管。LED 发射红外光，光线碰到障碍物后反射回来，被接收管捕捉并转换成 ADC 值。物体越近，反射光越强，ADC 原始值就越大。驱动要做的核心事只有一件：持续读这个 ADC 值，或者让芯片在 ADC 值跨过阈值时主动通知你。
这里有个容易误解的点：它测的是“红外反射强度”，不是“距离”。所以同一颗芯片，装在黑色外壳和白色外壳后面，读出来的原始值会差很多。驱动的职责不是把 ADC 值换算成厘米，而是把“反射强度超过某个阈值”翻译成“有物体接近”这个事件。理解了这一点，后面调阈值时就不会被“为什么数值不稳定”带偏。
环境光感应是另一条独立的数据通道。它测的是可见光强度，通常用来做屏幕亮度调节。在驱动里，这两个通道共用 I2C 接口但走不同的寄存器。调试时也建议分开验证：先确认环境光数据在变化，再去看接近检测，这样能快速定位是芯片没工作还是逻辑写错了。
2.2 I2C 读写的最小实现：先让芯片开口说话
STK3310 从驱动视角看就是一个 I2C 从设备，所有控制都通过寄存器读写完成。写驱动之前，先用一个最小的探测程序确认芯片在总线上有响应，这步能省掉后面大量排查时间。常见的 I2C 地址是 0x48（7 位地址），具体以你的板级配置为准。
#include <linux/i2c.h> #include <linux/i2c-dev.h> #include <stdio.h> #include <fcntl.h> #include <sys/ioctl.h> int main(void) { int fd = open("/dev/i2c-1", O_RDWR); if (fd < 0) { perror("open /dev/i2c-1"); return -1; } /* 0x48 是 7 位 I2C 地址，左移一位变成 8 位地址 */ if (ioctl(fd, I2C_SLAVE, 0x48) < 0) { perror("ioctl I2C_SLAVE"); return -1; } /* 读取产品 ID 寄存器，很多传感器会把 ID 放在 0x00 */ unsigned char reg = 0x00; unsigned char id = 0; if (write(fd, ®, 1) != 1) { perror("write reg"); return -1; } if (read(fd, &id, 1) != 1) { perror("read id"); return -1; } printf("chip id: 0x%02x\n", id); close(fd); return 0; }这段代码的逻辑是：打开 I2C 总线设备节点，把从机地址设置成目标芯片，然后先写寄存器地址再读数据。读回来的 ID 值需要和芯片手册里的值比对，能匹配上就说明硬件连接、I2C 地址、供电都没问题。
参数说明里有几个点值得注意。/dev/i2c-1是 I2C 控制器对应的设备节点，不同平台可能叫i2c-0或i2c-3，得用i2cdetect -l确认。I2C_SLAVE这个 ioctl 设置的是 7 位地址，内核会在传输时自动完成左移一位的转换。如果这里返回错误，先查总线号对不对，再查设备树里 i2c 节点是否使能。
2.3 驱动必读的几类寄存器：不是所有寄存器都要碰
STK3310 内部寄存器不少，但驱动真正需要操作的没那么复杂。按照功能划分，大致是四类：芯片信息类、工作模式类、数据输出类、中断控制类。芯片信息类包括产品 ID 和版本号，在 probe 阶段读一次用来确认设备身份。工作模式类控制芯片处于待机还是测量状态，以及测量周期多长。数据输出类放着 ADC 原始值和转换结果。中断控制类设置阈值、迟滞范围和中断使能。
我建议把寄存器操作封装成一组宏或者内联函数，而不是在代码里到处写裸的i2c_smbus_read/ write。原因有两个：一是可读性，二是方便调试。芯片手册里的寄存器地址是十六进制数字，直接散落在业务代码里，过两个月回头看根本不知道0x0d是干什么的。封装成PS_THRESHOLD_REG这样的宏，代码本身就变成了一部分文档。
| 寄存器类别 | 典型字段 | 驱动中的用途 |
|---|---|---|
| 芯片信息 | 产品 ID、版本号 | probe 阶段校验设备身份 |
| 工作模式 | 测量周期、待机/激活 | 低功耗切换、采样频率控制 |
| 数据输出 | PS ADC、ALS ADC | 上层应用读取原始数据 |
| 中断控制 | 阈值、迟滞、使能位 | 接近事件的主动上报 |
很多芯片还有“中断标志”寄存器。这个寄存器在中断触发后需要软件清掉，否则中断引脚会一直拉低，表现为“中断风暴”——中断处理函数不停被调用，但读到的数据根本没变化。这是驱动开发里最常见的翻车现场之一，后面避坑章节会单独讲。
2.4 中断上报和轮询怎么选：低功耗设备的必答题
STK3310 驱动在事件上报方式上有两条路：轮询和中断。轮询就是驱动定时去读 PS ADC 值，自己判断有没有超过阈值；中断是芯片自己比较阈值，超过时拉低中断引脚通知主控。从功耗角度看，中断方式明显更优——主控可以在大部分时间睡大觉，只有物体靠近时才被唤醒。轮询则要求主控周期性醒来，哪怕没有事件也要做一次 I2C 读操作，换来的是逻辑简单和调试直观。
我的习惯是：只要项目对功耗有要求，就选中断方式。具体到驱动代码，probe 阶段申请 GPIO 中断，在中断处理函数里读一次 PS 数据和中断标志，做基础过滤后上报事件，然后清中断标志。因为 I2C 操作可能睡眠，真正的读取逻辑放在线程化中断里做，而不是在 hardirq 上下文中直接处理。
有个容易被忽略的问题：芯片的中断引脚通常是开漏输出，这意味着驱动板上的上拉电阻必须存在，而且中断引脚不能随便接在某个没有配置成输入的 GPIO 上。设备树里interrupt-parent和interrupts属性要正确声明，否则中断号拿不到，probe 直接失败。
3. 从零搭一个 STK3310 驱动：最小组件的代码骨架
3.1 驱动框架选择：i2c_driver 是标准答案
在 Linux 内核里挂一个 I2C 设备驱动，标准做法是注册一个i2c_driver结构体。它负责描述这个驱动支持哪些设备、在设备匹配时做什么初始化、在设备移除时做什么清理。STK3310 这类小传感器非常适合这个模型——设备树里配好节点，内核在启动时自动完成匹配和 probe，驱动代码不需要关心设备是怎么被发现的。
#include <linux/i2c.h> #include <linux/module.h> #include <linux/interrupt.h> #include <linux/input.h> #define STK3310_DRV_NAME "stk3310" #define STK3310_REG_ID 0x00 #define STK3310_REG_PS_DATA 0x04 #define STK3310_REG_PS_THR 0x0d #define STK3310_REG_INT_FLAG 0x11 static irqreturn_t stk3310_irq_handler(int irq, void *dev_id) { struct i2c_client *client = dev_id; u8 flag; u16 ps_data; /* 先读中断标志，确认是 PS 事件还是 ALS 事件 */ flag = i2c_smbus_read_byte_data(client, STK3310_REG_INT_FLAG); ps_data = i2c_smbus_read_word_data(client, STK3310_REG_PS_DATA); ps_data = le16_to_cpu(ps_data); /* 正常工作后这里应该上报 input 事件，稍后展开 */ dev_info(&client->dev, "ps interrupt, flag=0x%02x data=%u\n", flag, ps_data); /* 清中断标志，否则中断引脚会一直保持低电平 */ i2c_smbus_write_byte_data(client, STK3310_REG_INT_FLAG, 0x00); return IRQ_HANDLED; } static int stk3310_probe(struct i2c_client *client) { if (!i2c_check_functionality(client->adapter, I2C_FUNC_SMBUS_BYTE_DATA | I2C_FUNC_SMBUS_WORD_DATA)) return -EIO; /* 读取产品 ID 确认设备身份 */ u8 id = i2c_smbus_read_byte_data(client, STK3310_REG_ID); if (id != 0x40) { dev_err(&client->dev, "unexpected chip id 0x%02x\n", id); return -ENODEV; } if (client->irq > 0) { int ret = request_threaded_irq(client->irq, NULL, stk3310_irq_handler, IRQF_TRIGGER_FALLING | IRQF_ONESHOT, STK3310_DRV_NAME, client); if (ret) { dev_err(&client->dev, "failed to request irq %d\n", client->irq); return ret; } } return 0; } static void stk3310_remove(struct i2c_client *client) { if (client->irq > 0) free_irq(client->irq, client); } static const struct i2c_device_id stk3310_id[] = { { STK3310_DRV_NAME, 0 }, { } }; MODULE_DEVICE_TABLE(i2c, stk3310_id); static struct i2c_driver stk3310_driver = { .driver = { .name = STK3310_DRV_NAME, .of_match_table = stk3310_of_match, }, .probe = stk3310_probe, .remove = stk3310_remove, .id_table = stk3310_id, }; module_i2c_driver(stk3310_driver); MODULE_LICENSE("GPL");代码逻辑分三段。第一段是中断处理函数，读标志和数据的顺序不能反——先读标志确认事件来源，再读数据避免读到一个正在更新的中间值。清标志放在最后，且必须执行，否则中断会被不断触发。第二段是 probe 函数，核心动作是校验 ID、申请中断。第三段是驱动注册骨架，of_match_table负责和设备树对接。
参数说明里有个细节值得单独讲：IRQF_ONESHOT。这个标志会让内核在中断处理函数执行期间屏蔽同一条中断线，对线程化中断尤其重要。如果不加，中断处理还在读 I2C，新的中断又来了，处理函数会被重入，最终把状态搞乱。
3.2 事件上报：input 子系统和 IIO 两条路怎么选
STK3310 测到物体接近后，驱动要把这个信息告诉上层。Linux 里有两个常见出口：input 子系统和 IIO 框架。input 适合按键类事件，比如“物体靠近”映射成一个键值，使用input_report_key上报；IIO 适合传感器类数据，比如暴露一个proximity通道，用户态通过iio_info读原始值。
我的选择标准很简单：如果产品只是用接近检测做屏幕熄灭或唤醒，就用 input，上报KEY_FAVORITES或自定义事件，上层直接用标准输入事件接口监听；如果产品还需要原始 ADC 值做标定或调试，就优先 IIO，把 raw 值暴露出来。两个都做也不是不行，但至少要有一个走得通，否则没法验证驱动。
下面是对应 input 方式的完整上报代码：
static void stk3310_report_ps_event(struct input_dev *input, bool near) { /* 上报接近状态，0 表示远离，1 表示靠近 */ input_report_key(input, KEY_FAVORITES, near ? 1 : 0); input_sync(input); }这段代码简短，但背后的约束是：input 设备必须在 probe 阶段创建好并注册到内核。input_report_key只负责把事件挂到缓冲区，input_sync负责通知用户态读取。如果漏掉input_sync，事件会一直留在缓冲区里不出去，表现为上层怎么等都等不到数据。
3.3 设备树配置：驱动跑不起来先查这个
设备树是硬件描述和驱动之间的桥梁。STK3310 的节点通常会放在某个 I2C 控制器的子节点里，包含地址、中断 GPIO、供电标志等信息。我见过不少项目，驱动代码明明没问题，但设备树里中断引脚配错了，结果 probe 阶段 IRQ 申请失败，整个驱动加载不起来。
&i2c1 { stk3310@48 { compatible = "vendor,stk3310"; reg = <0x48>; interrupt-parent = <&gpio1>; interrupts = <13 IRQ_TYPE_EDGE_FALLING>; }; };这段设备树声明了一个地址为 0x48 的 I2C 设备，中断引脚接在 gpio1 的第 13 脚，下降沿触发。compatible字符串必须和驱动里of_match_table定义的值一致，大小写和标点都不能错。reg是 I2C 从机地址，必须和芯片实际地址对得上，否则内核永远找不到这个设备。
需要特别提醒的是IRQ_TYPE_EDGE_FALLING。STK3310 的中断是在事件发生时引脚从高电平跳变到低电平，所以下降沿触发是符合芯片逻辑的。如果配成水平触发，中断处理函数会反复被调用，直到你把它标志清掉——逻辑上也能跑，但容易浪费 CPU。
4. 让接近检测“测得准”：三个非调不可的寄存器参数
4.1 PS 中断阈值：过高误判，过低漏报的平衡点
距离传感器驱动调参，第一刀永远砍在 PS 阈值上。这个阈值决定了“多大反射强度算作物体靠近”。设得太高，物体已经贴到外壳上了还不触发；设得太低，手指离屏幕两厘米就触发，把正常使用场景全打乱了。
阈值标定没有公式可套，必须靠实测数据。做法是：先驱动读出无遮挡时的 PS ADC 值，再把物体放到触发距离，读第二个值。阈值通常取两个值的中间偏上位置，留出环境波动空间。阈值写进芯片后，还可以通过读中断标志反推芯片内部判决逻辑是否跑通。
| 场景 | 无遮挡典型值 | 贴脸触发值 | 推荐阈值 |
|---|---|---|---|
| 白色外壳高透窗 | 5 - 20 | 300 - 600 | 150 - 250 |
| 黑色外壳小开孔 | 2 - 8 | 200 - 400 | 100 - 200 |
| 隔深色玻璃 | 10 - 50 | 100 - 250 | 60 - 120 |
注意表格里的数值是区间不是精确值，因为每个项目的外壳材质、开孔大小、LED 驱动电流都不同。这也是为什么驱动里阈值不能写死，应该通过 sysfs 或模块参数暴露给调试者。
4.2 LED 电流档位：距离传感器的“灵敏度旋钮”
反射强度不等于物体距离，它和 LED 发射功率强相关。LED 电流越大，红外光越强，能触发的距离越远，但代价是功耗上升，还可能造成接收管饱和。反过来，电流太小，短距离也触发不了。这个参数在驱动里通常对应一个 2 到 3 位的控制字段。
我在实际项目中总结的经验是：先默认用最低档，标定完如果触发距离不够，再逐步调大，直到找到一个“刚好能满足产品最小触发距离”的档位。不要一上来就往最大调，因为功耗翻倍的同时，温漂和外界红外干扰也会变大。具体档位和对应电流值要看芯片手册，驱动只负责把档位写进正确的寄存器位。
调试这个参数时重点关注一个现象：物体还没靠近，PS ADC 值就已经很高。这通常说明 LED 电流过大，接收管被环境红外光干扰了。此时优先调小电流档，而不是去改阈值。
4.3 迟滞窗口：防止边界值反复抖动
物体停在阈值附近时，反射强度的微小波动会导致频繁触发和释放，表现就是设备反复锁屏解锁、屏幕不停亮灭。解决这个问题靠迟滞：触发阈值设一个值，释放阈值设一个更小的值，中间留出一个不动作的窗口。
STK3310 的迟滞机制一般是在靠近阈值之外加一个释放偏移量。驱动的写法是：确认“已靠近”状态后，只有当 PS 值回落到“触发阈值 - 迟滞量”以下，才解除靠近状态。迟滞量不能太大，否则手移开很久屏幕才亮起来，体验很差；也不能太小，否则起不到防抖作用。
一个实用的工程做法是：在驱动里维护一个last_state变量，每次读到的 ADC 值先做判断再决定是否上报状态变化，而不是每次都上报。这样即使芯片没有硬件迟滞，驱动层面也能兜底。标定迟滞量时，可以用脚本连续采样，观察物体慢慢远离时的 ADC 值轨迹，取一个比轨迹噪声大两到三倍的偏移量。
5. STK3310 调试避坑：五个把驱动搞崩的经典现场
5.1 probe 失败，I2C 探测能读到设备但 ID 校验不过
现象：驱动加载时打印unexpected chip id，但用 i2cdetect 能看到 0x48 地址有设备响应。
原因：芯片的 I2C 地址和厂商默认地址不完全一致。有些硬件设计会把地址引脚拉高拉低，改掉默认地址；还有一部分原因是芯片处于待机模式，寄存器读接口只回了默认值。
解决：先把“校验 ID”这一步的读值打印出来，和芯片手册的 ID 表对比。如果读到的值和手册完全对不上，检查芯片供电是不是稳定、I2C 上拉电阻是否偏小，也检查是不是用错了总线。如果只是多个地址跳变，确认硬件地址引脚后改设备树里的reg字段就行。
5.2 中断风暴：中断触发后系统 CPU 占用居高不下
现象：驱动加载后 CPU 使用率飙升，但功能看起来没异常；用cat /proc/interrupts看到中断次数在疯涨。
原因：芯片的中断标志寄存器没有被清除。中断引脚是电平信号，标志位不清，芯片就一直拉低，内核认为中断持续发生。
解决：确认中断处理函数里清标志的代码真的执行了。常见坑是 I2C 写失败被忽略，或者清错了寄存器。我在项目中加了一行dev_dbg打印，每次中断输出当前标志值，一眼就看到写入没有生效。另外确认清标志和读数据用同一个 client，不要混用。
5.3 接近值漂移：环境光一强，误触发不断
现象：室内测试正常，拿到室外阳光下测试，设备频繁触发接近事件，屏幕一直处于熄灭状态。
原因：芯片的红外接收管对近红外波段的光有一定的响应，阳光里恰好含有大量近红外成分。弱光环境下反射信号占主导，太阳直射时环境红外直接压过反射信号。
解决：驱动把 ALS 数据纳进来做一个简单的联合判决——环境光强度超过某个上限时，PS 阈值整体抬高，或者直接忽略这次触发。更彻底的办法是在硬件上给接收管加遮光片，但驱动里做软过滤成本更低，而且能覆盖多数室内外切换场景。
5.4 低功耗模式进入后，靠近检测完全失效
现象：系统休眠后，STM 或应用处理器进入低功耗状态，本应能在物体靠近时唤醒，但设备完全没反应。
原因：很多芯片在待机模式下 LED 是不工作的，接近检测功能被整体关闭。驱动如果只是简单地把芯片设为待机，等于把检测能力也关了。
解决：查阅芯片手册确认有没有“低功耗接近检测模式”，这个模式下芯片会周期性打开 LED 和接收管做检测，只在触发时才通过中断引脚唤醒主控。驱动在进入 suspend 前要切换到这种模式，而不是直接关掉芯片电源。同时确认中断引脚配置的是“保持有效电平并唤醒系统”，否则中断只在系统醒着时有效。
5.5 I2C 传输失败率高：总线偶尔 NACK，影响数据连续性
现象：长时间跑下来，日志里频繁出现i2c transfer error，数据偶尔丢一个点。
原因：距离传感器的 I2C 速率可能超出了总线上其他设备能承受的范围，或者没有做总线错误恢复。STK3310 这类小传感器通常支持 400kHz 快速模式，但实际布线和上拉电阻质量差一些就容易出错。
解决：先把 I2C 速率降回 100kHz 验证是否稳定。如果降速后问题消失，说明是总线速度问题。驱动里建议对每次 SMBus 读写做次数受限的重试，遇到-ETIMEDOUT或-ENACK时重新发起传输，而不是直接把错误抛给上层。重试之间加一个 1ms 到 5ms 的延迟，防止连续抢总线造成更严重的拥塞。
6. 驱动开发期的自检习惯：把传感器数据搬进 sysfs 做回归
驱动写完后最痛苦的事情不是写代码，而是改了一版之后不知道有没有把旧功能改坏。距离传感器的行为依赖硬件环境和物理遮挡，不能像纯软件项目跑单元测试。我的做法是把原始数据和状态信息暴露到 sysfs，然后写一个简单的采样脚本做回归比对。
核心思路是：在驱动里加一组 sysfs 属性文件，分别暴露 PS ADC 值、ALS ADC 值、当前阈值和触发状态。这样不需要依赖上层应用，直接通过命令行就能验证驱动行为。代码大致是这个思路：
static ssize_t ps_raw_show(struct device *dev, struct device_attribute *attr, char *buf) { struct i2c_client *client = to_i2c_client(dev); u16 val = i2c_smbus_read_word_data(client, STK3310_REG_PS_DATA); val = le16_to_cpu(val); return sprintf(buf, "%u\n", val); } static DEVICE_ATTR_RO(ps_raw);这个属性的作用是：用户态读这个文件时，驱动实时发起一次 I2C 读取并返回当前 PS ADC 值。配合脚本做 100 次采样，可以画出波形、算出噪声范围，快速判断阈值设置是否合理。调试完可以把这个属性去掉，但如果项目还在迭代期，留着反而方便。
验证一个驱动改动是否引入回归，我会固定三个数据点：无遮挡时的平均值、贴实时的最大值、触发到释放的延迟时间。任何一版提交前先跑一遍这三个指标，和基线对比，偏差超过 20% 就直接定位是阈值变了还是芯片工作模式变了。
另外一个很实用的技巧是写一个自动标定脚本：用手反复遮挡和移开传感器，脚本记录两个状态下的 ADC 分布，输出建议阈值区间。这样做的好处是，每次拿到新壳子或更换了外壳颜色，不需要重新读手册、改代码，跑一遍脚本就能拿到经验值。标定脚本和驱动代码放在同一个仓库里，顺手也解决了一部分测试文档缺失的问题。
希望这套方法能帮你少走几周弯路。我自己第一次调距离传感器时，不懂红外反射原理，傻傻地拿 ADC 值反推距离，折腾了好几天才发现方向就错了。后来老老实实读手册、做标定、暴露 sysfs，才把“玄学”变成了“可复现的工程问题”。驱动开发最值钱的经验往往不是代码本身，而是那些踩过坑之后沉淀下来的检查清单——希望这篇能成为你清单的第一行。
本文还有配套的精品资源，点击获取
