WLED VL53L0X 手势 Usermod用激光测距传感器实现免触碰开关与亮度调节【免费下载链接】WLEDControl WS2812B and many more types of digital RGB LEDs with an ESP32 over WiFi!项目地址: https://gitcode.com/GitHub_Trending/wl/WLEDWLED 的VL53L0X_gesturesusermod 通过 VL53L0X 激光测距传感器让你只需用手一挥即可开关灯带、通过改变手与传感器的距离无级调节亮度特别适合厨房灯带等不便触碰的场景。本文以 usermods/VL53L0X_gestures/readme.md 为主线结合 usermods/VL53L0X_gestures/VL53L0X_gestures.cpp 的源码实现完整讲解该 usermod 的两种手势操作、可调参数、安装步骤以及底层的状态机逻辑与亮度换算公式。功能概述两种手势两种控制按照 readme 的原始描述该 usermod 实现了两类简单手势开关灯on/off在传感器下方挥一下手short motion。底层调用 WLED 的shortPressAction()因此其行为与物理按钮 1 的短按完全一致——默认切换开/关并且可以通过 WLED 的按钮宏macros自定义为执行任意预设。亮度调节brightness adjustment将手停留在传感器下方持续 1 秒切换到亮度模式之后通过改变手与传感器的距离来调整亮度距离越近越亮。参数可定制见下文。从源码结构看整个逻辑是一个简单的二态判定每次读到有目标的距离时记录motionStartTime若目标持续存在超过VL53L0X_LONG_MOTION_DELAY_MS默认 1000ms标记为 long motion 并实时把亮度映射到距离若目标在超时前消失released则执行shortPressAction()并复位状态。相关实现在 VL53L0X_gestures.cpp 第 63-104 行。可调参数四个编译宏及默认值readme 中提到see parameters below for customization这些参数在源码顶部以#ifndef形式定义默认值如下VL53L0X_gestures.cpp 第 21-35 行宏名称默认值作用VL53L0X_MAX_RANGE_MM230响应运动的最大距离毫米手距传感器超过此值视为无目标VL53L0X_MIN_RANGE_OFFSET60传感器可检测的最小距离毫米用于亮度计算的截断下限VL53L0X_DELAY_MS100采样间隔即多久读取一次传感器数据毫秒VL53L0X_LONG_MOTION_DELAY_MS1000持续有目标多久后进入亮度调节模式毫秒对应 readme 中的 hold for 1 second由于四个宏都使用#ifndef包裹只需在构建时于 build flags 中先定义同名宏即可覆盖默认值例如build_flags ${env.build_flags} -D USERMOD_VL53L0X_GESTURES -D VL53L0X_MAX_RANGE_MM300 -D VL53L0X_DELAY_MS80亮度换算公式进入亮度模式后源码将测距值线性映射到 0-255 亮度VL53L0X_gestures.cpp 第 90 行bri (VL53L0X_MAX_RANGE_MM - max(range, VL53L0X_MIN_RANGE_OFFSET)) * 255 / (VL53L0X_MAX_RANGE_MM - VL53L0X_MIN_RANGE_OFFSET);以默认值代入即bri (230 - max(range, 60)) * 255 / 170手距 ≤ 60mm 时分母截断生效亮度恒为最大值 255手距 230mm或更远的临界值时亮度为 0中间距离按线性关系过渡因此靠近变亮、远离变暗是连续无级的。每帧亮度更新后调用stateUpdated(1)触发状态生效WLED 会按正常流程应用新亮度。安装步骤readme 给出的官方安装步骤共两步结合 usermods/VL53L0X_gestures/library.json 与源码头部注释补充如下接线将 VL53L0X 传感器VCC、GND、SDA、SCL接到 WLED 开发板的默认 I2C 引脚上。WLED 中 I2C 引脚由i2c_sda/i2c_scl全局变量管理定义见 wled00/wled.h 第 820-828 行可在设置的引脚配置中查看/修改。开启 usermod 并添加依赖在platformio_override.ini的目标环境中添加构建标志注意 readme 原文拼写的plaformio_override.ini即指此文件build_flags ${env.build_flags} -D USERMOD_VL53L0X_GESTURES lib_deps ${env.lib_deps} pololu/VL53L0X ^1.3.0其中pololu/VL53L0X ^1.3.0依赖同时声明在 library.json 中源码#include VL53L0X.h即来自该库。源码解析初始化与循环逻辑setupI2C 可用性检查与高速模式初始化流程VL53L0X_gestures.cpp 第 50-60 行先检查i2c_scl 0 || i2c_sda 0若当前板/配置没有可用的 I2C 引脚直接置enabled false并跳过 usermod——这是一种优雅的降级不会报错也不会占用循环sensor.setTimeout(150)单次读数超时 150ms防止总线异常时死等sensor.init()失败时仅打印调试信息Failed to detect and initialize VL53L0X sensor!主循环仍会跳过所有逻辑sensor.setMeasurementTimingBudget(20000)将测量时间预算设为 20ms注释标明 set high speed mode即每个采样周期约 20ms 完成一次测距配合 100ms 的VL53L0X_DELAY_MS采样间隔留有充足余量。loop采样、状态判定与防打断主循环VL53L0X_gestures.cpp 第 63-104 行的关键点if (!enabled || strip.isUpdating()) return;strip.isUpdating()在像素数据正送往灯带期间返回 truewled00/FX.h 第 920 行此时跳过读取避免在 LED 刷屏期间干扰总线通过millis() - lastTime VL53L0X_DELAY_MS实现非阻塞定时采样sensor.readRangeSingleMillimeters()单次读取range VL53L0X_MAX_RANGE_MM判定为手在感应区内手进入感应区 → 记录motionStartTime并置wasMotionBefore true持续停留超过VL53L0X_LONG_MOTION_DELAY_MS→ 进入亮度模式按上文公式实时写入bri并stateUpdated(1)手离开感应区released 分支→ 若未曾进入亮度模式则执行shortPressAction()开关灯随后复位wasMotionBefore与isLongMotion。值得注意的一个细节进入亮度模式后即使手离开isLongMotion也会在同一分支被复位因此每次重新按住 1 秒都会从头开始一次完整的亮度调节会话。与 WLED 核心按钮机制的对接为何可以用宏定制开关行为readme 特别强调 on/off 走的是shortPressActionCan be customized via WLED macros。这个函数的定义在 wled00/button.cpp 第 22-41 行其逻辑是若该按钮位配置了macroButton则执行applyPreset(...)直接应用指定预设——这就是 readme 所说可通过 WLED macros 定制的实现路径在 WLED 界面的按钮宏设置里把按钮 1 的短按指向一个预设手势挥手就会应用该预设而非简单开关否则按按钮编号执行默认动作按钮 0 为toggleOnOff()开/关切换若开启按钮 MQTT 发布还会向 MQTT 主题推送short消息便于智能家居联动感知这次虚拟按键。函数原型声明在 wled00/fcn_declare.h 第 28 行shortPressAction(uint8_t b0)usermod 不带参数调用即作用于按钮 0。其他实现细节注册与 ID文件末尾通过REGISTER_USERMOD(vl53l0x_gestures)完成 usermod 注册VL53L0X_gestures.cpp 第 129-130 行getId()返回USERMOD_ID_VL53L0X其值 12 定义在 wled00/const.h 第 208 行。引脚占用提示wled00/pin_manager.h 第 62 行 留有注释说明该 usermod 使用标准 HW_I2C 引脚因此在配置其他 usermod 的 I2C 引脚时需注意与之共用总线。无持久化设置源码中addToConfig()处于注释状态说明该 usermod 当前不向cfg.json写入自定义设置全部行为参数均由编译宏决定。小结VL53L0X_gestures是一个实现紧凑但机制完整的 usermod用 VL53L0X 单次测距 简单的进入/停留/离开判定就实现了挥手开关 距离无级调光两个免触碰控制通道其开关动作复用 WLED 按钮短按机制天然支持按钮宏与 MQTT 发布扩展性优于自行编写独立控制逻辑。实际使用时重点关注四个编译宏响应上限距离、最小距离截断、采样间隔、长动作阈值并按 library.json 添加pololu/VL53L0X ^1.3.0依赖即可完成部署。【免费下载链接】WLEDControl WS2812B and many more types of digital RGB LEDs with an ESP32 over WiFi!项目地址: https://gitcode.com/GitHub_Trending/wl/WLED创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
WLED VL53L0X 手势 Usermod用激光测距传感器实现免触碰开关与亮度调节【免费下载链接】WLEDControl WS2812B and many more types of digital RGB LEDs with an ESP32 over WiFi!项目地址: https://gitcode.com/GitHub_Trending/wl/WLEDWLED 的VL53L0X_gesturesusermod 通过 VL53L0X 激光测距传感器让你只需用手一挥即可开关灯带、通过改变手与传感器的距离无级调节亮度特别适合厨房灯带等不便触碰的场景。本文以 usermods/VL53L0X_gestures/readme.md 为主线结合 usermods/VL53L0X_gestures/VL53L0X_gestures.cpp 的源码实现完整讲解该 usermod 的两种手势操作、可调参数、安装步骤以及底层的状态机逻辑与亮度换算公式。功能概述两种手势两种控制按照 readme 的原始描述该 usermod 实现了两类简单手势开关灯on/off在传感器下方挥一下手short motion。底层调用 WLED 的shortPressAction()因此其行为与物理按钮 1 的短按完全一致——默认切换开/关并且可以通过 WLED 的按钮宏macros自定义为执行任意预设。亮度调节brightness adjustment将手停留在传感器下方持续 1 秒切换到亮度模式之后通过改变手与传感器的距离来调整亮度距离越近越亮。参数可定制见下文。从源码结构看整个逻辑是一个简单的二态判定每次读到有目标的距离时记录motionStartTime若目标持续存在超过VL53L0X_LONG_MOTION_DELAY_MS默认 1000ms标记为 long motion 并实时把亮度映射到距离若目标在超时前消失released则执行shortPressAction()并复位状态。相关实现在 VL53L0X_gestures.cpp 第 63-104 行。可调参数四个编译宏及默认值readme 中提到see parameters below for customization这些参数在源码顶部以#ifndef形式定义默认值如下VL53L0X_gestures.cpp 第 21-35 行宏名称默认值作用VL53L0X_MAX_RANGE_MM230响应运动的最大距离毫米手距传感器超过此值视为无目标VL53L0X_MIN_RANGE_OFFSET60传感器可检测的最小距离毫米用于亮度计算的截断下限VL53L0X_DELAY_MS100采样间隔即多久读取一次传感器数据毫秒VL53L0X_LONG_MOTION_DELAY_MS1000持续有目标多久后进入亮度调节模式毫秒对应 readme 中的 hold for 1 second由于四个宏都使用#ifndef包裹只需在构建时于 build flags 中先定义同名宏即可覆盖默认值例如build_flags ${env.build_flags} -D USERMOD_VL53L0X_GESTURES -D VL53L0X_MAX_RANGE_MM300 -D VL53L0X_DELAY_MS80亮度换算公式进入亮度模式后源码将测距值线性映射到 0-255 亮度VL53L0X_gestures.cpp 第 90 行bri (VL53L0X_MAX_RANGE_MM - max(range, VL53L0X_MIN_RANGE_OFFSET)) * 255 / (VL53L0X_MAX_RANGE_MM - VL53L0X_MIN_RANGE_OFFSET);以默认值代入即bri (230 - max(range, 60)) * 255 / 170手距 ≤ 60mm 时分母截断生效亮度恒为最大值 255手距 230mm或更远的临界值时亮度为 0中间距离按线性关系过渡因此靠近变亮、远离变暗是连续无级的。每帧亮度更新后调用stateUpdated(1)触发状态生效WLED 会按正常流程应用新亮度。安装步骤readme 给出的官方安装步骤共两步结合 usermods/VL53L0X_gestures/library.json 与源码头部注释补充如下接线将 VL53L0X 传感器VCC、GND、SDA、SCL接到 WLED 开发板的默认 I2C 引脚上。WLED 中 I2C 引脚由i2c_sda/i2c_scl全局变量管理定义见 wled00/wled.h 第 820-828 行可在设置的引脚配置中查看/修改。开启 usermod 并添加依赖在platformio_override.ini的目标环境中添加构建标志注意 readme 原文拼写的plaformio_override.ini即指此文件build_flags ${env.build_flags} -D USERMOD_VL53L0X_GESTURES lib_deps ${env.lib_deps} pololu/VL53L0X ^1.3.0其中pololu/VL53L0X ^1.3.0依赖同时声明在 library.json 中源码#include VL53L0X.h即来自该库。源码解析初始化与循环逻辑setupI2C 可用性检查与高速模式初始化流程VL53L0X_gestures.cpp 第 50-60 行先检查i2c_scl 0 || i2c_sda 0若当前板/配置没有可用的 I2C 引脚直接置enabled false并跳过 usermod——这是一种优雅的降级不会报错也不会占用循环sensor.setTimeout(150)单次读数超时 150ms防止总线异常时死等sensor.init()失败时仅打印调试信息Failed to detect and initialize VL53L0X sensor!主循环仍会跳过所有逻辑sensor.setMeasurementTimingBudget(20000)将测量时间预算设为 20ms注释标明 set high speed mode即每个采样周期约 20ms 完成一次测距配合 100ms 的VL53L0X_DELAY_MS采样间隔留有充足余量。loop采样、状态判定与防打断主循环VL53L0X_gestures.cpp 第 63-104 行的关键点if (!enabled || strip.isUpdating()) return;strip.isUpdating()在像素数据正送往灯带期间返回 truewled00/FX.h 第 920 行此时跳过读取避免在 LED 刷屏期间干扰总线通过millis() - lastTime VL53L0X_DELAY_MS实现非阻塞定时采样sensor.readRangeSingleMillimeters()单次读取range VL53L0X_MAX_RANGE_MM判定为手在感应区内手进入感应区 → 记录motionStartTime并置wasMotionBefore true持续停留超过VL53L0X_LONG_MOTION_DELAY_MS→ 进入亮度模式按上文公式实时写入bri并stateUpdated(1)手离开感应区released 分支→ 若未曾进入亮度模式则执行shortPressAction()开关灯随后复位wasMotionBefore与isLongMotion。值得注意的一个细节进入亮度模式后即使手离开isLongMotion也会在同一分支被复位因此每次重新按住 1 秒都会从头开始一次完整的亮度调节会话。与 WLED 核心按钮机制的对接为何可以用宏定制开关行为readme 特别强调 on/off 走的是shortPressActionCan be customized via WLED macros。这个函数的定义在 wled00/button.cpp 第 22-41 行其逻辑是若该按钮位配置了macroButton则执行applyPreset(...)直接应用指定预设——这就是 readme 所说可通过 WLED macros 定制的实现路径在 WLED 界面的按钮宏设置里把按钮 1 的短按指向一个预设手势挥手就会应用该预设而非简单开关否则按按钮编号执行默认动作按钮 0 为toggleOnOff()开/关切换若开启按钮 MQTT 发布还会向 MQTT 主题推送short消息便于智能家居联动感知这次虚拟按键。函数原型声明在 wled00/fcn_declare.h 第 28 行shortPressAction(uint8_t b0)usermod 不带参数调用即作用于按钮 0。其他实现细节注册与 ID文件末尾通过REGISTER_USERMOD(vl53l0x_gestures)完成 usermod 注册VL53L0X_gestures.cpp 第 129-130 行getId()返回USERMOD_ID_VL53L0X其值 12 定义在 wled00/const.h 第 208 行。引脚占用提示wled00/pin_manager.h 第 62 行 留有注释说明该 usermod 使用标准 HW_I2C 引脚因此在配置其他 usermod 的 I2C 引脚时需注意与之共用总线。无持久化设置源码中addToConfig()处于注释状态说明该 usermod 当前不向cfg.json写入自定义设置全部行为参数均由编译宏决定。小结VL53L0X_gestures是一个实现紧凑但机制完整的 usermod用 VL53L0X 单次测距 简单的进入/停留/离开判定就实现了挥手开关 距离无级调光两个免触碰控制通道其开关动作复用 WLED 按钮短按机制天然支持按钮宏与 MQTT 发布扩展性优于自行编写独立控制逻辑。实际使用时重点关注四个编译宏响应上限距离、最小距离截断、采样间隔、长动作阈值并按 library.json 添加pololu/VL53L0X ^1.3.0依赖即可完成部署。【免费下载链接】WLEDControl WS2812B and many more types of digital RGB LEDs with an ESP32 over WiFi!项目地址: https://gitcode.com/GitHub_Trending/wl/WLED创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
