SCD_SCD/SCDV3/pkg/at_dev/at_cmd.h

/**
 * @file at_cmd.h
 * @brief AT命令驱动核心 - 重构版（安全架构）
 * @note  移除函数指针回调，采用查询模式，天然安全
 *        简化状态机，增加边界检查，防止IBUSERR和缓冲区溢出
 */
#ifndef __AT_CMD_H__
#define __AT_CMD_H__

#include <rtthread.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/* ==================== 配置 ==================== */
#define AT_RSP_BUF_SIZE         1024    /* 响应缓冲区大小 */
#define AT_CMD_BUF_SIZE         256     /* 命令缓冲区大小 */
#define AT_URC_MAX_NUM          16      /* 最大URC数量 */
#define AT_URC_MAX_LEN          32      /* URC前缀最大长度 */

/* ==================== 结果枚举 ==================== */
typedef enum {
    AT_RESULT_IDLE = 0,         /* 空闲 */
    AT_RESULT_OK,               /* 成功 */
    AT_RESULT_ERROR,            /* 错误 */
    AT_RESULT_TIMEOUT,          /* 超时 */
    AT_RESULT_CME_ERROR,        /* CME错误 */
    AT_RESULT_CMS_ERROR,        /* CMS错误 */
    AT_RESULT_ABORT             /* 中止 */
} at_result_t;

/* ==================== 状态枚举 ==================== */
typedef enum {
    AT_STATE_IDLE = 0,          /* 空闲 */
    AT_STATE_SENDING,           /* 发送中 */
    AT_STATE_WAITING,           /* 等待响应 */
    AT_STATE_DONE               /* 完成 */
} at_state_t;

/* ==================== URC回调类型 ==================== */
typedef void (*at_urc_cb_t)(const char *data, uint16_t len);

/* ==================== 命令结构 ==================== */
/**
 * @brief AT命令项
 * @note  简化设计，移除函数指针回调，改为查询模式
 */
typedef struct {
    const char *cmd;            /* 命令字符串（必须以\r\n结尾） */
    const char *expect_ok;      /* 期望的成功响应（可为NULL） */
    const char *expect_error;   /* 期望的错误响应（可为NULL） */
    uint16_t timeout_ms;        /* 超时时间（毫秒） */
    uint8_t retries;            /* 重试次数 */
} at_cmd_item_t;

/* ==================== API接口 ==================== */

/**
 * @brief 初始化AT命令模块
 * @param uart_name UART设备名，如"uart2"
 * @return 0成功，其他失败
 */
int at_init(const char *uart_name);

/**
 * @brief 反初始化AT命令模块
 */
void at_deinit(void);

/**
 * @brief 发送AT命令（异步）
 * @param cmd 命令结构体指针
 * @return 0成功启动，其他失败
 * @note  调用后需轮询at_process()或等待at_get_result()返回非IDLE
 *        此函数不会阻塞，立即返回
 *        cmd的生命周期必须保持到命令完成（可指向静态或全局变量）
 */
int at_exec_cmd(const at_cmd_item_t *cmd);

/**
 * @brief 发送原始数据
 * @param data 数据指针
 * @param len 数据长度
 * @return 实际发送字节数
 */
int at_send_raw(const uint8_t *data, uint16_t len);

/**
 * @brief 主处理函数
 * @note  必须在主循环或独立线程中定期调用，建议100ms周期
 *        驱动状态机运行，处理接收数据
 */
void at_process(void);

/**
 * @brief 获取当前执行结果
 * @return 结果状态
 * @note  返回AT_RESULT_IDLE表示命令仍在执行中
 *        返回其他值表示命令已完成，可获取响应
 */
at_result_t at_get_result(void);

/**
 * @brief 获取响应缓冲区
 * @return 响应字符串指针（以\0结尾）
 * @note  仅在at_get_result()返回非IDLE时有效
 *        缓冲区内容在下次调用at_exec_cmd()前有效
 */
const char* at_get_response(void);

/**
 * @brief 获取当前状态
 * @return 当前状态
 */
at_state_t at_get_state(void);

/**
 * @brief 中止当前命令
 */
void at_abort_cmd(void);

/**
 * @brief 注册URC处理函数
 * @param prefix URC前缀，如"+QMTRECV:""
 * @param callback 回调函数
 * @return 0成功，其他失败（URC表已满）
 * @note  URC（非请求结果码）是模块主动上报的数据
 *        此回调在中断上下文或at_process上下文中调用，需快速处理
 */
int at_register_urc(const char *prefix, at_urc_cb_t callback);

/**
 * @brief 注销URC处理函数
 * @param prefix URC前缀
 */
void at_unregister_urc(const char *prefix);

/**
 * @brief 清除响应缓冲区
 */
void at_clear_response(void);

/**
 * @brief 设置调试输出开关
 * @param enable 0关闭，1开启
 */
void at_set_debug(uint8_t enable);

/**
 * @brief 获取最后一条错误信息
 * @return 错误信息字符串（如"+CME ERROR: 3"）
 */
const char* at_get_error_info(void);

#ifdef __cplusplus
}
#endif

#endif /* __AT_CMD_H__ */