|
| 1 | +# pixels_dice_tray Usermod - BLE Requirement Notice |
| 2 | + |
| 3 | +## Important: This Usermod Requires Special Configuration |
| 4 | + |
| 5 | +The `pixels_dice_tray` usermod requires **ESP32 BLE (Bluetooth Low Energy)** support, which is not available in all WLED build configurations. |
| 6 | + |
| 7 | +### Why is library.json disabled? |
| 8 | + |
| 9 | +The `library.json` file has been renamed to `library.json.disabled` to prevent this usermod from being automatically included in builds that use `custom_usermods = *` (like the `usermods` environment in platformio.ini). |
| 10 | + |
| 11 | +The Tasmota Arduino ESP32 platform used by WLED does not include Arduino BLE library by default, which causes compilation failures when this usermod is auto-included. |
| 12 | + |
| 13 | +### How to Use This Usermod |
| 14 | + |
| 15 | +This usermod **requires a custom build configuration**. You cannot simply enable it with `custom_usermods = *`. |
| 16 | + |
| 17 | +1. **Copy the sample configuration:** |
| 18 | + ```bash |
| 19 | + cp platformio_override.ini.sample ../../../platformio_override.ini |
| 20 | + ``` |
| 21 | + |
| 22 | +2. **Edit `platformio_override.ini`** to match your ESP32 board configuration |
| 23 | + |
| 24 | +3. **Build with the custom environment:** |
| 25 | + ```bash |
| 26 | + pio run -e t_qt_pro_8MB_dice |
| 27 | + # or |
| 28 | + pio run -e esp32s3dev_8MB_qspi_dice |
| 29 | + ``` |
| 30 | + |
| 31 | +### Platform Requirements |
| 32 | + |
| 33 | +- ESP32-S3 or compatible ESP32 board with BLE support |
| 34 | +- Custom platformio environment (see `platformio_override.ini.sample`) |
| 35 | +- Cannot be used with ESP8266 or ESP32-S2 |
| 36 | + |
| 37 | +### Re-enabling for Custom Builds |
| 38 | + |
| 39 | +If you want to use this usermod in a custom build: |
| 40 | + |
| 41 | +1. Rename `library.json.disabled` back to `library.json` |
| 42 | +2. Manually add it to your custom environment's `custom_usermods` list |
| 43 | +3. Ensure your platform includes BLE support |
| 44 | + |
| 45 | +### References |
| 46 | + |
| 47 | +- See `README.md` for full usermod documentation |
| 48 | +- See `platformio_override.ini.sample` for build configuration examples |
0 commit comments