docs: добавь поясняющие комментарии к модулям и инструментам

python/set_devices/__init__.py

@@ -1 +1,5 @@
+# Входная точка пакета set_devices. Определяет доступные при импорте имена; подробные
+# контракты находятся в специализированных модулях пакета. Изменение реэкспортов влияет на
+# существующие import у потребителей.
+
 """Reusable device libraries from setcorp/templates."""

python/set_devices/balsam_can.py

@@ -1,3 +1,7 @@
+# Исторический регистровый CAN-протокол BALZAM/TMS2812. Формат идентификаторов и порядок слов
+# относятся именно к этому профилю; общий физический CAN не делает его совместимым с SET v2
+# или протоколом ПМ35.
+
 """GUI-neutral adapter for the shared templates Balsam 167 CAN decoder."""
 
 from __future__ import annotations

python/set_devices/bus_demo.py

@@ -1,3 +1,7 @@
+# Демонстрационная модель шины и устройств для интерфейса без оборудования. Синтетические
+# ответы служат проверке пользовательского сценария; они не являются измерениями физической
+# линии.
+
 """@file bus_demo.py
 @brief Генератор трафика полевой шины: разбор проверяется без железа.
 

python/set_devices/can485_board.py

@@ -1,3 +1,7 @@
+# Команды и кадры USB-моста CAN485 DevBoard_V1. Преобразование между представлением адаптера и
+# CAN отделено от последовательного порта, чтобы один контракт использовался в GUI и проверках
+# без устройства.
+
 """@file can485_board.py
 @brief Плата WeAct CAN485 DevBoard V1 (ESP32): её текстовый вывод и пакеты RS485.
 

python/set_devices/can_bridge.py

@@ -1,3 +1,7 @@
+# Клиентская логика CAN-моста, связывающая команды приложения и кадры адаптера. Транспортная
+# оболочка отделена от прикладного протокола устройства, поэтому один мост может обслуживать
+# разные профили.
+
 """Служебный уровень моста CAN <-> RS485: его кадры и его регистры.
 
 Мост пересылает кадры шины прозрачно, но два вида трафика принадлежат

python/set_devices/can_log_trends.py

@@ -1,3 +1,6 @@
+# Импорт журнала CAN485 в ограниченные по объёму кривые. Каждый канал сохраняет собственные
+# временные метки: пропуск сообщения на одном канале не должен искусственно сдвигать другой.
+
 """Convert ESP CAN485 logs into bounded, independently timestamped curves."""
 from __future__ import annotations
 

python/set_devices/can_ping.py

@@ -1,3 +1,7 @@
+# Адресный PING SETProtocol v2 через сегментированный classic CAN. Ответ сопоставляется с
+# ожидаемым обменом; успешная отправка CAN-пакета ещё не подтверждает доступность прикладного
+# сервиса.
+
 """Addressed SETProtocol v2 PING exchange over segmented classic CAN."""
 
 from __future__ import annotations

python/set_devices/can_transport.py

@@ -1,4 +1,8 @@
 # -*- coding: utf-8 -*-
+# Потоковый транспорт моста CAN/RS485 с сигнатурой AA 55 и CRC16. Приём может доставлять
+# произвольные фрагменты; parser сохраняет незавершённый кадр и отделяет CAN-идентификатор от
+# служебных флагов моста.
+
 """Транспортный кадр моста CAN <-> RS485.
 
 Это не протокол SETGUI (``A5 5A``) из ``protocol.py``, а кадр полевого

python/set_devices/ds18b20.py

@@ -1,3 +1,7 @@
+# Работа с термометрами DS18B20: поиск по ROM, запуск преобразования, чтение температуры и
+# настройка scratchpad. ROM является адресом устройства на общей шине; результат чтения нельзя
+# считать действительным до проверки статуса обмена и CRC.
+
 """@file ds18b20.py
 @brief Модель и кодеки датчиков DS18B20 на шине 1-Wire STM32F103C8T6.
 

python/set_devices/eeprom.py

@@ -1,3 +1,7 @@
+# Клиентские структуры каталога EEPROM датчиков DS18B20 и экспорт данных. ROM датчика и
+# назначенная позиция имеют разный смысл; проверка конфликтов позиций нужна до сохранения
+# конфигурации.
+
 """Каталог «датчик — позиция» во внешней EEPROM прибора DS18B20."""
 
 from __future__ import annotations

python/set_devices/firmware.py

@@ -1,3 +1,7 @@
+# Клиентское представление образа и подготовки передачи прошивки. Парсинг и проверки образа
+# отделены от физического программатора; этап передачи использует уже проверенные данные и
+# метаданные.
+
 """@file firmware.py
 @brief Проверка образов и переносимая машина блочной передачи прошивки.
 

