GS32Display1306

GS32Display1306 — это специализированная C++ библиотека для среды разработки Arduino IDE, созданная для управления OLED-дисплеями на базе чипа SSD1306 (128x64) по высокоскоростному интерфейсу SPI.

Данная библиотека разработана как часть экосистемы GS32Bios и оптимизирована для кастомизации и интеграции электроники в нестандартные корпуса (например, ТВ-ресиверы General Satellite GS 8304).

✨ Ключевые особенности

• Защита от зависания софта (Safe Boot): Если дисплей отключен, поврежден или неправильно подключен, метод begin() вернет false. При этом выполнение основного кода ESP32 не блокируется, а все последующие команды отрисовки игнорируются, не тратя ресурсы процессора.
• Аппаратное смещение (Global Offset): Возможность программно сдвинуть всю выводимую картинку по осям X и Y, чтобы идеально подогнать интерфейс под физическое пластиковое окошко передней панели корпуса.
• Динамическая настройка GPIO: Все пины управления SPI назначаются прямо в setup(), что избавляет от необходимости жестко прописывать их при объявлении объекта.
• Кастомные и встроенные иконки: Библиотека содержит встроенные оптимизированные иконки 16x16 (Wi-Fi, Bluetooth, Термометр, Влажность) без графических артефактов и поддерживает отрисовку любых пользовательских битмапов (PROGMEM) любого размера.
• Гибкое позиционирование: Полный ручной контроль координат, зазоров и размеров шрифта (1, 2, 3, 4) для каждого кадра отдельно.

---

🔌 Схема подключения (ESP32 WROOM-32 ➡️ OLED SPI)

Вы можете использовать любые свободные GPIO вашего ESP32, однако для максимальной стабильности рекомендуется использовать аппаратную шину VSPI:

Название пина на OLED	Пин ESP32 (Рекомендуемый)	Описание
GND	GND	Земля
VCC	3.3V / 5V	Питание дисплея
D0 (CLK)	GPIO 18	Тактовый сигнал SPI (SCK)
D1 (MOSI)	GPIO 23	Передача данных SPI (MOSI)
RES (RESET)	GPIO 4	Сброс дисплея
DC (A0)	GPIO 2	Выбор Данные/Команды
CS	GPIO 5	Выбор устройства на шине

---

📦 Установка

1. Скачайте репозиторий в виде .zip архива.
2. В Arduino IDE перейдите в меню: Скетч ➡️ Подключить библиотеку ➡️ Добавить .ZIP библиотеку...
3. Выберите скачанный архив.

💡 Важно: Библиотека автоматически потянет за собой зависимости от Adafruit SSD1306 и Adafruit GFX Library. Убедитесь, что они установлены в вашем менеджере библиотек.

---

🛠️ Документация функций (API)

Инициализация и статус

• GS32Display1306() — Конструктор класса. Создает пустой объект.
• bool begin(uint8_t mosi, uint8_t clk, uint8_t dc, uint8_t rst, uint8_t cs) — Инициализирует дисплей с указанными GPIO. Возвращает true при успехе и false, если дисплей не обнаружен.
• bool isReady() const — Возвращает true, если дисплей успешно работает, и false в случае сбоя.

Конфигурация геометрии

• void setGlobalOffset(int offsetX, int offsetY) — Задает постоянный сдвиг (в пикселях) для абсолютно всех элементов на экране. Используется для центрирования картинки в узких окошках корпусов.

Отрисовка элементов

• void clear() — Полностью очищает буфер экрана.
• void drawText(String text, int x, int y, uint8_t textSize) — Очищает экран и выводит только текст по координатам x, y (с учетом глобального смещения) и заданным размером шрифта textSize (1, 2, 3...).
• void drawIconText(const unsigned char* bitmap, int iconW, int iconH, String text, int x, int y, uint8_t textSize, int textOffsetFromIcon = 6) — Очищает экран и выводит горизонтальный блок из иконки и текста. Автоматически центрирует текст по вертикали относительно высоты иконки.
  • Если вместо bitmap передать nullptr, иконка не будет нарисована, а текст сместится к левому краю.

Встроенные иконки (16x16 пикселей)

• GS32_ICON_WIFI — Значок беспроводной сети.
• GS32_ICON_BT — Значок Bluetooth.
• GS32_ICON_TEMP — Значок термометра.
• GS32_ICON_HUM — Значок капли (влажность).

---

💻 Пример использования

Пример кода для интеграции в основной проект GS32Bios.ino:

#include "GS32Display1306.h"

// Создаем пустой объект дисплея
GS32Display1306 display;

// Пример создания собственной иконки (Стрелка вверх 8x8)
const unsigned char customArrow[] PROGMEM = {
  0x18, 0x3c, 0x7e, 0xff, 0x18, 0x18, 0x18, 0x18
};

void setup() {
  Serial.begin(115200);

  // Инициализация в setup(). Порядок: MOSI, CLK, DC, RESET, CS
  if(!display.begin(23, 18, 2, 4, 5)) {
    Serial.println("[ОШИБКА]: Дисплей передней панели не найден!");
    Serial.println("ESP32 продолжает работу в фоновом режиме...");
  } else {
    Serial.println("[ОК]: Дисплей успешно запущен.");
    // Сдвигаем всю картинку на 12 пикселей вправо и на 24 вниз под окошко GS 8304
    display.setGlobalOffset(12, 24); 
  }
}

void loop() {
  // 1. Вывод системного статуса со встроенной иконкой Wi-Fi (шрифт размера 2)
  display.drawIconText(GS32_ICON_WIFI, 16, 16, "ONLINE", 0, 0, 2);
  delay(2500);

  // 2. Вывод данных с кастомной иконкой 8x8 и увеличенным отступом текста
  display.drawIconText(customArrow, 8, 8, "UPDATE", 0, 4, 2, 10);
  delay(2500);

  // 3. Вывод только крупных часов (шрифт размера 3) без иконки
  display.drawText("12:45", 10, 0, 3);
  delay(2500);
}

📜 Лицензия

Этот проект является частью экосистемы GS32Bios и распространяется под лицензией MIT. Вы можете свободно использовать, модифицировать и распространять данный код в своих некоммерческих и коммерческих проектах.