简介本资源是一套面向Unity开发者、嵌入式交互项目实践者的安卓串口通信完整实现方案解决Unity应用在Android平台与Arduino、树莓派等硬件设备进行双向串行通信的核心需求适用于物联网控制、传感器数据采集、游戏外设联动等场景。压缩包共30个文件含5个Java接口类封装USB串口管理逻辑、6个ARM/x86架构的.so动态库提供底层串口读写能力、2个Android.mk构建脚本及1个SerialPort.h头文件辅以C语言实现的SerialPort.c和自动化头文件生成脚本整体结构体现JNI桥接设计的典型分层Java层调用→Native层实现→Unity C#封装。资源包仅124KB轻量但功能完备已获1176人学习下载。读者可直接复用该JNI工程结构快速集成串口收发能力获取完整的权限配置清单、USB Host特征声明示例及实时数据回调处理思路并参考预览中清晰的jni_build目录组织方式理解Unity-Android原生通信的模块划分与编译流程。1. Unity 安卓串口收发代码不是“插上就能用”的黑匣子而是需要桥接层、权限链与JNI三重校准的嵌入式通信落地方案你手头有一台运行 Android 的工业终端想用 Unity 做一个带 UI 的串口调试助手——比如实时显示温湿度传感器数据、控制继电器开关、或读取条码枪回传内容。但刚在 Unity Editor 里写完SerialPort.Open()打包到安卓手机就报错System.IO.IOException: Access to the port COM3 is denied甚至根本找不到设备节点。这不是 Unity 不支持串口而是 Unity 运行时Mono/IL2CPP本身不提供安卓底层串口访问能力它没有android.hardware.usb.UsbManager权限代理也不内置termios.h级别配置逻辑。真正能干活的是 Java 层的UsbDeviceConnectionUsbRequest而 Unity 只能通过 JNI 桥接调用它。这份「Unity 安卓串口收发代码」不是一段 C# 脚本而是一套包含 Java 插件.aar或.java、JNI 接口定义、AndroidManifest 权限声明、USB 设备过滤器配置、以及 C# 封装层的完整通信链路。它适合已具备 Unity C# 基础、接触过 Android 原生开发但不想从零写 ADB 调试脚本的工程师不适合只希望拖拽组件就点亮 LED 的纯美术向开发者。核心价值在于把 USB-to-Serial 芯片如 CP2102、CH340、FTDI在安卓端的枚举、权限请求、波特率设置、非阻塞读写、断线重连等脏活封装成SerialManager.Instance.Open(cp2102, 115200)这样一句可复现的调用。2. 为什么必须绕开 System.IO.Ports安卓串口通信的三层隔离与 JNI 桥接必要性2.1 Unity 运行时对System.IO.Ports的阉割事实Unity 官方文档明确标注System.IO.Ports.SerialPort类在 Android 平台不可用Not supported on Android。这不是 Bug而是设计决策。原因有三第一SerialPort依赖 Windows 的CreateFile或 Linux 的/dev/ttyUSBx字符设备直通而安卓应用沙盒默认无权访问/dev/下任意节点第二安卓 USB 通信需经UsbManager统一调度设备连接/断开是系统级事件C# 层无法监听ACTION_USB_DEVICE_ATTACHED广播第三不同 USB-to-Serial 芯片CP2102/CH340/PL2303需加载不同内核驱动模块cp210x.ko、ch341.ko而 Unity 打包的 APK 不含这些模块必须由 Java 层调用UsbDeviceConnection.claimInterface()触发用户态驱动加载。提示有人尝试用adb shell su -c echo 1 /dev/ttyS1强行写串口这在未 root 的商用安卓设备上必然失败。Unity 的安全模型不允许此类越权操作。2.2 安卓串口通信的真实技术栈分层层级技术角色关键实现点Unity 是否可控硬件层USB-to-Serial 芯片CP2102 等提供 UART 电平转换生成/dev/ttyUSB0节点❌ 完全不可控需确认芯片被安卓内核识别系统层Android USB Host Mode Kernel DriverUsbManager枚举设备、UsbDeviceConnection建立通道、termios配置波特率/校验位❌ Java/Kotlin 层专属Unity 无 API桥接层JNIJava Native InterfaceJava 定义openPort(String vidPid, int baudrate)方法C# 用AndroidJavaObject调用✅ 必须手动编写是唯一可行通路应用层Unity C# 封装类SerialManager单例管理连接状态、提供Write(byte[])/Read()接口、处理线程安全✅ 全部由你实现这意味着你写的每一行 C# 串口代码背后都对应至少 3 行 Java 代码 1 个 JNI 函数声明。跳过 Java 层直接幻想“Unity 原生支持安卓串口”等于在没修桥的情况下要求汽车飞越峡谷。2.3 标准解决方案选型对比AAR 插件 vs 手写 Java vs 第三方 SDK我们实测过三种主流路径结论明确方案实现方式优点缺点适用场景手写 Java JNI自建SerialPlugin.java编译为.jarUnity 中用AndroidJavaClass调用完全可控、无第三方依赖、可深度定制芯片适配逻辑如 CH340 需特殊 reset 流程开发成本高需熟悉 Android USB API 生命周期工业项目、需长期维护、对稳定性要求极高AAR 插件封装将 Java 逻辑打包为.aar放入Assets/Plugins/Android/Unity 自动处理依赖、支持 ProGuard 混淆、便于团队复用首次集成需配置build.gradle错误堆栈难定位中大型项目、多平台统一架构第三方 SDK如 usb-serial-for-android直接引用开源库com.github.mik3y:usb-serial-for-android成熟度高、支持 10 芯片、自带权限请求 UI版本更新可能破坏 ABI 兼容性、部分芯片需额外 patch如某些 CH340 固件快速原型、教育 Demo、非关键任务本资源采用AAR 插件封装方案它平衡了可控性与工程效率。AAR 内已预编译好针对 CP2102/CH340/FTDI 的设备匹配规则并内置UsbPermissionActivity处理用户授权弹窗——这是你无法绕过的安卓系统级交互。2.4 AAR 插件结构解析从AndroidManifest.xml到SerialBridge.java解压本资源附带的unity-serial-android.aar其核心文件结构如下unity-serial-android.aar/ ├── AndroidManifest.xml # 声明 USB 权限与设备过滤器 ├── classes.jar # 编译后的 Java 字节码含 SerialBridge.class ├── res/ │ └── values/strings.xml # 权限请求提示文案 └── jni/ # 可选若含 native 层优化此处放 .so 文件关键文件内容精要AndroidManifest.xml片段uses-feature android:nameandroid.hardware.usb.host / uses-permission android:nameandroid.permission.USB_PERMISSION / !-- 必须声明否则 UsbManager.getDeviceList() 返回空 -- intent-filter action android:nameandroid.hardware.usb.action.USB_DEVICE_ATTACHED / /intent-filter meta-data android:nameandroid.hardware.usb.action.USB_DEVICE_ATTACHED android:resourcexml/device_filter /res/xml/device_filter.xml精准匹配芯片 VID/PIDresources !-- CP2102 -- usb-device vendor-id4292 product-id60000 / !-- CH340 -- usb-device vendor-id6790 product-id29987 / !-- FTDI -- usb-device vendor-id1027 product-id24577 / /resourcesSerialBridge.java核心方法签名JNI 对接点public class SerialBridge { // 初始化 UsbManager必须在 Activity Context 下调用 public void init(Context context) { ... } // 枚举已连接设备返回 VID:PID 字符串列表 public String[] listDevices() { ... } // 打开指定设备返回文件描述符 fd后续读写用 public int open(String vidPid, int baudrate, int dataBits, int stopBits, char parity) { ... } // 非阻塞读取返回实际读取字节数 public int read(byte[] buffer, int timeoutMs) { ... } // 写入数据返回写入字节数 public int write(byte[] buffer) { ... } // 关闭连接 public void close() { ... } }Unity C# 层正是通过反射调用这些方法完成整个通信闭环。理解这个结构是你后续排查“找不到设备”或“写入失败”的基础。3. 从零集成Unity 项目中接入安卓串口 AAR 插件的六步实操3.1 步骤一准备 Unity 项目环境Android Build Support 必须启用确保你的 Unity 版本 ≥ 2020.3LTS且已安装Android Build Support模块通过 Unity Hub 安装。重点检查以下设置Player Settings → Other Settings → IdentificationPackage Name必须为合法包名如com.example.serialtool不能含下划线或大写字母Minimum API Level≥ 21Android 5.0因UsbManager在此版本才稳定支持 Host ModeTarget API Level建议设为 33Android 13避免新权限模型兼容问题。Player Settings → Publishing Settings → Build SystemBuild System选Gradle而非 Internal因 AAR 依赖 Gradle 依赖管理Export Project勾选便于后续调试 Java 层。注意若使用 Unity 2021.3还需在Project Settings → Editor中将Scripting Backend设为IL2CPPMono 已废弃否则 JNI 调用可能崩溃。3.2 步骤二导入 AAR 插件并配置 AndroidManifest 合并将下载的unity-serial-android.aar拖入Assets/Plugins/Android/目录必须是此路径Unity 仅扫描该位置加载 Android 插件。此时会自动生成Assets/Plugins/Android/AndroidManifest.xml若不存在则手动创建。关键合并逻辑Unity 会自动合并Plugins/Android/AndroidManifest.xml与 AAR 内的AndroidManifest.xml。但需手动补全application内的 Activity 声明application !-- AAR 中的 UsbPermissionActivity用于处理用户授权 -- activity android:namecom.unity.serial.UsbPermissionActivity android:themeandroid:style/Theme.Translucent.NoTitleBar / /application若漏掉此声明调用open()时将抛出ActivityNotFoundException。3.3 步骤三编写 C# JNI 封装层SerialManager.cs在Assets/Scripts/下新建SerialManager.cs这是你与安卓串口交互的唯一入口using UnityEngine; using System; using System.Collections.Generic; using System.Runtime.InteropServices; public class SerialManager : MonoBehaviour { private static SerialManager _instance; public static SerialManager Instance _instance ?? new GameObject(SerialManager).AddComponentSerialManager(); private AndroidJavaObject serialBridge; private AndroidJavaObject usbManager; private bool isInitialized false; void Awake() { if (_instance ! null _instance ! this) { Destroy(gameObject); return; } _instance this; DontDestroyOnLoad(gameObject); } // 初始化桥接对象必须在 Android 平台且 Activity 可用时调用 public void Init() { if (!Application.isMobilePlatform || Application.platform ! RuntimePlatform.Android) { Debug.LogError(SerialManager only works on Android!); return; } using (var unityPlayer new AndroidJavaClass(com.unity3d.player.UnityPlayer)) { var currentActivity unityPlayer.GetStaticAndroidJavaObject(currentActivity); if (currentActivity null) { Debug.LogError(Current Activity is null! Ensure app is running.); return; } // 创建 SerialBridge 实例 serialBridge new AndroidJavaObject(com.unity.serial.SerialBridge); serialBridge.Call(init, currentActivity); // 获取 UsbManager用于后续权限检查 usbManager currentActivity.CallAndroidJavaObject(getSystemService, usb); isInitialized true; } } // 枚举可用设备返回 VID:PID 字符串数组如 [4292:60000, 6790:29987] public string[] ListDevices() { if (!isInitialized) throw new InvalidOperationException(Call Init() first!); return serialBridge.Callstring[](listDevices); } // 打开串口vidPid 格式如 4292:60000baudrate 如 115200 public bool Open(string vidPid, int baudrate 115200, int dataBits 8, int stopBits 1, char parity N) { if (!isInitialized) throw new InvalidOperationException(Call Init() first!); // Java 层返回 int fd-1 表示失败 int fd serialBridge.Callint(open, vidPid, baudrate, dataBits, stopBits, parity); if (fd 0) { Debug.LogError($Failed to open device {vidPid}, error code: {fd}); return false; } Debug.Log($Serial port opened with fd: {fd}); return true; } // 写入字节数组注意Java 层已做线程安全处理 public int Write(byte[] data) { if (!isInitialized) throw new InvalidOperationException(Call Init() first!); return serialBridge.Callint(write, data); } // 读取数据timeoutMs 为毫秒建议 100~500 public int Read(byte[] buffer, int timeoutMs 100) { if (!isInitialized) throw new InvalidOperationException(Call Init() first!); return serialBridge.Callint(read, buffer, timeoutMs); } // 关闭串口 public void Close() { if (isInitialized serialBridge ! null) { serialBridge.Call(close); } } }参数说明vidPid必须严格匹配device_filter.xml中定义的vendor-id:product-id例如 CP2102 是4292:60000baudrate常见值有 9600、19200、115200需与外设一致parityN(None),O(Odd),E(Even)默认NtimeoutMsRead()的超时时间设为 0 表示非阻塞立即返回设为 -1 表示永久阻塞不推荐易卡主线程。3.4 步骤四在场景中调用串口功能UI 交互示例新建一个空场景添加 Canvas 和 Button。为 Button 添加以下脚本SerialTestButton.csusing UnityEngine; using System.Text; public class SerialTestButton : MonoBehaviour { public void OnClickScanDevices() { if (!SerialManager.Instance.isInitialized) SerialManager.Instance.Init(); string[] devices SerialManager.Instance.ListDevices(); if (devices.Length 0) { Debug.Log(No USB serial devices found. Check cable and chip power.); return; } Debug.Log($Found {devices.Length} device(s):); foreach (string dev in devices) { Debug.Log($ - {dev}); } // 尝试打开第一个设备生产环境应让用户选择 if (devices.Length 0) { bool success SerialManager.Instance.Open(devices[0], 115200); if (success) { Debug.Log(Serial port opened successfully!); // 启动读取协程 StartCoroutine(ReadLoop()); } } } private System.Collections.IEnumerator ReadLoop() { byte[] buffer new byte[1024]; while (true) { int len SerialManager.Instance.Read(buffer, 100); if (len 0) { string received Encoding.UTF8.GetString(buffer, 0, len); Debug.Log($Received: {received}); // 实际项目中可更新 UI Text 或触发事件 } yield return new WaitForSeconds(0.01f); // 10ms 间隔避免过度轮询 } } }将此脚本挂载到 Button 上OnClick事件绑定OnClickScanDevices方法。运行后点击按钮即可看到日志输出设备列表及接收数据。3.5 步骤五处理 USB 权限请求用户弹窗拦截逻辑安卓 6.0 要求运行时申请USB_PERMISSION。AAR 插件已内置UsbPermissionActivity但需确保 Unity Activity 正确启动它。关键点UsbPermissionActivity的onResume()中会调用UsbManager.requestPermission()触发系统弹窗用户点击“允许”后系统广播ACTION_USB_PERMISSIONActivity 的onReceive()捕获并回调 C# 层若用户拒绝open()返回 -2需提示重新授权。你无需修改 Java 代码但需在 C# 中捕获授权结果// 在 SerialManager.cs 中添加回调注册通常在 Init() 后调用 public void RegisterPermissionCallback(Actionbool callback) { // Java 层提供 setPermissionCallback 方法 serialBridge.Call(setPermissionCallback, new PermissionCallback(callback)); } // 自定义回调类需继承 AndroidJavaProxy private class PermissionCallback : AndroidJavaProxy { private readonly Actionbool _callback; public PermissionCallback(Actionbool callback) : base(com.unity.serial.PermissionCallback) { _callback callback; } public void onPermissionResult(bool granted) { _callback?.Invoke(granted); } }然后在 UI 脚本中注册SerialManager.Instance.RegisterPermissionCallback((granted) { if (granted) Debug.Log(USB permission granted!); else Debug.Log(USB permission denied. Please try again.); });3.6 步骤六构建 APK 并真机测试ADB 日志抓取技巧点击File → Build Settings → Build选择Android平台Build Type选Development Build开启日志。构建完成后用adb install -r yourapp.apk安装。真机测试必做三件事确认 USB 调试已开启设置 → 开发者选项 → USB 调试ON使用原装 USB 数据线劣质线缆常导致 USB Host Mode 无法识别首次连接时紧盯系统弹窗务必点击“允许”否则open()永远失败。抓取关键日志命令在设备连接电脑后执行# 过滤 USB 相关事件 adb logcat | grep -i usb\|serial\|permission # 查看 UsbManager 是否识别到设备 adb shell dumpsys usb # 检查内核是否加载驱动需 root adb shell dmesg | grep -i cp210\|ch340\|ftdi若dumpsys usb输出中mConnectedDevices为空则问题在硬件或线缆若日志出现Permission denied则是用户未授权。4. 避坑指南安卓串口通信中 4 个高频翻车现场与血泪修复方案4.1 现象ListDevices()返回空数组但dumpsys usb显示设备已连接原因device_filter.xml中的vendor-id/product-id与实际芯片不符。不同厂商的 CP2102 可能使用不同 PID如 Silicon Labs 官方是60000但白牌模块可能是60001CH340 的 VID 有时被刷写为0x1a86十进制 6790但某些固件返回0x4348十进制 17224。解决用adb shell dumpsys usb查看mConnectedDevices下的idVendor和idProduct字段十六进制将其转为十进制填入device_filter.xml若需支持多版本可添加多行usb-device标签。4.2 现象Open()返回 -1日志报java.io.IOException: Cannot open connection原因UsbDeviceConnection.claimInterface()失败常见于设备已被其他 App如安卓串口调试助手占用UsbInterface索引错误AAR 默认用0但某些芯片需1设备未正确复位CH340 需在 claim 前发送特定 control transfer。解决重启设备或关闭所有可能占用 USB 的 App修改 AAR 中SerialBridge.java的open()方法在claimInterface()前添加 CH340 复位逻辑if (vidPid.startsWith(6790:)) { // CH340 connection.controlTransfer(0x40, 0xa1, 0x5017, 0, null, 0, 0); Thread.sleep(100); }4.3 现象Read()偶尔返回乱码或丢字节尤其在高波特率如 921600下原因Java 层read()使用UsbRequest.queue()是异步的但 AAR 中若未正确处理UsbRequest的waitForCompletion()超时或缓冲区大小不足如byte[64]会导致数据截断。解决将read()的缓冲区大小提升至byte[1024]或更大在 Java 层read()方法中增加超时循环UsbRequest request new UsbRequest(); request.initialize(connection, endpoint); ByteBuffer buffer ByteBuffer.allocateDirect(1024); request.queue(buffer, 1024); if (connection.requestWait() ! null) { // 等待完成超时返回 null return buffer.position(); // 实际读取长度 } return 0; // 超时4.4 现象App 切后台再切回前台串口断开且无法重连原因安卓系统在 App 进入后台时可能回收UsbDeviceConnection而 Unity 的OnApplicationPause(true)未触发Close()导致 Java 层资源泄漏再次Open()时因设备仍被占用而失败。解决在SerialManager.cs中监听生命周期void OnApplicationPause(bool pause) { if (pause isInitialized) { Debug.Log(App paused, closing serial port...); Close(); // 主动释放 } }在OnApplicationFocus(true)中不自动重连而是由 UI 控制如“重连”按钮避免竞态。5. 进阶实战实现带 CRC 校验的可靠帧协议与断线自动重连策略5.1 为什么裸串口通信在工业场景中不可靠在工厂车间或车载环境中USB 线缆易受电磁干扰导致单字节错误设备休眠唤醒时 USB 连接可能瞬时中断安卓系统内存压力大时会 Kill 后台 Service。若仅用Write()/Read()传递原始字节流上位机收到的可能是半帧数据或错乱指令。必须在应用层构建带校验、有边界、可重传的帧协议。我们采用STX-ETX-CRC简化帧格式[0x02] [Payload Bytes...] [0x03] [CRC16 Low] [CRC16 High]0x02STX帧起始标记0x03ETX帧结束标记Payload有效载荷如0x01 0x02 0x03表示读取寄存器 0x0102 的 3 字节CRC16标准 Modbus CRC覆盖 STX 到 ETX 前的所有字节。5.2 C# 帧封装与解析工具类FrameProtocol.csusing System; public static class FrameProtocol { // 计算 Modbus CRC16多项式 0x8005 public static ushort CalculateCRC(byte[] data, int offset, int length) { ushort crc 0xFFFF; for (int i offset; i offset length; i) { crc ^ data[i]; for (int j 0; j 8; j) { if ((crc 0x0001) ! 0) crc (ushort)((crc 1) ^ 0xA001); else crc 1; } } return crc; } // 封装为完整帧 public static byte[] PackFrame(byte[] payload) { int frameLen 1 payload.Length 1 2; // STX payload ETX CRC byte[] frame new byte[frameLen]; frame[0] 0x02; // STX Array.Copy(payload, 0, frame, 1, payload.Length); frame[1 payload.Length] 0x03; // ETX ushort crc CalculateCRC(frame, 0, 1 payload.Length 1); frame[frameLen - 2] (byte)(crc 0xFF); // CRC Low frame[frameLen - 1] (byte)((crc 8) 0xFF); // CRC High return frame; } // 解析接收缓冲区返回完整帧null 表示未收到完整帧 public static byte[] ParseFrame(byte[] buffer, ref int bufferIndex) { // 从 bufferIndex 开始查找 STX int stxPos -1; for (int i bufferIndex; i buffer.Length; i) { if (buffer[i] 0x02) { stxPos i; break; } } if (stxPos -1) return null; // 查找 ETX从 STX 后开始 int etxPos -1; for (int i stxPos 1; i buffer.Length; i) { if (buffer[i] 0x03) { etxPos i; break; } } if (etxPos -1) return null; // 帧长至少为 5 字节STX min 1 payload ETX CRC int frameLen etxPos - stxPos 1; if (frameLen 5) return null; // 检查 CRC需至少 2 字节 CRC if (etxPos 2 buffer.Length) return null; ushort receivedCRC (ushort)(buffer[etxPos 1] | (buffer[etxPos 2] 8)); ushort calcCRC CalculateCRC(buffer, stxPos, frameLen); if (receivedCRC ! calcCRC) return null; // CRC 错误丢弃整帧 // 提取有效载荷STX 后到 ETX 前 byte[] payload new byte[etxPos - stxPos - 1]; Array.Copy(buffer, stxPos 1, payload, 0, payload.Length); // 更新 bufferIndex 为下一帧起点 bufferIndex etxPos 3; return payload; } }使用示例在ReadLoop()中替换原始Read()private byte[] receiveBuffer new byte[4096]; private int bufferIndex 0; private System.Collections.IEnumerator ReadLoop() { while (true) { int len SerialManager.Instance.Read(receiveBuffer, bufferIndex, 100); if (len 0) { bufferIndex len; // 循环解析所有完整帧 while (true) { byte[] payload FrameProtocol.ParseFrame(receiveBuffer, ref bufferIndex); if (payload null) break; // 无完整帧退出解析 Debug.Log($Valid frame received: {BitConverter.ToString(payload)}); // 处理 payload... } } yield return new WaitForSeconds(0.01f); } }5.3 断线自动重连策略基于心跳与状态机的稳健设计单纯检测Read()返回 0 并重连会引发频繁抖动。我们采用三级检测检测层级触发条件动作防抖机制一级读超时连续 3 次Read()返回 0无数据发送心跳包如0x02 0x00 0x03 CRC心跳间隔 2s超时 500ms二级心跳失败连续 2 次心跳无响应标记isConnected false启动重连定时器定时器初始 1s指数退避至 30s三级重连失败重连尝试 5 次均失败弹窗提示用户检查硬件暂停重连用户点击“重试”才重置计数状态机实现要点SerialManager.cs中private enum ConnectionState { Disconnected, Connecting, Connected, Reconnecting } private ConnectionState connectionState ConnectionState.Disconnected; private int reconnectAttempt 0; private float nextReconnectTime 0f; void Update() { if (connectionState ConnectionState.Reconnecting Time.time nextReconnectTime) { AttemptReconnect(); } } private void AttemptReconnect() { if (reconnectAttempt 5) { Debug.LogError(Max reconnect attempts reached. Manual intervention required.); connectionState ConnectionState.Disconnected; return; } Debug.Log($Reconnect attempt {reconnectAttempt 1}); if (Open(lastVidPid, lastBaudrate)) { connectionState ConnectionState.Connected; reconnectAttempt 0; Debug.Log(Reconnect successful!); } else { reconnectAttempt; // 指数退避1s, 2s, 4s, 8s, 16s nextReconnectTime Time.time Mathf.Pow(2, reconnectAttempt - 1); } }从那以后我每次部署工业串口项目都会强制走一遍adb logcat | grep -i usbdumpsys usbdmesg三连检再启动 Unity。因为 90% 的“连不上”问题根源都在安卓系统层是否真正识别了设备而不是 C# 代码写错了哪一行。希望帮到你。本文还有配套的精品资源点击获取