ht1621b 0.2.0

//! Low-level HT1621B protocol layer.
//!
//! [`Ht1621bBus`] implements the raw 3-wire framing and knows nothing about
//! LCD semantics.  Most users should prefer the ergonomic [`crate::Ht1621b`]
//! wrapper; use this layer directly only when you need raw command / RAM
//! access.

use arbitrary_int::{u4, u6};
#[cfg(feature = "read")]
use embedded_flex_pin::FlexPin;
use embedded_hal::delay::DelayNs;
use embedded_hal::digital::OutputPin;

// ---------------------------------------------------------------------------
// Write trait — implemented by every bus variant
// ---------------------------------------------------------------------------

/// Internal trait providing write-phase operations.
///
/// Implementors supply three primitive signals (`write_bit`, `cs_low`,
/// `cs_high`) and a per-frame settling delay.  All higher-level write methods
/// are derived from those.
pub(crate) trait Ht1621bBusWrite {
    /// Push one bit onto DA using a WR clock pulse.
    fn write_bit(&mut self, b: bool);

    /// Assert CS low (frame start).
    fn cs_low(&mut self);

    /// De-assert CS high (frame end).
    fn cs_high(&mut self);

    /// Post-frame settling delay (10 µs).
    fn frame_end(&mut self);

    /// Called just after CS↓ at the start of every write frame.
    ///
    /// Default no-op; the read/write bus variant overrides it to switch the
    /// bidirectional DA line back to output mode before clocking bits out.
    #[inline]
    fn begin_frame(&mut self) {}

    // -- helpers built on the primitives --------------------------------

    #[inline]
    fn write_addr_bits(&mut self, addr: u6) {
        let mut mask: u8 = 0x20;
        for _ in 0..6 {
            self.write_bit((addr.value() & mask) != 0);
            mask >>= 1;
        }
    }

    #[inline]
    fn write_id_101_addr(&mut self, addr: u6) {
        self.write_bit(true);
        self.write_bit(false);
        self.write_bit(true);
        self.write_addr_bits(addr);
    }

    #[inline]
    fn write_id_100(&mut self) {
        self.write_bit(true);
        self.write_bit(false);
        self.write_bit(false);
    }
    // -- public write API -----------------------------------------------

    /// Send an 8-bit command.
    ///
    /// Frame: CS↓ → `100` → C7–C0 → `X`(=0) → CS↑ → 10 µs settling.
    fn write_command(&mut self, cmd: u8) {
        self.cs_low();
        self.begin_frame();
        self.write_id_100();
        let mut mask: u8 = 0x80;
        for _ in 0..8 {
            self.write_bit((cmd & mask) != 0);
            mask >>= 1;
        }
        self.write_bit(false);
        self.cs_high();
        self.frame_end();
    }

    /// Burst-write multiple 4-bit words starting at `addr`.
    ///
    /// Frame: CS↓ → `101` → 6-bit addr → words … → CS↑ → 10 µs.
    fn write_words(&mut self, addr: u6, words: &[u4]) {
        self.cs_low();
        self.begin_frame();
        self.write_id_101_addr(addr);
        for &word in words {
            let value = word.value();
            let mut mask: u8 = 0x01;
            for _ in 0..4 {
                self.write_bit((value & mask) != 0);
                mask <<= 1;
            }
        }
        self.cs_high();
        self.frame_end();
    }

    /// Write a single 4-bit word to `addr` (wrapper around `write_words`).
    #[inline]
    fn write_word(&mut self, addr: u6, word: u4) {
        self.write_words(addr, &[word]);
    }

    /// Burst-write multiple bytes starting at `addr`.
    ///
    /// Each byte spans 2 RAM addresses (low→high nibble, LSB-first).
    fn write_bytes(&mut self, addr: u6, data: &[u8]) {
        self.cs_low();
        self.begin_frame();
        self.write_id_101_addr(addr);
        for &byte in data {
            let mut mask: u8 = 0x01;
            for _ in 0..8 {
                self.write_bit((byte & mask) != 0);
                mask <<= 1;
            }
        }
        self.cs_high();
        self.frame_end();
    }

    /// Write a single byte to `addr` (wrapper around `write_bytes`).
    #[inline]
    fn write_byte(&mut self, addr: u6, data: u8) {
        self.write_bytes(addr, &[data]);
    }
}

// ---------------------------------------------------------------------------
// Read trait — extends Write with read-phase operations
// ---------------------------------------------------------------------------

/// Internal trait extending [`Ht1621bBusWrite`] with read and
/// read-modify-write support.  Only bus variants that own an RD pin and a
/// bidirectional DA ([`FlexPin`]) implement this.
#[cfg(feature = "read")]
pub(crate) trait Ht1621bBusRead: Ht1621bBusWrite {
    /// Read one bit from DA using an RD clock pulse.
    ///
    /// RD↓ → wait → sample DA → RD↑ → wait.
    fn read_bit(&mut self) -> bool;

    /// Switch DA to input mode so the HT1621B can drive it.
    fn da_to_input(&mut self);

