Add embedded storage drivers and extend firmware metadata

2026-09-27 01:44:59 +03:00
parent 795a1279b1
commit 2ad29e7ffd
52 changed files with 5801 additions and 3 deletions
--- a/c/ds18b20/instance/README.md
+++ b/c/ds18b20/instance/README.md
@@ -0,0 +1,97 @@
+# Portable DS18B20
+
+Переносимое ядро для поиска DS18B20 на шине 1-Wire, запуска преобразования,
+чтения температуры, настройки разрешения и записи alarm/user bytes. Ядро не
+зависит от STM32 HAL, не выделяет память динамически и поддерживает несколько
+независимых экземпляров шин.
+
+Подтверждённые неблокирующие операции `TH`/`TL` с Copy/Recall/readback находятся
+во внутреннем модуле `Libraries/DS18B20/Modules/UserByte`. Основной core предоставляет ему
+низкоуровневые операции scratchpad и optional callback `strong_pullup`.
+
+## Подтверждённые EEPROM-байты
+
+Официальный [datasheet Analog Devices/Maxim DS18B20](https://www.analog.com/media/en/technical-documentation/data-sheets/DS18B20.pdf)
+определяет `TH=scratchpad[2]` и `TL=scratchpad[3]` как два независимо
+программируемых alarm-регистра. `Write Scratchpad` принимает TH, TL и
+configuration (`scratchpad[4]`), `Copy Scratchpad` сохраняет все три байта в
+EEPROM, а `Recall E2` возвращает их в scratchpad. Заводские значения после
+сброса: TH `+75` (`0x4B`), TL `+70` (`0x46`), configuration `0x7F`.
+Scratchpad[5..7] зарезервированы/read-only и пользовательскими не считаются.
+
+На реальном датчике пользователь отдельно прочитал TH `14`, TL `128` и config
+`31`, подтвердив, что поля GUI должны оставаться независимыми. Проверка
+сохранения после полного power-cycle и parasite-power всё ещё требует отдельной
+аппаратной приёмки.
+
+## Документация
+
+- [HELP.md](HELP.md) — публичный API, инициализация, примеры, коды ошибок,
+  диагностика, ограничения и тесты.
+- [PORTING.md](PORTING.md) — перенос на другой MCU/проект и checklist порта.
+- [PROJECT_RELATIONS.md](PROJECT_RELATIONS.md) — слои, зависимости, владение
+  памятью и связи с текущей прошивкой.
+
+## Структура
+
+```text
+DS18B20/
+├── Inc/                       публичный API и конфигурация
+├── Src/                       переносимое ядро 1-Wire/DS18B20
+├── Port/STM32F4_HAL/Inc/      публичный API STM32F4-порта
+├── Port/STM32F4_HAL/Src/      реализация GPIO/таймера STM32F4
+├── README.md                  точка входа
+├── HELP.md                    справочник API
+├── PORTING.md                 руководство по переносу
+└── PROJECT_RELATIONS.md       место библиотеки в проекте
+```
+
+Адаптер текущего приложения находится отдельно:
+`climate_control_f407vet6_f4/Core/Src/dallas_tools.c`.
+
+## Минимальное подключение
+
+```c
+#include ds18b20.h
+#include ds18b20_stm32f4_hal.h
+
+#define DS_CAPACITY 8U
+static ds18b20_t bus;
+static uint8_t roms[DS_CAPACITY][DS18B20_ROM_SIZE];
+static ds18b20_stm32f4_hal_t port = {
+    .port = GPIOE, .pin = GPIO_PIN_2,
+    .timer = TIM2, .timer_ticks_per_us = 72U
+};
+
+if (ds18b20_stm32f4_hal_init(&port) == DS18B20_OK &&
+    ds18b20_init(&bus, &ds18b20_stm32f4_hal_ops, &port,
+                 roms, DS_CAPACITY) == DS18B20_OK) {
+    (void)ds18b20_search(&bus);
+}
+```
+
+### Пошаговый поиск для GUI и Modbus
+
+Для приложения с постоянно работающими сервисами используйте
+`ds18b20_search_begin()` и `ds18b20_search_step()`. Один вызов `step`
+обрабатывает не более одного кандидата ROM. `DS18B20_E_BUSY` означает, что
+нужно вызвать функцию в следующем проходе цикла; `DS18B20_OK` завершает поиск.
+`DS18B20_E_BUSY` также включает внутренние повторы и переходы между проходами.
+Все остальные статусы терминальные; CRC_ERROR после исчерпания повторов
+нельзя продолжать вызывать в цикле. Подробности — в [HELP.md](HELP.md).
+
+Таймер должен быть заранее запущен и считать непрерывно. Значение
+`timer_ticks_per_us` задаётся частотой счёта таймера, а не частотой ядра.
+Преобразование температуры выполняйте неблокирующей парой
+`ds18b20_start_all()` / `ds18b20_conversion_ready()`; полный сценарий приведён
+в [HELP.md](HELP.md).
+
+### Опрос по сохранённым ID
+
+`ds18b20_add_known_rom(bus, rom)` добавляет проверенный ROM без обращения к
+линии. Повторное добавление не создаёт дубликат. См. [HELP.md](HELP.md).
+
+
+## Shared source
+
+Canonical source: `templates/c/ds18b20/instance`. Used by `home/climate`; its old paths are compatibility includes. Board-specific ports remain in the application. Change this library, not the forwarding files.