1. 从 System.IO.Ports 翻车说起:Unity 串口通信该用什么
在 Unity 这类代码开发工具里做串口通信,很多人的第一反应是 .NET 自带的 System.IO.Ports,然后在 Mac 或 Android 上翻车。我最早也是这么干的,编辑器里跑得好好的,一打包到移动端就报平台不支持,或者端口能打开但一个字节都收不到。后来换成专门的串口通信插件,I/O 走本机代码实现,Windows、Mac、Android 一套逻辑走通,这块才算稳定下来。
这篇写的就是我实际用下来的一套接入流程:设备怎么枚举、唯一 ID 怎么绑、事件驱动怎么收数、JSON 怎么直接映射成类,以及手边没有硬件时怎么用 TCP 串口模拟器先把逻辑跑通。适合已经会写 Unity 脚本、但被跨平台串口折腾过一轮的人。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 串口插件接入:从导入到第一个能收发的场景
2.1 导入与平台切换前的三件事
插件的导入本身没什么好说的,把包放进工程、等编译通过就行。真正容易出问题的是导入之后的三件事,我一般是按顺序确认,不跳步。
第一件是确认插件用的是本机代码实现的 I/O。这一点很关键,因为它的意义不是「性能更好」,而是「不依赖 .NET 的 System.IO.Ports」。后者在桌面平台上能用,但到了 Android 这类平台,运行时的串口实现并不完整,你写的代码能编译通过,运行起来却拿不到端口。插件把这一层换成了原生实现,跨平台才有意义。
第二件是把目标平台切过去再编译一次。很多人只在 Editor 下验证,觉得逻辑没问题就打包,结果平台相关的库没被正确带进去。我的习惯是:Editor 下跑通一次,切到目标平台再跑一次,两次都过了才算接入完成。
第三件是 Android 上的 USB 权限。移动端枚举到 USB 串口设备之后,系统会要求授权,没授权的情况下端口是打不开的。这一步不是插件能替你绕过的,得在拿到设备后先走一遍授权流程,授权结果稳定了再谈打开端口。我在第一次做 Android 串口时就栽在这,日志里只看到「打开失败」,查了半天以为是波特率不对,其实是权限弹窗被我一划而过。
提示:平台切换后建议清一次 Library 再编译,避免旧的平台缓存干扰判断。
2.2 设备枚举与唯一 ID 绑定
这是整个接入里最值得花时间的一步。串口的坑有一大半不是出在收发上,而是出在「你以为连的是这台设备,其实连的是另一台」。
Windows 上插拔 USB 转串口设备,COM 号是会变的。今天插上去是 COM3,明天换个 USB 口可能就是 COM5。如果你在代码里把端口号写死,换台机器或者换个口就得改代码,测试同学一插拔你就得重新打包。插件提供了设备唯一 ID 的能力,我一般用它来定位设备,端口号只作为展示用。
csharp复制// 设备枚举与按唯一 ID 打开:结构示意,具体方法名以插件文档为准
using System.Collections.Generic;
using UnityEngine;
public class SerialBootstrap : MonoBehaviour
{
[SerializeField] private string targetDeviceId; // 在 Inspector 里填目标设备的唯一 ID
[SerializeField] private int baudRate = 115200; // 必须与固件端一致
private object portHandle; // 插件返回的端口对象
void Start()
{
// 1. 枚举当前在线的串口设备
var devices = SerialPortPlugin.GetDeviceList();
if (devices == null || devices.Count == 0)
{
Debug.LogError("没有枚举到任何串口设备,先检查线缆和供电");
return;
}
// 2. 打印出来,方便第一次接入时把唯一 ID 抄进 Inspector
foreach (var d in devices)
{
Debug.Log($"设备: {d.Name} | 唯一ID: {d.UniqueId} | 端口: {d.PortName}");
}
// 3. 按唯一 ID 匹配,而不是按端口号匹配
var target = devices.Find(d => d.UniqueId == targetDeviceId);
if (target == null)
{
Debug.LogError($"目标设备 {targetDeviceId} 不在线");
return;
}
// 4. 打开端口,串口参数必须和固件端逐项对齐
portHandle = SerialPortPlugin.Open(
target,
baudRate: baudRate,
dataBits: 8,
stopBits: 1,
parity: Parity.None
);
if (portHandle == null)
{
Debug.LogError("端口打开失败,优先查权限和波特率");
}
}
}
代码里第 2 步的打印不要嫌啰嗦,第一次接入时把唯一 ID 抄下来填进 Inspector,后面换机器、换 USB 口都不用改代码。第 3 步按 ID 匹配是这段代码的核心:端口号是「位置」,唯一 ID 是「身份」,位置会变,身份不会。第 4 步的参数里,baudRate 是最容易对不上的一个,固件端写 9600、上位机写 115200,现象不是报错,而是收到一堆乱码,很容易被误判成编码问题。
注意:枚举列表里出现设备,不代表端口一定能打开。枚举只说明系统认到了硬件,打开还涉及权限和占用。
2.3 打开端口:参数对齐固件
串口参数一共就那么几项,但每一项对不上都有不同的表现形式,排起来是有顺序的。我一般按下面这张表逐项确认,不靠猜。
| 参数 | 常见取值 | 对不上时的现象 | 排查顺序 |
|---|---|---|---|
| 波特率 | 与固件一致,常见 9600 / 115200 | 收到乱码或全 0 | 第 1 位 |
| 数据位 | 8 | 字符错位、解析失败 | 第 2 位 |
| 停止位 | 1 | 偶发丢字节 | 第 3 位 |
| 校验位 | None | 整帧被拒或乱码 | 第 4 位 |
| 流控 | 一般不启用 | 发得出去收不回来 | 最后确认 |
排查顺序不是随便排的。波特率错的表现最明显,乱码一眼就能看出来;数据位和停止位错的表现更隐蔽,往往是「大部分时候正常,偶尔少一个字节」,容易被当成业务逻辑的 bug 去查。流控放在最后,是因为它在短距离、低速率下通常不影响,但一旦设备端启用了硬件流控而上位机没启用,现象就是发送正常、接收全空,这个组合最迷惑人。
打开端口之后,我习惯先做一次最小验证:发一个固定的心跳字节,看设备端有没有回。回了,说明链路通,再往上叠协议;不回,就别急着写业务代码,先在链路层把问题解决掉。这一步花五分钟,能省掉后面几个小时的「到底是协议解析错了还是根本没收到数据」。
3. 串口插件的事件驱动收数:把字节流变成可用的类
3.1 回调结构:为什么不要在回调里碰 Unity API
串口数据到达的时机是不确定的,插件用事件驱动的方式把数据推给你,而不是让你在主循环里轮询。这个设计本身是对的,但用的时候有个前提必须记住:回调执行的上下文不一定是 Unity 的主线程。
我见过最常见的翻车姿势,是在数据回调里直接 Instantiate 一个物体、改一个 Transform、或者更新 UI 文本。编辑器下大概率没事,打包到真机就偶发卡死或者报「不在主线程调用」。原因是原生层的回调线程和 Unity 的主线程是两条线,Unity 的大部分 API 只允许在主线程调用。
我的做法很简单:回调里只做一件事,把数据塞进队列,其它什么都不干。
csharp复制// 事件驱动接收:回调只入队,主线程消费
using System.Collections.Generic;
using UnityEngine;
public class SerialReceiver : MonoBehaviour
{
private readonly Queue<string> rxQueue = new Queue<string>();
private readonly object queueLock = new object();
void OnEnable()
{
// 数据到达事件
SerialPortPlugin.OnDataReceived += HandleData;
// 物理断开事件,拔线时触发
SerialPortPlugin.OnDisconnected += HandleDisconnected;
}
void OnDisable()
{
SerialPortPlugin.OnDataReceived -= HandleData;
SerialPortPlugin.OnDisconnected -= HandleDisconnected;
}
private void HandleData(byte[] buffer, int length)
{
if (length <= 0) return;
// 回调线程不碰 Unity API,只做编码和入队
string text = System.Text.Encoding.UTF8.GetString(buffer, 0, length);
lock (queueLock)
{
rxQueue.Enqueue(text);
}
}
private void HandleDisconnected()
{
// 断开事件同样先记录下来,交给主线程处理重连
lock (queueLock)
{
rxQueue.Enqueue("__DISCONNECTED__");
}
}
void Update()
{
lock (queueLock)
{
while (rxQueue.Count > 0)
{
string item = rxQueue.Dequeue();
if (item == "__DISCONNECTED__")
{
// 这里才做状态切换、UI 提示、重连调度
OnPortLost();
continue;
}
ProcessFrame(item);
}
}
}
private void OnPortLost() { /* 切状态机、提示、延迟重连 */ }
private void ProcessFrame(string frame) { /* 解析并驱动业务 */ }
}
加锁这件事别省。串口数据到达的频率可能很高,Queue 本身不是线程安全的,一边入队一边出队,偶发的 InvalidOperationException 就是这么来的。这种偶发问题最难查,因为它在编辑器里几乎不复现,只在真机高负载时冒出来。
3.2 JSON 直接映射到类变量
设备端和 Unity 之间传结构化数据,最省事的做法是传 JSON。插件提供了直接把 JSON 映射到类变量的能力,不需要自己写一遍字段解析。用法上和平常的 JSON 反序列化差不多,先定义和目标结构一致的类,再把字符串丢进去。
csharp复制// 设备上报的数据结构,字段名与 JSON 的 key 保持一致
[System.Serializable]
public class SensorPacket
{
public float temperature; // 温度
public int distance; // 距离
public string state; // 设备状态
}
// 反序列化:把一帧完整 JSON 映射成类实例
private SensorPacket ParsePacket(string json)
{
if (string.IsNullOrEmpty(json)) return null;
try
{
return SerialPortPlugin.JsonUtility.FromJson<SensorPacket>(json);
}
catch (System.Exception e)
{
// 解析失败不要静默吞掉,打日志并丢弃这一帧
Debug.LogWarning($"JSON 解析失败: {json}, 原因: {e.Message}");
return null;
}
}
这里有两点值得强调。一是字段类型要和设备端严格一致,设备发的是字符串 "25.3"、类里定义的是 float,有些解析器会宽容处理,有些会直接失败,行为不统一,最好在设备端就定死类型。二是解析失败要有日志,但不要抛出去打断主循环,串口数据里混进半帧是常事,一帧失败丢掉就行,下一帧接着来。
3.3 字符流切分与 List/Dictionary 转换
串口是字节流,不是消息流。你收到的数据在时间上是连续的,但没有天然的边界。设备一次发 30 个字节,你可能分两次收到 18 和 12,也可能两帧粘在一起一次收到 60 个。这就是常说的粘包和拆包,不处理的话,JSON 解析会随机失败。
我的处理方式是在协议层加一个明确的帧边界,最常用的是分隔符加长度校验。分隔符负责切,长度负责验。
csharp复制// 按换行符切帧:先累积,遇到分隔符再切出来
private readonly System.Text.StringBuilder frameBuffer = new System.Text.StringBuilder();
private void ProcessFrame(string chunk)
{
frameBuffer.Append(chunk);
string all = frameBuffer.ToString();
int idx;
while ((idx = all.IndexOf('\n')) >= 0)
{
string oneFrame = all.Substring(0, idx).Trim();
all = all.Substring(idx + 1);
if (oneFrame.Length > 0)
{
var packet = ParsePacket(oneFrame);
if (packet != null)
{
ApplyPacket(packet);
}
}
}
// 把没切完的残帧留到下一次
frameBuffer.Clear();
frameBuffer.Append(all);
}
插件还提供了把字符串转换成 List 或 Dictionary 的能力。我在批量数据上用得比较多:设备一次性上报多个通道的值,用逗号分隔,切出来直接转成 List<float> 或者带通道名的 Dictionary<string, float>,比在业务代码里手写 Split 再 Parse 干净得多。要注意的是转换前必须确认每一项都能转成目标类型,设备端少发一个字段、多一个空格,转换就会失败,所以我在转换外面包一层校验,校验不过就整帧丢弃并记一条日志,而不是让它带着半截数据往下走。
4. 串口插件的跨平台与 TCP 模拟器:没有硬件也能联调
4.1 Windows、Mac、Android 的差异
同一套代码在三个平台上跑,逻辑可以一致,但接入细节不完全一样。我按实际踩过的差异整理成一张表,接入新平台时对着过一遍。
| 平台 | 支持的物理接口 | 接入前要确认的 | 容易出的问题 |
|---|---|---|---|
| Windows | USB、PCI、EmbeddedUART | 驱动是否装好、端口是否被占用 | 插拔后端口号变化 |
| Mac | USB | 系统是否放行设备 | 枚举比 Windows 慢一拍 |
| Android | USB(OTG)、蓝牙 SPP | USB 授权是否通过 | 拔线后回调不及时 |
Windows 上最典型的问题是端口被别的程序占用。串口是独占资源,你这边开着,调试助手那边就打不开,反之亦然。现象是打开失败但没有任何有用的错误信息,关掉另一个程序就好了。Mac 上我遇到更多的是枚举时机,设备刚插上时列表可能是空的,等一小会儿再枚举才有,所以我在启动逻辑里加了一次重试,而不是枚举一次为空就判定失败。Android 上除了前面说的授权,拔线后的状态回调也可能有延迟,UI 上不能假设「拔了立刻就知道」,得有一个超时兜底。
这些差异不涉及业务逻辑,但会直接影响你第一次接入时的判断。我的习惯是把平台相关的部分收在一个小的适配层里,业务代码只依赖「有没有连上、收到什么数据」这两个状态,换平台时只改适配层。
4.2 TCP 串口模拟器的服务器与客户端模式
手边没有硬件、或者硬件在别人手上,是开发阶段的常态。插件带了一个 TCP 串口模拟器,可以把 TCP 连接当成串口来用,支持服务器模式和客户端模式两种。这个能力在联调阶段非常省事,因为你可以先在没有设备的情况下把收发逻辑、帧切分、JSON 解析全部跑通。
两种模式的差别在于谁先发起连接。服务器模式是 Unity 这边监听一个端口,等对端连进来;客户端模式是 Unity 主动去连一个已经存在的服务。我的选择习惯是:如果是自己写一个假设备来喂数据,用服务器模式,Unity 当服务端,测试脚本当客户端连进来发数据;如果设备端本身已经有一个 TCP 转发服务,用客户端模式,Unity 去连它。
csharp复制// TCP 串口模拟器:客户端模式示意
// 用 TCP 连接代替物理串口,收发接口与真实串口保持一致
var tcpPort = SerialPortPlugin.OpenTcpSimulator(
mode: TcpSimulatorMode.Client,
host: "127.0.0.1",
port: 9000
);
if (tcpPort == null)
{
Debug.LogError("TCP 模拟器连接失败,确认对端服务已启动");
}
这段代码的价值在于,它把「连接方式」和「收发逻辑」解耦了。上层的事件订阅、帧切分、JSON 解析一行都不用改,只是把端口的来源从物理设备换成了 TCP。等硬件到位,把这一行换回真实端口就行。
但要记住一个前提:模拟器验证的是你的软件逻辑,不是硬件链路。波特率、电气特性、设备固件的时序问题,模拟器一个都测不出来。我在模拟器上跑通之后,一定会再拿真实硬件走一遍最小收发,两者都过才算完成。
4.3 蓝牙 SPP 虚拟串口怎么接
插件支持蓝牙 SPP,也就是把蓝牙连接映射成一个虚拟的串口。用法上和普通串口没有本质区别,但接入顺序有讲究:得先在系统层面完成配对,让虚拟串口出现,插件才能枚举到它。
我一般的顺序是:先在系统蓝牙设置里配对设备,确认系统里多出来一个串口设备,再启动 Unity 去枚举。反过来做,也就是先开 Unity 再配对,大概率枚举不到,得重启一次应用。这不是插件的锅,是虚拟串口的建立时机在系统侧。
另外蓝牙 SPP 的吞吐和延迟跟有线不是一个量级,帧切分的缓冲要留得宽一点,超时判定也要放宽。有线上一百毫秒能收到的心跳回复,蓝牙上偶尔要几百毫秒,如果超时设得太紧,会误判断线,触发不必要的重连。
5. 串口插件避坑排查:五类现场问题从现象到解决
5.1 编辑器正常、打包后打不开端口
现象:Editor 下收发都正常,打包到 Android 或 Mac 上,日志里只有一句「打开失败」,没有任何异常堆栈。
原因:代码里混用了 .NET 的 System.IO.Ports,或者某个第三方库间接依赖了它。桌面平台上这套 API 可用,移动平台上运行时不完整,能编译不能跑。
解决:全局搜一遍 System.IO.Ports 的引用,全部换成插件的接口。插件本身是本机代码实现的 I/O,不依赖这套 API,换过去之后三个平台的行为才一致。换完记得切平台重新编译验证,别只在 Editor 下确认。
5.2 设备拔掉后程序还在往幽灵端口发数据
现象:运行中把 USB 线拔了,程序没有报错,还在定时发送,界面上的数据停在最后一帧不动,重插之后也连不回来。
原因:只处理了数据接收,没有处理物理断开。端口对象还持有句柄,发送调用不一定立刻失败,看起来就像「还活着」。
解决:订阅插件的断开事件,收到后立刻把端口状态切到「已断开」,停掉发送定时器,执行一次关闭释放句柄,再进入重连调度。重连不要用固定间隔死循环,我一般用递增间隔,避免设备没插回来时疯狂刷日志。
5.3 JSON 解析偶发失败或解析出全 0
现象:大部分帧解析正常,偶尔抛异常,或者解析成功但字段全是默认值。
原因:串口是字节流,一帧被拆成两次回调,或者两帧粘在一次回调里。直接拿单次回调的缓冲区去反序列化,必然出问题。
解决:在协议层加帧边界,按分隔符切、按长度校验,切出完整帧再解析。切不完的残帧留在缓冲区等下一次。解析失败的那一帧直接丢弃并记日志,不要试图「修一下再用」。
5.4 蓝牙设备配对成功但枚举不到串口
现象:系统蓝牙里显示已配对,Unity 里枚举设备列表是空的。
原因:SPP 需要系统先建立虚拟串口,插件枚举的是已经存在的串口,配对成功不等于虚拟串口已就绪。
解决:先在系统里确认虚拟串口出现,再启动应用。顺序不能反。如果系统里也没有,检查配对是否真的完成,有些设备配对后还需要在系统里手动启用串口服务。
5.5 TCP 模拟器联调通过、上真机连不上
现象:用 TCP 模拟器把所有逻辑跑通了,换成真实硬件后连不上或者数据不对。
原因:模拟器验证的是软件逻辑,绕过了波特率、电气特性、固件时序这些真实链路的问题;另外模拟器的地址端口是写死的,真机环境里那套配置根本不存在。
解决:把连接配置抽出来,模拟器配置和真机配置分开存,切换时只换配置不换代码。上真机后先做最小收发验证,再跑完整业务,别一上来就压满数据。
6. 串口插件的进阶用法:把断开检测做成自愈与上线前验证
把基础收发跑通只是起点,真正决定这套东西能不能长期用的是断开之后的行为。我现在的做法是把「断开」当成一个正常状态来设计,而不是异常。
具体来说,收到断开事件后不立刻重连,而是先进一个 Lost 状态,停掉所有发送任务,释放句柄,然后按递增间隔尝试重新枚举。重新枚举时仍然按唯一 ID 匹配,不按端口号,这样设备换了个 USB 口插回来也能自动接上。重连成功后不直接恢复业务,先发一轮心跳确认链路真的通了,再切回 Running。这套状态机不复杂,但它把「拔线」「换口」「设备重启」这几种现场常见情况都覆盖了,不用每次人工重启应用。
上线前我会走一遍固定的验证清单,五项都过才算完成:
| 验证项 | 怎么验 | 不通过说明什么 |
|---|---|---|
| 唯一 ID 绑定 | 换一个 USB 口重插,看能否自动连上 | 还在按端口号匹配 |
| 物理断开 | 运行中直接拔线,看状态是否切换 | 没订阅断开事件 |
| 帧切分 | 让设备端连续快发,看解析是否稳定 | 缓冲或切帧逻辑有问题 |
| JSON 容错 | 故意发一帧缺字段的数据 | 解析失败没被兜住 |
| 跨平台 | 目标平台各跑一次最小收发 | 还有平台相关依赖没清干净 |
还有一个我后来才养成的小习惯:把所有串口相关的日志加上统一前缀,并且把「枚举到的设备列表」在启动时完整打一次。出问题时这一条日志能直接告诉你「是没认到硬件」还是「认到了但没打开」,省掉大量来回确认。
血泪经验就一句:串口这类东西,出错的地方九成不在你写的业务代码里,而在连接、切帧、断开这三件「基础设施」上。从那以后我每次接新设备,都强制先把这三件事跑通再写业务,哪怕多花半天。希望帮到你。
