OLED-дисплей SSD1306 0.96″ и Arduino: подключение, библиотеки, память

Что это за экран и чем он не LCD

OLED 0.96″ — это матрица 128 на 64 светящиеся точки под управлением контроллера SSD1306. Подсветки нет: каждая точка светится сама, поэтому чёрный на нём по-настоящему чёрный, углы обзора любые, а питания хватает от USB. Бывает двухцветным — верхние 16 строк жёлтые, остальное голубое; это не режим, а так напечатана матрица, и в коде это никак не выбирается.

От LCD 1602 он отличается принципиально. LCD показывает знаки из зашитой таблицы: вы шлёте код буквы, экран рисует её сам. OLED не знает никаких букв — это просто 8 192 точки, и каждую зажигает ваша программа. Отсюда всё: любые шрифты и картинки, в том числе русские буквы без фокусов — но и буфер кадра в памяти платы, который на Arduino Uno занимает половину всей оперативной памяти.

Встречаются и родственники. Экран 0.91″ — это 128×32, те же контроллер и библиотеки, меняется размер в конструкторе: у Adafruit число 64 → 32, у U8g2 имя класса с «128X32», у GyverOLED параметр SSD1306_128x32. Экран 1.3″ выглядит так же, но внутри обычно стоит другой контроллер — SH1106; код для SSD1306 на нём даст сдвинутую картинку с мусором по краям, про это отдельный раздел ниже.

Подключение: четыре провода и один подвох

Подвох в порядке выводов. У одних модулей слева направо идут GND, VCC, SCL, SDA, у других — VCC, GND, SCL, SDA. Они выглядят одинаково, и если воткнуть второй по памяти о первом, питание и земля поменяются местами — а защиты от этого на модуле нет, перепутанные провода могут его сжечь. Читайте подписи на плате до включения, а не положение контактов. Сам чип SSD1306 трёхвольтовый, но на модулях стоит стабилизатор, и от 5 В платы Arduino они питаются штатно; на ESP берите 3V3. И ещё: если у модуля не четыре вывода, а семь (GND, VCC, D0, D1, RES, DC, CS) — это версия с шиной SPI, и всё ниже про четыре провода и адрес к ней не относится; конструктор там другой, display(128, 64, &SPI, DC, RES, CS). Куда идут его семь проводов — в таблице ниже.

В коде меняется только конструктор: Adafruit_SSD1306 display(128, 64, &SPI, 8, 9, 10) — числа здесь это DC, RES и CS. Всё остальное в статье — библиотеки, буфер, шрифты, ошибки — к SPI-версии относится полностью: контроллер тот же.

Линии SDA и SCL у всех плат те же, что и для любого другого устройства I2C: на Uno это A4 и A5, они же продублированы двумя контактами рядом с AREF. Что за плата NodeMCU и почему у неё выводы зовутся D1 и D2 — в статье про ESP8266. Номера взяты из файлов pins_arduino.h ядер 1.8.8 и 3.1.2. Если к той же шине подключён LCD 1602 или датчик — ничего не меняется, у каждого свой адрес.

Адрес 0x3C и почему фирменный пример не работает

Почти все модули 0.96″ сидят на адресе 0x3C. На обратной стороне есть резистор или перемычка, которой адрес меняют на 0x3D — но с завода она стоит на 0x3C. Иногда прямо на плате напечатано «0x78»: это тот же 0x3C, только записанный со сдвигом на бит, как его видит сам контроллер; в код пишите 0x3C. И вот самая частая история первого запуска.

#define SCREEN_ADDRESS 0x3D ///< See datasheet for Address;
                            ///< 0x3D for 128x64, 0x3C for 128x32
...
if(!display.begin(SSD1306_SWITCHCAPVCC, SCREEN_ADDRESS)) {
  Serial.println(F("SSD1306 allocation failed"));
  for(;;);
}

I2C scanner
Found 0x3C

Адрес 0x3D бывает только после перепайки перемычки
или резистора на обратной стороне платы.

