AP3216C 软件包提供了使用接近感应(ps)与光照强度(als)传感器 ap3216c
基本功能,并且提供了硬件中断的可选功能。本文介绍该软件包的基本功能,以及 Finsh/MSH
测试命令等。
- 光照强度 :支持 4 个量程
- 接近感应 :支持 4 种增益
- 中断触发 :光照强度及接近感应同时支持
高于阈值
或低于阈值
的两种硬件中断触发方式
名称 | 说明 |
---|---|
ap3216c.h | 传感器使用头文件 |
ap3216c.c | 传感器使用源代码 |
SConscript | RT-Thread 默认的构建脚本 |
README.md | 软件包使用说明 |
ap3216c_datasheet.pdf | 官方数据手册 |
AP3216C 软件包遵循 Apache-2.0 许可,详见 LICENSE 文件。
依赖 RT-Thread I2C
设备驱动框架。
使用 ap3216c
软件包需要在 RT-Thread 的包管理器中选择它,具体路径如下:
RT-Thread online packages
peripheral libraries and drivers --->
[*] ap3216c: a digital ambient light and a proximity sensor ap3216c driver library --->
[*] Enable hardware interrupt
(47) The number of the sensor hardware interrupt pin
Version (latest) --->
每个功能的配置说明如下:
ap3216c: a digital ambient light and a proximity sensor ap3216c driver library
:选择使用ap3216c
软件包;Enable hardware interrupt
:使能硬件中断功能;The number of the sensor hardware interrupt pin
:传感器硬件中断的引脚号;Version
:配置软件包版本,默认最新版本。
然后让 RT-Thread 的包管理器自动更新,或者使用 pkgs --update
命令更新包到 BSP 中。
按照前文介绍,获取 ap3216c
软件包后,就可以按照 下文提供的 API 使用传感器 ap3216c
与 Finsh/MSH
命令进行测试,详细内容如下。
ap3216c_device_t ap3216c_init(const char *i2c_bus_name)
根据总线名称,自动初始化对应的 ap3216c
设备,具体参数与返回说明如下表
参数 | 描述 |
---|---|
name | i2c 设备名称 |
返回 | 描述 |
!= NULL | 将返回 ap3216c 设备对象 |
= NULL | 查找失败 |
void ap3216c_deinit(ap3216c_device_t dev)
如果设备不再使用,反初始化将回收 ap3216c
设备的相关资源,具体参数说明如下表
参数 | 描述 |
---|---|
dev | ap3216c 设备对象 |
float ap3216c_read_ambient_light(ap3216c_device_t dev)
通过 ap3216c
传感器读取光照强度测量值,返回浮点型光照强度值(单位:lux),具体参数与返回说明如下表
参数 | 描述 |
---|---|
dev | ap3216c 设备对象 |
返回 | 描述 |
!= 0.0 | 测量光照强度值 |
=0.0 | 测量失败 |
在读取光照强度过程中,默认量程为 AP3216C_ALS_RANGE_20661,如需修改,请参照下文的设置参数 API 进行设置,可配置的量程列表如下
enum als_range
{
AP3216C_ALS_RANGE_20661, // 量程对应精度为 0.35 lux/count.
AP3216C_ALS_RANGE_5162, // 量程对应精度为 0.0788 lux/count.
AP3216C_ALS_RANGE_1291, // 量程对应精度为 0.0197 lux/count.
AP3216C_ALS_RANGE_323, // 量程对应精度为 0.0049 lux/count.
};
uint16_t ap3216c_read_ps_data(ap3216c_device_t dev)
通过 ap3216c
传感器读取接近感应测量值,返回 16
位接近感应值,具体参数与返回说明如下表
参数 | 描述 |
---|---|
dev | ap3216c 设备对象 |
返回 | 描述 |
!= 0 | 测量接近感应值 |
=0 | 测量物体不在传感器探测范围内 |
在读取接近感应过程中,计算出接近感应值,默认测量增益为 AP3216C_ALS_GAIN2。如需修改,请参照下文的设置参数 API 进行设置,可配置的增益列表如下
enum als_gain
{
AP3216C_ALS_GAIN1, //一倍检测增益
AP3216C_ALS_GAIN2, //二倍检测增益
AP3216C_ALS_GAIN4, //四倍检测增益
AP3216C_ALS_GAIN8, //八倍检测增益
};
rt_err_t ap3216c_set_param(ap3216c_device_t dev, ap3216c_cmd_t cmd, rt_uint8_t value)
通过 ap3216c
传感器设置参数,具体参数与返回说明如下表
参数 | 描述 |
---|---|
dev | ap3216c 设备对象 |
cmd | 将要设置参数的命令 |
value | 将要设置命令的值 |
返回 | 描述 |
RT_EOK | 设置参数成功 |
-RT_ERROR | 设置参数错误 |
通过设置命令,设置不同的命令类型,如果设置与默认相同,则不需要重新设置,具体命令类型与默认如下所示
AP3216C_SYSTEM_MODE, //系统配置(默认 : 0b000)
AP3216C_INT_PARAM, //中断清除方式(默认 : 0b0)
AP3216C_ALS_RANGE, //ALS 量程范围(默认 : 0b00)
AP3216C_ALS_PERSIST, //ALS 中断过滤次数(默认 : 0b0000)
AP3216C_ALS_CALIBRATION, //ALS 校准(默认 : 0x40)
AP3216C_ALS_LOW_THRESHOLD_L, //ALS 最小阈值低位字节(默认 : 0x00)
AP3216C_ALS_LOW_THRESHOLD_H, //ALS 最小阈值高位字节(默认 : 0x00)
AP3216C_ALS_HIGH_THRESHOLD_L, //ALS 最大阈值低位字节(默认 : 0xFF)
AP3216C_ALS_HIGH_THRESHOLD_H, //ALS 最大阈值高位字节(默认 : 0xFF)
AP3216C_PS_INTEGRATED_TIME, //PS 或者 IR 转换时间(默认 : 0000)
AP3216C_PS_AGAIN, //PS 检测增益 (默认 : 0b01)
AP3216C_PS_PERSIST, //PS 中断过滤次数(默认 : 0b01)
AP3216C_PS_LED_CONTROL, //IR LED 发送时间(默认 : 0b01)
AP3216C_PS_LED_DRIVER_RATIO, //IR LED 驱动电流比率(默认 : 0b11)
AP3216C_PS_INT_MODE, //PS 中断模式(默认 : 0x01)
AP3216C_PS_MEAN_TIME, //PS 平均采集时间(默认 : 0x00)
AP3216C_PS_WAITING_TIME, //PS 采集等待实际(默认 : 0x00)
AP3216C_PS_CALIBRATION_L, //PS 校准阈值低位字节(默认 : 0x00)
AP3216C_PS_CALIBRATION_H, //PS 校准阈值高位字节(默认 : 0x00)
AP3216C_PS_LOW_THRESHOLD_L, //PS 最小阈值低位字节(默认 :0x00)
AP3216C_PS_LOW_THRESHOLD_H, //PS 最小阈值高位字节(默认 :0x00)
AP3216C_PS_HIGH_THRESHOLD_L, //PS 最大阈值低位字节(默认 :0xff)
AP3216C_PS_HIGH_THRESHOLD_H, //PS 最大阈值高位字节(默认 :0xff)
例如 ,需要设置 ALS 量程为 AP3216C_ALS_RANGE_20661,使用命令如下
ap3216c_set_param(dev, AP3216C_ALS_RANGE, AP3216C_ALS_RANGE_20661); //dev 为设备对象
rt_err_t ap3216c_get_param(ap3216c_device_t dev, ap3216c_cmd_t cmd, rt_uint8_t *value)
通过 ap3216c
传感器获取设置参数,具体参数与返回说明如下表
参数 | 描述 |
---|---|
dev | ap3216c 设备对象 |
cmd | 将要获取参数的命令 |
value | 将要获取命令的参数 |
返回 | 描述 |
RT_EOK | 获取参数成功 |
-RT_ERROR | 获取参数错误 |
void ap3216c_int_als_cb(ap3216c_device_t dev, rt_bool_t enabled, ap3216c_threshold_t threshold, ap3216c_int_cb int_cb)
该功能为可选功能,支持使用硬件中断功能,配置相应的中断阈值与中断噪音过滤次数,具体参数与返回说明如下表
参数 | 描述 |
---|---|
dev | ap3216c 设备对象 |
enabled | 是否使能注册中断回调 |
threshold | 中断阈值与过滤次数 |
int_cb | 中断回调函数 |
表中 threshold
为中断阈值与中断噪音过滤次数结构体,内容如下
struct ap3216c_threshold
{
rt_uint16_t min; /* als 16 bits, ps 10 bits available(0-1 bit and 8-15 bit ) */
rt_uint16_t max; /* als 16 bits, ps 10 bits available(0-1 bit and 8-15 bit ) */
rt_uint8_t noises_time; /* filter special noises trigger interrupt */
}
- 注:
- 最大阈值与最小阈值在 als 中是16位,在 pa 中只有 10 位有效。
表中 int_cb
为用户自定义函数,函数结构如下
typedef void (*ap3216c_int_cb)(void *args)
void ap3216c_int_ps_cb(ap3216c_device_t dev, rt_bool_t enabled, ap3216c_threshold_t threshold, ap3216c_int_cb int_cb)
同设置 als 硬件中断回调函数功能一样,为可选功能,支持使用硬件中断功能,配置相应的中断阈值与中断噪音过滤次数,具体参数与返回说明如下表
参数 | 描述 |
---|---|
dev | ap3216c 设备对象 |
enabled | 是否使能注册中断回调 |
threshold | 中断阈值与过滤次数 |
int_cb | 中断回调函数 |
ap3216c 软件包提供了丰富的测试命令,项目只要在 RT-Thread 上开启 Finsh/MSH 功能即可。在做一些基于 ap3216c
的应用开发、调试时,这些命令会非常实用,它可以准确的读取指传感器测量的光照强度与接近感应。具体功能可以输入 ap3216c
,可以查看完整的命令列表
msh />ap3216c
Usage:
ap3216c probe <dev_name> - probe sensor by given name
ap3216c read - read sensor ap3216c data
msh />
当第一次使用 ap3216c
命令时,直接输入 ap3216c probe <dev_name>
,其中 <dev_name>
为指定的 i2c
总线,例如:i2c1
。如果有这个传感器,就不会提示错误;如果总线上没有这个传感器,将会显示提示找不到相关设备,日志如下:
msh />ap3216c probe i2c1 #探测成功,没有错误日志
msh />
msh />ap3216c probe i2c88 #探测失败,提示对应的 I2C 设备找不到
[E/ap3216c] can't find ap3216c device on 'i2c88'
msh />
探测成功之后,输入 ap3216c read
即可获取光照强度与接近感应检测值,包括提示信息,日志如下:
msh />ap3216c read #接近没有探测到物体
object is not proximity of sensor
ap3216c measure current brightness: 25.9 (lux)
msh />
msh />ap3216c read #接近有物体
ap3216c read current ps data : 219
ap3216c measure current brightness: 1.0(lux)
msh />
暂无。