# stm32h7_base

**Repository Path**: michaelhyg/stm32h7_base

## Basic Information

- **Project Name**: stm32h7_base
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-10
- **Last Updated**: 2026-04-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: stm32

## README

# STM32H743 Codex Base

这是一个完全基于 Codex 生成与整理的 STM32H7 基座工程，目标是作为后续 STM32 以太网应用的统一起点。

工程面向以下能力扩展：

- STM32H7 以太网通信
- Modbus TCP
- MQTT
- 差分 OTA
- Lua 脚本

当前仓库已经落地的基础能力主要集中在底座层：

- 基于 `.ioc` 生成的 STM32H743 工程骨架
- CMake + Ninja + GNU Arm 工具链构建流程
- FreeRTOS + LwIP 以太网基础集成
- 针对 STM32H7 GNU 构建的 Ethernet ping 关键修复
- 基础下载脚本 `flash.sh`
- Lua 运行时最小接入，以及 NodeMCU 风格的 `gpio` / `tmr` 脚本模块
- NodeMCU 风格 `i2c/iic` / `spi` / `pwm` 脚本模块
- NodeMCU 风格 `uart` 脚本模块
- Lua 版 `mqtt` 脚本模块
- 简化版 `ws2812` 脚本模块
- 基于 `UART8` 的 Lua 串口控制台
- Qt Lua 调试上位机
- 基于 HTTP 的 Lua 调试界面
- Lua 脚本保存到内部 Flash，并在设备启动时自动执行一次

上层业务能力目前在本仓库中的定位是“基座要承载的目标能力”，后续可以继续在此基础上补齐对应的 `User/services`、协议栈封装与应用逻辑。

## Project Goals

这个仓库的目标不是只保留一个最小 CubeMX 示例，而是沉淀一个适合继续演进的 STM32H7 基座程序，用来承载网络型固件功能，包括但不限于：

- 设备联网与远程接入
- 工业协议接入
- 消息总线通信
- 远程升级
- 脚本化扩展

## Current Structure

当前目录仍以 CubeMX 生成层为主：

- `Core/`
- `Drivers/`
- `LWIP/`
- `Middlewares/`
- `cmake/`
- `STM32H743_BASE.ioc`

其中：

- `Core/`、`Drivers/`、`LWIP/`、`Middlewares/` 是当前硬件初始化与协议栈基线
- `cmake/` 提供 GNU Arm 工具链与 CubeMX CMake bridge
- `flash.sh` 提供本地构建并通过 `pyocd` 下载的快捷入口

## Build

默认使用 `Debug` 预设构建：

```bash
cmake --preset Debug
cmake --build build/Debug -- -j4
```

如果本机已经安装了 STM32Cube 的 GNU 工具链，当前工程会优先从 STM32Cube bundles 路径解析 `arm-none-eabi-*` 工具；当前不再绑定单一 bundle 版本，会自动尝试已有版本目录。

## Flash

仓库根目录提供下载脚本：

```bash
./flash.sh
```

该脚本当前默认行为是：

- 自动探测可用的 `cmake` / `cube-cmake`
- 如本地尚未完成 `Debug` 配置，会先自动执行一次 `cmake --preset Debug`
- 先构建 `build/Debug`
- 使用 `pyocd` 下载 `STM32H743_BASE.elf`
- 下载完成后自动复位目标板

如需修改探针 UID、目标芯片或构建目录，可直接调整 [flash.sh](/Users/michael/hu/MCU/stm32/STM32H743_BASE/flash.sh)。

## Ethernet Notes

为了让 GNU/CMake 版本在 STM32H7 上更稳定地工作，当前基座已经包含几项以太网侧关键处理：

- PHY 复位脉冲
- ETH DMA 相关 section 放入 `RAM_D2`
- GNU 下发送路径使用连续对齐 TX buffer，并在发送前清理 D-Cache

这些修改的目标是为后续 Modbus TCP、MQTT、OTA 等网络功能提供更稳定的底层以太网基础。

## Next Steps

如果继续沿这个基座演进，比较自然的下一步通常是：

- 增加 `User/` 自有目录层，承载驱动、服务和应用逻辑
- 封装 Modbus TCP 服务
- 封装 MQTT 服务
- 引入差分 OTA 流程
- 引入 Lua 脚本执行与配置能力

## Lua Notes

当前工程已经增加了一个最小 Lua 服务层，位置在 `User/lua_c_api/`。

目前已经接入：

- NodeMCU 风格 `gpio` 模块
- NodeMCU 风格 `i2c / iic` 模块
- NodeMCU 风格 `spi` 模块
- NodeMCU 风格 `pwm` 模块
- NodeMCU 风格 `tmr` 模块
- NodeMCU 风格 `uart` 模块
- 基于 `UART8` 的 Lua 串口控制台协议
- Qt Lua 调试上位机 `tools/qt_serial_debugger`
- 测试入口模块 `User/test/lua_api_test.c`
- 示例脚本 `User/test/test_tmr_gpio.lua`
- 示例脚本 `User/test/test_i2c.lua`
- 示例脚本 `User/test/test_spi.lua`
- 示例脚本 `User/test/test_pwm.lua`
- 示例脚本 `User/test/test_uart.lua`
- 示例脚本 `User/test/test_mqtt.lua`
- 示例脚本 `User/test/test_ws2812.lua`
- 底层驱动 `User/ws2812/ws2812.c`
- 模块说明文档：
  - `User/lua_c_api/docs/gpio.md`
  - `User/lua_c_api/docs/i2c.md`
  - `User/lua_c_api/docs/spi.md`
  - `User/lua_c_api/docs/pwm.md`
  - `User/lua_c_api/docs/tmr.md`
  - `User/lua_c_api/docs/mqtt.md`
  - `User/lua_c_api/docs/uart.md`
  - `User/lua_c_api/docs/ws2812.md`