Человек открывает пример из библиотеки Adafruit, ssd1306_128x64_i2c, загружает — и видит чёрный экран. В примере стоит #define SCREEN_ADDRESS 0x3D, потому что Adafruit ориентируется на свои фирменные модули. Замените на 0x3C — и появится заставка. Мы это взяли прямо из файла примера версии 2.5.17; в более старых версиях цифра была та же. Та же ловушка прячется и без #define: вызов begin(SSD1306_SWITCHCAPVCC) без второго аргумента для экрана 128×64 подставит 0x3D сам (так написано в коде библиотеки). Всегда указывайте адрес явно.

Второй слой той же ловушки — в исходниках begin(). Эта функция не спрашивает у дисплея, есть ли он на шине: она выделяет память под буфер, шлёт команды настройки и возвращает «успех». false она возвращает в одном случае — если malloc не смог выделить 1 024 байта. Поэтому проверка if (!display.begin(…)) ловит не отсутствие экрана, а нехватку памяти, и надпись «SSD1306 allocation failed» значит именно это.

Чтобы узнать адрес наверняка, нужен сканер I2C — тот же, что для LCD: он опрашивает все адреса и печатает, кто отозвался. Код и разбор — в статье про LCD 1602 по I2C; в Trema IDE сканер лежит в примерах, раздел «Полезное».

Три библиотеки и сколько памяти берёт каждая

Для SSD1306 в нашем каталоге десятки библиотек, но живых варианта три. Мы поставили каждую из каталога libraries.trema.ru и собрали один и тот же скетч «привет» для Arduino Uno — вот что вышло.

Главное, что стоит вынести из этой картинки: буфер кадра — это 1 024 байта, и он есть у всех, просто библиотеки берут его по-разному. U8g2 в полном режиме и GyverOLED объявляют его заранее, и компилятор честно показывает 76 % и 64 % — при 76 % он ещё и напишет «Недостаточно памяти, программа может работать нестабильно»: это предупреждение, прошивка загрузится, но это сигнал перейти на постраничный режим. Adafruit берёт его командой malloc в момент запуска, и компилятор о нём не знает: в отчёте 27 %, а по факту те же 78 %. Мы проверили на скетче с массивом из 300 чисел: отчёт сборки говорит «59 %, свободно 829 байт», сборка зелёная, а при запуске begin() попросит 1 024 — и получит отказ. Экран чёрный, в мониторе «allocation failed», и ни одной ошибки при компиляции. Причём мало, чтобы свободных было ровно тысяча: по документации avr-libc malloc держит запас в 128 байт до стека и два байта тратит на заголовок, да и самому стеку нужно место — на практике буфер влезает, когда отчёт показывает не меньше ≈1 200 свободных, то есть статика не больше ≈40 %.

Для Arduino Uno и Nano отсюда простой совет: если экран — не единственное, что делает плата, берите U8g2 в постраничном режиме (676 байт) или GyverOLED без буфера (303 байта). На Mega 2560 с её 8 КБ и на ESP8266 с 80 КБ всё это не имеет значения: на Mega Adafruit вместе с буфером берёт 1 593 байта из 8 192 (19 %; компилятор покажет 569, то есть 6 %), на ESP8266 — около 1,7 КБ из 80 (2 %; в отчёте будет 35 %, но это само ядро ESP8266 занимает 28 КБ на любом скетче) — мы собрали и для них. Подробнее про то, какие бывают памяти и куда деваются байты, — в статье «Память Arduino».

Про эти две библиотеки отдельно, потому что в списке выше они выглядят выгоднее всех для Arduino Uno. iarduino_OLED_txt вообще не держит буфер кадра: текст уходит прямо в экран, и в оперативной памяти остаётся 1 723 байта из 2 048 — больше, чем у любой другой библиотеки с русским текстом. Платой служит флеш: русские шрифты лежат в нём, и «привет» весит 7 664 байта (со вторым шрифтом 12×16 — 11 980). iarduino_OLED — та же библиотека с буфером и графикой: 8 118 байт флеша и 1 350 ОЗУ. Обе есть в нашем каталоге, ставятся оттуда же.

Первый скетч: Adafruit

Начнём с самой распространённой библиотеки — под неё написано больше всего чужих примеров, и её стоит понимать, даже если потом перейдёте на другую.

