Zephyr API Documentation  3.7.0-rc3
A Scalable Open Source RTOS
Loading...
Searching...
No Matches

Provisioning. More...

Data Structures

struct  bt_mesh_dev_capabilities
 Device Capabilities. More...
 
struct  bt_mesh_prov
 Provisioning properties & capabilities. More...
 

Enumerations

enum  { BT_MESH_PROV_AUTH_CMAC_AES128_AES_CCM , BT_MESH_PROV_AUTH_HMAC_SHA256_AES_CCM }
 Available authentication algorithms. More...
 
enum  { BT_MESH_STATIC_OOB_AVAILABLE = BIT(0) , BT_MESH_OOB_AUTH_REQUIRED = BIT(1) }
 OOB Type field values. More...
 
enum  bt_mesh_output_action_t {
  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)
}
 Available Provisioning output authentication actions. More...
 
enum  bt_mesh_input_action_t {
  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)
}
 Available Provisioning input authentication actions. More...
 
enum  bt_mesh_prov_bearer_t { BT_MESH_PROV_ADV = BIT(0) , BT_MESH_PROV_GATT = BIT(1) , BT_MESH_PROV_REMOTE = BIT(2) }
 Available Provisioning bearers. More...
 
enum  bt_mesh_prov_oob_info_t {
  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_CERTIFICATE = BIT(7) ,
  BT_MESH_PROV_OOB_RECORDS = BIT(8) , 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)
}
 Out of Band information location. More...
 

Functions

int bt_mesh_input_string (const char *str)
 Provide provisioning input OOB string.
 
int bt_mesh_input_number (uint32_t num)
 Provide provisioning input OOB number.
 
int bt_mesh_prov_remote_pub_key_set (const uint8_t public_key[64])
 Provide Device public key.
 
int bt_mesh_auth_method_set_input (bt_mesh_input_action_t action, uint8_t size)
 Use Input OOB authentication.
 
int bt_mesh_auth_method_set_output (bt_mesh_output_action_t action, uint8_t size)
 Use Output OOB authentication.
 
int bt_mesh_auth_method_set_static (const uint8_t *static_val, uint8_t size)
 Use static OOB authentication.
 
int bt_mesh_auth_method_set_none (void)
 Don't use OOB authentication.
 
int bt_mesh_prov_enable (bt_mesh_prov_bearer_t bearers)
 Enable specific provisioning bearers.
 
int bt_mesh_prov_disable (bt_mesh_prov_bearer_t bearers)
 Disable specific provisioning bearers.
 
int bt_mesh_provision (const uint8_t net_key[16], uint16_t net_idx, uint8_t flags, uint32_t iv_index, uint16_t addr, const uint8_t dev_key[16])
 Provision the local Mesh Node.
 
int bt_mesh_provision_adv (const uint8_t uuid[16], uint16_t net_idx, uint16_t addr, uint8_t attention_duration)
 Provision a Mesh Node using PB-ADV.
 
int bt_mesh_provision_gatt (const uint8_t uuid[16], uint16_t net_idx, uint16_t addr, uint8_t attention_duration)
 Provision a Mesh Node using PB-GATT.
 
int bt_mesh_provision_remote (struct bt_mesh_rpr_cli *cli, const struct bt_mesh_rpr_node *srv, const uint8_t uuid[16], uint16_t net_idx, uint16_t addr)
 Provision a Mesh Node using PB-Remote.
 
int bt_mesh_reprovision_remote (struct bt_mesh_rpr_cli *cli, struct bt_mesh_rpr_node *srv, uint16_t addr, bool comp_change)
 Reprovision a Mesh Node using PB-Remote.
 
bool bt_mesh_is_provisioned (void)
 Check if the local node has been provisioned.
 

Detailed Description

Provisioning.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

#include <zephyr/bluetooth/mesh/main.h>

Available authentication algorithms.

Enumerator
BT_MESH_PROV_AUTH_CMAC_AES128_AES_CCM 
BT_MESH_PROV_AUTH_HMAC_SHA256_AES_CCM 

◆ anonymous enum

anonymous enum

#include <zephyr/bluetooth/mesh/main.h>

OOB Type field values.

Enumerator
BT_MESH_STATIC_OOB_AVAILABLE 

Static OOB information available.

BT_MESH_OOB_AUTH_REQUIRED 

OOB authentication required.

◆ bt_mesh_input_action_t

#include <zephyr/bluetooth/mesh/main.h>

Available Provisioning input authentication actions.

Enumerator
BT_MESH_NO_INPUT 
BT_MESH_PUSH 

Push.

BT_MESH_TWIST 

Twist.

BT_MESH_ENTER_NUMBER 

Input number.

BT_MESH_ENTER_STRING 

Input alphanumeric.

◆ bt_mesh_output_action_t

#include <zephyr/bluetooth/mesh/main.h>

Available Provisioning output authentication actions.

Enumerator
BT_MESH_NO_OUTPUT 
BT_MESH_BLINK 

Blink.

BT_MESH_BEEP 

Beep.

