WLED pixels_dice_tray UsermodBLE 支持要求、library.json 禁用机制与自定义构建实践【免费下载链接】WLEDControl WS2812B and many more types of digital RGB LEDs with an ESP32 over WiFi!项目地址: https://gitcode.com/GitHub_Trending/wl/WLED本文围绕 WLED 仓库中 BLE_REQUIREMENT.md 展开讲解pixels_dice_trayUsermod 为何无法随标准 WLED 固件一起编译、为什么它的library.json被改名为library.json.disabled以及如何通过platformio_override.ini自定义构建环境为 ESP32-S3 烧录一个支持 ESP32 BLEBluetooth Low Energy的定制固件。读完本篇你可以独立完成从复制示例配置、修改构建参数到执行pio run出固件的完整流程并理解 WLED 构建系统自动发现 Usermod 的底层机制。为什么这个 Usermod 需要特殊的 BLE 配置pixels_dice_tray是一个让 WLED 作为 BLE 主机BLE Central连接 Pixels Dice。骰子作为 BLE 外设Peripheral广播掷骰结果ESP32 负责扫描、连接并把结果转化为 LED 效果、TFT 菜单和 MQTT 事件。BLE 支持不是所有 WLED 构建都具备的WLED 的 ESP32 构建默认使用Tasmota Arduino ESP32 平台platform-espressif32例如 platformio.ini 中[esp32_idf_V4]使用的平台包以及 platformio.ini 中[esp32_idf_V5]使用的更新版本。该 Tasmota 平台默认不包含 Arduino BLE 库。如果把pixels_dice_tray自动纳入构建编译会直接失败因为它的源码依赖ESP32 BLE Arduino库见 platformio_override.ini.sample 中的lib_deps。因此该 Usermod不能简单地用custom_usermods *纳入通用构建必须走自定义构建环境见下文操作。library.json 为什么被禁用构建系统的自动发现机制library.json已被重命名为 library.json.disabled。要理解这个操作的必要性需要看 WLED 的 Usermod 加载脚本 pio-scripts/load_usermods.pyfor token in line.split(): if token *: for mod_path in sorted(usermod_dir.iterdir()): if mod_path.is_dir() and (mod_path / library.json).exists(): _custom_usermod_names.add(mod_path.name) usermods_libdeps.append(fsymlink://{mod_path.resolve()})pio-scripts/load_usermods.py 显示当构建配置中custom_usermods *platformio.ini 中的usermods等环境即采用此写法含义是展开为 usermods 文件夹中的所有 Usermod时脚本会遍历usermods/目录凡是目录内存在library.json的 Usermod 都会被以symlink://形式自动加入lib_deps参与编译。也就是说只要pixels_dice_tray目录下有library.json所有custom_usermods *的构建环境都会自动拉入它随即因为缺少 BLE 库而编译失败。把文件改名为library.json.disabled后load_usermods.py的目录扫描就找不到它从而安全地把它排除在通用构建之外——这是一个用命名约定实现的构建级开关。自定义构建操作步骤文档给出的完整流程如下全部步骤均可复现。第一步复制示例配置到构建根目录在usermods/pixels_dice_tray/目录下执行cp platformio_override.ini.sample ../../../platformio_override.ini即把示例文件复制到仓库根目录、重命名为platformio_override.ini与 platformio.ini 同目录PlatformIO 会自动将其与主配置合并。随后按你所用的 ESP32 开发板修改该文件。第二步理解示例配置中的两个构建环境platformio_override.ini.sample 定义了default_envs t_qt_pro_8MB_dice, esp32s3dev_8MB_qspi_dice两个环境的共同点配置项取值说明boardesp32-s3-devkitc-1通用 ESP32-S3 开发板板型platform${esp32s3.platform}复用 WLED 主配置的 ESP32-S3 平台定义Tasmota 平台包board_build.partitions${esp32.large_partitions}大容量分区布局board_build.f_flash/flash_mode80000000L/qio80MHz QIO 闪存build_flags${common.build_flags} ${esp32s3.build_flags}等在 WLED 通用构建参数之上追加 Usermod 宏lib_deps${esp32s3.lib_deps}ESP32 BLE Arduinoaxlan/pixels-dice-interface 1.2.0关键显式引入 Arduino BLE 库这正是标准构建缺失的部分Usermod 相关的关键编译宏t_qt_pro_8MB_dice环境-D USERMOD_PIXELS_DICE_TRAY ;; Enables this UserMod -D USERMOD_PIXELS_DICE_TRAY_BL_ACTIVE_LOW1 -D USERMOD_PIXELS_DICE_TRAY_ROTATION2这些宏在 pixels_dice_tray.cpp 中均有#ifndef默认值兜底如USERMOD_PIXELS_DICE_TRAY_ROTATION默认 0USERMOD_PIXELS_DICE_TRAY_REFRESH_RATE_MS默认 200ms因此最简构建只需-D USERMOD_PIXELS_DICE_TRAY一个宏即可启用。t_qt_pro_8MB_dice带 128x128 TFT 屏的 LILYGO T-QT Pro8MB 闪存在 Usermod 宏之外还引入bodmer/TFT_eSPI 2.5.43并携带一组 TFT_eSPI 编译期参数例如USER_SETUP_ID211、GC9A01_DRIVER1、TFT_WIDTH128/TFT_HEIGHT128、TFT_ROTATION3、引脚定义TFT_MOSI2、TFT_SCLK3、TFT_CS5、TFT_DC6、TFT_RST1、TFT_BL10以及 SPI 频率SPI_FREQUENCY40000000等。注意 TFT_eSPI 要求引脚在编译期固定运行时修改无效——这一点在 Usermod 源码注释中也有强调见 pixels_dice_tray.cpp 的NOTE: THIS MOD DOES NOT SUPPORT CHANGING THE SPI PINS FROM THE UI!。esp32s3dev_8MB_qspi_dice无屏幕的 ESP32-S3 开发板8MB 闪存只追加-D USERMOD_PIXELS_DICE_TRAY不引入 TFT_eSPI是验证 BLE 功能的最小构建。第三步用自定义环境构建pio run -e t_qt_pro_8MB_dice # 或 pio run -e esp32s3dev_8MB_qspi_dice构建产物即可通过 PlatformIO 常规方式烧录pio run -t upload示例配置中还设置了upload_speed 921600和monitor_filters esp32_exception_decoder便于解析崩溃回溯。平台要求与适用边界文档明确列出的平台要求ESP32-S3 或兼容的、具备 BLE 能力的 ESP32 开发板必须使用自定义 PlatformIO 环境参考 platformio_override.ini.sample不能用于 ESP8266 和 ESP32-S2二者不具备该 Usermod 所需的 BLE 支持/组合。从源码与示例配置还能补充两点边界原始 ESP32非 S3实测不可用。platformio_override.ini.sample 中保留了一个被整体注释掉的esp32dev_dice环境作者记录该环境可以编译和烧录但启动后在 AP 初始化之后即出现内存分配异常回溯指向 UDP 栈的new[]从源码结构看是BLE 扫描任务与 WiFi 网络任务并行运行时的竞争问题作者将其标记为 THIS DOES NOT WORK!!!!!!。这与 README.md 中 I found that the original ESP32 did not work 的结论一致。BLE 协议栈占用大量闪存。README.md 给出实测体积含 TFT 代码约 1.9MB不含则约 1.85MB已无法放入 WLED 默认的 4MB 分区布局tools/WLED_ESP32_4MB_256KB_FS.csv4MB 设备只能用本目录专门制作的 WLED_ESP32_4MB_64KB_FS.csv文件系统仅 64KB预设较多时会捉襟见肘。因此要发挥完整功能建议使用 8MB 及以上闪存——这也解释了示例环境为什么都命名为..._8MB_...。BLE 支持在源码中的落地方式以下细节可与文档要求互相印证帮助排查BLE 没连上一类问题。强制开启 WiFi 休眠。ESP32 上 BLE 与 WiFi 共存时WiFi 模组休眠是协议栈的硬性要求。pixels_dice_tray.cpp 的setup()中// Need to enable WiFi sleep: // E (1513) wifi:Error! Should enable WiFi modem sleep when both WiFi and Bluetooth are enabled!!!!!! noWifiSleep false;若漏掉这一行日志中会持续打印上述 IDF 错误BLE 行为会变得不可预期。README.md 提到这是该 Usermod 需要的唯一特殊行为。周期性 BLE 扫描与自动恢复。setup()中调用pixels::ScanForDice(ble_scan_duration_sec, BLE_TIME_BETWEEN_SCANS_SEC)启动后台扫描任务pixels_dice_tray.cpp。两个周期均有编译期默认值pixels_dice_tray.cpp单次扫描时长BLE_SCAN_DURATION_SEC 4秒两轮扫描间隔BLE_TIME_BETWEEN_SCANS_SEC 5秒ble_scan_duration_sec可经 Web 配置页调整设置项ble_scan_duration见 pixels_dice_tray.cpp 的addToConfig。loop()中还实现了扫描状态的自动切换所有配置的骰子都连上就StopScanning()有骰子掉线则重新ScanForDice()pixels_dice_tray.cpp。骰子槽位与通配符匹配。loop()通过pixels::ListDice()获取已连接设备先按已记录 ID 匹配再按配置名称匹配最后尝试*通配槽位并把通配符替换为该骰子的实际名称pixels_dice_tray.cpp配合UpdateDieNames的锁定逻辑pixels_dice_tray.cpp。这正是文档所说保存配置时若通配槽已连接骰子*会被替换为该骰子名称的实现。掷骰结果的 MQTT 上报。每收到一条掷骰更新若 MQTT 已连接则向$mqttDeviceTopic/dice/roll发布 JSON字段包括骰子名name、状态state、点数val、时间戳timepixels_dice_tray.cpp。TFT 构建的闲置断电。带 TFT 的构建还定义了USERMOD_PIXELS_DICE_TRAY_TIMEOUT_MS默认 5 分钟若配置了骰子却长时间扫不到任何设备Usermod 会关闭背光并调用esp_deep_sleep_start()进入深睡pixels_dice_tray.cpp。在自己的构建中重新启用 library.json如果你希望把这个 Usermod 纳入自己的自定义构建而不是每次依赖示例文件文档给出的步骤是把library.json.disabled改回library.json恢复 usermods/pixels_dice_tray/library.json 文件在你的自定义环境中显式将pixels_dice_tray加入custom_usermods列表确认该环境的lib_deps包含 BLE 支持ESP32 BLE Arduino库及axlan/pixels-dice-interface 1.2.0参考 platformio_override.ini.sample。需要注意第 1 步的影响面一旦library.json恢复pio-scripts/load_usermods.py 的*通配逻辑会重新把它拖进所有custom_usermods *的环境导致这些环境缺 BLE 库而编译失败。因此该文件保持.disabled状态是上游仓库有意为之的默认选择除非你确认所有通配构建环境都已补齐 BLE 依赖。小结与进一步阅读需求文档usermods/pixels_dice_tray/BLE_REQUIREMENT.md本篇的主体来源构建配置示例usermods/pixels_dice_tray/platformio_override.ini.sample含两个可用环境与一个已废弃的原始 ESP32 环境记录Usermod 完整文档usermods/pixels_dice_tray/README.md效果参数、TFT GUI、MQTT 事件、骰子连接配置核心实现usermods/pixels_dice_tray/pixels_dice_tray.cpp自动加载机制pio-scripts/load_usermods.py 与 platformio.ini核心要点回顾pixels_dice_tray的 BLE 依赖是平台级缺口——Tasmota 平台默认不含 Arduino BLE 库而custom_usermods *的目录扫描机制又会无条件纳入带library.json的 Usermod两者叠加决定了必须library.json.disabled 自定义环境ESP32 BLE Arduino库 USERMOD_PIXELS_DICE_TRAY宏的双保险方案。构建时认准esp32s3dev_8MB_qspi_dice或t_qt_pro_8MB_dice两个环境即可。【免费下载链接】WLEDControl WS2812B and many more types of digital RGB LEDs with an ESP32 over WiFi!项目地址: https://gitcode.com/GitHub_Trending/wl/WLED创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考