# esp32_control

**Repository Path**: taylorxp/esp32_control

## Basic Information

- **Project Name**: esp32_control
- **Description**: No description available
- **Primary Language**: C
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-20
- **Last Updated**: 2026-01-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ESP32 BLE GATT 服务框架

> **状态**: ✅ 生产级架构 - 可直接使用
>
> **版本**: 2.0 (新框架)
>
> **更新日期**: 2026-01-27

---

## 📖 项目概述

这是一个完整的 ESP32 BLE GATT 服务项目，包含了从老框架到新框架的完整重构过程。项目提供了两个版本：

- **老框架** ([legacy_framework/](legacy_framework/)) - 原始实现，已废弃但保留用于学习
- **新框架** ([new_framework/](new_framework/)) - 生产级重构，推荐使用

---

## 🚀 快速开始

### 1. 查看新框架（推荐）

```bash
# 新框架文档
cd docs/new_framework/
cat README.md
```

新框架特点：
- ✅ 统一错误处理
- ✅ 事件驱动架构
- ✅ 配置集中管理
- ✅ 单例模式
- ✅ 线程安全

### 2. 查看老框架（学习参考）

```bash
# 老框架文档
cd docs/legacy_framework/
cat README.md
```

老框架特点：
- ⚠️ 多个全局变量
- ⚠️ 回调阻塞
- ⚠️ 错误处理不一致
- ⚠️ 配置分散

### 3. 编译运行

```bash
# 编译项目（使用新框架）
cd ~/esp_learn/my_gatt_service_table_skills
idf.py build

# 烧录和监控
idf.py flash monitor
```

---

## 📁 项目结构

```
my_gatt_service_table_skills/
├── docs/                       # 📖 所有文档
│   │
│   ├── new_framework/          # ✨ 新框架文档（推荐）
│   │   ├── README.md               # 详细说明文档（15000+ 字）
│   │   ├── NEW_ARCHITECTURE_QUICKREF.md   # 快速参考
│   │   ├── REFACTORING_GUIDE.md           # 重构指南
│   │   ├── ARCHITECTURE_DIAGRAMS.md       # 架构图
│   │   └── REFACTORING_SUMMARY.md         # 重构总结
│   │
│   ├── legacy_framework/       # 📚 老框架文档（已废弃，仅供参考）
│   │   ├── README.md               # 详细说明文档（5000+ 字）
│   │   ├── FRAMEWORK_old.md        # 原始框架文档
│   │   └── README_original.md      # 原始 README
│   │
│   ├── technical/              # 🔧 技术文档
│   │   ├── PROTOCOL.md             # 协议定义
│   │   ├── BLE_LED_CONTROL_GUIDE.md    # LED 控制指南
│   │   ├── BUGFIX_HANDLE_INIT.md       # Bug 修复记录
│   │   ├── DEBUG_ANALYSIS.md           # 调试分析
│   │   └── RESPONSE_FORMAT_FIX.md      # 响应格式修复
│   │
│   ├── archived/               # 📦 已归档文档
│   │   ├── PROJECT_STATUS.md          # 项目状态
│   │   ├── CLEANUP_ANALYSIS.md         # 清理分析
│   │   ├── CLEANUP_SUMMARY.md          # 清理总结
│   │   └── IMPLEMENTATION_COMPLETE.md  # 实现完成报告
│   │
│   ├── platform/               # 平台移植相关（如适用）
│   └── plans/                  # 设计计划（如适用）
│
├── main/                       # 💻 源代码
│   ├── ble_core/               # 新框架核心层
│   ├── gatt_server/            # 新框架 GATT 服务器
│   ├── ble_app_new/            # 新框架应用管理器
│   ├── protocol/               # 协议层（共用）
│   ├── my_hal/                 # 硬件抽象层（共用）
│   ├── my_driver/              # 驱动层（共用）
│   ├── app_main_new.c          # 新框架主程序（当前使用）
│   └── app_main.c              # 老框架主程序（已废弃）
│
└── README.md                   # 🌟 本文件 - 全局导航
```

---

