/**
 * @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 = 0x01    // 板卡类型标识  
 * [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 处理串口环形缓冲区中的命令数据。
 * @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);

/**
 * @brief 执行命令（简化版）
 * @details 根据命令字符串直接构造命令帧并执行，无需手动构造协议帧
 * @param cmd_str 命令字符串（如"M730S0T1000"、"M731S100"等）
 * @note 简化的测试函数，自动处理协议帧构造、CRC计算和命令执行
 * @ingroup Command
 */
void command_execute(const char *cmd_str);

/**
 * @brief M737命令投光结束回调函数
 * @details 当定时器结束时调用此函数，向等待中的M737命令发送OK响应
 * @param none
 * @note 此函数由定时器中断调用，不应直接调用
 * @ingroup Command
 */
void command_m737_timer_finished_callback(void);

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

#endif // COMMAND_H
