Unity安卓串口通信实战：JNI桥接、设备扫描与避坑指南

简介：Unity安卓串口收发代码是一份面向Unity开发者的原生串口通信实现，解决Unity应用与Arduino、传感器等硬件设备的数据交互问题。资源包内含基于JNI的Java层串口封装、C/C++本地接口以及用于编译so库的Android.mk构建脚本，可直接接入Unity C#脚本，简化安卓平台串口打开、读写与权限处理流程。包内共30个文件，以so动态库、java源码、c/h源码及mk构建配置为主，同时保留svn版本记录，整体压缩包仅124KB，轻量易部署。已有1172人学习下载，适合具备基础Unity开发经验、希望绕过现成付费插件自行实现硬件通信的开发者。通过本资源可掌握Unity调用安卓底层串口的关键链路，理解JNI桥接、串口初始化、数据收发及AndroidManifest权限配置等核心细节，为后续扩展智能硬件交互功能提供可复用模板。

1. Unity安卓串口：一张串口线让Unity变身硬件的上位机

你拿Unity做了套可视化调试界面，打包成APK装到一台安卓工业屏上，结果要对接的硬件不是网口、不是蓝牙，就是一根老式USB转串口线。这时候才发现，Unity不会自己发现串口，它得靠安卓系统去打开设备节点，再跨语言把字节流递给你。本篇文章拆的就是这样一套Unity安卓串口收发代码，从C#怎么调用Java层、怎么拿到并打开串口设备，到独立线程读数据、回调抛给Unity主线程，一路讲到底层链路。适合做Unity工业上位机、机器人控制台、物联网调试面板的开发者，读完你可以把这份代码直接跑起来，再改成自己的协议帧。

2. 技术选型与架构：Unity为什么绕不开JNI桥这一次

2.1 为什么System.IO.Ports.SerialPort在安卓上不可用

很多从Windows开发切过来的人第一反应是：C#自带的System.IO.Ports.SerialPort不是能直接用吗？在Windows平台确实能直接打开COM口，但安卓不是Windows，Unity的Mono运行时在安卓上不会给你映射一堆COM接口。安卓下操作串口的唯一正统路径是访问Linux内核暴露的设备节点，也就是/dev/ttyS0、/dev/ttyMT1这一类的文件路径，读写本质上是对文件描述符做流操作，这个能力Unity没有开放给C#层。

这时候就轮到AndroidJavaClass和AndroidJavaObject出马了。Unity提供了一套从C#侧调用Java代码的桥接API，你可以通过它拿到UnityPlayer的当前Context，调用Java层封装好的串口工具类，打开指定设备节点，拿到InputStream和OutputStream，再把字节流传回C#。整条链路就是一条JNI桥：C# → Java → native层 -> Linux内核。

开头做项目结构设计时，我建议把桥接层当成独立模块来写，不要跟业务混在一起。桥接层的职责只有三件事：找到设备节点、打开串口、传输字节流。至于协议解析、UI刷新、数据存储，全部留在C#侧。这样做的直接好处是，将来要换成蓝牙或Socket通信，你只需要替换这个桥接层，业务代码一行都不用动。

2.2 通信选型对比：串口、蓝牙、Socket各自的适用边界

做硬件联调之前，先要判断设备到底该走哪种通道。串口不是效率最高的选择，它受波特率限制，9600波特率下每秒也就传不到1K字节，远不如4G模块的Socket带宽。但串口是工业现场最常见的存量接口，很多传感器、PLC、单片机控制板出厂就只引出一根UART，你没有选择空间。

如果设备同时支持串口和以太网，我在实际项目中更倾向于以太网，因为Unity的System.Net.Socket是完整可用的，不用碰任何安卓底层。但现实是，大量5V串口传感器、老式工控板只有UART输出，那就得老老实实走串口桥。

2.3 项目目录结构：桥接层和业务层如何划分

拆这份代码时，我习惯先把目录结构打印出来看，因为工程的组织方式直接反映设计意图。一个干净的Unity安卓串口工程应该长这样：

Assets/ ├── Plugins/ │ └── Android/ │ ├── AndroidManifest.xml │ └── serial-port-library/ # Java串口库与so库 ├── Scripts/ │ ├── Bridge/ │ │ └── SerialPortBridge.cs # C#侧桥接管理 │ ├── Core/ │ │ ├── SerialConfig.cs # 串口参数配置对象 │ │ ├── SerialDataReader.cs # 串口读取线程封装 │ │ └── SerialEventDispatcher.cs # 主线程事件分发 │ └── UI/ │ └── SerialConsoleView.cs # 调试面板 └── Scenes/ └── SerialTestScene.unity

