/**
 * anemometer_driver.h — RS485 风速仪 OOPC 驱动（不透明指针模式）
 *
 * 设计原则：
 *   - 对外只暴露 typedef 前向声明 + 公开 API 函数
 *   - 内部数据结构完全隐藏，外部无法篡改
 *   - 与 MultiButton 对比：Button 结构体字段对调用者可见 → 风速仪驱动采用 Opaque Pointer
 *
 * 适用场景：光伏跟踪器通过 RS485 Modbus RTU 读取超声波风速仪数据
 *
 * 依赖：
 *   - STM32F10x 标准库（USART、TIM、GPIO）
 *   - 无 RTOS 依赖，可在裸机/FreeRTOS 环境运行
 */

#ifndef ANEMOMETER_DRIVER_H
#define ANEMOMETER_DRIVER_H

#include "stm32f10x.h"

/*
 * 前向声明：外部调用者永远看不到 AnemometerDriver_S 的真实结构体定义。
 * 任何对内部字段的直接访问都在编译期被拦截。
 */
typedef struct AnemometerDriver_S AnemometerDriver_S;

/* ---------- 公开 API ---------- */

/**
 * 创建风速仪驱动实例（静态内存池，无 malloc）
 * @param h_uart      绑定的 USART 外设（如 USART2）
 * @param slave_addr  Modbus 从站地址（风速仪设备地址，默认 0x02）
 * @return 驱动实例句柄，NULL 表示无可用实例槽位
 */
AnemometerDriver_S* AnemometerDriver_Create(USART_TypeDef* h_uart,
                                            uint8_t slave_addr);

/**
 * 设置轮询间隔
 * @param me  驱动实例
 * @param ms  轮询周期（毫秒），默认 500ms
 */
void AnemometerDriver_SetPollInterval(AnemometerDriver_S* me, uint16_t ms);

/**
 * 读取最新风速值（只读，线程安全）
 * @param me  驱动实例（const 保证不修改内部状态）
 * @return 风速值 ×10（单位 0.1 m/s），0xFFFF 表示无效/超时
 */
uint16_t AnemometerDriver_GetWindSpeed(const AnemometerDriver_S* me);

/**
 * 主循环轮询入口——每隔 1ms 或主循环每 tick 调用一次。
 * 内部管理发帧间隔、超时检测、重试逻辑。
 *
 * 约定：本函数必须在非中断上下文中调用（main loop 或低优先级 task）。
 *
 * @param me  驱动实例
 */
void AnemometerDriver_Poll(AnemometerDriver_S* me);

/**
 * 字节接收中断服务入口——在 USART RXNE 中断 ISR 中调用。
 * 内部维护 FreeModbus 风格的接收状态机（STATE_RX_IDLE / RCV / ERROR）。
 *
 * @param me  驱动实例
 */
void AnemometerDriver_ReceiveISR(AnemometerDriver_S* me);

/**
 * 3.5 字符超时定时器中断入口——在 TIM 中断 ISR 中调用（建议 1ms tick 定时器）。
 * 帧结束时触发 CRC 校验与解析；溢出时自动丢弃并重置状态机。
 *
 * @param me  驱动实例
 */
void AnemometerDriver_TimerISR(AnemometerDriver_S* me);

#endif /* ANEMOMETER_DRIVER_H */