python/set_devices/gas_catalog.py

@@ -1,3 +1,7 @@
+# Описание объектов общего адресного пространства и подписок на значения. Каталог задаёт
+# адреса, типы и имена, а пакеты наблюдения несут текущие данные; сборка частей каталога
+# должна завершиться до использования всей схемы.
+
 """Каталог общего адресного пространства и поток выбранных значений.
 
 Прибор объявляет, какие регистры у него есть и как они называются, GUI

python/set_devices/gas_logger.py

@@ -1,3 +1,7 @@
+# Клиент согласованных снимков GAS-регистратора и проверка карты сигналов. Скачивание
+# выполняется в рабочем потоке транспорта; записи с истёкшим ожиданием нельзя автоматически
+# повторять, поскольку устройство уже могло применить команду.
+
 """Experimental GAS recorder map and transport-independent snapshot client.
 
 read(address, count) -> words; write(address, value) must await a confirmed
@@ -84,7 +88,13 @@ def schema_id(mapping):
 def c_header(mapping):
     """Generate the checked-in C mirror; --check in CI catches drift."""
     validate_map(mapping)
-    lines = ['/* Generated from pm35.json. Do not edit. */',
+    lines = ['/*\n'
+             ' * Связь регистратора ПМ35 с картой доступных сигналов. Адреса сигналов согласуются с\n'
+             ' * JSON-картой клиента; изменение только одной стороны приводит к неверной интерпретации снимка\n'
+             ' * даже при успешном обмене.\n'
+             ' */\n'
+             '\n'
+             '/* Generated from pm35.json. Do not edit. */',
              '#ifndef GL_PM35_MAP_H', '#define GL_PM35_MAP_H', '#include "gas_logger.h"',
              'static const gl_channel gl_pm35_channels[] = {']
     for c in mapping['channels']:

python/set_devices/generator_data.py

@@ -1,3 +1,7 @@
+# Подготовка точек генератора из встроенных форм, рецептов и CSV. Частота выборок и
+# длительность таблицы согласуются с возможностями устройства; импортированные каналы проходят
+# явный выбор и ресемплинг.
+
 """Built-in waveforms and CSV input for the point-based signal generator."""
 import csv
 import io

python/set_devices/models.py

@@ -1,3 +1,7 @@
+# Модели дискретных и числовых сигналов, каталога и снимка состояния. Эти структуры не зависят
+# от GUI и контроллера; демонстрационный источник позволяет заполнять их для проверки
+# отображения.
+
 """Модель нейтральных сигналов для шаблона без привязки к ТЗ."""
 
 from __future__ import annotations

python/set_devices/panel.py

@@ -1,3 +1,7 @@
+# Клиентский протокол удалённого меню: нажатия клавиш, запрос экрана и состояние строк. Ответ
+# прибора описывает экран, а не пиксели дисплея; mock-модель воспроизводит взаимодействие без
+# реальной платы.
+
 """@file panel.py
 @brief Зеркало экрана прибора и кнопки его панели.
 

python/set_devices/plot_formula.py

@@ -1,3 +1,7 @@
+# Кусочно-полиномиальное описание кривых для математических подписей графика. Коэффициенты
+# должны описывать именно отображаемую реконструкцию, включая преобразование нормированных
+# координат обратно в единицы осей.
+
 """Local polynomial representation of the curves actually drawn on a plot."""
 from dataclasses import dataclass
 import math

python/set_devices/plot_processing.py

@@ -1,3 +1,7 @@
+# Контракт обработки снимков графика: входные ряды, запрос расчёта и результирующие кривые.
+# Вычисленные данные отделены от исходных измерений; численная обработка делегируется общему
+# ядру C99.
+
 """Renderer-independent processing contract. Numerical work stays in C99.
 
 Adapters publish immutable snapshots in the displayed units. Calculated curves

python/set_devices/protocol.py

@@ -1,3 +1,7 @@
+# Кадрирование исторического GUI protocol v1. Parser накапливает части входного потока и
+# проверяет сообщение до выдачи результата; этот формат следует выбирать по профилю
+# соединения, а не только по сигнатуре.
+
 """Совместимое с ``lib/gui_transport`` кадрирование GUI protocol v1."""
 
 from __future__ import annotations

python/set_devices/protocol_capture.py

@@ -1,3 +1,7 @@
+# Ограниченная запись наблюдаемого на хосте трафика и экспорт синтетического логического
+# захвата. Время событий отражает наблюдение программой, а не аппаратные фронты;
+# перекрывающиеся пакеты одной линии сериализуются.
+
 """Bounded host traffic recording and synthetic DSView v3 logic captures.
 
 No hardware timing is inferred: timestamps are host observations and overlapping

python/set_devices/protocol_router.py

@@ -1,3 +1,7 @@
+# Выбор parser для текущего профиля соединения. Только выбранный протокол получает входные
+# байты; при смене режима выполняется reset, чтобы хвост старого пакета не попал в новый
+# parser.
+
 """Выбор wire-протокола для одного последовательного канала SETGUI.
 
 Во время подключения оба потоковых parser-а получают одинаковые байты. Первый

python/set_devices/qt_ports/__init__.py

@@ -1 +1,5 @@
+# Входная точка пакета set_devices.qt_ports. Определяет доступные при импорте имена; подробные
+# контракты находятся в специализированных модулях пакета. Изменение реэкспортов влияет на
+# существующие import у потребителей.
+
 """Reusable device libraries from setcorp/templates."""

python/set_devices/qt_ports/candle_adapter.py

@@ -1,3 +1,7 @@
+# Qt-совместимый транспорт WinUSB для candleLight/gs_usb. Детали ctypes скрыты в адаптере;
+# жизненный цикл устройства и канала должен завершаться закрытием ресурсов независимо от
+# состояния интерфейса.
+
 """WinUSB transport for candleLight/gs_usb CAN adapters.
 
 The native library is the same Candle API used by CANgaroo.  This module keeps

python/set_devices/qt_ports/f407_usb_bootloader.py

@@ -1,3 +1,7 @@
+# Асинхронный обновитель односекционного STM32F407 через SET v2 USB. Проверка образа
+# предшествует передаче, а продвижение по этапам зависит от ответов загрузчика; интерфейс не
+# должен блокироваться ожиданием Flash.
+
 """Asynchronous SET v2 USB updater for the STM32F407VE single-slot port."""
 from __future__ import annotations
 import struct

python/set_devices/qt_ports/mock_port.py

@@ -1,3 +1,7 @@
+# Qt-порт виртуального устройства для разработки интерфейса без COM-подключения. Сигналы и
+# ответы повторяют контракт обычного порта, чтобы UI мог переключать источник без изменения
+# обработчиков.
+
 """@file mock_port.py
 @brief Qt-таймер, имитирующий подключённый контроллер без COM-порта.
 

python/set_devices/qt_ports/plot_annotations.py

@@ -1,3 +1,7 @@
+# Отрисовка математических подписей кривых средствами Qt. Выравнивание и координаты текста
+# относятся к представлению; сами коэффициенты и данные реконструкции должны приходить из
+# модели расчёта.
+
 """Small right-aligned mathematical annotations shared by Qt plots."""
 try:
     from PySide6.QtCore import QRectF, Qt

python/set_devices/qt_ports/plot_navigation.py

@@ -1,3 +1,7 @@
+# Общие жесты клавиатуры и колеса для Qt-графиков. Обработчики переводят пользовательские
+# события в изменения области просмотра; настройки осей и сохранение данных остаются в
+# владельце графика.
+
 """Common keyboard and wheel gestures for all plot canvases (Qt 5/6)."""
 try:
     from PySide6.QtCore import Qt

python/set_devices/qt_ports/plot_processing.py

@@ -1,3 +1,7 @@
+# Qt-панель обработки графиков с выполнением расчётов в рабочей задаче. Снимок входных данных
+# отделён от живого графика; сигналы доставляют результат обратно в UI для добавления
+# самостоятельной вычисленной кривой.
+
 """Reusable Qt processing panel and plot attachment; no SETGUI dependency."""
 from __future__ import annotations
 from dataclasses import replace

python/set_devices/qt_ports/port_selection.py

@@ -1,3 +1,6 @@
+# Единое отображение и выбор последовательного порта в Qt-интерфейсе. Пользовательская подпись
+# может содержать описание устройства, но для открытия сохраняется системное имя порта.
+
 """Shared serial-port labels and selection for Qt project interfaces."""
 
 

python/set_devices/qt_ports/qt_compat.py

@@ -1,3 +1,7 @@
+# Точка импорта зависимостей Qt для транспортных адаптеров. Базовый пакет устройств не должен
+# загружать Qt при обычном импорте: это позволяет использовать переносимые модели в консольных
+# инструментах.
+
 """Qt transport dependencies; importing set_devices itself never loads Qt."""
 try:
     from PySide6.QtCore import QObject, Signal, QTimer, QElapsedTimer

python/set_devices/qt_ports/serial_port.py

@@ -1,3 +1,7 @@
+# Асинхронный QSerialPort с передачей входных фрагментов потоковому parser. Сигнал readyRead
+# не гарантирует целый кадр; открытие, закрытие и ошибки соединения обслуживаются в жизненном
+# цикле Qt.
+
 """@file serial_port.py
 @brief Неблокирующий QSerialPort и потоковый parser GUI transport.
 

python/set_devices/qt_ports/slcan_adapter.py

@@ -1,3 +1,7 @@
+# Последовательный транспорт Lawicel/SLCAN для CAN-адаптера. Текстовое представление кодирует
+# ID, длину и данные кадра; окончания строк разделяют команды и требуют накопления неполной
+# строки.
+
 """Serial Line CAN (Lawicel/SLCAN) transport."""
 
 from __future__ import annotations

python/set_devices/qt_ports/stm32_bootloader.py

@@ -1,3 +1,6 @@
+# Неблокирующий клиент ROM UART-загрузчика STM32. Команды и ACK/NACK обслуживаются
+# последовательными состояниями, чтобы ожидание устройства не блокировало цикл Qt.
+
 """Non-blocking client for the STM32 ROM UART bootloader described by AN3155."""
 
 from __future__ import annotations

python/set_devices/qt_ports/stm_settings.py

@@ -1,3 +1,7 @@
+# Транзакционное изменение настроек STM через регистровые команды FC03/FC06. Чтение, проверка
+# ответа и подтверждение записи составляют один клиентский обмен; отправка запроса не равна
+# успешному применению.
+
 """Transactional STM configuration extension (FC03/FC06, 0x1210)."""
 import struct
 

python/set_devices/qt_ports/tms_bootloader.py

@@ -1,3 +1,6 @@
+# Неблокирующая последовательность INITLOAD/LOAD/TFLASH для TMS. Ответы и таймауты управляют
+# переходами между этапами; размеры блоков и адреса берутся из протокола целевого контроллера.
+
 """Non-blocking port of Gui_Android's INITLOAD / LOAD / TFLASH workflow."""
 from .qt_compat import QObject, QTimer, Signal
 from .qt_compat import QSerialPort

python/set_devices/qt_ports/ump_can_client.py

@@ -1,3 +1,6 @@
+# Асинхронный клиент CAN-запросов УМП поверх существующего соединения. Ожидаемый ответ
+# привязан к активному запросу; транспортный цикл Qt отделён от модели регистратора.
+
 """Последовательный клиент CAN-логгера поверх уже подключённого Dima-адаптера."""
 import secrets
 from .qt_compat import QObject, QTimer, Signal

python/set_devices/qt_ports/wavegen.py

@@ -1,3 +1,7 @@
+# Рабочий транспорт генератора по USB CDC/COM для WG и блочной загрузки SET v2. Ожидания
+# выполняются в рабочем потоке; результаты возвращаются через сигналы, сохраняя отзывчивость
+# интерфейса.
+
 """USB CDC/COM worker for WG v1/v2/v3, with SET v2 block uploads. All waits run in a worker, never the GUI thread."""
 import time
 from PySide6.QtCore import QObject, QRunnable, Signal, QIODevice

python/set_devices/shared_protocol.py

@@ -1,3 +1,7 @@
+# Точка получения нативного SETProtocol для клиентских модулей. Загрузка отделена от
+# пользовательского интерфейса; настройка SETPROTOCOL_LIBRARY выбирает библиотеку, которую
+# должны использовать привязки.
+
 """Optional native SETProtocol backend, configured by SETPROTOCOL_LIBRARY."""
 
 from __future__ import annotations

python/set_devices/signal_reconstruction.py

@@ -1,3 +1,7 @@
+# Тонкий адаптер реконструкции сигнала и преобразования напряжений в коды ЦАП. Массивы и
+# рабочая память подготавливаются в Python, а численный алгоритм и проверки диапазонов
+# выполняет общее C-ядро.
+
 """Thin host adapter for the shared C99 reconstruction/DAC algorithms."""
 from __future__ import annotations
 import ctypes as C

python/set_devices/spectrum_demo.py

@@ -1,3 +1,7 @@
+# Демонстрационный источник спектра и гармоник для проверки интерфейса без STM32. Управляемые
+# частоты и амплитуды позволяют увидеть реакцию графика; эти данные не следует смешивать с
+# реальными измерениями.
+
 """@file spectrum_demo.py
 @brief Демонстрационный источник спектра для проверки вкладки без прибора.
 

python/set_devices/spectrum_stream.py

@@ -1,3 +1,7 @@
+# Разбор строкового потока спектра и гармоник STM32. Строка должна быть получена целиком и
+# пройти проверку до выдачи кадра; накопитель учитывает, что чтение порта может завершиться
+# посреди строки.
+
 """@file spectrum_stream.py
 @brief Разбор потока спектра и гармоник от прибора на STM32.
 

python/set_devices/tektronix.py

@@ -1,3 +1,7 @@
+# Получение осциллограмм Tektronix DPO4034 через SCPI/VISA. Параметры масштаба из прибора
+# переводят сырые отсчёты в физические значения; выбор VISA-ресурса отделён от графического
+# интерфейса.
+
 """DPO4034 SCPI acquisition over VISA (GPIB or Ethernet), without Qt.
 
 See docs/tektronix-dpo4034.md for wiring, commands and scaling.

python/set_devices/tms_flash.py

@@ -1,3 +1,7 @@
+# Планирование дампа внешней памяти TMS и сборка ответов CMD_UPLOAD. Адреса XINTF считаются
+# 16-битными словами, размер передачи — байтами; прогресс и смещение рассчитываются с явным
+# переводом единиц.
+
 """Legacy BALZAM/TMS parallel-memory dump protocol.
 
 The TMS320F2812 addresses external XINTF memory in 16-bit words, while

python/set_devices/tms_terminal.py

@@ -1,4 +1,8 @@
 # -*- coding: utf-8 -*-
+# Обмен с историческим терминалом TMS. Формат обычных ответов и телеметрии зависит от
+# используемого адаптера; состояние parser сохраняется между фрагментами, а профиль
+# контроллера выбирается вызывающим приложением.
+
 """Посылка ПЧ -> терминал прошивки ТМС (``TMS_TO_TERMINAL``).
 
 Это третий формат в проекте: не протокол SETGUI (``A5 5A``) из ``protocol.py``

python/set_devices/ump_logger.py

@@ -1,3 +1,7 @@
+# Клиент регистратора УМП v2 с выбором аналоговых каналов и чтением снимка. Индексы каналов и
+# регистровые адреса разделены; отображение результата не должно менять порядок слов принятого
+# снимка.
+
 """Протокол кольцевого логгера УМП v2.
 
 Технологические регистры 0..127 не изменены. Расширение 0x1000 сначала

python/set_devices/ump_logger_can.py

@@ -1,3 +1,7 @@
+# CAN-представление запросов регистратора periph_28335. Идентификаторы запросов и ответов
+# зависят от режима; обратное преобразование выполняется по этому контракту, а не по формату
+# общего моста.
+
 """CAN-транспорт расширения регистратора periph_28335.
 
 Служебные запросы идут на штатный RX ID платы 0xBA0000 + Mode - 1.

python/set_devices/ump_logger_demo.py

@@ -1,3 +1,7 @@
+# Синтетический снимок регистратора УМП для работы GUI без контроллера. Данные формируются в
+# ожидаемом представлении клиента, чтобы проверять выбор каналов и отображение одной и той же
+# моделью.
+
 """Синтетические записи УМП для проверки графиков без подключения платы."""
 import math
 

python/set_devices/waveform.py

@@ -1,3 +1,7 @@
+# Рецепты и таблицы периодических сигналов для генератора. Интерполяция и квантование
+# передаются общему ядру; экспорт таблицы сохраняет подготовленный порядок отсчётов для
+# циклического воспроизведения.
+
 """Reusable recipes and tables; interpolation/quantization live in C."""
 from __future__ import annotations
 import math

python/set_devices/wavegen_protocol.py

@@ -1,3 +1,6 @@
+# ctypes-привязка RTU-кодека генератора сигналов. Модуль преобразует аргументы и результаты, а
+# построение запросов и проверка ответов выполняются общей реализацией set_wavegen.
+
 """ctypes port of the shared wave generator RTU codec."""
 import ctypes as C
 from .signal_reconstruction import library