VCNL36821S STM32 HAL 库核心开发代码可直接移植

发财树

以下代码基于 STM32F103 系列，采用 I2C 通信方式，实现 VCNL36821S 初始化、近距离（PS）/ 环境光（ALS）数据读取、中断配置等核心功能，注释清晰，可直接适配主流 STM32 平台。
一、头文件与宏定义（vcnl36821s.h）

1. <font face="宋体">#ifndef __VCNL36821S_H
   
2. #define __VCNL36821S_H
   
3. 
   
4. #include "stm32f1xx_hal.h"
   
5. 
   
6. // *************************** 硬件配置 ***************************
   
7. // VCNL36821S I2C地址（A0/A1接GND时为0x60，左移1位适配HAL库）
   
8. #define VCNL36821S_I2C_ADDR    0x60 << 1
   
9. // 绑定使用的I2C句柄（根据实际工程修改）
   
10. #define VCNL36821S_I2C_HANDLE  &hi2c1
    
11. 
    
12. // *************************** 寄存器地址 ***************************
    
13. #define VCNL36821S_ID_REG        0x00    // 设备ID寄存器（默认值0x11）
    
14. #define VCNL36821S_PS_CONF1_REG  0x03    // PS配置寄存器1
    
15. #define VCNL36821S_PS_CONF2_REG  0x04    // PS配置寄存器2
    
16. #define VCNL36821S_ALS_CONF_REG  0x06    // ALS配置寄存器
    
17. #define VCNL36821S_ALS_THDL_REG  0x08    // ALS下限阈值寄存器（低字节）
    
18. #define VCNL36821S_ALS_THDH_REG  0x09    // ALS上限阈值寄存器（低字节）
    
19. #define VCNL36821S_PS_THDL_REG   0x0A    // PS下限阈值寄存器
    
20. #define VCNL36821S_PS_THDH_REG   0x0B    // PS上限阈值寄存器
    
21. #define VCNL36821S_INT_CTRL_REG  0x0D    // 中断控制寄存器
    
22. #define VCNL36821S_ALS_DATA_REG  0x10    // ALS数据寄存器（低字节）
    
23. #define VCNL36821S_PS_DATA_REG   0x18    // PS数据寄存器
    
24. 
    
25. // *************************** 函数声明 ***************************
    
26. /**
    
27. * @brief  检测VCNL36821S设备ID，验证通信链路
    
28. * @retval 1-检测成功，0-检测失败
    
29. */
    
30. uint8_t VCNL36821S_CheckID(void);
    
31. 
    
32. /**
    
33. * @brief  初始化VCNL36821S：配置ALS/PS工作模式
    
34. * @note   默认配置：ALS高分辨率+50Hz工频抑制；PS中等发射功率+100ms检测周期
    
35. */
    
36. void VCNL36821S_Init(void);
    
37. 
    
38. /**
    
39. * @brief  读取环境光强度（ALS）
    
40. * @retval 光强值（lx）
    
41. */
    
42. float VCNL36821S_ReadALS(void);
    
43. 
    
44. /**
    
45. * @brief  读取近距离检测值（PS）
    
46. * @retval PS原始值（范围0~4095，数值越大距离越近）
    
47. */
    
48. uint16_t VCNL36821S_ReadPS(void);
    
49. 
    
50. /**
    
51. * @brief  配置PS/ALS中断阈值
    
52. * @param  als_thdl: ALS下限阈值（0~65535）
    
53. * @param  als_thdh: ALS上限阈值（0~65535）
    
54. * @param  ps_thdl:  PS下限阈值（0~4095）
    
55. * @param  ps_thdh:  PS上限阈值（0~4095）
    
56. */
    
57. void VCNL36821S_SetIntThreshold(uint16_t als_thdl, uint16_t als_thdh, uint16_t ps_thdl, uint16_t ps_thdh);
    
58. 
    
59. /**
    
60. * @brief  启用PS/ALS中断功能
    
61. * @param  ps_int_en: 1-启用PS中断，0-禁用
    
62. * @param  als_int_en:1-启用ALS中断，0-禁用
    
63. */
    
64. void VCNL36821S_EnableInt(uint8_t ps_int_en, uint8_t als_int_en);
    
65. 
    
66. #endif</font>

复制代码

二、核心功能实现（vcnl36821s.c）

1. <font face="宋体">#include "vcnl36821s.h"
   
2. 
   
3. /**
   
4. * @brief  I2C寄存器写函数（底层封装，方便移植）
   
5. * @param  reg_addr: 寄存器地址
   
6. * @param  data: 要写入的数据
   
7. * @retval HAL状态
   
8. */
   
9. static HAL_StatusTypeDef VCNL36821S_WriteReg(uint8_t reg_addr, uint8_t data)
   
10. {
    
11.     return HAL_I2C_Mem_Write(VCNL36821S_I2C_HANDLE, VCNL36821S_I2C_ADDR,
    
12.                              reg_addr, 1, &data, 1, 100);
    
13. }
    
