escpos-vfd 0.3.0

//! Типизированная конфигурация serial-транспорта и параметров дисплея.
//!
//! Вручную созданный [`VfdConfig`] не содержит скрытых значений baud rate, кодовой
//! таблицы или размера экрана. Единственный путь с заранее выбранными настройками -
//! [`VfdConfig::preset`].
//!
//! Главная идея конфигурации: `SerialSettings` описывает только способ подключиться к
//! порту, а `DisplaySettings` описывает геометрию и ESC/POS-поведение устройства. Это
//! позволяет использовать один и тот же дисплей на разных портах или один serial-режим
//! с разными моделями дисплеев без глобальных констант.

use crate::error::ConfigError;
use serialport::{DataBits, FlowControl, Parity, StopBits};
use std::time::Duration;

/// Максимальное число символов в тексте бегущей строки worker-а.
pub const MAX_MARQUEE_CHARS: usize = 4_096;

/// Максимальный размер одной raw-команды, помещаемой в очередь worker-а.
pub const MAX_QUEUED_RAW_BYTES: usize = 64 * 1024;

/// Максимальная скорость бегущей строки в кадрах/символах в секунду.
pub const MAX_MARQUEE_CPS: u32 = 100;

/// Преднастроенные профили известных ESC/POS-совместимых дисплеев.
///
/// Пресеты нужны для сохранения проверенных наборов настроек, но не ограничивают ручную
/// конфигурацию. Если устройство отличается хотя бы одним параметром, используйте
/// [`SerialSettings`], [`DisplaySettings`] и [`VfdConfig::new`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Preset {
    /// Старое поведение этой библиотеки: 20x2, 9600 8N1, CP866, `ESC t 6`.
    ///
    /// Пресет подходит для Epson/ESC/POS-совместимых VFD, которые ожидают кириллицу в
    /// CP866 и выбирают нужную аппаратную таблицу командой `ESC t 6`.
    Epson20x2Cp866,
}

/// Настройки serial-подключения.
///
/// Все поля публичные, чтобы приложение могло точно выставить режим конкретного
/// устройства. Значения проверяются перед открытием порта через [`SerialSettings::validate`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SerialSettings {
    /// Имя serial-порта, например `/dev/cu.usbmodem101`, `/dev/ttyUSB0` или `COM3`.
    pub port_name: String,
    /// Скорость serial-порта в бодах.
    ///
    /// Значение должно быть больше нуля. Типичные значения для VFD: `9600`, `19200`,
    /// `38400`, но библиотека не ограничивает список скоростей.
    pub baud_rate: u32,
    /// Количество бит данных.
    pub data_bits: DataBits,
    /// Проверка чётности.
    pub parity: Parity,
    /// Количество stop bits.
    pub stop_bits: StopBits,
    /// Управление потоком.
    pub flow_control: FlowControl,
    /// Тайм-аут операций serial-порта.
    ///
    /// Значение передаётся в `serialport`; для worker это время ожидания одной
    /// блокирующей операции на устройстве, а не timeout всей очереди команд.
    pub timeout: Duration,
    /// Эксклюзивное открытие serial-порта на Unix.
    ///
    /// По умолчанию включено, чтобы второй процесс не смог случайно писать в тот же
    /// дисплей. Поле доступно только на Unix-платформах.
    #[cfg(unix)]
    pub exclusive: bool,
}

impl SerialSettings {
    /// Создаёт настройки serial-порта с явным baud rate.
    ///
    /// Остальные параметры получают распространённые значения `8N1`, без flow control,
    /// timeout `100 ms` и exclusive mode на Unix. Их можно изменить напрямую в полях
    /// структуры до создания [`VfdConfig`].
    ///
    /// # Ошибки
    ///
    /// Метод сам не возвращает ошибку. Проверка выполняется в [`SerialSettings::validate`]
    /// или при создании [`VfdConfig`].
    ///
    /// # Примеры
    ///
    /// ```
    /// use escpos_vfd::SerialSettings;
    /// use std::time::Duration;
    ///
    /// let mut serial = SerialSettings::new("/dev/ttyUSB0", 9_600);
    /// serial.timeout = Duration::from_millis(250);
    /// assert!(serial.validate().is_ok());
    /// ```
    pub fn new(port_name: impl Into<String>, baud_rate: u32) -> Self {
        Self {
            port_name: port_name.into(),
            baud_rate,
            data_bits: DataBits::Eight,
            parity: Parity::None,
            stop_bits: StopBits::One,
            flow_control: FlowControl::None,
            timeout: Duration::from_millis(100),
            #[cfg(unix)]
            exclusive: true,
        }
    }

