CYD Display

Русский

Версия: 0.9.16

CYD Display превращает поддерживаемые платы ESP32-CYD с экраном ST7789 и контроллером касаний XPT2046 в небольшой двусторонний дисплей для программ на PureBasic.

Возможности

нативный вывод RGB565 в разрешении 320×240 или 240×320;
framebuffer и рисование средствами PureBasic;
центрированные QR-коды с UTF-8, создаваемые в framebuffer PureBasic;
частичное обновление изменённой области;
аппаратные примитивы и встроенный текст, рисуемые непосредственно ESP32;
автономный скролл около 30 кадров/с без передачи кадров с ПК;
независимые автономные Clock и Date, автономный Timer с событием завершения;
четыре ориентации и управление подсветкой;
события нажатия, перемещения и отпускания;
четырёхточечная калибровка тачскрина с сохранением в NVS;
генерация тона и воспроизведение unsigned 8-bit mono PCM;
FAT32 microSD, загрузка файлов с ПК, автономное воспроизведение GIF;
скачивание файлов с SD на ПК, список каталога и удаление файлов;
MP3 с SD-карты, пауза, продолжение и остановка;
PWM-управление штатным RGB-светодиодом;
сканирование Wi-Fi с выводом SSID, BSSID, RSSI, канала и типа шифрования;
синхронные сенсорные вопросы с автоформатированием текста и 1–6 быстрыми закруглёнными кнопками;
вывод звука через штатный усилитель и гнездо SPK;
автономные короткие мелодии в RTTTL-подобной записи;
включение усилителя через GPIO4 с активным уровнем LOW;
пакетный протокол CYD/1 с CRC16 и восстановлением после обрыва связи.
консольная утилита для управления экраном из cmd, PowerShell и скриптов.

Структура репозитория

Source/Sketch — исходник прошивки Arduino для ESP32;
Source/Sketch/CYD_HardwareConfig.h — выбираемые профили плат;
Source/PB — исходники примеров, программ и диагностики PureBasic;
Lib/CYD_Display.pbi — подключаемая библиотека PureBasic;
PROGRAMMER_GUIDE.md — полный справочник API библиотеки;
CLI.md — синтаксис и примеры командной строки;
PROTOCOL.md — спецификация протокола CYD/1;
LICENSE — условия некоммерческого использования и отказ от гарантий;
VERSION — номер текущей версии.

Репозиторий содержит исходники без готовых EXE. Перед компиляцией примеров поместите Lib/CYD_Display.pbi рядом с нужным файлом из Source/PB либо добавьте каталог Lib в пути поиска PureBasic.

Подготовка платы

Перед сборкой откройте Source/Sketch/CYD_HardwareConfig.h и выберите CYD_ACTIVE_PROFILE:

CYD_PROFILE_FNK0103L — RGB 22/16/17, GPIO4 включает усилитель;
CYD_PROFILE_FNK0103L_ROTATED_180 — тот же FNK0103L, стартовый экран повёрнут на 180 градусов;
CYD_PROFILE_ESP32_024 — RGB 4/16/17, touch IRQ36.

Все профили используют ST7789 и XPT2046 на общей HSPI GPIO12/13/14, TFT CS15/DC2, touch CS33, подсветку GPIO27, отдельную SD VSPI GPIO18/19/23 с CS5 и аудио DAC GPIO26. Параметры инверсии, частоты TFT, полярности, IRQ и NVS namespace задаются профилем. В поставляемых исходниках активен профиль ESP32-024.

Для сборки и загрузки прошивки:

arduino-cli compile --fqbn esp32:esp32:esp32 .\Source\Sketch
arduino-cli upload -p COM5 --fqbn esp32:esp32:esp32 .\Source\Sketch

Требуются Arduino-библиотеки:

Adafruit GFX Library;
Adafruit ST7735 and ST7789 Library;
XPT2046_Touchscreen;
ESP8266Audio 2.0.0 для интерфейсов источника файла и аудиовыхода.

Исходники AnimatedGIF 2.2.0 включены в Source/Sketch по лицензии Apache-2.0; отдельно устанавливать эту библиотеку не требуется. Декодер minimp3 также включён в Source/Sketch по лицензии CC0.

