鸿蒙操作系统使用 Driver Development Kit 开发扩展外设驱动实战
一、背景说明
鸿蒙装机量本周正式突破 1 亿台,HarmonyOS 7 设备占比已超 82%,二合一平板、鸿蒙电脑等带 USB 扩展能力的设备越来越多——为非标外设(定制键盘、串口模块、专用读卡器)开发"即插即用"的驱动应用,正成为新的开发场景。本文聚焦一个具体技术点:使用 Driver Development Kit 的 DriverExtensionAbility 开发一个用户态扩展外设驱动,实现设备枚举、驱动绑定与 RPC 通信的完整闭环,全部代码可直接编译运行(需在 2in1/平板等支持扩展外设的设备上验证)。
二、技术原理
HarmonyOS 把"外设驱动"做成了应用形态:驱动就是一个普通 HAP,内核侧由 HDF 扩展驱动框架承接,用户态由 DriverExtensionAbility 承载,核心概念如下:
- DriverExtensionAbility:
type: driver类型的扩展组件,生命周期由系统外设扩展服务 SA 管理。外设插入(VID+PID 匹配)时拉起,拔出后销毁;生命周期回调onInit → onConnect → onDisconnect → onRelease。 - onConnect 返回 RemoteObject:驱动服务端在
onConnect中返回一个rpc.RemoteObject桩实例,客户端应用通过它做 IPC 通信——这是驱动与业务应用的标准数据通道。 - deviceManager(@ohos.driver.deviceManager):客户端 API,
queryDevices()枚举已接入的扩展外设,bindDeviceDriver()绑定设备对应的驱动服务端。 - DDK(Driver Development Kit):C 语言套件(HidDdk/UsbDdk/USBSerialDDK/ScsiPeripheralDDK),仅在 DriverExtension 进程内可用,用于与物理设备读写报文。
数据流:外设插入 → 系统按 VID/PID 匹配并拉起 DriverExtensionAbility → 客户端 bindDeviceDriver 拿到 RemoteObject → sendMessageRequest 走 RPC → 驱动侧 onRemoteMessageRequest 处理 →(经 DDK 与硬件交互)→ reply 返回结果。
三、实现步骤
工程为 Stage 模型,目标设备为 2in1/平板(API 12+,DDK C-API 建议 API 18+)。需声明扩展外设权限:
{
"module": {
"requestPermissions": [
{ "name": "ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER" }
]
}
}
1. module.json5 注册驱动组件
关键是 type: driver 与 metadata 中的总线、VID/PID 匹配列表:
{
"extensionAbilities": [
{
"name": "DriverExtAbility",
"icon": "$media:startIcon",
"description": "demo usb driver",
"type": "driver",
"exported": true,
"srcEntry": "./ets/driverextability/DriverExtAbility.ets",
"metadata": [
{ "name": "bus", "value": "USB" },
{ "name": "desc", "value": "the sample of driverExtensionAbility" },
{ "name": "vendor", "value": "demo" },
{ "name": "vid", "value": "0x12D1" },
{ "name": "pid", "value": "0x10A2" },
{ "name": "launchOnBind", "value": "true" },
{ "name": "ohos.permission.ACCESS_DDK_ALLOWED", "value": "true" }
]
}
]
}
2. 驱动服务端 DriverExtAbility.ets
重写生命周期,并在 onConnect 中返回 RPC 桩——客户端发来的请求在这里处理:
import { DriverExtensionAbility } from '@kit.DriverDevelopmentKit';
import { Want } from '@kit.AbilityKit';
import { rpc } from '@kit.IPCKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
const TAG: string = 'DriverExt';
const REQUEST_CODE = 99; // 与客户端约定的请求码
// RPC 桩:处理客户端发来的消息
class DriverStub extends rpc.RemoteObject {
constructor(des: string) {
super(des);
}
onRemoteMessageRequest(code: number, data: rpc.MessageSequence,
reply: rpc.MessageSequence, option: rpc.MessageOption): boolean {
if (code === REQUEST_CODE) {
// 客户端可多次 writeString 写入多段数据,这里按序读出
const optFirst: string = data.readString();
hilog.info(0xFF00, TAG, `recv from client: ${optFirst}`);
// 处理结果回写给客户端(真实场景可在此经 DDK 与硬件交互)
reply.writeString(optFirst + ' World');
}
return true;
}
}
export default class DriverExtAbility extends DriverExtensionAbility {
onInit(want: Want) {
hilog.info(0xFF00, TAG, `onInit, want: ${want.abilityName}`);
// 可在此初始化 USB DDK / HID DDK 等原生能力
}
onRelease() {
hilog.info(0xFF00, TAG, 'onRelease');
}
// 外设客户端绑定成功时回调,返回驱动服务端的 RPC 桩
onConnect(want: Want): rpc.RemoteObject {
hilog.info(0xFF00, TAG, `onConnect, want: ${want.abilityName}`);
return new DriverStub('driverStub');
}
onDisconnect(want: Want) {
hilog.info(0xFF00, TAG, `onDisconnect, want: ${want.abilityName}`);
}
onDump(params: Array<string>) {
return ['driver dump'];
}
}
3. 客户端:枚举设备并绑定驱动(Index.ets)
业务应用用 deviceManager 查询设备、绑定驱动、发起 RPC 请求:
import { deviceManager } from '@kit.DriverDevelopmentKit';
import { rpc } from '@kit.IPCKit';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct Index {
@State log: string = '';
private remote: rpc.RemoteObject | null = null;
// 枚举扩展外设并绑定对应驱动
bindDriver(): void {
deviceManager.queryDevices(deviceManager.BusType.BUS_TYPE_USB)
.then((devices: Array<deviceManager.USBDevice>) => {
if (devices.length === 0) {
this.log = '未接入扩展外设';
return;
}
const target = devices[0];
return deviceManager.bindDeviceDriver(target.deviceId,
(error: BusinessError, remote: rpc.RemoteObject) => remote,
(err: BusinessError, remote: rpc.RemoteObject) => {
if (err) {
this.log = `绑定失败 code=${err.code}`;
return;
}
this.remote = remote;
this.log = '设备已连接,可发送请求';
});
})
.catch((err: BusinessError) => {
this.log = `query failed code=${err.code}`;
});
}
// 发送 RPC 请求:发送 "Hello",期望返回 "Hello World"
sendRequest(): void {
if (!this.remote) {
this.log = '请先绑定驱动';
return;
}
const data = rpc.MessageSequence.create();
const reply = rpc.MessageSequence.create();
data.writeString('Hello');
this.remote.sendMessageRequest(99, data, reply, { async: true })
.then(() => {
this.log = `驱动返回:${reply.readString()}`;
data.reclaim();
reply.reclaim();
})
.catch((err: BusinessError) => {
this.log = `request failed code=${err.code}`;
});
}
build() {
Column({ space: 12 }) {
Button('绑定驱动').onClick(() => { this.bindDriver(); })
Button('发送请求').onClick(() => { this.sendRequest(); })
Text(this.log || '操作日志')
.fontSize(13)
.width('90%')
.height(100)
.backgroundColor('#F2F3F5')
.padding(8)
.borderRadius(8)
}
.width('100%')
.height('100%')
.justifyContent(FlexAlign.Center)
}
}
四、应用场景示例
接入真实硬件时,驱动服务端在 onRemoteMessageRequest 内通过 DDK 读写设备——以 USB 串口(USBSerialDDK)读取传感器数据为例(C API 在 Native 侧封装、经 NAPI 暴露给上例的 RPC 处理函数调用):
#include "usb_serial_ddk.h"
// 读取 64 字节传感器报文(仅 DriverExtension 进程内可调用)
int32_t ReadSensor(uint64_t deviceId, uint8_t *out, uint32_t bufSize) {
USBDeviceHandle *dev = nullptr;
int32_t ret = OH_UsbSerial_Open(deviceId, 0, &dev); // 打开指定设备
if (ret != USB_SERIAL_DDK_SUCCESS) { return ret; }
uint32_t bytesRead = 0;
ret = OH_UsbSerial_Read(dev, out, bufSize, &bytesRead, 1000); // 1s 超时
OH_UsbSerial_Close(&dev);
return ret;
}
五、技术要点
1. 生命周期与设备绑定
DriverExtensionAbility 的存活时间与外设接入时段一致:单设备插入即拉起、拔出即销毁;多个外设依次接入时生命周期从第一个插入持续到最后一个拔出。多驱动声明了同一 VID+PID 时,只有最先安装的驱动会被拉起。
2. RPC 通信规范
onRemoteMessageRequest中参数顺序为 code→data→reply→option,读数据用data.readString()、写结果用reply.writeString();MessageSequence用完必须reclaim()手动回收,否则内存持续增长;- 请求码(如 99)由业务自定义,用于在回调中区分不同请求类型。
3. 错误处理
try {
await deviceManager.bindDeviceDriver(deviceId, cb, cb);
} catch (err) {
const e = err as BusinessError;
if (e.code === 401) {
console.error('参数错误或缺少 ACCESS_EXTENSIONAL_DEVICE_DRIVER 权限');
} else {
console.error(`bind failed code=${e.code}, msg=${e.message}`);
}
}
4. 使用限制
- DDK 的 C-API(HidDdk/UsbDdk 等)只能在 DriverExtension 进程内调用,在子进程或其他 Ability 中调用会失败;
- 客户端如需使用 DDK 相关能力,需申请
ohos.permission.ACCESS_DDK_DRIVERS并在 HarmonyAppProvision 的 acls 中跨级别申请; - 扩展外设框架目前仅支持标准系统设备(2in1、平板等),SDK 建议 API 18 及以上。
六、扩展建议
- HID 协议驱动:用 HidDdk 的
OH_Hid_EmitEvent/OH_Hid_GetReport实现非标键盘、手柄驱动的输入输出报告交互; - 边接收边上报:驱动端开启非阻塞读取(
OH_Hid_SetNonBlocking),配合会话内定时把传感器数据推送给客户端; - 设备元数据:客户端可用
deviceManager.queryDevices返回的 USBDevice 信息(vid/pid/名称)做设备白名单校验:
const matched = devices.find((d: deviceManager.USBDevice) =>
d.vendorId === 0x12D1 && d.productId === 0x10A2);
结语
本文用 Driver Development Kit 完成了鸿蒙扩展外设驱动从组件注册、生命周期管理到 RPC 双向通信的完整实现,核心代码约 170 行,均可直接编译运行(真机需支持扩展外设)。掌握 DriverExtensionAbility 与 deviceManager 的配合方式后,为非标外设提供"即插即用"的系统级驱动应用就有了清晰的工程路径。
更多推荐




所有评论(0)