hub_pairing.h File Reference

Internal pairing-state model for hub‑owned discovery and key‑exchange flows. More...

#include "proto_frame.h"
#include "radio_interface.h"
#include <cstdint>
#include <string>

Include dependency graph for hub_pairing.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	esphome::home_io_control::pairing::PairingContext
	Context object that lives for the duration of a single pairing attempt. More...

Namespaces
namespace	esphome
namespace	esphome::home_io_control
namespace	esphome::home_io_control::pairing

Enumerations
enum class	esphome::home_io_control::pairing::PairingState : uint8_t {   esphome::home_io_control::pairing::IDLE , esphome::home_io_control::pairing::TX_DISCOVER , esphome::home_io_control::pairing::WAIT_DISCOVER_RESPONSE , esphome::home_io_control::pairing::TX_KEY_INIT ,   esphome::home_io_control::pairing::WAIT_KEY_CHALLENGE , esphome::home_io_control::pairing::TX_KEY_TRANSFER , esphome::home_io_control::pairing::WAIT_KEY_CONFIRM , esphome::home_io_control::pairing::REGISTER_DEVICE ,   esphome::home_io_control::pairing::COMPLETE , esphome::home_io_control::pairing::FAILED }
	State machine for the three‑phase pairing flow. More...

Detailed Description

Internal pairing-state model for hub‑owned discovery and key‑exchange flows.

This module implements the three‑phase pairing procedure that temporarily tracks a newly paired device in the controller's runtime registry and installs the system key on the device:

Phase 1 — Discovery (broadcast 0x28 → device responds 0x29): Controller broadcasts a discovery packet on the primary channel. A device in pairing mode (PROG button pressed) responds with its node ID and type/subtype. The controller validates the response and extracts device metadata.

Phase 2 — Authenticated Key Exchange (0x31 → 0x3C → 0x32 → 0x33): The controller sends CMD_KEY_INIT (0x31) to the device. The device challenges with CMD_CHALLENGE_REQ (0x3C). The controller proves knowledge of the system key with CMD_CHALLENGE_RESP (0x3D) and simultaneously sends the encrypted system key via CMD_KEY_TRANSFER (0x32). The device confirms with CMD_KEY_CONFIRM (0x33).

Phase 3 — Configuration (CMD_SET_CONFIG1): The controller sends a configuration frame (0x6F) to enable automatic status updates from the device. This phase completes even if the config frame fails; the device will still operate in polled mode.

All frames use the standard authenticated exchange flow defined in hub_exchange.h. The pairing state machine serializes these phases, logs the YAML metadata the user should add, and keeps the paired device in the current runtime registry until reboot.

Definition in file hub_pairing.h.