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

c/set-protocol/CMakeLists.txt

@@ -1,3 +1,7 @@
+# Сборка библиотеки setprotocol_static, set_protocol, setprotocol. Состав исходников и
+# публичные include-пути задают подключение к проекту потребителя. Файл также собирает и
+# регистрирует хостовые проверки; запускать их следует через CTest из каталога сборки.
+
 cmake_minimum_required(VERSION 3.13)
 project(setprotocol C)
 

c/set-protocol/include/altera_logic.h

@@ -1,3 +1,9 @@
+/*
+ * Автомат UART-клиента логического анализатора Altera: запрос, накопление ответа и контроль
+ * времени. Одновременно выполняется одна операция; ARM нельзя безусловно повторять, поскольку
+ * повторный запуск меняет состояние захвата.
+ */
+
 /** Altera logic analyzer UART client. C99, caller-owned memory, no OS/heap.
  * One request at a time; no automatic retries (ARM is not idempotent).
  * Initialize aligned storage of la_context_size() bytes, then call la_next,

c/set-protocol/include/altera_stream.h

@@ -1,3 +1,9 @@
+/*
+ * Приём потока выборок Altera Logic через SETCAN/GAS по CAN или UART. Счётчики выборок
+ * сохраняют положение во времени; получение пакетов и обновление изображения должны
+ * обслуживаться независимо.
+ */
+
 /** SETCAN/GAS Altera Logic online stream, shared by CAN and UART.
  * Caller-owned context; one serialized caller. No heap, OS or Qt dependencies.
  */

c/set-protocol/include/balsam_can.h

@@ -1,3 +1,9 @@
+/*
+ * Исторический регистровый CAN-протокол BALZAM/TMS2812. Формат идентификаторов и порядок слов
+ * относятся именно к этому профилю; общий физический CAN не делает его совместимым с SET v2
+ * или протоколом ПМ35.
+ */
+
 /**
  * @file balsam_can.h
  * @brief CAN_Bal_2812 extended-CAN register space.

c/set-protocol/include/firmware_image.h

@@ -1,3 +1,9 @@
+/*
+ * Проверка Intel HEX и подготовка адресованного образа прошивки. Контрольные суммы записей,
+ * расширенные адреса и пересечения проверяются до использования результата; рабочая память
+ * C-парсера принадлежит вызывающему.
+ */
+
 #ifndef SET_FIRMWARE_IMAGE_H
 #define SET_FIRMWARE_IMAGE_H
 #include "pcan_abi.h"

c/set-protocol/include/gui_catalog.h

