ht1621b 0.1.1

//! Platform-agnostic driver for the **HT1621B** LCD controller.
//!
//! The HT1621B is driven over a custom 3-wire serial interface (not SPI):
//! - **CS**: active-low chip select, frames each transaction
//! - **WR**: write clock, data latched on the rising edge
//! - **DA**: data line
//!
//! Each transaction is framed by CS↓ … CS↑.  Within a frame the first 3 bits
//! select the mode:
//!
//! | ID   | Mode       | Payload                            |
//! |------|------------|------------------------------------|
//! | 100  | Command    | 8-bit command + 1 don't-care bit   |
//! | 101  | Write RAM  | 6-bit addr + N × 4-bit data        |
//! | 110  | Read RAM   | 6-bit addr + N × 4-bit data (read) |
//!
//! RAM is 32 × 4 bits (128 segments).  The address auto-increments after each
//! nibble in write/read mode, allowing continuous burst transfer.  Command
//! bits and the RAM address are sent MSB-first; RAM data nibbles are sent
//! LSB-first (D0→D3) per the datasheet.
//!
//! # Layers
//!
//! - [`Ht1621bBus`]: low-level protocol layer (raw commands / RAM writes).
//! - [`Ht1621b`]: ergonomic, command-based wrapper with [`Config`], power
//!   control, buzzer, and time-base / watchdog helpers.
//!
//! Both are generic over [`embedded_hal::digital::OutputPin`] and
//! [`embedded_hal::delay::DelayNs`], so the driver works with any
//! `embedded-hal` 1.0 implementation.
//!
//! # Example
//!
//! ```ignore
//! use ht1621b::{Config, Ht1621b};
//!
//! // `cs`, `wr`, `da`: OutputPin; `delay`: DelayNs; `async_delay`: async DelayNs
//! let mut lcd = Ht1621b::new(cs, wr, da, delay, &mut async_delay, Config::default()).await;
//! lcd.write_byte(arbitrary_int::u6::new(0x00), 0xEF); // display a digit
//! ```

#![no_std]

use arbitrary_int::{u4, u6};
use derive_setters::Setters;
use embedded_hal::delay::DelayNs;
use embedded_hal::digital::OutputPin;

mod bus;
pub use bus::Ht1621bBus;

/// Raw 8-bit command codes.
///
/// [`Ht1621bBus::write_command`] prepends the 3-bit ID (100) and appends the
/// don't-care fill bit X (=0), forming the full 12-bit frame: `100` + C7–C0
/// + `X`.  All don't-care bits (X) are filled with 0.
pub mod cmd {
    // System / display control
    pub const SYS_DIS: u8 = 0x00; // 0000_0000  osc + LCD bias off
    pub const SYS_EN: u8 = 0x01; // 0000_0001  system oscillator on
    pub const LCD_OFF: u8 = 0x02; // 0000_0010  LCD bias off
    pub const LCD_ON: u8 = 0x03; // 0000_0011  LCD bias on

    // Time base / WDT enable
    pub const TIMER_DIS: u8 = 0x04; // 0000_0100
    pub const WDT_DIS: u8 = 0x05; // 0000_0101
    pub const TIMER_EN: u8 = 0x06; // 0000_0110
    pub const WDT_EN: u8 = 0x07; // 0000_0111

    // Tone enable
    pub const TONE_OFF: u8 = 0x08; // 0000_1000
    pub const TONE_ON: u8 = 0x09; // 0000_1001

    // Clear
    pub const CLR_TIMER: u8 = 0x0C; // 0000_11XX
    pub const CLR_WDT: u8 = 0x0E; // 0000_111X

    // System clock source
    pub const XTAL_32K: u8 = 0x14; // 0001_01XX
    pub const RC_256K: u8 = 0x18; // 0001_10XX
    pub const EXT_256K: u8 = 0x1C; // 0001_11XX

    // LCD bias / COM  (0010_abX?, ab: 00=2COM 01=3COM 10=4COM)
    pub const BIAS_1_2_2COM: u8 = 0x20; // 0010_0000
    pub const BIAS_1_2_3COM: u8 = 0x24; // 0010_0100
    pub const BIAS_1_2_4COM: u8 = 0x28; // 0010_1000
    pub const BIAS_1_3_2COM: u8 = 0x21; // 0010_0001
    pub const BIAS_1_3_3COM: u8 = 0x25; // 0010_0101
    pub const BIAS_1_3_4COM: u8 = 0x29; // 0010_1001

