Merge pull request #104 from chrivers/chrivers/entertainment-reversing

First version of entertainment mode support!

> [!IMPORTANT]
> ***This is the big one people have been waiting for!*** :-)

After spending countless hours reverse-engineering the proprietary Zigbee data
format used by Philips Hue lights for "Entertainment Mode", *even countlesser*
hours have gone into implementing support in Bifrost.

Today, I am proud to announce that Bifrost is the **first program in the world**
to have an entirely Open Source (Free Software) implementation of Hue
Entertainment mode!

This has been a monumental effort. Before starting this work, the Bifrost code
base was about 7200 lines of code. Now, it is over 15000 lines!. In other
words, implementing entertainment mode more than doubled the code base!

I think it's fair to say, that this was more complicated than anticipated.

To make this work at all, the Zigbee2Mqtt project was updated with patches from
myself (@chrivers), @danielhitch, and the author of Zigbee2Mqtt, @Koenkk.

Special thanks to @Koenkk for taking time out of his busy schedule, to help us
get the necessary bits in place. The new code was first released in version 2.1.1.

> [!WARNING]
> Zigbee2Mqtt MUST BE AT LEAST version 2.1.1 for Entertainment Mode to work.

> [!IMPORTANT]
> Even though version 2.1.1 is the minimum version, version 2.1.3 or greater is
> highly recommended, since some important bugs were fixed after version 2.1.1.

This is the very first of Bifrost that supports Entertainment Mode at all, so
please bear with us while we iron out any bugs or rough edges.

Should work:
 - Creating Entertainment Areas from the Hue App.
 - Updating Entertainment Area settings.
 - Adding lights or 7-segment strips to entertainment areas.
 - Streaming to Entertainment Areas from "Hue Sync for PC" (tested).
 - Streaming to Entertainment Areas from Play HDMI sync box 8K (tested).
 - Streaming to one or more lights.
 - Streaming to a combination of lamps and light strips.

Perhaps working: (please let us know what your experience is!)
 - Adding 3-segment strips to entertainment areas.
 - Adding non-color lights to entertainment areas.
 - Streaming to Entertainment Areas from Play HDMI sync box (older, non-8K version).

Not yet working:
 - Adjusting "stream mode" ("From Device" vs "From Bridge")
 - Adjusting "relative brightness" for lights
 - Streaming in XY color mode (most things seem to use RGB mode)

Author: chrivers

Cargo.lock

