wizlight 0.1.0-beta.1

Async client for Philips WiZ smart bulbs over the local UDP protocol, plus the wizlight CLI
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
//! The scene table: which light modes exist, what they are called, how they
//! behave, and which devices can play them.
//!
//! A scene — WiZ calls them "light modes" — is an effect the bulb runs by
//! itself. One `setPilot` starts it and no further traffic is needed, which
//! makes it categorically different from driving colour frame by frame.
//!
//! # Where this table comes from
//!
//! Every id here was **written to an `ESP25_SHRGB_01` on fw 1.38.0 and read
//! back**, and the WiZ app was then walked through mode by mode with `getPilot`
//! polled throughout, so the vendor's own software supplied the names and the
//! grouping. That measurement is the authority for this module, and it
//! disagrees with every published source in at least one place.
//!
//! The bulb makes it measurable by reporting only the parameters that apply: a
//! running scene's `getPilot` carries `speed` if and only if its rate can be
//! set, and `dimming` if and only if its brightness can be. So
//! [`Adjustable`] is observed rather than transcribed, and it corrects
//! [WiZ's own light-mode table][pro] twice — that table claims an adjustable
//! speed for Cozy and Candlelight, and neither reports one. Cozy was confirmed
//! by eye to hold still. It also under-reports the undimmable scenes, flagging
//! only Night light where Wake up and Alarm ignore `dimming` too.
//!
//! # Two different questions
//!
//! [`Scene::animates`] and [`Adjustable::speed`] are not the same thing, and
//! conflating them is what the published sources do:
//!
//! - **Wake up** and **Bedtime** change over minutes, at a rate configured in
//!   the app. The WiZ app files them under their own heading, *Progresivo* —
//!   [`Category::Progressive`] here — and the bulb reports no `speed` for
//!   them. They animate; their rate is not ours to set.
//! - **Candlelight** and **Alarm** animate too, and likewise take no `speed`.
//! - Everything under [`Category::White`] and [`Category::Functional`] holds
//!   still.
//!
//! So hide a speed slider on [`Adjustable::speed`], and decide whether a scene
//! is "moving" with [`Scene::animates`].
//!
//! # What the sources got wrong
//!
//! - Ids **`38` and `39`** are real scenes that nothing in the ecosystem lists —
//!   static whites at 3500 K and 5000 K. The app does not offer them, and
//!   neither does `pywizlight`, openHAB or WiZ's own table. They are named
//!   **here and nowhere else**, Soft white and Crisp white, after where each
//!   was measured to sit. Both reach full brightness: alternated against their
//!   own colour temperatures at `dimming: 100`, neither is distinguishable.
//! - Id **`41` is a scene this crate refuses to send.** It renders a white of
//!   roughly 6200 K, but at `dimming: 100` it emits about a *third* of what
//!   every other white emits at `dimming: 100`. It honours `dimming`
//!   underneath that ceiling — pulsing it 100 to 10 is plainly visible — so the
//!   parameter is not ignored; the **scale** is simply not the same one, and a
//!   caller asking for full brightness quietly gets a third of it. See
//!   [`SceneId::new`]. It is still named on the way *in*, because `42..=248`
//!   all clamp onto it and a bulb can therefore be found sitting there.
//! - Id **`37` is not a scene.** Writing it is accepted and puts the bulb in
//!   colour-temperature mode, reporting `sceneId: 0, temp: 2200`. It is an
//!   alias for a CCT, so [`SceneId`] refuses it and says what to send instead.
//! - Ids **`42..=248` are accepted on `setPilot` and clamped to `41`**. They
//!   look valid — the bulb answers `success` — and do something no caller asked
//!   for, so [`SceneId`] refuses them too. `248` is the firmware's internal
//!   slot for [`Bulb::pulse`](crate::Bulb::pulse), reported alongside
//!   `"effect": "pulse"` in `getPilot` while a pulse is active, which explains
//!   why `setPilot`'s `sceneId` wire range check ends at `248`.
//! - The **user slots `256..=265` work**, contradicting an earlier measurement
//!   here that found `256` refused. The slot was simply empty: saving a custom
//!   mode in the app makes its id writable, and saving a second one makes `257`
//!   work while the rest stay refused. See [`SceneId::user_slot`].
//! - Per-class availability is the **one thing still unverified**, since only
//!   RGB hardware was on hand. It is [WiZ's table][pro] for ids `1..=33` and
//!   `pywizlight`'s for `34..=36` and `40`, and the two disagree about
//!   dimmable white — see [`Scene::available_for`]. `38`, `39` and `41` are
//!   marked colour-only because that is the only class they were seen on.
//!
//! [pro]: https://docs.pro.wizconnected.com/#light-modes

