prepare alternative display driver support

rework tertiary display API again
improved char display API
2026-08-26 21:51:01 +02:00 · 2026-08-26 19:39:33 +02:00 · 2026-08-25 01:05:23 +02:00
7 changed files with 656 additions and 124 deletions
@@ -321,6 +321,7 @@ dependencies = [
 "base64 0.23.1",
 "ch1115",
 "critical-section",
+ "display-interface",
 "display-interface-spi",
 "embassy-executor",
 "embassy-futures",
@@ -343,6 +344,7 @@ dependencies = [
 "log",
 "num_enum",
 "pn532",
+ "ssd1306",
 ]

 [[package]]
@@ -607,6 +609,17 @@ version = "0.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7ba2aab1ef3793e6f7804162debb5ac5edb93b3d650fbcc5aeb72fcd0e6c03a0"

+[[package]]
+name = "display-interface-i2c"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0d964fa85bbbb5a6ecd06e58699407ac5dc3e3ad72dac0ab7e6b0d00a1cd262d"
+dependencies = [
+ "display-interface",
+ "embedded-hal 1.0.0",
+ "embedded-hal-async",
+]
+
 [[package]]
 name = "display-interface-spi"
 version = "0.5.0"
@@ -1942,6 +1955,19 @@ version = "0.1.10"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2532096657941c2fea9c289d370a250971c689d4f143798ff67113ec042024a5"

+[[package]]
+name = "maybe-async-cfg"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a1e083394889336bc66a4eaf1011ffbfa74893e910f902a9f271fa624c61e1b2"
+dependencies = [
+ "proc-macro-error",
+ "proc-macro2",
+ "pulldown-cmark",
+ "quote",
+ "syn 1.0.109",
+]
+
 [[package]]
 name = "memchr"
 version = "2.8.3"
@@ -2690,6 +2716,30 @@ dependencies = [
 "toml_edit",
 ]

+[[package]]
+name = "proc-macro-error"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "da25490ff9892aab3fcf7c36f08cfb902dd3e71ca0f9f9517bea02a73a5ce38c"
+dependencies = [
+ "proc-macro-error-attr",
+ "proc-macro2",
+ "quote",
+ "syn 1.0.109",
+ "version_check",
+]
+
+[[package]]
+name = "proc-macro-error-attr"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a1be40180e52ecc98ad80b184934baf3d0d29f979574e439af5a55274b35f869"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "version_check",
+]
+
 [[package]]
 name = "proc-macro2"
 version = "1.0.107"
@@ -2719,6 +2769,17 @@ dependencies = [
 "syn 1.0.109",
 ]

+[[package]]
+name = "pulldown-cmark"
+version = "0.11.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "679341d22c78c6c649893cbd6c3278dcbe9fc4faa62fea3a9296ae2b50c14625"
+dependencies = [
+ "bitflags 2.13.1",
+ "memchr",
+ "unicase",
+]
+
 [[package]]
 name = "quote"
 version = "1.0.47"
@@ -3133,6 +3194,20 @@ version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a0f368519fc6c85fc1afdb769fb5a51123f6158013e143656e25a3485a0d401c"

+[[package]]
+name = "ssd1306"
+version = "0.10.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3ea6aac2d078bbc71d9b8ac3f657335311f3b6625e9a1a96ccc29f5abfa77c56"
+dependencies = [
+ "display-interface",
+ "display-interface-i2c",
+ "display-interface-spi",
+ "embedded-graphics-core",
+ "embedded-hal 1.0.0",
+ "maybe-async-cfg",
+]
+
 [[package]]
 name = "stable_deref_trait"
 version = "1.2.1"
@@ -3400,6 +3475,12 @@ version = "0.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e87a2ed6b42ec5e28cc3b94c09982969e9227600b2e3dcbc1db927a84c06bd69"

+[[package]]
+name = "unicase"
+version = "2.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dbc4bc3a9f746d862c45cb89d705aa10f187bb96c76001afab07a0d35ce60142"
+
 [[package]]
 name = "unicode-id-start"
 version = "1.4.0"
@@ -35,6 +35,7 @@ esp-hal-wifimanager = { git = "https://github.com/InvisibleUSA/esp-hal-wifimanag
 ] }
 esp-println = { version = "0.17.0", features = ["esp32s3", "log-04"] }
 display-interface-spi = "0.5.0"
+display-interface = "*"
 ili9341 = "0.6.0"
 embedded-hal = "1.0.0"
 embedded-hal-bus = "0.3.0"
@@ -47,6 +48,7 @@ embassy-sync = "0.8.0"
 embedded-hal-async = "1.0.0"
 i2c-character-display = "0.5.1"
 ch1115 = { version = "0.1.2", features = ["graphics"] }
