137 lines
5.2 KiB
ReStructuredText
137 lines
5.2 KiB
ReStructuredText
.. _bluetooth_mesh_provisioning:
|
|
|
|
Provisioning
|
|
############
|
|
|
|
Provisioning is the process of adding devices to a mesh network. It requires
|
|
two devices operating in the following roles:
|
|
|
|
* The *provisioner* represents the network owner, and is responsible for
|
|
adding new nodes to the mesh network.
|
|
* The *provisionee* is the device that gets added to the network through the
|
|
Provisioning process. Before the provisioning process starts, the
|
|
provisionee is an *unprovisioned device*.
|
|
|
|
The Provisioning module in the Zephyr Bluetooth Mesh stack supports both the
|
|
Advertising and GATT Provisioning bearers for the provisionee role, as well as
|
|
the Advertising Provisioning bearer for the provisioner role.
|
|
|
|
The Provisioning process
|
|
************************
|
|
|
|
All Bluetooth Mesh nodes must be provisioned before they can participate in a
|
|
Bluetooth Mesh network. The Provisioning API provides all the functionality
|
|
necessary for a device to become a provisioned mesh node.
|
|
|
|
Beaconing
|
|
=========
|
|
|
|
To start the provisioning process, the unprovisioned device must first start
|
|
broadcasting the Unprovisioned Beacon. This makes it visible to nearby
|
|
provisioners, which can initiate the provisioning. To indicate that the device
|
|
needs to be provisioned, call :cpp:func:`bt_mesh_prov_enable()`. The device
|
|
starts broadcasting the Unprovisioned Beacon with the device UUID and the
|
|
``OOB information`` field, as specified in the ``prov`` parameter passed to
|
|
:cpp:func:`bt_mesh_init`. Additionally, a Uniform Resource Identifier (URI)
|
|
may be specified, which can point the provisioner to the location of some Out
|
|
Of Band information, such as the device's public key or an authentication
|
|
value database. The URI is advertised in a separate beacon, with a URI hash
|
|
included in the unprovisioned beacon, to tie the two together.
|
|
|
|
|
|
Uniform Resource Identifier
|
|
---------------------------
|
|
|
|
The Uniform Resource Identifier shall follow the format specified in the
|
|
Bluetooth Core Specification Supplement. The URI must start with a URI scheme,
|
|
encoded as a single utf-8 data point, or the special ``none`` scheme, encoded
|
|
as ``0x01``. The available schemes are listed on the `Bluetooth website
|
|
<https://www.bluetooth.com/specifications/assigned-numbers/uri-scheme-name-string-mapping/>`_.
|
|
|
|
Examples of encoded URIs:
|
|
|
|
.. list-table:: URI encoding examples
|
|
|
|
* - URI
|
|
- Encoded
|
|
* - ``http://example.com``
|
|
- ``\x16//example.com``
|
|
* - ``https://www.zephyrproject.org/``
|
|
- ``\x17//www.zephyrproject.org/``
|
|
* - ``just a string``
|
|
- ``\x01just a string``
|
|
|
|
Provisioning invitation
|
|
=======================
|
|
|
|
The provisioner initiates the Provisioning process by sending a Provisioning
|
|
invitation. The invitations prompts the provisionee to call attention to
|
|
itself using the Health Server
|
|
:ref:`bluetooth_mesh_models_health_srv_attention`, if available.
|
|
|
|
The Unprovisioned device automatically responds to the invite by presenting a
|
|
list of its capabilities, including the supported Out of Band Authentication
|
|
methods.
|
|
|
|
Authentication
|
|
==============
|
|
|
|
After the initial exchange, the provisioner selects an Out of Band (OOB)
|
|
Authentication method. This allows the user to confirm that the device the
|
|
provisioner connected to is actually the device they intended, and not a
|
|
malicious third party.
|
|
|
|
The Provisioning API supports the following authentication methods for the
|
|
provisionee:
|
|
|
|
* **Static OOB:** An authentication value is assigned to the device in
|
|
production, which the provisioner can query in some application specific
|
|
way.
|
|
* **Input OOB:** The user inputs the authentication value. The available input
|
|
actions are listed in :cpp:enum:`bt_mesh_input_action_t`.
|
|
* **Output OOB:** Show the user the authentication value. The available output
|
|
actions are listed in :cpp:enum:`bt_mesh_output_action_t`.
|
|
|
|
The application must provide callbacks for the supported authentication
|
|
methods in :cpp:type:`bt_mesh_prov`, as well as enabling the supported actions
|
|
in :cpp:var:`bt_mesh_prov::output_actions` and
|
|
:cpp:var:`bt_mesh_prov::input_actions`.
|
|
|
|
When an Output OOB action is selected, the authentication value should be
|
|
presented to the user when the output callback is called, and remain until the
|
|
:cpp:var:`bt_mesh_prov::input_complete` or :cpp:var:`bt_mesh_prov::complete`
|
|
callback is called. If the action is ``blink``, ``beep`` or ``vibrate``, the
|
|
sequence should be repeated after a delay of three seconds or more.
|
|
|
|
When an Input OOB action is selected, the user should be prompted when the
|
|
application receives the :cpp:var:`bt_mesh_prov::input` callback. The user
|
|
response should be fed back to the Provisioning API through
|
|
:cpp:func:`bt_mesh_input_string()` or :cpp:func:`bt_mesh_input_number()`. If
|
|
no user response is recorded within 60 seconds, the Provisioning process is
|
|
aborted.
|
|
|
|
Data transfer
|
|
=============
|
|
|
|
After the device has been successfully authenticated, the provisioner
|
|
transfers the Provisioning data:
|
|
|
|
* Unicast address
|
|
* A network key
|
|
* IV index
|
|
* Network flags
|
|
|
|
* Key refresh
|
|
* IV update
|
|
|
|
Additionally, a device key is generated for the node. All this data is stored
|
|
by the mesh stack, and the provisioning :cpp:var:`bt_mesh_prov::complete`
|
|
callback gets called.
|
|
|
|
API reference
|
|
*************
|
|
|
|
.. doxygengroup:: bt_mesh_prov
|
|
:project: Zephyr
|
|
:members:
|