SHiNE-server/ESP32/esp32/ESP32-S3-Touch-AMOLED-2.16/CODEX_PORTING_GUIDE.md

ESP32-S3-Touch-AMOLED-2.16 Codex Guide

Этот файл переносится в другие проекты как готовая инструкция для Codex по этой плате.

1) Что это за плата

• Модель: Waveshare ESP32-S3-Touch-AMOLED-2.16
• MCU: ESP32-S3 (flash 16MB, PSRAM 8MB)
• Экран: AMOLED, физически 480x480, углы скруглены (часть крайних пикселей может быть невидима)
• Touch: CST92xx
• IMU: QMI8658
• Аудио:
  • DAC/вывод (динамик): ES8311
  • ADC/вход (микрофоны): ES7210

2) Что уже установлено в этой среде

• Ubuntu
• arduino-cli 1.4.0
• esp32:esp32 core 3.3.5
• esptool из ~/.arduino15/packages/esp32/tools/esptool_py/5.1.0/esptool
• USB порт платы: обычно /dev/ttyACM0

Проверка:

arduino-cli version
arduino-cli core list
arduino-cli board list
ls -l /dev/ttyACM0

3) Структура подпроекта (эталон)

• official-demo/ — официальный repo Waveshare (примеры+библиотеки)
• original-firmware/ — backup/restore заводской прошивки
• test-device/ — прошивки и burn.sh
• reference/ — заметки и ссылки

4) Бэкап перед любыми экспериментами

cd ESP32-S3-Touch-AMOLED-2.16/original-firmware
./backup_factory.sh

Ожидаемый результат:

• factory-full-16mb.bin
• factory-full-16mb.bin.sha256

Восстановление:

./restore_factory_backup.sh

5) Деплой (прошивка) — стандарт

Главный скрипт:

cd ESP32-S3-Touch-AMOLED-2.16/test-device
./burn.sh <mode>

Режимы:

• hello — базовый экран
• widgets — экран+touch+IMU (официальный пример)
• audio — тест аудио тракта
• simple — кастомный интеграционный тест (экран, touch, запись/воспроизведение, VU, tilt)

6) Как писать код под эту плату (важно)

1. Экран

   • Рабочее разрешение использовать 480x480.
   • Не рисовать критичный текст/кнопки впритык к краю; держать safe margin (~20px+) из-за скругленных углов.
   • Не делать полный fillScreen в каждом loop: только частичные обновления (fillRect/локальные перерисовки), иначе мерцание.

2. Touch

   • Настройка CST:
     • setMaxCoordinates(480, 480)
     • setSwapXY(true)
     • setMirrorXY(true, false)
   • Обрабатывать touch по IRQ + getPoint.
   • После смещения UI обязательно пересчитывать hitbox кнопок.

3. Аудио

   • Для динамика инициализировать ES8311.
   • Для микрофона обязательно инициализировать ES7210; без этого запись может быть пустой.
   • Для отладки записи показывать VU/peak на экране во время RECORD.
   • Для быстрой проверки тракта всегда держать кнопку BEEP (тон), чтобы отделить проблему динамика от проблемы микрофона.

4. IMU

   • QMI8658 обновлять с ограниченной частотой (например 80–150 мс для UI-строки), чтобы не шуметь перерисовками.

5. Стабильность UI

   • Статика: рисуется один раз в setup.
   • Динамика: отдельная зона, перерисовывать только по изменению данных.

7) Рекомендуемый workflow для Codex

1. Проверить порт и инструменты.
2. Если новая плата/первый запуск — сделать backup flash.
3. Собрать и залить simple.
4. Пройти ручной чек:
   • экран отображает текст без обрезки,
   • touch срабатывает по кнопкам,
   • BEEP слышно,
   • VU двигается во время записи,
   • PLAY воспроизводит записанное,
   • Tilt меняется при повороте.
5. Только после этого усложнять приложение.

8) Ссылки

• Product page: https://www.waveshare.com/product/arduino/boards-kits/esp32-s3/esp32-s3-touch-amoled-2.16.htm
• Docs: https://docs.waveshare.com/ESP32-S3-Touch-AMOLED-2.16
• Arduino setup: https://docs.waveshare.com/ESP32-S3-Touch-AMOLED-2.16/Development-Environment-Setup-Arduino
• Official examples: https://github.com/waveshareteam/ESP32-S3-Touch-AMOLED-2.16