Files
templates/c/uart-usb

USART → USB

Минимальный двоичный мультиплексор 2–4 UART-каналов в USB: независимый RX, TX только на канале 1, настройка скорости, подтверждения и диагностика потерь. Переносимое ядро C99 не содержит HAL, ОС, heap и глобального состояния.

Слои: SETGUI → Python/Qt порт → C-кодек / WinUSB → USB bulk → C-кодек → STM32G474 DMA → USART. Применяется в CAN_projects, ветка candle-g474.

Файл Назначение Зависимость
uart_usb.h, uart_usb.c Формат, потоковый parser, builders, смысловые события ABI C99, stdint, string
ports/stm32g474/uart_usb_g474.* Кольцевой RX DMA, один TX DMA CMSIS STM32G474
ports/windows/uart_usb_winusb.c 16 запросов IN одновременно, SetupDi, WinUSB Windows 7+, WinUSB, SetupAPI
python/set_devices/uart_usb.py ctypes, жизненный цикл USB handle Python stdlib, собранная DLL
python/set_devices/qt_ports/uart_usb_terminal.py Worker, четыре окна, запись исходных байтов Qt5/Qt6

Аппаратный порт STM32G474VET6

Канал Блок RX TX DMAMUX RX
1 USART2 PA3, AF7 PA2, AF7 26
2 USART3 PB11, AF7 выключен 28
3 UART4 PC11, AF5 выключен 30
4 UART5 PD2, AF5 выключен 32

USART1 PA9/PA10 остаётся загрузчику. CAN PB8/PB9 и USB PA11/PA12 сохраняются. Выводы сверены с таблицами alternate function STM32G474xE, DMA — с RM0440. Используйте логические уровни платы и общую GND; внешний RS232/RS485 требует соответствующего трансивера.

UART_USB_CHANNELS=2, 3 или 4 задаётся сборкой, по умолчанию 4. DMA1 Channel1…4 обслуживают RX, Channel5 — USART2 TX. PCLK1=144 МГц, 8N1, oversampling 16, диапазон 1200…6000000 бит/с, погрешность BRR до 2%. По умолчанию каждый вход работает на 1000000 бит/с. Одновременные четыре входа по 1 Мбит/с дают 400000 байт/с полезных данных. USB FS имеет общую пропускную способность для всех USART и CAN; предел каждого отдельного UART не является гарантией суммарной скорости USB.

Каждый вход имеет DMA-кольцо 4096 байт; при отставании потребителя сохраняется новейшая половина кольца и точно увеличивается счётчик программно потерянных байтов. Вторая половина оставляет запас от перезаписи во время копирования. Аппаратные ORE/FE/NE/PE и TE считаются событиями; число утраченных до DMA байтов при ORE аппаратурой не сообщается. Счётчики uint32 сбрасываются при START и переполняются по модулю 2^32. STOP, USB reset и suspend прекращают захват; оставшийся в DMA хвост не гарантирован после STOP. Resume требует нового START.

Контракт порта

ub_g474_init(), ub_g474_config(channel, baud), ub_g474_start(), ub_g474_stop(), ub_g474_tx(data, length), ub_g474_read(channel, out, capacity), ub_g474_stats(channel, &lost, &errors) и ub_g474_abort() вызываются одним основным циклом с защитой от USB reset. Только обработчики DMA меняют счётчики оборотов. Порт использует статическую память и не вызывает пользовательские callbacks. UB_BUSY гарантирует отсутствие побочного действия команды.

Протокол версии 1

USB interface 2: class FF, subclass 55, protocol 01, bulk IN 83, bulk OUT 03, max packet 64. CAN и DFU сохраняют номера 0 и 1. Windows получает WinUSB через Microsoft OS 1.0. USART использует отдельный GUID {8a650f40-8fb3-49b5-a067-5b2494740001}, чтобы CAN-клиенты gs_usb не считали новый интерфейс ещё одним CAN-адаптером. Ревизия USB bcdDevice=0x0001 обновляет кэш состава интерфейсов Windows после прошивки; переподключите кабель USB.

Запись: A7 | (type << 4) OR channel | length_lo | length_hi | payload. Payload 0…60 байт, длина little-endian. Данные не экранируются; целостность обеспечивает USB CRC и повтор транзакций. Parser допускает произвольные разрывы и несколько записей в одном системном чтении. Повреждённый заголовок пропускается до следующей синхронизации.

type Направление channel payload
1 CONFIG host → MCU 1…N baud uint32 LE, только до START
2 START host → MCU 0 пусто; запускает все входы и обнуляет счётчики
3 STOP host → MCU 0 пусто; BUSY до окончания стопового бита TX
4 TX host → MCU 1 1…60 исходных байтов
8 ACK MCU → host как в команде command, status, rx_channels, tx_channel; четыре uint8
9 RX MCU → host 1…N 1…60 исходных байтов
10 STATS MCU → host 1…N lost uint32 LE, errors uint32 LE; раз в секунду

Статусы: 0 OK, 1 INVALID, 2 BUSY. Одновременно ожидается один ACK. Хост повторяет только явно отклонённые BUSY команды. После потери ACK не повторяет TX: отключает сессию, исключая неопределённое дублирование байтов. ACK TX означает принятие в DMA. STOP подтверждается после физического завершения TX.

Быстрый старт в C после открытия собственного USB IN:

#include "uart_usb.h" /* Подключает общую структуру записи и parser. */
ub_parser parser = {0}; /* Выделяет независимое состояние одного USB-потока. */
ub_frame frame; /* Принимает один проверенный заголовок и его payload. */
ub_event event; /* Возвращает смысловые поля без ручного разбора смещений. */
uint8_t out[64]; /* Вмещает максимальную команду USB FS. */
uint16_t size = ub_make_config(1, 1000000, out); /* Настраивает RX1 на 1 Мбит/с. */
usb_write(out, size); /* Порт приложения передаёт команду выбранному интерфейсу. */
uint16_t used = ub_feed(&parser, incoming, received, &frame); /* Parser потребляет очередной фрагмент USB. */
if (frame.type && ub_describe(&frame, &event)) { /* Обрабатывает только целый корректный ответ. */
    handle_event(&event); /* Приложение получает уже разобранную модель события. */
} /* Остаток incoming после used снова передаётся ub_feed. */

Сборка DLL и проверки

Соберите cmake -S templates/c/uart-usb -B build/uart-usb -A x64, затем cmake --build build/uart-usb --config Release. Для Win32 используйте отдельный каталог и -A Win32. DLL должна совпадать по разрядности с Python/SETGUI. Установите uart_usb.dll в src/gui_desktop/native, рядом с модулем Python либо задайте UART_USB_LIBRARY. Отсутствие DLL является явной ошибкой установки.

Проверки: python -m pytest templates/c/uart-usb/tests -q при настроенных PYTHONPATH=templates/python и UART_USB_LIBRARY=<полный путь DLL>. Эталоны включают все 65 разрывов максимальной записи, шум, неправильные длины, 1000 сообщений в случайных фрагментах и несовместимые ACK.

Терминал обновляет только последние 8 КиБ каждого RX. Для полного захвата выберите «Запись RX…» до START: worker создаст отдельную папку сессии и rx1.bin…rx4.bin без служебных заголовков и перекодирования. На неподключённой плате измерение реальной скорости и проверка проводов не выполняются; это отдельная аппаратная проверка.