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 без служебных заголовков и перекодирования.
На неподключённой плате измерение реальной скорости и проверка проводов
не выполняются; это отдельная аппаратная проверка.