The latest development version of this page may be more current than this released 2.2.1 version.

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

Examples of encoded URIs:

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 Attention state, 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 bt_mesh_input_action_t.
Output OOB: Show the user the authentication value. The available output actions are listed in bt_mesh_output_action_t.

The application must provide callbacks for the supported authentication methods in bt_mesh_prov, as well as enabling the supported actions in bt_mesh_prov::output_actions and 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 bt_mesh_prov::input_complete or 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 bt_mesh_prov::input callback. The user response should be fed back to the Provisioning API through bt_mesh_input_string() or 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 bt_mesh_prov::complete callback gets called.

API reference¶

group bt_mesh_prov

Bluetooth Mesh Provisioning.

Enums

enum bt_mesh_output_action_t¶

Available Provisioning output authentication actions.

Values:

BT_MESH_NO_OUTPUT = 0¶

BT_MESH_BLINK = BIT(0)¶

BT_MESH_BEEP = BIT(1)¶

BT_MESH_VIBRATE = BIT(2)¶

BT_MESH_DISPLAY_NUMBER = BIT(3)¶

BT_MESH_DISPLAY_STRING = BIT(4)¶

enum bt_mesh_input_action_t¶

Available Provisioning input authentication actions.

Values:

BT_MESH_NO_INPUT = 0¶

BT_MESH_PUSH = BIT(0)¶

BT_MESH_TWIST = BIT(1)¶

BT_MESH_ENTER_NUMBER = BIT(2)¶

BT_MESH_ENTER_STRING = BIT(3)¶

enum bt_mesh_prov_bearer_t¶

Available Provisioning bearers.

Values:

BT_MESH_PROV_ADV = BIT(0)¶

BT_MESH_PROV_GATT = BIT(1)¶

enum bt_mesh_prov_oob_info_t¶

Out of Band information location.

Values:

BT_MESH_PROV_OOB_OTHER = BIT(0)¶

BT_MESH_PROV_OOB_URI = BIT(1)¶

BT_MESH_PROV_OOB_2D_CODE = BIT(2)¶

BT_MESH_PROV_OOB_BAR_CODE = BIT(3)¶

BT_MESH_PROV_OOB_NFC = BIT(4)¶

BT_MESH_PROV_OOB_NUMBER = BIT(5)¶

BT_MESH_PROV_OOB_STRING = BIT(6)¶

BT_MESH_PROV_OOB_ON_BOX = BIT(11)¶

BT_MESH_PROV_OOB_IN_BOX = BIT(12)¶

BT_MESH_PROV_OOB_ON_PAPER = BIT(13)¶

BT_MESH_PROV_OOB_IN_MANUAL = BIT(14)¶

BT_MESH_PROV_OOB_ON_DEV = BIT(15)¶

Functions

int bt_mesh_input_string(const char *str)¶

Provide provisioning input OOB string.

This is intended to be called after the bt_mesh_prov input callback has been called with BT_MESH_ENTER_STRING as the action.

Return

Zero on success or (negative) error code otherwise.

Parameters

str: String.

int bt_mesh_input_number(u32_t num)¶

Provide provisioning input OOB number.

This is intended to be called after the bt_mesh_prov input callback has been called with BT_MESH_ENTER_NUMBER as the action.

Return

Zero on success or (negative) error code otherwise.

Parameters

num: Number.

int bt_mesh_prov_enable(bt_mesh_prov_bearer_t bearers)¶

Enable specific provisioning bearers.

Enable one or more provisioning bearers.

Return

Zero on success or (negative) error code otherwise.

Parameters

bearers: Bit-wise or of provisioning bearers.

int bt_mesh_prov_disable(bt_mesh_prov_bearer_t bearers)¶

Disable specific provisioning bearers.

Disable one or more provisioning bearers.

Return

Zero on success or (negative) error code otherwise.

Parameters

bearers: Bit-wise or of provisioning bearers.

int bt_mesh_provision(const u8_t net_key[16], u16_t net_idx, u8_t flags, u32_t iv_index, u16_t addr, const u8_t dev_key[16])¶

Provision the local Mesh Node.

This API should normally not be used directly by the application. The only exception is for testing purposes where manual provisioning is desired without an actual external provisioner.

Return

Zero on success or (negative) error code otherwise.

Parameters

net_key: Network Key
net_idx: Network Key Index
flags: Provisioning Flags
iv_index: IV Index
addr: Primary element address
dev_key: Device Key

