Claude Code、Codex、ChatGPT 很容易生成一份“看起来完整”的五线无刷泵驱动：初始化 GPIO，输出 PWM，捕获 FG，最后返回 success=true。

真正危险的窗口却发生在第一行代码执行之前。

如果控制器刚上电、正在复位、固件下载中或看门狗刚触发，PWM 引脚可能暂时处于输入/高阻状态。与此同时，某些泵控制接口会把“PWM 悬空”解释为全速命令。

于是出现一个很反直觉的样机故障：

MCU 还没完成初始化，泵已经开始转；等固件终于把 PWM 拉到停机电平，泵反而停下了。

这不是“PWM 占空比写错”那么简单，而是控制器复位状态、板级上下拉、泵接口逻辑和电源时序共同形成的系统问题。

本文用 FOREACH DPL30H 五线无刷接口的公开参数做工程案例，给出一个可运行的 Python 安全状态机、FG 转速换算、故障注入时间轴和 8 项单元测试。重点不是替代正式电气规格，而是回答：

如何证明从上电、复位、GPIO 初始化、启动到 FG 反馈的全过程，都不存在未定义的满速窗口？

先给结论

工程问题	结论
main() 第一行写停机电平是否足够？	不足。软件执行前的复位、高阻、Bootloader、下载和掉电窗口仍需由硬件默认态与电源时序覆盖。
FG 有脉冲是否等于液体正常流动？	不等于。FG 只能证明转子反馈存在，还需压力、流量、重量、液位或工艺传感器提供独立证据。
3.3 V GPIO 能否直接驱动公开的 0–5 V PWM 端？	公开页面不足以证明兼容，必须以所选 SKU 的受控电气规格和实测结果为准。
AI 最适合承担什么？	生成状态机、测试和故障注入脚本；不能替工程师猜输入阈值、上下拉阻值、FG 拓扑或放行参数。

图 1｜五线无刷泵把电源、方向、速度命令与 FG 反馈分开；“软件能写 PWM”不等于上电过程已经安全。

一、两个官方事实组合后，才暴露出真正的风险

事实 1：DPL30H 的 PWM 悬空状态不是停机

FOREACH DPL30H 高压液体隔膜泵的官方选型与接口说明 给出了五线无刷版本的公开逻辑：

信号	公开功能
VCC（红）	电源正极
GND（黑）	地
DIR（黄）	高电平或悬空为 CW，低电平为 CCW
FG（绿）	转速反馈
PWM（蓝）	速度命令

关键电平是：

• PWM 为 0–0.25 V：停机；
• PWM 悬空或为 4.5–5 V：全速；
• 支持 PWM 或 0–5 V 模拟电压调速；
• FG 每个转子机械转输出 3 个方波脉冲。

事实 2：部分 MCU 的 GPIO 复位默认是高阻

MCU 厂商资料普遍要求设计者检查复位后的引脚状态。例如 TI MSP432E411Y 数据手册 明确说明，大多数 GPIO 默认配置为高阻；ST STEVAL-IHM040V1 硬件说明 也提醒，MCU 复位及初始化之前输出可能为高阻，如果外部上下拉不合适，功率级可能处于不确定或不安全状态。

证据边界：不同 MCU、不同引脚、启动模式和板级配置可能不同。 本文不能把某颗 MCU 的复位行为外推到所有控制板。

系统级推论：高阻 + “悬空=全速”可能形成上电失控窗口

若所选控制器的泵 PWM 引脚在复位期间为高阻，又没有外部电路把泵端 PWM 定义到停机区，那么这个悬空窗口可能被 DPL30H 解释为全速命令。

这是一条由两个一手事实组合出的系统级推论：

MCU reset / GPIO Hi-Z
        +
pump PWM floating = full speed
        ↓
uncommanded full-speed window may exist

它不是说所有 DPL30H 控制板上电都会满速。是否发生取决于：

• 具体 MCU 与具体引脚的复位状态；
• 内部及外部上拉/下拉；
• 泵电源和 MCU 电源的建立顺序；
• PWM 输入结构与阻抗；
• 看门狗复位、下载固件和掉电过程；
• 最终受控电气规格。

