串口

串口通道用于连接 USB 转串口、RS232、RS485 转换器或其它表现为 COM 口的设备。Zeus 负责打开、关闭、写入和接收事件；你不需要直接使用 System.IO.Ports.SerialPort。

接设备前先确认三件事

要确认	例子	去哪里看
端口名	`COM3`	Windows 设备管理器
通信参数	`9600, 8N1`	设备手册或现场配置
协议	原始字节、自定义帧、Modbus RTU	设备通讯协议文档

只知道 COM 口还不够。波特率、校验位、停止位或协议不一致时，端口可能能打开，但收不到正确数据。

最小用法

await using var app = ZeusHost.Create(builder =>
{
    builder.AddSerialPort("meter", "COM3", 9600);
});

var meter = app.Channels.Get("meter");
meter.DataReceived += (_, e) =>
{
    Console.WriteLine(Convert.ToHexString(e.Data.Span));
};

await app.StartAsync();
await meter.WriteAsync(new byte[] { 0x01, 0x03, 0x00, 0x00, 0x00, 0x02, 0xC4, 0x0B });

这里的 meter 是你给通道起的名字，不是系统里的 COM 口名。COM3 才是操作系统端口名。

更完整的参数写法

设备如果不是默认 8N1，用 options 写法：

builder.AddSerialPort("meter", options =>
{
    options.PortName = "COM3";
    options.BaudRate = 9600;
    options.DataBits = 8;
    options.Parity = System.IO.Ports.Parity.Even;
    options.StopBits = System.IO.Ports.StopBits.One;
    options.ReadTimeoutMilliseconds = 500;
    options.WriteTimeoutMilliseconds = 500;
});

参数说明

属性	默认	大白话
`PortName`	`COM1`	Windows 看到的端口号
`BaudRate`	`115200`	每秒传输速率，必须和设备一致
`DataBits`	`8`	数据位，常见是 8
`Parity`	`None`	校验位，常见是 None / Even
`StopBits`	`One`	停止位，常见是 One
`ReadTimeoutMilliseconds`	`1000`	读超时
`WriteTimeoutMilliseconds`	`1000`	写超时

从虚拟通道切换过来

开发界面时先写：

builder.AddVirtualChannel("meter");

接硬件时只改成：

builder.AddSerialPort("meter", "COM3", 9600);

如果你使用 JSON 配置，改 zeus.json 里的通道类型即可，不需要重新编译。

和协议怎么配合

串口通道只负责字节，不理解设备协议。

设备协议	推荐做法
设备手册给的是固定十六进制命令	直接 `WriteAsync`，在 `DataReceived` 里处理返回字节
设备是“帧头 + 长度 + 校验”	使用自定义帧
设备是 Modbus RTU	使用 Modbus，不要手拼 CRC

常见问题

现象	最可能原因	处理
打开失败，提示端口被占用	串口助手或其它程序正在使用	关闭其它程序，重新启动应用
找不到 `COM3`	端口号变了或驱动没装好	看设备管理器，重新插拔 USB 转串口
能打开但收不到数据	接线、波特率、校验位或设备未主动上报	先用串口助手确认设备能回包
收到乱码	把二进制协议当文本显示	先用 `Convert.ToHexString` 看原始字节
Modbus 一直超时	从站地址、功能码、RTU/TCP 或 CRC 不对	先用虚拟 Modbus 从站验证主站逻辑

没有硬件时，继续用虚拟通道。

接设备前先确认三件事​

最小用法​

更完整的参数写法​

参数说明​

从虚拟通道切换过来​

和协议怎么配合​

常见问题​