Согласовать SCI-ядро и жизненный цикл прошивки с UlitCo

Сохранить совместимый переход RAM-ядра, постоянный поток Qt, точную диагностику обмена и журнал без повторов процентов. Добавить проверку транспортной точки входа официальным TI compiler.
Добавить SCI и J-Link и обновить общие порты устройств
2026-11-13 19:23:41 +03:00 · 2026-11-13 17:07:20 +03:00 · 2026-11-12 15:53:12 +03:00 · 2026-11-12 15:00:41 +03:00 · 2026-11-12 15:00:41 +03:00 · 2026-11-12 15:00:22 +03:00
1061 changed files with 141842 additions and 1316 deletions
@@ -27,3 +27,6 @@ Desktop.ini

 # Generated native library (built before packaging)
 python/protocan/native/
+
+# Кэш pytest создаётся проверками автоматически и не входит в исходники общей библиотеки.
+.pytest_cache/
@@ -0,0 +1,3 @@
+[submodule "third_party/kdiff3"]
+	path = third_party/kdiff3
+	url = https://invent.kde.org/sdk/kdiff3.git
@@ -0,0 +1,27 @@
+PROJECT_NAME           = "templates"
+PROJECT_BRIEF          = "Переносимые библиотеки и правила интеграции"
+OUTPUT_DIRECTORY       = .codex-build/doxygen
+CREATE_SUBDIRS         = NO
+OUTPUT_LANGUAGE        = Russian
+INPUT                  = README.md NEW_PROJECT.md CONTRIBUTING.md doc/submodules.dox c python
+FILE_PATTERNS          = *.h *.c *.dox *.md
+RECURSIVE              = YES
+USE_MDFILE_AS_MAINPAGE = README.md
+MARKDOWN_SUPPORT       = YES
+AUTOLINK_SUPPORT       = YES
+EXTRACT_ALL            = NO
+EXTRACT_STATIC         = NO
+SOURCE_BROWSER         = YES
+INLINE_SOURCES         = NO
+STRIP_FROM_PATH        = .
+GENERATE_HTML          = YES
+HTML_OUTPUT            = html
+GENERATE_TREEVIEW      = YES
+DISABLE_INDEX          = NO
+GENERATE_LATEX         = NO
+QUIET                  = YES
+WARNINGS               = YES
+WARN_IF_UNDOCUMENTED   = NO
+WARN_IF_DOC_ERROR      = YES
+WARN_AS_ERROR          = FAIL_ON_WARNINGS
+HAVE_DOT               = NO
@@ -84,7 +84,7 @@ STM32F103RC, STM32F103ZE и STM32G474CE объявляют поддержку з
 возвращают `PNAND_ERROR_WRITE_PROTECTED`, пока плата и порт не доработаны.

 Рабочий пример полноценного G474-порта находится в соседнем проекте
-`candleLight_fw`: `src/device/device_g4.c` отвечает за clock/GPIO,
+`CANdle_stm32` (candleLight): `src/device/device_g4.c` отвечает за clock/GPIO,
 `src/can/m_can.c` — за FDCAN, а `include/config.h` — за привязку платы
 STM32G474VET6. Эти файлы остаются в прошивке, поскольку зависят от STM32 HAL,
 USB gs_usb и конкретной разводки адаптера; переносимая логика протоколов
@@ -120,3 +120,188 @@ USB gs_usb и конкретной разводки адаптера; перен

 Так новый проект не является копией старого: он использует общие ядра одной
 версии, а аппаратные отличия видны в одном небольшом каталоге `port/`.
+
+## Слияние и обновление `templates` как Git submodule
+
+### Что именно хранит основной проект
+
+Основной проект не хранит содержимое `lib/templates` в своей истории. Вместо
+этого он хранит **gitlink** — ссылку на один конкретный commit репозитория
+`templates`. Поэтому при работе есть два независимых уровня истории:
+
+1. изменения библиотек сливаются и публикуются в репозитории `templates`;
+2. основной проект отдельным коммитом переводит gitlink на проверенную ревизию
+   `templates`.
+
+Обычный `git merge` в основном проекте не переносит исходники между ветками
+`templates` и не создаёт merge-коммит внутри сабмодуля. Он может только выбрать
+одну из уже существующих ссылок на commit. Если ссылки разошлись, сначала нужно
+получить общий commit в самом `templates`, а затем зафиксировать его в основном
+проекте.
+
+Текущую зафиксированную ревизию удобно смотреть из корня основного проекта:
+
+```bash
+git submodule status lib/templates
+git diff --submodule=log
+```
+
+Символ `-` перед SHA в `git submodule status` означает, что сабмодуль ещё не
+инициализирован; `+` — что рабочая копия сабмодуля находится не на том commit,
+который записан в основном проекте; `U` — конфликт gitlink.
+
+### Клонирование проекта и переключение его веток
+
+Новый клон лучше сразу создавать вместе с сабмодулями:
+
+```bash
+git clone --recurse-submodules <url-основного-проекта>
+cd <основной-проект>
+```
+
+Если проект уже клонирован:
+
+```bash
+git submodule update --init --recursive
+```
+
+После `git switch`, `git checkout`, `git pull` или завершения слияния основной
+проект может начать ссылаться на другую ревизию `templates`. Рабочее дерево
+сабмодуля следует явно привести к записанному состоянию:
+
+```bash
+git submodule update --init --recursive
+```
+
+Это нормальный и воспроизводимый режим: внутри `lib/templates` обычно будет
+detached HEAD, потому что проект фиксирует commit, а не ветку. Не следует делать
+там `git pull`, пока не выбрана рабочая ветка и не понятно, какую ревизию должен
+получить основной проект.
+
+### Обычное обновление проекта на новую версию `templates`
+
+Сначала изменение должно быть проверено, закоммичено, отправлено и слито в
+целевую ветку самого репозитория `templates`. После этого из корня основного
+проекта выполняется:
+
+```bash
+git -C lib/templates fetch origin
+git -C lib/templates switch --detach origin/master
+git add lib/templates
+git diff --cached --submodule=log
+git commit -m "build(templates): обновить общие библиотеки"
+```
+
+Перед коммитом нужно собрать основной проект и прогнать его тесты: успешные
+тесты в `templates` подтверждают работу библиотеки, но не проверяют конкретный
+порт, настройки платы и интеграцию приложения.
+
+Коммит основного проекта содержит только переход со старого SHA сабмодуля на
+новый. Случайные незакоммиченные файлы внутри `lib/templates` в него не входят.
+Проверить оба уровня перед фиксацией можно так:
+
+```bash
+git status
+git -C lib/templates status
+git diff --submodule=log
+```
+
+Не нужно обновлять сабмодуль на последний `master` автоматически при каждой
+сборке. Зафиксированный SHA нужен именно для того, чтобы одна и та же версия
+проекта всегда собиралась с одной и той же версией библиотек.
+
+### Если библиотеку правят из рабочего дерева основного проекта
+
+Нельзя коммитить изменение, оставаясь на detached HEAD: такой commit легко
+потерять при следующем `git submodule update`. Сначала внутри сабмодуля создаётся
+обычная ветка:
+
+```bash
+git -C lib/templates fetch origin
+git -C lib/templates switch -c feat/<имя> origin/master
+```
+
+Затем изменения коммитятся и отправляются именно в репозиторий `templates`:
+
+```bash
+git -C lib/templates add <файлы>
+git -C lib/templates commit -m "feat(<библиотека>): <описание>"
+git -C lib/templates push -u origin feat/<имя>
+```
+
+После проверки ветка сливается в `master` репозитория `templates`. Только после
+публикации итогового commit основной проект обновляет свой gitlink по процедуре
+из предыдущего раздела. Не следует отправлять в общий основной проект ссылку на
+commit сабмодуля, которого ещё нет на сервере: остальные разработчики и CI не
+смогут его получить.
+
+### Что происходит при слиянии веток основного проекта
+
+Возможны три ситуации:
+
+1. Gitlink изменён только в одной ветке. Git обычно принимает эту ревизию
+   автоматически. После merge нужно выполнить `git submodule update` и тесты.
+2. Обе ветки указывают на разные commits, но один commit `templates` является
+   предком другого. Следует выбрать более новый проверенный commit, выполнить
+   `git add lib/templates` и продолжить merge.
+3. Обе ветки указывают на расходящиеся commits `templates`. Это настоящий
+   конфликт истории сабмодуля: выбирать один SHA наугад нельзя, потому что так
+   потеряются изменения второй ветки.
+
+При конфликте сначала смотрят, какие ссылки пришли с обеих сторон:
+
+```bash
+git ls-files -u lib/templates
+git -C lib/templates fetch origin
+git -C lib/templates log --oneline --graph --decorate --all
+```
+
+Затем в отдельной ветке **репозитория `templates`** объединяют оба commit,
+устраняют конфликты исходников, запускают тесты и публикуют результат:
+
+```bash
+git -C lib/templates switch -c merge/<имя> <sha-одной-стороны>
+git -C lib/templates merge <sha-другой-стороны>
+# исправить конфликты и запустить тесты templates
+git -C lib/templates add <исправленные-файлы>
+git -C lib/templates commit
+git -C lib/templates push -u origin merge/<имя>
+```
+
+Если общий merge-коммит уже существует в `origin/master`, создавать ещё один не
+нужно: достаточно выбрать существующий SHA. После получения итогового commit
+конфликт завершается на уровне основного проекта:
+
+```bash
+git -C lib/templates switch --detach <итоговый-sha>
+git add lib/templates
+git diff --cached --submodule=log
+git merge --continue
+git submodule update --init --recursive
+```
+
+`git add lib/templates` здесь отмечает разрешённым именно gitlink. Не нужно
+удалять каталог, копировать библиотеку поверх него или разрешать конфликт как
+обычный текстовый файл.
+
+### Что должно попасть в merge request основного проекта
+
+Перед отправкой результата следует проверить:
+
+1. итоговый commit `templates` доступен в удалённом репозитории;
+2. `git -C lib/templates status` не показывает локальных изменений;
+3. `git submodule status` не начинается с `+`, `-` или `U`;
+4. `git diff --submodule=log <целевая-ветка>...HEAD` показывает ожидаемый набор
+   commits библиотек;
+5. тесты `templates`, сборка основного проекта и проверки на целевой плате
+   прошли;
+6. в основном проекте закоммичены необходимые изменения адаптеров, конфигурации
+   и сам новый gitlink.
+
+После получения ветки другой разработчик восстанавливает ровно выбранное
+состояние одной командой:
+
+```bash
+git pull
+git submodule update --init --recursive
+```
@@ -24,6 +24,18 @@ templates/

 ## Что лежит

