Support shared serial ports and optional verification in TMS flashing

Reviewed-on: #4

Doxyfile

@@ -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

NEW_PROJECT.md

@@ -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
+```

README.md

@@ -48,6 +48,10 @@ templates/
 
 ### 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+ |
@@ -72,6 +76,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 +90,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).
+
 Дальше в сборку добавляются только нужные каталоги:
 
 ```

c/can-sensor/CMakeLists.txt

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

c/can-sensor/can_sensor.c

@@ -1,3 +1,9 @@
+/*
+ * Обмен настройками датчиков DS18B20 через однокадровые сообщения SETCAN. ROM идентифицирует
+ * датчик независимо от его позиции; прикладное состояние и отправка CAN предоставляются через
+ * интерфейс библиотеки.
+ */
+
 /**
  * @file can_sensor.c
  * @brief Однокадровый транспорт SETCAN SETTINGS для локаций DS18B20.

c/can-sensor/can_sensor.h

@@ -1,3 +1,9 @@
+/*
+ * Обмен настройками датчиков DS18B20 через однокадровые сообщения SETCAN. ROM идентифицирует
+ * датчик независимо от его позиции; прикладное состояние и отправка CAN предоставляются через
+ * интерфейс библиотеки.
+ */
+
 /**
  * @file can_sensor.h
  * @brief Портируемый транспорт SETTINGS для привязки DS18B20 к локации.

c/can-sensor/ports/stm32f1/can_sensor_stm32f1.c

@@ -1,3 +1,9 @@
+/*
+ * Прямой bxCAN-порт датчиков для STM32F1 без HAL. Регистры контроллера обеспечивают передачу и
+ * приём SETCAN, а конфигурация платы задаёт подключение шины; это аппаратная реализация
+ * интерфейса can_sensor.
+ */
+
 /**
  * @file can_sensor_stm32f1.c
  * @brief Опросный порт can-sensor на bxCAN STM32F1 без STM32 HAL.

c/can-sensor/ports/stm32f1/can_sensor_stm32f1.h

@@ -1,3 +1,9 @@
+/*
+ * Прямой bxCAN-порт датчиков для STM32F1 без HAL. Регистры контроллера обеспечивают передачу и
+ * приём SETCAN, а конфигурация платы задаёт подключение шины; это аппаратная реализация
+ * интерфейса can_sensor.
+ */
+
 /**
  * @file can_sensor_stm32f1.h
  * @brief Опросный порт can-sensor на bxCAN микроконтроллеров STM32F1.

c/can-sensor/ports/stm32f1/can_sensor_stm32f1_config.f103.template.h

@@ -1,3 +1,9 @@
+/*
+ * Конфигурация can-sensor для порта stm32f1. Макросы задают параметры сборки и ограничения,
+ * используемые исходниками этого модуля. Это образец для проекта: значения выводов, размеров
+ * памяти и параметров устройства необходимо согласовать с целевой платой.
+ */
+
 /**
  * @file can_sensor_stm32f1_config.f103.template.h
  * @brief Шаблон выводов CAN1 для STM32F103 без ремапа.

c/can-sensor/tests/test_can_sensor.c

@@ -1,3 +1,9 @@
+/*
+ * Проверки can_sensor: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+ * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+ * настройками рабочего устройства.
+ */
+
 #include "can_sensor.h"
 
 #include <stdio.h>

c/candle/CMakeLists.txt

@@ -1,3 +1,7 @@
+# Сборка библиотеки candle. Состав исходников и публичные include-пути задают подключение к
+# проекту потребителя. Платформенные зависимости и условия сборки задаются здесь, а не в
+# прикладных исходниках.
+
 cmake_minimum_required(VERSION 3.15)
 project(candle C)
 if(NOT WIN32)

c/candle/candle.c

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

c/candle/candle.def

@@ -1,3 +1,7 @@
+; Доступ к CAN-адаптерам candleLight/gs_usb в Windows через WinUSB. Перечисление устройств,
+; открытие канала и обмен кадрами образуют отдельный транспортный слой; он не интерпретирует
+; прикладные регистры SETProtocol.
+
 EXPORTS
     candle_list_scan
     candle_list_free

c/candle/candle.h

@@ -20,6 +20,12 @@
 
 */
 
+/*
+ * Доступ к CAN-адаптерам candleLight/gs_usb в Windows через WinUSB. Перечисление устройств,
+ * открытие канала и обмен кадрами образуют отдельный транспортный слой; он не интерпретирует
+ * прикладные регистры SETProtocol.
+ */
+
 #pragma once
 #include <stdint.h>
 #include <stdbool.h>

c/candle/candle_ctrl_req.c

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

c/candle/candle_ctrl_req.h

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

c/candle/candle_defs.h

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

c/candle/ch_9.h

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

c/ds18b20-ds2480/CMakeLists.txt

@@ -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)

c/ds18b20-ds2480/ds18b20_ds2480.c