@@ -36,6 +36,7 @@ keywords = [
 [workspace]
 members = [
     "crates/hue",
+    "crates/svc",
     "crates/zcl",
 ]
 
@@ -44,7 +45,7 @@ unstable_features = "forbid"
 unused_lifetimes = "warn"
 unused_qualifications = "warn"
 
-[lints.clippy]
+[workspace.lints.clippy]
 all         = { level = "warn", priority = -1 }
 correctness = { level = "warn", priority = -1 }
 pedantic    = { level = "warn", priority = -1 }
@@ -57,19 +58,43 @@ multiple_crate_versions = "allow"
 missing_errors_doc      = "allow"
 missing_panics_doc      = "allow"
 
+[lints]
+workspace = true
+
 [features]
-default = ["server", "server-banner"]
+default = [
+    "server",
+    "server-banner",
+    "tls-openssl",
+    # "tls-rustls",
+]
+
+tls-openssl = [
+    "axum-server/tls-openssl",
+    "reqwest/native-tls",
+    "dep:openssl"
+]
+
+tls-rustls  = [
+    "axum-server/rustls",
+    "axum-server/tls-rustls-no-provider",
+    "reqwest/rustls-tls"
+]
 
 server = []
 server-banner = ["server", "dep:termcolor", "dep:itertools"]
 
+[profile.dev]
+debug = "limited"
+split-debuginfo = "unpacked"
+
 [dependencies]
 axum = { version = "0.8.1", features = ["json", "tokio", "macros", "multipart"], default-features = false }
 axum-core = "0.5.0"
-axum-server = { version = "0.7.1", features = ["rustls", "tls-rustls-no-provider"], default-features = false }
+axum-server = { version = "0.7.1", features = [], default-features = false }
 bytes = "1.10.0"
 chrono = { version = "0.4.39", features = ["clock", "serde"], default-features = false }
-clap = { version = "4.5.29", features = ["std", "color", "derive"], default-features = false }
+clap = { version = "4.5.29", features = ["std", "color", "derive", "help", "usage"], default-features = false }
 config = { version = "0.15.8", default-features = false, features = ["yaml"] }
 futures = "0.3.31"
 hyper = "1.6.0"
@@ -83,7 +108,7 @@ serde = { version = "1.0.217", features = ["derive"], default-features = false }
 serde_json = "1.0.138"
 serde_yml = "0"
 thiserror = "2.0.11"
-tokio = { version = "1.43.0", features = ["io-util", "process", "rt-multi-thread"], default-features = false }
+tokio = { version = "1.43.0", features = ["io-util", "process", "rt-multi-thread", "signal"], default-features = false }
 tokio-stream = { version = "0.1.17", features = ["sync"], default-features = false }
 tokio-tungstenite = "0.26.1"
 tower = "0.5.2"
@@ -102,12 +127,18 @@ sha1 = "0.10.6"
 rustls-pemfile = "2.2.0"
 termcolor = { version = "1.4.1", optional = true }
 itertools = { version = "0.14.0", optional = true }
-reqwest = { version = "0.12.12", default-features = false, features = ["json", "rustls-tls"] }
+reqwest = { version = "0.12.12", default-features = false, features = ["json"] }
 url = { version = "2.5.4", features = ["serde"] }
 hex = "0.4.3"
 async-trait = "0.1.86"
 hue = { version = "0.1.0", path = "crates/hue" }
 zcl = { path = "crates/zcl" }
+openssl = { version = "0.10", optional = true }
+tokio-util = { version = "0.7.13", features = ["net"] }
+tokio-openssl = "0.6.5"
+udp-stream = "0.0.12"
+maplit = "1.0.2"
+svc = { version = "0.1.0", path = "crates/svc" }
 
 [dev-dependencies]
 clap-stdin = "0.6.0"

Cargo.toml

@@ -31,10 +31,10 @@ To install Bifrost from source, you will need the following:
 3.  The MAC address of the network interface you want to run the server on
 4.  `build-essential` package for compiling the source code (on Debian/Ubuntu systems)
 
-First, install `build-essential` :
+First, install a few necessary build dependencies:
 
 ```sh
-sudo apt install build-essential
+sudo apt install build-essential pkg-config libssl-dev
 ```
 
 When you have these things available, install bifrost:

README.md

@@ -103,6 +103,9 @@ pub enum ZclDataType {
     /** IEEE address (U64) type */
     ZclIeeeaddr = 0xf0,
 
+    /** 128-bit security key */
+    ZclSecurityKey = 0xf1,
+
     /** Invalid data type */
     ZclInvalid = 0xff,
 }
@@ -149,32 +152,34 @@ pub enum ZclAttrValue {
     Bytes(Vec<u8>),
     String(String),
     IeeeAddr(Vec<u8>),
+    SecurityKey([u8; 16]),
     Unsupported,
 }
 
 impl Debug for ZclAttrValue {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         match self {
             Self::Null => write!(f, "Null"),
-            Self::X8(val) => write!(f, "x8:{}", val),
-            Self::X16(val) => write!(f, "x16:{}", val),
-            Self::X32(val) => write!(f, "x32:{}", val),
-            Self::Bool(val) => write!(f, "bool:{}", val),
-            Self::B8(val) => write!(f, "b8:{:02X}", val),
-            Self::B16(val) => write!(f, "b16:{:04X}", val),
-            Self::B32(val) => write!(f, "b32:{:08X}", val),
-            Self::B40(val) => write!(f, "b40:{:010X}", val),
-            Self::B48(val) => write!(f, "b48:{:012X}", val),
-            Self::B56(val) => write!(f, "b56:{:014X}", val),
-            Self::B64(val) => write!(f, "b64:{:016X}", val),
-            Self::U8(val) => write!(f, "u8:{:02X}", val),
-            Self::U16(val) => write!(f, "u16:{:04X}", val),
-            Self::U32(val) => write!(f, "u32:{:08X}", val),
-            Self::I16(val) => write!(f, "i16:{:04X}", val),
-            Self::E8(val) => write!(f, "e8:{:02X}", val),
+            Self::X8(val) => write!(f, "x8:{val}"),
+            Self::X16(val) => write!(f, "x16:{val}"),
+            Self::X32(val) => write!(f, "x32:{val}"),
+            Self::Bool(val) => write!(f, "bool:{val}"),
+            Self::B8(val) => write!(f, "b8:{val:02X}"),
+            Self::B16(val) => write!(f, "b16:{val:04X}"),
+            Self::B32(val) => write!(f, "b32:{val:08X}"),
+            Self::B40(val) => write!(f, "b40:{val:010X}"),
+            Self::B48(val) => write!(f, "b48:{val:012X}"),
+            Self::B56(val) => write!(f, "b56:{val:014X}"),
+            Self::B64(val) => write!(f, "b64:{val:016X}"),
+            Self::U8(val) => write!(f, "u8:{val:02X}"),
+            Self::U16(val) => write!(f, "u16:{val:04X}"),
+            Self::U32(val) => write!(f, "u32:{val:08X}"),
+            Self::I16(val) => write!(f, "i16:{val:04X}"),
+            Self::E8(val) => write!(f, "e8:{val:02X}"),
             Self::Bytes(val) => write!(f, "hex:{}", hex::encode(val)),
-            Self::String(val) => write!(f, "str:{}", &val),
+            Self::String(val) => write!(f, "str:{val}"),
             Self::IeeeAddr(val) => write!(f, "ieeeaddr {}", hex::encode(val)),
+            Self::SecurityKey(val) => write!(f, "seckey {}", hex::encode(val)),
             Self::Unsupported => write!(f, "Unsupported"),
         }
     }
@@ -240,6 +245,11 @@ impl ZclAttr {
                 ZclAttrValue::String(String::from_utf8(buf)?)
             }
             ZclDataType::ZclIeeeaddr => todo!(),
+            ZclDataType::ZclSecurityKey => {
+                let mut buf = [0; 16];
+                rdr.read_exact(&mut buf)?;
+                ZclAttrValue::SecurityKey(buf)
+            }
             ZclDataType::ZclInvalid => todo!(),
         };
 
