lcd_parallel_bus 0.1.0

use crate::{bus::LcdBus, Chip, Config, Layout, LcdError};
use embedded_hal_async::delay::DelayNs;

/// Represents the LCD.
///
/// This struct holds together the bus, the LCD config, and the layout of the display. Most
/// configuration options can be set via the Lcd methods. Only the function_mode of the chip, ie.
/// the interface bandwidth, the font, and the line count, has to be configured via the
/// [ChipConfig][crate::ChipConfig]
/// methods before the Lcd is created. The line count in the [ChipConfig][crate::ChipConfig] should not be confused with
/// the layout. It is related to the mapping of DDRAM adresses to the display positions, see the
/// HD44780 reference manual for further information.
pub struct Lcd<Bus> {
    bus: Bus,
    layout: Layout,
    config: Config,
}

impl<Bus: LcdBus> Lcd<Bus> {
    /// Returns Lcd object.
    ///
    /// Not all combinations of bus, layout, and config objects can be combined together. The
    /// specific variants should result in a plausible combination. A layout that has lines
    /// configured to be controlled via Chip::Two combined with a [Config::SingleChip] or a bus type
    /// that can only communicate with a single chip will not work.
    ///
    /// The following errors can occur:
    ///   * [LcdError::InitSingleChipWrongLayout]: When config is [Config::SingleChip], but layout
    ///     contains lines to be controlled via [Chip::Two].
    ///   * [LcdError::InitSingleChipWrongBus]: When config is [Config::SingleChip], but bus has no E2
    ///     pin.
    ///   * [LcdError::InitDoubleChipWrongLayout]: When config is [Config::DoubleChip], but layout only
    ///     addresses [Chip::One].
    ///   * [LcdError::InitDoubleChipWrongBus]: When config is [Config::DoubleChip], but bus has no E2
    ///     pin.
    ///
    /// # Example
    ///
    /// ```
    /// let layout = Layout::TwoLine([(Chip::One, [0, 39]), (Chip::One, [64, 103])]);
    /// let mut chip_config = ChipConfig::default();
    /// chip_config.display_on();
    /// let bus = ParallelBus4SingleChip::new(rs, rw, en, d4, d5, d6, d7);
    /// let mut lcd = Lcd::new(bus, layout, Config::SingleChip([chip_config]))?;
    /// ```
    pub fn new(bus: Bus, layout: Layout, config: Config) -> Result<Self, LcdError> {
        match config {
            Config::SingleChip(_) => {
                for i in 0..layout.line_count() {
                    match layout.line_config(i)?.0 {
                        Chip::One => continue,
                        _ => return Err(LcdError::InitSingleChipWrongLayout),
                    }
                }
                if bus.has_en2() {
                    return Err(LcdError::InitSingleChipWrongBus);
                }
                Ok(Lcd {
                    bus,
                    layout,
                    config,
                })
            }
            Config::DoubleChip(_) => {
                let mut chip_two_used = false;
                for i in 0..layout.line_count() {
                    match layout.line_config(i)?.0 {
                        Chip::Two => chip_two_used = true,
                        _ => continue,
                    };
                }
                if !chip_two_used {
                    return Err(LcdError::InitDoubleChipWrongLayout);
                }
                if bus.has_en2() {
                    Ok(Lcd {
                        bus,
                        layout,
                        config,
                    })
                } else {
                    Err(LcdError::InitDoubleChipWrongBus)
                }
            }
        }
    }

    /// Initializes the specified chip.
    ///
    /// Init needs to be called before communication with the lcd. Multiple calls are possible.
    ///
    /// # Example
    ///
    /// ```
    /// lcd.init(&mut delay, Chip::One).await?;
    /// ```
    pub async fn init<D: DelayNs>(&mut self, delay: &mut D, chip: Chip) -> Result<(), LcdError> {
        self.bus
            .init(
                delay,
                chip,
                self.config.chip_config(chip)?.function_mode,
                self.config.chip_config(chip)?.display_mode,
                self.config.chip_config(chip)?.entry_mode,
            )
            .await
    }

    /// Prints the given string to given line starting from specific position.
    ///
    /// Convenience method that transforms the string to bytes and calls [Lcd::print_bytes]. See
    /// docs [here][Lcd::print_bytes].
    ///
    /// # Example
    ///
    /// ```
    /// lcd.print(&mut delay, 0, 0, "Hi there,").await?;
    /// ```
    pub async fn print<D: DelayNs>(
        &mut self,
        delay: &mut D,
        line: usize,
        column: u8,
        string: &str,
    ) -> Result<(), LcdError> {
        self.print_bytes(delay, line, column, string.as_bytes())
            .await
    }

