# 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 заводской прошивки
- `test-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/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