Fixed-size per-attempt telemetry recorder for the pairing flow. More...

#include <pairing_telemetry.h>

Collaboration diagram for esphome::home_io_control::PairingTelemetry:

Public Member Functions
void	begin ()
	Reset all state and start a new attempt. Call once at discover_and_pair() entry.
void	record_tx (uint8_t cmd)
	Record that we transmitted a frame.
void	record_rx (const IoFrame &frame, int16_t rssi)
	Record that we received and accepted a frame.
void	record_rx_reject (const IoFrame &frame, int16_t rssi)
	Record that we received a frame that parsed but was rejected by a classifier.
void	record_lbt_defer (int16_t rssi)
	Record a listen-before-talk defer (channel busy).
void	record_hop ()
	Record a frequency hop while waiting.
void	set_phase (pairing::PairingState phase)
	Record a pairing state-machine phase transition.
void	set_outcome (PairingOutcome outcome)
	Record the final outcome of the attempt.
void	set_paired_device (const uint8_t node_id[NODE_ID_SIZE], DeviceType type)
	Record the successfully paired device, if any.
void	increment_discovery_attempt ()
	Increment the discovery attempt counter (one call per discovery command retry).
void	set_advice_codes (const std::string &codes)
	Record the advisor's short advice codes for the ;advice= result-sensor field.
const PairingTelemetryEvent *	events () const
uint8_t	event_count () const
uint16_t	heard_count () const
bool	truncated () const
pairing::PairingState	phase () const
PairingOutcome	outcome () const
uint8_t	discovery_attempts () const
uint8_t	lbt_retries () const
bool	has_paired_device () const
const uint8_t *	paired_node_id () const
DeviceType	paired_device_type () const
uint32_t	duration_ms () const
void	log_summary () const
	Emit a multi-line human-readable summary via ESP_LOGI. Call once, at the end of the attempt.
std::string	result_sensor_string () const
	Render the frozen v1; machine-readable result string.

Detailed Description

Fixed-size per-attempt telemetry recorder for the pairing flow.

Owned by the hub, reset at the start of every discover_and_pair() call. Not thread-safe — pairing is a single blocking call on the main loop, matching the rest of this component.

Definition at line 71 of file pairing_telemetry.h.

Member Function Documentation

◆ begin()

void esphome::home_io_control::PairingTelemetry::begin ( )

Reset all state and start a new attempt. Call once at discover_and_pair() entry.

Definition at line 75 of file pairing_telemetry.cpp.

◆ discovery_attempts()

uint8_t esphome::home_io_control::PairingTelemetry::discovery_attempts ( ) const

inlinenodiscard

Returns: Number of discovery command attempts made.

Definition at line 130 of file pairing_telemetry.h.

◆ duration_ms()

uint32_t esphome::home_io_control::PairingTelemetry::duration_ms ( ) const

nodiscard

Returns: Duration of the attempt so far (or total, once complete) in milliseconds.

Definition at line 165 of file pairing_telemetry.cpp.

◆ event_count()

uint8_t esphome::home_io_control::PairingTelemetry::event_count ( ) const

inlinenodiscard

Returns: Number of events actually stored (<= PAIRING_TELEMETRY_MAX_EVENTS).

Definition at line 116 of file pairing_telemetry.h.

◆ events()

const PairingTelemetryEvent * esphome::home_io_control::PairingTelemetry::events ( ) const

inlinenodiscard

Returns: Recorded events (up to PAIRING_TELEMETRY_MAX_EVENTS), oldest first.

Definition at line 114 of file pairing_telemetry.h.

◆ has_paired_device()

bool esphome::home_io_control::PairingTelemetry::has_paired_device ( ) const

inlinenodiscard

Returns: true if a device was successfully paired this attempt.

Definition at line 134 of file pairing_telemetry.h.

◆ heard_count()

uint16_t esphome::home_io_control::PairingTelemetry::heard_count ( ) const

inlinenodiscard

Returns: Total RX events seen, including ones beyond the storage capacity.

Definition at line 118 of file pairing_telemetry.h.

◆ increment_discovery_attempt()

void esphome::home_io_control::PairingTelemetry::increment_discovery_attempt ( )

Increment the discovery attempt counter (one call per discovery command retry).

Definition at line 160 of file pairing_telemetry.cpp.

◆ lbt_retries()

uint8_t esphome::home_io_control::PairingTelemetry::lbt_retries ( ) const

inlinenodiscard

Returns: Total listen-before-talk retries consumed across the whole attempt.

Definition at line 132 of file pairing_telemetry.h.

◆ log_summary()

void esphome::home_io_control::PairingTelemetry::log_summary ( ) const

Emit a multi-line human-readable summary via ESP_LOGI. Call once, at the end of the attempt.

Definition at line 167 of file pairing_telemetry.cpp.

Here is the call graph for this function:

◆ outcome()

PairingOutcome esphome::home_io_control::PairingTelemetry::outcome ( ) const

inlinenodiscard

Returns: Final outcome, or PairingOutcome::NONE if no attempt has completed yet.

Definition at line 128 of file pairing_telemetry.h.

◆ paired_device_type()

DeviceType esphome::home_io_control::PairingTelemetry::paired_device_type ( ) const

inlinenodiscard

Returns: Paired device's type; only meaningful if has_paired_device() is true.

Definition at line 138 of file pairing_telemetry.h.

◆ paired_node_id()

const uint8_t * esphome::home_io_control::PairingTelemetry::paired_node_id ( ) const

inlinenodiscard

Returns: Paired device's node ID; only meaningful if has_paired_device() is true.

Definition at line 136 of file pairing_telemetry.h.

◆ phase()

