Merge pull request #105 from chrivers/chrivers/hue-crate-entertainment-mode

This pull request implements the necessary code in the hue crate, to support decoding and encoding of Hue Entertainment Mode (also known as "Sync mode").

There are two major new areas of support:
 - Encoding and decoding the DTLS stream going to the bridge (from a sync client)
 - Encoding and decoding the specialized Zigbee frames going from the bridge, to the lights.

Especially the latter part builds on the previous work done by the Bifrost project, to reverse engineer the Hue Entertainment zigbee format.

This pull request does not in itself add entertainment mode support to the Bifrost bridge. It only adds required library code needed to implement that support in an upcoming pull request.

Author: chrivers

Cargo.lock

@@ -18,6 +18,11 @@ workspace = true
 [dependencies]
 bitflags = "2.8.0"
 byteorder = "1.5.0"
+chrono = { version = "0.4.39", default-features = false }
 packed_struct = "0.10.1"
 serde = { version = "1.0.217", features = ["derive"] }
 thiserror = "2.0.11"
+uuid = "1.13.1"
+
+[dev-dependencies]
+hex = "0.4.3"

crates/hue/Cargo.toml

@@ -4,27 +4,121 @@
 //
 // Original code by Thomas Lochmatter
 
+use std::ops::{Index, IndexMut};
+
 use crate::gamma::GammaCorrection;
 
