uart_rx.h
/**
******************************************************************************
* @file uart_rx.h
* @brief 串口中断接收、环形缓冲区和简单二进制帧接收。
*
* 本文件是团队自己写的代码，放在 Core/Inc；uart_rx.c 放在 Core/Src。
* CubeMX 重新生成代码不会覆盖这两个文件。
*
* 使用前确认 CubeMX 已配置：USARTx、USARTx global interrupt，且中断服务函数中
* 有 HAL_UART_IRQHandler(&huartx)。本模块自己实现 HAL_UART_RxCpltCallback，
* 工程中不要再定义第二个同名回调函数。
*
* --------------------------------------------------------------------------
* 【串口助手发送多条可读命令：回车换行结尾】
*
* UART_Rx_ReadLine() 用于接收人能看懂的 ASCII 命令。发送端每一条命令都应以
* 换行 '\n' 结束；串口助手一般选择“发送新行”或“CRLF”，即发送 \r\n。
* 本模块会忽略 \r，并把 \n 识别为一条命令结束。因此连续发送：
*
* LEDON\r\nPWM=50\r\n12\r\n
*
* 程序会依次得到三个独立字符串："LEDON"、"PWM=50"、"12"。不能只使用 if
* 取一次，因为电脑可能一次就发送多条命令；应在 while 内把已完整接收的行全部处理。
*
* main.c 命令识别完整示例（需要在 Includes 区加入 #include <string.h>）：
* @code
* char line[32];
*
* // 放在 while(1) 内。每轮会处理接收缓冲区中所有已收完整的命令。
* while (UART_Rx_ReadLine(&uart1_rx, line, sizeof(line)) == UART_RX_STATUS_OK)
* {
* if (strcmp(line, "LEDON") == 0)
* {
* // strcmp 返回 0 表示两个字符串完全相同。
* HAL_GPIO_WritePin(LED_GPIO_Port, LED_Pin, GPIO_PIN_SET);
* UART_Tx_SendLine(&huart1, "LED is ON", 100U);
* }
* else if (strcmp(line, "LEDOFF") == 0)
* {
* HAL_GPIO_WritePin(LED_GPIO_Port, LED_Pin, GPIO_PIN_RESET);
* UART_Tx_SendLine(&huart1, "LED is OFF", 100U);
* }
* else if (strncmp(line, "PWM=", 4U) == 0)
* {
* // strncmp(..., 4U)==0 表示前四个字符正好是 P、W、M、=。
* // &line[4] 是等号后的第一个字符，例如 "PWM=50" 中的 "50"。
* uint32_t duty;
* if ((UART_Rx_ParseU32(&line[4], &duty) != 0U) && (duty <= 100U))
* {
* // 这里按你的 PWM 驱动实际函数替换，例如设置为 50% 占空比。
* // PWM_Driver_SetDutyPercent(&boost_pwm, (float)duty);
* UART_Tx_SendLine(&huart1, "PWM updated", 100U);
* }
* else
* {
* UART_Tx_SendLine(&huart1, "PWM must be 0~100", 100U);
* }
* }
* else
* {
* UART_Tx_SendLine(&huart1, "Unknown command", 100U);
* }
* }
* @endcode
*
* 比赛时题目会规定命令字和参数格式；只需要把 "LEDON"、"PWM=" 等字符串及其
* 对应处理动作替换成题目要求即可。若题目规定的是 AA 55 等二进制帧，不使用本段
* 的 ReadLine/strcmp 方法，应使用后面的 ReadByte + Protocol_Parser。
* --------------------------------------------------------------------------
*
* 二进制帧固定格式：
* HEADER[0] ... HEADER[N-1] LENGTH DATA[0] ... DATA[LENGTH-1] CHECKSUM
*
* - HEADER：帧头数组，长度 N 可为 1~16 字节，由题目决定。
* - LENGTH：DATA 区的字节数，不包括帧头、长度字节和校验字节。
* - CHECKSUM：SUM8/XOR8 为 1 字节；CRC16-Modbus 为 2 字节（低字节在前）。
* - 校验范围默认是 LENGTH + DATA，不包含帧头和校验字节。
*
* main.c 完整使用示例：
* @code
* // USER CODE BEGIN Includes
* #include "uart_rx.h"
*
* // USER CODE BEGIN PV
* static UART_Rx_t uart1_rx;
* static uint8_t uart1_rx_buffer[128]; // 中断收到的字节先暂存在这里
* static Protocol_Parser_t protocol;
* static Protocol_Frame_t received_frame;
*
* // USER CODE BEGIN 2，必须放在 MX_USART1_UART_Init() 之后：
* UART_Rx_Init(&uart1_rx, &huart1, uart1_rx_buffer, sizeof(uart1_rx_buffer));
* UART_Rx_Start(&uart1_rx); // 开始单字节中断接收
*
* // 题目若定义帧：AA 55 LEN DATA... SUM8，则这样写：
* static const uint8_t frame_header[] = {0xAAU, 0x55U};
* Protocol_Parser_Init(&protocol, frame_header, sizeof(frame_header),
* PROTOCOL_CHECKSUM_SUM8);
*
* // USER CODE BEGIN 3，放进 while(1)：
* uint8_t one_byte;
* while (UART_Rx_ReadByte(&uart1_rx, &one_byte) == UART_RX_STATUS_OK)
* {
* if (Protocol_Parser_FeedByte(&protocol, one_byte) == PROTOCOL_STATUS_FRAME_READY)
* {
* Protocol_Parser_TakeFrame(&protocol, &received_frame);
*
* // 例如收到：AA 55 03 11 22 33 69
* // received_frame.length = 7U;
* // received_frame.data[0..6] = {0xAA,0x55,0x03,0x11,0x22,0x33,0x69};
* // 之后直接按数组下标使用，不需要关心命令、载荷等额外结构。
* // 第一个数据的下标 = 帧头长度 + 1 个 LENGTH 字节。
* uint8_t first_data = received_frame.data[sizeof(frame_header) + 1U]; // 0x11
* (void)first_data;
* }
* }
* @endcode
*
* 比赛时只改帧头数组内容、帧头数组长度和校验方式：
* @code
* static const uint8_t frame_header[] = {0x55U, 0xAAU, 0x12U, 0x34U};
* Protocol_Parser_Init(&protocol, frame_header, sizeof(frame_header),
* PROTOCOL_CHECKSUM_XOR8);
* // 可选校验方式：PROTOCOL_CHECKSUM_SUM8、PROTOCOL_CHECKSUM_XOR8、
* // PROTOCOL_CHECKSUM_CRC16_MODBUS、PROTOCOL_CHECKSUM_NONE。
* @endcode
******************************************************************************
*/
#ifndef UART_RX_H
#define UART_RX_H
#ifdef __cplusplus
extern "C" {
#endif
#include "usart.h"
typedef enum
{
UART_RX_STATUS_OK = 0,
UART_RX_STATUS_EMPTY,
UART_RX_STATUS_INCOMPLETE,
UART_RX_STATUS_INVALID_ARG,
UART_RX_STATUS_NOT_INITIALIZED,
UART_RX_STATUS_BUSY,
UART_RX_STATUS_HAL_ERROR,
UART_RX_STATUS_BUFFER_SMALL
} UART_Rx_Status_t;
/* UART 中断接收对象。应用层只需定义变量并传给 Init，不要手动修改成员。 */
typedef struct
{
UART_HandleTypeDef *huart;
uint8_t *buffer;
uint16_t capacity;
volatile uint16_t read_index;
volatile uint16_t write_index;
uint8_t rx_byte;
volatile uint32_t overflow_count;
volatile uint32_t error_count;
uint8_t initialized;
uint8_t running;
} UART_Rx_t;
UART_Rx_Status_t UART_Rx_Init(UART_Rx_t *device, UART_HandleTypeDef *huart,
uint8_t *buffer, uint16_t capacity);
UART_Rx_Status_t UART_Rx_Start(UART_Rx_t *device);
UART_Rx_Status_t UART_Rx_Stop(UART_Rx_t *device);
uint16_t UART_Rx_Available(const UART_Rx_t *device);
UART_Rx_Status_t UART_Rx_ReadByte(UART_Rx_t *device, uint8_t *byte);
/**
* @brief 从串口环形缓冲区取出一整行 ASCII 文本，并转换成 C 字符串。
* @param device 已 Init 且 Start 的 UART 接收对象，例如 &uart1_rx。
* @param line 用户提供的 char 数组，用于保存文本，例如 char line[32]。
* @param line_capacity line 数组总容量，必须写 sizeof(line)，不要手写数字。
* @return UART_RX_STATUS_OK：已得到一行；其他常见返回值见下方。
*
* 本函数适用于“串口助手文本发送”，不是十六进制二进制帧解析器。
* 例如电脑发送 hello 并按回车，串口收到的原始字节是：
* 0x68 0x65 0x6C 0x6C 0x6F 0x0D 0x0A
* 本函数返回后 line 内容是 "hello"；末尾的 \r 和 \n 被自动丢弃，且自动补 \0。
*
* 返回值含义：
* - UART_RX_STATUS_OK：已经收到 \n，line 内是一条完整字符串。
* - UART_RX_STATUS_EMPTY：目前没有收到任何字节。
* - UART_RX_STATUS_INCOMPLETE：收到了一部分文本，但尚未收到 \n；下次 while 循环再调用。
* - UART_RX_STATUS_BUFFER_SMALL：完整一行长度超过 line 数组容量；该行被丢弃。
*
* main.c 使用例子：
* @code
* char line[32];
* if (UART_Rx_ReadLine(&uart1_rx, line, sizeof(line)) == UART_RX_STATUS_OK)
* {
* // 电脑文本发送 hello + 回车：line 为 "hello"。
* // 电脑文本发送 12 + 回车：line[0]='1'，line[1]='2'，不是数值 12。
* UART_Tx_SendLine(&huart1, line, 100U);
* }
* @endcode
*
* 若题目给的是 AA 55 LEN DATA CHECKSUM 这类二进制报文，请使用
* UART_Rx_ReadByte() + Protocol_Parser_FeedByte()，不要使用本函数。
*/
UART_Rx_Status_t UART_Rx_ReadLine(UART_Rx_t *device, char *line, uint16_t line_capacity);
/**
* @brief 将一行纯十进制 ASCII 文本转换为可计算的 uint32_t 无符号整数。
* @param text 以 \0 结尾的字符串，通常来自 UART_Rx_ReadLine()，例如 "12"。
* @param value 转换成功后写入数值，例如 "12" 转为 12U。
* @return 1=转换成功；0=字符串为空、含非数字字符或数值超过 uint32_t 范围。
*
* 此函数只接受十进制非负整数，允许首尾空格和开头的 + 号：
* "12"、" 12 "、"+12" 均成功；"12.5"、"-12"、"hello" 均失败。
*
* main.c 使用例子：
* @code
* char line[32];
* uint32_t number;
* if (UART_Rx_ReadLine(&uart1_rx, line, sizeof(line)) == UART_RX_STATUS_OK)
* {
* if (UART_Rx_ParseU32(line, &number) != 0U)
* {
* number = number + 1U; // 电脑发 12，number 变成 13
* UART_Tx_SendU32(&huart1, number, 100U);
* }
* }
* @endcode
*/
uint8_t UART_Rx_ParseU32(const char *text, uint32_t *value);
/**
* @brief 将一行 ASCII 小数文本转换为可计算的 float 浮点数。
* @param text 以 \0 结尾的字符串，通常来自 UART_Rx_ReadLine()；例如 "3.287"。
* @param value 转换成功后写入浮点结果的变量地址，例如 &dac_pin_voltage。
* @return 1U：转换成功；0U：字符串格式错误或参数为 NULL，value 保持原值。
*
* 支持：首尾空格、可选的 + / - 号、整数部分和小数部分，例如 "12"、"3.287"、
* "-0.5"、".25"。不支持科学计数法（例如 "1e-3"）、逗号小数点（"3,2"）
* 和单位（"3.3V"）。发送端每条数据仍须以 \r\n 结尾。
*
* main.c 使用案例：电脑发送 3.287 并勾选“发送新行（CRLF）”后，变量保存为 3.287f。
* @code
* char line[32];
* float dac_pin_voltage;
*
* if (UART_Rx_ReadLine(&uart1_rx, line, sizeof(line)) == UART_RX_STATUS_OK)
* {
* if (UART_Rx_ParseFloat(line, &dac_pin_voltage) != 0U)
* {
* // 例如：3.287 + 1.0 = 4.287
* dac_pin_voltage = dac_pin_voltage + 1.0f;
*
* // 参数依次为：串口、浮点值、小数位数、超时 ms。
* UART_Tx_SendFloat(&huart1, dac_pin_voltage, 3U, 100U);
* UART_Tx_SendLine(&huart1, "", 100U);
* }
* else
* {
* UART_Tx_SendLine(&huart1, "Float format error", 100U);
* }
* }
* @endcode
*/
uint8_t UART_Rx_ParseFloat(const char *text, float *value);
UART_Rx_Status_t UART_Rx_Clear(UART_Rx_t *device);
uint32_t UART_Rx_GetOverflowCount(const UART_Rx_t *device);
uint32_t UART_Rx_GetErrorCount(const UART_Rx_t *device);
/* 单帧 DATA 最大长度。完整数组还需容纳帧头、长度和最多两个校验字节。 */
#define PROTOCOL_MAX_HEADER_LENGTH 16U /* 题目帧头超过 16 字节时，只改这个数值。 */
#define PROTOCOL_MAX_DATA_LENGTH 128U
#define PROTOCOL_MAX_FRAME_LENGTH (PROTOCOL_MAX_HEADER_LENGTH + 1U + PROTOCOL_MAX_DATA_LENGTH + 2U)
typedef enum
{
PROTOCOL_CHECKSUM_NONE = 0, /* 无校验：帧尾没有校验字节。 */
PROTOCOL_CHECKSUM_SUM8, /* LENGTH 和 DATA 累加，保留低 8 位。 */
PROTOCOL_CHECKSUM_XOR8, /* LENGTH 和 DATA 逐字节异或。 */
PROTOCOL_CHECKSUM_CRC16_MODBUS/* CRC 初值 FFFF，低字节先到。 */
} Protocol_Checksum_t;
typedef enum
{
PROTOCOL_STATUS_OK = 0,
PROTOCOL_STATUS_FRAME_READY, /* 一帧已校验完成，可调用 TakeFrame。 */
PROTOCOL_STATUS_INVALID_ARGUMENT,
PROTOCOL_STATUS_NOT_READY,
PROTOCOL_STATUS_LENGTH_ERROR,
PROTOCOL_STATUS_CHECKSUM_ERROR,
PROTOCOL_STATUS_BUSY
} Protocol_Status_t;
/* 这就是给业务程序用的完整帧数组。data[0] 永远是帧头的第一个字节。 */
typedef struct
{
uint16_t length; /* data[] 实际有效字节数。 */
uint8_t data[PROTOCOL_MAX_FRAME_LENGTH];/* 完整帧：帧头、长度、数据、校验。 */
} Protocol_Frame_t;
/* 解析器内部状态。只需定义变量和调用 API，不需直接修改成员。 */
typedef struct
{
uint8_t header[PROTOCOL_MAX_HEADER_LENGTH];
uint8_t header_length;
uint8_t header_index;
Protocol_Checksum_t checksum_type;
uint8_t state;
uint8_t data_length;
uint8_t received_data_count;
uint16_t checksum;
uint8_t received_crc_low;
Protocol_Frame_t completed_frame;
uint8_t frame_ready;
uint8_t initialized;
uint32_t frame_count;
uint32_t length_error_count;
uint32_t checksum_error_count;
} Protocol_Parser_t;
/* 设置帧头数组、帧头长度和校验方式；格式始终为 HEADER LENGTH DATA CHECKSUM。 */
Protocol_Status_t Protocol_Parser_Init(Protocol_Parser_t *parser,
const uint8_t *header, uint8_t header_length,
Protocol_Checksum_t checksum_type);
/* 每从 UART 环形缓冲区读到一个字节，就调用一次。 */
Protocol_Status_t Protocol_Parser_FeedByte(Protocol_Parser_t *parser, uint8_t byte);
uint8_t Protocol_Parser_IsFrameReady(const Protocol_Parser_t *parser);
/* 把已完成的一帧复制到 frame->data[]，并允许接收下一帧。 */
Protocol_Status_t Protocol_Parser_TakeFrame(Protocol_Parser_t *parser,
Protocol_Frame_t *frame);
#ifdef __cplusplus
}
#endif
#endif /* UART_RX_H */