@@ -1,3 +1,9 @@
+/*
+ * Каталог объектов GUI v1 и подписка на выбранные значения. Записи каталога описывают типы,
+ * адреса и имена; поток наблюдения передаёт значения отдельно от описания, поэтому клиент
+ * должен сохранять соответствие выбранным объектам.
+ */
+
 /**
  * @file    gui_catalog.h
  * @brief   Каталог общего адресного пространства и поток выбранных значений.

c/set-protocol/include/gui_frame.h

@@ -1,3 +1,9 @@
+/*
+ * Кадрирование GUI v1 с сигнатурой A5 5A и CRC32. Потоковый разбор сохраняет незавершённое
+ * сообщение между вызовами; готовый кадр выдаётся только после проверки длины и контрольной
+ * суммы.
+ */
+
 /**
  * @file    gui_frame.h
  * @brief   Транспорт GUI-протокола SETGUI на стороне МК.

c/set-protocol/include/pcan_abi.h

@@ -1,3 +1,9 @@
+/*
+ * Стабильная C-граница для ctypes, JNI и других языков. Фиксированные типы и явные размеры
+ * буферов отделяют бинарный контракт от внутренних структур; изменения сигнатур требуют
+ * согласованного обновления привязок.
+ */
+
 /**
  * @file pcan_abi.h
  * @brief Stable C ABI for desktop, Android and other foreign runtimes.

c/set-protocol/include/pcan_config.h

@@ -1,3 +1,9 @@
+/*
+ * Параметры сборки транспорта ProtoCAN: размеры и выбор реализации CRC. Они участвуют в
+ * компиляции ядра и потребителей заголовков; согласованность настроек важна для размеров
+ * структур и буферов.
+ */
+
 /**
  * @file    pcan_config.h
  * @brief   Настройки времени компиляции.

c/set-protocol/include/pcan_crc.h

@@ -1,3 +1,9 @@
+/*
+ * CRC-16/CCITT-FALSE для транспортного кадра ProtoCAN. Табличный и побитовый варианты должны
+ * давать одинаковый результат; CRC считается по оговорённым байтам кадра, без добавления
+ * сигнатуры.
+ */
+
 /**
  * @file    pcan_crc.h
  * @brief   CRC-16/CCITT-FALSE: poly 0x1021, init 0xFFFF, без рефлексии,

c/set-protocol/include/pcan_frame.h

@@ -1,3 +1,9 @@
+/*
+ * Преобразование CAN-кадра в поток AA 55 и обратный побайтный разбор. LEN описывает участок
+ * SEQ..DATA, CRC16 покрывает LEN..DATA; частичный пакет остаётся в состоянии parser до
+ * следующего фрагмента.
+ */
+
 /**
  * @file    pcan_frame.h
  * @brief   Транспортный кадр и потоковый разборщик.

c/set-protocol/include/pcan_gas.h

@@ -1,3 +1,9 @@
+/*
+ * Общее адресное пространство ProtoCAN, разбитое на регионы с обработчиками чтения и записи.
+ * Поиск региона и проверка доступа предшествуют обращению к приложению; номер регистра не
+ * является адресом памяти процессора.
+ */
+
 /**
  * @file    pcan_gas.h
  * @brief   Общее адресное пространство (General Address Space).

c/set-protocol/include/pcan_id.h

@@ -1,3 +1,8 @@
+/*
+ * Явная упаковка полей в 29-битный идентификатор ProtoCAN и их извлечение. Маски и сдвиги
+ * задают переносимый wire-формат без зависимости от расположения битовых полей компилятора.
+ */
+
 /**
  * @file    pcan_id.h
  * @brief   Упаковка и разбор 29-битного идентификатора ProtoCAN.

c/set-protocol/include/pcan_link.h

@@ -1,3 +1,9 @@
+/*
+ * Канал ProtoCAN поверх произвольного потока байтов. Контекст хранит parser и параметры
+ * отправки; физический ввод-вывод подключается обратными вызовами, а готовые CAN-кадры
+ * передаются обработчику приложения.
+ */
+
 /**
  * @file    pcan_link.h
  * @brief   Экземпляр канала связи поверх произвольного байтового потока.

c/set-protocol/include/pcan_modbus_server.h

@@ -1,3 +1,9 @@
+/*
+ * Доступ к окнам Modbus-регистров через один classic CAN-кадр ProtoCAN. Сервер сопоставляет
+ * команду с банком и диапазоном регистров; чтение и запись значений выполняет предоставленный
+ * приложением интерфейс.
+ */
+
 /**
  * @file pcan_modbus_server.h
  * @brief Modbus register windows transported in one classic ProtoCAN frame.

c/set-protocol/include/pcan_ring.h

@@ -1,3 +1,9 @@
+/*
+ * Кольцевая очередь байтов для одного производителя и одного потребителя. Размер хранилища
+ * должен быть степенью двойки; одна позиция резервируется для различения пустого и полного
+ * состояния.
+ */
+
 /**
  * @file    pcan_ring.h
  * @brief   Кольцевой буфер байтов: один писатель, один читатель.

c/set-protocol/include/periph28335.h

@@ -1,3 +1,9 @@
+/*
+ * Протокол периферийного контроллера ПМ35/TMS320F28335: регистры, команды и разбор ответов.
+ * Этот профиль имеет собственную адресацию и не должен подменяться протоколом основного
+ * TMS320F2812.
+ */
+
 /**
  * @file periph28335.h
  * @brief Shared PM35/TMS320F28335 register protocol.

c/set-protocol/include/protocan_transport.h

@@ -1,3 +1,9 @@
+/*
+ * Общий заголовок подключения библиотеки протокола. Он собирает публичные определения в одной
+ * точке; конкретные контракты кадров, буферов и кодов ошибок описаны в подключаемых
+ * специализированных заголовках.
+ */
+
 /**
  * @file    protocan_transport.h
  * @brief   Зонтичный заголовок библиотеки. Достаточно подключить его одного.

c/set-protocol/include/set_boot.h

@@ -1,3 +1,9 @@
+/*
+ * Транспортно-независимый односекционный обновитель прошивки. Признак валидности снимается до
+ * стирания, а commit вызывается после проверки записанного образа чтением; порядок операций
+ * нужен для восстановления после прерывания питания.
+ */
+
 #ifndef SET_BOOT_H
 #define SET_BOOT_H
 #include "set_firmware.h"