use std::fmt;
use std::str::FromStr;

use serde::Serialize;

use super::model::BulbClass;
use super::types::SceneId;
use crate::error::{Error, Result};

/// How a scene behaves, as the WiZ app groups its light modes.
///
/// Taken from the app's own headings, which are the only source that separates
/// a scene that animates from one whose rate can be set. The four scenes the
/// app does not offer are grouped by what they were measured to do.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum Category {
    /// A static white. Most report the colour temperature they run at; see
    /// [`Scene::kelvin`].
    White,
    /// A static scene for a purpose — reading, watching television, growing
    /// plants.
    Functional,
    /// Changes over minutes, at a rate set in the WiZ app rather than by
    /// `speed`. Wake up and Bedtime.
    Progressive,
    /// An animation. Most, but not all, take a `speed`.
    Dynamic,
}

/// Which pilot parameters a scene responds to.
///
/// Measured, not documented: the bulb reports a parameter in `getPilot` if and
/// only if the running scene uses it. A parameter that does not apply is still
/// **accepted with `success` and silently discarded**, which is why this is
/// worth knowing before sending one.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize)]
pub struct Adjustable {
    /// `speed` sets the animation rate.
    ///
    /// False for every static scene, and also for the animating ones whose rate
    /// is not exposed: Wake up, Bedtime, Candlelight and Alarm.
    pub speed: bool,
    /// `dimming` sets the brightness while the scene runs.
    ///
    /// False for Wake up, Night light and Alarm, which drive their own
    /// brightness. Anything modulating brightness underneath a scene has to
    /// avoid those three: the packets are accepted and nothing changes.
    pub dimming: bool,
}

/// One entry in the scene table: a light mode the bulb can play by itself.
///
/// Looked up by id with [`Scene::from_id`] or by name with
/// [`Scene::from_name`], listed for a class with [`Scene::for_class`], and the
/// whole table is [`Scene::all`]. Nothing here needs a bulb, or a network.
///
/// ```
/// use wizlight::protocol::{BulbClass, Category, Scene};
///
/// let scene: Scene = "deep-dive".parse()?;
/// assert_eq!(scene.id().get(), 23);
/// assert_eq!(scene.name(), "Deep dive");
/// assert_eq!(scene.category(), Category::Dynamic);
/// assert!(scene.animates() && scene.adjustable().speed);
/// // A colour animation, so nothing without RGB emitters can play it.
/// assert!(!scene.available_for(BulbClass::Tw));
///
/// // Wake up animates too, but its rate is set in the app, not by us.
/// let wake_up = Scene::from_id(9).expect("9 is Wake up");
/// assert!(wake_up.animates() && !wake_up.adjustable().speed);
/// # Ok::<(), wizlight::Error>(())
/// ```
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize)]
pub struct Scene {
    id: u16,
    name: &'static str,
    category: Category,
    /// The colour temperature the bulb reports while it runs, where it reports
    /// one.
    kelvin: Option<u16>,
    /// Which classes can play it, as `RGB` / `TW` / `DW` bits. Not serialised:
    /// a caller with a bulb has already filtered by class, and one without has
    /// [`Scene::available_for`].
    #[serde(skip)]
    classes: u8,
    adjustable: Adjustable,
}

