Serial 模块文档¶

所属工具箱：ADC and Serial

Serial 模块外观

简介¶

一句话描述：该模块实现Simulink模型与外部设备之间的串行端口数据收发通信，支持灵活的通信配置选项。

该模块是RflySim工具链ADC and Serial接口库中的硬件通信模块，支持在Simulink仿真过程中通过串行接口与各类外部硬件设备（如传感器、第三方微控制器、外设等）进行实时数据交换，主要用于需要Simulink模型对接外部硬件的半物理仿真、硬件在环仿真以及实机部署场景。

Serial模块支持读写两种工作模式，可灵活配置波特率、帧格式、阻塞机制、通信协议等参数，同时支持解释执行和代码生成两种运行方式，既可以在仿真调试阶段使用解释执行快速验证通信逻辑，也可以在部署阶段编译生成C代码获得更高的通信实时性。该模块常配合PX4飞控硬件、其他外设拓展使用，为RflySim平台的半物理仿真、实机验证流程提供稳定的串行通信支持。

端口说明¶

输入端口（Inputs）¶

端口名	数据类型	维度	说明
`DataIn`	`uint8`	N×1	Writing模式下输入待发送到串行端口的数据，N为待发送数据长度

仅在Writing操作模式下存在该输入端口，Reading模式下本模块无输入端口。

输出端口（Outputs）¶

端口名	数据类型	维度	说明
`DataOut`	`uint8`	N×1	Reading模式下输出从串行端口接收到的数据，N为配置的读取字节数
`ByteCount`	`double`	1×1	Reading模式下开启`Output Number of Bytes Receive`选项后输出，为实际接收到的字节数

仅在Reading操作模式下存在输出端口，Writing模式下本模块无输出端口。

参数配置（Parameters）¶

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

参数名	类型	默认值	可选值/范围	说明
`Device Name`	`string`	`/dev/ttyS0`	任意合法设备路径	指定要通信的串行端口设备名称，Linux系统通常为`/dev/`开头的路径，Windows系统通常为`COMx`格式
`Read or Write to serial`	`enum`	`Reading`	`Reading`, `Writing`	选择串行端口的操作模式：`Writing`为从Simulink发送数据到串行端口，`Reading`为从串行端口读取数据到Simulink
`Baud Rate`	`int`	`115200`	标准串行波特率枚举值	设置串行通信的波特率，需与连接的外部设备波特率一致
`Blocking`	`bool`	`false`	`true`, `false`	是否启用阻塞模式：启用后模块会等待发送/接收操作完成再继续仿真，否则直接继续执行
`Output Number of Bytes Receive`	`bool`	`false`	`true`, `false`	Reading模式下可用：启用后会额外输出实际接收到的字节数信号
`Enable Terminator`	`bool`	`false`	`true`, `false`	Writing模式下可用：启用后会在每次发送的数据末尾附加终止符（换行符）
`Enable Header`	`bool`	`false`	`true`, `false`	Writing模式下可用：启用后会为发送的数据包添加头部标识，适配需要包头的通信协议
`Enable Comm Protocol`	`bool`	`false`	`true`, `false`	启用后使用指定通信协议处理数据传输，适配复杂通信场景
`indicate number of bytes to read`	`int`	`4`	≥1的正整数	Reading模式下指定需要读取的字节数
`Simulate using`	`enum`	`Interpreted Execution`	`Interpreted Execution`, `Code Generation`	选择仿真执行方式：解释执行适合调试，代码生成模式性能更高，支持部署

参数设置说明¶

`Device Name`¶

不同操作系统下串行设备的命名规则不同：Linux系统通常为/dev/ttyUSB0、/dev/ttyS0这类路径格式，Windows系统通常为COM1、COM3这类格式，需要根据实际连接的设备修改为对应名称。

`Read or Write to serial`¶

选择不同的操作模式会自动变更模块的端口结构：选择Writing会生成输入端口，无输出端口；选择Reading会生成输出端口，无输入端口，开启字节数输出后会额外增加一个输出端口。

`indicate number of bytes to read`¶

仅在Reading模式下生效，模块会按照该参数指定的长度预分配缓冲区并读取对应长度的数据，若实际接收不足该长度，阻塞模式会等待收满，非阻塞模式会输出已接收数据并通过ByteCount端口输出实际接收长度。

`Simulate using`¶

如果需要生成C代码进行半物理仿真或实际部署，需要选择Code Generation模式，开发调试阶段可选择Interpreted Execution模式方便排查问题。

模块特性（Block Characteristics）¶

特性项	值
支持的数据类型	`double`、`single`、`uint8`、`uint16`、`uint32`、`int8`、`int16`、`int32`
直接馈通（Direct Feedthrough）	是（Writing模式）/ 否（Reading模式无输入）
采样时间	离散
代码生成支持	是

数据通信协议¶

本模块为标准串行端口（UART）通信，遵循标准RS-232串行通信规范，数据格式与通信规则对用户开放配置，无额外自定义协议。

使用示例¶

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

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

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

注意事项与常见问题¶

初始化顺序：同一串行端口不能同时被多个Serial模块或其他进程打开占用，否则会触发端口打开失败错误。请确保一个串行端口仅被一个Serial模块使用，同时关闭系统中其他占用该端口的程序。
参数匹配要求：模块配置的波特率必须与连接的外部硬件设备波特率完全一致，否则会出现乱码或通信失败问题。使能终止符、头部、自定义通信协议等选项时，参数配置必须和对端设备的通信协议保持一致，否则无法完成正确的数据解析。
设备名称格式：不同操作系统的串行设备名称格式不同，Linux系统通常为/dev/ttyUSB0、/dev/ttyS0这类路径格式，Windows系统通常为COM1、COM3这类格式，请根据实际操作系统填写正确的设备名称，错误的设备名称会导致端口打开失败。
阻塞模式影响：如果开启Blocking阻塞模式，仿真步长会被串行收发操作阻塞，若对端设备无数据返回会导致仿真停滞。如果需要保证仿真实时运行，请关闭阻塞模式。
读取字节数配置：Reading模式下需根据实际通信数据包长度正确配置indicate number of bytes to read参数，若配置值小于实际数据包长度会导致数据截断，大于实际长度会等待多余数据，引发延迟或数据错位。
采样时间匹配：Serial模块的采样时间需要和模型整体仿真步长匹配，过高的采样频率超过串行端口的实际传输速率时，会出现数据丢包或缓冲区溢出问题。在非阻塞模式下，建议根据波特率和单次收发数据量合理设置采样间隔。
执行模式选择：如果需要调试通信逻辑，选择Interpreted Execution解释执行模式即可；如果需要进行长时间仿真或生成代码部署，需要切换为Code Generation代码生成模式，否则仿真速度会明显偏低。
权限问题（Linux系统）：在Linux系统下使用USB转串口设备时，当前用户需要拥有串口设备的访问权限，如果出现打开端口失败的提示，可以通过将当前用户加入dialout用户组解决权限问题。

更新日志¶

v4.10 (2024-08-13): 初始版本发布，实现Simulink与外部设备通过串行端口进行数据收发通信，支持操作模式选择、波特率配置、终止符/包头/通信协议可选使能、解释执行与代码生成两种运行模式等功能。