mirror of
https://git.kernel.org/pub/scm/bluetooth/bluez.git
synced 2024-11-26 21:54:33 +08:00
doc/mesh: Add Remote Provisioning DBus APIs
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
This commit is contained in:
Brian Gix
Brian Gix
parent
5845f003ac
commit
265c12dc96
140
doc/mesh-api.txt
140
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
|
||||
procedure, as defined in the Mesh Profile Specification:
|
||||
0 - Device Key Refresh Only
|
||||
1 - Node Address Refresh
|
||||
2 - Node Composition Refresh
|
||||
|
||||
If not present, procedure 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 procedure was performed.
|
||||
If procedure 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 procedure 1 was performed this
|
||||
value may be different from the original. If procedure 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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user