# 文心快码嵌入式FreeRTOS MCP扩展

专为文心快码设计的嵌入式FreeRTOS开发MCP扩展，支持BK7252等芯片的自动项目生成。提供完整的嵌入式开发工作流，从项目创建到代码生成的一站式解决方案。

## 🚀 功能特性

### 核心功能
- **智能项目生成**: 根据芯片知识库自动创建完整的FreeRTOS项目结构
- **知识库集成**: 集成芯片规格书、SDK文档和项目需求文档
- **记忆库功能**: SQLite数据库保存项目配置，支持持续开发
- **多芯片支持**: 支持BK7252、STM32F4、ESP32等主流嵌入式芯片
- **模板系统**: 基于Jinja2的智能代码模板生成

### 增强功能
- **代码验证**: 自动验证生成的代码符合FreeRTOS最佳实践
- **外设驱动生成**: 自动生成GPIO、UART、SPI、I2C等外设驱动代码
- **内存分析**: 堆栈使用分析和优化建议
- **项目配置管理**: YAML配置文件管理芯片特性和项目设置

## 📋 系统要求

### 基础环境
- **操作系统**: Windows 10/11, Linux, macOS
- **Python**: 3.8 或更高版本
- **包管理器**: pip 最新版本

### 开发工具（可选）
- **MSYS2** (Windows): 用于GCC ARM工具链
- **GCC ARM工具链**: 用于代码编译
- **文心快码插件**: 用于MCP集成

## 🔧 安装部署

### 1. 快速安装

```bash
# 克隆项目
git clone https://github.com/aitersmam888/freertos_mcp.git
cd embedded_freertos_mcp

# 安装Python依赖
pip install -r requirements.txt

# 安装开发依赖（可选）
pip install -r requirements-dev.txt
```

### 2. 开发环境配置

#### Windows环境
```bash
# 安装MSYS2（如果尚未安装）
# 下载地址: https://www.msys2.org/

# 在MSYS2中安装GCC ARM工具链
pacman -S mingw-w64-x86_64-arm-none-eabi-gcc
pacman -S make
```

#### Linux环境
```bash
# Ubuntu/Debian
sudo apt-get install gcc-arm-none-eabi make

# CentOS/RHEL
sudo yum install arm-none-eabi-gcc make
```

#### macOS环境
```bash
# 使用Homebrew安装
brew install arm-none-eabi-gcc make
```

### 3. 文心快码集成配置

在文心快码设置中添加MCP服务器配置：

```json
{
  "mcpServers": {
    "embedded-freertos": {
      "command": "python",
      "args": ["-m", "src.embedded_freertos_mcp"]
    }
  }
}
```

### 4. 环境验证

运行测试命令验证安装：

```bash
# 验证Python模块导入
python -c "from src.embedded_freertos_mcp.models.chip_analysis import ChipCapabilities; print('✅ 模型导入成功')"

# 验证知识库加载
python -c "from src.embedded_freertos_mcp.knowledge.knowledge_loader import KnowledgeLoader; print('✅ 知识库加载成功')"

# 验证项目生成器
python -c "from src.embedded_freertos_mcp.generators.project_generator import ProjectGenerator; print('✅ 项目生成器就绪')"
```

## 💡 使用方法

### 1. MCP工具调用

在文心快码中通过自然语言调用工具：

#### 创建新项目
```
创建一个基于BK7252的智能家居网关项目
- 项目名称: smart_home_gateway
- 芯片型号: BK7252N
- 功能需求: WiFi连接、BLE通信、传感器数据采集
- 输出路径: ./my_projects
```

#### 获取芯片信息
```
查看BK7252芯片的详细规格和外设支持
```

#### 生成驱动代码
```
为BK7252生成UART和GPIO驱动代码
- 波特率: 115200
- GPIO引脚: PA0, PA1
```

### 2. 命令行使用

#### 直接运行MCP服务器
```bash
python -m src.embedded_freertos_mcp
```

#### 使用项目生成器
```python
from src.embedded_freertos_mcp.generators.project_generator import ProjectGenerator

# 初始化生成器
generator = ProjectGenerator("knowledge_base", "memory.db")

# 生成项目结构
project = generator.generate_project(
    project_name="test_project",
    chip_family="bk7252",
    output_path="./output"
)
```

### 3. API接口示例

