Библиотека Adafruit SSD1306 и Adafruit GFX

менеджер: Adafruit SSD1306, Adafruit GFX LibraryAdafruitверсия SSD1306 2.5.17, GFX 1.12.6

OLED-дисплеи 0,96″ и 1,3″ на SSD1306: текст, линии, фигуры, картинки. Рисование — из библиотеки GFX.

Дисплей держится в памяти платы как буфер: 128×64 точки — это 1024 байта, половина ОЗУ UNO. Всё рисуется в буфер, потом display() отправляет его целиком. Сами команды рисования — текст, линии, прямоугольники, окружности, битмапы — живут в Adafruit GFX, общей для всех дисплеев Adafruit, поэтому ставятся обе библиотеки.

Менеджер предложит ещё Adafruit BusIO — соглашайтесь, это зависимость. У дисплеев 1,3″ часто стоит не SSD1306, а SH1106: библиотека для него другая, Adafruit SH110X, с тем же набором методов.

Установка и подключение

В менеджере библиотек ищите Adafruit SSD1306, Adafruit GFX Library автора Adafruit. Если менеджер предложит поставить зависимости — соглашайтесь. Как открыть менеджер и что делать, если библиотека не находится, — в общей статье про библиотеки.

#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>

Создание объекта — обычно до setup():

Adafruit_SSD1306 display(128, 64, &Wire, -1);         // ширина, высота, шина, вывод сброса (−1 — нет)
display.begin(SSD1306_SWITCHCAPVCC, 0x3C);              // в setup(); адрес 0x3C или 0x3D

Методы

Только то, что нужно в обычном скетче. Сигнатуры сверены с версией SSD1306 2.5.17, GFX 1.12.6.

begin(uint8_t vcc, uint8_t address): Инициализация: SSD1306_SWITCHCAPVCC и адрес 0x3C (реже 0x3D). false — дисплей не ответил.
clearDisplay(): Очистить буфер. Экран изменится после display().
display(): Отправить буфер на экран. Без него ничего не видно.
setTextSize(uint8_t s): Размер шрифта: 1 — 6×8 точек на символ, 2 — вдвое крупнее.
setTextColor(SSD1306_WHITE): Цвет текста; SSD1306_WHITE, SSD1306_BLACK или (WHITE, BLACK) для инверсии.
setCursor(int16_t x, int16_t y): Куда печатать, в точках от левого верхнего угла.
print(...) / println(...): Вывести текст или число, как в Serial.
drawPixel(x, y, color): Одна точка.
drawLine(x0, y0, x1, y1, color): Линия.
drawRect(x, y, w, h, color) / fillRect(...): Прямоугольник контуром или заливкой.
drawCircle(x, y, r, color) / fillCircle(...): Окружность.
drawBitmap(x, y, bitmap, w, h, color): Монохромная картинка из массива PROGMEM.
invertDisplay(bool): Инвертировать весь экран.
dim(bool): Приглушить яркость.
setRotation(0–3): Повернуть изображение на 90° шагами.

Пример

#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>

Adafruit_SSD1306 display(128, 64, &Wire, -1);

void setup() {
  Serial.begin(9600);
  if (!display.begin(SSD1306_SWITCHCAPVCC, 0x3C)) {
    Serial.println("Дисплей не найден");
    while (1);
  }
  display.setTextColor(SSD1306_WHITE);
}

void loop() {
  int value = analogRead(A0);
  display.clearDisplay();
  display.setTextSize(1);
  display.setCursor(0, 0);
  display.print("A0:");
  display.setTextSize(3);
  display.setCursor(0, 20);
  display.print(value);
  // полоса-индикатор внизу
  display.drawRect(0, 54, 128, 10, SSD1306_WHITE);
  display.fillRect(0, 54, map(value, 0, 1023, 0, 128), 10, SSD1306_WHITE);
  display.display();
  delay(100);
}

Схема одна для любого экрана: очистить буфер, нарисовать, display(). Кириллицу штатный шрифт не умеет — либо латиница, либо свой шрифт через setFont().

На чём попадаются

begin() не проходит

Адрес 0x3D вместо 0x3C или дисплей на SH1106. Проверьте сканером и посмотрите на маркировку контроллера.

Пустой экран, ошибок нет

Нет display() после рисования — самая частая.

Скетч перестал помещаться в память

Буфер экрана съедает килобайт из двух. На UNO остаётся мало; строки заворачивайте в F(), большие массивы — в PROGMEM.

Картинка сдвинута или полосит

Дисплей 128×32 объявлен как 128×64 или наоборот. Высота задаётся в конструкторе.