ELECTRONICS

Библиотека Adafruit GFX: графика и текст на дисплеях

Обновлено

В менеджере библиотек
Adafruit GFX Library by Adafruit
Версия
1.13.0 · всего 100 версий, первая — 1.0.0
Платы
любые — автор не ограничивал
Зависимости
Adafruit BusIO — менеджер предложит поставить вместе
СкачатьAdafruit_GFX_Library-1.13.0.zip · 349 КБ

Архивы — копии из официального индекса Arduino, контрольная сумма совпадает. Сверено 02.11.2026.

Графика для дисплеев Adafruit и совместимых: текст, линии, фигуры, картинки, шрифты. Работает поверх драйвера экрана — SSD1306, SH1106, ST7735, ILI9341.

GFX сама с экраном не разговаривает: это набор команд рисования, общий для всех драйверов. Класс драйвера — Adafruit_SSD1306, Adafruit_ST7735, Adafruit_ILI9341 — наследует GFX, поэтому drawLine() или print() пишутся одинаково для любого экрана. Меняется только объект и строка его создания.

Координаты — в точках от левого верхнего угла: x вправо, y вниз. Цвет — 16-битное число: у монохромного OLED это SSD1306_WHITE и SSD1306_BLACK, у цветных экранов — формат RGB565, например 0xF800 — красный.

Отдельно GFX обычно не ставят: менеджер предлагает её как зависимость драйвера. Но ищут её почти вдвое чаще, чем драйвер SSD1306, — потому что именно в ней живут шрифты и вопрос «как вывести русский текст».

Как скачать и установить

  1. Через менеджер — самый простой путь. В Arduino IDE: Инструменты → Управлять библиотеками (Ctrl+Shift+I). Введите Adafruit GFX Library и найдите в списке строку «Adafruit GFX Library by Adafruit» — одноимённых библиотек бывает несколько, отличаются они автором. Нажмите «Установить», и на вопрос про зависимости — «Установить всё».
  2. Конкретная версия — если в чужом проекте указана не последняя. В той же карточке менеджера рядом с кнопкой есть выпадающий список версий: выберите нужную и нажмите «Установить».
  3. Из архива — если нет интернета на рабочем компьютере или менеджер не открывается. Скачайте ZIP выше, затем Скетч → Подключить библиотеку → Добавить .ZIP библиотеку и укажите файл. Распаковывать не нужно.

Файл Adafruit_GFX.h отдельно не скачивают: он внутри библиотеки и появляется после установки. Если среда пишет Adafruit_GFX.h: No such file or directory — библиотека не установлена или установлена не та. Как устроен менеджер и куда складываются файлы — в общей статье про библиотеки.

Строка подключения:

#include <Adafruit_SSD1306.h>   // драйвер вашего дисплея
#include <Adafruit_GFX.h>

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

Adafruit_SSD1306 display(128, 64, &Wire, -1);   // объект драйвера — он и есть GFX
// все методы ниже вызываются у него: display.drawLine(...)

С каким дисплеем работает

GFX сама с экраном не разговаривает: это общий набор команд рисования, а обмен с дисплеем ведёт драйвер. Ставите драйвер своего экрана — GFX менеджер подтянет как зависимость, — создаёте объект драйвера, и все методы ниже вызываются у него.

Схема подключения OLED-дисплея SSD1306 0,96″ к Arduino UNO по I2C: SDA к A4, SCL к A5, VCC к 5 В, GND к GND
Схема с пояснением к каждому проводу — на странице модуля «OLED SSD1306».
OLED 0,96″ и 0,91″ на SSD1306
Драйвер из менеджера: Adafruit SSD1306

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

OLED 1,3″ на SH1106
Драйвер из менеджера: Adafruit SH110X

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

TFT 1,44–2″ на ST7735 и ST7789
Драйвер из менеджера: Adafruit ST7735 and ST7789 Library

Adafruit_ST7735 tft(CS, DC, RST);