BT_MESH_VIBRATE 

Vibrate.

BT_MESH_DISPLAY_NUMBER 

Output numeric.

BT_MESH_DISPLAY_STRING 

Output alphanumeric.

◆ bt_mesh_prov_bearer_t

#include <zephyr/bluetooth/mesh/main.h>

Available Provisioning bearers.

Enumerator
BT_MESH_PROV_ADV 

PB-ADV bearer.

BT_MESH_PROV_GATT 

PB-GATT bearer.

BT_MESH_PROV_REMOTE 

PB-Remote bearer.

◆ bt_mesh_prov_oob_info_t

#include <zephyr/bluetooth/mesh/main.h>

Out of Band information location.

Enumerator
BT_MESH_PROV_OOB_OTHER 

Other.

BT_MESH_PROV_OOB_URI 

Electronic / URI.

BT_MESH_PROV_OOB_2D_CODE 

2D machine-readable code

BT_MESH_PROV_OOB_BAR_CODE 

Bar Code.

BT_MESH_PROV_OOB_NFC 

Near Field Communication (NFC)

BT_MESH_PROV_OOB_NUMBER 

Number.

BT_MESH_PROV_OOB_STRING 

String.

BT_MESH_PROV_OOB_CERTIFICATE 

Support for certificate-based provisioning.

BT_MESH_PROV_OOB_RECORDS 

Support for provisioning records.

BT_MESH_PROV_OOB_ON_BOX 

On box.

BT_MESH_PROV_OOB_IN_BOX 

Inside box.

BT_MESH_PROV_OOB_ON_PAPER 

On piece of paper.

BT_MESH_PROV_OOB_IN_MANUAL 

Inside manual.

BT_MESH_PROV_OOB_ON_DEV 

On device.

Function Documentation

◆ bt_mesh_auth_method_set_input()

int bt_mesh_auth_method_set_input ( bt_mesh_input_action_t  action,
uint8_t  size 
)

#include <zephyr/bluetooth/mesh/main.h>

Use Input OOB authentication.

Provisioner only.

Instruct the unprovisioned device to use the specified Input OOB authentication action. When using BT_MESH_PUSH, BT_MESH_TWIST or BT_MESH_ENTER_NUMBER, the bt_mesh_prov::output_number callback is called with a random number that has to be entered on the unprovisioned device.

When using BT_MESH_ENTER_STRING, the bt_mesh_prov::output_string callback is called with a random string that has to be entered on the unprovisioned device.

Parameters
actionAuthentication action used by the unprovisioned device.
sizeAuthentication size.
Returns
Zero on success or (negative) error code otherwise.

◆ bt_mesh_auth_method_set_none()

int bt_mesh_auth_method_set_none ( void  )

#include <zephyr/bluetooth/mesh/main.h>

Don't use OOB authentication.

Provisioner only.

Don't use any authentication when provisioning new devices. This is the default behavior.

Warning
Not using any authentication exposes the mesh network to impersonation attacks, where attackers can pretend to be the unprovisioned device to gain access to the network. Authentication is strongly encouraged.
Returns
Zero on success or (negative) error code otherwise.

◆ bt_mesh_auth_method_set_output()

int bt_mesh_auth_method_set_output ( bt_mesh_output_action_t  action,
uint8_t  size 
)

#include <zephyr/bluetooth/mesh/main.h>

Use Output OOB authentication.

Provisioner only.

Instruct the unprovisioned device to use the specified Output OOB authentication action. The bt_mesh_prov::input callback will be called.

When using BT_MESH_BLINK, BT_MESH_BEEP, BT_MESH_VIBRATE or BT_MESH_DISPLAY_NUMBER, and the application has to call bt_mesh_input_number with the random number indicated by the unprovisioned device.

When using BT_MESH_DISPLAY_STRING, the application has to call bt_mesh_input_string with the random string displayed by the unprovisioned device.

Parameters
actionAuthentication action used by the unprovisioned device.
sizeAuthentication size.
Returns
Zero on success or (negative) error code otherwise.

◆ bt_mesh_auth_method_set_static()

int bt_mesh_auth_method_set_static ( const uint8_t static_val,
uint8_t  size 
)

#include <zephyr/bluetooth/mesh/main.h>

Use static OOB authentication.

Provisioner only.

Instruct the unprovisioned device to use static OOB authentication, and use the given static authentication value when provisioning.

Parameters
static_valStatic OOB value.
sizeStatic OOB value size.
Returns
Zero on success or (negative) error code otherwise.

◆ bt_mesh_input_number()

int bt_mesh_input_number ( uint32_t  num)

#include <zephyr/bluetooth/mesh/main.h>

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.

Parameters
numNumber.
Returns
Zero on success or (negative) error code otherwise.

◆ bt_mesh_input_string()

int bt_mesh_input_string ( const char *  str)

#include <zephyr/bluetooth/mesh/main.h>

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.

Parameters
strString.
Returns
Zero on success or (negative) error code otherwise.

◆ bt_mesh_is_provisioned()

bool bt_mesh_is_provisioned ( void  )