// Первый скетч на библиотеке Adafruit: текст двух размеров.
#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>

// 128×64 точки, шина Wire, вывода сброса нет (-1).
Adafruit_SSD1306 display(128, 64, &Wire, -1);

void setup() {
  Serial.begin(9600);
  // Адрес 0x3C — у почти всех модулей 0.96". В фирменном примере стоит
  // 0x3D, и с ним экран останется чёрным.
  if (!display.begin(SSD1306_SWITCHCAPVCC, 0x3C)) {
    Serial.println("SSD1306 allocation failed");   // не хватило ОЗУ под буфер
    for (;;);
  }
  display.clearDisplay();
  display.setTextSize(1);                 // 6×8 точек на знак: 21 знак в строке
  display.setTextColor(SSD1306_WHITE);
  display.setCursor(0, 0);
  display.println("Hello, Arduino!");
  display.setTextSize(2);                 // 12×16: 10 знаков в строке
  display.println("OLED");
  display.display();                      // без этой строки на экране ничего
}

void loop() {
}

14 078 байт флеша и 569 байт ОЗУ по отчёту (плюс тысяча при запуске). Три вещи, которые ловят всех. Первая — адрес 0x3C в begin(), уже обсудили. Вторая — display() в конце: всё рисование идёт в буфер, и пока не вызвать эту команду, на стекле ничего не меняется. Третья — встроенный шрифт 5×7 точек с шагом 6: при setTextSize(1) в строку помещается 21 знак, при размере 2 — 10, и кириллицы в нём нет: таблица на 256 знаков, и каждый байт русской буквы попадёт на чужой символ — рамки, чёрточки, греческие буквы. Вместо «Привет» выйдет двенадцать знаков мусора.

Версии 128×32 — тот же скетч с display(128, 32, …). Если перепутать высоту, картинка пойдёт «через строку» — сжатая или растянутая, — это не брак экрана.

U8g2: постраничный режим для Uno

U8g2 — самая большая библиотека для монохромных экранов: сотни шрифтов и почти любой контроллер. Платой за это служит архив в 14 МБ — ставится дольше остальных. Конструкторов в ней почти пять тысяч (для одного SSD1306 128×64 — девяносто), поэтому имя читается как формула: U8G2_SSD1306_128X64_NONAME_1_HW_I2C — контроллер, размер, тип платы, режим буфера, способ подключения. Режимов три: _F_ — полный кадр в памяти, _1_ — одна полоска в 128 байт, _2_ — две. Для Uno берите _1_.

// U8g2 в постраничном режиме: 676 байт ОЗУ вместо 1 572.
#include <Wire.h>
#include <U8g2lib.h>

// _1_ в имени — постраничный буфер. Замените на _F_ — будет полный.
U8G2_SSD1306_128X64_NONAME_1_HW_I2C u8g2(U8G2_R0, U8X8_PIN_NONE);

void setup() {
  u8g2.begin();
}

void loop() {
  u8g2.firstPage();
  do {                                   // этот блок выполнится 8 раз
    u8g2.setFont(u8g2_font_ncenB14_tr);
    u8g2.drawStr(0, 24, "Hello, Arduino!");
  } while (u8g2.nextPage());
  delay(1000);
}

Цикл do … while (nextPage()) — это и есть постраничный режим: библиотека рисует кадр восемь раз, каждый раз только полоску в 8 строк, и шлёт её в дисплей. Код внутри цикла должен рисовать одно и то же все восемь проходов — поэтому считывать датчик надо до firstPage(), а не внутри. Мы измерили цену: 10 756 байт флеша, 676 байт ОЗУ против 1 572 у _F_ при том же флеше. Кадр обновляется медленнее, но для показаний датчиков и меню это незаметно.

Вот показания аналогового входа крупными цифрами с полоской внизу — скетч, который после замены analogRead на чтение любого датчика становится готовым прибором. Собран: 10 688 байт флеша, 670 байт ОЗУ — крупный цифровой шрифт стоит всего полкилобайта, потому что в нём только цифры и знаки, и вместе с мелким 6×12 это меньше одного шрифта ncenB14 из первого скетча.