+### FPGA и DSView
+
+| Блок | Назначение |
+|---|---|
+| [Блоки логического анализатора](hdl/logic-analyzer/README.md) | Аппаратный триггер, BRAM, AXI и кольцевой буфер DDR |
+| [Осциллограф](hdl/scope-acquisition/README.md) | Синхронизация каналов ADC, триггер, буфер и выдача записи |
+| [Ethernet в FPGA](hdl/logic-udp-ethernet/README.md) | RGMII, MDIO для RTL8211F, UDP-поток и буфер восьми входов |
+| [HDMI-отрисовка](hdl/logic-hdmi-preview/README.md) | График восьми цифровых каналов из входов или потока |
+| [Трёхфазный ШИМ](hdl/vfd-pwm/README.md) | DDS, рампа, комплементарные выходы и мёртвое время |
+| [DSView Ethernet](tools/dsview/zynq-ethernet/README.md) | Нативное подключение TCP/UDP, запуск и остановка |
+| [ZNET](c/zynq-net/README.md) | C99-кодек Ethernet-команд ввода-вывода |
+
 ### C

 | Библиотека | Что делает | Зависимости | Что нужно от платформы |
@@ -40,14 +52,19 @@ templates/
 | [`c/set-protocol/ports/stm32f407-devboard-v1`](c/set-protocol/ports/stm32f407-devboard-v1) | доступ SETGUI к Modbus-регистрам F407 через CAN485 DevBoard_V1 | `pcan_modbus_server`, STM32 HAL CAN | bxCAN FIFO0 и callbacks карты регистров |
 | [`c/set-protocol/ports/stm32-bxcan`](c/set-protocol/ports/stm32-bxcan) | порт прикладного ProtoCAN для STM32, бывший SETCAN; сохранён API `PROTOCAN_*` | STM32 HAL CAN/RTC/TIM + общее ядро `pcan_id` | classic bxCAN; настройки платы предоставляет прошивка |
 | [`c/set-protocol/ports/tms320f2812`](c/set-protocol/ports/tms320f2812) | SETProtocol v2 firmware service по segmented classic CAN | `set_protocol`, `set_can`, `set_firmware` | CAN TX, Flash erase/write/read, optional signature policy и reboot |
-| [`c/protocan-boot`](c/protocan-boot) | адресная прошивка по ProtoCAN: A/B-слоты, сессия, CRC32, verify и rollback-контракт | C99 | CAN TX, erase/write Flash, boot metadata, проверка образа и reboot |
+| [`c/protocan-boot`](c/protocan-boot) | адресная прошивка по ProtoCAN: A/B-слоты, сессия, CRC32, verify и rollback-контракт | C99 | **STM32F103C8/F407VE/G474VE и TMS320F2812/F28335-порты в комплекте**; проекты STM32 подключены через templates, есть boot main и вход из приложения |
 | [`c/rs485-boot`](c/rs485-boot) | прошивка по RS-485 в формате SETGUI v1: потоковый parser, CRC32 и resume | C99 | UART TX/RX, DE, Flash — **порты STM32F103 и STM32G474VET в комплекте** |
 | [`c/rtc-service`](c/rtc-service) | RTC с резервированным backup-томом | `stdint.h` | доступ к RTC и backup-памяти — **порт K1921VK028 в комплекте** |
+| [`c/global-time`](c/global-time) | программные часы 1 мс, ProtoCAN RTCSETUP, готовность платы и атомарная метка логгера | C99 | IRQ lock, CAN TX, такт 1 мс — **порт TMS320F28335 eCAN-A / CPU Timer2 в комплекте** |
 | [`c/firmware-info`](c/firmware-info) | SemVer, build stamp и git build ID работающего образа | C99 | config-порты STM32F1/F4/G4 и К1921ВК028; упаковка для Modbus/SETGUI |
 | [`c/parallel-nand`](c/parallel-nand) | parallel NAND x8: raw read/program/erase, профили Micron MT29F1G08 и Hynix HY27UF084G2M, bad-block marker и банковое окно GAS для SETGUI | C99, опционально `set-protocol/pcan_gas` | **порты TMS320F2812, STM32F103RC/ZE, STM32F407VE и STM32G474CEU6; запись требует управляемого WP#** |

 ### Python

+Экспериментальный [`c/gas-logger`](c/gas-logger/README.md): непрерывная запись
+в два банка RAM, снимки через GAS/Modbus/ProtoCAN, JSON-карта имён и адресов,
+проектный порт ПМ35 и MCU-порты C28x / STM32. Клиент в `set_devices.gas_logger`.
+
 | Модуль | Что делает | Зависимости |
 |---|---|---|
 | [`python/setprotocol/firmware_database.py`](python/setprotocol/firmware_database.py) | база прошивок: HTTPS-каталог, скачивание с SHA-256 и кэшем, публикация в Gitea без SETGUI; [подключение и CLI](tools/firmware-publish/DATABASE.md) | stdlib, Python 3.10+ |
@@ -58,8 +75,13 @@ templates/

 ### Инструменты

+Исходники внешних приложений находятся в [`third_party`](third_party/README.md):
+[`third_party/kdiff3`](third_party/kdiff3) содержит официальный репозиторий KDiff3
+как вложенный Git submodule для развития сравнения файлов и каталогов в SETGUI.
+
 | Инструмент | Что делает |
 |---|---|
+| [`tools/firmware-build/fpga`](tools/firmware-build/fpga/README.md) | общий итератор версии и HDL-паспорт для Xilinx ISE, Vivado и Altera/Intel Quartus; контроль `.bit`/`.sof`, manifest, SHA-256 и архив |
 | [`tools/firmware-publish`](tools/firmware-publish) | единый BAT и конфигурации для проверки и публикации `.hex` Keil / `.bin` CCS 12 в каталоге SETGUI |

 Общие тренды для Android GUI и SETGUI: [формат JSON, C99-ядро и адаптеры](c/set-protocol/docs/GUI_TRENDS.md).
@@ -72,6 +94,11 @@ templates/
 В ней отдельно описаны граница ядра, ABI, память, три wire format и состояние
 портов Windows, Android, Linux и MCU.

+Обзор всего репозитория, включая слияние при подключении через submodule:
+[`doc/index.html`](doc/index.html). Справочник Doxygen собирается командой
+`powershell -ExecutionPolicy Bypass -File doc/build-doxygen.ps1` в
+`.codex-build/doxygen/html/index.html`.
+
 ## Как подключить к проекту

 **Сабмодуль** — когда нужна одна конкретная версия и обновление по команде:
@@ -81,6 +108,10 @@ git submodule add https://git.rd12.ru/Andrey/templates.git lib/templates
 git submodule update --init --recursive
 ```

+Как обновлять зафиксированную ревизию, переносить изменения из проекта и
+разрешать конфликт gitlink при слиянии веток, подробно описано в разделе
+[`Слияние и обновление templates как Git submodule`](NEW_PROJECT.md#слияние-и-обновление-templates-как-git-submodule).
+
 Дальше в сборку добавляются только нужные каталоги:

 ```
@@ -105,7 +136,7 @@ git subtree pull --prefix lib/templates https://git.rd12.ru/Andrey/templates.git
 | `KONOR_ds18b20` | st7789, keypad, menu, eeprom-ft24c256, can-sensor, ds18b20, firmware-info |
 | `OpticalTester` | st7789, keypad, menu, eeprom-ft24c256 |
 | `CAN_to_RS485` | set-protocol legacy transport, python/protocan |
-| `candleLight_fw` | эталон разделения общей логики и G431/G474 FDCAN-порта; общий ProtoCAN Boot переносится по контракту `protocan-boot` |
+| `CANdle_stm32` (candleLight) | G431/G474 FDCAN board-support; CAN/UART-загрузчик G474 и вход из приложения подключены к `protocan-boot/ports/stm32g474` через templates |
 | `SETGUI` | python/protocan |
 | `SETGUI`, Android GUI и новые устройства SET | set-protocol |
 | `k1921vk028` | rtc-service |
@@ -1,3 +1,7 @@
+# Сборка библиотеки can_sensor. Состав исходников и публичные include-пути задают подключение
+# к проекту потребителя. Файл также собирает и регистрирует хостовые проверки; запускать их
+# следует через CTest из каталога сборки.
+
 cmake_minimum_required(VERSION 3.13)
 project(can_sensor C)

