From: Brian Gix <brian.gix@xxxxxxxxx>
Remote Provisioning (introduced in Mesh Profile Specification v1.1)
* Allows Provisioners to use a remote server to scan for and
provision devices.
* Allows Config managers to reprovision existing nodes to:
* Refresh Device Keys
* Reassign Node Addresses
* Refresh Node Composition
---
doc/mesh-api.txt | 140 +++++++++++++++++++++++++++++++++++++++++++++--
1 file changed, 134 insertions(+), 6 deletions(-)
diff --git a/doc/mesh-api.txt b/doc/mesh-api.txt
index 85de6705e..393ae566f 100644
--- a/doc/mesh-api.txt
+++ b/doc/mesh-api.txt
@@ -484,7 +484,28 @@ Methods:
Specifies number of seconds for scanning to be active.
If set to 0 or if this key is not present, then the
scanning will continue until UnprovisionedScanCancel()
- or AddNode() methods are called.
+ or AddNode() methods are called. If not present, and a
+ remote server is specified, the default timeout will be
+ 60 seconds.
+
+ uint16 Server
+ Specifies a remote server on which to perform scanning.
+ If not present, scanning will be local. If present,
+ the timeout must be between 1 and 60 seconds.
+
+ uint16 Subnet
+ Specifies a subnet for the remote server. If not
+ present, primary subnet will be used. If Server not
+ present, the Subnet will be ignored.
+
+ array{byte}[16] Filter
+ Specifies a specific UUID to search for. If not
+ present, all found UUIDs will be returned.
+
+ uint8 array Extended
+ Specifies variable number of Bluetooth AD types to
+ return with scan result. Only valid if a Filter has been
+ specified.
Each time a unique unprovisioned beacon is heard, the
ScanResult() method on the app will be called with the result.
@@ -514,8 +535,48 @@ Methods:
of the unprovisioned device to be added to the network.
The options parameter is a dictionary that may contain
- additional configuration info (currently an empty placeholder
- for forward compatibility).
+ additional optional configuration info:
+
+ uint16 Server
+ Specifies a remote server to perform provisioning on. If
+ not present, provisioning will be done locally.
+
+ uint16 Subnet
+ Specifies a subnet for the remote server. If not
+ present, primary subnet will be used. If Server not
+ present Subnet will be ignored.
+
+ PossibleErrors:
+ org.bluez.mesh.Error.InvalidArguments
+ org.bluez.mesh.Error.NotAuthorized
+
+ void Reprovision(uint16 unicast, dict options)
+
+ This method is used by the application that supports
+ org.bluez.mesh.Provisioner1 interface to perform one of the
+ Node Provisioning Protocol Interface procedures with a remote
+ node to refresh its device key, unicast address, and
+ composition. Remote node being reprovisioned must have the
+ Remote Provisioning Server model.
+
+ The unicast parameter is the 16-bit primary node address of
+ the remote node being reprovisioned.
+
+ The options parameter is a dictionary that may contain
+ additional optional configuration info:
+
+ uint8 NPPI
+ Specifies the Node Provisioning Protocol Interface
+ behavior, as defined in the Mesh Profile Specification:
+ 0 - Device Key Refresh Only
+ 1 - Node Address Refresh
+ 2 - Node Composition Refresh
+
+ If not present, behavior 0 will be used.
+
+ uint16 Subnet
+ Specifies the subnet remote node is on. If not
+ present, primary subnet will be tried.
PossibleErrors:
org.bluez.mesh.Error.InvalidArguments
@@ -1055,11 +1116,19 @@ Object path freely definable
byte remote device UUID (always), a 16 bit mask of OOB
authentication flags (optional), and a 32 bit URI hash (if URI
bit set in OOB mask). Whether these fields exist or not is a
- decision of the remote device.
+ decision of the unprovisioned device.
The options parameter is a dictionary that may contain
- additional scan result info (currently an empty placeholder for
- forward compatibility).
+ additional optional configuration info:
+
+ uint16 Server
+ Specifies the remote server that received the
+ Unprovisioned beacon. If not present, beacon was
+ received locally.
+
+ uint8 array ExtendedData
+ If Extended data was requested during scanning, any
+ received data will be returned here.
If a beacon with a UUID that has already been reported is
recieved by the daemon, it will be silently discarded unless it
@@ -1082,6 +1151,26 @@ Object path freely definable
PossibleErrors:
org.bluez.mesh.Error.Abort
+ uint16 unicast RequestReprovData(uint16 original, uint8 count)
+
+ This method is implemented by a Provisioner capable application
+ and is called when the remote node being reprovisioned has been
+ fully authenticated and confirmed. This method will only be
+ called if the NPPI-1 procedure (Node Address Refresh) is being
+ performed.
+
+ The original parameter is the current unicast address of the
+ node being reprovisioned.
+
+ The count parameter is the number of consecutive unicast
+ addresses the remote node is requesting.
+
+ Return Parameter:
+ unicast - Primary Unicast address of the new node
+
+ PossibleErrors:
+ org.bluez.mesh.Error.Abort
+
void AddNodeComplete(array{byte}[16] uuid, uint16 unicast, uint8 count)
This method is called when the node provisioning initiated
@@ -1096,6 +1185,33 @@ Object path freely definable
The new node may now be sent messages using the credentials
supplied by the RequestProvData method.
+ void ReprovComplete(uint16 original, uint8 nppi, uint16 unicast,
+ uint8 count)
+
+ This method is called when the node Reprovisioning initiated
+ by a Reprovision() method call successfully completed.
+
+ The original parameter is the former primary address of the
+ node that has been reprovisioned.
+
+ The nppi parameter indicates which NPPI behavior was performed.
+ If behavior 1 or 2 was performed, the node is materially
+ different than it was before reprovisioning, and Composition,
+ Bindings, Publication and Subscription settings should be
+ refreshed.
+
+ The unicast parameter is the new primary address that has been
+ assigned to the node, If NPPI behavior 1 was performed this
+ value may be different from the original. If behavior 0 or 2
+ was performed, the original and new primary address should be
+ the same.
+
+ The count parameter is the number of unicast addresses assigned
+ to the node.
+
+ The node may now be sent messages using the credentials
+ supplied by the RequestReprovData method.
+
void AddNodeFailed(array{byte}[16] uuid, string reason)
This method is called when the node provisioning initiated by
@@ -1109,6 +1225,18 @@ Object path freely definable
"decryption-error", "unexpected-error",
"cannot-assign-addresses".
+ void ReprovFailed(uint16 unicast, string reason)
+
+ This method is called when node reprovisioning initiated by
+ Reprovision() has failed. If reprovisioning has failed, the
+ prior credentials of the remote node may still be valid.
+
+ The reason parameter identifies the reason for provisioning
+ failure. The defined values are: "aborted", "timeout",
+ "bad-pdu", "confirmation-failed", "out-of-resources",
+ "decryption-error", "unexpected-error",
+ "cannot-assign-addresses".
+
Provisioning Agent Hierarchy
============================
Service unique name
--
2.39.0
