Documentation

NordicSemiconductor · Oct 9, 2023 · 3c63b7c · 3c63b7c
1 parent 2bd670b
commit 3c63b7c
Show file tree

Hide file tree

Showing 7 changed files with 86 additions and 34 deletions.
diff --git a/nRFMeshProvision/Documentation.docc/MeshNetworkManager.md b/nRFMeshProvision/Documentation.docc/MeshNetworkManager.md
@@ -90,8 +90,8 @@ Use it to create, load or import a Bluetooth mesh network and send messages.
 - ``registerCallback(forMessagesFrom:to:callback:)-7axud``
 - ``unregisterCallback(forMessagesWithOpCode:from:)-2pj32``
 - ``unregisterCallback(forMessagesWithOpCode:from:)-9rbl0``
-- ``unregisterCallback(forMessagesWithType:from:)-2cij2``
-- ``unregisterCallback(forMessagesWithType:from:)-7mdko``
+- ``unregisterCallback(forMessagesWithType:from:)-15wz4``
+- ``unregisterCallback(forMessagesWithType:from:)-1g3i0``
 
 ### Bearer Callbacks
 

diff --git a/nRFMeshProvision/Documentation.docc/Provisioning.md b/nRFMeshProvision/Documentation.docc/Provisioning.md
@@ -8,10 +8,10 @@ The provisioner, in a secure way, assigns a Unicast Address and sends the Networ
 Knowing the key, the new device, now called a Node, can exchange mesh messages with other nodes.
 
 > To provision a new device, the provisioner does not need to have an address assigned. Having a
-  Unicast Address makes the provisioner a node.
+  Unicast Address makes the provisioner a configuration manager node.
 
-A provisioner with a Unicast Address assigned may also configure nodes after they have been
-provisioned. Configuration messages are sent between *Configuration Client* model on the provisioner 
+A configuration manager may configure nodes after they have been provisioned. 
+Configuration messages are sent between *Configuration Client* model on the manager 
 and *Configuration Server* model on the target device, and, on the Upper Transport layer, are encrypted 
 using the node's Device Key, generated during provisioning.
 
@@ -40,10 +40,12 @@ func centralManager(_ central: CBCentralManager,
 }
 ```
 
-> Important: Provisioning of new devices using the current version of the nRF Mesh library 
-  supports only with the use of GATT PB Bearer, i.e. remote provisioning is not supported. 
-  New devices must support GATT PB Bearer in order to be provisioned using a mobile device.
-  This also applies to the nRF Mesh library for Android.
+> Important: nRF Mesh library supports PB GATT Bearer and PB Remote Bearer. 
+  PB Adv Bearer is not supported. 
+
+To provision a device which does not support PB GATT Bearer a ``PBRemoteBearer`` must be used.
+A node supporting *Remote Provisioning Server* model must be provisioned and in range of the
+unprovisioned device. All provisioning messages will be sent via that node.
 
 Provisioning process is initiated by calling ``ProvisioningManager/identify(andAttractFor:)``
 ```swift