@@ -1,3 +1,9 @@
+/*
+ * Обмен настройками датчиков DS18B20 через однокадровые сообщения SETCAN. ROM идентифицирует
+ * датчик независимо от его позиции; прикладное состояние и отправка CAN предоставляются через
+ * интерфейс библиотеки.
+ */
+
 /**
 * @file can_sensor.c
 * @brief Однокадровый транспорт SETCAN SETTINGS для локаций DS18B20.
@@ -1,3 +1,9 @@
+/*
+ * Обмен настройками датчиков DS18B20 через однокадровые сообщения SETCAN. ROM идентифицирует
+ * датчик независимо от его позиции; прикладное состояние и отправка CAN предоставляются через
+ * интерфейс библиотеки.
+ */
+
 /**
 * @file can_sensor.h
 * @brief Портируемый транспорт SETTINGS для привязки DS18B20 к локации.
@@ -1,3 +1,9 @@
+/*
+ * Прямой bxCAN-порт датчиков для STM32F1 без HAL. Регистры контроллера обеспечивают передачу и
+ * приём SETCAN, а конфигурация платы задаёт подключение шины; это аппаратная реализация
+ * интерфейса can_sensor.
+ */
+
 /**
 * @file can_sensor_stm32f1.c
 * @brief Опросный порт can-sensor на bxCAN STM32F1 без STM32 HAL.
@@ -1,3 +1,9 @@
+/*
+ * Прямой bxCAN-порт датчиков для STM32F1 без HAL. Регистры контроллера обеспечивают передачу и
+ * приём SETCAN, а конфигурация платы задаёт подключение шины; это аппаратная реализация
+ * интерфейса can_sensor.
+ */
+
 /**
 * @file can_sensor_stm32f1.h
 * @brief Опросный порт can-sensor на bxCAN микроконтроллеров STM32F1.
@@ -1,3 +1,9 @@
+/*
+ * Конфигурация can-sensor для порта stm32f1. Макросы задают параметры сборки и ограничения,
+ * используемые исходниками этого модуля. Это образец для проекта: значения выводов, размеров
+ * памяти и параметров устройства необходимо согласовать с целевой платой.
+ */
+
 /**
 * @file can_sensor_stm32f1_config.f103.template.h
 * @brief Шаблон выводов CAN1 для STM32F103 без ремапа.
@@ -1,3 +1,9 @@
+/*
+ * Проверки can_sensor: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+ * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+ * настройками рабочего устройства.
+ */
+
 #include "can_sensor.h"

 #include <stdio.h>
@@ -0,0 +1,15 @@
+cmake_minimum_required(VERSION 3.16) # Эта версия поддерживает используемые target_compile_features и CTest без платформенных расширений.
+project(can485_monitor C) # Переносимое ядро собирается независимо от Linux-порта и приложения SETGUI.
+add_library(can485_monitor STATIC src/can485_monitor.c) # Все платформы связываются с одним обработчиком команд и wire-форматов.
+target_include_directories(can485_monitor PUBLIC include) # Потребитель получает только публичный C-контракт библиотеки.
+target_compile_features(can485_monitor PUBLIC c_std_99) # Ядро не требует C11 и платформенных расширений языка.
+include(CTest) # Стандартный BUILD_TESTING управляет автономной проверкой библиотеки.
+if(BUILD_TESTING) # Host-проверка не требует Linux, Qt и физической CAN-шины.
+    add_executable(test_can485_monitor tests/test_can485_monitor.c) # Использует независимые wire-векторы и фикстуру аппаратных отказов.
+    target_link_libraries(test_can485_monitor PRIVATE can485_monitor) # Проверяет настоящую библиотеку, не тестовую копию алгоритма.
+    add_test(NAME can485_monitor_contract COMMAND test_can485_monitor) # Регистрирует единый поведенческий контракт для всех аппаратных портов.
+endif() # Завершает необязательную сборку тестов.
+if(CMAKE_SYSTEM_NAME STREQUAL "Linux") # Linux-заголовки не попадают в сборки ESP32, Windows и других MCU.
+    add_executable(zynq-can485d ports/zynq-linux/main.c) # SocketCAN, USB и Ethernet реализуются только аппаратным портом.
+    target_link_libraries(zynq-can485d PRIVATE can485_monitor) # Linux использует ровно то же C99-ядро, что host-проверка.
+endif() # Завершает платформенную часть библиотеки.
@@ -0,0 +1,75 @@
+# CAN485 monitor
+
+Общее C99-ядро команд CAN485 DevBoard/SETGUI и Linux-порт для PS CAN Zynq.
+Протоколы CAN (SETCAN, ProtoCAN, УМП, Balsam, DEIF и остальные) разбираются
+существующими библиотеками `templates/python`, без копий в проекте платы.
+
+Слои: SETGUI BoardTab → `qt_ports/can485_port.py` → Ethernet TCP или USB tty →
+`ports/zynq-linux/main.c` → `can485_monitor.c` → SocketCAN / RS485 / каталог SD.
+В ядре нет Linux, Qt, HAL, выделения памяти и глобального контекста.
+
+| Файл | Назначение и зависимости |
+|---|---|
+| `include/can485_monitor.h` | Контракт C99, `stdint.h`, `stddef.h` |
+| `src/can485_monitor.c` | Проверка команд, фильтр, маршруты, AA55/CRC8, строки CAN |
+| `ports/zynq-linux/main.c` | SocketCAN, rtnetlink, TCP, USB tty, UART RS485, SD, POSIX/Linux |
+| `tests/test_can485_monitor.c` | Эталонный пакет, ошибки/границы, маршрутизация, отказы оборудования |
+
+Порт предоставляет четыре callback: `emit(context,line)`,
+`configure(context,kbps,mode,running)`, `send(context,frame,source)` и
+`control(context,command)`. `source=0` означает CAN, `source=1` — RS485.
+`configure` и `send` возвращают 1 только после принятия операции драйвером.
+Аппаратный ACK этим результатом не подтверждается. Контекст и буферы принадлежат приложению.
+
+```c
+#include "can485_monitor.h" /* Подключает переносимое ядро библиотеки. */
+void example(cm_port port) { /* Аппаратные callback передаются вызывающей платформой. */
+    cm_monitor state; /* Контекст не разделяется с другим экземпляром моста. */
+    cm_init(&state, port); /* CAN остановлен, оба направления маршрута выключены. */
+    cm_command(&state, "V"); /* Версия и статус не меняют оборудование. */
+    cm_command(&state, "S125"); /* Запрашивает CAN 125 кбит/с через аппаратный callback. */
+    cm_command(&state, "M1"); /* Listen-only запрещает ручной TX и RS485→CAN. */
+    cm_frame frame = {0x123, 2, 0, {0xAB, 0xCD}}; /* STD ID и два исходных байта. */
+    cm_receive(&state, &frame, 0, 12345); /* Приём CAN в момент 12,345 с монотонного времени. */
+    cm_status(&state, 12345, "sd=idle"); /* Статус содержит только известные платформе поля. */
+} /* Реальная плата передаёт только фактически принятые кадры в cm_receive. */
+```
+
+Поддержаны команды `V ? H S M O C F Q R B T X Z L D G I` и Linux-расширение
+`Ncan0` / `Ncan1`. Команды строго проверяются целиком. RS485-пакет:
+`AA 55 FLAGS ID[4]be DLC DATA[8] CRC8(FLAGS..DATA, poly=0x07, init=0)`.
+CAN STD/EXT/RTR сохраняются. DATA TX через `T` повторяет контракт существующего ESP GUI.
+
+Linux-порт запускается с CAN остановленным, маршрутами и записью SD выключенными.
+`S`/`M`/`O` запускают CAN; `C` останавливает интерфейс. Настройка через rtnetlink
+требует root или `CAP_NET_ADMIN`; RAW CAN — соответствующих прав Linux.
+M2 требует реальной поддержки `CAN_CTRLMODE_PRESUME_ACK`; ошибка драйвера
+не маскируется под успешный no-ack. Фильтр программный и не отключает аппаратный ACK.
+
+TCP-порт по умолчанию **37579**, один управляющий клиент. Подключённый USB
+может получать поток, но команды второго транспорта возвращают `#ERR busy`.
+Второй TCP-клиент не вытесняет первого. При обрыве владельца маршруты выключаются,
+его SD-download отменяется. Медленный клиент отключается при заполнении очереди 64 КиБ.
+Служба не включает периодический CAN TX: этот таймер принадлежит SETGUI и
+останавливается при отключении. Смена `N` закрывает только собственный CAN socket.
+
+`--usb /dev/ttyGS0` использует USB OTG CDC ACM, если образ Linux предоставляет
+gadget serial. Также допустим выделенный UART через USB-UART, свободный от
+console/getty. Разъём USB HOST и USB-JTAG сами по себе CDC не создают.
+USB и RS485 должны использовать разные tty. RTS/CTS выключены. RS485 требует
+физического трансивера с аппаратным управлением направлением либо предварительной
+настройки драйвера UART; Linux-порт не переключает произвольные GPIO платы.
+
+SD — заранее выбранный каталог `--logs`, например `/mnt/sd/can-logs`.
+Журналы `can_*.csv` содержат совместимые текстовые строки кадров; импорт SETGUI
+распознаёт этот формат автоматически. Выдача файла асинхронная, блоками 128 байт,
+с проверяемыми offset/size/CRC32. Путь ограничен одним каталогом, `..` и symlink
+запрещены. Запись SD выключается перед чтением. `vin`, TEC и REC не выдумываются,
+если платформа не получила реальные значения.
+
+Используется: Zynq RK7020 (`demo/can485`) и CAN-панель SETGUI (`pc/zynq_can_panel.py`).
+Для единого физического источника задавайте одинаковый **TEMPLATES_ROOT** при
+запуске SETGUI и сборке ARM (`build.ps1 -Templates <тот же каталог>`).
+После изменения Python перезапустите приложение; изменение C требует пересборки
+службы, изменение встроенных библиотек EXE — пересборки EXE. Подмодули разных
+checkout обновляются явно: Git не обновляет уже собранную прошивку автоматически.
@@ -0,0 +1,24 @@
+#ifndef CAN485_MONITOR_H /* Защищает публичный контракт монитора от повторного включения. */
+#define CAN485_MONITOR_H /* Одинаковое ядро обслуживает команды DevBoard на разных платформах. */
+#include <stdint.h> /* Фиксирует размеры CAN ID, счётчиков и байтов независимо от процессора. */
+#include <stddef.h> /* Размеры выходных строк выражены штатным типом size_t. */
+typedef struct { uint32_t id; uint8_t dlc, flags, data[8]; } cm_frame; /* flags: бит 0 EXT, бит 1 RTR; Classic CAN содержит до восьми байтов. */
+typedef struct { /* Платформа предоставляет ввод-вывод, не копируя разбор команд. */
+    void (*emit)(void *, const char *); /* Принимает одну законченную строку с LF для Ethernet, USB и журнала. */
+    int (*configure)(void *, unsigned, unsigned, int); /* Применяет битрейт в кбит/с, режим M0/M1/M2 и состояние драйвера; ноль означает ошибку. */
+    int (*send)(void *, const cm_frame *, int); /* Передаёт кадр в CAN при source=0 либо в RS485 при source=1; успех означает принятие локальным драйвером. */
+    int (*control)(void *, const char *); /* Обслуживает аппаратную скорость B и файловые L/D/G/I; ответы формирует сам порт. */
+    void *context; /* Контекст принадлежит вызывающему коду и позволяет иметь несколько независимых мостов. */
+} cm_port; /* В ядре нет HAL, Linux, Qt, динамической памяти и глобального состояния. */
+typedef struct { /* Состояние протокола отделено от сетевых клиентов и файловых дескрипторов. */
+    cm_port port; unsigned bitrate, mode, route, baud, running; /* Скорости заданы в кбит/с для CAN и бод для RS485; route использует два младших бита направлений. */
+    uint32_t filter_id, filter_mask, rx, tx, rsrx, rstx, buserr, dropcan, droprs, rscrc; /* Счётчики относятся к фактическим операциям порта; фильтр сравнивает только 29 бит ID. */
+    uint64_t now; /* Последнее подтверждённое монотонное время позволяет ответу V сохранять реальный uptime между периодическими статусами. */
+} cm_monitor; /* Всё изменяемое состояние хранится в экземпляре вызывающего приложения. */
+void cm_init(cm_monitor *, cm_port); /* Инициализирует остановленный CAN 125 кбит/с, normal, маршруты выключены и RS485 512000 бод. */
+void cm_command(cm_monitor *, const char *); /* Проверяет полную команду без CR/LF и применяет её только после успешной валидации. */
+void cm_receive(cm_monitor *, const cm_frame *, int, uint64_t); /* Принимает кадр CAN=0 либо RS485=1 и монотонное время в миллисекундах. */
+void cm_status(cm_monitor *, uint64_t, const char *); /* Печатает совместимый #STAT; дополнительная строка содержит подтверждённые поля SD/Linux. */
+int cm_packet_decode(const uint8_t *, cm_frame *); /* Проверяет все 17 байт AA55/CRC8, формат ID и DLC до маршрутизации RS485. */
+void cm_packet_encode(const cm_frame *, uint8_t *); /* Формирует RS485 AA55, FLAGS, ID big-endian, DLC, восемь байтов и CRC8/0x07. */
+#endif /* Завершает независимый публичный контракт CAN485 monitor. */
@@ -1,3 +1,7 @@
+# Сборка библиотеки candle. Состав исходников и публичные include-пути задают подключение к
+# проекту потребителя. Платформенные зависимости и условия сборки задаются здесь, а не в
+# прикладных исходниках.
+
 cmake_minimum_required(VERSION 3.15)
 project(candle C)
 if(NOT WIN32)
