Bluetooth Mesh Features#

Bluetooth Mesh applications can implement optional networking or energy features. The Bluetooth Mesh Profile Specification defines four features:

  • Proxy

  • Relay

  • Friend

  • Low Power Node (LPN)

This section describes each feature.

Note: These features apply only to Bluetooth Mesh nodes. The provisioner is not subject to feature support.

Proxy#

The Proxy feature allows a node to receive and transmit Bluetooth Mesh messages between GATT and advertising bearers. The proxy feature is used to forward Network packets received by a node between GATT bearer and advertising bearers. This feature is optional and can be enabled/disabled at runtime. When this feature is enabled, the corresponding GATT Proxy service must be exposed.

The Proxy feature defines two roles:

  • Proxy Server – Supports both the GATT bearer and the advertising bearer.

  • Proxy Client – Supports only the GATT bearer.

For a proxy feature to run, the corresponding proxy routine class must be part of the stack initialization table. The following code snippet gives a proxy server example.

static const struct sli_bgapi_class * const btmesh_class_table[] =
{
  SL_BTMESH_BGAPI_CLASS(health_server),
  SL_BTMESH_BGAPI_CLASS(proxy),
  SL_BTMESH_BGAPI_CLASS(proxy_server),
  SL_BTMESH_BGAPI_CLASS(node),
  NULL
};

Relay#

The Relay feature allows a node to receive and retransmit Bluetooth Mesh messages over the advertising bearer, enabling network coverage.

A provisioner can enable the Relay feature on a supported node by using:

sl_status_t sl_btmesh_config_client_set_relay(uint16_t enc_netkey_index,
                                              uint16_t server_address,
                                              uint8_t value,
                                              uint8_t retransmit_count,
                                              uint16_t retransmit_interval_ms,
                                              uint32_t *handle);

A getter function is also available. For more details, refer to the Bluetooth Mesh Configuration Client section of the API HTML documentation.

Note: Limit the number of Relay nodes in large networks. Excessive relay nodes can significantly increase network traffic.

Friend#

The Friend feature allows a node to help a node supporting the Low Power feature to operate by storing messages destined for that node. Friendship is used by Low Power Nodes to limit the amount of time that they need to listen.

The application code for nodes supporting that feature need to enable it using:

  • sl_status_t sl_btmesh_friend_init(void) for enabling the feature.

  • sl_status_t sl_btmesh_friend_deinit(void) for disabling the feature.

For more information, refer to the HTML API Reference delivered with the SDK.

Low Power Node#

The Low Power Node (LPN) feature allows a node to operate within a Bluetooth Mesh network at significantly reduced receiver duty cycles, only in conjunction with a node supporting the Friend feature.

Similarly to the Friend feature, the application code for nodes supporting the Low Power Node feature needs to enable it:

  • sl_status_t sl_btmesh_lpn_init(void)

  • sl_status_t sl_btmesh_lpn_deinit(void)

When the feature has been enabled on a node, and if a node offering friendship is within radio range, the friendship can be established and terminated using the following routines with the associated network key index:

  • sl_status_t sl_btmesh_lpn_establish_friendship(uint16_t netkey_index)

  • sl_status_t sl_btmesh_lpn_terminate_friendship(uint16_t netkey_index)

The Silicon Labs Bluetooth Mesh API allows the user to configure the time interval at which the LPN will poll the friend as well as other time variables:

  • sl_status_t sl_btmesh_lpn_config(uint8_t setting_id, uint32_t value)

The following arrays describes the setting id enum used by the stack to aggregates the LPN configuration values (enum sl_btmesh_lpn_settings_t):

id enum

Value

Description

sl_btmesh_lpn_queue_length

0x0

Minimum queue length that the friend must support. Choose an appropriate length based on the expected message frequency and LPN sleep period because messages that do not fit into the friend queue are dropped. Note that the given value is rounded up to the nearest power of 2. Range: 2..128.

sl_btmesh_lpn_poll_timeout

0x1

Poll timeout in milliseconds, which is the longest time that LPN sleeps in between querying its friend for queued messages. Long poll timeout allows the LPN to sleep for longer periods, at the expense of increased latency for receiving messages. Note that the given value is rounded up to the nearest 100 ms Range: 1 s to 95 h 59 min 59 s 900 ms.

sl_btmesh_lpn_receive_delay

0x2

Receive delay in milliseconds. Receive delay is the time between the LPN sending a request and listening for a response. Receive delay allows the friend node time to prepare the message and LPN to sleep. Range: 10 ms to 255 ms The default receive delay in 10 ms.

sl_btmesh_lpn_request_retries

0x3

Request retry is the number of retry attempts to repeat e.g., the friend poll message if the friend update was not received by the LPN. Range is from 0 to 10, default is 3.

