stm32-iot-sensor-node/32_MODULES.md

# 模块接口设计文档

## 1. 模块概览

### 1.1 模块分类
```
mylib/
├── 通信模块 (Communication)
│   ├── esp8266.c/.h      # WiFi通信模块
│   ├── usart1.c/.h       # 串口通信模块
│   └── queue.c/.h        # 数据队列管理
├── 传感器模块 (Sensors)
│   ├── dht11.c/.h        # 温湿度传感器
│   └── adc.c/.h          # ADC模数转换
├── 显示模块 (Display)
│   ├── oled.c/.h         # OLED显示屏
│   └── wfont.c/.h        # 中文字库
├── 控制模块 (Control)
│   ├── led.c/.h          # LED控制
│   ├── beep.c/.h         # 蜂鸣器控制
│   └── button.c/.h       # 按键输入
├── 系统模块 (System)
│   ├── systick.c/.h      # 系统定时器
│   ├── delay.c/.h        # 延时函数
│   ├── iwdg.c/.h         # 独立看门狗
│   └── eeprom.c/.h       # EEPROM存储
└── 硬件抽象层 (HAL)
    └── gpio_iic.c/.h     # GPIO模拟I²C
```

## 2. 通信模块接口

### 2.1 ESP8266 WiFi模块 (esp8266.h/.c)

**功能描述**: ESP8266 WiFi模块驱动，提供AT指令控制和TCP通信功能

**硬件连接**:
- PA2: USART2_RX (ESP8266 TX)
- PA3: USART2_TX (ESP8266 RX)

**API接口**:
```c
// 模块初始化
void esp8266_init(void);
/*
 * 功能: 初始化ESP8266模块和USART2
 * 参数: 无
 * 返回: 无
 * 说明: 配置USART2波特率115200，初始化接收队列
 */

// WiFi连接
int esp8266_connect_wifi(const char *ssid, const char *passwd);
/*
 * 功能: 连接到指定的WiFi网络
 * 参数: ssid - WiFi名称, passwd - WiFi密码
 * 返回: 1-连接成功, 0-连接失败
 * 说明: 发送AT+CWJAP指令连接WiFi
 */

// TCP连接
int esp8266_tcp_connect(const char *ip, uint16_t port);
/*
 * 功能: 建立TCP客户端连接
 * 参数: ip - 服务器IP地址, port - 端口号
 * 返回: 1-连接成功, 0-连接失败
 * 说明: 使用AT+CIPSTART建立TCP连接
 */

// 数据发送
int esp8266_write(const char *data, uint16_t len);
/*
 * 功能: 通过TCP发送数据
 * 参数: data - 数据缓冲区, len - 数据长度
 * 返回: 实际发送的字节数，0表示失败
 * 说明: 使用AT+CIPSEND发送数据
 */

// 数据接收
uint16_t esp8266_read(char *buf, uint16_t buf_size);
/*
 * 功能: 读取接收到的数据
 * 参数: buf - 接收缓冲区, buf_size - 缓冲区大小
 * 返回: 实际读取的字节数
 * 说明: 从接收队列中读取数据
 */

// 清空缓冲区
void esp8266_clear_read_buf(void);
/*
 * 功能: 清空接收缓冲区
 * 参数: 无
 * 返回: 无
 */

// 关闭连接
void esp8266_tcp_close(void);
/*
 * 功能: 关闭TCP连接
 * 参数: 无
 * 返回: 无
 */
```

**使用示例**:
```c
// 初始化并连接WiFi
esp8266_init();
if (esp8266_connect_wifi("my_wifi", "password123")) {
    printf("WiFi连接成功\r\n");

    // 连接服务器
    if (esp8266_tcp_connect("192.168.1.100", 5000)) {
        printf("服务器连接成功\r\n");

        // 发送数据
        char data[] = "Hello Server!";
        int sent = esp8266_write(data, strlen(data));
        printf("发送了%d字节数据\r\n", sent);
    }
}
```