/// Playable by full-colour devices.
const RGB: u8 = 1 << 0;
/// Playable by tunable white devices, and by the tunable-white fans.
const TW: u8 = 1 << 1;
/// Playable by dimmable white devices.
const DW: u8 = 1 << 2;

/// Takes both `speed` and `dimming`.
const PACED: Adjustable = Adjustable {
    speed: true,
    dimming: true,
};
/// Takes `dimming` only — either static, or animating at a rate it owns.
const DIMMABLE: Adjustable = Adjustable {
    speed: false,
    dimming: true,
};
/// Takes neither. Wake up, Night light and Alarm.
const FIXED: Adjustable = Adjustable {
    speed: false,
    dimming: false,
};

/// The table, in id order.
///
/// Note the two gaps. `37` is not a scene at all, and `41` is one the bulb
/// plays but this crate will not send — both are refused by [`SceneId`], which
/// explains why. See the [module docs](self).
const SCENES: &[Scene] = &[
    Scene::new(1, "Ocean", Category::Dynamic, RGB, PACED),
    Scene::new(2, "Romance", Category::Dynamic, RGB, PACED),
    Scene::new(3, "Sunset", Category::Dynamic, RGB, PACED),
    Scene::new(4, "Party", Category::Dynamic, RGB, PACED),
    Scene::new(5, "Fireplace", Category::Dynamic, RGB, PACED),
    // WiZ's table says this one takes a speed. It does not, and it holds still.
    Scene::new(6, "Cozy", Category::Functional, RGB | TW, DIMMABLE),
    Scene::new(7, "Forest", Category::Dynamic, RGB, PACED),
    Scene::new(8, "Pastel colors", Category::Dynamic, RGB, PACED),
    Scene::new(9, "Wake up", Category::Progressive, RGB | TW | DW, FIXED),
    Scene::new(
        10,
        "Bedtime",
        Category::Progressive,
        RGB | TW | DW,
        DIMMABLE,
    ),
    Scene::white(11, "Warm white", 2700, RGB | TW),
    Scene::white(12, "Daylight", 4200, RGB | TW),
    Scene::white(13, "Cool white", 6500, RGB | TW | DW),
    Scene::new(
        14,
        "Night light",
        Category::Functional,
        RGB | TW | DW,
        FIXED,
    ),
    Scene::new(15, "Focus", Category::Functional, RGB | TW, DIMMABLE),
    Scene::new(16, "Relax", Category::Functional, RGB | TW, DIMMABLE),
    Scene::new(17, "True colors", Category::Functional, RGB, DIMMABLE),
    Scene::new(18, "TV time", Category::Functional, RGB | TW, DIMMABLE),
    Scene::new(19, "Plant growth", Category::Functional, RGB, DIMMABLE),
    Scene::new(20, "Spring", Category::Dynamic, RGB, PACED),
    Scene::new(21, "Summer", Category::Dynamic, RGB, PACED),
    Scene::new(22, "Fall", Category::Dynamic, RGB, PACED),
    Scene::new(23, "Deep dive", Category::Dynamic, RGB, PACED),
    Scene::new(24, "Jungle", Category::Dynamic, RGB, PACED),
    Scene::new(25, "Mojito", Category::Dynamic, RGB, PACED),
    Scene::new(26, "Club", Category::Dynamic, RGB, PACED),
    Scene::new(27, "Christmas", Category::Dynamic, RGB, PACED),
    Scene::new(28, "Halloween", Category::Dynamic, RGB, PACED),
    // Animates, but the rate is not exposed — WiZ's table says otherwise.
    Scene::new(
        29,
        "Candlelight",
        Category::Dynamic,
        RGB | TW | DW,
        DIMMABLE,
    ),
    Scene::new(30, "Golden white", Category::Dynamic, RGB | TW | DW, PACED),
    Scene::new(31, "Pulse", Category::Dynamic, RGB | TW | DW, PACED),
    Scene::new(32, "Steampunk", Category::Dynamic, RGB | TW | DW, PACED),
    Scene::new(33, "Diwali", Category::Dynamic, RGB | TW | DW, PACED),
    Scene::white(34, "White", 4000, RGB | DW),
    Scene::new(35, "Alarm", Category::Dynamic, RGB | TW | DW, FIXED),
    Scene::new(36, "Snowy sky", Category::Dynamic, RGB, PACED),
    // 37 is not a scene: it writes a 2200 K colour temperature.
    // 38, 39 and 41 are named here and nowhere else — see `Scene::name`.
    Scene::white(38, "Soft white", 3500, RGB),
    Scene::white(39, "Crisp white", 5000, RGB),
    Scene::new(40, "Dim-to-warm", Category::White, RGB | TW, DIMMABLE),
    // 41 is deliberately absent, though the bulb plays it: its brightness scale
    // does not match anything else's. See `SceneId::new`.
];

