HuePulse Technical Documentation

HuePulse is a high-performance, sound-reactive lighting system built for Philips Hue smart ecosystems. It captures acoustic audio locally, performs real-time volume/BPM analysis, and blasts binary streaming datagrams to the Hue Bridge via UDP port 2100.

Zero Cloud Latency: Audio is sampled and computed entirely in device RAM. No audio packets or voice streams are ever transmitted over the Internet or stored on disk.

1. Architecture Overview

HuePulse employs a hybrid multi-layer architecture designed for microsecond response times:

Audio Capture Engine (Dart/Android): 16-bit PCM streaming at 22,050 Hz via AndroidRecordConfig with unprocessed audio source, preventing audio ducking or interference when music plays on the phone (e.g., Spotify).
Native UDP DTLS 1.2 PSK (Kotlin/BouncyCastle): Direct socket connection on port 2100 using TLS_PSK_WITH_AES_128_GCM_SHA256 with ProtocolVersion.DTLSv12.only().
CLIP v2 Spatial Resolution: Automatic query of /clip/v2/resource/entertainment_configuration mapping 3D Cartesian coordinates (X, Y, Z) to entertainment channel IDs.
Safety Governor (REST Fallback): In case UDP is disabled or unreachable, a token-bucket throttled coalescing queue dispatches Zigbee broadcasts while enforcing the strict physical 10 req/s threshold on Hue Bridge v2.

2. Quick Setup & Network Requirements

Create an Entertainment Area: Open the official Philips Hue app on iOS/Android, go to Settings → Entertainment Areas, and select your room with at least 1 color lamp or lightstrip.
Same Local Wi-Fi Subnet: Connect your smartphone to the same Wi-Fi network as your Philips Hue Bridge (2.4 GHz or 5 GHz). Ensure AP Client Isolation is disabled in your router.
Launch HuePulse: The app will auto-discover your Bridge via mDNS and Philips N-UPnP. Press the large physical circular button on your Hue Bridge once when prompted to authenticate.

3. HueStream Binary Protocol (v2.0)

Streaming datagrams adhere to the Hue Entertainment v2 binary layout:

Header (16 Bytes):
  [0..8]   "HueStream" (ASCII)
  [9..10]  0x02, 0x00 (Protocol Version 2.0)
  [11]     0x00 (Sequence Counter)
  [12..13] 0x00, 0x00 (Reserved)
  [14]     0x00 (Color Space: RGB 16-bit)
  [15]     0x00 (Reserved)

Payload:
  [16..51] Entertainment Area UUID (36 Bytes ASCII)
  [52..N]  Repeated 7-Byte Channel Blocks:
           Byte 0: Channel ID (0..19)
           Bytes 1-2: Red   (16-bit Big-Endian, 0..65535)
           Bytes 3-4: Green (16-bit Big-Endian, 0..65535)
           Bytes 5-6: Blue  (16-bit Big-Endian, 0..65535)

4. Bridge Hardware Compatibility

Philips Hue Bridge v2 (Square White): Fully supported. Streams up to 20 channels at 25–50 FPS.
Philips Hue Bridge Pro (2026 Black): Fully supported. Up to 150+ devices with built-in Wi-Fi and quad-core CPU.
Gradient Lightstrips: Multi-zone channels (3 zones on Ambiance, 7 zones on Play) map to the primary channel in v0.9.0-rc1, with independent spatial EQ chasers scheduled for future releases.