    // Tone frequency
    pub const TONE_4K: u8 = 0x40; // 010X_XXXX
    pub const TONE_2K: u8 = 0x60; // 011X_XXXX

    // IRQ enable
    pub const IRQ_DIS: u8 = 0x80; // 100X_0XXX
    pub const IRQ_EN: u8 = 0x88; // 100X_1XXX

    // Time base / WDT clock output frequency
    pub const F1: u8 = 0xA0; // 101X_X000
    pub const F2: u8 = 0xA1; // 101X_X001
    pub const F4: u8 = 0xA2; // 101X_X010
    pub const F8: u8 = 0xA3; // 101X_X011
    pub const F16: u8 = 0xA4; // 101X_X100
    pub const F32: u8 = 0xA5; // 101X_X101
    pub const F64: u8 = 0xA6; // 101X_X110
    pub const F128: u8 = 0xA7; // 101X_X111

    // Test mode
    pub const TEST: u8 = 0xE0; // 1110_0000
    pub const NORMAL: u8 = 0xE3; // 1110_0011
}

/// LCD bias level.
#[derive(Clone, Copy, PartialEq, Eq)]
pub enum Bias {
    /// 1/2 bias.
    Half,
    /// 1/3 bias.
    Third,
}

/// Number of COM (backplane) lines driven.
#[derive(Clone, Copy, PartialEq, Eq)]
pub enum Commons {
    Two,
    Three,
    Four,
}

/// System clock source.
#[derive(Clone, Copy, PartialEq, Eq)]
pub enum ClockSource {
    /// On-chip RC oscillator, 256 kHz.
    Rc256k,
    /// External 32.768 kHz crystal.
    Xtal32k,
    /// External 256 kHz clock.
    Ext256k,
}

impl ClockSource {
    #[inline]
    fn command(self) -> u8 {
        match self {
            ClockSource::Rc256k => cmd::RC_256K,
            ClockSource::Xtal32k => cmd::XTAL_32K,
            ClockSource::Ext256k => cmd::EXT_256K,
        }
    }

    /// Oscillator stabilisation time (ms) to wait after `SYS_EN` before
    /// enabling the LCD bias.  A 32.768 kHz crystal needs far longer to
    /// start up than the on-chip RC or an already-running external clock.
    #[inline]
    fn stabilize_ms(self) -> u32 {
        match self {
            ClockSource::Rc256k => 2,
            ClockSource::Ext256k => 2,
            ClockSource::Xtal32k => 50,
        }
    }
}

/// Buzzer output frequency.
#[derive(Clone, Copy, PartialEq, Eq)]
pub enum ToneFreq {
    /// 4 kHz.
    Khz4,
    /// 2 kHz.
    Khz2,
}

impl ToneFreq {
    #[inline]
    fn command(self) -> u8 {
        match self {
            ToneFreq::Khz4 => cmd::TONE_4K,
            ToneFreq::Khz2 => cmd::TONE_2K,
        }
    }
}

/// Time base / WDT clock output frequency.
///
/// Sets both the time-base output frequency and the WDT time-out period
/// (they share one prescaler): F128=128Hz/(1/32s) … F1=1Hz/(4s).
#[derive(Clone, Copy, PartialEq, Eq)]
pub enum TimerFreq {
    F1,
    F2,
    F4,
    F8,
    F16,
    F32,
    F64,
    F128,
}

impl TimerFreq {
    #[inline]
    fn command(self) -> u8 {
        match self {
            TimerFreq::F1 => cmd::F1,
            TimerFreq::F2 => cmd::F2,
            TimerFreq::F4 => cmd::F4,
            TimerFreq::F8 => cmd::F8,
            TimerFreq::F16 => cmd::F16,
            TimerFreq::F32 => cmd::F32,
            TimerFreq::F64 => cmd::F64,
            TimerFreq::F128 => cmd::F128,
        }
    }
}

/// Time-base subsystem mode.  Time base and WDT share one generator and are
/// mutually exclusive; this enum makes an illegal "both on" state
/// unrepresentable.  IRQ output follows the mode (on for TimeBase/Watchdog,
/// off for Off).
#[derive(Clone, Copy, PartialEq, Eq)]
pub enum TimerMode {
    /// Time base + WDT off; IRQ output off.
    Off,
    /// Periodic time-base interrupt at `freq` (IRQ enabled).
    TimeBase(TimerFreq),
    /// Watchdog at `freq` (IRQ enabled); feed with [`Ht1621b::wdt_feed`].
    Watchdog(TimerFreq),
}

