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.
void	record_recent_one_way_sighting (const RecentOneWayPairingSighting &sighting)
	Seed telemetry with a 1W pairing-gesture frame observed shortly before this attempt began.
const PairingTelemetryEvent *	events () const
uint8_t	event_count () const
uint16_t	heard_count () const
uint32_t	hop_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 92 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 73 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 179 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 172 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 162 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 160 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 183 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 164 of file pairing_telemetry.h.

◆ hop_count()

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

inlinenodiscard

Returns: Total number of channel hops during the attempt. Not itemized in events() — see record_hop()'s doc comment for why.

Definition at line 167 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 167 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 181 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 174 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 177 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 187 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 185 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 175 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.

Counted via hop_count() only, deliberately not stored in the fixed event array: at the current 5-7 ms hop slice, a multi-second discovery window produces far more hops than PAIRING_TELEMETRY_MAX_EVENTS, which used to exhaust the buffer with hop events alone within about a second of essentially every real attempt (issue #27). This did not produce a false rf_silent — heard_count() is incremented in record_() before the capacity check, so it still counts an RX/RX_REJECT that arrives after the array is full. What it did do: once the array was full, PairingAdvisor's 1w_traffic/channel_busy/foreign_controller passes — which all scan events(), not heard_count() — could only ever see whatever RX/RX_REJECT evidence had landed in roughly the first ~200 ms of the attempt, and truncated() was true on nearly every real pairing attempt. A hop carries no per-event information worth itemizing (no channel index, no RSSI) anyway; the total count is enough.

Definition at line 140 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 134 of file pairing_telemetry.cpp.

◆ record_recent_one_way_sighting()

void esphome::home_io_control::PairingTelemetry::record_recent_one_way_sighting ( const RecentOneWayPairingSighting & sighting )

Seed telemetry with a 1W pairing-gesture frame observed shortly before this attempt began.

Recorded as an RX event with its real RSSI, marked seeded (PairingTelemetryEvent::aux = 1) so log_summary() can label it honestly instead of implying a live in-window capture, and so PairingAdvisor's channel_busy pass — which is specifically about live contention during this attempt — can exclude it while ONE_WAY_PAIRING_TRAFFIC still picks it up like any other RX. It counts toward heard_count(). Timestamped at the start of the attempt (millis_offset ≈ 0), since its real arrival time — before begin() — isn't preserved; the seeded marker is what tells a reader not to read that as "heard 0 ms into this attempt". The caller ( PairingEngine::discover_and_pair()) is responsible for deciding whether sighting is recent enough to seed with — this method always records what it's given.

Parameters

sighting The overheard frame to seed telemetry with.

Definition at line 145 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 124 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 129 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 120 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 208 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 144 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 155 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 161 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 150 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 173 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()

◆ hop_count()

◆ increment_discovery_attempt()

◆ lbt_retries()

◆ log_summary()

◆ outcome()

◆ paired_device_type()

◆ paired_node_id()

◆ phase()

◆ record_hop()

◆ record_lbt_defer()

◆ record_recent_one_way_sighting()

◆ record_rx()

◆ record_rx_reject()

◆ record_tx()

◆ result_sensor_string()

◆ set_advice_codes()

◆ set_outcome()

◆ set_paired_device()

◆ set_phase()

◆ truncated()