c/set-protocol/include/set_can.h

@@ -1,3 +1,9 @@
+/*
+ * Сегментация SET v2 и интерпретация CAN-данных зависят от выбранного слоя. Адрес и номер
+ * сегмента должны проверяться до объединения данных; classic CAN-пакет ограничен восемью
+ * байтами.
+ */
+
 #ifndef SET_CAN_H
 #define SET_CAN_H
 

c/set-protocol/include/set_crc.h

@@ -1,3 +1,9 @@
+/*
+ * Общие контрольные суммы исторических протоколов SET. Алгоритмы с разными полиномами,
+ * начальными значениями и отражением битов не взаимозаменяемы, даже если возвращают одинаковый
+ * по ширине целый тип.
+ */
+
 /** @file set_crc.h @brief Shared checksums used by legacy SET controllers. */
 #ifndef SET_CRC_H
 #define SET_CRC_H

c/set-protocol/include/set_emu_igbt.h

@@ -1,3 +1,9 @@
+/*
+ * Модель каналов IGBT для стенда: входные состояния, задержки и сформированные выходы. Логика
+ * времени отделена от аппаратного порта; модель предназначена для воспроизводимого обмена с
+ * эмулятором.
+ */
+
 #ifndef SET_EMU_IGBT_H
 #define SET_EMU_IGBT_H
 #include "set_regmap.h"

c/set-protocol/include/set_emu_server.h

@@ -1,3 +1,9 @@
+/*
+ * Эталонная композиция сервисов эмулятора: УМП, TMS, IGBT и генератор сигналов. Общая карта
+ * регистров маршрутизирует обращения; другой продукт может составить собственную карту через
+ * set_regmap.
+ */
+
 /* Reference service composition for emulator boards; use set_regmap directly
  * for a different map, subset, or multiple instances of any module. */
 #ifndef SET_EMU_SERVER_H

c/set-protocol/include/set_emu_tms.h

@@ -1,3 +1,9 @@
+/*
+ * Модель ответов TMS для эмулятора контроллера. Синтетические аналоговые и дискретные значения
+ * упаковываются в ожидаемый формат терминала, чтобы проверять клиент без подключения рабочего
+ * контроллера.
+ */
+
 #ifndef SET_EMU_TMS_H
 #define SET_EMU_TMS_H
 #include "set_regmap.h"

c/set-protocol/include/set_emu_ump.h

@@ -1,3 +1,9 @@
+/*
+ * Синтетические сигналы УМП и регистратор эмулятора. Хранилище предоставляет вызывающий код;
+ * обновление модели и выдача записей разделены, чтобы клиент мог получать воспроизводимые
+ * снимки.
+ */
+
 #ifndef SET_EMU_UMP_H
 #define SET_EMU_UMP_H
 #include "set_regmap.h"

c/set-protocol/include/set_firmware.h

