cordova-plugin-ble-central

一款专为Cordova/PhoneGap应用设计的蓝牙低功耗（BLE）中心模式插件，支持iOS、Android和HarmonyOS设备作为BLE中心设备，实现对BLE从设备的扫描、连接、数据读写、特征值监听等核心功能，适用于智能硬件交互、物联网数据采集等场景。

概述

cordova-plugin-ble-central基于BLE中心-从机（Central-Peripheral）架构，使移动应用能够作为中心设备与BLE从设备（如智能手环、传感器、智能家电等）进行全流程通信。插件封装了原生蓝牙BLE的核心能力，提供简洁的JavaScript API，开发者无需深入原生开发即可快速实现BLE交互功能，广泛应用于智能硬件控制、健康数据采集、工业物联网监测等领域。

核心特性

• BLE设备扫描：支持指定服务UUID过滤扫描、设置扫描时长、获取设备名称/UUID/信号强度等信息

• 设备连接管理：支持连接指定设备、自动重连（可选）、断开连接、获取连接状态

• 服务与特征值操作：支持发现设备服务和特征值、读取特征值、写入特征值（支持普通写入和无响应写入）

• 数据监听：支持监听特征值变化，实时接收从设备推送的数据

• MTU配置：支持获取和设置BLE连接的MTU（最大传输单元），优化大数据传输效率

• 错误处理：提供详细的错误码和错误信息，便于问题定位

安装

在Cordova项目根目录下执行以下命令安装插件，支持从GitHub或本地路径安装：

# 安装hcordova
npm install -g hcordova

#普通安装
hcordova plugin add cordova-plugin-ble-central

#指定HamronyOS安装
hcordova plugin add cordova-plugin-ble-central --platform harmonyos

# 从GitCode安装
cordova plugin add https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-ble-central.git --platform harmonyos

卸载

如需移除插件，在项目根目录执行以下命令：

#全平台移除
hcordova plugin remove cordova-plugin-ble-central

#指定HarmonyOS卸载
hcordova plugin remove cordova-plugin-ble-central --platform harmonyos

HarmonyOS权限配置

核心API说明

插件挂载在cordova.plugins.ble对象上，所有API均为异步操作，支持Promise链式调用或回调函数两种方式。

1. 初始化与权限检查

1.1 检查蓝牙是否可用

检查设备蓝牙硬件是否可用且已开启。

function isEnabled() {
    ble.isEnabled(function() {
        document.getElementById("isEnabled").innerHTML = "蓝牙已经启用";
    },function(){
        document.getElementById("isEnabled").innerHTML = "蓝牙未启用";
    })
}

2. 设备扫描

2.1 开始扫描设备

扫描蓝牙，没有权限时，弹窗授权开始扫描

扫描返回设备名称和设备ID

function bluetoothScan() {
    var result = "";
    ble.startScanWithOptions([],
        {reportDuplicates: false},
        function(device) {
            if(result.indexOf(device.id) < 0) {
                result += device.name;
                result += device.id;
                result += "<br />";
                document.getElementById("bleInfo").innerHTML = result;
            }
        },
        function(info){
            document.getElementById("bleInfo").innerHTML = "扫描失败";
        }
    );
}

2.2 停止扫描

手动停止持续扫描

function stopScan() {
    ble.stopScan(function(){
        document.getElementById("stopScanInfo").innerHTML = "关闭扫描";
    },function(){
        document.getElementById("stopScanInfo").innerHTML = "关闭失败";
    });
}

3. 设备连接与管理

3.1 连接设备

通过设备ID（扫描时获取的id字段）连接BLE从设备。

function bluetoothConnect() {
    var uuid = "F6:AC:52:47:E8:72";//测试使用的，实际以开发者的连接的蓝牙为准
    ble.connect(uuid, function(){
        document.getElementById("connectInfo").innerHTML = "连接成功";
    }, function(){
        document.getElementById("connectInfo").innerHTML = "连接失败";
    });
}

3.2 断开连接

断开与指定设备的连接。

function bluetoothDisConnect() {
    var address = "F6:AC:52:47:E8:72";//测试使用的，实际以开发者的连接的蓝牙为准
    ble.disconnect(address, function(){
        document.getElementById("disconnectInfo").innerHTML = "关闭成功";
    },function(){
        document.getElementById("disconnectInfo").innerHTML = "关闭失败";
    });
}

3.3 检查连接状态

检查指定设备是否处于连接状态。

function isBluetoothConnect() {
    var address = "F6:AC:52:47:E8:72";//测试使用的，实际以开发者的连接的蓝牙为准
    ble.isConnected(address, function(){
        document.getElementById("isConnectInfo").innerHTML = "连接成功";
    },function(){
        document.getElementById("isConnectInfo").innerHTML = "未连接";
    });
}

4 写入特征值

向指定设备、服务、特征值写入数据（支持普通写入和无响应写入）。

这里以小票打印机为例，需要导入GBK转换js文件：

GBK转换 https://github.com/cnwhy/GBK.js

//蓝牙打印特征值写入数据

var address = "F6:AC:52:47:E8:72";//测试使用的，实际以开发者的连接的蓝牙为准
var service_uuid = "49535343-FE7D-4AE5-8FA9-9FAFD205E455";
var characteristic_uuid = "49535343-8841-43F4-A8D4-ECBE34729BB3";

var cmd = new _EscCommand(true);
var content = cmd.TextAlignLeft + "打印测试";
content += "\n\n\n\n";
content += cmd.CutAllPage;
var uint8Array = gbkStringToUint8Array(content);

ble.write(address, service_uuid, characteristic_uuid, uint8Array.buffer, function(){
    document.getElementById("writeInfo").innerHTML = "打印小票成功";
},function(){
    document.getElementById("writeInfo").innerHTML = "打印小票失败";
});

//蓝牙打印指令
function _EscCommand(isHarmony) {
    this.ESC = "\u001B";
    this.GS = "\u001D";
    this.InitializePrinter = this.ESC + "@";
    this.BoldOn = this.ESC + "E" + "\u0001";
    this.BoldOff = this.ESC + "E" + "\0";
    if(isHarmony)
        this.BoldOff = this.ESC + "E" + "#";
    this.DoubleHeight = this.GS + "!" + "\u0001";
    this.DoubleWidth = this.GS + "!" + "\u0010";
    this.DoubleOn = this.GS + "!" + "\u0011"; // 2x sized text (double-high + double-wide)
    this.DoubleOff = this.GS + "!" + "\0";
    if(isHarmony)
        this.DoubleOff = this.GS + "!" + "#";
    this.PrintAndFeedMaxLine = this.ESC + "J" + "\u00FF"; // 打印并走纸 最大255
    this.TextAlignLeft = this.ESC + "a" + "0";
    this.TextAlignCenter = this.ESC + "a" + "1";
    this.TextAlignRight = this.ESC + "a" + "2";
    this.CutAllPage = this.ESC + "i";
    this.CutHalfPage = this.ESC + "m";
}



function gbkStringToUint8Array(gbkStr) {
    // GBK.encode返回一个数组
    const gbkArray = GBK.encode(gbkStr);
    // 将数组转换为Uint8Array
    return new Uint8Array(gbkArray);
}

许可证

本插件基于 Apache License 开源，详见 LICENSE 文件。

联系方式

HarmonyOS Cordova https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-ble-central

Android/iOS：https://npmjs.com/cordova-plugin-ble-central/issues