### 2.2 USART1串口模块 (usart1.h/.c)

**功能描述**: USART1串口通信，主要用于调试输出

**硬件连接**:
- PA9: USART1_TX
- PA10: USART1_RX

**API接口**:
```c
// 串口初始化
void usart1_init(u32 baudrate);
/*
 * 功能: 初始化USART1
 * 参数: baudrate - 波特率 (通常115200)
 * 返回: 无
 */

// 发送字符串
void usart1_send_string(const char *str);
/*
 * 功能: 发送字符串到USART1
 * 参数: str - 字符串指针
 * 返回: 无
 */

// 发送单个字符
void usart1_send_char(char c);
/*
 * 功能: 发送单个字符
 * 参数: c - 字符
 * 返回: 无
 */

// 重定向printf
int fputc(int ch, FILE *f);
/*
 * 功能: printf重定向到USART1
 * 参数: ch - 字符, f - 文件指针
 * 返回: 发送的字符
 */
```

## 3. 传感器模块接口

### 3.1 DHT11温湿度传感器 (dht11.h/.c)

**功能描述**: DHT11数字温湿度传感器驱动

**硬件连接**:
- PC10: DHT11数据线

**数据格式**:
```
buf[0]: 湿度整数部分
buf[1]: 湿度小数部分
buf[2]: 温度整数部分
buf[3]: 温度小数部分
buf[4]: 校验和 (前4字节之和的低8位)
```

**API接口**:
```c
// 传感器初始化
void dht11_init(void);
/*
 * 功能: 初始化DHT11传感器引脚
 * 参数: 无
 * 返回: 无
 * 说明: 配置PC10为开漏输出模式
 */

// 读取传感器数据
int dht11_get_values(u8 buf[5]);
/*
 * 功能: 读取温湿度数据
 * 参数: buf - 5字节数据缓冲区
 * 返回: 1-读取成功, 0-读取失败
 * 说明: 执行完整的数据读取时序，包含校验
 */
```

**使用示例**:
```c
u8 dht11_data[5];
if (dht11_get_values(dht11_data)) {
    // 数据校验成功
    float humidity = dht11_data[0] + dht11_data[1] * 0.1;
    float temperature = dht11_data[2] + dht11_data[3] * 0.1;
    printf("温度: %.1f°C, 湿度: %.1f%%\r\n", temperature, humidity);
} else {
    printf("DHT11读取失败\r\n");
}
```

### 3.2 ADC模数转换模块 (adc.h/.c)

**功能描述**: ADC多通道模拟量采集

**硬件连接**:
- PA0-PA7: ADC通道0-7

**API接口**:
```c
// ADC初始化
void adc1_init(void);
/*
 * 功能: 初始化ADC1
 * 参数: 无
 * 返回: 无
 * 说明: 配置ADC为连续转换模式，启用DMA
 */

// 读取ADC通道值
float adc1_read_channel(u8 channel);
/*
 * 功能: 读取指定ADC通道的电压值
 * 参数: channel - ADC通道号 (0-7)
 * 返回: 电压值 (V)
 * 说明: 返回转换后的实际电压值
 */
```

## 4. 显示模块接口

### 4.1 OLED显示屏模块 (oled.h/.c)

**功能描述**: 128x64分辨率OLED显示屏驱动

**硬件连接**:
- PB6: I²C时钟线 (SCL)
- PB7: I²C数据线 (SDA)

**显示特性**:
- 分辨率: 128x64像素
- 接口: I²C (0x78)
- 缓冲区: 128x8字节帧缓冲

