Add the DMX planner: looks, library, positions, drop guess, Art-Net and a favicon

.gitignore

@@ -10,3 +10,6 @@
 # The firmware has its own target directory.
 /esp32/target/
 /esp32/.embuild/
+
+# Brainstorm mockups of the visual companion
+.superpowers/

Cargo.toml

@@ -4,6 +4,7 @@ members = [
   "host",
   "esp32-emulator",
   "crates/autoblink-core-midi",
+  "crates/autoblink-core-dmx",
   "crates/autoblink-core-prolink",
   "crates/autoblink-core-dbserver",
 ]
@@ -13,7 +14,7 @@ members = [
 exclude = ["esp32"]
 
 [workspace.package]
-version = "1.23.0"
+version = "1.29.0"
 edition = "2021"
 license = "Proprietary"
 authors = ["AUTOBLINK team"]

crates/autoblink-core-dmx/Cargo.toml

@@ -0,0 +1,11 @@
+[package]
+name = "autoblink-core-dmx"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+authors.workspace = true
+
+[dependencies]
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+autoblink-core-midi = { path = "../autoblink-core-midi" }

crates/autoblink-core-dmx/src/artnet.rs

@@ -0,0 +1,105 @@
+//! The Art-Net ArtDmx packet: the reader and the writer.
+
+use crate::render::Universe;
+use crate::show::UNIVERSE;
+
+/// The UDP port of Art-Net.
+pub const ARTNET_PORT: u16 = 6454;
+
+const ID: &[u8; 8] = b"Art-Net\0";
+const OP_DMX: u16 = 0x5000;
+const HEADER: usize = 18;
+
+/// Returns the universe (Net << 8 | SubUni) and the data of an ArtDmx packet, or None.
+pub fn parse_artdmx(packet: &[u8]) -> Option<(u16, &[u8])> {
+    if packet.len() < HEADER || &packet[..8] != ID {
+        return None;
+    }
+    if u16::from_le_bytes([packet[8], packet[9]]) != OP_DMX {
+        return None;
+    }
+    let len = usize::from(u16::from_be_bytes([packet[16], packet[17]]));
+    if len == 0 || len > UNIVERSE {
+        return None;
+    }
+    let data = packet.get(HEADER..HEADER + len)?;
+    let universe = u16::from(packet[15] & 0x7f) << 8 | u16::from(packet[14]);
+    Some((universe, data))
+}
+
+/// Writes an ArtDmx packet for `universe` with `data` (512 bytes) into `out`. Returns the length.
+pub fn build_artdmx(sequence: u8, universe: u16, data: &Universe, out: &mut [u8; 530]) -> usize {
+    out[..8].copy_from_slice(ID);
+    out[8..10].copy_from_slice(&OP_DMX.to_le_bytes());
+    out[10..12].copy_from_slice(&14u16.to_be_bytes());
+    out[12] = sequence;
+    out[13] = 0;
+    out[14] = universe as u8;
+    out[15] = (universe >> 8) as u8 & 0x7f;
+    out[16..18].copy_from_slice(&(UNIVERSE as u16).to_be_bytes());
+    out[HEADER..].copy_from_slice(data);
+    HEADER + UNIVERSE
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn packet(universe: u16, data: &[u8]) -> Vec<u8> {
+        let mut p = b"Art-Net\0".to_vec();
+        p.extend([
+            0x00,
+            0x50,
+            0,
+            14,
+            0,
+            0,
+            universe as u8,
+            (universe >> 8) as u8,
+        ]);
+        p.extend((data.len() as u16).to_be_bytes());
+        p.extend(data);
+        p
+    }
+
+    #[test]
+    fn parse_valid_artdmx() {
+        let p = packet(0x0102, &[1, 2, 3, 4]);
+        assert_eq!(parse_artdmx(&p), Some((0x0102, &[1u8, 2, 3, 4][..])));
+    }
+
+    #[test]
+    fn parse_rejects() {
+        let mut p = packet(0, &[1, 2]);
+        p[0] = b'X';
+        assert!(parse_artdmx(&p).is_none());
+        let mut p = packet(0, &[1, 2]);
+        p[9] = 0x21;
+        assert!(parse_artdmx(&p).is_none());
+        assert!(parse_artdmx(&packet(0, &[1, 2])[..17]).is_none());
+        let mut p = packet(0, &[1, 2]);
+        p[17] = 9;
+        assert!(parse_artdmx(&p).is_none());
+        assert!(parse_artdmx(&packet(0, &[0; 513])).is_none());
+        assert!(parse_artdmx(&packet(0, &[])).is_none());
+        assert!(parse_artdmx(&packet(0, &[0; 512])).is_some());
+        assert!(parse_artdmx(&packet(0, &[1])).is_some());
+    }
+
+    #[test]
+    fn build_round_trip() {
+        let mut data = [0u8; UNIVERSE];
+        data[0] = 7;
+        data[511] = 9;
+        let mut out = [0u8; 530];
+        let n = build_artdmx(3, 0x0102, &data, &mut out);
+        assert_eq!(n, 530);
+        let (u, d) = parse_artdmx(&out[..n]).unwrap();
+        assert_eq!(u, 0x0102);
+        assert_eq!(d, &data[..]);
+        assert_eq!(out[12], 3);
+        assert_eq!(out[10..12], [0, 14]);
+        assert_eq!(out[13], 0);
+        assert_eq!(out[16..18], [2, 0]);
+    }
+}

crates/autoblink-core-dmx/src/clock.rs

@@ -0,0 +1,161 @@
+//! The beat clock of the DMX planner.
+//!
+//! On WiFi, a beat packet arrives late by up to about 300 ms, because the access
+//! point holds a broadcast until the next DTIM beacon. A late packet is never
+//! early. Thus the clock keeps an anchor, the predicted time of the last beat,
+//! and moves it only to an earlier time.
+
+/// Number of packets that the clock compares to find a constant lateness.
+const WINDOW: usize = 8;
+/// The lateness in ms above which the whole window moves the anchor.
+const LATE_MS: f64 = 20.0;
+/// The time in ms after the last packet at which the clock stops.
+const STOP_MS: f64 = 2000.0;
+
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct Beat {
+    pub phase: f64,
+    pub beat_in_bar: u8,
+    pub count: u32,
+    pub ms_per_beat: f64,
+}
+
+#[derive(Default)]
+pub struct BeatClock {
+    anchor_ms: Option<f64>,
+    count: u32,
+    beat_in_bar: u8,
+    period_ms: f64,
+    last_packet_ms: f64,
+    lateness: Vec<f64>,
+}
+
+impl BeatClock {
+    pub fn beat(&mut self, now_ms: u64, beat_in_bar: u8, bpm: f64) {
+        let t = now_ms as f64;
+        let old_period = self.period_ms;
+        self.period_ms = if bpm > 0.0 { 60000.0 / bpm } else { 500.0 };
+        self.last_packet_ms = t;
+        let Some(anchor) = self.anchor_ms else {
+            self.anchor_ms = Some(t);
+            self.count = 0;
+            self.beat_in_bar = beat_in_bar;
+            return;
+        };
+        // The prediction uses the period of the last beat, not the new one.
+        let period = if old_period > 0.0 {
+            old_period
+        } else {
+            self.period_ms
+        };
+        let predicted = anchor + period;
+        let expected = self.beat_in_bar % 4 + 1;
+        let bib_ok = self.beat_in_bar == 0 || beat_in_bar == 0 || beat_in_bar == expected;
+        if bib_ok && t >= predicted - period / 2.0 && t <= predicted + period {
+            self.count = self.count.wrapping_add(1);
+            if beat_in_bar != 0 {
+                self.beat_in_bar = beat_in_bar;
+            } else if self.beat_in_bar != 0 {
+                self.beat_in_bar = expected;
+            }
+            self.anchor_ms = Some(t.min(predicted));
+            self.lateness.push((t - predicted).max(0.0));
+            if self.lateness.len() > WINDOW {
+                self.lateness.remove(0);
+            }
+            if self.lateness.len() == WINDOW {
+                let min = self.lateness.iter().copied().fold(f64::MAX, f64::min);
+                if min > LATE_MS {
+                    self.anchor_ms = self.anchor_ms.map(|a| a + min);
+                    self.lateness.clear();
+                }
+            }
+        } else {
+            // A lost packet leaves a gap. The count goes on by the beats of the gap.
+            let gap = ((t - anchor) / period).round().max(1.0) as u32;
+            self.anchor_ms = Some(t);
+            self.count = self.count.wrapping_add(gap);
+            self.beat_in_bar = beat_in_bar;
+            self.lateness.clear();
+        }
+    }
+
+    /// `None` before the first beat, and 2000 ms after the last beat packet.
+    pub fn now(&self, now_ms: u64) -> Option<Beat> {
+        let anchor = self.anchor_ms?;
+        let t = now_ms as f64;
+        if t - self.last_packet_ms > STOP_MS {
+            return None;
+        }
+        let n = ((t - anchor) / self.period_ms).floor().max(0.0);
+        let phase = ((t - anchor) / self.period_ms - n).clamp(0.0, 1.0);
+        let n = n as u32;
+        let beat_in_bar = if self.beat_in_bar == 0 {
+            0
+        } else {
+            ((u32::from(self.beat_in_bar) - 1 + n) % 4) as u8 + 1
+        };
+        Some(Beat {
+            phase,
+            beat_in_bar,
+            count: self.count.wrapping_add(n),
+            ms_per_beat: self.period_ms,
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn late_packets_keep_phase() {
+        let mut c = BeatClock::default();
+        for (i, late) in [0u64, 300, 100, 250, 180].iter().enumerate() {
+            c.beat(i as u64 * 500 + late, (i % 4) as u8 + 1, 120.0);
+        }
+        let b = c.now(2000).unwrap();
+        assert!(b.phase < 0.02, "{}", b.phase);
+        assert_eq!(b.count, 4);
+    }
+
+    #[test]
+    fn early_packet_moves_anchor() {
+        let mut c = BeatClock::default();
+        for i in 0..4u64 {
+            c.beat(i * 500, (i % 4) as u8 + 1, 120.0);
+        }
+        c.beat(2000 - 40, 1, 120.0);
+        assert_eq!(c.now(1960).unwrap().phase, 0.0);
+    }
+
+    #[test]
+    fn resync_counts_lost_beats() {
+        let mut c = BeatClock::default();
+        c.beat(0, 1, 120.0);
+        c.beat(500, 2, 120.0);
+        c.beat(1500, 4, 120.0);
+        let b = c.now(1500).unwrap();
+        assert_eq!(b.count, 3);
+        assert_eq!(b.beat_in_bar, 4);
+    }
+
+    #[test]
+    fn stops_after_2_s() {
+        let mut c = BeatClock::default();
+        assert!(c.now(0).is_none());
+        c.beat(1000, 1, 120.0);
+        assert!(c.now(3000).is_some());
+        assert!(c.now(3001).is_none());
+    }
+
+    #[test]
+    fn predicts_between_packets() {
+        let mut c = BeatClock::default();
+        c.beat(0, 4, 120.0);
+        let b = c.now(750).unwrap();
+        assert_eq!(b.count, 1);
+        assert_eq!(b.beat_in_bar, 1);
+        assert_eq!(b.phase, 0.5);
+    }
+}