98 lines
5.6 KiB
Markdown
98 lines
5.6 KiB
Markdown
# 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.
|