TFT 2,4–3,2″ на ILI9341
Драйвер из менеджера: Adafruit ILI9341

Adafruit_ILI9341 tft(CS, DC);

Матрицы 8×8 на MAX7219
Драйвер из менеджера: Max72xxPanel — только с GitHub

Max72xxPanel matrix(CS, 4, 1); — если GFX не нужна, проще LedControl или MD_Parola

Экран держит ещё килобайт — и среда его не показывает

Драйвер OLED 128×64 выделяет буфер экрана — 1024 байта — при begin(), уже во время работы, поэтому в отчёте среды его нет. На UNO к цифре отчёта прибавьте килобайт. Не хватило памяти — begin() вернёт false, отсюда проверка if (!display.begin(…)) во всех примерах.

1,3″ OLED выглядит так же, а работает иначе

Дисплеи 1,3″ почти всегда на SH1106, а не на SSD1306: с драйвером SSD1306 по краю экрана идёт мусор, картинка сдвинута на два столбца. Нужен драйвер Adafruit SH110X — остальной код на GFX не меняется.

Русские буквы

Встроенный шрифт GFX — таблица CP437: латиница и псевдографика, кириллицы нет. Строки в скетче записаны в UTF-8, где русская буква занимает два байта, поэтому print("Привет") выводит пары случайных символов. Способов три.

СпособКакЦена
U8g2_for_Adafruit_GFXбиблиотека из менеджера от автора U8g2: рисует его шрифты с кириллицей поверх любого дисплея на GFX; её print() понимает UTF-8 сам, строки пишутся как естьшрифт с кириллицей — несколько килобайт флеша; основной путь
Свой шрифт GFXfontконвертер fontconvert из папки библиотеки делает шрифт из TTF, включая кириллицу; строку перекодируют из UTF-8 в однобайтную функцией-перекодировщикомнадо собрать инструмент и написать перекодировку
Замена glcdfont.cв библиотеке подменяют файл встроенного шрифта на вариант с русскими буквами — так в большинстве старых уроковслетает при каждом обновлении библиотеки

Методы

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

Экран и координаты

int16_t width()

Ширина экрана в точках — с учётом поворота. Пишите координаты через неё, и скетч заработает на экране другого размера.

Возвращает: ширина в точках.

display.drawFastHLine(0, 10, display.width(), SSD1306_WHITE);

int16_t height()

Высота экрана с учётом поворота.

Возвращает: высота в точках.

int16_t bottom = display.height() - 1;

void setRotation(uint8_t r)

Повернуть систему координат. Ноль — (0, 0) в левом верхнем углу, x вправо, y вниз; остальные — поворот по 90° по часовой.

r
0–3.
display.setRotation(2);   // вверх ногами

uint8_t getRotation()

Прочитать текущий поворот.

Возвращает: 0–3.

if (display.getRotation() % 2) Serial.println("портрет");

void fillScreen(uint16_t color)

Залить весь экран. У OLED то же самое делает clearDisplay() драйвера.

color
цвет: SSD1306_WHITE и SSD1306_BLACK у монохромного OLED, RGB565 у цветных — например, 0xF800 красный.
display.fillScreen(SSD1306_BLACK);

void invertDisplay(bool i)

Инвертировать экран на уровне контроллера дисплея: белое станет чёрным, без перерисовки.

display.invertDisplay(true);

Точки и линии

void drawPixel(int16_t x, int16_t y, uint16_t color)

Одна точка. Всё остальное библиотека строит из них.

display.drawPixel(64, 32, SSD1306_WHITE);

void drawLine(int16_t x0, int16_t y0, int16_t x1, int16_t y1, uint16_t color)

Линия между двумя точками под любым углом.

display.drawLine(0, 0, 127, 63, SSD1306_WHITE);

void drawFastHLine(int16_t x, int16_t y, int16_t w, uint16_t color)

Горизонтальная линия от точки вправо — быстрее drawLine(). drawFastVLine(x, y, h, color) — вертикальная вниз.