#include <zephyr/bluetooth/mesh/main.h>

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

Returns
True if the node is provisioned. False otherwise.

◆ bt_mesh_prov_disable()

int bt_mesh_prov_disable ( bt_mesh_prov_bearer_t  bearers)

#include <zephyr/bluetooth/mesh/main.h>

Disable specific provisioning bearers.

Disable one or more provisioning bearers.

Parameters
bearersBit-wise or of provisioning bearers.
Returns
Zero on success or (negative) error code otherwise.

◆ bt_mesh_prov_enable()

int bt_mesh_prov_enable ( bt_mesh_prov_bearer_t  bearers)

#include <zephyr/bluetooth/mesh/main.h>

Enable specific provisioning bearers.

Enable one or more provisioning bearers.

Parameters
bearersBit-wise or of provisioning bearers.
Returns
Zero on success or (negative) error code otherwise.

◆ bt_mesh_prov_remote_pub_key_set()

int bt_mesh_prov_remote_pub_key_set ( const uint8_t  public_key[64])

#include <zephyr/bluetooth/mesh/main.h>

Provide Device public key.

Parameters
public_keyDevice public key in big-endian.
Returns
Zero on success or (negative) error code otherwise.

◆ bt_mesh_provision()

int bt_mesh_provision ( const uint8_t  net_key[16],
uint16_t  net_idx,
uint8_t  flags,
uint32_t  iv_index,
uint16_t  addr,
const uint8_t  dev_key[16] 
)

#include <zephyr/bluetooth/mesh/main.h>

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.

Parameters
net_keyNetwork Key
net_idxNetwork Key Index
flagsProvisioning Flags
iv_indexIV Index
addrPrimary element address
dev_keyDevice Key
Returns
Zero on success or (negative) error code otherwise.

◆ bt_mesh_provision_adv()

int bt_mesh_provision_adv ( const uint8_t  uuid[16],
uint16_t  net_idx,
uint16_t  addr,
uint8_t  attention_duration 
)

#include <zephyr/bluetooth/mesh/main.h>

Provision a Mesh Node using PB-ADV.

Parameters
uuidUUID
net_idxNetwork Key Index
addrAddress to assign to remote device. If addr is 0, the lowest available address will be chosen.
attention_durationThe attention duration to be send to remote device
Returns
Zero on success or (negative) error code otherwise.

◆ bt_mesh_provision_gatt()

int bt_mesh_provision_gatt ( const uint8_t  uuid[16],
uint16_t  net_idx,
uint16_t  addr,
uint8_t  attention_duration 
)

#include <zephyr/bluetooth/mesh/main.h>

Provision a Mesh Node using PB-GATT.

Parameters
uuidUUID
net_idxNetwork Key Index
addrAddress to assign to remote device. If addr is 0, the lowest available address will be chosen.
attention_durationThe attention duration to be send to remote device
Returns
Zero on success or (negative) error code otherwise.

◆ bt_mesh_provision_remote()

int bt_mesh_provision_remote ( struct bt_mesh_rpr_cli cli,
const struct bt_mesh_rpr_node srv,
const uint8_t  uuid[16],
uint16_t  net_idx,
uint16_t  addr 
)

#include <zephyr/bluetooth/mesh/main.h>

Provision a Mesh Node using PB-Remote.

Parameters
cliRemote Provisioning Client Model to provision with.
srvRemote Provisioning Server that should be used to tunnel the provisioning.
uuidUUID of the unprovisioned node
net_idxNetwork Key Index to give to the unprovisioned node.
addrAddress to assign to remote device. If addr is 0, the lowest available address will be chosen.
Returns
Zero on success or (negative) error code otherwise.

◆ bt_mesh_reprovision_remote()

int bt_mesh_reprovision_remote ( struct bt_mesh_rpr_cli cli,
struct bt_mesh_rpr_node srv,
uint16_t  addr,
bool  comp_change 
)

#include <zephyr/bluetooth/mesh/main.h>

Reprovision a Mesh Node using PB-Remote.

Reprovisioning can be used to change the device key, unicast address and composition data of another device. The reprovisioning procedure uses the same protocol as normal provisioning, with the same level of security.

There are three tiers of reprovisioning:

  1. Refreshing the device key
  2. Refreshing the device key and node address. Composition data may change, including the number of elements.
  3. Refreshing the device key and composition data, in case the composition data of the target node changed due to a firmware update or a similar procedure.

The target node indicates that its composition data changed by instantiating its composition data page 128. If the number of elements have changed, it may be necessary to move the unicast address of the target node as well, to avoid overlapping addresses.

Note
Changing the unicast addresses of the target node requires changes to all nodes that publish directly to any of the target node's models.
Parameters
cliRemote Provisioning Client Model to provision on
srvRemote Provisioning Server to reprovision
addrAddress to assign to remote device. If addr is 0, the lowest available address will be chosen.
comp_changeThe target node has indicated that its composition data has changed. Note that the target node will reject the update if this isn't true.
Returns
Zero on success or (negative) error code otherwise.