nRF Mesh Flutter Plugin

A Flutter plugin for Bluetooth Mesh networking, based on Nordic Semiconductor's nRF Mesh libraries (iOS / Android Kotlin Mesh).

Features

Network Management: Create, load, save, export, and import mesh networks
Device Provisioning: Provision unprovisioned devices into the mesh network
Device Scanning: Scan for nearby unprovisioned BLE devices
Message Communication: Send and receive mesh messages
Node Management: Manage provisioned nodes in the network
Group Management: Create and manage mesh groups
Standard Models: Support for Generic On/Off, Light, and other standard BLE Mesh models

Supported Platforms

iOS: 13.0+
Android: API 24+ (Android 7.0 Nougat)

Installation

Add nrf_mesh_flutter to your pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  nrf_mesh_flutter: ^6.9.7

Release notes language

Release notes in CHANGELOG.md are maintained in English only.

Dependency policy

Avoid adding new third-party Dart dependencies unless they are strictly required for Bluetooth Mesh interoperability or the Flutter plugin contract.

Prefer the Dart / Flutter SDK (dart:*, package:flutter/...) and small in-repo utilities (for example debounceMeshNetworkUpdates uses only dart:async).
Runtime packages today (convert, crypto, pointycastle, plugin_platform_interface, meta) exist for encoding/hashing/AES-CMAC and platform abstraction; expanding this set should include a CHANGELOG rationale and stay minimal.
Development dependencies are intentionally narrow: flutter_test, flutter_lints, and pigeon — do not pull in extra pub packages for tests or tooling convenience.

Recommended: sending raw Access messages

If you need to send vendor/custom messages (or want to avoid the implicit parameters['bytes'] convention), prefer sendAccess(...):

await PlatoJobsNrfMeshManager.instance.sendAccess(
  opCode: 0x8202, // example: Generic OnOff Set (ack)
  parameters: const [0x01, 0x01], // payload bytes
  address: 0x0003, // destination (unicast/group/virtual)
  appKeyIndex: 0,
);

Incoming messages (Phase 0 baseline)

Incoming Access PDUs are surfaced on:

Stream	Model	Typical contents
`messageStream`	`MeshMessage`	`opcode`, `parameters['bytes']`, `address` (source unicast when known)
`rxAccessMessageStream`	`RxAccessMessage`	`opcode`, `parameters`, `source`, `destination`, `metadataStatus`

Receive path inventory (Phase 0.1)

Surface	Opcode / payload	Source	Destination	RX AppKey index	Network TTL	Platform notes
`messageStream`	`opcode` + `parameters['bytes']`	`MeshMessage.address` (incoming)	—	always `null` today	not exposed	Matches Access payload after decode
`rxAccessMessageStream`	`opcode` + `parameters`	`RxAccessMessage.source`	`RxAccessMessage.destination`	always `null` today (Phase 1.4)	not exposed	Use `metadataStatus` when fields absent
`provisioningEventStream`	`ProvisioningEventType` + text fields	`deviceId`	—	—	—	Not Access-layer RX
`meshNetworkUpdatedStream`	monotonic `int` sequence	—	—	—	—	DB lifecycle hint, not a mesh PDU

Platform gaps (Phase 0.2)

Inbound Application Key index on receive: not forwarded on Android or iOS today → tracked as Phase 1.4 (nullable + docs / capability when stacks align). Query supportsRxAppKeyIndex() — it returns false until native metadata is wired.
Network / relay TTL on inbound PDUs: not exposed on either bridge path.
Android reflection RX path: setExperimentalRxMetadataEnabled(true) is deprecated (Phase 1.3); default Kotlin Mesh MeshMessageReceived path should be used.
Bluetooth Mesh Proxy Filter driven from Flutter: not implemented (Phase 3.2). Query supportsProxyFilter() — false until Nordic bearer/filter hooks are bridged.

Phase 0.3: Guaranteed vs best-effort

This plugin aims for the same Dart API on Android and iOS: method names, parameter meaning, and whether a call succeeds or throws should match unless this README says otherwise.

