146 lines
9.8 KiB
Markdown
146 lines
9.8 KiB
Markdown
# 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, UART 9600 бод. Байты передаются в
|
||
Data Mode с экранированием E3, reset/поиск/strong pullup — в Command Mode.
|
||
Переключения режима выполняет библиотека. Повышенные скорости UART,
|
||
Overdrive и Search Accelerator пока не реализованы. Параметры
|
||
таймингов длинной линии остаются заводскими. Аппаратная проверка обязательна
|
||
для выбранной топологии/нагрузки. Протокол проверен по документации **DS2480B**;
|
||
старые ревизии DS2480 без суффикса B отдельно не проверялись.
|
||
|
||
## Подключение и тесты
|
||
|
||
Добавьте `ds2480.c`, `ds18b20_ds2480.c` и путь к заголовкам в сборку прошивки.
|
||
Номер UART, GPIO и библиотеку платформы выбирает приложение. Порт [STM32F407 / STM32F4 HAL](ports/stm32f4/README.md) входит в библиотеку.
|
||
|
||
```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`.
|
||
Подключена к опросу climate через USART6 PC6/PC7; администратор выбирает GPIO или DS2480.
|
||
Ожидание преобразования в climate неблокирующее: `ds2480_power_begin/end`.
|
||
|
||
## Источники
|
||
|
||
- [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)
|