CYD Display

Русский

Версия: 0.9.11

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

Возможности

нативный вывод RGB565 в разрешении 320×240 или 240×320;
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;
включение усилителя через GPIO4 с активным уровнем LOW;
пакетный протокол CYD/1 с CRC16 и восстановлением после обрыва связи.
консольная утилита для управления экраном из cmd, PowerShell и скриптов.

Структура релиза

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

Release формируется с нуля скриптом сборки и не содержит внутренних файлов передачи проекта между сессиями разработки.

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

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

CYD_PROFILE_FNK0103L — RGB 22/16/17, GPIO4 включает усилитель;
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.4.1 или новее.

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

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

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

IncludeFile "CYD_Display.pbi"

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

Открыть устройство через CYD_Open("COM5").
Нарисовать кадр функциями CYD_ClearBuffer(), CYD_FillRect(), CYD_DrawLine(), CYD_DrawText() или CYD_DrawImage().
Передать изменения вызовом 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_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() возвращает тип, состояние, ошибку и путь.

Файловые операции и 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 без калибровки:

Build\CYD_CLI.exe --port auto touch-raw 10

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

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

Готовые программы

Build/CYD_Demo.exe — демонстрация экрана, тача, калибровки и звука;
Build/CYD_Calibrate.exe — интерактивная калибровка с выводом сырых X/Y;
Build/CYD_GraphicsDemo.exe — текст, примитивы, график и виджеты;
Build/CYD_FastGraphicsDemo.exe — аппаратные примитивы и автономный скролл;
Build/CYD_CLI.exe — управление экраном, графикой, скроллом, тачем и звуком из командной строки;
Build/CYD_AudioTest.exe — максимальная громкость: три тона и PCM-свип;
Build/CYD_GIFPlayer.exe — аналог GIF-плеера с декодированием на ESP32;
Build/CYD_MP3Player.exe — загрузка и управление MP3 с SD-карты;
Build/CYD_SmokeTest.exe — короткий автоматический тест;
Build/CYD_ProtocolTest.exe — расширенная диагностика протокола.

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

Если порт не указан, CYD_CLI.exe автоматически проверяет COM1…COM256 и выбирает первое устройство, ответившее на CYD HELLO. То же поведение явно задаётся параметром --port auto; конкретный порт можно выбрать, например, через --port COM5.

Полное руководство по библиотеке находится в 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 и собственные уведомления об авторских правах.

English

Version: 0.9.11

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;
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;
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.

Release 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;
Build — compiled executables;
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 release is rebuilt from scratch and does not contain internal files used to hand the project between development sessions.

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_ESP32_024 — RGB 4/16/17; touch IRQ36.

Both 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.4.1 or newer.

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

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("COM5").
Draw a frame with CYD_ClearBuffer(), CYD_FillRect(), CYD_DrawLine(), CYD_DrawText(), or CYD_DrawImage().
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_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.

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:

Build\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.

Included programs

Build/CYD_Demo.exe — display, touch, calibration, and audio demo;
Build/CYD_Calibrate.exe — interactive calibration with raw X/Y output;
Build/CYD_GraphicsDemo.exe — text, primitives, graphs, and widgets;
Build/CYD_FastGraphicsDemo.exe — hardware primitives and autonomous scroll;
Build/CYD_CLI.exe — command-line display, graphics, scrolling, touch, and audio control;
Build/CYD_AudioTest.exe — maximum-volume tones and PCM sweep;
Build/CYD_GIFPlayer.exe — GIF player decoded on the ESP32;
Build/CYD_MP3Player.exe — SD-card MP3 upload and control;
Build/CYD_SmokeTest.exe — short automatic test;
Build/CYD_ProtocolTest.exe — extended protocol diagnostics.

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

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.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

CYD Display

Русский

Возможности

Структура релиза

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

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

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

SD, GIF и MP3

Калибровка

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

Готовые программы

Лицензия

English

Features

Release layout

Preparing the board

Using the library from PureBasic

Drawing functions

SD, GIF, and MP3

Calibration

Touch questions

Included programs

License

About

Releases

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
Lib		Lib
Pictures		Pictures
Source		Source
.gitattributes		.gitattributes
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

Release layout

Preparing the board

Using the library from PureBasic

Drawing functions

SD, GIF, and MP3

Calibration

Touch questions

Included programs

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Contributors

Languages