Пост

Подключение и тестирование OLED-дисплея 2.23 дюйма на Raspberry Pi Zero

OLED-дисплей HAT диагональю 2,23 дюйма с разрешением 128×32 пикселя построен на контроллере SSD1305 и подключается к Raspberry Pi по шине SPI. Модуль совместим с платами серии Raspberry Pi и Jetson Nano, имеет стандартный 40-контактный GPIO-разъём, питание 3,3 В или 5 В и угол обзора более 160 градусов. В статье — настройка Raspberry Pi OS Lite, установка библиотек и запуск компактного тестового скрипта, который выводит на экран IP-адрес, температуру процессора и загрузку CPU в реальном времени.

Подключение и тестирование OLED-дисплея 2.23 дюйма на Raspberry Pi Zero

Описание

OLED-дисплей HAT диагональю 2,23 дюйма с разрешением 128×32 пикселя построен на контроллере SSD1305 и подключается к Raspberry Pi по шине SPI. Модуль совместим с платами серии Raspberry Pi и Jetson Nano, имеет стандартный 40-контактный GPIO-разъём, питание 3,3 В или 5 В и угол обзора более 160 градусов. В статье — настройка Raspberry Pi OS Lite, установка библиотек и запуск компактного тестового скрипта, который выводит на экран IP-адрес, температуру процессора и загрузку CPU в реальном времени.

Внешний вид OLED-модуля на GPIO-разъёме

Модуль со стороны деталей

Дисплей занимает четыре сигнальные линии: MOSI (данные SPI), SCLK (тактовая частота), CE0 (выбор чипа), а также два управляющих пина — DC (BCM 24, выбор данных или команды) и RST (BCM 25, сброс). Питание подаётся от пина 3V3. Модуль крепится прямо на GPIO, поэтому дополнительных проводов не требуется.

Рекомендации

Для теста достаточно Raspberry Pi OS Lite — графический интерфейс не нужен, все операции выполняются в терминале. Перед первым запуском убедитесь, что модуль плотно посажен на GPIO-разъём и не касается металлических частей корпуса. Если планируете использовать дисплей как постоянный индикатор статуса, закрепите плату стойками из комплекта, чтобы избежать перекосов и случайного снятия под нагрузкой.

Подготовка системы

Включите шину SPI — по умолчанию модуль работает именно через неё. Запустите утилиту конфигурации:

1
sudo raspi-config

В меню выберите 3 Interface Options → I5 SPI → Yes, подтвердите и перезагрузите плату:

1
sudo reboot

Если raspi-config недоступен, SPI можно включить вручную. В актуальных версиях Raspberry Pi OS (Bookworm и новее) файл конфигурации находится по пути /boot/firmware/config.txt — ранее он располагался в /boot/config.txt. Добавьте в конец файла строку dtparam=spi=on и перезагрузитесь.

Проверить, что SPI активен, можно командой:

1
ls /dev/spidev0.*

В выводе должны появиться /dev/spidev0.0 и /dev/spidev0.1.

Установка библиотек

Обновите список пакетов и установите зависимости из репозитория Raspberry Pi OS:

1
2
sudo apt update
sudo apt install -y python3-spidev python3-rpi.gpio python3-pil

python3-spidev обеспечивает доступ к шине SPI, python3-rpi.gpio — к управляющим пинам DC и RST, python3-pil (Pillow) — работу с изображениями, которые отрисовываются в буфере и затем передаются на дисплей.

Тестовый скрипт

Создайте файл ~/tft_project/oled_info.py и скопируйте в него код ниже. Скрипт инициализирует дисплей SSD1305, читает системные данные и раз в три секунды перерисовывает экран. Стандартный шрифт Pillow на 32-пиксельной высоте не помещается — три строки по 11 пикселей дают 33, поэтому в коде используется собственный компактный шрифт 5×7 с шагом 6 пикселей по горизонтали.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# OLED 128x32 SSD1305 — вывод IP, температуры CPU и загрузки CPU

import time
import spidev
import subprocess
import RPi.GPIO as GPIO
from PIL import Image

PIN_DC, PIN_RST = 24, 25
SPI_SPEED = 8000000

spi = spidev.SpiDev()
spi.open(0, 0)
spi.max_speed_hz = SPI_SPEED
GPIO.setmode(GPIO.BCM)
GPIO.setup(PIN_DC, GPIO.OUT)
GPIO.setup(PIN_RST, GPIO.OUT)

def cmd(c):
    GPIO.output(PIN_DC, GPIO.LOW)
    spi.xfer2([c])