w
длина в точках.
display.drawFastHLine(0, 11, 128, SSD1306_WHITE);

Фигуры

void drawRect(int16_t x, int16_t y, int16_t w, int16_t h, uint16_t color)

Прямоугольник контуром. fillRect() с теми же параметрами — залитый: им же стирают кусок экрана перед новым выводом.

x, y
левый верхний угол.
w, h
ширина и высота.
display.fillRect(64, 20, 64, 16, SSD1306_BLACK);

void drawRoundRect(int16_t x0, int16_t y0, int16_t w, int16_t h, int16_t radius, uint16_t color)

Прямоугольник со скруглёнными углами — кнопки, рамки, корпус батареи. fillRoundRect() — залитый.

radius
радиус скругления; не больше половины меньшей стороны.
display.drawRoundRect(0, 0, 60, 20, 4, SSD1306_WHITE);

void drawCircle(int16_t x0, int16_t y0, int16_t r, uint16_t color)

Окружность по центру и радиусу. fillCircle() — круг.

display.fillCircle(64, 32, 10, SSD1306_WHITE);

void drawEllipse(int16_t x0, int16_t y0, int16_t rw, int16_t rh, uint16_t color)

Эллипс по центру и двум радиусам. fillEllipse() — залитый. Появились в 1.12 — в старых примерах их нет.

rw, rh
радиусы по горизонтали и вертикали.
display.drawEllipse(64, 32, 30, 15, SSD1306_WHITE);

void drawTriangle(int16_t x0, int16_t y0, int16_t x1, int16_t y1, int16_t x2, int16_t y2, uint16_t color)

Треугольник по трём вершинам — стрелки, указатели. fillTriangle() — залитый.

display.fillTriangle(60, 40, 64, 30, 68, 40, SSD1306_WHITE);

void drawRotatedRect(int16_t cenX, int16_t cenY, int16_t w, int16_t h, int16_t angleDeg, uint16_t color)

Прямоугольник, повёрнутый на угол вокруг своего центра — стрелка прибора, наклонённая плашка. fillRotatedRect() — залитый. Тоже новинка 1.12.

cenX, cenY
центр.
angleDeg
угол в градусах.
display.fillRotatedRect(64, 32, 40, 4, 30, SSD1306_WHITE);

Картинки

void drawBitmap(int16_t x, int16_t y, const uint8_t bitmap[], int16_t w, int16_t h, uint16_t color)

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

bitmap
имя массива с PROGMEM.
w, h
размер картинки в точках.
display.drawBitmap(8, 24, thermo, 16, 16, SSD1306_WHITE);

void drawBitmap(int16_t x, int16_t y, const uint8_t bitmap[], int16_t w, int16_t h, uint16_t color, uint16_t bg)

То же, но нули рисуются цветом фона — картинка непрозрачная и сразу затирает старое под собой.

display.drawBitmap(0, 24, buf, 64, 16, SSD1306_WHITE, SSD1306_BLACK);

void drawXBitmap(int16_t x, int16_t y, const uint8_t bitmap[], int16_t w, int16_t h, uint16_t color)

Картинка в формате XBM — его выдаёт GIMP при экспорте. Биты в байте идут в обратном порядке, поэтому массив из GIMP в drawBitmap() выходит зеркальным.

display.drawXBitmap(0, 0, logo_bits, 32, 32, SSD1306_WHITE);

void drawRGBBitmap(int16_t x, int16_t y, const uint16_t bitmap[], int16_t w, int16_t h)

Цветная картинка для TFT: по 16-битному числу RGB565 на точку. На UNO влезает только маленькая — 32×32 уже 2 КБ флеша.

tft.drawRGBBitmap(0, 0, icon565, 32, 32);

Текст

void setCursor(int16_t x, int16_t y)

Куда печатать. Для встроенного шрифта — левый верхний угол первой буквы, для шрифтов из Fonts/ — базовая линия, по которой буквы «стоят».

display.setCursor(0, 0);

int16_t getCursorX()

