/**
 * @file onewire.h
 * @brief Программная шина 1-Wire на выводе с открытым стоком.
 *
 * Драйвер не зависит от типа датчика: он выдаёт тайминги, ищет ROM и считает
 * CRC8. Работа с DS18B20 вынесена в ds18b20.c.
 *
 * Реализация разделена надвое:
 *   src/onewire.c   переносимая часть - побайтовый обмен, CRC8, поиск ROM,
 *                   MATCH ROM и SKIP ROM; ни регистров, ни задержек;
 *   ports/<платформа>  пять функций, зависящих от железа: OneWire_Init,
 *                   OneWire_DelayUs, OneWire_Reset, OneWire_WriteBit
 *                   и OneWire_ReadBit.
 *
 * Чтобы перенести библиотеку на другой микроконтроллер, достаточно написать
 * эти пять функций - остальное собирается как есть.
 */

#ifndef ONEWIRE_H
#define ONEWIRE_H

#include <stdint.h>

/** Размер идентификатора устройства 1-Wire в байтах. */
#define ONEWIRE_ROM_SIZE 8U

/**
 * @brief Состояние обхода шины алгоритмом SEARCH ROM.
 *
 * Структура принадлежит вызывающему коду; параллельные обходы должны
 * использовать разные экземпляры.
 */
typedef struct {
    uint8_t rom[ONEWIRE_ROM_SIZE]; /**< Текущий найденный идентификатор. */
    uint8_t last_discrepancy;      /**< Позиция последней развилки, 1..64. */
    uint8_t last_family_discrepancy; /**< Развилка внутри кода семейства. */
    uint8_t last_device;           /**< Признак завершённого обхода. */
} OneWire_Search;

/**
 * @brief Настраивает вывод шины и счётчик циклов для микросекундных задержек.
 *
 * Вызывается один раз после инициализации тактирования системы.
 */
void OneWire_Init(void);

/**
 * @brief Формирует импульс сброса и проверяет ответ устройств.
 *
 * @note На время выборки presence прерывания запрещаются примерно на 75 мкс;
 *       длительность самого импульса сброса на точность не влияет.
 *
 * @return 1, если хотя бы одно устройство выдало presence-импульс, иначе 0.
 */
uint8_t OneWire_Reset(void);

/**
 * @brief Передаёт один бит в тайм-слоте записи.
 *
 * @param bit Передаваемое значение, отличное от нуля означает единицу.
 */
void OneWire_WriteBit(uint8_t bit);

/**
 * @brief Считывает один бит в тайм-слоте чтения.
 *
 * @return Принятое значение бита: 0 или 1.
 */
uint8_t OneWire_ReadBit(void);

/**
 * @brief Передаёт байт младшим битом вперёд.
 *
 * @param value Передаваемый байт.
 */
void OneWire_WriteByte(uint8_t value);

/**
 * @brief Принимает байт младшим битом вперёд.
 *
 * @return Принятый байт.
 */
uint8_t OneWire_ReadByte(void);

/**
 * @brief Передаёт блок байтов подряд без промежуточных сбросов.
 *
 * @param data Указатель на передаваемые байты.
 * @param size Количество байтов.
 */
void OneWire_WriteBytes(const uint8_t *data, uint32_t size);

/**
 * @brief Принимает блок байтов подряд.
 *
 * @param data Буфер приёмника.
 * @param size Количество байтов.
 */
void OneWire_ReadBytes(uint8_t *data, uint32_t size);

/**
 * @brief Считает CRC8 Dallas/Maxim с полиномом 0x8C.
 *
 * @param data Проверяемые байты.
 * @param size Количество байтов.
 * @return Значение CRC8; для блока вместе с контрольным байтом равно нулю.
 */
uint8_t OneWire_Crc8(const uint8_t *data, uint32_t size);

/**
 * @brief Подготавливает состояние к новому полному обходу шины.
 *
 * @param search Состояние обхода, принадлежащее вызывающему коду.
 */
void OneWire_SearchInit(OneWire_Search *search);

/**
 * @brief Находит следующий идентификатор на шине.
 *
 * @param search Состояние обхода, ранее подготовленное OneWire_SearchInit.
 * @return 1, если поле rom содержит новый проверенный ROM, иначе 0.
 */
uint8_t OneWire_SearchNext(OneWire_Search *search);

/**
 * @brief Адресует конкретное устройство командой MATCH ROM.
 *
 * @param rom Восьмибайтовый идентификатор устройства.
 * @return 1 при наличии presence-импульса, иначе 0.
 */
uint8_t OneWire_SelectRom(const uint8_t *rom);

/**
 * @brief Адресует все устройства шины командой SKIP ROM.
 *
 * @return 1 при наличии presence-импульса, иначе 0.
 */
uint8_t OneWire_SkipRom(void);

/**
 * @brief Задерживает выполнение на заданное число микросекунд.
 *
 * Используется драйверами шины и модулем DS18B20 при ожидании EEPROM.
 *
 * @param microseconds Длительность задержки.
 */
void OneWire_DelayUs(uint32_t microseconds);

#endif /* ONEWIRE_H */