一、背景说明

鸿蒙装机量本周正式突破 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 及以上。
六、扩展建议
  1. HID 协议驱动:用 HidDdk 的 OH_Hid_EmitEvent/OH_Hid_GetReport 实现非标键盘、手柄驱动的输入输出报告交互;
  2. 边接收边上报:驱动端开启非阻塞读取(OH_Hid_SetNonBlocking),配合会话内定时把传感器数据推送给客户端;
  3. 设备元数据:客户端可用 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 的配合方式后,为非标外设提供"即插即用"的系统级驱动应用就有了清晰的工程路径。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