349 lines
15 KiB
Markdown
349 lines
15 KiB
Markdown
# escpos-vfd
|
||
|
||
`escpos-vfd` — Rust-библиотека для символьных VFD-дисплеев покупателя (customer display),
|
||
которые работают через serial-порт и понимают Epson/ESC/POS-совместимые команды.
|
||
|
||
Настройки порта и дисплея разделены: можно независимо задать скорость, геометрию,
|
||
кодировку, аппаратную таблицу символов и яркость. Для проверенного 20×2 дисплея с CP866
|
||
есть готовый пресет `Preset::Epson20x2Cp866`.
|
||
|
||
|
||
|
||
## Установка
|
||
|
||
```toml
|
||
[dependencies]
|
||
escpos-vfd = "0.3"
|
||
```
|
||
|
||
Tokio API подключается отдельным feature:
|
||
|
||
```toml
|
||
[dependencies]
|
||
escpos-vfd = { version = "0.3", features = ["tokio"] }
|
||
```
|
||
|
||
Без feature `tokio` async-зависимости не подключаются.
|
||
|
||
## Быстрый старт
|
||
|
||
Для 20×2 дисплея с `9600 8N1`, CP866 и таблицей `ESC t 6` достаточно готового пресета:
|
||
|
||
```rust,no_run
|
||
use escpos_vfd::{Preset, Vfd, VfdConfig};
|
||
|
||
fn main() -> escpos_vfd::Result<()> {
|
||
let config = VfdConfig::preset(
|
||
"/dev/cu.usbmodem101",
|
||
Preset::Epson20x2Cp866,
|
||
)?;
|
||
|
||
let mut display = Vfd::open(config)?;
|
||
|
||
display.clear()?;
|
||
display.set_brightness(2)?;
|
||
display.print_line(1, "Привет!")?;
|
||
display.print_line(2, "escpos-vfd")?;
|
||
|
||
Ok(())
|
||
}
|
||
```
|
||
|
||
Полный пример: [examples/preset_sync.rs](examples/preset_sync.rs).
|
||
|
||
## Что выбрать
|
||
|
||
| Задача | API |
|
||
| --- | --- |
|
||
| Запустить проверенный 20×2 CP866 дисплей | `VfdConfig::preset(...)` |
|
||
| Настроить другой дисплей | `SerialSettings` + `DisplaySettings` |
|
||
| Писать напрямую из текущего потока | `Vfd` |
|
||
| Отправлять команды из нескольких потоков | `VfdWorker` + `VfdHandle` |
|
||
| Писать напрямую из Tokio task | `tokio::AsyncVfd` |
|
||
| Отправлять команды из нескольких Tokio tasks | `tokio::AsyncVfdWorker` |
|
||
| Отправить нестандартную команду | `write_raw(...)` |
|
||
|
||
## Настройка другого дисплея
|
||
|
||
Пресет не обязателен. Параметры serial-порта и дисплея можно задать вручную:
|
||
|
||
```rust,no_run
|
||
use escpos_vfd::{DisplaySettings, SerialSettings, TextEncoding, Vfd, VfdConfig};
|
||
use serialport::{DataBits, FlowControl, Parity, StopBits};
|
||
use std::time::Duration;
|
||
|
||
fn main() -> escpos_vfd::Result<()> {
|
||
let mut serial = SerialSettings::new("/dev/ttyUSB0", 9_600);
|
||
serial.data_bits = DataBits::Eight;
|
||
serial.parity = Parity::None;
|
||
serial.stop_bits = StopBits::One;
|
||
serial.flow_control = FlowControl::None;
|
||
serial.timeout = Duration::from_millis(100);
|
||
|
||
let mut display = DisplaySettings::new(20, 2, TextEncoding::Cp866);
|
||
display.code_table = Some(6);
|
||
display.brightness = Some(1..=4);
|
||
|
||
let config = VfdConfig::new(serial, display)?;
|
||
let mut vfd = Vfd::open(config)?;
|
||
|
||
vfd.print_line(1, "Ручной режим")?;
|
||
vfd.print_at(1, 2, "20x2, CP866")?;
|
||
|
||
Ok(())
|
||
}
|
||
```
|
||
|
||
Полный пример: [examples/manual_sync.rs](examples/manual_sync.rs).
|
||
|
||
### Serial-порт
|
||
|
||
`SerialSettings::new(port, baud_rate)` использует обычные значения `8N1`, без flow
|
||
control, с тайм-аутом `100 ms`. На Unix порт по умолчанию открывается эксклюзивно.
|
||
Все эти параметры можно изменить через поля `SerialSettings`.
|
||
|
||
### Дисплей
|
||
|
||
`DisplaySettings::new(columns, rows, encoding)` задаёт геометрию и текстовую кодировку.
|
||
Размеры должны быть в диапазоне `1..=255`.
|
||
|
||
Дополнительно можно настроить:
|
||
|
||
- `code_table` — аппаратную таблицу символов через `ESC t n`;
|
||
- `reset_on_open` — отправку `ESC @` при открытии;
|
||
- `brightness` — допустимый диапазон яркости;
|
||
- `brightness_settle` — паузу после изменения яркости.
|
||
|
||
`VfdConfig` также содержит `queue_capacity` для worker API. По умолчанию очередь вмещает
|
||
32 команды; значение `0` запрещено.
|
||
|
||
## Кодировка и таблица символов
|
||
|
||
Кодировка текста и таблица символов самого дисплея — разные настройки.
|
||
|
||
`TextEncoding` определяет, как Rust-строка превращается в байты:
|
||
|
||
| Значение | Назначение |
|
||
| --- | --- |
|
||
| `Cp866` | CP866 / IBM866 |
|
||
| `Windows1251` | Windows-1251 / CP1251 |
|
||
| `Ascii` | только ASCII, остальные символы заменяются на `?` |
|
||
| `Utf8` | UTF-8 без перекодирования |
|
||
|
||
`code_table` отвечает за команду `ESC t n`. Например, конкретному CP866-дисплею могут
|
||
одновременно понадобиться:
|
||
|
||
```rust
|
||
let mut display = DisplaySettings::new(20, 2, TextEncoding::Cp866);
|
||
display.code_table = Some(6);
|
||
```
|
||
|
||
Если таблица уже выбрана DIP-переключателями или устройство использует другой механизм,
|
||
оставьте `code_table = None`.
|
||
|
||
Перед обычным выводом библиотека заменяет некоторые типографские символы на более
|
||
безопасные для символьного VFD варианты: например, длинное тире на `-`, `№` на `#`, а
|
||
табуляцию на пробел.
|
||
|
||
## Вывод текста
|
||
|
||
Все публичные координаты начинаются с **1**:
|
||
|
||
```rust
|
||
vfd.print_line(1, "Первая строка")?;
|
||
vfd.print_at(6, 2, "текст")?;
|
||
```
|
||
|
||
`print_line()` обрезает слишком длинный текст и дополняет короткий пробелами до ширины
|
||
дисплея. Это позволяет полностью перезаписать строку без остатка предыдущего текста.
|
||
|
||
`print_at()` пишет с указанной позиции и обрезает текст по правому краю. Автоматического
|
||
переноса на следующую строку нет.
|
||
|
||
Текстовые методы заменяют управляющие символы, включая `NUL`, `ESC`, `US`, `CR`, `LF`
|
||
и form feed, пробелами. Для намеренной отправки команд используется только `write_raw()`.
|
||
В CP866 и Windows-1251 каждый неподдерживаемый Unicode-символ заменяется одним `?`,
|
||
поэтому кодирование не нарушает настроенную ширину строки.
|
||
|
||
Неверные координаты возвращают `VfdError::InvalidLine` или
|
||
`VfdError::InvalidCoordinate`.
|
||
|
||
## Worker и частичные обновления
|
||
|
||
`VfdWorker` владеет дисплеем в отдельном потоке, а `VfdHandle` можно клонировать и
|
||
передавать между потоками.
|
||
|
||
Очередь ограничена по размеру: если она заполнена, отправитель ждёт свободное место вместо
|
||
неограниченного накопления команд. Вызов метода handle завершается после фактического
|
||
выполнения команды или ошибки I/O.
|
||
|
||
```rust,no_run
|
||
use escpos_vfd::{Preset, VfdConfig, VfdWorker};
|
||
|
||
fn main() -> escpos_vfd::Result<()> {
|
||
let config = VfdConfig::preset(
|
||
"/dev/cu.usbmodem101",
|
||
Preset::Epson20x2Cp866,
|
||
)?;
|
||
|
||
let worker = VfdWorker::start(config)?;
|
||
let display = worker.handle();
|
||
|
||
display.print_line_diff(1, "Temp: 21.5 C")?;
|
||
display.print_line_diff(2, "Humidity: 42%")?;
|
||
|
||
worker.shutdown()?;
|
||
Ok(())
|
||
}
|
||
```
|
||
|
||
`print_line_diff()` хранит кэш последнего содержимого строк. Если текст не изменился,
|
||
запись не выполняется; если изменился только фрагмент, worker отправляет только изменённые
|
||
смежные диапазоны. Это удобно для часов, статусов и других часто обновляемых значений.
|
||
|
||
Для нормального завершения используйте `VfdWorker::shutdown()`.
|
||
|
||
### Бегущая строка
|
||
|
||
Worker также умеет обновлять marquee по таймеру:
|
||
|
||
```rust
|
||
use std::time::Duration;
|
||
|
||
display.set_marquee_text("Длинный текст для бегущей строки")?;
|
||
display.start_marquee(1, 8, Duration::from_millis(1500))?;
|
||
|
||
// ...
|
||
|
||
display.stop_marquee()?;
|
||
```
|
||
|
||
`cps` задаёт скорость в символах в секунду и ограничен значением
|
||
`MAX_MARQUEE_CPS`; `end_pause` — паузу после полного прохода. Текст ограничен
|
||
`MAX_MARQUEE_CHARS` символами.
|
||
`stop_marquee()` останавливает анимацию, но не очищает уже отображённый текст.
|
||
|
||
## Tokio
|
||
|
||
Feature `tokio` добавляет два варианта API:
|
||
|
||
- `AsyncVfd` — прямой драйвер поверх `AsyncWrite`;
|
||
- `AsyncVfdWorker` — одна задача-писатель, bounded queue и клонируемый
|
||
`AsyncVfdHandle`.
|
||
|
||
```rust,no_run
|
||
use escpos_vfd::tokio::AsyncVfdWorker;
|
||
use escpos_vfd::{Preset, VfdConfig};
|
||
|
||
#[tokio::main]
|
||
async fn main() -> escpos_vfd::Result<()> {
|
||
let config = VfdConfig::preset(
|
||
"/dev/cu.usbmodem101",
|
||
Preset::Epson20x2Cp866,
|
||
)?;
|
||
|
||
let worker = AsyncVfdWorker::start(config).await?;
|
||
let display = worker.handle();
|
||
|
||
display.print_line_diff(1, "Tokio worker").await?;
|
||
display.print_line_diff(2, "async I/O").await?;
|
||
|
||
worker.shutdown().await?;
|
||
Ok(())
|
||
}
|
||
```
|
||
|
||
После попадания команды в очередь отмена ожидающего future не отменяет уже поставленную
|
||
запись в устройство. Для корректного завершения используйте
|
||
`AsyncVfdWorker::shutdown().await`.
|
||
|
||
## Низкоуровневая запись
|
||
|
||
Если нужной команды нет в типизированном API, байты можно отправить напрямую:
|
||
|
||
```rust
|
||
vfd.write_raw(&[0x1b, 0x40])?;
|
||
```
|
||
|
||
`write_raw()` не кодирует и не интерпретирует данные. В worker API такая запись также не
|
||
обновляет строковый кэш, поэтому после raw-команд, меняющих текст на экране, лучше
|
||
выполнить `clear()` или `print_line()`. Размер одной queued raw-команды ограничен
|
||
`MAX_QUEUED_RAW_BYTES`; низкоуровневые `Vfd::write_raw()` и `AsyncVfd::write_raw()`
|
||
пишут предоставленный slice напрямую без промежуточной очереди.
|
||
|
||
Для нестандартных транспортов и диагностики доступен публичный
|
||
`escpos_vfd::codec::EpsonCodec`, который формирует байты команд без открытия serial-порта.
|
||
`EpsonCodec::new(display)` валидирует геометрию и возвращает `Result`.
|
||
|
||
## Ошибки
|
||
|
||
Библиотека использует `escpos_vfd::Result<T> = Result<T, VfdError>` и разделяет ошибки по
|
||
смыслу:
|
||
|
||
| Ошибка | Когда возникает |
|
||
| --- | --- |
|
||
| `VfdError::Config(...)` | неверная конфигурация |
|
||
| `VfdError::Serial(...)` | ошибка открытия или настройки serial-порта |
|
||
| `VfdError::Io(...)` | ошибка записи или `flush` |
|
||
| `VfdError::InvalidCoordinate` | координата вне дисплея |
|
||
| `VfdError::InvalidLine` | строка вне `1..=rows` |
|
||
| `VfdError::UnsupportedBrightness` | неподдерживаемый уровень яркости |
|
||
| `VfdError::QueueClosed` | очередь worker-а закрыта |
|
||
| `VfdError::WorkerStopped` | worker остановился до подтверждения команды |
|
||
| `VfdError::WorkerPanicked` | sync worker завершился с panic |
|
||
| `VfdError::WorkerCancelled` | Tokio worker был отменён |
|
||
|
||
## Примеры
|
||
|
||
В репозитории есть небольшие аппаратные примеры для основных сценариев:
|
||
|
||
| Пример | Что показывает |
|
||
| --- | --- |
|
||
| `preset_sync` | запуск с готовым пресетом |
|
||
| `manual_sync` | ручную конфигурацию |
|
||
| `tokio_worker` | Tokio worker |
|
||
| `clock` | частые diff-обновления |
|
||
| `marquee` | бегущую строку |
|
||
| `brightness` | яркость |
|
||
| `position` | позиционирование |
|
||
| `update_at` | частичные обновления |
|
||
| `blink` | повторную запись в позицию |
|
||
|
||
Например:
|
||
|
||
```bash
|
||
cargo run --example preset_sync -- /dev/cu.usbmodem101
|
||
cargo run --example marquee -- /dev/cu.usbmodem101 20 8 1500 2
|
||
cargo run --features tokio --example tokio_worker -- /dev/cu.usbmodem101 20
|
||
```
|
||
|
||
## Проверка на реальном дисплее
|
||
|
||
Автоматические тесты проверяют формирование команд, кодировки, координаты, кэш строк,
|
||
worker queue, marquee и async-поведение на тестовых транспортах. Конкретное устройство
|
||
всё равно стоит проверить отдельно:
|
||
|
||
1. Выставьте правильный serial/DIP-режим.
|
||
2. Запустите `cargo run --example preset_sync -- <port>`.
|
||
3. Проверьте очистку, строки, кириллицу и яркость.
|
||
4. Проверьте `update_at` и `marquee`.
|
||
5. При использовании Tokio запустите пример `tokio_worker`.
|
||
|
||
## Разработка
|
||
|
||
```bash
|
||
cargo fmt --all -- --check
|
||
cargo clippy --all-targets --no-default-features --locked -- -D warnings
|
||
cargo clippy --all-targets --all-features --locked -- -D warnings
|
||
cargo test --all-targets --no-default-features --locked
|
||
cargo test --all-targets --all-features --locked
|
||
RUSTDOCFLAGS='-D warnings -D missing_docs -D rustdoc::broken_intra_doc_links' \
|
||
cargo doc --all-features --no-deps --locked
|
||
```
|
||
|
||
Подробная документация публичного API: [docs.rs/escpos-vfd](https://docs.rs/escpos-vfd).
|
||
|
||
## Лицензия
|
||
|
||
`escpos-vfd` распространяется под двойной лицензией `MIT OR Apache-2.0`.
|