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

python/protocan/__init__.py

@@ -1,3 +1,7 @@
+# Входная точка пакета protocan. Определяет доступные при импорте имена; подробные контракты
+# находятся в специализированных модулях пакета. Изменение реэкспортов влияет на существующие
+# import у потребителей.
+
 """Переносимые модули и тонкая Python-обёртка SETProtocol."""
 
 # Consumers may supply additional platform ports from their pinned templates

python/protocan/balsam.py

@@ -1,3 +1,6 @@
+# Python-привязка исторического CAN-протокола Balsam к общему C99-ядру. Модуль представляет
+# результат в объектах Python; двоичный контракт регистров остаётся в balsam_can.
+
 """Balsam 167 legacy CAN register decoder backed by the shared C99 core."""
 
 from __future__ import annotations

python/protocan/can_boot.py

@@ -1,3 +1,7 @@
+# Клиент A/B-загрузчика ProtoCAN с оконной передачей блоков по восемь байт. Ответы принимаются
+# только для целевого адреса и текущей сессии; продвижение по этапам зависит от подтверждения,
+# а не от факта отправки.
+
 """Legacy ProtoCAN Boot client ported from Gui_Android CanFirmwareProtocol.kt."""
 from __future__ import annotations
 
@@ -66,6 +70,8 @@ class CanBootTransfer:
                 and p.msg_type == 12 and p.pm == 1 and p.device_type == t.device_type
                 and p.device == t.device and p.body >> 8 == t.session_id and len(frame.data) == 8)
 
+    # Окно содержит до 16 блоков. Последний неполный блок заполняется 0xFF,
+    # но метаданные образа сохраняют исходную длину без этого дополнения.
     def _window(self):
         total = (len(self.image.data) + 7) // 8
         self._window_end = min(total, self.next_block + 16)
@@ -78,6 +84,8 @@ class CanBootTransfer:
         command = ProtoCanId.parse(frame.can_id).body & 255
         expected_command = {"enter": 2, "image": 3, "compat": 4, "erase": 5,
                             "data": 0, "verify": 6, "commit": 7, "reboot": 9}.get(self.stage)
+        # Позднее подтверждение предыдущего этапа нельзя применять к новому:
+        # оно не продвигает автомат и не считается ошибкой текущего запроса.
         if command != expected_command:
             return [], ""
         status, slot, expected = struct.unpack_from("<BBH", frame.data)

python/protocan/devboard_v1.py

@@ -1,3 +1,7 @@
+# Команды и кадры USB-моста CAN485 DevBoard_V1. Преобразование между представлением адаптера и
+# CAN отделено от последовательного порта, чтобы один контракт использовался в GUI и проверках
+# без устройства.
+
 """CAN485 DevBoard_V1 USB command and frame helpers (no GUI/serial dependency)."""
 
 from __future__ import annotations

python/protocan/gas_catalog.py

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

python/protocan/legacycan.py

@@ -1,3 +1,7 @@
+# Общая модель исторического CAN_terminal и его каталога проектов. Выбор проекта определяет
+# интерпретацию регистров; транспорт и отображение подключаются отдельно, без переноса таблиц
+# протокола в каждый GUI.
+
 """UI-independent model of the historical CAN_terminal protocol.
 
 The catalog is migrated from ``CAN_terminal/Projects.ini``.  Both desktop

python/protocan/native.py

@@ -1,3 +1,8 @@
+# Стабильная C-граница для ctypes, JNI и других языков. Фиксированные типы и явные размеры
+# буферов отделяют бинарный контракт от внутренних структур; изменения сигнатур требуют
+# согласованного обновления привязок. Поиск DLL/SO учитывает явный путь окружения и варианты
+# имён библиотеки.
+
 """ctypes port for the shared C99 SETProtocol core.
 
 The protocol implementation lives in ``c/set-protocol``.  This module

python/protocan/periph28335.py

@@ -1,3 +1,7 @@
+# Протокол периферийного контроллера ПМ35/TMS320F28335: регистры, команды и разбор ответов.
+# Этот профиль имеет собственную адресацию и не должен подменяться протоколом основного
+# TMS320F2812.
+
 """Thin Python port of the shared C99 PM35/TMS320F28335 protocol."""
 
 from __future__ import annotations

