/*******************************************************************************
 * File Name         : PythonLink.h
 * Description       : Python通信链路模块 - 用于发送GPS/IMU数据到Python程序
 * Created on        : 2025-11-13
 * Author            : Auto-generated
 *******************************************************************************/

#ifndef FML_PYTHONLINK_H_
#define FML_PYTHONLINK_H_

/*******************************************************************************
 *                              Include Files                                  *
 *******************************************************************************/
#include "HIDO_TypeDef.h"
#include "GPS.h"

/*******************************************************************************
 *                                  Macro                                      *
 *******************************************************************************/
// 协议帧格式常量
#define PYTHONLINK_FRAME_HEADER1        0xAA    // 帧头1
#define PYTHONLINK_FRAME_HEADER2        0x55    // 帧头2
#define PYTHONLINK_FRAME_FOOTER1        0x0D    // 帧尾1 (CR)
#define PYTHONLINK_FRAME_FOOTER2        0x0A    // 帧尾2 (LF)

// 数据类型定义
#define PYTHONLINK_TYPE_GPS             0x01    // GPS数据包 (10Hz)
#define PYTHONLINK_TYPE_IMU             0x02    // IMU数据包 (100Hz)
#define PYTHONLINK_TYPE_CONTROL         0x10    // 控制命令包 (Python->STM32)

// 缓冲区大小
#define PYTHONLINK_TX_BUF_SIZE          2048    // 发送缓冲区 (增大以减少 DMA 发送队列溢出/丢包)
#define PYTHONLINK_RX_BUF_SIZE          1024     // 接收缓冲区 (增大以适应DMA循环缓冲)

// 调试选项: 置1则发送固定内容以排查乱码
#define PYTHONLINK_FORCE_FIXED_PAYLOAD  0

/*******************************************************************************
 *                             Type Definition                                 *
 *******************************************************************************/

/**
 * @brief GPS数据包结构 (用于发送到Python)
 * 包含: 航向角、经纬度、东北天速度、定位质量等
 */
typedef struct __attribute__((packed))
{
    HIDO_DOUBLE m_dLatitude;             // 纬度(°), 正数为北纬
    HIDO_DOUBLE m_dLongitude;            // 经度(°), 正数为东经
    HIDO_FLOAT m_fHeadingAngle;          // 航向角(°), 0~360
    HIDO_FLOAT m_fPitchAngle;            // 俯仰角(°)
    HIDO_FLOAT m_fRollAngle;             // 横滚角(°)
    HIDO_FLOAT m_fEastVelocity;          // 东方向速度(m/s)
    HIDO_FLOAT m_fNorthVelocity;         // 北方向速度(m/s)
    HIDO_FLOAT m_fUpVelocity;            // 天顶方向速度(m/s)
    HIDO_FLOAT m_fAltitude;              // 高程(m)
    HIDO_UINT32 m_u32UTCTime;            // UTC时间, hhmmss格式
    HIDO_UINT8 m_u8PositionQuality;      // 定位质量: 0=无效,1=单点,2=差分,4=固定,5=浮点
    HIDO_UINT8 m_u8SatelliteCount;       // 卫星数量
    HIDO_UINT8 m_u8Reserved[2];          // 保留字节(对齐)
} ST_PythonLink_GPS;

/**
 * @brief IMU数据包结构 (用于发送到Python)
 * 包含: 三轴加速度、三轴角速度、温度
 */
typedef struct __attribute__((packed))
{
    HIDO_FLOAT m_fAccelX;                // X轴加速度(g)
    HIDO_FLOAT m_fAccelY;                // Y轴加速度(g)
    HIDO_FLOAT m_fAccelZ;                // Z轴加速度(g)
    HIDO_FLOAT m_fGyroX;                 // X轴角速度(°/s)
    HIDO_FLOAT m_fGyroY;                 // Y轴角速度(°/s)
    HIDO_FLOAT m_fGyroZ;                 // Z轴角速度(°/s)
    HIDO_FLOAT m_fTemperature;           // 传感器温度(℃)
    HIDO_UINT32 m_u32UTCTime;            // UTC时间, hhmmss.sss格式(毫秒)
} ST_PythonLink_IMU;

