Flutter 与开源鸿蒙（OpenHarmony）蓝牙外设通信实战：连接打印机、扫码枪与工业传感器

2501_94551709

636人浏览 · 2025-12-25 15:07:48

2501_94551709 · 2025-12-25 15:07:48 发布

Flutter 与开源鸿蒙（OpenHarmony）蓝牙外设通信实战：连接打印机、扫码枪与工业传感器

作者：子榆.
平台：CSDN
日期：2025年12月24日
关键词：Flutter、OpenHarmony、蓝牙、BLE、外设通信、信创、物联网

引言：让 Flutter 应用“听得见”硬件的声音

在政务大厅、仓储物流、智能制造等场景中，移动终端需频繁与 蓝牙外设 交互：

🖨️ 便携打印机：现场打印回执单
🔍 扫码枪：快速录入商品条码
🌡️ 工业传感器：采集温湿度、压力数据

然而，Flutter 官方 flutter_blue 插件 不支持 OpenHarmony，而 OpenHarmony 提供了完整的 蓝牙能力栈（Bluetooth Kit）。

🎯 本文目标：通过 NAPI 桥接 OpenHarmony 蓝牙 API，在 Flutter 应用中实现：

✅ 扫描并连接 BLE 外设

✅ 向打印机发送 ESC/POS 指令

✅ 接收扫码枪的 HID 数据

✅ 订阅传感器实时上报

并附完整代码、协议解析与真机演示。

一、OpenHarmony 蓝牙能力全景

能力	API 模块	适用设备
经典蓝牙（BR/EDR）	`@ohos.bluetooth`	打印机、扫码枪（HID/SPP）
低功耗蓝牙（BLE）	`@ohos.bluetooth.ble`	传感器、Beacon
GATT 服务发现	`GattClient`	自定义 BLE 设备
RFCOMM 串口	`SppClient`	工业串口设备

✅ 优势：

支持 后台持续连接（即使 App 进入后台）

提供 统一权限模型（BLUETOOTH + ACCESS_BLUETOOTH）

二、整体架构设计

[Flutter UI (Dart)]
        │
        ▼
[MethodChannel] ←─ 发起扫描、连接、发送
        │
        ▼
[NAPI Bridge (C++)]
        │
        ├──▶ [Bluetooth Manager] ←─ 控制蓝牙开关、扫描
        ├──▶ [GattClient / SppClient] ←─ 连接 BLE / 经典设备
        └──▶ [Data Parser] ←─ 解析 ESC/POS、HID、自定义协议
                │
                ▼
        [蓝牙外设] ←─ 打印机 / 扫码枪 / 传感器

💡 关键点：

不同设备使用不同通信协议（需分别处理）

数据回调通过 napi_ref 传回 Dart

三、开发准备

3.1 权限声明（module.json5）

{
  "module": {
    "requestPermissions": [
      { "name": "ohos.permission.USE_BLUETOOTH" },
      { "name": "ohos.permission.DISCOVER_BLUETOOTH" },
      { "name": "ohos.permission.ACCESS_BLUETOOTH" },
      { "name": "ohos.permission.LOCATION" } // Android 兼容要求（OHOS 实际不需要，但部分设备仍需）
    ]
  }
}

3.2 真机要求

支持 蓝牙 4.0+ 的 OpenHarmony 设备（如 MatePad、HiHope 开发板）
外设需处于 可被发现模式

四、Step 1：NAPI 封装蓝牙核心功能

4.1 初始化与扫描

// bluetooth_bridge.cpp
#include "bluetooth_host.h"
#include "hilog/log.h"

#define LOG_TAG "BtBridge"

static sptr<IBluetoothHost> g_bt_host = nullptr;
static std::vector<BluetoothRemoteDevice> g_discovered_devices;