Где сейчас курсор по горизонтали — после print() он стоит за последним символом. getCursorY() — по вертикали.

Возвращает: координата в точках.

int16_t endX = display.getCursorX();

void setTextSize(uint8_t s)

Увеличить шрифт в целое число раз: 1 — встроенные 6×8 точек, 2 — 12×16, 3 — 18×24. Масштаб пикселями, поэтому крупные буквы «ступенчатые».

display.setTextSize(2);

void setTextSize(uint8_t sx, uint8_t sy)

Разный масштаб по ширине и высоте — узкий высокий шрифт для цифр.

display.setTextSize(1, 2);

void setTextColor(uint16_t c)

Цвет текста. Фон не рисуется: новые буквы ложатся поверх старых.

display.setTextColor(SSD1306_WHITE);

void setTextColor(uint16_t c, uint16_t bg)

Цвет текста и фона — каждая буква сама затирает место под собой. Работает только со встроенным шрифтом.

display.setTextColor(SSD1306_WHITE, SSD1306_BLACK);

void setTextWrap(bool w)

Переносить ли строку, дошедшую до края. false — хвост уходит за экран; нужно для бегущей строки.

display.setTextWrap(false);

print(...)

Вывести текст или число, как в Serial: строки, целые, дробные с точностью, F("…"). println() — с переходом на новую строку.

Возвращает: сколько символов выведено.

display.print(t, 1);

void drawChar(int16_t x, int16_t y, unsigned char c, uint16_t color, uint16_t bg, uint8_t size)

Нарисовать один символ в любом месте, не трогая курсор.

c
код символа.
size
масштаб, как у setTextSize().
display.drawChar(120, 0, 'A', SSD1306_WHITE, SSD1306_BLACK, 1);

void getTextBounds(const char* string, int16_t x, int16_t y, int16_t* x1, int16_t* y1, uint16_t* w, uint16_t* h)

Узнать размер надписи до вывода — чтобы поставить её по центру или прижать к правому краю.

x, y
где был бы курсор.
x1, y1, w, h
сюда запишутся угол и размер.
display.getTextBounds("Niro", 0, 20, &x1, &y1, &w, &h);

void setFont(const GFXfont* f = NULL)

Шрифт из папки Fonts/ библиотеки: FreeSans, FreeSerif, FreeMono, от 9 до 24 пунктов. Без аргумента — вернуть встроенный. Шрифт занимает флеш: FreeSans 9 пт — около 2 КБ, 24 пт — около 8 КБ.

f
адрес шрифта: &FreeSans9pt7b после #include <Fonts/FreeSans9pt7b.h>.
display.setFont(&FreeSans9pt7b);

void cp437(bool x = true)

Включить правильную таблицу встроенного шрифта. Без неё символы после 176-го сдвинуты на один — и знак градуса выводится не тот.

display.cp437(true);
display.write(248);   // °

Холсты

GFXcanvas1(uint16_t w, uint16_t h)

Невидимый монохромный экран в памяти: рисуете в нём любыми методами GFX, а потом выводите целиком одной картинкой. На TFT так убирают мерцание: экран не видит промежуточных шагов. Бит на точку, 64×16 — 128 байт.

w, h
размер холста.
GFXcanvas1 counter(64, 16);

GFXcanvas16(uint16_t w, uint16_t h)

Цветной холст для TFT, два байта на точку. На UNO годится только для маленьких участков: 80×20 — уже 3,2 КБ, больше всей памяти.

GFXcanvas16 label(60, 12);   // 1440 байт

uint8_t* getBuffer()

Буфер холста — его передают в drawBitmap() или drawRGBBitmap(), чтобы вывести холст на экран.

Возвращает: указатель на точки холста.

display.drawBitmap(0, 24, counter.getBuffer(), 64, 16, SSD1306_WHITE, SSD1306_BLACK);

Примеры

Надпись по центру и фигуры

#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>
#include <Fonts/FreeSans9pt7b.h>

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