Использование в PureBasic

Скопируйте Lib/CYD_Display.pbi рядом с проектом и подключите:

IncludeFile "CYD_Display.pbi"

Основной цикл:

Открыть устройство через CYD_Open() с автопоиском либо явно указать порт, например CYD_Open("COM5").
Нарисовать кадр функциями CYD_ClearBuffer(), CYD_FillRect(), CYD_DrawLine(), CYD_DrawText(), CYD_DrawImage() или CYD_DrawQRCode().
Передать изменения вызовом CYD_Flush().
В цикле программы получать касания через CYD_GetEvent().
Перед завершением вызвать CYD_Close().

Функции отрисовки

В библиотеку перенесены возможности исходной WeActDisplay с префиксом CYD_ и нативной геометрией CYD:

CYD_DrawPixel(), CYD_DrawLine(), CYD_DrawRect();
CYD_FillRect(), CYD_DrawCircle(), CYD_DrawTriangle();
CYD_DrawText(), CYD_DrawTextSmall/Medium/Large();
CYD_GetTextWidth(), CYD_GetTextHeight();
CYD_DrawWrappedText(), CYD_DrawWrappedTextAutoSize();
CYD_DrawImage(), CYD_DrawImageCentered(), CYD_DrawImageFullScreen();
CYD_DrawQRCode(Text, Foreground, Background, Scale) — QR Model 2, уровень M, версии 1–10, до 212 байт UTF-8; при Scale = 0 код автоматически масштабируется и центрируется;
CYD_DrawProgressBar(), CYD_DrawGraph(), CYD_DrawSpinner();
CYD_ShowTime(), CYD_ShowDate(), CYD_ShowTextFile();
CYD_StartScrollText(), CYD_UpdateScrollText(), CYD_DrawScrollText().

Быстрый слой ESP32:

CYD_DeviceDrawPixel(), CYD_DeviceDrawLine();
CYD_DeviceDrawRect(), CYD_DeviceFillRect();
CYD_DeviceDrawCircle(), CYD_DeviceDrawTriangle();
CYD_DeviceDrawText(), CYD_DeviceDrawButton();
CYD_DeviceStartScrollText(), CYD_DeviceStopScrollText().
CYD_DeviceStartClock(), CYD_DeviceStopClock();
CYD_DeviceStartDate(), CYD_DeviceStopDate();
CYD_DeviceStartTimer(), CYD_DeviceWaitTimer(), CYD_DeviceStopTimer().

Clock выводит HH:MM:SS, Date — YYYY-MM-DD. Они независимо запускаются и останавливаются, а после начальной синхронизации с локальным временем ПК обновляются самим ESP32. Timer ведёт обратный отсчёт на ESP32; CLI ждёт его аппаратное событие завершения.

CYD_DeviceStartScrollText() передаёт строку, область, направление и скорость только один раз. Дальнейшие кадры формирует ESP32 локально. Быстрый встроенный шрифт предназначен для ASCII; для кириллицы, системных шрифтов и сглаживания остаётся framebuffer-функция CYD_DrawText().

Для упрощения переноса старых программ предусмотрены варианты имён CYD_DrawPixelBuffer(), CYD_DrawRectangleBuffer(), CYD_DrawLineBuffer(), CYD_DrawCircleBuffer(), CYD_DrawTextSystemFont(), CYD_LoadImageToBuffer() и CYD_UpdateDisplay().

SD, GIF и MP3

CYD_UploadFileToSD() копирует локальный файл на FAT32-карту. После загрузки данные не передаются по COM при каждом кадре или аудиоблоке:

CYD_UploadFileToSD("demo.gif", "/CYD/demo.gif")
CYD_PlayGIFFromSD("/CYD/demo.gif")

CYD_UploadFileToSD("music.mp3", "/CYD/music.mp3")
CYD_PlayMP3FromSD("/CYD/music.mp3", 255)

GIF поддерживает скорость, число повторов, паузу, продолжение и остановку. Режим #CYD_GIF_COVER по умолчанию заполняет весь экран с обрезкой краёв; доступны также #CYD_GIF_CONTAIN и #CYD_GIF_STRETCH. MP3 поддерживает громкость 0…255, циклический режим, паузу, продолжение и остановку. CYD_GetMediaStatus() возвращает тип, состояние, ошибку и путь.

