feat(ds18b20-ds2480): добавь драйвер датчиков через UART-мост
This commit is contained in:
145
c/ds18b20-ds2480/README.md
Normal file
145
c/ds18b20-ds2480/README.md
Normal file
@@ -0,0 +1,145 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user