## 📚 文档导航

### 新手入门

1. **了解新框架** - 📘 [docs/new_framework/README.md](docs/new_framework/README.md)
   - 完整的新架构说明
   - 核心设计理念
   - API 接口文档
   - 使用指南

2. **快速参考** - 📗 [docs/new_framework/NEW_ARCHITECTURE_QUICKREF.md](docs/new_framework/NEW_ARCHITECTURE_QUICKREF.md)
   - API 速查表
   - 常用代码片段
   - 使用技巧

3. **了解协议** - 📕 [docs/technical/PROTOCOL.md](docs/technical/PROTOCOL.md)
   - 协议帧格式
   - 命令定义
   - 数据格式

### 深入学习

4. **重构指南** - 📙 [docs/new_framework/REFACTORING_GUIDE.md](docs/new_framework/REFACTORING_GUIDE.md)
   - 老框架问题分析
   - 新架构设计
   - 迁移步骤
   - 最佳实践

5. **架构图** - 📊 [docs/new_framework/ARCHITECTURE_DIAGRAMS.md](docs/new_framework/ARCHITECTURE_DIAGRAMS.md)
   - 架构对比图
   - 模块依赖关系
   - 数据流图
   - 事件流转图

6. **老框架参考** - 📚 [docs/legacy_framework/README.md](docs/legacy_framework/README.md)
   - 了解老框架设计
   - 理解重构原因
   - API 对照表

### 技术文档

7. **LED 控制指南** - 💡 [docs/technical/BLE_LED_CONTROL_GUIDE.md](docs/technical/BLE_LED_CONTROL_GUIDE.md)
   - LED 控制实现
   - 使用示例

8. **调试分析** - 🔍 [docs/technical/DEBUG_ANALYSIS.md](docs/technical/DEBUG_ANALYSIS.md)
   - 问题分析
   - 调试技巧

9. **Bug 修复记录** - 🐛 [docs/technical/BUGFIX_HANDLE_INIT.md](docs/technical/BUGFIX_HANDLE_INIT.md)
   - Bug 描述
   - 修复方案

---

## 🎯 框架对比

| 特性 | 老框架 | 新框架 | 说明 |
|------|--------|--------|------|
| **错误处理** | ❌ 混乱 (bool/esp_err_t) | ✅ 统一 (ble_err_t) | 新框架一致性好 |
| **事件处理** | ❌ 回调阻塞 | ✅ 事件队列解耦 | 新框架不阻塞 BLE 栈 |
| **配置管理** | ❌ 分散硬编码 | ✅ 集中 + NVS | 新框架易于管理 |
| **全局变量** | ❌ 3+ 个 | ✅ 1 个单例 | 新架构减少 66% |
| **线程安全** | ❌ 无保护 | ✅ 互斥锁 | 新框架多任务安全 |
| **可测试性** | ❌ 难以 mock | ✅ 接口清晰 | 新框架易于测试 |
| **可维护性** | ⚠️ 中等 | ✅ 高 | 新框架模块化好 |
| **文档完整性** | ⚠️ 基本 | ✅ 详细 | 新框架文档完善 |

### 核心改进

#### 1. 统一错误处理

```c
// 老框架 - 混用三种方式
bool ble_manager_init(...);
esp_err_t esp_ble_gatts_app_register(...);
ESP_ERROR_CHECK(nvs_flash_erase());

// 新框架 - 统一使用 ble_err_t
ble_err_t ble_app_manager_init(const ble_config_t* config);
```

#### 2. 事件队列机制

```c
// 老框架 - 回调中直接处理（阻塞）
void ble_manager_gap_event_handler(...) {
    esp_ble_gap_start_advertising(&adv_params);  // 阻塞!
}

// 新框架 - 事件队列（不阻塞）
ble_event_t event = {.type = BLE_EVENT_CONNECTED};
ble_event_queue_post(queue, &event);  // 立即返回
```

#### 3. 配置集中管理