**API接口**:
```c
// OLED初始化
void oled_init(void);
/*
 * 功能: 初始化OLED显示屏
 * 参数: 无
 * 返回: 无
 * 说明: 发送初始化指令序列
 */

// 清空屏幕
void oled_clear(void);
/*
 * 功能: 清空显示内容
 * 参数: 无
 * 返回: 无
 */

// 填充屏幕
void oled_fill(u8 fill_data);
/*
 * 功能: 用指定数据填充屏幕
 * 参数: fill_data - 填充数据 (0x00-0xFF)
 * 返回: 无
 */

// 绘制像素点
void oled_draw_point(u8 x, u8 y, u8 val);
/*
 * 功能: 在指定位置绘制像素点
 * 参数: x - X坐标(0-127), y - Y坐标(0-63), val - 像素值
 * 返回: 无
 */

// 绘制文本
void oled_draw_text8(u8 x, u8 y, const char *text);
/*
 * 功能: 绘制8x16像素文本
 * 参数: x - 起始X坐标, y - 起始Y坐标, text - 文本内容
 * 返回: 无
 */

// 绘制中文文本
void oled_draw_text16(u8 x, u8 y, const char *text);
/*
 * 功能: 绘制16x16像素中文文本
 * 参数: x - 起始X坐标, y - 起始Y坐标, text - 中文文本
 * 返回: 无
 * 说明: 支持GBK编码中文字符
 */

// 刷新显示
void oled_refresh_framebuffer(void);
/*
 * 功能: 将帧缓冲区内容刷新到屏幕
 * 参数: 无
 * 返回: 无
 */
```

**使用示例**:
```c
// 初始化OLED
oled_init();
oled_clear();

// 显示文本
oled_draw_text8(0, 0, "Hello");
oled_draw_text16(0, 16, "温度");

// 刷新显示
oled_refresh_framebuffer();
```

### 4.2 中文字库模块 (wfont.h/.c)

**功能描述**: OLED中文显示字库

**字库特性**:
- 编码: GBK
- 字体: 16x16像素
- 范围: 常用汉字

**API接口**:
```c
// 获取汉字字模数据
const u8* get_chinese_font(const char *gbk_char);
/*
 * 功能: 获取GBK字符的字模数据
 * 参数: gbk_char - GBK编码字符 (2字节)
 * 返回: 32字节字模数据指针
 */
```

## 5. 控制模块接口

### 5.1 LED控制模块 (led.h/.c)

**功能描述**: LED状态指示控制

**硬件连接**:
- PB0: LED0 (红色)
- PB1: LED1 (绿色)
- PB2: LED2 (蓝色)

**API接口**:
```c
// LED初始化
void led_init(void);
/*
 * 功能: 初始化LED控制引脚
 * 参数: 无
 * 返回: 无
 */

// 设置LED状态
void led_set_status(u8 led_num, u8 status);
/*
 * 功能: 设置指定LED的状态
 * 参数: led_num - LED编号(0-2), status - 状态(0-熄灭, 1-点亮)
 * 返回: 无
 */

// LED闪烁
void led_blink(u8 led_num, u8 times);
/*
 * 功能: LED闪烁指定次数
 * 参数: led_num - LED编号, times - 闪烁次数
 * 返回: 无
 */
```

### 5.2 蜂鸣器控制模块 (beep.h/.c)

**功能描述**: 蜂鸣器报警控制

**硬件连接**:
- PB5: 蜂鸣器控制

**API接口**:
```c
// 蜂鸣器初始化
void beep_init(void);
/*
 * 功能: 初始化蜂鸣器控制引脚
 * 参数: 无
 * 返回: 无
 */

// 开启蜂鸣器
void beep_on(void);
/*
 * 功能: 开启蜂鸣器
 * 参数: 无
 * 返回: 无
 */

// 关闭蜂鸣器
void beep_off(void);
/*
 * 功能: 关闭蜂鸣器
 * 参数: 无
 * 返回: 无
 */

// 蜂鸣器鸣叫
void beep_beep(u16 times, u16 delay_ms);
/*
 * 功能: 蜂鸣器鸣叫指定次数
 * 参数: times - 鸣叫次数, delay_ms - 每次鸣叫持续时间
 * 返回: 无
 */
```