@@ -1,3 +1,9 @@
+/*
+ * Команды DS18B20 поверх интерфейса DS2480B: адресация ROM, преобразование температуры и
+ * scratchpad. Транспортный статус следует проверять до использования результата; сырая
+ * температура сохраняет знаковое представление датчика.
+ */
+
 #include "ds18b20_ds2480.h"
 #include <string.h>
 

c/ds18b20-ds2480/ds18b20_ds2480.h

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

c/ds18b20-ds2480/ds2480.c

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

c/ds18b20-ds2480/ds2480.h

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

c/ds18b20-ds2480/examples/read_first.c

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

c/ds18b20-ds2480/ports/stm32f4/ds2480_stm32f4_hal.c

@@ -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)

c/ds18b20-ds2480/ports/stm32f4/ds2480_stm32f4_hal.h

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

c/ds18b20-ds2480/ports/stm32f4/tests/stm32f4xx_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

c/ds18b20-ds2480/ports/stm32f4/tests/test_port.c

@@ -1,3 +1,11 @@
+/*
+ * Проверки port: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+ * Сценарии для навигации по файлу:
+ *   test_clear
+ * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+ * настройками рабочего устройства.
+ */
+
 #include "ds2480_stm32f4_hal.h"
 #include <assert.h>
 #include <stdio.h>

c/ds18b20-ds2480/tests/test_ds18b20_ds2480.c

@@ -1,3 +1,9 @@
+/*
+ * Проверки ds18b20_ds2480: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+ * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+ * настройками рабочего устройства.
+ */
+
 #include "ds18b20_ds2480.h"
 #include <stdio.h>
 #include <stdlib.h>

c/ds18b20/CMakeLists.txt

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

c/ds18b20/include/ds18b20.h

@@ -1,3 +1,9 @@
+/*
+ * Работа с термометрами DS18B20: поиск по ROM, запуск преобразования, чтение температуры и
+ * настройка scratchpad. ROM является адресом устройства на общей шине; результат чтения нельзя
+ * считать действительным до проверки статуса обмена и CRC.
+ */
+
 /**
  * @file ds18b20.h
  * @brief Драйвер термометров DS18B20 поверх шины 1-Wire.

c/ds18b20/include/onewire.h

@@ -1,3 +1,9 @@
+/*
+ * Общие операции 1-Wire и обход дерева 64-битных ROM. Поиск разрешает коллизии побитно,
+ * поэтому обнаружение нескольких устройств не сводится к чтению одного адреса. Электрические
+ * уровни и длительности импульсов задаёт порт.
+ */
+
 /**
  * @file onewire.h
  * @brief Программная шина 1-Wire на выводе с открытым стоком.

c/ds18b20/instance/CMakeLists.txt

@@ -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)

c/ds18b20/instance/Inc/ds18b20.h

@@ -1,3 +1,9 @@
+/*
+ * Работа с термометрами DS18B20: поиск по ROM, запуск преобразования, чтение температуры и
+ * настройка scratchpad. ROM является адресом устройства на общей шине; результат чтения нельзя
+ * считать действительным до проверки статуса обмена и CRC.
+ */
+
 #ifndef PORTABLE_DS18B20_H
 #define PORTABLE_DS18B20_H
 

c/ds18b20/instance/Inc/ds18b20_config.h

@@ -1,3 +1,9 @@
+/*
+ * Конфигурация ds18b20. Макросы задают параметры сборки и ограничения, используемые
+ * исходниками этого модуля. Смысл и единицы каждого параметра определяются местом его
+ * использования; размеры буферов должны быть согласованы у всех потребителей заголовка.
+ */
+
 #ifndef PORTABLE_DS18B20_CONFIG_H
 #define PORTABLE_DS18B20_CONFIG_H
 #define DS18B20_DEFAULT_TIMEOUT_MS 750U

c/ds18b20/instance/Src/ds18b20.c

@@ -1,3 +1,9 @@
+/*
+ * Работа с термометрами DS18B20: поиск по ROM, запуск преобразования, чтение температуры и
+ * настройка scratchpad. ROM является адресом устройства на общей шине; результат чтения нельзя
+ * считать действительным до проверки статуса обмена и CRC.
+ */
+
 #include "ds18b20.h"
 #include "ds18b20_config.h"
 #include <string.h>

c/ds18b20/instance/Tests/run_host_tests.ps1

@@ -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"

c/ds18b20/instance/Tests/test_ds18b20_copy_delay.c

@@ -1,3 +1,10 @@
+/*
+ * Проверки ds18b20_copy_delay: фиксируют ожидаемое поведение на воспроизводимых входных
+ * данных.
+ * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+ * настройками рабочего устройства.
+ */
+
 #include "ds18b20.h"
 
 #include <assert.h>

c/ds18b20/instance/Tests/test_ds18b20_incremental_search.c

@@ -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"

c/ds18b20/ports/stm32f1/onewire_config.f103.template.h

