更新记录

4.0.94（2026-06-12） 下载此版本

新建

平台兼容性

uni-app x(5.0)

其他

Uni-dlms-Plugin 使用说明

1. 插件简介

Uni-dlms-Plugin 是一个 uni-app 原生插件，用于在 Android 侧基于 Gurux DLMS 库生成和维护 DLMS/COSEM 会话相关报文。

这个插件的职责是：

• 创建和维护本地 DLMS 会话
• 生成 SNRM、AARQ、读、写、释放、断开等十六进制报文
• 接收并解析设备返回的关键响应报文，推进会话状态

这个插件不负责：

• 蓝牙收发
• 串口收发
• TCP/UDP 通信
• 设备连接管理

也就是说，插件只负责“生成要发给设备的报文”和“把设备回包喂回会话”，实际通信链路需要由业务层自己实现。

2. 插件信息

• 插件名称：Uni-dlms-Plugin
• 插件 ID：Uni-dlms-Plugin
• Android 模块类：com.fd.dlms.DlmsModule
• 集成方式：aar

相关文件：

• 插件描述文件：package.json
• 示例页面：dlms-module.vue
• Android AAR 输出目录：dlms/build/outputs/aar

3. AAR 产物说明

当前工程 :dlms 模块已配置版本号 4.0.94，执行以下命令可生成发布包：

.\gradlew.bat :dlms:assembleRelease

默认生成文件：

• dlms-4.0.94-release.aar

如果你要把该插件交付给 uni-app 原生插件目录使用，建议将最新生成的 AAR 拷贝或替换到插件目录中，保证插件目录内的 AAR 与当前版本一致。

4. 集成方式

4.1 在 uni-app 项目中集成

将 Uni-dlms-Plugin 整个目录放入项目的原生插件目录中，并确保其中包含：

• package.json
• Android AAR 文件

推荐目录结构如下：

项目根目录
└─ nativeplugins
   └─ Uni-dlms-Plugin
      ├─ package.json
      ├─ 使用说明.md
      └─ android
        └─dlms-4.0.94-release.aar

如果你的项目已经约定了其他原生插件目录，也可以按项目规范放置，但需要保证构建工具能够识别到 package.json 和对应的 AAR。

4.2 uni-app 中引用插件

然后在 App 端通过以下方式获取插件实例：

const dlmsPlugin = uni.requireNativePlugin('Uni-dlms-Plugin')

说明：

• 仅 APP-PLUS 环境可用
• H5、小程序环境下不可用

建议写法：

let dlmsPlugin = null

// #ifdef APP-PLUS
dlmsPlugin = uni.requireNativePlugin('Uni-dlms-Plugin')
// #endif

4.3 manifest.json / manifest.config.ts 中声明插件

在 uni-app 项目里引入原生插件后，还需要在应用配置中声明插件信息。

如果你使用的是传统 manifest.json 方式，需要声明 nativePlugins。

如果你当前项目使用的是 manifest.config.ts，则需要在 plugins 中加入如下配置：

plugins: {
  'Uni-dlms-Plugin': {
    __plugin_info__: {
      name: 'Uni-dlms-Plugin',
      description: 'DLMS native plugin',
      platforms: 'Android',
      url: '',
      android_package_name: '',
      ios_bundle_id: '',
      isCloud: false,
      bought: -1,
      pid: '',
      parameters: {},
    },
  },
},

说明：

• plugins 的 key 必须与 uni.requireNativePlugin('Uni-dlms-Plugin') 中的名称一致
• 当前插件仅支持 Android，因此 platforms 填 Android
• 如果后续有插件市场信息，可再补充 url、pid 等字段

4.4 运行方式说明

接入原生插件后，不能仅通过普通 Web 预览或普通运行方式验证插件能力。

需要使用：

• Android 自定义基座
• 或集成了该插件的原生 Android 工程

也就是说，插件接入完成后，通常还需要重新打包自定义基座，再在真机环境中运行测试。

5. 自定义基座与证书说明

5.1 为什么需要自定义基座

Uni-dlms-Plugin 属于 Android 原生插件，只有在已经集成该 AAR 的自定义基座或原生 APK 中，uni.requireNativePlugin('Uni-dlms-Plugin') 才能正确获取到插件实例。

如果没有重新打包自定义基座，常见现象包括：

• 获取不到插件实例
• 页面提示插件未加载
• 原生能力无法调用

5.2 打包自定义基座前需要准备证书

在打包 Android 自定义基座时，需要准备签名证书。

通常需要准备的信息包括：

• 证书文件
• 证书别名
• 证书密码
• 别名密码

5.3 证书生成说明

证书生成请按 uni-app / Android 标准签名流程自行处理。

本文档不展开证书生成步骤，接入方可自行搜索以下方向：

• uni-app 自定义基座 证书生成
• Android keystore 生成
• JKS 签名证书生成

5.4 推荐联调流程

推荐流程如下：

1. 将插件目录放入 uni-app 项目指定原生插件目录
2. 在 manifest.config.ts 中声明 plugins
3. 准备 Android 签名证书
4. 打包自定义基座
5. 安装自定义基座到真机
6. 运行 uni-app 页面并调用插件