/**
 * @brief 数据帧头结构
 */
typedef struct __attribute__((packed))
{
    HIDO_UINT8 m_u8Header1;              // 帧头1 (0xAA)
    HIDO_UINT8 m_u8Header2;              // 帧头2 (0x55)
    HIDO_UINT8 m_u8Type;                 // 数据类型
    HIDO_UINT16 m_u16Length;             // 数据长度(payload)
} ST_PythonLink_FrameHeader;

/**
 * @brief 数据帧尾结构
 */
typedef struct __attribute__((packed))
{
    HIDO_UINT16 m_u16CRC;                // CRC16校验
    HIDO_UINT8 m_u8Footer1;              // 帧尾1 (0x0D)
    HIDO_UINT8 m_u8Footer2;              // 帧尾2 (0x0A)
} ST_PythonLink_FrameFooter;

/**
 * @brief 控制命令包结构 (Python -> STM32)
 * 包含: 转向PWM和油门PWM值
 */
typedef struct __attribute__((packed))
{
    HIDO_UINT16 m_u16SteeringPWM;        // 转向PWM值 (1000~2000us)
    HIDO_UINT16 m_u16ThrottlePWM;        // 油门PWM值 (1000~2000us)
} ST_PythonLink_Control;

/*******************************************************************************
 *                             Global Function                                 *
 *******************************************************************************/

/**
 * @brief 初始化 PythonLink 模块
 *        - 配置 UART5 DMA 发送和接收
 *        - 初始化内部缓冲区
 * @return HIDO_OK: 成功, HIDO_ERR: 失败
 */
HIDO_INT32 PythonLink_Init(HIDO_VOID);

/**
 * @brief PythonLink 轮询函数 (在主循环中定期调用)
 *        - 处理接收数据(接收Python控制命令)
 *        - 解析控制命令并应用到PWM输出
 * @return 无
 */
HIDO_VOID PythonLink_Poll(HIDO_VOID);

/**
 * @brief 获取最新的控制命令
 * @param _pu16SteeringPWM: 转向PWM值输出指针 (1000~2000us)
 * @param _pu16ThrottlePWM: 油门PWM值输出指针 (1000~2000us)
 * @param _pu32Timestamp: 时间戳输出指针 (ms)
 * @return HIDO_TRUE: 有有效命令, HIDO_FALSE: 无有效命令
 */
HIDO_BOOL PythonLink_GetControl(HIDO_UINT16 *_pu16SteeringPWM, 
                                 HIDO_UINT16 *_pu16ThrottlePWM,
                                 HIDO_UINT32 *_pu32Timestamp);

/**
 * @brief 发送GPS数据包到Python
 *        - 自动封装为协议帧并通过DMA发送
 *        - 适用于10Hz GPS数据更新
 * @param _pstGPRMI: GPRMI数据结构指针
 * @return HIDO_OK: 成功, HIDO_ERR: 失败
 */
HIDO_INT32 PythonLink_SendGPSData(const ST_GPRMI *_pstGPRMI);

/**
 * @brief 发送IMU数据包到Python
 *        - 自动封装为协议帧并通过DMA发送
 *        - 适用于100Hz IMU数据更新
 * @param _pstGPIMU: GPIMU数据结构指针
 * @return HIDO_OK: 成功, HIDO_ERR: 失败
 */
HIDO_INT32 PythonLink_SendIMUData(const ST_GPIMU *_pstGPIMU);

/**
 * @brief 获取发送统计信息
 * @param _pu32GPSCount: GPS数据包发送计数
 * @param _pu32IMUCount: IMU数据包发送计数
 * @param _pu32ErrorCount: 发送错误计数
 * @return 无
 */
HIDO_VOID PythonLink_GetStats(HIDO_UINT32 *_pu32GPSCount, 
                               HIDO_UINT32 *_pu32IMUCount, 
                               HIDO_UINT32 *_pu32ErrorCount);

/**
 * @brief 打印调试信息
 * @return 无
 */
HIDO_VOID PythonLink_PrintDebugInfo(HIDO_VOID);
HIDO_VOID PythonLink_PrintRxDebug(HIDO_VOID);

#endif /* FML_PYTHONLINK_H_ */