@@ -1,3 +1,9 @@
+/*
+ * Конфигурация ds18b20 для порта stm32f1. Макросы задают параметры сборки и ограничения,
+ * используемые исходниками этого модуля. Это образец для проекта: значения выводов, размеров
+ * памяти и параметров устройства необходимо согласовать с целевой платой.
+ */
+
 /**
  * @file onewire_config.f103.template.h
  * @brief Шаблон привязки шины 1-Wire для STM32F103 (порт stm32f1).

c/ds18b20/ports/stm32f1/onewire_stm32f1.c

@@ -1,3 +1,9 @@
+/*
+ * Аппаратные временные слоты 1-Wire на STM32F1: управление линией, чтение уровня и
+ * микросекундные задержки. Конфигурация выбирает GPIO и таймер; общий алгоритм поиска ROM
+ * остаётся в onewire.c.
+ */
+
 /**
  * @file onewire_stm32f1.c
  * @brief Порт шины 1-Wire на STM32F1: тайминги, вывод и задержки.

c/ds18b20/ports/stm32f4/onewire_config.f407.template.h

@@ -1,3 +1,9 @@
+/*
+ * Конфигурация ds18b20 для порта stm32f4. Макросы задают параметры сборки и ограничения,
+ * используемые исходниками этого модуля. Это образец для проекта: значения выводов, размеров
+ * памяти и параметров устройства необходимо согласовать с целевой платой.
+ */
+
 /**
  * @file onewire_config.f407.template.h
  * @brief Шаблон привязки шины 1-Wire для STM32F407VET6 (порт stm32f4).

c/ds18b20/ports/stm32f4/onewire_stm32f4.c

@@ -1,3 +1,9 @@
+/*
+ * Аппаратные временные слоты 1-Wire на STM32F4 с открытым стоком. Порт использует
+ * CMSIS-регистры и параметры onewire_config.h; частота таймера должна соответствовать расчёту
+ * задержек при обмене с датчиками.
+ */
+
 /**
  * @file onewire_stm32f4.c
  * @brief Порт шины 1-Wire на STM32F4: тайминги, вывод и задержки.

c/ds18b20/ports/stm32g4/onewire_config.g431.template.h

@@ -1,3 +1,9 @@
+/*
+ * Конфигурация ds18b20 для порта stm32g4. Макросы задают параметры сборки и ограничения,
+ * используемые исходниками этого модуля. Это образец для проекта: значения выводов, размеров
+ * памяти и параметров устройства необходимо согласовать с целевой платой.
+ */
+
 /**
  * @file onewire_config.g431.template.h
  * @brief Шаблон привязки шины 1-Wire для STM32G431 (порт stm32g4).

c/ds18b20/ports/stm32g4/onewire_config.g474.template.h

@@ -1,3 +1,9 @@
+/*
+ * Конфигурация ds18b20 для порта stm32g4. Макросы задают параметры сборки и ограничения,
+ * используемые исходниками этого модуля. Это образец для проекта: значения выводов, размеров
+ * памяти и параметров устройства необходимо согласовать с целевой платой.
+ */
+
 /**
  * @file onewire_config.g474.template.h
  * @brief Шаблон привязки шины 1-Wire для STM32G474 (порт stm32g4).

c/ds18b20/ports/stm32g4/onewire_stm32g4.c

@@ -1,3 +1,9 @@
+/*
+ * Аппаратные временные слоты 1-Wire для STM32G431/G474. GPIO и таймер задаются конфигурацией
+ * проекта; чтение уровня выполняется с линии, поэтому паразитное питание и подтяжка относятся
+ * к схеме платы.
+ */
+
 /**
  * @file onewire_stm32g4.c
  * @brief Порт шины 1-Wire на STM32G4: тайминги, вывод и задержки.

c/ds18b20/src/ds18b20.c

@@ -1,3 +1,9 @@
+/*
+ * Работа с термометрами DS18B20: поиск по ROM, запуск преобразования, чтение температуры и
+ * настройка scratchpad. ROM является адресом устройства на общей шине; результат чтения нельзя
+ * считать действительным до проверки статуса обмена и CRC.
+ */
+
 /**  test
  * @file ds18b20.c
  * @brief Реализация драйвера DS18B20: поиск, чтение и запись scratchpad.

c/ds18b20/src/onewire.c

@@ -1,3 +1,9 @@
+/*
+ * Общие операции 1-Wire и обход дерева 64-битных ROM. Поиск разрешает коллизии побитно,
+ * поэтому обнаружение нескольких устройств не сводится к чтению одного адреса. Электрические
+ * уровни и длительности импульсов задаёт порт.
+ */
+
 /**
  * @file onewire.c
  * @brief Переносимая часть шины 1-Wire: побайтовый обмен, CRC8 и поиск ROM.

c/ds18b20/tests/fake_onewire.c

@@ -1,3 +1,9 @@
+/*
+ * Проверки fake_onewire: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+ * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+ * настройками рабочего устройства.
+ */
+
 /**
  * @file fake_onewire.c
  * @brief Симулятор шины 1-Wire с виртуальными датчиками DS18B20.

c/ds18b20/tests/fake_onewire.h

@@ -1,3 +1,9 @@
+/*
+ * Проверки fake_onewire: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+ * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+ * настройками рабочего устройства.
+ */
+
 /**
  * @file fake_onewire.h
  * @brief Модель шины 1-Wire с виртуальными датчиками для host-тестов.