Пост

Подключение нестандартной TFT-панели ST7789 76x284 к Raspberry Pi Zero

В мире микроконтроллеров и одноплатных компьютеров подключение дисплеев часто кажется простой задачей, пока вы не столкнетесь с нестандартным разрешением. Панели на базе контроллера ST7789 с разрешением 76x284 (часто встречающиеся в виде 2.25-дюймовых модулей с 8-пиновым SPI-интерфейсом) являются ярким примером такого испытания. Стандартные библиотеки (Adafruit, Pimoroni, luma) либо не поддерживают такие размеры, либо неверно применяют смещения (offsets), из-за чего пользователь видит лишь белый экран или цветной шум. Данная статья описывает проверенный метод запуска такой панели на Raspberry Pi Zero 1.3 через написание собственного низкоуровневого драйвера с использованием `spidev`.

Подключение нестандартной TFT-панели ST7789 76x284 к Raspberry Pi Zero В мире микроконтроллеров и одноплатных компьютеров подключение дисплеев часто кажется простой задачей, пока вы не столкнетесь с нестандартным разрешением. Панели на базе контроллера ST7789 с разрешением 76x284 (часто встречающиеся в виде 2.25-дюймовых модулей с 8-пиновым SPI-интерфейсом) являются ярким примером такого испытания. Стандартные библиотеки (Adafruit, Pimoroni, luma) либо не поддерживают такие размеры, либо неверно применяют смещения (offsets), из-за чего пользователь видит лишь белый экран или цветной шум. Данная статья описывает проверенный метод запуска такой панели на Raspberry Pi Zero 1.3 через написание собственного низкоуровневого драйвера с использованием spidev.

Рекомендации по подготовке

Перед началом работы убедитесь, что у вас установлена актуальная версия Raspberry Pi OS (Bookworm или новее). Для работы нам понадобятся базовые библиотеки для работы с GPIO и SPI, а также библиотека Pillow для генерации изображений. Рекомендуется использовать виртуальное окружение (venv), чтобы не засорять системный Python. Обязательно используйте только 3.3В питание (Pin 1), подача 5В может вывести панель из строя.

Внешний вид TFT-панели ST7789

Аппаратное подключение

Подключение выполняется к 40-контактному разъему GPIO. Обратите внимание на порядок пинов на самой плате дисплея (обычно они подписаны: GND, VCC, SCL, SDA, RST, DC, CS, BL).

Пин панели Физический пин RPi GPIO (BCM) Назначение
GND Pin 6 GND Земля
VCC Pin 1 3.3V Питание
SCL Pin 23 GPIO 11 SPI SCLK
SDA Pin 19 GPIO 10 SPI MOSI
RST Pin 22 GPIO 25 Reset
DC Pin 18 GPIO 24 Data/Command
CS Pin 24 GPIO 8 Chip Select (CE0)
BL Pin 12 GPIO 18 Подсветка (Active Low)

Внешний вид TFT-панели ST7789

Настройка операционной системы

По умолчанию SPI на Raspberry Pi может быть отключен. Кроме того, необходимо убедиться, что аппаратный Chip Select не отключен сторонними оверлеями. Откройте файл конфигурации:

1
sudo nano /boot/firmware/config.txt