// 扫描回调
class ScanCallback : public IBluetoothScanCallback {
public:
    void OnDeviceFound(const BluetoothRemoteDevice &device) override {
        g_discovered_devices.push_back(device);
        // 通知 Dart（通过保存的 callback ref）
        NotifyDartDeviceFound(device.GetDeviceName(), device.GetDeviceAddr());
    }
};

static napi_value StartScan(napi_env env, napi_callback_info info) {
    if (!g_bt_host) {
        g_bt_host = IBluetoothHost::GetDefaultHost();
    }
    
    static sptr<ScanCallback> callback = new ScanCallback();
    g_bt_host->StartBleScan(callback); // 或 StartClassicScan
    
    return nullptr;
}

4.2 连接经典蓝牙设备（如打印机）

// 使用 SPP（串口协议）
static sptr<ISppClient> g_spp_client = nullptr;

static napi_value ConnectPrinter(napi_env env, napi_callback_info info) {
    char addr[18];
    // 获取设备 MAC 地址参数
    
    SppConfig config;
    config.uuid = "00001101-0000-1000-8000-00805F9B34FB"; // SPP 标准 UUID
    
    g_spp_client = ISppClient::Create(config);
    int ret = g_spp_client->Connect(addr);
    
    if (ret == 0) {
        // 连接成功，启动接收线程
        std::thread([=]() {
            uint8_t buffer[1024];
            while (true) {
                int len = g_spp_client->Receive(buffer, sizeof(buffer));
                if (len > 0) {
                    // 打印机状态回执（如缺纸）
                    NotifyDartPrinterStatus(std::string((char*)buffer, len));
                }
            }
        }).detach();
    }
    
    return nullptr;
}

4.3 发送打印指令（ESC/POS）

static napi_value PrintText(napi_env env, napi_callback_info info) {
    char text[512];
    // 获取要打印的文本
    
    // 构造 ESC/POS 指令
    std::vector<uint8_t> cmd;
    cmd.insert(cmd.end(), {0x1B, 0x40}); // 初始化
    cmd.insert(cmd.end(), text, text + strlen(text));
    cmd.insert(cmd.end(), {0x0A, 0x0A, 0x1D, 0x56, 0x41, 0x03}); // 切纸
    
    if (g_spp_client) {
        g_spp_client->Send(cmd.data(), cmd.size());
    }
    
    return nullptr;
}

4.4 连接 BLE 传感器（GATT）

static sptr<IGattClient> g_gatt_client = nullptr;

static void OnCharacteristicChanged(
    const std::string &deviceId,
    const std::string &serviceUuid,
    const std::string &charUuid,
    const std::vector<uint8_t> &value
) {
    // 温湿度传感器示例：value = {0x12, 0x34} → 温度 0x1234 / 100 = 46.6℃
    float temp = (value[0] << 8 | value[1]) / 100.0f;
    NotifyDartSensorData(temp);
}

static napi_value ConnectSensor(napi_env env, napi_callback_info info) {
    char addr[18];
    // ...
    
    GattClientConfig config;
    config.deviceAddr = addr;
    config.onCharacteristicChanged = OnCharacteristicChanged;
    
    g_gatt_client = IGattClient::Create(config);
    g_gatt_client->Connect();
    
    // 启用通知
    g_gatt_client->EnableNotification("SERVICE_UUID", "CHAR_UUID");
    
    return nullptr;
}

五、Step 2：Flutter 端集成与 UI 构建

5.1 定义桥接类

// lib/bluetooth_bridge.dart
class BluetoothDevice {
  final String name;
  final String address;
  final bool isBle;

  BluetoothDevice(this.name, this.address, this.isBle);
}

class BluetoothBridge {
  static const _channel = MethodChannel('com.example/bluetooth');

  static Stream<BluetoothDevice> get onDeviceDiscovered async* {
    // 通过 EventChannel 监听设备发现
    final stream = EventChannel('com.example/bluetooth/device').receiveBroadcastStream();
    await for (var data in stream) {
      yield BluetoothDevice(
        data['name'],
        data['address'],
        data['isBle'],
      );
    }
  }