// строка по центру экрана по горизонтали
void printCentered(const char *text, int16_t y) {
  int16_t x1, y1;
  uint16_t w, h;
  display.getTextBounds(text, 0, y, &x1, &y1, &w, &h);
  display.setCursor((display.width() - w) / 2 - x1, y);
  display.print(text);
}

void setup() {
  display.begin(SSD1306_SWITCHCAPVCC, 0x3C);
  display.clearDisplay();
  display.setTextColor(SSD1306_WHITE);

  display.setFont(&FreeSans9pt7b);   // курсор — на базовой линии, поэтому y = 20, а не 0
  printCentered("Niro", 20);
  display.setFont();                  // обратно встроенный 6×8

  display.drawRoundRect(0, 28, 128, 36, 6, SSD1306_WHITE);
  display.fillCircle(24, 46, 10, SSD1306_WHITE);
  display.fillTriangle(52, 56, 64, 36, 76, 56, SSD1306_WHITE);
  display.drawLine(90, 36, 116, 56, SSD1306_WHITE);
  display.display();
}

void loop() {}
Запустить в симулятореСхема с этим скетчем — запустить в браузере

Пример на OLED SSD1306, но всё, кроме строки создания объекта и begin(), без изменений работает на любом дисплее с драйвером на GFX.

Значок из картинки

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

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

// значок термометра 16×16: бит на точку, строка — два байта.
// Такие массивы делают из картинки конвертером image2cpp
const uint8_t PROGMEM thermo[] = {
  0x03, 0xC0, 0x06, 0x60, 0x04, 0x20, 0x04, 0x20,
  0x04, 0x20, 0x05, 0xA0, 0x05, 0xA0, 0x05, 0xA0,
  0x05, 0xA0, 0x0D, 0xB0, 0x1B, 0xD8, 0x17, 0xE8,
  0x17, 0xE8, 0x1B, 0xD8, 0x0C, 0x30, 0x07, 0xE0
};

void setup() {
  if (!display.begin(SSD1306_SWITCHCAPVCC, 0x3C)) for (;;);   // 0x3C — адрес большинства 0,96″
  display.clearDisplay();
  display.drawBitmap(8, 24, thermo, 16, 16, SSD1306_WHITE);
  display.setTextSize(2);
  display.setTextColor(SSD1306_WHITE);
  display.setCursor(32, 25);
  display.print("23.5");
  display.display();
}

void loop() {}
Запустить в симулятореСхема с этим скетчем — запустить в браузере

Слева — термометр 16×16 точек, справа — число. Массив записан во флеш-память (PROGMEM), поэтому не тратит оперативную. Свою картинку в такой массив превращает онлайн-конвертер image2cpp: чёрно-белое изображение нужного размера, формат «Arduino code», режим «Horizontal».

Индикатор батареи

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

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

// значок батареи с заполнением по напряжению на A0
void drawBattery(int16_t x, int16_t y, uint8_t percent) {
  display.drawRoundRect(x, y, 40, 18, 3, SSD1306_WHITE);   // корпус
  display.fillRect(x + 40, y + 5, 3, 8, SSD1306_WHITE);    // плюсовой контакт
  int16_t w = 36L * percent / 100;
  display.fillRect(x + 2, y + 2, w, 14, SSD1306_WHITE);    // заряд
}

void setup() {
  if (!display.begin(SSD1306_SWITCHCAPVCC, 0x3C)) for (;;);
  display.setTextColor(SSD1306_WHITE);
}

void loop() {
  // Li-ion через делитель пополам: 3,0 В — пусто, 4,2 В — полно
  float v = analogRead(A0) * 5.0 / 1023 * 2;
  int percent = constrain((v - 3.0) / 1.2 * 100, 0, 100);
  display.clearDisplay();
  drawBattery(10, 20, percent);
  display.setTextSize(2);
  display.setCursor(64, 21);
  display.print(percent);
  display.print('%');
  display.display();
  delay(500);
}
Запустить в симулятореСхема с этим скетчем — запустить в браузере