-pub struct ColorSpace {
-    rgb: [f64; 9],
-    xyz: [f64; 9],
-    gamma: GammaCorrection,
-}
+#[derive(Clone, Debug)]
+pub struct Matrix3(pub [f64; 3 * 3]);
+
+impl Matrix3 {
+    #[must_use]
+    pub const fn identity() -> Self {
+        Self([
+            1.0, 0.0, 0.0, //
+            0.0, 1.0, 0.0, //
+            0.0, 0.0, 1.0, //
+        ])
+    }
+
+    #[must_use]
+    pub fn inverted(&self) -> Option<Self> {
+        let mut current = self.clone();
+        let mut inverse = Self::identity();
+
+        // Gaussian elimination (part 1)
+        for i in 0..3 {
+            // Get the diagonal term
+            let mut d = current[[i, i]];
+
+            // If it is 0, there must be at least one row with a non-zero element (otherwise, the matrix is not invertible)
+            if d == 0.0 {
+                let mut r = i + 1;
+
+                while r < 3 && (current[[r, i]]).abs() < 1e-10 {
+                    r += 1;
+                }
+
+                if r == 3 {
+                    return None;
+                } // i is the rank
+
+                for c in 0..3 {
+                    current[[i, c]] += current[[r, c]];
+                    inverse[[i, c]] += inverse[[r, c]];
+                }
+
+                d = current[[i, i]];
+            }
+
+            // Divide the row by the diagonal term
+            let inv = 1.0 / d;
+            for c in 0..3 {
+                current[[i, c]] *= inv;
+                inverse[[i, c]] *= inv;
+            }
+
+            // Divide all subsequent rows with a non-zero coefficient, and subtract the row
+            for r in i + 1..3 {
+                let p = current.0[r * 3 + i];
+                if p != 0.0 {
+                    for c in 0..3 {
+                        current[[r, c]] -= current[[i, c]] * p;
+                        inverse[[r, c]] -= inverse[[i, c]] * p;
+                    }
+                }
+            }
+        }
+
+        // Gaussian elimination (part 2)
+        for i in (0..3).rev() {
+            for r in 0..i {
+                let d = current[[r, i]];
+                for c in 0..3 {
+                    current[[r, c]] -= current[[i, c]] * d;
+                    inverse[[r, c]] -= inverse[[i, c]] * d;
+                }
+            }
+        }
+
+        Some(inverse)
+    }
 
-impl ColorSpace {
     #[allow(clippy::suboptimal_flops)]
     #[must_use]
-    fn mult(d: [f64; 3], m: &[f64; 9]) -> [f64; 3] {
+    fn mult(&self, d: [f64; 3]) -> [f64; 3] {
+        let m = self.0;
         let cx = d[0] * m[0] + d[1] * m[1] + d[2] * m[2];
         let cy = d[0] * m[3] + d[1] * m[4] + d[2] * m[5];
         let cz = d[0] * m[6] + d[1] * m[7] + d[2] * m[8];
         [cx, cy, cz]
     }
+}
+
+impl Index<[usize; 2]> for Matrix3 {
+    type Output = f64;
+
+    fn index(&self, index: [usize; 2]) -> &Self::Output {
+        &self.0[index[0] * 3 + index[1]]
+    }
+}
 
+impl IndexMut<[usize; 2]> for Matrix3 {
+    fn index_mut(&mut self, index: [usize; 2]) -> &mut Self::Output {
+        &mut self.0[index[0] * 3 + index[1]]
+    }
+}
+
+pub struct ColorSpace {
+    rgb: Matrix3,
+    xyz: Matrix3,
+    gamma: GammaCorrection,
+}
+
+impl ColorSpace {
     #[must_use]
     pub fn xyz_to_rgb(&self, x: f64, y: f64, z: f64) -> [f64; 3] {
-        Self::mult([x, y, z], &self.rgb).map(|q| self.gamma.transform(q))
+        self.rgb.mult([x, y, z]).map(|q| self.gamma.transform(q))
     }
 
     #[allow(non_snake_case)]
@@ -36,7 +130,7 @@ impl ColorSpace {
 
     #[must_use]
     pub fn rgb_to_xyz(&self, r: f64, g: f64, b: f64) -> [f64; 3] {
-        Self::mult([r, g, b].map(|q| self.gamma.inverse(q)), &self.xyz)
+        self.xyz.mult([r, g, b].map(|q| self.gamma.inverse(q)))
     }
 
     #[allow(clippy::many_single_char_names)]
@@ -74,45 +168,92 @@ impl ColorSpace {
 
 /// Wide gamut color space
 pub const WIDE: ColorSpace = ColorSpace {
-    rgb: [
+    rgb: Matrix3([
         1.4625, -0.1845, -0.2734, //
-        -0.5228, 1.4479, 0.0681, //
+        -0.5229, 1.4479, 0.0681, //
         0.0346, -0.0958, 1.2875, //
-    ],
-    xyz: [
+    ]),
+    xyz: Matrix3([
         0.7164, 0.1010, 0.1468, //
         0.2587, 0.7247, 0.0166, //
         0.0000, 0.0512, 0.7740, //
-    ],
+    ]),
     gamma: GammaCorrection::NONE,
 };
 
 /// sRGB color space
 pub const SRGB: ColorSpace = ColorSpace {
-    rgb: [
-        3.2405, -1.5371, -0.4985, //
-        -0.9693, 1.8760, 0.0416, //
-        0.0556, -0.2040, 1.0572, //
-    ],
-    xyz: [
+    rgb: Matrix3([
+        3.2401, -1.5370, -0.4983, //
+        -0.9693, 1.8760, 0.0415, //
+        0.0558, -0.2040, 1.0572, //
+    ]),
+    xyz: Matrix3([
         0.4125, 0.3576, 0.1804, //
         0.2127, 0.7152, 0.0722, //
         0.0193, 0.1192, 0.9503, //
-    ],
+    ]),
     gamma: GammaCorrection::SRGB,
 };
 
 /// Adobe RGB color space
 pub const ADOBE: ColorSpace = ColorSpace {
-    rgb: [
+    rgb: Matrix3([
         2.0416, -0.5652, -0.3447, //
         -0.9695, 1.8763, 0.0415, //
         0.0135, -0.1184, 1.0154, //
-    ],
-    xyz: [
+    ]),
+    xyz: Matrix3([
         0.5767, 0.1856, 0.1882, //
         0.2974, 0.6273, 0.0753, //
         0.0270, 0.0707, 0.9911, //
-    ],
+    ]),
     gamma: GammaCorrection::NONE,
 };
+
+#[cfg(test)]
+mod tests {
+    use std::iter::zip;
+
+    use crate::colorspace::{ColorSpace, ADOBE, SRGB, WIDE};
+
+    macro_rules! compare {
+        ($expr:expr, $value:expr) => {
+            let a = $expr;
+            let b = $value;
+            eprintln!("{a} vs {b:.4}");
+            assert!((a - b).abs() < 1e-4);
+        };
+    }
+
+    fn verify_matrix(cs: &ColorSpace) {
+        let xyz = &cs.xyz;
+        let rgb = &cs.rgb;
+
+        let xyzi = xyz.inverted().unwrap();
+        let rgbi = rgb.inverted().unwrap();
+
+        zip(xyz.0, rgbi.0).for_each(|(a, b)| {
+            compare!(a, b);
+        });
+
+        zip(rgb.0, xyzi.0).for_each(|(a, b)| {
+            compare!(a, b);
+        });
+    }
+
+    #[test]
+    fn iverse_wide() {
+        verify_matrix(&WIDE);
+    }
+
+    #[test]
+    fn iverse_srgb() {
+        verify_matrix(&SRGB);
+    }
+
+    #[test]
+    fn iverse_adobe() {
+        verify_matrix(&ADOBE);
+    }
+}

crates/hue/src/colorspace.rs

@@ -15,6 +15,12 @@ pub enum HueError {
     #[error(transparent)]
     PackedStructError(#[from] packed_struct::PackingError),
 
+    #[error(transparent)]
+    UuidError(#[from] uuid::Error),
+
+    #[error("Bad header in hue entertainment stream")]
+    HueEntertainmentBadHeader,
+
     #[error("Failed to decode Hue Zigbee Update")]
     HueZigbeeDecodeError,
 

crates/hue/src/error.rs

@@ -59,3 +59,47 @@ impl GammaCorrection {
     /// Standard gamma correction for sRGB color space
     pub const SRGB: Self = Self::new(0.42, 0.003_130_8, 12.92, 0.055);
 }
+
+#[cfg(test)]
+mod tests {
+    use crate::gamma::GammaCorrection;
+
+    macro_rules! compare {
+        ($expr:expr, $value:expr) => {
+            assert!(($expr - $value).abs() < 1e-5);
+        };
+    }
+
+    #[test]
+    fn gamma_none() {
+        let gc = GammaCorrection::NONE;
+
+        compare!(gc.transform(0.0), 0.0);
+        compare!(gc.transform(0.1), 0.1);
+        compare!(gc.transform(0.9), 0.9);
+        compare!(gc.transform(1.0), 1.0);
+        compare!(gc.transform(10.0), 10.0);
+    }
+
+    #[test]
+    fn inv_gamma_none() {
+        let gc = GammaCorrection::NONE;
+
+        compare!(gc.inverse(0.0), 0.0);
+        compare!(gc.inverse(0.1), 0.1);
+        compare!(gc.inverse(0.9), 0.9);
+        compare!(gc.inverse(1.0), 1.0);
+        compare!(gc.inverse(10.0), 10.0);
+    }
+
+    #[test]
+    fn srgb_roundtrip() {
+        let gc = GammaCorrection::SRGB;
+
+        compare!(gc.inverse(gc.transform(0.0)), 0.0);
+        compare!(gc.inverse(gc.transform(0.1)), 0.1);
+        compare!(gc.inverse(gc.transform(0.9)), 0.9);
+        compare!(gc.inverse(gc.transform(1.0)), 1.0);
+        compare!(gc.inverse(gc.transform(10.0)), 10.0);
+    }
+}

crates/hue/src/gamma.rs

@@ -5,6 +5,7 @@ pub mod colorspace;
 pub mod error;
 pub mod flags;
 pub mod gamma;
+pub mod stream;
 pub mod xy;
 pub mod zigbee;