    /// Switch DA to output mode so the MCU can drive it.
    fn da_to_output(&mut self);

    // -- public read API ------------------------------------------------

    #[inline]
    fn write_id_110(&mut self) {
        self.write_bit(true);
        self.write_bit(true);
        self.write_bit(false);
    }

    #[inline]
    fn write_id_110_addr(&mut self, addr: u6) {
        self.write_id_110();
        self.write_addr_bits(addr);
    }

    /// Burst-read multiple 4-bit words starting at `addr`.
    ///
    /// Frame: CS↓ → `110` → 6-bit addr → read nibbles via RD → CS↑ → 10 µs.
    /// Data is output LSB-first (D0→D3) and sampled on RD↑.
    fn read_words(&mut self, addr: u6, buf: &mut [u4]) {
        self.cs_low();
        self.da_to_output();
        self.write_id_110_addr(addr);
        self.da_to_input();
        for slot in buf.iter_mut() {
            let mut value: u8 = 0;
            let mut mask: u8 = 0x01;
            for _ in 0..4 {
                if self.read_bit() {
                    value |= mask;
                }
                mask <<= 1;
            }
            *slot = u4::new(value);
        }
        self.cs_high();
        self.frame_end();
    }

    /// Read a single 4-bit word from `addr`.
    #[inline]
    fn read_word(&mut self, addr: u6) -> u4 {
        let mut buf = [u4::new(0)];
        self.read_words(addr, &mut buf);
        buf[0]
    }

    /// Read-modify-write a single 4-bit word at `addr` in a single CS frame.
    ///
    /// Frame: CS↓ → `101` → 6-bit addr → read nibble via RD → write modified
    /// nibble via WR → CS↑ → 10 µs.
    fn read_modify_write_word(&mut self, addr: u6, f: impl FnOnce(u4) -> u4) {
        self.cs_low();
        self.da_to_output();
        self.write_id_101_addr(addr);
        self.da_to_input();
        let mut value: u8 = 0;
        let mut mask: u8 = 0x01;
        for _ in 0..4 {
            if self.read_bit() {
                value |= mask;
            }
            mask <<= 1;
        }
        let current = u4::new(value);
        let modified = f(current);
        self.da_to_output();
        let mod_val = modified.value();
        let mut mask: u8 = 0x01;
        for _ in 0..4 {
            self.write_bit((mod_val & mask) != 0);
            mask <<= 1;
        }
        self.cs_high();
        self.frame_end();
    }

    /// Burst-read multiple bytes starting at `addr` in a single CS frame.
    ///
    /// Frame: CS↓ → `110` → 6-bit addr → read bytes via RD → CS↑ → 10 µs.
    /// Each byte spans 2 RAM addresses (low→high nibble, LSB-first).
    fn read_bytes(&mut self, addr: u6, buf: &mut [u8]) {
        self.cs_low();
        self.da_to_output();
        self.write_id_110_addr(addr);
        self.da_to_input();
        for slot in buf.iter_mut() {
            let mut lo: u8 = 0;
            let mut mask: u8 = 0x01;
            for _ in 0..4 {
                if self.read_bit() {
                    lo |= mask;
                }
                mask <<= 1;
            }
            let mut hi: u8 = 0;
            let mut mask: u8 = 0x01;
            for _ in 0..4 {
                if self.read_bit() {
                    hi |= mask;
                }
                mask <<= 1;
            }
            *slot = lo | (hi << 4);
        }
        self.cs_high();
        self.frame_end();
    }

    /// Read a single byte from `addr` (wrapper around `read_bytes`).
    #[inline]
    fn read_byte(&mut self, addr: u6) -> u8 {
        let mut buf = [0u8];
        self.read_bytes(addr, &mut buf);
        buf[0]
    }

    /// Read-modify-write multiple 4-bit words in a single CS frame.
    ///
    /// Frame: CS↓ → `101` → 6-bit addr → for each word: read nibble via RD →
    /// write modified nibble via WR → CS↑ → 10 µs.
    /// `f` receives the current nibble value and its index `0..len`.
    fn read_modify_write_words(
        &mut self,
        addr: u6,
        len: usize,
        mut f: impl FnMut(u4, usize) -> u4,
    ) {
        self.cs_low();
        self.da_to_output();
        self.write_id_101_addr(addr);
        for i in 0..len {
            self.da_to_input();
            let mut value: u8 = 0;
            let mut mask: u8 = 0x01;
            for _ in 0..4 {
                if self.read_bit() {
                    value |= mask;
                }
                mask <<= 1;
            }
            let modified = f(u4::new(value), i);
            self.da_to_output();
            let v = modified.value();
            let mut mask: u8 = 0x01;
            for _ in 0..4 {
                self.write_bit((v & mask) != 0);
                mask <<= 1;
            }
        }
        self.cs_high();
        self.frame_end();
    }
}

// ===========================================================================
// 3-wire bus — write only
// ===========================================================================

