📖 MicroPython SSD13XX Reader

Электронная книга (ридер) на базе Raspberry Pi Pico (RP2040) и OLED-дисплея SSD1306 с I²C-интерфейсом.

Проект позволяет читать текстовые файлы, разбитые на главы или темы, с удобной навигацией по двум кнопкам. Поддерживается транслитерация русского языка, разбивка длинных строк, сглаживание непечатаемых символов и виртуальный пейджер (работа с большими файлами без загрузки целиком в память).

---

🎯 Возможности

• ✅ Поддержка SSD1306 (128×64, I²C)
• ✅ Чтение текстовых файлов с карты памяти / внутренней файловой системы
• ✅ Транслитерация кириллицы в латиницу (для отображения на дисплее без кириллического шрифта)
• ✅ Виртуальный пейджер — файл не загружается целиком, читается по страницам (экономия RAM)
• ✅ Две кнопки навигации: листание вперёд/назад и выбор файла
• ✅ Автоматическая сборка меню из всех .txt, .md, .py и т.д. файлов в папке /chapters
• ✅ Бегущая строка для длинных имён файлов и заголовков
• ✅ Регулировка яркости дисплея (3 уровня)
• ✅ Утилиты на ПК для разбивки книги на главы (split_chapters.py) или вложенные темы (split_topics.py)
• ✅ Визуальный редактор спрайтов / чёрно-белых картинок (HTML) для создания кастомной графики

---

🧱 Аппаратные требования

Компонент	Рекомендация
Плата	Raspberry Pi Pico / Pico W / RP2040
Дисплей	SSD1306 (128×64) с I²C
Кнопки	2 тактовые кнопки (подтяжка к 3.3V)
Светодиод	Встроенный на GP25 (опционально)
Память	2 МБ Flash (достаточно для текстов)

Файлы для чтения хранятся на внутренней файловой системе MicroPython.

---

🔌 Подключение дисплея и кнопок

Дисплей SSD1306 (I²C)

SSD1306	RP2040 (Pico)
VCC	3.3V (или 5V)
GND	GND
SCL	GP5
SDA	GP4

В main.py используется I2C(0, sda=Pin(4), scl=Pin(5)). При необходимости поменяйте пины.

Кнопки

Кнопка	Пин	Примечание
Влево / назад	GP11	Подтяжка PULL_DOWN
Вправо / вперёд	GP9	Подтяжка PULL_DOWN

Нажатие обеих кнопок одновременно → выбор (select).

---

📥 Установка и запуск

1️⃣ Установите MicroPython на Pico

Официальное руководство:
Raspberry Pi Pico Python SDK

2️⃣ Загрузите файлы на плату

Скопируйте на Pico:

• main.py
• ssd1306.py (взять из MicroPython-репозитория или использовать прилагаемый)
• ezFBfont.py и ezFBfont_micro_full_05.py (для шрифтов)
• любые текстовые файлы — в папку /chapters

Если папки /chapters нет — создайте её в корне файловой системы.

3️⃣ Подготовка текстов

Для больших книг используйте скрипты на ПК:

python split_chapters.py my_book.txt ./chapters

или

python split_topics.py my_book.txt ./chapters

Они разобьют файл на главы / темы по заголовкам вида:

## 1. Название главы
...
## 2. Другая глава

Имена файлов будут вида: 1_Название_главы.txt, 2_Другая_глава.txt и т.д.

4️⃣ Запуск

Перезагрузите Pico. На дисплее появится меню выбора файла из папки /chapters.

🕹️ Управление

Действие	Кнопки
Перемещение по меню / страницы	Левая / Правая
Выбор файла / выход из чтения	Левая + Правая (одновременно)

В режиме чтения: левая кнопка — предыдущая страница, правая — следующая.

🛠️ Дополнительные утилиты

split_chapters.py

Разбивает книгу на главы по заголовкам ## N. Текст. Создаёт chapters_index.json и отдельные .txt-файлы.

split_topics.py

Разбивает на три уровня: # Глава → ## Параграф → ### Тема. Создаёт topics_index.json и файлы вида 1.2.3_Название_темы.txt.

SSD1306 Pixel Editor.html

Визуальный редактор чёрно-белых картинок (128×64 и другие размеры). Позволяет рисовать пиксели, импортировать изображения (с регулировкой порога яркости) и экспортировать готовый Python-код для отрисовки на дисплей:

IMAGE_DATA = [0x00, 0x3C, ...]
draw_image(display)

Откройте HTML-файл в браузере — никакого сервера не требуется.

⚙️ Настройка под себя

Изменение пинов дисплея

В main.py:

i2c = I2C(0, sda=Pin(4), scl=Pin(5), freq=400000)

Изменение пинов кнопок

BTN_LEFT = Pin(11, Pin.IN, Pin.PULL_DOWN)
BTN_RIGHT = Pin(9, Pin.IN, Pin.PULL_DOWN)

Яркость

По умолчанию: 30%, 60%, 100%. Изменить можно в списке BRIGHT_LEVELS.

Транслитерация

Словарь _RU_MAP в main.py можно расширять любыми символами (математические, валюты, стрелки и т.д.).

🧠 Особенности реализации

• Виртуальный пейджер — при открытии файла сканируются только позиции начала страниц (offsets), сами страницы читаются по требованию. Это позволяет просматривать файлы любого размера, не боясь нехватки RAM.
• Неблокирующая обработка кнопок — меню не тормозит, анимация бегущей строки работает плавно.
• Очистка текста — удаляются непечатаемые управляющие символы, табуляции заменяются пробелами, а переводы строк обрабатываются корректно.

📁 Структура проекта после установки

/
├── main.py
├── ssd1306.py
├── ezFBfont.py
├── ezFBfont_micro_full_05.py
└── chapters/
    ├── 1_First_chapter.txt
    ├── 2_Second_chapter.txt
    ├── chapters_index.json   (если создан split_chapters.py)
    └── ...

🐛 Известные ограничения

• Шрифт только латиница + транслитерация (нет полноценной кириллицы на дисплее)
• Максимальный объём одной страницы — ~2 КБ (защита от переполнения)
• Длина строки ограничена шириной экрана (128 / ширина символа)

🤝 Вклад в проект

Pull Request'ы приветствуются. Если вы нашли баг или хотите добавить поддержку других дисплеев (SSD1315, SH1106) — создавайте Issue.

📜 Лицензия

Проект предоставлен «как есть» без явной лицензии. При значительном использовании кода укажите авторство: ntfs-sys.

Автор: ntfs-sys Репозиторий: github.com/ntfs-sys/micropython_ssd13XX_reader