图 2｜示例上电时序：控制器处于高阻时，软件尚不能提供停机保证；安全状态必须由硬件与上电顺序共同建立。图中的延时和 40% 命令仅为架构示例。

二、为什么只改 main() 的第一行还不够

很多修复会在固件入口尽快执行。更严谨的伪代码会先预装停机电平，再把复用功能切换为输出，避免切换瞬间出现毛刺；具体顺序必须按所选 MCU 手册确认：

gpio_preload_output_latch(PUMP_PWM_PIN, STOP_LEVEL);
gpio_switch_mux_to_output(PUMP_PWM_PIN);

这比完全不处理好，但不能覆盖以下窗口：

1. 电源已经加到泵，MCU 电源还未稳定；
2. MCU 处于 POR/BOR/外部复位；
3. Bootloader、调试器或固件下载尚未进入应用代码；
4. 时钟、引脚复用和 PWM 外设初始化尚未完成；
5. 看门狗复位后，GPIO 又回到默认状态；
6. MCU 掉电速度快于泵电源掉电速度；
7. 固件异常卡死，外设保持在最后状态。

安全设计要回答的不是“程序启动后多久写 0”，而是：

在程序没有能力控制引脚的全过程里，泵端看到的电平是什么？

因此至少要分三层处理：

1. 板级默认安全态

PWM 端在 MCU 高阻时应保持在已确认的停机范围。但本文不会拍脑袋给出一个通用下拉电阻值，因为公开资料没有给出 DPL30H PWM 输入阻抗、内部上拉等效值和输入电流。

正确流程是：

• 获取所选 SKU 的正式电气规格；
• 根据输入结构与泄漏电流计算外部网络；
• 覆盖上电、复位、下载、掉电和故障状态；
• 在泵端实测 PWM 电压，而不是只看 MCU 寄存器。

2. 独立使能或电源门控

若系统风险较高，可让泵电源或独立使能在 MCU 未证明安全状态前保持关闭。这样即使 PWM 线浮动，也不能直接驱动泵。

3. 固件状态机

固件只有在“硬件安全电平已确认、配置版本正确、启动条件满足”后，才允许进入启动斜坡和 FG 验证。

三、不要擅自把 3.3 V GPIO 当成已兼容

一个常见 AI 幻觉是：

5 V PWM 输入当然也兼容 3.3 V CMOS，直接连接即可。

公开页面只明确给出了：

• 0–0.25 V：停机；
• 4.5–5 V 或悬空：全速；
• 支持 PWM 或 0–5 V 模拟调速。

3.3 V 既不在公开停机区，也没有达到公开的 4.5–5 V 全速区。 没有正式接口规格时，不能据此宣称 3.3 V GPIO 可直接驱动，也不能猜测推荐 PWM 频率、输入阈值或输入电流。

FG 也有同样边界：在没有确认它是推挽还是开漏、输出幅度和允许电流之前，不能直接决定是否加 3.3 V 上拉。

这类信息必须来自受控规格或项目确认，而不是让 Claude Code 根据“常见做法”补全。

四、FG 每转 3 脉冲，怎样换算转速？

公开接口说明给出每转 3 个 FG 脉冲。若测得 FG 频率为 $f_{FG}$，转速为：

$$RPM=\frac{60f_{FG}}{3}=20f_{FG}$$

若使用相邻 FG 边沿周期 $T_{FG}$：

$$RPM=\frac{20}{T_{FG}}$$

def rpm_from_fg_frequency(fg_hz: float, pulses_per_revolution: int = 3) -> float:
    if fg_hz < 0:
        raise ValueError("FG frequency must be non-negative")
    return 60.0 * fg_hz / pulses_per_revolution


def rpm_from_fg_period(period_s: float, pulses_per_revolution: int = 3) -> float:
    if period_s <= 0:
        raise ValueError("FG period must be positive")
    return 60.0 / (pulses_per_revolution * period_s)