```c
// 老框架 - 配置分散
static uint8_t raw_adv_data[] = { ... };  // app_main.c
static esp_ble_adv_params_t adv_params = { ... };  // ble_manager.c

// 新框架 - 配置集中
ble_config_t config;
ble_config_get_default(&config);
config.device_name = "MyDevice";
```

#### 4. 单例模式

```c
// 老框架 - 多个全局变量
static ble_manager_ctx_t g_ble_mgr_ctx = { 0 };
static gatt_service_ctx_t g_gatt_ctx = { 0 };

// 新框架 - 单例模式
ble_app_manager_t* mgr = ble_app_manager_get_instance();
```

---

## 💻 代码示例

### 新框架基本使用

```c
#include "ble_app_manager.h"
#include "ble_config.h"

void app_main(void) {
    // 1. 获取配置
    ble_config_t config;
    ble_config_get_default(&config);
    config.device_name = "MyDevice";

    // 2. 初始化
    ble_err_t err = ble_app_manager_init(&config);
    if (err != BLE_OK) {
        ESP_LOGE(TAG, "初始化失败: %s", ble_error_to_string(err));
        return;
    }

    // 3. 注册回调
    ble_app_callbacks_t callbacks = {
        .on_connected = my_connected_cb,
        .on_disconnected = my_disconnected_cb,
        .on_data_received = my_data_recv_cb,
    };
    ble_app_manager_register_callbacks(&callbacks);

    // 4. 开始广播
    ble_app_manager_start_advertising();
}

// 回调函数
void my_connected_cb(uint16_t conn_id, const uint8_t* addr) {
    ESP_LOGI(TAG, "已连接: %d", conn_id);
}

void my_data_recv_cb(const uint8_t* data, uint16_t len) {
    ESP_LOGI(TAG, "收到数据: %d 字节", len);

    // 处理数据...
    uint8_t response[] = {0x01, 0x02, 0x03};
    ble_app_manager_send_data(response, sizeof(response));
}
```

---

## 📖 学习路径

### 初学者路径（1-2 天）

1. 阅读 [new_framework/README.md](new_framework/README.md) - 了解新框架
2. 阅读 [docs/technical/PROTOCOL.md](docs/technical/PROTOCOL.md) - 理解协议
3. 编译运行项目 - 动手实践
4. 修改配置 - 体验配置管理

### 进阶路径（3-5 天）

5. 阅读 [new_framework/REFACTORING_GUIDE.md](new_framework/REFACTORING_GUIDE.md) - 理解重构
6. 阅读 [new_framework/ARCHITECTURE_DIAGRAMS.md](new_framework/ARCHITECTURE_DIAGRAMS.md) - 理解架构
7. 对比 [legacy_framework/README.md](legacy_framework/README.md) - 理解差异
8. 实现自定义功能 - 扩展项目

### 高级路径（1-2 周）

9. 深入研究源代码 - main/ 目录
10. 学习平台移植 - docs/platform/（如适用）
11. 性能优化 - 调整参数
12. 单元测试 - 编写测试用例

---

## 🎓 核心概念

### 1. 错误处理

所有模块统一使用 `ble_err_t` 错误码：

```c
ble_err_t err = ble_app_manager_init(&config);
if (err != BLE_OK) {
    ESP_LOGE(TAG, "错误: %s", ble_error_to_string(err));
}
```

### 2. 事件队列

使用事件队列解耦 BLE 栈回调和业务逻辑：

```c
// 发布事件（不阻塞）
ble_event_t event = {.type = BLE_EVENT_CONNECTED};
ble_event_queue_post(queue, &event);

// 处理事件（在专用任务中）
void my_handler(const ble_event_t* event, void* user_data) {
    // 处理事件...
}
```

### 3. 配置管理

使用统一的配置结构：

```c
ble_config_t config;
ble_config_get_default(&config);     // 获取默认配置
config.device_name = "MyDevice";     // 自定义配置
ble_config_validate(&config);        // 验证配置
ble_config_save_to_nvs(&config);     // 保存到 NVS
```

### 4. 单例模式

应用管理器使用单例模式：

```c
ble_app_manager_t* mgr = ble_app_manager_get_instance();
ble_app_manager_init(&config);
```

