wizlight
An async Rust client for Philips WiZ smart bulbs, speaking the local UDP
protocol directly — no cloud, no account, no hub. The crate ships both a library
and a wizlight command-line tool.
It is a port of the parts of pywizlight that matter for
real-time control, and it is the protocol layer underneath
WiZzard.
Status: beta development, and the public API is frozen. The request/response transport, discovery, typed pilot/config methods, the measured 5 Hz rate-limited streaming path, the
syncPilotpush listener and the full CLI surface —discover,status,info,on,off,toggle,set,pulse,scenes,watchandbench— are in.Prereleases are published to keep the release path exercised rather than to be depended on, so every version below has to be spelled out in full. Cargo does not match a prerelease against an ordinary requirement:
wizlight = "0.1"resolves to nothing, and plaincargo install wizlightfails, until0.1.0is out.
Planned scope
Discovery by UDP broadcast— done; the CLI derives every viable subnet's broadcast address from local interfaces, while repeatable--broadcastflags override auto-detection. Fixture-tested and verified on a192.168.0.0/24LAN, where flag-free discovery selected192.168.0.255and found both bulbs— donegetPilot/setPilot/setState/getSystemConfigand friends, as typed requests and responsesBulb model parsing: capabilities, scene support and Kelvin range— doneA rate-limited streaming path for driving bulbs from live audio or video— done; its 20 Hz default is explicitly a placeholder until hardware benchmarking— done, with one shared listener and per-MAC subscriptionssyncPilotpush updates
Not planned: RGB ↔ RGB+CW conversion. A WiZ RGB bulb has five emitters, and
deciding how to spread a colour across them is a judgement call, not a protocol
detail. This crate lets you send r/g/b, or all five channels, and holds no
opinion about which — see [PilotBuilder], and --cold / --warm on the CLI,
which reaches the same five emitters. pywizlight's "trapezoid" was ported
and measured against raw RGB on hardware before being dropped: it renders a
near-white better, ties or loses elsewhere, and cannot reach some colours at all.
Anything that good is worth an application deciding for itself.
The wire protocol, measured behavior, model grammar, scene rules and known
unknowns are collected in docs/WIZ_PROTOCOL.md.
Library quickstart
[]
= { = "0.1.0-beta.1", = false }
The prerelease has to be spelled out in full: a plain "0.1" requirement does
not match 0.1.0-beta.1, and will keep doing nothing until 0.1.0 ships.
default-features = false matters. The cli feature is on by default so
that cargo install wizlight produces a working binary, and it pulls in clap,
anyhow and tracing-subscriber. Library consumers do not want any of those.
use ;
use ;
use Bulb;
async
Runnable versions live in examples/discover.rs and
examples/set_colour.rs:
$ cargo run --example discover
$ cargo run --example set_colour -- 192.168.0.5
For real-time producers, create one stream and offer each frame without an
.await. The stream keeps one pending frame, so a producer can never build a
queue behind the network; if it outruns the rate limit, the newest frame wins.
The default is the measured 5 Hz (200 ms) zero-skip optical ceiling on
hardware; use StreamConfig to override it.
use ;
use ;
# async
Every channel value is a valid one, so Channel::new cannot fail. The types
that do have a range — Dimming, Kelvin, Speed, Ratio, Devices, and
SceneId against the scene table — return a Result, because the bulb is not a
reliable validator: it silently clamps an out-of-range dimming and reports
success.
Colour, colour temperature and scene are mutually exclusive in one request, and asking for two of them fails at build time rather than silently picking one:
use ;
let clash = new
.rgb
.temp
.set_pilot;
assert!;
Scenes — WiZ calls them light modes — are effects the bulb animates by itself,
and the table of them is a const, so a scene picker needs no bulb and nothing
to await:
use ;
// Names are matched ignoring case and punctuation, so the spellings used by
// pywizlight, openHAB and WiZ's own docs all resolve.
let scene = from_name.expect;
assert_eq!;
assert_eq!;
// 39 scenes for a colour bulb, 17 for tunable white, 11 for dimmable white.
assert_eq!;
// Animating and taking a `speed` are different questions: Wake up ramps over
// minutes at a rate set in the app, so the builder refuses a `speed` for it.
assert!;
let wake_up = from_id.expect;
assert!;
The table is measured, not transcribed: every id was written to an
ESP25_SHRGB_01 on fw 1.38.0 and read back, and the WiZ app was walked through
mode by mode to name them. The bulb reports speed and dimming only where the
running scene uses them, which makes both directly observable — and corrects
WiZ's own published table in two places.
A SceneId therefore has to be an id the bulb will actually play, which is
narrower than what it accepts. 37 sets a colour temperature instead of a
scene, and 42–248 are silently clamped to 41; both answer success, and
both are refused here with a message saying what they really do. Custom light
modes made in the app are addressable as user slots:
use SceneId;
let first_custom_mode = user_slot.expect;
assert_eq!;
assert!; // really sets 2200 K
assert!; // really plays 41
Bulbs are found by broadcasting, and reported as they answer rather than in a batch at the end — a discovery run keeps re-broadcasting, so a bulb switched on halfway through is still found:
use Duration;
use Discovery;
async
Requests are retried and paced to what the hardware can actually absorb: three
attempts, each given 500 ms to be answered, and no two datagrams closer together
than 20 ms — so an unreachable bulb fails in under two seconds. See
RetryPolicy
to change that.
CLI
$ wizlight discover
9877d523a4da 192.168.0.8 ESP25_SHRGB_01 1.38.0
9877d5230f0a 192.168.0.7 ESP25_SHRGB_01 1.38.0
$ wizlight status 9877d5230f0a
on scene Warm white (11) 2700 K 100% -49 dBm
$ wizlight on 9877d5230f0a --rgb 255,80,0 --brightness 60
$ wizlight on 9877d5230f0a --rgb 255,80,0 --warm 64 # the fifth emitter too
$ wizlight on --all --scene "deep dive" --speed 120
$ wizlight off --all
$ wizlight watch 9877d5230f0a
Address a bulb by MAC, not by IP. A <target> accepts either, but DHCP
moves a bulb's address without warning and the MAC is the only stable identity
the protocol exposes. A MAC costs one short scan to resolve, and it stops as
soon as that bulb answers.
| Command | What it does |
|---|---|
discover |
Every bulb that answers, with MAC, address, model and firmware |
status <target> |
What the bulb says it is doing |
info <target> |
Model, firmware, class, Kelvin range and what it can do |
scenes <target> |
Only the scenes that bulb's class actually plays |
on / off / toggle |
on also takes --rgb, --hsv, --cold, --warm, --kelvin, --scene, --speed, --brightness |
set <target> |
The same options, sent as setState. It does not leave a bulb that was off alone: measured on ESP25_SHRGB_01 fw 1.38.0, setState turns it on exactly as setPilot does |
pulse <target> |
Transient brightness pulse (--delta, --duration) that restores the prior state when finished |
watch <target> |
Tail syncPilot updates until Ctrl-C; human output shows only fields changed since the previous update |
bench <target> |
Ramp setPilot rate, probe packet-to-photon latency and internal interpolation, and restore the pre-bench state on exit |
--all replaces the target on any of them and fans out to every bulb a scan
finds, concurrently. One bulb failing does not abort the rest, and does not let
the run exit 0 either.
It always costs the full scan, though — around five seconds — because there is
no way to know that the last bulb has answered. When you know how many to
expect, --wait 1 is plenty on a quiet network: both bulbs here answer a
broadcast in about 100 ms.
The ways of naming a colour are mutually exclusive, and clap rejects two of them
before anything is sent. --cold and --warm are the exception, and compose
with --rgb or --hsv: the white emitters are the other half of the same
colour mode, not a competing one. --scene takes an id or a name, matched
ignoring case and punctuation. Asking a bulb for something it has no hardware
for — colour on a dimmable white — fails with a message naming its class,
because the bulb will not refuse it: it answers success and does nothing.
A colour write sets all five emitters at once. Measured on ESP25_SHRGB_01
fw 1.38.0: the channels you leave out go dark, so --warm 128 on its own means
white only, and there is no way to add a white to a colour already showing —
send them together. For the same reason a colour with every channel at zero is
refused here rather than sent: the bulb discards it, and if anything else rides
along in the request (as state does on on) it answers success having done
nothing. Use off to go dark and --brightness to go dim.
Output
-
stdout is results, stderr is everything else — logs, diagnostics and errors, including the JSON ones. Redirect stdout and you get data or nothing.
-
--jsonon every command, with one envelope for both outcomes:resultis shaped by the command; under--allit is a list of{"target", "ok", "result"}or{"target", "ok", "error"}, one per bulb.watch --jsonis the streaming exception: it writes one envelope per update as newline-delimited JSON, and includes the bulb MAC in each--allresult. -
Exit codes:
0success,1failed,2usage,3nothing answered to that target,4a bulb was there and stopped answering. The last two are separate because they call for different reactions — re-scan, or retry. -
-vraises the log level (-vinfo,-vvdebug,-vvvtrace) andRUST_LOGoverrides it entirely. -
Colour is dropped when stderr is not a terminal, when
NO_COLORis set to anything non-empty, and under--json.
--timeout is how long to wait for each reply before retrying, and --wait
is how long a scan lasts. The CLI is deliberately more patient than the
library's default: a bulb at the far end of a flat has a round trip past a
second.
Shell completions
Generate a completion script from the installed binary and load it in the current shell:
| Shell | Command |
|---|---|
| Bash | source <(wizlight completions bash) |
| Zsh | source <(wizlight completions zsh) |
| Fish | wizlight completions fish | source |
| PowerShell | wizlight completions powershell | Out-String | Invoke-Expression |
| Elvish | eval (wizlight completions elvish | slurp) |
Add the command to the shell's startup file to load it in future sessions. Every
GitHub release also carries the generated files as wizlight.bash, _wizlight,
wizlight.fish, wizlight.ps1 and wizlight.elv, ready to place in the shell's
normal completion directory. Scene values are completed as accepted lowercase,
hyphenated names such as deep-dive.
A man page is deliberately not shipped. It would duplicate --help, while none
of the current cross-platform installers has a portable man-directory hook;
the built-in help remains available through every installation route.
Installing
From 0.1.0-alpha.3 onward each release carries prebuilt binaries, so a Rust
toolchain is not a prerequisite. Substitute the newest tag from the
releases page — the usual
releases/latest/download/… URL cannot be used yet, because GitHub does not
count a prerelease as the latest release.
$ curl --proto '=https' --tlsv1.2 -LsSf https://github.com/LucasAmion/wizlight-rs/releases/download/v0.1.0-beta.1/wizlight-installer.sh | sh
On Windows, in PowerShell:
> irm https://github.com/LucasAmion/wizlight-rs/releases/download/v0.1.0-beta.1/wizlight-installer.ps1 | iex
Or with Homebrew, on macOS and Linux:
$ brew install LucasAmion/tap/wizlight
Or, if you already have cargo-binstall,
which fetches the same prebuilt archives instead of compiling:
$ cargo binstall wizlight --version 0.1.0-beta.1
Binaries are built for macOS (Apple Silicon and Intel), Linux (x86-64 and
arm64) and Windows (x86-64). The Linux builds are statically linked against
musl, so they carry no glibc requirement and run on Alpine as happily as on
Debian. On a glibc system binstall looks for a gnu build first and falls back
to the musl one, so it finds these.
From source, with a Rust toolchain, the version has to be spelled out.
cargo install resolves *, and * does not match a prerelease, so the bare
form fails outright rather than finding the alpha — the same applies to
cargo binstall above, which resolves the version the same way:
$ cargo install wizlight
error: could not find `wizlight` in registry `crates-io` with version `*`
$ cargo install wizlight --version 0.1.0-beta.1
Plain cargo install wizlight starts working when 0.1.0 ships.
macOS: "cannot be verified"
Only if you download an archive from the releases page with a browser. The
warning comes from the com.apple.quarantine attribute, which browsers set and
curl, Homebrew and cargo do not — so the commands above never trigger it.
To clear it:
$ xattr -d com.apple.quarantine ./wizlight
Acknowledgements
pywizlight is the protocol reference and port source.
wiz-lights-rs informed the typed API shape. The behavior
recorded here is checked against captures and the local mock rather than assumed
to match either project.
Compatibility
- MSRV 1.85 (Rust 2024 edition)
- Tested on Linux, macOS and Windows
Licence
MIT — see LICENSE.