    /// Проверяет, что настройки можно применить к serial-порту.
    ///
    /// Метод не открывает устройство. Он только ловит ошибки, которые библиотека может
    /// определить заранее: пустое имя порта и нулевой baud rate.
    ///
    /// # Ошибки
    ///
    /// Возвращает [`ConfigError::EmptyPortName`] или [`ConfigError::ZeroBaudRate`].
    pub fn validate(&self) -> std::result::Result<(), ConfigError> {
        if self.port_name.trim().is_empty() {
            return Err(ConfigError::EmptyPortName);
        }
        if self.baud_rate == 0 {
            return Err(ConfigError::ZeroBaudRate);
        }
        Ok(())
    }
}

/// Текстовая кодировка, используемая для байтов дисплея.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TextEncoding {
    /// IBM866 / CP866.
    ///
    /// Частый выбор для русской кириллицы на Epson/АТОЛ-совместимых дисплеях.
    Cp866,
    /// Windows-1251.
    ///
    /// Используйте, если руководство дисплея явно указывает Windows-1251 или CP1251.
    Windows1251,
    /// Только ASCII, всё вне ASCII заменяется на `?`.
    Ascii,
    /// UTF-8 без перекодирования.
    ///
    /// Подходит только устройствам, которые действительно принимают UTF-8 байты.
    Utf8,
}

/// Настройки геометрии и ESC/POS-команд дисплея.
///
/// `columns` и `rows` задают координатную сетку, используемую для проверки `print_line`
/// и `print_at`. `code_table` управляет только аппаратной командой `ESC t n`, а
/// `encoding` определяет программное преобразование текста в байты.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DisplaySettings {
    /// Количество символов в строке.
    ///
    /// Допустимый диапазон: `1..=255`. Значение используется для обрезки, заполнения
    /// пробелами и проверки координаты `x`.
    pub columns: usize,
    /// Количество строк.
    ///
    /// Допустимый диапазон: `1..=255`. Значение используется для проверки `line` и `y`
    /// во всех методах печати.
    pub rows: usize,
    /// Кодировка текстовых байтов.
    ///
    /// Это программное преобразование Rust-строки в байты транспорта. Оно не выбирает
    /// аппаратную таблицу дисплея.
    pub encoding: TextEncoding,
    /// Таблица символов для `ESC t n`; `None` отключает отправку команды.
    ///
    /// Это отдельная аппаратная команда протокола. Для многих дисплеев CP866 работает
    /// только когда одновременно выбраны `encoding = TextEncoding::Cp866` и нужное
    /// значение `code_table`.
    pub code_table: Option<u8>,
    /// Отправлять `ESC @` при открытии.
    ///
    /// Сброс полезен для predictable startup, но его можно выключить, если приложение
    /// намеренно сохраняет состояние дисплея между открытиями.
    pub reset_on_open: bool,
    /// Поддерживаемый диапазон яркости для `US X n`.
    ///
    /// `None` означает, что типизированная установка яркости запрещена и
    /// [`crate::Vfd::set_brightness`] вернёт [`crate::VfdError::UnsupportedBrightness`].
    pub brightness: Option<std::ops::RangeInclusive<u8>>,
    /// Задержка после изменения яркости.
    ///
    /// Некоторые дисплеи требуют короткую паузу после `US X n`. Sync API блокирует
    /// текущий поток на это время; Tokio API ждёт через async sleep.
    pub brightness_settle: Duration,
}