Class	Meaning
Guaranteed	Wire contract: Pigeon methods and stream types are stable; documented behaviors (e.g. `supportsRxSourceAddress()` meaning, deprecation of experimental Android RX) are intentional.
Best-effort	RX field completeness: source / destination / opcode bytes may be absent when the Nordic stack or bearer does not supply them — treat `RxMetadataStatus` and nullability as authoritative.
Best-effort	Topology snapshots: `getNodes()` / `getGroups()` reflect the native mesh DB at query time; live RF state can diverge until you reconnect or reprovision. Use `meshNetworkUpdatedStream` (+ optional `debounceMeshNetworkUpdates`) to refresh caches after DB edits.

Cross-platform mapping (Nordic stacks):

Field	Android (Kotlin Mesh 1.0+, GATT proxy session)	iOS (`nRFMeshProvision`, `MeshNetworkDelegate`)
Payload	`message.parameters`	`message.parameters`
Source → `MeshMessage.address` / `RxAccessMessage.source`	`NetworkEvent.MeshMessageReceived.source`	`didReceiveMessage ... sentFrom source`
`RxAccessMessage.destination`	`MeshMessageReceived.destination` (`MeshAddress`)	Delegate `to destination`

Portable Dart code: keep null-safe handling for address, source, and destination (legacy paths, bearers, or transient states may omit them).

Android: supportsRxSourceAddress() reflects whether the active bridge populates source for incoming traffic (public networkEvents path on Kotlin Mesh 1.0+). Legacy reflection tuning via setExperimentalRxMetadataEnabled is deprecated (Phase 1.3); enabling it logs Log.w on Android.

iOS: supportsRxSourceAddress() is true when the mesh delegate delivers sentFrom.

Optional inbound metadata (AppKey index on receive, richer TTL/network fields, etc.) belongs to Phase 1.4 in the Roadmap (planning checklist)—implemented only when Nordic stacks expose it consistently or documented as platform-specific.

Mesh DB change hints (Phase 2)

When the native mesh configuration database may have changed (nodes, groups, keys, provisioning saves, etc.), the plugin emits on meshNetworkUpdatedStream. Each event is a monotonically increasing int sequence number—apps typically debounce and then refresh getNodes() / getGroups() / key APIs as needed. For a dependency-free debounce, use debounceMeshNetworkUpdates from this package (Phase 2.2 helper).

Platform	Typical trigger
Android (Kotlin Mesh)	`NetworkEvent.NetworkUpdated` from `networkEvents`
iOS (`nRFMeshProvision`)	After successful `MeshNetworkManager.save()` and after loads / imports that affect the DB

Roadmap (planning checklist)

Product parity work is tracked by phase 0–5 below (not by release tags). The technical sections Incoming messages (Phase 0 baseline) and Mesh DB change hints (Phase 2) are part of those phases.

Acceptance principles

Same Dart API semantics on Android and iOS: success vs failure, parameter meaning, and stream field meanings must align unless explicitly documented otherwise.
When parity is impossible: call it out in docs and/or RxMetadataStatus / a dedicated enum—no silent behavioral forks between platforms.
Each milestone should ship Pigeon changes (when applicable), an example page or integration test, and a CHANGELOG entry.

Phase 0 — Baseline & documentation (~1–2 days)

ID	Item	Deliverable
0.1	Inventory receive/uplink paths: `messageStream`, `rxAccessMessageStream`, provisioning callbacks	Comparison table (opcode, bytes, source, destination, appKey, TTL, …)
0.2	Check whether iOS can achieve Android `MeshMessageReceived`-grade source/destination	Written gap list
0.3	README «platform differences»: what is guaranteed vs best-effort	Phase 0.3: Guaranteed vs best-effort — overlaps inventory tables; extend when stacks change

Phase 1 — Receive-path parity (high priority, ~1–2 weeks)

