1# USB串口通信管理 2 3<!--Kit: Basic Services Kit--> 4<!--Subsystem: USB--> 5<!--Owner: @hwymlgitcode--> 6<!--Designer: @w00373942--> 7<!--Tester: @dong-dongzhen--> 8<!--Adviser: @w_Machine_cc--> 9 10## 简介 11 12USB串口通信服务中通过Host设备的USB接口连接串口设备的串口进行串行数据传输，通信管理核心目标是实现设备间的高效、稳定数据传输与协同控制。主要使用在工业自动化与远程监控、物联网设备互联、医疗设备管理等场景。 13 14## 环境准备 15 16请参考USB串口通信服务开发概述[环境准备](usbSerial-overview.md#环境准备)。 17 18## 开发指导 19 20### 接口说明 21 22| 接口名 | 描述 | 23|------------------------------------------------------------------------------|--------------------------| 24| getPortList(): Readonly<SerialPort>[] | 获取串口设备列表。 | 25| hasSerialRight(portId: number): boolean | 检查应用程序是否具有访问串口设备的权限。 | 26| requestSerialRight(portId: number): Promise<boolean> | 请求对串口设备的访问权限。 | 27| open(portId: number): void | 打开串口设备。 | 28| close(portId: number): void | 关闭串口设备。 | 29| read(portId: number, buffer: Uint8Array, timeout?: number): Promise<number> | 从串口设备读取数据，使用Promise异步返回。 | 30| readSync(portId: number, buffer: Uint8Array, timeout?: number): number | 以同步方法从串口设备读取数据。 | 31| write(portId: number, buffer: Uint8Array, timeout?: number): Promise<number> | 往串口设备写入数据，使用Promise异步返回。 | 32| writeSync(portId: number, buffer: Uint8Array, timeout?: number): number | 以同步方法往串口设备写入数据。 | 33 34 35### 开发步骤 36 37开发者可以通过上述接口读取和写入数据： 38 39> **说明：** 40> 41> 以下示例代码只是串口数据传输的必要流程，需要放入具体的方法中执行。 42 431. 导入模块。 44 45 ```ts 46 // 导入serialManager模块。 47 import { serialManager } from '@kit.BasicServicesKit'; 48 import { buffer } from '@kit.ArkTS'; 49 ``` 50 512. 获取设备列表。 52 53 ```ts 54 // 获取连接主设备的USB设备列表 55 let portList: serialManager.SerialPort[] = serialManager.getPortList(); 56 console.info(`usbSerial portList: ${portList}`); 57 if (portList === undefined || portList.length === 0) { 58 console.error('usbSerial portList is empty'); 59 return; 60 } 61 ``` 62 633. 获取设备操作权限。 64 65 ```ts 66 // 此处对列表中的第一台USB设备判断是否拥有访问权限 67 // 函数名仅作为示例，实际需要与业务结合命名 68 async function serialDefault() { 69 let portId: number = portList[0].portId; 70 if (!serialManager.hasSerialRight(portId)) { 71 await serialManager.requestSerialRight(portId).then(result => { 72 if(!result) { 73 // 没有访问设备的权限且用户不授权则退出 74 console.error('The user does not have permission to perform this operation'); 75 return; 76 } 77 }); 78 } 79 } 80 ``` 81 824. 根据串口打开设备。 83 84 ```ts 85 try { 86 serialManager.open(portId) 87 console.info(`open usbSerial success, portId: ${portId}`); 88 } catch (error) { 89 console.error(`open usbSerial error： ${error}`); 90 } 91 ``` 92 935. 通过串口读取数据。 94 95 ```ts 96 // 异步读取 97 let readBuffer: Uint8Array = new Uint8Array(64); 98 serialManager.read(portId, readBuffer, 2000).then((size: number) => { 99 console.info(`read usbSerial success, readBuffer: ${readBuffer}`); 100 }).catch((error: Error) => { 101 console.error(`read usbSerial error: ${error}`); 102 }) 103 104 // 同步读取 105 let readSyncBuffer: Uint8Array = new Uint8Array(64); 106 try { 107 serialManager.readSync(portId, readSyncBuffer, 2000); 108 console.info(`readSync usbSerial success, readSyncBuffer: ${readSyncBuffer}`); 109 } catch (error) { 110 console.error(`readSync usbSerial error: ${error}`); 111 } 112 ``` 113 1146. 通过串口写入数据。 115 116 ```ts 117 // 异步写入 118 let writeBuffer: Uint8Array = new Uint8Array(buffer.from('Hello World', 'utf-8').buffer) 119 serialManager.write(portId, writeBuffer, 2000).then((size: number) => { 120 console.info(`write usbSerial success, writeBuffer: ${writeBuffer}`); 121 }).catch((error: Error) => { 122 console.error(`write usbSerial error: ${error}`); 123 }) 124 125 // 同步写入 126 let writeSyncBuffer: Uint8Array = new Uint8Array(buffer.from('Hello World', 'utf-8').buffer) 127 try { 128 serialManager.writeSync(portId, writeSyncBuffer, 2000); 129 console.info(`writeSync usbSerial success, writeSyncBuffer: ${writeSyncBuffer}`); 130 } catch (error) { 131 console.error(`writeSync usbSerial error: ${error}`); 132 } 133 ``` 134 1357. 关闭串口设备。 136 137 ```ts 138 try { 139 serialManager.close(portId); 140 console.info(`close usbSerial success, portId: ${portId}`); 141 } catch (error) { 142 console.error(`close usbSerial error: ${error}`); 143 } 144 ``` 145 146### 调测验证 147 1481. 准备一根USB转串口线缆，线缆的USB接口连接到OpenHarmony设备USB端口（该端口需支持USB转串口），线缆的串口接口连接到目标设备的串口上。 1492. 在OpenHarmony设备上执行上述示例。 1503. 返回`usbSerial success`，表示相关接口调用成功，设备串口通信能力正常；返回`usbSerial error`，表示接口调用失败。