impl DisplaySettings {
    /// Создаёт ручные настройки дисплея.
    ///
    /// По умолчанию включён `ESC @` при открытии, яркость `1..=4` и короткая задержка
    /// после её изменения. Аппаратная таблица символов не выбирается автоматически:
    /// задайте `code_table = Some(n)`, если вашему дисплею нужна команда `ESC t n`.
    ///
    /// # Ошибки
    ///
    /// Метод сам не возвращает ошибку. Проверка выполняется в
    /// [`DisplaySettings::validate`] или при создании [`VfdConfig`].
    ///
    /// # Примеры
    ///
    /// ```
    /// use escpos_vfd::{DisplaySettings, TextEncoding};
    ///
    /// let mut display = DisplaySettings::new(20, 2, TextEncoding::Cp866);
    /// display.code_table = Some(6);
    /// assert!(display.validate().is_ok());
    /// ```
    pub fn new(columns: usize, rows: usize, encoding: TextEncoding) -> Self {
        Self {
            columns,
            rows,
            encoding,
            code_table: None,
            reset_on_open: true,
            brightness: Some(1..=4),
            brightness_settle: Duration::from_millis(2),
        }
    }

    /// Проверяет геометрию и диапазоны настроек дисплея.
    ///
    /// # Ошибки
    ///
    /// Возвращает [`ConfigError::InvalidColumns`], [`ConfigError::InvalidRows`] или
    /// [`ConfigError::InvalidBrightnessRange`].
    pub fn validate(&self) -> std::result::Result<(), ConfigError> {
        if !(1..=u8::MAX as usize).contains(&self.columns) {
            return Err(ConfigError::InvalidColumns(self.columns));
        }
        if !(1..=u8::MAX as usize).contains(&self.rows) {
            return Err(ConfigError::InvalidRows(self.rows));
        }
        if let Some(range) = &self.brightness {
            let min = *range.start();
            let max = *range.end();
            if min == 0 || min > max {
                return Err(ConfigError::InvalidBrightnessRange { min, max });
            }
        }
        Ok(())
    }
}

/// Полная конфигурация VFD: serial transport плюс геометрия/протокол дисплея.
///
/// Один и тот же `VfdConfig` используется sync и Tokio API. `queue_capacity` влияет
/// только на worker-обёртки; низкоуровневый [`crate::Vfd`] открывает порт напрямую.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct VfdConfig {
    /// Настройки serial-порта.
    pub serial: SerialSettings,
    /// Настройки дисплея.
    pub display: DisplaySettings,
    /// Ёмкость очереди фонового worker.
    ///
    /// Используется только [`crate::VfdWorker`] и `escpos_vfd::tokio::AsyncVfdWorker`.
    /// Значение `32` по умолчанию даёт backpressure без бесконтрольного роста памяти.
    pub queue_capacity: usize,
}

impl VfdConfig {
    /// Создаёт полностью ручную конфигурацию.
    ///
    /// Метод сразу валидирует serial и display настройки, поэтому ошибки конфигурации
    /// возвращаются до попытки открыть устройство.
    ///
    /// # Ошибки
    ///
    /// Возвращает [`ConfigError`], если serial, display или `queue_capacity` содержат
    /// недопустимые значения.
    pub fn new(
        serial: SerialSettings,
        display: DisplaySettings,
    ) -> std::result::Result<Self, ConfigError> {
        let cfg = Self {
            serial,
            display,
            queue_capacity: 32,
        };
        cfg.validate()?;
        Ok(cfg)
    }

    /// Создаёт конфигурацию из пресета.
    ///
    /// `Preset::Epson20x2Cp866` воспроизводит прежние настройки библиотеки: 20x2,
    /// 9600 baud, CP866, `ESC @`, `ESC t 6` и яркость `1..=4`.
    ///
    /// # Ошибки
    ///
    /// Возвращает [`ConfigError::EmptyPortName`], если имя порта пустое.
    pub fn preset(
        port_name: impl Into<String>,
        preset: Preset,
    ) -> std::result::Result<Self, ConfigError> {
        match preset {
            Preset::Epson20x2Cp866 => {
                let serial = SerialSettings::new(port_name, 9600);
                let mut display = DisplaySettings::new(20, 2, TextEncoding::Cp866);
                display.code_table = Some(6);
                display.reset_on_open = true;
                display.brightness = Some(1..=4);
                display.brightness_settle = Duration::from_millis(2);
                Self::new(serial, display)
            }
        }
    }

