/** * @file command.c * @brief 串口命令解析与处理模块实现 * @details 实现基于状态机的协议解析器，支持 D5 03 LEN [cmd] CRC 格式的命令处理， * 包含命令帧解析、响应生成和传感器状态管理功能。 * @author Hulk * @date 2025-08-13 * @version 1.0.0 * @ingroup Command */ #include "command.h" #include "uart_ring_buffer.h" #include "led.h" #include #include #include #include "board_config.h" /* ============================================================================ * 协议格式说明 * ============================================================================ */ /** * @name 协议帧格式 * @{ * @details * Host -> Device 命令帧格式： * [0] HEADER = 0xD5 // 包头标识 * [1] BOARD_TYPE = 0x03 // 板卡类型标识 * [2] LEN = 数据区字节数 // 有效载荷长度 * [3..(3+LEN-1)] 数据 // 命令数据，如 "M1", "M2S123" * [last] CRC = 校验码 // 从索引1到(last-1)的累加和低8位 * * 最小协议包长度为 6 字节 * 数据示例（两字节命令）："M1" / "M2" / "M3" * * Device -> Host 响应帧格式： * [0] 0xB5 // 响应包头 * [1] TYPE // 响应类型（0xF0=成功，0xF1..=错误类型） * [2] LEN // 响应数据长度 * [3..(3+LEN-1)] 数据 // 响应数据，如 "ok", "err" * [last] CRC // 校验码（同命令帧规则） * @} */ /* ============================================================================ * 协议常量定义 * ============================================================================ */ /** @name 协议帧标识符 * @{ */ #define PROTOCOL_PACKAGE_HEADER 0xD5 /**< 命令帧包头标识 */ #define PROTOCOL_BOARD_TYPE 0x03 /**< 板卡类型标识 */ /** @} */ /** @name 命令长度限制 * @{ */ #define COMMAND_MIN_LEN 2 /**< 最小命令长度，如"M1" */ #define PROTOCOL_MIN_FRAME_LEN (3 + COMMAND_MIN_LEN + 1) /**< 最小完整帧长度：header+type+len+payload+crc = 6 */ #define PROTOCOL_MAX_FRAME_LEN 16 /**< 最大完整帧长度 */ /** @} */ /** @name 响应帧标识符 * @{ */ #define RESP_HEADER 0xB5 /**< 响应帧包头标识 */ #define RESP_TYPE_OK 0xF0 /**< 成功响应类型 */ #define RESP_TYPE_CRC_ERR 0xF1 /**< CRC校验错误 */ #define RESP_TYPE_HEADER_ERR 0xF2 /**< 包头错误 */ #define RESP_TYPE_TYPE_ERR 0xF3 /**< 类型错误 */ #define RESP_TYPE_LEN_ERR 0xF4 /**< 长度错误 */ /** @} */ /* ============================================================================ * 模块内部变量 * ============================================================================ */ /** @brief 传感器周期上报使能标志 */ static volatile bool s_sensor_report_enabled = false; /** @name 预设响应数据 * @{ */ static const uint8_t s_report_status_ok[] = { 'o', 'k' }; /**< 成功响应数据 */ static const uint8_t s_report_status_err[] = { 'e','r','r' }; /**< 错误响应数据 */ /** @} */ /* ============================================================================ * 公共接口函数 * ============================================================================ */ /** * @brief 查询是否启用周期性传感器上报。 * @return true 表示启用；false 表示禁用。 * @ingroup Command */ bool get_sensor_report_enabled(void) { return s_sensor_report_enabled; } /** * @brief 设置是否启用周期性传感器上报标志。 * @details 本模块内部保存的布尔状态，供其他逻辑决定是否进行周期性数据上报； * 推荐通过本函数修改而非直接访问全局/静态变量，以便后续扩展（如加锁/回调）。 * @param enabled true 启用周期上报；false 禁用。 * @ingroup Command */ void set_sensor_report_enabled(bool enabled) { s_sensor_report_enabled = enabled; } /** * @brief 计算协议包的 8 位累加校验值（Checksum）。 * @details 对输入缓冲区逐字节累加并取低 8 位，累加范围为 data[1] 至 data[len-2]， * 即不包含包头 HEADER（索引 0）与尾部 CRC 字节（索引 len-1）。 * 当 len 小于最小协议帧长度（PACKAGE_MIN_LENGTH）时返回 0。 * @param data 指向待校验的完整协议包缓冲区。 * @param len 缓冲区总长度（字节），应满足 header + type + len + payload + crc 的最小格式。 * @return uint8_t 计算得到的 8 位校验值。 * @note 本函数实现为简单求和校验（Checksum），非多项式 CRC；与本协议“从索引 1 累加到 len-2”的规则一致。 * @ingroup Command */ static uint8_t command_sum_crc_calc(const uint8_t *data, uint8_t len) { uint16_t crc = 0; // 仅在满足协议最小帧长时计算（header + type + len + payload + crc） if (len < PROTOCOL_MIN_FRAME_LEN) return 0; // 累加从索引 1 到 len-2 的字节（不含 header 和 crc 字节） for (uint8_t i = 1; i < (len - 1); i++) { crc += data[i]; } return (uint8_t)(crc & 0xFF); } /** * @brief 发送协议响应帧。 * @details 构造并发送格式为 B5 TYPE LEN [payload] CRC 的响应帧， * 自动计算CRC校验值并通过串口输出。 * @param type 响应类型码（如 RESP_TYPE_OK, RESP_TYPE_CRC_ERR 等）。 * @param payload 指向响应数据的缓冲区，可为 NULL。 * @param len 响应数据长度（字节），payload为NULL时填充0。 * @note 内部使用固定大小缓冲区，超长响应将被丢弃。 * @warning 通过 printf 发送，确保串口已正确初始化。 * @ingroup Command */ static void send_response(uint8_t type, const uint8_t *payload, uint8_t len) { uint8_t buf_len = (uint8_t)(3 + len + 1); uint8_t buf[16]; // 简单场景足够，必要时可增大 if (buf_len > sizeof(buf)) return; // 防御 buf[0] = RESP_HEADER; buf[1] = type; buf[2] = len; for (uint8_t i = 0; i < len; i++) buf[3 + i] = payload ? payload[i] : 0; buf[buf_len - 1] = command_sum_crc_calc(buf, buf_len); for (uint8_t i = 0; i < buf_len; i++) { printf("%c", buf[i]); } // 刷新缓冲区 fflush(stdout); } /** * @brief 判断字符是否为十进制数字字符。 * @param c 待检查的字符（ASCII码值）。 * @return bool 判断结果。 * @retval true 字符为 '0' 到 '9' 之间的数字字符。 * @retval false 字符不是十进制数字字符。 * @ingroup Command */ static inline bool is_dec_digit(uint8_t c) { return (c >= '0' && c <= '9'); } /** * @brief 从缓冲区解析十进制无符号整数。 * @details 从指定位置开始连续读取十进制数字字符，累加构成32位无符号整数。 * 遇到非数字字符或到达长度限制时停止解析。 * @param s 指向待解析字符缓冲区的起始位置。 * @param n 允许解析的最大字符数。 * @param out 输出参数，存储解析结果，可为NULL。 * @return uint8_t 实际消耗的字符数。 * @retval 0 首字符不是数字，解析失败。 * @retval >0 成功解析的数字字符个数。 * @note 不处理符号、空白字符或进制前缀。 * @warning 不进行溢出检查，超出uint32_t范围时按无符号算术溢出处理。 * @ingroup Command */ static uint8_t parse_uint_dec(const uint8_t *s, uint8_t n, uint32_t *out) { uint8_t i = 0; uint32_t v = 0; while (i < n && is_dec_digit(s[i])) { v = v * 10u + (uint32_t)(s[i] - '0'); i++; } if (i == 0) return 0; // 未读到数字 if (out) *out = v; // return i; } /* ============================================================================ * 命令处理函数 * ============================================================================ */ /** * @brief 解析并处理完整的命令帧。 * @details 处理经过协议校验的完整命令帧，支持以下命令格式： * - 无参数命令：M<数字>（如 M1、M2、M10、M201） * - 带参数命令：M<数字>S<参数>（如 M100S123，参数为十进制） * * 支持的命令： * - M1: 开启LED，启用传感器上报 * - M2: 关闭LED，禁用传感器上报 * - M100S: 设置PWM值（示例） * * @param frame 指向完整命令帧的缓冲区（从包头0xD5开始）。 * @param len 命令帧总长度（字节）。 * @note 函数内部进行帧格式校验，格式错误时自动发送错误响应。 * @warning 假设输入帧已通过基本协议校验（包头、类型、CRC等）。 * @ingroup Command */ void handle_command(const uint8_t *frame, uint8_t len) { // 帧格式：D5 03 LEN [cmd] CRC; cmd 支持变长，如 "M1"、"M10"、"M201"、"M123S400"，有最小长度限制和命令长度校验 uint8_t cmd_len = frame[2]; if (len < PROTOCOL_MIN_FRAME_LEN || (uint8_t)(3 + cmd_len + 1) != len) return; // 长度不匹配或者小于最小限制 const uint8_t *cmd = &frame[3]; // 提取命令部分 // 命令必须以 'M' 开头 if (cmd[0] != 'M'){ send_response(RESP_TYPE_TYPE_ERR, s_report_status_err, sizeof(s_report_status_err)); return; } // 从 'M' 后开始解析 uint8_t cmd_index = 1; // 解析M后的十进制数，即命令本体 uint32_t base_cmd = 0; uint8_t used_base_cmd = parse_uint_dec(&cmd[cmd_index], (cmd_len - cmd_index), &base_cmd); if (used_base_cmd == 0) { // 'M' 后没有数字，格式错误 send_response(RESP_TYPE_LEN_ERR, s_report_status_err, sizeof(s_report_status_err)); return; } cmd_index = (uint8_t)(cmd_index + used_base_cmd); // 更新索引到命令后 // 情况A：无附加参数的基础命令 if (cmd_index == cmd_len) { // 仅基础命令，如 M1, M2, M3 switch (base_cmd) { case 1u: // M1命令 set_sensor_report_enabled(true); // led_on(); // send_response(RESP_TYPE_OK, s_report_status_ok, sizeof(s_report_status_ok)); uint8_t test_response1[] = { 0xAA, 0xBB, 0xCC, 0xDD }; send_response(RESP_TYPE_OK, test_response1, sizeof(test_response1)); return; case 2u: // M2命令 set_sensor_report_enabled(false); // led_off(); // send_response(RESP_TYPE_OK, s_report_status_ok, sizeof(s_report_status_ok)); uint8_t test_response2[] = { 0xDD, 0xCC, 0xBB, 0xAA }; send_response(RESP_TYPE_OK, test_response2, sizeof(test_response2)); return; // 示例：M3、M10、M201、M100 等（按需添加） // case 3u: // M3命令 // send_response(RESP_TYPE_OK, s_report_status_ok, sizeof(s_report_status_ok)); // return; // case 10u: // M10命令 // send_response(RESP_TYPE_OK, s_report_status_ok, sizeof(s_report_status_ok)); // return; // case 201u: // M201命令 // send_response(RESP_TYPE_OK, s_report_status_ok, sizeof(s_report_status_ok)); // return; default: // 其它无参数命令在此扩展（示例：M100）处理逻辑该如何待定 // send_response(RESP_TYPE_OK, s_report_status_ok, sizeof(s_report_status_ok)); // return; break; } // 未在处理列表的无参数基础命令，回复错误 send_response(RESP_TYPE_TYPE_ERR, s_report_status_err, sizeof(s_report_status_err)); return; } // 情况B：有附加参数的命令 if (cmd[cmd_index] == 'S') { cmd_index++; uint32_t param_value = 0; const uint8_t used_param_cmd = parse_uint_dec(&cmd[cmd_index], (uint8_t)(cmd_len - cmd_index), ¶m_value); if (used_param_cmd == 0) { // 'S' 后没有数字，格式错误 send_response(RESP_TYPE_LEN_ERR, s_report_status_err, sizeof(s_report_status_err)); return; } switch (base_cmd) { // case 100u: // // set_pwm(param_value); // printf("Set PWM to %u\n", param_value); // return; default: break; } send_response(RESP_TYPE_TYPE_ERR, s_report_status_err, sizeof(s_report_status_err)); } } /** * @brief 处理串口环形缓冲区中的命令数据，解析完整的协议帧。 * @details 本函数实现一个基于状态机的协议解析器，用于处理格式为 D5 03 LEN [cmd] CRC 的命令帧： * - 状态1：等待包头字节 PROTOCOL_PACKAGE_HEADER (0xD5) * - 状态2：接收板卡类型字节 PROTOCOL_BOARD_TYPE (0x03) * - 状态3：接收长度字段并计算期望的完整帧长度 * - 状态4：继续接收剩余数据直到完整帧 * - 状态5：对完整帧进行校验（包头、板卡类型、CRC）并处理 * * 函数采用非阻塞方式处理，每次调用处理缓冲区中所有可用数据。 * 遇到格式错误、长度异常或校验失败时自动重置状态机。 * * @note 本函数使用静态变量维护解析状态，因此不可重入。在中断环境中使用需注意并发安全。 * 协议帧最大长度受 PROTOCOL_MAX_FRAME_LEN 限制，超出范围的帧将被丢弃。 * * @warning 函数依赖 uart_ring_buffer_available() 和 uart_ring_buffer_get() * 正确实现，若这些函数有缺陷可能导致死循环或数据丢失。 * * @see handle_command() 用于处理校验通过的完整命令帧 * @see command_sum_crc_calc() 用于计算和校验 CRC 值 * @see send_response() 用于发送错误响应 * * @ingroup Command */ void command_process(void) { static uint8_t cmd_buf[PROTOCOL_MAX_FRAME_LEN]; static uint8_t cmd_len = 0; static uint8_t expected_cmd_len = 0; // 0 表示尚未确定总长度 while (uart_ring_buffer_available() > 0) { int byte = uart_ring_buffer_get(); if (byte < 0) break; if (cmd_len == 0) { if ((uint8_t)byte == PROTOCOL_PACKAGE_HEADER) { cmd_buf[cmd_len++] = (uint8_t)byte; expected_cmd_len = 0; // 等待进一步字段以确定长度 } else { // 丢弃非起始字节 } continue; } if (cmd_len >= PROTOCOL_MAX_FRAME_LEN) { // 防御：缓冲溢出，复位状态机 cmd_len = 0; expected_cmd_len = 0; } // 缓存后续字节 cmd_buf[cmd_len++] = (uint8_t)byte; // 当到达长度字段（索引 2）后，确定总长度：3 + LEN + 1 if (cmd_len == 3) { uint8_t payload_len = cmd_buf[2]; expected_cmd_len = (uint8_t)(3 + payload_len + 1); if (expected_cmd_len > PROTOCOL_MAX_FRAME_LEN) { // 异常：长度超界，复位状态机 cmd_len = 0; expected_cmd_len = 0; } continue; } if (expected_cmd_len > 0 && cmd_len == expected_cmd_len) { // 到帧尾，进行各项校验 bool verification_status = true; #ifdef DEBUG_VERBOSE if (cmd_buf[0] != PROTOCOL_PACKAGE_HEADER) { send_response(RESP_TYPE_HEADER_ERR, s_report_status_err, sizeof(s_report_status_err)); verification_status = false; } #endif if (verification_status && cmd_buf[1] != PROTOCOL_BOARD_TYPE) { send_response(RESP_TYPE_TYPE_ERR, s_report_status_err, sizeof(s_report_status_err)); verification_status = false; } if (verification_status) { uint8_t crc_calc = command_sum_crc_calc(cmd_buf, expected_cmd_len); uint8_t crc_recv = cmd_buf[expected_cmd_len - 1]; if (crc_calc != crc_recv) { send_response(RESP_TYPE_CRC_ERR, s_report_status_err, sizeof(s_report_status_err)); verification_status = false; } } if (verification_status) { handle_command(cmd_buf, expected_cmd_len); } // 复位，等待下一帧 cmd_len = 0; expected_cmd_len = 0; } } }