项目介绍与迭代说明
日期：2026年5月10日
一、项目概述
本项目基于 STM32F407 系列开发板，面向“软硬件协同 + 本地接口服务 + 网页展示”的课程目标，完成了一套可演示、可扩展的系统。系统由两部分构成：
- 硬件模块：完成板级外设驱动与设备状态采集，提供统一的状态接口输出。
- 软件模块：提供本地 API 服务、串口桥接与网页端展示，用于上位机演示和后续功能扩展。
整体定位是“课堂可演示的完整样例”，强调可运行、可观察、可扩展。硬件负责真实数据，软件负责接口与展示，两者通过串口与 JSON 数据格式完成协同。
二、项目目标与范围
1. 目标
- 建立稳定的板级外设驱动框架，具备 LED、按键、ADC、LCD、触摸、串口等典型功能。
- 输出统一的设备状态结构，便于后续上位机、网页或其他程序读取。
- 在上位机侧提供本地 API 服务与演示界面，形成完整的“设备状态可视化 + 交互链路”。
2. 范围
- 硬件侧：基于 CubeMX/HAL 生成工程，集中在
app_modules.c编排业务逻辑。 - 软件侧：本地 API 服务、串口数据桥接、网页可视化、接口调用示例。
三、系统架构
1. 总体架构
- 设备层：STM32F407 采集外设状态并输出 JSON。
- 传输层：串口（USART）输出，桥接程序写入本地 API。
- 服务层：本地 API 提供状态读写与 AI 调用入口。
- 展示层：网页端展示设备状态与服务状态。
2. 模块划分
- 硬件模块：
硬件模块/- 外设驱动初始化
- 设备状态封装
- JSON 输出接口
- 软件模块：
软件模块/- 本地 API 服务（
service/api_server.py） - 串口桥接（
service/serial_bridge.py） - 网页端页面（
web/） - 接口文档与演示（
api/、demo/）
- 本地 API 服务（
四、团队成员与分工
- 冯宇轩：硬件模块负责人，完成外设接入、CubeMX 配置与
app_modules.c逻辑编排；输出设备状态与 JSON 规范。 - 尹一熹：软件模块负责人，完成本地 API 服务、串口桥接与接口对接；维护
device_status.json缓存流程。 - 林与峰：前端与演示负责人，完成网页展示与交互脚本；组织演示流程、准备展示材料与讲解。
分工采用“负责人 + 协作支撑”的方式，关键功能由对应负责人主导实现，其他成员参与联调与测试，确保硬件、服务、网页三端联动一致。
五、硬件模块设计与实现
1. 已接入外设
- LED：PC13，作为运行状态指示。
- KEY1：PA0，按键触发 LED 切换并可发送指令。
- ADC1：PB0/PB1，采集两路模拟量。
- USART1：PA9/PA10，调试串口，支持 printf 输出。
- USART3：PB10/PB11，用作 WiFi 串口，启用 DMA 循环接收。
- I2C1：PB8/PB9，连接触摸控制器 CST816。
- SPI1：PB3/PB5，LCD 刷屏。
- LCD 控制脚：背光、复位、数据/命令、片选等控制线。
2. 软件结构特点
- 保留 CubeMX/HAL 自动生成代码，降低维护成本。
- 业务逻辑集中在
app_modules.c，避免散落在main.c。 - 提供统一设备状态接口：
App_GetDeviceStatus()：读取 LED、ADC、触摸等状态。App_FormatDeviceStatusJson()：格式化为 JSON 字符串。
3. 可扩展资源
结合原理图可继续扩展 WiFi/Bluetooth/GPS、Camera、RS232、SRAM、Ethernet、MP3 Decode 等资源，仍保持“驱动层 + 应用编排层”的结构。
六、软件模块设计与实现
1. 本地 API 服务
GET /api/health：服务状态与凭证加载检查。GET /api/device/status：读取设备状态。POST /api/device/status：写入设备状态，便于桥接程序更新。POST /api/ai/chat：读取根目录api id.txt与api key.txt，转发聊天请求到上游兼容接口。/：前端页面入口，展示设备状态与服务状态。
2. 串口桥接与实时刷新
- 串口输出形如
[STATUS] {...}的 JSON。 serial_bridge.py解析后写入本地 API。- 网页端轮询状态并显示最近同步时间，判断同步是否超时。
3. 前端展示
index.html：页面结构。styles.css：样式。app.js：交互脚本。- 主要功能：展示服务状态、设备状态、AI 请求结果与同步时间。
七、关键技术点与难点处理
-
统一状态模型
硬件侧通过App_GetDeviceStatus()聚合 LED、ADC、触摸等信息，再由App_FormatDeviceStatusJson()统一输出。软件侧仅需解析 JSON 即可完成对接，降低跨端耦合。 -
串口到接口的桥接
硬件输出采用[STATUS] {...}的单行 JSON 格式，桥接程序按前缀识别后写入本地 API，避免杂乱串口输出影响解析，并保证网页展示数据稳定。 -
离线与演示兜底
设备状态采用device_status.json做缓存，本地 API 在无硬件时仍可返回有效数据；AI 请求支持上游不可用时的本地兜底回复，确保演示连续性。 -
低耦合结构
硬件侧集中在app_modules.c，软件侧以 API 服务为中心，网页仅依赖接口数据；结构清晰，后续扩展 WiFi 或上位机程序不会破坏现有链路。
八、测试与验证
- 串口稳定性：连续输出状态并观察桥接进程是否持续写入，无丢包或异常崩溃。
- 接口正确性：对
GET/POST /api/device/status进行读写测试，确认前端显示与缓存一致。 - 页面刷新：观察同步时间与状态变化，验证超时提示逻辑是否正常。
- 硬件功能：按键切换、LED 指示、ADC 变化、触摸事件触发是否稳定可复现。
九、运行与演示流程
1. 启动服务
在工程根目录执行：
python 软件模块/service/api_server.py
浏览器访问：
http://127.0.0.1:8000/
2. 启动串口桥接
在根目录执行：
pip install pyserial
python 软件模块/service/api_server.py
python 软件模块/service/serial_bridge.py --port COM3 --baudrate 115200
说明：COM3 改为实际串口号。
3. 演示内容
- LED 与按键：展示硬件输入输出响应。
- ADC：展示采样结果实时更新。
- 触摸：展示触摸事件触发。
- 网页端：同步展示状态与更新时间。
十、迭代过程与版本演进
迭代 1：基础硬件驱动与可运行工程
- 完成 CubeMX 工程搭建与 HAL 初始化。
- 接入 LED、按键、ADC、串口等基础外设。
- 明确代码分层结构，建立
app_modules.c统一编排入口。
成果：硬件侧具备稳定运行与基础数据输出能力。
迭代 2：设备状态接口规范化
- 设计统一设备状态结构体。
- 增加
App_GetDeviceStatus()与App_FormatDeviceStatusJson()。 - 以 JSON 作为跨端数据交换格式，便于上位机对接。
成果：硬件侧输出格式统一，软件侧可稳定解析。
迭代 3：本地 API 服务搭建
- 设计本地 REST API，包括健康检查与状态读写。
- 引入
device_status.json作为缓存，提高稳定性。 - 可在无硬件时以模拟方式演示接口。
成果：本地接口可运行，具备演示基础。
迭代 4：串口桥接与网页展示
- 增加串口桥接程序，实时写入设备状态。
- 搭建网页端展示，自动刷新同步时间。
- 完成“硬件-串口-服务-网页”的完整闭环。
成果：课程演示具备完整链路与可视化界面。
迭代 5：AI 接口扩展（可选展示）
- 增加 AI 聊天转发接口，支持上游兼容服务。
- 通过根目录
api id.txt、api key.txt加载凭证。
成果：系统具备扩展性展示点，可展示软硬件系统的可拓展能力。
十一、项目亮点与价值
- 软硬件协同闭环完整，演示效果直观。
- 设备状态统一输出，便于后续多端对接。
- 结构清晰，可扩展性强，适合课程项目展示。
- 可在无硬件环境下演示软件侧功能，降低展示风险。
十二、后续可扩展方向
- 加入 WiFi 模块，实现设备端直连网络更新状态。
- 扩展 LCD 与触摸 UI，形成更完整的人机交互演示。
- 增加数据存储与日志功能，展示系统稳定性。
- 增加上位机桌面程序或移动端展示。
十三。其他要求
1.github团队仓库链接
https://github.com/xx-s-group/Software-Engineering-Team-Introduction
2.课设仓库
https://github.com/xx-s-group/Course-Design-Project