inject-faults

故障注入

使用 evaluate_matlab_code 和 Simulink.fault API，以编程方式向 Simulink 模型注入故障。故障会覆盖模块端口上的信号值，以模拟硬件故障、传感器故障和执行器异常。

适用场景

• 为安全分析注入传感器固定值故障、噪声或偏置（Simulink、Simscape、System Composer）
• 通过仿真验证 FMEA 故障模式
• 测试控制器应对执行器或传感器故障的鲁棒性
• 添加故障占位项（不含行为），以便在定义故障逻辑前进行 FMEA 可追溯性管理
• 配置故障触发条件（定时、条件触发、始终启用）
• 为自动化测试创建故障场景
• 比较正常行为与故障行为
• 将故障关联到 FMEA 故障模式单元格
• 生成故障规范报告
• 导出包含嵌入式故障行为的模型，供没有 Simulink Fault Analyzer 的团队使用
• 注册自定义故障行为库
• 将引用模型、子系统或链接库中的故障信息同步（也称为重新同步 / 同步 / 同步故障 / 更新故障引用）到父模型

不适用场景

• 创建 FMEA 电子表格或安全分析文档 -> 使用 manage-safety-analysis
• 构建或编辑模型结构 -> 使用 building-simulink-models
• 运行标准（无故障）仿真 -> 使用 simulating-simulink-models
• 编写通过/失败测试 -> 使用 testing-simulink-models

探查

hasFA = ~isempty(which('Simulink.fault.addFault'));
fprintf('Simulink Fault Analyzer available: %d\n', hasFA);

核心概念

• 故障：应用于模块端口（输入端口或输出端口）的修改，用于覆盖信号值。
• 无行为的故障：用于记录故障点但无法仿真的占位项。
• 有行为的故障：具有关联行为模型、可进行仿真的故障（参见 references/fault-behaviors.md）。
• 故障模型：包含故障行为子系统的 .slx 文件。
• 触发器：故障激活的时机（始终启用、定时、条件触发、手动）。
• 故障信息文件：<ModelName>_faultInfo.xml 用于在模型旁存储所有故障元数据。

重要限制

1. 故障附加到模块端口，而不是模块。 必须通过 get_param(blockPath, 'PortHandles') 获取端口句柄。
2. 绝不要直接编辑 _faultInfo.xml 文件。 修改故障定义时，始终使用 MATLAB API。
3. 故障名称必须是有效的 MATLAB 标识符（不能包含空格、斜杠或特殊字符）。请使用驼峰式或帕斯卡式命名。
4. 故障行为模型名称（addBehavior 的第一个参数）也必须是有效的 MATLAB 标识符。
5. 绝不要使用 Simulink.fault.deleteAll 或 Simulink.fault.deleteFault 来切换仿真中的故障状态。 删除故障会永久销毁故障对象、其行为模型（.slx 文件）及其可追溯性链接。若要运行正常仿真，请使用 Simulink.fault.injection(model, false) 禁用所有故障注入；要重新启用，请使用 Simulink.fault.injection(model, true)。若要禁用特定元素上的故障，请使用 Simulink.fault.enable(modelElement, false)。
6. 不支持： Stateflow 图表、故障模型或观测器模型中的故障。

工作流

1. 了解模型。 使用 model_overview 和 model_read 找出脆弱的信号路径——单点执行器、传感器反馈，以及扇出范围较大的计算量。
2. 预检。 查询已编译的端口属性，确认信号兼容性。如果模型尚未编译，请先征求用户同意再进行编译。参见 references/preflight-and-adding-faults.md。
3. 获取端口句柄。 故障附加到端口句柄，而不是模块路径。使用 get_param(blk, 'PortHandles')。
4. 添加故障。 调用 Simulink.fault.addFault(portHandle, Name=..., Description=...)。参见 references/preflight-and-adding-faults.md。
5. 添加行为。 调用 addBehavior(fault, modelName, FaultBehavior='mwfaultlib/...')。参见 references/fault-behaviors.md。
6. 配置触发器。 设置 fault.TriggerType 及相应属性（例如，Timed 使用 StartTime，Conditional 使用 Conditional，Manual 使用 TriggerActive）。参见 references/triggers-and-conditionals.md。
7. 保存。 调用 Simulink.fault.save('ModelName')。
8. 仿真。 通过 Simulink.fault.injection(mdl, true) 启用注入，然后调用 sim(...)。参见 references/simulation-workflows.md。