    /// Prints the given byte slice to given line starting from specific position.
    ///
    /// Column is the position within the address range for that given line, starting at 0.
    /// If column is bigger than the length of the address range Err([LcdError::PrintStartOutsideLayout]) is returned.
    /// If the slice is bigger than the remaining address range, the slice will be silently truncated.
    pub async fn print_bytes<D: DelayNs>(
        &mut self,
        delay: &mut D,
        line: usize,
        column: u8,
        byte_slice: &[u8],
    ) -> Result<(), LcdError> {
        let (chip, address_range) = self.layout.line_config(line)?;
        if column > address_range[1] - address_range[0] {
            return Err(LcdError::PrintStartOutsideLayout);
        }
        let increment_mode = self.config.chip_config(chip)?.entry_mode & 0b0000_0010;
        let printable_char_count = match increment_mode {
            2 => {
                if (address_range[1] - address_range[0] + 1 - column) as usize
                    >= byte_slice.len() - 1
                {
                    byte_slice.len()
                } else {
                    (address_range[1] - address_range[0] + 1 - column) as usize
                }
            }
            _ => {
                if column as usize >= byte_slice.len() - 1 {
                    byte_slice.len()
                } else {
                    column as usize
                }
            }
        };
        self.write_instruction(delay, chip, 0b1000_0000 | (address_range[0] + column))
            .await?;
        for byte in byte_slice.iter().take(printable_char_count) {
            self.write_data(delay, chip, *byte).await?;
        }
        Ok(())
    }

    /// Turns off display for specified chip.
    pub async fn display_off<D: DelayNs>(
        &mut self,
        delay: &mut D,
        chip: Chip,
    ) -> Result<(), LcdError> {
        self.config.chip_config(chip)?.display_off();
        let display_mode = self.config.chip_config(chip)?.display_mode;
        self.write_instruction(delay, chip, display_mode).await
    }

    /// Turns on display for specified chip.
    pub async fn display_on<D: DelayNs>(
        &mut self,
        delay: &mut D,
        chip: Chip,
    ) -> Result<(), LcdError> {
        self.config.chip_config(chip)?.display_on();
        let display_mode = self.config.chip_config(chip)?.display_mode;
        self.write_instruction(delay, chip, display_mode).await
    }

    /// Turns off cursor for specified chip.
    pub async fn cursor_off<D: DelayNs>(
        &mut self,
        delay: &mut D,
        chip: Chip,
    ) -> Result<(), LcdError> {
        self.config.chip_config(chip)?.cursor_off();
        let display_mode = self.config.chip_config(chip)?.display_mode;
        self.write_instruction(delay, chip, display_mode).await
    }

    /// Turns on cursor for specified chip.
    pub async fn cursor_on<D: DelayNs>(
        &mut self,
        delay: &mut D,
        chip: Chip,
    ) -> Result<(), LcdError> {
        self.config.chip_config(chip)?.cursor_on();
        let display_mode = self.config.chip_config(chip)?.display_mode;
        self.write_instruction(delay, chip, display_mode).await
    }

    /// Turns off blink for specified chip.
    pub async fn blink_off<D: DelayNs>(
        &mut self,
        delay: &mut D,
        chip: Chip,
    ) -> Result<(), LcdError> {
        self.config.chip_config(chip)?.blink_off();
        let display_mode = self.config.chip_config(chip)?.display_mode;
        self.write_instruction(delay, chip, display_mode).await
    }

    /// Turns on blink for specified chip.
    pub async fn blink_on<D: DelayNs>(
        &mut self,
        delay: &mut D,
        chip: Chip,
    ) -> Result<(), LcdError> {
        self.config.chip_config(chip)?.blink_on();
        let display_mode = self.config.chip_config(chip)?.display_mode;
        self.write_instruction(delay, chip, display_mode).await
    }

    /// Turns on writing from right to left for specified chip.
    pub async fn right_to_left<D: DelayNs>(
        &mut self,
        delay: &mut D,
        chip: Chip,
    ) -> Result<(), LcdError> {
        self.config.chip_config(chip)?.right_to_left();
        let entry_mode = self.config.chip_config(chip)?.entry_mode;
        self.write_instruction(delay, chip, entry_mode).await
    }

    /// Turns on writing from left to right for specified chip.
    pub async fn left_to_right<D: DelayNs>(
        &mut self,
        delay: &mut D,
        chip: Chip,
    ) -> Result<(), LcdError> {
        self.config.chip_config(chip)?.left_to_right();
        let entry_mode = self.config.chip_config(chip)?.entry_mode;
        self.write_instruction(delay, chip, entry_mode).await
    }

    /// Turns off autoscroll for specified chip.
    pub async fn autoscroll_off<D: DelayNs>(
        &mut self,
        delay: &mut D,
        chip: Chip,
    ) -> Result<(), LcdError> {
        self.config.chip_config(chip)?.autoscroll_off();
        let entry_mode = self.config.chip_config(chip)?.entry_mode;
        self.write_instruction(delay, chip, entry_mode).await
    }

    /// Turns on autoscroll for specified chip.
    ///
    /// For each character inserted the display moves one character along.
    pub async fn autoscroll_on<D: DelayNs>(
        &mut self,
        delay: &mut D,
        chip: Chip,
    ) -> Result<(), LcdError> {
        self.config.chip_config(chip)?.autoscroll_on();
        let entry_mode = self.config.chip_config(chip)?.entry_mode;
        self.write_instruction(delay, chip, entry_mode).await?;
        Ok(())
    }

