戰(zhàn)：USB Host橋接實(shí)現(xiàn)手機(jī)直連單片機(jī))
簡介一份面向 Unity 開發(fā)者的安卓串口收發(fā)代碼包用于解決 Unity 應(yīng)用與 Arduino、樹莓派等外部硬件設(shè)備的數(shù)據(jù)交互問題。壓縮包共 30 個(gè)文件大小約 124KB包含 JNI 橋接相關(guān)的 C/C 源文件.c/.h、Android.mk/Application.mk 構(gòu)建配置、Java 串口接口封裝、多架構(gòu) .so 動(dòng)態(tài)庫及 SVN 元數(shù)據(jù)等。通過閱讀源碼可了解 JNI 層如何封裝打開、關(guān)閉、發(fā)送與接收串口數(shù)據(jù)的邏輯并查看 armeabi-v7a、armeabi、x86 三種 CPU 架構(gòu)的庫文件便于在真機(jī)調(diào)試時(shí)替換對應(yīng) so 庫對于有一定 Android 原生基礎(chǔ)、想擺脫現(xiàn)成插件限制的 Unity 開發(fā)者是可直接參考的實(shí)現(xiàn)樣本。已有 1172 人學(xué)習(xí)下載適合作為復(fù)刻串口收發(fā)功能的起點(diǎn)。1. 一條手機(jī)直連單片機(jī)的數(shù)據(jù)鏈路Unity做界面安卓原生USB口負(fù)責(zé)收發(fā)有一次接產(chǎn)線數(shù)據(jù)采集面板的活兒甲方拿了一臺(tái)現(xiàn)場安卓平板要求直接插USB轉(zhuǎn)串口線讀取下方RS485傳感器數(shù)據(jù)同時(shí)在一套Unity做的三維工控界面里實(shí)時(shí)刷新數(shù)值。大部分人聽到“Unity串口”第一反應(yīng)是用C#的System.IO.Ports但這個(gè)庫在安卓上直接失效連打開設(shè)備都會(huì)拋異常原因在于安卓的串口權(quán)限模型和Windows差了一個(gè)時(shí)代。這篇文章拆一套能跑起來的Unity安卓串口收發(fā)方案核心思路是把底層USB串口讀寫交給安卓原生層C#通過AndroidJavaObject橋接調(diào)用Unity只負(fù)責(zé)協(xié)議解析和UI渲染。適合在Unity里做設(shè)備上位機(jī)、需要手機(jī)直連單片機(jī)或傳感器的開發(fā)者讀完照著配權(quán)限、寫代碼基本能在幾分鐘內(nèi)跑通數(shù)據(jù)回路。2. 技術(shù)選型拆解為什么繞開C#串口API把寶押在安卓USB Host上2.1 安卓串口的三條路有兩條走不通先看現(xiàn)狀。在Windows上寫串口System.IO.Ports拿過來就用打開COM3讀數(shù)據(jù)幾行代碼搞定但這個(gè)體驗(yàn)在安卓平臺(tái)上徹底失效。Unity的Mono運(yùn)行時(shí)在安卓上沒有串口設(shè)備文件的訪問權(quán)限SerialPort類實(shí)際調(diào)用會(huì)直接失敗或者打開后沒有任何數(shù)據(jù)返回。原因是安卓應(yīng)用層的設(shè)備訪問受SELinux和權(quán)限模型雙重控制工廠設(shè)備里常見的/dev/ttyS0、/dev/ttyMTK節(jié)點(diǎn)普通應(yīng)用連列目錄的權(quán)限都沒有。第二條路是直接用FileStream讀/dev/ttyS*設(shè)備節(jié)點(diǎn)這也是很多老項(xiàng)目在網(wǎng)上流傳的做法。這個(gè)方案依賴root權(quán)限需要把App裝在root過的設(shè)備上再在授權(quán)下執(zhí)行chmod 666。實(shí)際跑起來會(huì)發(fā)現(xiàn)另一個(gè)問題不同SOC平臺(tái)的tty節(jié)點(diǎn)命名完全不同高通平臺(tái)叫ttyHS聯(lián)發(fā)科部分平臺(tái)叫ttyMT展銳的節(jié)點(diǎn)又是另一套。今天能在這臺(tái)機(jī)器跑通的代碼換一批設(shè)備就全滅維護(hù)成本高到失控。所以真正可復(fù)現(xiàn)的路徑只剩第三條USB Host外接串口轉(zhuǎn)接芯片。安卓手機(jī)和平板普遍支持OTG系統(tǒng)把外接的CH340、FT232、CP210x這類轉(zhuǎn)接芯片枚舉成USB設(shè)備應(yīng)用層通過UsbManager獲得設(shè)備句柄。這里不像PC那樣由內(nèi)核自動(dòng)加載串口驅(qū)動(dòng)安卓不會(huì)把USB轉(zhuǎn)串口芯片變成/dev/ttyUSB0需要開發(fā)者在應(yīng)用層實(shí)現(xiàn)對應(yīng)芯片的協(xié)議。繞這一大圈本質(zhì)是用USB的批量傳輸端點(diǎn)模擬異步串口的收發(fā)。2.2 自寫芯片驅(qū)動(dòng)不劃算選現(xiàn)成庫省掉八成工作量USB轉(zhuǎn)串口芯片的協(xié)議并不是統(tǒng)一標(biāo)準(zhǔn)。拿市面上最常見的兩種芯片舉例CH340的控制傳輸命令和FT232的格式完全不是一回事波特率配置、流控開關(guān)、數(shù)據(jù)位設(shè)置的寄存器偏移都對不上。這意味著不借助外部庫需要拿到每顆芯片的數(shù)據(jù)手冊逐個(gè)寄存器實(shí)現(xiàn)配置命令再自己處理廠商芯片的識(shí)別邏輯。我見過有人在這個(gè)環(huán)節(jié)翻車——花兩個(gè)星期照著CH340手冊寫了一個(gè)能用的驅(qū)動(dòng)換一批FT232的轉(zhuǎn)接板控制命令全部失效又要重新讀FT232手冊。這種純應(yīng)用層開發(fā)去啃芯片協(xié)議性價(jià)比實(shí)在低。工程上推薦直接引入現(xiàn)成的USB串口開源庫它把設(shè)備枚舉、VID/PID匹配、芯片差異、波特率寄存器配置全部封裝在底層上層唯一需要關(guān)心的就是打開、讀、寫三個(gè)動(dòng)作。實(shí)際測過CH340和FT232兩種轉(zhuǎn)接板同一份代碼幾乎不用改就能切換芯片。2.3 工程目錄逐文件拆解每個(gè)文件管哪一段拿一個(gè)可運(yùn)行的Unity工程示例串口相關(guān)資源集中放在兩個(gè)目錄下Unity側(cè)的C#腳本和Android插件。Assets/ ├── Plugins/ │ └── Android/ │ ├── AndroidManifest.xml │ ├── libs/ │ │ └── usb-serial-lib.aar │ └── java/ │ └── com/devdemo/serial/ │ ├── SerialPortBridge.java │ └── SerialCallback.java ├── Scripts/ │ ├── Serial/ │ │ ├── SerialPortConfig.cs │ │ ├── SerialPortService.cs │ │ └── SerialFrame.cs │ └── Demo/ │ └── SerialDemoController.cs └── Prefabs/ └── SerialManager.prefabPlugins/Android下的AndroidManifest.xml不是Unity工程默認(rèn)那個(gè)而是構(gòu)建APK時(shí)給安卓打包用的合并清單負(fù)責(zé)聲明USB Host特性、權(quán)限過濾規(guī)則把USB設(shè)備枚舉的Intent-Filter掛到主Activity上。libs目錄放串口庫的aarjava目錄放我們自己的橋接類SerialPortBridge和回調(diào)接口SerialCallback。Scripts/Serial里SerialPortConfig.cs承載當(dāng)前串口的參數(shù)集合波特率、數(shù)據(jù)位、停止位、校驗(yàn)位都在這定義并通過Inspector露出SerialPortService.cs是全局唯一的串口服務(wù)入口控制打開、關(guān)閉、讀寫SerialFrame.cs是協(xié)議解析工具負(fù)責(zé)把收到的原始字節(jié)流按自定義幀格式拆解。Demo目錄掛一個(gè)演示控制器把串口事件轉(zhuǎn)發(fā)到UI顯示文本。Prefabs/SerialManager.prefab是一個(gè)內(nèi)含SerialPortService組件的空物體場景啟動(dòng)時(shí)掛上即可。這種組織方式的好處是協(xié)議、底層、UI三層隔離。后期協(xié)議從Modbus改成私有文本協(xié)議時(shí)只需要?jiǎng)覵erialFrame其余代碼基本不動(dòng)。2.4 USB通信模型底料endpoint、批量傳輸和控制傳輸串口庫封裝得再深底層還是在跟USB的endpoint打交道。UsbDevice暴露接口后需要拿到UsbDeviceConnection再找到對應(yīng)接口的In/Out兩個(gè)endpoint。endpoint就是USB設(shè)備上數(shù)據(jù)傳輸?shù)耐ǖ酪粋€(gè)負(fù)責(zé)往設(shè)備發(fā)數(shù)據(jù)一個(gè)負(fù)責(zé)收數(shù)據(jù)。批量傳輸不保證實(shí)時(shí)性但適合收發(fā)一幀一幀的串口數(shù)據(jù)?？刂苽鬏攧t用來做設(shè)備配置比如切換波特率、設(shè)置數(shù)據(jù)位、請求設(shè)備描述符都走控制端點(diǎn)。UsbSerialPort的setParameters方法內(nèi)部就是拼好控制命令發(fā)到控制端點(diǎn)再由轉(zhuǎn)接芯片改寫內(nèi)部寄存器。理解了這一層就能明白自寫芯片協(xié)議的工作量在哪里——每顆芯片的控制字格式都不同做一次就得重新折騰一遍寄存器映射。提示權(quán)限是一個(gè)繞不開的環(huán)節(jié)。UsbManager是系統(tǒng)服務(wù)App要用設(shè)備必須得到用戶授權(quán)。授權(quán)彈窗呼出后如果沒有對應(yīng)的BroadcastReceiver處理返回結(jié)果后續(xù)openDevice調(diào)用會(huì)一直失敗。這部分在下一章代碼里能看到具體落法。3. 核心模塊拆解從USB設(shè)備枚舉到串口打開的完整鏈路3.1 AndroidManifest配置讓系統(tǒng)把轉(zhuǎn)接板識(shí)別成可用USB設(shè)備Unity導(dǎo)出的APK原本帶一個(gè)自動(dòng)生成的AndroidManifest.xml里面只有Unity入口Activity。外接USB轉(zhuǎn)串口設(shè)備時(shí)需要額外聲明USB Host特性并且給Activity加上USB設(shè)備插拔的Intent-Filter否則設(shè)備插上去系統(tǒng)沒有任何反應(yīng)UsbManager.getDeviceList()拿到的列表永遠(yuǎn)是空的。?xml version1.0 encodingutf-8? manifest xmlns:androidhttp://schemas.android.com/apk/res/android uses-feature android:nameandroid.hardware.usb.host android:requiredtrue / application activity android:namecom.unity3d.player.UnityPlayerActivity 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/usb_device_filter / /activity /application /manifest這段配置做了兩件事。uses-feature聲明應(yīng)用依賴USB Host硬件系統(tǒng)在一開始就知道這個(gè)App需要OTG能力。intent-filter和meta-data組合起來把USB設(shè)備插拔事件路由到UnityPlayerActivity同時(shí)由usb_device_filter.xml文件做設(shè)備過濾。設(shè)備過濾文件通常按廠商VID和產(chǎn)品PID來放行只讓特定芯片觸發(fā)打開流程?xml version1.0 encodingutf-8? resources usb-device vendor-id6790 product-id29987 / usb-device vendor-id1027 product-id24577 / /resources這兩個(gè)ID是我實(shí)際調(diào)試中用到的分別對應(yīng)CH340和FT232兩種常見芯片的組合識(shí)別碼。不同廠商轉(zhuǎn)接板的VID/PID五花八門如果擔(dān)心漏設(shè)備也可以把過濾文件寫成空列表讓系統(tǒng)對所有USB設(shè)備廣播在Java代碼里再靠芯片協(xié)議探測來判斷是不是串口。我的習(xí)慣是過濾寫嚴(yán)一點(diǎn)只放已經(jīng)驗(yàn)證過的板子防止車間現(xiàn)場彈出些莫名其妙的權(quán)限請求干擾作業(yè)。3.2 SerialPortBridge.java設(shè)備枚舉、鑒權(quán)、連接一次說清Java側(cè)的核心類叫SerialPortBridge負(fù)責(zé)把UsbManager的系統(tǒng)服務(wù)能力包裝成Unity方便調(diào)用的接口。先看設(shè)備枚舉public class SerialPortBridge { private static final String ACTION_USB_PERMISSION com.devdemo.serial.USB_PERMISSION; private Context context; private UsbManager usbManager; private PendingIntent usbPermissionIntent; private UsbSerialPort serialPort; private UsbDeviceConnection connection; public SerialPortBridge(Context context, Activity activity) { this.context context; this.usbManager (UsbManager) context.getSystemService(Context.USB_SERVICE); this.usbPermissionIntent PendingIntent.getBroadcast( context, 0, new Intent(ACTION_USB_PERMISSION), PendingIntent.FLAG_MUTABLE); } public String[] enumDevices() { HashMapString, UsbDevice devices usbManager.getDeviceList(); ListString names new ArrayList(); for (UsbDevice device : devices.values()) { names.add(device.getDeviceName()); } return names.toArray(new String[0]); } }枚舉方法把UsbManager內(nèi)的所有USB設(shè)備名取出來返回給Unity側(cè)。一個(gè)安卓設(shè)備會(huì)掛多個(gè)USB設(shè)備比如觸控屏、鍵鼠、數(shù)據(jù)線通通都會(huì)出現(xiàn)在這里。光拿名字不夠打開前還要通過UsbSerialProber探測哪一個(gè)是能被串口芯片協(xié)議識(shí)別的設(shè)備。請求權(quán)限的代碼public void requestPermission(String deviceName) { UsbDevice device findDeviceByName(deviceName); if (device null) return; if (!usbManager.hasPermission(device)) { usbManager.requestPermission(device, usbPermissionIntent); } }這里的回調(diào)不是同步返回而是通過ACTION_USB_PERMISSION廣播回到注冊好的BroadcastReceiver。我在構(gòu)造方法里動(dòng)態(tài)注冊Receiver到應(yīng)用Context上收到允許結(jié)果后馬上執(zhí)行openDevice和UsbSerialPort初始化。不熟悉這個(gè)模式的開發(fā)者把requestPermission當(dāng)同步調(diào)用緊接著就調(diào)openDevice必然每次失敗這個(gè)坑后面避坑章節(jié)會(huì)詳細(xì)展開。打開串口的核心方法public int open(String deviceName, int baudRate) { UsbDevice device findDeviceByName(deviceName); if (!usbManager.hasPermission(device)) { return -2; } connection usbManager.openDevice(device); if (connection null) { return -3; } UsbSerialPort port UsbSerialProber .getDefaultProber() .probeDevice(connection, device); if (port null) { return -4; } serialPort port; serialPort.open(connection); serialPort.setParameters( baudRate, 8, UsbSerialPort.STOPBITS_1, UsbSerialPort.PARITY_NONE); return 0; }幾個(gè)返回值對應(yīng)不同失敗原因-2是沒授權(quán)-3是系統(tǒng)把設(shè)備占了-4是芯片協(xié)議不匹配。Unity側(cè)拿到返回值就能直接給用戶一個(gè)明確的提示文案。setParameters里的參數(shù)分別對應(yīng)波特率、數(shù)據(jù)位、停止位和校驗(yàn)位和Windows串口編程里DCB結(jié)構(gòu)體的內(nèi)容一一對應(yīng)這里配置錯(cuò)了后面讀到的數(shù)據(jù)全部是亂碼。3.3 C#側(cè)橋接Unity把調(diào)用傳到Java層的標(biāo)準(zhǔn)姿勢Unity側(cè)并不直接持有UsbManager所有安卓系統(tǒng)服務(wù)調(diào)用都必須經(jīng)過AndroidJavaObject。SerialPortService以單例形式存在構(gòu)造時(shí)同時(shí)創(chuàng)建Java橋接對象和回調(diào)代理public class SerialPortService : AndroidJavaProxy { public delegate void DataReceivedHandler(byte[] data); public event DataReceivedHandler DataReceived; private AndroidJavaObject bridge; private readonly object lockObj new object(); public SerialPortService() : base(com.devdemo.serial.SerialCallback) { AndroidJavaClass unityPlayer new AndroidJavaClass(com.unity3d.player.UnityPlayer); AndroidJavaObject activity unityPlayer.GetStaticAndroidJavaObject(currentActivity); bridge new AndroidJavaObject( com.devdemo.serial.SerialPortBridge, activity, this); } public string[] GetDeviceList() { return bridge.Callstring[](enumDevices); } public int Open(string deviceName, int baudRate) { return bridge.Callint(open, deviceName, baudRate); } public void Close() { bridge.Call(close); } }AndroidJavaProxy是Unity提供的動(dòng)態(tài)代理機(jī)制C#對象可以作為Java接口回調(diào)的實(shí)參傳進(jìn)Java層。Java的SerialCallback接口定義一個(gè)onData(byte[])方法C#類通過重寫OnData方法接收底層數(shù)據(jù)這樣Unity側(cè)不用開額外線程就能拿到串口字節(jié)。調(diào)用過程有兩個(gè)注意點(diǎn)。AndroidJavaObject.Call傳參時(shí)bool要轉(zhuǎn)成Java booleanstring直接用C#的string即可返回值是數(shù)組的Unity能直接轉(zhuǎn)成對應(yīng)類型的C#數(shù)組。另外在Linux編輯器模式下調(diào)試會(huì)報(bào)找不到UnityPlayer類所以串口服務(wù)初始化要包在#if UNITY_ANDROID宏里等真機(jī)打包后再調(diào)用。4. 數(shù)據(jù)收發(fā)實(shí)戰(zhàn)從讀取線程到幀解析完整鏈路一幀不丟4.1 Java側(cè)讀取線程別把USB讀操作塞到主線程USB串口庫提供的read操作是阻塞式的。如果直接在Unity下幀循環(huán)里調(diào)用橋接去讀每一幀都卡在USB讀取上界面明顯掉幀。數(shù)據(jù)流量一上來主線程和渲染線程互相等整個(gè)應(yīng)用就“假死”了。正確做法是在Java層起一條獨(dú)立線程循環(huán)調(diào)用read把讀到的數(shù)據(jù)通過回調(diào)拋給Unityprivate Thread readThread; private volatile boolean running; public void startReading() { running true; readThread new Thread(() - { byte[] buffer new byte[512]; while (running serialPort ! null) { try { int len serialPort.read(buffer, 300); if (len 0) { byte[] data new byte[len]; System.arraycopy(buffer, 0, data, 0, len); callback.onData(data); } } catch (Exception e) { running false; } } }); readThread.start(); } public void stopReading() { running false; if (readThread ! null) { readThread.interrupt(); } }read的第二個(gè)參數(shù)是超時(shí)毫秒數(shù)300毫秒內(nèi)沒有新數(shù)據(jù)就返回0或負(fù)值。進(jìn)入循環(huán)后如果串口斷開read會(huì)拋異常這里捕獲后把running置false線程自然退出避免出現(xiàn)僵尸線程。每次從buffer截取實(shí)際讀到的長度再一次性提交回調(diào)。不直接復(fù)用整個(gè)512字節(jié)數(shù)組是因?yàn)閁nity側(cè)會(huì)把這個(gè)數(shù)組當(dāng)完整數(shù)據(jù)做幀解析如果混入多余空字節(jié)會(huì)判斷錯(cuò)幀長。4.2 Unity側(cè)數(shù)據(jù)接收隊(duì)列把Java回調(diào)轉(zhuǎn)成主線程親和的事件流Java回調(diào)到C#側(cè)時(shí)OnData方法運(yùn)行在子線程而Unity大部分API不允許子線程訪問。處理方法是在C#側(cè)把收到的字節(jié)放入線程安全的隊(duì)列然后在Update里統(tǒng)一取出處理private readonly ConcurrentQueuebyte[] pendingData new ConcurrentQueuebyte[](); public void OnData(byte[] data) { pendingData.Enqueue(data); } private void Update() { byte[] data; while (pendingData.TryDequeue(out data)) { ProcessSerialData(data); } }注意幾個(gè)細(xì)節(jié)OnData回調(diào)必須保證線程安全如果隊(duì)列不加鎖回調(diào)并發(fā)進(jìn)來就可能壞數(shù)據(jù)ConcurrentQueue的TryDequeue保證出隊(duì)原子性但ProcessSerialData內(nèi)部不能做耗時(shí)操作否則隊(duì)列會(huì)越堆越長。ProcessSerialData內(nèi)部流程是先把原始字節(jié)拼進(jìn)一個(gè)分組緩沖區(qū)再按幀頭幀尾切分。不能每收到一次回調(diào)就算一幀因?yàn)榇诘膔ead可能一幀分兩次讀到也可能一次讀到半幀。常見做法是積累式緩沖新字節(jié)append到尾部再循環(huán)從頭查找完整幀。4.3 發(fā)送鏈路指令組包、異步寫入和失敗降級(jí)發(fā)送接口同樣走AndroidJavaObject.Call回到Java層。write是同步的在主線程調(diào)用可能卡頓所以發(fā)送時(shí)我一般放在Unity協(xié)程里或Task.Run包一層public bool Write(byte[] payload) { if (bridge null) return false; return bridge.Callbool(write, payload); }Java側(cè)對write封裝一層重試邏輯public boolean write(byte[] data) { if (serialPort null) return false; try { int written serialPort.write(data, 300); return written data.length; } catch (Exception e) { return false; } }寫入時(shí)序有一個(gè)容易翻車的點(diǎn)兩個(gè)指令間隔太短轉(zhuǎn)接芯片的發(fā)送緩沖區(qū)還沒把上一幀發(fā)完下一幀就綴上去。應(yīng)用層要保證每次發(fā)送之間至少有一個(gè)幀的間隔不建議硬編碼毫秒級(jí)delay。更穩(wěn)妥的做法是維護(hù)一個(gè)發(fā)送隊(duì)列上一幀write返回后再發(fā)下一幀。對實(shí)時(shí)性要求不高的工業(yè)采集場景發(fā)送頻率控制在20幀每秒以內(nèi)穩(wěn)定性會(huì)好很多。4.4 協(xié)議幀封裝幀頭、長度、命令字和CRC16的通用實(shí)現(xiàn)單片機(jī)那邊幾乎不會(huì)用裸字節(jié)當(dāng)業(yè)務(wù)數(shù)據(jù)至少帶一個(gè)簡單幀格式。下面是一個(gè)可以直接拿去改的組包實(shí)現(xiàn)public static class SerialFrame { public static byte[] BuildFrame(byte cmd, byte[] payload) { int length 1 1 payload.Length 1 2; byte[] frame new byte[length]; frame[0] 0xAA; frame[1] 0x55; frame[2] (byte)(payload.Length 1); frame[3] cmd; System.Buffer.BlockCopy(payload, 0, frame, 4, payload.Length); ushort crc Crc16.Compute(frame, frame.Length - 2); frame[frame.Length - 2] (byte)(crc 0xFF); frame[frame.Length - 1] (byte)((crc 8) 0xFF); return frame; } }幀結(jié)構(gòu)是兩字節(jié)幀頭0xAA55一字節(jié)長度字段一字節(jié)命令字然后是負(fù)載最后兩字節(jié)CRC16校驗(yàn)尾。接收端解析先找?guī)^讀長度字段判斷幀長計(jì)算CRC比對校驗(yàn)尾。這個(gè)格式很通用能應(yīng)付大多數(shù)單片機(jī)通信。CRC16用查表法實(shí)現(xiàn)代碼不復(fù)雜。組包時(shí)注意CRC計(jì)算范圍是除校驗(yàn)尾以外的所有字節(jié)兩個(gè)校驗(yàn)字節(jié)的順序由單片機(jī)固件決定。調(diào)試時(shí)如果CRC一直對不上先把這兩字節(jié)交換一下再看。這類“對不上校驗(yàn)”的排查點(diǎn)后面避坑章節(jié)會(huì)專門提。注意幀頭、長度字段和CRC的字節(jié)序一定要先跟設(shè)備端固件確認(rèn)。很多項(xiàng)目聯(lián)調(diào)翻車都是協(xié)議看起來一致實(shí)際高低字節(jié)順序完全相反。5. 串口調(diào)試避坑五類高頻問題從現(xiàn)象到根因的排查路線5.1 設(shè)備列表為空USB轉(zhuǎn)串口板插上沒反應(yīng)現(xiàn)象Unity界面上點(diǎn)“刷新設(shè)備”枚舉數(shù)組為空OTG線已插好轉(zhuǎn)接板指示燈也亮了。原因AndroidManifest沒聲明USB Host特性或Activity沒有接收USB_DEVICE_ATTACHED廣播。系統(tǒng)層面可能壓根沒把設(shè)備加入U(xiǎn)sbManager設(shè)備列表。另一種情況是部分平板廠商對USB設(shè)備做了白名單限制。解決先確認(rèn)清單里有uses-feature android.hardware.usb.host再檢查Intent-Filter是否齊全。排除后在電腦上用adb shell執(zhí)行dumpsys usb查看系統(tǒng)枚舉結(jié)果如果這里都沒有就是硬件接觸或供電問題。帶RS485隔離模塊的轉(zhuǎn)接板常吃電流單靠平板USB口供電經(jīng)常帶不動(dòng)這時(shí)得外接供電。5.2 權(quán)限彈窗出現(xiàn)但點(diǎn)確定之后沒有任何回調(diào)現(xiàn)象第一次插入設(shè)備系統(tǒng)彈出USB設(shè)備授權(quán)對話框點(diǎn)了允許但串口就是打不開甚至反復(fù)彈窗。原因請求權(quán)限用的PendingIntent在Android 12以上需要顯式指定可變性標(biāo)志如果配了FLAG_MUTABLE或FLAG_IMMUTABLE不當(dāng)權(quán)限回調(diào)廣播就發(fā)不出來。另外BroadcastReceiver如果用Activity作為context動(dòng)態(tài)注冊Activity銷毀后收不到任何事件。解決PendingIntent.getBroadcast(context, 0, intent, PendingIntent.FLAG_IMMUTABLE | PendingIntent.FLAG_UPDATE_CURRENT)Receiver注冊改用context.getApplicationContext()這樣即使頁面重建也不會(huì)丟廣播。還要區(qū)分手機(jī)系統(tǒng)設(shè)置里的“USB調(diào)試”彈窗那是開發(fā)者選項(xiàng)和應(yīng)用層USB權(quán)限是兩回事。5.3 串口打開正常但收到的字節(jié)全是亂碼現(xiàn)象read能收到數(shù)據(jù)打印出來是\u00ff\u00fe之類或者高位字節(jié)全部丟失。原因最常見是波特率不匹配。單片機(jī)端配置9600安卓側(cè)按115200打開肯定亂碼。另一類是數(shù)據(jù)位、停止位、校驗(yàn)位有一項(xiàng)不一致比如設(shè)備端是8N1代碼里寫成了7E1導(dǎo)致字節(jié)錯(cuò)位。解決先查看設(shè)備說明書確認(rèn)串口參數(shù)再把setParameters里四個(gè)參數(shù)對齊。還亂碼就換一根更短的連接線工業(yè)現(xiàn)場長線傳輸高波特率很容易受干擾。試到2400或4800許多老傳感器在低速下反而穩(wěn)定。5.4 數(shù)據(jù)能收但丟幀嚴(yán)重幀與幀之間斷流現(xiàn)象偶爾能收到完整數(shù)據(jù)幀但數(shù)據(jù)不連續(xù)中間缺字節(jié)報(bào)文頭尾經(jīng)常對不上。原因讀取線程buffer太小或讀取間隔太長。USB批量傳輸一次最大有效載荷不過64字節(jié)單次讀取后沒及時(shí)清空下一個(gè)包就可能覆蓋前一個(gè)。另一頭可能是Unity側(cè)ProcessSerialData耗時(shí)太長隊(duì)列堆積串口數(shù)據(jù)延遲后看起來就像斷流。解決Java讀取線程把buffer加大到1024超時(shí)設(shè)200到300毫秒。Unity側(cè)處理函數(shù)不要直接做日志輸出先把字節(jié)緩沖到幀緩沖區(qū)拼出完整幀再處理。如果還是掉考慮在AndroidManifest里給讀取線程加高優(yōu)先級(jí)或者直接用后臺(tái)Service持有連接。5.5 鎖屏或切后臺(tái)后串口斷開回到前臺(tái)必須重新打開現(xiàn)象平板鎖屏一段時(shí)間解鎖后串口數(shù)據(jù)停了重新點(diǎn)打開設(shè)備報(bào)設(shè)備被占用或打不開。原因UsbDeviceConnection的存活和Activity生命周期有關(guān)。Unity場景在后臺(tái)被回收J(rèn)ava層bridge對象雖然還在底層連接已經(jīng)被系統(tǒng)回收。解決把bridge對象的生命周期和應(yīng)用進(jìn)程對齊在Unity里把SerialPortService掛到一個(gè)DontDestroyOnLoad的空物體上同時(shí)監(jiān)聽Application的pause和resume事件。暫停時(shí)主動(dòng)stopReading恢復(fù)時(shí)再startReading可以有效減少斷開概率。需要高強(qiáng)度后臺(tái)采集的場景就得把USB連接放到前臺(tái)服務(wù)里維護(hù)那已經(jīng)超出本文范圍但方向是明確的。6. 二次開發(fā)思路把這套鏈路改造成你自己的協(xié)議通道拿到這套代碼后最常見的改造需求就是替換成自己團(tuán)隊(duì)的私有協(xié)議。我的建議是先不要?jiǎng)覬ava層Java層只負(fù)責(zé)把可靠的字節(jié)流送到C#協(xié)議相關(guān)的一切都收斂在SerialFrame和回調(diào)處理函數(shù)里。這樣做的理由是Java層每次改動(dòng)都要重新導(dǎo)出aar、重新打APK聯(lián)調(diào)成本高而C#層的改動(dòng)可以即時(shí)生效熱更新也不受影響。具體改協(xié)議時(shí)我把SerialFrame做成靜態(tài)工具類留出三個(gè)口子BuildFrame用來組包發(fā)送TryParseFrame用來從字節(jié)流里提取完整幀CalculateCRC用來替換校驗(yàn)算法。很多私有協(xié)議其實(shí)就是把幀頭改成別的魔數(shù)或者在幀尾多塞一個(gè)應(yīng)答號(hào)。這種程度的改動(dòng)只需要復(fù)制一份SerialFrame改一兩個(gè)方法完全不影響串口底層。還有一個(gè)實(shí)用技巧是事件驅(qū)動(dòng)模式。SerialPortService已經(jīng)暴露了DataReceived事件但更推薦在業(yè)務(wù)層做二次轉(zhuǎn)發(fā)public class SerialDemoController : MonoBehaviour { private void OnEnable() { SerialPortService.Instance.DataReceived OnSerialData; } private void OnDisable() { SerialPortService.Instance.DataReceived - OnSerialData; } private void OnSerialData(byte[] frame) { // 在這里按命令字分發(fā)例如0x01轉(zhuǎn)溫度顯示0x02轉(zhuǎn)開關(guān)量狀態(tài) } }這個(gè)寫法保證了每個(gè)業(yè)務(wù)模塊只訂閱自己關(guān)心的消息不會(huì)在同一個(gè)回調(diào)里寫一堆switch-case。多設(shè)備場景下還可以給回調(diào)加一個(gè)deviceId參數(shù)把多個(gè)串口的字節(jié)流按端口分開。驗(yàn)證方面我在Unity側(cè)放了一個(gè)調(diào)試面板實(shí)時(shí)顯示收包計(jì)數(shù)、錯(cuò)誤幀計(jì)數(shù)和最近一幀的十六進(jìn)制內(nèi)容。每次改動(dòng)協(xié)議解析邏輯先用調(diào)試面板確認(rèn)幀格式正確再開始做UI聯(lián)動(dòng)。從那以后我每次接新的串口設(shè)備都先花十分鐘在安卓原生層用日志確認(rèn)枚舉、權(quán)限、連接三個(gè)節(jié)點(diǎn)全部通過再回來改Unity側(cè)界面。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取 Unity安卓串口通信實(shí)戰(zhàn)：USB Host橋接實(shí)現(xiàn)手機(jī)直連單片機(jī)
簡介一份面向 Unity 開發(fā)者的安卓串口收發(fā)代碼包用于解決 Unity 應(yīng)用與 Arduino、樹莓派等外部硬件設(shè)備的數(shù)據(jù)交互問題。壓縮包共 30 個(gè)文件大小約 124KB包含 JNI 橋接相關(guān)的 C/C 源文件.c/.h、Android.mk/Application.mk 構(gòu)建配置、Java 串口接口封裝、多架構(gòu) .so 動(dòng)態(tài)庫及 SVN 元數(shù)據(jù)等。通過閱讀源碼可了解 JNI 層如何封裝打開、關(guān)閉、發(fā)送與接收串口數(shù)據(jù)的邏輯并查看 armeabi-v7a、armeabi、x86 三種 CPU 架構(gòu)的庫文件便于在真機(jī)調(diào)試時(shí)替換對應(yīng) so 庫對于有一定 Android 原生基礎(chǔ)、想擺脫現(xiàn)成插件限制的 Unity 開發(fā)者是可直接參考的實(shí)現(xiàn)樣本。已有 1172 人學(xué)習(xí)下載適合作為復(fù)刻串口收發(fā)功能的起點(diǎn)。1. 一條手機(jī)直連單片機(jī)的數(shù)據(jù)鏈路Unity做界面安卓原生USB口負(fù)責(zé)收發(fā)有一次接產(chǎn)線數(shù)據(jù)采集面板的活兒甲方拿了一臺(tái)現(xiàn)場安卓平板要求直接插USB轉(zhuǎn)串口線讀取下方RS485傳感器數(shù)據(jù)同時(shí)在一套Unity做的三維工控界面里實(shí)時(shí)刷新數(shù)值。大部分人聽到“Unity串口”第一反應(yīng)是用C#的System.IO.Ports但這個(gè)庫在安卓上直接失效連打開設(shè)備都會(huì)拋異常原因在于安卓的串口權(quán)限模型和Windows差了一個(gè)時(shí)代。這篇文章拆一套能跑起來的Unity安卓串口收發(fā)方案核心思路是把底層USB串口讀寫交給安卓原生層C#通過AndroidJavaObject橋接調(diào)用Unity只負(fù)責(zé)協(xié)議解析和UI渲染。適合在Unity里做設(shè)備上位機(jī)、需要手機(jī)直連單片機(jī)或傳感器的開發(fā)者讀完照著配權(quán)限、寫代碼基本能在幾分鐘內(nèi)跑通數(shù)據(jù)回路。2. 技術(shù)選型拆解為什么繞開C#串口API把寶押在安卓USB Host上2.1 安卓串口的三條路有兩條走不通先看現(xiàn)狀。在Windows上寫串口System.IO.Ports拿過來就用打開COM3讀數(shù)據(jù)幾行代碼搞定但這個(gè)體驗(yàn)在安卓平臺(tái)上徹底失效。Unity的Mono運(yùn)行時(shí)在安卓上沒有串口設(shè)備文件的訪問權(quán)限SerialPort類實(shí)際調(diào)用會(huì)直接失敗或者打開后沒有任何數(shù)據(jù)返回。原因是安卓應(yīng)用層的設(shè)備訪問受SELinux和權(quán)限模型雙重控制工廠設(shè)備里常見的/dev/ttyS0、/dev/ttyMTK節(jié)點(diǎn)普通應(yīng)用連列目錄的權(quán)限都沒有。第二條路是直接用FileStream讀/dev/ttyS*設(shè)備節(jié)點(diǎn)這也是很多老項(xiàng)目在網(wǎng)上流傳的做法。這個(gè)方案依賴root權(quán)限需要把App裝在root過的設(shè)備上再在授權(quán)下執(zhí)行chmod 666。實(shí)際跑起來會(huì)發(fā)現(xiàn)另一個(gè)問題不同SOC平臺(tái)的tty節(jié)點(diǎn)命名完全不同高通平臺(tái)叫ttyHS聯(lián)發(fā)科部分平臺(tái)叫ttyMT展銳的節(jié)點(diǎn)又是另一套。今天能在這臺(tái)機(jī)器跑通的代碼換一批設(shè)備就全滅維護(hù)成本高到失控。所以真正可復(fù)現(xiàn)的路徑只剩第三條USB Host外接串口轉(zhuǎn)接芯片。安卓手機(jī)和平板普遍支持OTG系統(tǒng)把外接的CH340、FT232、CP210x這類轉(zhuǎn)接芯片枚舉成USB設(shè)備應(yīng)用層通過UsbManager獲得設(shè)備句柄。這里不像PC那樣由內(nèi)核自動(dòng)加載串口驅(qū)動(dòng)安卓不會(huì)把USB轉(zhuǎn)串口芯片變成/dev/ttyUSB0需要開發(fā)者在應(yīng)用層實(shí)現(xiàn)對應(yīng)芯片的協(xié)議。繞這一大圈本質(zhì)是用USB的批量傳輸端點(diǎn)模擬異步串口的收發(fā)。2.2 自寫芯片驅(qū)動(dòng)不劃算選現(xiàn)成庫省掉八成工作量USB轉(zhuǎn)串口芯片的協(xié)議并不是統(tǒng)一標(biāo)準(zhǔn)。拿市面上最常見的兩種芯片舉例CH340的控制傳輸命令和FT232的格式完全不是一回事波特率配置、流控開關(guān)、數(shù)據(jù)位設(shè)置的寄存器偏移都對不上。這意味著不借助外部庫需要拿到每顆芯片的數(shù)據(jù)手冊逐個(gè)寄存器實(shí)現(xiàn)配置命令再自己處理廠商芯片的識(shí)別邏輯。我見過有人在這個(gè)環(huán)節(jié)翻車——花兩個(gè)星期照著CH340手冊寫了一個(gè)能用的驅(qū)動(dòng)換一批FT232的轉(zhuǎn)接板控制命令全部失效又要重新讀FT232手冊。這種純應(yīng)用層開發(fā)去啃芯片協(xié)議性價(jià)比實(shí)在低。工程上推薦直接引入現(xiàn)成的USB串口開源庫它把設(shè)備枚舉、VID/PID匹配、芯片差異、波特率寄存器配置全部封裝在底層上層唯一需要關(guān)心的就是打開、讀、寫三個(gè)動(dòng)作。實(shí)際測過CH340和FT232兩種轉(zhuǎn)接板同一份代碼幾乎不用改就能切換芯片。2.3 工程目錄逐文件拆解每個(gè)文件管哪一段拿一個(gè)可運(yùn)行的Unity工程示例串口相關(guān)資源集中放在兩個(gè)目錄下Unity側(cè)的C#腳本和Android插件。Assets/ ├── Plugins/ │ └── Android/ │ ├── AndroidManifest.xml │ ├── libs/ │ │ └── usb-serial-lib.aar │ └── java/ │ └── com/devdemo/serial/ │ ├── SerialPortBridge.java │ └── SerialCallback.java ├── Scripts/ │ ├── Serial/ │ │ ├── SerialPortConfig.cs │ │ ├── SerialPortService.cs │ │ └── SerialFrame.cs │ └── Demo/ │ └── SerialDemoController.cs └── Prefabs/ └── SerialManager.prefabPlugins/Android下的AndroidManifest.xml不是Unity工程默認(rèn)那個(gè)而是構(gòu)建APK時(shí)給安卓打包用的合并清單負(fù)責(zé)聲明USB Host特性、權(quán)限過濾規(guī)則把USB設(shè)備枚舉的Intent-Filter掛到主Activity上。libs目錄放串口庫的aarjava目錄放我們自己的橋接類SerialPortBridge和回調(diào)接口SerialCallback。Scripts/Serial里SerialPortConfig.cs承載當(dāng)前串口的參數(shù)集合波特率、數(shù)據(jù)位、停止位、校驗(yàn)位都在這定義并通過Inspector露出SerialPortService.cs是全局唯一的串口服務(wù)入口控制打開、關(guān)閉、讀寫SerialFrame.cs是協(xié)議解析工具負(fù)責(zé)把收到的原始字節(jié)流按自定義幀格式拆解。Demo目錄掛一個(gè)演示控制器把串口事件轉(zhuǎn)發(fā)到UI顯示文本。Prefabs/SerialManager.prefab是一個(gè)內(nèi)含SerialPortService組件的空物體場景啟動(dòng)時(shí)掛上即可。這種組織方式的好處是協(xié)議、底層、UI三層隔離。后期協(xié)議從Modbus改成私有文本協(xié)議時(shí)只需要?jiǎng)覵erialFrame其余代碼基本不動(dòng)。2.4 USB通信模型底料endpoint、批量傳輸和控制傳輸串口庫封裝得再深底層還是在跟USB的endpoint打交道。UsbDevice暴露接口后需要拿到UsbDeviceConnection再找到對應(yīng)接口的In/Out兩個(gè)endpoint。endpoint就是USB設(shè)備上數(shù)據(jù)傳輸?shù)耐ǖ酪粋€(gè)負(fù)責(zé)往設(shè)備發(fā)數(shù)據(jù)一個(gè)負(fù)責(zé)收數(shù)據(jù)。批量傳輸不保證實(shí)時(shí)性但適合收發(fā)一幀一幀的串口數(shù)據(jù)?？刂苽鬏攧t用來做設(shè)備配置比如切換波特率、設(shè)置數(shù)據(jù)位、請求設(shè)備描述符都走控制端點(diǎn)。UsbSerialPort的setParameters方法內(nèi)部就是拼好控制命令發(fā)到控制端點(diǎn)再由轉(zhuǎn)接芯片改寫內(nèi)部寄存器。理解了這一層就能明白自寫芯片協(xié)議的工作量在哪里——每顆芯片的控制字格式都不同做一次就得重新折騰一遍寄存器映射。提示權(quán)限是一個(gè)繞不開的環(huán)節(jié)。UsbManager是系統(tǒng)服務(wù)App要用設(shè)備必須得到用戶授權(quán)。授權(quán)彈窗呼出后如果沒有對應(yīng)的BroadcastReceiver處理返回結(jié)果后續(xù)openDevice調(diào)用會(huì)一直失敗。這部分在下一章代碼里能看到具體落法。3. 核心模塊拆解從USB設(shè)備枚舉到串口打開的完整鏈路3.1 AndroidManifest配置讓系統(tǒng)把轉(zhuǎn)接板識(shí)別成可用USB設(shè)備Unity導(dǎo)出的APK原本帶一個(gè)自動(dòng)生成的AndroidManifest.xml里面只有Unity入口Activity。外接USB轉(zhuǎn)串口設(shè)備時(shí)需要額外聲明USB Host特性并且給Activity加上USB設(shè)備插拔的Intent-Filter否則設(shè)備插上去系統(tǒng)沒有任何反應(yīng)UsbManager.getDeviceList()拿到的列表永遠(yuǎn)是空的。?xml version1.0 encodingutf-8? manifest xmlns:androidhttp://schemas.android.com/apk/res/android uses-feature android:nameandroid.hardware.usb.host android:requiredtrue / application activity android:namecom.unity3d.player.UnityPlayerActivity 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/usb_device_filter / /activity /application /manifest這段配置做了兩件事。uses-feature聲明應(yīng)用依賴USB Host硬件系統(tǒng)在一開始就知道這個(gè)App需要OTG能力。intent-filter和meta-data組合起來把USB設(shè)備插拔事件路由到UnityPlayerActivity同時(shí)由usb_device_filter.xml文件做設(shè)備過濾。設(shè)備過濾文件通常按廠商VID和產(chǎn)品PID來放行只讓特定芯片觸發(fā)打開流程?xml version1.0 encodingutf-8? resources usb-device vendor-id6790 product-id29987 / usb-device vendor-id1027 product-id24577 / /resources這兩個(gè)ID是我實(shí)際調(diào)試中用到的分別對應(yīng)CH340和FT232兩種常見芯片的組合識(shí)別碼。不同廠商轉(zhuǎn)接板的VID/PID五花八門如果擔(dān)心漏設(shè)備也可以把過濾文件寫成空列表讓系統(tǒng)對所有USB設(shè)備廣播在Java代碼里再靠芯片協(xié)議探測來判斷是不是串口。我的習(xí)慣是過濾寫嚴(yán)一點(diǎn)只放已經(jīng)驗(yàn)證過的板子防止車間現(xiàn)場彈出些莫名其妙的權(quán)限請求干擾作業(yè)。3.2 SerialPortBridge.java設(shè)備枚舉、鑒權(quán)、連接一次說清Java側(cè)的核心類叫SerialPortBridge負(fù)責(zé)把UsbManager的系統(tǒng)服務(wù)能力包裝成Unity方便調(diào)用的接口。先看設(shè)備枚舉public class SerialPortBridge { private static final String ACTION_USB_PERMISSION com.devdemo.serial.USB_PERMISSION; private Context context; private UsbManager usbManager; private PendingIntent usbPermissionIntent; private UsbSerialPort serialPort; private UsbDeviceConnection connection; public SerialPortBridge(Context context, Activity activity) { this.context context; this.usbManager (UsbManager) context.getSystemService(Context.USB_SERVICE); this.usbPermissionIntent PendingIntent.getBroadcast( context, 0, new Intent(ACTION_USB_PERMISSION), PendingIntent.FLAG_MUTABLE); } public String[] enumDevices() { HashMapString, UsbDevice devices usbManager.getDeviceList(); ListString names new ArrayList(); for (UsbDevice device : devices.values()) { names.add(device.getDeviceName()); } return names.toArray(new String[0]); } }枚舉方法把UsbManager內(nèi)的所有USB設(shè)備名取出來返回給Unity側(cè)。一個(gè)安卓設(shè)備會(huì)掛多個(gè)USB設(shè)備比如觸控屏、鍵鼠、數(shù)據(jù)線通通都會(huì)出現(xiàn)在這里。光拿名字不夠打開前還要通過UsbSerialProber探測哪一個(gè)是能被串口芯片協(xié)議識(shí)別的設(shè)備。請求權(quán)限的代碼public void requestPermission(String deviceName) { UsbDevice device findDeviceByName(deviceName); if (device null) return; if (!usbManager.hasPermission(device)) { usbManager.requestPermission(device, usbPermissionIntent); } }這里的回調(diào)不是同步返回而是通過ACTION_USB_PERMISSION廣播回到注冊好的BroadcastReceiver。我在構(gòu)造方法里動(dòng)態(tài)注冊Receiver到應(yīng)用Context上收到允許結(jié)果后馬上執(zhí)行openDevice和UsbSerialPort初始化。不熟悉這個(gè)模式的開發(fā)者把requestPermission當(dāng)同步調(diào)用緊接著就調(diào)openDevice必然每次失敗這個(gè)坑后面避坑章節(jié)會(huì)詳細(xì)展開。打開串口的核心方法public int open(String deviceName, int baudRate) { UsbDevice device findDeviceByName(deviceName); if (!usbManager.hasPermission(device)) { return -2; } connection usbManager.openDevice(device); if (connection null) { return -3; } UsbSerialPort port UsbSerialProber .getDefaultProber() .probeDevice(connection, device); if (port null) { return -4; } serialPort port; serialPort.open(connection); serialPort.setParameters( baudRate, 8, UsbSerialPort.STOPBITS_1, UsbSerialPort.PARITY_NONE); return 0; }幾個(gè)返回值對應(yīng)不同失敗原因-2是沒授權(quán)-3是系統(tǒng)把設(shè)備占了-4是芯片協(xié)議不匹配。Unity側(cè)拿到返回值就能直接給用戶一個(gè)明確的提示文案。setParameters里的參數(shù)分別對應(yīng)波特率、數(shù)據(jù)位、停止位和校驗(yàn)位和Windows串口編程里DCB結(jié)構(gòu)體的內(nèi)容一一對應(yīng)這里配置錯(cuò)了后面讀到的數(shù)據(jù)全部是亂碼。3.3 C#側(cè)橋接Unity把調(diào)用傳到Java層的標(biāo)準(zhǔn)姿勢Unity側(cè)并不直接持有UsbManager所有安卓系統(tǒng)服務(wù)調(diào)用都必須經(jīng)過AndroidJavaObject。SerialPortService以單例形式存在構(gòu)造時(shí)同時(shí)創(chuàng)建Java橋接對象和回調(diào)代理public class SerialPortService : AndroidJavaProxy { public delegate void DataReceivedHandler(byte[] data); public event DataReceivedHandler DataReceived; private AndroidJavaObject bridge; private readonly object lockObj new object(); public SerialPortService() : base(com.devdemo.serial.SerialCallback) { AndroidJavaClass unityPlayer new AndroidJavaClass(com.unity3d.player.UnityPlayer); AndroidJavaObject activity unityPlayer.GetStaticAndroidJavaObject(currentActivity); bridge new AndroidJavaObject( com.devdemo.serial.SerialPortBridge, activity, this); } public string[] GetDeviceList() { return bridge.Callstring[](enumDevices); } public int Open(string deviceName, int baudRate) { return bridge.Callint(open, deviceName, baudRate); } public void Close() { bridge.Call(close); } }AndroidJavaProxy是Unity提供的動(dòng)態(tài)代理機(jī)制C#對象可以作為Java接口回調(diào)的實(shí)參傳進(jìn)Java層。Java的SerialCallback接口定義一個(gè)onData(byte[])方法C#類通過重寫OnData方法接收底層數(shù)據(jù)這樣Unity側(cè)不用開額外線程就能拿到串口字節(jié)。調(diào)用過程有兩個(gè)注意點(diǎn)。AndroidJavaObject.Call傳參時(shí)bool要轉(zhuǎn)成Java booleanstring直接用C#的string即可返回值是數(shù)組的Unity能直接轉(zhuǎn)成對應(yīng)類型的C#數(shù)組。另外在Linux編輯器模式下調(diào)試會(huì)報(bào)找不到UnityPlayer類所以串口服務(wù)初始化要包在#if UNITY_ANDROID宏里等真機(jī)打包后再調(diào)用。4. 數(shù)據(jù)收發(fā)實(shí)戰(zhàn)從讀取線程到幀解析完整鏈路一幀不丟4.1 Java側(cè)讀取線程別把USB讀操作塞到主線程USB串口庫提供的read操作是阻塞式的。如果直接在Unity下幀循環(huán)里調(diào)用橋接去讀每一幀都卡在USB讀取上界面明顯掉幀。數(shù)據(jù)流量一上來主線程和渲染線程互相等整個(gè)應(yīng)用就“假死”了。正確做法是在Java層起一條獨(dú)立線程循環(huán)調(diào)用read把讀到的數(shù)據(jù)通過回調(diào)拋給Unityprivate Thread readThread; private volatile boolean running; public void startReading() { running true; readThread new Thread(() - { byte[] buffer new byte[512]; while (running serialPort ! null) { try { int len serialPort.read(buffer, 300); if (len 0) { byte[] data new byte[len]; System.arraycopy(buffer, 0, data, 0, len); callback.onData(data); } } catch (Exception e) { running false; } } }); readThread.start(); } public void stopReading() { running false; if (readThread ! null) { readThread.interrupt(); } }read的第二個(gè)參數(shù)是超時(shí)毫秒數(shù)300毫秒內(nèi)沒有新數(shù)據(jù)就返回0或負(fù)值。進(jìn)入循環(huán)后如果串口斷開read會(huì)拋異常這里捕獲后把running置false線程自然退出避免出現(xiàn)僵尸線程。每次從buffer截取實(shí)際讀到的長度再一次性提交回調(diào)。不直接復(fù)用整個(gè)512字節(jié)數(shù)組是因?yàn)閁nity側(cè)會(huì)把這個(gè)數(shù)組當(dāng)完整數(shù)據(jù)做幀解析如果混入多余空字節(jié)會(huì)判斷錯(cuò)幀長。4.2 Unity側(cè)數(shù)據(jù)接收隊(duì)列把Java回調(diào)轉(zhuǎn)成主線程親和的事件流Java回調(diào)到C#側(cè)時(shí)OnData方法運(yùn)行在子線程而Unity大部分API不允許子線程訪問。處理方法是在C#側(cè)把收到的字節(jié)放入線程安全的隊(duì)列然后在Update里統(tǒng)一取出處理private readonly ConcurrentQueuebyte[] pendingData new ConcurrentQueuebyte[](); public void OnData(byte[] data) { pendingData.Enqueue(data); } private void Update() { byte[] data; while (pendingData.TryDequeue(out data)) { ProcessSerialData(data); } }注意幾個(gè)細(xì)節(jié)OnData回調(diào)必須保證線程安全如果隊(duì)列不加鎖回調(diào)并發(fā)進(jìn)來就可能壞數(shù)據(jù)ConcurrentQueue的TryDequeue保證出隊(duì)原子性但ProcessSerialData內(nèi)部不能做耗時(shí)操作否則隊(duì)列會(huì)越堆越長。ProcessSerialData內(nèi)部流程是先把原始字節(jié)拼進(jìn)一個(gè)分組緩沖區(qū)再按幀頭幀尾切分。不能每收到一次回調(diào)就算一幀因?yàn)榇诘膔ead可能一幀分兩次讀到也可能一次讀到半幀。常見做法是積累式緩沖新字節(jié)append到尾部再循環(huán)從頭查找完整幀。4.3 發(fā)送鏈路指令組包、異步寫入和失敗降級(jí)發(fā)送接口同樣走AndroidJavaObject.Call回到Java層。write是同步的在主線程調(diào)用可能卡頓所以發(fā)送時(shí)我一般放在Unity協(xié)程里或Task.Run包一層public bool Write(byte[] payload) { if (bridge null) return false; return bridge.Callbool(write, payload); }Java側(cè)對write封裝一層重試邏輯public boolean write(byte[] data) { if (serialPort null) return false; try { int written serialPort.write(data, 300); return written data.length; } catch (Exception e) { return false; } }寫入時(shí)序有一個(gè)容易翻車的點(diǎn)兩個(gè)指令間隔太短轉(zhuǎn)接芯片的發(fā)送緩沖區(qū)還沒把上一幀發(fā)完下一幀就綴上去。應(yīng)用層要保證每次發(fā)送之間至少有一個(gè)幀的間隔不建議硬編碼毫秒級(jí)delay。更穩(wěn)妥的做法是維護(hù)一個(gè)發(fā)送隊(duì)列上一幀write返回后再發(fā)下一幀。對實(shí)時(shí)性要求不高的工業(yè)采集場景發(fā)送頻率控制在20幀每秒以內(nèi)穩(wěn)定性會(huì)好很多。4.4 協(xié)議幀封裝幀頭、長度、命令字和CRC16的通用實(shí)現(xiàn)單片機(jī)那邊幾乎不會(huì)用裸字節(jié)當(dāng)業(yè)務(wù)數(shù)據(jù)至少帶一個(gè)簡單幀格式。下面是一個(gè)可以直接拿去改的組包實(shí)現(xiàn)public static class SerialFrame { public static byte[] BuildFrame(byte cmd, byte[] payload) { int length 1 1 payload.Length 1 2; byte[] frame new byte[length]; frame[0] 0xAA; frame[1] 0x55; frame[2] (byte)(payload.Length 1); frame[3] cmd; System.Buffer.BlockCopy(payload, 0, frame, 4, payload.Length); ushort crc Crc16.Compute(frame, frame.Length - 2); frame[frame.Length - 2] (byte)(crc 0xFF); frame[frame.Length - 1] (byte)((crc 8) 0xFF); return frame; } }幀結(jié)構(gòu)是兩字節(jié)幀頭0xAA55一字節(jié)長度字段一字節(jié)命令字然后是負(fù)載最后兩字節(jié)CRC16校驗(yàn)尾。接收端解析先找?guī)^讀長度字段判斷幀長計(jì)算CRC比對校驗(yàn)尾。這個(gè)格式很通用能應(yīng)付大多數(shù)單片機(jī)通信。CRC16用查表法實(shí)現(xiàn)代碼不復(fù)雜。組包時(shí)注意CRC計(jì)算范圍是除校驗(yàn)尾以外的所有字節(jié)兩個(gè)校驗(yàn)字節(jié)的順序由單片機(jī)固件決定。調(diào)試時(shí)如果CRC一直對不上先把這兩字節(jié)交換一下再看。這類“對不上校驗(yàn)”的排查點(diǎn)后面避坑章節(jié)會(huì)專門提。注意幀頭、長度字段和CRC的字節(jié)序一定要先跟設(shè)備端固件確認(rèn)。很多項(xiàng)目聯(lián)調(diào)翻車都是協(xié)議看起來一致實(shí)際高低字節(jié)順序完全相反。5. 串口調(diào)試避坑五類高頻問題從現(xiàn)象到根因的排查路線5.1 設(shè)備列表為空USB轉(zhuǎn)串口板插上沒反應(yīng)現(xiàn)象Unity界面上點(diǎn)“刷新設(shè)備”枚舉數(shù)組為空OTG線已插好轉(zhuǎn)接板指示燈也亮了。原因AndroidManifest沒聲明USB Host特性或Activity沒有接收USB_DEVICE_ATTACHED廣播。系統(tǒng)層面可能壓根沒把設(shè)備加入U(xiǎn)sbManager設(shè)備列表。另一種情況是部分平板廠商對USB設(shè)備做了白名單限制。解決先確認(rèn)清單里有uses-feature android.hardware.usb.host再檢查Intent-Filter是否齊全。排除后在電腦上用adb shell執(zhí)行dumpsys usb查看系統(tǒng)枚舉結(jié)果如果這里都沒有就是硬件接觸或供電問題。帶RS485隔離模塊的轉(zhuǎn)接板常吃電流單靠平板USB口供電經(jīng)常帶不動(dòng)這時(shí)得外接供電。5.2 權(quán)限彈窗出現(xiàn)但點(diǎn)確定之后沒有任何回調(diào)現(xiàn)象第一次插入設(shè)備系統(tǒng)彈出USB設(shè)備授權(quán)對話框點(diǎn)了允許但串口就是打不開甚至反復(fù)彈窗。原因請求權(quán)限用的PendingIntent在Android 12以上需要顯式指定可變性標(biāo)志如果配了FLAG_MUTABLE或FLAG_IMMUTABLE不當(dāng)權(quán)限回調(diào)廣播就發(fā)不出來。另外BroadcastReceiver如果用Activity作為context動(dòng)態(tài)注冊Activity銷毀后收不到任何事件。解決PendingIntent.getBroadcast(context, 0, intent, PendingIntent.FLAG_IMMUTABLE | PendingIntent.FLAG_UPDATE_CURRENT)Receiver注冊改用context.getApplicationContext()這樣即使頁面重建也不會(huì)丟廣播。還要區(qū)分手機(jī)系統(tǒng)設(shè)置里的“USB調(diào)試”彈窗那是開發(fā)者選項(xiàng)和應(yīng)用層USB權(quán)限是兩回事。5.3 串口打開正常但收到的字節(jié)全是亂碼現(xiàn)象read能收到數(shù)據(jù)打印出來是\u00ff\u00fe之類或者高位字節(jié)全部丟失。原因最常見是波特率不匹配。單片機(jī)端配置9600安卓側(cè)按115200打開肯定亂碼。另一類是數(shù)據(jù)位、停止位、校驗(yàn)位有一項(xiàng)不一致比如設(shè)備端是8N1代碼里寫成了7E1導(dǎo)致字節(jié)錯(cuò)位。解決先查看設(shè)備說明書確認(rèn)串口參數(shù)再把setParameters里四個(gè)參數(shù)對齊。還亂碼就換一根更短的連接線工業(yè)現(xiàn)場長線傳輸高波特率很容易受干擾。試到2400或4800許多老傳感器在低速下反而穩(wěn)定。5.4 數(shù)據(jù)能收但丟幀嚴(yán)重幀與幀之間斷流現(xiàn)象偶爾能收到完整數(shù)據(jù)幀但數(shù)據(jù)不連續(xù)中間缺字節(jié)報(bào)文頭尾經(jīng)常對不上。原因讀取線程buffer太小或讀取間隔太長。USB批量傳輸一次最大有效載荷不過64字節(jié)單次讀取后沒及時(shí)清空下一個(gè)包就可能覆蓋前一個(gè)。另一頭可能是Unity側(cè)ProcessSerialData耗時(shí)太長隊(duì)列堆積串口數(shù)據(jù)延遲后看起來就像斷流。解決Java讀取線程把buffer加大到1024超時(shí)設(shè)200到300毫秒。Unity側(cè)處理函數(shù)不要直接做日志輸出先把字節(jié)緩沖到幀緩沖區(qū)拼出完整幀再處理。如果還是掉考慮在AndroidManifest里給讀取線程加高優(yōu)先級(jí)或者直接用后臺(tái)Service持有連接。5.5 鎖屏或切后臺(tái)后串口斷開回到前臺(tái)必須重新打開現(xiàn)象平板鎖屏一段時(shí)間解鎖后串口數(shù)據(jù)停了重新點(diǎn)打開設(shè)備報(bào)設(shè)備被占用或打不開。原因UsbDeviceConnection的存活和Activity生命周期有關(guān)。Unity場景在后臺(tái)被回收J(rèn)ava層bridge對象雖然還在底層連接已經(jīng)被系統(tǒng)回收。解決把bridge對象的生命周期和應(yīng)用進(jìn)程對齊在Unity里把SerialPortService掛到一個(gè)DontDestroyOnLoad的空物體上同時(shí)監(jiān)聽Application的pause和resume事件。暫停時(shí)主動(dòng)stopReading恢復(fù)時(shí)再startReading可以有效減少斷開概率。需要高強(qiáng)度后臺(tái)采集的場景就得把USB連接放到前臺(tái)服務(wù)里維護(hù)那已經(jīng)超出本文范圍但方向是明確的。6. 二次開發(fā)思路把這套鏈路改造成你自己的協(xié)議通道拿到這套代碼后最常見的改造需求就是替換成自己團(tuán)隊(duì)的私有協(xié)議。我的建議是先不要?jiǎng)覬ava層Java層只負(fù)責(zé)把可靠的字節(jié)流送到C#協(xié)議相關(guān)的一切都收斂在SerialFrame和回調(diào)處理函數(shù)里。這樣做的理由是Java層每次改動(dòng)都要重新導(dǎo)出aar、重新打APK聯(lián)調(diào)成本高而C#層的改動(dòng)可以即時(shí)生效熱更新也不受影響。具體改協(xié)議時(shí)我把SerialFrame做成靜態(tài)工具類留出三個(gè)口子BuildFrame用來組包發(fā)送TryParseFrame用來從字節(jié)流里提取完整幀CalculateCRC用來替換校驗(yàn)算法。很多私有協(xié)議其實(shí)就是把幀頭改成別的魔數(shù)或者在幀尾多塞一個(gè)應(yīng)答號(hào)。這種程度的改動(dòng)只需要復(fù)制一份SerialFrame改一兩個(gè)方法完全不影響串口底層。還有一個(gè)實(shí)用技巧是事件驅(qū)動(dòng)模式。SerialPortService已經(jīng)暴露了DataReceived事件但更推薦在業(yè)務(wù)層做二次轉(zhuǎn)發(fā)public class SerialDemoController : MonoBehaviour { private void OnEnable() { SerialPortService.Instance.DataReceived OnSerialData; } private void OnDisable() { SerialPortService.Instance.DataReceived - OnSerialData; } private void OnSerialData(byte[] frame) { // 在這里按命令字分發(fā)例如0x01轉(zhuǎn)溫度顯示0x02轉(zhuǎn)開關(guān)量狀態(tài) } }這個(gè)寫法保證了每個(gè)業(yè)務(wù)模塊只訂閱自己關(guān)心的消息不會(huì)在同一個(gè)回調(diào)里寫一堆switch-case。多設(shè)備場景下還可以給回調(diào)加一個(gè)deviceId參數(shù)把多個(gè)串口的字節(jié)流按端口分開。驗(yàn)證方面我在Unity側(cè)放了一個(gè)調(diào)試面板實(shí)時(shí)顯示收包計(jì)數(shù)、錯(cuò)誤幀計(jì)數(shù)和最近一幀的十六進(jìn)制內(nèi)容。每次改動(dòng)協(xié)議解析邏輯先用調(diào)試面板確認(rèn)幀格式正確再開始做UI聯(lián)動(dòng)。從那以后我每次接新的串口設(shè)備都先花十分鐘在安卓原生層用日志確認(rèn)枚舉、權(quán)限、連接三個(gè)節(jié)點(diǎn)全部通過再回來改Unity側(cè)界面。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取