wled · netmindz · May 23, 2026 · May 23, 2026 · May 23, 2026 · May 24, 2026
diff --git a/usermods/dali_gear/library.json b/usermods/dali_gear/library.json
@@ -0,0 +1,7 @@
+{
+  "name": "dali_gear",
+  "build": { "libArchive": false },
+  "dependencies": {
+    "qqqDALI": "https://github.com/netmindz/DALI-Lighting-Interface.git#fix/esp32-volatile-cast"
+  }
+}
diff --git a/usermods/dali_gear/readme.md b/usermods/dali_gear/readme.md
@@ -0,0 +1,140 @@
+# DALI Gear Usermod
+
+Makes WLED act as a **DALI control gear** (IEC 62386) — i.e. a light that responds to commands from an external DALI master (wall dimmer, BMS, building automation system, etc.).
+
+DALI (Digital Addressable Lighting Interface) is a standardised two-wire bus protocol for lighting control. This usermod puts WLED on the bus as a gear device: the DALI master sends brightness/on/off/colour commands, and WLED adjusts its LEDs accordingly.
+
+> **ESP32 only.** The hardware timer API used for Manchester decoding is not available on ESP8266.
+
+## Hardware
+
+You need a DALI bus interface circuit to convert between the DALI bus voltage (9.5–22.5 V) and the ESP32's 3.3 V GPIO levels.
+
+### Minimal DIY circuit (from [qqqlab/DALI-Lighting-Interface](https://github.com/qqqlab/DALI-Lighting-Interface))
+
+```
+3.3V ESP32         5.6V               ___
+                   Zener        +----|___|---- 12V Power Supply
+            ___    Diode        |     220 Ω
+RX ---+-----|___|---|>|----------+------------- DALI+
+      |      10K                |
+     +-+                        |
+     | | 100K          ___    |/   PNP             DALI BUS
+     +-+        TX ---|___|----|    Transistor
+      |                 1K     |\
+      |                          V
+GND --+---------------------------+------------- DALI-
+```
+
+> **Note:** For this circuit the TX polarity must be inverted. The transistor pulls the bus low when the GPIO is HIGH. Configure your TX pin accordingly and invert the output in hardware or adjust the HAL callbacks in the source.
+
+Commercial DALI interface modules (e.g. Waveshare Pico-DALI2, Mikroe DALI Click) are a simpler alternative.
+
+### Pin assignment
+
+| Signal | Direction | Description |
+|---|---|---|
+| RX | Input | Reads DALI bus state (high = bus idle, low = bus asserted) |
+| TX | Output | Drives DALI bus — needed for backward frame responses to QUERY commands |
+
+Default pins are **RX=14, TX=17** (Waveshare Pico-DALI2).
+
+Configure both pins in the WLED usermod settings page.
+
+## Configuration
+
+| Setting | Default | Description |
+|---|---|---|
+| Enabled | false | Enable/disable the usermod |
+| pin_rx | 14 | GPIO for DALI bus RX |
+| pin_tx | 17 | GPIO for DALI bus TX |
+| daliAddr | -1 | Short address (0–63) to respond to, or -1 to respond to broadcast only |
+
+## DALI commands handled
+
+### Direct Arc Power Control (DAPC)
+
+When the master sends a DAPC frame, the arc level (0–254) is mapped linearly to WLED brightness (0–255). WLED's existing gamma correction handles perceptual uniformity at the LED output.
+
+| DALI arc level | WLED behaviour |
+|---|---|
+| 0 | Turn off |
+| 1–254 | Set brightness proportionally, turn on |
+| 255 (mask) | Ignored (no change) |
+
+### Indirect commands
+
+| Command | Number | WLED action |
+|---|---|---|
+| OFF | 0 | Turn off |
+| UP | 1 | Increase brightness by 10 |
+| DOWN | 2 | Decrease brightness by 10 |
+| STEP UP | 3 | Increase brightness by 1 |
+| STEP DOWN | 4 | Decrease brightness by 1 |
+| RECALL MAX LEVEL | 5 | Set brightness to 255, turn on |
+| RECALL MIN LEVEL | 6 | Set brightness to 1, turn on |
+| STEP DOWN AND OFF | 7 | Decrease by 1; turn off if at minimum |
+| ON AND STEP UP | 8 | Turn on if off, then increase by 10 |
+| GO TO LAST ACTIVE LEVEL | 10 | Restore last brightness before turn-off |
+
+### DT8 colour temperature (IEC 62386-209)
+
+Colour temperature commands from a DALI master are mapped to WLED's CCT value via `strip.setCCT()`. The mired value is converted to Kelvin (`K = 1,000,000 / mireds`). WLED's accepted range is 1900–10091 K; values outside this range are clamped.
+
+Two CCT application flows are supported:
+
+**Standard flow (IEC 62386-209 §11.3.4.1):**
+
+1. `SET DTR0` — lower byte of colour temperature in mireds
+2. `SET DTR1` — upper byte of colour temperature in mireds
+3. `ENABLE DEVICE TYPE 8` — activates DT8 interpretation
+4. `SET TEMPORARY COLOUR TEMPERATURE` (0xE1) — loads DTR0+DTR1 into temporary register
+5. `ACTIVATE` (0xE2) — applies the temporary colour temperature
+
+**Non-standard combined flow (observed in some masters):**
+
+Some DALI masters skip the `0xE1` + `0xE2` sequence and instead apply the colour temperature implicitly alongside the subsequent DAPC command. The usermod detects this: if DTR0/DTR1 are set and DT8 is active when a DAPC frame arrives, the CCT is applied at the same time as the brightness change.
+
+**QUERY COLOUR TYPE (0xE7):**
+
+Some masters query the gear's colour capabilities before sending CCT commands. The usermod responds with a backward frame value of `0x02` (bit 1 = Tc colour temperature supported), sent 4 ms after the query frame to meet the DALI spec requirement (7Te–22Te ≈ 2.9–9.2 ms settling window).
+
+`SET DTR0`, `SET DTR1`, and `ENABLE DEVICE TYPE 8` are sniffed as broadcast-level frames regardless of the configured `daliAddr`.
+
+### CCT on RGB-only strips
+
+`strip.setCCT()` adjusts the colour temperature via WLED's internal CCT pipeline. For an RGB-only strip (no dedicated white or CCT channel), **White Balance Correction** must be enabled in WLED LED settings (Config → LED Preferences → White Balance Correction) for the CCT value to affect the LED output. This makes WLED apply a colour temperature correction on the RGB channels.
+
+## Addressing
+
+DALI addressing works as follows:
+
+- **Broadcast** (`0xFE`/`0xFF`): always handled regardless of `daliAddr` setting
+- **Short address** (0–63): set `daliAddr` to the address the DALI master has assigned to this device
+- **Group address**: not handled
+
+Set `daliAddr` to `-1` (default) to respond only to broadcast commands. This is useful for a single-gear installation.
+
+## Enabling the usermod
+
+Add to your `platformio_override.ini`:
+
+```ini
+[env:esp32dev]
+custom_usermods = dali_gear
+lib_deps =
+    ${env.lib_deps}
+    https://github.com/netmindz/DALI-Lighting-Interface.git#fix/esp32-volatile-cast
+```
+
+## Limitations
+
+- No short address commissioning via DALI bus (set the address manually in WLED config)
+- No group address support
+- No DALI scene mapping
+
+## Dependencies
+
+- [qqqlab/DALI-Lighting-Interface](https://github.com/qqqlab/DALI-Lighting-Interface) (GPL-3.0)
+  Low-level Manchester-encoded DALI bus driver by qqqlab.
+  This usermod uses the fork at `https://github.com/netmindz/DALI-Lighting-Interface.git#fix/esp32-volatile-cast` which includes an ESP32 volatile-cast fix.