impl Scene {
    const fn new(
        id: u16,
        name: &'static str,
        category: Category,
        classes: u8,
        adjustable: Adjustable,
    ) -> Self {
        Self {
            id,
            name,
            category,
            kelvin: None,
            classes,
            adjustable,
        }
    }

    /// A static white that reports the temperature it runs at.
    const fn white(id: u16, name: &'static str, kelvin: u16, classes: u8) -> Self {
        Self {
            id,
            name,
            category: Category::White,
            kelvin: Some(kelvin),
            classes,
            adjustable: DIMMABLE,
        }
    }

    /// Every scene this crate knows, in id order.
    ///
    /// The table is a `const`, so a scene picker can be built with no bulb
    /// connected and nothing to await.
    #[must_use]
    pub const fn all() -> &'static [Self] {
        SCENES
    }

    /// The scene with this id, or `None` if the table does not name one.
    ///
    /// This is the read-side lookup, for naming the `sceneId` in a
    /// [`Pilot`](super::Pilot). It takes a plain `u16` for that reason — a bulb
    /// reports ids that are not scenes, including `0` for "no scene, colour is
    /// active" and `256..=265` for a custom mode made in the app.
    #[must_use]
    pub fn from_id(id: u16) -> Option<Self> {
        SCENES.iter().copied().find(|scene| scene.id == id)
    }

    /// The scene with this name, matched leniently.
    ///
    /// Case is ignored, and so is anything that is not a letter or a digit, so
    /// `Deep dive`, `deep-dive` and `DEEPDIVE` are the same scene. That also
    /// makes the other spellings in the ecosystem resolve —
    /// `pywizlight`'s `Wake-up` and `Plantgrowth`, openHAB's `Bed Time` — which
    /// is why the rule strips separators instead of canonicalising them.
    ///
    /// # Errors
    ///
    /// Returns [`Error::UnknownScene`] if no scene matches.
    pub fn from_name(name: &str) -> Result<Self> {
        SCENES
            .iter()
            .copied()
            .find(|scene| normalised(scene.name).eq(normalised(name)))
            .ok_or_else(|| Error::UnknownScene {
                message: format!(
                    "no scene is called `{name}`; names are matched ignoring case, spaces \
                     and punctuation"
                ),
            })
    }

    /// Every scene a device of `class` can play, in id order.
    ///
    /// This is the class's table, not a given device's: a dimmable white
    /// *module* plays these, while a `DIMTRIACS` wall switch of the same class
    /// plays nothing. [`BulbType::scenes`](super::BulbType::scenes) is the one
    /// that knows the difference.
    pub fn for_class(class: BulbClass) -> impl Iterator<Item = Self> {
        SCENES
            .iter()
            .copied()
            .filter(move |scene| scene.available_for(class))
    }

    /// Its id, ready to be sent.
    #[must_use]
    pub const fn id(self) -> SceneId {
        // Every entry in the table is by definition a scene the table names,
        // which is what `SceneId` checks.
        SceneId::new_unchecked(self.id)
    }

    /// Its display name.
    ///
    /// Every name is WiZ's own, taken from the app, **except two**. `38` and
    /// `39` are real scenes that no documentation, no library and not even the
    /// WiZ app gives a name to, so they are called **Soft white** (3500 K) and
    /// **Crisp white** (5000 K) — descriptions of where they were measured to
    /// sit, not names anyone else will recognise. Match on
    /// [`id`](Scene::id) if that distinction matters.
    #[must_use]
    pub const fn name(self) -> &'static str {
        self.name
    }

    /// How it behaves, as the WiZ app groups its light modes.
    #[must_use]
    pub const fn category(self) -> Category {
        self.category
    }

    /// Whether the light changes over time.
    ///
    /// **Not the same as [`Adjustable::speed`]**: Wake up, Bedtime, Candlelight
    /// and Alarm all animate without taking a `speed`. Use this to decide
    /// whether a scene is "moving", and `adjustable().speed` to decide whether
    /// to offer a rate control.
    #[must_use]
    pub const fn animates(self) -> bool {
        matches!(self.category, Category::Dynamic | Category::Progressive)
    }

    /// Which parameters it responds to.
    #[must_use]
    pub const fn adjustable(self) -> Adjustable {
        self.adjustable
    }

    /// The colour temperature the bulb reports while this scene runs.
    ///
    /// Only the whites report one, and not even all of them — `41` renders
    /// white and reports nothing, and Dim-to-warm varies its own temperature by
    /// brightness, which is the whole point of it.
    #[must_use]
    pub const fn kelvin(self) -> Option<u16> {
        self.kelvin
    }

    /// Whether a device of `class` can play it.
    ///
    /// **The one part of this module that is not measured.** Only colour
    /// hardware was available, so the tunable-white and dimmable-white lists
    /// are inherited: [WiZ's own table][pro] for `1..=33`, `pywizlight` for
    /// `34..=36` and `40`. The two agree exactly on tunable white and disagree
    /// on dimmable white, where WiZ also lists Cool white, Golden white and
    /// Diwali; WiZ is followed here, though its prose contradicts its own
    /// table. Soft white and Crisp white are reported colour-only because that
    /// is the only class they have been seen on, not because anything says so.
    ///
    /// Sockets and dimmable fans play nothing. A tunable-white fan gets the
    /// tunable-white list, since its light is one — `pywizlight` returns
    /// nothing for either kind of fan, which looks like an omission in its
    /// table rather than a fact about the hardware.
    ///
    /// [pro]: https://docs.pro.wizconnected.com/#light-modes
    #[must_use]
    pub const fn available_for(self, class: BulbClass) -> bool {
        let bit = match class {
            BulbClass::Rgb => RGB,
            BulbClass::Tw | BulbClass::FanTw => TW,
            BulbClass::Dw => DW,
            BulbClass::Socket | BulbClass::FanDim => return false,
        };
        self.classes & bit != 0
    }
}