/// Power-on configuration for [`Ht1621b`].
#[derive(Clone, Copy, Setters)]
pub struct Config {
    pub bias: Bias,
    pub commons: Commons,
    pub clock: ClockSource,
}

impl Default for Config {
    /// 1/3 bias, 4 COM, internal RC 256 kHz — the datasheet reset defaults
    /// for a typical multiplexed LCD panel.
    fn default() -> Self {
        Self {
            bias: Bias::Third,
            commons: Commons::Four,
            clock: ClockSource::Rc256k,
        }
    }
}

impl Config {
    /// Resolve `bias` + `commons` into the matching BIAS command code.
    #[inline]
    fn bias_command(self) -> u8 {
        match (self.bias, self.commons) {
            (Bias::Half, Commons::Two) => cmd::BIAS_1_2_2COM,
            (Bias::Half, Commons::Three) => cmd::BIAS_1_2_3COM,
            (Bias::Half, Commons::Four) => cmd::BIAS_1_2_4COM,
            (Bias::Third, Commons::Two) => cmd::BIAS_1_3_2COM,
            (Bias::Third, Commons::Three) => cmd::BIAS_1_3_3COM,
            (Bias::Third, Commons::Four) => cmd::BIAS_1_3_4COM,
        }
    }
}

/// High-level, ergonomic HT1621B driver.
///
/// Wraps [`Ht1621bBus`] and exposes semantic, command-based operations so
/// callers never handle raw command codes.  RAM data helpers
/// ([`Ht1621b::write_byte`] etc.) are delegated to the bus for display use.
pub struct Ht1621b<CS, WR, DA, D> {
    bus: Ht1621bBus<CS, WR, DA, D>,
}

