repository·main·Indexed 18 days ago
https://github.com/nordicsemi/ios-nrf-mesh-libraryA Swift-based framework for iOS providing full support for Bluetooth Mesh provisioning, configuration, and communication. It enables developers to manage mesh networks using GATT Proxy to accommodate iOS hardware and API constraints.
The nRF Mesh library is used to provision, configure, and control Bluetooth mesh devices within a mesh network on iOS. It supports sending and receiving mesh messages and is compatible with the following specifications:
The nRF Mesh library enables iOS applications to provision Bluetooth® Mesh devices into a mesh network, configure them, and facilitate message exchange (send/receive).
Key Technical Constraints:
The ProvisioningManager allows you to manage network-level configuration during or after the provisioning process. You can manage:
networkKey: The key used to secure the mesh network.unicastAddress: The specific address assigned to a device.suggestedUnicastAddress: A preferred address to suggest during provisioning.isUnicastAddressValid(_:): A method to verify if a given unicast address is valid for the current configuration.You can send messages by triggering a publication from a model on the local node. This method follows the Bluetooth Mesh Protocol specification and requires the model to be properly configured first.
Prerequisites:
ConfigModelAppBind message.ConfigModelPublicationSet or ConfigModelPublicationVirtualAddressSet.Execution:
Call ModelDelegate/publish(using:) or ModelDelegate/publish(_:using:). The message will be sent to the destination specified in the Publish object.
Handling Responses:
If the message requires an acknowledgment, the response is delivered via the ModelDelegate/model(_:didReceiveResponse:toAcknowledgedMessage:from:) method.
// Trigger a publication from a model delegate
delegate.publish(using: publishObject)Bearers are responsible for delivering Protocol Data Units (PDUs) to remote nodes.
Important iOS Limitation: Due to iOS API limitations, the ADV Bearer is not available. To connect an iPhone to a mesh network, you must use a GATT Bearer to connect to a node that has the GATT Proxy feature enabled. The GATT Proxy node then proxies your messages to the network using an ADV Bearer.
Key Bearer Types:
GattBearer: Used for connecting via GATT Proxy.PBGattBearer: A specific implementation for GATT Proxy.PBRemoteBearer: Used for remote provisioning of devices that do not support the GATT Mesh Provisioning Service via a node with a Remote Provisioning Server model.MeshNetworkManager is the primary interface for interacting with a Bluetooth mesh network in the iOS library. You use it to manage the lifecycle of a mesh network (creating, loading, saving, importing, and exporting) and to perform core mesh operations like provisioning devices, publishing data, and sending/receiving messages.CBOR.encode(..., asByteString: true), the library handles endianness for you. If the computer is little-endian, the raw bytes of all items except UInt8 will be reversed to comply with CBOR's big-endian (network byte order) requirement. UInt8 arrays are treated as already being in network byte order and are not reversed.The upgradeMode (set via FirmwareUpgradeConfiguration.upgradeMode) determines the sequence of commands sent after the upload step.
| Mode | Process | Description |
|---|---|---|
.confirmOnly | upload $\rightarrow$ confirm $\rightarrow$ reset | Default mode. Supports all DFU variants (Multi-Image, SUIT, etc.). Does not support automatic error recovery; if the device fails to boot, it must be re-flashed. |
.testAndConfirm | upload $\rightarrow$ test $\rightarrow$ reset $\rightarrow$ confirm | Recommended for Single Image DFU. Allows recovery from bad firmware. During test, images are marked 'Pending'. After reset, if booted successfully, they become 'Active'. |
.testOnly | upload $\rightarrow$ test $\rightarrow$ reset | Useful for running tests on a new image before manually confirming it as the primary boot image. |
.uploadOnly | upload $\rightarrow$ reset | A specialized mode that ignores Bootloader Info and proceeds immediately to reset. Use with caution. |
To reduce the number of Network PDUs exchanged between a Proxy Client and a Proxy Server, you can implement a ProxyFilter. This allows you to control which addresses are allowed to pass through the proxy.
Key Components:
ProxyFilter: The filter implementation.ProxyFilerType: Defines the type of filtering logic.ProxyFilterDelegate: Handles filter-related events.ProxyFilterSetup: Used to configure the filter.Configuration Messages for Filters:
AddAddressesToFilterRemoveAddressesFromFilterSetFilterTypeFilterStatusThe MeshNetworkManager uses a decoupled architecture where the transport layer is abstracted by the Bearer protocol.
MeshNetworkManager sends messages through its transmitter property, which must be an object conforming to the Bearer protocol.MeshNetworkManager/bearerDidDeliverData(_:ofType:) method.To simplify this bidirectional communication, you can assign the MeshNetworkManager instance directly to the Bearer/dataDelegate property of the bearer.
Provisioning is the secure process of adding an unprovisioned device to an existing mesh network.
Core Provisioning Components:
ProvisioningManager: Manages the provisioning lifecycle.ProvisioningDelegate: Handles provisioning events and callbacks.UnprovisionedDevice: Represents a device that has not yet been added to the network.ProvisioningState: Tracks the current stage of the provisioning process.Provisioning involves complex security handshakes using PublicKey, AuthenticationMethod, and potentially Out-of-Band (OOB) information (OobType, InputAction, OutputAction).
All API calls must be made from the Main Thread (for DFU, FileSystem, and most other operations) unless the documentation explicitly states that background thread calls are allowed.
Failure to comply with this requirement will result in a deliberate application crash to prevent undefined behavior and ensure system stability.