/**
 * @file command.h
 * @brief 串口命令解析与处理模块接口声明。
 * @details 提供基于环形缓冲区的串口协议解析、命令处理及状态管理功能，
 *          支持格式为 D5 03 LEN [cmd] CRC 的命令帧解析与响应。
 */
#ifndef COMMAND_H
#define COMMAND_H

#include <stdint.h>
#include <stdbool.h>

/**
 * @defgroup Command 命令处理模块
 * @brief 串口命令解析与处理
 * @{
 */

/**
 * @section Command_Protocol 协议格式
 * 接收命令帧格式：
 * @code
 * [0] HEADER = 0xD5        // 包头标识
 * [1] BOARD_TYPE = 0x03    // 板卡类型标识  
 * [2] LEN = 数据区字节数    // 有效载荷长度
 * [3..(3+LEN-1)] 数据      // 命令数据
 * [last] CRC               // 校验码（从索引1累加到len-2的低8位）
 * @endcode
 * 
 * 响应帧格式：
 * @code
 * [0] HEADER = 0xB5        // 响应包头
 * [1] TYPE                 // 响应类型（0xF0=成功，0xF1..=错误类型）
 * [2] LEN                  // 响应数据长度
 * [3..(3+LEN-1)] 数据      // 响应数据
 * [last] CRC               // 校验码
 * @endcode
 *
 * @section Command_Usage 使用说明
 * 1) 初始化环形缓冲区：
 * @code{.c}
 * uart_ring_buffer_init();
 * @endcode
 *
 * 2) 在主循环中调用命令处理：
 * @code{.c}
 * while(1) {
 *     command_process();  // 处理接收到的命令
 *     // 其他业务逻辑
 * }
 * @endcode
 *
 * 3) 查询传感器上报状态：
 * @code{.c}
 * if(get_sensor_report_enabled()) {
 *     // 执行传感器数据上报
 * }
 * @endcode
 */

/**
 * @brief 获取传感器周期上报使能状态。
 * @return bool 上报状态。
 * @retval true  传感器周期上报已启用。
 * @retval false 传感器周期上报已禁用。
 * @ingroup Command
 */
bool get_sensor_report_enabled(void);

/**
 * @brief 设置传感器周期上报使能状态。
 * @param enabled 上报使能标志。
 * @arg true  启用传感器周期上报。
 * @arg false 禁用传感器周期上报。
 * @note 推荐通过此函数修改状态，便于后续功能扩展。
 * @ingroup Command
 */
void set_sensor_report_enabled(bool enabled);

/**
 * @brief 处理串口环形缓冲区中的命令数据。
 * @details 基于状态机的非阻塞协议解析器，处理完整的命令帧并自动响应。
 *          每次调用处理缓冲区中所有可用数据，遇到错误时自动重置状态机。
 * @note 使用静态变量维护解析状态，函数不可重入。
 * @warning 依赖环形缓冲区正确实现，建议在主循环中周期调用。
 * @ingroup Command
 */
void command_process(void);

/**
 * @brief 解析并处理完整的命令帧。
 * @param cmd 指向完整命令帧的缓冲区（从包头0xD5开始）。
 * @param len 命令帧总长度（字节）。
 * @note 内部函数，由 command_process() 调用，一般不直接使用。
 * @ingroup Command
 */
void handle_command(const uint8_t *cmd, uint8_t len);

/** @} */ // end of Command group

#endif // COMMAND_H