use std::fmt;
use std::str::FromStr;
use serde::{Serialize, Serializer};
use super::scene::Scene;
use crate::error::{Error, Result};
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize)]
pub enum BulbClass {
#[serde(rename = "RGB")]
Rgb,
#[serde(rename = "TW")]
Tw,
#[serde(rename = "DW")]
Dw,
#[serde(rename = "SOCKET")]
Socket,
#[serde(rename = "FANDIM")]
FanDim,
#[serde(rename = "FANTW")]
FanTw,
}
impl BulbClass {
#[must_use]
pub fn from_identifier(identifier: &str) -> Self {
if identifier.contains("RGB") {
Self::Rgb
} else if identifier.contains("DDTW") {
Self::FanTw
} else if identifier.contains("TW") {
Self::Tw
} else if identifier.contains("SOCKET") {
Self::Socket
} else if identifier.contains("FANDIM") {
Self::FanDim
} else {
Self::Dw
}
}
#[must_use]
pub const fn description(self) -> &'static str {
match self {
Self::Rgb => "RGB Tunable",
Self::Tw => "Tunable White",
Self::Dw => "Dimmable White",
Self::Socket => "Socket",
Self::FanDim => "Fan Dimmable",
Self::FanTw => "Fan Tunable White",
}
}
#[must_use]
pub const fn needs_kelvin_range(self) -> bool {
matches!(self, Self::Rgb | Self::Tw | Self::FanTw)
}
#[must_use]
pub const fn as_str(self) -> &'static str {
match self {
Self::Rgb => "RGB",
Self::Tw => "TW",
Self::Dw => "DW",
Self::Socket => "SOCKET",
Self::FanDim => "FANDIM",
Self::FanTw => "FANTW",
}
}
}
impl fmt::Display for BulbClass {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(self.as_str())
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize)]
pub enum Heads {
#[serde(rename = "SH")]
Single,
#[serde(rename = "DH")]
Dual,
}
impl Heads {
#[must_use]
pub fn from_identifier(identifier: &str) -> Option<Self> {
if identifier.contains("DH") {
Some(Self::Dual)
} else if identifier.contains("SH") {
Some(Self::Single)
} else {
None
}
}
#[must_use]
pub const fn count(self) -> u8 {
match self {
Self::Single => 1,
Self::Dual => 2,
}
}
}
#[derive(Clone, Debug, PartialEq, Eq, Hash)]
pub struct ModuleName(String);
impl ModuleName {
pub fn parse(name: &str) -> Result<Self> {
let identifier = name.split('_').nth(1).unwrap_or_default();
if identifier.is_empty() {
return Err(Error::UnknownModel {
message: format!(
"`{name}` is not a module name: expected <family>_<identifier>[_<revision>]"
),
});
}
Ok(Self(name.to_owned()))
}
#[must_use]
pub fn as_str(&self) -> &str {
&self.0
}
#[must_use]
pub fn family(&self) -> &str {
self.0.split('_').next().unwrap_or_default()
}
#[must_use]
pub fn identifier(&self) -> &str {
self.0.split('_').nth(1).unwrap_or_default()
}
#[must_use]
pub fn revision(&self) -> Option<&str> {
let rest = self.0.splitn(3, '_').nth(2)?;
(!rest.is_empty()).then_some(rest)
}
#[must_use]
pub fn class(&self) -> BulbClass {
BulbClass::from_identifier(self.identifier())
}
#[must_use]
pub fn heads(&self) -> Option<Heads> {
Heads::from_identifier(self.identifier())
}
}
impl FromStr for ModuleName {
type Err = Error;
fn from_str(name: &str) -> Result<Self> {
Self::parse(name)
}
}
impl fmt::Display for ModuleName {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(&self.0)
}
}
impl Serialize for ModuleName {
fn serialize<S: Serializer>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error> {
serializer.serialize_str(&self.0)
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize)]
pub struct KelvinRange {
min: u16,
max: u16,
}
impl KelvinRange {
#[must_use]
pub const fn new(min: u16, max: u16) -> Self {
if min <= max {
Self { min, max }
} else {
Self { min: max, max: min }
}
}
#[must_use]
pub const fn min(self) -> u16 {
self.min
}
#[must_use]
pub const fn max(self) -> u16 {
self.max
}
#[must_use]
pub const fn contains(self, kelvin: u16) -> bool {
self.min <= kelvin && kelvin <= self.max
}
}
impl fmt::Display for KelvinRange {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "{}-{} K", self.min, self.max)
}
}
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash, Serialize)]
pub struct Features {
pub color: bool,
pub color_tmp: bool,
pub effect: bool,
pub brightness: bool,
pub dual_head: bool,
pub fan: bool,
pub fan_breeze_mode: bool,
pub fan_reverse: bool,
}
impl Features {
#[must_use]
pub const fn for_class(class: BulbClass, dual_head: bool, effect: bool) -> Self {
let (color, color_tmp, brightness, fan) = match class {
BulbClass::Rgb => (true, true, true, false),
BulbClass::Tw => (false, true, true, false),
BulbClass::Dw => (false, false, true, false),
BulbClass::Socket => (false, false, false, false),
BulbClass::FanDim => (false, false, true, true),
BulbClass::FanTw => (false, true, true, true),
};
Self {
color,
color_tmp,
effect,
brightness,
dual_head,
fan,
fan_breeze_mode: fan,
fan_reverse: fan,
}
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum Derivation {
ModuleName,
KnownTypeId(u32),
AssumedTypeId(u32),
}
const fn class_for_type_id(type_id: u32) -> Option<BulbClass> {
match type_id {
0 => Some(BulbClass::Dw),
_ => None,
}
}
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub struct BulbData<'a> {
pub module_name: Option<&'a str>,
pub type_id: Option<u32>,
pub fw_version: Option<&'a str>,
pub kelvin_range: Option<KelvinRange>,
pub white_channels: Option<u32>,
pub white_to_color_ratio: Option<u32>,
pub fan_speed_range: Option<u32>,
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
#[non_exhaustive]
pub struct BulbType {
pub class: BulbClass,
pub features: Features,
pub module_name: Option<ModuleName>,
pub kelvin_range: Option<KelvinRange>,
pub fw_version: Option<String>,
pub white_channels: Option<u32>,
pub white_to_color_ratio: Option<u32>,
pub fan_speed_range: Option<u32>,
pub derivation: Derivation,
}
impl BulbType {
pub fn from_data(data: &BulbData<'_>) -> Result<Self> {
let name = data.module_name.filter(|name| !name.is_empty());
let (module_name, class, derivation) = match (name, data.type_id) {
(Some(name), _) => {
let module = ModuleName::parse(name)?;
let class = module.class();
(Some(module), class, Derivation::ModuleName)
}
(None, Some(type_id)) => match class_for_type_id(type_id) {
Some(class) => (None, class, Derivation::KnownTypeId(type_id)),
None => (None, BulbClass::Dw, Derivation::AssumedTypeId(type_id)),
},
(None, None) => {
return Err(Error::UnknownModel {
message: "the device reported neither a moduleName nor a typeId".to_owned(),
});
}
};
let heads = module_name.as_ref().and_then(ModuleName::heads);
let effect = match class {
BulbClass::Rgb | BulbClass::Tw | BulbClass::FanTw => true,
BulbClass::Socket | BulbClass::FanDim => false,
BulbClass::Dw => module_name.is_none() || heads.is_some(),
};
if data.kelvin_range.is_none() && class.needs_kelvin_range() {
return Err(Error::UnknownModel {
message: format!(
"a {} device must report a Kelvin range, and this one did not",
class.description()
),
});
}
Ok(Self {
class,
features: Features::for_class(class, heads == Some(Heads::Dual), effect),
module_name,
kelvin_range: data.kelvin_range,
fw_version: data.fw_version.map(ToOwned::to_owned),
white_channels: data.white_channels,
white_to_color_ratio: data.white_to_color_ratio,
fan_speed_range: data.fan_speed_range,
derivation,
})
}
pub fn scenes(&self) -> impl Iterator<Item = Scene> {
let class = self.class;
let table: &'static [Scene] = if self.features.effect {
Scene::all()
} else {
&[]
};
table
.iter()
.copied()
.filter(move |scene| scene.available_for(class))
}
}
#[cfg(test)]
mod tests {
use super::*;
const CORPUS: &[(&str, BulbClass, Option<Heads>, bool)] = {
use BulbClass::{Dw, FanDim, FanTw, Rgb, Socket, Tw};
use Heads::{Dual, Single};
&[
("ESP25_SHRGB_01", Rgb, Some(Single), true),
("ESP01_SHRGB_03", Rgb, Some(Single), true),
("ESP20_DHRGB_01", Rgb, Some(Dual), true),
("ESP20_DHRGB_01B", Rgb, Some(Dual), true),
("ESP20_SHRGB_01ABI", Rgb, Some(Single), true),
("ESP03_SHRGB3_01ABI", Rgb, Some(Single), true),
("ESP20_SHRGBC_01", Rgb, Some(Single), true),
("ESP20_SHRGB_01BT", Rgb, Some(Single), true),
("ESP01_SHRGB1C_31", Rgb, Some(Single), true),
("ESP21_SHTW_01", Tw, Some(Single), true),
("ESP05_SHTW_21", Tw, Some(Single), true),
("ESP14_SHTW1C_01", Tw, Some(Single), true),
("ESP05_SHDW_21", Dw, Some(Single), true),
("ESP06_SHDW9_01", Dw, Some(Single), true),
("ESP01_SHDW1C_31", Dw, Some(Single), true),
("ESP01_DIMTRIACS_01", Dw, None, false),
("ESP10_SOCKET_06", Socket, None, false),
("ESP25_SOCKET_01", Socket, None, false),
("ESP03_FANDIMS_31", FanDim, None, false),
("ESP03_DDTW_01", FanTw, None, true),
]
};
fn from_name(name: &str) -> BulbType {
BulbType::from_data(&BulbData {
module_name: Some(name),
kelvin_range: Some(KelvinRange::new(2200, 6500)),
..BulbData::default()
})
.expect("the corpus parses")
}
#[test]
fn every_known_module_name_derives_the_same_type_pywizlight_gives_it() {
for &(name, class, heads, effect) in CORPUS {
let bulb_type = from_name(name);
let module = bulb_type.module_name.as_ref().expect("a module name");
assert_eq!(module.class(), class, "{name}");
assert_eq!(module.heads(), heads, "{name}");
assert_eq!(bulb_type.class, class, "{name}");
assert_eq!(bulb_type.features.effect, effect, "{name}");
assert_eq!(
bulb_type.features.dual_head,
heads == Some(Heads::Dual),
"{name}"
);
assert_eq!(bulb_type.derivation, Derivation::ModuleName, "{name}");
assert_eq!(module.as_str(), name, "{name}");
}
}
#[test]
fn the_feature_map_matches_the_class() {
let rgb = from_name("ESP25_SHRGB_01").features;
assert_eq!(
rgb,
Features {
color: true,
color_tmp: true,
effect: true,
brightness: true,
dual_head: false,
fan: false,
fan_breeze_mode: false,
fan_reverse: false,
}
);
let tunable = from_name("ESP21_SHTW_01").features;
assert!(!tunable.color && tunable.color_tmp && tunable.brightness);
let dimmable = from_name("ESP05_SHDW_21").features;
assert!(!dimmable.color && !dimmable.color_tmp && dimmable.brightness);
let socket = from_name("ESP10_SOCKET_06").features;
assert!(!socket.brightness && !socket.effect);
let fan = from_name("ESP03_FANDIMS_31").features;
assert!(fan.fan && fan.fan_breeze_mode && fan.fan_reverse);
assert!(fan.brightness && !fan.color_tmp && !fan.effect);
let fan_tw = from_name("ESP03_DDTW_01").features;
assert!(fan_tw.fan && fan_tw.color_tmp && fan_tw.effect && !fan_tw.color);
}
#[test]
fn match_order_is_load_bearing() {
assert_eq!(BulbClass::from_identifier("SHRGB"), BulbClass::Rgb);
assert_eq!(BulbClass::from_identifier("DDTW"), BulbClass::FanTw);
assert_eq!(BulbClass::from_identifier("SHTW1C"), BulbClass::Tw);
assert_eq!(BulbClass::from_identifier("FANDIMS"), BulbClass::FanDim);
assert_eq!(BulbClass::from_identifier("SOCKET"), BulbClass::Socket);
assert_eq!(BulbClass::from_identifier("DIMTRIACS"), BulbClass::Dw);
}
#[test]
fn a_module_name_keeps_its_three_parts() {
let module = ModuleName::parse("ESP01_SHRGB1C_31").unwrap();
assert_eq!(module.family(), "ESP01");
assert_eq!(module.identifier(), "SHRGB1C");
assert_eq!(module.revision(), Some("31"));
let long = ModuleName::parse("ESP20_SHRGB_01_ABI").unwrap();
assert_eq!(long.revision(), Some("01_ABI"));
assert_eq!(long.to_string(), "ESP20_SHRGB_01_ABI");
let short = ModuleName::parse("ESP20_SHRGB").unwrap();
assert_eq!(short.revision(), None);
assert_eq!(short.class(), BulbClass::Rgb);
assert_eq!(ModuleName::parse("ESP20_SHRGB_").unwrap().revision(), None);
}
#[test]
fn a_name_with_no_identifier_is_refused() {
for name in ["INVALID", "", "_", "ESP20_"] {
let err = ModuleName::parse(name).expect_err("no identifier");
assert!(matches!(err, Error::UnknownModel { .. }), "{name}: {err}");
}
let err = BulbType::from_data(&BulbData {
module_name: Some("INVALID"),
..BulbData::default()
})
.expect_err("no identifier");
assert!(err.to_string().contains("INVALID"), "{err}");
}
#[test]
fn a_class_that_must_report_a_kelvin_range_and_does_not_is_an_error() {
for name in ["ESP21_SHTW_01", "ESP25_SHRGB_01", "ESP03_DDTW_01"] {
let err = BulbType::from_data(&BulbData {
module_name: Some(name),
..BulbData::default()
})
.expect_err("no kelvin range");
assert!(
err.to_string().contains("must report a Kelvin range"),
"{name}: {err}"
);
}
for name in ["ESP05_SHDW_21", "ESP10_SOCKET_06", "ESP03_FANDIMS_31"] {
let bulb_type = BulbType::from_data(&BulbData {
module_name: Some(name),
..BulbData::default()
})
.expect("no range needed");
assert_eq!(bulb_type.kelvin_range, None, "{name}");
}
}
#[test]
fn type_id_stands_in_for_a_missing_module_name() {
let known = BulbType::from_data(&BulbData {
type_id: Some(0),
fw_version: Some("1.8.0"),
white_channels: Some(1),
white_to_color_ratio: Some(20),
..BulbData::default()
})
.expect("typeId 0 is known");
assert_eq!(known.class, BulbClass::Dw);
assert_eq!(known.derivation, Derivation::KnownTypeId(0));
assert_eq!(known.module_name, None);
assert_eq!(known.kelvin_range, None);
assert!(known.features.effect && known.features.brightness);
assert!(!known.features.color && !known.features.color_tmp);
let assumed = BulbType::from_data(&BulbData {
type_id: Some(1),
..BulbData::default()
})
.expect("an unknown typeId still yields dimmable white");
assert_eq!(assumed.class, BulbClass::Dw);
assert_eq!(assumed.derivation, Derivation::AssumedTypeId(1));
let empty = BulbType::from_data(&BulbData {
module_name: Some(""),
type_id: Some(0),
..BulbData::default()
})
.expect("falls through to the typeId");
assert_eq!(empty.derivation, Derivation::KnownTypeId(0));
}
#[test]
fn a_device_with_neither_a_module_name_nor_a_type_id_is_unknowable() {
let err = BulbType::from_data(&BulbData::default()).expect_err("nothing to go on");
assert!(
err.to_string()
.contains("neither a moduleName nor a typeId"),
"{err}"
);
}
#[test]
fn the_measured_bulb_derives_what_the_hardware_does() {
let bulb_type = BulbType::from_data(&BulbData {
module_name: Some("ESP25_SHRGB_01"),
fw_version: Some("1.38.0"),
kelvin_range: Some(KelvinRange::new(2200, 6500)),
white_channels: Some(1),
white_to_color_ratio: Some(80),
..BulbData::default()
})
.expect("the bulb on the desk");
assert_eq!(bulb_type.class, BulbClass::Rgb);
assert_eq!(
bulb_type.kelvin_range,
Some(KelvinRange::new(2200, 6500)),
"the reported range, not the 1000-12000 the wire accepts"
);
assert_eq!(bulb_type.white_channels, Some(1));
assert_eq!(bulb_type.white_to_color_ratio, Some(80));
assert_eq!(bulb_type.fan_speed_range, None);
assert!(!bulb_type.features.dual_head);
}
#[test]
fn kelvin_range_orders_its_bounds_and_answers_what_it_covers() {
let range = KelvinRange::new(6500, 2200);
assert_eq!((range.min(), range.max()), (2200, 6500));
assert!(range.contains(2200) && range.contains(6500) && range.contains(4000));
assert!(!range.contains(2199) && !range.contains(6501));
assert_eq!(range.to_string(), "2200-6500 K");
}
#[test]
fn json_uses_the_names_the_protocol_uses() {
let bulb_type = from_name("ESP20_DHRGB_01");
let json = serde_json::to_value(&bulb_type).unwrap();
assert_eq!(json["class"], "RGB");
assert_eq!(json["module_name"], "ESP20_DHRGB_01");
assert_eq!(json["derivation"], "module_name");
assert_eq!(json["features"]["dual_head"], true);
assert_eq!(
json["kelvin_range"],
serde_json::json!({"min":2200,"max":6500})
);
let assumed = BulbType::from_data(&BulbData {
type_id: Some(7),
..BulbData::default()
})
.unwrap();
let json = serde_json::to_value(&assumed).unwrap();
assert_eq!(
json["derivation"],
serde_json::json!({"assumed_type_id": 7})
);
assert_eq!(json["module_name"], serde_json::Value::Null);
}
}