Убедитесь, что строка dtparam=spi=on присутствует и не закомментирована. Если вы ранее добавляли dtoverlay=spi0-0cs для других проектов, закомментируйте её (поставьте # в начале), так как она отключает аппаратный CS, необходимый для нашей панели. После сохранения перезагрузите плату:

1
sudo reboot

После перезагрузки проверьте наличие устройств SPI:

1
ls /dev/spidev*

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

Подготовка окружения Python

Создайте папку для проекта и настройте виртуальное окружение с доступом к системным библиотекам (это необходимо для корректной работы некоторых зависимостей):

1
2
3
4
mkdir ~/tft_project
cd ~/tft_project
python3 -m venv venv --system-site-packages
source venv/bin/activate

Установите необходимые пакеты:

1
pip install spidev RPi.GPIO Pillow numpy

Разработка кастомного драйвера

Проблема стандартных библиотек в том, что они не знают о физических смещениях (offsets) матрицы. Видимая область 76x284 начинается не с координаты (0,0) в памяти контроллера (которая рассчитана на 240x320), а со смещением 82 по оси X и 18 по оси Y. Кроме того, панель требует SPI Mode 3. Ниже представлен класс, который инициализирует дисплей напрямую, минуя сложные библиотеки. Создайте файл tft_driver.py и скопируйте в него этот код:

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
import time
import spidev
import RPi.GPIO as GPIO
from PIL import Image
import numpy as np

class ST7789:
    def __init__(self, dc=24, rst=25, bl=18, width=76, height=284, 
                 offset_left=82, offset_top=18, speed_hz=8000000):
        self.width = width
        self.height = height
        self.offset_left = offset_left
        self.offset_top = offset_top
        
        GPIO.setwarnings(False)
        GPIO.setmode(GPIO.BCM)
        GPIO.setup(dc, GPIO.OUT)
        GPIO.setup(rst, GPIO.OUT)
        GPIO.setup(bl, GPIO.OUT)
        self.dc_pin = dc
        self.rst_pin = rst
        self.bl_pin = bl
        
        # Включаем подсветку (Active Low)
        GPIO.output(bl, GPIO.LOW)
        
        self.spi = spidev.SpiDev()
        self.spi.open(0, 0)
        self.spi.max_speed_hz = speed_hz
        self.spi.mode = 3  # Критически важно для этой панели
        
        self._init_display()
    
    def _cmd(self, c):
        GPIO.output(self.dc_pin, GPIO.LOW)
        self.spi.xfer2([c])
    
    def _data(self, d):
        GPIO.output(self.dc_pin, GPIO.HIGH)
        if isinstance(d, (list, bytes, bytearray)):
            self.spi.xfer2(list(d))
        else:
            self.spi.xfer2([d])
    
    def _init_display(self):
        GPIO.output(self.rst_pin, GPIO.HIGH)
        time.sleep(0.01)
        GPIO.output(self.rst_pin, GPIO.LOW)
        time.sleep(0.01)
        GPIO.output(self.rst_pin, GPIO.HIGH)
        time.sleep(0.12)
        
        self._cmd(0x01); time.sleep(0.15)
        self._cmd(0x11); time.sleep(0.12)
        
        # MADCTL: 0x00 = RGB (0x08 был бы BGR)
        self._cmd(0x36); self._data(0x00)
        self._cmd(0x3A); self._data(0x55)
        self._cmd(0x20) # Отключаем инверсию
        self._cmd(0x29); time.sleep(0.1)
    
    def display(self, img):
        img = img.convert("RGB")
        x0, y0 = self.offset_left, self.offset_top
        x1 = x0 + self.width - 1
        y1 = y0 + self.height - 1
        
        self._cmd(0x2A)
        self._data([x0 >> 8, x0 & 0xFF, x1 >> 8, x1 & 0xFF])
        self._cmd(0x2B)
        self._data([y0 >> 8, y0 & 0xFF, y1 >> 8, y1 & 0xFF])
        self._cmd(0x2C)
        
        pixels = np.array(img)
        r = pixels[:, :, 0].astype(np.uint16)
        g = pixels[:, :, 1].astype(np.uint16)
        b = pixels[:, :, 2].astype(np.uint16)
        
        rgb565 = ((r & 0xF8) << 8) | ((g & 0xFC) << 3) | (b >> 3)
        data = rgb565.astype('>u2').tobytes()
        
        GPIO.output(self.dc_pin, GPIO.HIGH)
        chunk_size = 4096
        for i in range(0, len(data), chunk_size):
            self.spi.xfer2(list(data[i:i+chunk_size]))

Тестирование

Создайте тестовый скрипт test_display.py:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
from tft_driver import ST7789
from PIL import Image, ImageDraw, ImageFont
import time

disp = ST7789()
print("Инициализация прошла успешно!")

# Заливка цветами
for color, name in [("red", "КРАСНЫЙ"), ("green", "ЗЕЛЕНЫЙ"), ("blue", "СИНИЙ"), ("black", "ЧЕРНЫЙ")]:
    print(f"Заливка: {name}")
    img = Image.new("RGB", (disp.width, disp.height), color=color)
    disp.display(img)
    time.sleep(1)

# Вывод текста
img = Image.new("RGB", (disp.width, disp.height), color="black")
draw = ImageDraw.Draw(img)
draw.text((10, 20), "RPi ZERO\nST7789\nWORKS!", fill="white")
disp.display(img)
print("Скрипт завершен. Изображение на экране.")

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

1
python test_display.py

Пример успешного выполнения

Если на экране появился текст и цвета сменились в правильной последовательности, значит, панель успешно запущена.

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

Проблема: Экран остается белым при включенной подсветке. Решение: Убедитесь, что SPI работает в режиме Mode 3. По умолчанию многие библиотеки используют Mode 0, что приводит к игнорированию команд контроллером. Также проверьте, что не активирован dtoverlay=spi0-0cs в /boot/firmware/config.txt.

Проблема: Вместо заливки цветом на экране хаотичный цветной шум. Решение: Неправильно заданы смещения (offsets). Библиотека рисует в “слепой” зоне памяти. Для этой панели жестко задайте смещение 82 пикселя по X и 18 по Y при установке адресного окна (команды 0x2A и 0x2B).

Проблема: Подсветка не включается или, наоборот, горит постоянно. Решение: На данной панели пин BL (Backlight) инвертирован (Active Low). Для включения подсветки на него нужно подавать низкий логический уровень (GND / LOW), а для выключения — высокий (3.3V / HIGH).

Проблема: Красный и синий цвета перепутаны местами. Решение: Измените порядок цветовых каналов. В команде MADCTL (0x36) отправляйте байт 0x00 для схемы RGB или 0x08 для схемы BGR.

Мы прошли путь от полного непонимания и белого экрана до создания собственного драйвера, который полностью контролирует каждый байт данных. Использование spidev вместо тяжелых библиотек дает максимальную производительность и гибкость, позволяя в дальнейшем интегрировать эту панель с любыми графическими фреймворками, включая LVGL и SquareLine Studio. Теперь вы обладаете полным контролем над нестандартным железом.

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

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

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