当前实现属于“兼容风格的最小子集”，目标是先把 STM32 板级脚本执行能力和定时/引脚控制接口跑通，再继续向脚本存储、Web 配置、OTA 联动等方向扩展。

其中新增的外设脚本模块当前支持范围为：

- `i2c / iic`：`I2C1`，对应 `PB8(SCL)` / `PB9(SDA)`
- `spi`：`SPI1` 对应 `PB3/PB4/PB5`，`SPI3` 对应 `PC10/PC11/PC12`
- `pwm`：`PA8(TIM1_CH1)`、`PE5(TIM15_CH1)`

这些模块都同时支持“按外设号选择”和“按当前板级已映射的硬件引脚组选择”，例如：

- `i2c.setup(i2c.I2C1, 100000)` 或 `iic.setup("pb8", "pb9", 400000)`
- `spi.setup(spi.SPI1, spi.MODE0, 1000000)` 或 `spi.setup("pb3", "pb4", "pb5", spi.MODE0, 1000000)`
- `pwm.setup(pwm.PA8, 1000, 512)`

其中 `mqtt.connect()` 采用异步启动方式，连接结果通过 `mqtt.on_connect(...)` 回调返回，避免脚本在等待网络握手时卡住。
当前以太网默认改为 `DHCP` 获取地址，启动后会通过 `net_status_service` 打印 `link/IP/mask/gw`，方便排查 MQTT、OTA 等依赖网络的功能。
示例脚本 `User/test/test_mqtt.lua` 会在网络未就绪时自动等待并重试连接，减少开机阶段 DHCP 尚未完成时的误判。

其中 `tmr` 当前不是基于 FreeRTOS software timer，而是通过 `TIM12` 的 `HAL_TIM_PeriodElapsedCallback()` 节拍驱动，再在 `lua_service_poll()` 里完成 Lua 回调派发。

当前 Lua 串口控制台使用 `UART8`，支持以下控制帧：

- `@@LUA_PING\n`
- `@@LUA_EXEC <len>\n<script-bytes>`
- `@@LUA_STORE <slot> <len>\n<script-bytes>`
- `@@LUA_FLASH_LOAD\n`
- `@@LUA_RESET\n`

Qt 上位机会把这些控制帧从输出窗口中过滤掉，因此输出区域默认只保留设备普通输出，例如 Lua `print(...)` 的内容。

其中 `@@LUA_FLASH_LOAD` 会把 MCU 内部 Flash 中保存的 Lua 脚本原样回传到上位机编辑器，`@@LUA_RESET` 会让板子立即复位，方便脚本保存后重新启动验证。

当前工程会在 `STM32H743` 的内部 Flash 末尾预留 `128 KB` 作为 Lua 脚本存储区，并让擦除逻辑跟随链接脚本自动推导 bank / sector：

- 起始地址：`0x081E0000`
- 大小：`128 KB`
- 对应区域：`Bank 2 / Sector 7`
- 当前用途：保存上位机下发的 Lua 脚本
- 当前行为：设备启动时会自动执行这份已保存脚本一次

因此链接脚本中的应用代码区被收敛到前 `1920 KB`，避免程序镜像覆盖脚本存储区。

## Lua HTTP Debug

当前工程还提供了一个设备侧 HTTP 调试界面，服务由 `User/services/lua_http` 提供，并在 `freertos.c` 中从默认任务启动。

默认行为：

- 监听 `80` 端口
- 访问 `http://<board-ip>/`
- 支持在线编辑和执行 Lua 脚本
- 支持把当前编辑器中的脚本保存到 MCU 内部 Flash
- 支持从 MCU Flash 重新加载当前保存脚本
- 支持把 MCU Flash 中保存的脚本下载到本地

调试页面会显示：

- 当前网络状态
- IP / Mask / GW
- Flash 中已保存脚本的文件名和长度
- 本次执行期间 Lua `print(...)` 的即时输出

当前 HTTP API 为：

- `GET /`
- `GET /api/status`
- `GET /api/script`
- `GET /download/script.lua`
- `POST /api/exec`
- `POST /api/save?slot=<name>`

其中 `POST /api/exec` 和 `POST /api/save` 的请求体直接使用纯文本 Lua 脚本内容即可。为了避免把异步输出误解为同步返回，当前页面只捕获“本次执行期间”的即时 `print` 内容；定时器回调或 MQTT 回调里后续产生的输出仍然会继续走串口。

## License

本仓库包含 STM32Cube 生成代码、HAL/CMSIS/LwIP/FreeRTOS 等第三方组件。各组件授权以其原始文件头和上游许可证为准。