Expand description
§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
[dependencies]
wizlight = { version = "0.1.0-beta.1", default-features = 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 std::net::{IpAddr, Ipv4Addr};
use wizlight::protocol::{Channel, Dimming, PilotBuilder};
use wizlight::Bulb;
#[tokio::main]
async fn main() -> Result<(), wizlight::Error> {
let bulb = Bulb::connect(IpAddr::V4(Ipv4Addr::new(192, 168, 0, 5))).await?;
let pilot = bulb.get_pilot().await?;
println!("on={:?}, dimming={:?}", pilot.state, pilot.dimming);
bulb.set_pilot(
&PilotBuilder::new()
.rgb(Channel::new(255), Channel::new(80), Channel::new(0))
.dimming(Dimming::new(40)?),
)
.await?;
Ok(())
}Runnable versions live in examples/discover.rs and
examples/set_colour.rs:
$ cargo run --example discover
$ cargo run --example set_colour -- 192.168.0.5For 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 std::net::{IpAddr, Ipv4Addr};
use wizlight::{Bulb, Dimming, PilotBuilder};
let bulb = Bulb::connect(IpAddr::V4(Ipv4Addr::new(192, 168, 0, 5))).await?;
let stream = bulb.stream();
stream.send(&PilotBuilder::new().dimming(Dimming::new(40)?))?;
stream.send(&PilotBuilder::new().dimming(Dimming::new(60)?))?;
let counters = stream.shutdown().await;
println!("sent {}, coalesced {}", counters.sent, counters.coalesced);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 wizlight::protocol::{Channel, Kelvin, PilotBuilder};
let clash = PilotBuilder::new()
.rgb(Channel::new(255), Channel::new(0), Channel::new(0))
.temp(Kelvin::new(2700).expect("2700 K is in range"))
.set_pilot();
assert!(clash.is_err());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 wizlight::protocol::{BulbClass, Scene};
// Names are matched ignoring case and punctuation, so the spellings used by
// pywizlight, openHAB and WiZ's own docs all resolve.
let scene = Scene::from_name("deep-dive").expect("Deep dive is a scene");
assert_eq!(scene.id().get(), 23);
assert_eq!(scene.name(), "Deep dive");
// 39 scenes for a colour bulb, 17 for tunable white, 11 for dimmable white.
assert_eq!(Scene::for_class(BulbClass::Tw).count(), 17);
// 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!(scene.animates() && scene.adjustable().speed);
let wake_up = Scene::from_id(9).expect("9 is Wake up");
assert!(wake_up.animates() && !wake_up.adjustable().speed);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 wizlight::protocol::SceneId;
let first_custom_mode = SceneId::user_slot(1).expect("there are ten slots");
assert_eq!(first_custom_mode.get(), 256);
assert!(SceneId::new(37).is_err()); // really sets 2200 K
assert!(SceneId::new(100).is_err()); // really plays 41Bulbs 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 std::time::Duration;
use wizlight::Discovery;
#[tokio::main]
async fn main() -> Result<(), wizlight::Error> {
for bulb in Discovery::new().collect(Duration::from_secs(5)).await? {
println!("{} at {}", bulb.mac, bulb.addr);
}
Ok(())
}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 9877d5230f0aAddress 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:{"ok": true, "command": "status", "target": "9877d5230f0a", "result": {"state": true, "dimming": 100}} {"ok": false, "command": "status", "target": "9877d5230f0a", "error": "no reply from …"}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 | shOn Windows, in PowerShell:
> irm https://github.com/LucasAmion/wizlight-rs/releases/download/v0.1.0-beta.1/wizlight-installer.ps1 | iexOr with Homebrew, on macOS and Linux:
$ brew install LucasAmion/tap/wizlightOr, if you already have cargo-binstall,
which fetches the same prebuilt archives instead of compiling:
$ cargo binstall wizlight --version 0.1.0-beta.1Binaries 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.1Plain 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.
Re-exports§
pub use protocol::Adjustable;pub use protocol::BulbClass;pub use protocol::BulbData;pub use protocol::BulbType;pub use protocol::Category;pub use protocol::Channel;pub use protocol::Derivation;pub use protocol::DeviceError;pub use protocol::Devices;pub use protocol::Dimming;pub use protocol::Features;pub use protocol::Heads;pub use protocol::Kelvin;pub use protocol::KelvinRange;pub use protocol::ModelConfig;pub use protocol::ModuleName;pub use protocol::PULSE_SCENE_ID;pub use protocol::Pilot;pub use protocol::PilotBuilder;pub use protocol::PilotParams;pub use protocol::Power;pub use protocol::PulseDelta;pub use protocol::PulseParams;pub use protocol::Ratio;pub use protocol::Request;pub use protocol::Response;pub use protocol::Scene;pub use protocol::SceneId;pub use protocol::Speed;pub use protocol::Success;pub use protocol::SystemConfig;pub use protocol::UserConfig;
Modules§
- cli
- The
wizlightcommand-line interface (featurecli, on by default). - protocol
- The wire format: what goes into a datagram and what comes back.
Structs§
- Bulb
- One bulb, and the socket used to talk to it.
- Bulb
Stream - A non-blocking submission handle for real-time pilot updates.
- Discovered
- A bulb that answered a discovery broadcast.
- Discovery
- A discovery run, configured and then started.
- Discovery
Stream - Bulbs, as they answer.
- Push
Manager - Owns the shared UDP listener and its per-MAC subscription registry.
- Push
Subscription - A cancellable stream of push events for one MAC.
- Retry
Policy - How hard
Bulb::requesttries before giving up. - Stream
Config - Rate-limit settings for
Bulb::stream_with_config. - Stream
Counters - A snapshot of what a
BulbStreamhas done.
Enums§
- Error
- Everything
wizlightcan fail with. - Push
Event - One unsolicited message from a subscribed bulb.
- Push
Unavailable - A typed reason that push updates cannot be used.
Constants§
- BROADCAST
- Where discovery shouts by default: the all-subnets broadcast address, on the
standard
PORT. - DEFAULT_
INTERVAL - How often the registration goes out again, absent
Discovery::interval. - DEFAULT_
STREAM_ INTERVAL - The measured default gap between streamed frames: 200 ms, or 5 Hz.
- DEFAULT_
WAIT - A sensible span to run
Discovery::collectfor. - PORT
- The UDP port every WiZ device listens on.
- PUSH_
KEEPALIVE_ INTERVAL - How often an active subscription is renewed at its bulb.
- PUSH_
PORT - The UDP port WiZ bulbs send push updates to.