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@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
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
