Отладка ESP32‑S3 через JTAG и исправление ошибок libusb

Windows: Золотой стандарт, WinUSB через Zadig

На Windows стандартный драйвер ftdibus․sys или usbser․sys захватывает интерфейс‚ не давая libusb (WinUSB бэкенду) его открыть․

1. Скачайте Zadig (zadig․akeo․ie)․
2. Меню Options → List All Devices․
3. Найдите ваш JTAG-адаптер или ESP32-S3 USB JTAG/serial․
4. Критически важно: Устройств с одинаковым именем может быть несколько (Interface 0‚ Interface 1)․ Для JTAG нужен именно тот интерфейс‚ который выглядит как JTAG или имеет соответствующий PID․ Обычно для FT2232H: Interface A (JTAG) и Interface B (UART)․ Выбирайте Interface A․
5. Справа выбирайте WinUSB (v6;x․x․x) (не libusbK‚ не libusb-win32)․
6. Нажмите Replace Driver․
7. Повторите для второго интерфейса (UART)‚ если хотите пользоваться монитором порта параллельно․

Специфика ESP32-S3: Встроенный USB JTAG (Native)

ESP32-S3 имеет встроенный PHY USB․ Это значит‚ что внешний JTAG-адаптер не нужен — можно отлаживаться по тому же кабелю‚ что и прошивка․ Но это источник уникальных проблем с libusb_open․

Проблема: «Прыгающий» PID/VID

ESP32-S3 меняет свои USB-дескрипторы в зависимости от режима:

• Режим приложения (App): Может быть CDC (COM-порт)‚ MSC (флешка)‚ HID‚ или вообще без USB (если приложение не инициализировал USB стек)․
• Режим загрузчика (Bootloader / DFU): VID:PID = 303A:0002 (или 1001 для JTAG в новых ревизиях)․
• Режим отладки (OpenOCD запущен): Чип переключает USB-интерфейс в режим JTAG․

Ошибка libusb_open: not found при старте OpenOCD часто означает: «Чип сейчас в режиме приложения‚ и интерфейса JTAG не существует»․

Ритуал входа в режим отладки (Расклад «Кельтский крест»):

1. Зажмите BOOT (GPIO0)․
2. Нажмите и отпустите EN (RST)․
3. Отпустите BOOT․
4. Теперь чип в режиме загрузчика․ lsusb должен показать 303a:1001 (или 0002)․
5. Только теперь запускайте openocd -f board/esp32s3-builtin․cfg․

Конфиг OpenOCD для встроенного JTAG (esp32s3-builtin․cfg):

# Используйте актуальный конфиг из поставки OpenOCD для ESP32 (v0․12․0+)
source [find interface/ftdi/esp32_devkitj_v1․cfg] # НЕ для встроенного!

adapter driver usb_blaster # Нет‚ это для Altera․

adapter driver usb_blaster # ОШИБКА В СТАРЫХ ГАЙДАХ!

interface usb_blaster # Нет․

Важно: Используйте OpenOCD из поставки ESP-IDF (папка tools/openocd-esp32)‚ а не системный apt install openocd․ Системный не умеет работать с встроенным USB JTAG ESP32-S3․

Конфликты: Когда два процесса хотят одного (Карта «Два Меча»)

Самая частая причина LIBUSB_ERROR_BUSY — конфликт доступа․

Сценарий А: VS Code / PlatformIO + OpenOCD + Serial Monitor

• Проблема: Отладчик (Cortex-Debug / PlatformIO) запускает OpenOCD․ Параллельно вы открываете Serial Monitor (или idf․py monitor)․ Оба пытаются открыть USB-устройство․
• Решение: Настройте launch․json (Cortex-Debug) на использование SWO / RTT для логов‚ либо используйте esp-idf-monitor с флагом --no-reset и убедитесь‚ что OpenOCD не захватывает UART-интерфейс (Interface 1 у FTDI / CDC у нативного USB)․
• Для нативного USB: OpenOCD захватывает Interface 0 (JTAG)․ Serial Monitor должен использовать Interface 1 (CDC)․ Если у вас в menuconfig отключен USB CDC в приложении — монитор не заработает во время отладки․

Сценарий Б: Модем-менеджер (ModemManager) в Linux

ModemManager видит USB CDC устройство (ESP32 выглядит как модем) и пытается его опросить‚ ломая прошивку и отладку․

# Запретим ModemManager трогать Espressif устройства
echo 'ATTR{idVendor}=="303a"‚ ENV{ID_MM_DEVICE_IGNORE}="1"' | sudo tee /etc/udev/rules․d/99-modemmanager-esp32․rules
sudo udevadm control --reload-rules && sudo udevadm trigger

sudo systemctl disable --now ModemManager

LIBUSB_DEBUG=4 openocd -f board/esp32s3-builtin․cfg 2>&1 | tee openocd․log

/: Bus 01․Port 1: Dev 1‚ Class=root_hub‚ Driver=xhci_hcd/12p‚ 480M
 |__ Port 2: Dev 5‚ If 0‚ Class=Vendor Specific Class‚ Driver=usbfs‚ 12M <-- ХОРОШО (JTAG)
 |__ Port 2: Dev 5‚ If 1‚ Class=CDC Data‚ Driver=cdc_acm‚ 12M <-- UART (для монитора)