ID	Item	Android	iOS	Acceptance
1.1	Align `MeshMessage.address` with `RxAccessMessage.source` / `destination` semantics	Uses `NetworkEvent.MeshMessageReceived` source & destination on Kotlin Mesh 1.0+	`MeshNetworkDelegate` path supplies source & destination	Same opcode fixture → same reported source in integration/unit coverage where feasible
1.2	`supportsRxSourceAddress()` matches reality	`true` on default `networkEvents` receive path	`true` when delegate delivers `sentFrom`	Tests or assertions on representative builds
1.3	Deprecate / demote Android reflection experimental RX path	`setExperimentalRxMetadataEnabled` deprecated + `Log.w` when enabled (6.9.4); default public API	N/A	Default CI build without reflection dependency
1.4	Inbound `appKeyIndex` (optional)	Evaluate Kotlin Mesh / security APIs	Evaluate delegate/callback surface	`supportsRxAppKeyIndex()` reflects capability; same semantics if filled; otherwise document + nullable fields

Phase 2 — Network lifecycle (~1–2 weeks, medium priority)

ID	Item	Android	iOS	Acceptance
2.1	`NetworkUpdated`-class signal to Flutter	`networkEvents` → `NetworkUpdated`	Save/load/import/reset-driven notify (current bridge)	`meshNetworkUpdatedStream` (today: monotonic `int` seq); optional future: reasons / `Stream<void>`
2.2	Debounce & merge (avoid event storms)	App/plugin policy	Same	Example + `debounceMeshNetworkUpdates`: debounced refresh drives `getNodes()` / `getGroups()` consistently

Current plugin note: 2.1 is implemented end-to-end; 2.2 ships debounceMeshNetworkUpdates and the example uses it; centralized coalescing inside the plugin remains optional follow-up.

Phase 3 — Proxy & connection strategy (~2–3 weeks, medium priority, as needed)

ID	Item	Notes
3.1	Abstract proxy / bearer state machine	Align Kotlin Mesh bearer vs iOS GATT proxy states → unified Dart model (`disconnected` / `connecting` / `proxyReady` / `provisioning`, …)
3.2	Proxy Filter (advanced subset)	`supportsProxyFilter()` (false today = explicit unsupported probe); expose Nordic Proxy Filter subset on Android + parity/doc on iOS when implemented
3.3	Auto-reconnect (optional)	Configurable policy aligned with Nordic guidance; example toggle + compliance/power warnings

Current plugin note: 3.1 (partial) — MeshBearerSnapshot / getMeshBearerSnapshot() fold isProxyConnected + isProvisioningConnected into MeshBearerPhase (disconnected / proxyReady / provisioning) with provisioning precedence when both natives report connected. A distinct connecting phase is not observable from these booleans alone — track in-flight connects via local Future state.

3.2 (probe) — supportsProxyFilter() returns false on Android and iOS today (explicit «unsupported» capability); mesh traffic uses Nordic stack defaults until filter configuration is wired.

Phase 4 — Provisioning parity (Mesh 1.1 / enhanced) (~2–4 weeks, business-driven)

ID	Item	Notes
4.1	Capabilities → Flutter (OOB list, etc.)	Structured Pigeon types; Kotlin ↔ iOS symmetry
4.2	Enhanced provisioning / Mesh 1.1 params	Follow Nordic API deltas on both stacks + capability probes
4.3	Static / output OOB state machine parity	Callback naming & ordering aligned; E2E provisioning tests

Phase 5 — Dependencies & health (ongoing)

ID	Item
5.1	Android: Kotlin Mesh + kotlin-ble aligned with Nordic’s recommended matrix (BOM / sample versions)
5.2	iOS: `nRFMeshProvision` patch bumps + Swift/Xcode compatibility; note in CHANGELOG
5.3	Dart: dependency constraints + pub health (`dart pub outdated`, dry-run before release)

Suggested sequencing (shortest path to «dual-stack consistent»)

Phase 1 (receive metadata + supportsRxSourceAddress) — highest user-visible impact.
Phase 0 docs & matrices — avoids ambiguity during Phase 1 reviews.
Phase 2 — better refresh model & power (partially delivered).
Phase 4 — only if Mesh 1.1 / advanced provisioning is required.
Phase 3 & Phase 5 — parallel or interleaved with the above.