  static Future<void> startScan() async {
    await _channel.invokeMethod('startScan');
  }

  static Future<void> connectPrinter(String address) async {
    await _channel.invokeMethod('connectPrinter', address);
  }

  static Future<void> printText(String text) async {
    await _channel.invokeMethod('printText', text);
  }

  static Future<void> connectSensor(String address) async {
    await _channel.invokeMethod('connectSensor', address);
  }
}

5.2 构建外设管理界面

// lib/device_page.dart
class DevicePage extends StatefulWidget {
  @override
  _DevicePageState createState() => _DevicePageState();
}

class _DevicePageState extends State<DevicePage> {
  List<BluetoothDevice> _devices = [];
  String _status = '点击“扫描”查找设备';

  @override
  void initState() {
    super.initState();
    // 监听设备发现
    BluetoothBridge.onDeviceDiscovered.listen((device) {
      setState(() {
        _devices.add(device);
        _status = '发现 ${_devices.length} 台设备';
      });
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('蓝牙外设')),
      body: Column(
        children: [
          Padding(
            padding: EdgeInsets.all(16),
            child: Row(
              children: [
                ElevatedButton(
                  onPressed: () {
                    _devices.clear();
                    BluetoothBridge.startScan();
                  },
                  child: Text('扫描'),
                ),
                SizedBox(width: 10),
                Text(_status),
              ],
            ),
          ),
          Expanded(
            child: ListView.builder(
              itemCount: _devices.length,
              itemBuilder: (context, index) {
                var dev = _devices[index];
                return ListTile(
                  title: Text(dev.name),
                  subtitle: Text(dev.address),
                  trailing: ElevatedButton(
                    onPressed: () {
                      if (dev.name.contains('Printer')) {
                        _showPrintDialog(dev.address);
                      } else if (dev.name.contains('Sensor')) {
                        BluetoothBridge.connectSensor(dev.address);
                        ScaffoldMessenger.of(context).showSnackBar(
                          SnackBar(content: Text('已连接传感器'))
                        );
                      }
                    },
                    child: Text('连接'),
                  ),
                );
              },
            ),
          )
        ],
      ),
    );
  }

  void _showPrintDialog(String address) {
    TextEditingController controller = TextEditingController();
    showDialog(
      context: context,
      builder: (_) => AlertDialog(
        title: Text('打印内容'),
        content: TextField(controller: controller),
        actions: [
          TextButton(
            onPressed: () => Navigator.pop(context),
            child: Text('取消')
          ),
          TextButton(
            onPressed: () {
              BluetoothBridge.connectPrinter(address);
              BluetoothBridge.printText(controller.text);
              Navigator.pop(context);
              ScaffoldMessenger.of(context).showSnackBar(
                SnackBar(content: Text('打印指令已发送'))
              );
            },
            child: Text('打印')
          )
        ],
      )
    );
  }
}

六、运行效果演示

6.1 测试设备

打印机：佳博 GP-3120T（支持 ESC/POS）
扫码枪：霍尼韦尔 Xenon XP（HID 模式）
传感器：自研 BLE 温湿度模块（GATT 服务）

6.2 真机效果

蓝牙外设通信
图1：Flutter 应用成功连接打印机并打印“Hello OpenHarmony!”

🔍 验证点：

扫码枪扫描后，自动输入到 TextField（系统级 HID，无需额外处理）

传感器数据每秒更新，无丢包

打印指令包含 切纸、换行 等控制符

七、协议解析指南

设备类型	协议	关键指令
热敏打印机	ESC/POS	`0x1B 0x40`（初始化），`0x1D 0x56 0x41 0x03`（切纸）
扫码枪	HID 键盘	无需处理，系统自动输入
BLE 传感器	自定义 GATT	特征值格式：`[Temp_H, Temp_L, Hum_H, Hum_L]`