renode-stm32/README.md

STM32H723 板卡仿真

使用 Renode 运行 STM32H723 运动控制固件，支持上位机通信、六轴参数、IO 报警、运动流程及固件升级联调。

快速启动

环境要求：Windows、Python 3.10+、just、Renode，无需安装 Python 第三方依赖。

在项目目录执行：

Copy-Item .env.example .env              # 首次使用时创建本地配置
just elf "E:/firmware/controller.elf"    # 设置本机固件路径
just format                              # 项目迁移后更新模型路径
just check                               # 检查运行环境
just run                                 # 启动仿真，Ctrl+C 退出
just stop                                # 在另一终端停止仿真并清理虚拟串口

固件不纳入版本管理，建议存放于 .runtime/firmware/。just elf 仅保存路径，不复制文件。

配置与连接

常用参数在 .env 中设置，完整配置见 .env.example。相对路径以项目根目录为基准，建议使用 /。

配置优先级：命令行参数 > 系统环境变量 > .env > 内置默认值。

配置项	用途与默认值
H723_ELF	本机 ELF 固件路径
H723_FLASH_IMAGE	外部 Flash 镜像，默认 .runtime/w25q16.bin
H723_INTERNAL_FLASH_IMAGE	内部 Flash 镜像，默认 .runtime/stm32-internal.bin
H723_UART_PORT	通信端口，默认 12321
H723_GDB_PORT	GDB 端口，默认 3333
H723_WS_PORT	板卡状态 WebSocket 端口，默认 12322
H723_COM	虚拟串口，默认 COM12
H723_DEBUG / H723_USB	调试模式 / 虚拟串口模式，默认关闭
H723_FAST_SERIAL	加速串口仿真，默认关闭；在 .env 中设为 true 开启
H723_WIRE	启用 V1.51 完整送丝机，默认关闭
H723_LASER1 / H723_LASER2	启用 V1.5 SUP25A / V1.60 SUP25AD 焊枪，默认关闭，互斥

just run --wire --laser1                  # 送丝机 + SUP25A
just run --wire --laser2 --no-laser1      # 送丝机 + SUP25AD，覆盖 .env 的 laser1
just run --no-wire --no-laser1 --no-laser2 # 使用原有简化外设和页面展开方式

启用的外设直接显示在网页画布中，无需展开；选择只由启动参数和 .env 决定。设备参数不跨 Renode 进程保存，模型上的电源按钮模拟外设单独重新上电。协议范围、控制接口与测试见 外部设备。

上位机默认连接 tcp://127.0.0.1:12321，使用 Modbus RTU 原始帧，站号 8，不是 Modbus TCP。同一时间仅连接一个客户端。

TCP 桥接最多排队 32 个完整请求，每帧最长 8206 字节；满载时暂停 socket 读取，让 TCP 对发送方施加背压。额外客户端会被断开。固件响应使用独立的 64 KiB 有界队列，客户端持续不接收导致溢出时记录日志并断连，不阻塞固件，也不生成替代固件的成功回执。请按请求／响应顺序通信，并为暂停调试期间的等待配置适当超时。

软件复位保留 TCP 连接，清除旧半帧及已排队请求，支持升级程序跨复位继续通信；客户端应等待板卡重新就绪再发送下一请求。断连会取消该会话尚未投递的请求，重新连接不会重放上一会话已排队的响应。裸 UART 字节没有事务标识，若旧请求的固件响应直到新请求投递后才产生，桥接器无法可靠区分归属；请求间的 5 ms 空闲也不代表固件已经处理完成。请逐请求等待回执，异常断连后先等待板卡就绪再开始新会话。监视器直接调用 boardSerial WriteChar 无法使用异步背压，只应逐请求注入；超过容量会记录错误并断开当前 TCP 会话。

暂停仿真时若发送方持续灌入大量请求后关闭，TCP 缓冲中尚未读取的数据可能使关闭通知延后处理；此时新连接仍被拒绝，需要恢复仿真消费后才能完成旧连接清理。正常通信应等待当前请求回复再发送下一请求。