注意事项

始终

• 注入故障前，使用 model_read 确认目标模块
• 创建故障前检查已编译的端口信息（参见 references/preflight-and-adding-faults.md）
• 设置触发器属性之前，先添加行为
• 任何故障变更后，都使用 Simulink.fault.save('ModelName') 保存
• 使用 activate(fault) 验证故障处于激活状态，再运行带故障的仿真
• 分析完成后，使用 Simulink.fault.injection(mdl, false) 禁用故障注入
• 验证测试输入信号在故障注入点处非零
• 选择 mwfaultlib 行为前，检查总线兼容性

绝不

• 使用 Simulink.fault.Fault() 构造函数——请改用 Simulink.fault.addFault()
• 将库模块路径（例如 mwfaultlib/Stuck-at-Ground）作为故障模型名称参数传给 addBehavior——请使用 FaultBehavior 名值对
• 假定故障仿真已关闭——每次运行名义仿真前都要确认
• 违反“关键约束”部分中的任何要求

先征求同意

• 因任何原因修改设计模型前（添加模块、更改采样时间、重新连接信号）
• 在可能共享的模型上启用故障前（这会改变模型行为）
• 删除现有故障前（行为模型 .slx 也会被删除）
• 将 fault.Persistent = true 启用前——这会使故障在仿真过程中不可逆

故障排除

问题	原因	解决方法
Simulink.fault.Fault() 中出现 Assertion failed	不要直接使用 Fault() 构造函数	改用 Simulink.fault.addFault(portHandle, Name=..., Description=...)
Fault name must follow MATLAB variable naming conventions	名称包含空格或特殊字符	使用驼峰式或帕斯卡式命名，且不包含空格（例如 SensorStuckAtZero）
Invalid name for a fault model	行为模型名称包含无效字符	使用简单的 MATLAB 标识符（例如 StuckAtZero，不要使用 Stuck-at-Zero）
Unable to add fault... only to block input or output ports	传入了模块路径或句柄，而不是端口句柄	使用 ph = get_param(blockPath, 'PortHandles'); ph.Outport(1)
Target signal is a continuous-time signal	Fault Analyzer 无法向连接到连续模块的连续信号注入故障	请参阅 references/advanced-operations.md 中的连续时间信号决策树
Output dimensions do not match 或 Data type mismatch	故障常量的大小或类型与目标信号不匹配	请参阅 references/fault-behaviors.md 中的“向量和矩阵故障值”
总线信号使用非 Ground 行为时故障注入失败	大多数 mwfaultlib 行为仅支持标量	对整个总线使用 Stuck-at-Ground，或使用 BusElement 指定单个元素
同一端口上有多个故障，但只有一个生效	每次只有一个端口故障处于活动状态	使用 activate(fault) 进行选择，或设置不同的 StartTime 值
故障已存在，但仿真仍按标称状态运行	未启用故障注入，或故障未激活	调用 Simulink.fault.injection('Model', true) 和 activate(f)

参考文件

文件	内容
references/preflight-and-adding-faults.md	端口检查、编译检查、添加故障、解析端口句柄、故障对象属性和方法
references/fault-behaviors.md	内置行为、自定义行为、总线故障、向量／矩阵故障、发现、数据输入端口源
references/triggers-and-conditionals.md	触发器类型、条件创建、条件／符号对象属性
references/simulation-workflows.md	运行仿真、标称状态与故障状态对比、选择性故障隔离
references/advanced-operations.md	FMEA 链接、报告、导出、删除、连续时间变通方法、同步引用模型／子系统／库中的故障
references/test-case-integration.md	将故障集添加到 Simulink Test 测试用例中（R2024a+）

---

版权所有 2026 The MathWorks, Inc.

---