/// Low-level protocol layer (3-wire, write-only).
///
/// Owns CS, WR, DA pins plus a delay source and implements the raw HT1621B
/// 3-wire framing.  It is generic over any [`OutputPin`] and [`DelayNs`]
/// implementations, so it is not tied to a specific HAL.
pub struct Ht1621bBus<CS, WR, DA, D> {
    cs: CS,
    wr: WR,
    da: DA,
    delay: D,
}

impl<CS, WR, DA, D> Ht1621bBus<CS, WR, DA, D>
where
    CS: OutputPin,
    WR: OutputPin,
    DA: OutputPin,
    D: DelayNs,
{
    /// Create the protocol-layer instance.
    ///
    /// Idles the bus (CS=High, WR=High, DA=High).
    pub fn new(mut cs: CS, mut wr: WR, mut da: DA, delay: D) -> Self {
        let _ = cs.set_high();
        let _ = wr.set_high();
        let _ = da.set_high();
        Self { cs, wr, da, delay }
    }
}

impl<CS, WR, DA, D> Ht1621bBusWrite for Ht1621bBus<CS, WR, DA, D>
where
    CS: OutputPin,
    WR: OutputPin,
    DA: OutputPin,
    D: DelayNs,
{
    #[inline]
    fn write_bit(&mut self, b: bool) {
        if b {
            let _ = self.da.set_high();
        } else {
            let _ = self.da.set_low();
        }
        let _ = self.wr.set_low();
        self.delay.delay_us(5);
        let _ = self.wr.set_high();
        self.delay.delay_us(5);
    }

    #[inline]
    fn cs_low(&mut self) {
        let _ = self.cs.set_low();
    }

    #[inline]
    fn cs_high(&mut self) {
        let _ = self.cs.set_high();
    }

    #[inline]
    fn frame_end(&mut self) {
        self.delay.delay_us(10);
    }
}

// ===========================================================================
// 4-wire bus — write + read + read-modify-write
// ===========================================================================

/// Low-level protocol layer with read support (4-wire).
///
/// Like [`Ht1621bBus`] but adds the **RD** pin required for RAM read and
/// read-modify-write operations.  The DA pin must implement [`FlexPin`] so
/// the driver can switch between output and input modes at runtime.
#[cfg(feature = "read")]
pub struct Ht1621bBusRW<CS, WR, RD, DA, D> {
    cs: CS,
    wr: WR,
    rd: RD,
    da: DA,
    delay: D,
}

#[cfg(feature = "read")]
impl<CS, WR, RD, DA, D> Ht1621bBusRW<CS, WR, RD, DA, D>
where
    CS: OutputPin,
    WR: OutputPin,
    RD: OutputPin,
    DA: FlexPin,
    D: DelayNs,
{
    /// Create the protocol-layer instance.
    ///
    /// Idles the bus (CS=High, WR=High, RD=High, DA=High).
    pub fn new(mut cs: CS, mut wr: WR, mut rd: RD, mut da: DA, delay: D) -> Self {
        let _ = cs.set_high();
        let _ = wr.set_high();
        let _ = rd.set_high();
        let _ = da.set_high();
        Self {
            cs,
            wr,
            rd,
            da,
            delay,
        }
    }
}

#[cfg(feature = "read")]
impl<CS, WR, RD, DA, D> Ht1621bBusWrite for Ht1621bBusRW<CS, WR, RD, DA, D>
where
    CS: OutputPin,
    WR: OutputPin,
    RD: OutputPin,
    DA: FlexPin,
    D: DelayNs,
{
    #[inline]
    fn write_bit(&mut self, b: bool) {
        if b {
            let _ = self.da.set_high();
        } else {
            let _ = self.da.set_low();
        }
        let _ = self.wr.set_low();
        self.delay.delay_us(5);
        let _ = self.wr.set_high();
        self.delay.delay_us(5);
    }

    #[inline]
    fn cs_low(&mut self) {
        let _ = self.cs.set_low();
    }

    #[inline]
    fn cs_high(&mut self) {
        let _ = self.cs.set_high();
    }

    #[inline]
    fn frame_end(&mut self) {
        self.delay.delay_us(10);
    }

    #[inline]
    fn begin_frame(&mut self) {
        self.da_to_output();
    }
}

#[cfg(feature = "read")]
impl<CS, WR, RD, DA, D> Ht1621bBusRead for Ht1621bBusRW<CS, WR, RD, DA, D>
where
    CS: OutputPin,
    WR: OutputPin,
    RD: OutputPin,
    DA: FlexPin,
    D: DelayNs,
{
    #[inline]
    fn read_bit(&mut self) -> bool {
        let _ = self.rd.set_low();
        self.delay.delay_us(5);
        let bit = self.da.is_high().unwrap_or(true);
        let _ = self.rd.set_high();
        self.delay.delay_us(5);
        bit
    }

    #[inline]
    fn da_to_input(&mut self) {
        self.da.set_as_input_no_pull();
    }

    #[inline]
    fn da_to_output(&mut self) {
        self.da.set_as_output_default_speed();
        let _ = self.da.set_high();
    }
}