    /// Устанавливает ёмкость bounded-очереди worker.
    ///
    /// Значение `0` запрещено: такая очередь не смогла бы принять даже команду shutdown.
    ///
    /// # Ошибки
    ///
    /// Возвращает [`ConfigError::ZeroQueueCapacity`] при `capacity = 0`.
    pub fn with_queue_capacity(
        mut self,
        capacity: usize,
    ) -> std::result::Result<Self, ConfigError> {
        self.queue_capacity = capacity;
        self.validate()?;
        Ok(self)
    }

    /// Проверяет serial и display настройки.
    ///
    /// # Ошибки
    ///
    /// Возвращает первый найденный [`ConfigError`].
    pub fn validate(&self) -> std::result::Result<(), ConfigError> {
        self.serial.validate()?;
        self.display.validate()?;
        if self.queue_capacity == 0 {
            return Err(ConfigError::ZeroQueueCapacity);
        }
        Ok(())
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn epson_preset_matches_legacy_settings() {
        let cfg = VfdConfig::preset("COM1", Preset::Epson20x2Cp866).unwrap();

        assert_eq!(cfg.serial.port_name, "COM1");
        assert_eq!(cfg.serial.baud_rate, 9600);
        assert_eq!(cfg.serial.data_bits, DataBits::Eight);
        assert_eq!(cfg.serial.parity, Parity::None);
        assert_eq!(cfg.serial.stop_bits, StopBits::One);
        assert_eq!(cfg.serial.flow_control, FlowControl::None);
        assert_eq!(cfg.serial.timeout, Duration::from_millis(100));
        assert_eq!(cfg.display.columns, 20);
        assert_eq!(cfg.display.rows, 2);
        assert_eq!(cfg.display.encoding, TextEncoding::Cp866);
        assert_eq!(cfg.display.code_table, Some(6));
        assert!(cfg.display.reset_on_open);
        assert_eq!(cfg.display.brightness, Some(1..=4));
    }

    #[test]
    fn manual_config_has_no_hidden_code_table_or_baud() {
        let serial = SerialSettings::new("/tmp/tty", 19_200);
        let display = DisplaySettings::new(16, 4, TextEncoding::Windows1251);
        let cfg = VfdConfig::new(serial, display).unwrap();

        assert_eq!(cfg.serial.baud_rate, 19_200);
        assert_eq!(cfg.display.columns, 16);
        assert_eq!(cfg.display.rows, 4);
        assert_eq!(cfg.display.code_table, None);
    }

    #[test]
    fn invalid_config_values_are_rejected() {
        assert!(matches!(
            SerialSettings::new("", 9600).validate(),
            Err(ConfigError::EmptyPortName)
        ));
        assert!(matches!(
            SerialSettings::new("p", 0).validate(),
            Err(ConfigError::ZeroBaudRate)
        ));
        assert!(matches!(
            DisplaySettings::new(0, 2, TextEncoding::Cp866).validate(),
            Err(ConfigError::InvalidColumns(0))
        ));
        assert!(matches!(
            DisplaySettings::new(20, 256, TextEncoding::Cp866).validate(),
            Err(ConfigError::InvalidRows(256))
        ));

        let mut display = DisplaySettings::new(20, 2, TextEncoding::Cp866);
        let min = 4;
        let max = 1;
        display.brightness = Some(min..=max);
        assert!(matches!(
            display.validate(),
            Err(ConfigError::InvalidBrightnessRange { min: 4, max: 1 })
        ));

        let cfg = VfdConfig::preset("COM1", Preset::Epson20x2Cp866).unwrap();
        assert!(matches!(
            cfg.with_queue_capacity(0),
            Err(ConfigError::ZeroQueueCapacity)
        ));
    }
}