renode-stm32/docs/external-devices.md

外部设备

设备与连接

启动项	协议依据	接口	默认身份
--wire	超强伟业-送丝机通信协议 V1.51	UART8、115200 8N1、站号 10；PF2 自动使能	步进版本 704，硬件版本 220
--laser1	双摆单枪头通讯协议 V1.5（2025.7.09）	USART2、115200 8N1、站号 9；PE3 报警输入	SUP25A、软件 350、硬件 220
--laser2	SUP25AD SUP26AD双摆单枪头通信协议 V1.60	同一 USART2，不能与 laser1 同时使用	SUP25AD、软件 5000、硬件 220

版本和设备 ID 是仿真身份，不代表实物序列号。USART2、UART8 及 PE3/PF2 对应关系由当前固件初始化和实际收发验证。焊枪 ALM 的设备侧高有效信号经板卡输入级后表现为 PE3 低有效；PC0 是独立的激光器报警输入。

未启用时保留既有简化送丝机及网页控件。启用 --wire 后由完整送丝机独占 UART8 响应。焊枪模型不会替上位机写板卡型号或工艺配置。

状态与生命周期

• 设备动作、延时、回抽补丝、防抖和回执使用仿真时间。
• 送丝机默认供电且运行许可为 1，上位机仍可通过 0115 修改；网页不显示或修改运行许可。手动送丝／回抽仍受运行许可和过流保护约束。
• 单独修改数字焊枪工艺槽位会更新缓存及当前工艺的屏幕参数；导入、切换工艺或修改当前工艺别名才改变有效轨迹，遵循 V1.60 第 3.5.2 节注 2。
• MCU 软件复位保留外设参数及供电状态，只丢弃旧串口响应并恢复报警输入线。
• 送丝机电源按钮保持开／关状态。断电立即停止动作、取消旧响应并释放网页按钮，不再响应串口；开机恢复当前实例已保存参数、清除过流并重新采样 PF2。两种焊枪也保持独立的电源开／关；断电取消串口及防抖任务，开机恢复已保存工艺和各自的上电同步标记。MCU 复位不改变外设供电。
• Renode 进程重新启动后所有外设重新使用默认参数，不创建外设持久化文件。
• 送丝／回抽按钮为短触。断开操作者连接会释放其按钮，旁观连接断开不影响其他操作者。

WebSocket

沿用 /board，新增主题 board.devices。subscribe、snapshot、unsubscribe 与现有主题一致。

快照包含 sequence、仿真时间 nowNs、wire 和 torch。未启用的设备为 null。焊枪状态提供供电 powered、实际生效图形、毫米尺寸、角度、Hz 频率、工艺号、报警和监控；送丝机提供供电状态 powered、方向、速度、自动动作阶段及协议运行许可。只读参数包括 autoSpeed、manualFeedSpeed、manualRetractSpeed（cm/min），startDelayMs、refillDelayMs、periodMs（ms），retractLengthMm、refillLengthMm（mm），smoothness（%）及 averageSpeed（cm/min）。诊断字段 requests、lastAddress、lastWriteAddress、lastWriteCode 表示实际外设串口处理结果。

焊枪 displayParameters 包含 shape、width、height、angle、frequency、spacing，采用与顶层同名字段相同的单位。数字枪取当前工艺槽位的已接收参数，用于左侧屏幕数值；顶层字段仍为实际生效参数，用于右侧扫描轨迹。仅写 1405 后屏幕宽度更新，1385 回读和有效轨迹仍保持原值，导入后两者一致；非当前工艺槽位修改不替换当前屏幕参数。旧枪没有这层缓存区别，两组字段一致。

{"type":"set","topic":"board.devices","device":"wire","input":"feed","value":1}

