From 8a57fe34e53e95528e50e7e7c075976af86a32b8 Mon Sep 17 00:00:00 2001 From: The_miro Date: Sun, 2 Aug 2026 01:08:18 +0200 Subject: [PATCH] Add a move-in quickstart for dimming the stage light over Zigbee MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Drives an old ~250 W filament stage fixture from HA via the existing Zigbee2MQTT backbone: a 400 W-rated dimmer module wired inline into a Schuko extension lead, ~€25. Leads with verifying the lamp, because the wattage decides between a €25 module and a €100 dimmer pack, and it's the one step here with real fire risk. Documents the three stop conditions (discharge lamp, transformer, cooling fan) and the escape hatch if the lamp turns out over 400 W. Guidance only, matching the network-integration.md convention — nothing in this repo touches the fixture or the pairing. The Z2M side needs no config beyond permit-join, since setup-container-host.sh already sets homeassistant: true, and pairings live in database.db, which the restic backups cover. Co-Authored-By: Claude Opus 5 --- docs/stage-light-dimmer.md | 256 +++++++++++++++++++++++++++++++++++++ 1 file changed, 256 insertions(+) create mode 100644 docs/stage-light-dimmer.md diff --git a/docs/stage-light-dimmer.md b/docs/stage-light-dimmer.md new file mode 100644 index 0000000..82982b3 --- /dev/null +++ b/docs/stage-light-dimmer.md @@ -0,0 +1,256 @@ +# Stage light dimmer — driving an old filament fixture from HA over Zigbee + +**Short answer: a SONOFF MINI Extreme ZBDIM (400 W halogen rating) wired inline +into a short Schuko extension lead, paired to the existing Zigbee2MQTT instance. +Roughly €25, appears in HA as a normal dimmable `light` with no HA config at +all.** The only reason this needs a document is that the lamp has to be verified +*before* anything is bought — the wattage decides whether this is a €25 job or a +€100 one, and getting it wrong is the one path here with a real fire risk. + +This is guidance, not automation — **nothing under this repo touches the fixture, +the dimmer, or the Zigbee pairing.** Same convention as `network-integration.md`: +you do this by hand, at move-in, after Phase 1 is up. + +## 0. Prerequisite + +Phase 1 must be running first: the Docker stack from +`tools/setup-container-host.sh`, with Mosquitto, Home Assistant, and +Zigbee2MQTT talking to the Haozee CC2652P dongle (`docs/project-plan.md:16`). +Nothing below works until `docker logs zigbee2mqtt` shows a healthy coordinator. + +Everything in this doc stays on the Zigbee backbone rather than adding a WiFi +dimmer, for the reasons in `docs/components.md:208`. + +## 1. Verify the lamp before buying anything + +The fixture as measured in 2026: **19.6 cm lens diameter, ~15 Ω cold across the +lamp's own terminals, no transformer, no cooling fan.** That works out to roughly +a 250 W mains filament lamp. Re-verify at move-in — the fixture may have been +relamped, and the whole plan hangs on this number. + +### 1a. Read the lamp first + +The wattage is usually stamped on the pinch, base, or glass, and the fixture +nameplate states max lamp wattage and voltage. A type code is enough — CP60 / +CP61 / CP62 = 1000 W, CP95 = 500 W, HPL 575 = 575 W. **If you can read it, skip +to §2** — a printed number beats every estimate below. + +### 1b. Or measure it running — better than any estimate + +Not required, but it ends the guessing completely and costs almost nothing. A +plug-in energy meter (~€10, rated 16 A / 3680 W, so fine up to a 2 kW lamp) +reports true wattage directly: no tungsten coefficient, no lead nulling, no +arithmetic. A clamp meter (~€15) on the live lead does the same job. + +Worth owning regardless — it's the same instrument you'll want the first time an +automation's power figures look wrong anywhere else in this project. + +### 1c. Otherwise, estimate from cold resistance + +Disconnected from mains, probe **across the lamp's own two pins** — not at the +plug. The plug reading includes the fixture's switch, wiring, and socket +contacts, which added ~4–5 Ω of error last time and made the lamp look half its +actual size. + + P ≈ V² / (R_cold × k) → at 230 V: P ≈ 3530 / R_cold + +`k` is tungsten's hot/cold resistance ratio, ~15 for theatre halogen (range +13–17). Expect ±25% overall. + +| Cold reading | Likely lamp | | Cold reading | Likely lamp | +|---|---|---|---|---| +| ~18 Ω | 200 W | | ~5.4 Ω | 650 W | +| ~15 Ω | 250 W | | ~4.7 Ω | 750 W | +| ~12 Ω | 300 W | | ~3.5 Ω | 1000 W | +| ~7 Ω | 500 W | | ~1.8 Ω | 2000 W | +| open / ∞ | blown filament — **or a discharge lamp, see §1c** | + +Null your leads first (short the probes, subtract that reading). Irrelevant at +15 Ω, critical below 5 Ω where lead resistance is a large fraction of the total. + +A reading that wanders means bad probe contact, or that you're measuring a +winding rather than a filament. A good filament reads stable. + +### 1d. Optional cross-check: fixture size + +A sanity check on the estimate, not a rule. Lens diameter tracks wattage across +*professional theatrical* ranges, but older and budget fixtures routinely pair a +large lens with a modest lamp — lens size is set by the beam optics you want, not +the power. **Where this table disagrees with a terminal measurement, the +measurement wins.** + +| Fresnel lens Ø | Typical lamp | | PAR can Ø | Typical lamp | +|---|---|---|---|---| +| 75 mm (3") | 150–300 W | | PAR36 · 114 mm | 6–12 V + **transformer** | +| 125 mm (5") | 500–650 W | | PAR56 · 178 mm | 300–500 W | +| 150 mm (6") | 1000 W | | PAR64 · 204 mm | 500–1000 W | +| 200 mm (8") | 2000 W | | | | + +This fixture's 196 mm lens sits on PAR64, which would normally imply 500–1000 W, +while the terminal reading says ~250 W. That conflict is exactly what the caveat +above covers — but it's also why §1a/§1b are worth doing rather than trusting +either number alone. + +### 1e. Three things that stop this plan dead + +**Discharge lamp.** If the lamp or fixture says HMI, MSR, CSI, CDM, or HQI, or +there's a ballast/igniter in the base — **it cannot be phase-dimmed at all.** +Attempting it destroys the lamp and possibly the ballast. On/off relay only. + +**Transformer in the fixture.** Confirm by pulling the lamp and re-measuring at +the plug: open circuit means the path was the filament and you're fine; a +remaining reading of tens of ohms means there's a winding in there. That's an +inductive load, generic dimmer modules are not automatically safe on it, and the +lamp is low-voltage rather than mains. Stop and reassess. + +**Cooling fan.** If the fixture has one, it is usually wired in parallel with the +lamp downstream of the dimmer. Dim the circuit and the fan stalls while the lamp +still throws full heat. It must be fed from unswitched mains, ahead of the +dimmer. + +## 2. Bill of materials — ~€25 + +| Item | Price | Note | +|---|---|---| +| [SONOFF MINI Extreme ZBDIM](https://www.amazon.de/SONOFF-elektronische-Halogenlampen-Neutralleiter-Leistungsmessung/dp/B0GFN145VT) | €15–20 | 400 W halogen, Zigbee 3.0, Z2M-supported, power monitoring, acts as a router | +| Short Schuko extension lead | ~€5 | Gets cut in half | +| Surface junction box (Abzweigdose) | ~€3 | Houses the module | +| Inline fuse holder + 2 A fuse | ~€3 | The module has no internal fuse | + +At 250 W into a 400 W rating you sit at ~62% load — the headroom you want for +cold-filament inrush. + +**Do not buy a plug-in Zigbee dimmer.** The whole category caps around 200 W +because a plug body has nowhere to dump triac heat. The +[AduroSmart ERIA dimmable plug](https://www.amazon.de/AduroSmart-Steckdose-Dimmbar-kompatibel-81855/dp/B08PKQVQTQ) +is the only real Schuko option and it's rated 200 W — *under* this lamp's draw. + +[Candeo C204](https://www.amazon.de/Candeo-Dimmermodul-erforderlich-kompatibel-Smartthings/dp/B091GTK61Y) +(~€35) is an equally valid module if the SONOFF is unavailable. Same 400 W +halogen rating, same build job, no power monitoring. + +## 3. Build the inline dimmer + +Cut the extension lead, wire the module in a junction box: Schuko plug in, Schuko +socket out. The module needs neutral, which an extension lead has. + +- Proper enclosure, no exposed conductors. +- Strain relief on **both** cable entries. +- Fuse in the live leg, upstream of the module. +- Don't bury the box anywhere unventilated. Thermal is the dominant failure mode. + +If cutting mains cable isn't something you want to do, this is a 15-minute job +for an electrician — and there's no off-the-shelf product that avoids it, given +the 200 W plug ceiling above. + +## 4. Pair with Zigbee2MQTT + +`tools/setup-container-host.sh:503` sets `permit_join: false`, which is the right +default and means pairing is a deliberate act: + +1. Z2M web UI → **Permit join**, scoped to the coordinator. +2. Power the module. It should appear within ~30 s. +3. Let permit-join time out. Don't leave it open. +4. **Rename it immediately** — `stage_lamp` or similar. Otherwise + `light.0x00124b00...` ends up baked into every automation you write. + +`tools/setup-container-host.sh:502` already sets `homeassistant: true`, so MQTT +discovery creates the HA `light` entity automatically. **No HA YAML, no manual +entity definition, nothing to commit to this repo** — the pairing lives in Z2M's +`database.db`, which the restic backups already cover +(`docs/project-plan.md:459`). + +If Z2M reports the device as unsupported, pull a newer image rather than writing +a converter — the compose file already tracks `koenkk/zigbee2mqtt:latest` +(`tools/setup-container-host.sh:1184`). + +## 5. Configure + +One setting genuinely matters: + +- **`power_on_behavior` → `off`.** Defaults are often `previous` or `on`, which + means a power blip or a Z2M container restart brings a 250 W stage lamp to full + brightness in an empty room. + +Two worth doing: + +- **Lower `min_brightness`.** Defaults are tuned to stop LEDs flickering at the + bottom of the range. A filament dims smoothly to near-zero, so dropping it + recovers the usable low end. +- **Pass `transition: 2` in `light.turn_on` calls.** Ramping over a couple of + seconds cuts the cold-filament inrush, which is the biggest single wear event + on the lamp and the main stress on the triac. + +Optional and situational: + +- **`switch_type`** — only relevant if a physical wall switch is wired to the + module's input. Irrelevant for an inline extension-lead build; set it if the + fixture ever gets a permanent installation. +- **Edge mode**, if the module exposes it. Trailing edge (Phasenabschnitt) and + leading edge (Phasenanschnitt) both work fine on a pure resistive filament, so + leave the default alone. It only becomes a real decision if a transformer ever + enters the picture (§1e), where leading edge is the more tolerant of the two. +- **Surface the power reading in HA.** The ZBDIM's power monitoring arrives as + its own sensor entity. A dashboard card, or a template alert if draw exceeds + the expected figure, is cheap early warning on a failing lamp or a wrong + relamp — and it's the only thing here that would catch someone plugging a + bigger fixture into this dimmer. +- **Don't bother with a dimming curve.** Filament light output is very nonlinear + against phase angle, so the HA brightness slider won't feel perceptually even. + Correcting it is fiddly and buys little on a fixture like this; live with it + unless it actually bothers you. + +## 6. First run + +- Non-flammable surface, module in open air, not boxed into anything yet. +- RCD-protected circuit, ideally on a 6 A or 10 A MCB rather than 16 A. +- Stay with it for the first 30 minutes and sweep the full dim range rather than + parking at one level — **mid-dim is peak triac dissipation, not full-on**. +- **Check the power reading against the ~250 W estimate.** This is what the + SONOFF's power monitoring is for; it replaces the resistance estimate with a + direct measurement. Materially higher than expected → stop, reassess headroom. +- Check the fixture's clearance. Old stage cans run 200 °C+ housings and want + ~0.5 m from anything flammable. If the triac ever fails short, the lamp sits at + 100% indefinitely — fine for the fixture, less fine for a curtain. + +Worth doing once while the lamp is out: clean the lamp socket contacts. The +~4–5 Ω gap between the plug and terminal readings in 2026 was fixture wiring and +contacts, dissipating several watts as heat inside an already-hot fixture. + +Two more that aren't required but pay for themselves: + +- **Buy a spare lamp at the same time.** Theatre lamp types get discontinued and + an old fixture is worth nothing without one. Record the exact type code once + you've read it in §1a. +- **Label the finished dimmer box** with both numbers — lamp draw and module + rating (250 W / 400 W). Future-you plugging a different fixture into a box that + looks like a generic extension lead is the most plausible way this ends up + overloaded. + +## 7. If the lamp turns out bigger than ~400 W + +Everything above is void; a 1 kW lamp pulls ~4.3 A steady and 50 A of cold +inrush, well past any in-wall module. Two routes, both built around a used +theatrical dimmer pack (€50–100 for 4×1200 W), which handles inrush, fusing, +heatsinking, and EMI properly: + +| | Approach | Cost | Note | +|---|---|---|---| +| **B** | Zigbee 0–10 V dimmer (YSRSAI YSR-Mini-01 or Lonsonho VM-Zigbee-S02, ~€20–25) into the pack's **0–10 V analog input** | €75–125 | Stays on the Zigbee backbone. Most analog packs already have this input. | +| **C** | ESP32 + RS485 module (~€10) running [andyboeh/esphome-dmx512](https://github.com/andyboeh/esphome-dmx512) driving the pack over DMX512 | €60–110 | Cheapest, fits the existing `firmware/` ESPHome pattern, but breaks the Zigbee-only lighting rule in `docs/components.md:208`. | + +Prefer **B** — €20 more to keep lighting on one backbone is noise, and either +way you get three spare channels for future fixtures. + +## 8. Troubleshooting + +| Symptom | Likely cause | +|---|---| +| Device never appears in Z2M | Permit-join timed out; module has no neutral; too far from coordinator for its first hop | +| Appears in Z2M, not in HA | `homeassistant: true` missing, or Mosquitto auth failing — check `docker logs zigbee2mqtt` | +| Lamp stuck at full, unresponsive | Triac failed short. Unplug at the wall. Usually means the load exceeded rating — re-measure before replacing | +| Buzzing or humming from the lamp | Normal for phase-cut dimming of big filaments (magnetostriction). Worse at mid-dim. A dimmer pack's choke fixes it; an inline module won't | +| Flicker at low brightness | Raise `min_brightness` | +| Module warm to the touch | Expected. Hot enough to be uncomfortable means it's under-rated for the load | +| Resistance readings that don't reconcile | A parallel path can never *raise* total resistance. If pulling the lamp makes the reading go **down**, the two measurements weren't the same configuration — re-probe both at the lamp terminals | +| Lamp reads open but fixture still conducts | The lamp is blown *and* there's a fan or transformer across the input. Both §1e cases at once — replace the lamp, then re-read §1e before wiring anything |