/*
 * 模块名称：RS-485 半双工通信驱动
 * 模块功能：RS-485 半双工通信驱动实现，核心要点：
 *          1. 发送前拉高 DE（切换到发送态）
 *          2. HAL_UART_Transmit 内部已等待 TC（发送完成）标志
 *          3. 发送完毕后拉低 DE（切回接收态）
 *          4. 使用 HAL_UARTEx_ReceiveToIdle_IT 实现变长帧接收
 *          参考：ST AN3070 应用笔记、controllerstech.com RS485 教程
 * 适用平台：STM32F4 系列
 * 作者：王建锋
 * 创建日期：2026-07-18
 * 修改记录：
 *     2026-07-18  王建锋  创建初始版本
 */

#include "rs485.h"

/*
 * 内部辅助宏 - 方向控制
 */
#define RS485_DIR_TX(h)  HAL_GPIO_WritePin((h)->dir_port, (h)->dir_pin, GPIO_PIN_SET)
#define RS485_DIR_RX(h)  HAL_GPIO_WritePin((h)->dir_port, (h)->dir_pin, GPIO_PIN_RESET)

/*
 * 公共函数实现
 */

/*
 * 函数功能：初始化 RS-485 句柄
 * 入口参数：handle   - RS-485 句柄指针
 *           huart    - UART 外设句柄
 *           dir_port - DE 引脚 GPIO 端口
 *           dir_pin  - DE 引脚 GPIO 编号
 * 返回值：无
 * 限定条件：UART 和 GPIO 须先由 CubeMX 完成初始化
 * 函数说明：初始化后立即将 DE 拉低，使 RS-485 收发器处于接收状态
 */
void rs485_init(rs485_handle_t *handle,
                UART_HandleTypeDef *huart,
                GPIO_TypeDef *dir_port,
                uint16_t dir_pin)
{
    handle->huart    = huart;
    handle->dir_port = dir_port;
    handle->dir_pin  = dir_pin;
    handle->rx_size  = 0;

    /* 默认进入接收状态 */
    RS485_DIR_RX(handle);
}

/*
 * 函数功能：阻塞方式发送数据
 * 入口参数：handle  - RS-485 句柄指针
 *           data    - 待发送数据缓冲区
 *           len     - 待发送字节数
 *           timeout - 发送超时（ms），传 0 使用默认值
 * 返回值：HAL_OK / HAL_TIMEOUT / HAL_ERROR
 * 限定条件：须在主循环或 RTOS 任务中调用，不可在 UART 中断中调用
 * 函数说明：
 *   时序：DE=HIGH → UART 发送 N 字节 → 等 TC → DE=LOW
 *   HAL_UART_Transmit 内部会等待 TXE（发送寄存器空）逐字节搬数据，
 *   最后还会等待 TC（发送完成）标志，确保最后一字节的停止位已移出。
 *   因此返回后再拉低 DE 是安全的
 */
HAL_StatusTypeDef rs485_transmit(rs485_handle_t *handle,
                                  const uint8_t *data,
                                  uint16_t len,
                                  uint32_t timeout)
{
    HAL_StatusTypeDef status;

    if (timeout == 0U) {
        timeout = RS485_TIMEOUT_DEFAULT;
    }

    /* 1. 切换到发送状态 */
    RS485_DIR_TX(handle);

    /* 2. 阻塞发送（内部等待 TC） */
    status = HAL_UART_Transmit(handle->huart,
                                (uint8_t *)data,
                                len,
                                timeout);

    /* 3. 发送完毕或超时，切回接收状态 */
    RS485_DIR_RX(handle);

    return status;
}

/*
 * 函数功能：启动中断方式接收（IDLE 空闲帧检测）
 * 入口参数：handle    - RS-485 句柄指针
 *           buf       - 接收缓冲区
 *           buf_size  - 缓冲区最大容量
 * 返回值：HAL_OK / HAL_ERROR
 * 限定条件：UART 须已开启全局中断（NVIC 使能）
 * 函数说明：
 *   使用 HAL_UARTEx_ReceiveToIdle_IT 实现变长帧接收。
 *   当 UART 总线空闲超过 1 个字符时间后，硬件触发 IDLE 中断，
 *   HAL 自动调用 HAL_UARTEx_RxEventCallback 并返回已接收字节数。
 *   用户须在该回调中重新调用本函数重新开启接收
 */
HAL_StatusTypeDef rs485_receive_start(rs485_handle_t *handle,
                                       uint8_t *buf,
                                       uint16_t buf_size)
{
    handle->rx_size = 0;
    return HAL_UARTEx_ReceiveToIdle_IT(handle->huart, buf, buf_size);
}

/*
 * 函数功能：缓存最近一次接收的字节数
 * 入口参数：handle - RS-485 句柄指针
 *           size   - 本次接收到的字节数
 * 返回值：无
 * 限定条件：须在 HAL_UARTEx_RxEventCallback 中调用
 */
void rs485_rx_set_size(rs485_handle_t *handle, uint16_t size)
{
    handle->rx_size = size;
}

/*
 * 函数功能：获取最近一次接收的字节数
 * 入口参数：handle - RS-485 句柄指针
 * 返回值：字节数
 */
uint16_t rs485_rx_get_size(const rs485_handle_t *handle)
{
    return handle->rx_size;
}