433_STM32/Driver_RF433/Inc/rf433.h

/**
 ******************************************************************************
 * @file    rf433.h
 * @brief   RF433模块驱动主接口
 * @note    基于原e32_demo.h重构，保持与原版设备兼容
 ******************************************************************************
 */

#ifndef __RF433_H__
#define __RF433_H__

#ifdef __cplusplus
extern "C" {
#endif

#include "rf433_config.h"
#include "rf433_hal.h"
#include <stdint.h>
#include <stdbool.h>

/* ============================================================================
 * 错误码定义
 * ============================================================================ */

typedef enum
{
    RF433_OK                  = 0,  // 成功
    RF433_ERROR               = -1, // 通用错误
    RF433_ERROR_BUSY          = -2, // 模块忙
    RF433_ERROR_TIMEOUT       = -3, // 超时
    RF433_ERROR_INVALID_PARAM = -4, // 无效参数
    RF433_ERROR_NO_MEMORY     = -5, // 内存不足
    RF433_ERROR_NOT_INIT      = -6, // 未初始化
    RF433_ERROR_NO_DATA       = -7, // 无数据
} rf433_error_t;

/* ============================================================================
 * 配置参数枚举（与原e32_demo.h保持一致）
 * ============================================================================ */

typedef enum
{
    RF433_OFF = 0x00,
    RF433_ON  = 0x01,
} rf433_on_off_t;

typedef enum
{
    RF433_RADIO_RATE_2400   = 0x02,
    RF433_RADIO_RATE_4800   = 0x03,
    RF433_RADIO_RATE_9600   = 0x04,
    RF433_RADIO_RATE_19200  = 0x05,
    RF433_RADIO_RATE_38400  = 0x06,
    RF433_RADIO_RATE_62500  = 0x07,
} rf433_radio_rate_t;

typedef enum
{
    RF433_UART_8N1 = 0x00,
    RF433_UART_8O1 = 0x01,
    RF433_UART_8E1 = 0x02,
} rf433_uart_parity_t;

typedef enum
{
    RF433_UART_RATE_1200  = 0x00,
    RF433_UART_RATE_2400  = 0x01,
    RF433_UART_RATE_4800  = 0x02,
    RF433_UART_RATE_9600  = 0x03,
    RF433_UART_RATE_19200 = 0x04,
    RF433_UART_RATE_38400 = 0x05,
    RF433_UART_RATE_57600 = 0x06,
    RF433_UART_RATE_115200= 0x07,
} rf433_uart_rate_t;

typedef enum
{
    RF433_WOR_PERIOD_250MS  = 0x00,
    RF433_WOR_PERIOD_500MS  = 0x01,
    RF433_WOR_PERIOD_750MS  = 0x02,
    RF433_WOR_PERIOD_1000MS = 0x03,
    RF433_WOR_PERIOD_1250MS = 0x04,
    RF433_WOR_PERIOD_1500MS = 0x05,
    RF433_WOR_PERIOD_1750MS = 0x06,
    RF433_WOR_PERIOD_2000MS = 0x07,
} rf433_wor_period_t;

typedef enum
{
    RF433_TX_POWER_DBM_30  = 0x00,
    RF433_TX_POWER_DBM_27  = 0x01,
    RF433_TX_POWER_DBM_24  = 0x02,
    RF433_TX_POWER_DBM_21  = 0x03,
} rf433_transmit_power_t;

/* ============================================================================
 * 配置结构体（与原e32_register_t保持一致）
 * ============================================================================ */

typedef struct
{
    /* 00H是固定HEAD，无法修改 */
    
    /* ======== 用户参数寄存器 01H ======== */
    struct 
    {
        uint8_t address_h; /* 模块地址      (用户参数寄存器地址: 01H、02H) 不同地址的模块无法直接互相通信(广播地址除外); 65535为广播地址，用于群发信息  */	
    }register_1;
    
    /* ======== 用户参数寄存器 02H ======== */
    struct 
    {
        uint8_t address_l;
    }register_2;    
     
    /* ======== 用户参数寄存器 03H ======== */
    union {
        uint8_t value;
        struct
        {
            rf433_radio_rate_t     radio_rate             : 3;  /* 空中速率     (寄存器地址: 03H Bit2-0) 速率越高，抗干扰性越差，传输距离越近；但传输速率越高，延迟越小 */
            rf433_uart_rate_t      uart_baud_rate         : 3;  /* 串口波特率   (寄存器地址: 03H Bit7-5) 省电模式(模式2)是强制固定波特率为9600；其他传输模式时为用户设置的串口波特率 */
            rf433_uart_parity_t    uart_parity            : 2;  /* 串口校验位   (寄存器地址: 03H Bit4-3) */
        }field;
    }register_3;
    
    /* ======== 用户参数寄存器 04H ======== */
    struct 
    {
        uint8_t channel;  /* 信道参数      (寄存器地址: 04H) 相邻信道间隔1MHz，模块通信频率与信道有关；通信频率 = 起始频率 + (1MHz x 信道参数)  */
    }register_4;   	
    
    /* ======== 用户参数寄存器 05H ======== */
    union {
        uint8_t value;
        struct
        {
            rf433_transmit_power_t tx_power               : 2;  /* 发射功率                         (寄存器地址: 05H Bit1-0) 不同型号的模块的功率值可能不一样，具体值需要参考模块手册 */
            rf433_on_off_t         packet_fec             : 1;	/* 前向纠错FEC                      (寄存器地址: 05H Bit2  ) 收发双方必须一致，否则无法通信。开启后，抗干扰性明显提升，但传输速率会降低 */
            rf433_wor_period_t     wake_on_radio_period   : 3;  /* 无线唤醒WOR周期                  (寄存器地址: 05H Bit2-0) 收发双方必须设置一致，否则无法通信 */	
            rf433_on_off_t         reserve                : 1;  /* 保留 IO输出方式*/
            rf433_on_off_t         specify_target         : 1;  /* 指定目标传输，也叫定点传输模式       (寄存器地址: 05H Bit7  ) 用户在发送数据时，需要在数据的首字节写入目标地址和信道 */
        }field;
    }register_5;
    
}rf433_register_t;

/* ============================================================================
 * 数据包结构体（与原e32_specify_target_buffer_t保持一致）
 * ============================================================================ */

typedef struct
{
    uint8_t address_h;           // 目标地址高字节
    uint8_t address_l;           // 目标地址低字节
    uint8_t channel;             // 目标信道
    uint8_t data[237];          // 数据（最大237字节）
} rf433_specify_target_buffer_t;

/* ============================================================================
 * 命令枚举（与原request_cmd_t保持一致）
 * ============================================================================ */

typedef enum
{
    RF433_REQUEST_CMD_CONFIG    =  0x00,
    RF433_REQUEST_CMD_NAME      ,
    RF433_REQUEST_CMD_VERSION   ,
} rf433_request_cmd_t;

/* ============================================================================
 * 回调函数类型定义
 * ============================================================================ */

/**
 * @brief 数据接收回调函数类型
 * @param data 接收到的数据
 * @param length 数据长度
 * @param user_data 用户数据
 */
typedef void (*rf433_rx_callback_t)(const uint8_t *data, uint16_t length, void *user_data);

/**
 * @brief 发送完成回调函数类型
 * @param status 发送状态
 * @param user_data 用户数据
 */
typedef void (*rf433_tx_callback_t)(rf433_error_t status, void *user_data);

/* ============================================================================
 * 核心API函数
 * ============================================================================ */

/**
 * @brief 初始化RF433模块
 * @param config 初始配置（NULL使用默认配置）
 * @return RF433_OK 成功
 *         RF433_ERROR 失败
 */
rf433_error_t rf433_init(const rf433_register_t *config);

/**
 * @brief 反初始化RF433模块
 * @return RF433_OK 成功
 */
rf433_error_t rf433_deinit(void);

/**
 * @brief 设置模块配置（基于原e32_demo_menu_config）
 * @param config 配置参数
 * @return RF433_OK 成功
 *         RF433_ERROR_BUSY 模块忙
 *         RF433_ERROR_TIMEOUT 超时
 */
rf433_error_t rf433_set_config(const rf433_register_t *config);

/**
 * @brief 获取模块配置
 * @param config 配置参数输出
 * @return RF433_OK 成功
 *         RF433_ERROR_INVALID_PARAM 无效参数
 */
rf433_error_t rf433_get_config(rf433_register_t *config);

/**
 * @brief 设置工作模式
 * @param mode 工作模式
 * @return RF433_OK 成功
 *         RF433_ERROR_BUSY 模块忙
 */
rf433_error_t rf433_set_work_mode(rf433_work_mode_t mode);

/**
 * @brief 复位模块
 * @return RF433_OK 成功
 */
rf433_error_t rf433_reset(void);

/* ============================================================================
 * 条件编译的TX/RX API
 * ============================================================================ */

#if (RF433_MODE == RF433_MODE_TX) || (RF433_MODE == RF433_MODE_BOTH)

/**
 * @brief 发送数据（透明传输模式，基于原e32_demo_transmit）
 * @param buffer 数据指针
 * @param length 数据长度
 * @return RF433_OK 成功
 *         RF433_ERROR_BUSY 模块忙
 *         RF433_ERROR_TIMEOUT 超时
 *         RF433_ERROR_INVALID_PARAM 无效参数
 */
rf433_error_t rf433_transmit(uint8_t *buffer, uint16_t length);

/**
 * @brief 发送数据包（指定目标模式）
 * @param packet 数据包
 * @return RF433_OK 成功
 *         RF433_ERROR_BUSY 模块忙
 *         RF433_ERROR_TIMEOUT 超时
 *         RF433_ERROR_INVALID_PARAM 无效参数
 */
rf433_error_t rf433_transmit_packet(const rf433_specify_target_buffer_t *packet);

#endif /* (RF433_MODE == RF433_MODE_TX) || (RF433_MODE == RF433_MODE_BOTH) */

#if (RF433_MODE == RF433_MODE_RX) || (RF433_MODE == RF433_MODE_BOTH)

/**
 * @brief 启动接收
 * @return RF433_OK 成功
 *         RF433_ERROR_BUSY 模块忙
 */
rf433_error_t rf433_rx_start(void);

/**
 * @brief 停止接收
 * @return RF433_OK 成功
 */
rf433_error_t rf433_rx_stop(void);

/**
 * @brief 接收数据（阻塞模式）
 * @param buffer 数据缓冲区
 * @param max_length 最大接收长度
 * @param actual_length 实际接收长度
 * @param timeout 超时时间（ms）
 * @return RF433_OK 成功
 *         RF433_ERROR_TIMEOUT 超时
 *         RF433_ERROR_INVALID_PARAM 无效参数
 */
rf433_error_t rf433_receive(uint8_t *buffer, uint16_t max_length, uint16_t *actual_length, uint32_t timeout);

/**
 * @brief 检查是否有数据可读
 * @param has_data 是否有数据输出
 * @return RF433_OK 成功
 */
rf433_error_t rf433_rx_check_data(bool *has_data);

/**
 * @brief 读取数据（非阻塞模式）
 * @param buffer 数据缓冲区
 * @param max_length 最大读取长度
 * @param actual_length 实际读取长度
 * @return RF433_OK 成功
 *         RF433_ERROR_NO_DATA 无数据
 *         RF433_ERROR_INVALID_PARAM 无效参数
 */
rf433_error_t rf433_rx_read(uint8_t *buffer, uint16_t max_length, uint16_t *actual_length);

/**
 * @brief 注册接收回调函数
 * @param callback 回调函数
 * @param user_data 用户数据
 * @return RF433_OK 成功
 *         RF433_ERROR_INVALID_PARAM 无效参数
 */
rf433_error_t rf433_rx_register_callback(rf433_rx_callback_t callback, void *user_data);

/**
 * @brief 注销接收回调函数
 * @return RF433_OK 成功
 */
rf433_error_t rf433_rx_unregister_callback(void);

#endif /* (RF433_MODE == RF433_MODE_RX) || (RF433_MODE == RF433_MODE_BOTH) */

#ifdef __cplusplus
}
#endif

#endif /* __RF433_H__ */