| Message ID | 20230124202616.310544-1-brian.gix@gmail.com |
|---|---|
| Headers | show |
| Series | Mesh v1.1 additions | expand |
Hi Brian, Just a few terminology comments to make t consistent with the spec. On Tue, 2023-01-24 at 12:26 -0800, Brian Gix wrote: > From: Brian Gix <brian.gix@intel.com> > > 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 ingas: "behavior" -> "procedure" > Specification: > + 0 - Device Key Refresh Only > + 1 - Node Address Refresh > + 2 - Node Composition Refresh > + > + If not present, behavior 0 will be used. ingas: "behavior" -> "procedure" > + > + 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. ingas: "behavior" -> "procedure" > + If behavior 1 or 2 was performed, the node is ingas: "behavior" -> "procedure" > 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 ingas: "," -> "." "behavior" -> "procedure" > performed this > + value may be different from the original. If behavior > 0 or 2 ingas: "behavior" -> "procedure" > + 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