/******************************************************************************
 * @file    app_th.h
 * @brief   CBR3 温湿度采集：2s 周期、失败计数、最近有效值
 * @author  cyWu <1917507415@qq.com>
 * @date    2026.09.03
 * @version V1.3.0，对外温湿度与显示/上报绑死（T>=0.5℃ / H>=2%）
 *
 * @note    规格书 8.4：联动、数码管、DP3/DP4 都用对外温湿度；采样失败保持
 *          上一对外值继续判，直到连续 3 次失败显示 "--"（DP24
 *          fault_code=1）。对外值首次跟上，之后
 *          |ΔT|>=BOARD_TH_TEMP_PUB_DELTA_X10、|ΔH|>=BOARD_TH_HUMI_PUB_DELTA
 *          才改，避免小数抖动导致显示、APP、联动各跳。
 ******************************************************************************/

#ifndef __APP_TH_H__
#define __APP_TH_H__

#include <stdint.h>

/**
 * @brief  初始化温湿度模块
 * @return 无
 */
void app_th_init(void);

/**
 * @brief  业务节拍：内部 2s 才真正采一次；采的时候走总线互斥
 * @param  dt 距上次调用的毫秒数
 * @return 无
 */
void app_th_poll(uint16_t dt);

/**
 * @brief  是否已有有效采样
 * @return 1=有效，0=从未成功
 */
uint8_t app_th_get_valid(void);

/**
 * @brief  对外温度（数码管 + DP3 + 联动）
 * @return 温度 ×10（如 25.3℃ → 253）
 */
int16_t app_th_get_temp_x10(void);

/**
 * @brief  对外湿度（数码管 + DP4 + 联动）
 * @return 湿度 0~100 整数 %
 */
uint8_t app_th_get_humi(void);

/**
 * @brief  连续失败次数
 * @return 连续失败次数
 */
uint8_t app_th_get_fail_cnt(void);

/**
 * @brief  传感器故障（连续失败 ≥ BOARD_TH_FAIL_MAX）
 * @return 1=故障（显示 --、fault_code=1），0=正常
 */
uint8_t app_th_is_fault(void);

/**
 * @brief  最近一次采样是否成功（app_linkage / app_disp 用，规格书 8.4）
 * @return 1=成功，0=失败/未采样过
 */
uint8_t app_th_last_sample_ok(void);

/**
 * @brief  取走一次「本周期采样成功」事件（供 usr_le_adv 的 500ms 任务上下文）
 * @note   ⚠ 生产者是 app_th_poll（20ms 硬件定时器中断上下文），那里只置
 *         volatile pending，不开关广播、不打日志、不写 flash。
 *         消费者（usr_ble_adv_updata，BLE 线程任务上下文）调本函数取走，
 *         内部 local_irq_disable 保护，取到即清。
 *         只在真正采样成功（last_ok 那次）时产生，失败/fault 不产生，
 *         温度、湿度都是对外值（与数码管/DP3/DP4 一致）。
 * @param  t_x10 出参：对外温度 ×10（可为 NULL）
 * @param  h     出参：对外湿度 %（可为 NULL）
 * @return 1=取到一次新采样，0=无新采样
 */
uint8_t app_th_take_sample(int16_t *t_x10, uint8_t *h);

#endif /* __APP_TH_H__ */