+ssd1306 = { version = "0.10.0", features = [] }


 [patch.crates-io]
@@ -12,7 +12,9 @@ use creaturedex::drivers::i2c_bus::I2cBusPinConfiguration;
 use creaturedex::drivers::nfc_pn532::NfcPn532Driver;
 use creaturedex::drivers::secondary_oled::SecondaryDisplay;
 use creaturedex::drivers::spi_bus;
-use creaturedex::drivers::tertiary_lcd::{TertiaryDisplay, init_tertiary_lcd, write_wrapped};
+use creaturedex::drivers::tertiary_lcd::{
+    BOX, EMPTY, EXAMPLE, HEART, TertiaryDisplay, TertiaryDisplayPinConfiguration,
+};
 use creaturedex::navigation::inputs::Inputs;
 use creaturedex::navigation::navigation::{self};
 use creaturedex::navigation::outputs::Outputs;
@@ -87,8 +89,12 @@ async fn main(spawner: Spawner) {
        config.build()
    };

-    let mut lcd: TertiaryDisplay = init_tertiary_lcd(AtomicDevice::new(shared_i2c));
-    if let Err(e) = write_wrapped(&mut lcd, "Testing more than 16 chars what happens now?") {
+    let mut lcd: TertiaryDisplay = TertiaryDisplayPinConfiguration { i2c: shared_i2c }.build();
+    lcd.load_charset(EXAMPLE).unwrap();
+    let h = EXAMPLE[HEART];
+    let e = EXAMPLE[EMPTY];
+    let b = EXAMPLE[BOX];
+    if let Err(e) = lcd.write(&alloc::format!("Custom symbols: {h}{e}{b} And more stuff to wrap and cut off please.")) {
        log::error!(
            "Tertiary LCD startup text write failed over shared I2C bus; check the shared bus, wiring, and device responses: {e}"
        );
@@ -135,7 +141,7 @@ async fn main(spawner: Spawner) {
 }

 fn display_shit(oled: &mut SecondaryDisplay<'static>, text: &str) {
-    oled.clear().unwrap();
+    oled.clear(BinaryColor::Off).unwrap();

    let text_style = MonoTextStyle::new(&FONT_6X10, BinaryColor::On);
    Text::new(text, Point::new(10, 20), text_style)
@@ -1,11 +1,13 @@
 use alloc::boxed::Box;
+use embedded_hal_bus::i2c::AtomicDevice;
 use embedded_hal_bus::util::AtomicCell;
 use esp_hal::gpio::interconnect::PeripheralInput;
 use esp_hal::i2c::master::Config;
 use esp_hal::{gpio::interconnect::PeripheralOutput, i2c::master::I2c};

-type InnerI2cBus = esp_hal::i2c::master::I2c<'static, esp_hal::Blocking>;
-pub type I2cBus = &'static AtomicCell<InnerI2cBus>;
+type InnerI2cBus<'a> = esp_hal::i2c::master::I2c<'a, esp_hal::Blocking>;
+pub type I2cBus<'a> = &'a AtomicCell<InnerI2cBus<'a>>;
+pub type I2cDevice<'a> = AtomicDevice<'a, esp_hal::i2c::master::I2c<'a, esp_hal::Blocking>>;

 pub struct I2cBusPinConfiguration<I2C, SCL, SDA> {
    pub i2c_peripheral: I2C,
@@ -13,13 +15,13 @@ pub struct I2cBusPinConfiguration<I2C, SCL, SDA> {
    pub sda: SDA,
 }

-impl<I2C, SCL, SDA> I2cBusPinConfiguration<I2C, SCL, SDA>
+impl<'a, I2C, SCL, SDA> I2cBusPinConfiguration<I2C, SCL, SDA>
 where
-    I2C: esp_hal::i2c::master::Instance + 'static,
-    SCL: PeripheralOutput<'static> + PeripheralInput<'static>,
-    SDA: PeripheralOutput<'static> + PeripheralInput<'static>,
+    I2C: esp_hal::i2c::master::Instance + 'a,
+    SCL: PeripheralOutput<'a> + PeripheralInput<'a>,
+    SDA: PeripheralOutput<'a> + PeripheralInput<'a>,
 {
-    pub fn build(self) -> I2cBus {
+    pub fn build(self) -> I2cBus<'a> {
        let config = Config::default().with_frequency(esp_hal::time::Rate::from_khz(400));
        let i2c = match I2c::new(self.i2c_peripheral, config) {
            Ok(bus) => bus.with_sda(self.sda).with_scl(self.scl),
@@ -1,6 +1,6 @@
-use alloc::format;
-use ch1115::{Ch1115, Size128x64};
+use alloc::{format, string::String};
 use display_interface_spi::SPIInterface;
+use embedded_graphics::pixelcolor::BinaryColor;
 use embedded_hal_bus::spi::AtomicDevice;
 use embedded_hal_bus::util::AtomicCell;
 use esp_hal::delay::Delay;
@@ -8,10 +8,72 @@ use esp_hal::gpio::Output;

 use crate::drivers::spi_bus::{DisplaySpiBus, SharedOutput, SharedReset};

-pub type GenericSecondaryDisplay<'a, BUS, RST, DC> =
-    Ch1115<SPIInterface<AtomicDevice<'a, BUS, Output<'a>, Delay>, DC>, RST, Size128x64>;
-pub type SecondaryDisplay<'a> =
-    GenericSecondaryDisplay<'a, DisplaySpiBus, SharedReset<'a>, SharedOutput<'a>>;
+pub struct SecondaryDisplay<'a>(
+    #[cfg(feature = "wokwi")] ssd1306_aliases::SecondaryDisplay<'a>,
+    #[cfg(not(feature = "wokwi"))] ch1115_aliases::SecondaryDisplay<'a>,
+);
+
+impl<'a> SecondaryDisplay<'a> {
+    pub fn flush(&mut self) -> Result<(), String> {
+        #[cfg(not(feature = "wokwi"))]
+        return self.0.flush().map_err(|e| format!("{e:?}"));
+        #[cfg(feature = "wokwi")]
+        return Ok(());
+    }
+}
+
+impl<'a> embedded_graphics::geometry::Dimensions for SecondaryDisplay<'a> {
+    fn bounding_box(&self) -> embedded_graphics::primitives::Rectangle {
+        self.0.bounding_box()
+    }
+}
+
+impl<'a> embedded_graphics::draw_target::DrawTarget for SecondaryDisplay<'a> {
+    type Color = BinaryColor;
+
+    type Error = String;
+
+    fn draw_iter<I>(&mut self, pixels: I) -> Result<(), Self::Error>
+    where
+        I: IntoIterator<Item = embedded_graphics::prelude::Pixel<Self::Color>>,
+    {
+        self.0.draw_iter(pixels).map_err(|e| format!("{e:?}"))
+    }
+
+    fn fill_contiguous<I>(
+        &mut self,
+        area: &embedded_graphics::primitives::Rectangle,
+        colors: I,
+    ) -> Result<(), Self::Error>
+    where
+        I: IntoIterator<Item = Self::Color>,
+    {
+        self.0
+            .fill_contiguous(area, colors)
+            .map_err(|e| format!("{e:?}"))
+    }
+
+    fn fill_solid(
+        &mut self,
+        area: &embedded_graphics::primitives::Rectangle,
+        color: Self::Color,
+    ) -> Result<(), Self::Error> {
+        self.0.fill_solid(area, color).map_err(|e| format!("{e:?}"))
+    }
+
+    fn clear(&mut self, color: Self::Color) -> Result<(), Self::Error> {
+        #[cfg(feature = "wokwi")]
+        return self.0.clear(color).map_err(|e| format!("{e:?}"));
+
+        #[cfg(not(feature = "wokwi"))]
+        {
+            let _ = color;
+            self.0.clear().map_err(|e| format!("{e:?}"))
+        }
+    }
+}
+
+pub const SECONDARY_DISPLAY_COUNT: usize = 3;

 pub struct SecondaryDisplayPinConfiguration<'a> {
    pub spi_bus: &'a AtomicCell<DisplaySpiBus>,
@@ -21,39 +83,112 @@ pub struct SecondaryDisplayPinConfiguration<'a> {
 }

 impl<'a> SecondaryDisplayPinConfiguration<'a> {
-    pub fn build(self) -> [SecondaryDisplay<'a>; 3] {
-        let mut displays = self.cs_pins.map(|cs| {
-            let spi_dev = AtomicDevice::new(self.spi_bus, cs, Delay::new()).unwrap();
-            let interface = SPIInterface::new(spi_dev, self.dc.clone());
+    pub fn build(self) -> [SecondaryDisplay<'a>; SECONDARY_DISPLAY_COUNT] {
+        #[cfg(feature = "wokwi")]
+        type Displays<'b> = [ssd1306_aliases::SecondaryDisplay<'b>; SECONDARY_DISPLAY_COUNT];
+        #[cfg(not(feature = "wokwi"))]
+        type Displays<'b> = [ch1115_aliases::SecondaryDisplay<'b>; SECONDARY_DISPLAY_COUNT];

-            Ch1115::new(interface, self.res.clone(), Size128x64)
-        });
+        let reset_pin = self.res.clone();
+        let mut displays = Displays::new(self);
+        displays.reset(reset_pin);

-        init_single_reset(&mut displays, self.res);
-
-        displays
+        displays.map(SecondaryDisplay)
    }
 }

-fn init_single_reset<'a: 'b, 'b>(
-    displays: impl IntoIterator<Item = &'b mut SecondaryDisplay<'a>>,
-    shared_reset: SharedReset<'a>,
-) {
-    let mut displays = displays.into_iter().peekable();
+trait MultiDisplay<'a> {
+    fn new(config: SecondaryDisplayPinConfiguration<'a>) -> Self;
+    fn reset(&mut self, shared_reset: SharedReset<'a>);
+}

-    // Reset all secondaries via shared reset
-    let Some(any_display) = displays.peek_mut() else {
-        // no display to initialize
-        return;
+mod ch1115_aliases {
+    use super::*;
+    use ch1115::{Ch1115, Size128x64};
+
+    type GenericSecondaryDisplay<'a, BUS, RST, DC> =
+        Ch1115<SPIInterface<AtomicDevice<'a, BUS, Output<'a>, Delay>, DC>, RST, Size128x64>;
+    pub type SecondaryDisplay<'a> =
+        GenericSecondaryDisplay<'a, DisplaySpiBus, SharedReset<'a>, SharedOutput<'a>>;
+
+    impl<'a> MultiDisplay<'a> for [SecondaryDisplay<'a>; SECONDARY_DISPLAY_COUNT] {
+        fn new(config: SecondaryDisplayPinConfiguration<'a>) -> Self {
+            config.cs_pins.map(|cs| {
+                let spi_dev = AtomicDevice::new(config.spi_bus, cs, Delay::new()).unwrap();
+                let interface = SPIInterface::new(spi_dev, config.dc.clone());
+
+                SecondaryDisplay::new(interface, config.res.clone(), Size128x64)
+            })
+        }
+
+        fn reset(&mut self, shared_reset: SharedReset<'a>) {
+            let mut displays = self.iter_mut().peekable();
+
+            // Reset all secondaries via shared reset
+            let Some(any_display) = displays.peek_mut() else {
+                // no display to initialize
+                return;
+            };
+            any_display.hard_reset(&mut Delay::new()).unwrap();
+
+            shared_reset.disable(true);
+
+            for (i, display) in displays.enumerate() {
+                display
+                    .init(&mut Delay::new())
+                    .map_err(|e| format!("Failed to init secondary display {}: {e:?}", i + 1))
+                    .unwrap();
+            }
+        }
+    }
+}
+
+mod ssd1306_aliases {
+    use super::*;
+    use ssd1306::{
+        Ssd1306, mode::BufferedGraphicsMode, rotation::DisplayRotation, size::DisplaySize128x64,
    };
-    any_display.hard_reset(&mut Delay::new()).unwrap();

-    shared_reset.disable(true);
+    type GenericSecondaryDisplay<'a, BUS, DC> = Ssd1306<
+        SPIInterface<AtomicDevice<'a, BUS, Output<'a>, Delay>, DC>,
+        DisplaySize128x64,
+        BufferedGraphicsMode<DisplaySize128x64>,
+    >;
+    pub type SecondaryDisplay<'a> = GenericSecondaryDisplay<'a, DisplaySpiBus, SharedOutput<'a>>;

-    for (i, display) in displays.enumerate() {
-        display
-            .init(&mut Delay::new())
-            .map_err(|e| format!("Failed to init secondary display {}: {e:?}", i + 1))
-            .unwrap();
+    impl<'a> MultiDisplay<'a> for [SecondaryDisplay<'a>; SECONDARY_DISPLAY_COUNT] {
+        fn new(config: SecondaryDisplayPinConfiguration<'a>) -> Self {
+            config.cs_pins.map(|cs| {
+                let spi_dev = AtomicDevice::new(config.spi_bus, cs, Delay::new()).unwrap();
+                let interface = SPIInterface::new(spi_dev, config.dc.clone());
+
+                Ssd1306::new(interface, DisplaySize128x64, DisplayRotation::Rotate0)
+                    .into_buffered_graphics_mode()
+            })
+        }
+
+        fn reset(&mut self, mut shared_reset: SharedReset<'a>) {
+            use ssd1306::mode::DisplayConfig as _;
+
+            let mut displays = self.iter_mut().peekable();
+
+            // Reset all secondaries via shared reset
+            let Some(any_display) = displays.peek_mut() else {
+                // no display to initialize
+                return;
+            };
+            any_display
+                .reset(&mut shared_reset, &mut Delay::new())
+                .unwrap();
+
+            shared_reset.disable(true);
+
+            for (i, display) in displays.enumerate() {
+                display
+                    .init()
+                    .map_err(|e| format!("Failed to init secondary display {}: {e:?}", i + 1))
+                    .unwrap();
+            }
+        }
    }
 }
@@ -1,103 +1,410 @@
-use embedded_hal::i2c::I2c;
 use embedded_hal_bus::i2c::AtomicDevice;
 use esp_hal::delay::Delay;
 use i2c_character_display::{CharacterDisplayPCF8574T, LcdDisplayType};
 use log::error;

+use crate::create_custom_char_set;
+use crate::drivers::i2c_bus::{I2cBus, I2cDevice};
+
 type GenericTertiaryDisplay<I2C> = CharacterDisplayPCF8574T<I2C, Delay>;
-pub type TertiaryDisplay<'a> =
-    GenericTertiaryDisplay<AtomicDevice<'a, esp_hal::i2c::master::I2c<'a, esp_hal::Blocking>>>;
+type TertiaryDisplayRaw<'a> = GenericTertiaryDisplay<I2cDevice<'a>>;
+pub type TertiaryDisplayError<'a> = i2c_character_display::CharacterDisplayError<I2cDevice<'a>>;

-pub fn init_tertiary_lcd<I2C>(i2c: I2C) -> GenericTertiaryDisplay<I2C>
-where
-    I2C: I2c,
-{
-    let mut lcd = CharacterDisplayPCF8574T::new(i2c, LcdDisplayType::Lcd16x2, Delay::new());
-    match lcd.init() {
-        Ok(()) => {
-            log::info!("I2C tertiary LCD initialized on PCF8574T at address 0x27");
-            lcd
-        }
-        Err(_) => {
-            error!(
-                "I2C tertiary LCD init failed on PCF8574T at address 0x27; check bus wiring, power, and device address"
-            );
-            panic!("tertiary LCD initialization failed");
+pub struct TertiaryDisplayPinConfiguration<'a> {
+    pub i2c: I2cBus<'a>,
+}
+
+impl<'a> TertiaryDisplayPinConfiguration<'a> {
+    pub fn build(self) -> TertiaryDisplay<'a> {
+        let device = AtomicDevice::new(self.i2c);
+        let mut lcd = CharacterDisplayPCF8574T::new(device, LcdDisplayType::Lcd16x2, Delay::new());
+        match lcd.init() {
+            Ok(()) => {
+                log::info!("I2C tertiary LCD initialized on PCF8574T at address 0x27");
+                TertiaryDisplay {
+                    display: lcd,
+                    charset: create_custom_char_set!(),
+                }
+            }
+            Err(e) => {
+                panic!("I2C tertiary LCD init failed on PCF8574T at address 0x27: {e}");
+            }
        }
    }
 }

-pub fn write_line<I2C>(
-    lcd: &mut GenericTertiaryDisplay<I2C>,
-    line: u8,
-    text: &str,
-) -> Result<(), i2c_character_display::CharacterDisplayError<I2C>>
-where
-    I2C: I2c,
-{
-    if let Err(e) = lcd.set_cursor(0, line) {
-        error!("I2C LCD cursor move failed on line {line}; bus or device may be unavailable");
-        return Err(e);
-    }
-    if let Err(e) = lcd.print(text) {
-        error!(
-            "I2C LCD print failed on line {line}; payload length={} and device may be busy or disconnected",
-            text.len()
-        );
-        return Err(e);
-    }
-    Ok(())
+#[derive(Debug, Clone)]
+pub enum TertiaryDisplayWriteError<'a> {
+    Display(TertiaryDisplayError<'a>),
+    Format(LinesError),
 }

-pub fn write_wrapped<I2C>(
-    lcd: &mut GenericTertiaryDisplay<I2C>,
-    text: &str,
-) -> Result<(), i2c_character_display::CharacterDisplayError<I2C>>
-where
-    I2C: I2c,
-{
-    const DISPLAY_WIDTH: usize = 16;
-    const DISPLAY_ROWS: usize = 2;
+impl<'a> From<TertiaryDisplayError<'a>> for TertiaryDisplayWriteError<'a> {
+    fn from(value: TertiaryDisplayError<'a>) -> Self {
+        Self::Display(value)
+    }
+}

-    if let Err(e) = lcd.clear() {
-        error!(
-            "I2C LCD clear failed before wrapped write; check the shared bus and display response"
-        );
-        return Err(e);
+impl From<LinesError> for TertiaryDisplayWriteError<'_> {
+    fn from(value: LinesError) -> Self {
+        Self::Format(value)
+    }
+}
+
+impl<'a> core::fmt::Display for TertiaryDisplayWriteError<'a> {
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        match self {
+            Self::Display(e) => write!(f, "display error: {e}"),
+            Self::Format(e) => write!(f, "format error: {e}"),
+        }
+    }
+}
+
+pub struct TertiaryDisplay<'a> {
+    display: TertiaryDisplayRaw<'a>,
+    charset: CustomCharset,
+}
+
+impl<'a> TertiaryDisplay<'a> {
+    pub const WIDTH: usize = 16;
+    pub const ROWS: usize = 2;
+
+    pub fn inner_mut(&mut self) -> &mut TertiaryDisplayRaw<'a> {
+        &mut self.display
    }

-    let mut offset = 0;
-    for row in 0..DISPLAY_ROWS {
-        let remaining = &text[offset..];
-        if remaining.is_empty() {
-            return Ok(());
+    pub fn load_charset(&mut self, charset: CustomCharset) -> Result<(), TertiaryDisplayError<'a>> {
+        self.charset = charset;
+        for (index, charmap) in self
+            .charset
+            .set
+            .into_iter()
+            .enumerate()
+            .take(self.charset.len)
+        {
+            self.display
+                .create_char(index as u8, charmap)
+                .inspect_err(|e| error!("I2C Custom character {index} init failed: {e}"))?;
+        }
+        Ok(())
+    }
+
+    pub fn clear(&mut self) -> Result<(), TertiaryDisplayError<'a>> {
+        if let Err(e) = self.display.clear() {
+            error!("I2C LCD clear failed; bus may be busy or device unresponsive");
+            return Err(e);
+        }
+        Ok(())
+    }
+
+    /// Writes text to the LCD. Normal strings wrap by default but this can be controlled
+    /// via explicit [`Lines::checked`].
+    pub fn write<'b, L: Into<Lines<'b>>>(
+        &mut self,
+        text: L,
+    ) -> Result<(), TertiaryDisplayWriteError<'a>> {
+        let lines = text.into();
+
+        // Use original to get correct position in original string
+        lines
+            .original
+            .iter()
+            .try_for_each(|text| Lines::invalid_chars(text, Some(&self.charset)))?;
+
+        let lines = lines.into_result()?;
+
+        self.display
+            .clear()
+            .inspect_err(|e| error!("I2C LCD clear failed before wrapped write: {e}"))?;
+
+        for (row, line) in lines.into_iter().enumerate() {
+            self.display.set_cursor(0, row as u8).inspect_err(|e| {
+                error!("I2C LCD cursor move failed while writing wrapped row {row}: {e}")
+            })?;
+
+            self.display
+                .print(line)
+                .inspect_err(|e| error!("I2C LCD wrapped write failed on row {row}: {e}"))?;
        }

-        let chunk = if remaining.len() > DISPLAY_WIDTH {
-            &remaining[..DISPLAY_WIDTH]
-        } else {
-            remaining
+        Ok(())
+    }
+}
+
+#[derive(Debug, PartialEq, Eq, Clone)]
+pub enum LinesError {
+    ColumnOverflow { line: u8, columns: usize },
+    LineOverflow,
+    InvalidChar { position: usize, symbol: char },
+}
+
+impl core::fmt::Display for LinesError {
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        match self {
+            Self::ColumnOverflow { line, columns } => {
+                write!(
+                    f,
+                    "text too long for line {line}: {columns} > {}",
+                    TertiaryDisplay::WIDTH
+                )
+            }
+            Self::LineOverflow => write!(f, "text has too many lines"),
+            Self::InvalidChar { position, symbol } => {
+                write!(f, "Invalid character {symbol} at offset {position}")
+            }
+        }
+    }
+}
+
+#[derive(Debug, PartialEq, Eq, Clone)]
+pub struct Lines<'a> {
+    pub lines: Result<[&'a str; TertiaryDisplay::ROWS], LinesError>,
+    /// Unmodified original string. Only first entry is populated unless constructed with [`by_line`]
+    pub original: [&'a str; TertiaryDisplay::ROWS],
+}
+
+impl<'a> Lines<'a> {
+    pub fn into_result(self) -> Result<[&'a str; TertiaryDisplay::ROWS], LinesError> {
+        self.lines
+    }
+
+    /// Validates that the text contains only non-control ASCII characters,
+    /// newlines, and contiguous custom characters up to `charset.len`.
+    /// If `charset` is `None`, allow any custom char up to and including maximum.
+    pub fn invalid_chars(text: &str, charset: Option<&CustomCharset>) -> Result<(), LinesError> {
+        for (pos, c) in text.char_indices() {
+            let is_standard_valid = c == '\n' || (' '..='~').contains(&c);
+
+            if is_standard_valid {
+                continue;
+            }
+
+            let first_invalid_custom_char =
+                charset.map(|c| c.len).unwrap_or(CUSTOM_CHAR_COUNT.into());
+
+            if (c as usize) >= first_invalid_custom_char {
+                return Err(LinesError::InvalidChar {
+                    position: pos,
+                    symbol: c,
+                });
+            }
+        }
+        Ok(())
+    }
+
+    /// Checks pre-split lines strictly for length and valid characters.
+    pub fn by_line(lines: [&'a str; TertiaryDisplay::ROWS]) -> Self {
+        let this = |res| Self {
+            lines: res,
+            original: lines,
        };

-        if let Err(e) = lcd.set_cursor(0, row as u8) {
-            error!(
-                "I2C LCD cursor move failed while writing wrapped row {row}; bus may be busy or device unresponsive"
-            );
-            return Err(e);
+        for line in lines.iter() {
+            if let Err(e) = Self::invalid_chars(line, None) {
+                return this(Err(e));
+            }
        }
-        if let Err(e) = lcd.print(chunk) {
-            error!(
-                "I2C LCD wrapped write failed on row {row}; chunk length={} and text may exceed display width",
-                chunk.len()
-            );
-            return Err(e);
-        }
-        offset += chunk.len();

-        if offset >= text.len() {
-            return Ok(());
+        for (i, line) in lines.iter().enumerate() {
+            if line.len() > TertiaryDisplay::WIDTH {
+                return this(Err(LinesError::ColumnOverflow {
+                    line: i as u8,
+                    columns: line.len(),
+                }));
+            }
        }
+
+        this(Ok(lines))
    }

-    Ok(())
+    /// Strictly checks an input string.
+    /// Fails if there are invalid chars, too many newlines, or if any segment exceeds WIDTH.
+    pub fn checked(input: &'a str) -> Self {
+        let this = |res| Self {
+            lines: res,
+            original: [input, ""],
+        };
+
+        if let Err(e) = Self::invalid_chars(input, None) {
+            return this(Err(e));
+        }
+
+        let mut out = [""; TertiaryDisplay::ROWS];
+        let mut parts = input.split('\n');
+
+        for (i, out) in out.iter_mut().enumerate() {
+            if let Some(part) = parts.next() {
+                if part.len() > TertiaryDisplay::WIDTH {
+                    return this(Err(LinesError::ColumnOverflow {
+                        line: i as u8,
+                        columns: part.len(),
+                    }));
+                }
+                *out = part;
+            }
+        }
+
+        if parts.next().is_some() {
+            return this(Err(LinesError::LineOverflow));
+        }
+
+        this(Ok(out))
+    }
+
+    /// Wraps text automatically at `WIDTH` or at newlines.
+    /// Discards (clamps) any leftover text that exceeds `ROWS`.
+    /// Fails immediately if invalid characters are present.
+    pub fn clamped(input: &'a str) -> Self {
+        let this = |res| Self {
+            lines: res,
+            original: [input, ""],
+        };
+        if let Err(e) = Self::invalid_chars(input, None) {
+            return this(Err(e));
+        }
+
+        let mut out = [""; TertiaryDisplay::ROWS];
+        let mut remaining = input;
+
+        for out in out.iter_mut() {
+            if remaining.is_empty() {
+                break;
+            }
+
+            let (segment, rest) = Self::next_segment(remaining, TertiaryDisplay::WIDTH);
+            *out = segment;
+            remaining = rest;
+        }
+
+        this(Ok(out))
+    }
+
+    /// Helper function to slice an ASCII string up to `max_width`
+    /// or until the next newline, whichever comes first.
+    fn next_segment(s: &str, max_width: usize) -> (&str, &str) {
+        let nl_pos = s.find('\n');
+
+        let split_pos = match nl_pos {
+            Some(pos) if pos <= max_width => pos,
+            _ => core::cmp::min(s.len(), max_width),
+        };
+
+        let segment = &s[..split_pos];
+        let mut rest = &s[split_pos..];
+
+        if let Some(stripped) = rest.strip_prefix('\n') {
+            rest = stripped;
+        }
+
+        (segment, rest)
+    }
 }
+
+impl<'a> From<&'a str> for Lines<'a> {
+    fn from(value: &'a str) -> Self {
+        Self::clamped(value)
+    }
+}
+
+impl<'a> From<&'a alloc::string::String> for Lines<'a> {
+    fn from(value: &'a alloc::string::String) -> Self {
+        Self::clamped(value)
+    }
+}
+
+/// 5x8 pixel charmap. Each set bit is a black pixel.
+pub type CharMap = [u8; 8];
+pub struct CustomCharset {
+    set: [CharMap; CUSTOM_CHAR_COUNT as usize],
+    len: usize,
+}
+
+impl core::ops::Index<CharMap> for CustomCharset {
+    type Output = &'static str;
+
+    fn index(&self, map: CharMap) -> &Self::Output {
+        let encoded = self.set[..self.len]
+            .iter()
+            .position(|&m| m == map)
+            .expect("Unknown char map in this set.");
+
+        match encoded {
+            0 => &"\x00",
+            1 => &"\x01",
+            2 => &"\x02",
+            3 => &"\x03",
+            4 => &"\x04",
+            5 => &"\x05",
+            6 => &"\x06",
+            7 => &"\x07",
+            8 => &"\x08",
+            9 => &"\x09",
+            10 => &"\x0A",
+            11 => &"\x0B",
+            12 => &"\x0C",
+            13 => &"\x0D",
+            14 => &"\x0E",
+            15 => &"\x0F",
+            pos => unreachable!(
+                "More than {CUSTOM_CHAR_COUNT} (=max) elements in array? Found element at {pos}."
+            ),
+        }
+    }
+}
+
+#[macro_export]
+macro_rules! create_custom_char_set {
+    () => {{
+        CustomCharset { set: [EMPTY; CUSTOM_CHAR_COUNT as usize], len: 0 }
+    }};
+    ($($char:expr),+ $(,)?) => {{
+        // Count how many characters were passed using macro repetition length
+        const LEN: usize = [$(stringify!($char)),+].len();
+
+        // Ensure we don't exceed the defined maximum capacity
+        const _: () = assert!(
+            LEN <= CUSTOM_CHAR_COUNT as usize,
+            "Too many characters provided for CUSTOM_CHAR_COUNT"
+        );
+
+        // Build a fixed-size array populated with the provided characters,
+        // and pad the rest with empty CharMaps (zeros) to fit CUSTOM_CHAR_COUNT.
+        const SET: [CharMap; CUSTOM_CHAR_COUNT as usize] = {
+            let mut buffer = [[0u8; 8]; CUSTOM_CHAR_COUNT as usize];
+            let input = [$($char),*];
+            let mut i = 0;
+            while i < input.len() {
+                buffer[i] = input[i];
+                i += 1;
+            }
+            buffer
+        };
+
+        CustomCharset {
+            set: SET,
+            len: LEN,
+        }
+    }};
+}
+
+pub const CUSTOM_CHAR_COUNT: u8 = 16;
+
+pub const HEART: CharMap = [
+    0b00000, // Top row
+    0b01010, //  * *
+    0b11111, // *****
+    0b11111, // *****
+    0b01110, //  ***
+    0b00100, //   *
+    0b00000, // Bottom row
+    0b00000, // Cursor line (usually left blank)
+];
+
+pub const EMPTY: CharMap = [0; 8];
+pub const BOX: CharMap = [
+    0b11111, 0b11111, 0b11111, 0b11111, 0b11111, 0b11111, 0b11111,
+    0b00000, // Cursor line (usually left blank)
+];
+
+pub const EXAMPLE: CustomCharset = create_custom_char_set!(HEART, BOX, EMPTY);
+
@@ -1,6 +1,5 @@
 use embedded_graphics::{
-    draw_target::DrawTarget as _,
-    pixelcolor::{Rgb565, RgbColor as _},
+    draw_target::DrawTarget as _, pixelcolor::{BinaryColor, Rgb565, RgbColor as _},
 };

 use crate::drivers::{
@@ -19,9 +18,9 @@ pub struct Outputs {
 impl Outputs {
    pub fn clear_screens(&mut self) {
        self.primary_display.clear(Rgb565::BLACK).unwrap();
-        self.secondary_display_1.clear().unwrap();
-        // self.secondary_display_2.clear().unwrap();
-        // self.secondary_display_3.clear().unwrap();
+        self.secondary_display_1.clear(BinaryColor::Off).unwrap();
+        self.secondary_display_2.clear(BinaryColor::Off).unwrap();
+        self.secondary_display_3.clear(BinaryColor::Off).unwrap();
        self.tertiary_display.clear().unwrap();
    }
 }
Author	SHA1	Message	Date
ede1998	bd124bf9c2	prepare alternative display driver support	2026-08-26 21:51:01 +02:00
ede1998	e33262577d	rework tertiary display API again	2026-08-26 19:39:33 +02:00
ede1998	e26b1f571d	improved char display API	2026-08-25 01:05:23 +02:00