impl FromStr for Scene {
    type Err = Error;

    fn from_str(name: &str) -> Result<Self> {
        Self::from_name(name)
    }
}

impl fmt::Display for Scene {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(self.name)
    }
}

impl From<Scene> for SceneId {
    fn from(scene: Scene) -> Self {
        scene.id()
    }
}

/// A name reduced to what matching cares about: letters and digits, lowercased.
fn normalised(name: &str) -> impl Iterator<Item = char> + '_ {
    name.chars()
        .filter(|c| c.is_alphanumeric())
        .map(|c| c.to_ascii_lowercase())
}

#[cfg(test)]
mod tests {
    use super::*;

    /// The shape of the table, and the two gaps that are the whole story: `37`
    /// is not a scene at all, and `41` is one the bulb plays but the crate will
    /// not send.
    #[test]
    fn the_table_covers_the_scenes_worth_sending() {
        let ids: Vec<u16> = Scene::all().iter().map(|s| s.id().get()).collect();
        let expected: Vec<u16> = (1..=36).chain(38..=40).collect();
        assert_eq!(ids, expected);
    }

    #[test]
    fn per_class_counts() {
        assert_eq!(Scene::for_class(BulbClass::Rgb).count(), 39);
        assert_eq!(Scene::for_class(BulbClass::Tw).count(), 17);
        assert_eq!(Scene::for_class(BulbClass::Dw).count(), 11);
        // A tunable-white fan is a tunable-white light with a fan attached.
        assert_eq!(Scene::for_class(BulbClass::FanTw).count(), 17);
        assert_eq!(Scene::for_class(BulbClass::Socket).count(), 0);
        assert_eq!(Scene::for_class(BulbClass::FanDim).count(), 0);
    }