pairing::PairingState esphome::home_io_control::PairingTelemetry::phase ( ) const

inlinenodiscard

Returns: Highest phase reached during the attempt.

Definition at line 126 of file pairing_telemetry.h.

◆ record_hop()

void esphome::home_io_control::PairingTelemetry::record_hop ( )

Record a frequency hop while waiting.

The exchange engine does not expose which channel index a hop landed on, so this only marks that a hop happened, not where to.

Definition at line 141 of file pairing_telemetry.cpp.

◆ record_lbt_defer()

void esphome::home_io_control::PairingTelemetry::record_lbt_defer ( int16_t rssi )

Record a listen-before-talk defer (channel busy).

Parameters

rssi	RSSI in dBm that triggered the defer.

Definition at line 135 of file pairing_telemetry.cpp.

◆ record_rx()

void esphome::home_io_control::PairingTelemetry::record_rx	(	const IoFrame &	frame,
		int16_t	rssi )

Record that we received and accepted a frame.

Parameters

frame	Parsed frame (cmd, src, dst, and the 1W protocol bit are recorded — dst and the 1W bit feed PairingAdvisor's ONE_WAY_PAIRING_TRAFFIC and FOREIGN_CONTROLLER_PAIRING detection, see pairing_advisor.h).
rssi	RSSI in dBm.

Definition at line 125 of file pairing_telemetry.cpp.

◆ record_rx_reject()

void esphome::home_io_control::PairingTelemetry::record_rx_reject	(	const IoFrame &	frame,
		int16_t	rssi )

Record that we received a frame that parsed but was rejected by a classifier.

Parameters

frame	Parsed frame (cmd, src, dst, and the 1W protocol bit are recorded — dst and the 1W bit feed PairingAdvisor's ONE_WAY_PAIRING_TRAFFIC and FOREIGN_CONTROLLER_PAIRING detection, see pairing_advisor.h).
rssi	RSSI in dBm.

Definition at line 130 of file pairing_telemetry.cpp.

◆ record_tx()

void esphome::home_io_control::PairingTelemetry::record_tx ( uint8_t cmd )

Record that we transmitted a frame.

Parameters

cmd	Frame command byte.

Definition at line 121 of file pairing_telemetry.cpp.

◆ result_sensor_string()

std::string esphome::home_io_control::PairingTelemetry::result_sensor_string ( ) const

nodiscard

Render the frozen v1; machine-readable result string.

Format (never change without bumping the version tag — the Phase 2 rig's read-back contract parses this exactly; the space after each ; is intentional — Home Assistant's UI only line-wraps this sensor's long value at whitespace, so a fields-only-separated-by-; string renders as one unbroken, unreadable line): v1; outcome=<...>; phase=<...>; node=<XXXXXX|->; type=<...|->; attempts=<n>; lbt=<n>; dur_ms=<n>; heard=<n>; advice=<comma-separated codes|none>

Returns: The formatted result string.

Definition at line 193 of file pairing_telemetry.cpp.

Here is the call graph for this function:

◆ set_advice_codes()

void esphome::home_io_control::PairingTelemetry::set_advice_codes ( const std::string & codes )

inline

Record the advisor's short advice codes for the ;advice= result-sensor field.

Parameters

codes Comma-separated short codes (e.g. "1w_traffic,channel_busy"), or empty if none.

Definition at line 111 of file pairing_telemetry.h.

◆ set_outcome()

void esphome::home_io_control::PairingTelemetry::set_outcome ( PairingOutcome outcome )

Record the final outcome of the attempt.

Parameters

outcome Final disposition.

Definition at line 148 of file pairing_telemetry.cpp.

Here is the call graph for this function:

◆ set_paired_device()

void esphome::home_io_control::PairingTelemetry::set_paired_device	(	const uint8_t	node_id[NODE_ID_SIZE],
		DeviceType	type )

Record the successfully paired device, if any.

Parameters

node_id	Paired device's node ID.
type	Paired device's type.

Definition at line 154 of file pairing_telemetry.cpp.

◆ set_phase()

void esphome::home_io_control::PairingTelemetry::set_phase ( pairing::PairingState phase )

Record a pairing state-machine phase transition.

Parameters

phase New phase.

Definition at line 143 of file pairing_telemetry.cpp.

Here is the call graph for this function:

◆ truncated()

bool esphome::home_io_control::PairingTelemetry::truncated ( ) const

inlinenodiscard

Returns: true if any event (of any kind — TX/RX/RX_REJECT/LBT_DEFER/HOP/PHASE) was dropped because the fixed event array was full. Deliberately not derived from heard_count() > event_count() — the two counters measure different populations (heard_count() is RX/RX_REJECT only; event_count() is stored events of every kind), so that comparison misses truncation whenever most stored events aren't RX/RX_REJECT.

Definition at line 124 of file pairing_telemetry.h.

The documentation for this class was generated from the following files:

components/home_io_control/pairing_telemetry.h
components/home_io_control/pairing_telemetry.cpp

Public Member Functions

Detailed Description

Member Function Documentation

◆ begin()

◆ discovery_attempts()

◆ duration_ms()

◆ event_count()

◆ events()

◆ has_paired_device()

◆ heard_count()

◆ increment_discovery_attempt()

◆ lbt_retries()

◆ log_summary()

◆ outcome()

◆ paired_device_type()

◆ paired_node_id()

◆ phase()

◆ record_hop()

◆ record_lbt_defer()

◆ record_rx()

◆ record_rx_reject()

◆ record_tx()

◆ result_sensor_string()

◆ set_advice_codes()

◆ set_outcome()

◆ set_paired_device()

◆ set_phase()

◆ truncated()