@@ -5,5 +9,5 @@ if(NOT WIN32)
 endif()
 add_library(candle SHARED candle.c candle_ctrl_req.c candle.def)
 target_compile_definitions(candle PRIVATE UNICODE _UNICODE)
-target_link_libraries(candle PRIVATE setupapi winusb ole32 advapi32)
+target_link_libraries(candle PRIVATE setupapi winusb ole32 advapi32 cfgmgr32) # Configuration Manager сопоставляет интерфейсы CAN и DFU по родительскому USB-узлу.
 target_include_directories(candle PUBLIC ${CMAKE_CURRENT_SOURCE_DIR})
@@ -19,6 +19,12 @@

 */

+/*
+ * Доступ к CAN-адаптерам candleLight/gs_usb в Windows через WinUSB. Перечисление устройств,
+ * открытие канала и обмен кадрами образуют отдельный транспортный слой; он не интерпретирует
+ * прикладные регистры SETProtocol.
+ */
+
 #include "candle.h"

 #include <stdarg.h>
@@ -28,6 +34,86 @@
 #include "candle_defs.h"
 #include "candle_ctrl_req.h"
 #include "ch_9.h"
+#include <cfgmgr32.h> /* Сопоставляет интерфейсы CAN и DFU по общему родительскому USB-устройству Windows. */
+
+static DWORD candle_dfu_parent(const wchar_t *path, DEVINST *parent) /* Возвращает родителя интерфейса, чтобы команда не попала в другой подключённый адаптер. */
+{ /* Начало поиска физического USB-устройства по пути выбранного CAN-интерфейса. */
+    HDEVINFO devices = SetupDiCreateDeviceInfoList(NULL, NULL); /* Создаёт временный набор SetupAPI без перечисления посторонних устройств. */
+    if (devices == INVALID_HANDLE_VALUE) return GetLastError(); /* Сохраняет причину отказа создания набора Windows. */
+    SP_DEVICE_INTERFACE_DATA iface = {0}; /* Подготавливает описание интерфейса для открытия по точному пути. */
+    iface.cbSize = sizeof(iface); /* Передаёт SetupAPI размер структуры текущей разрядности процесса. */
+    SP_DEVINFO_DATA info = {0}; /* Получает идентификатор узла PnP выбранного интерфейса. */
+    info.cbSize = sizeof(info); /* Указывает размер структуры устройства согласно контракту SetupAPI. */
+    DWORD size = 0, error = ERROR_SUCCESS; /* Хранит требуемое число байтов и итоговый код Windows. */
+    if (!SetupDiOpenDeviceInterfaceW(devices, path, 0, &iface)) error = GetLastError(); /* Открывает только заданный путь, сохраняя ошибку исчезнувшего устройства. */
+    if (!error) SetupDiGetDeviceInterfaceDetailW(devices, &iface, NULL, 0, &size, NULL); /* Узнаёт объём буфера переменной длины для пути USB-интерфейса. */
+    PSP_DEVICE_INTERFACE_DETAIL_DATA_W detail = size ? malloc(size) : NULL; /* Выделяет буфер только после успешного определения его размера. */
+    if (!error && !detail) error = size ? ERROR_NOT_ENOUGH_MEMORY : GetLastError(); /* Отличает нехватку памяти от ошибки поиска описания. */
+    if (detail) { /* Обрабатывает описание только при наличии выделенного буфера. */
+        detail->cbSize = sizeof(*detail); /* Согласует размер заголовка с архитектурой Win32 или Win64. */
+        if (!SetupDiGetDeviceInterfaceDetailW(devices, &iface, detail, size, NULL, &info)) error = GetLastError(); /* Получает узел интерфейса из SetupAPI. */
+        else if (CM_Get_Parent(parent, info.DevInst, 0) != CR_SUCCESS) error = ERROR_NOT_FOUND; /* Получает общий родительский узел составного USB-адаптера. */
+        free(detail); /* Освобождает описание после получения идентификатора родителя. */
+    } /* Завершает работу с описанием интерфейса. */
+    SetupDiDestroyDeviceInfoList(devices); /* Освобождает набор SetupAPI при любом результате поиска. */
+    return error; /* Возвращает ноль при успехе либо причину отказа Windows. */
+} /* Завершает сопоставление интерфейса с физическим USB-устройством. */
+
+uint32_t __stdcall candle_dev_enter_dfu(const wchar_t *can_path, uint8_t status[6]) /* Возвращает код Windows и шестибайтовый DFU_GETSTATUS согласно DFU 1.1. */
+{ /* Начало отдельного сеанса управляющего интерфейса обновления. */
+    if (!can_path || !status) return ERROR_INVALID_PARAMETER; /* Запрещает отсутствие точного пути адаптера или выходного буфера статуса. */
+    memset(status, 0, 6); /* Исключает использование неинициализированных полей ответа при ошибке USB. */
+    DEVINST wanted_parent = 0; /* Запоминает физический адаптер, выбранный пользователем до остановки CAN. */
+    DWORD error = candle_dfu_parent(can_path, &wanted_parent); /* Ищет родителя по сохранённому пути CAN, не заменяя его первым найденным устройством. */
+    if (error) return error; /* Прерывает переход, если выбранный адаптер уже исчез из PnP. */
+    GUID guid = {0xc25b4308, 0x04d3, 0x11e6, {0xb3, 0xea, 0x60, 0x57, 0x18, 0x9e, 0x64, 0x43}}; /* GUID интерфейса обновления из дескриптора CANable 2.5. */
+    HDEVINFO devices = SetupDiGetClassDevsW(&guid, NULL, NULL, DIGCF_PRESENT | DIGCF_DEVICEINTERFACE); /* Перечисляет только подключённые интерфейсы обновления CANable 2.5. */
+    if (devices == INVALID_HANDLE_VALUE) return GetLastError(); /* Возвращает отказ SetupAPI без попытки послать команду. */
+    error = ERROR_NOT_FOUND; /* Отсутствие интерфейса обновления не считается успешным входом в DFU. */
+    for (DWORD index = 0; ; ++index) { /* Проверяет интерфейсы до точного совпадения физического устройства. */
+        SP_DEVICE_INTERFACE_DATA iface = {0}; /* Создаёт независимое описание очередного DFU-интерфейса. */
+        iface.cbSize = sizeof(iface); /* Задаёт обязательный размер структуры SetupAPI. */
+        if (!SetupDiEnumDeviceInterfaces(devices, NULL, &guid, index, &iface)) { /* Завершает обход либо сообщает ошибку перечисления. */
+            if (GetLastError() != ERROR_NO_MORE_ITEMS) error = GetLastError(); /* Отличает штатный конец списка от отказа Windows. */
+            break; /* Выходит из обхода после исчерпания интерфейсов или ошибки. */
+        } /* Завершает проверку результата перечисления. */
+        DWORD size = 0; /* Хранит размер описания очередного интерфейса в байтах. */
+        SetupDiGetDeviceInterfaceDetailW(devices, &iface, NULL, 0, &size, NULL); /* Определяет буфер для полного пути интерфейса обновления. */
+        if (!size) { error = GetLastError(); break; } /* Не продолжает работу с неполным результатом SetupAPI. */
+        PSP_DEVICE_INTERFACE_DETAIL_DATA_W detail = malloc(size); /* Выделяет описание с достаточным местом для USB-пути. */
+        if (!detail) { error = ERROR_NOT_ENOUGH_MEMORY; break; } /* Не допускает обращения к отсутствующему буферу. */
+        detail->cbSize = sizeof(*detail); /* Сохраняет ABI описания интерфейса Windows. */
+        if (!SetupDiGetDeviceInterfaceDetailW(devices, &iface, detail, size, NULL, NULL)) { /* Получает путь, который можно передать CreateFileW. */
+            error = GetLastError(); free(detail); break; /* Сохраняет ошибку и освобождает буфер перед выходом. */
+        } /* Завершает чтение пути интерфейса. */
+        DEVINST parent = 0; /* Хранит родителя текущего кандидата на обновление. */
+        if (candle_dfu_parent(detail->DevicePath, &parent) || parent != wanted_parent) { /* Исключает каждый интерфейс другого физического адаптера. */
+            free(detail); continue; /* Освобождает описание неподходящего кандидата и продолжает поиск. */
+        } /* Завершает проверку принадлежности выбранному USB-адаптеру. */
+        HANDLE file = CreateFileW(detail->DevicePath, GENERIC_READ | GENERIC_WRITE, 0, NULL, OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL | FILE_FLAG_OVERLAPPED, NULL); /* Эксклюзивно открывает интерфейс обновления выбранного устройства для WinUSB. */
+        free(detail); /* Путь больше не нужен после открытия системного дескриптора. */
+        if (file == INVALID_HANDLE_VALUE) { error = GetLastError(); break; } /* Не скрывает отсутствие доступа или занятость интерфейса. */
+        WINUSB_INTERFACE_HANDLE usb = NULL; /* Хранит отдельный WinUSB-сеанс интерфейса обновления без CAN bulk endpoint. */
+        error = ERROR_SUCCESS; /* Сбрасывает исходное отсутствие интерфейса после точного совпадения устройства. */
+        if (!WinUsb_Initialize(file, &usb)) error = GetLastError(); /* Проверяет наличие рабочего WinUSB-драйвера DFU runtime. */
+        USB_INTERFACE_DESCRIPTOR descriptor = {0}; /* Получает реальный номер и класс открытого интерфейса. */
+        if (!error && !WinUsb_QueryInterfaceSettings(usb, 0, &descriptor)) error = GetLastError(); /* Не предполагает, что произвольный WinUSB-интерфейс поддерживает DFU. */
+        if (!error && (descriptor.bInterfaceClass != 0xFE || descriptor.bInterfaceSubClass != 1 || descriptor.bInterfaceProtocol != 1)) error = ERROR_NOT_SUPPORTED; /* Проверяет класс приложения, подкласс DFU и runtime-протокол по DFU 1.1. */
+        ULONG timeout = 500, transferred = 0; /* Ограничивает управляющий USB-запрос 500 миллисекундами и учитывает длину ответа. */
+        if (!error && !WinUsb_SetPipePolicy(usb, 0, PIPE_TRANSFER_TIMEOUT, sizeof(timeout), &timeout)) error = GetLastError(); /* Устанавливает тайм-аут endpoint 0, чтобы отсутствующий ответ не блокировал программу. */
+        WINUSB_SETUP_PACKET packet = {0}; /* Обнуляет поля USB SETUP перед запросом перехода в загрузчик. */
+        packet.RequestType = 0x21; packet.Request = 0; packet.Value = 1000; packet.Index = descriptor.bInterfaceNumber; /* DFU_DETACH: class/interface OUT, запрос 0, ожидаемое время отключения 1000 мс. */
+        if (!error && !WinUsb_ControlTransfer(usb, packet, NULL, 0, &transferred, NULL)) error = GetLastError(); /* Отправляет DETACH и требует подтверждённой USB-транзакции. */
+        packet.RequestType = 0xA1; packet.Request = 3; packet.Value = 0; packet.Length = 6; /* DFU_GETSTATUS: class/interface IN, запрос 3, ответ ровно 6 байт по DFU 1.1. */
+        if (!error && !WinUsb_ControlTransfer(usb, packet, status, 6, &transferred, NULL)) error = GetLastError(); /* Проверяет результат до отложенного перехода прошивки через 300 мс. */
+        if (!error && transferred != 6) error = ERROR_INVALID_DATA; /* Не трактует укороченный ответ как подтверждение входа в загрузчик. */
+        if (usb) WinUsb_Free(usb); /* Освобождает WinUSB до появления загрузчика с другим VID/PID. */
+        CloseHandle(file); /* Освобождает файловый дескриптор после успеха и при любой ошибке USB. */
+        break; /* Не отправляет DETACH повторно и не переключается на другой адаптер при отказе. */
+    } /* Завершает поиск и обработку единственного выбранного адаптера. */
+    SetupDiDestroyDeviceInfoList(devices); /* Освобождает перечень интерфейсов при любом результате. */
+    return error; /* Статус прошивки возвращается отдельно от системной ошибки USB. */
+} /* Завершает управление DFU runtime без записи flash или изменения образа. */

 static bool candle_dev_interal_open(candle_handle hdev);