def data(d):
    GPIO.output(PIN_DC, GPIO.HIGH)
    for i in range(0, len(d), 4096):
        spi.xfer2(d[i:i+4096])

def init():
    GPIO.output(PIN_RST, GPIO.HIGH); time.sleep(0.1)
    GPIO.output(PIN_RST, GPIO.LOW);  time.sleep(0.1)
    GPIO.output(PIN_RST, GPIO.HIGH); time.sleep(0.1)
    for c in [0xAE,0xD5,0x80,0xA8,0x1F,0xD3,0x00,0x40,
              0x8D,0x14,0x20,0x00,0xA1,0xC8,0xDA,0x12,
              0x81,0xCF,0xD9,0xF1,0xDB,0x40,0xA4,0xA6,0xAF]:
        cmd(c)

def show(img):
    if img.mode != '1':
        img = img.convert('1')
    cmd(0x21); cmd(4); cmd(131)
    cmd(0x22); cmd(0); cmd(3)
    px = img.load()
    buf = []
    for page in range(4):
        for x in range(128):
            b = 0
            for bit in range(8):
                y = page*8 + bit
                if y < 32 and px[x, y] != 0:
                    b |= (1 << bit)
            buf.append(b)
    data(buf)

# Компактный шрифт 5x7 (цифры, латиница, базовые символы)
FONT = {
    '0': [0x3E,0x51,0x49,0x45,0x3E], '1': [0x00,0x42,0x7F,0x40,0x00],
    '2': [0x42,0x61,0x51,0x49,0x46], '3': [0x21,0x41,0x45,0x4B,0x31],
    '4': [0x18,0x14,0x12,0x7F,0x10], '5': [0x27,0x45,0x45,0x45,0x39],
    '6': [0x3C,0x4A,0x49,0x49,0x30], '7': [0x01,0x71,0x09,0x05,0x03],
    '8': [0x36,0x49,0x49,0x49,0x36], '9': [0x06,0x49,0x49,0x29,0x1E],
    'A': [0x7E,0x11,0x11,0x11,0x7E], 'B': [0x7F,0x49,0x49,0x49,0x36],
    'C': [0x3E,0x41,0x41,0x41,0x22], 'D': [0x7F,0x41,0x41,0x22,0x1C],
    'E': [0x7F,0x49,0x49,0x49,0x41], 'F': [0x7F,0x09,0x09,0x09,0x01],
    'G': [0x3E,0x41,0x49,0x49,0x7A], 'H': [0x7F,0x08,0x08,0x08,0x7F],
    'I': [0x00,0x41,0x7F,0x41,0x00], 'J': [0x20,0x40,0x41,0x3F,0x01],
    'K': [0x7F,0x08,0x14,0x22,0x41], 'L': [0x7F,0x40,0x40,0x40,0x40],
    'M': [0x7F,0x02,0x0C,0x02,0x7F], 'N': [0x7F,0x04,0x08,0x10,0x7F],
    'O': [0x3E,0x41,0x41,0x41,0x3E], 'P': [0x7F,0x09,0x09,0x09,0x06],
    'Q': [0x3E,0x41,0x51,0x21,0x5E], 'R': [0x7F,0x09,0x19,0x29,0x46],
    'S': [0x46,0x49,0x49,0x49,0x31], 'T': [0x01,0x01,0x7F,0x01,0x01],
    'U': [0x3F,0x40,0x40,0x40,0x3F], 'V': [0x1F,0x20,0x40,0x20,0x1F],
    'W': [0x3F,0x40,0x38,0x40,0x3F], 'X': [0x63,0x14,0x08,0x14,0x63],
    'Y': [0x07,0x08,0x70,0x08,0x07], 'Z': [0x61,0x51,0x49,0x45,0x43],
    ':': [0x00,0x36,0x36,0x00,0x00], '.': [0x00,0x60,0x60,0x00,0x00],
    '%': [0x23,0x13,0x08,0x64,0x62], ' ': [0x00,0x00,0x00,0x00,0x00],
    '-': [0x08,0x08,0x08,0x08,0x08], '/': [0x20,0x10,0x08,0x04,0x02],
}

def draw_text(img, x, y, text):
    px = img.load()
    cx = x
    for ch in text:
        glyph = FONT.get(ch, FONT.get(ch.upper(), FONT[' ']))
        for col, bits in enumerate(glyph):
            for row in range(7):
                if bits & (1 << row):
                    dx, dy = cx + col, y + row
                    if 0 <= dx < 128 and 0 <= dy < 32:
                        px[dx, dy] = 1
        cx += 6
    return cx

def get_ip():
    try:
        return subprocess.check_output(["hostname", "-I"]).decode().split()[0]
    except Exception:
        return "NoIP"