// Крупное число с аналогового входа — как будто показания датчика.
#include <Wire.h>
#include <U8g2lib.h>

U8G2_SSD1306_128X64_NONAME_1_HW_I2C u8g2(U8G2_R0, U8X8_PIN_NONE);

void setup() {
  u8g2.begin();
}

void loop() {
  int value = analogRead(A0);
  u8g2.firstPage();
  do {
    u8g2.setFont(u8g2_font_6x12_tr);
    u8g2.drawStr(0, 10, "A0 reading");
    u8g2.setFont(u8g2_font_logisoso32_tn);   // только цифры, 32 точки высотой
    u8g2.setCursor(0, 58);
    u8g2.print(value);
    // Полоска-индикатор вдоль нижнего края:
    u8g2.drawFrame(0, 60, 128, 4);
    u8g2.drawBox(0, 60, map(value, 0, 1023, 0, 128), 4);
  } while (u8g2.nextPage());
  delay(100);
}

Русский текст на OLED

В отличие от LCD 1602, здесь никаких ограничений: буква — это просто точки. Нужен только шрифт, в котором эти буквы нарисованы. В U8g2 таких 22, их имена кончаются на _t_cyrillic, а строки надо печатать через print() после enableUTF8Print():

// Русский текст на OLED: шрифт с кириллицей и печать через print().
#include <Wire.h>
#include <U8g2lib.h>

U8G2_SSD1306_128X64_NONAME_1_HW_I2C u8g2(U8G2_R0, U8X8_PIN_NONE);

void setup() {
  u8g2.begin();
  u8g2.enableUTF8Print();                // понимать русские буквы в строках
}

void loop() {
  u8g2.firstPage();
  do {
    u8g2.setFont(u8g2_font_10x20_t_cyrillic);   // _t_cyrillic — с кириллицей
    u8g2.setCursor(0, 24);
    u8g2.print("Привет, мир!");
  } while (u8g2.nextPage());
  delay(1000);
}

Собрано: 15 764 байта флеша — шрифт 10×20 с кириллицей весит почти 7 КБ против 1,4 КБ у того же шрифта без неё: в нём 387 знаков вместо 95, потому что это не только русский алфавит, а весь блок кириллицы с украинскими, сербскими и казахскими буквами. ОЗУ почти не изменилось — 682 байта против 676: шрифты лежат во флеше. Если нужно компактнее — u8g2_font_6x12_t_cyrillic или u8g2_font_5x8_t_cyrillic. А одну строку можно вывести и без enableUTF8Print() — командой drawUTF8(x, y, "Привет").

Второй путь — GyverOLED: русские буквы, включая строчную ё, у неё в единственном встроенном шрифте, и никаких настроек (одна мелочь из кода: заглавная Ё печатается как Е):

// GyverOLED: русские буквы сразу, 5,5 КБ флеша.
#include <GyverOLED.h>

// OLED_BUFFER — кадр в памяти платы (скетч берёт 1 327 байт ОЗУ, из них 1 024 — буфер),
// OLED_NO_BUFFER — рисовать прямо в дисплей (303 байта).
GyverOLED<SSD1306_128x64, OLED_BUFFER> oled;

void setup() {
  oled.init();
  oled.clear();
  oled.setScale(2);            // буквы вдвое крупнее
  oled.setCursor(0, 0);
  oled.print("Привет!");
  oled.setScale(1);
  oled.setCursor(0, 4);        // строка 4 — это 4-я «страница» по 8 точек
  oled.print("GyverOLED, 128x64");
  oled.update();               // отправить буфер в дисплей
}

void loop() {
}

5 530 байт флеша — в два с половиной раза меньше, чем у Adafruit, и 1 327 байт ОЗУ с буфером или 303 без (второй параметр шаблона OLED_NO_BUFFER). Масштаб setScale(2) делает буквы 12×16, и это простейший способ получить крупные цифры термометра. У библиотеки русский автор и русская документация — для кружка это аргумент.

И третий путь — русские библиотеки iarduino_OLED_txt и iarduino_OLED. Текст в них печатается функцией print(строка, столбец, строка_экрана), а шрифты с кириллицей уже внутри: SmallFontRus 6×8 и MediumFontRus 12×16. Скетч ниже мы собрали: 7 664 байта флеша и всего 325 байт ОЗУ.

