Flutter北欧半导体nRF Mesh网络控制插件nordic_nrf_mesh_faradine的使用

nordic_nrf_mesh_faradine

一个用于通过北欧半导体SDK管理并实现Mesh网络通信的Flutter插件。

特性

此插件封装了以下两个库：

• IOS-nRF-Mesh-Library
• Android-nRF-Mesh-Library（具体为此fork版本）

提供了Dart-only API，并具有以下功能：

• 创建、加载和管理Mesh网络模型
• (De)provision BLE Mesh节点
• 扫描附近的BLE设备
• 连接到BLE Mesh节点并用作代理进行Mesh网络通信
• 加密和解密Mesh PDUs（并非所有Mesh消息类型都受支持）
• 基于事件的API（使用StreamControllers）
• 管理Mesh组
• 管理节点的发布和订阅
• 管理Mesh provisioners
• Key Refresh Procedure（在Android上部分支持）

(注意: 蓝牙扫描和连接功能由flutter_reactive_ble完成)

如何使用

安装

在Flutter应用中安装插件

安装插件

1. 在pubspec.yaml文件中运行以下命令添加此包：

   flutter pub add nordic_nrf_mesh_faradine

2. 对于Android:

   • 打开项目的/android/settings.gradle文件，在底部粘贴插件的示例app设置。
   • 修改/android/gradle/wrapper/gradle-wrapper.properties文件中的distributionUrl，将版本号从默认的8.3改为7.4。这可以确保Gradle与插件兼容。
   • 同步Gradle文件或重启IDE以解决构建错误。

3. 本地使用:

   • 克隆仓库。
   • 执行git submodule update --init。

4. 更新构建脚本:

   • Android: 复制插件示例应用的gradle脚本到/android/settings.gradle。
   • iOS:
     • 将插件示例应用的Podfile脚本复制到自己的项目中（当前未测试）。

初始化

导入插件：

import 'package:nordic_nrf_mesh_faradine/nordic_nrf_mesh_faradine.dart';

要开始使用插件，首先实例化NordicNrfMesh对象：

final nordicNrfMesh = NordicNrfMesh();

通过这个单例对象可以访问主API。

Mesh网络特性

为了能够使用Mesh功能，每次运行时都需要加载Mesh网络。可以通过以下方式获取网络：

final MeshManagerApi meshManager = nordicNrfMesh.meshManagerApi;
final MeshNetwork meshNetwork = await meshManager.loadMeshNetwork();

或者：

final String networkAsJson = '{"mesh": "network"}';
final MeshManagerApi meshManager = nordicNrfMesh.meshManagerApi;
final MeshNetwork meshNetwork = await meshManager.importMeshNetworkJson(networkAsJson);

虽然上述方法简单易用，但它们不会实时更新。因此，我们强烈建议用户使用事件流来获取实时数据：

class MyPluginWrapper {
  late IMeshNetwork? _meshNetwork;
  late final NordicNrfMesh _nordicNrfMesh;
  late final MeshManagerApi _meshManagerApi;
  late final StreamSubscription<IMeshNetwork?> onNetworkUpdateSubscription;
  late final StreamSubscription<IMeshNetwork?> onNetworkImportSubscription;
  late final StreamSubscription<IMeshNetwork?> onNetworkLoadingSubscription;

  void init() {
    _nordicNrfMesh = NordicNrfMesh();
    _meshManagerApi = _nordicNrfMesh.meshManagerApi;
    _meshNetwork = _meshManagerApi.meshNetwork;

    // 订阅网络更新事件
    onNetworkUpdateSubscription = _meshManagerApi.onNetworkUpdated.listen((event) {
      _meshNetwork = event;
    });

    onNetworkImportSubscription = _meshManagerApi.onNetworkImported.listen((event) {
      _meshNetwork = event;
    });

    onNetworkLoadingSubscription = _meshManagerApi.onNetworkLoaded.listen((event) {
      _meshNetwork = event;
    });
  }

