1# 开发适用串口协议的设备驱动 2<!--Kit: Driver Development Kit--> 3<!--Subsystem: Driver--> 4<!--Owner: @lixinsheng2--> 5<!--Designer: @w00373942--> 6<!--Tester: @dong-dongzhen--> 7<!--Adviser: @w_Machine_cc--> 8 9## 简介 10 11在工业用途场景中和一些陈旧设备上，都有对非标串口设备的使用需求，例如：温湿度测量计、特殊身份读卡器等，当系统中没有适配该设备的驱动时，会导致设备接入后无法使用。USB Serial DDK（USB Serial Driver Develop Kit）是为开发者提供的USB串口驱动程序开发套件，支持开发者基于用户态，在应用层开发USB串口设备驱动。USB Serial DDK提供了一系列主机侧访问设备的接口，包括主机侧打开和关闭接口、串口读写通信等。依赖这些驱动开发接口，该类三方生态外设可顺利接入OpenHarmony，满足生态安全加密场景应用需求。 12 13### 基本概念 14 15在进行USB Serial DDK开发前，开发者应了解以下基本概念： 16 17- **USB 串口** 18 19 USB 串口（USB-to-Serial）是指一种接口转换技术，它允许通过 USB（通用串行总线）接口实现与传统串行端口（如 RS-232、RS-485 等）之间的数据通信。这种技术通常通过专门的硬件适配器或特定的内置芯片来实现。 20 21- **AMS** 22 23 AMS（Ability Manager Service）用于协调各Ability运行关系、及对生命周期进行调度的系统服务。在驱动开发过程中用于拉起和关闭扩展驱动能力DriverExtensionAbility。 24 25- **BMS** 26 27 BMS（Bundle Manager Service）在OpenHarmony上主要负责应用的安装、卸载和数据管理。 28 29- **DDK** 30 31 DDK（Driver Develop Kit）是OpenHarmony基于扩展外设框架，为开发者提供的驱动应用开发的工具包，可针对非标USB串口设备，开发对应的驱动。 32 33- **非标外设** 34 35 非标外设（也称为自定义外设或专有外设）是指不遵循通用标准或专门为特定应用场景定制设计的外围设备。这类设备往往需要专门的软件支持或者特殊的接口来实现与主机系统的通信。 36 37- **标准外设** 38 39 标准外设指的是遵循行业广泛接受的标准规范设计的外围设备（USB 键盘、鼠标）。这些设备通常具有统一的接口协议、物理尺寸和电气特性，使得其可以在不同的系统之间互换使用。 40 41### 实现原理 42 43非标外设应用通过扩展外设管理服务获取USB串口设备的ID，通过RPC将ID和要操作的动作下发给USB串口驱动应用，USB串口驱动应用通过调用USB Serial DDK接口可设置串口属性（波特率、数据位、校验位等），读取串口数据，DDK接口使用HDI服务将指令下发至内核驱动，内核驱动使用指令与设备通信。 44 45**图1** USB Serial DDK调用原理 46 47 48 49### 约束与限制 50 51- USB Serial DDK开放API支持USB串口接口非标外设扩展驱动开发场景。 52 53- USB Serial DDK开放API使用范围内仅允许DriverExtensionAbility生命周期内使用。 54 55- 使用USB Serial DDK开放API需要在module.json5中声明匹配的ACL权限，例如ohos.permission.ACCESS_DDK_USB_SERIAL。 56 57## 环境搭建 58 59请参考[环境准备](environmental-preparation.md)完成开发前的准备工作。 60 61## 开发指导 62 63### 接口说明 64 65| 名称 | 描述 | 66| -------- | -------- | 67| OH_UsbSerial_Init(void) | 初始化USB Serial DDK。 | 68| OH_UsbSerial_Release(void) | 释放USB Serial DDK。 | 69| OH_UsbSerial_Open(uint64_t deviceId, uint8_t interfaceIndex, UsbSerial_Device **dev) | 通过deviceId和interfaceIndex打开USB串口设备。请在设备使用完后调用OH_UsbSerial_Close()关闭设备，否则会造成内存泄漏。 | 70| OH_UsbSerial_Close(UsbSerial_Device **dev) | 关闭USB串口设备，请在设备使用完后关闭设备，否则会造成内存泄漏。 | 71| OH_UsbSerial_Read(UsbSerial_Device *dev, uint8_t *buff, uint32_t bufferSize, uint32_t *bytesRead) | 从USB串口设备读取数据到缓冲区。 | 72| OH_UsbSerial_Write(UsbSerial_Device *dev, uint8_t *buff, uint32_t bufferSize, uint32_t *bytesWritten) | 将buff中的数据写入USB串口设备。 | 73| OH_UsbSerial_SetBaudRate(UsbSerial_DeviceHandle *dev, uint32_t baudRate) | 设置USB串口设备的波特率。如果串口的数据位为8，停止位为1，不校验，则调用该接口。 | 74| OH_UsbSerial_SetParams(UsbSerial_Device *dev, UsbSerial_Params *params) | 设置USB串口设备的参数，包含波特率、数据传输位、停止位、校验设置。 | 75| OH_UsbSerial_SetTimeout(UsbSerial_Device *dev, int timeout) | 设置读取USB串口设备上报数据的超时时间，默认时间为0。 | 76| OH_UsbSerial_SetFlowControl(UsbSerial_Device *dev, UsbSerial_FlowControl flowControl) | 设置流控参数。 | 77| OH_UsbSerial_Flush(UsbSerial_Device *dev) | 写入完成后清空输入和输出缓冲区。 | 78| OH_UsbSerial_FlushInput(UsbSerial_Device *dev) | 刷新输入缓冲区，缓冲区中的数据会被立刻清空。 | 79| OH_UsbSerial_FlushOutput(UsbSerial_Device *dev) | 刷新输出缓冲区，缓冲区中的数据会被立刻清空。 | 80 81详细的接口说明请参考[USB Serial DDK](../../reference/apis-driverdevelopment-kit/capi-serialddk.md)。 82 83### 开发步骤 84 85以下步骤描述了如何使用 **USB Serial DDK**开发USB串口驱动： 86 87**添加动态链接库** 88 89CMakeLists.txt中添加以下lib。 90```txt 91libusb_serial_ndk.z.so 92``` 93 94**头文件** 95```c++ 96#include <serial/usb_serial_api.h> 97#include <serial/usb_serial_types.h> 98``` 99 1001. 初始化DDK。 101 102 使用 **usb_serial_api.h** 的 **OH_UsbSerial_Init** 初始化DDK。 103 104 ```c++ 105 // 初始化USB Serial DDK 106 OH_UsbSerial_Init(); 107 ``` 108 1092. 打开USB串口设备。 110 111 使用 **usb_serial_api.h** 的 **OH_UsbSerial_Open** 打开设备。 112 113 ```c++ 114 UsbSerial_Device *dev = NULL; 115 uint64_t deviceId = 1688858450198529; 116 uint8_t interfaceIndex = 0; 117 // 打开deviceId和interfaceIndex指定的USB串口设备 118 OH_UsbSerial_Open(deviceId, interfaceIndex, &dev); 119 ``` 120 1213. 设置USB串口设备的参数。 122 123 使用 **usb_serial_api.h** 的 **OH_UsbSerial_SetParams** 接口设置串口参数，或者直接调用 **OH_UsbSerial_SetBaudRate** 设置波特率，使用 **OH_UsbSerial_SetTimeout** 设置读取数据的超时时间。 124 125 ```c++ 126 UsbSerial_Params params; 127 params.baudRate = 9600; 128 params.nDataBits = 8; 129 params.nStopBits = 1; 130 params.parity = 0; 131 // 设置串口参数 132 OH_UsbSerial_SetParams(dev, ¶ms); 133 134 // 设置波特率 135 uint32_t baudRate = 9600; 136 OH_UsbSerial_SetBaudRate(dev, baudRate); 137 138 // 设置超时时间 139 int timeout = 500; 140 OH_UsbSerial_SetTimeout(dev, timeout); 141 ``` 142 1434. 设置流控、清空缓冲区。 144 145 使用 **usb_serial_api.h** 的 **OH_UsbSerial_SetFlowControl** 设置流控方式，使用 **OH_UsbSerial_Flush** 清空缓冲区，使用 **OH_UsbSerial_FlushInput** 清空输入缓冲区，使用 **OH_UsbSerial_FlushOutput** 清空输出缓冲区。 146 147 ```c++ 148 // 设置软件流控 149 OH_UsbSerial_SetFlowControl(dev, USB_SERIAL_SOFTWARE_FLOW_CONTROL); 150 151 // 清空缓冲区 152 OH_UsbSerial_Flush(dev); 153 154 // 清空输入缓冲区 155 OH_UsbSerial_FlushInput(dev); 156 157 // 清空输出缓冲区 158 OH_UsbSerial_FlushOutput(dev); 159 ``` 1605. 向USB串口设备写入/读取数据。 161 162 使用 **usb_serial_api.h** 的 **OH_UsbSerial_Write** 给设备发送数据，并使用 **OH_UsbSerial_Read** 读取设备发送过来的数据。 163 164 ```c++ 165 uint32_t bytesWritten = 0; 166 // 测试设备读取指令，具体指令根据设备协议而定 167 uint8_t writeBuff[8] = {0x01, 0x03, 0x00, 0x00, 0x00, 0x01, 0x84, 0xA}; 168 // 发送数据 169 OH_UsbSerial_Write(dev, writeBuff, sizeof(writeBuff), &bytesWritten); 170 171 // 接收数据 172 uint8_t readBuff[100]; 173 uint32_t bytesRead = 0; 174 OH_UsbSerial_Read(dev, readBuff, sizeof(readBuff), &bytesRead); 175 ``` 176 1776. 关闭USB串口设备。 178 179 在所有请求处理完毕，程序退出前，使用 **usb_serial_api.h** 的 **OH_UsbSerial_Close** 关闭设备。 180 ```c++ 181 // 关闭设备 182 OH_UsbSerial_Close(&dev); 183 ``` 184 1857. 释放DDK。 186 187 在关闭USB串口设备后，使用 **usb_serial_api.h** 的 **OH_UsbSerial_Release** 释放DDK。 188 189 ```c++ 190 // 释放USB Serial DDK 191 OH_UsbSerial_Release(); 192 ``` 193 194### 调测验证 195 196驱动应用侧开发完成后，可在OpenHarmony设备上安装应用，测试步骤如下： 197 1981. 在设备上点击驱动应用，应用在设备上被拉起。 1992. 点击波特率等设置按钮，可以设置串口属性。 2003. 点击数据读取按钮，可以读取到串口设备数据。 201