@@ -1,3 +1,9 @@
+/*
+ * Кодирование метаданных и сообщений обновления SETProtocol v2. Размер образа, совместимость и
+ * параметры начала передачи передаются явно; сериализация команды сама по себе не выполняет
+ * запись Flash.
+ */
+
 #ifndef SET_FIRMWARE_H
 #define SET_FIRMWARE_H
 

c/set-protocol/include/set_plot.h

@@ -1,3 +1,9 @@
+/*
+ * Математика взаимодействия с графиком: области просмотра, масштабирование, перемещение и
+ * координатные преобразования. Расчёты общие для JNI и ctypes; цвета, события GUI и рисование
+ * остаются в приложении.
+ */
+
 /** @file set_plot.h
  * @brief Toolkit-independent plot interaction math shared by JNI and ctypes.
  * Coordinates are doubles in the caller's units. No allocation or global state.

c/set-protocol/include/set_protocol.h

@@ -1,3 +1,9 @@
+/*
+ * Основной бинарный формат SETProtocol v2: поля кадра, контрольная сумма и потоковый parser.
+ * Числа сериализуются явно, поэтому выравнивание C-структур не влияет на байты линии;
+ * транспорт передаёт готовые массивы.
+ */
+
 #ifndef SET_PROTOCOL_H
 #define SET_PROTOCOL_H
 

c/set-protocol/include/set_regmap.h

@@ -1,3 +1,9 @@
+/*
+ * Транспортно-независимая карта 16-битных регистров с отдельными регионами и обработчиками.
+ * Проверка диапазонов и прав доступа выполняется до вызова сервиса; относительное смещение
+ * региона отличается от общего адреса.
+ */
+
 /* Transport-independent 16-bit word address space. No heap, clocks or board headers. */
 #ifndef SET_REGMAP_H
 #define SET_REGMAP_H

c/set-protocol/include/set_signal.h

@@ -1,3 +1,9 @@
+/*
+ * Восстановление сигнала по точкам и подготовка кодов 12-битного ЦАП. Совпадающие времена
+ * усредняются, экстраполяция не выполняется; для циклического периода конечная точка
+ * обрабатывается отдельно. Напряжения вне диапазона отклоняются, а не обрезаются.
+ */
+
 /** @file set_signal.h Portable interpolation and DAC waveform preparation. */
 #ifndef SET_SIGNAL_H
 #define SET_SIGNAL_H

c/set-protocol/include/set_spectrum.h

@@ -1,3 +1,9 @@
+/*
+ * Общий расчёт FFT: оценка частоты дискретизации по времени, ресемплинг, фильтр, окно и
+ * спектр. Выход — односторонняя пиковая амплитуда; DC и частота Найквиста не удваиваются.
+ * Временные метки задаются в секундах.
+ */
+
 /** Shared host-side FFT for Android/JNI and desktop/ctypes; no GUI dependencies. */
 #ifndef SET_SPECTRUM_H
 #define SET_SPECTRUM_H

c/set-protocol/include/set_telemetry.h

@@ -1,3 +1,9 @@
+/*
+ * Сообщения подписки и телеметрии SETProtocol v2. Период, идентификатор подписки и перечень
+ * адресов сериализуются отдельно от значений; получатель должен связывать поток с
+ * соответствующей подпиской.
+ */
+
 #ifndef SET_TELEMETRY_H
 #define SET_TELEMETRY_H
 

c/set-protocol/include/set_trends.h

@@ -1,3 +1,9 @@
+/*
+ * Общий разбор числовых источников трендов, включая GAS и raw CAN. Знаковость слова, смещение
+ * и коэффициент преобразования относятся к описанию сигнала; визуальная история графика
+ * хранится на стороне клиента.
+ */
+
 /** @file set_trends.h
  * @brief Shared GUI trend decoding and GUI v1 GAS subscription payloads.
  * No transport, rendering, allocation or global state. JNI/ctypes call the

c/set-protocol/include/set_wavegen.h

@@ -1,3 +1,9 @@
+/*
+ * Транзакционная загрузка таблицы и циклическое воспроизведение через ЦАП. Блоки принимаются
+ * до commit, а запуск использует согласованную таблицу; порт stop должен остановить DMA до
+ * возврата и освободить использование массива.
+ */
+
 /** @file set_wavegen.h Transactional table upload and cyclic DAC playback. */
 #ifndef SET_WAVEGEN_H
 #define SET_WAVEGEN_H