@@ -650,6 +736,30 @@ bool __stdcall DLL candle_dev_open(candle_handle hdev)

 }

+bool __stdcall DLL candle_dev_get_product(candle_handle hdev, wchar_t *product, uint32_t capacity) /* Читает USB Product String открытого адаптера в буфер UTF-16; capacity измеряется в wchar_t, включая завершающий ноль. */
+{ /* Начало чтения отображаемого имени без изменения режима CAN. */
+    if (!product || !capacity) return false; /* Не пишет в отсутствующий либо пустой выходной буфер. */
+    product[0] = 0; /* Сохраняет пустую строку при любом отказе чтения дескриптора. */
+    candle_device_t *dev = (candle_device_t*)hdev; /* Получает уже открытый WinUSB-сеанс выбранного физического адаптера. */
+    if (!dev || !dev->winUSBHandle) return false; /* Не открывает устройство заново и не обращается к закрытому интерфейсу. */
+    USB_DEVICE_DESCRIPTOR descriptor = {0}; /* Получает индекс строки продукта из стандартного дескриптора устройства. */
+    ULONG received = 0; /* Хранит фактически полученное количество байтов управляющего ответа. */
+    if (!WinUsb_GetDescriptor(dev->winUSBHandle, 1, 0, 0, (PUCHAR)&descriptor, sizeof(descriptor), &received) || received != sizeof(descriptor)) return false; /* Тип 1 обозначает Device Descriptor по USB 2.0; неполный ответ не используется. */
+    UCHAR string_index = descriptor.iProduct; /* Для обычных адаптеров использует объявленный устройством индекс USB Product String. */
+    if (descriptor.idVendor == 0x1D50 && descriptor.idProduct == 0x606F) string_index = 2; /* В CANable Candlelight имя продукта имеет индекс 2; WinUSB может подменять iProduct индексом имени интерфейса, как описано в штатном примере проекта. */
+    if (!string_index) return false; /* Нулевой iProduct означает, что устройство не предоставляет имя продукта. */
+    UCHAR raw[256] = {0}; /* Буфер вмещает строковый дескриптор USB, чей однобайтовый bLength ограничен 255 байтами. */
+    USHORT language = 0x0409; /* Использует английский идентификатор USB как резервный вариант для устройств без списка языков. */
+    if (WinUsb_GetDescriptor(dev->winUSBHandle, 3, 0, 0, raw, sizeof(raw), &received) && received >= 4 && raw[0] >= 4 && raw[1] == 3) language = (USHORT)(raw[2] | ((USHORT)raw[3] << 8)); /* Тип 3 и индекс 0 возвращают список LANGID; выбирает первый язык, предоставленный адаптером. */
+    if (!WinUsb_GetDescriptor(dev->winUSBHandle, 3, string_index, language, raw, sizeof(raw), &received)) return false; /* Читает именно строку продукта на поддерживаемом устройством языке. */
+    if (received < 2 || raw[1] != 3 || raw[0] < 2 || raw[0] > received || (raw[0] & 1)) return false; /* Проверяет тип, размер и чётное число байтов UTF-16 перед копированием в выходной буфер. */
+    uint32_t count = (raw[0] - 2) / 2; /* Исключает двухбайтовый заголовок и переводит длину UTF-16LE из байтов в число кодовых единиц. */
+    if (count >= capacity) return false; /* Не обрезает индивидуальный номер в конце имени и оставляет место для завершающего нуля. */
+    for (uint32_t index = 0; index < count; ++index) product[index] = (wchar_t)(raw[2 + index * 2] | ((USHORT)raw[3 + index * 2] << 8)); /* Явно собирает кодовые единицы UTF-16LE без предположений о выравнивании массива байтов. */
+    product[count] = 0; /* Завершает строку для безопасного чтения через ctypes и отображения в Qt. */
+    return count > 0; /* Пустое имя оставляет интерфейсу стандартную резервную подпись адаптера. */
+} /* Завершает получение настоящего имени из прошивки USB-адаптера. */
+
 bool __stdcall DLL candle_dev_get_timestamp_us(candle_handle hdev, uint32_t *timestamp_us)
 {
 	return candle_ctrl_get_timestamp(hdev, timestamp_us);
@@ -817,6 +927,38 @@ bool __stdcall DLL candle_channel_stop(candle_handle hdev, uint8_t ch)
    return candle_ctrl_set_device_mode(dev, ch, CANDLE_DEVMODE_RESET, 0);
 }

