/**
  ******************************************************************************
  * @file    integration_guide.md
  * @brief   应用层模块集成指南
  * @author  Application Layer
  * @version 1.0
  ******************************************************************************
  * @attention
  * 本文档说明如何将uart2_print、io_monitor、cmd_parser、relay_control
  * 四个模块集成到现有工程中。
  ******************************************************************************
  */

# 应用层模块集成指南

## 一、文件清单

### 新增文件

| 文件路径 | 说明 |
|---------|------|
| `Core/Inc/uart2_print.h` | UART2打印模块头文件 |
| `Core/Src/uart2_print.c` | UART2打印模块实现 |
| `Core/Inc/io_monitor.h` | IO监控模块头文件 |
| `Core/Src/io_monitor.c` | IO监控模块实现 |
| `Core/Inc/cmd_parser.h` | 指令解析模块头文件 |
| `Core/Src/cmd_parser.c` | 指令解析模块实现 |
| `Core/Inc/relay_control.h` | 继电器控制模块头文件 |
| `Core/Src/relay_control.c` | 继电器控制模块实现 |

### 需要修改的文件

| 文件路径 | 修改内容 |
|---------|---------|
| `Core/Src/main.c` | 添加头文件引用、初始化调用、主循环任务 |
| `Core/Src/usart.c` | 添加UART2接收中断处理 |
| `Core/Src/stm32f1xx_it.c` | 添加UART2接收缓冲变量 |

---

## 二、main.c 修改说明

### 2.1 在 `USER CODE BEGIN Includes` 区域添加

```c
/* USER CODE BEGIN Includes */
#include "rf433.h"
#include "rf433_config.h"
#include "rf433_hal.h"

/* 应用层模块头文件 */
#include "uart2_print.h"
#include "io_monitor.h"
#include "cmd_parser.h"
#include "relay_control.h"

#if (RF433_MODE == RF433_MODE_TX) || (RF433_MODE == RF433_MODE_BOTH)
#include "rf433_tx_app.h"
#endif

#if (RF433_MODE == RF433_MODE_RX) || (RF433_MODE == RF433_MODE_BOTH)
#include "rf433_rx_app.h"
#endif

/* USER CODE END Includes */
```

### 2.2 在 `USER CODE BEGIN PV` 区域添加

```c
/* USER CODE BEGIN PV */
static uint8_t uart2_rx_byte = 0;
/* USER CODE END PV */
```

### 2.3 在 `USER CODE BEGIN 2` 区域修改

```c
  /* USER CODE BEGIN 2 */
  
  /* 初始化应用层模块 */
  UART2_Print_Init();
  IO_Monitor_Init();
  CmdParser_Init();
  Relay_Init();
  
  /* 启动UART2接收中断 */
  HAL_UART_Receive_IT(&huart2, &uart2_rx_byte, 1);
  
  /* 初始化RF433模块 - 使用默认配置 */
  rf433_init(NULL);
   
  /* 启动UART接收 - 使用rf433_hal中的临时变量 */
  HAL_UART_Receive_IT(&huart1, &rf433_uart_rx_tmp, 1);
  
  /* 根据配置模式初始化TX/RX应用层 */
#if (RF433_MODE == RF433_MODE_TX) || (RF433_MODE == RF433_MODE_BOTH)
  /* TX模式初始化 */
  rf433_tx_app_init(NULL);
  rf433_tx_app_start(RF433_DEFAULT_TX_COUNT, RF433_DEFAULT_TX_INTERVAL);
#endif

#if (RF433_MODE == RF433_MODE_RX) || (RF433_MODE == RF433_MODE_BOTH)
  /* RX模式初始化 */
  rf433_rx_app_init(NULL);
  rf433_rx_app_start();
#endif
  
  /* 打印启动信息 */
  UART2_Print_Printf("\r\n========================================\r\n");
  UART2_Print_Printf("E32-433TBH-SC Application Started\r\n");
  UART2_Print_Printf("System Clock: %d MHz\r\n", SystemCoreClock / 1000000);
  UART2_Print_Printf("========================================\r\n");
  
  /* USER CODE END 2 */
```

### 2.4 在 `USER CODE BEGIN 3` 区域修改

