120 lines
5.0 KiB
Markdown
120 lines
5.0 KiB
Markdown
# 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`
|
||
|
||
Проверка:
|
||
|
||
```bash
|
||
arduino-cli version
|
||
arduino-cli core list
|
||
arduino-cli board list
|
||
ls -l /dev/ttyACM0
|
||
```
|
||
|
||
## 3) Структура подпроекта (эталон)
|
||
|
||
- `official-demo/` — официальный repo Waveshare (примеры+библиотеки)
|
||
- `original-firmware/` — backup/restore заводской прошивки
|
||
- `main-device/` — прошивки и `burn.sh`
|
||
- `reference/` — заметки и ссылки
|
||
|
||
## 4) Бэкап перед любыми экспериментами
|
||
|
||
```bash
|
||
cd ESP32-S3-Touch-AMOLED-2.16/original-firmware
|
||
./backup_factory.sh
|
||
```
|
||
|
||
Ожидаемый результат:
|
||
- `factory-full-16mb.bin`
|
||
- `factory-full-16mb.bin.sha256`
|
||
|
||
Восстановление:
|
||
|
||
```bash
|
||
./restore_factory_backup.sh
|
||
```
|
||
|
||
## 5) Деплой (прошивка) — стандарт
|
||
|
||
Главный скрипт:
|
||
|
||
```bash
|
||
cd ESP32-S3-Touch-AMOLED-2.16/main-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
|