Heartbeat
The Heartbeat feature provides functionality for monitoring Bluetooth Mesh nodes and determining the distance between nodes.
The Heartbeat feature is configured through the Configuration Server model.
Heartbeat messages
Heartbeat messages are sent as transport control packets through the network, and are only encrypted with a network key. Heartbeat messages contain the original Time To Live (TTL) value used to send the message and a bitfield of the active features on the node. Through this, a receiving node can determine how many relays the message had to go through to arrive at the receiver, and what features the node supports.
Available Heartbeat feature flags:
Heartbeat publication
Heartbeat publication is controlled through the Configuration models, and can be triggered in two ways:
- Periodic publication
The node publishes a new Heartbeat message at regular intervals. The publication can be configured to stop after a certain number of messages, or continue indefinitely.
- Triggered publication
The node publishes a new Heartbeat message every time a feature changes. The set of features that can trigger the publication is configurable.
The two publication types can be combined.
Heartbeat subscription
A node can be configured to subscribe to Heartbeat messages from one node at the time. To receive a Heartbeat message, both the source and destination must match the configured subscription parameters.
Heartbeat subscription is always time limited, and throughout the subscription period, the node keeps track of the number of received Heartbeats as well as the minimum and maximum received hop count.
All Heartbeats received with the configured subscription parameters are passed
to the bt_mesh_hb_cb::recv event handler.
When the Heartbeat subscription period ends, the
bt_mesh_hb_cb::sub_end callback gets called.
API reference
- group bt_mesh_heartbeat
Heartbeat.
Defines
-
BT_MESH_HB_CB_DEFINE(_name)
Register a callback structure for Heartbeat events.
Registers a callback structure that will be called whenever Heartbeat events occur
- Parameters:
_name – Name of callback structure.
Functions
-
void bt_mesh_hb_pub_get(struct bt_mesh_hb_pub *get)
Get the current Heartbeat publication parameters.
- Parameters:
get – Heartbeat publication parameters return buffer.
-
void bt_mesh_hb_sub_get(struct bt_mesh_hb_sub *get)
Get the current Heartbeat subscription parameters.
- Parameters:
get – Heartbeat subscription parameters return buffer.
-
struct bt_mesh_hb_pub
- #include <heartbeat.h>
Heartbeat Publication parameters.
Public Members
-
uint16_t dst
Destination address.
-
uint16_t count
Remaining publish count.
-
uint8_t ttl
Time To Live value.
-
uint16_t feat
Bitmap of features that trigger a Heartbeat publication if they change.
Legal values are BT_MESH_FEAT_RELAY, BT_MESH_FEAT_PROXY, BT_MESH_FEAT_FRIEND and BT_MESH_FEAT_LOW_POWER.
-
uint16_t net_idx
Network index used for publishing.
-
uint32_t period
Publication period in seconds.
-
uint16_t dst
-
struct bt_mesh_hb_sub
- #include <heartbeat.h>
Heartbeat Subscription parameters.
Public Members
-
uint32_t period
Subscription period in seconds.
-
uint32_t remaining
Remaining subscription time in seconds.
-
uint16_t src
Source address to receive Heartbeats from.
-
uint16_t dst
Destination address to received Heartbeats on.
-
uint16_t count
The number of received Heartbeat messages so far.
-
uint8_t min_hops
Minimum hops in received messages, ie the shortest registered path from the publishing node to the subscribing node.
A Heartbeat received from an immediate neighbor has hop count = 1.
-
uint8_t max_hops
Maximum hops in received messages, ie the longest registered path from the publishing node to the subscribing node.
A Heartbeat received from an immediate neighbor has hop count = 1.
-
uint32_t period
-
struct bt_mesh_hb_cb
- #include <heartbeat.h>
Heartbeat callback structure.
Public Members
-
void (*recv)(const struct bt_mesh_hb_sub *sub, uint8_t hops, uint16_t feat)
Receive callback for heartbeats.
Gets called on every received Heartbeat that matches the current Heartbeat subscription parameters.
- Param sub:
Current Heartbeat subscription parameters.
- Param hops:
The number of hops the Heartbeat was received with.
- Param feat:
The feature set of the publishing node. The value is a bitmap of BT_MESH_FEAT_RELAY, BT_MESH_FEAT_PROXY, BT_MESH_FEAT_FRIEND and BT_MESH_FEAT_LOW_POWER.
-
void (*sub_end)(const struct bt_mesh_hb_sub *sub)
Subscription end callback for heartbeats.
Gets called when the subscription period ends, providing a summary of the received heartbeat messages.
- Param sub:
Current Heartbeat subscription parameters.
-
void (*pub_sent)(const struct bt_mesh_hb_pub *pub)
Publication sent callback for heartbeats.
Gets called when the heartbeat is successfully published.
- Param pub:
Current Heartbeat publication parameters.
-
void (*recv)(const struct bt_mesh_hb_sub *sub, uint8_t hops, uint16_t feat)
-
BT_MESH_HB_CB_DEFINE(_name)