print(rpm_from_fg_frequency(150.0))  # 3000 rpm
print(rpm_from_fg_period(1 / 150))   # 3000 rpm

这只是转子反馈。FG 有脉冲不能单独证明：

• 液体已经移动；
• 流量等于目标值；
• 管路没有堵塞；
• 泵内没有气泡；
• 阀和过滤器状态正确。

如果要证明液路结果，还需要压力、流量、重量、液位或工艺传感器等独立证据。

五、最小安全状态机：先证明安全，再允许启动

下面的 Python 代码是架构示例。启动宽限期、FG 超时和任何转速基线都不是产品放行参数，必须由真实电机、负载、采样和风险分析确定。

from dataclasses import dataclass
from enum import Enum, auto


class State(Enum):
    BOOT_HIZ = auto()
    SAFE_LEVEL_CONFIRMED = auto()
    STARTUP_GRACE = auto()
    RUN = auto()
    FAULT_FG_TIMEOUT = auto()


@dataclass(frozen=True)
class GuardConfig:
    pulses_per_revolution: int = 3
    startup_grace_s: float = 0.30   # example only
    fg_timeout_s: float = 0.16      # example only
    published_stop_max_v: float = 0.25


class PumpGuard:
    def __init__(self, config=GuardConfig()):
        self.config = config
        self.reset()

    def reset(self):
        self.state = State.BOOT_HIZ
        self.commanded_duty = 0.0
        self.command_time_s = None
        self.last_fg_edge_s = None
        self.last_fg_period_s = None
        self.flow_confirmed = False

    def confirm_hardware_safe_level(self, measured_pwm_v: float):
        if not 0.0 <= measured_pwm_v <= self.config.published_stop_max_v:
            raise ValueError("PWM input is not proven inside the stop band")
        self.state = State.SAFE_LEVEL_CONFIRMED

    def command_run(self, duty: float, now_s: float):
        if self.state is not State.SAFE_LEVEL_CONFIRMED:
            raise RuntimeError("Run blocked until hardware-safe level is confirmed")
        if not 0.0 < duty <= 1.0:
            raise ValueError("Duty must be in (0, 1]")
        # 新命令必须开启新的证据窗口；不能复用启动前的 FG 边沿。
        self.last_fg_edge_s = None
        self.last_fg_period_s = None
        self.commanded_duty = duty
        self.command_time_s = now_s
        self.state = State.STARTUP_GRACE

    def on_fg_edge(self, now_s: float):
        if self.last_fg_edge_s is not None:
            period = now_s - self.last_fg_edge_s
            if period <= 0:
                raise ValueError("FG timestamps must increase")
            self.last_fg_period_s = period
        self.last_fg_edge_s = now_s

    def tick(self, now_s: float):
        if self.state not in {State.STARTUP_GRACE, State.RUN}:
            return self.state

        age_from_command = now_s - self.command_time_s
        if self.state is State.STARTUP_GRACE and age_from_command <= self.config.startup_grace_s:
            return self.state

        fg_age = float("inf") if self.last_fg_edge_s is None else now_s - self.last_fg_edge_s
        if fg_age > self.config.fg_timeout_s:
            self.commanded_duty = 0.0
            self.last_fg_period_s = None
            self.state = State.FAULT_FG_TIMEOUT
        else:
            self.state = State.RUN
        return self.state

    @property
    def rpm(self):
        if self.last_fg_period_s is None:
            return None
        return 60.0 / (self.config.pulses_per_revolution * self.last_fg_period_s)

这个状态机刻意做了四件事：

1. BOOT_HIZ 不等于停机，只表示软件尚未取得可信控制；
2. 在实测 PWM 安全电平前，command_run() 必须拒绝执行；
3. 每次新启动都会清空旧 FG 时间戳，启动前的残留边沿不能为本次命令背书；
4. FG 超时后命令归零，并进入明确故障态。

六、FG 看门狗不能只“保存最后一次 RPM”

下面是另一种很隐蔽的驱动 bug：FG 脉冲消失后，程序仍返回最后一次计算得到的 3000 rpm。

if last_fg_period_s:
    rpm = 20.0 / last_fg_period_s