Декодер принимает CBR и VBR. Гарантированно проверенный профиль — CBR не выше 256 кбит/с. VBR допустим, только если битрейт каждого кадра не превышает 256 кбит/с: среднего значения 256 кбит/с недостаточно, поскольку отдельные кадры могут достигать 320 кбит/с. Рекомендуемая перекодировка:

ffmpeg -i input.mp3 -codec:a libmp3lame -b:a 256k output.mp3

Файловые операции и RGB:

CYD_ListSDFiles("/CYD")
ForEach CYD_SDEntries()
  Debug CYD_SDEntries()\Name
Next

CYD_DownloadFileFromSD("/CYD/demo.gif", "downloaded.gif")
CYD_DeleteSDFile("/CYD/demo.gif")
CYD_SetRGB(255, 80, 0)

Поиск точек доступа:

If CYD_ScanWiFi() >= 0
  ForEach CYD_WiFiNetworks()
    Debug CYD_WiFiNetworks()\SSID
  Next
EndIf

Калибровка

Вызовите CYD_StartTouchCalibration() и последовательно нажмите четыре мишени. Коэффициенты сохраняются во flash/NVS платы. Калибровку можно отменить через CYD_CancelTouchCalibration() или удалить вызовом CYD_ResetTouchCalibration().

Сенсорные вопросы

Стандартный вопрос с коротким звуковым сигналом:

