80 lines
13 KiB
Python
80 lines
13 KiB
Python
"""Тонкий ctypes-порт общего C-кодека и конвейера WinUSB для USART G474.""" # Хранит протокол исключительно в c/uart-usb, без алгоритмического fallback.
|
|
import ctypes as ct # Связывает Python с единым стабильным ABI C99.
|
|
import importlib.util # Находит каталог установленного SETGUI без создания его главного окна.
|
|
import os # Читает явно заданный путь UART_USB_LIBRARY для исходников и тестов.
|
|
from pathlib import Path # Одинаково разрешает пути исходного и установленного приложения.
|
|
from dataclasses import dataclass # Передаёт UI готовые смысловые поля вместо wire-структуры.
|
|
class Frame(ct.Structure): # Повторяет только ABI структуры C, а не алгоритм разбора USB.
|
|
_fields_ = [('type', ct.c_uint8), ('channel', ct.c_uint8), ('length', ct.c_uint16), ('data', ct.c_uint8 * 60)] # Размер payload и естественное выравнивание совпадают с uart_usb.h.
|
|
class Parser(ct.Structure): # Владеет памятью состояния общего потокового parser.
|
|
_fields_ = [('bytes', ct.c_uint8 * 64), ('used', ct.c_uint16)] # C хранит до одной записи, включая незавершённый заголовок.
|
|
class CEvent(ct.Structure): # Описывает смысловой ABI ответа без packed-полей или платформенных enum.
|
|
_fields_ = [(name, ct.c_uint32) for name in ('kind', 'channel', 'length', 'command', 'status', 'channels', 'tx_channel', 'lost', 'errors')] + [('data', ct.c_uint8 * 60)] # Все числовые поля C имеют фиксированные 32 бита.
|
|
@dataclass(frozen=True) # Делает событие неизменяемым при передаче из worker в GUI.
|
|
class Event: # Содержит только проверенные C-ядром значения протокола.
|
|
kind: int # Значения ABI: 1 — RX, 2 — ACK, 3 — статистика.
|
|
channel: int # Указывает логический канал 1…4 либо общий канал 0.
|
|
data: bytes # Содержит полезные бинарные байты RX без служебных полей.
|
|
command: int # Идентифицирует команду, к которой относится ACK.
|
|
status: int # Возвращает результат: 0 — успех, 1 — неверные параметры, 2 — занято.
|
|
channels: int # Объявляет фактическое количество включённых приёмников прошивки.
|
|
tx_channel: int # Показывает единственный разрешённый канал передачи.
|
|
lost: int # Считает отброшенные прошивкой байты при перегрузке USB.
|
|
errors: int # Считает замеченные аппаратные события USART и DMA.
|
|
class Native: # Предоставляет высокоуровневые команды и события поверх одного C-кодека.
|
|
def __init__(self, library=None): # Позволяет тесту явно выбрать проверяемую DLL без изменения окружения приложения.
|
|
candidates = [Path(library)] if library else [] # Предпочитает явно выбранную библиотеку нужной архитектуры.
|
|
if not library and os.environ.get('UART_USB_LIBRARY'): candidates.append(Path(os.environ['UART_USB_LIBRARY'])) # Поддерживает отдельный путь исходной сборки.
|
|
candidates.append(Path(__file__).with_suffix('.dll')) # Поддерживает самостоятельную установку библиотеки set_devices.
|
|
spec = importlib.util.find_spec('gui_desktop') # Находит штатный пакет GUI без импорта его Qt-панелей.
|
|
if spec and spec.origin: candidates.append(Path(spec.origin).parent / 'native' / 'uart_usb.dll') # Использует стандартный каталог нативных библиотек SETGUI.
|
|
path = next((item for item in candidates if item.is_file()), None) # Не загружает случайную DLL из текущего каталога процесса.
|
|
if path is None: raise RuntimeError('Не найдена uart_usb.dll. Соберите c/uart-usb/ports/windows и установите DLL в gui_desktop/native.') # Ошибка установки не подменяет C-кодек реализацией Python.
|
|
self.lib = ct.CDLL(str(path)) # Загружает C ABI cdecl, одинаково объявленный для x86 и x64.
|
|
ptr = ct.POINTER(ct.c_uint8) # Задаёт тип указателя на бинарные массивы общего API.
|
|
signatures = {'ub_feed': ([ct.POINTER(Parser), ptr, ct.c_uint16, ct.POINTER(Frame)], ct.c_uint16), 'ub_describe': ([ct.POINTER(Frame), ct.POINTER(CEvent)], ct.c_int), 'ub_make_config': ([ct.c_uint8, ct.c_uint32, ptr], ct.c_uint16), 'ub_make_start': ([ptr], ct.c_uint16), 'ub_make_stop': ([ptr], ct.c_uint16), 'ub_make_tx': ([ptr, ct.c_uint16, ptr], ct.c_uint16), 'ub_usb_paths': ([ct.c_wchar_p, ct.c_uint32], ct.c_int), 'ub_usb_open': ([ct.c_wchar_p], ct.c_void_p), 'ub_usb_close': ([ct.c_void_p], None), 'ub_usb_read': ([ct.c_void_p, ptr, ct.c_uint32], ct.c_int), 'ub_usb_write': ([ct.c_void_p, ptr, ct.c_uint32], ct.c_int)} # Описывает только типы ABI, оставляя все wire-операции в C.
|
|
for name, (args, result) in signatures.items(): # Явные сигнатуры предотвращают обрезание 64-битных handles ctypes.
|
|
function = getattr(self.lib, name); function.argtypes = args; function.restype = result # Проверяет наличие всех экспортов при открытии терминала.
|
|
self.parser = Parser() # Каждое подключение получает независимое состояние разбора USB-потока.
|
|
def make(self, name, channel=0, baud=0, data=b''): # Создаёт целую команду общим C builder без знания её байтового заголовка.
|
|
if name == 'tx' and not 1 <= len(data) <= 60: raise ValueError('Один пакет TX должен содержать 1…60 байт') # Проверяет границу ABI до преобразования Python длины в uint16.
|
|
out = (ct.c_uint8 * 64)() # Выделяет максимальный выходной буфер публичного ABI.
|
|
if name == 'config': size = self.lib.ub_make_config(channel, baud, out) # Передаёт выбранную скорость в битах в секунду C-кодеку.
|
|
elif name == 'start': size = self.lib.ub_make_start(out) # Вызывает общий builder запуска всех каналов.
|
|
elif name == 'stop': size = self.lib.ub_make_stop(out) # Вызывает общий builder остановки всех каналов.
|
|
elif name == 'tx': size = self.lib.ub_make_tx((ct.c_uint8 * len(data)).from_buffer_copy(data), len(data), out) # Передаёт полезные байты, а выбор единственного TX выполняет C.
|
|
else: raise ValueError('Неизвестная команда USART-моста') # Не допускает скрытого построения произвольного wire-пакета в GUI.
|
|
if not size: raise ValueError('Неверные параметры команды USART-моста') # Не отправляет отвергнутую C builder команду.
|
|
return bytes(out[:size]) # Возвращает точное готовое представление для WinUSB WritePipe.
|
|
def feed(self, data): # Передаёт произвольные фрагменты USB в общее C-состояние parser.
|
|
result, offset = [], 0 # Накапливает несколько записей одного блока конвейера WinUSB.
|
|
while offset < len(data): # Продолжает разбор до потребления всех байтов драйвера.
|
|
fragment = data[offset:offset + 65535] # Ограничивает длину одним uint16, как требует публичный ABI C.
|
|
buffer = (ct.c_uint8 * len(fragment)).from_buffer_copy(fragment) # Даёт C непрерывную память входного фрагмента.
|
|
frame, event = Frame(), CEvent() # Выделяет независимые структуры результата для одного сообщения.
|
|
consumed = self.lib.ub_feed(ct.byref(self.parser), buffer, len(fragment), ct.byref(frame)) # Все границы, синхронизацию и длины проверяет общий C parser.
|
|
if not consumed: raise RuntimeError('C parser не потребил входные данные') # Не допускает бесконечный цикл при несовместимой DLL.
|
|
offset += consumed # Продолжает с остатка, который C ещё не прочитал.
|
|
if frame.type and self.lib.ub_describe(ct.byref(frame), ct.byref(event)): # Получает только семантически корректные ответы прошивки.
|
|
result.append(Event(event.kind, event.channel, bytes(event.data[:event.length]), event.command, event.status, event.channels, event.tx_channel, event.lost, event.errors)) # Преобразует готовую C-модель без чтения смещений wire-payload.
|
|
return result # Возвращает события для журнала, отображения и автомата подтверждения команд.
|
|
def paths(self): # Перечисляет отдельные USB USART-интерфейсы G474 без открытия CAN.
|
|
out = ct.create_unicode_buffer(32768) # Вмещает несколько полных системных путей устройств Windows.
|
|
size = self.lib.ub_usb_paths(out, len(out)) # Передаёт системное перечисление нативному Windows-порту.
|
|
if size < 0: raise RuntimeError('Не удалось перечислить WinUSB USART-интерфейсы') # Отличает системную ошибку от корректного пустого списка.
|
|
return [item for item in out[:size].split('\0') if item] # Преобразует системный MULTI_SZ, который не является wire-протоколом устройства.
|
|
class Usb: # Владеет одним непрозрачным WinUSB handle в рабочем потоке.
|
|
def __init__(self, native, path): # Открывает выбранный интерфейс после явного действия пользователя.
|
|
self.native, self.handle = native, native.lib.ub_usb_open(path) # C проверяет bInterfaceNumber, подкласс и версию до обмена.
|
|
if not self.handle: raise RuntimeError('Не удалось открыть USART USB. Проверьте прошивку G474, WinUSB и доступ к интерфейсу 2.') # Объясняет отличие старой CAN-прошивки от нового моста.
|
|
def write(self, data): # Передаёт уже готовую C-команду без изменения её байтов.
|
|
buffer = (ct.c_uint8 * len(data)).from_buffer_copy(data) # Сохраняет буфер до завершения синхронного ограниченного OUT.
|
|
if self.native.lib.ub_usb_write(self.handle, buffer, len(data)) != len(data): raise RuntimeError('Ошибка записи USB USART') # Неполная запись никогда не считается подтверждённой командой.
|
|
def read(self): # Получает сразу несколько готовых пакетов без задержки очереди аппаратных RX.
|
|
buffer = (ct.c_uint8 * 4096)() # Снижает число переходов ctypes, собирая до 4 КиБ готовых USB-пакетов.
|
|
size = self.native.lib.ub_usb_read(self.handle, buffer, len(buffer)) # В C постоянно ожидают шестнадцать независимых запросов IN.
|
|
if size < 0: raise RuntimeError('USB USART отключён или чтение завершилось ошибкой: ' + str(size)) # Прекращает worker при физическом отключении устройства.
|
|
return bytes(buffer[:size]) # Пустой блок означает таймаут 50 мс и позволяет обработать STOP либо TX.
|
|
def close(self): # Останавливает все pending I/O до уничтожения Python объекта.
|
|
if self.handle: self.native.lib.ub_usb_close(self.handle); self.handle = None # Повторное закрытие безопасно и не освобождает чужой CAN handle.
|