hub_exchange.h File Reference

Internal exchange-state model for hub-owned authenticated non‑pairing flows. More...

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

Include dependency graph for hub_exchange.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::exchange::OutboundExchangeContext
	Context carried across one outbound authenticated exchange. More...
struct	esphome::home_io_control::exchange::InboundAuthContext
	Context for a single inbound authentication (device‑initiated command). More...
struct	esphome::home_io_control::ListenSpec
	How one listen window is to be spent — everything ExchangeEngine::listen() needs; everything else is the handler's business. More...

Namespaces
namespace	esphome
namespace	esphome::home_io_control
namespace	esphome::home_io_control::exchange

Typedefs
using	esphome::home_io_control::ReplyHandler = std::function<ReplyDisposition(const IoFrame *parsed, const RadioRxPacket &packet)>
	Invoked for every packet the radio delivers during a listen, before the listen decides whether to keep waiting.

Enumerations
enum class	esphome::home_io_control::exchange::OutboundExchangeState : uint8_t {   esphome::home_io_control::exchange::IDLE , esphome::home_io_control::exchange::TX_REQUEST , esphome::home_io_control::exchange::WAIT_FIRST_RESPONSE , esphome::home_io_control::exchange::BUILD_AUTH_RESPONSE ,   esphome::home_io_control::exchange::TX_AUTH_RESPONSE , esphome::home_io_control::exchange::WAIT_FINAL_RESPONSE , esphome::home_io_control::exchange::SUCCESS , esphome::home_io_control::exchange::FAILED }
	Progress stages of an outbound authenticated exchange (non‑pairing). More...
enum class	esphome::home_io_control::exchange::InboundAuthState : uint8_t {   esphome::home_io_control::exchange::IDLE , esphome::home_io_control::exchange::TX_CHALLENGE , esphome::home_io_control::exchange::WAIT_CHALLENGE_RESPONSE , esphome::home_io_control::exchange::VERIFIED ,   esphome::home_io_control::exchange::FAILED }
	Progress stages of inbound authentication (device‑initiated commands). More...
enum class	esphome::home_io_control::ListenPolicy : uint8_t { esphome::home_io_control::HOLD_REQUEST_CHANNEL , esphome::home_io_control::ROTATE_ALL_CHANNELS , esphome::home_io_control::ROTATE_SKIPPING_REQUEST }
	Which channels a listen covers. More...
enum class	esphome::home_io_control::ReplyDisposition : uint8_t { esphome::home_io_control::ACCEPT , esphome::home_io_control::IGNORE , esphome::home_io_control::ABORT }
	What the caller wants done with the frame a listen just received. More...
enum class	esphome::home_io_control::ListenOutcome : uint8_t { esphome::home_io_control::ACCEPTED , esphome::home_io_control::ABORTED , esphome::home_io_control::TIMED_OUT }
	How one call to ExchangeEngine::listen() ended. More...

Detailed Description

Internal exchange-state model for hub-owned authenticated non‑pairing flows.

This module defines the progress-stage enums and context structures used for outbound authenticated exchanges (controller → device) and inbound authentication (device → controller). These are the building blocks that power commands like set_position, request_status, and handling unsolicited status‑update frames.

Note on the enums: ExchangeEngine's blocking helpers drive control flow through the decisions:: classifiers; the state enums below are written at each step but only read back by the exchange debug snapshot, so log lines can name the stage an exchange reached before failing.

Exchange lifecycle (outbound):

1. Controller sends a command with START flag (e.g., CMD_EXECUTE, CMD_PRIVATE).
2. Device may challenge with CMD_CHALLENGE_REQ (0x3C) if it requires auth.
3. Controller computes HMAC and responds with CMD_CHALLENGE_RESP (0x3D).
4. Device finally sends the response frame (e.g., CMD_PRIVATE_RESP with position).

Inbound authentication (device-initiated): Device sends a command that requires verification (e.g., CMD_STATUS_UPDATE). Controller challenges with 0x3C, device proves knowledge of system key with 0x3D, controller acknowledges with CMD_STATUS_UPDATE_RESP (0x72).

Both paths rely on the HMAC construction defined in proto_crypto.h which uses AES-128-ECB to encrypt an IV derived from the original frame bytes and a 6-byte random challenge.

This header also defines the shared listen primitive's types (ListenPolicy, ReplyDisposition, ListenOutcome, ReplyHandler, ListenSpec) — the single channel-policy-aware wait loop both ExchangeEngine's outbound waits and PairingEngine's waits are built on. See ExchangeEngine::listen() (exchange_engine.h) for the loop itself.

Definition in file hub_exchange.h.