Proxy

The Proxy feature allows legacy devices like phones to access the Bluetooth Mesh network through GATT. The Proxy feature is only compiled in if the CONFIG_BT_MESH_GATT_PROXY option is set. The Proxy feature state is controlled by the Configuration Server, and the initial value can be set with bt_mesh_cfg_srv.gatt_proxy.

Nodes with the Proxy feature enabled can advertise with Network Identity and Node Identity, which is controlled by the Configuration Client.

The GATT Proxy state indicates if the Proxy feature is supported.

Private Proxy

A node supporting the Proxy feature and the Private Beacon Server model can advertise with Private Network Identity and Private Node Identity types, which is controlled by the Private Beacon Client. By advertising with this set of identification types, the node allows the legacy device to connect to the network over GATT while maintaining the privacy of the network.

The Private GATT Proxy state indicates whether the Private Proxy functionality is supported.

Proxy Solicitation

In the case where both GATT Proxy and Private GATT Proxy states are disabled on a node, a legacy device cannot connect to it. A node supporting the On-Demand Private Proxy Server may however be solicited to advertise connectable advertising events without enabling the Private GATT Proxy state. To solicit the node, the legacy device can send a Solicitation PDU by calling the bt_mesh_proxy_solicit() function. To enable this feature, the device must to be compiled with the CONFIG_BT_MESH_PROXY_SOLICITATION option set.

Solicitation PDUs are non-mesh, non-connectable, undirected advertising messages containing Proxy Solicitation UUID, encrypted with the network key of the subnet that the legacy device wants to connect to. The PDU contains the source address of the legacy device and a sequence number. The sequence number is maintained by the legacy device and is incremented for every new Solicitation PDU sent.

Each node supporting the Solicitation PDU reception holds its own Solicitation Replay Protection List (SRPL). The SRPL protects the solicitation mechanism from replay attacks by storing solicitation sequence number (SSEQ) and solicitation source (SSRC) pairs of valid Solicitation PDUs processed by the node. The delay between updating the SRPL and storing the change to the persistent storage is defined by CONFIG_BT_MESH_RPL_STORE_TIMEOUT.

The Solicitation PDU RPL Configuration models, Solicitation PDU RPL Configuration Client and Solicitation PDU RPL Configuration Server, provide the functionality of saving and clearing SRPL entries. A node that supports the Solicitation PDU RPL Configuration Client model can clear a section of the SRPL on the target by calling the bt_mesh_sol_pdu_rpl_clear() function. Communication between the Solicitation PDU RPL Configuration Client and Server is encrypted using the application key, therefore, the Solicitation PDU RPL Configuration Client can be instantiated on any device in the network.

When the node receives the Solicitation PDU and successfully authenticates it, it will start advertising connectable advertisements with the Private Network Identity type. The duration of the advertisement can be configured by the On-Demand Private Proxy Client model.

API reference

group bt_mesh_proxy

Proxy.

Defines

BT_MESH_PROXY_CB_DEFINE(_name)

Register a callback structure for Proxy events.

Registers a structure with callback functions that gets called on various Proxy events.

Parameters:

_name – Name of callback structure.

Functions

int bt_mesh_proxy_identity_enable(void)

Enable advertising with Node Identity.

This API requires that GATT Proxy support has been enabled. Once called each subnet will start advertising using Node Identity for the next 60 seconds.

Returns:: 0 on success, or (negative) error code on failure.

int bt_mesh_proxy_private_identity_enable(void)

Enable advertising with Private Node Identity.

This API requires that GATT Proxy support has been enabled. Once called each subnet will start advertising using Private Node Identity for the next 60 seconds.

Returns:: 0 on success, or (negative) error code on failure.

int bt_mesh_proxy_connect(uint16_t net_idx)

Allow Proxy Client to auto connect to a network.

This API allows a proxy client to auto-connect a given network.

Parameters:

net_idx – Network Key Index

Returns:

0 on success, or (negative) error code on failure.

int bt_mesh_proxy_disconnect(uint16_t net_idx)

Disallow Proxy Client to auto connect to a network.

This API disallows a proxy client to connect a given network.

Parameters:

net_idx – Network Key Index

Returns:

0 on success, or (negative) error code on failure.

int bt_mesh_proxy_solicit(uint16_t net_idx)

Schedule advertising of Solicitation PDUs.

Once called, the device will schedule advertising Solicitation PDUs for the amount of time defined by adv_int * (CONFIG_BT_MESH_SOL_ADV_XMIT + 1), where adv_int is 20ms for Bluetooth v5.0 or higher, or 100ms otherwise.

If the number of advertised Solicitation PDUs reached 0xFFFFFF, the advertisements will no longer be started until the node is reprovisioned.

Parameters:

net_idx – Network Key Index

Returns:

0 on success, or (negative) error code on failure.

struct bt_mesh_proxy_cb

#include <proxy.h>

Callbacks for the Proxy feature.

Should be instantiated with BT_MESH_PROXY_CB_DEFINE.

Public Members

void (*identity_enabled)(uint16_t net_idx)

Started sending Node Identity beacons on the given subnet.

Param net_idx:: Network index the Node Identity beacons are running on.

void (*identity_disabled)(uint16_t net_idx)

Stopped sending Node Identity beacons on the given subnet.

Param net_idx:: Network index the Node Identity beacons were running on.