diff --git a/README.md b/README.md
new file mode 100644
index 0000000..fd280fb
--- /dev/null
+++ b/README.md
@@ -0,0 +1,124 @@
+# VFD — библиотека управления VFD-дисплеями (Epson mode)
+
+Небольшая Rust-библиотека для управления **VFD-дисплеями Epson/ESC-совместимого режима**
+(например PD-2600 / PD-2800 и похожие).
+
+Подходит для:
+
+- домашних IoT-проектов
+- индикаторов состояния
+- часов, дашбордов, уведомлений
+- ретро-интерфейсов
+
+Поддержка:
+
+- печать текста по координатам
+- обновление строк через diff (без мерцания)
+- яркость дисплея
+- программный marquee (бегущая строка)
+- работа через serial (USB-UART)
+
+---
+
+## Возможности
+
+- Двухстрочный дисплей (ширина настраивается)
+- `print_line_diff` — обновление только изменённых символов
+- Управление яркостью (1–4)
+- Бегущая строка (marquee) в отдельном воркере
+- Потокобезопасный API (worker + handle)
+
+---
+
+## Установка
+
+Добавьте библиотеку в `Cargo.toml`:
+
+```toml
+[dependencies]
+m = { path = "./path/to/vfd-lib" }
+```
+
+---
+
+## Быстрый старт
+
+```rust
+use m::vfd::VfdConfig;
+use m::worker::VfdWorker;
+
+let cfg = VfdConfig::new("/dev/cu.usbmodem101")
+    .with_width(20);
+
+let worker = VfdWorker::start(cfg)?;
+let vfd = worker.handle();
+
+vfd.clear();
+vfd.set_brightness(2);
+vfd.print_line_diff(1, "Hello VFD!");
+vfd.print_line_diff(2, "It works!");
+```
+
+---
+
+## Бегущая строка (marquee)
+
+```rust
+use std::time::Duration;
+
+vfd.set_marquee_text(" Это пример бегущей строки ");
+vfd.start_marquee(
+    2,                              // строка
+    8,                              // символов в секунду
+    Duration::from_millis(1500),    // пауза в конце
+);
+```
+
+Marquee работает в фоне и не мешает `print_line_diff`,
+если не писать в ту же строку.
+
+---
+
+## Управление яркостью
+
+```rust
+vfd.set_brightness(1); // диапазон 1..4
+```
+
+Яркость можно менять динамически (ночной режим, «дыхание» и т.п.).
+
+---
+
+## Примеры
+
+Запуск через `cargo run --example` или `task`:
+
+```bash
+cargo run --example clock -- /dev/cu.usbmodem101 20 8
+cargo run --example marquee -- /dev/cu.usbmodem101 20 8 1500 2
+cargo run --example brightness -- /dev/cu.usbmodem101 20 800
+```
+
+Примеры:
+
+- `clock` — часы
+- `marquee` — бегущая строка
+- `brightness` — демонстрация яркости
+
+---
+
+## Требования
+
+- Дисплей в **Epson-режиме** (DIP-переключатели)
+- Скорость: 9600 baud
+- Кодировка: CP866 (кириллица)
+
+---
+
+## Идеи для использования
+
+- часы / дата / температура
+- MQTT-дашборд
+- уведомления умного дома
+- статус сервиса / сборки
+- ретро-индикатор