def get_cpu_temp():
    try:
        with open("/sys/class/thermal/thermal_zone0/temp") as f:
            return f"{int(f.read()) / 1000:.0f}C"
    except Exception:
        return "N/A"

def get_cpu_load():
    try:
        with open("/proc/stat") as f:
            parts = f.readline().split()
        total1 = sum(int(p) for p in parts[1:])
        idle1 = int(parts[4])
        time.sleep(0.05)
        with open("/proc/stat") as f:
            parts = f.readline().split()
        total2 = sum(int(p) for p in parts[1:])
        idle2 = int(parts[4])
        dtotal = total2 - total1
        didle = idle2 - idle1
        if dtotal == 0:
            return "0%"
        return f"{int((dtotal - didle) * 100 / dtotal)}%"
    except Exception:
        return "N/A"

if __name__ == "__main__":
    try:
        init()
        while True:
            img = Image.new('1', (128, 32), 0)
            draw_text(img, 2, 1,  "IP " + get_ip())
            draw_text(img, 2, 10, "CPU " + get_cpu_temp())
            draw_text(img, 2, 19, "LOAD " + get_cpu_load())
            show(img)
            time.sleep(3)
    except KeyboardInterrupt:
        pass
    finally:
        try:
            cmd(0xAE)
        except Exception:
            pass
        GPIO.cleanup()
        spi.close()

Запустите скрипт из папки проекта:

1
2
cd ~/tft_project
python3 oled_info.py

На экране появятся три строки: IP-адрес, температура процессора в градусах Цельсия и текущая загрузка CPU в процентах. Данные обновляются каждые три секунды. Для остановки нажмите Ctrl+C — скрипт выключит дисплей и освободит GPIO.

Результат теста на OLED-дисплее

Типичные проблемы и решения

Проблема: Изображение сдвинуто влево, левая граница не отображается, справа видны артефакты. Контроллер SSD1305 имеет внутреннюю видеопамять 132×64 пикселя, тогда как сам дисплей физически 128×32. Из-за этого при выводе без коррекции начало координат смещается. Решение — установить смещение столбцов в 4 пикселя в командах установки адресного окна: cmd(0x21); cmd(4); cmd(131). В некоторых ревизиях панели смещение может быть 2 или 0 — подбирается экспериментально по ровной рамке.

Проблема: Текст не помещается по высоте, нижняя строка обрезана. Стандартный шрифт Pillow ImageFont.load_default() имеет высоту около 11 пикселей, три строки занимают 33 пикселя при доступных 32. Решение — использовать собственный компактный шрифт 5×7 с шагом 6 пикселей по горизонтали и 9 по вертикали, как в скрипте выше. Это даёт три строки с запасом и не требует внешних файлов шрифтов.

Проблема: Скрипт падает с ошибкой Permission denied при доступе к /dev/spidev0.0 или GPIO. Пользователь не входит в группы spi и gpio. Проверьте права командой ls -l /dev/spidev0.0 и добавьте пользователя в нужные группы: sudo usermod -aG spi,gpio $USER, затем перезайдите в систему. В свежих сборках Raspberry Pi OS пользователь pi уже включён в эти группы; проблема возникает, если создан новый пользователь или используется кастомный образ.

Проблема: Дисплей остаётся чёрным после запуска скрипта. Проверьте, что SPI включён: ls /dev/spidev0.* — должны быть видны /dev/spidev0.0 и /dev/spidev0.1. Если файлов нет, вернитесь к разделу «Подготовка системы» и включите SPI через raspi-config. Также убедитесь, что модуль плотно посажен на GPIO, а пины DC (BCM 24) и RST (BCM 25) не перепутаны. Если после перезагрузки экран по-прежнему чёрный, проверьте контраст: команда 0x81, 0xCF в последовательности инициализации задаёт его значение, и при слишком низком контрасте свечение может быть незаметным при дневном свете.

Модуль 2.23 дюйма на SSD1305 с разрешением 128×32 хорошо подходит для роли компактного статус-индикатора: три строки текста помещаются с запасом, а подключение по SPI не требует дополнительных проводов — HAT садится прямо на GPIO. Главное, что стоит запомнить при работе с этой моделью, — смещение столбцов на 4 пикселя и компактный шрифт вместо стандартного Pillow. После внесения этих двух правок дисплей стабильно выводит системную информацию, и на его основе можно строить более сложные сценарии: бегущие строки, графики загрузки, переключение экранов по таймеру.

Авторский пост защищен лицензией CC BY 4.0 .

© evdokimoff. Некоторые права защищены.

Использует тему Chirpy для Jekyll