#### 芯片分析
```python
from src.embedded_freertos_mcp.models.chip_analysis import ChipCapabilities

# 创建芯片能力模型
chip = ChipCapabilities(
    chip_family="BK7252",
    core="Cortex-M4",
    frequency=200000000,
    flash_size=2097152,
    ram_size=524288,
    peripherals=["UART", "SPI", "I2C", "GPIO", "PWM"]
)
```

#### 知识库查询
```python
from src.embedded_freertos_mcp.knowledge.knowledge_loader import KnowledgeLoader

loader = KnowledgeLoader("knowledge_base")
chip_info = loader.load_chip_config("bk7252")
```

## 🗂️ 项目架构

### 核心模块结构

```
src/
├── embedded_freertos_mcp/     # 主包
│   ├── __init__.py           # 包初始化
│   ├── server.py             # MCP服务器主程序
│   ├── main.py               # 命令行入口
│   ├── generators/           # 代码生成器
│   │   └── project_generator.py
│   ├── knowledge/           # 知识库管理
│   │   └── knowledge_loader.py
│   ├── memory/              # 记忆库管理
│   │   └── memory_manager.py
│   ├── models/              # 数据模型
│   │   └── chip_analysis.py
│   ├── templates/           # 代码模板
│   │   ├── projects/
│   │   │   ├── generic_template/
│   │   │   └── bk7252n_iot_gateway/
│   │   ├── drivers/
│   │   └── freertos/
│   └── tools/               # 工具集
│       ├── project_tools.py
│       ├── chip_analyzer.py
│       └── code_validator.py
├── generators/              # 独立生成器
│   └── template_manager.py
└── tools/                  # 独立工具
    └── code_validator.py
```

### 知识库结构

```
knowledge_base/
├── datasheets/             # 芯片规格书
│   ├── bk/                # BK系列芯片文档
│   │   ├── bk7252_summary.txt
│   │   └── parameters.yaml
│   ├── stm32/             # STM32系列文档
│   └── esp32/             # ESP32系列文档
├── sdks/                  # 原厂SDK
│   ├── bk7252_sdk/        # BK7252 SDK文档
│   └── stm32f4_sdk/       # STM32F4 SDK文档
├── requirements/           # 项目需求文档
│   ├── 项目需求.txt        # 总体需求规范
│   └── functional_docs/   # 功能详细文档
└── freertos/              # FreeRTOS文档
    ├── api_reference/
    └── best_practices/
```

### 配置系统

```
config/
├── mcu_configs/           # 芯片配置文件
│   ├── bk7252.yaml       # BK7252配置
│   └── stm32f4.yaml      # STM32F4配置
├── compiler_configs/      # 编译器配置
│   └── gcc_arm.yaml      # GCC ARM配置
└── validation_rules/      # 验证规则
    └── memory_rules.yaml # 内存验证规则
```

## 🎯 支持的芯片平台

### 当前支持的芯片

| 芯片型号 | 架构 | 主频 | Flash | RAM | 特性 |
|---------|------|------|-------|-----|------|
| **BK7252N** | Cortex-M4 | 200MHz | 2MB | 512KB | WiFi/BLE, 丰富外设 |
| **STM32F407** | Cortex-M4 | 168MHz | 1MB | 192KB | 高性能, 丰富外设 |
| **ESP32-S3** | Xtensa LX7 | 240MHz | 8MB | 512KB | 双核, WiFi/BLE |
| **GD32F450** | Cortex-M4 | 200MHz | 1MB | 256KB | 国产替代, 兼容STM32 |

### 扩展支持计划
- ✅ **已完成**: BK7252, STM32F4基础支持
- 🔄 **进行中**: ESP32系列深度集成
- 📅 **计划中**: RISC-V架构芯片支持

## 📁 生成的项目结构

### 标准项目模板

```
smart_home_gateway/           # 项目根目录
├── src/                      # 源代码目录
│   ├── main.c               # 应用程序主入口
│   ├── system.c             # 系统初始化和配置
│   ├── system.h             # 系统头文件
│   ├── tasks/               # FreeRTOS任务代码
│   │   ├── wifi_task.c      # WiFi连接任务
│   │   ├── ble_task.c       # BLE通信任务
│   │   └── sensor_task.c    # 传感器数据采集任务
│   └── drivers/             # 外设驱动
│       ├── uart_driver.c    # UART驱动
│       ├── gpio_driver.c    # GPIO驱动
│       └── i2c_driver.c     # I2C驱动
├── inc/                      # 头文件目录
│   ├── config.h             # 项目配置头文件
│   ├── task_config.h         # 任务配置
│   └── peripheral_config.h  # 外设配置
├── freertos/                 # FreeRTOS源码
│   ├── Config/              # FreeRTOS配置
│   ├── Source/              # FreeRTOS核心源码
│   └── portable/            # 移植层代码
├── build/                    # 构建输出目录
├── scripts/                 # 构建脚本
├── Makefile                 # 主构建文件
├── linker_script.ld         # 链接脚本
└── README.md                # 项目说明文档
```