Answer = CYD_Question("Продолжить?", #YesNo, 200)

Пользовательские ответы:

Answer = CYD_Question("Выберите режим",
                      #custom,
                      -1,
                      "Тихий",
                      "Обычный",
                      "Турбо")

Текст автоматически переносится и центрируется. Нижняя полоса делится на нужное число одинаковых кнопок. Процедура ждёт нажатия сенсора на кнопку и возвращает номер ответа от 1; при ошибке возвращается 0. Значение громкости beep — 0…254, -1 отключает сигнал.

Кнопки имеют закруглённую форму и объёмную светлую и тёмную грани. Геометрия рисуется непосредственно ESP32; с ПК передаются только системный шрифт вопроса и небольшие области подписей. Выбор происходит сразу при нажатии, после чего ESP32 кратко инвертирует грани без повторной передачи bitmap. Встроенные типы используют интернациональные подписи OK, YES, NO, IGNORE. Кириллица полностью поддерживается в тексте вопроса и пользовательских подписях режима #custom.

Для низкоуровневой проверки XPT2046 без калибровки:

CYD_CLI.exe --port auto touch-raw 10

Во время выполнения следует несколько раз нажать на экран. Строка 1 raw_x raw_y pressure означает, что контроллер физически отвечает.

Калибровка подтверждает отпускание в течение 50 мс. Краткий провал чтения XPT2046 больше не может засчитать одно удержание как две разные точки.

Программы и примеры

В Source/PB находятся исходники демонстрации, калибровки, графических примеров, CLI, GIF- и MP3-плееров, аудиотеста, smoke-теста и расширенной диагностики протокола.

Все программы являются консольными. Библиотека не использует WinAPI и основана на стандартных библиотеках PureBasic.

Если порт не указан, библиотека и программы автоматически проверяют COM1…COM256 и выбирают первое устройство, ответившее на CYD HELLO. Конкретный порт можно передать библиотеке как CYD_Open("COM5"), а CLI — через --port COM5. Значение auto включает автопоиск явно.

Полное руководство по библиотеке находится в PROGRAMMER_GUIDE.md. Синтаксис и примеры CYD_CLI находятся в CLI.md. Краткая справка доступна командой:

CYD_CLI.exe --help

Лицензия

Copyright (C) CheshirCa 2026 — https://t.me/cheshircanest

Код CYD Display разрешено использовать, копировать, изменять и распространять только в некоммерческих целях с сохранением атрибуции. Коммерческое использование, продажа, платное распространение и включение в коммерческие продукты или услуги требуют явного письменного разрешения автора. Полные условия и отказ от гарантий находятся в файле LICENSE.

Включённые исходники AnimatedGIF 2.2.0 сохраняют отдельную лицензию Apache-2.0 и собственные уведомления об авторских правах.

QR-кодировщик адаптирован из Project Nayuki QR Code generator; уведомление MIT сохранено в CYD_Display.pbi.

English

Version: 0.9.16

CYD Display turns supported ESP32-CYD boards with an ST7789 display and an XPT2046 touch controller into a compact bidirectional display for PureBasic applications.

Features

native RGB565 output at 320×240 or 240×320;
a PureBasic framebuffer and drawing API with partial dirty-region updates;
centered UTF-8 QR codes generated in the PureBasic framebuffer;
hardware primitives and built-in text rendered directly by the ESP32;
autonomous scrolling at approximately 30 FPS without host frame transfers;
independent Clock and Date elements and a Timer with a completion event;
four orientations, backlight control, and press/move/release touch events;
four-point touchscreen calibration stored in NVS;
tone generation and unsigned 8-bit mono PCM playback;
autonomous short melodies in RTTTL-like notation;
FAT32 microSD upload, download, directory listing, and deletion;
autonomous GIF and MP3 playback with pause, resume, and stop controls;
PWM control of the onboard RGB LED;
Wi-Fi scanning with SSID, BSSID, RSSI, channel, and encryption information;
synchronous touch questions with automatic text layout and one to six rounded answer buttons;
audio through the onboard amplifier and SPK connector, with active-low amplifier enable on GPIO4;
the CRC16-protected CYD/1 packet protocol with recovery after interrupted communication;
a command-line utility for cmd, PowerShell, and scripts.

Repository layout

Source/Sketch — Arduino firmware source for the ESP32;
Source/Sketch/CYD_HardwareConfig.h — selectable board profiles;
Source/PB — PureBasic examples, programs, and diagnostics;
Lib/CYD_Display.pbi — the PureBasic include library;
PROGRAMMER_GUIDE.md — complete library API reference;
CLI.md — command-line syntax and examples;
PROTOCOL.md — CYD/1 protocol specification;
LICENSE — non-commercial terms and warranty disclaimer;
VERSION — current version number.

The repository contains source files without prebuilt executables. Before compiling an example, place Lib/CYD_Display.pbi beside the selected file from Source/PB, or add Lib to the PureBasic include search path.

Preparing the board

Before building, open Source/Sketch/CYD_HardwareConfig.h and select CYD_ACTIVE_PROFILE:

CYD_PROFILE_FNK0103L — RGB 22/16/17; GPIO4 enables the amplifier;
CYD_PROFILE_FNK0103L_ROTATED_180 — the same FNK0103L hardware with a 180-degree rotated startup screen;
CYD_PROFILE_ESP32_024 — RGB 4/16/17; touch IRQ36.

All profiles use an ST7789 and XPT2046 on shared HSPI pins GPIO12/13/14, TFT CS15/DC2, touch CS33, backlight GPIO27, separate SD VSPI pins GPIO18/19/23 with CS5, and audio DAC GPIO26. Display inversion, TFT frequency, polarity, IRQ, and NVS namespace are profile settings. The shipped sources select the ESP32-024 profile.

Build and upload the firmware with:

arduino-cli compile --fqbn esp32:esp32:esp32 .\Source\Sketch
arduino-cli upload -p COM5 --fqbn esp32:esp32:esp32 .\Source\Sketch

Required Arduino libraries:

Adafruit GFX Library;
Adafruit ST7735 and ST7789 Library;
XPT2046_Touchscreen;
ESP8266Audio 2.0.0 for file-source and audio-output interfaces.

AnimatedGIF 2.2.0 sources are included under the Apache-2.0 license in Source/Sketch; no separate AnimatedGIF installation is required. The minimp3 decoder is also included in Source/Sketch under the CC0 license.

Using the library from PureBasic

Copy Lib/CYD_Display.pbi next to your project and include it:

IncludeFile "CYD_Display.pbi"

Basic application flow:

Open the device with CYD_Open() for automatic discovery, or select a port explicitly, for example with CYD_Open("COM5").
Draw a frame with CYD_ClearBuffer(), CYD_FillRect(), CYD_DrawLine(), CYD_DrawText(), CYD_DrawImage(), or CYD_DrawQRCode().
Transfer changed regions with CYD_Flush().
Read touch events with CYD_GetEvent() in the application loop.
Call CYD_Close() before exiting.

Drawing functions

The library provides the original WeActDisplay functionality under a CYD_ prefix and uses native CYD geometry:

CYD_DrawPixel(), CYD_DrawLine(), CYD_DrawRect();
CYD_FillRect(), CYD_DrawCircle(), CYD_DrawTriangle();
CYD_DrawText(), CYD_DrawTextSmall/Medium/Large();
CYD_GetTextWidth(), CYD_GetTextHeight();
CYD_DrawWrappedText(), CYD_DrawWrappedTextAutoSize();
CYD_DrawImage(), CYD_DrawImageCentered(), CYD_DrawImageFullScreen();
CYD_DrawQRCode(Text, Foreground, Background, Scale) — QR Model 2, Medium error correction, versions 1–10, and up to 212 UTF-8 bytes; Scale = 0 automatically fits and centers the symbol;
CYD_DrawProgressBar(), CYD_DrawGraph(), CYD_DrawSpinner();
CYD_ShowTime(), CYD_ShowDate(), CYD_ShowTextFile();
CYD_StartScrollText(), CYD_UpdateScrollText(), CYD_DrawScrollText().

The fast ESP32-side layer provides:

CYD_DeviceDrawPixel(), CYD_DeviceDrawLine();
CYD_DeviceDrawRect(), CYD_DeviceFillRect();
CYD_DeviceDrawCircle(), CYD_DeviceDrawTriangle();
CYD_DeviceDrawText(), CYD_DeviceDrawButton();
CYD_DeviceStartScrollText(), CYD_DeviceStopScrollText();
CYD_DeviceStartClock(), CYD_DeviceStopClock();
CYD_DeviceStartDate(), CYD_DeviceStopDate();
CYD_DeviceStartTimer(), CYD_DeviceWaitTimer(), CYD_DeviceStopTimer().

Clock displays HH:MM:SS and Date displays YYYY-MM-DD. After initial synchronization with the PC's local time, both update independently on the ESP32. Timer counts down on the ESP32, while the CLI waits for its hardware completion event.

CYD_DeviceStartScrollText() transfers the string, region, direction, and speed once; the ESP32 generates subsequent frames locally. The fast built-in font is intended for ASCII. Use the framebuffer-based CYD_DrawText() for Cyrillic, system fonts, and antialiasing.

Compatibility aliases include CYD_DrawPixelBuffer(), CYD_DrawRectangleBuffer(), CYD_DrawLineBuffer(), CYD_DrawCircleBuffer(), CYD_DrawTextSystemFont(), CYD_LoadImageToBuffer(), and CYD_UpdateDisplay().

SD, GIF, and MP3

CYD_UploadFileToSD() copies a local file to a FAT32 card. Once uploaded, GIF frames and MP3 blocks do not need to be retransmitted over COM:

CYD_UploadFileToSD("demo.gif", "/CYD/demo.gif")
CYD_PlayGIFFromSD("/CYD/demo.gif")

CYD_UploadFileToSD("music.mp3", "/CYD/music.mp3")
CYD_PlayMP3FromSD("/CYD/music.mp3", 255)

GIF playback supports speed, loop count, pause, resume, and stop. #CYD_GIF_COVER fills the screen and crops the edges; alternatives are #CYD_GIF_CONTAIN and #CYD_GIF_STRETCH. MP3 playback supports volume 0…255, looping, pause, resume, and stop. CYD_GetMediaStatus() returns the media type, state, error, and path.

The decoder accepts CBR and VBR. The validated guaranteed profile is CBR at no more than 256 kbps. VBR is suitable only when every frame stays at or below 256 kbps: an average of 256 kbps is not sufficient because individual frames may reach 320 kbps. Recommended transcoding command:

ffmpeg -i input.mp3 -codec:a libmp3lame -b:a 256k output.mp3

File and RGB operations:

CYD_ListSDFiles("/CYD")
ForEach CYD_SDEntries()
  Debug CYD_SDEntries()\Name
Next

CYD_DownloadFileFromSD("/CYD/demo.gif", "downloaded.gif")
CYD_DeleteSDFile("/CYD/demo.gif")
CYD_SetRGB(255, 80, 0)

Wi-Fi access-point scanning:

If CYD_ScanWiFi() >= 0
  ForEach CYD_WiFiNetworks()
    Debug CYD_WiFiNetworks()\SSID
  Next
EndIf

Calibration

Call CYD_StartTouchCalibration() and press the four targets in sequence. The coefficients are stored in the board's flash/NVS. Cancel calibration with CYD_CancelTouchCalibration() or erase it with CYD_ResetTouchCalibration().

Touch questions

A standard question with a short beep:

Answer = CYD_Question("Continue?", #YesNo, 200)

Custom answers:

Answer = CYD_Question("Select mode",
                      #custom,
                      -1,
                      "Quiet",
                      "Normal",
                      "Turbo")

Text is wrapped and centered automatically. The bottom strip is divided into equal buttons. The procedure waits for a touch and returns an answer number starting with 1, or 0 on failure. Beep volume is 0…254; -1 disables the sound.

Buttons are rounded and use light and dark edges for depth. Their geometry is drawn directly by the ESP32. The PC transfers only the question's system-font text and small label regions. Selection happens on press, after which the ESP32 briefly inverts the edges without another bitmap transfer. Built-in types use OK, YES, NO, and IGNORE. Cyrillic is fully supported in the question and custom answer labels.

For low-level XPT2046 testing without calibration:

CYD_CLI.exe --port auto touch-raw 10

Press the display several times while the command runs. A line formatted as 1 raw_x raw_y pressure means that the controller is responding physically.

Calibration confirms release for 50 ms. A brief XPT2046 read dropout therefore cannot count one continuous press as two calibration points.

Programs and examples

Source/PB contains the demo, calibration tool, graphics examples, CLI, GIF and MP3 players, audio test, smoke test, and extended protocol diagnostics.

All programs are console programs. The library does not use WinAPI and is built on the standard PureBasic libraries.

When no port is specified, the library and programs scan COM1 through COM256 and select the first device that answers CYD HELLO. Pass CYD_Open("COM5") to the library or --port COM5 to the CLI to select a specific port. The explicit value auto enables discovery.

See PROGRAMMER_GUIDE.md for the complete library guide and CLI.md for CLI syntax and examples. Brief command help is available with:

CYD_CLI.exe --help

License

CYD Display code may be used, copied, modified, and distributed only for non-commercial purposes with attribution preserved. Commercial use, sale, paid distribution, or inclusion in commercial products or services requires the author's explicit written permission. See LICENSE for the complete terms and warranty disclaimer.

The included AnimatedGIF 2.2.0 sources retain their separate Apache-2.0 license and original copyright notices.

The QR encoder is adapted from the Project Nayuki QR Code generator; its MIT notice is retained in CYD_Display.pbi.

Navigation Menu

Repository files navigation

CYD Display

Русский

Возможности

Структура репозитория

Подготовка платы

Использование в PureBasic

Функции отрисовки

SD, GIF и MP3

Калибровка

Сенсорные вопросы

Программы и примеры

Лицензия

English

Features

Repository layout

Preparing the board

Using the library from PureBasic

Drawing functions

SD, GIF, and MP3

Calibration

Touch questions

Programs and examples

License

About

Releases

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
Lib		Lib
Pictures		Pictures
Source		Source
.gitattributes		.gitattributes
.gitignore		.gitignore
CLI.md		CLI.md
LICENSE		LICENSE
PROGRAMMER_GUIDE.md		PROGRAMMER_GUIDE.md
PROTOCOL.md		PROTOCOL.md
Readme.md		Readme.md
VERSION		VERSION

Folders and files

Latest commit

History

Repository files navigation

CYD Display

Русский

Возможности

Структура репозитория

Подготовка платы

Использование в PureBasic

Функции отрисовки

SD, GIF и MP3

Калибровка

Сенсорные вопросы

Программы и примеры

Лицензия

English

Features

Repository layout

Preparing the board

Using the library from PureBasic

Drawing functions

SD, GIF, and MP3

Calibration

Touch questions

Programs and examples

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Contributors

Languages