+bool __stdcall DLL candle_channel_start_configured(candle_handle hdev, uint8_t ch, uint32_t flags) /* Новый вход сохраняет прежний ABI start и позволяет отключать HW_TIMESTAMP. */
+{ /* Явно выбранные Python-флаги должны попасть в прошивку без автоматического дополнения. */
+    return candle_ctrl_set_device_mode((candle_device_t*)hdev, ch, CANDLE_DEVMODE_START, flags); /* Передаём точную маску после проверки возможностей на уровне транспорта. */
+} /* Завершение запуска с явно заданными параметрами. */
+
+bool __stdcall DLL candle_channel_get_data_capabilities(candle_handle hdev, uint8_t ch, candle_capability_t *cap) /* Экспортируем чтение FD-пределов для расчёта тайминга на любой частоте CAN. */
+{ /* Общая форма capability позволяет повторно использовать валидатор номинального тайминга. */
+    return candle_ctrl_data_capability((candle_device_t*)hdev, ch, cap); /* USB-запрос возвращает реальные пределы выбранного канала. */
+} /* Завершение получения возможностей быстрой фазы. */
+
+bool __stdcall DLL candle_channel_set_termination(candle_handle hdev, uint8_t ch, uint32_t state) /* Значения 0 и 1 соответствуют OFF и ON стандарта gs_usb. */
+{ /* Проверка исключает отправку неопределённого состояния в прошивку. */
+    return state <= 1 && candle_ctrl_termination((candle_device_t*)hdev, ch, &state, true); /* Выполняем запись только для допустимого состояния. */
+} /* Завершение переключения терминатора. */
+
+bool __stdcall DLL candle_channel_get_termination(candle_handle hdev, uint8_t ch, uint32_t *state) /* Чтение состояния не меняет топологию CAN. */
+{ /* Используем тот же формат 32-битного значения, что и при записи. */
+    return candle_ctrl_termination((candle_device_t*)hdev, ch, state, false); /* false выбирает USB_DIR_IN и GET_TERMINATION. */
+} /* Завершение чтения терминатора. */
+
+bool __stdcall DLL candle_channel_get_diagnostics(candle_handle hdev, uint8_t ch, uint32_t *state, uint32_t *rxerr, uint32_t *txerr) /* Сохраняем счётчики, которые старый get_state отбрасывал. */
+{ /* Диагностика выполняется только для уже открытого устройства. */
+    candle_device_state_t data = {0}; /* Полная структура протокола содержит три слова: состояние, RX и TX. */
+    if (!candle_ctrl_get_state((candle_device_t*)hdev, ch, &data)) { /* Не возвращаем нулевые счётчики как будто запрос был успешным. */
+        return false; /* Причина USB-отказа уже записана управляющим запросом. */
+    } /* Дальнейшее копирование относится только к подтверждённому ответу. */
+    *state = data.state; /* Сохраняем состояние Error-active, Warning, Passive, Bus-off, Stopped или Sleeping. */
+    *rxerr = data.rxerr; /* Счётчик ошибок приёма измеряется в единицах CAN-контроллера. */
+    *txerr = data.txerr; /* Счётчик ошибок передачи помогает отличать отсутствие ACK от ошибок приёма. */
+    return true; /* Все три выходных значения относятся к одному USB-ответу. */
+} /* Завершение расширенной диагностики канала. */
+
 /* Write len bytes from buf to the OUT pipe, aborting after 300 ms.
 * Writes are serialised by writeMutex in CandleApiInterface so dev->txEvent
 * is never accessed by two threads simultaneously. */
@@ -1011,14 +1153,13 @@ bool __stdcall DLL candle_fd_frame_read(candle_handle hdev, candle_fd_frame_t *f
    }
    dev->rxurbs[urb_num].pending = false;

-    /* Minimum: classic CAN header (12 bytes) + at least 8 data bytes = 20 bytes */
-    static const DWORD classic_min = sizeof(candle_frame_t) - 4;
-    if (bytes_transfered < classic_min) {
+    const DWORD header_size = 12; /* Заголовок gs_usb занимает 12 байт в Classic и FD; короткий FD может не содержать восьми байтов данных. */
+    if (bytes_transfered < header_size) { /* До чтения flags и DLC проверяем наличие полного заголовка. */
        candle_prepare_read(dev, urb_num);
        candle_logf(L"fd read too small urb=%u bytes=%lu min=%lu",
                    urb_num,
                    bytes_transfered,
-                    classic_min);
+                    header_size); /* Минимальная длина здесь относится к заголовку, а payload проверяется после определения формата. */
        dev->last_error = CANDLE_ERR_READ_SIZE;
        return false;
    }