这里最关键的是Assets/Plugins/Android目录。Unity打包安卓时会把这个目录下的内容合并进最终APK的目录结构中，所以Java源码、AndroidManifest.xml、so库都放在这里。我自己习惯把串口库的Java源代码直接丢在这个目录里，而不是给jar包，因为遇到设备节点扫描、流控参数这类需要改源码的场景，直接能改到。

SerialPortBridge.cs暴露给业务层的接口就四个：Open、Close、Send、RegisterReceiver。不暴露设备路径、不暴露字节流缓冲区的细节，所有设备连接状态通过事件向上通知。业务层看到的是一个抽象串口对象，底层是JNI桥还是蓝牙通道都无所谓。

3. 核心模块拆解：一个串口请求从发送到回调的完整链路

3.1 C#桥接层：用AndroidJavaClass打开设备节点

首先要明确，C#侧不能直接new一个Java串口对象再随便调用，所有跨语言调用都必须通过AndroidJavaObject包装。拿到当前UnityActivity的Context是第一步，因为Java层打开设备节点时需要用到安卓应用的上下文信息判断权限状态。

using UnityEngine; using System; public class SerialPortBridge { private AndroidJavaObject serialHelper; private AndroidJavaObject context; public bool Open(SerialConfig config) { // 获取Unity当前Activity，用于后续Java调用 using (AndroidJavaClass unityPlayer = new AndroidJavaClass("com.unity3d.player.UnityPlayer")) { context = unityPlayer.GetStatic<AndroidJavaObject>("currentActivity"); } // 创建Java层串口工具实例 using (AndroidJavaClass helperClass = new AndroidJavaClass("com.example.serial.SerialPortHelper")) { serialHelper = helperClass.CallStatic<AndroidJavaObject>( "getInstance", context, config.DevicePath, config.BaudRate ); if (serialHelper == null) return false; } return serialHelper.Call<bool>("isOpen"); } public void Close() { if (serialHelper != null) { serialHelper.Call("close"); serialHelper.Dispose(); serialHelper = null; } } public int Send(byte[] data) { if (serialHelper == null) return -1; return serialHelper.Call<int>("write", data); } }

这段代码里有几个容易翻车的点。第一，AndroidJavaObject需要持有长生命周期引用，千万不能在Open方法里用using包住然后释放掉，否则Java层对象被Unity侧GC回收，底层文件描述符也会跟着关闭。第二，CallStatic方法可以直接调用Java类的静态工厂方法，不用先new一个实例，用这种方式拿到单例对象最稳妥。第三，发送数据我直接传byte[]，Java层会把它当成字节数组参数处理，不需要做任何marshal操作。

3.2 Java侧封装：从设备节点到输入输出流

Java层是整个串口链路的枢轴，它负责调用底层native方法打开设备节点，然后向上层提供输入输出流。注意这个设备节点不是随便打开的，非root的普通应用直接open /dev/ttyS1会报Permission denied，常见解决路径是使用USB转串口设备，或者把应用签名成系统应用。

package com.example.serial; import android.content.Context; import java.io.File; import java.io.FileDescriptor; import java.io.FileInputStream; import java.io.FileOutputStream; import java.io.IOException; public class SerialPortHelper { private static SerialPortHelper instance = null; private FileDescriptor descriptor; private FileInputStream inputStream; private FileOutputStream outputStream; private boolean open = false; static { System.loadLibrary("serial_port"); } private native FileDescriptor nativeOpen(String path, int baudrate, int flags); private native void nativeClose(FileDescriptor fd); public static SerialPortHelper getInstance(Context ctx, String path, int baudrate) { if (instance == null) { instance = new SerialPortHelper(ctx, path, baudrate); } return instance; } private SerialPortHelper(Context ctx, String path, int baudrate) { try { descriptor = nativeOpen(path, baudrate, 0); if (descriptor == null) { throw new IOException("nativeOpen returned null, path: " + path); } inputStream = new FileInputStream(descriptor); outputStream = new FileOutputStream(descriptor); open = true; } catch (IOException e) { open = false; } } public int write(byte[] data) { if (!open || outputStream == null) return -1; try { outputStream.write(data); outputStream.flush(); return data.length; } catch (IOException e) { return -1; } } public FileInputStream getInputStream() { return inputStream; } public boolean isOpen() { return open; } public void close() { if (!open) return; open = false; try { if (inputStream != null) inputStream.close(); if (outputStream != null) outputStream.close(); if (descriptor != null) nativeClose(descriptor); } catch (IOException e) { // 关闭失败一般出现在设备被拔出时，忽略即可 } } }

这块的参数说明值得写一下。nativeOpen的第一个参数是设备节点路径，第二个是波特率，第三个是flags，通常传0表示默认阻塞模式。波特率直接传整数，由客户端决定，C#侧配置成9600还是115200完全由业务场景决定：GPS模块用9600，TTL电平调试用115200比较常见。值得注意的细节是FileInputStream可以直接接收一个FileDescriptor对象，这是Java标准库的能力，也是串口和普通文件读写共用的一条路径。

3.3 读取线程设计：阻塞读取加主线程分发

串口数据是持续到达的，你不可能在主线程里死等。常见设计是启动一个独立后台线程，用InputStream.read阻塞等待新字节，读到的原始数据先放入一个临时的累积缓冲区，按帧解析后通过Unity主线程事件系统抛出。

using System.Threading; using UnityEngine; public class SerialDataReader { private AndroidJavaObject serialHelper; private Thread readThread; private volatile bool running; private byte[] buffer = new byte[1024]; private Queue<byte[]> frameQueue = new Queue<byte[]>(); public void Start(AndroidJavaObject helper) { serialHelper = helper; running = true; readThread = new Thread(ReadLoop); readThread.IsBackground = true; readThread.Start(); } private void ReadLoop() { try { AndroidJavaObject inputStream = serialHelper.Call<AndroidJavaObject>("getInputStream"); while (running) { int len = inputStream.Call<int>("read", buffer); if (len > 0) { byte[] frame = new byte[len]; System.Buffer.BlockCopy(buffer, 0, frame, 0, len); lock (frameQueue) { frameQueue.Enqueue(frame); } } } } catch (System.Exception e) { Debug.LogError("串口读取异常: " + e.Message); } finally { running = false; } } public void Dispatch(Action<byte[]> onFrame) { lock (frameQueue) { while (frameQueue.Count > 0) { byte[] frame = frameQueue.Dequeue(); onFrame?.Invoke(frame); } } } }

这里的读线程用的是阻塞式read，而不是自旋轮询。Symbolically，read会一直阻塞直到有字节到达，这比while(true)+Sleep的方式效率高，CPU占用率极低。Dispatch方法要从Unity主线程的Update循环里调用，UnityAPI不能在子线程操作，所以数据到了之后只进队列不碰任何Unity对象，由主线程统一消费。参数方面，buffer大小1024字节对于常见的串口帧足够，如果是定长大数据帧可以改成4096，但不要太小，否则read返回的字节数会频繁触发多次解析。

4. 避坑指南：串口联调中五个反直觉的坑

这一节把我在实机上踩过的坑按现象到原因到解决方式的格式列出来，每条都是付过学费的。

4.1 打开设备节点报Permission denied

现象：应用启动后调用nativeOpen，直接抛IOException，日志显示open failed: EACCES (Permission denied)。

原因：安卓系统的文件权限模型对/dev/ttyS0这类内核设备节点默认只授予root用户和system组，普通第三方应用即使声明了所有权限也无法直接open。设备厂商在init.rc里定义的设备节点权限决定一切。

解决：两种方案任选。一是应用换成USB转串口硬件设备，这类设备走USB权限模型，应用可以正常申请USB权限后读写。二是把APK签名放进/system/app分区做成系统应用，同时在AndroidManifest里声明android.permission.WRITE_EXTERNAL_STORAGE。项目联调时我强烈建议先用USB转串口模式，省掉越权和签名流程的折腾。

4.2 AndroidJavaObject被GC回收导致偶发断连

现象：串口用着用着突然失联，日志无任何异常，重新Open又能恢复，且失联时间不固定。

原因：C#侧创建AndroidJavaObject后没有保存引用，或者在某次方法调用完后调用Dispose，Unity层的垃圾回收器把这些包装对象回收掉，底层Java对象和文件描述符也随之释放。

解决：把serialHelper和inputStream的引用提升为成员字段持有，绝不Dispose，除非主动关闭串口。在C#层面，AndroidJavaObject是一个包装句柄，对它的生命周期管理要跟对真实串口一样认真，每次用了就丢等于每次用完就拔线。

4.3 读线程CPU占用率飙到100%

现象：打开串口后整机发烫，查看CPU占用发现进程持续占满一个核心。

原因：读线程没有使用阻塞读取，而是用while(true)不断调available再read拼数据，available返回0时空转循环。Unity子线程优先级默认是Normal，空转时毫无阻塞机制。

解决：改用InputStream.read(buffer)阻塞读取，数据没到就让线程挂起，内核在数据到达时唤醒。这样读线程空闲时间几乎不消耗CPU，实测CPU占用率能压到0.5%以下。

4.4 串口数据末尾总是多出\r\n

现象：设备发来的十六进制帧末尾凭空多出两个字节0x0D 0x0A，导致帧校验失败。

原因：很多下位机固件串口打印用了print或者println函数，println在末尾自动追加了回车换行。也有的是调试信息混淆进了数据帧，打印日志同样走串口。

解决：处理数据时先按帧头帧尾做切片，不要把整包读到的原始字节当完整帧。常见做法是维护累加缓冲区，等凑齐帧头+长度字段+帧尾才抛给上层解析，多余的行只需要在协议层剥离。

4.5 同一份代码在A板上能用，在B板上设备路径变了

现象：开发板A上配/dev/ttyS1跑得好好的，换到开发板B或者某个工控屏上就打不开了，日志提示No such file or directory。

原因：不同厂商的内核设备映射差异很大，有的平台把串口映射成ttyS0，有的映射成ttyMT0或者ttyUSB0，USB转串口插入顺序不同还会让节点名漂移。

解决：把设备路径抽到配置项，做一次启动时的可用设备扫描，遍历/dev/tty和/dev/ttyUSB下所有节点，逐个尝试打开。这份代码界面里留一个设备节点下拉框，启动时自动扫描填充，比写死路径可靠得多，也算是个玄学问题用工程手段解决。

5. 构建与验证：从Unity工程到安卓真机联调的完整流程

5.1 Unity构建安卓APK的配置细节

Unity对安卓打包支持很成熟，但串口工程有几个不能省的前提配置。打开Project Settings里的Player设置，Other Settings下的Api Compatibility Level必须选.NET Standard 2.1或者ARMv7、ARM64都勾上。脚本后台值保持默认，不用改成IL2CPP，Mono和IL2CPP在这份代码上都能跑，区别不大。

关键是Assets/Plugins/Android/AndroidManifest.xml。Unity默认生成的Manifest不会给你添加USB权限和串口设备权限声明，需要手动加。基础权限声明一般长这样：

<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.yourcompany.serialtest"> <uses-feature android:name="android.hardware.usb.host" /> <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" /> <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" /> <application> <activity android:name="com.unity3d.player.UnityPlayerActivity"> <intent-filter> <action android:name="android.intent.action.MAIN" /> <category android:name="android.intent.category.LAUNCHER" /> </intent-filter> </activity> <meta-data android:name="unityplayer.UnityActivity" android:value="true" /> </application> </manifest>

uses-feature声明usb.host是让设备告诉安卓系统你的APK需要USB宿主能力。挂载USB转串口时系统会弹授权对话框，这时候Application的Activity需要处理onNewIntent回调，Java侧在UnityPlayerActivity里重写这个方法授予USB设备权限。

构建时把USB OTG线插上安卓设备，Build And Run可以直接部署。敲一下打包命令也行：

/path/to/Unity -batchmode -buildTarget Android -projectPath ./SerialDemo -executeMethod BuildScript.BuildApk -quit

5.2 真机联调：从打开串口到收到第一包数据

APK装好后，连接硬件前先在Unity界面的设备下拉框里看看扫描结果，确认识别到了ttyUSB0或ttyS1。选好波特率后点打开，四个状态码要逐项确认：Java层isOpen返回true、inputStream创建成功、读线程running为true、帧回调有事件触发。

如果这四个状态没全绿，对照上一节的避坑清单排查。我常用的排查思路是先拿到设备节点路径，用adb shell ls -l /dev/ttyS*看看权限位是不是crw-rw----，再确认当前应用跑在哪个uid下，权限问题当场暴露。

收到第一包数据后，建议立刻做一次回环测试：用一根杜邦线把串口的TXD和RXD短接，发送端发出的字节会原样回到接收端。如果回环正常而接外部设备乱码，那就是波特率或电平不匹配的问题，跟代码无关了。

5.3 模拟数据源：没有硬件也能开发调试

还有一个没硬件时逼疯开发者的场景，有套简单办法：写一个模拟串口脚本，用Linux的伪终端pty生成一对虚拟设备，App打开master端，脚本往slave端写数据。

socat -d -d pty,raw,echo=0 pty,raw,echo=0

socat会输出两个设备路径，比如/dev/pts/3和/dev/pts/4。把开发板或USB转串口指向其中一个路径用脚本写入，Unity端打开另一个路径就能调试收数据逻辑，非常实用。实测拿模拟源调试协议解析和UI更新，跟真机效果没什么差别。

6. 二次开发：把收发Demo改成能用的协议层

手里有了稳定的串口收发通道，摆在面前的下一个问题就是怎么把裸字节流变成业务数据。如果直接按整包收发，不同长度的帧会粘在一起，握手协议、校验逻辑都没地方写。这一步我会先上一层心跳帧协议，再谈多设备管理。

6.1 自定义帧协议：从裸字节到结构化消息

做协议层的时候，我会在数据外层加一个最简帧头结构：帧头、长度、命令字、数据体、CRC校验。这样收端就能按长度字段切帧，粘包和半包都在这一层解决。

public class FrameProtocol { private List<byte> buffer = new List<byte>(); public void Push(byte[] data) { buffer.AddRange(data); // 按长度字段循环切帧，直到剩余数据不够一帧 while (buffer.Count >= 6) { if (buffer[0] != 0xAA || buffer[1] != 0x55) { buffer.RemoveAt(0); continue; } int len = buffer[2]; if (buffer.Count < len + 5) break; if (Crc16(buffer, 0, len + 3) != (ushort)(buffer[len + 3] | buffer[len + 4] << 8)) { buffer.RemoveRange(0, len + 4); continue; } byte[] frame = buffer.GetRange(0, len + 5).ToArray(); buffer.RemoveRange(0, len + 5); // 解析出命令字和payload，投递给业务层 } } private ushort Crc16(byte[] data, int offset, int length) { // 标准CRC16算法实现 ushort crc = 0xFFFF; for (int i = offset; i < offset + length; i++) { crc ^= data[i]; for (int bit = 0; bit < 8; bit++) { if ((crc & 0x0001) != 0) crc = (ushort)((crc >> 1) ^ 0xA001); else crc >>= 1; } } return crc; } }

这个实现的切帧逻辑很直接：遍历缓冲区找帧头，取出长度字段算出一帧完整长度，校验CRC通过后整帧抛出，否则继续往后找。参数上，帧头选用AA 55是为了避开纯文本传感器可能输出的连续ASCII字节，两个字节连续出现才认作帧头。

同一份数据里如果有多个串口设备在汇报，就在命令字里带上设备地址，这样帧协议天然就支持一主多从的轮询模型。这类帧结构在旁人看来毫不起眼，但在工业场景能兜住九成通信问题。

6.2 多串口并发管理的改造思路

如果项目要同时接两块传感器板子，最容易踩的坑是干脆开两份SerialPortBridge然后忘了哪个设备回调对应哪个事件。我会先把设备抽象成SerialDevice类，每个设备实例内聚自己的桥接、读线程、协议解析和错误计数。

主控用Dictionary<string, SerialDevice>按设备名管理，比如"gps"对应/dev/ttyUSB0，"imu"对应/dev/ttyUSB1。业务层发命令时按设备名找到实例，收数据时一眼就能从回调参数里看到是哪个设备来的。这套改造做完，加第三块板子只需要加一行配置，不用改任何业务逻辑。

串口这种老技术，看着土，但在成本敏感的项目里它就是能干活。让我记起教训最深的一次，是在联调那天把波特率配错，设置了9600但下位机实际跑115200，界面上看一切正常就是数据乱码，折腾半天才想起来核对波特率。从那以后我每次搭串口工程都强制把波特率、设备路径、校验位三项在启动时打印出来跟设备手册逐条核对，才敢说进入联调。串口的坑大多不是难，而是细。希望这篇拆解能帮你在项目的硬骨头里少试几轮错。

本文还有配套的精品资源，点击获取