esp32s3-diag

«Рентген платы» — ESP-IDF прошивка ESP32-S3 для диагностики USB Host: enum, дескрипторы, endpoints, control/bulk transfers, FTDI vendor init, SHPROTO handshake.

Web UI: http://esp32s3-diag.local/

⚠ ПЕРЕД НАЧАЛОМ ЭКСПЕРИМЕНТОВ — ОБЯЗАТЕЛЬНО

Сохранить настройки спектрометра. Диагностика шлёт на прибор реальные USB-transfers (control-transfer, FTDI vendor requests SIO_RESET/SET_BAUDRATE/SET_DATA/SET_FLOW, SHPROTO кадры). Побочный эффект — сброс/перезапись параметров, потеря пользовательских калибровок, конфига, режимов. Восстановить их без сохранённой резервной копии нельзя.

Порядок:

1. Подключить спектрометр к штатному ПО.
2. Выгрузить полный backup настроек (все меню: калибровка, energy scale, mode, thresholds, waterfall config).
3. Убедиться что backup читаемый (открыть на другой машине или сверить размер/хеш).
4. Только после этого — подключать прибор к esp32s3-diag.

Disclaimer

Тесты выполняются на свой страх и риск. Автор ответственности не несёт.

Возможные последствия (неполный список):

• порча/сброс пользовательских настроек спектрометра;
• потеря калибровок;
• некорректные baud/parity/flow → зависание USB-моста прибора;
• износ flash прибора от повторных vendor-запросов;
• временная или постоянная неработоспособность USB-канала прибора.

Запуск любого теста (probe, control-transfer, bulk-out, bulk-in) означает согласие с этими условиями. Если не согласны — не запускайте.

После диагностики — вернуть штатную прошивку

Диагностика прошивает плату своей прошивкой поверх штатной (те же offsets 0x0 / 0x8000 / 0x10000). После теста залейте обратно рабочую прошивку прибора её штатным флешером — штатная прошивка перезапишет диаг полностью, отдельного стирания не нужно (для AtomSpectra-водопада — flasher соответствующего проекта).

Настройки самого спектрометра это не восстановит: диаг слал прибору реальные USB-запросы (FTDI vendor init, SHPROTO), которые могли сбросить его калибровки. Вернуть их можно только из backup, снятого ДО теста (см. предупреждение выше).

Быстрый старт

1. Сборка (Docker, ESP-IDF v5.4)

cd esp32s3-diag
$env:MSYS_NO_PATHCONV=1
docker run --rm -v "$(pwd -W):/p" -w /p espressif/idf:v5.4 bash -c "idf.py build"

Бинарь: build/esp32s3_diag.bin.

2. Прошивка

Определить COM-порт (CH343, не COM5 = SoundBlaster):

Get-CimInstance Win32_PnPEntity | Where { $_.Name -match 'CH340|CH343|CP210|FTDI' }

Прошить (пример COM14):

python -m esptool --chip esp32s3 -p COM14 -b 460800 --before default_reset --after hard_reset write_flash --flash_mode dio --flash_size 16MB --flash_freq 80m 0x0 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin 0x10000 build/esp32s3_diag.bin

3. Первый запуск — WiFi (новая плата)

Новая или свежепрошитая плата WiFi не знает — её надо один раз подключить к сети. Плата сама поднимает точку доступа esp32s3-diag-Setup (192.168.4.1):

• Подключиться телефоном/ПК к этой AP.
• Открыть captive portal (если не открылся — http://192.168.4.1/) → ввести SSID/пароль.
• Плата перезагрузится и подключится к основной сети. Дальше IP находится сам при каждом запуске — повторять не нужно.

Сеть — только 2.4 ГГц (ESP32-S3 не умеет 5 ГГц).

Если NVS уже прошит (штатно — через scripts/nvs_wifi.example.csv, скопировать в scripts/nvs_wifi.csv и вписать свои SSID/пароль — файл в .gitignore):

cd esp32s3-diag
python -m esptool --chip esp32s3 -p COM14 write_flash 0x9000 build/nvs_wifi.bin

4. Web UI

http://esp32s3-diag.local/

Вкладки: Диагностика (6 этапов) · Шина (USB Host) · Спектрометр (probe FSM) · Система · Лог · Control-Transfer.

5. Диагностика прибора

1. Подключить спектрометр по USB к плате esp32s3-diag.
2. В браузере → вкладка Диагностика → дождаться зелёного Enum + Detect.
3. Вкладка Спектрометр → кнопка Старт → probe запустит FTDI init + SHPROTO -inf sweep по baudам.
4. После теста → кнопка Скачать полный отчёт (JSON с system/usb/probe/лог) → приложить к обращению за диагнозом.

Опознание «не того чипа». Если прибор не определяется — вкладка Диагностика различает три случая по сырым VID:PID:

• enum_events = 0 → шина физически пуста (VBUS / кабель / mux на USB0 вместо USB1);
• enum_events > 0, но список устройств пуст, а показан last_enum VID:PID → устройство поднялось, но не открылось: сверьте VID:PID — не тот конвертер (чужой чип) либо отвал питания на open;
• растущий detach (dev_gone_events) → прибор мелькает и отваливается (слабое питание USB Host).

6. Ручные bulk/control transfers (расширенный режим)

Пример — отправить SHPROTO кадр -inf вручную (FTDI addr=1, bulk-out EP=0x02):

curl -X POST http://esp32s3-diag.local/api/bulk-out \
  -H "Content-Type: application/json" \
  -d '{"addr":1,"ep":2,"data":[1,3,6,0,45,105,110,102,13,10],"timeout":500}'

Прочитать ответ (bulk-in EP=0x81, 64 байта):

curl "http://esp32s3-diag.local/api/bulk-in?addr=1&ep=0x81&len=64&timeout=1000"

Endpoints (для справки)

Метод	URL	Назначение
GET	/api/system	форензик MCU
GET	/api/usb	снапшот USB Host (вкл. last_enum_vid/pid/class, dev_gone_events)
GET	/api/probe/status	статус FSM probe
POST	/api/probe/start	запуск probe (FTDI init + SHPROTO -inf)
POST	/api/probe/stop	остановка
POST	/api/control-transfer	ручной control transfer
POST	/api/bulk-out	ручной bulk-out
GET	/api/bulk-in	ручной bulk-in
GET	/api/log	инкрементальный лог
GET	/api/log/download	скачать весь лог
GET	/api/report	скачать полный отчёт (system+usb+probe+tasks+log)

Готовый flasher (без сборки)

Не хочется собирать — возьмите esp32s3-diag-flasher.exe из Releases: выбор COM-порта → прошивка → автопоиск IP платы → браузер открывается сам.

Пошаговая инструкция со скриншотами: docs/usage-walkthrough.md.

Документация

• docs/usage-walkthrough.md — пошаговая инструкция с экранами (flasher → web UI → отчёт).
• references/diagnostic-flow.md — 6 этапов диагностики с зелёными/красными критериями.
• references/known-devices/README.md — реестр эталонов USB-устройств.