Значок батареи заполняется по напряжению на A0, рядом — проценты. Аккумулятор подключают через делитель пополам: 4,2 В напрямую на аналоговый вход UNO подавать можно, но у ESP и 3,3-вольтовых плат — нельзя.

График с прокруткой

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

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

uint8_t history[128];   // по точке на столбец экрана

void setup() {
  if (!display.begin(SSD1306_SWITCHCAPVCC, 0x3C)) for (;;);
}

void loop() {
  // сдвигаем историю влево и дописываем новое значение справа
  memmove(history, history + 1, sizeof(history) - 1);
  history[127] = map(analogRead(A0), 0, 1023, 63, 12);   // 12 строк сверху — под подпись

  display.clearDisplay();
  display.setTextSize(1);
  display.setTextColor(SSD1306_WHITE);
  display.setCursor(0, 0);
  display.print("A0: ");
  display.print(analogRead(A0));
  display.drawFastHLine(0, 11, 128, SSD1306_WHITE);
  for (int x = 1; x < 128; x++)
    display.drawLine(x - 1, history[x - 1], x, history[x], SSD1306_WHITE);
  display.display();
  delay(30);
}
Запустить в симулятореСхема с этим скетчем — запустить в браузере

Показания A0 рисуются линией, которая ползёт справа налево, сверху — текущее значение. История хранится в массиве на 128 точек — по одной на столбец экрана.

Холст: вывод куска экрана целиком

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

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

// холст — невидимый экран в памяти: рисуем в нём, потом выводим целиком.
// На TFT это убирает мерцание; на OLED — удобно собирать кусок экрана отдельно
GFXcanvas1 counter(64, 16);   // 64 × 16 точек = 128 байт

void setup() {
  if (!display.begin(SSD1306_SWITCHCAPVCC, 0x3C)) for (;;);
  display.clearDisplay();
  display.setTextColor(SSD1306_WHITE);
  display.setCursor(0, 0);
  display.print("Uptime, s:");
  display.display();
}

void loop() {
  counter.fillScreen(0);
  counter.setTextSize(2);
  counter.setCursor(0, 0);
  counter.print(millis() / 1000);
  // холст выводится как картинка: белые точки и чёрный фон разом
  display.drawBitmap(0, 24, counter.getBuffer(), 64, 16, SSD1306_WHITE, SSD1306_BLACK);
  display.display();
  delay(100);
}
Запустить в симулятореСхема с этим скетчем — запустить в браузере

Счётчик секунд рисуется в холсте 64×16, а на экран попадает одной картинкой вместе с чёрным фоном — старые цифры затираются сами. На цветном TFT тот же приём убирает мерцание, когда число обновляется часто.

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

Вместо русских букв — кракозябры

Во встроенном шрифте нет кириллицы, а строки в UTF-8. Способы — в разделе «Русские буквы».

Экран пустой, а скетч работает

Три причины по частоте: не тот адрес (у большинства OLED 0x3C, у части 0x3D — проверьте сканером); begin() вернул false — не хватило памяти под буфер; забыли display.display() — у OLED всё рисуется в буфер и выводится только этим вызовом.

Текст со шрифтом из Fonts/ уехал вверх и обрезан

У этих шрифтов курсор — базовая линия, а не верхний угол: setCursor(0, 0) рисует строку выше экрана. Ставьте y не меньше высоты шрифта — для 9pt это около 13.

Цифры наслаиваются друг на друга

setTextColor(c) рисует только сами буквы. У встроенного шрифта поможет setTextColor(цвет, фон); у шрифтов из Fonts/ фона нет вовсе — затирайте место fillRect() или выводите через холст.

Вместо значка градуса другой символ

Без cp437(true) символы после 176-го сдвинуты на один. Включите её в setup() и выводите градус как write(248).

Картинка из GIMP вышла зеркальной

GIMP сохраняет XBM, где биты в байте идут в обратном порядке. Выводите её drawXBitmap(), а не drawBitmap().

Где используется на сайте

Что дальше