int bt_mesh_provision_adv(const u8_t uuid[16], u16_t net_idx, u16_t addr, u8_t attention_duration)¶

Provision a Mesh Node using PB-ADV.

Return

Zero on success or (negative) error code otherwise.

Parameters

uuid: UUID
net_idx: Network Key Index
addr: Address to assign to remote device. If addr is 0, the lowest available address will be chosen.
attention_duration: The attention duration to be send to remote device

bool bt_mesh_is_provisioned(void)¶

Check if the local node has been provisioned.

This API can be used to check if the local node has been provisioned or not. It can e.g. be helpful to determine if there was a stored network in flash, i.e. if the network was restored after calling settings_load().

Return: True if the node is provisioned. False otherwise.

struct bt_mesh_prov¶

#include <main.h>

Provisioning properties & capabilities.

Public Members

const u8_t *uuid¶: The UUID that’s used when advertising as unprovisioned

const char *uri¶: Optional URI. This will be advertised separately from the unprovisioned beacon, however the unprovisioned beacon will contain a hash of it so the two can be associated by the provisioner.

bt_mesh_prov_oob_info_t oob_info¶: Out of Band information field.

const u8_t *static_val¶: Static OOB value

u8_t static_val_len¶: Static OOB value length

u8_t output_size¶: Maximum size of Output OOB supported

u16_t output_actions¶: Supported Output OOB Actions

u8_t input_size¶: Maximum size of Input OOB supported

u16_t input_actions¶: Supported Input OOB Actions

int (*output_number)(bt_mesh_output_action_t act, u32_t num)¶

Output of a number is requested.

This callback notifies the application that it should output the given number using the given action.

Return

Zero on success or negative error code otherwise

Parameters

act: Action for outputting the number.
num: Number to be outputted.

int (*output_string)(const char *str)¶

Output of a string is requested.

This callback notifies the application that it should display the given string to the user.

Return

Zero on success or negative error code otherwise

Parameters

str: String to be displayed.

int (*input)(bt_mesh_input_action_t act, u8_t size)¶

Input is requested.

This callback notifies the application that it should request input from the user using the given action. The requested input will either be a string or a number, and the application needs to consequently call the bt_mesh_input_string() or bt_mesh_input_number() functions once the data has been acquired from the user.

Return

Zero on success or negative error code otherwise

Parameters

act: Action for inputting data.
num: Maximum size of the inputted data.

void (*input_complete)(void)¶

The other device finished their OOB input.

This callback notifies the application that it should stop displaying its output OOB value, as the other party finished their OOB input.

void (*unprovisioned_beacon)(u8_t uuid[16], bt_mesh_prov_oob_info_t oob_info, u32_t *uri_hash)¶

Unprovisioned beacon has been received.

This callback notifies the application that an unprovisioned beacon has been received.

Parameters

uuid: UUID
oob_info: OOB Information
uri_hash: Pointer to URI Hash value. NULL if no hash was present in the beacon.

void (*link_open)(bt_mesh_prov_bearer_t bearer)¶

Provisioning link has been opened.

This callback notifies the application that a provisioning link has been opened on the given provisioning bearer.

Parameters

bearer: Provisioning bearer.

void (*link_close)(bt_mesh_prov_bearer_t bearer)¶

Provisioning link has been closed.

This callback notifies the application that a provisioning link has been closed on the given provisioning bearer.

Parameters

bearer: Provisioning bearer.

void (*complete)(u16_t net_idx, u16_t addr)¶

Provisioning is complete.

This callback notifies the application that provisioning has been successfully completed, and that the local node has been assigned the specified NetKeyIndex and primary element address.

Parameters

net_idx: NetKeyIndex given during provisioning.
addr: Primary element address.

void (*node_added)(u16_t net_idx, u8_t uuid[16], u16_t addr, u8_t num_elem)¶

A new node has been added to the provisioning database.

This callback notifies the application that provisioning has been successfully completed, and that a node has been assigned the specified NetKeyIndex and primary element address.

Parameters

net_idx: NetKeyIndex given during provisioning.
uuid: UUID of the added node
addr: Primary element address.
num_elem: Number of elements that this node has.

void (*reset)(void)¶

Node has been reset.

This callback notifies the application that the local node has been reset and needs to be reprovisioned. The node will not automatically advertise as unprovisioned, rather the bt_mesh_prov_enable() API needs to be called to enable unprovisioned advertising on one or more provisioning bearers.