6. 返回值约定

5.1 成功返回

插件成功时直接通过回调返回业务数据，不统一包一层 ok 字段。

常见成功返回类型：

• String：如 sessionId、单条十六进制报文
• String[]：如多包报文
• Boolean：如关闭会话、判断是否需要认证

5.2 失败返回

插件发生异常时，回调返回对象格式如下：

{
  "code": -1,
  "message": "错误信息",
  "type": "异常类型"
}

示例：

{
  "code": -1,
  "message": "Session not found: xxx",
  "type": "IllegalArgumentException"
}

7. API 与签名方法

7.1 关键参数说明

7.2 示例

dlmsPlugin.createSession(
  true,
  16,
  1,
  'NONE',
  '',
  'HDLC',
  result => {
    console.log('sessionId:', result)
  }
)

8. 典型调用流程

推荐的标准流程如下：

1. 调用 createSession 创建本地会话
2. 调用 openSessionRequestHex 生成 SNRM
3. 通过蓝牙、串口或 TCP 将 SNRM 发送给设备
4. 收到设备 UA 后调用 applyOpenSessionResponse
5. 调用 associationRequestHex 生成 AARQ
6. 发送 AARQ 给设备
7. 收到设备 AARE 后调用 applyAssociationResponse
8. 如有需要，调用 isAuthenticationRequired
9. 调用 readRequestHex 或 writeRequestHex 执行业务读写
10. 结束时调用 releaseRequestHex 或 disconnectRequestHex
11. 最后调用 closeSession 清理本地会话

9. 完整示例

let dlmsPlugin = null

// #ifdef APP-PLUS
dlmsPlugin = uni.requireNativePlugin('Uni-dlms-Plugin')
// #endif

function createDlmsSession() {
  return new Promise((resolve, reject) => {
    dlmsPlugin.createSession(true, 16, 1, 'NONE', '', 'HDLC', result => {
      if (result && result.code === -1) {
        reject(result)
        return
      }
      resolve(result)
    })
  })
}

function getSnrm(sessionId) {
  return new Promise((resolve, reject) => {
    dlmsPlugin.openSessionRequestHex(sessionId, result => {
      if (result && result.code === -1) {
        reject(result)
        return
      }
      resolve(result)
    })
  })
}

function applyUa(sessionId, uaHex) {
  return new Promise((resolve, reject) => {
    dlmsPlugin.applyOpenSessionResponse(sessionId, uaHex, result => {
      if (result && result.code === -1) {
        reject(result)
        return
      }
      resolve(result)
    })
  })
}

10. 枚举值说明

插件内部对部分字符串枚举做了容错处理：

• 不区分大小写
• 支持中划线自动转下划线
• 支持空格自动转下划线

例如以下写法通常都能被识别：

• none
• NONE
• octet-string
• octet string
• OCTET_STRING

默认值：

• authentication 默认值：NONE
• interfaceType 默认值：HDLC
• objectType 默认值：DATA
• dataType 默认值：STRING

11. 注意事项

• 插件仅支持 Android
• 插件仅适用于 APP-PLUS
• 插件联调需要基于自定义基座或已集成插件的原生包运行
• sessionId 必须由 createSession 返回，不可自行伪造
• associationRequestHex、readRequestHex、writeRequestHex 可能返回多包数组，业务层发送时要按顺序处理
• 插件不负责自动重试、超时控制、分包重发
• 报文入参要求为十六进制字符串，允许带空格和换行
• 若十六进制字符串长度为奇数或包含非法字符，插件会抛出错误

12. 常见问题

11.1 uni.requireNativePlugin 获取不到插件

请检查：

• 是否运行在 APP-PLUS
• 插件目录是否已正确集成
• AAR 是否已放入原生插件目录
• 自定义基座或原生工程是否重新构建

12.2 为什么已经放了插件还是不能调用

常见原因是还没有重新打包自定义基座。

原生插件不会自动出现在默认运行容器中，只有在包含该插件 AAR 的自定义基座或原生包中才可用。

12.3 返回 Session not found

说明传入的 sessionId 无效，常见原因：

• 会话尚未创建
• 会话已被 closeSession 清理
• 页面刷新后本地变量丢失

12.4 打包自定义基座时提示签名或证书问题

请检查：

• 是否已经生成 Android 签名证书
• 证书路径是否正确
• 别名、证书密码、别名密码是否填写正确
• 打包配置中是否引用了对应证书

12.5 为什么插件没有直接返回读结果

因为当前插件只负责“生成请求报文”和“推进会话状态”，并不接管通信链路，也不直接解析完整业务读值。实际读写结果仍需要业务层和设备交互后自行处理。

13. 推荐交付方式

对外提供插件时，建议至少包含以下内容：

• package.json
• 当前版本的 Android AAR
• 本使用说明
• 一个最小调用示例页面

如果当前插件目录里的 AAR 仍是旧文件名，建议将最新生成的 dlms-4.0.94-release.aar 一并同步过去，避免交付版本与源码版本不一致。