07 Laser Sensor Vl53l1x Driver
一、硬件介绍
1. VL53L0X介绍
VL53L0X 芯片内部集成了激光发射器和 SPAD 红外接收器,采用了第二代FightSenseTM 技术,通过接收器所接收到的光子时间来计算距离,最远测量距离可达两米,适合中短距离测量的应用.
VL53L0X传感器有3-4cm的盲区,有效测量范围3cm-200cm,精度+-3%
VL53L0X芯片IO电压为2.8V,3.3V供电需要串联120R电阻
响应频率20ms(最快),误差+-5%
2. VL53L1X介绍
VL53L1X是VL53L0X的升级版本,感光部分面积明显增大,有更远的探测距离,参数如下:
3. VL53L1X典型电路
XSHUT为输入引脚,用于模式选择(休眠),需要上拉电阻放置漏电流
GPIO1为中断输出引脚,用于输出测量dataready中断
为了达到极限传输率(400khz),上拉电阻需要根据电压和总线电容值选择,可以参见vl53l1x datasheet
4. VL53L0X与VL53L1X区别？
VL53L0X为2m测距版本,VL53L1X为4m版本.目前测试发现,这两颗芯片并不只是性能区别,官方给出的是两套库,不能相互通用.仔细阅读芯片手册甚至调用API的配置过程也是不同的,需要特别注意一下手中的芯片是哪个版本,然后对应的去找官网的库文件.
二、移植过程介绍
1. 官方库文件如何使用？
除了数据手册,我们还能从ST官方下载一个软件开发包,这里面包含了所有官方的API,和基于STM32的示例程序.
VL53L1X软件包下载地址:X-CUBE-53L1A1:The X-CUBE-53L1A1 software package
解压后,依次进入 Drivers->BSP->Components->vl53l1x ,这里的所有文件我们都要复制到自己的工程,我们可以新建一个文件夹/vl53l1x/core存放.这里是与硬件无关的基础文件,是不需要任何改动的
以上源文件还不够,还有一部分是与硬件相关的文件和用户配置文件,我们可以打开一个示例工程,复制到自己工程的/vl53l1x/platform目录.这些文件路径比较长,可以看以下图片找到.
2. 如何移植到ESP32？
拿到官方库文件后,如果想移植VL53L1X到ESP32等平台,需要实现以下底层函数 .这些函数声明在vl53l1_platform.h,需要在vl53l1_platform.c中编写实现
VL53L1_WrByte、VL53L1_WrWord、
VL53L1_WrDWord 、 VL53L1_RdByte 、 VL53L1_RdWord 、 VL53L1_RdDWord 、
VL53L1_WriteMulti、VL53L1_ReadMulti、VL53L1_UpdateByte、VL53L1_PollingDelay感谢kazkojima在github上分享的移植代码,链接 这个工程下载下来并不能工作,还需要下载官方库文件,做少许的修改.我进行了进一步的修改:链接
同理VL53L0X需要移植以下函数
VL53L0X_WrByte、VL53L0X_WrWord、
VL53L0X_WrDWord 、 VL53L0X_RdByte 、 VL53L0X_RdWord 、 VL53L0X_RdDWord 、
VL53L0X_WriteMulti、VL53L0X_ReadMulti、VL53L0X_UpdateByte、VL53L0X_PollingDelay3. vl53l1x模式选择与启动顺序
根据XSHUT引脚的输入电平,可以切换传感器HW Standby模式和SW Standby模式.如果主机不管理传感器模式,XSHUT应该被上拉为高电平.
This option optimizes power consumption as the VL53L1X can be completely powwhen not used, and then woken up through a host GPIO (using the XSHUT pin).
HW Standby :XSHUT拉低时,传感器电源被关闭
SW Standby :XSHUT拉高,进入boot和SW Standby 模式
4. 使用官方API校准传感器
校准流程:调用顺序要完全一致.官方流程图缺少一步:在绿色校准函数调用前需要VL53L1_SetPresetMode ！！！
5. 使用官方GUI程序校准传感器
调试了一周,遇到了无数的坑,大部分都是卡在初始化和校准阶段,很难处理.偶然发现官方还有用于配置和显示的GUI程序,相见恨晚啊.目前只有windows版本(需要配合官方硬件 STM32F401RE nucleo board 连接传感器使用).使用软件校准得到基准值后,初始化时填入的即可.如果使用API自己编写校准程序,非常容易出错,如下错误排查1.
三、测试代码分析
1. 初始化
/*init vl53l1 module*/
void vl53l1_init()
{
Roi0.TopLeftX = 0; //测量目标区 可选最小4*4,最大16*16
Roi0.TopLeftY = 15;
Roi0.BotRightX = 7;
Roi0.BotRightY = 0;
Roi1.TopLeftX = 8;
Roi1.TopLeftY = 15;
Roi1.BotRightX = 15;
Roi1.BotRightY = 0;
int status = VL53L1_WaitDeviceBooted(Dev); //等待设备初始化完成
status = VL53L1_DataInit(Dev); //设备初始化,上电后立刻执行
status = VL53L1_StaticInit(Dev); //装载参数
status = VL53L1_SetDistanceMode(Dev, VL53L1_DISTANCEMODE_LONG);//设置测量模式
status = VL53L1_SetMeasurementTimingBudgetMicroSeconds(Dev, 50000); //设置最长时间,根据测量模式确定
status = VL53L1_SetInterMeasurementPeriodMilliSeconds(Dev, 100); //测量间隔
status = VL53L1_SetUserROI(Dev, &Roi0); //设置ROI
status = VL53L1_StartMeasurement(Dev); //启动测量
if(status) {
printf("VL53L1_StartMeasurement failed \n");
while(1);
}
}以上初始化步骤除VL53L1_SetUserROI,其余不可少
PerformRefSpadManagement等初始化函数用在VL53L1上会报错,不明原因(已解决,见上面校准流程图提示).
roi 配置参见2.4 ranging description 2.8 Sensing array optical center
2. 轮寻测量
测量流程图:
轮训测量有两种方法,如上图所示,一种是阻塞方式(drivers polling mode),一种是非阻塞方式(Host polling mode),下图展示了阻塞方式的测量.
/* Autonomous ranging loop*/
static void
AutonomousLowPowerRangingTest(void)
{
printf("Autonomous Ranging Test\n");
static VL53L1_RangingMeasurementData_t RangingData;
VL53L1_UserRoi_t Roi1;
int roi = 0;
float left = 0, right = 0;
if (0/*isInterrupt*/) {
} else {
do // polling mode
{
int status = VL53L1_WaitMeasurementDataReady(Dev); //等待测量结果
if(!status) {
status = VL53L1_GetRangingMeasurementData(Dev, &RangingData); //获取单次测量数据
if(status==0) {
if (roi & 1) {
left = RangingData.RangeMilliMeter;
printf("L %3.1f R %3.1f\n", right/10.0, left/10.0);
} else
right = RangingData.RangeMilliMeter;
}
if (++roi & 1) {
status = VL53L1_SetUserROI(Dev, &Roi1);
} else {
status = VL53L1_SetUserROI(Dev, &Roi0);
}
status = VL53L1_ClearInterruptAndStartMeasurement(Dev); //释放中断
}
}
while (1);
}
// return status;
}3. 中断测量模式
其实这种模式和轮训测量没什么大的区别,因为轮训测量也要进行清除中断标志的操作,只是通知的方式不一样.
4. 传感器校准
/*Calibration vl53l1 module*/
static VL53L1_CalibrationData_t vl53l1_calibration(VL53L1_Dev_t *dev)
{
int status;
int32_t targetDistanceMilliMeter = 703;
VL53L1_CalibrationData_t calibrationData;
status = VL53L1_WaitDeviceBooted(dev);
status = VL53L1_DataInit(dev); //performs the device initialization
status = VL53L1_StaticInit(dev); // load device settings specific for a given use case.
status = VL53L1_SetPresetMode(dev,VL53L1_PRESETMODE_AUTONOMOUS);
status = VL53L1_PerformRefSpadManagement(dev);
status = VL53L1_PerformOffsetCalibration(dev,targetDistanceMilliMeter);
status = VL53L1_PerformSingleTargetXTalkCalibration(dev,targetDistanceMilliMeter);
status = VL53L1_GetCalibrationData(dev,&calibrationData);
if (status)
{
ESP_LOGE(TAG, "vl53l1_calibration failed \n");
calibrationData.struct_version = 0;
return calibrationData;
}else
{
ESP_LOGI(TAG, "vl53l1_calibration done ! version = %u \n",calibrationData.struct_version);
return calibrationData;
}
}github源码:https://github.com/qljz1993/esp32-vl53l1x-test
四、 错误排查
1. 激光测量的潜在问题
tof镜头检测的并不是到一个点的距离,而是一个椎体中的最短距离,这会导致一个问题,当飞行器靠近墙面飞行,返回的可能不是到地板的距离,而是到墙面的距离.
飞行器定高时,测距模式为长距离模式,要求在黑暗无红外光的环境,在室外强光下,激光传感器会受到很大的干扰,导致测量精度降低,在室外依旧建议气压定高.
2. 提示timeout
# 使用I2C
ets Jun 8 2016 00:22:57
rst:0xc (SW_CPU_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
configsip: 0, SPIWP:0xee
clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00
mode:DIO, clock div:2
load:0x3fff0018,len:4
load:0x3fff001c,len:6180
load:0x40078000,len:10180
ho 0 tail 12 room 4
load:0x40080400,len:6660
entry 0x40080764
I (31) boot: ESP-IDF v3.2.2-dirty 2nd stage bootloader
I (31) boot: compile time 11:50:48
I (31) boot: Enabling RNG early entropy source...
I (36) boot: SPI Speed : 40MHz
I (40) boot: SPI Mode : DIO
I (44) boot: SPI Flash Size : 4MB
I (48) boot: Partition Table:
I (52) boot: ## Label Usage Type ST Offset Length
I (59) boot: 0 nvs WiFi data 01 02 00009000 00006000
I (66) boot: 1 phy_init RF data 01 01 0000f000 00001000
I (74) boot: 2 factory factory app 00 00 00010000 00100000
I (81) boot: End of partition table
I (86) esp_image: segment 0: paddr=0x00010020 vaddr=0x3f400020 size=0x0b2d8 ( 45784) map
I (111) esp_image: segment 1: paddr=0x0001b300 vaddr=0x3ffb0000 size=0x0218c ( 8588) load
I (114) esp_image: segment 2: paddr=0x0001d494 vaddr=0x40080000 size=0x00400 ( 1024) load
0x40080000: _WindowOverflow4 at /home/libo/esp/esp-idf-v3.2.2/components/freertos/xtensa_vectors.S:1779
I (118) esp_image: segment 3: paddr=0x0001d89c vaddr=0x40080400 size=0x02774 ( 10100) load
I (130) esp_image: segment 4: paddr=0x00020018 vaddr=0x400d0018 size=0x1c62c (116268) map
0x400d0018: _flash_cache_start at ??:?
I (176) esp_image: segment 5: paddr=0x0003c64c vaddr=0x40082b74 size=0x07e60 ( 32352) load
0x40082b74: _gettimeofday_r at /home/libo/esp/esp-idf-v3.2.2/components/newlib/time.c:220
I (196) boot: Loaded app from partition at offset 0x10000
I (196) boot: Disabling RNG early entropy source...
I (197) cpu_start: Pro cpu up.
I (200) cpu_start: Starting app cpu, entry point is 0x400810fc
0x400810fc: call_start_cpu1 at /home/libo/esp/esp-idf-v3.2.2/components/esp32/cpu_start.c:246
I (191) cpu_start: App cpu up.
I (211) heap_init: Initializing. RAM available for dynamic allocation:
I (218) heap_init: At 3FFAE6E0 len 00001920 (6 KiB): DRAM
I (224) heap_init: At 3FFB3348 len 0002CCB8 (179 KiB): DRAM
I (230) heap_init: At 3FFE0440 len 00003AE0 (14 KiB): D/IRAM
I (236) heap_init: At 3FFE4350 len 0001BCB0 (111 KiB): D/IRAM
I (243) heap_init: At 4008A9D4 len 0001562C (85 KiB): IRAM
I (249) cpu_start: Pro cpu start user code
I (267) cpu_start: Starting scheduler on PRO CPU.
I (0) cpu_start: Starting scheduler on APP CPU.
I (4868) vl53l0x: refSpadCount = 1, isApertureSpads = 128
I (4868) vl53l0x: VL53L0X_PerformRefSpadManagement API status: -7 : Time out error
I (5448) vl53l0x: VL53L0X_PerformSingleRangingMeasurement API status: -7 : Time out errortypedef struct {
uint32_t TimeStamp; /*!< 32-bit time stamp. */
uint32_t MeasurementTimeUsec;
/*!< Give the Measurement time needed by the device to do the
* measurement.*/
uint16_t RangeMilliMeter; /*!< range distance in millimeter. */
uint16_t RangeDMaxMilliMeter;
/*!< Tells what is the maximum detection distance of the device
* in current setup and environment conditions (Filled when
* applicable) */
FixPoint1616_t SignalRateRtnMegaCps;
/*!< Return signal rate (MCPS)\n these is a 16.16 fix point
* value, which is effectively a measure of target
* reflectance.*/
FixPoint1616_t AmbientRateRtnMegaCps;
/*!< Return ambient rate (MCPS)\n these is a 16.16 fix point
* value, which is effectively a measure of the ambien
* t light.*/
uint16_t EffectiveSpadRtnCount;
/*!< Return the effective SPAD count for the return signal.
* To obtain Real value it should be divided by 256 */
uint8_t ZoneId;
/*!< Denotes which zone and range scheduler stage the range
* data relates to. */
uint8_t RangeFractionalPart;
/*!< Fractional part of range distance. Final value is a
* FixPoint168 value. */
uint8_t RangeStatus;
/*!< Range Status for the current measurement. This is device
* dependent. Value = 0 means value is valid.
* See \ref RangeStatusPage */
} VL53L0X_RangingMeasurementData_t;五、ESP32+VL53L1x例程
1. 例程说明
实现功能:通过VL53L1x 检测到高度变化(持续一秒),红灯亮起.高度恢复正常值(持续一秒),绿灯亮起.
可配置参数:通过make menuconfig 设置I2C 号码、端口号、LED端口号
例程解析见代码注释与用户手册
2. 注意事项
该例程只适用于VL53L1x,寄送的传感器为该型号.VL53L0x为老版本硬件,不适用本例程.
官方标称400cm测量距离,为黑暗环境下测得.室内正常灯光环境,可以保证10cm-260cm范围的有效测量
初始化函数vl53l1_init(VL53L1_Dev_t *) 中部分参数,需要根据实际使用环境确定,还有优化的空间.
传感器安装位置应确保在检测位置正上方
模块上电时自动矫正基准高度,如果基准高度有变化,需要重新上电重置参数
3. 例程链接
git clone https://github.com/qljz1993/esp32-vl53l1x-test.git最后更新于
这有帮助吗？