Before diving into individual messages, here is how the overall friendship process flows:

Think of the Friend node as a post office for the LPN. The LPN checks in periodically to collect its mail, then goes back to sleep.

When a Friend node hears a Friend Request from an LPN, it replies with a Friend Offer message. This message tells the LPN what the Friend node can offer — how long it will keep a receive window open, how many messages it can queue, and how many subscription addresses it can track.

ReceiveWindow visualised:

What happens when an LPN wants to switch to a new Friend? Or when it establishes a completely new friendship? The new Friend node sends a Friend Clear message to the old Friend node to terminate the previous friendship.

An LPN can be part of groups — for example, “all lights in room 3” or “all temperature sensors on floor 2”. These are represented as group addresses and virtual addresses.

Since the LPN sleeps, the Friend node must know which group addresses to watch for and store messages from. The LPN tells the Friend node its subscriptions using three messages:

The Heartbeat message is sent by any mesh node to help other nodes figure out the network topology. It is not specific to the Friend feature, but it is part of the same Transport Control message layer.

By counting hops taken for a Heartbeat to arrive, a node can determine how many relay hops away the sender is. This is used to configure TTL values, identify unreachable nodes, and debug mesh connectivity.

BlueZ includes bluetooth-meshd, the Linux Bluetooth Mesh daemon. You can experiment with mesh nodes, including the Friend feature, using the mesh-cfgclient and meshctl tools.

Step 1 — Check if meshd is running:

sudo systemctl status bluetooth-meshd
# or start it manually:
sudo /usr/libexec/bluetooth/bluetooth-meshd --nodetach -d

Step 2 — Launch meshctl (interactive mesh shell):

meshctl

Step 3 — Create or join a mesh network:

[meshctl]# create
# This provisions the local node and creates a new network
# You will get a UUID for the node

Step 4 — Enable the Friend feature on a node via config client:

[meshctl]# menu config
[config]# target 0100
# 0100 is the unicast address of the node

# Set Friend feature ON (bit 1 of feature field)
[config]# set-friend on

Step 5 — Configure heartbeat publication (to monitor topology):

[config]# hb-pub set 0100 FFFF 0A 0A 0 0
# Arguments: dst  count  period  TTL  netkey-index  features
# FFFF = all-nodes address
# TTL 0A = 10 hops max

Step 6 — Inspect raw mesh network traffic with btmon:

sudo btmon
# Look for Network PDU events in the output
# You can filter for opcodes 0x03 through 0x09 in transport control

Step 7 — Python snippet to inspect mesh config via D-Bus:

import dbus

bus = dbus.SystemBus()
mesh_obj = bus.get_object("org.bluez.mesh", "/org/bluez/mesh")
mgr = dbus.Interface(mesh_obj, "org.freedesktop.DBus.ObjectManager")

objects = mgr.GetManagedObjects()
for path, interfaces in objects.items():
    if "org.bluez.mesh.Node1" in interfaces:
        props = interfaces["org.bluez.mesh.Node1"]
        print(f"Node: {path}")
        print(f"  Features: {props.get('Features', 'N/A')}")
        # Features includes friend, relay, proxy flags

Step 8 — Monitor friend establishment in meshd debug logs:

sudo /usr/libexec/bluetooth/bluetooth-meshd --nodetach -d 2>&1 | grep -i friend
# Look for lines like:
# "Friend Request received from 00AA"
# "Sending Friend Offer to 00AA"
# "Friendship established with LPN 00AA"