### 5. 回调机制

通过回调接收事件通知：

```c
ble_app_callbacks_t callbacks = {
    .on_connected = my_connected_cb,
    .on_data_received = my_data_recv_cb,
};
ble_app_manager_register_callbacks(&callbacks);
```

---

## 🔧 常见问题

### Q1: 如何切换回老框架？

修改 `main/CMakeLists.txt` 第 37 行：

```cmake
# 使用新框架
app_main_new.c

# 改为使用老框架
# app_main.c
```

### Q2: 如何自定义配置？

```c
ble_config_t config;
ble_config_get_default(&config);

// 自定义设备名
config.device_name = "MyDevice";

// 自定义 MTU
config.gatt.mtu_size = 512;

// 自定义广播参数
config.adv_params.adv_int_min = 0x20;  // 20ms
config.adv_params.adv_int_max = 0x40;  // 40ms

ble_config_validate(&config);
```

### Q3: 如何调试问题？

1. 启用详细日志：
   ```c
   esp_log_level_set("*", ESP_LOG_DEBUG);
   esp_log_level_set("BLE_APP_MGR", ESP_LOG_VERBOSE);
   ```

2. 打印配置：
   ```c
   ble_config_print(&config);
   ```

3. 监控统计：
   ```c
   const ble_app_stats_t* stats = ble_app_manager_get_stats();
   ```

### Q4: 如何处理错误？

```c
ble_err_t err = ble_app_manager_send_data(data, len);
if (err != BLE_OK) {
    ESP_LOGE(TAG, "发送失败: %s", ble_error_to_string(err));

    // 根据错误类型处理
    switch (err) {
        case BLE_ERR_NOT_CONNECTED:
            ESP_LOGW(TAG, "未连接，无法发送");
            break;
        case BLE_ERR_NOTIFY_DISABLED:
            ESP_LOGW(TAG, "通知未启用");
            break;
        case BLE_ERR_DATA_TOO_LONG:
            ESP_LOGW(TAG, "数据过长");
            break;
        default:
            ESP_LOGE(TAG, "未知错误");
    }
}
```

---

## 📊 项目统计

### 代码量

- **新框架**: ~1200 行
  - ble_core: ~400 行
  - gatt_server: ~400 行
  - ble_app_manager: ~400 行

- **老框架**: ~800 行
  - bluetooth: ~500 行
  - ble_app: ~300 行

### 文档数量

- **新框架文档**: 5 份
- **老框架文档**: 3 份
- **技术文档**: 5 份
- **归档文档**: 4 份

### 改进指标

| 指标 | 改进 |
|------|------|
| 全局变量 | 减少 66% |
| 错误处理一致性 | 100% |
| 线程安全 | 新增 ✅ |
| 可测试性 | 大幅提升 |
| 可维护性 | 大幅提升 |

---

## 🤝 贡献

欢迎提交问题和改进建议！

### 贡献流程

1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

---

## 📄 许可证

本项目基于 ESP-IDF 示例代码，遵循 ESPRESSIF MIT License。

---

## 📞 支持

如有问题，请参考：

- 📘 [新框架文档](docs/new_framework/README.md)
- 📗 [快速参考](docs/new_framework/NEW_ARCHITECTURE_QUICKREF.md)
- 📙 [重构指南](docs/new_framework/REFACTORING_GUIDE.md)
- 📕 [架构图](docs/new_framework/ARCHITECTURE_DIAGRAMS.md)
- ESP-IDF 官方文档: https://docs.espressif.com/projects/esp-idf/

---

## 🎉 总结

这是一个**完整的、生产级的 BLE 项目重构案例**：

✅ **新框架** - 可直接用于实际项目
✅ **老框架** - 保留用于学习和对比
✅ **完整文档** - 17 份详细文档
✅ **代码示例** - 丰富的使用示例
✅ **最佳实践** - 经过验证的设计模式

**推荐使用新框架进行开发！** 🚀

---

**最后更新**: 2026-01-27
**当前版本**: 2.0
**维护者**: Claude