python/protocan/plot.py

@@ -1,3 +1,7 @@
+# Адаптер общей математики графика из set_plot.c. Область просмотра и координатные
+# преобразования рассчитываются ядром; приложение отвечает за единицы, получение измерений и
+# отрисовку.
+
 """Plot interaction port. All numerical operations use templates' set_plot.c.
 
 This module has no Qt dependency. The application supplies its SETProtocol CDLL.

python/protocan/protocan.py

@@ -1,4 +1,7 @@
 # -*- coding: utf-8 -*-
+# Явная упаковка полей в 29-битный идентификатор ProtoCAN и их извлечение. Маски и сдвиги
+# задают переносимый wire-формат без зависимости от расположения битовых полей компилятора.
+
 """Разбор и сборка сообщений ProtoCAN — прикладного уровня шины CAN.
 
 Раскладка полей повторяет ``ProtoCanId_t`` из SETCAN/Inc/protocan.h:

python/protocan/protocol.py

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

python/protocan/setp_firmware.py

@@ -1,3 +1,7 @@
+# Клиент обновления SETProtocol v2 через сегментированный classic CAN. Состояние передачи
+# связывает запросы и подтверждения; сегментация транспорта отделена от команд начала, данных
+# и завершения обновления.
+
 """SETProtocol v2 firmware client over segmented classic CAN."""
 
 from __future__ import annotations

python/protocan/spectrum.py

@@ -1,3 +1,7 @@
+# Привязка общего расчёта спектра C99 к клиенту. Входные временные метки задаются в секундах;
+# частота дискретизации и нормировка определяются ядром, поэтому отображение не должно
+# повторно нормировать амплитуды.
+
 """Shared FFT adapter for desktop GUIs; no numpy/Qt dependency or duplicated DSP.
 
 Pass NativeProtocol.lib (rebuilt with set_spectrum.c). Timestamp inputs are seconds.

python/protocan/stm32_boot.py

@@ -1,3 +1,6 @@
+# Пакеты системного UART-загрузчика STM32 по AN3155. Команды этого режима отличаются от
+# SETProtocol; переход в ROM bootloader и физический обмен обслуживает внешний клиент.
+
 """Packets and constants for the STM32 system-memory UART bootloader (AN3155)."""
 
 from __future__ import annotations

python/protocan/tms2812.py

@@ -1,3 +1,7 @@
+# Исторический протокол основного контроллера ПМ67/TMS320F2812. Формирование команд и проверка
+# ответов находятся в общем ядре; адреса памяти C28x считаются словами, тогда как длины
+# передачи могут задаваться байтами.
+
 """Thin Python adapter for the shared C99 PM67/TMS320F2812 protocol."""
 
 from __future__ import annotations

python/protocan/tms_firmware.py

@@ -1,3 +1,7 @@
+# Последовательность обновления BALZAM/ПМ67 через команды TMS. Адрес задаётся в 16-битных
+# словах, а размер передаваемого блока — в байтах; смешение этих единиц смещает запись даже
+# при корректной контрольной сумме.
+
 """BALZAM/PM67 firmware protocol, ported from Gui_Android Tms2812Protocol.
 
 Addresses count 16-bit words; transfer lengths count bytes.

python/protocan/tms_terminal.py

@@ -1,3 +1,7 @@
+# Обмен с историческим терминалом TMS. Формат обычных ответов и телеметрии зависит от
+# используемого адаптера; состояние parser сохраняется между фрагментами, а профиль
+# контроллера выбирается вызывающим приложением.
+
 """Thin host binding for legacy TMS2812 requests and ordinary responses.
 
 The wire implementation is c/set-protocol/src/tms2812.c, also used by JNI.

python/protocan/transport.py

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

python/protocan/trends.py

@@ -1,3 +1,7 @@
+# Модели источников и настроек трендов, используемые клиентскими приложениями. Идентификатор
+# сигнала связывает историю с источником независимо от имени и порядка; визуальное
+# переименование не должно менять физический источник.
+
 """Portable trend configuration shared by SETGUI and Android (no Qt/Android).
 
 Numeric CAN decoding uses set_trends.c through NativeTrends. JSON adapters