```c
    /* USER CODE BEGIN 3 */
    
    /* 应用层任务处理 */
    UART2_Print_Task();
    IO_Monitor_Task();
    CmdParser_Task();
    
#if (RF433_MODE == RF433_MODE_TX) || (RF433_MODE == RF433_MODE_BOTH)
    /* TX任务 */
    rf433_tx_app_task();
#endif

#if (RF433_MODE == RF433_MODE_RX) || (RF433_MODE == RF433_MODE_BOTH)
    /* RX任务 */
    rf433_rx_app_task();
#endif
    
    /* USER CODE END 3 */
```

### 2.5 在 `USER CODE BEGIN 4` 区域添加

```c
/* USER CODE BEGIN 4 */

void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart)
{
    if (huart->Instance == USART1)
    {
        /* 调用RF433模块的UART接收回调 */
        rf433_hal_uart_rxcplt_callback();
    }
    else if (huart->Instance == USART2)
    {
        /* 喂入指令解析器 */
        CmdParser_FeedByte(uart2_rx_byte, HAL_GetTick());
        
        /* 重新启动接收 */
        HAL_UART_Receive_IT(&huart2, &uart2_rx_byte, 1);
    }
}

void HAL_UART_TxCpltCallback(UART_HandleTypeDef *huart)
{
    if (huart->Instance == USART2)
    {
        /* 调用UART2打印模块的发送完成回调 */
        UART2_Print_TxCpltCallback();
    }
}

/* USER CODE END 4 */
```

---

## 三、usart.c 修改说明

### 3.1 删除原有的 `HAL_UART_RxCpltCallback` 函数

原有的回调函数在 `USER CODE BEGIN 1` 区域，需要删除：

```c
/* USER CODE BEGIN 1 */
// 删除以下代码
// void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart)
// {
//     if (huart->Instance == USART1)
//     {
//         rf433_hal_uart_rxcplt_callback();
//     }
// }
/* USER CODE END 1 */
```

改为：

```c
/* USER CODE BEGIN 1 */
/* UART回调函数已移至main.c统一管理 */
/* USER CODE END 1 */
```

---

## 四、Keil工程配置

### 4.1 添加源文件到工程

1. 打开Keil工程 `MDK-ARM/project.uvprojx`
2. 在Project窗口中，右键点击 `Application/User/Core` 分组
3. 选择 `Add Existing Files...`
4. 添加以下文件：
   - `Core/Src/uart2_print.c`
   - `Core/Src/io_monitor.c`
   - `Core/Src/cmd_parser.c`
   - `Core/Src/relay_control.c`

### 4.2 添加头文件路径

1. 点击工程设置图标（魔术棒）
2. 切换到 `C/C++` 标签页
3. 在 `Include Paths` 中确认 `Core/Inc` 已在路径中

---

## 五、测试验证

### 5.1 编译工程

编译应无错误，如有警告请检查：
- 头文件路径是否正确
- 源文件是否已添加到工程

### 5.2 下载运行

下载程序后，通过串口调试助手连接UART2（115200bps），应看到：

```
========================================
E32-433TBH-SC Application Started
System Clock: 72 MHz
========================================
[UART2] Init OK, buffer size: 256
[IO] Init OK, initial states: 0x00
[CMD] Init OK
[RELAY] Init OK, state=OFF
```

### 5.3 指令测试

发送以下指令测试：

```
$RL,1,1*FF\r\n     打开继电器1
$RL,1,0*FF\r\n     关闭继电器1
$DI,0*FF\r\n       查询所有DI状态
$DI,1*FF\r\n       查询DI1状态
$ECHO*FF\r\n       心跳测试
```

---

## 六、注意事项

1. **不要修改HAL初始化代码**：`MX_GPIO_Init`、`MX_USARTx_UART_Init` 等函数由CubeMX生成，不应手动修改

2. **中断优先级**：UART1优先级为0，UART2优先级为1，UART3优先级为2，已按计划配置

3. **调试开关**：各模块开头有 `DEBUG_xxx` 宏，设为1启用调试日志，设为0禁用

4. **缓冲区大小**：`UART2_TX_BUFFER_SIZE` 默认256字节，可根据需要调整

5. **去抖参数**：`IO_DEBOUNCE_COUNT` 默认3次，`IO_SCAN_PERIOD_MS` 默认10ms