@@ -55,7 +57,7 @@ followed by ``ProvisioningManager/provision(usingAlgorithm:publicKey:authenticat
 provisioningManager.address = ...    // Defaults to the next available address.
 provisioningManager.networkKey = ... // Defaults to the Primary Network Key.
 // Start:
-try provisioningManager.provision(usingAlgorithm:       .fipsP256EllipticCurve,
+try provisioningManager.provision(usingAlgorithm:       .BTM_ECDH_P256_HMAC_SHA256_AES_CCM,
                                   publicKey:            ...,
                                   authenticationMethod: ...)
 ```

diff --git a/nRFMeshProvision/Documentation.docc/nRFMeshProvision.md b/nRFMeshProvision/Documentation.docc/nRFMeshProvision.md
@@ -8,8 +8,8 @@ The nRF Mesh library allows to provision Bluetooth mesh devices into a mesh netw
 them and send and receive messages.
 
 The library is compatible with the following [Bluetooth specifications](https://www.bluetooth.com/specifications/specs/?status=active&show_latest_version=0&show_latest_version=1&keyword=mesh&filter=):
-- **Mesh Profile 1.0.1** (with experimental support for **Mesh Protocol 1.1**)
-- **Mesh Model 1.0.1**
+- **Mesh Protocol 1.1** (backwards compatible with **Mesh Profile 1.0.1**)
+- **Mesh Model 1.1**
 - **Mesh Device Properties 2**
 - **Configuration Database Profile 1.0.1**
 
@@ -29,16 +29,47 @@ The snippet below demostrates how to start.
 // Create the Mesh Network Manager instance.
 meshNetworkManager = MeshNetworkManager()
 
-// Customize network parameters. 
-meshNetworkManager.networkParameters = .custom { builder in
-    builder.defaultTtl = ...
-    builder.discardTimeout = ...
-    builder.acknowledgmentTimerInterval = ...
-    builder.transmissionTimerInterval = ...
-    builder.retransmissionLimit = ...
-    builder.acknowledgmentMessageTimeout = ...
-    builder.acknowledgmentMessageInterval = ...
-    // If you know what you're doing, customize the advanced parameters.
+// Customize network parameters using basic:
+meshNetworkManager.networkParameters = .basic { parameters in
+    parameters.setDefaultTtl(...)
+    // Configure SAR Receiver properties
+    parameters.discardIncompleteSegmentedMessages(after: ...)
+    parameters.transmitSegmentAcknowledgmentMessage(
+        usingSegmentReceptionInterval: ...,
+        multipliedByMinimumDelayIncrement: ...)
+    parameters.retransmitSegmentAcknowledgmentMessages(
+        exactly: ..., timesWhenNumberOfSegmentsIsGreaterThan: ...)
+    // Configure SAR Transmitter properties
+    parameters.transmitSegments(withInterval: ...)
+    parameters.retransmitUnacknowledgedSegmentsToUnicastAddress(
+        atMost: ..., timesAndWithoutProgress: ...,
+        timesWithRetransmissionInterval: ..., andIncrement: ...)
+    parameters.retransmitAllSegmentsToGroupAddress(exactly: ..., timesWithInterval: ...)
+    // Configure message configuration
+    parameters.retransmitAcknowledgedMessage(after: ...)
+    parameters.discardAcknowledgedMessages(after: ...)
+}
+// ...or advanced configurator:
+meshNetworkManager.networkParameters = .advanced { parameters in
+    parameters.defaultTtl = ...
+    // Configure SAR Receiver properties
+    parameters.sarDiscardTimeout = ...
+    parameters.sarAcknowledgmentDelayIncrement = ...
+    parameters.sarReceiverSegmentIntervalStep = ...
+    parameters.sarSegmentsThreshold = ...
+    parameters.sarAcknowledgmentRetransmissionsCount = ...
+    // Configure SAR Transmitter properties
+    parameters.sarSegmentIntervalStep = ...
+    parameters.sarUnicastRetransmissionsCount = ...
+    parameters.sarUnicastRetransmissionsWithoutProgressCount = ...
+    parameters.sarUnicastRetransmissionsIntervalStep = ...
+    parameters.sarUnicastRetransmissionsIntervalIncrement = ...
+    parameters.sarMulticastRetransmissionsCount = ...
+    parameters.sarMulticastRetransmissionsIntervalStep = ...
+    // Configure acknowledged message timeouts
+    parameters.acknowledgmentMessageInterval = ...
+    parameters.acknowledgmentMessageTimeout = ...
+    // And if you really know what you're doing...
     builder.allowIvIndexRecoveryOver42 = ...
     builder.ivUpdateTestMode = ...
 }
@@ -130,7 +161,7 @@ provisioning procedure.
 - ``LogLevel``
 - ``LogCategory``
 
-### Bearers
+### Bearer
 
 Bearers are objects resopnsible for delivering PDUs to remote nodes. Bluetooth mesh, among others. defines 
 ADV Bearer and GATT Bearer. Due to API limitations on iOS the ADV Bearer is not available. An iPhone
@@ -146,7 +177,7 @@ can be connected to the mesh network using a GATT connection to a node with GATT
 - ``PduType``
 - ``PduTypes``
 
-### GATT Bearers
+### GATT Bearer
 
 GATT Bearer is used when connecting to a node with GATT Proxy feature. It uses a GATT connection 
 instead of Bluetooth advertising. Messages sent over that bearer need to be proxied to the network
@@ -164,6 +195,13 @@ using ADV Bearer by the GATT Proxy node.
 - ``MeshProvisioningService``
 - ``MeshProxyService``
 
+### Remote Bearer
+
+PB Remote Bearer allows to provision a device which does not support GATT Mesh Provisioning Service
+via a node with Remote Provisioning Server model.
+
+- ``PBRemoteBearer``
+
 ### Provisioning
 
 Provisioning is the process of adding an unprovisioned device to a mesh network in a secure way. 
@@ -424,6 +462,15 @@ Provisioning is the process of adding an unprovisioned device to a mesh network
 - ``PrivateNodeIdentitySet``
 - ``PrivateNodeIdentityStatus``
 
+### Configuration - Segmentation and Reassembly
+
+- ``SarReceiverGet``
+- ``SarReceiverSet``
+- ``SarReceiverStatus``
+- ``SarTransmitterGet``
+- ``SarTransmitterSet``
+- ``SarTransmitterStatus``
+
 ### Remote Provisioning Message Types
 
 - ``RemoteProvisioningMessage``
@@ -436,6 +483,7 @@ Provisioning is the process of adding an unprovisioned device to a mesh network
 - ``RemoteProvisioningScanState``
 - ``RemoteProvisioningLinkState``
 - ``RemoteProvisioningLinkCloseReason``
+- ``RemoteProvisioningLinkStateMessage``
 - ``AdTypes``
 - ``AdStructure``
 - ``NodeProvisioningProtocolInterfaceProcedure``

diff --git a/nRFMeshProvision/Layers/NetworkParameters.swift b/nRFMeshProvision/Layers/NetworkParameters.swift
@@ -35,8 +35,10 @@ import Foundation
 /// Network parameters configure the transsmition and retranssmition intervals,
 /// acknowledge message timeout, the default Time To Live (TTL) and other.
 ///
-/// Use ``NetworkParameters/default`` or ``NetworkParameters/custom(_:)`` to create
-/// an instance of this structure.
+/// Use one of the following buildersto create an instance of this structure:
+/// - ``NetworkParameters/default`` - the default configuration
+/// - ``NetworkParameters/basic(_:)`` - using verbose buuilder
+/// - ``NetworkParameters/advanced(_:)`` - for advanced users
 ///
 /// - since: 4.0.0
 public struct NetworkParameters {
@@ -90,7 +92,7 @@ public struct NetworkParameters {
         /// ```
         ///
         /// Number of retransmissions of the Segment Acknowledgment message can be set using
-        /// ``retranssmitSegmentAcknowledgmentMessages(_:timesWhenNumberOfSegmentsIsGreaterThan:)``.
+        /// ``retransmitSegmentAcknowledgmentMessages(exactly:timesWhenNumberOfSegmentsIsGreaterThan:)``.
         ///
         /// - parameters:
         ///   - segmentReceptionInterval: A value that indicates the interval between received segments
@@ -119,7 +121,7 @@ public struct NetworkParameters {
         ///
         /// When a receiver receives a segment of a segmented message composed of 2 or more
         /// segments it starts the SAR Acknowledgment timer. The initial value of this timer
-        /// is controller by ``setAcknowledgmentTimerInterval(_:andMinimumDelayIncrement:)``
+        /// is controller by ``transmitSegmentAcknowledgmentMessage(usingSegmentReceptionInterval:multipliedByMinimumDelayIncrement:)``
         /// and depends on the number of segments. Each time a new segment is received, the timer
         /// is restarted. When the timer expires, a Segment Acknowledgment message is sent to the
         /// transmitter indicating which segments were received until that point.

diff --git a/nRFMeshProvision/MeshNetworkDelegate.swift b/nRFMeshProvision/MeshNetworkDelegate.swift
@@ -110,11 +110,12 @@ public protocol MeshNetworkDelegate: AnyObject {
     ///   accept the message.
     /// - ``LowerTransportError/timeout`` - when the segmented message targeting
     ///   a Unicast Address was not acknowledged before the
-    ///   ``NetworkParameters/retransmissionLimit`` was reached
+    ///   ``NetworkParameters/sarUnicastRetransmissionsCount`` or
+    ///   ``NetworkParameters/sarUnicastRetransmissionsWithoutProgressCount`` was reached
     ///   (for unacknowledged messages only).
     /// - ``AccessError/timeout`` - when the response for an acknowledged message
-    ///   has not been received before the time run out (for acknowledged messages
-    ///   only).
+    ///   has not been received before the ``NetworkParameters/acknowledgmentMessageTimeout``
+    ///   run out (for acknowledged messages only).
     ///
     /// - parameters:
     ///   - manager:      The manager used to send the message.

diff --git a/nRFMeshProvision/MeshNetworkManager+Callbacks.swift b/nRFMeshProvision/MeshNetworkManager+Callbacks.swift
@@ -776,7 +776,7 @@ public extension MeshNetworkManager {
     ///
     /// The destination is optional. If not set it will not be checked.
     ///
-    /// - important: To unregister the callback call ``unregisterCallback(forMessagesWithType:from:)-2cij2``.
+    /// - important: To unregister the callback call ``unregisterCallback(forMessagesWithType:from:)-15wz4``.
     ///
     /// - warning: This method is implemented using ``waitFor(messageFrom:to:timeout:)-24q2d``.
     ///            It is not possible to await a message and message stream simultanosly.
@@ -807,7 +807,7 @@ public extension MeshNetworkManager {
     ///
     /// The destination is optional. If not set it will not be checked.
     ///
-    /// - important: To unregister the callback call ``unregisterCallback(forMessagesWithType:from:)-7mdko``.
+    /// - important: To unregister the callback call ``unregisterCallback(forMessagesWithType:from:)-1g3i0``.
     ///
     /// - warning: This method is implemented using ``waitFor(messageFrom:to:timeout:)-24q2d``.
     ///            It is not possible to await a message and message stream simultanosly.

diff --git a/nRFMeshProvision/MeshNetworkManager.swift b/nRFMeshProvision/MeshNetworkManager.swift
@@ -100,7 +100,6 @@ public class MeshNetworkManager: NetworkParametersProvider {
     ///   - delegateQueue: The `DispatchQueue` to call delegate methods on.
     ///                    By default the global main queue will be used.
     /// - seeAlso: ``LocalStorage``
-    /// - seeAlso: ``LowerTransportLayer.checkAgainstReplayAttack(_:NetworkPdu)``
     public init(using storage: Storage = LocalStorage(),
                 delegateQueue: DispatchQueue = DispatchQueue.main) {
         self.storage = storage