In Bluetooth Classic, every device has a unique hardware address called BD_ADDR. In Bluetooth Mesh, that’s not required. Instead, every node gets a 128-bit number called a Device UUID.

During the Key Refresh procedure, the Configuration Client uses the device key (established during provisioning) to securely send new keys to each specific node — this is why every node’s UUID must be unique.

The whole process happens in three clean phases. The network never goes fully offline — devices keep communicating throughout. Here’s the big picture:

Notice that during Phases 1 and 2, nodes accept both old and new keys for receiving. This is the transition window that keeps the network alive while all nodes slowly update.

The Configuration Client (think of it as the mesh network manager — typically a phone or gateway running BlueZ mesh tools) starts Phase 1. It decides which nodes will get the new keys and which ones will be blacklisted.

It sends two types of config messages to each non-blacklisted node:

• Config NetKey Update — delivers the new network key
• Config AppKey Update — delivers new application key(s) bound to the NetKey

Low Power Nodes (LPN) caution: LPNs sleep most of the time and only wake up to poll their Friend node. The Config Client must check the PollTimeout timer and retry key delivery accordingly — LPNs can take much longer to receive the new keys.

Using BlueZ’s mesh tools, you can interact with the Configuration Client model via D-Bus. Here’s how to inspect and trigger key operations:

# Start BlueZ mesh daemon (ensure bluetooth.service is running)
sudo systemctl start bluetooth

# Launch interactive mesh-cfgclient tool
sudo mesh-cfgclient

# Inside mesh-cfgclient shell:
# List known nodes and their addresses
list-nodes

# Get the current key refresh phase for a node at address 0x0005
get-composition 0005

# Send a NetKey Update to node 0x0005 (Phase 1 trigger)
# net-update <node-addr> <net-index>
net-update 0005 0000

# Send AppKey Update bound to NetKey index 0x0000
# app-update <node-addr> <net-index> <app-index>
app-update 0005 0000 0000

# Once all nodes are updated, push Phase 2 beacon
# key-refresh-phase <node-addr> <net-index> <transition>
# transition=2 moves to Phase 2
key-refresh-phase 0005 0000 2

# transition=3 triggers Phase 3 (revoke old keys)
key-refresh-phase 0005 0000 3

Note: The exact CLI commands depend on your BlueZ version. The underlying D-Bus interface is org.bluez.mesh.Management1. For scripted automation, use the Python bluetooth-mesh library which wraps these D-Bus calls.

// Python bluetooth-mesh library example (Phase 1 via D-Bus)
// Install: pip3 install bluetooth-mesh

import asyncio
from bluetooth_mesh.application import Application
from bluetooth_mesh.messages.config import ConfigNetKeyUpdateMessage

async def send_netkey_update(app, node_addr, net_index, new_key_bytes):
    # Build the Config NetKey Update message
    msg = ConfigNetKeyUpdateMessage.build(dict(
        net_key_index=net_index,
        net_key=new_key_bytes
    ))
    # Send using device key of target node
    await app.send_dev(
        destination=node_addr,
        app_index=0,
        data=msg
    )
    print(f"NetKey Update sent to node 0x{node_addr:04X}")

asyncio.run(send_netkey_update(app, 0x0005, 0x0000, new_key))

Once every non-blacklisted node has the new keys stored, the Config Client kicks off Phase 2. It does this in one of two ways:

In Phase 2, each node:

• Transmits packets using new keys only
• Receives packets using both old and new keys (so no one gets locked out mid-transition)
• Only processes Secure Network Beacons secured with the new NetKey

This is the final step. The Config Client sends another Secure Network Beacon (or a Config Key Refresh Phase Set with transition=3) signalling all nodes to drop the old keys entirely.

After Phase 3:

• All nodes transmit and receive using only Key A2
• The blacklisted nodes still only have Key A1 — they are now completely cut off
• The mesh is back to normal operation, just with fresh keys

# Inside mesh-cfgclient: trigger Phase 3 (revoke old keys)
# This sends Config Key Refresh Phase Set with transition=3
# which tells each node to permanently drop Key A1

key-refresh-phase 0005 0000 3

# Alternatively, the Secure Network beacon with Key Refresh Flag=0
# transmitted using the NEW key automatically triggers Phase 3
# on any node that receives it while still in Phase 1

# Verify the current key refresh state of a node
get-key-refresh-phase 0005 0000
# Expected output: Phase 0 (normal operation with new key)

Here is how the four states (Phase 0 through Phase 3) connect to each other and what triggers each transition:

The spec has strict rules about when update messages are valid. Violating these causes errors:

Also: if a node is in Phase 1 and receives a Secure Network Beacon with Key Refresh Flag=0 using the new NetKey, it jumps straight to Phase 3 — skipping Phase 2 entirely. This is an optimisation for smaller networks.