Engineering hygiene (all phases)

Follow the Dependency policy — no new optional third-party Dart deps without strong justification.
Regenerate Pigeon / CocoaPods when pigeon/mesh_api.dart or native versioning changes.
Keep example pages aligned with new APIs.
Run dart pub publish --dry-run / pana before release.

iOS Configuration

Add the following to your ios/Podfile:

platform :ios, '13.0'
use_frameworks!

Android Configuration

Add Bluetooth permissions to your android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30"/>
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30"/>
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" android:usesPermissionFlags="neverForLocation"/>
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

Quick Start

import 'package:nrf_mesh_flutter/nrf_mesh_flutter.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Initialize the mesh manager
  await PlatoJobsNrfMeshManager.instance.initialize();

  runApp(const MyApp());
}

Provisioning Flow (High Level)

flowchart TD
  A[initialize()] --> B[loadNetwork()]
  B -->|null / empty| C[createNetwork()]
  B -->|exists| D[scanForDevices()]
  C --> D
  D --> E[provisionDevice()]
  E --> F[sendMessage()]
  F --> G[messageStream]

Mocking (No Hardware Needed)

For UI development without real Mesh hardware you can inject a fake bridge:

import 'package:nrf_mesh_flutter/nrf_mesh_flutter.dart';

final fake = FakePlatoJobsMeshBridge(
  scenario: FakeMeshScenario()
      .add(
        FakeMeshScenarioStep.discoveredDevice(
          UnprovisionedDevice(
            deviceId: 'dev-1',
            name: 'Demo',
            serviceUuid: '',
            rssi: -40,
            serviceData: const <int>[1, 2, 3],
          ),
        ),
      )
      .add(
        FakeMeshScenarioStep.incomingMessage(GenericOnOffSet(state: true)),
      ),
);
PlatoJobsNrfMeshManager.setBridgeForTesting(fake);
await PlatoJobsNrfMeshManager.instance.initialize();

Notes:

Call scanForDevices() to start the scripted scenario (it runs once per fake instance).
You can still push events manually with emitDiscoveredDevice(...) / emitIncomingMessage(...).

Usage

Network Management

// Create a new mesh network
final network = await PlatoJobsNrfMeshManager.instance.createNetwork('My Mesh Network');

// Load an existing network
final loadedNetwork = await PlatoJobsNrfMeshManager.instance.loadNetwork();

// Save the current network
await PlatoJobsNrfMeshManager.instance.saveNetwork();

// Export network to a file
await PlatoJobsNrfMeshManager.instance.exportNetwork('/path/to/export.json');

// Import network from a file
await PlatoJobsNrfMeshManager.instance.importNetwork('/path/to/import.json');

Device Scanning

// Start scanning for unprovisioned devices
StreamSubscription<UnprovisionedDevice> subscription =
    PlatoJobsNrfMeshManager.instance.scanForDevices().listen((device) {
  print('Discovered: ${device.name} (${device.deviceId})');
});

// Stop scanning
await PlatoJobsNrfMeshManager.instance.stopScan();

// Cancel subscription when done
await subscription.cancel();

Device Provisioning

// Provision a device
final node = await PlatoJobsNrfMeshManager.instance.provisionDevice(
  device,
  ProvisioningParameters(
    deviceName: 'My Device',
    oobMethod: 0,
    enablePrivacy: false,
  ),
);

Sending Messages

// Send a Generic On/Off message
await PlatoJobsNrfMeshManager.instance.sendMessage(
  GenericOnOffSet(
    state: true,
    transitionTime: 0,
    delay: 0,
    address: 0xC000, // e.g. group address or node unicast
    appKeyIndex: 0,
  ),
);

// Listen for incoming messages
PlatoJobsNrfMeshManager.instance.messageStream.listen((message) {
  print('Received message: ${message.opcode}');
});

Node Management

// Get all provisioned nodes
final nodes = await PlatoJobsNrfMeshManager.instance.getNodes();

// Remove a node
await PlatoJobsNrfMeshManager.instance.removeNode(nodeId);