// Русский текст библиотекой iarduino_OLED_txt: буфера кадра нет,
// в оперативной памяти остаётся 1 723 байта из 2 048.
#include <Wire.h>
#include <iarduino_OLED_txt.h>

// Адрес 0x3C или 0x3D — у модуля Trema он выбирается переключателем.
iarduino_OLED_txt oled(0x3C);

void setup() {
  oled.begin(&Wire);
  oled.setFont(SmallFontRus);            // шрифт 6x8 с кириллицей
  oled.print("Привет, мир!", OLED_C, 2); // OLED_C — по центру, строка 2
}

void loop() {
}

Если русский текст выходит «кракозябрами», у этих библиотек есть переключатель кодировки: setCoding(TXT_UTF8) — как сохраняет современная Arduino IDE и Trema IDE, TXT_CP866 и TXT_WIN1251 — для старых файлов. По умолчанию UTF-8, так что обычно трогать не нужно.

Яркость и выгорание

Подстроечника у OLED нет, но яркость регулируется из кода: у Adafruit — display.dim(true) или команда SSD1306_SETCONTRAST, у U8g2 и GyverOLED — setContrast(0…255). И одно свойство, о котором редко пишут: точки OLED изнашиваются от работы, и надпись, которая месяцами горит на одном месте, оставляет след — это заметно на приборах, включённых круглые сутки. Для таких гасите экран, когда на него не смотрят, или сдвигайте картинку на пару точек время от времени. Для кружкового проекта это не важно.

SSD1306 или SH1106: почему картинка съехала

Экраны 1.3″ и часть 0.96″ собраны на контроллере SH1106. Он почти совместим с SSD1306, но у него матрица 132 столбца, а не 128, и нет команды «горизонтальная адресация», которой пользуются библиотеки для SSD1306. В результате код для SSD1306 на SH1106 рисует, но со сдвигом на два столбца и полосой мусора у края — или не рисует вовсе.

• U8g2: замените в конструкторе SSD1306 на SH1106 — всё остальное то же самое.
• GyverOLED: первый параметр шаблона SSH1106_128x64 (именно с двумя S — так в библиотеке), и только вместе с OLED_BUFFER: без буфера SH1106 она не поддерживает.
• Adafruit: нужна отдельная библиотека Adafruit SH110X с классом Adafruit_SH1106G; она тоже в каталоге — и, в отличие от SSD1306, её begin() честно возвращает false, если экрана нет на шине.

Определить контроллер по внешнему виду нельзя; продавец обычно пишет его в названии. Если не написано, а экран 1.3″ — скорее всего SH1106; 0.96″ — скорее всего SSD1306. Проверка простая: загрузить скетч для одного и посмотреть, ровная ли картинка.

Ошибки и странности, которые мы воспроизвели или разобрали

OLED в Trema IDE

Мы делаем русскую среду для школ и кружков; OLED — одна из деталей, с которыми в ней знакомятся с окном «Нужна библиотека».

• Библиотека ставится из окна ошибки. Напишите #include <Adafruit_SSD1306.h> или <U8g2lib.h>, нажмите «Проверить» — и программа предложит нужную библиотеку из нашего каталога, а зависимости Adafruit доставит сама. Каталог — российский сервер libraries.trema.ru; U8g2 со всеми её 14 МБ качается оттуда же.
• Сканер адресов — в примерах, раздел «Полезное», скетч I2C_Scanner с русскими комментариями.
• Ошибки объясняются по-русски. «Не хватает библиотеки: Adafruit_SSD1306.h» — карточка с кнопкой. Честно о том, чего нет: «SSD1306 allocation failed» — это сообщение из монитора порта во время работы, а не из компилятора, и карточки на него нет; подсказать, что 1 024 байта буфера не видны в отчёте сборки, программа пока тоже не умеет. Мы это знаем и думаем, как показать.

Живой дисплей к этой статье мы не подключали: все числа — из сборок, все ловушки — из исходников библиотек. Если у вас получается иначе — напишите, проверим.