### 项目配置文件示例

#### config.h
```c
#ifndef CONFIG_H
#define CONFIG_H

// FreeRTOS配置
#define configUSE_PREEMPTION        1
#define configCPU_CLOCK_HZ          200000000
#define configTICK_RATE_HZ          1000
#define configTOTAL_HEAP_SIZE       (50 * 1024)

// 外设配置
#define UART_BAUD_RATE              115200
#define WIFI_SSID                   "MyNetwork"
#define SENSOR_UPDATE_INTERVAL      1000

#endif
```

## 记忆库功能

- **保存项目配置**: 自动保存项目设置到SQLite数据库
- **加载历史项目**: 快速恢复之前的开发状态
- **芯片知识积累**: 持续学习芯片特性和最佳实践

## 开发工具

集成以下开发工具：

- **GCC ARM编译**: 使用arm-none-eabi-gcc
- **Make构建系统**: 自动化编译流程
- **调试支持**: 支持J-Link/ST-Link调试器
- **内存分析**: 堆栈使用情况分析

## 🔍 故障排除与调试

### 常见问题解决方案

#### 1. 模块导入错误
**问题**: `ModuleNotFoundError: No module named 'yaml'`
**解决**: 
```bash
pip install pyyaml
# 或者使用内置的JSON备选方案（已实现容错）
```

#### 2. 工具链路径问题
**问题**: 找不到arm-none-eabi-gcc
**解决**:
```bash
# 检查工具链安装
which arm-none-eabi-gcc

# 添加环境变量（Linux/macOS）
export PATH=$PATH:/path/to/gcc-arm/bin

# Windows系统路径设置
set PATH=%PATH%;C:\msys64\mingw64\bin
```

#### 3. 知识库文件缺失
**问题**: 芯片配置文件不存在
**解决**:
```bash
# 检查知识库结构
ls knowledge_base/datasheets/

# 添加缺失的芯片配置
cp config/mcu_configs/template.yaml config/mcu_configs/new_chip.yaml
```

#### 4. 权限问题（Windows）
**问题**: 文件访问被拒绝
**解决**:
- 以管理员权限运行命令行
- 检查文件权限设置
- 关闭防病毒软件的实时保护

### 调试模式

启用详细日志输出：
```bash
# 设置环境变量
export EMBEDDED_FREERTOS_DEBUG=1

# 或直接运行调试模式
python -m src.embedded_freertos_mcp --debug
```

### 日志文件位置
- **应用日志**: `logs/embedded_freertos_mcp.log`
- **错误日志**: `logs/error.log`
- **调试日志**: `logs/debug.log` (当启用调试模式时)

## 🤝 贡献指南

### 开发环境设置
```bash
# 1. Fork项目
git clone https://github.com/your-fork/embedded_freertos_mcp.git

# 2. 创建开发分支
git checkout -b feature/new-feature

# 3. 安装开发依赖
pip install -r requirements-dev.txt

# 4. 运行测试
python -m pytest tests/

# 5. 提交更改
git commit -m "添加新功能"
git push origin feature/new-feature
```

### 代码规范
- 遵循PEP 8代码风格
- 使用类型注解
- 添加详细的文档字符串
- 编写单元测试

### 提交Pull Request
1. 确保所有测试通过
2. 更新相关文档
3. 提供清晰的变更描述
4. 关联相关Issue

## 📞 支持与反馈

### 问题报告
如果您遇到问题，请提供：
1. 操作系统和Python版本
2. 详细的错误信息
3. 复现步骤
4. 相关日志文件

### 联系方式
- **GitHub Issues**: [项目Issues页面]
- **文档**: 查看本项目Wiki
- **社区**: 嵌入式开发技术论坛

## 📄 许可证

本项目采用MIT许可证。详见[LICENSE](LICENSE)文件。

## 🙏 致谢

感谢以下开源项目的贡献：
- **FreeRTOS**: 实时操作系统内核
- **Jinja2**: 模板引擎
- **Pydantic**: 数据验证
- **SQLite**: 轻量级数据库

---

**嵌入式FreeRTOS MCP扩展** - 让嵌入式开发更智能、更高效！ 🚀