    /// Clears display and at same time moves cursor to first address for specified chip.
    pub async fn clear_display<D: DelayNs>(
        &mut self,
        delay: &mut D,
        chip: Chip,
    ) -> Result<(), LcdError> {
        self.write_instruction(delay, chip, 0b0000_0001).await
    }

    /// Sets cursor to first address for specified chip.
    pub async fn return_home<D: DelayNs>(
        &mut self,
        delay: &mut D,
        chip: Chip,
    ) -> Result<(), LcdError> {
        self.write_instruction(delay, chip, 0b0000_0010).await
    }

    /// Moves cursor one address to the left for specified chip.
    pub async fn move_cursor_left<D: DelayNs>(
        &mut self,
        delay: &mut D,
        chip: Chip,
    ) -> Result<(), LcdError> {
        self.write_instruction(delay, chip, 0b0001_0000).await
    }

    /// Moves cursor one address to the right for specified chip.
    pub async fn move_cursor_right<D: DelayNs>(
        &mut self,
        delay: &mut D,
        chip: Chip,
    ) -> Result<(), LcdError> {
        self.write_instruction(delay, chip, 0b0001_0100).await
    }

    /// Scrolls display one step to the left for specified chip.
    pub async fn scroll_display_left<D: DelayNs>(
        &mut self,
        delay: &mut D,
        chip: Chip,
    ) -> Result<(), LcdError> {
        self.write_instruction(delay, chip, 0b0001_1100).await
    }

    /// Scrolls display one step to the right for specified chip.
    pub async fn scroll_display_right<D: DelayNs>(
        &mut self,
        delay: &mut D,
        chip: Chip,
    ) -> Result<(), LcdError> {
        self.write_instruction(delay, chip, 0b0001_1000).await
    }

    /// Sets address of CGRAM for specified chip to specified address.
    pub async fn set_cg_address<D: DelayNs>(
        &mut self,
        delay: &mut D,
        chip: Chip,
        address: u8,
    ) -> Result<(), LcdError> {
        self.write_instruction(delay, chip, 0b0100_0000 | (0b0011_1111 & address))
            .await
    }

    /// Sets address of DDRAM for specified chip to specified address.
    pub async fn set_dd_address<D: DelayNs>(
        &mut self,
        delay: &mut D,
        chip: Chip,
        address: u8,
    ) -> Result<(), LcdError> {
        self.write_instruction(delay, chip, 0b1000_0000 | (0b0111_1111 & address))
            .await
    }

    /// Reads one byte from the bus for specified chip.
    pub async fn read_data<D: DelayNs>(
        &mut self,
        delay: &mut D,
        chip: Chip,
    ) -> Result<u8, LcdError> {
        self.bus.wait_for_display(delay, chip).await?;
        self.bus.read_data(delay, chip).await
    }

    /// Reads the busy flag and the current address of the address counter for specified chip.
    pub async fn busy_flag_and_address_counter<D: DelayNs>(
        &mut self,
        delay: &mut D,
        chip: Chip,
    ) -> Result<(bool, u8), LcdError> {
        self.bus.wait_for_display(delay, chip).await?;
        self.bus.busy_flag_and_address_counter(delay, chip).await
    }

    /// Makes one instruction to specified chip.
    pub async fn write_instruction<D: DelayNs>(
        &mut self,
        delay: &mut D,
        chip: Chip,
        instruction: u8,
    ) -> Result<(), LcdError> {
        self.bus.wait_for_display(delay, chip).await?;
        self.bus.write_instruction(delay, chip, instruction).await
    }

    /// Writes one byte to specified chip.
    pub async fn write_data<D: DelayNs>(
        &mut self,
        delay: &mut D,
        chip: Chip,
        data: u8,
    ) -> Result<(), LcdError> {
        self.bus.wait_for_display(delay, chip).await?;
        self.bus.write_data(delay, chip, data).await
    }

    /// Sets up a custom character for specified chip.
    ///
    /// It is possible to store up to eight custom characters in the addresses from 0 to 7.
    /// They are defined via arrays of eight bytes in which the first five bits represent the pixel
    /// value of each line. A one represents a "dark" pixel.
    ///
    /// The characters can be used by printing the bytes from 0 to 7.
    pub async fn set_custom_character<D: DelayNs>(
        &mut self,
        delay: &mut D,
        chip: Chip,
        address: u8,
        pattern: [u8; 8],
    ) -> Result<(), LcdError> {
        if (address & 0b0111) != address {
            return Err(LcdError::InvalidCGAddress);
        }
        self.set_cg_address(delay, chip, address << 3).await?;
        for line in pattern.iter() {
            self.write_data(delay, chip, line & 0b0001_1111).await?;
        }
        Ok(())
    }

    /// Destructs the Lcd and returns the bus, layout, and config.
    pub fn release(self) -> (Bus, Layout, Config) {
        (self.bus, self.layout, self.config)
    }
}