    /// `pywizlight`'s `TW_SCENES` is the one availability list two sources
    /// agree on, so it is pinned id by id rather than by count.
    #[test]
    fn the_tunable_white_list_is_the_one_both_sources_agree_on() {
        let tw: Vec<u16> = Scene::for_class(BulbClass::Tw)
            .map(|scene| scene.id().get())
            .collect();
        assert_eq!(
            tw,
            [
                6, 9, 10, 11, 12, 13, 14, 15, 16, 18, 29, 30, 31, 32, 33, 35, 40
            ]
        );
    }

    /// WiZ's DW column, plus `34` and `35` from `pywizlight`. The three ids
    /// `pywizlight` leaves out — `13`, `30`, `33` — are the divergence, and this
    /// test is where it is visible.
    #[test]
    fn the_dimmable_white_list_follows_the_vendor_table() {
        let dw: Vec<u16> = Scene::for_class(BulbClass::Dw)
            .map(|scene| scene.id().get())
            .collect();
        assert_eq!(dw, [9, 10, 13, 14, 29, 30, 31, 32, 33, 34, 35]);
    }

    #[test]
    fn ids_and_names_round_trip() {
        for scene in Scene::all() {
            assert_eq!(Scene::from_id(scene.id().get()), Some(*scene));
            assert_eq!(Scene::from_name(scene.name()).unwrap(), *scene);
            assert_eq!(scene.to_string(), scene.name());
        }
    }

    #[test]
    fn names_are_unique() {
        for scene in Scene::all() {
            let clashes = Scene::all()
                .iter()
                .filter(|other| normalised(other.name()).eq(normalised(scene.name())))
                .count();
            assert_eq!(clashes, 1, "`{scene}` is not a unique name");
        }
    }

    /// Two names are ours rather than WiZ's, and they are the ones a reader is
    /// most likely to mistake for official. Pinned so that renaming one is a
    /// deliberate act.
    #[test]
    fn the_two_scenes_nobody_names_are_labelled_by_us() {
        let ours = [(38, "Soft white"), (39, "Crisp white")];
        for (id, name) in ours {
            let scene = Scene::from_id(id).unwrap();
            assert_eq!(scene.name(), name);
            assert_eq!(scene.category(), Category::White);
            // Named after where they sit, so they have to be findable that way.
            assert_eq!(Scene::from_name(name).unwrap().id().get(), id);
        }
        // 41 would have been the third, and is deliberately absent: the bulb
        // plays it, but at a third of every other scene's brightness.
        assert_eq!(Scene::from_id(41), None);
    }

    #[test]
    fn names_are_matched_leniently() {
        let deep_dive = Scene::from_id(23).unwrap();
        for spelling in [
            "Deep dive",
            "deep dive",
            "deep-dive",
            "DEEPDIVE",
            "Deep_Dive",
        ] {
            assert_eq!(Scene::from_name(spelling).unwrap(), deep_dive, "{spelling}");
        }

        // The spellings the rest of the ecosystem uses have to resolve, since
        // they are what a user reads elsewhere and types at us.
        for (spelling, id) in [
            ("Wake-up", 9),      // pywizlight
            ("Plantgrowth", 19), // pywizlight
            ("TV time", 18),
            ("Dim-to-warm", 40),
            ("Bed Time", 10), // openHAB
            ("Wakeup", 9),    // openHAB
            ("Deepdive", 23), // Adafruit
            ("Pastel Colors", 8),
        ] {
            assert_eq!(
                Scene::from_name(spelling).unwrap().id().get(),
                id,
                "{spelling}"
            );
        }
    }