c/set-protocol/include/setprotocol.h

@@ -1,3 +1,9 @@
+/*
+ * Общий заголовок подключения библиотеки протокола. Он собирает публичные определения в одной
+ * точке; конкретные контракты кадров, буферов и кодов ошибок описаны в подключаемых
+ * специализированных заголовках.
+ */
+
 /**
  * @file setprotocol.h
  * @brief Единственная C99-точка включения полного SETProtocol.

c/set-protocol/include/setprotocol_abi.h

@@ -1,3 +1,9 @@
+/*
+ * Стабильная C-граница для ctypes, JNI и других языков. Фиксированные типы и явные размеры
+ * буферов отделяют бинарный контракт от внутренних структур; изменения сигнатур требуют
+ * согласованного обновления привязок.
+ */
+
 /**
  * @file setprotocol_abi.h
  * @brief Стабильная FFI-граница SETProtocol ABI v1.

c/set-protocol/include/tms2812.h

@@ -1,3 +1,9 @@
+/*
+ * Исторический протокол основного контроллера ПМ67/TMS320F2812. Формирование команд и проверка
+ * ответов находятся в общем ядре; адреса памяти C28x считаются словами, тогда как длины
+ * передачи могут задаваться байтами.
+ */
+
 /**
  * @file tms2812.h
  * @brief Shared PM67/TMS320F2812 legacy terminal and memory protocol.

c/set-protocol/include/ump_protocol.h

@@ -1,3 +1,8 @@
+/*
+ * Регистровый протокол УМП для UART/CAN с общей проверкой функций и диапазонов. Октеты
+ * извлекаются явно, чтобы формат оставался одинаковым на восьмибитных и C28x-платформах.
+ */
+
 /* UMP logger v2 (PM35), independent of PM67 and SET protocol v2.
  * Octets use 16-bit storage: C28x has CHAR_BIT=16 and no uint8_t.
  * All lengths below count wire octets or register words, never sizeof bytes.

c/set-protocol/ports/android/Android.mk

@@ -1,3 +1,6 @@
+# Сборка общей библиотеки SETProtocol средствами Android NDK. C-ядро и JNI-обёртки входят в
+# один модуль; список исходников должен включать реализации всех native-методов Kotlin.
+
 LOCAL_PATH := $(call my-dir)
 
 include $(CLEAR_VARS)

c/set-protocol/ports/android/kotlin/ru/setcorp/setflash/core/CanBridgeProtocol.kt

@@ -1,3 +1,8 @@
+/*
+ * Kotlin-модель обмена с мостом CAN/RS485. Преобразование wire-кадров делегируется общему
+ * ядру; пользовательский интерфейс получает типизированные поля, не зависящие от JNI-массивов.
+ */
+
 package ru.setcorp.setflash.core
 
 import ru.setcorp.setprotocol.NativeSetProtocol as NativeProtoCan

c/set-protocol/ports/android/kotlin/ru/setcorp/setflash/core/GuiProtocol.kt

@@ -1,3 +1,9 @@
+/*
+ * Кадрирование исторического GUI protocol v1. Parser накапливает части входного потока и
+ * проверяет сообщение до выдачи результата; этот формат следует выбирать по профилю
+ * соединения, а не только по сигнатуре.
+ */
+
 package ru.setcorp.setflash.core
 
 import java.util.zip.CRC32

c/set-protocol/ports/android/kotlin/ru/setcorp/setflash/core/ProtoCanCatalog.kt