@@ -1041,6 +1182,11 @@ bool __stdcall DLL candle_fd_frame_read(candle_handle hdev, candle_fd_frame_t *f
    if (is_fd_frame) {
        /* can_dlc is at byte offset 8 in both classic and FD wire frames. */
        const uint8_t raw_dlc = dev->rxurbs[urb_num].buf[8];
+        if (raw_dlc > 15) { /* FD DLC является четырёхбитным кодом и не может содержать значения выше 15. */
+            candle_prepare_read(dev, urb_num); /* Повреждённый USB-пакет не должен останавливать последующий приём. */
+            dev->last_error = CANDLE_ERR_READ_SIZE; /* Неверный DLC считается ошибкой формата входного кадра. */
+            return false; /* Не превращаем повреждённый DLC в пустой успешный FD-кадр. */
+        } /* Далее длина безопасно вычисляется по таблице CAN FD. */
        const DWORD data_len  = candle_dlc_to_len(raw_dlc);
        const DWORD min_size  = 12 + data_len; /* header + data, without timestamp */

@@ -1071,6 +1217,11 @@ bool __stdcall DLL candle_fd_frame_read(candle_handle hdev, candle_fd_frame_t *f
        }
        /* else: timestamp stays zero from memset above */
    } else {
+        if (bytes_transfered < sizeof(candle_frame_t) - sizeof(uint32_t)) { /* Classic-пакет обязан содержать весь восьмибайтовый буфер данных, даже при меньшем DLC. */
+            candle_prepare_read(dev, urb_num); /* Возобновляем соответствующий URB после отклонения неполного пакета. */
+            dev->last_error = CANDLE_ERR_READ_SIZE; /* Не допускаем чтение неполученных данных из локальной структуры. */
+            return false; /* Повреждённый Classic-пакет не попадает в Python через FD API. */
+        } /* Минимальный размер Classic теперь проверен отдельно от коротких FD. */
        /* Classic CAN frame — copy into FD struct, fixing the timestamp position */
        candle_frame_t classic;
        DWORD copy_len = (bytes_transfered < sizeof(classic)) ? bytes_transfered : sizeof(classic);
@@ -1,4 +1,10 @@
+; Доступ к CAN-адаптерам candleLight/gs_usb в Windows через WinUSB. Перечисление устройств,
+; открытие канала и обмен кадрами образуют отдельный транспортный слой; он не интерпретирует
+; прикладные регистры SETProtocol.
+
 EXPORTS
+    candle_dev_get_product ; Имя продукта из USB-дескриптора прошивки для списка адаптеров SETGUI.
+    candle_dev_enter_dfu ; Переход через отдельный DFU runtime-интерфейс того же физического USB-адаптера.
    candle_list_scan
    candle_list_free
    candle_list_length
@@ -27,3 +33,13 @@ EXPORTS
    candle_frame_data
    candle_frame_timestamp_us
    candle_dev_last_error
+    candle_channel_start_configured ; Точная маска запуска с управляемыми аппаратными метками.
+    candle_channel_get_data_capabilities ; Пределы тайминга быстрой фазы CAN FD.
+    candle_channel_set_termination ; Переключение встроенного терминатора.
+    candle_channel_get_termination ; Чтение состояния встроенного терминатора.
+    candle_channel_get_diagnostics ; Состояние и счётчики ошибок CAN.
+    candle_channel_set_data_timing ; Тайминг фазы данных CAN FD.
+    candle_fd_frame_send ; Отправка полного кадра CAN FD до 64 байт.
+    candle_fd_frame_read ; Приём FD и Classic без обрезания данных.
+    candle_fd_frame_type ; Различение RX, TX echo и ошибок FD.
+    candle_fd_frame_id ; Получение CAN ID из структуры FD.
@@ -20,6 +20,12 @@

 */

+/*
+ * Доступ к CAN-адаптерам candleLight/gs_usb в Windows через WinUSB. Перечисление устройств,
+ * открытие канала и обмен кадрами образуют отдельный транспортный слой; он не интерпретирует
+ * прикладные регистры SETProtocol.
+ */
+
 #pragma once
 #include <stdint.h>
 #include <stdbool.h>
@@ -240,7 +246,9 @@ bool __stdcall DLL candle_list_length(candle_list_handle list, uint8_t *len);
 bool __stdcall DLL candle_dev_get(candle_list_handle list, uint8_t dev_num, candle_handle *hdev);
 bool __stdcall DLL candle_dev_get_state(candle_handle hdev, candle_devstate_t *state);
 wchar_t * __stdcall DLL candle_dev_get_path(candle_handle hdev);
+bool __stdcall DLL candle_dev_get_product(candle_handle hdev, wchar_t *product, uint32_t capacity); /* Возвращает USB Product String в UTF-16; capacity включает завершающий ноль и измеряется в wchar_t. */
 bool __stdcall DLL candle_dev_open(candle_handle hdev);
+uint32_t __stdcall DLL candle_dev_enter_dfu(const wchar_t *can_path, uint8_t status[6]); /* Переводит выбранный физический адаптер в DFU и возвращает Win32-код плюс ответ DFU_GETSTATUS. */
 bool __stdcall DLL candle_dev_get_timestamp_us(candle_handle hdev, uint32_t *timestamp_us);
 bool __stdcall DLL candle_dev_close(candle_handle hdev);
 bool __stdcall DLL candle_dev_free(candle_handle hdev);
@@ -253,6 +261,11 @@ bool __stdcall DLL candle_channel_set_timing(candle_handle hdev, uint8_t ch, can
 bool __stdcall DLL candle_channel_set_bitrate(candle_handle hdev, uint8_t ch, uint32_t bitrate);
 bool __stdcall DLL candle_channel_start(candle_handle hdev, uint8_t ch, uint32_t flags);
 bool __stdcall DLL candle_channel_stop(candle_handle hdev, uint8_t ch);
+bool __stdcall DLL candle_channel_start_configured(candle_handle hdev, uint8_t ch, uint32_t flags); /* Запускаем с точной маской без принудительного включения аппаратных меток. */
+bool __stdcall DLL candle_channel_get_data_capabilities(candle_handle hdev, uint8_t ch, candle_capability_t *cap); /* Возвращаем пределы тайминга быстрой фазы FD. */
+bool __stdcall DLL candle_channel_set_termination(candle_handle hdev, uint8_t ch, uint32_t state); /* Состояние терминатора: 0 — выключен, 1 — включён. */
+bool __stdcall DLL candle_channel_get_termination(candle_handle hdev, uint8_t ch, uint32_t *state); /* Чтение не меняет подключение встроенного резистора. */
+bool __stdcall DLL candle_channel_get_diagnostics(candle_handle hdev, uint8_t ch, uint32_t *state, uint32_t *rxerr, uint32_t *txerr); /* Передаём состояние CAN и оба счётчика ошибок без потери данных ответа. */

 bool __stdcall DLL candle_frame_send(candle_handle hdev, uint8_t ch, candle_frame_t *frame);
 bool __stdcall DLL candle_frame_read(candle_handle hdev, candle_frame_t *frame, uint32_t timeout_ms);
@@ -19,6 +19,11 @@

 */

+/*
+ * Управляющие USB-запросы адаптера candleLight: конфигурация, временные параметры CAN и режим
+ * канала. Эти транзакции идут через control endpoint и отличаются от потока CAN-кадров.
+ */
+
 #include "candle_ctrl_req.h"
 #include "ch_9.h"

@@ -34,8 +39,10 @@ enum {
    CANDLE_TIMESTAMP_GET       = 6,
    /* 7: IDENTIFY, 8: GET_USER_ID, 9: SET_USER_ID (not used here) */
    CANDLE_BREQ_DATA_BITTIMING = 10,
-    /* 11: SET_TERMINATION, not used here */
-    CANDLE_BREQ_GET_STATE      = 12,
+    CANDLE_BREQ_BT_CONST_EXT   = 11, /* Расширенные пределы номинальной и быстрой фазы согласно gs_usb. */
+    CANDLE_BREQ_SET_TERMINATION = 12, /* Запрос gs_usb 12 переключает встроенный резистор окончания шины. */
+    CANDLE_BREQ_GET_TERMINATION = 13, /* Запрос gs_usb 13 читает текущее состояние терминатора. */
+    CANDLE_BREQ_GET_STATE      = 14, /* Стандартный GET_STATE имеет номер 14; номер 12 принадлежит терминатору. */
    CANDLE_BREQ_BUS_OFF_RECOVERY = 32,
 };

@@ -232,3 +239,22 @@ bool candle_ctrl_bus_off_recover(candle_device_t *dev, uint8_t channel)
    dev->last_error = rc ? CANDLE_ERR_OK : CANDLE_ERR_SET_DEVICE_MODE;
    return rc;
 }
+
+bool candle_ctrl_data_capability(candle_device_t *dev, uint8_t channel, candle_capability_t *cap) /* Структура gs_usb BT_CONST_EXT содержит десять общих и восемь быстрых полей uint32. */
+{ /* Используем массив, поскольку протокол содержит только однородные 32-битные значения без отступов. */
+    uint32_t fields[18] = {0}; /* 18 полей по 4 байта образуют стандартный ответ размером 72 байта. */
+    bool rc = usb_control_msg(dev->winUSBHandle, CANDLE_BREQ_BT_CONST_EXT, USB_DIR_IN|USB_TYPE_VENDOR|USB_RECIP_INTERFACE, channel, 0, fields, sizeof(fields)); /* Запрашиваем пределы именно выбранного CAN-канала. */
+    if (rc) { /* Выходная структура должна меняться только после успешного USB-ответа. */
+        memcpy(cap, fields, 2 * sizeof(uint32_t)); /* Маска функций и частота CAN общие для обеих фаз. */
+        memcpy(&cap->tseg1_min, &fields[10], 8 * sizeof(uint32_t)); /* Поля DTSEG1…DBRP_INC заменяют номинальные пределы структуры capability. */
+    } /* При отказе вызывающий код получит false и не использует нулевые пределы. */
+    dev->last_error = rc ? CANDLE_ERR_OK : CANDLE_ERR_GET_BITTIMING_CONST; /* Сохраняем диагностический код чтения аппаратных ограничений. */
+    return rc; /* Успех означает наличие полной структуры пределов быстрой фазы. */
+} /* Завершение запроса расширенных возможностей FD. */
+
+bool candle_ctrl_termination(candle_device_t *dev, uint8_t channel, uint32_t *state, bool write) /* Переключение терминатора использует стандартные SET=12 и GET=13. */
+{ /* Состояние передаётся одним 32-битным словом согласно протоколу gs_usb. */
+    bool rc = usb_control_msg(dev->winUSBHandle, write ? CANDLE_BREQ_SET_TERMINATION : CANDLE_BREQ_GET_TERMINATION, (write ? USB_DIR_OUT : USB_DIR_IN)|USB_TYPE_VENDOR|USB_RECIP_INTERFACE, channel, 0, state, sizeof(*state)); /* Номер CAN-канала передаётся в wValue, а wIndex равен нулю по спецификации. */
+    dev->last_error = rc ? CANDLE_ERR_OK : CANDLE_ERR_SET_DEVICE_MODE; /* Ошибка настройки доступна Python через candle_dev_last_error. */
+    return rc; /* Не выдаём успешное переключение при отказе USB-контроллера. */
+} /* Завершение управления встроенным окончанием шины. */
@@ -20,6 +20,11 @@

 */

+/*
+ * Управляющие USB-запросы адаптера candleLight: конфигурация, временные параметры CAN и режим
+ * канала. Эти транзакции идут через control endpoint и отличаются от потока CAN-кадров.
+ */
+
 #pragma once

 #include "candle_defs.h"
@@ -46,4 +51,6 @@ bool candle_ctrl_set_data_bittiming(candle_device_t *dev, uint8_t channel, candl
 bool candle_ctrl_get_timestamp(candle_device_t *dev, uint32_t *current_timestamp);
 bool candle_ctrl_get_state(candle_device_t *dev, uint8_t channel, candle_device_state_t *data);
 bool candle_ctrl_bus_off_recover(candle_device_t *dev, uint8_t channel);
+bool candle_ctrl_data_capability(candle_device_t *dev, uint8_t channel, candle_capability_t *cap); /* Читаем пределы быстрой фазы CAN FD отдельным запросом расширенной структуры. */
+bool candle_ctrl_termination(candle_device_t *dev, uint8_t channel, uint32_t *state, bool write); /* Передаём состояние терминатора: 0 — выключен, 1 — включён. */

@@ -20,6 +20,12 @@

 */

+/*
+ * Двоичные структуры и константы gs_usb, общие для драйвера и USB-адаптера. Размеры полей и
+ * упаковка определяют совместимость с прошивкой: менять их как обычные внутренние структуры
+ * нельзя.
+ */
+
 #pragma once

 #include <stdint.h>
@@ -19,6 +19,11 @@

 */

+/*
+ * Типы стандартных USB-дескрипторов и запросов из главы 9 спецификации USB. Драйвер использует
+ * их для описания устройства и конечных точек; это транспортные определения, а не формат CAN.
+ */
+
 #pragma once

 #define USB_DIR_OUT                     0               /* to device */
@@ -1,3 +1,7 @@
+# Сборка библиотеки ds18b20_ds2480. Состав исходников и публичные include-пути задают
+# подключение к проекту потребителя. Файл также собирает и регистрирует хостовые проверки;
+# запускать их следует через CTest из каталога сборки.
+
 cmake_minimum_required(VERSION 3.13)
 project(ds18b20_ds2480 C)
 add_library(ds18b20_ds2480 STATIC ds2480.c ds18b20_ds2480.c)
@@ -1,3 +1,9 @@
+/*
+ * Команды DS18B20 поверх интерфейса DS2480B: адресация ROM, преобразование температуры и
+ * scratchpad. Транспортный статус следует проверять до использования результата; сырая
+ * температура сохраняет знаковое представление датчика.
+ */
+
 #include "ds18b20_ds2480.h"
 #include <string.h>

@@ -1,3 +1,9 @@
+/*
+ * Команды DS18B20 поверх интерфейса DS2480B: адресация ROM, преобразование температуры и
+ * scratchpad. Транспортный статус следует проверять до использования результата; сырая
+ * температура сохраняет знаковое представление датчика.
+ */
+
 #ifndef DS18B20_DS2480_H
 #define DS18B20_DS2480_H
 #include "ds2480.h"
@@ -1,3 +1,9 @@
+/*
+ * UART-мост DS2480B для операций 1-Wire: сброс, обмен битами и байтами, поиск устройств и
+ * управление питанием. После ошибки связи состояние готовности сбрасывается, чтобы следующий
+ * обмен не продолжался в неизвестном режиме моста.
+ */
+
 #include "ds2480.h"

 static ds2480_status fault(ds2480 *bus, ds2480_status status)
@@ -1,3 +1,9 @@
+/*
+ * UART-мост DS2480B для операций 1-Wire: сброс, обмен битами и байтами, поиск устройств и
+ * управление питанием. После ошибки связи состояние готовности сбрасывается, чтобы следующий
+ * обмен не продолжался в неизвестном режиме моста.
+ */
+
 #ifndef DS2480_H
 #define DS2480_H

@@ -1,3 +1,9 @@
+/*
+ * Минимальный блокирующий пример: подготовить мост DS2480B, найти первый датчик, запустить
+ * преобразование и прочитать температуру. Обратные вызовы UART и задержек предоставляет плата;
+ * ожидание преобразования входит во время вызова.
+ */
+
 #include "ds18b20_ds2480.h"

 /* board_port supplies the four callbacks documented in ds2480.h.
@@ -1,3 +1,9 @@
+/*
+ * UART-порт DS2480B для STM32F4. Подготовка линии и очистка ошибок USART отделены от команд
+ * датчика; после сбоя обмена мост должен пройти предусмотренное восстановление до продолжения
+ * работы с 1-Wire.
+ */
+
 #include "ds2480_stm32f4_hal.h"

 #define RX_ERRORS (USART_SR_ORE | USART_SR_NE | USART_SR_FE | USART_SR_PE)
@@ -1,3 +1,9 @@
+/*
+ * UART-порт DS2480B для STM32F4. Подготовка линии и очистка ошибок USART отделены от команд
+ * датчика; после сбоя обмена мост должен пройти предусмотренное восстановление до продолжения
+ * работы с 1-Wire.
+ */
+
 #ifndef DS2480_STM32F4_HAL_H
 #define DS2480_STM32F4_HAL_H

@@ -1,3 +1,11 @@
+/*
+ * Проверки stm32f4xx_hal: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+ * Сценарии для навигации по файлу:
+ *   test_clear
+ * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+ * настройками рабочего устройства.
+ */
+
 /* Host-only HAL model, never add this directory to a firmware include path. */
 #ifndef TEST_STM32F4_HAL_H
 #define TEST_STM32F4_HAL_H
@@ -1,3 +1,11 @@
+/*
+ * Проверки port: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+ * Сценарии для навигации по файлу:
+ *   test_clear
+ * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+ * настройками рабочего устройства.
+ */
+
 #include "ds2480_stm32f4_hal.h"
 #include <assert.h>
 #include <stdio.h>
@@ -1,3 +1,9 @@
+/*
+ * Проверки ds18b20_ds2480: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+ * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+ * настройками рабочего устройства.
+ */
+
 #include "ds18b20_ds2480.h"
 #include <stdio.h>
 #include <stdlib.h>
@@ -1,3 +1,7 @@
+# Сборка библиотеки ds18b20. Состав исходников и публичные include-пути задают подключение к
+# проекту потребителя. Файл также собирает и регистрирует хостовые проверки; запускать их
+# следует через CTest из каталога сборки.
+
 cmake_minimum_required(VERSION 3.13)
 project(ds18b20 C)

@@ -1,3 +1,9 @@
+/*
+ * Работа с термометрами DS18B20: поиск по ROM, запуск преобразования, чтение температуры и
+ * настройка scratchpad. ROM является адресом устройства на общей шине; результат чтения нельзя
+ * считать действительным до проверки статуса обмена и CRC.
+ */
+
 /**
 * @file ds18b20.h
 * @brief Драйвер термометров DS18B20 поверх шины 1-Wire.
@@ -1,3 +1,9 @@
+/*
+ * Общие операции 1-Wire и обход дерева 64-битных ROM. Поиск разрешает коллизии побитно,
+ * поэтому обнаружение нескольких устройств не сводится к чтению одного адреса. Электрические
+ * уровни и длительности импульсов задаёт порт.
+ */
+
 /**
 * @file onewire.h
 * @brief Программная шина 1-Wire на выводе с открытым стоком.
@@ -1,3 +1,7 @@
+# Сборка библиотеки ds18b20_instance. Состав исходников и публичные include-пути задают
+# подключение к проекту потребителя. Файл также собирает и регистрирует хостовые проверки;
+# запускать их следует через CTest из каталога сборки.
+
 cmake_minimum_required(VERSION 3.13)
 project(ds18b20_instance C)
 add_library(ds18b20_instance STATIC Src/ds18b20.c)
@@ -1,3 +1,9 @@
+/*
+ * Работа с термометрами DS18B20: поиск по ROM, запуск преобразования, чтение температуры и
+ * настройка scratchpad. ROM является адресом устройства на общей шине; результат чтения нельзя
+ * считать действительным до проверки статуса обмена и CRC.
+ */
+
 #ifndef PORTABLE_DS18B20_H
 #define PORTABLE_DS18B20_H

@@ -1,3 +1,9 @@
+/*
+ * Конфигурация ds18b20. Макросы задают параметры сборки и ограничения, используемые
+ * исходниками этого модуля. Смысл и единицы каждого параметра определяются местом его
+ * использования; размеры буферов должны быть согласованы у всех потребителей заголовка.
+ */
+
 #ifndef PORTABLE_DS18B20_CONFIG_H
 #define PORTABLE_DS18B20_CONFIG_H
 #define DS18B20_DEFAULT_TIMEOUT_MS 750U
@@ -1,3 +1,9 @@
+/*
+ * Работа с термометрами DS18B20: поиск по ROM, запуск преобразования, чтение температуры и
+ * настройка scratchpad. ROM является адресом устройства на общей шине; результат чтения нельзя
+ * считать действительным до проверки статуса обмена и CRC.
+ */
+
 #include "ds18b20.h"
 #include "ds18b20_config.h"
 #include <string.h>
@@ -1,3 +1,7 @@
+# Сборка и запуск хостовых проверок экземплярного DS18B20. Скрипт готовит исполняемые тесты
+# для проверки поиска ROM и задержек EEPROM без платы; ошибка компиляции или проверки должна
+# завершить прогон неуспешно.
+
 $ErrorActionPreference = "Stop"
 $out = Join-Path $env:TEMP "test_ds18b20_copy_delay.exe"
 $test = Join-Path $PSScriptRoot "test_ds18b20_copy_delay.c"
@@ -1,3 +1,10 @@
+/*
+ * Проверки ds18b20_copy_delay: фиксируют ожидаемое поведение на воспроизводимых входных
+ * данных.
+ * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+ * настройками рабочего устройства.
+ */
+
 #include "ds18b20.h"

 #include <assert.h>
@@ -1,3 +1,10 @@
+/*
+ * Проверки ds18b20_incremental_search: фиксируют ожидаемое поведение на воспроизводимых
+ * входных данных.
+ * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+ * настройками рабочего устройства.
+ */
+
 /* Model real SEARCH ROM participation: each branch filters the active slaves.
 * Fault injection tests transport recovery, not analog cable characteristics. */
 #include "ds18b20.h"
@@ -1,3 +1,9 @@
+/*
+ * Конфигурация ds18b20 для порта stm32f1. Макросы задают параметры сборки и ограничения,
+ * используемые исходниками этого модуля. Это образец для проекта: значения выводов, размеров
+ * памяти и параметров устройства необходимо согласовать с целевой платой.
+ */
+
 /**
 * @file onewire_config.f103.template.h
 * @brief Шаблон привязки шины 1-Wire для STM32F103 (порт stm32f1).
@@ -1,3 +1,9 @@
+/*
+ * Аппаратные временные слоты 1-Wire на STM32F1: управление линией, чтение уровня и
+ * микросекундные задержки. Конфигурация выбирает GPIO и таймер; общий алгоритм поиска ROM
+ * остаётся в onewire.c.
+ */
+
 /**
 * @file onewire_stm32f1.c
 * @brief Порт шины 1-Wire на STM32F1: тайминги, вывод и задержки.
--- a/Show More
+++ b/Show More