sl_btmesh_lpn_retry_interval

0x4

Time interval between retry attempts in milliseconds. Range is 0 to 100 ms.

sl_btmesh_lpn_clock_accuracy

0x5

Clock accuracy in ppm, which will be taken into account when opening and closing the receive window, and determining the poll timeout. Should be used with care, because inaccurate clock can increase the receive window length to up to 2.5 times in some cases. Default value is 0.

sl_btmesh_lpn_max_receive_window

0x6

Maximum acceptable friend receive window in milliseconds. Friend Offers with a larger receive window will be rejected. This setting also limits how long the LPN waits for Friend Offers, because friends with large receive windows delay their Friend Offer messages longer. Range: 1–255 ms. Default: 255 ms.

sl_btmesh_lpn_min_subscription_list_size

0x7

Minimum subscription list size that the friend must support. Friend Offers with a smaller subscription list size will be rejected. Range: 0–255. Default: 0.

sl_btmesh_lpn_min_friend_offer_rssi

0x8

Minimum acceptable RSSI value in dBm reported in Friend Offer messages. This setting also limits how long the LPN waits for Friend Offers, because friends with low RSSI values delay their Friend Offer messages longer. If the friend does not support RSSI reporting, the empty RSSI value is also accepted. The value is interpreted as a two's complement 8-bit signed integer; the upper 24 bits of the uint32 parameter are ignored. Range: -128–127. Default: -128.

sl_btmesh_lpn_receive_window_factor

0x9

Value for ReceiveWindowFactor. Informs the friend how much it should delay sending its Friend Offer based on its receive window capability. The effective factor is 1 + 0.5 × receive_window_factor. Range: 0–3. Default: 0 (factor of 1.0).

sl_btmesh_lpn_rssi_factor

0xa

Value for RSSIFactor. Informs the friend how much it should delay sending its Friend Offer based on the RSSI it measured for the Friend Request. The effective factor is 1 + 0.5 × rssi_factor. Range: 0–3. Default: 0 (factor of 1.0).

sl_btmesh_lpn_friend_offer_listen_timeout_slack

0xb

Additional time in milliseconds to listen for Friend Offers after their expected arrival time. The expected arrival time is derived from the configured maximum receive window, minimum RSSI, and their respective factors. A non-zero slack compensates for advertisement timing inaccuracies on both ends. If the calculated listen time plus slack would exceed 1000 ms, it is clamped to 1000 ms. Range: 1–1000 ms. Default: 20 ms.

See the Friend Offer Listen Timeout section of the Bluetooth Mesh Node Power Consumption guide for more details about the configuration options and their effect on the LPN power consumption.

Additionally, a friend poll request can be sent from the LPN at any time using the flowing routine with the appropriate network key index:

sl_status_t sl_btmesh_lpn_poll(uint16_t netkey_index)

However, it is not required for correct operation, because the procedure will be performed automatically before the poll timeout expires.

For more information on the friend and LPN API, refer to the HTML API documentation.

Bitmask#

From a practical standpoint, the device composition data of each node contains a 2-byte field indicating the supported features. The following array illustrates the features field:

Bit

Feature

Notes

0

Relay

Relay feature supported if set to 1. 0 otherwise.

1

Proxy

Proxy feature supported if set to 1. 0 otherwise.

2

Friend

Friend feature supported if set to 1. 0 otherwise.

3

Low Power Node (LPN)

LPN feature supported if set to 1. 0 otherwise.

4 - 15

Reserved for future use.

Reserved for future use.

As mentioned in section Bluetooth Mesh Device Composition Data, each node, after provisioning, sends its composition data page 0 to the provisioner. In the code example presented in that section, the macro SL_BTMESH_FEATURE_BITMASK is used with the default value of 3:

sl_btmesh_dcd.c

const uint8_t __mesh_dcd[] = {
  U16TOA(0x02FF), /* Company ID */
  U16TOA(0x0001), /* Product ID */
  U16TOA(0x0700), /* Version Number */
  U16TOA(SL_BTMESH_CONFIG_RPL_SIZE), /* Capacity of Replay Protection List */
  U16TOA(SL_BTMESH_FEATURE_BITMASK), /* Features Bitmask */
  /* Main */
    U16TOA(0x0000), /* Location */
    0x02, /* Number of SIG Models = 2 */
    0x00, /* Number of Vendor Models = 0 */
    /* SIG Models */
      U16TOA(0x0000), /* Configuration Server */
      U16TOA(0x0002), /* Health Server */
};

sl_btmesh_.h

#define SL_BTMESH_FEATURE_BITMASK 3

In this example, that macro enables the relay and proxy features (3) in the Bluetooth Mesh stack. This is the default setting.