HIL16CtrlsNorm 模块文档¶

所属工具箱：RflySim APIs

HIL16CtrlsNorm 模块外观

简介¶

一句话描述：该模块用于在RflySim硬件在环（HIL）仿真中，将Simulink生成的16维归一化控制信号发送给CopterSim，支持Simulink自定义控制器与PX4原生控制器的模式切换。

该模块是RflySim工具链中面向自定义控制器硬件在环仿真开发的核心API模块，主要用于Simulink控制器开发场景下的控制信号交互。开发者可以将自定义算法输出的16维归一化控制信号接入该模块，模块会将信号转发至CopterSim的DLL物理仿真模型，实现自定义控制器对无人机动力学模型的控制。

该模块支持自动解锁、PX4输出屏蔽/解除、模式切换等配置，可配合PX4飞控完成硬件在环仿真：当使能输入有效时，使用Simulink自定义控制器控制无人机；当使能输入无效时，可自动切换到PX4原生Loiter模式保持悬停，方便开发者在仿真中验证自定义控制器的控制效果，对接CopterSim动力学仿真与PX4飞控，同时支持RflySim3D可视化实时仿真展示。

端口说明¶

输入端口（Inputs）¶

端口名	数据类型	维度	说明
`isEnCtrl`	`boolean`	`1×1`	使能控制信号输入标志位，输入为true时发送输入的归一化控制信号，输入为false时发送全零控制信号
`CtrlS`	`double`	`1×16`	16维归一化控制信号，范围为-1到1，用于HIL仿真

输出端口（Outputs）¶

端口名	数据类型	维度	说明
`CtrlS_out`	`double`	`1×16`	处理后的16维归一化控制信号，将被发送到CopterSim DLL模型的inPWM接口

参数配置（Parameters）¶

双击模块打开的 Mask 对话框中可配置以下参数：

参数名	类型	默认值	可选值/范围	说明
`Auto arm`	`bool`	`false`	`true/false`	勾选后，使能控制时模块自动发送解锁指令
`Auto block PX4`	`bool`	`false`	`true/false`	勾选后，控制使能时自动屏蔽PX4输出，允许Simulink控制器控制载具
`Auto Loiter`	`bool`	`false`	`true/false`	勾选后，控制禁用时自动解除PX4输出屏蔽，并切换PX4到自动Loiter模式，保持载具空中悬停
`Sample Time(s)`	`double`	`0.01`	`>0`	模块采样时间，单位为秒

参数设置说明¶

`Auto arm`¶

勾选该选项后，当isEnCtrl输入为true（使能控制）时，模块会自动向飞控发送解锁指令，无需用户额外处理解锁逻辑，简化HIL仿真的起飞流程。

`Auto block PX4`¶

该参数用于实现Simulink用户控制器和PX4原生控制器的切换：当勾选后，isEnCtrl为true时，模块会发送信号屏蔽PX4的输出，此时载具完全由Simulink中搭建的用户控制器输出控制信号；若不勾选，则不会修改PX4的输出使能状态。

`Auto Loiter`¶

该参数用于保证切换回PX4控制时载具的安全性：当勾选后，isEnCtrl为false（禁用用户控制）时，模块会自动解除对PX4输出的屏蔽，并命令PX4切换到Loiter（悬停）模式，保证载具可以稳定保持在空中，避免切换过程中出现失控风险。

`Sample Time(s)`¶

该参数指定模块执行控制信号发送的采样周期，需匹配Simulink仿真的步长设置，默认值为0.01s对应100Hz的控制频率，符合大多数无人机控制器的周期要求。

模块特性（Block Characteristics）¶

特性项	值
支持的数据类型	`double`、`single`
直接馈通（Direct Feedthrough）	是
采样时间	离散
代码生成支持	否

数据通信协议¶

模块通过UDP协议与CopterSim进行通信，将归一化控制信号发送至CopterSim，默认遵循RflySim平台的通信端口规则，数据格式为16个double类型归一化控制量+配置指令数据。

使用示例¶

相关使用示例请参考以下路径：

[RflySim安装路径]/RflySimAPIs/5.RflySimFlyCtrl/0.ApiExps/16.CtrlsSingalsAPI/Readme.pdf

请在上述路径中查看 Readme.pdf 获取完整的示例说明与操作步骤。

注意事项与常见问题¶

初始化顺序：该模块依赖CopterSim完成HIL仿真环境初始化后才能正常发送控制信号，需要确保仿真启动前CopterSim已经完成硬件在环连接配置，否则会导致控制信号无法正确传输到PX4飞控。
归一化范围约束：输入的16维控制信号CtrlS[16]必须保证数值范围为-1到1，即使是油门通道也需要符合该范围要求，超出范围会导致CopterSim解析控制信号出错，引发飞行器控制异常。不同机型控制范围要匹配需求：多旋翼的控制信号通常控制在0到1范围内，固定翼控制信号可使用全范围-1到1。
功能选项逻辑匹配：勾选Auto Loiter后，当isEnCtrl输入为false时会自动切换PX4到Loiter悬停模式，请勿再额外通过其他模块发送模式切换指令，避免模式指令冲突导致飞控工作异常；如果需要全程由Simulink控制器控制，请勿同时勾选Auto Loiter。
采样时间匹配：模块的Sample Time(s)参数需要和Simulink模型整体步长、CopterSim的仿真步长保持匹配，步长差异过大会导致控制信号发送时序紊乱，引发控制时延或者信号丢包问题。
使能信号逻辑：当isEnCtrl输入为false时模块会全输出0信号，若开启了Auto block PX4会同时屏蔽PX4输出，请勿在isEnCtrl false时无操作保持仿真，避免飞行器失去控制坠机。

更新日志¶

v4.24 (2024-08-07): 初始版本发布，实现发送16维归一化控制信号到CopterSim的硬件在环仿真功能，支持自动解锁、PX4输出屏蔽、自动Loiter模式切换配置

模块名	说明
`getStatesFromCopterSim`	从CopterSim获取无人机的状态数据
`setPX4OffboardNorm`	发送归一化的offboard控制指令给PX4
`HIL8CtrlsNorm`	发送硬件在环8维归一化控制信号到CopterSim
`VehicleCtrlRaw`	发送原始PWM控制信号到CopterSim用于HIL仿真