@@ -1,3 +1,8 @@
+/*
+ * Общий каталог типов сообщений ProtoCAN для Android-клиентов. Числовые коды являются частью
+ * протокола; подписи служат отображению и не должны использоваться вместо кодов в обмене.
+ */
+
 package ru.setcorp.setflash.core
 
 /** Canonical ProtoCAN message-type registry shared by Android protocol clients. */

c/set-protocol/ports/android/kotlin/ru/setcorp/setflash/core/Tms2812Protocol.kt

@@ -1,3 +1,8 @@
+/*
+ * Kotlin-фасад протокола BALZAM/TMS320F2812. Кадрирование и контрольные суммы выполняет
+ * C99-ядро через NativeSetProtocol; модели Kotlin описывают аргументы и результаты операций.
+ */
+
 package ru.setcorp.setflash.core
 
 import ru.setcorp.setprotocol.NativeSetProtocol

c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/NativeSetProtocol.kt

@@ -1,3 +1,8 @@
+/*
+ * Kotlin-объявления JNI-вызовов общего SETProtocol. Порядок и типы аргументов должны совпадать
+ * с setprotocol_jni.c; библиотека должна содержать все объявленные нативные символы.
+ */
+
 package ru.setcorp.setprotocol
 
 /** Thin Kotlin facade over the shared C99 SETProtocol core. */

c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/balsam/BalsamCanProtocol.kt

@@ -1,3 +1,8 @@
+/*
+ * Android-представление исторического CAN-протокола BALZAM. Код связывает Kotlin-модели с
+ * общим ядром; регистры и формат идентификаторов не относятся к протоколу ПМ35.
+ */
+
 package ru.setcorp.setprotocol.balsam
 
 import ru.setcorp.setprotocol.NativeSetProtocol

c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/legacycan/LegacyCanTerminal.kt

@@ -1,3 +1,9 @@
+/*
+ * Android-модель исторического CAN-терминала и выбора проекта. Каталог определяет семантику
+ * команд, а транспорт только доставляет CAN-кадры; UI не должен создавать собственную копию
+ * wire-формата.
+ */
+
 package ru.setcorp.setprotocol.legacycan
 
 /** Wire formats implemented by the historical CAN_terminal application. */

c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/periph28335/Periph28335Protocol.kt

@@ -1,3 +1,8 @@
+/*
+ * Android-фасад отдельного протокола ПМ35/TMS320F28335. Запросы и ответы преобразуются через
+ * общее ядро; профиль периферийного контроллера сохраняется отдельно от TMS320F2812.
+ */
+
 package ru.setcorp.setprotocol.periph28335
 
 import ru.setcorp.setprotocol.NativeSetProtocol

c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/trends/GuiGasWatch.kt

@@ -1,3 +1,9 @@
+/*
+ * Android-поддержка наблюдения за объектами GAS через GUI-протокол. Подписка связывает список
+ * выбранных адресов с поступающими значениями; смена выбора требует согласования состояния
+ * клиента.
+ */
+
 package ru.setcorp.setprotocol.trends
 
 import ru.setcorp.setprotocol.NativeSetProtocol

c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/trends/NativePlot.kt

@@ -1,3 +1,9 @@
+/*
+ * Адаптер общей математики графика из set_plot.c. Область просмотра и координатные
+ * преобразования рассчитываются ядром; приложение отвечает за единицы, получение измерений и
+ * отрисовку.
+ */
+
 package ru.setcorp.setprotocol.trends
 
 /** Shared C99 plot math, also used by the Python/Qt port. No UI dependency. */

c/set-protocol/ports/android/kotlin/ru/setcorp/setprotocol/trends/PlotViewport.kt

@@ -1,3 +1,8 @@
+/*
+ * Модель области просмотра графика для Android. Границы и преобразования координат связывают
+ * жесты интерфейса с общей математикой; изменение видимой области не меняет измеренные данные.
+ */
+
 package ru.setcorp.setprotocol.trends
 
 /** Normalized top-left viewport; independent of pixels, units, toolkit and samples. */