A Heartbeat is a Transport Control message that a node broadcasts periodically so that other nodes can figure out the shape of the network — which nodes are reachable and how many hops away they are.

Think of it like a ping in networking — except instead of checking if a server is alive, it helps the mesh understand its own topology.

Heartbeat Message Fields

The Heartbeat Transport Control message uses opcode 0x0A and carries three fields:

InitTTL — Why Does It Matter?

When a Heartbeat is received, the receiving node compares the InitTTL (what TTL the sender started with) against the current TTL (what’s left when it arrived). The difference tells you how many hops the message traveled — that’s the distance!

Features Field — Bit Layout

The 16-bit Features field tells other nodes which capabilities are currently active:

Transport Control messages use a 7-bit opcode. Here is the full opcode table. These messages are not application data — they are internal mesh control signals.

Battery-powered mesh nodes (sensors, switches) cannot stay awake all the time to receive messages. The Friendship feature solves this. A Low Power node (LPN) pairs with a always-on Friend node. The Friend stores incoming messages while the LPN sleeps. When the LPN wakes up, it polls the Friend — “any messages for me?” — and goes back to sleep.

The Three Timing Parameters

Friendship Timing — Step by Step

Friendship is not automatic — the Low Power node must actively find and choose a Friend. Here is the full negotiation flow:

What Terminates Friendship?

If the LPN goes silent long enough that the PollTimeout timer expires on the Friend node, the Friend treats the friendship as terminated. It stops storing messages for that LPN. The LPN would need to run the Friend Request process again to find a new Friend.

BlueZ includes mesh-cfgclient and a mesh daemon (bluetooth-meshd) that implement the full Bluetooth Mesh stack including Heartbeat subscriptions and Friendship. Here are some practical examples using BlueZ tools.

1. Start the Mesh Daemon

# Start the BlueZ mesh daemon (it listens on D-Bus)
sudo bluetooth-meshd --nodetach --debug

# In another terminal, start the config client
mesh-cfgclient

2. Subscribe a Node to Heartbeat Messages

To receive Heartbeat messages, a node must be configured with a Heartbeat Subscription. This is done via the Configuration Model using the mesh-cfgclient tool:

# Inside mesh-cfgclient interactive shell:
# Connect to target node (replace with actual unicast address)
connect 0001

# Set heartbeat subscription
# dst = group address, period = 0x11 (approx 17 seconds), count = 0x11
hb-sub 0001 0x0001 0xC000 0x11 0x11 0x7F 0x00

3. Parsing the Heartbeat Features Field in C (BlueZ Source Style)

#include <stdint.h>
#include <stdio.h>

/* Heartbeat message payload (after opcode) */
struct hb_msg {
    uint8_t  rfu_and_init_ttl;  /* bit7 = RFU, bits 6:0 = InitTTL */
    uint16_t features;          /* little-endian, 16-bit features field */
} __attribute__((packed));

#define HB_FEAT_RELAY      (1 << 0)
#define HB_FEAT_PROXY      (1 << 1)
#define HB_FEAT_FRIEND     (1 << 2)
#define HB_FEAT_LOW_POWER  (1 << 3)

void parse_heartbeat(const uint8_t *pdu, uint8_t len)
{
    if (len < 3)
        return;

    uint8_t  init_ttl = pdu[0] & 0x7F;       /* mask out RFU bit */
    uint16_t features = pdu[1] | (pdu[2] << 8); /* little-endian */

    printf("InitTTL  : %u\n", init_ttl);
    printf("Relay    : %s\n", (features & HB_FEAT_RELAY)     ? "yes" : "no");
    printf("Proxy    : %s\n", (features & HB_FEAT_PROXY)     ? "yes" : "no");
    printf("Friend   : %s\n", (features & HB_FEAT_FRIEND)    ? "yes" : "no");
    printf("LowPower : %s\n", (features & HB_FEAT_LOW_POWER) ? "yes" : "no");
}

4. Hop Count Calculation

/*
 * When a Heartbeat is received, the mesh stack gives us:
 *   - init_ttl : from the Heartbeat payload
 *   - rx_ttl   : the TTL value in the Network PDU when received
 *
 * hop_count = init_ttl - rx_ttl
 * (tells us how many relay hops the message took)
 */
uint8_t calc_hops(uint8_t init_ttl, uint8_t rx_ttl)
{
    if (rx_ttl > init_ttl)
        return 0;           /* should not happen, guard clause */
    return init_ttl - rx_ttl;
}

5. Monitoring Mesh Traffic with btmon

# btmon captures HCI-level traffic — useful to see raw mesh PDUs
sudo btmon -w mesh_capture.btsnoop

# In another terminal, run your mesh application
# Then Ctrl+C btmon and open the file in Wireshark
# Filter: btle.advertising_header.pdu_type == 0x02  (non-connectable adv)
# Mesh PDUs ride inside advertising bearer PDUs