Group Management

// Create a new group
final group = await PlatoJobsNrfMeshManager.instance.createGroup('Living Room');

// Get all groups
final groups = await PlatoJobsNrfMeshManager.instance.getGroups();

// Add a node to a group
await PlatoJobsNrfMeshManager.instance.addNodeToGroup(nodeId, groupId);

API Reference

Core Class

`PlatoJobsNrfMeshManager`

The main entry point for the plugin. Uses singleton pattern.

Singleton Access:

PlatoJobsNrfMeshManager.instance

Methods:

Method	Description
`initialize()`	Initialize the mesh manager
`createNetwork(name)`	Create a new mesh network
`loadNetwork()`	Load an existing mesh network
`saveNetwork()`	Save the current mesh network
`exportNetwork(path)`	Export network to a JSON file
`importNetwork(path)`	Import network from a JSON file
`scanForDevices()`	Start scanning for unprovisioned devices
`stopScan()`	Stop scanning
`provisionDevice(device, params)`	Provision a device
`sendMessage(message)`	Send a mesh message
`getNodes()`	Get all provisioned nodes
`removeNode(nodeId)`	Remove a node
`createGroup(name)`	Create a new group
`getGroups()`	Get all groups
`addNodeToGroup(nodeId, groupId)`	Add a node to a group
`supportsRxSourceAddress()`	Whether inbound messages can include a reliable source address
`supportsRxAppKeyIndex()`	Whether inbound metadata can include Application Key index (Phase 1.4; `false` until native wiring)
`getMeshBearerSnapshot()`	Phase 3.1: `MeshBearerPhase` from native proxy vs provisioning connection flags
`supportsProxyFilter()`	Phase 3.2: whether Proxy Filter can be configured (`false` until bridged)

Properties:

Property	Type	Description
`messageStream`	`Stream<MeshMessage>`	Stream of received mesh messages
`meshNetworkUpdatedStream`	`Stream<int>`	Hint when native mesh DB may have changed (refresh topology caches)

Data Models

`MeshBearerSnapshot` / `MeshBearerPhase` (Phase 3.1)

Portable snapshot of mesh-proxy vs PB-GATT provisioning bearer activity. Built by querying native isProxyConnected and isProvisioningConnected together — see the Phase 3 roadmap table (above) for precedence rules and connecting limitations.

`MeshNetwork`

Represents a Bluetooth Mesh network.

Properties:

networkId: Unique network identifier
name: Network name
networkKeys: List of network keys
appKeys: List of application keys
nodes: List of provisioned nodes
groups: List of mesh groups
provisioner: Network provisioner info

`ProvisionedNode`

Represents a provisioned mesh node.

Properties:

uuid: Node UUID
unicastAddress: Node unicast address
elements: List of elements
networkKeys: List of network keys
appKeys: List of application keys
features: Node features (relay, proxy, friend, low power)

`UnprovisionedDevice`

Represents a discovered unprovisioned device.

Properties:

deviceId: Device identifier
name: Device name
serviceUuid: Service UUID
rssi: Signal strength
serviceData: Service data from advertising packets

`MeshGroup`

Represents a mesh group.

Properties:

groupId: Group identifier
name: Group name
address: Group address
nodeIds: List of node IDs in the group

`MeshMessage`

Base class for mesh messages.

Properties:

opcode: Message opcode
parameters: Message parameters

Architecture

The plugin follows a layered architecture:

┌─────────────────────────────────┐
│         Dart Layer              │
│  (PlatoJobsNrfMeshManager)      │
├─────────────────────────────────┤
│     Platform Interface          │
│  (PlatoJobsMeshPlatform)        │
├─────────────────────────────────┤
│   Pigeon Generated Code          │
│  (Auto-generated codec)          │
├─────────────────────────────────┤
│     Native Layer                 │
│  (Swift / Kotlin)                │
├─────────────────────────────────┤
│   Nordic nRF Mesh Library        │
│  (iOS / Android)                │
└─────────────────────────────────┘

Dependencies

Flutter Dependencies