14. 
    
15. /**
    
16. * @brief  I2C寄存器读函数（底层封装，方便移植）
    
17. * @param  reg_addr: 寄存器地址
    
18. * @param  data: 读取数据缓冲区
    
19. * @param  len: 读取长度
    
20. * @retval HAL状态
    
21. */
    
22. static HAL_StatusTypeDef VCNL36821S_ReadReg(uint8_t reg_addr, uint8_t *data, uint16_t len)
    
23. {
    
24.     return HAL_I2C_Mem_Read(VCNL36821S_I2C_HANDLE, VCNL36821S_I2C_ADDR,
    
25.                             reg_addr, 1, data, len, 100);
    
26. }
    
27. 
    
28. // 检测设备ID
    
29. uint8_t VCNL36821S_CheckID(void)
    
30. {
    
31.     uint8_t dev_id = 0;
    
32.     if(VCNL36821S_ReadReg(VCNL36821S_ID_REG, &dev_id, 1) != HAL_OK)
    
33.     {
    
34.         return 0;
    
35.     }
    
36.     // 验证威世VCNL36821S默认ID
    
37.     return (dev_id == 0x11) ? 1 : 0;
    
38. }
    
39. 
    
40. // 传感器初始化
    
41. void VCNL36821S_Init(void)
    
42. {
    
43.     // 通信失败直接退出
    
44.     if(!VCNL36821S_CheckID()) return;
    
45. 
    
46.     // ********************* PS配置 *********************
    
47.     // PS_CONF1: 0x20 → PS检测周期100ms，16次平均滤波
    
48.     VCNL36821S_WriteReg(VCNL36821S_PS_CONF1_REG, 0x20);
    
49.     // PS_CONF2: 0x08 → LED发射功率中等（120mA），禁用PS唤醒
    
50.     VCNL36821S_WriteReg(VCNL36821S_PS_CONF2_REG, 0x08);
    
51. 
    
52.     // ********************* ALS配置 *********************
    
53.     // ALS_CONF: 0x18 → ALS分辨率16位，启用50Hz工频抑制，测量速率10Hz
    
54.     VCNL36821S_WriteReg(VCNL36821S_ALS_CONF_REG, 0x18);
    
55. 
    
56.     // 等待传感器稳定
    
57.     HAL_Delay(20);
    
58. }
    
59. 
    
60. // 读取环境光强度（转换为lx）
    
61. float VCNL36821S_ReadALS(void)
    
62. {
    
63.     uint8_t als_data[2] = {0};
    
64.     uint16_t als_raw = 0;
    
65.     float als_lx = 0.0f;
    
66. 
    
67.     // 读取ALS 16位数据（低字节+高字节）
    
68.     if(VCNL36821S_ReadReg(VCNL36821S_ALS_DATA_REG, als_data, 2) != HAL_OK)
    
69.     {
    
70.         return 0.0f;
    
71.     }
    
72. 
    
73.     als_raw = (uint16_t)((als_data[1] << 8) | als_data[0]);
    
74.     // 转换公式（参考威世官方手册）：1LSB = 0.01 lx
    
75.     als_lx = als_raw * 0.01f;
    
76. 
    
77.     return als_lx;
    
78. }
    
79. 
    
80. // 读取近距离检测原始值
    
81. uint16_t VCNL36821S_ReadPS(void)
    
82. {
    
83.     uint8_t ps_data[2] = {0};
    
84.     uint16_t ps_raw = 0;
    
85. 
    
86.     // 读取PS 12位数据（低字节+高字节，仅低12位有效）
    
87.     if(VCNL36821S_ReadReg(VCNL36821S_PS_DATA_REG, ps_data, 2) != HAL_OK)
    
88.     {
    
89.         return 0;
    
90.     }
    
91. 
    
92.     ps_raw = (uint16_t)((ps_data[1] << 8) | ps_data[0]) & 0x0FFF; // 仅保留低12位
    
93.     return ps_raw;
    
94. }
    
95. 
    
96. // 配置中断阈值
    
97. void VCNL36821S_SetIntThreshold(uint16_t als_thdl, uint16_t als_thdh, uint16_t ps_thdl, uint16_t ps_thdh)
    