设备	输入	值
wire	power	1 开机、0 关机；幂等，不复位板卡 MCU
wire	feed / retract	1 按下、0 松开；连接持有，断线释放
wire	overcurrent	1 注入锁存过流；写 0 不清除，重新上电解除
torch	power	1 开机、0 关机，保持状态；断电后 UART 不响应，ALM 释放对应板卡 PE3 低电平
torch	collision	物理碰撞源：1 触发、0 释放；按连接持有，断线释放物理源；3 ms 防抖，启用自动恢复后释放 250 ms 清除锁存
torch	collisionFault	网页碰撞故障卡片：1 注入，0 释放并执行碰撞清除（旧枪 004C、新枪 1013）；最后一个注入连接断开也清除。其他连接仍持有碰撞时不能清除，不影响硬件和温度故障
torch	hardware	0/1，兼容旧入口，对应硬件故障掩码 bit0
torch	hardwareFaults	SUP25A：bit0 驱动总故障，bit1/2 为 +15V 过压／欠压，bit3/4 为 −15V 过压／欠压；同路过压／欠压互斥。SUP25AD：1283 的 bit0–5
torch	operatingFaults	仅 SUP25AD，1284 的 bit4–7：24V 欠压、驱动过流、轨迹异常、电机堵转
torch	currentMa	仅 SUP25A，±15V 电流输入，0–9999 mA；按 0048 的 600／800／1000／1200 mA 或禁止档判断报警
torch	temperature	兼容旧入口：SUP25A 枪体（−200 至 1000），SUP25AD 保护镜（−200 至 2000），单位 0.1 ℃
torch	temperature0–temperature7	仅 SUP25AD：驱动器、保护镜、准直镜、Y 电机、X 电机、Y 反射镜、X 反射镜、分光镜；−200 至 2000，−9990 表示测温断线，不报警
torch	processIo	SUP25AD 三位工艺输入组合 0–7，30 ms 防抖，1227 开启后才跟随选工艺
torch	processIo1–processIo3	SUP25AD 单路物理输入，0/1；在设备锁内合并，其余引脚保持不变

{"type":"powerCycle","topic":"board.devices","device":"torch"}

写操作可附带字符串 requestId，应用后的快照回传关联编号；暂停仿真时命令等待恢复。普通命令每连接只允许一项等待，满时返回 busy。短触按钮按最终电平合并，释放不受普通命令等待限制。客户端应等待回应后再发送下一项普通操作。

协议边界

• V1.5 的同步写地址说明误指 042F；按监控表实现 0038 → 042D，042F 为配对状态。当前固件通信验证符合此布局。
• V1.5 的驱动总报警、电源过流和正负电源电压报警由外设分别回读 0430–0433。当前板卡固件 1.7.0.28 的 MotionManager::set_torch_alarm_analog() 虽读取 0430–0437，但只使用 0435 枪体过温和 0437 碰撞；前四项不会进入板卡 A0D0–A0D6 报警区，LWS 因此无法显示。独立实例实测五项驱动／电压故障及 900 mA 过流时报警区全零，温度原始值 900（90 ℃）使 A0D3=0040，碰撞使 A0D3=0010。TODO：确认旧款驱动及电源报警的板卡映射并在固件中处理；外设不得将它们伪装成碰撞或过温。
• V1.60 的 200F 为型号；文档未定义 2010/2011 的业务含义，作为保留字返回零，不伪造版本字段。
• V1.60 的宽高文字上限与 1–8 mm 频率表存在差异；模型允许至 8 mm，使用 SUP25AD 200 聚焦的公开频率表，未模拟铜嘴限制。
• 1400 的 0/1 缓存／导入行为已实现；不推荐的 2/3 未给出完整操作语义，暂返回非法值。私有配对、加密及未公开的协议兼容映射不伪造成功。
• 送丝机脉冲模式参数可读写，运动展示报告协议中的平均速度。TODO：厂家未给出平滑度到瞬时电机速度的曲线，不能据此生成可信的脉冲速度波形。
• 光斑按有效参数绘制静态几何示意，不是实测振镜反馈或光学能量分布。数字枪灯的颜色／模式按协议，未规定的闪烁周期仅以 1 Hz 展示。送丝动画和状态灯闪烁使用仿真时间，仿真暂停时停止推进。
• 当前默认覆盖 SUP25A、SUP25AD。SUP26A／SUP26AD 的独立身份及频率表选择尚未提供启动选项，不将其标成已验证型号。

验证

python tests/external_devices.py --protocol-only
python tests/external_devices.py --flash .runtime/w25q16.bin --transport both --com COM12

协议测试通过真实 USART 寄存器收发，不直接调用协议执行方法；端到端测试使用参数镜像副本，通过 COM12／TCP 的板卡固件转发。未指定 --flash 时使用项目配置的外部 Flash；原始镜像不被测试修改。COM 端口必须空闲，不连接真实板卡。