impl<CS, WR, DA, D> Ht1621b<CS, WR, DA, D>
where
    CS: OutputPin,
    WR: OutputPin,
    DA: OutputPin,
    D: DelayNs,
{
    /// Create the driver and run the power-on initialisation sequence.
    ///
    /// `async_delay` is borrowed only for the duration of this call and is
    /// used for the long, ms-scale waits (power-on settle and clock-dependent
    /// oscillator stabilisation) so the executor is not blocked; the short
    /// bit-level bus timing still uses the owned blocking `delay`.
    ///
    /// Sequence: ~1 ms power-on settle → bias/COM → clock source →
    /// system disable → system enable → oscillator-stabilisation delay
    /// (clock-dependent) → clear RAM → LCD on.  A blank display is shown as
    /// soon as the bias generator turns on.
    pub async fn new<AD>(
        cs: CS,
        wr: WR,
        da: DA,
        delay: D,
        async_delay: &mut AD,
        config: Config,
    ) -> Self
    where
        AD: embedded_hal_async::delay::DelayNs,
    {
        let bus = Ht1621bBus::new(cs, wr, da, delay);
        let mut this = Self { bus };
        async_delay.delay_ms(1).await;
        this.bus.write_command(config.bias_command());
        this.bus.write_command(config.clock.command());
        this.bus.write_command(cmd::SYS_DIS);
        this.bus.write_command(cmd::SYS_EN);
        async_delay.delay_ms(config.clock.stabilize_ms()).await;
        this.clear();
        this.bus.write_command(cmd::LCD_ON);
        this
    }

    /// Clear all display RAM (32 × 4 bits) to zero, blanking every segment.
    #[inline]
    pub fn clear(&mut self) {
        self.bus.write_bytes(u6::new(0), &[0u8; 16]);
    }

    /// Apply a new [`Config`] at runtime.
    ///
    /// Updates the LCD bias/COM and system clock source (BIAS + clock
    /// commands).  Other state (LCD on/off, time base, tone) is left
    /// untouched.
    #[inline]
    pub fn set_config(&mut self, config: Config) {
        self.bus.write_command(config.bias_command());
        self.bus.write_command(config.clock.command());
    }

    /// Turn the LCD bias generator on (LCD ON).
    #[inline]
    pub fn lcd_on(&mut self) {
        self.bus.write_command(cmd::LCD_ON);
    }

    /// Turn the LCD bias generator off (LCD OFF).
    #[inline]
    pub fn lcd_off(&mut self) {
        self.bus.write_command(cmd::LCD_OFF);
    }

    /// Enter lowest-power sleep: blank the display, then stop the system
    /// oscillator and LCD bias generator (LCD OFF + SYS DIS).
    ///
    /// The time base / WDT stop while asleep and RAM should be considered
    /// stale on wake.  Use [`Ht1621b::wake`] to resume.
    #[inline]
    pub fn sleep(&mut self) {
        self.bus.write_command(cmd::LCD_OFF);
        self.bus.write_command(cmd::SYS_DIS);
    }

    /// Wake from [`Ht1621b::sleep`]: restart the oscillator and turn the LCD
    /// bias generator back on (SYS EN + LCD ON).
    ///
    /// RAM contents are not restored here; rewrite the display data after
    /// waking if needed.
    #[inline]
    pub fn wake(&mut self) {
        self.bus.write_command(cmd::SYS_EN);
        self.bus.write_command(cmd::LCD_ON);
    }

    /// Turn the buzzer on at the given frequency.
    ///
    /// Sets the tone frequency (`TONE 4k`/`TONE 2k`) then enables output
    /// (`TONE ON`).
    #[inline]
    pub fn tone_on(&mut self, freq: ToneFreq) {
        self.bus.write_command(freq.command());
        self.bus.write_command(cmd::TONE_ON);
    }

    /// Turn the buzzer off (TONE OFF).
    #[inline]
    pub fn tone_off(&mut self) {
        self.bus.write_command(cmd::TONE_OFF);
    }

    /// Configure the time-base / WDT subsystem.
    ///
    /// Time base and WDT are mutually exclusive (shared generator); the
    /// unused one is disabled here, the frequency set, the counter cleared,
    /// and IRQ output enabled/disabled to match the mode.
    pub fn set_timer_mode(&mut self, mode: TimerMode) {
        match mode {
            TimerMode::Off => {
                self.bus.write_command(cmd::TIMER_DIS);
                self.bus.write_command(cmd::WDT_DIS);
                self.bus.write_command(cmd::IRQ_DIS);
            }
            TimerMode::TimeBase(freq) => {
                self.bus.write_command(cmd::WDT_DIS);
                self.bus.write_command(freq.command());
                self.bus.write_command(cmd::CLR_TIMER);
                self.bus.write_command(cmd::TIMER_EN);
                self.bus.write_command(cmd::IRQ_EN);
            }
            TimerMode::Watchdog(freq) => {
                self.bus.write_command(cmd::TIMER_DIS);
                self.bus.write_command(freq.command());
                self.bus.write_command(cmd::CLR_WDT);
                self.bus.write_command(cmd::WDT_EN);
                self.bus.write_command(cmd::IRQ_EN);
            }
        }
    }

    /// Feed the watchdog (CLR WDT); call periodically in `Watchdog` mode.
    #[inline]
    pub fn wdt_feed(&mut self) {
        self.bus.write_command(cmd::CLR_WDT);
    }

    /// Reset the time-base counter / realign phase (CLR TIMER).
    #[inline]
    pub fn timer_clear(&mut self) {
        self.bus.write_command(cmd::CLR_TIMER);
    }

    /// Access the underlying protocol layer for raw operations.
    #[inline]
    pub fn bus(&mut self) -> &mut Ht1621bBus<CS, WR, DA, D> {
        &mut self.bus
    }

    /// Burst-write 4-bit words to RAM (see [`Ht1621bBus::write_words`]).
    #[inline]
    pub fn write_words(&mut self, addr: u6, words: &[u4]) {
        self.bus.write_words(addr, words);
    }

    /// Write a single 4-bit word to RAM (see [`Ht1621bBus::write_word`]).
    #[inline]
    pub fn write_word(&mut self, addr: u6, word: u4) {
        self.bus.write_word(addr, word);
    }

    /// Burst-write bytes to RAM (see [`Ht1621bBus::write_bytes`]).
    #[inline]
    pub fn write_bytes(&mut self, addr: u6, data: &[u8]) {
        self.bus.write_bytes(addr, data);
    }

    /// Write a single byte to RAM (see [`Ht1621bBus::write_byte`]).
    #[inline]
    pub fn write_byte(&mut self, addr: u6, data: u8) {
        self.bus.write_byte(addr, data);
    }
}