just run --debug              # 暂停 CPU，等待 GDB 调试
just run --usb --com COM13    # 使用虚拟串口，需安装 HW VSP3 驱动
just run -f                   # 关闭本项目上次启动的实例后重新启动
just run --no-debug --usb --com COM12 # 默认使用普通串口时序
just run --fast-serial        # 临时开启快速串口仿真
just run --no-fast-serial     # 覆盖 .env 配置，使用普通串口时序

虚拟串口默认参数为 115200、8N1，退出时自动移除本项目创建的端口。异常退出后可执行 just stop 清理残留；若串口仍被应用打开，先关闭该应用再重试。

新启动的会话通过独立进程组请求 Renode 正常退出，just stop、run --force 及运行终端的 Ctrl+C 不再依赖空闲的交互监视器。后台没有控制台时会创建隐藏控制台并转接日志，不弹出窗口。旧版本的运行记录仍使用原监视器停止方式；若它被交互连接占用，请在该连接输入 quit 或关闭连接后重试。正常退出失败时会明确报错，运行程序继续保留 Flash 锁及会话记录，直到 Renode 实际退出。

快速模式保留固件执行、组帧、DMA、CRC 和回执，但缩短串口传输等待；验证真实串口耗时、吞吐量或超时时应关闭。

普通 USB 模式保留虚拟 COM 驱动的波特率节流及 Renode UART 的仿真接收时序。桥接器收齐请求后才交给 UART，因此端到端等待包含宿主传输和仿真接收两个阶段，不能直接作为真实串口延迟测量。驱动节流同时保护最长 8206 字节升级帧的完整传输；不要通过关闭驱动节流来校准耗时。普通 TCP 模式绕过虚拟 COM 驱动，可用于单独评估 Renode 接收时序。

板卡指示灯可通过 ws://127.0.0.1:12322/board 订阅，协议见 WebSocket 文档。

实时波形

网页点击 X/Y/Z/A/B/C 任一轴接口，查看真实引脚脉冲。支持最近 10 秒仿真历史、暂停、缩放及游标测量；移动命令由上位机发送。

ADC1 常规转换已按时钟、采样周期和分辨率计时；详细范围见 时序说明。

数据与限制

.runtime/ 存放本地固件、Flash 镜像、日志及运行状态，已被 Git 忽略。清理前应停止仿真；删除 Flash 镜像会丢失已保存参数，删除 ELF 后需重新提供固件。

内部 Flash 程序、启动标记和外部 Flash 参数均跨进程保留。内部镜像不存在时以 ELF 初始化；存在时恢复镜像，由 Factory 决定是否启动 Upgrade。更换 ELF 后若需重新初始化程序，先清除内部镜像。

正常退出还会保存内部 Flash 已完成的编程字，即使固件尚未清除 PG；退出时 PG 仍开启的当前未完成字，其新字节不会额外保存。该退出过滤只读取已验证原生模型的编程计数与地址，不改映射内存或 PG／复位行为；安装版布局不兼容时会明确拒绝打开持久化镜像。

外部 SPI Flash 的机器复位会终止未完成事务，保留已编程的数据；不足 256 字节的页写会在复位时保存已经接收的部分，后续命令从新事务开始。正常页写仍按当前固件的固定 256 字节事务处理，尚未模拟独立片选线的全部行为。启动脚本只有在固件加载、镜像恢复和通信服务启动全部完成后才报告成功。

停止 Renode 后可清除镜像，运行中的镜像拒绝清除；固件、OTA 备份、日志和 .env 均保留：

just clean flash1    # 清除内部 Flash，下次启动从 ELF 初始化
just clean flash2    # 清除外部 W25Q16，下次启动恢复空白参数区
just clean           # 清除上述两类镜像

仿真用于协议与逻辑验证，未完整模拟真实电机、模拟电路及全部外设时序，运动耗时不能直接等同于实物。

协议与集成测试

项目创建、下载与完整读回统一由协议测试的 projects 组验证，分片传输由 robustness 组验证。运行方式见 测试说明。