Подключение нестандартной 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В может вывести панель из строя.
Аппаратное подключение
Подключение выполняется к 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) |
Настройка операционной системы
По умолчанию 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. Теперь вы обладаете полным контролем над нестандартным железом.