plugin_platform_interface: ^2.1.8 - Platform interface support
convert: ^3.1.2 - JSON/codecs helpers
crypto: ^3.0.7 - Cryptographic hashing helpers
meta: ^1.17.0 - Annotations
pointycastle: ^4.0.0 - AES-CMAC support for Bluetooth Mesh virtual addresses

Native Dependencies

iOS: nRFMeshProvision ~> 4.8.0
Android: Nordic Kotlin Mesh Library 1.0.0 (core, bearer, bearer-gatt, bearer-pbgatt, bearer-provisioning, provisioning) plus no.nordicsemi.kotlin.ble:client-android:2.0.0-alpha19

Error Handling

All async methods may throw PlatoJobsMeshException (a readable wrapper over platform errors, timeouts, and common BLE failures).

try {
  await PlatoJobsNrfMeshManager.instance.initialize();
} on PlatoJobsMeshException catch (e) {
  // e.g. permission / connection / timeout / invalid state
  print('Mesh error: $e');
}

Android 12+ / 14+ Notes

Android 12+ needs runtime permissions: BLUETOOTH_SCAN / BLUETOOTH_CONNECT.
Android 13+ 如果要在通知中提示连接状态，可能需要 POST_NOTIFICATIONS（由你的 App 决定是否需要）。
Android 14+ background scan/connection restrictions are stricter: keep provisioning/proxy connection in a user-visible flow, and implement retry + timeouts.

iOS 13+ / 17+ Notes

Add Bluetooth usage descriptions to Info.plist (e.g. NSBluetoothAlwaysUsageDescription).
iOS 17+ is more sensitive about background operations: keep mesh actions in the foreground flow where possible.

Examples

See the example directory for a complete demo application demonstrating all features.

License

MIT License - see LICENSE file for details.

Author

PlatoJobs

GitHub: https://github.com/platojobs
Project: https://github.com/platojobs/nrf_mesh_flutter

Changelog

For the full history, see CHANGELOG.md.

Latest

See CHANGELOG.md for the full history and the latest release notes.

nRF Mesh Flutter Plugin

Features

Supported Platforms

Installation

Release notes language

Dependency policy

Recommended: sending raw Access messages

Incoming messages (Phase 0 baseline)

Receive path inventory (Phase 0.1)

Platform gaps (Phase 0.2)

Phase 0.3: Guaranteed vs best-effort

Mesh DB change hints (Phase 2)

Roadmap (planning checklist)

Acceptance principles

Phase 0 — Baseline & documentation (~1–2 days)

Phase 1 — Receive-path parity (high priority, ~1–2 weeks)

Phase 2 — Network lifecycle (~1–2 weeks, medium priority)

Phase 3 — Proxy & connection strategy (~2–3 weeks, medium priority, as needed)

Phase 4 — Provisioning parity (Mesh 1.1 / enhanced) (~2–4 weeks, business-driven)

Phase 5 — Dependencies & health (ongoing)

Suggested sequencing (shortest path to «dual-stack consistent»)

Engineering hygiene (all phases)

iOS Configuration

Android Configuration

Quick Start

Provisioning Flow (High Level)

Mocking (No Hardware Needed)

Usage

Network Management

Device Scanning

Device Provisioning

Sending Messages

Node Management

Group Management

API Reference

Core Class

PlatoJobsNrfMeshManager

Data Models

MeshBearerSnapshot / MeshBearerPhase (Phase 3.1)

MeshNetwork

ProvisionedNode

UnprovisionedDevice

MeshGroup

MeshMessage

Architecture

Dependencies

Flutter Dependencies

Native Dependencies

Error Handling

Android 12+ / 14+ Notes

iOS 13+ / 17+ Notes

Examples

License

Author

Changelog

Latest

Libraries

nrf_mesh_flutter package

`PlatoJobsNrfMeshManager`

`MeshBearerSnapshot` / `MeshBearerPhase` (Phase 3.1)

`MeshNetwork`

`ProvisionedNode`

`UnprovisionedDevice`

`MeshGroup`

`MeshMessage`