  void dispose() {
    onNetworkUpdateSubscription.cancel();
    onNetworkLoadingSubscription.cancel();
    onNetworkImportSubscription.cancel();
  }
}

(De)Provisioning

节点必须被provision才能加入网络。此功能通过NordicNrfMesh实例提供。以下是签名：

Future<ProvisionedMeshNode> provisioning(
  final MeshManagerApi meshManagerApi,
  final BleMeshManager bleMeshManager,
  final DiscoveredDevice device,
  final String serviceDataUuid, {
  final ProvisioningEvent? events,
});

Future<ConfigNodeResetStatus> deprovision(
  final MeshManagerApi meshManagerApi,
  final ProvisionedMeshNode meshNode,
);

(如需示例用法，请参考示例应用。)

蓝牙功能

(注意: 蓝牙扫描和连接功能由flutter_reactive_ble完成)

扫描设备

不同的扫描器通过NordicNrfMesh实例可用。API以Mesh为中心，您可以轻松获取手机周围的Mesh设备，也可以通过NordicNrfMesh.scanWithServices进行自定义扫描。

连接到设备

要实现连接功能，必须使用BleManager和BleManagerCallbacks抽象类。

为方便起见，我们在此插件中提供了一个特定于Mesh节点的实现。要处理与Mesh代理节点的BLE连接，需要创建并初始化一个BleMeshManager实例：

final bleMeshManager = BleMeshManager();
bleMeshManager.callbacks = MyBleCallbacks(meshManager); // 必须设置

(上面代码中的MyBleCallbacks必须继承自BleMeshManagerCallbacks。)

之后，您需要扫描设备，然后调用connect方法：

DiscoveredDevice device;
// 扫描范围内的设备
[...]
// 如果找到设备，则连接
bleMeshManager.connect(device);

自定义BLE功能

如果您的用例未实现，您可以自行实现。不过，您仍然可以通过以下代码获取对flutter_reactive_ble插件其他功能的访问权限：

final blePlugin = FlutterReactiveBle();

示例应用

如需更深入的使用，请参考示例应用，它展示了部分常用功能。在基于选项卡的布局中，它提供了以下示例用法：

• 基本Mesh网络管理
• 扫描并provision新节点（带有基于事件的UI）
• 扫描、连接并发送消息给已provision的节点

相关链接

• Android-nRF-Mesh-Library（fork版本）
• iOS-nRF-Mesh-Library（fork版本）
• Bluetooth Mesh Profile v1.0.1
• flutter_reactive_ble

(注意: 此插件使用了北欧半导体库的fork版本。这样做是为了能够扩展这些库以包含一些DooZ特定的API，但并未更改源代码。)

示例代码

以下是完整的示例代码，展示了如何使用插件的基本功能：

import 'package:flutter/material.dart';
import 'package:nordic_nrf_mesh_faradine/nordic_nrf_mesh_faradine.dart';

void main() => runApp(MyApp());

class MyApp extends StatefulWidget {
  [@override](/user/override)
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  late NordicNrfMesh _nordicNrfMesh;
  late MeshManagerApi _meshManagerApi;
  late IMeshNetwork? _meshNetwork;

  [@override](/user/override)
  void initState() {
    super.initState();
    _nordicNrfMesh = NordicNrfMesh();
    _meshManagerApi = _nordicNrfMesh.meshManagerApi;
    _meshNetwork = _meshManagerApi.meshNetwork;

    // 订阅网络更新事件
    _meshManagerApi.onNetworkUpdated.listen((event) {
      setState(() {
        _meshNetwork = event;
      });
    });
  }

  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(
          title: Text('nordic_nrf_mesh_faradine 示例'),
        ),
        body: Center(
          child: Text(_meshNetwork != null
              ? 'Mesh网络已加载: ${_meshNetwork!.name}'
              : '加载Mesh网络...'),
        ),
      ),
    );
  }
}