# DS18B20 через DS2480B

Переносимая библиотека C99: поиск DS18B20 на общей шине, температура,
разрешение 9–12 бит, TH/TL и сохранение в EEPROM через UART-мост DS2480B.
Поддерживаются внешнее и паразитное питание: преобразование и запись EEPROM
используют strong pullup, включаемый мостом сразу после последнего бита команды.

Ядро не зависит от HAL, CMSIS, ОС или существующей GPIO-библиотеки `ds18b20`.
Динамической памяти и глобального состояния нет. Каждый UART-мост имеет свой
`ds2480`, каждый обход — свой `ds2480_search`.

```text
Приложение → ds18b20_ds2480 → ds2480 → callbacks UART/задержки → платформа
```

## Файлы

| Файл | Назначение | Зависимости |
|---|---|---|
| `ds2480.h`, `ds2480.c` | Калибровка, reset, обмен битами/байтами, поиск ROM, CRC, strong pullup | `stdint.h`, callbacks |
| `ds18b20_ds2480.h`, `ds18b20_ds2480.c` | Команды термометра, проверка scratchpad, знаковая температура | `ds2480`, `string.h` |
| `examples/read_first.c` | Полный цикл для первого найденного DS18B20 | ядро, порт приложения |
| `tests/test_ds18b20_ds2480.c` | Модель UART-моста и нескольких устройств 1-Wire | ядро, стандартная библиотека C |

## Контракт порта

```c
int prepare(void *user);
int write(void *user, const uint8_t *data, uint32_t size, uint32_t timeout_ms);
int read(void *user, uint8_t *data, uint32_t size, uint32_t timeout_ms);
void delay_ms(void *user, uint32_t ms);
```

Первые три callbacks возвращают `0` при успехе, иначе ошибку.
`prepare` аппаратно сбрасывает DS2480B или формирует UART BREAK не короче 2 мс,
настраивает **9600 бод, 8N1**, выдерживает минимум 2 мс после сброса и очищает RX
и ошибки UART. Эта функция должна иметь собственный конечный таймаут.
Нельзя просто посылать `C1` работающему мосту вместо сброса.

`write` передаёт ровно `size` байтов и ждёт окончания передачи; `read` получает
ровно `size` байтов. Обе операции ограничены `timeout_ms`; при частичном обмене
возвращается ошибка. Приём должен работать уже во время передачи: ответ может
появиться до вызова `read`. `delay_ms` не должна возвращаться раньше заданного
времени (учтите округление системного тика).

Управлять одним UART извне одновременно с библиотекой нельзя. В RTOS блокировка
нужна на всю операцию верхнего уровня, включая поиск и ожидание преобразования.
Тайминги 1-Wire формирует мост, запрещать прерывания на время слотов не требуется.

## Быстрый старт

Функции `prepare`, `write`, `read`, `delay_ms` и `uart_context` предоставляет плата.
Следующий код располагается внутри функции приложения:

```c
ds2480 bus;
ds2480_search search = {{0}, 0, 0};
ds2480_port port = {uart_context, prepare, write, read, delay_ms};
int16_t raw;
ds2480_status status = ds2480_init(&bus, &port, 20);
if (status != DS2480_OK) return;
status = ds18b20_ds2480_next(&bus, &search);
if (status != DS2480_OK) return;
status = ds18b20_ds2480_convert(&bus, search.rom);
if (status != DS2480_OK) return;
status = ds18b20_ds2480_temperature(&bus, search.rom, &raw);
if (status != DS2480_OK) return;
float celsius = raw / 16.0f;
(void)celsius;
```

Вызывайте `next` повторно с тем же курсором до `DS2480_DONE`, сохраняя каждый
найденный ROM в памяти приложения. Лимита количества датчиков в ядре нет.
Пустая шина возвращает `DS2480_NO_PRESENCE`; обрыв поиска и ошибки CRC не
маскируются под успешное завершение. Для нового обхода обнулите курсор.

`convert(bus, NULL)` одновременно запускает все устройства — допустимо только
на шине исключительно с DS18B20. Затем читайте каждое по ROM. Для паразитного
питания суммарный ток должен укладываться в возможности моста; при необходимости
преобразуйте по одному датчику. Преобразование блокирует вызов на 750 мс плюс
UART-обмен. EEPROM использует выдержку 12 мс, её содержимое после перезапуска
этой функцией не проверяется. Чтение температуры само преобразование не запускает.
Значение 85 °C после включения нельзя отличить от настоящих 85 °C без завершённого
преобразования; не считайте его заведомой ошибкой.

## Ошибки и ограничения

- `IO` — таймаут/ошибка порта, `PROTOCOL` — неожиданный ответ DS2480B.
  После них экземпляр не готов к работе: повторите `ds2480_init`.
- `SHORT` — короткое замыкание, `NO_PRESENCE` — нет presence.
- `CRC` — неверная контрольная сумма, `DATA` — недопустимые данные или
  неподтверждённая запись. Выход температуры/scratchpad при ошибке не меняется.
- При ошибке во время strong pullup ядро вызывает `prepare`, чтобы прекратить
  импульс, и остаётся неготовым. При отказе самого порта снятие питания гарантировать
  невозможно; восстановление UART/моста остаётся задачей приложения.

Используется стандартная скорость 1-Wire и только Command Mode: байт передаётся
восьмью командами Single Bit. Поэтому любые значения, включая `E3`, передаются
без экранирования. Это простая реализация для опроса температуры; повышенные
скорости UART, Overdrive и Search Accelerator пока не реализованы. Параметры
таймингов длинной линии остаются заводскими. Аппаратная проверка обязательна
для выбранной топологии/нагрузки. Протокол проверен по документации **DS2480B**;
старые ревизии DS2480 без суффикса B отдельно не проверялись.

## Подключение и тесты

Добавьте `ds2480.c`, `ds18b20_ds2480.c` и путь к заголовкам в сборку прошивки.
Номер UART, GPIO и библиотеку платформы выбирает приложение. Готовый порт
для конкретной платы пока не входит в библиотеку.

```cmake
set(DS18B20_DS2480_BUILD_TESTS OFF CACHE BOOL "" FORCE)
add_subdirectory(third_party/templates/c/ds18b20-ds2480)
target_link_libraries(firmware PRIVATE ds18b20_ds2480)
```

Отдельная сборка хостовых тестов:

```sh
cmake -S . -B build
cmake --build build --config Debug
ctest --test-dir build -C Debug --output-on-failure
```

Без CMake, из каталога библиотеки:

```sh
clang -std=c99 -Wall -Wextra -Wpedantic -Werror -I . ds2480.c ds18b20_ds2480.c tests/test_ds18b20_ds2480.c -o build/test.exe
./build/test.exe
```

Тесты моделируют калибровку без ответа, несколько ROM с развилками, другие
семейства, адресацию, все разрешения, отрицательную температуру, CRC, пустую
и замкнутую шину, ошибки транспорта, strong pullup и восстановление после ошибок.
Это программная модель; испытания на физическом DS2480B пока не проводились.

## Использование

Добавлена в сабмодуль `templates` проекта `john103C6T6NewVer`, ветка `ds2480`.
В рабочую прошивку ещё не включена: для этого требуется порт выбранного UART.

## Источники

- [DS2480B datasheet, таблицы команд и ответов](https://www.analog.com/media/en/technical-documentation/data-sheets/ds2480b.pdf)
- [DS18B20 datasheet, команды, питание и scratchpad](https://www.analog.com/media/en/technical-documentation/data-sheets/ds18b20.pdf)