这段代码语法正确，但没有检查最后一次边沿是否已经过期。泵停转、FG 断线或输入捕获失败后，界面可能一直显示“3000 rpm 正常”。

必须同时检查：

fg_age_s = now_s - last_fg_edge_s

if fg_age_s > fg_timeout_s:
    rpm = None
    state = State.FAULT_FG_TIMEOUT
    commanded_duty = 0.0

Microchip AN3453 的失速检测说明 也采用类似思路：正常运行时周期反馈会持续清零计时器，若脉冲长时间缺失，定时器溢出并触发停机。这个方法可以作为工业控制模式参考，但不代表 DPL30H 内部使用相同实现。

图 3｜合成故障注入：PWM 运行命令仍在，FG 边沿在 2.4 s 消失；仅保存上一次周期会留下“陈旧转速”，必须在超时后把 RPM 标为无效并进入故障态。

七、8 项单元测试，比“代码能编译”更接近工程交付

我把上述架构写成可运行模块，并增加 8 项测试：

import unittest


class PumpGuardTests(unittest.TestCase):
    def setUp(self):
        self.guard = PumpGuard(
            GuardConfig(startup_grace_s=0.30, fg_timeout_s=0.16)
        )

    def test_run_is_blocked_before_safe_level_confirmation(self):
        with self.assertRaises(RuntimeError):
            self.guard.command_run(duty=0.5, now_s=0.0)

    def test_unconfirmed_3v3_is_not_treated_as_safe(self):
        with self.assertRaises(ValueError):
            self.guard.confirm_hardware_safe_level(3.3)

    def test_fg_edges_move_guard_to_run(self):
        self.guard.confirm_hardware_safe_level(0.10)
        self.guard.command_run(duty=0.5, now_s=0.0)
        for edge in [0.20, 0.206667, 0.213334]:
            self.guard.on_fg_edge(edge)
        self.assertEqual(self.guard.tick(0.31), State.RUN)

    def test_fg_period_converts_to_rpm(self):
        self.guard.on_fg_edge(1.000000)
        self.guard.on_fg_edge(1.006667)
        self.assertAlmostEqual(self.guard.rpm, 3000, delta=1)

    def test_fg_timeout_forces_zero_command(self):
        self.guard.confirm_hardware_safe_level(0.10)
        self.guard.command_run(duty=0.6, now_s=0.0)
        self.guard.on_fg_edge(0.20)
        self.assertEqual(self.guard.tick(0.40), State.FAULT_FG_TIMEOUT)
        self.assertEqual(self.guard.commanded_duty, 0.0)
        self.assertIsNone(self.guard.rpm)

    def test_watchdog_reset_returns_to_boot_hiz(self):
        self.guard.reset()
        self.assertEqual(self.guard.state, State.BOOT_HIZ)

    def test_precommand_fg_is_not_reused_after_new_start(self):
        self.guard.on_fg_edge(0.900000)
        self.guard.on_fg_edge(0.906667)
        self.guard.confirm_hardware_safe_level(0.10)
        self.guard.command_run(duty=0.5, now_s=1.0)
        self.assertIsNone(self.guard.rpm)
        self.assertEqual(self.guard.tick(1.31), State.FAULT_FG_TIMEOUT)

    def test_fg_does_not_prove_liquid_flow(self):
        self.guard.on_fg_edge(1.000000)
        self.guard.on_fg_edge(1.006667)
        self.assertGreater(self.guard.rpm, 0)
        self.assertFalse(self.guard.flow_confirmed)

本地运行结果：

Ran 8 tests in 0.001s
OK

完整可运行模块、测试和生成两张图的脚本已整理到 GitHub 工程仓库 pump-pwm-fg-startup-guard。

这些测试不能代替硬件测试，但能让 Claude Code / Codex 生成的后续修改持续满足几个关键不变量：

• 未证明安全电平，不得启动；
• 新启动不得复用启动前的旧 FG 边沿；
• FG 超时，必须撤销运行命令；
• 看门狗复位，必须回到未授权状态；
• 3.3 V 未确认，不得自行判定兼容；
• FG 有转速，不得自动设置 flow_confirmed=True。