--lws-only 单独运行数字枪 A250/5 校验、200 ms 图形切换读回、精确报警位与全局标志、外设供电及连接观测。焊枪断电需验证 A801 清零并恢复。当前 ELF 没有空闲送丝机心跳，断电及查询失败后 A802 仍可能保持 1，不能据此证明送丝机在线；送丝机通过实际参数查询失败及上电后查询成功验证恢复，并保留连接位观测。对从站 8 的请求返回从站 10 的异常帧仍判失败，不改写帧地址或增加兼容读法。

送丝机卡片

卡片左侧显示当前速度、连续／脉冲模式和动作阶段，右侧显示夹辊及焊丝方向。送丝／抽丝为按住生效，按钮按压反馈与设备是否实际运动分开；断电禁用动作。过流从标题栏故障菜单注入，右上角状态灯变红，悬停查看原因，重新上电解除。

点击标题向下展开自动送丝、手动动作、回抽补丝、脉冲四组只读参数。仅展开状态保存到浏览器 pcb-feeder-parameters-expanded，不会恢复或重放设备命令。展开不移动原有端子，不产生页面滚动区域。夹辊动画表示方向和速度变化，不用于推算真实辊径或送丝长度。

两种焊枪卡片

MockSUP25A／MockSUP25AD 保留两种物理接口和协议身份；版本标签分别为协议 v1.5／v1.60，硬件、软件版本和同步原始值仅保留在后台协议中。左侧显示当前工艺已接收、适用的屏幕参数，右侧为实际生效工艺的静态光斑；亮度由实际板卡使能和 PWM 活动及焊枪供电决定，不从主机状态灯反推实际输出。

• 圆显示直径，直线显示宽度；螺旋显示外径、内径和间距
• 高度和角度按各型号及形状显示；旧枪三尖瓣没有独立高度
• SUP25AD 工艺灯 1014 和主机状态灯 1015 仅保留后台协议支持，网页不显示；设备异常通过独立警示图标提示，悬停查看具体原因；碰撞源释放但锁存未清时明确提示，点击警示图标进入硬件页
• SUP25AD 工艺 IO 保留后台协议输入，网页不提供三个 IO 操作按钮；实际生效工艺号只读显示
• 监控和硬件统一由标题展开入口访问，顶部不再提供独立三点菜单；监控页集中显示并编辑测量输入，不再单独提供温度页。硬件页只保留故障卡片，碰撞与其他故障使用同样的样式，活动源或锁存存在时呈选中状态，关闭卡片释放源并清除碰撞锁存；其他故障未解除时警示图标仍保留。物理输入 collision 继续遵循协议锁存与清除规则
• SUP25A 监控页提供枪体温度和电源电流输入，两行使用相同的输入列及宽度；电源电流指协议 041B 的 ±15V 电源电流，单位 mA。0047=2 时禁用报警检测，0048 控制电流报警档位
• SUP25AD 八路温度分别回读 1287–128E，并按各自 1208–120F 阈值生成对应报警位；阈值 0 屏蔽该项，−999.0 ℃ 表示断线且不报警
• 数字故障位来自公开的 1283 bit0–5 和 1284 bit4–7；电源循环清除注入的驱动／运行故障，实际温度源仍保留，热源未消失时仍可能报警
• 故障注入是设备报告状态的模拟，不包含电源电路、传感器电气波形或实际振镜反馈；厂家未公开的故障恢复状态机仍属于模型边界

点击标题展开监控及硬件页，分别保存到浏览器 pcb-sup25a-monitor-expanded 和 pcb-sup25ad-monitor-expanded。同一个展开区内切换监控和故障页，无滚动区；展开时下方送丝机自动顺延，端子连线同步移动。监控页的测量输入使用可见输入框，数字枪同时保留各测温通道的连接／断开操作；工艺参数仍只读。激光源报警 PC0 独立放回板卡信号 3。

LWS 数字测温映射不是连续八字：驱动器在板卡 041E，041F 保留旧枪枪体字段，其余七路在 0420–0426；测试按实际字段映射检查，不能用 041F 开始的连续区间代替。