    #[test]
    fn an_unknown_name_names_itself_in_the_error() {
        let err = Scene::from_name("Cozy Whitest").unwrap_err();
        assert!(
            matches!(&err, Error::UnknownScene { message } if message.contains("`Cozy Whitest`")),
            "{err}"
        );
    }

    #[test]
    fn ids_that_are_not_scenes_are_none() {
        // 0 means "no scene" on a read; 37 writes a colour temperature rather
        // than a scene; 41 is played by the bulb but not offered here; 42 and
        // up clamp onto 41; 256 is a user slot; 1000 was Rhythm.
        for id in [0, 37, 41, 42, 100, 248, 256, 265, 1000] {
            assert_eq!(Scene::from_id(id), None, "{id}");
        }
    }

    /// Animating and taking a `speed` are different questions, and the four
    /// scenes where they differ are the reason both exist.
    #[test]
    fn animating_is_not_the_same_as_taking_a_speed() {
        let animates_without_a_speed = [9, 10, 29, 35];
        for id in animates_without_a_speed {
            let scene = Scene::from_id(id).unwrap();
            assert!(scene.animates(), "{scene} should animate");
            assert!(!scene.adjustable().speed, "{scene} should take no speed");
        }

        let party = Scene::from_id(4).unwrap();
        assert!(party.animates() && party.adjustable().speed);

        // Measured: WiZ's table claims a speed for Cozy, the bulb reports none,
        // and the light was watched holding still.
        let cozy = Scene::from_id(6).unwrap();
        assert_eq!(cozy.category(), Category::Functional);
        assert!(!cozy.animates() && !cozy.adjustable().speed);
    }

    /// Wake up, Night light and Alarm swallow `dimming`. Anything modulating
    /// brightness under a scene has to know.
    #[test]
    fn the_undimmable_scenes_are_the_measured_three() {
        let undimmable: Vec<u16> = Scene::all()
            .iter()
            .filter(|scene| !scene.adjustable().dimming)
            .map(|scene| scene.id().get())
            .collect();
        assert_eq!(undimmable, [9, 14, 35]);
    }

    #[test]
    fn the_whites_report_the_temperature_they_run_at() {
        let ladder: Vec<(u16, u16)> = Scene::all()
            .iter()
            .filter_map(|scene| Some((scene.id().get(), scene.kelvin()?)))
            .collect();
        assert_eq!(
            ladder,
            [
                (11, 2700),
                (12, 4200),
                (13, 6500),
                (34, 4000),
                (38, 3500),
                (39, 5000)
            ]
        );

        // Every scene reporting a temperature is a white, but not every white
        // reports one: Dim-to-warm varies its own, and 41 reports nothing.
        for scene in Scene::all().iter().filter(|s| s.kelvin().is_some()) {
            assert_eq!(scene.category(), Category::White, "{scene}");
        }
        // Dim-to-warm varies its own temperature by brightness, which is the
        // whole point of it, so it reports none.
        assert_eq!(Scene::from_id(40).unwrap().kelvin(), None);
    }

    #[test]
    fn a_scene_serialises_as_its_id_name_and_behaviour() {
        let json = serde_json::to_value(Scene::from_id(23).unwrap()).unwrap();
        assert_eq!(
            json,
            serde_json::json!({
                "id": 23,
                "name": "Deep dive",
                "category": "dynamic",
                "kelvin": null,
                "adjustable": {"speed": true, "dimming": true},
            })
        );
    }
}