98. {
    
99.     // 配置ALS下限阈值（低字节）
    
100.     VCNL36821S_WriteReg(VCNL36821S_ALS_THDL_REG, als_thdl & 0xFF);
     
101.     VCNL36821S_WriteReg(VCNL36821S_ALS_THDL_REG + 1, (als_thdl >> 8) & 0xFF);
     
102.     // 配置ALS上限阈值（低字节）
     
103.     VCNL36821S_WriteReg(VCNL36821S_ALS_THDH_REG, als_thdh & 0xFF);
     
104.     VCNL36821S_WriteReg(VCNL36821S_ALS_THDH_REG + 1, (als_thdh >> 8) & 0xFF);
     
105. 
     
106.     // 配置PS下限阈值（12位）
     
107.     VCNL36821S_WriteReg(VCNL36821S_PS_THDL_REG, ps_thdl & 0xFF);
     
108.     VCNL36821S_WriteReg(VCNL36821S_PS_THDL_REG + 1, (ps_thdl >> 8) & 0x0F);
     
109.     // 配置PS上限阈值（12位）
     
110.     VCNL36821S_WriteReg(VCNL36821S_PS_THDH_REG, ps_thdh & 0xFF);
     
111.     VCNL36821S_WriteReg(VCNL36821S_PS_THDH_REG + 1, (ps_thdh >> 8) & 0x0F);
     
112. }
     
113. 
     
114. // 启用中断功能
     
115. void VCNL36821S_EnableInt(uint8_t ps_int_en, uint8_t als_int_en)
     
116. {
     
117.     uint8_t int_ctrl = 0;
     
118.     // 读取当前中断控制寄存器值
     
119.     VCNL36821S_ReadReg(VCNL36821S_INT_CTRL_REG, &int_ctrl, 1);
     
120. 
     
121.     // 设置PS/ALS中断使能位
     
122.     if(ps_int_en) int_ctrl |= 0x02;  // BIT1: PS中断使能
     
123.     else int_ctrl &= ~0x02;
     
124. 
     
125.     if(als_int_en) int_ctrl |= 0x01; // BIT0: ALS中断使能
     
126.     else int_ctrl &= ~0x01;
     
127. 
     
128.     // 写入配置
     
129.     VCNL36821S_WriteReg(VCNL36821S_INT_CTRL_REG, int_ctrl);
     
130. }</font>

复制代码

三、主函数调用示例（main.c）

1. <font face="宋体">#include "stm32f1xx_hal.h"
   
2. #include "vcnl36821s.h"
   
3. 
   
4. // 全局I2C句柄（根据实际工程生成）
   
5. I2C_HandleTypeDef hi2c1;
   
6. 
   
7. int main(void)
   
8. {
   
9.     HAL_Init();
   
10.     SystemClock_Config();
    
11.     MX_I2C1_Init(); // 初始化I2C1（速率400kHz，开漏输出）
    
12. 
    
13.     float als_lx;
    
14.     uint16_t ps_raw;
    
15. 
    
16.     // 初始化VCNL36821S
    
17.     VCNL36821S_Init();
    
18. 
    
19.     // 配置中断阈值（示例：ALS<100lx或>5000lx触发；PS<100或>3000触发）
    
20.     VCNL36821S_SetIntThreshold(1000, 50000, 100, 3000);
    
21.     // 启用ALS+PS中断
    
22.     VCNL36821S_EnableInt(1, 1);
    
23. 
    
24.     while(1)
    
25.     {
    
26.         // 读取环境光和近距离数据
    
27.         als_lx = VCNL36821S_ReadALS();
    
28.         ps_raw = VCNL36821S_ReadPS();
    
29. 
    
30.         // 示例：根据PS值判断距离（可根据实际场景校准）
    
31.         if(ps_raw > 3000)
    
32.         {
    
33.             // 物体接近（<5cm），执行熄屏/触发动作
    
34.         }
    
35.         else if(ps_raw < 100)
    
36.         {
    
37.             // 物体远离（>20cm），执行亮屏/复位动作
    
38.         }
    
39. 
    
40.         // 示例：根据ALS值调节屏幕亮度
    
41.         if(als_lx < 50.0f)
    
42.         {
    
43.             // 低光环境，调亮屏幕
    
44.         }
    
45.         else if(als_lx > 2000.0f)
    
46.         {
    
47.             // 强光环境，调暗屏幕
    
48.         }
    
49. 
    
50.         HAL_Delay(200); // 200ms读取一次，可按需调整
    
51.     }
    
52. }</font>

复制代码

四、移植与使用注意事项

• 硬件适配：
  
  
  • I2C 引脚需配置为开漏输出，SDA/SCL 串联 4.7kΩ 上拉电阻到 3.3V；
  • 传感器 INT 引脚可接 STM32 外部中断引脚（如 PA0），用于中断触发；
  • 保证传感器光学窗口无遮挡，避免油污 / 灰尘影响检测精度。
    
    
• 代码移植：
  
  
  • 修改VCNL36821S_I2C_HANDLE为工程实际使用的 I2C 句柄；
  • 根据实际需求调整 PS 发射功率、ALS 测量速率（修改初始化寄存器值）；
  • PS 原始值需根据实际场景校准（如：3000 对应 5cm，100 对应 20cm）。
    
    
• 性能优化：
  
  
  • 低功耗场景：配置传感器自动休眠，仅在需要时唤醒读取数据；
  • 抗干扰优化：开启 ALS 工频抑制，PS 可增加平均滤波次数（修改 PS_CONF1 寄存器）。