八、建议至少做 8 类故障注入

一篇驱动程序是否可靠，不应只看正常路径。台架上至少要注入：

1. MCU 复位 200 ms，PWM 端处于高阻；
2. 泵电源先于 MCU 电源建立；
3. 固件初始化故意延迟；
4. 在线下载固件或 Bootloader 停留；
5. 看门狗复位；
6. FG 线断开或输入捕获关闭；
7. PWM 有命令、FG 有反馈，但液路被夹管或阀关闭；
8. MCU 先掉电、泵电源后掉电。

每个场景至少同步记录：

• 泵端 PWM 电压；
• MCU reset 与 GPIO 模式；
• 泵电源和独立使能；
• FG 边沿及边沿年龄；
• 压力/流量或重量证据；
• 状态机状态与故障码；
• 固件版本、板卡版本和回路版本。

九、Claude Code / Codex 应该做什么，不应该做什么

AI 很适合：

• 生成输入捕获、环形缓冲区和时间戳代码；
• 编写状态机、单元测试和故障注入脚本；
• 计算 FG 频率、RPM、超时和命令—反馈偏差；
• 查找“保存陈旧 RPM”“复位后自动恢复运行”等代码缺陷；
• 把示波器、FG、压力和流量日志对齐到统一时间轴；
• 生成测试报告和回归差异。

AI 不应该自行决定：

• 通用下拉电阻值；
• 3.3 V 是否兼容；
• 推荐 PWM 频率；
• FG 是开漏还是推挽；
• 启动宽限期和超时阈值；
• 哪个 RPM 偏差可以放行；
• FG 正常是否等于液路正常。

这些边界必须来自所选 SKU 的正式电气规格、原理图、风险分析和实测数据。

十、发布前检查表

在整机放行前，至少确认：

• 所选 MCU 具体引脚的复位状态已从数据手册核对；
• PWM 端在 MCU 高阻时的电压已在泵端实测；
• 泵和控制器的上电/掉电顺序已覆盖；
• 看门狗、Bootloader 和在线下载场景已注入；
• PWM 输入结构、3.3 V 兼容性和推荐频率来自受控规格；
• FG 输出类型、电平和上拉要求来自受控规格；
• FG 超时会撤销命令，陈旧 RPM 会被标记无效；
• 压力或流量证据独立于 FG；
• 安全状态不依赖“固件总能及时运行”；
• 所有阈值都带来源、版本和台架验证记录。

结语

AI 生成的泵驱动最容易关注“运行后怎样调速”，却忽略“程序运行前，硬件处于什么状态”。

真正可靠的顺序应该是：

硬件默认安全态
    → MCU 复位与上电顺序验证
    → PWM 停机电平实测确认
    → 启动斜坡
    → FG 反馈验证
    → 压力/流量结果验证
    → 才允许进入 RUN

当 Claude Code 或 Codex 返回 success=true 时，工程师还需要追问三件事：

1. 软件尚未运行时，泵端 PWM 是多少伏？
2. FG 最后一个边沿是否已经过期？
3. 即使转子在转，液体真的按预期移动了吗？

这三个问题，比“代码是否编译通过”更接近真实的仪器安全。

参考资料

1. FOREACH：DPL30H High-Pressure Diaphragm Pump Selection Guide
2. FOREACH：2-Wire vs 5-Wire Brushless Diaphragm Pumps
3. Texas Instruments：MSP432E411Y Datasheet，GPIO default high-impedance notes
4. STMicroelectronics：STEVAL-IHM040V1 Hardware Description，reset/high-impedance safety notes
5. Microchip AN3453：Stall Detection

边界说明：本文的时序、启动宽限期、FG 超时和故障注入数据均为架构示例，不是 FOREACH 产品放行参数。“上电可能满速”是泵接口公开逻辑与具体控制板复位状态组合后的系统推论，不代表所有控制板必然发生。量产设计必须以所选型号的正式电气规格、受控图纸和项目确认结果为准。