标签：鸿蒙、OpenHarmony、USB DDK、ACCESS_DDK_USB、HAP 安装、DevEco Studio、身份证读卡器、外设开发

---

🔥 前言

最近在做鸿蒙系统下USB 东信EST-100身份证阅读器对接开发，新手容易犯的错误，都体验了一把：包名冲突、权限申请、HAP 签名安装、OpenHarmony 重启失效等。本文基于 DevEco Studio 6.0.2 Release，

完整记录：

✅ 工程创建 ✅ SDK 配置 ✅ AGC 权限申请 ✅ 读卡 SDK 集成 ✅ HAP 安装

一套流程直接跑通，适合做鸿蒙外设、USB 驱动、读卡器开发的同学参考。

---

📌 一、开发环境与 SDK 要求

1. 开发工具

• IDE：DevEco Studio 6.0.2 Release
• SDK 路径：E:\ADevEcoStudioSDK（可自定义）
• 

2. 强制版本要求

• 最低 API 11，低于 11 不支持 USB DDK
• HarmonyOS / OpenHarmony 配置分开处理
• 

---

📌 二、新建 Empty Ability 工程

1. Create Project → 选择 Empty Ability
2. 项目配置关键点：
   • Project name：自定义（如simpledemo）
   • Bundle name：必须改成自己的！（默认com.example.donseereader会冲突）
   • Compatible SDK：4.1.0 (11) 及以上
   • Device type：Phone/Tablet/2in1
3. 等待工程同步完成。

---

📌 三、核心配置：HarmonyOS vs OpenHarmony

1. HarmonyOS 配置（build-profile.json5）

json

"products": [
  {
    "name": "default",
    "signingConfig": "default",
    "compatibleSdkVersion": "4.1.0(11)",
    "runtimeOS": "HarmonyOS",
    "targetSdkVersion": "5.1.1(19)"
  }
]

2. OpenHarmony 配置（必须改，否则重启 APP 失效）

json

"products": [
  {
    "name": "default",
    "signingConfig": "default",
    "targetSdkVersion": 20,
    "compatibleSdkVersion": 20,
    "compileSdkVersion": 20,
    "runtimeOS": "OpenHarmony",
    "buildOption": {
      "strictMode": {
        "caseSensitiveCheck": true,
        "useNormalizedOHMUrl": true
      }
    }
  }
]

---

📌 四、2 个高频报错 100% 解决

❌ 报错 1：Bundle name already in use（包名被占用）

原因：Demo 默认包名重复解决：Project Structure → Modules → 直接修改 Bundle name 为自定义即可。

---

❌ 报错 2：缺少 ACCESS_DDK_USB 权限

原因：USB DDK 是受限权限，必须去 AGC 平台申请解决：下文完整权限申请流程

---

📌 五、AGC 申请 ACCESS_DDK_USB 权限（必看）

1. 打开华为开发者官网：https://developer.huawei.com/consumer/cn/
2. 进入你的应用 → 开放能力管理 → ACL 权限
3. 搜索并勾选申请：
   • ohos.permission.ACCESS_DDK_USB
   • ohos.permission.ACCESS_DDK_USB_SERIAL
4. 申请原因示例：

   公司产品基于鸿蒙系统，需要使用 USB 读卡器，申请 USB DDK 权限

5. 提交后重新签名即可拿到临时证书调试，不用等审核完成。
6. 
7. 
8. 

---

📌 六、工程内声明权限配置

1. module.json5 添加权限

json

"requestPermissions": [
  {
    "name": "ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER"
  },
  {
    "name": "ohos.permission.ACCESS_DDK_USB",
    "reason": "$string:ddk_usb_reason_text",
    "usedScene": {
      "abilities": ["DriverExtAbility"],
      "when": "inuse"
    }
  }
]

2. string.json 添加权限描述

json

{
  "name": "ddk_usb_reason_text",
  "value": "申请ACCESS_DDK_USB权限"
}

---

📌 七、集成东信EST-100身份证阅读器  DonseeDeviceLib 读卡 SDK

步骤 1：放入 HAR 包

将 DonseeDeviceLib.har 复制到：entry/src/libs

步骤 2：oh-package.json5 添加依赖

json

"dependencies": {
  "donseedevicelib": "file:./src/libs/DonseeDeviceLib.har"
}

步骤 3：ETS 页面导入类

typescript

运行

import DonseeDevice from 'donseedevicelib/src/main/ets/model/DonseeDevice';
import { IDCardInfor } from 'donseedevicelib/src/main/ets/model/IDCardInfor';

步骤 4：调用读卡 API

typescript

运行

// 打开USB读卡器
let ret = DonseeDevice.Donsee_Open("USB");

// 读取身份证
let idInfo: IDCardInfor = DonseeDevice.Donsee_ReadIDCard(1);

---

📌 八、获取 UDID + HAP 安装命令（hdc_std）

1. 先连接设备调试 USB 口

2. 常用命令（直接复制用）

cmd

:: 查看设备是否连接
hdc_std list targets

:: 获取设备UDID（发给开发打签名用）
hdc_std shell bm get -u

:: 首次安装
hdc_std install entry-default-signed.hap

:: 覆盖安装（升级）
hdc_std install -r entry-default-signed.hap

:: 卸载应用
hdc_std uninstall com.example.donseereader

:: 查看所有包名
hdc_std shell bm dump -a

---

📌 九、安装失败 code:9568289 解决

错误信息：install failed due to grant request permissions failed解决方法：

1. 确认 AGC 已申请ACCESS_DDK_USB
2. 重新配置签名
3. Rebuild Project
4. 再次执行 hdc 安装命令

---

📌 十、运行效果

成功运行后可实现：

• USB 读卡器打开 / 连接
• 身份证信息完整读取：姓名、性别、民族、出生日期、住址、身份证号、签发机关、有效期

---

📌 十一、流程总结（一张图记住）

1. 新建工程 → 改包名
2. 配置 build-profile.json5
3. 声明 DDK 权限
4. AGC 申请权限
5. 集成读卡 SDK
6. 编译签名 HAP
7. hdc 获取 UDID、安装 HAP
8. 运行读卡测试

---

📌 总结

本文覆盖鸿蒙 USB 外设开发从 0 到 1，解决最痛的 3 个问题：✅ 包名冲突✅ ACCESS_DDK_USB 权限申请✅ HAP 安装失败如果你在做：身份证读卡器、社保卡读卡器、USB 外设、鸿蒙 DDK 驱动开发，这篇文章可以直接当手册用。

---

👉 欢迎交流

有问题直接评论区留言，我会一一回复～点赞 + 收藏 + 关注，持续更新鸿蒙外设开发实战！