1.. _bluetooth_mesh_heartbeat:
2
3Heartbeat
4#########
5
6The Heartbeat feature provides functionality for monitoring Bluetooth mesh nodes
7and determining the distance between nodes.
8
9The Heartbeat feature is configured through the :ref:`bluetooth_mesh_models_cfg_srv` model.
10
11Heartbeat messages
12******************
13
14Heartbeat messages are sent as transport control packets through the network,
15and are only encrypted with a network key. Heartbeat messages contain the
16original Time To Live (TTL) value used to send the message and a bitfield of
17the active features on the node. Through this, a receiving node can determine
18how many relays the message had to go through to arrive at the receiver, and
19what features the node supports.
20
21Available Heartbeat feature flags:
22
23- :c:macro:`BT_MESH_FEAT_RELAY`
24- :c:macro:`BT_MESH_FEAT_PROXY`
25- :c:macro:`BT_MESH_FEAT_FRIEND`
26- :c:macro:`BT_MESH_FEAT_LOW_POWER`
27
28Heartbeat publication
29*********************
30
31Heartbeat publication is controlled through the Configuration models, and can
32be triggered in two ways:
33
34Periodic publication
35   The node publishes a new Heartbeat message at regular intervals. The
36   publication can be configured to stop after a certain number of messages, or
37   continue indefinitely.
38
39Triggered publication
40   The node publishes a new Heartbeat message every time a feature changes. The
41   set of features that can trigger the publication is configurable.
42
43The two publication types can be combined.
44
45Heartbeat subscription
46**********************
47
48A node can be configured to subscribe to Heartbeat messages from one node at
49the time. To receive a Heartbeat message, both the source and destination must
50match the configured subscription parameters.
51
52Heartbeat subscription is always time limited, and throughout the subscription
53period, the node keeps track of the number of received Heartbeats as well as
54the minimum and maximum received hop count.
55
56All Heartbeats received with the configured subscription parameters are passed
57to the :cpp:member:`bt_mesh_hb_cb::recv` event handler.
58
59When the Heartbeat subscription period ends, the
60:cpp:member:`bt_mesh_hb_cb::sub_end` callback gets called.
61
62API reference
63**************
64
65.. doxygengroup:: bt_mesh_heartbeat
66