## 6. 系统模块接口

### 6.1 系统定时器模块 (systick.h/.c)

**功能描述**: SysTick系统定时器，提供精确延时和时间基准

**API接口**:
```c
// SysTick初始化
void systick_init(void);
/*
 * 功能: 初始化SysTick定时器
 * 参数: 无
 * 返回: 无
 * 说明: 配置1ms中断
 */

// 获取系统时钟计数
uint32_t get_system_tick(void);
/*
 * 功能: 获取系统时钟计数
 * 参数: 无
 * 返回: 系统时钟计数 (毫秒)
 */

// 毫秒延时
void delay_ms(uint32_t ms);
/*
 * 功能: 毫秒级精确延时
 * 参数: ms - 延时时间
 * 返回: 无
 */
```

### 6.2 独立看门狗模块 (iwdg.h/.c)

**功能描述**: 独立看门狗，防止系统死机

**API接口**:
```c
// 看门狗初始化
void iwdg_init(u8 prer, u16 rlr);
/*
 * 功能: 初始化独立看门狗
 * 参数: prer - 预分频器, rlr - 重载值
 * 返回: 无
 */

// 喂狗操作
void iwdg_feed(void);
/*
 * 功能: 重置看门狗计数器
 * 参数: 无
 * 返回: 无
 */
```

### 6.3 EEPROM存储模块 (eeprom.h/.c)

**功能描述**: EEPROM参数存储，用于保存配置信息

**API接口**:
```c
// EEPROM初始化
void eeprom_init(void);
/*
 * 功能: 初始化EEPROM
 * 参数: 无
 * 返回: 无
 */

// 写入数据
void eeprom_write(u16 addr, u8 data);
/*
 * 功能: 向指定地址写入数据
 * 参数: addr - 地址, data - 数据
 * 返回: 无
 */

// 读取数据
u8 eeprom_read(u16 addr);
/*
 * 功能: 从指定地址读取数据
 * 参数: addr - 地址
 * 返回: 读取的数据
 */
```

## 7. 模块间依赖关系

```
主程序 (main.c)
    ├── 通信模块
    │   ├── esp8266 → usart1 → systick
    │   └── queue
    ├── 传感器模块
    │   ├── dht11 → systick → gpio_iic
    │   └── adc → systick
    ├── 显示模块
    │   ├── oled → gpio_iic → wfont
    │   └── wfont
    ├── 控制模块
    │   ├── led
    │   ├── beep
    │   └── button → exti_button
    └── 系统模块
        ├── systick
        ├── delay → systick
        ├── iwdg
        └── eeprom
```

## 8. 错误处理机制

### 8.1 返回值约定
- **函数返回值类型**: `int` 或 `uint8_t`
- **成功返回值**: `1` 或非负数
- **失败返回值**: `0` 或负数
- **错误码定义**:
  ```c
  #define ERR_SUCCESS         0   // 成功
  #define ERR_PARAM_INVALID  -1  // 参数无效
  #define ERR_TIMEOUT        -2  // 超时
  #define ERR_NOT_READY      -3  // 设备未就绪
  #define ERR_CHECKSUM       -4  // 校验错误
  #define ERR_COMM_FAILED    -5  // 通信失败
  ```

### 8.2 调试接口
```c
// 调试信息输出
#define DEBUG_PRINT(fmt, ...) \
    do { \
        if (debug_enabled) { \
            printf("[DEBUG] %s:%d: " fmt "\r\n", __FILE__, __LINE__, ##__VA_ARGS__); \
        } \
    } while(0)

// 错误信息输出
#define ERROR_PRINT(fmt, ...) \
    printf("[ERROR] %s:%d: " fmt "\r\n", __FILE__, __LINE__, ##__VA_ARGS__)
```

---

**文档版本**: v1.0
**最后更新**: 2025-11-16
**作者**: STM32项目组