@@ -261,6 +271,7 @@ pub struct ZclReadAttrResp {
 }
 
 impl ZclReadAttrResp {
+    #[allow(clippy::cast_possible_truncation)]
     pub fn parse(data: &[u8]) -> ZclResult<Self> {
         let mut attr = vec![];
 
@@ -279,6 +290,7 @@ pub struct ZclWriteAttr {
 }
 
 impl ZclWriteAttr {
+    #[allow(clippy::cast_possible_truncation)]
     pub fn parse(data: &[u8]) -> ZclResult<Self> {
         let mut attr = vec![];
 
@@ -297,6 +309,7 @@ pub struct ZclReportAttr {
 }
 
 impl ZclReportAttr {
+    #[allow(clippy::cast_possible_truncation)]
     pub fn parse(data: &[u8]) -> ZclResult<Self> {
         let mut attr = vec![];
 
@@ -316,7 +329,7 @@ pub struct ZclDefaultResp {
 }
 
 impl ZclDefaultResp {
-    pub fn parse(data: &[u8]) -> ZclResult<Self> {
+    pub const fn parse(data: &[u8]) -> ZclResult<Self> {
         Ok(Self {
             cmd: data[0],
             stat: data[1],

crates/zcl/src/attr.rs

@@ -1,5 +1,6 @@
 use crate::frame::{ZclFrame, ZclFrameDirection};
 
+#[must_use]
 pub fn describe(frame: &ZclFrame, _data: &[u8]) -> Option<String> {
     if frame.manufacturer_specific() {
         return None;

crates/zcl/src/cluster/colorctrl.rs

@@ -1,5 +1,6 @@
 use crate::frame::{ZclFrame, ZclFrameDirection};
 
+#[must_use]
 pub fn describe(frame: &ZclFrame, _data: &[u8]) -> Option<String> {
     if frame.flags.direction == ZclFrameDirection::ClientToServer {
         match frame.cmd {

crates/zcl/src/cluster/effects.rs

@@ -1,5 +1,6 @@
 use crate::frame::{ZclFrame, ZclFrameDirection};
 
+#[must_use]
 pub fn describe(frame: &ZclFrame, _data: &[u8]) -> Option<String> {
     if frame.flags.direction == ZclFrameDirection::ClientToServer {
         match frame.cmd {

crates/zcl/src/cluster/groups.rs

@@ -2,7 +2,7 @@ use packed_struct::PackedStructSlice;
 
 use crate::error::ZclResult;
 use crate::frame::ZclFrame;
-use hue::zigbee::{HueEntFrame, HueEntSegmentConfig, HueEntStop};
+use hue::zigbee::{HueEntFrame, HueEntSegmentConfig, HueEntSegmentLayout, HueEntStop};
 
 pub fn describe(frame: &ZclFrame, data: &[u8]) -> ZclResult<Option<String>> {
     if !frame.cluster_specific() {
@@ -12,6 +12,14 @@ pub fn describe(frame: &ZclFrame, data: &[u8]) -> ZclResult<Option<String>> {
     match frame.cmd {
         1 => Ok(Some(format!("{:x?}", HueEntFrame::parse(data)?))),
         3 => Ok(Some(format!("{:x?}", HueEntStop::unpack_from_slice(data)?))),
+        4 => {
+            let res = if frame.c2s() && data.len() == 1 {
+                "HueEntSegmentLayoutReq".to_string()
+            } else {
+                format!("{:x?}", HueEntSegmentLayout::parse(data)?)
+            };
+            Ok(Some(res))
+        }
         7 => Ok(Some(format!("{:x?}", HueEntSegmentConfig::parse(data)?))),
         _ => Ok(None),
     }

crates/zcl/src/cluster/hue_fc01.rs

@@ -10,7 +10,7 @@ pub fn describe(frame: &ZclFrame, data: &[u8]) -> ZclResult<Option<String>> {
 
     match frame.cmd {
         0x00 => {
-            let zflags = Flags::from_bits((data[0] as u16) | (data[1] as u16) << 8).unwrap();
+            let zflags = Flags::from_bits(u16::from(data[0]) | (u16::from(data[1]) << 8)).unwrap();
             Ok(Some(format!("{:?} {}", zflags, hex::encode(&data[2..]))))
         }
         _ => Ok(None),

crates/zcl/src/cluster/hue_fc03.rs

@@ -1,5 +1,6 @@
 use crate::frame::{ZclFrame, ZclFrameDirection};
 
+#[must_use]
 pub fn describe(frame: &ZclFrame, _data: &[u8]) -> Option<String> {
     if frame.manufacturer_specific() {
         return None;

crates/zcl/src/cluster/levelctrl.rs

@@ -1,5 +1,6 @@
 use crate::frame::{ZclFrame, ZclFrameDirection};
 
+#[must_use]
 pub fn describe(frame: &ZclFrame, _data: &[u8]) -> Option<String> {
     if frame.manufacturer_specific() {
         return None;

crates/zcl/src/cluster/onoff.rs

@@ -4,13 +4,14 @@ use hue::zigbee::Flags;
 
 use crate::frame::{ZclFrame, ZclFrameDirection};
 
+#[must_use]
 pub fn describe(frame: &ZclFrame, data: &[u8]) -> Option<String> {
     if frame.manufacturer_specific() {
         if frame.flags.direction == ZclFrameDirection::ClientToServer {
             match frame.cmd {
                 0x02 => Some(format!(
                     "SetComposite {:?}",
-                    Flags::from_bits((data[3] as u16) | (data[4] as u16) << 8).unwrap()
+                    Flags::from_bits(u16::from(data[3]) | (u16::from(data[4]) << 8)).unwrap()
                 )),
                 _ => None,
             }

crates/zcl/src/cluster/scenes.rs

@@ -83,11 +83,18 @@ impl ZclFrame {
         })
     }
 
+    #[must_use]
+    pub fn c2s(&self) -> bool {
+        self.flags.direction == ZclFrameDirection::ClientToServer
+    }
+
+    #[must_use]
     pub fn cluster_specific(&self) -> bool {
         self.flags.frame_type == ZclFrameType::ClusterSpecific
     }
 
-    pub fn manufacturer_specific(&self) -> bool {
+    #[must_use]
+    pub const fn manufacturer_specific(&self) -> bool {
         self.flags.manufacturer_specific
     }
 }

crates/zcl/src/frame.rs

@@ -33,18 +33,24 @@ bridge:
   gateway: 10.0.0.1
   timezone: Europe/Copenhagen
 
-  # http port for emulated bridge
+  # HTTP port for emulated bridge
   #
   # beware: most client programs do NOT support non-standard ports.
   # This is for advanced users (e.g. bifrost behind a reverse proxy)
   http_port: 80
 
-  # https port for emulated bridge
+  # HTTPS port for emulated bridge
   #
   # beware: most client programs do NOT support non-standard ports.
   # This is for advanced users (e.g. bifrost behind a reverse proxy)
   https_port: 443
 
+  # DTLS port for emulated bridge (Hue Entertainment streaming)
+  #
+  # beware: client programs do NOT support non-standard ports.
+  # For advanced users (e.g. bifrost behind a port forwarded firewall)
+  entm_port: 2100
+
 # Zigbee2mqtt section
 #
 # Make a sub-section for each zigbee2mqtt server you want to connect